Convert to custom elements spec v1

README.md

@@ -26,20 +26,20 @@ You can take the same ideas (and standards), apply them directly server side, to
 ```javascript
 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";
-};
+// Define a new class that extends a native HTML Element
+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.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.define(componentName, Constructor)`
 
 Registers an element, so that it will be used when the given element name is found during parsing.
 
@@ -131,31 +131,27 @@ 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.connectedCallback(document)`
 
-Called when an element is created.
+Called when an element is attached to the 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.
 
 This method is called with `this` bound to the element that's being rendered (just like in browser-land). The `document` object that would normally be available as a global in the browser is instead passed as an argument here for convenience (useful if you want to use `document.querySelectorAll` and friends). Note that if you're rendering with `renderFragment` instead of `renderPage` this will be a DocumentFragment, not a Document, although in almost all cases you can safely ignore this.
 
 If this callback returns a promise, the rendering process will not resolve until that promise does, and will fail if that promise fails. You can use this to perform asynchronous actions without your component definitions. Pull tweets from twitter and draw them into the page, or anything else you can imagine.
 
-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.
+These callbacks are called in opening tag order, so a parent's connectedCallback 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.**
+**So far only the connectedCallback 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.**
 
 ## Why does this exist?
 

component-examples.md

@@ -14,14 +14,14 @@ With the web component below, rendering `<my-greeting></my-greeting>` will resul
 `<my-greeting>Hi there</my-greeting>`.
 
 ```javascript
-var components = require("server-components");
-
-var StaticElement = components.newElement();
-StaticElement.createdCallback = function () {
-    this.innerHTML = "Hi there";
-};
-
-components.registerElement("my-greeting", { prototype: StaticElement });
+var customElements = require("server-components");
+
+class StaticElement extends customElements.HTMLElement {
+    connectedCallback() {
+        this.innerHTML = "Hi there"
+    }
+}
+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
@@ -40,17 +40,17 @@ example is below: a visitor counter. All the rage in the 90s, with web component
 comeback!
 
 ```javascript
-var components = require("server-components");
+var customElements = 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 customElements.HTMLElement {
+    connectedCallback() {
+        currentCount += 1;
+        this.innerHTML = "There have been " + currentCount + " visitors.";
+    }
+}
+customElements.define("visitor-counter", CounterElement);
 ```
 
 After a few visitors, this will render `<visitor-counter></visitor-counter>` into something like
@@ -81,17 +81,16 @@ Components can be parameterized in all sorts of ways. One interesting pattern is
 For example, you might want a component that wraps HTML, parses all the text within, and replaces URL strings with actual links (using the excellent [Linkify library](https://github.com/SoapBox/linkifyjs), but here in a server side DOM, not a real one):
 
 ```javascript
-var components = require("server-components");
+var customElements = 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 customElements.HTMLElement {
+    connectedCallback() {
+        // Delegate the whole thing to a real front-end library!
+        linkify(this, { target: () => null, linkClass: "autolinked" }, document);
+    }
+}
+customElements.define("linkify-urls", LinkifyElement);
 ```
 
 With this, we can pass HTML into Server Components that looks like

package.json

@@ -39,12 +39,22 @@
     "watch": "^0.18.0"
   },
   "dependencies": {
-    "domino": "^1.0.23",
-    "validate-element-name": "^1.0.0"
+    "domino": "^1.0.23"
   },
   "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,39 @@ 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 = {};
 
 /**
- * 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.
+ * Re-export methods for convenience
  */
-exports.registerElement = function registerElement(name, options) {
-    var nameValidationResult = validateElementName(name);
-    if (!nameValidationResult.isValid) {
-        throw new Error(`Registration failed for '${name}'. ${nameValidationResult.message}`);
-    }
+exports.define = function (name, constructor, options) {
+    return CustomElementRegistry.instance().define(name, constructor, options);
+};
+exports.get = function (name) {
+    return CustomElementRegistry.instance().get(name);
+};
+exports.whenDefined = function (name) {
+    return CustomElementRegistry.instance().whenDefined(name);
+};
+exports.reset = function (name) {
+    return CustomElementRegistry.instance().reset();
+};
 
-    if (options && options.prototype) {
-        registeredElements[name] = options.prototype;
-    } else {
-        registeredElements[name] = exports.newElement();
-    }
 
-    return registeredElements[name].constructor;
-};
+const _upgradedProp = '__$CE_upgraded';
+
+
+function transformTree(document, visitedNodes, currentNode, callback) {
+
+    var task = visitedNodes.has(currentNode) ? undefined : callback(currentNode);
+
+    visitedNodes.add(currentNode);
 
-function recurseTree(rootNode, callback) {
-    for (let node of rootNode.childNodes) {
-        callback(node);
-        recurseTree(node, callback);
+    for (var child of currentNode.childNodes) {
+        transformTree(document, visitedNodes, child, callback);
     }
 }
 
@@ -89,24 +86,28 @@ function renderNode(rootNode) {
     let createdPromises = [];
 
     var document = getDocument(rootNode);
+    var visitedNodes = new Set();
+    var customElements = exports.customElements;
 
-    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));
-                    }));
-                }
+    transformTree(document, visitedNodes, rootNode, function render (element) {
+
+        const definition = customElements.getDefinition(element.localName);
+
+        if (definition) {
+            if ( element[_upgradedProp] ) {
+                return;
+            }
+            upgradeElement(element, definition, true);
+
+            if (definition.connectedCallback) {
+                var p = new Promise(function(resolve, reject) {
+                    resolve( definition.connectedCallback.call(element, document) );
+                });
+                createdPromises.push(p);
             }
         }
     });
-
-    return Promise.all(createdPromises).then(() => rootNode);
+    return Promise.all(createdPromises).then(function(){ return rootNode; });
 }
 
 /**
@@ -154,3 +155,35 @@ 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;
+    }
+
+    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) {
+    return Array.prototype.slice.call(arrayLike).map(fn);
+}