update to polymer js 0.5.1

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 property as an attribute.
 ///
 /// You can also use [PublishedProperty] to provide additional information,
 /// such as automatically syncing the property back to the attribute.
@@ skipping 180 matching lines @@
     //     new JsObject.fromBrowserObject(poly).callMethod('init')
     //
     // However doing it that way hits an issue with JS-interop in IE10: we get a
     // JsObject that wraps something other than `poly`, due to improper caching.
     // By reusing _polymerElementProto that we used for 'register', we can
     // then call apply on it to invoke init() with the correct `this` pointer.
     JsFunction init = _polymerElementProto['init'];
     init.apply([], thisArg: poly);
   }
 
-  // Note: these are from src/declaration/import.js
-  // For now proxy to the JS methods, because we want to share the loader with
-  // polymer.js for interop purposes.
+  // Warning for when people try to use `importElements` or `import`.
+  static const String _DYNAMIC_IMPORT_WARNING = 'Dynamically loading html '
+      'imports has very limited support right now in dart, see '
+      'http://dartbug.com/17873.';
+
+  /// Loads the set of HTMLImports contained in `node`. Returns a future that
+  /// resolves when all the imports have been loaded. This method can be used to
+  /// lazily load imports. For example, given a template:
+  ///
+  ///     <template>
+  ///       <link rel="import" href="my-import1.html">
+  ///       <link rel="import" href="my-import2.html">
+  ///     </template>
+  ///
+  ///     Polymer.importElements(template.content)
+  ///         .then((_) => print('imports lazily loaded'));
+  ///

[Siggi Cherem (dart-lang), 2014/11/25 17:53:42]

maybe add a line here in the docs about the limited support for this as well?

[jakemac, 2014/12/01 18:42:51]

Done.

+  /// Dart Notes: From src/lib/import.js For now proxy to the JS methods,

[Siggi Cherem (dart-lang), 2014/11/25 17:53:42]

nit use only 2 // for this part of the comment (so it doesn't show up in the
dart docs)

[jakemac, 2014/12/01 18:42:52]

Done.

+  /// because we want to share the loader with polymer.js for interop purposes.
   static Future importElements(Node elementOrFragment) {
+    print(_DYNAMIC_IMPORT_WARNING);
     var completer = new Completer();
     js.context['Polymer'].callMethod('importElements',
         [elementOrFragment, () => completer.complete()]);
     return completer.future;
   }
 
-  static Future importUrls(List urls) {
+  /// Loads an HTMLImport for each url specified in the `urls` array. Notifies
+  /// when all the imports have loaded by calling the `callback` function
+  /// argument. This method can be used to lazily load imports. For example,
+  /// For example,
+  ///
+  ///     Polymer.import(['my-import1.html', 'my-import2.html'])
+  ///         .then((_) => print('imports lazily loaded'));
+  ///
+  /// Dart Notes: From src/lib/import.js. For now proxy to the JS methods,

[Siggi Cherem (dart-lang), 2014/11/25 17:53:42]

same two comments here

[jakemac, 2014/12/01 18:42:52]

Done.

+  /// because we want to share the loader with polymer.js for interop purposes.
+  static Future import(List urls) {
+    print(_DYNAMIC_IMPORT_WARNING);
     var completer = new Completer();
-    js.context['Polymer'].callMethod('importUrls',
+    js.context['Polymer'].callMethod('import',
         [urls, () => completer.complete()]);
     return completer.future;
   }
 
+  /// Deprecated: Use `import` instead.
+  @deprecated
+  static Future importUrls(List urls) {
+    return import(urls);
+  }
+
   static final Completer _onReady = new Completer();
 
   /// Future indicating that the Polymer library has been loaded and is ready
   /// for use.
   static Future get onReady => _onReady.future;
 
   /// Returns a list of elements that have had polymer-elements created but
   /// are not yet ready to register. The list is an array of element
   /// definitions.
   static List<Element> get waitingFor =>
@@ skipping 129 matching lines @@
   /// If this class is a superclass, calling `super.created()` is sufficient.
   void polymerCreated() {
     var t = nodeBind(this).templateInstance;
     if (t != null && t.model != null) {
       window.console.warn('Attributes on $_name were data bound '
           'prior to Polymer upgrading the element. This may result in '
           'incorrect binding types.');
     }
     prepareElement();
     if (!isTemplateStagingDocument(ownerDocument)) {
-      makeElementReady();
+      _makeElementReady();
     }
   }
 
   /// *Deprecated* use [shadowRoots] instead.
   @deprecated
   ShadowRoot getShadowRoot(String customTagName) => shadowRoots[customTagName];
 
   void prepareElement() {
     if (_elementPrepared) {
       window.console.warn('Element already prepared: $_name');
       return;
     }
     _initJsObject();
     // Dart note: get the corresponding <polymer-element> declaration.
     _element = _getDeclaration(_name);
     // install property storage
     createPropertyObserver();
     openPropertyObserver();
     // install boilerplate attributes
     copyInstanceAttributes();
     // process input attributes
     takeAttributes();
     // add event listeners
     addHostListeners();
   }
 
   /// Initialize JS interop for this element. For now we just initialize the
-  // JsObject, but in the future we could also initialize JS APIs here.
+  /// JsObject, but in the future we could also initialize JS APIs here.
   _initJsObject() {
     _jsElem = new JsObject.fromBrowserObject(this);
   }
 
-  makeElementReady() {
+  /// Deprecated: This is no longer a public method.
+  @deprecated
+  makeElementReady() => _makeElementReady();
+
+  _makeElementReady() {
     if (_readied) return;
     _readied = true;
     createComputedProperties();
 
-    // TODO(sorvell): We could create an entry point here
-    // for the user to compute property values.
-    // process declarative resources
     parseDeclarations(_element);
-    // TODO(sorvell): CE polyfill uses unresolved attribute to simulate
-    // :unresolved; remove this attribute to be compatible with native
-    // CE.
+    // NOTE: Support use of the `unresolved` attribute to help polyfill
+    // custom elements' `:unresolved` feature.
     attributes.remove('unresolved');
     // user entry point
     _readyLog.info(() => '[$this]: ready');
     ready();
   }
 
-  /// Called when [prepareElement] is finished, which means that the element's
-  /// shadowRoot has been created, its event listeners have been setup,
-  /// attributes have been reflected to properties, and property observers have
-  /// been setup. To wait until the element has been attached to the default

[Siggi Cherem (dart-lang), 2014/11/25 17:53:42]

maybe keep this last sentence to help guide our users that read the dart docs?

[jakemac, 2014/12/01 18:42:51]

Done.

-  /// view, use [attached] or [domReady].
+  /// Lifecycle method called when the element has populated it's `shadowRoot`,
+  /// prepared data-observation, and made itself ready for API interaction.
   void ready() {}
 
-  /// domReady can be used to access elements in dom (descendants,
-  /// ancestors, siblings) such that the developer is enured to upgrade
-  /// ordering. If the element definitions have loaded, domReady
-  /// can be used to access upgraded elements.
-  ///
-  /// To use, override this method in your element.
+  /// Implement to access custom elements in dom descendants, ancestors,
+  /// or siblings. Because custom elements upgrade in document order,
+  /// elements accessed in `ready` or `attached` may not be upgraded. When
+  /// `domReady` is called, all registered custom elements are guaranteed
+  /// to have been upgraded.
   void domReady() {}
 
   void attached() {
     if (!_elementPrepared) {
       // Dart specific message for a common issue.
       throw new StateError('polymerCreated was not called for custom element '
           '$_name, this should normally be done in the .created() if Polymer '
           'is used as a mixin.');
     }
 
     cancelUnbindAll();
     if (!hasBeenAttached) {
       _hasBeenAttached = true;
       async((_) => domReady());
     }
   }
 
   void detached() {
     if (!preventDispose) asyncUnbindAll();
   }
 
-  /// Recursive ancestral <element> initialization, oldest first.
+  /// Walks the prototype-chain of this element and allows specific
+  /// classes a chance to process static declarations.
+  ///
+  /// In particular, each polymer-element has it's own `template`.
+  /// `parseDeclarations` is used to accumulate all element `template`s
+  /// from an inheritance chain.
+  ///
+  /// `parseDeclaration` static methods implemented in the chain are called
+  /// recursively, oldest first, with the `<polymer-element>` associated
+  /// with the current prototype passed as an argument.
+  ///
+  /// An element may override this method to customize shadow-root generation.
   void parseDeclarations(PolymerDeclaration declaration) {
     if (declaration != null) {
       parseDeclarations(declaration.superDeclaration);
       parseDeclaration(declaration.element);
     }
   }
 
-  /// Parse input `<polymer-element>` as needed, override for custom behavior.
+  /// Perform init-time actions based on static information in the
+  /// `<polymer-element>` instance argument.
+  ///
+  /// For example, the standard implementation locates the template associated
+  /// with the given `<polymer-element>` and stamps it into a shadow-root to
+  /// implement shadow inheritance.
+  ///
+  /// An element may override this method for custom behavior.
   void parseDeclaration(Element elementElement) {
     var template = fetchTemplate(elementElement);
 
     if (template != null) {
       var root = shadowFromTemplate(template);
 
       var name = elementElement.attributes['name'];
       if (name == null) return;
       shadowRoots[name] = root;
     }
   }
 
-  /// Return a shadow-root template (if desired), override for custom behavior.
+  /// Given a `<polymer-element>`, find an associated template (if any) to be
+  /// used for shadow-root generation.
+  ///
+  /// An element may override this method for custom behavior.
   Element fetchTemplate(Element elementElement) =>
       elementElement.querySelector('template');
 
   /// Utility function that stamps a `<template>` into light-dom.
   Node lightFromTemplate(Element template, [Node refNode]) {
     if (template == null) return null;
 
     // TODO(sorvell): mark this element as an event controller so that
     // event listeners on bound nodes inside it will be called on it.
     // Note, the expectation here is that events on all descendants
@@ skipping 70 matching lines @@
   /// Use [MutationObserver] if you want to listen to a stream of changes.
   Future<List<MutationRecord>> onMutation(Node node) {
     var completer = new Completer();
     new MutationObserver((mutations, observer) {
       observer.disconnect();
       completer.complete(mutations);
     })..observe(node, childList: true, subtree: true);
     return completer.future;
   }
 
+  // copy attributes defined in the element declaration to the instance
+  // e.g. <polymer-element name="x-foo" tabIndex="0"> tabIndex is copied
+  // to the element instance here.
   void copyInstanceAttributes() {
     _element._instanceAttributes.forEach((name, value) {
       attributes.putIfAbsent(name, () => value);
     });
   }
 
   void takeAttributes() {
     if (_element._publishLC == null) return;
     attributes.forEach(attributeToProperty);
   }
@@ skipping 26 matching lines @@
       // install new value (has side-effects)
       smoke.write(this, decl.name, newValue);
     }
   }
 
   /// Return the published property matching name, or null.
   // TODO(jmesserly): should we just return Symbol here?
   smoke.Declaration propertyForAttribute(String name) {
     final publishLC = _element._publishLC;
     if (publishLC == null) return null;
-    //console.log('propertyForAttribute:', name, 'matches', match);
     return publishLC[name];
   }
 
   /// Convert representation of [value] based on [type] and [currentValue].
   Object deserializeValue(String value, Object currentValue, Type type) =>
       deserialize.deserializeValue(value, currentValue, type);
 
   String serializeValue(Object value) {
     if (value == null) return null;
 
@@ skipping 38 matching lines @@
     var syntax = this.syntax;
     var t = templateBind(template);
     if (syntax == null && t.bindingDelegate == null) {
       syntax = element.syntax;
     }
     var dom = t.createInstance(this, syntax);
     _observers.addAll(getTemplateInstanceBindings(dom));
     return dom;
   }
 
+  /// Called by TemplateBinding/NodeBind to setup a binding to the given
+  /// property. It's overridden here to support property bindings in addition to
+  /// attribute bindings that are supported by default.
   Bindable bind(String name, bindable, {bool oneTime: false}) {
     var decl = propertyForAttribute(name);
     if (decl == null) {
       // Cannot call super.bind because template_binding is its own package
       return nodeBindFallback(this).bind(name, bindable, oneTime: oneTime);
     } else {
       // use n-way Polymer binding
       var observer = bindProperty(decl.name, bindable, oneTime: oneTime);
       // NOTE: reflecting binding information is typically required only for
       // tooling. It has a performance cost so it's opt-in in Node.bind.
@@ skipping 11 matching lines @@
       }
       return observer;
     }
   }
 
   _recordBinding(String name, observer) {
     if (bindings == null) bindings = {};
     this.bindings[name] = observer;
   }
 
-  bindFinished() => makeElementReady();
+  /// Called by TemplateBinding when all bindings on an element have been
+  /// executed. This signals that all element inputs have been gathered and it's
+  /// safe to ready the element, create shadow-root and start data-observation.
+  bindFinished() => _makeElementReady();
 
   Map<String, Bindable> get bindings => nodeBindFallback(this).bindings;
   set bindings(Map value) { nodeBindFallback(this).bindings = value; }
 
   TemplateInstance get templateInstance =>
       nodeBindFallback(this).templateInstance;
 
-  // TODO(sorvell): unbind/unbindAll has been removed, as public api, from
-  // TemplateBinding. We still need to close/dispose of observers but perhaps
-  // we should choose a more explicit name.
+  /// Called at detached time to signal that an element's bindings should be
+  /// cleaned up. This is done asynchronously so that users have the chance to
+  /// call `cancelUnbindAll` to prevent unbinding.
   void asyncUnbindAll() {
     if (_unbound == true) return;
     _unbindLog.fine(() => '[$_name] asyncUnbindAll');
     _unbindAllJob = scheduleJob(_unbindAllJob, unbindAll);
   }
 
+  /// This method should rarely be used and only if `cancelUnbindAll` has been
+  /// called to prevent element unbinding. In this case, the element's bindings
+  /// will not be automatically cleaned up and it cannot be garbage collected by
+  /// by the system. If memory pressure is a concern or a large amount of
+  /// elements need to be managed in this way, `unbindAll` can be called to
+  /// deactivate the element's bindings and allow its memory to be reclaimed.
   void unbindAll() {
     if (_unbound == true) return;
     closeObservers();
     closeNamedObservers();
     _unbound = true;
   }
 
+  //// Call in `detached` to prevent the element from unbinding when it is
+  //// detached from the dom. The element is unbound as a cleanup step that
+  //// allows its memory to be reclaimed. If `cancelUnbindAll` is used, consider
+  /// calling `unbindAll` when the element is no longer needed. This will allow
+  /// its memory to be reclaimed.
   void cancelUnbindAll() {
     if (_unbound == true) {
       _unbindLog.warning(() =>
           '[$_name] already unbound, cannot cancel unbindAll');
       return;
     }
     _unbindLog.fine(() => '[$_name] cancelUnbindAll');
     if (_unbindAllJob != null) {
       _unbindAllJob.stop();
       _unbindAllJob = null;
     }
   }
 
   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.
+  /// Creates a CompoundObserver to observe property changes.
+  /// NOTE, this is only done if there are any properties in the `_observe`
+  /// object.
   void createPropertyObserver() {
     final observe = _element._observe;
     if (observe != null) {
       var o = _propertyObserver = new CompoundObserver();
       // keep track of property observer so we can shut it down
       _observers.add(o);
 
       for (var path in observe.keys) {
         o.addPath(this, path);
 
         // TODO(jmesserly): on the Polymer side it doesn't look like they
         // will observe arrays unless it is a length == 1 path.
         observeArrayValue(path, path.getValueFrom(this), null);
       }
     }
   }
 
+  /// Start observing property changes.
   void openPropertyObserver() {
     if (_propertyObserver != null) {
       _propertyObserver.open(notifyPropertyChanges);
     }
 
     // Dart note: we need an extra listener only to continue supporting
     // @published properties that follow the old syntax until we get rid of it.
     // This workaround has timing issues so we prefer the new, not so nice,
     // syntax.
     if (_element._publish != null) {
       changes.listen(_propertyChangeWorkaround);
     }
   }
 
-  /// Responds to property changes on this element.
+  /// Handler for property changes; routes changes to observing methods.
+  /// Note: array valued properties are observed for array splices.
   void notifyPropertyChanges(List newValues, Map oldValues, List paths) {
     final observe = _element._observe;
     final called = new HashSet();
 
     oldValues.forEach((i, oldValue) {
       final newValue = newValues[i];
 
       // Date note: we don't need any special checking for null and undefined.
 
       // note: paths is of form [object, path, object, path]
@@ skipping 11 matching lines @@
         // TODO(sorvell): call method with the set of values it's expecting;
         // e.g. 'foo bar': 'invalidate' expects the new and old values for
         // foo and bar. Currently we give only one of these and then
         // deliver all the arguments.
         smoke.invoke(this, method,
             [oldValue, newValue, newValues, oldValues, paths], adjust: true);
       }
     });
   }
 
-  // Dart note: had to rename this to avoid colliding with
-  // Observable.deliverChanges. Even worse, super calls aren't possible or
-  // it prevents Polymer from being a mixin, so we can't override it even if
-  // we wanted to.
+  /// Force any pending property changes to synchronously deliver to handlers
+  /// specified in the `observe` object.
+  /// Note: normally changes are processed at microtask time.
+  ///
+  /// Dart note: had to rename this to avoid colliding with

[Siggi Cherem (dart-lang), 2014/11/25 17:53:42]

same here, remove one / - this comment is meant for the code, but not for dart
docs

[jakemac, 2014/12/01 18:42:52]

Done.

+  /// Observable.deliverChanges. Even worse, super calls aren't possible or
+  /// it prevents Polymer from being a mixin, so we can't override it even if
+  /// we wanted to.
   void deliverPropertyChanges() {
     if (_propertyObserver != null) {
       _propertyObserver.deliver();
     }
   }
 
   // Dart note: this workaround is only for old-style @published properties,
   // which have timing issues. See _bindOldStylePublishedProperty below.
   // TODO(sigmund): deprecate this.
   void _propertyChangeWorkaround(List<ChangeRecord> records) {
@@ skipping 234 matching lines @@
     }
 
     _eventsLog.fine(() => '<<< [$_name]: dispatch $callbackOrMethod');
   }
 
   /// Call [methodName] method on this object with [args].
   invokeMethod(Symbol methodName, List args) =>
       smoke.invoke(this, methodName, args, adjust: true);
 
   /// Invokes a function asynchronously.
-  /// This will call `Platform.flush()` and then return a `new Timer`
+  /// This will call `WebComponents.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.
   ///
   /// To cancel, call [Timer.cancel] on the result of this method.
   Timer asyncTimer(void method(), Duration timeout) {
     // 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.
 
     // when polyfilling Object.observe, ensure changes
     // propagate before executing the async method
     scheduleMicrotask(Observable.dirtyCheck);
-    _Platform.callMethod('flush'); // for polymer-js interop
+    _Polymer.callMethod('flush'); // for polymer-js interop

[Siggi Cherem (dart-lang), 2014/11/25 17:53:42]

I thought this was going to call _WebComponents.flush, not _Polymer.flush? Or do
we need to fix the comment instead?

[jakemac, 2014/12/01 18:42:52]

One is an alias of the other, they moved over to using Polymer.flush though

[Siggi Cherem (dart-lang), 2014/12/02 01:31:26]

OK. It might be worth to fix the comment then (same below)

[jakemac, 2014/12/03 18:34:57]

Done.

     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.
+  /// Invokes a function asynchronously. The context of the callback function is
+  /// function is bound to 'this' automatically. Returns a handle which may be
+  /// passed to cancelAsync to cancel the asynchronous call.
   ///
   /// If you would prefer to run the callback after a given duration, see
   /// the [asyncTimer] method.
   ///
   /// If you would like to cancel this, use [cancelAsync].
   int async(RequestAnimationFrameCallback method) {
     // when polyfilling Object.observe, ensure changes
     // propagate before executing the async method
     scheduleMicrotask(Observable.dirtyCheck);
-    _Platform.callMethod('flush'); // for polymer-js interop
+    _Polymer.callMethod('flush'); // for polymer-js interop

[Siggi Cherem (dart-lang), 2014/11/25 17:53:42]

ditto

[jakemac, 2014/12/01 18:42:51]

same

[jakemac, 2014/12/03 18:34:57]

Done.

     return window.requestAnimationFrame(method);
   }
 
-  /// Cancel an operation scenduled by [async]. This is just shorthand for:
-  ///     window.cancelAnimationFrame(id);
+  /// Cancel an operation scheduled by [async].
   void cancelAsync(int id) => window.cancelAnimationFrame(id);
 
   /// Fire a [CustomEvent] targeting [onNode], or `this` if onNode is not
   /// supplied. Returns the new event.
   CustomEvent fire(String type, {Object detail, Node onNode, bool canBubble,
         bool cancelable}) {
     var node = onNode != null ? onNode : this;
     var event = new CustomEvent(
       type,
       canBubble: canBubble != null ? canBubble : true,
@@ skipping 253 matching lines @@
 final Logger _eventsLog = new Logger('polymer.events');
 final Logger _unbindLog = new Logger('polymer.unbind');
 final Logger _bindLog = new Logger('polymer.bind');
 final Logger _watchLog = new Logger('polymer.watch');
 final Logger _readyLog = new Logger('polymer.ready');
 
 final Expando _eventHandledTable = new Expando<Set<Node>>();
 
 final JsObject _PolymerGestures = js.context['PolymerGestures'];