Component Model

Here's a good starting point for learning about the component model spec, which is currently under development (also see periodically updating gh-pages).

Introduction

TODO Populate with beautifully crafted words.

• Component Model Use Cases
• Behavior Attachment

Properties

The component model aims to satisfy several key properties. These properties were extracted from the use cases. This section explains component model basics by studying each property.

Extensibility

The component model enables creation of new types of DOM elements by allowing the use of existing DOM elements in Javascript prototype chain. For example, here's how you would create a new sub-type of HTMLElement:

function LayoutManagerPanel() {
    HTMLElement.call(this);
}

LayoutManagerPanel.prototype = Object.create(HTMLElement.prototype);

// ...

// 1) Will not be able to add instances of LayoutManagerPanel to document without this call.
// 2) First parameter specifies the tagName of the element being registered and must be a string prefixed with "x-".
Element.register("x-layout-manager-panel", LayoutManagerPanel);

// ...

var panel = new LayoutManagerPanel();
document.body.appendChild(panel);
// or
document.body.innerHTML = "<x-layout-manager-panel></x-layout-manager-panel>";

The resulting panel instance is a Javascript object that is a valid DOM element, which can be added to the DOM tree. You can then extend this object using standard Javascript prototype inheritance.

Required Building Blocks:

• Constructable DOM Types
• Registering Elements

Consistency

Because components are just DOM objects, they inherently share the same traversal and manipulation APIs, as defined by the DOM Core. The authors of components can extend these APIs by adding custom methods and properties on DOM objects, using standard Javascript inheritance:

Widget.prototype = Object.create(HTMLElement.prototype, {
    update: {
        value: function() { /* ... */ }
    },
    value: {
        get: function() { /* ... */ },
        set: function() { /* ... */ }
    },
   // ...
});

The common API surface and the ability to extend it serves as a natural API boundary for framework authors, enabling interoperability.

Required Building Blocks:

• Constructable DOM Types

Encapsulation

Encapsulation refers to ability of the component to hide its implementation details and state from the document. To enable hiding of the implementation details, the component model provides a way to build a DOM tree that is not accessible from the document DOM tree, but is rendered as part of the document. This DOM tree, associated with the component is the shadow DOM. The boundary between the document DOM tree and shadow DOM tree provides complete encapsulation, and ensures that no information about the shadow DOM tree crosses this boundary. Additionally, the boundary serves as a convenient style application lever, giving the component a choice of letting (or not letting) document CSS affect the shadow DOM tree.

Every DOM element instance may only have (or host) one shadow DOM tree. A shadow tree is instantiated by creating an instance of the ShadowRoot object, which takes a reference to the hosting element as a parameter. Attempting to create more than one instance for the same element throws an exception:

function LayoutManagerPanel() {
    HTMLElement.call(this);
    var shadow = new ShadowRoot(this);
    var shadow2 = new ShadowRoot(this); // throws an exception.
   // ...
}

A ShadowRoot instance is a Node, and acts as the root of the element's shadow DOM subtree. The ShadowRoot itself is never rendered, nor has styles. In this regard, it's similar to the DocumentFragment. It has two properties:

• applyAuthorSheets, which is either true (that is, apply author style sheets from the document), or false (don't);
• shadowHost, which points to the hosting element.

Required Building Blocks:

• Shadow DOM

Composability

Being DOM objects, components fit naturally into the document DOM tree and support all of its composition properties. In addition, the content element allows controlling interaction between shadow and document DOM trees. A content element specifies places where immediate document tree children of the component are rendered inside the shadow tree.

There can be more than one content element in the shadow tree. The includes attribute provides a convenient way to sort element's children by CSS selector. For example, a DockLayoutPanel component could be used like this in the document DOM tree:

<x-dock-layout-panel>
    <h1 class="north">On Gardens</h1>
    <ul class="west">
        <li>Automatic Gardens</li>
        <li>Gardening on minefields</li>
    </ul>
    <p>I love gardening.</p>
    <div class="south">Written by Chauncey Gardiner.</div>
</x-dock-layout-panel>

Provided that its shadow DOM tree looks like this:

<#shadow-root>
    <div class="north">
        <content includes=".north">
    </div>
    <div>
        <div class="west">
            <content includes=".west">
        </div>
        <div class="east">
            <content>
        </div>
    </div>
    <div class="south">
        <content includes=".south">
    </div>
<#shadow-root>

The document DOM tree children on of x-dock-layout-panel will be rendered as if composed from this tree:

<x-dock-layout-panel>
    <div class="north">
        <h1 class="north">On Gardens</h1>
    </div>
    <div>
        <div class="west">
            <ul class="west">
                <li>Automatic Gardens</li>
                <li>Gardening on minefields</li>
            </ul>
        </div>
        <div class="east">
            <p>I love gardening.</p>
        </div>
    </div>
    <div class="south">
        <div class="south">Written by Avid Gardener.</div>
    </div>
</x-dock-layout-panel>

Required Building Blocks:

• Content Element

Desugaring

The component model also explains pretty well how the native HTML elements are built and dispels some of the magic associated with the "DOM object vs. Javascript object" juxtaposition.

Allowing DOM elements to participate in the Javascript inheritance chain makes DOM elements more approachable and easier to work with.

Complex DOM elements that are rendered with more than one CSS box (and aren't specified in terms of CSS, like lists) are just components that have shadow DOM. Coincidentally, this also explains why you can't add shadow DOM subtrees to input or details elements -- their ShadowRoots are claimed by HTMLInputElement and HTMLDetailsElement constructors, respectively.

Required Building Blocks:

• Shadow DOM
• Content Element

Performance

Considering the way Web works, the component model must allow decoupling of the instantiation and the declaration of the components in order to provide reasonable performance characteristics. It's an unfortunate, but necessary requirement. In other words, we must be able to handle situations where a component instance is created before it is declared. Here's an simple example:

// somewhere in view.js
...
document.body.innerHTML = '<div class="awesome"><x-layout><x-spring-panel>...</x-spring-panel></x-layout>';

...
// somewhere in layout.js
Element.register('x-layout', Layout);
Element.register('x-spring-panel', SpringPanel);

In this situation, there is no room for error: view.js must wait for layout.js to load before executing. You can't load layout.js lazily or in any different order, since it defines the components that are used in view.js. Given that asynchronous, deferred or lazy-loading of script are all common performance techniques in today's Web, we must do better than block or throw an exception in such cases.

The component model offers this solution:

When unknown DOM element with an "x-"-prefixed tagName is encountered, we put an placeholder HTMLUnknownElement instance in its place. As soon as the element is defined, all placeholder instances are replaced (think replaceChild with the extra work of transferring children, attributes, and children) with the new, proper DOM element.

Required Building Blocks:

• Registering Elements

Confinement

Confinement refers to the document protecting its implementation details and state from the component and can be viewed as the reverse of encapsulation. The API surface of the component model lends itself well to proper confinement. Here's an approach that could be used to provide it (very early brainstorming):

• Confinement is not tied to the component model. Instead, it's a new twist on the method of loading scripts. A script could be loaded as usual or it could be confined, or loaded into its own context.

• When confined, a script has its own global and document objects. These objects only reveal some safe limited subset of the actual document objects. Think of it as a same-origin iframe with restrictions on document and window.

• You can communicate with the main document using window.postMessage.

• The confined document DOM tree is always empty. Attempting to insert into it throws exceptions.

• ... except when you append to elements in shadow DOM. That's right, you can do Element.register and new ShadowRoot in the confined document.

• Whenever you register an element, it registers in the main document as well. Creating an instance of a component from an confined document produces a functional DOM element shell that proxies to the actual element in the confined document.

Proposed API: introduce a new confined attribute to the script element. Presence of this attribute triggers loading scripts

Required Building Blocks:

• Confinement Primitives

Building Blocks

Now, let's break down the component model by its building blocks.

Shadow DOM

var element = document.createElement("div");
var shadow = new ShadowRoot(element);
var shadow2 = new ShadowRoot(element); // throws an exception.

Confinement Primitives

• Isolation Brainstorm