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

Overview

Isolation

Depending on the source and the purpose of a component it may be desirable to limit access to the component from the containing document, or vice versa. E.g., a page may want to include components from a third party out of convenience, but limit the access those components have to other contents of the page. Conversely, a component with a complicated internal structure and scripting may want to disallow the containing page from (iadvertently, perhaps) meddling with its internal structure. There are several dimensions to this problem:

• DOM access via JavaScript
• event propagation
• CSS
  • styling
  • changing of display type, or setting display: none
  • generated content

Note that since components may include other components, "containing document" may also refer to "containing component", or - to be more general - "containing tree scopes".

Component distrusts Document

JavaScript

• getElementById(), getElementsByTagName(), getElementsByName() and getElementsByClassName() (and their ...NS incarnations) do not reach into shadow trees.

Exception: none

• querySelector() and querySelectorAll() do not reach into shadow trees, even when using a shadow pseudo-ID (!).

Exception: none

• The host element's .shadow property is null (TODO: as an alternative, accessing it throws an exception?).

Exception: TODO: the template has the attribute allow-shadow-accessor (?)

CSS

• Style rules of the containing document do not match nodes in the shadow tree.

Exception: Shadow tree elements that have explicit pseudoID attributes may match, provided they are explicitly matched by an equivalent pseudo-element selector.

Exception: The template has the allow-selectors-through attribute: outside selectors may cross into the shadow tree.

Exception: The template has the apply-author-sheets attribute: outside selectors may be applied fully within the shadow tree. (TODO: is that really required on top of allow-selectors-through?)

• Nodes in the shadow tree do not inherit styles from the host element

Exception: TODO: define a shadow tree to reset all CSS attributes to initial, but allow a (scoped) style sheet to set them to inherit?

• A child or descendant selector of a shadow pseudo-ID selector (e.g., host::pseudo div) does not match, even if the shadow tree's element with pseudo-ID pseudo does happen to have a <div> descendant. In other words, the shadow pseudo-ID simple selector(s) must be a member of the last selector sequence.

Exception: none

• TODO: prevent setting display and content?

Exception: TODO: see "CSS filtering" below.

• TODO: prevent generated content - i.e., ::before and ::after?

Exception: TODO: ?

• TODO: in general, add a way to specify specifically which CSS attributes are allowed?

Document distrusts Component

JavaScript

• A component does not have access to document, nor windows. treeScope.document returns null (TODO: throws?).

Exception: The document specifies that it's ok that bindings from that source access its DOM (TODO: how?).

• A component has access to its tree scope, but not to its parent tree scope. treeScope.parentTreeScope returns null (TODO: throws?).

Exception: The parent tree scope (document or template) specifies that it's ok that bindings from that source access its DOM (TODO: how?).

• A component does not have access to its host element. element.treeScope.hostElement is null (TODO: throws?).

Exception: The containing document or template specifies that it's ok that bindings from that source access the host element (TODO: how?)

• TODO: Communication to the containing page takes place via attribute-forwarding and events?

TODO: is it safe to allow the document to grant access to the document or window object to a component, even considering that that component might be included as part of a different component elsewhere? In this case the nested component could manipulate the document, and the document's DOM, but if the containing component distrusts the document (and by extension presumably the nested component as well), it would not get access to the containing component from the document.

CSS

• Style rules are not applied to nodes outside the shadow tree, even if declared in style sheets that are defined or imported via <style> that has no scoped attribute. <style> elements within a shadow tree that don't have the scoped attribute set must be treated as if it was set and every rule was prefixed with :root.

Exception: The containing document or template does not prohibit that style sheets of bindings from that source may affect its nodes (default: allowed) (TODO: how?)

• Children of the host element do not inherit styles from a shadow tree's <content> element that they are rendered "under".

Exception: The <content> element has the apply-binding-sheets attribute AND the containing document or template does not prohibit that it's ok that bindings from that source act as inheritance parent (default: allowed) (TODO: how?)

Extensibility

New element types are created by extending DOM elements. Each descendant can create its own shadow DOM subtree. If the descendant chooses to do so, the parent shadow DOM subtree becomes inaccessible and invisible. It's still there (to ensure that the code written to exercise it doesn't freak out), but it isn't rendered -- it's a ghost tree. A child may return this tree back to life by using <inherited> element anywhere in its shadow DOM subtree. The <inherited> is replaced with the parent shadow DOM subtree when rendering.

The essential mechanics of this behavior are probably as follows:

• when initializing element, walk up to the prototype chain until top
• walking down, for each member of the prototype chain, create shadow DOM subtree
• render only the tree at the bottom of the chain.

Every instance also gets an opportunity to create its own shadow DOM subtree by using the shadow property. If the property is set, the newly blessed shadow DOM subtree behaves as if it was stuck at the bottom of the prototype chain, turning its prototype shadow DOM subtree into a ghost.

Desugaring

From component model's perspective, all native form controls or elements with non-trivial behavior are also sub-classes of more primitive DOM elements with shadow DOM subtrees and behaviors attached. Thus, you can extend them and override shadow DOM subtrees just like you would with any component.

For example, in Rendering Form Controls with SVG use case, this allows the engineer to override appearance of a form element completely or to reuse it and supplement it with extra bits of appearance.

Styles

<style scoped> is a natural way to limit style sheets to only affect the shadow tree of a component. The component model follows the implementation suggested in this www-style thread. That is, a selector is only matched up to, and including, the scoping element - i.e., the parent element of <style scoped> - but not further. The exceptions are:

• the selector contains the :root pseudo-class (note that this will fail if not used within the first selector sequence), or
• the selector contains the :scope pseudo-class

CSS4: care must be taken that the subject of a selector is the scoping element or a descendant thereof.

[TODO: notes on crossing the boundary from/into the shadow tree]