Specs: make element registrations be per-module, define how they are

sky/specs/apis.md

 APIs
 ====
 
 The Sky core API
 ----------------
 
 ```javascript
 module 'sky:core' {
 
   // EVENTS
 
-  interface Event {
+  class Event {
     constructor (String type, Boolean bubbles, any data); // O(1)
     readonly attribute String type; // O(1)
     readonly attribute Boolean bubbles; // O(1)
     attribute any data; // O(1)
 
     readonly attribute EventTarget target; // O(1)
     void preventDefault(); // O(1)
     attribute any result; // O(1) // defaults to undefined
 
     // TODO(ianh): do events get blocked at scope boundaries, e.g. focus events when both sides are in the scope?
     // TODO(ianh): do events ger retargetted, e.g. focus when leaving a custom element?
   }
 
   callback EventListener any (Event event); // return value is assigned to Event.result
 
-  interface EventTarget {
+  abstract class EventTarget {
     any dispatchEvent(Event event); // O(N) in total number of listeners for this type in the chain // returns Event.result
     void addEventListener(String type, EventListener listener); // O(1)
     void removeEventListener(String type, EventListener listener); // O(N) in event listeners with that type
     private Array<String> getRegisteredEventListenerTypes(); // O(N)
     private Array<EventListener> getRegisteredEventListenersForType(String type); // O(N)
   }
 
-  interface CustomEventTarget : EventTarget {
+  class CustomEventTarget : EventTarget {
     constructor (); // O(1)
     attribute EventTarget parentNode; // getter O(1), setter O(N) in height of tree, throws if this would make a loop
 
     // you can inherit from this to make your object into an event target
   }
 
 
 
   // DOM
 
   typedef ChildNode (Element or Text);
   typedef ChildArgument (Element or Text or String);
 
-  abstract interface Node : EventTarget {
+  abstract class Node : EventTarget {
     readonly attribute TreeScope? ownerScope; // O(1)
     
     readonly attribute ParentNode? parentNode; // O(1)
     readonly attribute Element? parentElement; // O(1) // if parentNode isn't an element, returns null
     readonly attribute ChildNode? previousSibling; // O(1)
     readonly attribute ChildNode? nextSibling; // O(1)
     
     // the following all throw if parentNode is null
     void insertBefore(ChildArgument... nodes); // O(N) in number of arguments plus all their descendants
     void insertAfter(ChildArgument... nodes); // O(N) in number of arguments plus all their descendants
     void replaceWith(ChildArgument... nodes); // O(N) in number of descendants plus arguments plus all their descendants
     void remove(); // O(N) in number of descendants
     Node cloneNode(Boolean deep); // O(1) if deep=false, O(N) in the number of descendants if deep=true
 
     // called when parentNode changes
     virtual void parentChangeCallback(ParentNode? oldParent, ParentNode? newParent, ChildNode? previousSibling, ChildNode? nextSibling); // O(N) in descendants (calls attached/detached)
     virtual void attachedCallback(); // noop
     virtual void detachedCallback(); // noop
   }
 
-  abstract interface ParentNode : Node {
+  abstract class ParentNode : Node {
     readonly attribute ChildNode? firstChild; // O(1)
     readonly attribute ChildNode? lastChild; // O(1)
     
     // Returns a new Array every time.
     Array<ChildNode> getChildNodes(); // O(N) in number of child nodes
     Array<Element> getChildElements(); // O(N) in number of child nodes // TODO(ianh): might not be necessary if we have the parser drop unnecessary whitespace text nodes
 
     void append(ChildArgument... nodes); // O(N) in number of arguments plus all their descendants
     void prepend(ChildArgument... nodes); // O(N) in number of arguments plus all their descendants
     void replaceChildrenWith(ChildArgument... nodes); // O(N) in number of descendants plus arguments plus all their descendants
   }
 
-  interface Attr {
+  class Attr {
     constructor (String name, String value); // O(1)
     readonly attribute String name; // O(1)
     readonly attribute String value; // O(1)
   }
 
-  interface Element : ParentNode {
+  abstract class Element : ParentNode {

[esprehn, 2014/10/31 23:13:44]

Do we get rid of "upgrade" ? Right now custom elements start off as Element
instances before we prototype swizzle them.

     readonly attribute String tagName; // O(1)
 
     Boolean hasAttribute(String name); // O(N) in arguments
     String getAttribute(String name); // O(N) in arguments
     void setAttribute(String name, String value); // O(N) in arguments
     void removeAttribute(String name); // O(N) in arguments
     
     // Returns a new Array and new Attr instances every time.
     Array<Attr> getAttributes(); // O(N) in arguments
 
     readonly attribute ShadowRoot? shadowRoot; // O(1) // returns the shadow root
     Array<ContentElement> getDestinationInsertionPoints(); // O(N) in number of insertion points the node is in
 
     virtual void attributeChangeCallback(String name, String? oldValue, String? newValue); // noop
     // TODO(ianh): does a node ever need to know when it's been redistributed?
   }
-  Element createElement(String tagName, Dictionary attributes, ChildArguments... nodes); // O(M+N), M = number of attributes, N = number of nodes plus all their descendants
-  Element createElement(String tagName, Dictionary attributes); // shorthand
-  Element createElement(String tagName, ChildArguments... nodes); // shorthand
-  Element createElement(String tagName); // shorthand
 
-  dictionary ElementRegistration {
-    String tagName;
-    Boolean shadow;
-    Object prototype;
-  }
-  Object registerElement(ElementRegistration options); // O(N) in number of outstanding elements with that tag name to be upgraded
-
-  interface Text : Node {
+  class Text : Node {
     constructor (String value); // O(1)
     attribute String value; // O(1)
 
     void replaceWith(String node); // O(1) // special case override of Node.replaceWith()
 
     virtual void valueChangeCallback(String? oldValue, String? newValue); // noop
   }
 
-  interface DocumentFragment : ParentNode {
+  class DocumentFragment : ParentNode {
     constructor (ChildArguments... nodes); // O(N) in number of arguments plus all their descendants
   }
 
-  abstract interface TreeScope : ParentNode {
+  abstract class TreeScope : ParentNode {
     readonly attribute Document? ownerDocument; // O(1)
     readonly attribute TreeScope? parentScope; // O(1)
 
     Element? findId(String id); // O(1)
   }
 
-  interface ShadowRoot : TreeScope {
+  class ShadowRoot : TreeScope {
     constructor (Element host); // O(1) // note that there is no way in the API to use a newly created ShadowRoot
     readonly attribute Element host; // O(1)
   }
 
-  interface Document : TreeScope {
+  class Document : TreeScope {
     constructor (ChildArguments... nodes); // O(N) in number of arguments plus all their descendants
   }
   
-  interface SelectorQuery {
+  class SelectorQuery {
     constructor (String selector); // O(F()) where F() is the complexity of the selector
 
     Boolean matches(Element element); // O(F())
     Element? find(ParentNode root); // O(N*F()) where N is the number of descendants
     Array<Element> findAll(ParentNode root); // O(N*F()) where N is the number of descendants
   }
 
   // Built-in Elements
-  interface ImportElement : Element { }
-  interface TemplateElement : Element {
+  class ImportElement : Element {
+    constructor (Dictionary attributes, ChildArguments... nodes); // O(M+N), M = number of attributes, N = number of nodes plus all their descendants
+    constructor (ChildArguments... nodes); // shorthand
+    constructor (Dictionary attributes); // shorthand
+    constructor (); // shorthand
+  }
+  class TemplateElement : Element {
+    constructor (Dictionary attributes, ChildArguments... nodes); // O(M+N), M = number of attributes, N = number of nodes plus all their descendants
+    constructor (ChildArguments... nodes); // shorthand
+    constructor (Dictionary attributes); // shorthand
+    constructor (); // shorthand
     readonly attribute DocumentFragment content; // O(1)
   }
-  interface ScriptElement : Element { }
-  interface StyleElement : Element { }
-  interface ContentElement : Element {
+  class ScriptElement : Element {
+    constructor (Dictionary attributes, ChildArguments... nodes); // O(M+N), M = number of attributes, N = number of nodes plus all their descendants
+    constructor (ChildArguments... nodes); // shorthand
+    constructor (Dictionary attributes); // shorthand
+    constructor (); // shorthand
+  }
+  class StyleElement : Element {
+    constructor (Dictionary attributes, ChildArguments... nodes); // O(M+N), M = number of attributes, N = number of nodes plus all their descendants
+    constructor (ChildArguments... nodes); // shorthand
+    constructor (Dictionary attributes); // shorthand
+    constructor (); // shorthand
+  }
+  class ContentElement : Element {
+    constructor (Dictionary attributes, ChildArguments... nodes); // O(M+N), M = number of attributes, N = number of nodes plus all their descendants
+    constructor (ChildArguments... nodes); // shorthand
+    constructor (Dictionary attributes); // shorthand
+    constructor (); // shorthand
     Array<Node> getDistributedNodes(); // O(N) in distributed nodes
   }
-  interface ImgElement : Element { }
-  interface IframeElement : Element { }
-  interface TElement : Element { }
-  interface AElement : Element { }
-  interface TitleElement : Element { }
+  class ImgElement : Element {
+    constructor (Dictionary attributes, ChildArguments... nodes); // O(M+N), M = number of attributes, N = number of nodes plus all their descendants
+    constructor (ChildArguments... nodes); // shorthand
+    constructor (Dictionary attributes); // shorthand
+    constructor (); // shorthand
+  }
+  class IframeElement : Element {
+    constructor (Dictionary attributes, ChildArguments... nodes); // O(M+N), M = number of attributes, N = number of nodes plus all their descendants
+    constructor (ChildArguments... nodes); // shorthand
+    constructor (Dictionary attributes); // shorthand
+    constructor (); // shorthand
+  }
+  class TElement : Element {
+    constructor (Dictionary attributes, ChildArguments... nodes); // O(M+N), M = number of attributes, N = number of nodes plus all their descendants
+    constructor (ChildArguments... nodes); // shorthand
+    constructor (Dictionary attributes); // shorthand
+    constructor (); // shorthand
+  }
+  class AElement : Element {
+    constructor (Dictionary attributes, ChildArguments... nodes); // O(M+N), M = number of attributes, N = number of nodes plus all their descendants
+    constructor (ChildArguments... nodes); // shorthand
+    constructor (Dictionary attributes); // shorthand
+    constructor (); // shorthand
+  }
+  class TitleElement : Element {
+    constructor (Dictionary attributes, ChildArguments... nodes); // O(M+N), M = number of attributes, N = number of nodes plus all their descendants
+    constructor (ChildArguments... nodes); // shorthand
+    constructor (Dictionary attributes); // shorthand
+    constructor (); // shorthand
+  }
 
 
 
+  dictionary ElementRegistration {
+    String tagName;
+    Boolean shadow;
+    Object prototype;
+  }
+
+  interface ElementConstructor {
+    constructor (Dictionary attributes, ChildArguments... nodes); // O(M+N), M = number of attributes, N = number of nodes plus all their descendants
+    constructor (ChildArguments... nodes); // shorthand
+    constructor (Dictionary attributes); // shorthand
+    constructor (); // shorthand
+
+    constructor attribute String tagName;
+  }
+
   // MODULES
-  abstract interface AbstractModule : EventTarget {
+  abstract class AbstractModule : EventTarget {
+    readonly attribute Document document; // O(1) // the Documentof the module or application
     Promise<any> import(String url); // O(Yikes) // returns the module's exports
+
+    // createElement() lets you create elements that will be upgraded later when you register the element
+    Element createElement(String tagName, Dictionary attributes, ChildArguments... nodes); // O(M+N), M = number of attributes, N = number of nodes plus all their descendants
+    Element createElement(String tagName, Dictionary attributes); // shorthand
+    Element createElement(String tagName, ChildArguments... nodes); // shorthand
+    Element createElement(String tagName); // shorthand
+
+    ElementConstructor registerElement(ElementRegistration options); // O(N) in number of outstanding elements with that tag name to be upgraded
+
     ScriptElement? currentScript; // O(1) // returns the <script> element currently being executed if any, and if it's in this module; else null
   }
 
-  interface Module : AbstractModule {
+  class Module : AbstractModule {
     constructor (Application application, Document document); // O(1)
+    readonly attribute Application application; // O(1)
+
     attribute any exports; // O(1) // defaults to the module's document
-    readonly attribute Document document; // O(1) // the module's document
-    readonly attribute Application application; // O(1)
   }
 
-  interface Application : AbstractModule {
+  class Application : AbstractModule {
     constructor (Document document); // O(1)
     attribute String title; // O(1)
-    readonly attribute Document document; // O(1) // the application's document
   }
 
   // see script.md for a description of the global object, though note that
   // the sky core module doesn't use it or affect it in any way.
 
 }
 ```
 
+TODO(ianh): is it ok that you can do
+module.application.registerElement()? we need application so that a
+module can implement <title> and get to application.title...
+
 TODO(ianh): event loop
 
 TODO(ianh): define the DOM APIs listed above, including firing the
 change callbacks
 
 TODO(ianh): schedule microtask, schedule task, requestAnimationFrame,
 custom element callbacks...
 
 
 
@@ skipping 13 matching lines @@
 Sky IDL works more or less the same as Web IDL but the syntax is a bit
 different.
 
 ```javascript
 module 'sky:modulename' {
 
   // this is a comment
 
   typedef NewType OldType; // useful when OldType is a commonly-used union
 
-  interface InterfaceName {
-    // an interface corresponds to a JavaScript prototype
+  class ClassName {
+    // a class corresponds to a JavaScript prototype
+    // corresponds to a WebIDL 'interface'
   }
 
-  abstract interface Superinterface {
-    // an abstract interface can't have a constructor
-    // in every other respect it is the same as a regular interface
+  abstract class Superclass {
+    // an abstract class can't have a constructor
+    // in every other respect it is the same as a regular class
   }
 
-  interface Subinterface : Superinterface {
+  class Subclass : Superclass {
     // properties
     readonly attribute ReturnType attributeName; // getter
     attribute ReturnType attributeName; // getter and setter
 
     // methods and constructors
     constructor ();
     ReturnType method();
       // When the platform calls this method, it always invokes the "real" method, even if it's been
       // deleted from the prototypes (as if it took a reference to the method at startup, and stored
       // state using Symbols)
     virtual ReturnType methodCallback();
       // when the platform calls this, it actually calls it the way JS would, so author overrides do
       // affect what gets called. Make sure if you override it that you call the superclass implementation!
       // The default implementations of 'virtual' methods all end by calling the identically named method
       // on the superclass, if there is such a method.
 
+    // properties on the constructor
+    constructor readonly attribute ReturnType staticName;
+
     // private APIs - see below
     private void method();
 
     // arguments and overloading are done as follows
     // note that the argument names are only for documentation purposes
     ReturnType method(ArgumentType argumentName1, ArgumentType argumentName2);
     // the last argument's type can have "..." appended to it to indicate a varargs-like situation
     ReturnType method(ArgumentType argumentName1, ArgumentType... allSubsequentArguments);
   }
 
   dictionary Options {
     String foo;
     Integer bar;
   }
 
   // the module can have properties and methods also
   attribute String Foo;
   void method();
 
+  interface InterfaceName {
+    // describes a template of a prototype, in the same syntax as a class
+    // not actually exposed in the runtime
+  }
+
 }
 ```
 
 ### Private APIs ###
 
 Private APIs are only accessible via Symbol objects, which are then
 exposed on the sky:debug module's exports object as the name of the
 member given in the IDL.
 
 For example, consider:
 
 ```javascript
-interface Foo {
+class Foo {
   private void Bar();
 }
 ```
 
 In a script with a ``foo`` object of type ``Foo``, ``foo.Bar`` is
 undefined. However, it can be obtained as follows:
 
 ```html
 <import src="sky:debug" as="debug"/>
 <!-- ... import whatever defines 'foo' ... -->
 <script>
   foo[debug.Bar]
 </script>
 ```
 
 ### Types ###
 
 The following types are available:
 
 * ``Integer`` - WebIDL ``long long``
 * ``Float`` - WebIDL ``double``
 * ``String`` - WebIDL ``USVString``
 * ``Boolean`` - WebIDL ``boolean``
 # ``Object`` - WebIDL ``object``
-* ``InterfaceName`` - an instance of the interface InterfaceName
+* ``ClassName`` - an instance of the class ClassName
 * ``DictionaryName`` - an instance of the dictionary DictionaryName
 * ``Promise<Type>`` - WebIDL ``Promise<T>``
 * ``Array<Type>`` - WebIDL ``sequence<T>``
 * ``Dictionary`` - unordered set of name-value String-String pairs with no duplicate names
 * ``Type?`` - union of Type and the singleton type with value "null" (WebIDL nullable)
 * ``(Type1 or Type2)`` - union of Type1 and Type2 (WebIDL union)
 * ``any`` - union of all types (WebIDL ``any``)
 
 Methods that return nothing (undefined, in JS) use the keyword "void"
 instead of a type.
@@ skipping 24 matching lines @@
   the core mojo fabric JS API   sky:mojo:fabric:core
   the asyncWait/cancelWait mojo fabric JS API (interface to IPC thread)  sky:mojo:fabric:ipc
   the mojom for the shell, proxying through C++ so that the shell pipe isn't exposed  sky:mojo:shell
   the sky API  sky:core
   the sky debug symbols for private APIs  sky:debug
 ```
 
 TODO(ianh): determine if we want to separate the "this" from the
 Document, especially for Modules, so that exposing a module's element
 doesn't expose the module's exports attribute.