big update to observe, template_binding, polymer

pkg/polymer/lib/src/declaration.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;
 
 /**
  * **Warning**: this class is experiental and subject to change.
  *
  * The implementation for the `polymer-element` element.
@@ skipping 23 matching lines @@
   // TODO(jmesserly): this is a cache, because it's tricky in Dart to get from
   // Type -> Supertype.
   Type _supertype;
   Type get supertype => _supertype;
 
   // TODO(jmesserly): this is also a cache, since we can't store .element on
   // each level of the __proto__ like JS does.
   PolymerDeclaration _super;
   PolymerDeclaration get superDeclaration => _super;
 
+  String _extendsName;
+
   String _name;
   String get name => _name;
 
   /**
    * Map of publish properties. Can be a [VariableMirror] or a [MethodMirror]
    * representing a getter. If it is a getter, there will also be a setter.
+   *
+   * Note: technically these are always single properties, so we could use
+   * a Symbol instead of a PropertyPath. However there are lookups between
+   * this map and [_observe] so it is easier to just track paths.
    */
-  Map<Symbol, DeclarationMirror> _publish;
+  Map<PropertyPath, DeclarationMirror> _publish;
 
   /** The names of published properties for this polymer-element. */
-  Iterable<Symbol> get publishedProperties =>
-      _publish != null ? _publish.keys : const [];
+  Iterable<String> get publishedProperties =>
+      _publish != null ? _publish.keys.map((p) => '$p') : const [];
 
   /** Same as [_publish] but with lower case names. */
   Map<String, DeclarationMirror> _publishLC;
 
-  Map<Symbol, Symbol> _observe;
+  Map<PropertyPath, Symbol> _observe;
 
   Map<String, Object> _instanceAttributes;
 
   List<Element> _sheets;
   List<Element> get sheets => _sheets;
 
   List<Element> _styles;
   List<Element> get styles => _styles;
 
   DocumentFragment get templateContent {
     final template = this.querySelector('template');
     return template != null ? templateBind(template).content : null;
   }
 
   /** Maps event names and their associated method in the element class. */
   final Map<String, String> _eventDelegates = {};
 
   /** Expected events per element node. */
   // TODO(sigmund): investigate whether we need more than 1 set of local events
   // per element (why does the js implementation stores 1 per template node?)
   Expando<Set<String>> _templateDelegates;
 
   PolymerDeclaration.created() : super.created() {
     // fetch the element name
     _name = attributes['name'];
+    // fetch our extendee name
+    _extendsName = attributes['extends'];
     // install element definition, if ready
     registerWhenReady();
   }
 
   void registerWhenReady() {
     // if we have no prototype, wait
     if (waitingForType(name)) {
       return;
     }
-    // fetch our extendee name
-    var extendee = attributes['extends'];
-    if (waitingForExtendee(extendee)) {
+    if (waitingForExtendee(_extendsName)) {
       //console.warn(name + ': waitingForExtendee:' + extendee);
       return;
     }
     // TODO(sjmiles): HTMLImports polyfill awareness:
     // elements in the main document are likely to parse
     // in advance of elements in imports because the
     // polyfill parser is simulated
     // therefore, wait for imports loaded before
     // finalizing elements in the main document
     // TODO(jmesserly): Polymer.dart waits for HTMLImportsLoaded, so I've
     // removed "whenImportsLoaded" for now. Restore the workaround if needed.
-    _register(extendee);
+    _register(_extendsName);
   }
 
   void _register(extendee) {
     //console.group('registering', name);
     register(name, extendee);
     //console.groupEnd();
     // subclasses may now register themselves
     _notifySuper(name);
   }
 
@@ skipping 61 matching lines @@
 
     // get basal prototype
     _supertype = _getRegisteredType(extendee);
     if (_supertype != null) _super = _getDeclaration(extendee);
 
     var cls = reflectClass(_type);
 
     // transcribe `attributes` declarations onto own prototype's `publish`
     publishAttributes(cls, _super);
 
-    publishProperties(type);
+    publishProperties(_type);
 
     inferObservers(cls);
 
+    // desugar compound observer syntax, e.g. @ObserveProperty('a b c')
+    explodeObservers(cls);
+
     // Skip the rest in Dart:
     // chain various meta-data objects to inherited versions
     // chain custom api to inherited
     // build side-chained lists to optimize iterations
     // inherit publishing meta-data
     // x-platform fixup
   }
 
   /** Implement various declarative features. */
   void desugar(name, extendee) {
     // compile list of attributes to copy to instances
     accumulateInstanceAttributes();
     // parse on-* delegates declared on `this` element
     parseHostEvents();
     // install external stylesheets as if they are inline
     installSheets();
 
+    adjustShadowElement();
+
     // TODO(sorvell): install a helper method this.resolvePath to aid in
     // setting resource paths. e.g.
     // this.$.image.src = this.resolvePath('images/foo.png')
     // Potentially remove when spec bug is addressed.
     // https://www.w3.org/Bugs/Public/show_bug.cgi?id=21407
     // TODO(jmesserly): resolvePath not ported, see first comment in this class.
 
     // under ShadowDOMPolyfill, transforms to approximate missing CSS features
     _shimShadowDomStyling(templateContent, name, extendee);
 
     var cls = reflectClass(type);
     // TODO(jmesserly): this feels unnatrual in Dart. Since we have convenient
     // lazy static initialization, can we get by without it?
     var registered = cls.declarations[#registerCallback];
     if (registered != null &&
         registered is MethodMirror &&
         registered.isStatic &&
         registered.isRegularMethod) {
       cls.invoke(#registerCallback, [this]);
     }
   }
 
+  // TODO(sorvell): remove when spec addressed:
+  // https://www.w3.org/Bugs/Public/show_bug.cgi?id=22460
+  // make <shadow></shadow> be <shadow><content></content></shadow>
+  void adjustShadowElement() {
+    // TODO(sorvell): avoid under SD polyfill until this bug is addressed:
+    // https://github.com/Polymer/ShadowDOM/issues/297
+    if (!_hasShadowDomPolyfill) {
+      final content = templateContent;
+      if (content == null) return;
+
+      for (var s in content.querySelectorAll('shadow')) {
+        if (s.nodes.isEmpty) s.append(new ContentElement());
+      }
+    }
+  }
+
   void registerType(String name) {
     var baseTag;
     var decl = this;
     while (decl != null) {
       baseTag = decl.attributes['extends'];
       decl = decl.superDeclaration;
     }
     document.register(name, type, extendsTag: baseTag);
   }
 
   void publishAttributes(ClassMirror cls, PolymerDeclaration superDecl) {
     // get properties to publish
     if (superDecl != null && superDecl._publish != null) {
       // Dart note: even though we walk the type hierarchy in
       // _getPublishedProperties, this will additionally include any names
       // published via the `attributes` attribute.
       _publish = new Map.from(superDecl._publish);
     }
 
     _publish = _getPublishedProperties(cls, _publish);
 
     // merge names from 'attributes' attribute
     var attrs = attributes['attributes'];
     if (attrs != null) {
       // names='a b c' or names='a,b,c'
       // record each name for publishing
-      for (var attr in attrs.split(attrs.contains(',') ? ',' : ' ')) {
+      for (var attr in attrs.split(_ATTRIBUTES_REGEX)) {
         // remove excess ws
         attr = attr.trim();
 
         // do not override explicit entries
-        if (attr != '' && _publish != null && _publish.containsKey(attr)) {
+        if (attr == '') continue;
+
+        var property = new Symbol(attr);
+        var path = new PropertyPath([property]);
+        if (_publish != null && _publish.containsKey(path)) {
           continue;
         }
 
-        var property = new Symbol(attr);
         var mirror = _getProperty(cls, property);
         if (mirror == null) {
           window.console.warn('property for attribute $attr of polymer-element '
               'name=$name not found.');
           continue;
         }
         if (_publish == null) _publish = {};
-        _publish[property] = mirror;
+        _publish[path] = mirror;
       }
     }
 
     // NOTE: the following is not possible in Dart; fields must be declared.
     // install 'attributes' as properties on the prototype,
     // but don't override
   }
 
   void accumulateInstanceAttributes() {
     // inherit instance attributes
@@ skipping 83 matching lines @@
             new StyleElement()..text = '$cssText',
             content.firstChild);
       }
     }
   }
 
   List<Element> findNodes(String selector, [bool matcher(Element e)]) {
     var nodes = this.querySelectorAll(selector).toList();
     var content = templateContent;
     if (content != null) {
-      nodes = nodes..addAll(content.queryAll(selector));
+      nodes = nodes..addAll(content.querySelectorAll(selector));
     }
     if (matcher != null) return nodes.where(matcher).toList();
     return nodes;
   }
 
   /**
    * Promotes external stylesheets and style elements with the attribute
    * polymer-scope='global' into global scope.
    * This is particularly useful for defining @keyframe rules which
    * currently do not function in scoped or shadow style elements.
    * (See wkb.ug/72462)
    */
   // TODO(sorvell): remove when wkb.ug/72462 is addressed.
   void installGlobalStyles() {
     var style = styleForScope(_STYLE_GLOBAL_SCOPE);
     Polymer.applyStyleToScope(style, document.head);
   }
 
   String cssTextForScope(String scopeDescriptor) {
     var cssText = new StringBuffer();
     // handle stylesheets
     var selector = '[$_SCOPE_ATTR=$scopeDescriptor]';
     matcher(s) => s.matches(selector);
 
     for (var sheet in sheets.where(matcher)) {
       cssText..write(_cssTextFromSheet(sheet))..write('\n\n');
     }
     // handle cached style elements
     for (var style in styles.where(matcher)) {
-      cssText..write(style.textContent)..write('\n\n');

[Siggi Cherem (dart-lang), 2014/02/03 22:52:48]

was this just broken before :/?

[Jennifer Messerly, 2014/02/04 00:33:06]

apparently, yes :)

+      cssText..write(style.text)..write('\n\n');
     }
     return cssText.toString();
   }
 
   StyleElement styleForScope(String scopeDescriptor) {
     var cssText = cssTextForScope(scopeDescriptor);
     return cssTextToScopeStyle(cssText, scopeDescriptor);
   }
 
   StyleElement cssTextToScopeStyle(String cssText, String scopeDescriptor) {
     if (cssText == '') return null;
 
     return new StyleElement()
         ..text = cssText
         ..attributes[_STYLE_SCOPE_ATTRIBUTE] = '$name-$scopeDescriptor';
   }
 
   /**
    * fetch a list of all observable properties names in our inheritance chain
    * above Polymer.
    */
-  // TODO(sjmiles): perf: reflection is slow, relatively speaking
-  // If an element may take 6us to create, getCustomPropertyNames might
-  // cost 1.6us more.
   void inferObservers(ClassMirror cls) {
-    if (cls == _objectType) return;
+    if (cls == _htmlElementType) return;
     inferObservers(cls.superclass);
     for (var method in cls.declarations.values) {
       if (method is! MethodMirror || method.isStatic
           || !method.isRegularMethod) continue;
 
       String name = MirrorSystem.getName(method.simpleName);
       if (name.endsWith(_OBSERVE_SUFFIX) && name != 'attributeChanged') {
-        if (_observe == null) _observe = new Map();
+        // TODO(jmesserly): now that we have a better system, should we
+        // deprecate *Changed methods?
+        if (_observe == null) _observe = new HashMap();
         name = name.substring(0, name.length - 7);
-        _observe[new Symbol(name)] = method.simpleName;
+        _observe[new PropertyPath(name)] = method.simpleName;
       }
     }
   }
 
+  void explodeObservers(ClassMirror cls) {

[Siggi Cherem (dart-lang), 2014/02/03 22:52:48]

nit: consider adding a short doc here to point to [ObserveProperty].

[Jennifer Messerly, 2014/02/04 00:33:06]

sure. wish polymer-js would doc these :|

+    if (cls == _htmlElementType) return;
+
+    explodeObservers(cls.superclass);
+    for (var method in cls.declarations.values) {
+      if (method is! MethodMirror || method.isStatic
+          || !method.isRegularMethod) continue;
+
+      for (var meta in _safeGetMetadata(method)) {
+        if (meta.reflectee is! ObserveProperty) continue;
+
+        if (_observe == null) _observe = new HashMap();
+
+        for (String name in meta.reflectee.names) {
+          _observe[new PropertyPath(name)] = method.simpleName;

[Siggi Cherem (dart-lang), 2014/02/03 22:52:48]

what if 2 methods react on the same path?

@ObserveProperties("a.b.c d")
doA() {} 

@ObserveProperties("a.b.c e")
doB() {} 

[Jennifer Messerly, 2014/02/04 00:33:06]

good catch. JS doesn't support this. Added support for it. 

+        }
+      }
+    }
+  }
   void publishProperties(Type type) {

[Siggi Cherem (dart-lang), 2014/02/03 22:52:48]

nit: + empty line above

[Jennifer Messerly, 2014/02/04 00:33:06]

Done.

     // Dart note: _publish was already populated by publishAttributes
     if (_publish != null) _publishLC = _lowerCaseMap(_publish);
   }
 
-  Map<String, dynamic> _lowerCaseMap(Map<Symbol, dynamic> properties) {
+  Map<String, dynamic> _lowerCaseMap(Map<PropertyPath, dynamic> properties) {
     final map = new Map<String, dynamic>();
     properties.forEach((name, value) {
-      map[MirrorSystem.getName(name).toLowerCase()] = value;
+      map['$name'.toLowerCase()] = value;

[Siggi Cherem (dart-lang), 2014/02/03 22:52:48]

'$name' -> name ? or is this to protect from key being null?

[Jennifer Messerly, 2014/02/04 00:33:06]

name is a PropertyPath, not a String. Clarified.

     });
     return map;
   }
 }
 
 /// maps tag names to prototypes
 final Map _typesByName = new Map<String, Type>();
 
 Type _getRegisteredType(String name) => _typesByName[name];
 
@@ skipping 17 matching lines @@
   }
 }
 
 /// track document.register'ed tag names and their declarations
 final Map _declarations = new Map<String, PolymerDeclaration>();
 
 bool _isRegistered(String name) => _declarations.containsKey(name);
 PolymerDeclaration _getDeclaration(String name) => _declarations[name];
 
 final _objectType = reflectClass(Object);
-
+final _htmlElementType = reflectClass(HtmlElement);
 
 Map _getPublishedProperties(ClassMirror cls, Map props) {
-  if (cls == _objectType) return props;
+  if (cls == _htmlElementType) return props;
   props = _getPublishedProperties(cls.superclass, props);
   for (var member in cls.declarations.values) {
     if (member.isStatic || member.isPrivate) continue;
 
     if (member is VariableMirror && !member.isFinal
         || member is MethodMirror && member.isGetter) {
 
       for (var meta in member.metadata) {
         if (meta.reflectee is PublishedProperty) {
           // Note: we delay the setter check until we find @published because
           // it's a tad expensive.
           if (member is! MethodMirror || _hasSetter(cls, member)) {
             if (props == null) props = {};
-            props[member.simpleName] = member;
+            props[new PropertyPath([member.simpleName])] = member;
           }
           break;
         }
       }
     }
   }
 
   return props;
 }
 
@@ skipping 12 matching lines @@
     // bug introduced between Chrome 31 and 32. After 32
     // JsClassMirror.declarations on Object calls
     // JsClassMirror.typeVariables, which tries to get the _jsConstructor's
     // .prototype["<>"]. This ends up getting the "" property instead, maybe
     // because "<>" doesn't exist, and gets ";" which then blows up because
     // the code later on expects a List of ints.
   } while (cls != _objectType);
   return null;
 }
 
+List _safeGetMetadata(MethodMirror method) {
+  // TODO(jmesserly): dart2js blows up getting metadata from methods in some
+  // cases. Why does this happen? It seems like the culprit might be named
+  // arguments. Unfortunately even calling method.parameters also
+  // triggers the bug in computeFunctionRti. For now we guard against it
+  // with this check.
+  try {
+    return method.metadata;
+  } catch (e) {
+    return [];
+  }
+}
+
 bool _hasSetter(ClassMirror cls, MethodMirror getter) {
   var setterName = new Symbol('${MirrorSystem.getName(getter.simpleName)}=');
   var mirror = cls.declarations[setterName];
   return mirror is MethodMirror && mirror.isSetter;
 }
 
 
 /** Attribute prefix used for declarative event handlers. */
 const _EVENT_PREFIX = 'on-';
 
 /** Whether an attribute declares an event. */
 bool _hasEventPrefix(String attr) => attr.startsWith(_EVENT_PREFIX);
 
 String _removeEventPrefix(String name) => name.substring(_EVENT_PREFIX.length);
 
 /**
  * Using Polymer's platform/src/ShadowCSS.js passing the style tag's content.
  */
 void _shimShadowDomStyling(DocumentFragment template, String name,
     String extendee) {
-  if (js.context == null || template == null) return;
-  if (!js.context.hasProperty('ShadowDOMPolyfill')) return;
+  if (template == null || !_hasShadowDomPolyfill) return;
 
   var platform = js.context['Platform'];
   if (platform == null) return;
   var shadowCss = platform['ShadowCSS'];
   if (shadowCss == null) return;
   shadowCss.callMethod('shimStyling', [template, name, extendee]);
 }
 
+final bool _hasShadowDomPolyfill = js.context != null &&
+    js.context.hasProperty('ShadowDOMPolyfill');
+
 const _STYLE_SELECTOR = 'style';
 const _SHEET_SELECTOR = '[rel=stylesheet]';
 const _STYLE_GLOBAL_SCOPE = 'global';
 const _SCOPE_ATTR = 'polymer-scope';
 const _STYLE_SCOPE_ATTRIBUTE = 'element';
 const _STYLE_CONTROLLER_SCOPE = 'controller';
 
 String _cssTextFromSheet(LinkElement sheet) {
   if (sheet == null) return '';
 
@@ skipping 32 matching lines @@
 // TODO(jmesserly): is this list complete?
 final _eventTranslations = const {
   // TODO(jmesserly): these three Polymer.js translations won't work in Dart,
   // because we strip the webkit prefix (below). Reconcile.
   'webkitanimationstart': 'webkitAnimationStart',
   'webkitanimationend': 'webkitAnimationEnd',
   'webkittransitionend': 'webkitTransitionEnd',
 
   'domfocusout': 'DOMFocusOut',
   'domfocusin': 'DOMFocusIn',
+  'dommousescroll': 'DOMMouseScroll',
 
   // TODO(jmesserly): Dart specific renames. Reconcile with Polymer.js
   'animationend': 'webkitAnimationEnd',
   'animationiteration': 'webkitAnimationIteration',
   'animationstart': 'webkitAnimationStart',
   'doubleclick': 'dblclick',
   'fullscreenchange': 'webkitfullscreenchange',
   'fullscreenerror': 'webkitfullscreenerror',
   'keyadded': 'webkitkeyadded',
   'keyerror': 'webkitkeyerror',
@@ skipping 10 matching lines @@
   return map;
 }();
 
 // Dart note: we need this function because we have additional renames JS does
 // not have. The JS renames are simply case differences, whereas we have ones
 // like doubleclick -> dblclick and stripping the webkit prefix.
 String _eventNameFromType(String eventType) {
   final result = _reverseEventTranslations[eventType];
   return result != null ? result : eventType;
 }
+
+final _ATTRIBUTES_REGEX = new RegExp(r'\s|,');