Port of github.com/polymer/polymer.

pkg/polymer/lib/src/instance.dart

+// Copyright (c) 2013, the Dart project authors.  Please see the AUTHORS file
+// for details. All rights reserved. Use of this source code is governed by a
+// BSD-style license that can be found in the LICENSE file.
+
+part of polymer;
+
+/**
+ * Use this annotation to publish a field as an attribute. For example:
+ *
+ *     class MyPlaybackElement extends PolymerElement {
+ *       // This will be available as an HTML attribute, for example:
+ *       //     <my-playback volume="11">
+ *       @published double volume;
+ *     }
+ */
+// TODO(jmesserly): does @published imply @observable or vice versa?
+const published = const PublishedProperty();
+
+/** An annotation used to publish a field as an attribute. See [published]. */
+class PublishedProperty extends ObservableProperty {
+  const PublishedProperty();
+}
+
+// TODO(jmesserly): make this the mixin so we can have Polymer type extensions,
+// and move the implementation of PolymerElement in here. Once done it will look
+// like:
+// abstract class Polymer { ... all the things ... }
+// typedef PolymerElement = HtmlElement with Polymer, Observable;
+abstract class Polymer {
+  // TODO(jmesserly): should this really be public?
+  /** Regular expression that matches data-bindings. */
+  static final bindPattern = new RegExp(r'\{\{([^{}]*)}}');
+
+  /**
+   * Like [document.register] but for Polymer elements.
+   *
+   * Use the [name] to specify custom elment's tag name, for example:
+   * "fancy-button" if the tag is used as `<fancy-button>`.
+   *
+   * The [type] is the type to construct. If not supplied, it defaults to
+   * [PolymerElement].
+   */
+  // NOTE: this is called "element" in src/declaration/polymer-element.js, and
+  // exported as "Polymer".
+  static void register(String name, [Type type]) {
+    //console.log('registering [' + name + ']');
+    if (type == null) type = PolymerElement;
+    _registerClassMirror(name, reflectClass(type));
+  }
+
+  // TODO(jmesserly): we use ClassMirror internall for now, until it is possible
+  // to get from ClassMirror -> Type.
+  static void _registerClassMirror(String name, ClassMirror type) {
+    _typesByName[name] = type;
+    // notify the registrar waiting for 'name', if any
+    _notifyType(name);
+  }
+}
+
+/**
+ * The base class for Polymer elements. It provides convience features on top
+ * of the custom elements web standard.
+ */
+class PolymerElement extends CustomElement with ObservableMixin {
+  // Fully ported from revision:
+  // https://github.com/Polymer/polymer/blob/4dc481c11505991a7c43228d3797d28f21267779
+  //
+  //   src/instance/attributes.js
+  //   src/instance/base.js
+  //   src/instance/events.js
+  //   src/instance/mdv.js
+  //   src/instance/properties.js
+  //   src/instance/utils.js
+  //
+  // Not yet ported:
+  //   src/instance/style.js -- blocked on ShadowCSS.shimPolyfillDirectives
+
+  /// The one syntax to rule them all.
+  static final BindingDelegate _polymerSyntax = new PolymerExpressions();
+
+  static int _preparingElements = 0;
+
+  PolymerDeclaration _declaration;
+
+  /** The most derived `<polymer-element>` declaration for this element. */
+  PolymerDeclaration get declaration => _declaration;
+
+  Map<String, StreamSubscription> _elementObservers;
+  bool _unbound; // lazy-initialized
+  Job _unbindAllJob;
+
+  bool get _elementPrepared => _declaration != null;
+
+  bool get applyAuthorStyles => false;
+  bool get resetStyleInheritance => false;
+  bool get alwaysPrepare => false;
+
+  /**
+   * Shadow roots created by [parseElement]. See [getShadowRoot].
+   */
+  final _shadowRoots = new HashMap<String, ShadowRoot>();
+
+  /** Map of items in the shadow root(s) by their [Element.id]. */
+  // TODO(jmesserly): various issues:
+  // * wrap in UnmodifiableMapView?
+  // * should we have an object that implements noSuchMethod?
+  // * should the map have a key order (e.g. LinkedHash or SplayTree)?
+  // * should this be a live list? Polymer doesn't, maybe due to JS limitations?
+  // For now I picked the most performant choice: non-live HashMap.
+  final Map<String, Element> $ = new HashMap<String, Element>();
+
+  /**
+   * Gets the shadow root associated with the corresponding custom element.
+   *
+   * This is identical to [shadowRoot], unless there are multiple levels of
+   * inheritance and they each have their own shadow root. For example,
+   * this can happen if the base class and subclass both have `<template>` tags
+   * in their `<polymer-element>` tags.
+   */
+  // TODO(jmesserly): Polymer does not have this feature. Reconcile.
+  ShadowRoot getShadowRoot(String customTagName) => _shadowRoots[customTagName];
+
+  ShadowRoot createShadowRoot([name]) {
+    if (name != null) {
+      throw new ArgumentError('name argument must not be supplied.');
+    }
+
+    // Provides ability to traverse from ShadowRoot to the host.
+    // TODO(jmessery): remove once we have this ability on the DOM.
+    final root = super.createShadowRoot();
+    _shadowHost[root] = host;
+    return root;
+  }
+
+  /**
+   * Invoke [callback] in [wait], unless the job is re-registered,
+   * which resets the timer. For example:
+   *
+   *     _myJob = job(_myJob, callback, const Duration(milliseconds: 100));
+   *
+   * Returns a job handle which can be used to re-register a job.
+   */
+  Job job(Job job, void callback(), Duration wait) =>
+      runJob(job, callback, wait);
+
+  // TODO(jmesserly): I am not sure if we should have the
+  // created/createdCallback distinction. See post here:
+  // https://groups.google.com/d/msg/polymer-dev/W0ZUpU5caIM/v5itFnvnehEJ
+  // Same issue with inserted and removed.
+  void created() {
+    if (document.window != null || alwaysPrepare || _preparingElements > 0) {
+      prepareElement();
+    }
+  }
+
+  void prepareElement() {
+    // Dart note: get the _declaration, which also marks _elementPrepared
+    _declaration = _getDeclaration(reflect(this).type);
+    // do this first so we can observe changes during initialization
+    observeProperties();
+    // install boilerplate attributes
+    copyInstanceAttributes();
+    // process input attributes
+    takeAttributes();
+    // add event listeners
+    addHostListeners();
+    // guarantees that while preparing, any sub-elements will also be prepared
+    _preparingElements++;
+    // process declarative resources
+    parseDeclarations(_declaration);
+    _preparingElements--;
+    // user entry point
+    ready();
+  }
+
+  /** Called when [prepareElement] is finished. */
+  void ready() {}
+
+  void inserted() {
+    if (!_elementPrepared) {
+      prepareElement();
+    }
+    cancelUnbindAll(preventCascade: true);
+  }
+
+  void removed() {
+    asyncUnbindAll();
+  }
+
+  /** Recursive ancestral <element> initialization, oldest first. */
+  void parseDeclarations(PolymerDeclaration declaration) {
+    if (declaration != null) {
+      parseDeclarations(declaration.superDeclaration);
+      parseDeclaration(declaration.host);
+    }
+  }
+
+  /**
+   * Parse input `<polymer-element>` as needed, override for custom behavior.
+   */
+  void parseDeclaration(Element elementElement) {
+    var root = shadowFromTemplate(fetchTemplate(elementElement));
+
+    // Dart note: this is extra code compared to Polymer to support
+    // the getShadowRoot method.
+    if (root == null) return;
+
+    var name = elementElement.attributes['name'];
+    if (name == null) return;
+    _shadowRoots[name] = root;
+  }
+
+  /**
+   * Return a shadow-root template (if desired), override for custom behavior.
+   */
+  Element fetchTemplate(Element elementElement) =>
+      elementElement.query('template');
+
+  /** Utility function that creates a shadow root from a `<template>`. */
+  ShadowRoot shadowFromTemplate(Element template) {
+    if (template == null) return null;
+    // cache elder shadow root (if any)
+    var elderRoot = this.shadowRoot;
+    // make a shadow root
+    var root = createShadowRoot();
+    // migrate flag(s)(
+    root.applyAuthorStyles = applyAuthorStyles;
+    root.resetStyleInheritance = resetStyleInheritance;
+    // stamp template
+    // which includes parsing and applying MDV bindings before being
+    // inserted (to avoid {{}} in attribute values)
+    // e.g. to prevent <img src="images/{{icon}}"> from generating a 404.
+    var dom = instanceTemplate(template);
+    // append to shadow dom
+    root.append(dom);
+    // perform post-construction initialization tasks on shadow root
+    shadowRootReady(root, template);
+    // return the created shadow root
+    return root;
+  }
+
+  void shadowRootReady(ShadowRoot root, Element template) {
+    // locate nodes with id and store references to them in this.$ hash
+    marshalNodeReferences(root);
+    // add local events of interest...
+    addInstanceListeners(root, template);
+    // TODO(jmesserly): port this
+    // set up pointer gestures
+    // PointerGestures.register(root);
+  }
+
+  /** Locate nodes with id and store references to them in [$] hash. */
+  void marshalNodeReferences(ShadowRoot root) {
+    if (root == null) return;
+    for (var n in root.queryAll('[id]')) {
+      $[n.id] = n;
+    }
+  }
+
+  void attributeChanged(String name, String oldValue) {
+    if (name != 'class' && name != 'style') {
+      attributeToProperty(name, attributes[name]);
+    }
+  }
+
+  // TODO(jmesserly): use stream or future here?
+  void onMutation(Node node, void listener(MutationObserver obs)) {
+    new MutationObserver((records, MutationObserver observer) {
+      listener(observer);
+      observer.disconnect();
+    })..observe(node, childList: true, subtree: true);
+  }
+
+  void copyInstanceAttributes() {
+    _declaration._instanceAttributes.forEach((name, value) {
+      attributes[name] = value;
+    });
+  }
+
+  void takeAttributes() {
+    if (_declaration._publishLC == null) return;
+    attributes.forEach(attributeToProperty);
+  }
+
+  /**
+   * If attribute [name] is mapped to a property, deserialize
+   * [value] into that property.
+   */
+  void attributeToProperty(String name, String value) {
+    // try to match this attribute to a property (attributes are
+    // all lower-case, so this is case-insensitive search)
+    var property = propertyForAttribute(name);
+    if (property == null) return;
+
+    // filter out 'mustached' values, these are to be
+    // replaced with bound-data and are not yet values
+    // themselves.
+    if (value == null || value.contains(Polymer.bindPattern)) return;
+
+    // get original value
+    final self = reflect(this);
+    final defaultValue = self.getField(property.simpleName).reflectee;
+
+    // deserialize Boolean or Number values from attribute
+    final newValue = deserializeValue(value, defaultValue,
+        _inferPropertyType(defaultValue, property));
+
+    // only act if the value has changed
+    if (!identical(newValue, defaultValue)) {
+      // install new value (has side-effects)
+      self.setField(property.simpleName, newValue);
+    }
+  }
+
+  /** Return the published property matching name, or null. */
+  // TODO(jmesserly): should we just return Symbol here?
+  DeclarationMirror propertyForAttribute(String name) {
+    final publishLC = _declaration._publishLC;
+    if (publishLC == null) return null;
+    //console.log('propertyForAttribute:', name, 'matches', match);
+    return publishLC[name];
+  }
+
+  /**
+   * Convert representation of [value] based on [type] and [defaultValue].
+   */
+  // TODO(jmesserly): this should probably take a ClassMirror instead of
+  // TypeMirror, but it is currently impossible to get from a TypeMirror to a
+  // ClassMirror.
+  Object deserializeValue(String value, Object defaultValue, TypeMirror type) =>
+      deserialize.deserializeValue(value, defaultValue, type);
+
+  String serializeValue(Object value, TypeMirror inferredType) {
+    if (value == null) return null;
+
+    final type = inferredType.qualifiedName;
+    if (type == const Symbol('dart.core.bool')) {
+      return _toBoolean(value) ? '' : null;
+    } else if (type == const Symbol('dart.core.String')
+        || type == const Symbol('dart.core.int')
+        || type == const Symbol('dart.core.double')) {
+      return '$value';
+    }
+    return null;
+  }
+
+  void reflectPropertyToAttribute(String name) {
+    // TODO(sjmiles): consider memoizing this
+    final self = reflect(this);
+    // try to intelligently serialize property value
+    // TODO(jmesserly): cache symbol?
+    final propValue = self.getField(new Symbol(name)).reflectee;
+    final property = _declaration._publish[name];
+    var inferredType = _inferPropertyType(propValue, property);
+    final serializedValue = serializeValue(propValue, inferredType);
+    // boolean properties must reflect as boolean attributes
+    if (serializedValue != null) {
+      attributes[name] = serializedValue;
+      // TODO(sorvell): we should remove attr for all properties
+      // that have undefined serialization; however, we will need to
+      // refine the attr reflection system to achieve this; pica, for example,
+      // relies on having inferredType object properties not removed as
+      // attrs.
+    } else if (inferredType.qualifiedName == const Symbol('dart.core.bool')) {
+      attributes.remove(name);
+    }
+  }
+
+  /**
+   * Creates the document fragment to use for each instance of the custom
+   * element, given the `<template>` node. By default this is equivalent to:
+   *
+   *     template.createInstance(this, polymerSyntax);
+   *
+   * Where polymerSyntax is a singleton `PolymerExpressions` instance from the
+   * [polymer_expressions](https://pub.dartlang.org/packages/polymer_expressions)
+   * package.
+   *
+   * You can override this method to change the instantiation behavior of the
+   * template, for example to use a different data-binding syntax.
+   */
+  DocumentFragment instanceTemplate(Element template) =>
+      template.createInstance(this, _polymerSyntax);
+
+  NodeBinding bind(String name, model, String path) {
+    // note: binding is a prepare signal. This allows us to be sure that any
+    // property changes that occur as a result of binding will be observed.
+    if (!_elementPrepared) prepareElement();
+
+    var property = propertyForAttribute(name);
+    if (property != null) {
+      unbind(name);
+      // use n-way Polymer binding
+      var observer = bindProperty(property.simpleName, model, path);
+      // reflect bound property to attribute when binding
+      // to ensure binding is not left on attribute if property
+      // does not update due to not changing.
+      reflectPropertyToAttribute(name);
+      return bindings[name] = observer;
+    } else {
+      return super.bind(name, model, path);
+    }
+  }
+
+  void asyncUnbindAll() {
+    if (_unbound == true) return;
+    _unbindLog.info('[$localName] asyncUnbindAll');
+    _unbindAllJob = job(_unbindAllJob, unbindAll, const Duration(seconds: 0));
+  }
+
+  void unbindAll() {
+    if (_unbound == true) return;
+
+    unbindAllProperties();
+    super.unbindAll();
+    _unbindNodeTree(shadowRoot);
+    // TODO(sjmiles): must also unbind inherited shadow roots
+    _unbound = true;
+  }
+
+  void cancelUnbindAll({bool preventCascade}) {
+    if (_unbound == true) {
+      _unbindLog.warning(
+          '[$localName] already unbound, cannot cancel unbindAll');
+      return;
+    }
+    _unbindLog.info('[$localName] cancelUnbindAll');
+    if (_unbindAllJob != null) {
+      _unbindAllJob.stop();
+      _unbindAllJob = null;
+    }
+
+    // cancel unbinding our shadow tree iff we're not in the process of
+    // cascading our tree (as we do, for example, when the element is inserted).
+    if (preventCascade == true) return;
+    _forNodeTree(shadowRoot, (n) {
+      if (n is PolymerElement) {
+        (n as PolymerElement).cancelUnbindAll();
+      }
+    });
+  }
+
+  static void _unbindNodeTree(Node node) {
+    _forNodeTree(node, (node) => node.unbindAll());
+  }
+
+  static void _forNodeTree(Node node, void callback(Node node)) {
+    if (node == null) return;
+
+    callback(node);
+    for (var child = node.firstChild; child != null; child = child.nextNode) {
+      _forNodeTree(child, callback);
+    }
+  }
+
+  /** Set up property observers. */
+  void observeProperties() {
+    // TODO(sjmiles):
+    // we observe published properties so we can reflect them to attributes
+    // ~100% of our team's applications would work without this reflection,
+    // perhaps we can make it optional somehow
+    //
+    // add user's observers
+    final observe = _declaration._observe;
+    final publish = _declaration._publish;
+    if (observe != null) {
+      observe.forEach((name, value) {
+        if (publish != null && publish.containsKey(name)) {
+          observeBoth(name, value);
+        } else {
+          observeProperty(name, value);
+        }
+      });
+    }
+    // add observers for published properties
+    if (publish != null) {
+      publish.forEach((name, value) {
+        if (observe == null || !observe.containsKey(name)) {
+          observeAttributeProperty(name);
+        }
+      });
+    }
+  }
+
+  void _observe(String name, void callback(newValue, oldValue)) {
+    _observeLog.info('[$localName] watching [$name]');
+    // TODO(jmesserly): this is a little different than the JS version so we
+    // can pass the oldValue, which is missing from Dart's PathObserver.
+    // This probably gives us worse performance.
+    var path = new PathObserver(this, name);
+    Object oldValue = null;
+    _registerObserver(name, path.changes.listen((_) {
+      final newValue = path.value;
+      final old = oldValue;
+      oldValue = newValue;
+      callback(newValue, old);
+    }));
+  }
+
+  void _registerObserver(String name, StreamSubscription sub) {
+    if (_elementObservers == null) {
+      _elementObservers = new Map<String, StreamSubscription>();
+    }
+    _elementObservers[name] = sub;
+  }
+
+  void observeAttributeProperty(String name) {
+    _observe(name, (value, old) => reflectPropertyToAttribute(name));
+  }
+
+  void observeProperty(String name, Symbol method) {
+    final self = reflect(this);
+    _observe(name, (value, old) => self.invoke(method, [old]));
+  }
+
+  void observeBoth(String name, Symbol methodName) {
+    final self = reflect(this);
+    _observe(name, (value, old) {
+      reflectPropertyToAttribute(name);
+      self.invoke(methodName, [old]);
+    });
+  }
+
+  void unbindProperty(String name) {
+    if (_elementObservers == null) return;
+    var sub = _elementObservers.remove(name);
+    if (sub != null) sub.cancel();
+  }
+
+  void unbindAllProperties() {
+    if (_elementObservers == null) return;
+    for (var sub in _elementObservers.values) sub.cancel();
+    _elementObservers.clear();
+  }
+
+  /**
+   * Bind a [property] in this object to a [path] in model. *Note* in Dart it
+   * is necessary to also define the field:
+   *
+   *     var myProperty;
+   *
+   *     created() {
+   *       super.created();
+   *       bindProperty(#myProperty, this, 'myModel.path.to.otherProp');
+   *     }
+   */
+  // TODO(jmesserly): replace with something more localized, like:
+  // @ComputedField('myModel.path.to.otherProp');
+  NodeBinding bindProperty(Symbol name, Object model, String path) =>
+      // apply Polymer two-way reference binding
+      _bindProperties(this, name, model, path);
+
+  /**
+   * bind a property in A to a path in B by converting A[property] to a
+   * getter/setter pair that accesses B[...path...]
+   */
+  static NodeBinding _bindProperties(PolymerElement inA, Symbol inProperty,
+        Object inB, String inPath) {
+
+    if (_bindLog.isLoggable(Level.INFO)) {
+      _bindLog.info('[$inB]: bindProperties: [$inPath] to '
+          '[${inA.localName}].[$inProperty]');
+    }
+
+    // Dart note: normally we only reach this code when we know it's a
+    // property, but if someone uses bindProperty directly they might get a
+    // NoSuchMethodError either from the getField below, or from the setField
+    // inside PolymerBinding. That doesn't seem unreasonable, but it's a slight
+    // difference from Polymer.js behavior.
+
+    // capture A's value if B's value is null or undefined,
+    // otherwise use B's value
+    var path = new PathObserver(inB, inPath);
+    if (path.value == null) {
+      path.value = reflect(inA).getField(inProperty).reflectee;
+    }
+    return new _PolymerBinding(inA, inProperty, inB, inPath);
+  }
+
+  /** Attach event listeners on the host (this) element. */
+  void addHostListeners() {
+    var events = _declaration._eventDelegates;
+    if (events.isEmpty) return;
+
+    if (_eventsLog.isLoggable(Level.INFO)) {
+      _eventsLog.info('[$localName] addHostListeners: $events');
+    }
+    addNodeListeners(this, events.keys, hostEventListener);
+  }
+
+  /** Attach event listeners inside a shadow [root]. */
+  void addInstanceListeners(ShadowRoot root, Element template) {
+    var templateDelegates = _declaration._templateDelegates;
+    if (templateDelegates == null) return;
+    var events = templateDelegates[template];
+    if (events == null) return;
+
+    if (_eventsLog.isLoggable(Level.INFO)) {
+      _eventsLog.info('[$localName] addInstanceListeners: $events');
+    }
+    addNodeListeners(root, events, instanceEventListener);
+  }
+
+  void addNodeListeners(Node node, Iterable<String> events,
+      void listener(Event e)) {
+
+    for (var name in events) {
+      addNodeListener(node, name, listener);
+    }
+  }
+
+  void addNodeListener(Node node, String event, void listener(Event e)) {
+    node.on[event].listen(listener);
+  }
+
+  void hostEventListener(Event event) {
+    // TODO(jmesserly): do we need this check? It was using cancelBubble, see:
+    // https://github.com/Polymer/polymer/issues/292
+    if (!event.bubbles) return;
+
+    bool log = _eventsLog.isLoggable(Level.INFO);
+    if (log) {
+      _eventsLog.info('>>> [$localName]: hostEventListener(${event.type})');
+    }
+
+    var h = findEventDelegate(event);
+    if (h != null) {
+      if (log) _eventsLog.info('[$localName] found host handler name [$h]');
+      var detail = event is CustomEvent ?
+          (event as CustomEvent).detail : null;
+      // TODO(jmesserly): cache the symbols?
+      dispatchMethod(new Symbol(h), [event, detail, this]);
+    }
+
+    if (log) {
+      _eventsLog.info('<<< [$localName]: hostEventListener(${event.type})');
+    }
+  }
+
+  String findEventDelegate(Event event) =>
+      _declaration._eventDelegates[_eventNameFromType(event.type)];
+
+  /** Call [methodName] method on [this] with [args], if the method exists. */
+  // TODO(jmesserly): I removed the [node] argument as it was unused. Reconcile.
+  void dispatchMethod(Symbol methodName, List args) {
+    bool log = _eventsLog.isLoggable(Level.INFO);
+    if (log) _eventsLog.info('>>> [$localName]: dispatch $methodName');
+
+    // TODO(sigmund): consider making event listeners list all arguments
+    // explicitly. Unless VM mirrors are optimized first, this reflectClass call
+    // will be expensive once custom elements extend directly from Element (see
+    // dartbug.com/11108).
+    var self = reflect(this);
+    var method = self.type.methods[methodName];
+    if (method != null) {
+      // This will either truncate the argument list or extend it with extra
+      // null arguments, so it will match the signature.
+      // TODO(sigmund): consider accepting optional arguments when we can tell
+      // them appart from named arguments (see http://dartbug.com/11334)
+      args.length = method.parameters.where((p) => !p.isOptional).length;
+    }
+    self.invoke(methodName, args);
+
+    if (log) _eventsLog.info('<<< [$localName]: dispatch $methodName');
+
+    // TODO(jmesserly): workaround for HTML events not supporting zones.
+    performMicrotaskCheckpoint();
+  }
+
+  void instanceEventListener(Event event) {
+    _listenLocal(host, event);
+  }
+
+  // TODO(sjmiles): much of the below privatized only because of the vague
+  // notion this code is too fiddly and we need to revisit the core feature
+  void _listenLocal(Element host, Event event) {
+    // TODO(jmesserly): do we need this check? It was using cancelBubble, see:
+    // https://github.com/Polymer/polymer/issues/292
+    if (!event.bubbles) return;
+
+    bool log = _eventsLog.isLoggable(Level.INFO);
+    if (log) _eventsLog.info('>>> [$localName]: listenLocal [${event.type}]');
+
+    final eventOn = '$_EVENT_PREFIX${_eventNameFromType(event.type)}';
+    if (event.path == null) {
+      _listenLocalNoEventPath(host, event, eventOn);
+    } else {
+      _listenLocalEventPath(host, event, eventOn);
+    }
+
+    if (log) _eventsLog.info('<<< [$localName]: listenLocal [${event.type}]');
+  }
+
+  static void _listenLocalEventPath(Element host, Event event, String eventOn) {
+    var c = null;
+    for (var target in event.path) {
+      // if we hit host, stop
+      if (identical(target, host)) return;
+
+      // find a controller for the target, unless we already found `host`
+      // as a controller
+      c = identical(c, host) ? c : _findController(target);
+
+      // if we have a controller, dispatch the event, and stop if the handler
+      // returns true
+      if (c != null && _handleEvent(c, target, event, eventOn)) {
+        return;
+      }
+    }
+  }
+
+  // TODO(sorvell): remove when ShadowDOM polyfill supports event path.
+  // Note that _findController will not return the expected controller when the
+  // event target is a distributed node.  This is because we cannot traverse
+  // from a composed node to a node in shadowRoot.
+  // This will be addressed via an event path api
+  // https://www.w3.org/Bugs/Public/show_bug.cgi?id=21066
+  static void _listenLocalNoEventPath(Element host, Event event,
+      String eventOn) {
+
+    if (_eventsLog.isLoggable(Level.INFO)) {
+      _eventsLog.info('event.path() not supported for ${event.type}');
+    }
+
+    var target = event.target;
+    var c = null;
+    // if we hit dirt or host, stop
+    while (target != null && target != host) {
+      // find a controller for target `t`, unless we already found `host`
+      // as a controller
+      c = identical(c, host) ? c : _findController(target);
+
+      // if we have a controller, dispatch the event, return 'true' if
+      // handler returns true
+      if (c != null && _handleEvent(c, target, event, eventOn)) {
+        return;
+      }
+      target = target.parent;
+    }
+  }
+
+  // TODO(jmesserly): this won't find the correct host unless the ShadowRoot
+  // was created on a PolymerElement.
+  static Element _findController(Node node) {
+    while (node.parentNode != null) {
+      node = node.parentNode;
+    }
+    return _shadowHost[node];
+  }
+
+  static bool _handleEvent(Element ctrlr, Node node, Event event,
+      String eventOn) {
+
+    // Note: local events are listened only in the shadow root. This dynamic
+    // lookup is used to distinguish determine whether the target actually has a
+    // listener, and if so, to determine lazily what's the target method.
+    var name = node is Element ? (node as Element).attributes[eventOn] : null;
+    if (name != null && _handleIfNotHandled(node, event)) {
+      if (_eventsLog.isLoggable(Level.INFO)) {
+        _eventsLog.info('[${ctrlr.localName}] found handler name [$name]');
+      }
+      var detail = event is CustomEvent ?
+          (event as CustomEvent).detail : null;
+
+      if (node != null) {
+        // TODO(jmesserly): cache symbols?
+        ctrlr.xtag.dispatchMethod(new Symbol(name), [event, detail, node]);
+      }
+    }
+
+    // TODO(jmesserly): do we need this? It was using cancelBubble, see:
+    // https://github.com/Polymer/polymer/issues/292
+    return !event.bubbles;
+  }
+
+  // TODO(jmesserly): I don't understand this bit. It seems to be a duplicate
+  // delivery prevention mechanism?
+  static bool _handleIfNotHandled(Node node, Event event) {
+    var list = _eventHandledTable[event];
+    if (list == null) _eventHandledTable[event] = list = new Set<Node>();
+    if (!list.contains(node)) {
+      list.add(node);
+      return true;
+    }
+    return false;
+  }
+
+  /**
+   * Invokes a function asynchronously.
+   * This will call `Platform.flush()` and then return a `new Timer`
+   * with the provided [method] and [timeout].
+   *
+   * If you would prefer to run the callback using
+   * [window.requestAnimationFrame], see the [async] method.
+   */
+  // Dart note: "async" is split into 2 methods so it can have a sensible type
+  // signatures. Also removed the various features that don't make sense in a
+  // Dart world, like binding to "this" and taking arguments list.
+  Timer asyncTimer(void method(), Duration timeout) {
+    // when polyfilling Object.observe, ensure changes
+    // propagate before executing the async method
+    platform.flush();
+    return new Timer(timeout, method);
+  }
+
+  /**
+   * Invokes a function asynchronously.
+   * This will call `Platform.flush()` and then call
+   * [window.requestAnimationFrame] with the provided [method] and return the
+   * result.
+   *
+   * If you would prefer to run the callback after a given duration, see
+   * the [asyncTimer] method.
+   */
+  int async(RequestAnimationFrameCallback method) {
+    // when polyfilling Object.observe, ensure changes
+    // propagate before executing the async method
+    platform.flush();
+    return window.requestAnimationFrame(method);
+  }
+
+  /**
+   * Fire a [CustomEvent] targeting [toNode], or this if toNode is not
+   * supplied. Returns the [detail] object.
+   */
+  Object fire(String type, {Object detail, Node toNode, bool canBubble}) {
+    var node = toNode != null ? toNode : this;
+    //log.events && console.log('[%s]: sending [%s]', node.localName, inType);
+    node.dispatchEvent(new CustomEvent(
+      type,
+      canBubble: canBubble != null ? canBubble : true,
+      detail: detail
+    ));
+    return detail;
+  }
+
+  /**
+   * Fire an event asynchronously. See [async] and [fire].
+   */
+  asyncFire(String type, {Object detail, Node toNode, bool canBubble}) {
+    // TODO(jmesserly): I'm not sure this method adds much in Dart, it's easy to
+    // add "() =>"
+    async((x) => fire(
+        type, detail: detail, toNode: toNode, canBubble: canBubble));
+  }
+
+  /**
+   * Remove [className] from [old], add class to [anew], if they exist.
+   */
+  void classFollows(Element anew, Element old, String className) {
+    if (old != null) {
+      old.classes.remove(className);
+    }
+    if (anew != null) {
+      anew.classes.add(className);
+    }
+  }
+}
+
+// Dart note: Polymer addresses n-way bindings by metaprogramming: redefine
+// the property on the PolymerElement instance to always get its value from the
+// model@path. We can't replicate this in Dart so we do the next best thing:
+// listen to changes on both sides and update the values.
+// TODO(jmesserly): our approach leads to race conditions in the bindings.
+// See http://code.google.com/p/dart/issues/detail?id=13567
+class _PolymerBinding extends NodeBinding {
+  final InstanceMirror _target;
+  final Symbol _property;
+  StreamSubscription _sub;
+  Object _lastValue;
+
+  _PolymerBinding(PolymerElement node, Symbol property, model, path)
+      : _target = reflect(node),
+        _property = property,
+        super(node, MirrorSystem.getName(property), model, path) {
+
+    _sub = node.changes.listen(_propertyValueChanged);
+  }
+
+  void close() {
+    if (closed) return;
+    _sub.cancel();
+    super.close();
+  }
+
+  void boundValueChanged(newValue) {
+    _lastValue = newValue;
+    _target.setField(_property, newValue);
+  }
+
+  void _propertyValueChanged(List<ChangeRecord> records) {
+    for (var record in records) {
+      if (record.changes(_property)) {
+        final newValue = _target.getField(_property).reflectee;
+        if (!identical(_lastValue, newValue)) {
+          value = newValue;
+        }
+        return;
+      }
+    }
+  }
+}
+
+bool _toBoolean(value) => null != value && false != value;
+
+TypeMirror _propertyType(DeclarationMirror property) =>
+    property is VariableMirror
+        ? (property as VariableMirror).type
+        : (property as MethodMirror).returnType;
+
+TypeMirror _inferPropertyType(Object value, DeclarationMirror property) {
+  var type = _propertyType(property);
+  if (type.qualifiedName == const Symbol('dart.core.Object') ||
+      type.qualifiedName == const Symbol('dynamic')) {
+    // Attempt to infer field type from the default value.
+    if (value != null) {
+      type = reflect(value).type;
+    }
+  }
+  return type;
+}
+
+final Logger _observeLog = new Logger('polymer.observe');
+final Logger _eventsLog = new Logger('polymer.events');
+final Logger _unbindLog = new Logger('polymer.unbind');
+final Logger _bindLog = new Logger('polymer.bind');
+
+final Expando _shadowHost = new Expando<Element>();
+
+final Expando _eventHandledTable = new Expando<Set<Node>>();