Specs: Element registration in the Dart world

sky/specs/dom.md

 Sky DOM APIs
 ============
 
 ```dart
 // ELEMENT TREE API
 
 abstract class ChildNode {
   @nonnull external TreeScope get ownerScope; // O(1)
 
   external ParentNode get parentNode; // O(1)
@@ skipping 61 matching lines @@
 }
 
 class Attr {
   const Attr (this.name, [this.value = '']); // O(1)
   final String name; // O(1)
   final String value; // O(1)
 }
 
 // @tagname annotation for registering elements
 // only useful when placed on classes that inherit from Element
-class tagname {
-  const tagname(this.value);
-  @nonnull final String value;
+class tagname extends AutomaticMetadata {
+  const tagname(this.name);
+  @nonnull final String name;
+  void init(DeclarationMirror target, Module module) {
+    assert(target is ClassMirror);
+    if (!target.isSubclassOf(reflectClass(Element)))
+      throw Error('@tagname can only be used on descendants of Element');
+    module.registerElement(name, (target as ClassMirror).reflectedType);
+  }
 }
 
 abstract class FindRoot { }
 
 abstract class Element extends ParentNode with ChildNode implements FindRoot {
-  Element({Map</*@nonnull*/ String, /*@nonnull*/ String> attributes: null,
-           List</*nonnull*/ ChildNode> nodes: null}); // O(M+N), M = number of attributes, N = number of nodes plus all their descendants
+  external Element({Map</*@nonnull*/ String, /*@nonnull*/ String> attributes: null,
+                   List</*nonnull*/ ChildNode> nodes: null,
+                   Module hostModule: null}); // O(M+N), M = number of attributes, N = number of nodes plus all their descendants
+  // initialises the internal attributes table
+  // appends the given child nodes
+  // if this.needsShadow, creates a shadow tree
 
   @nonnull String get tagName { // O(N) in number of annotations on the class
     // throws a StateError if the class doesn't have an @tagname annotation
     var tagnameClass = reflectClass(tagname);
     return (reflectClass(this.runtimeType).metadata.singleWhere((mirror) => mirror.type == tagnameClass).reflectee as tagname).value;
   }
 
   @nonnull external bool hasAttribute(@nonnull String name); // O(N) in number of attributes
   @nonnull external String getAttribute(@nonnull String name); // O(N) in number of attributes
   external void setAttribute(@nonnull String name, [@nonnull String value = '']); // O(N) in number of attributes
   external void removeAttribute(@nonnull String name); // O(N) in number of attributes
 
   // Returns a new Array and new Attr instances every time.
   @nonnull external List<Attr> getAttributes(); // O(N) in number of attributes
 
+  get bool needsShadow => false; // O(1)
   external ShadowRoot get shadowRoot; // O(1)
   // returns the shadow root
   // TODO(ianh): Should this be mutable? It would help explain how it gets set...
 
   void endTagParsedCallback() { }
   void attributeChangeCallback(String name, String oldValue, String newValue) { }
   // name will never be null when this is called by sky
 
   // TODO(ianh): does a node ever need to know when it's been redistributed?
 
@@ skipping 153 matching lines @@
 }
 
 class SelectorQuery {
   external SelectorQuery(@nonnull String selector); // O(F()) where F() is the complexity of the selector
 
   @nonnull external bool matches(@nonnull Element element); // O(F())
   external Element find(@nonnull FindRoot root); // O(N*F())+O(M) where N is the number of descendants and M the average depth of the tree
   @nonnull external List</*@nonnull*/ Element> findAll(FindRoot root); // O(N*F())+O(N*M) where N is the number of descendants and M the average depth of the tree
 }
 ```