Roll polymer packages to version 0.3.4

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.
+/// 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.
 ///
 /// For example:
 ///
 ///     class MyPlaybackElement extends PolymerElement {
 ///       // This will be available as an HTML attribute, for example:
 ///       //
 ///       //     <my-playback volume="11">
 ///       //
 ///       // It will support initialization and data-binding via <template>:
 ///       //
 ///       //     <template>
 ///       //       <my-playback volume="{{x}}">
 ///       //     </template>
 ///       //
 ///       // If the template is instantiated or given a model, `x` will be
 ///       // used for this field and updated whenever `volume` changes.
-///       @published double volume;
+///       @published
+///       double get volume => readValue(#volume);
+///       set volume(double newValue) => writeValue(#volume, newValue);
 ///
 ///       // This will be available as an HTML attribute, like above, but it
 ///       // will also serialize values set to the property to the attribute.
 ///       // In other words, attributes['volume2'] will contain a serialized
 ///       // version of this field.
-///       @PublishedProperty(reflect: true) double volume2;
+///       @PublishedProperty(reflect: true)
+///       double get volume2 => readValue(#volume2);
+///       set volume2(double newValue) => writeValue(#volume2, newValue);
 ///     }
 ///
+/// **Important note**: the pattern using `readValue` and `writeValue`
+/// guarantees that reading the property will give you the latest value at any
+/// given time, even if change notifications have not been propagated.
+///
+/// We still support using @published on a field, but this will not
+/// provide the same guarantees, so this is discouraged. For example:
+///
+///       // Avoid this if possible. This will be available as an HTML
+///       // attribute too, but you might need to delay reading volume3 
+///       // asynchronously to guarantee that you read the latest value
+///       // set through bindings.
+///       @published double volume3;
 const published = const PublishedProperty();
 
 /// An annotation used to publish a field as an attribute. See [published].
 class PublishedProperty extends ObservableProperty {
   /// Whether the property value should be reflected back to the HTML attribute.
   final bool reflect;
 
   const PublishedProperty({this.reflect: false});
 }
 
@@ skipping 19 matching lines @@
     if (n is! Iterable) {
       throw new UnsupportedError('ObserveProperty takes either an Iterable of '
           'names, or a space separated String, instead of `$n`.');
     }
     return n;
   }
 
   const ObserveProperty(this._names);
 }
 
+/// Use this to create computed properties that are updated automatically. The
+/// annotation includes a polymer expression that describes how this property
+/// value can be expressed in terms of the values of other properties. For
+/// example:
+///
+///     class MyPlaybackElement extends PolymerElement {
+///       @observable int x;
+///
+///       // Reading xTimes2 will return x * 2.
+///       @ComputedProperty('x * 2')
+///       int get xTimes2 => readValue(#xTimes2);
+///
+/// If the polymer expression is assignable, you can also define a setter for
+/// it. For example:
+///
+///       // Reading c will return a.b, writing c will update a.b.
+///       @ComputedProperty('a.b')
+///       get c => readValue(#c);
+///       set c(newValue) => writeValue(#c, newValue);
+///
+/// The expression can do anything that is allowed in a polymer expresssion,
+/// even making calls to methods in your element. However, dependencies that are
+/// only used within those methods and that are not visible in the polymer
+/// expression, will not be observed. For example:
+///
+///       // Because `x` only appears inside method `m`, we will not notice
+///       // that `d` has changed if `x` is modified. However, `d` will be
+///       // updated whenever `c` changes.
+///       @ComputedProperty('m(c)')
+///       get d => readValue(#d);
+///
+///       m(c) => c + x;
+class ComputedProperty {
+  /// A polymer expression, evaluated in the context of the custom element where
+  /// this annotation is used.
+  final String expression;
+
+  const ComputedProperty(this.expression);
+}
 
 /// Base class for PolymerElements deriving from HtmlElement.
 ///
 /// See [Polymer].
 class PolymerElement extends HtmlElement with Polymer, Observable {
   PolymerElement.created() : super.created() {
     polymerCreated();
   }
 }
 
@@ skipping 82 matching lines @@
   static Future get onReady => _onReady.future;
 
   /// The most derived `<polymer-element>` declaration for this element.
   PolymerDeclaration get element => _element;
   PolymerDeclaration _element;
 
   /// Deprecated: use [element] instead.
   @deprecated PolymerDeclaration get declaration => _element;
 
   Map<String, StreamSubscription> _namedObservers;
-  List<Iterable<Bindable>> _observers = [];
+  List<Bindable> _observers = [];
 
   bool _unbound; // lazy-initialized
   PolymerJob _unbindAllJob;
 
   CompoundObserver _propertyObserver;
   bool _readied = false;
 
   JsObject _jsElem;
 
   /// Returns the object that should be used as the event controller for
@@ skipping 43 matching lines @@
     if (_element != null) return _element.name;
     var isAttr = attributes['is'];
     return (isAttr == null || isAttr == '') ? localName : isAttr;
   }
 
   /// By default the data bindings will be cleaned up when this custom element
   /// is detached from the document. Overriding this to return `true` will
   /// prevent that from happening.
   bool get preventDispose => false;
 
+  /// Properties exposed by this element.
+  // Dart note: unlike Javascript we can't override the original property on
+  // the object, so we use this mechanism instead to define properties. See more
+  // details in [_PropertyAccessor].
+  Map<Symbol, _PropertyAccessor> _properties = {};
+
+  /// Helper to implement a property with the given [name]. This is used for
+  /// normal and computed properties. Normal properties can provide the initial
+  /// value using the [initialValue] function. Computed properties ignore
+  /// [initialValue], their value is derived from the expression in the
+  /// [ComputedProperty] annotation that appears above the getter that uses this
+  /// helper.
+  readValue(Symbol name, [initialValue()]) {
+    var property = _properties[name];
+    if (property == null) {
+      var value;
+      // Dart note: most computed properties are created in advance in
+      // createComputedProperties, but if one computed property depends on
+      // another, the declaration order might matter. Rather than trying to
+      // register them in order, we include here also the option of lazily
+      // creating the property accessor on the first read.
+      var binding = _getBindingForComputedProperty(name);
+      if (binding == null) { // normal property
+        value = initialValue != null ? initialValue() : null;
+      } else {
+        value = binding.value;
+      }
+      property = _properties[name] = new _PropertyAccessor(name, this, value);
+    }
+    return property.value;
+  }
+
+  /// Helper to implement a setter of a property with the given [name] on a
+  /// polymer element. This can be used on normal properties and also on
+  /// computed properties, as long as the expression used for the computed
+  /// property is assignable (see [ComputedProperty]).
+  writeValue(Symbol name, newValue) {
+    var property = _properties[name];
+    if (property == null) {
+      // Note: computed properties are created in advance in
+      // createComputedProperties, so we should only need to create here
+      // non-computed properties.
+      property = _properties[name] = new _PropertyAccessor(name, this, null);
+    }
+    property.value = newValue;
+  }
+
   /// If this class is used as a mixin, this method must be called from inside
   /// of the `created()` constructor.
   ///
   /// 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.');
@@ skipping 33 matching lines @@
 
   /// Initialize JS interop for this element. For now we just initialize the
   // JsObject, but in the future we could also initialize JS APIs here.
   _initJsObject() {
     _jsElem = new JsObject.fromBrowserObject(this);
   }
 
   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.
     attributes.remove('unresolved');
     // user entry point
@@ skipping 243 matching lines @@
   ///
   /// 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) {
     var syntax = this.syntax;
     var t = templateBind(template);
     if (syntax == null && t.bindingDelegate == null) {
       syntax = element.syntax;
     }
     var dom = t.createInstance(this, syntax);
-    registerObservers(getTemplateInstanceBindings(dom));
+    _observers.addAll(getTemplateInstanceBindings(dom));
     return dom;
   }
 
   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
@@ skipping 65 matching lines @@
       _forNodeTree(child, callback);
     }
   }
 
   /// Set up property observers.
   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
-      registerObservers([o]);
+      _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);
       }
     }
   }
 
   void openPropertyObserver() {
     if (_propertyObserver != null) {
       _propertyObserver.open(notifyPropertyChanges);
     }
-    // Dart note: we need an extra listener.
-    // see comment on [_propertyChange].
+
+    // 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(_propertyChange);
+      changes.listen(_propertyChangeWorkaround);
     }
   }
 
   /// Responds to property changes on this element.
   void notifyPropertyChanges(List newValues, Map oldValues, List paths) {
     final observe = _element._observe;
     final called = new HashSet();
 
     oldValues.forEach((i, oldValue) {
       final newValue = newValues[i];
@@ skipping 25 matching lines @@
   // 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.
   void deliverPropertyChanges() {
     if (_propertyObserver != null) {
       _propertyObserver.deliver();
     }
   }
 
-  // Dart note: this is not called by observe-js because we don't have
-  // the mechanism for defining properties on our proto.
-  // TODO(jmesserly): this has similar timing issues as our @published
-  // properties do generally -- it's async when it should be sync.
-  void _propertyChange(List<ChangeRecord> records) {
+  // 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) {
     for (var record in records) {
       if (record is! PropertyChangeRecord) continue;
 
-      final name = smoke.symbolToName(record.name);
-      final reflect = _element._reflect;
-      if (reflect != null && reflect.contains(name)) {
-        reflectPropertyToAttribute(name);
-      }
+      var name = record.name;
+      // The setter of a new-style property will create an accessor in
+      // _properties[name]. We can skip the workaround for those properties.
+      if (_properties[name] != null) continue;
+      _propertyChange(name);
     }
   }
 
+  void _propertyChange(Symbol nameSymbol) {
+    var name = smoke.symbolToName(nameSymbol);
+    var reflect = _element._reflect;
+    if (reflect != null && reflect.contains(name)) {
+      reflectPropertyToAttribute(name);
+    }
+  }
+
   void observeArrayValue(PropertyPath name, Object value, Object old) {
     final observe = _element._observe;
     if (observe == null) return;
 
     // we only care if there are registered side-effects
     var callbacks = observe[name];
     if (callbacks == null) return;
 
     // if we are observing the previous value, stop
     if (old is ObservableList) {
@@ skipping 10 matching lines @@
       }
       var sub = value.listChanges.listen((changes) {
         for (var callback in callbacks) {
           smoke.invoke(this, callback, [old], adjust: true);
         }
       });
       registerNamedObserver('${name}__array', sub);
     }
   }
 
-  void registerObservers(Iterable<Bindable> observers) {
-    _observers.add(observers);
+  emitPropertyChangeRecord(Symbol name, newValue, oldValue) {
+    if (identical(oldValue, newValue)) return;
+    _propertyChange(name);
   }
 
+  bindToAccessor(Symbol name, Bindable bindable, {resolveBindingValue: false}) {
+    // Dart note: our pattern is to declare the initial value in the getter.  We
+    // read it via smoke to ensure that the value is initialized correctly.
+    var oldValue = smoke.read(this, name);
+    var property = _properties[name];
+    if (property == null) {
+      // We know that _properties[name] is null only for old-style @published
+      // properties. This fallback is here to make it easier to deprecate the
+      // old-style of published properties, which have bad timing guarantees
+      // (see comment in _PolymerBinding).
+      return _bindOldStylePublishedProperty(name, bindable, oldValue);
+    }
+
+    property.bindable = bindable;
+    var value = bindable.open(property.updateValue);
+
+    if (resolveBindingValue) {
+      // capture A's value if B's value is null or undefined,
+      // otherwise use B's value
+      var v = (value == null ? oldValue : value);
+      if (!identical(value, oldValue)) {
+        bindable.value = value = v;
+      }
+    }
+
+    property.updateValue(value);
+    var o = new _CloseOnlyBinding(property);
+    _observers.add(o);
+    return o;
+  }
+
+  // Dart note: this fallback uses our old-style binding mechanism to be able to
+  // link @published properties with bindings. This mechanism is backwards from
+  // what Javascript does because we can't override the original property. This
+  // workaround also brings some timing issues which are described in detail in
+  // dartbug.com/18343.
+  // TODO(sigmund): deprecate old-style @published properties.
+  _bindOldStylePublishedProperty(Symbol name, Bindable bindable, oldValue) {
+    // capture A's value if B's value is null or undefined,
+    // otherwise use B's value
+    if (bindable.value == null) bindable.value = oldValue;
+
+    var o = new _PolymerBinding(this, name, bindable);
+    _observers.add(o);
+    return o;
+  }
+
+  _getBindingForComputedProperty(Symbol name) {
+    var exprString = element._computed[name];
+    if (exprString == null) return null;
+    var expr = PolymerExpressions.getExpression(exprString);
+    return PolymerExpressions.getBinding(expr, this,
+        globals: element.syntax.globals);
+  }
+
+  createComputedProperties() {
+    var computed = this.element._computed;
+    for (var name in computed.keys) {
+      try {
+        // Dart note: this is done in Javascript by modifying the prototype in
+        // declaration/properties.js, we can't do that, so we do it here.
+        var binding = _getBindingForComputedProperty(name);
+
+        // Follow up note: ideally we would only create the accessor object
+        // here, but some computed properties might depend on others and
+        // evaluating `binding.value` could try to read the value of another
+        // computed property that we haven't created yet. For this reason we
+        // also allow to also create the accessor in [readValue].
+        if (_properties[name] == null) {
+          _properties[name] = new _PropertyAccessor(name, this, binding.value);
+        }
+        bindToAccessor(name, binding);
+      } catch (e) {
+        window.console.error('Failed to create computed property $name'
+            ' (${computed[name]}): $e');
+      }
+    }
+  }
+
+  // Dart note: to simplify the code above we made registerObserver calls
+  // directly invoke _observers.add/addAll.
   void closeObservers() {
-    _observers.forEach(closeObserverList);
+    for (var o in _observers) {
+      if (o != null) o.close();
+    }
     _observers = [];
   }
 
-  void closeObserverList(Iterable<Bindable> observers) {
-    for (var o in observers) {
-      if (o != null) o.close();
-    }
-  }
-
   /// Bookkeeping observers for memory management.
   void registerNamedObserver(String name, StreamSubscription sub) {
     if (_namedObservers == null) {
       _namedObservers = new Map<String, StreamSubscription>();
     }
     _namedObservers[name] = sub;
   }
 
   bool closeNamedObserver(String name) {
     var sub = _namedObservers.remove(name);
@@ skipping 14 matching lines @@
   /// Bind the [name] property in this element to [bindable]. *Note* in Dart it
   /// is necessary to also define the field:
   ///
   ///     var myProperty;
   ///
   ///     ready() {
   ///       super.ready();
   ///       bindProperty(#myProperty,
   ///           new PathObserver(this, 'myModel.path.to.otherProp'));
   ///     }
-  Bindable bindProperty(Symbol name, Bindable bindable, {oneTime: false}) {
+  Bindable bindProperty(Symbol name, bindableOrValue, {oneTime: false}) {
     // 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.
 
     if (_bindLog.isLoggable(Level.FINE)) {
-      _bindLog.fine('bindProperty: [$bindable] to [$_name].[$name]');
+      _bindLog.fine('bindProperty: [$bindableOrValue] to [$_name].[$name]');
     }
 
-    // capture A's value if B's value is null or undefined,
-    // otherwise use B's value
-    // TODO(sorvell): need to review, can do with ObserverTransform
-    var v = bindable.value;
-    if (v == null) {
-      bindable.value = smoke.read(this, name);
+    if (oneTime) {
+      if (bindableOrValue is Bindable) {
+        _bindLog.warning('bindProperty: expected non-bindable value '
+            'on a one-time binding to [$_name].[$name], '
+            'but found $bindableOrValue.');
+      }
+      smoke.write(this, name, bindableOrValue);
+      return null;
     }
 
-    // TODO(jmesserly): we need to fix this -- it doesn't work like Polymer.js
-    // bindings. https://code.google.com/p/dart/issues/detail?id=18343
-    // apply Polymer two-way reference binding
-    //return Observer.bindToInstance(inA, inProperty, observable,
-    //    resolveBindingValue);
-    return new _PolymerBinding(this, name, bindable);
+    return bindToAccessor(name, bindableOrValue, resolveBindingValue: true);
   }
 
   /// Attach event listeners on the host (this) element.
   void addHostListeners() {
     var events = _element._eventDelegates;
     if (events.isEmpty) return;
 
     if (_eventsLog.isLoggable(Level.FINE)) {
       _eventsLog.fine('[$_name] addHostListeners: $events');
     }
@@ skipping 152 matching lines @@
 
     if (scope == null) return;
 
     if (_ShadowCss != null) {
       cssText = _shimCssText(cssText, scope is ShadowRoot ? scope.host : null);
     }
     var style = element.cssTextToScopeStyle(cssText,
         _STYLE_CONTROLLER_SCOPE);
     applyStyleToScope(style, scope);
     // cache that this style has been applied
-    Set styles = _scopeStyles[scope];
-    if (styles == null) _scopeStyles[scope] = styles = new Set();
-    styles.add('$_name$name');
+    styleCacheForScope(scope).add('$_name$name');
   }
 
   Node findStyleScope([node]) {
     // find the shadow root that contains this element
     var n = node;
     if (n == null) n = this;
     while (n.parentNode != null) {
       n = n.parentNode;
     }
     return n;
   }
 
-  bool scopeHasNamedStyle(Node scope, String name) {
-    Set styles = _scopeStyles[scope];
-    return styles != null && styles.contains(name);
+  bool scopeHasNamedStyle(Node scope, String name) =>
+      styleCacheForScope(scope).contains(name);
+
+  Map _polyfillScopeStyleCache = {};
+
+  Set styleCacheForScope(Node scope) {
+    var styles;
+    if (_hasShadowDomPolyfill) {
+      var name = scope is ShadowRoot ? scope.host.localName
+          : (scope as Element).localName;
+      var styles = _polyfillScopeStyleCache[name];
+      if (styles == null) _polyfillScopeStyleCache[name] = styles = new Set();
+    } else {
+      styles = _scopeStyles[scope];
+      if (styles == null) _scopeStyles[scope] = styles = new Set();
+    }
+    return styles;
   }
 
   static final _scopeStyles = new Expando();
 
   static String _shimCssText(String cssText, [Element host]) {
     var name = '';
     var is_ = false;
     if (host != null) {
       name = host.localName;
       is_ = host.attributes.containsKey('is');
@@ skipping 44 matching lines @@
   ///
   /// Returns the newly created job.
   // Dart note: renamed to scheduleJob to be a bit more consistent with Dart.
   PolymerJob scheduleJob(PolymerJob job, void callback(), [Duration wait]) {
     if (job == null) job = new PolymerJob._();
     // Dart note: made start smarter, so we don't need to call stop.
     return job..start(callback, wait);
   }
 }
 
-// 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
+// Dart note: this is related to _bindOldStylePublishedProperty. Polymer
+// addresses n-way bindings by metaprogramming: redefine the property on the
+// PolymerElement instance to always get its value from the model@path. This is
+// supported in Dart using a new style of @published property declaration using
+// the `readValue` and `writeValue` methods above. In the past we used to work
+// around this by listening to changes on both sides and updating the values.
+// This object provides the hooks to do this.
+// TODO(sigmund,jmesserly): delete after a deprecation period.
 class _PolymerBinding extends Bindable {
   final Polymer _target;
   final Symbol _property;
   final Bindable _bindable;
   StreamSubscription _sub;
   Object _lastValue;
 
   _PolymerBinding(this._target, this._property, this._bindable) {
     _sub = _target.changes.listen(_propertyValueChanged);
     _updateNode(open(_updateNode));
   }
 
   void _updateNode(newValue) {
     _lastValue = newValue;
     smoke.write(_target, _property, newValue);
+    // Note: we don't invoke emitPropertyChangeRecord here because that's
+    // done by listening on changes on the PolymerElement.
   }
 
   void _propertyValueChanged(List<ChangeRecord> records) {
     for (var record in records) {
       if (record is PropertyChangeRecord && record.name == _property) {
         final newValue = smoke.read(_target, _property);
         if (!identical(_lastValue, newValue)) {
           this.value = newValue;
         }
         return;
       }
     }
   }
 
   open(callback(value)) => _bindable.open(callback);
   get value => _bindable.value;
   set value(newValue) => _bindable.value = newValue;
 
   void close() {
     if (_sub != null) {
       _sub.cancel();
       _sub = null;
     }
     _bindable.close();
   }
 }
 
+// Ported from an inline object in instance/properties.js#bindToAccessor.
+class _CloseOnlyBinding extends Bindable {
+  final _PropertyAccessor accessor;
+
+  _CloseOnlyBinding(this.accessor);
+
+  open(callback) {}
+  get value => null;
+  set value(newValue) {}
+  deliver() {}
+
+  void close() {
+    if (accessor.bindable == null) return;
+    accessor.bindable.close();
+    accessor.bindable = null;
+  }
+}
+
 bool _toBoolean(value) => null != value && false != value;
 
 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 _eventHandledTable = new Expando<Set<Node>>();
 
 final JsObject _PolymerGestures = js.context['PolymerGestures'];