Convert to custom elements spec v1

README.md

@@ -27,19 +27,19 @@ You can take the same ideas (and standards), apply them directly server side, to
 var components = require("server-components");
 
 // Get the prototype for a new element
-var NewElement = components.newElement();
-
-// When the element is created during DOM parsing, you can transform the HTML inside it.
-// This can be configurable too, either by setting attributes or adding HTML content
-// inside it or elsewhere in the page it can interact with. Elements can fire events
-// that other elements can receive to allow interactions, or even expose methods
-// or data that other elements in the page can access directly.
-NewElement.createdCallback = function () {
-    this.innerHTML = "Hi there";
-};
+class NewElement extends components.HTMLElement {
+    // When the element is created during DOM parsing, you can transform the HTML inside it.
+    // This can be configurable too, either by setting attributes or adding HTML content
+    // inside it or elsewhere in the page it can interact with. Elements can fire events
+    // that other elements can receive to allow interactions, or even expose methods
+    // or data that other elements in the page can access directly.
+    connectedCallback() {
+        this.innerHTML = "Hi there";
+    }
+}
 
 // Register the element with an element name
-components.registerElement("my-new-element", { prototype: NewElement });
+components.customElements.define("my-new-element", NewElement);
 ```
 
 For examples of more complex component definitions, take a look at the [example components](https://github.com/pimterry/server-components/blob/master/component-examples.md)
@@ -83,15 +83,15 @@ There aren't many published sharable components to drop in quite yet, as it's st
 
 ### Top-level API
 
-#### `components.newElement()`
+#### `components.HTMLElement`
 
 Creates a returns a new custom HTML element prototype, extending the HTMLElement prototype.
 
 Note that this does *not* register the element. To do that, call `components.registerElement` with an element name, and options (typically including the prototype returned here as your 'prototype' value).
 
 This is broadly equivalent to `Object.create(HTMLElement.prototype)` in browser land, and exactly equivalent here to `Object.create(components.dom.HTMLElement.prototype)`. You can call that yourself instead if you like, but it's a bit of a mouthful.
 
-#### `components.registerElement(componentName, options)`
+#### `components.customElements.define(componentName, Constructor)`
 
 Registers an element, so that it will be used when the given element name is found during parsing.
 
@@ -131,9 +131,9 @@ These methods are methods you can implement on your component prototype (as retu
 
 Any methods that are implemented, from this selection or otherwise, will be exposed on your element in the DOM during rendering. I.e. you can call `document.querySelector("my-element").setTitle("New Title")` and to call the `setTitle` method on your object, which can then potentially change how your component is rendered.
 
-#### `yourComponent.createdCallback(document)`
+#### `yourComponentConstructor.prototype.createdCallback(document)`
 
-Called when an element is created.
+Called when an element is attached to the faux DOM.
 
 **This is where you put your magic!** Rewrite the elements contents to dynamically generate what your users will actually see client side. Read configuration from attributes or the initial child nodes to create flexible reconfigurable reusable elements. Register for events to create elements that interact with the rest of the application structure. Build your page.
 
@@ -143,17 +143,13 @@ If this callback returns a promise, the rendering process will not resolve until
 
 These callbacks are called in opening tag order, so a parent's createdCallback is called, then each of its children's, then its next sibling element.
 
-#### `yourComponent.attachedCallback(document)`
-
-Called when the element is attached to the DOM. This is different to when it's created when your component is being built programmatically, not through HTML parsing. *Not yet implemented*
-
-#### `yourComponent.detachedCallback(document)`
+#### `yourComponentConstructor.prototype.disconnectedCallback(document)`
 
 Called when the element is removed from the DOM. *Not yet implemented*
 
-#### `yourComponent.attributeChangedCallback(document)`
+#### `yourComponentConstructor.prototype.attributeChangedCallback(document)`
 
-Called when an attribute of the element is added, changed, or removed. *Not yet implemented*.
+Called when an attribute of the element is added, changed, or removed. *Partially implemented;* runs on component initialization.
 
 **So far only the createdCallback is implemented here, as the others are less relevant initially for the key simpler cases. Each of those will be coming in time though! Watch this space.**
 

component-examples.md

@@ -16,12 +16,12 @@ With the web component below, rendering `<my-greeting></my-greeting>` will resul
 ```javascript
 var components = require("server-components");
 
-var StaticElement = components.newElement();
-StaticElement.createdCallback = function () {
-    this.innerHTML = "Hi there";
-};
-
-components.registerElement("my-greeting", { prototype: StaticElement });
+class StaticElement extends components.HTMLElement {
+    connectedCallback() {
+        this.innerHTML = "Hi there"
+    }
+}
+components.customElements.define("my-greeting", StaticElement);
 ```
 
 This is very basic, and toy cases like this aren't immediately useful, but this can be helpful for standard
@@ -42,15 +42,15 @@ comeback!
 ```javascript
 var components = require("server-components");
 
-var CounterElement = components.newElement();
 var currentCount = 0;
 
-CounterElement.createdCallback = function () {
-    currentCount += 1;
-    this.innerHTML = "There have been " + currentCount + " visitors.";
-};
-
-components.registerElement("visitor-counter", { prototype: CounterElement });
+class CounterElement extends components.HTMLElement {
+    connectedCallback() {
+        currentCount += 1;
+        this.innerHTML = "There have been " + currentCount + " visitors.";
+    }
+}
+components.customElements.define("visitor-counter", CounterElement);
 ```
 
 After a few visitors, this will render `<visitor-counter></visitor-counter>` into something like
@@ -84,14 +84,13 @@ For example, you might want a component that wraps HTML, parses all the text wit
 var components = require("server-components");
 var linkify = require("linkifyjs/element");
 
-var LinkifyElement = components.newElement();
-
-LinkifyElement.createdCallback = function (document) {
-    // Delegate the whole thing to a real normal front-end library!
-    linkify(this, { target: () => null, linkClass: "autolinked" }, document);
- };
-
-components.registerElement("linkify-urls", { prototype: LinkifyElement });
+class LinkifyElement extends components.HTMLElement {
+    connectedCallback() {
+        // Delegate the whole thing to a real front-end library!
+        linkify(this, { target: () => null, linkClass: "autolinked" }, document);
+    }
+}
+components.customElements.define("linkify-urls", LinkifyElement);
 ```
 
 With this, we can pass HTML into Server Components that looks like

package.json

@@ -44,7 +44,18 @@
   },
   "jshintConfig": {
     "esversion": 6,
-    "node": true
+    "node": true,
+    "globals": {
+      "describe": false,
+      "xdescribe": false,
+      "it": false,
+      "xit": false,
+      "before": false,
+      "beforeEach": false,
+      "after": false,
+      "afterEach": false,
+      "expect": false
+    }
   },
   "engines": {
     "node": ">= 4.0.0"

src/extend-domino.js

@@ -0,0 +1,44 @@
+//
+// Strict mode disallows us to overwrite Document.prototype properties.
+// This file is to stay out of strict mode.
+//
+var domino = require("domino");
+var Document = require('domino/lib/Document');
+var Element = require('domino/lib/Element');
+
+
+module.exports = function (newHTMLElement, _createElement) {
+  var result = {};
+
+  //
+  // Patch document.createElement
+  //
+  Document.prototype.createElement = function(tagName, options) {
+    return _createElement(this, tagName, options, true);
+  };
+
+  //
+  // Patch HTMLElement
+  //
+  result.HTMLElement = newHTMLElement;
+  result.HTMLElement.prototype = Object.create(domino.impl.HTMLElement.prototype, {
+    constructor: {value: result.HTMLElement, configurable: true, writable: true},
+  });
+
+
+  //
+  // Patch doc.createElementNS
+  //
+  var HTMLNS = 'http://www.w3.org/1999/xhtml';
+  var _origCreateElementNS = Document.prototype.createElementNS;
+
+  Document.prototype.createElementNS = function(namespaceURI, qualifiedName) {
+    if (namespaceURI === 'http://www.w3.org/1999/xhtml') {
+      return this.createElement(qualifiedName);
+    } else {
+      return _origCreateElementNS.call(this, namespaceURI, qualifiedName);
+    }
+  };
+
+  return result;
+};

src/index.js

@@ -1,7 +1,6 @@
 "use strict";
 
 var domino = require("domino");
-var validateElementName = require("validate-element-name");
 
 /**
  * The DOM object (components.dom) exposes tradition DOM objects (normally globally available
@@ -17,41 +16,28 @@ exports.dom = domino.impl;
  * with an element name, and options (typically including the prototype returned here as your
  * 'prototype' value).
  */
-exports.newElement = function newElement() {
-    return Object.create(domino.impl.HTMLElement.prototype);
-};
+var CustomElementRegistry = require('./registry');
+exports.customElements = CustomElementRegistry.instance();
+exports.HTMLElement = CustomElementRegistry.HTMLElement;
 
-var registeredElements = {};
+const _upgradedProp = '__$CE_upgraded';
 
-/**
- * Registers an element, so that it will be used when the given element name is found during parsing.
- *
- * Element names are required to contain a hyphen (to disambiguate them from existing element names),
- * be entirely lower-case, and not start with a hyphen.
- *
- * The only option currently supported is 'prototype', which sets the prototype of the given element.
- * This prototype will have its various callbacks called when it is found during document parsing,
- * and properties of the prototype will be exposed within the DOM to other elements there in turn.
- */
-exports.registerElement = function registerElement(name, options) {
-    var nameValidationResult = validateElementName(name);
-    if (!nameValidationResult.isValid) {
-        throw new Error(`Registration failed for '${name}'. ${nameValidationResult.message}`);
-    }
 
-    if (options && options.prototype) {
-        registeredElements[name] = options.prototype;
-    } else {
-        registeredElements[name] = exports.newElement();
-    }
+function transformTree(document, visitedNodes, currentNode, callback) {
 
-    return registeredElements[name].constructor;
-};
+    var task = visitedNodes.has(currentNode) ? undefined : callback(currentNode);
+
+    visitedNodes.add(currentNode);
+
+    let visitChildren = () => Promise.all(
+        map(currentNode.childNodes, (child) => transformTree(document, visitedNodes, child, callback))
+    );
 
-function recurseTree(rootNode, callback) {
-    for (let node of rootNode.childNodes) {
-        callback(node);
-        recurseTree(node, callback);
+    if ( task && task.then ) {
+        return task.then(visitChildren);
+    }
+    else {
+        return visitChildren();
     }
 }
 
@@ -89,24 +75,29 @@ function renderNode(rootNode) {
     let createdPromises = [];
 
     var document = getDocument(rootNode);
+    var visitedNodes = new Set();
+    var upgradedNodes = new Set();
+    var customElements = exports.customElements;
+
+    return transformTree(document, visitedNodes, rootNode, function render (element) {
 
-    recurseTree(rootNode, (foundNode) => {
-        if (foundNode.tagName) {
-            let nodeType = foundNode.tagName.toLowerCase();
-            let customElement = registeredElements[nodeType];
-            if (customElement) {
-                // TODO: Should probably clone node, not change prototype, for performance
-                Object.setPrototypeOf(foundNode, customElement);
-                if (customElement.createdCallback) {
-                    createdPromises.push(new Promise((resolve) => {
-                        resolve(customElement.createdCallback.call(foundNode, document));
-                    }));
-                }
+        const definition = customElements.getDefinition(element.localName);
+
+        if (definition) {
+            if ( upgradedNodes.has(element[_upgradedProp]) ) {
+                return;
             }
-        }
-    });
+            upgradeElement(element, definition, true);
+            upgradedNodes.add(element);
 
-    return Promise.all(createdPromises).then(() => rootNode);
+            if (definition.connectedCallback) {
+                return new Promise(function(resolve, reject) {
+                    resolve( definition.connectedCallback.call(element, document) );
+                });
+            }
+        }
+    })
+        .then(() => rootNode);
 }
 
 /**
@@ -154,3 +145,40 @@ function getDocument(rootNode) {
         return rootNode;
     }
 }
+
+function upgradeElement (element, definition, callConstructor) {
+    const prototype = definition.constructor.prototype;
+    Object.setPrototypeOf(element, prototype);
+    if (callConstructor) {
+        CustomElementRegistry.instance()._setNewInstance(element);
+        new (definition.constructor)();
+        element[_upgradedProp] = true;
+        console.assert(CustomElementRegistry.instance()._newInstance === null);
+    }
+
+    const observedAttributes = definition.observedAttributes;
+    const attributeChangedCallback = definition.attributeChangedCallback;
+    if (attributeChangedCallback && observedAttributes.length > 0) {
+
+        // Trigger attributeChangedCallback for existing attributes.
+        // https://html.spec.whatwg.org/multipage/scripting.html#upgrades
+        for (let i = 0; i < observedAttributes.length; i++) {
+            const name = observedAttributes[i];
+            if (element.hasAttribute(name)) {
+                const value = element.getAttribute(name);
+                attributeChangedCallback.call(element, name, null, value, null);
+            }
+        }
+    }
+  }
+
+//
+// Helpers
+//
+function map (arrayLike, fn) {
+    var results = [];
+    for (var i=0; i < arrayLike.length; i++) {
+        results.push( fn(arrayLike[i]) );
+    }
+    return results;
+}