WHATWG Wiki - User contributions [en]

Component Model Discussion: Rendering

2012-01-12T02:40:42Z

Rolandsteiner: /* Rendering */ fix some copy/paste typos

= Overview =

The question asked herein is how to best treat the following somewhat mutually exclusive requirements:

[1] The containing document "wants" to naturally style the host element (using <x-foo> notation here - see the [http://wiki.whatwg.org/index.php?title=Component_Model_Discussion:_Registration Component Registration page] for alternatives). E.g.,

x-foo {
background-color: yellow;
border: 1px solid blue;
}

[2] The component "wants" to be able to style its outermost rendering rectangle. Because of [http://wiki.whatwg.org/index.php?title=Component_Model_Discussion:_Isolation Isolation], this rectangle is ideally located within the component, i.e., within the shadow DOM.

and as a somewhat lesser concern:

[3] Every point between the rectangles should correspond to a valid DOM range.

ad [3]: Note that conversely, in no variant there is a mapping from a DOM range with anchor <x-foo> to a rectangle/screen position, since the children of <x-foo> may be rendered in arbitrary places, depending on <content> elements within the shadow DOM, or even not at all.

== Rendering ==

This consists of the following, more or less orthogonal, sub-questions

* is the host element rendered or not?
* is the shadow root rendered or not?
* is the shadow root an element or a separate node type?
* using <code>display: transparent</code>?

Almost all combinations of the above have their respective merits and problems. Assume we have the following DOM structure:

<A>
<x-foo> -----> [ShadowRoot (S)]
<B/> <Y/>
<C/> <Z/>
<D/>
</x-foo>
</A>

This could conceivably be rendered in the following ways:

=== [A] rendered host element, rendered shadow root, shadow root is element ===

A---------------------------------------------------------------------+
| x-foo-------------------------------------------------+ |
| | SR------------------------------------+ | |
| | | Y------+ Z------+ | | |
| [A,0] | ??? | [S,0] | | [S,1] | | [S,2] | ??? | [A,1] |
| | | +------+ +------+ | | |
| | +-------------------------------------+ | |
| +-----------------------------------------------------+ |
+---------------------------------------------------------------------+

Consequences:

* Shadow root as element requires separate TreeScope tree and host-element pointer

Issues:

* Styles set on <x-foo> such as <code>background-color</code> don't really affect the component's rendering if the component overrides them on the shadow root.
* The potential gaps between the shadow root's rectangle and the outer host element's rectangle don't directly map to a DOM position.

=== [B] rendered host element with default <code>display: transparent</code>, rendered shadow root, shadow root is element ===

A-------------------------------------------------------+
| x-foo - - - - - - - - - - - - - - - - - + |
| :SR------------------------------------+: |
| :| Z------+ +------+ |: |
| [A,0] :| [S,0] | | [S,1] | | [S,2] |: [A,1] |
| :| Z------+ +------+ |: |
| :+-------------------------------------+: |
| + - - - - - - - - - - - - - - - - - - - + |
+-------------------------------------------------------+

Consequences:

* Shadow root as element requires separate TreeScope tree and host-element pointer

Issues:

* Containing document can't style the shadow host, but this is more apparent because of <code>display: transparent</code>. Containing document could set <code>display</code> to something different if needed.
* If <code>display</code> is set to something different it becomes variant [A], with the associated issues.

=== [C] rendered host element, rendered shadow root, shadow root is separate node type, shadow root's rectangle always is the same as the host element's (no gap) ===

A-------------------------------------------------------+
| x-foo-----------------------------------+ |
| |SR------------------------------------+| |
| || Z------+ +------+ || |
| [A,0] || [S,0] | | [S,1] | | [S,2] || [A,1] |
| || Z------+ +------+ || |
| |+-------------------------------------+| |
| +---------------------------------------+ |
+-------------------------------------------------------+

This allows both the document to style <x-foo>, as well as allowing the component to have its own outer rectangle, but prevents any gap from forming between them. However, this raises more questions than it answers:

Issues:

* Need to spec how ShadowRoot node type is styleable
* <code>margin</code>, <code>padding</code>, <code>position</code> et al must not apply, so need to define how styles apply to ShadowRoot in detail.

=== [D] rendered host element, shadow root not rendered ===

A-----------------------------------------------------+
| x-foo---------------------------------+ |
| | Y------+ Z------+ | |
| [A,0] | ??? | | ??? | | ??? | [A,1] |
| | +------+ +------+ | |
| +-------------------------------------+ |
+-----------------------------------------------------+

Issues:

* Confinement requires separate style-sheet in order for the component to be able to style the host element.
* The potential gaps between the rectangles of the shadow root's children and the outer host element don't directly map to a DOM position.

=== [E] host element has <code>display: transparent</code> by default, shadow root not rendered ===

A---------------------------------------+
| x-foo - - - - - - - - - + |
| :Y------+ Z------+: |
| ??? :| | ??? | |: ??? |
| :+------+ +------+: |
| + - - - - - - - - - - - + |
+---------------------------------------+

Issues:

* Containing document can't style the shadow host, but this is more apparent because of <code>display: transparent</code>. Containing document could set <code>display</code> to something different if needed.
* If <code>display</code> is set to something different it becomes variant [D], with the associated issues.
* The potential gaps between the rectangles of the shadow root's children and the outer host element don't directly map to a DOM position.

=== [F] host element not rendered, rendered shadow root ===

In this scenario, the ShadowRoot most likely is an element.

A-----------------------------------------------------+
| SR------------------------------------+ |
| | Y------+ Z------+ | |
| [A,0] | [S,0] | | [S,1] | | [S,2] | [A,1] |
| | +------+ +------+ | |
| +-------------------------------------+ |
+-----------------------------------------------------+

Issues:

* Containing document can't style the shadow host. Because of Isolation it also can't style the ShadowRoot, unless styles styles set on <x-foo> are forwarded somehow. If so, mechanism of style forwarding needs to be specced.

=== [F2] neither host element nor shadow root rendered, shadow root has single child <R> as root element ===

Similar to [F], but the ShadowRoot doesn't have to be an element itself, can be extended towards [G] later on.

A-----------------------------------------------------+
| R-------------------------------------+ |
| | Y------+ Z------+ | |
| [A,0] | [R,0] | | [R,1] | | [R,2] | [A,1] |
| | +------+ +------+ | |
| +-------------------------------------+ |
+-----------------------------------------------------+

Issues:

* Containing document can't style the shadow host. Because of Isolation it also can't style the ShadowRoot nor the shadow root element, unless styles styles set on <x-foo> are forwarded somehow. If so, mechanism of style forwarding needs to be specced.

=== [G] neither host element nor shadow root rendered ===

A-------------------------------------+
| Y------+ Z------+ |
| ??? | | ??? | | ??? |
| +------+ +------+ |
+-------------------------------------+

Undoubtedly the most flexible from a layout perspective, as it allows a single element to "create" multiple renderers.

Issues:

* There is no single rendering rectangle corresponding to <x-foo>.
* Containing document can't style the host element. Styles set on <x-foo> could be forwarded to ALL children of the shadow root, but it's not clear this is useful.
* The potential gaps between the rectangles of the shadow root's children and the host element's parent don't directly map to a DOM position.

=== [Z] Other? ===

There is a marvelous variant that solves all issues and doesn't suffer any of the above drawbacks which this paragraph is too small to contain.

== Current State ==

Currently we implemented variant [D].

We probably want to go towards [F2].

Component Model Use Cases

2011-11-02T16:41:20Z

Rolandsteiner: /* Custom Controls */ Add "entry-helper"

These use cases represent a set of problems we are trying to solve by implementing a [[Component_Model | component model]] for the web.

=Custom Controls=

Current practice for sizable web applications is to use JavaScript libraries to provide a system to support the construction of custom controls. Implementing these controls can be made simpler and more interoperable with runtime support.

==Layout Manager==

{| cellpadding="8" cellspacing="0"
|+style="caption-side:top; text-align: left; color:Gray" | Layout Manager Use Case Parameters
! align="right" valign="top" | Who
| Web Framework Engineer
|-
! align="right" valign="top" | What
| Build a layout library, consisting of a UI layout primitives, such as ''panel'', ''resizeable panel'', ''tab group'', ''stack'', ''accordion containers'', etc.
|-
! align="right" valign="top" | Purpose
|
* Allow web application developers to easily build constrained layout and populate it with arbitrary HTML content.
* Provide a way for developers to build their own layout primitives by extending the provided ones.
|-
! align="right" valign="top" | Examples
|
* [http://dojotoolkit.org/reference-guide/dijit/layout.html#dijit-layout Dijit Layout]
* [http://code.google.com/webtoolkit/doc/latest/DevGuideUiPanels.html GWT Panels]
* [http://dev.sencha.com/deploy/ext-4.0.2a/docs/#/api/Ext.panel.AbstractPanel Sencha Panels]
* [http://guides.sproutcore.com/views.html SproutCore Views]
|-
! align="right" valign="top" | Desirable Properties
|
* [[Component_Model#Composability | Composability]] -- a method to compose layouts with both UI primitives and DOM elements.
* [[Component_Model#Extensibility | Extensibility]] -- a way to build on layout primitives to create new ones.
* [[Component_Model#Encapsulation | Encapsulation]] -- styles, defined to hold layout in place should not be in danger of being stomped on by the author stylesheets.
* [[Component_Model#Performance | Performance]] -- layouts built with layout manager should appear quickly, avoiding re-flows and [http://en.wikipedia.org/wiki/Flash_of_unstyled_content FOUC]-like symptoms.
|}

==Widget Mix-and-Match==

{| cellpadding="8" cellspacing="0"
|+ style="caption-side:top; text-align: left; color:Gray" | Mix-and-matching Use Case Parameters
! align="right" valign="top" | Who
| Web Application Engineer
|-
! align="right" valign="top" | What
| Build an application using multiple existing controls from several frameworks.
|-
! align="right" valign="top" | Purpose
|
* Write application faster by reusing code.
* Avoid having to exclusively go with one framework.
|-
! align="right" valign="top" | Examples
|
* [http://stackoverflow.com/questions/4534274/how-do-you-access-dijit-elements-in-jquery How do you access Dijit elements in JQuery]
* [http://yehudakatz.com/2011/06/11/using-sproutcore-2-0-with-jquery-ui/ Using SproutCore 2.0 with jQuery UI]
* [http://stackoverflow.com/questions/394601/which-javascript-framework-jquery-vs-dojo-vs Which JavaScript framework (jQuery vs Dojo vs … )?]
|-
! align="right" valign="top" | Desirable Properties
|
* [[Component_Model#Consistency | Consistency]] -- a compatible way to expose properties and methods across widget frameworks.
* [[Component_Model#Composability | Composability]] -- a method to compose with cross-framework widgets.
|}

==Rendering Form Controls with SVG==

{| cellpadding="8" cellspacing="0"
|+ style="caption-side:top; text-align: left; color:Gray" | SVG Form Controls Use Case Parameters
! align="right" valign="top" | Who
| Web Application Engineer or Web Framework Engineer
|-
! align="right" valign="top" | What
| Create a set of UI controls that act like standard HTML forms controls, but use SVG for rendering.
|-
! align="right" valign="top" | Purpose
|
* Provide custom appearance of form controls, consistent with overall the Web application theme.
* Make the form controls scale beautifully for various resolutions and form factors.
|-
! align="right" valign="top" | Examples
|
[http://docs.sproutcore.com/#doc=SC.ImageButtonView&src=false SproutCore's ImageButtonView], [http://dev.sencha.com/deploy/touch/docs/?class=Ext.form.Number Sencha's Number] -- examples of extensive themed form control hierarchy.
|-
! align="right" valign="top" | Desirable Properties
|
* [[Component_Model#Consistency | Consistency]] -- the controls should act just like any other DOM elements.
* [[Component_Model#Encapsulation | Encapsulation]] -- the document shouldn't be able to accidentally mess up the rendering of the controls.
* [[Component_Model#Performance | Performance]] -- load quickly, avoid [http://en.wikipedia.org/wiki/Flash_of_unstyled_content FOUC]-like symptoms when using controls.
|}

==Contacts Widget==

{| cellpadding="8" cellspacing="0"
|+ style="caption-side:top; text-align: left; color:Gray" | Contacts Widget Use Case Parameters
! align="right" valign="top" | Who
| Web Application Engineer
|-
! align="right" valign="top" | What
| Build a drop-in Contacts widget, which has a pre-defined appearance and shows a list of your contacts, with a way to change the widget to compact or full view and to tell the widget to refresh its state.
|-
! align="right" valign="top" | Purpose
|
* Use the widget anywhere in the application without having to worry about styles affecting its appearance.
* Hide details of loading contact data and other plumbing of the widget from the consuming code with a stable API.
|-
! align="right" valign="top" | Examples
| [http://i.imgur.com/4eDXM.png A screenshot of Google+ "in your circles" widget]
|-
! align="right" valign="top" | Desirable Properties
|
* [[Component_Model#Encapsulation | Encapsulation]] -- means to ensure style of the document does not affect the widget, and widget's logic is kept to the widget.
* [[Component_Model#Composability | Composability]] -- easily added anywhere in the DOM tree.
|}

==Like/+1 Button==

{| cellpadding="8" cellspacing="0"
|+ style="caption-side:top; text-align: left; color:Gray" | Like/+1 Button Use Case Parameters
! align="right" valign="top" | Who
| Web Application Engineer
|-
! align="right" valign="top" | What
| Build a drop-in widget with a pre-defined appearance of a button, showing a count of likes/+1s for this instance of a button (count is stored at a central location), embeddable on any document on the Web.
|-
! align="right" valign="top" | Purpose
|
* Provide a simple vehicle for Web authors to embed the button.
* Isolate widget implementation details from the document.
|-
! align="right" valign="top" | Examples
|
* [http://developers.facebook.com/docs/reference/plugins/like/ Facebook Like button embedding instructions]
* [http://www.google.com/webmasters/+1/button/ Google +1 button embedding instructions]
|-
! align="right" valign="top" | Desirable Properties
|
* [[Component_Model#Encapsulation | Encapsulation]] -- means to ensure style of the document does not affect the widget, and widget's logic is kept to the widget.
* [[Component_Model#Confinement | Confinement]] -- a way to completely isolate the widget implementation from the document in which it is being embedded.
* [[Component_Model#Performance | Performance]] -- don't block the page load.
|}

==Table-based Charts==

{| cellpadding="8" cellspacing="0"
|+ style="caption-side:top; text-align: left; color:Gray" | Table-based Charts Use Case Parameters
! align="right" valign="top" | Who
| Web Framework Engineer
|-
! align="right" valign="top" | What
| Provide a way to represent table data markup as charts or diagrams.
|-
! align="right" valign="top" | Purpose
| Make it easy for Web authors to create charts and diagrams using table markup.
|-
! align="right" valign="top" | Examples
|
* [http://www.wait-till-i.com/2008/01/08/generating-charts-from-accessible-data-tables-using-the-google-charts-api/ Christian Heilmann's tochart script]
|-
! align="right" valign="top" | Desirable Properties
|
* [[Component_Model#Composability | Composability]] -- one should be able to make chart by creating a table, imperatively or declaratively.
* [[Component_Model#Performance | Performance]] -- no FOUC or blocking load when charts are loaded.
|}

==Timezone selection via Image==

{| cellpadding="8" cellspacing="0"
|+ style="caption-side:top; text-align: left; color:Gray" | Timezone selection via Image Use Case Parameters
! align="right" valign="top" | Who
| Web Framework Engineer
|-
! align="right" valign="top" | What
| Graphical representation of a timezone selector that shows a world map in addition to/instead of a drop-down list.
|-
! align="right" valign="top" | Purpose
| Make it easy for Web authors to spruce up time zone selection (or similar).
|-
! align="right" valign="top" | Examples
|
* [http://www.timezonecheck.com Time Zone Map]
|-
! align="right" valign="top" | Desirable Properties
|
* [[Component_Model#Extensibility | Extensibility]] -- Basically extending <select>. Should fall back to a simple <select> where components are not supported.
* [[Component_Model#Consistency | Consistency]] -- Extend the <select> API for item selection.
|}

==Entry-helper==

{| cellpadding="8" cellspacing="0"
|+ style="caption-side:top; text-align: left; color:Gray" | Entry-helper Use Case Parameters
! align="right" valign="top" | Who
| Web Framework Engineer, Web Application Engineer
|-
! align="right" valign="top" | What
| Add an entry-helper (drop-down) list to input fields.
|-
! align="right" valign="top" | Purpose
|
Help the user fill in a form field, show suggestions and acceptable values, speed up data entry.
|-
! align="right" valign="top" | Examples
|
* Most browser's address bar or web search field
|-
! align="right" valign="top" | Desirable Properties
|
* [[Component_Model#Extensibility | Extensibility]] -- Basically extending <input>. Should fall back to a simple <input> where components are not supported.
|}

=Built-in HTML Elements=

Many non-trivial (i.e. with additional behavior and styling beyond the standard box model) elements that exist in HTML today could be implemented using HTML/CSS/JS. It makes sense to provide a standardized way to accomplish this, with the short-term goals of reducing the size of browsers C++ code and making new element implementation easier, and the long-term goal of converging built-in HTML element implementations across browsers.

{| cellpadding="8" cellspacing="0"
|+ style="caption-side:top; text-align: left; color:Gray" | Built-in HTML Elements Use Case Parameters
! align="right" valign="top" | Who
| Browser Engineer
|-
! align="right" valign="top" | What
| Implement a built-in HTML element by composing or extending existing HTML elements
|-
! align="right" valign="top" | Purpose
|
* Reduce amount of custom UI code (fewer bugs, less code rot, leading to fewer future bugs).
* Remove magic: make it easier for authors to grok control behavior in familiar terms, allow authors to style controls using CSS.
* ''Stretch'': specify built-in element behavior in terms of the component model specification.
|-
! align="right" valign="top" | Desirable Properties
|
* [[Component_Model#Encapsulation | Encapsulation]] -- ensure that implementation details are not exposed to the document
* [[Component_Model#Desugaring | Desugaring]] -- explain appearance and behavior of controls in terms of CSS/DOM.
|}

==Media Controls For The Video Element==

Using DOM elements, build a media controls panel for the [http://www.whatwg.org/specs/web-apps/current-work/multipage/the-video-element.html#the-video-element video element]. The media controls include:
* timeline slider
* stop/start, replay, closed-captioning, forward, rewind and volume buttons, and
* a volume control, which is revealed when hovering over the volume button.

The implementation details of the media controls should not be accessible or perceptible from outside of the video element. Document styles should not interfere with the styles of the media controls panel. However, we must provide a way for an author to explicitly style all parts of the media controls panel.

==Details/Summary Elements==

Implement [http://www.whatwg.org/specs/web-apps/current-work/multipage/interactive-elements.html#the-details-element details] and [http://www.whatwg.org/specs/web-apps/current-work/multipage/interactive-elements.html#the-summary-element summary] elements. According to the spec, the first <code>summary</code> element found in the flow content is used to represent a summary or legend of details. In case a <code>summary</code> element is not found, the UA is supposed to auto-generate some fallback content. The <code>details</code> element itself needs to have a marker indicating whether <code>details</code> element is open or closed - i.e., whether all contents of <details> are shown, or only the summary.

Just like media controls, the implementation should not be accessible by the consumer of the elements. For example, the reordering of flow content to position <code>summary</code> element as first item in the disclosure widget should be imperceptible to DOM traversal methods.

Component Model Strawman: Styling

2011-10-31T18:08:09Z

Rolandsteiner: add link to brainstorming page

see also the [http://wiki.whatwg.org/wiki/Component_Model_CSS_Brainstorming brainstorming page].

= Overview =

There are 4 actors that may modify the style of (parts of) a component:

* the browser
* the component author
* the page author
* the user

We intend to use the ShadowScope to be the staging point for component styling

= Specified Styles and Inheritance =

To style the component in a way that meets expectations, we probably need an algorithm similar to the following:

# The shadow root inherits styles from host element's parent ([[User:Rolandsteiner|RolandSteiner]]: directly or via ShadowScope?)
# All styles set on the host element (+) all styles set on the shadow root are applied to the shadow root element. To this end, the cascade order is (from least to most important):
## browser styles
## user styles
## component author styles on shadow root
## page author styles on the host element
## <tt>!important</tt> page author styles on the host element
## <tt>!important</tt> component author styles on the shadow root
## <tt>!important</tt> user styles

= Issues and Questions =

'''''What does it mean if the host element is assigned, e.g., <tt>display: table</tt>?'''''

We could ignore that property value, but that seems rather arbitrary and requires a detailed spec on what is ignored when, how and why. Another (better?) approach could be to define a new value <tt>display: component</tt>. If this value is set, an element renders as if it was a component - i.e., the element itself is not rendered, nor are its children by default. If it has a component bound to it, it is rendered instead. Otherwise, this is effectively equivalent to <tt>display: none</tt> (or we could set a different fallback, e.g. <tt>display: inline</tt>, but IMHO this just complicates things).

To further facilitate this, we can add a pseudo-class <tt>:component</tt> that matches if the element is a component. With this, the UA stylesheet just needs an entry <tt>:component { display: component }</tt> to properly render components, while still allowing the page author to override specific elements he doesn't want to be rendered as components.

'''''In that case, what does it mean if a generated-content pseudo element such as <tt>::before</tt> sets <tt>display: component</tt>?'''''

We can either ignore this and treat it as equivalent to <tt>display: none</tt> - the generated content does not have a component assigned to it after all - or use that as a staging point for decorators somehow.

Component Model

2011-10-29T01:41:12Z

Rolandsteiner: /* Introduction */ add more brainstorming links

Here's a good starting point for learning about the [https://github.com/dglazkov/component-model component model spec], which is being developed by applying a [[Component_Model_Methodology | defined methodology]].

=Introduction=

The '''Component Model''' introduces comprehensive support for creating DOM elements. [[Component_Model_Use_Cases | Examples]] include layout managers, combinations of Dojo and jQuery widgets, isolated widgets, such as Like/+1 buttons, and built-in HTML elements themselves. Reflecting on the experience of Mozilla's XBL and Microsoft Internet Explorer's HTML components, the Component Model formalizes the concept of loosely coupled, coherent units of [[Behavior Attachment | behavior]] in the [http://www.w3.org/wiki/Open_Web_Platform Web platform]. The functionality goals of the Component Model resemble the goals of [http://dev.w3.org/2006/xbl2/ XBL2]; unlike XBL2, the Component Model seeks to be more incremental and modular while leveraging and integrating with new technologies.

Strawman pages:

* [http://wiki.whatwg.org/wiki/Component_Model_Strawman:_Decorators Decorators]
* [http://wiki.whatwg.org/wiki/Component_Model_Strawman:_Element_Registration Element Registration]
* [http://wiki.whatwg.org/wiki/Component_Model_Strawman:_Styling Styling]
* [http://wiki.whatwg.org/wiki/Component_Model_Strawman:_Isolation Isolation]

Related links:

* [[Behavior_Attachment | Behavior Attachment]] -- a general overview of the behavior attachment problem
* [[Component_Model_Methodology | Component Model Methodology]]
* [[Component_Model_Use_Cases | Component Model Use Cases]]
* [[Component_Model_Declarative_Syntax | Component Model Declarative Syntax]]
* [https://github.com/dglazkov/component-model Component Model Spec on Github]
* [http://dglazkov.github.com/component-model/ Component Model Spec Snapshot on Github Pages]
* [[Component_Model_Progressive_Enhancement | Component Model Progressive Enhancement]]
* [[Custom_Tags_Analysis | Custom Tags Analysis]]

Discussion and brainstorming pages:

* [http://wiki.whatwg.org/wiki/Component_Model_Discussion Main discussion page with open questions]
* [http://wiki.whatwg.org/wiki/Component_Model_Discussion:_Rendering Rendering-specific discussion]
* [http://wiki.whatwg.org/wiki/Component_Model_Brainstorming general brainstorming]
* [http://wiki.whatwg.org/wiki/Component_Model_CSS_Brainstorming brainstorming page about CSS and styling]
* [http://wiki.whatwg.org/wiki/Component_Model_Isolation_Brainstorming brainstorming page about isolation and confinement]
* [http://wiki.whatwg.org/wiki/Component_Model_Decorator_Brainstorming brainstorming page about decorators]
* [http://wiki.whatwg.org/wiki/Component_Model_IDL_Brainstorming brainstorming page about IDLs and communication across boundaries]
* [http://wiki.whatwg.org/wiki/Component_Model_Aspect-oriented_Components_Brainstorming brainstorming about aspect-oriented components]

=Properties=

The component model aims to satisfy several key properties. These properties were extracted from the [[Component_Model_Use_Cases | 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:
<code>
<pre>
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>";
</pre>
</code>

The resulting <code>panel</code> 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 | Constructable DOM Types]]
* [[#Registering_Elements | Registering Elements]]

==Consistency==

Because components are just DOM objects, they inherently share the same traversal and manipulation APIs, as defined by the [http://dvcs.w3.org/hg/domcore/raw-file/tip/Overview.html DOM4]. The authors of components can extend these APIs by adding custom methods and properties on DOM objects, using standard JavaScript inheritance:
<code>
<pre>
Widget.prototype = Object.create(HTMLElement.prototype, {
update: {
value: function() { /* ... */ }
},
value: {
get: function() { /* ... */ },
set: function() { /* ... */ }
},
// ...
});
</pre>
</code>
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 | 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 [http://glazkov.com/2011/01/14/what-the-heck-is-shadow-dom/ shadow DOM]. The boundary between the document DOM tree and shadow DOM tree provides complete encapsulation, and ensures that:
* no shadow DOM tree nodes cross this boundary during event dispatch;
* document DOM tree has no access to nodes in the shadow DOM tree.

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 <code>ShadowRoot</code> 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:

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

Required Building Blocks:
* [[#Shadow_DOM | Shadow DOM]]

==Composability==

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

There can be more than one <code>content</code> element in the shadow tree. The <code>includes</code> attribute provides a convenient way to sort element's children by CSS selector. For example, a <code>DockLayoutPanel</code> component could be used like this in the document DOM tree:
<code>
<pre>
<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>
</pre>
</code>
Provided that its shadow DOM tree looks like this:
<code>
<pre>
<#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>
</pre>
</code>
The document DOM tree children on of <code>x-dock-layout-panel</code> will be rendered as if composed from this tree:
<code>
<pre>
<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>
</pre>
</code>

Required Building Blocks:
* [[#Content_Element | 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 [http://dev.w3.org/csswg/css3-lists/ lists]) are just components that have shadow DOM. Coincidentally, this also explains why you can't add shadow DOM subtrees to <code>input</code> or <code>details</code> elements -- their <code>ShadowRoot</code>s are claimed by <code>HTMLInputElement</code> and <code>HTMLDetailsElement</code> constructors, respectively.

Required Building Blocks:
* [[#Shadow_DOM | Shadow DOM]]
* [[#Content_Element | 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:

<code>
<pre>
// 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);
</pre>
</code>

In this situation, there is no room for error: <code>view.js</code> ''must'' wait for <code>layout.js</code> to load before executing. You can't load <code>layout.js</code> lazily or in any different order, since it defines the components that are used in <code>view.js</code>. 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 an unknown DOM element with an "x-"-prefixed <code>tagName</code> is encountered, we put a placeholder <code>HTMLUnknownElement</code> instance in its place. As soon as the element is defined, all placeholder instances are replaced ([http://www.w3.org/TR/DOM-Level-3-Core/core.html#Document3-renameNode Document.renameNode]) with the new, proper DOM element.

Required Building Blocks:
* [[#Registering_Elements | Registering Elements]]

== Confinement ==
Confinement refers to the document protecting its implementation details and state from the component and can be viewed as the inverse of [[#Encapsulation | encapsulation]].

Required Building Blocks:
* [[#Confinement_Primitives | Confinement Primitives]]

=Building Blocks=

The component model is comprised of the following building blocks.

==Shadow DOM==

Any DOM element can host a shadow DOM subtree. The shadow DOM subtree originates at <code>ShadowRoot</code>, which is coupled the hosting element at the time of its construction. You don't need any other building blocks in order to take advantage of the shadow DOM:
<code>
<pre>
var element = document.createElement("div");
var shadow = new ShadowRoot(element);
shadow.appendChild(document.createElement("p")).textContent = "weee!!';
</pre>
</code>

A <code>ShadowRoot</code> instance is a [http://dvcs.w3.org/hg/domcore/raw-file/tip/Overview.html#interface-node Node], and acts as the root of the element's shadow DOM subtree. The <code>ShadowRoot</code> itself is never rendered, nor has styles. In this regard, it's similar to the [http://dvcs.w3.org/hg/domcore/raw-file/tip/Overview.html#interface-documentfragment DocumentFragment]. It has two properties:
* <code>applyAuthorSheets</code>, which is either '''true''' (that is, apply author style sheets from the document), or '''false''' (don't);
* <code>shadowHost</code>, which points to the hosting element.

==Content Element==

The <code>content</code> element is used with [[#Shadow_DOM | Shadow DOM]] and provides a mechanism for distributing hosting element's children inside of its shadow subtree. To preserve the [[#Encapsulation | encapsulation]] property, the <code>content</code> elements act as insertion points and do not leak any information about hosting element's children to the shadow DOM subtree or vise versa.

==Constructable DOM Types==
The inability to construct DOM element using <code>new</code> (with some exceptions) or use them in the prototype inheritance chain had confounded many Web developers since the beginning of DOM. This building block intends to rectify at least the latter by allowing <code>HTMLElement.call</code> invocation and thus enabling creation of JavaScript objects with DOM elements in the prototype chain.

==Registering Elements==
Working in conjunction with [[#Constructable_DOM_Types | Constructable DOM Types]], this building block makes the list of valid markup tag names extensible by exposing <code>Element.register</code>:
<code>
<pre>
partial interface Element {
static void register(in String tagName, in Function constructor);
}
</pre>
</code>

It is possible to envisage a milder (though less elegant) version of element registration by keeping DOM element construction magical (thus decoupling it from [[#Constructable_DOM_Types | Constructable DOM Types]]) and making <code>Element.register</code> use a callback, rather than <code>constructor</code> as parameter. The callback would be invoked with an already-constructed DOM object with the specified <code>tagName</code>, leaving the work of setting up properties on this object to the callback.

==Confinement Primitives==

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 <code>window.postMessage</code>.

* 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 <code>Element.register</code> and <code>new ShadowRoot</code> 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 <code>confined</code> attribute to the <code>script</code> element. Presence of this attribute triggers loading scripts in the confined context.

Confinement of script execution could be useful outside of the component model and also could be related to [https://dvcs.w3.org/hg/content-security-policy/raw-file/tip/csp-specification.dev.html Content Security Policy].

* [[Component_Model_Isolation_Brainstorming | Isolation Brainstorm]]

=Building Blocks Use Case Coverage=

Here's a list of building blocks, tabulated against the [[Component_Model_Use_Cases | use cases]] and approximate percentage of satisfying them:

{| cellpadding="10" cellspacing="0" style="border-collapse: collapse;"
|- valign="top" style="border-bottom: 1px solid LightGray;"
! align="left" | Building Block
! align="left" | [[Component_Model_Use_Cases#Layout_Manager | Layout Manager]]
! align="left" | [[Component_Model_Use_Cases#Widget_Mix-and-Match | Mix-and-Match]]
! align="left" | [[Component_Model_Use_Cases#Rendering_Form_Controls_with_SVG | SVG Controls]]
! align="left" | [[Component_Model_Use_Cases#Contacts_Widget | Contacts Widget]]
! align="left" | [[Component_Model_Use_Cases#Like.2F.2B1_Button | Like/+1 Button]]
! align="left" | [[Component_Model_Use_Cases#Media_Controls_For_The_Video_Element | Media Controls for the Video Element]]
! align="left" | [[Component_Model_Use_Cases#Details.2FSummary_Elements | Details/Summary Element]]
|- valign="top" style="border-bottom: 1px solid LightGray;"
| [[Component_Model#Shadow_DOM | Shadow DOM]]
| 25%
| -
| 34%
| 100%
| 25%
| 100%
| 50%
|- valign="top" style="border-bottom: 1px solid LightGray;"
| [[Component_Model#Content_Element | Content Element]]
| 25%
| -
| -
| -
| -
| -
| 50%
|- valign="top" style="border-bottom: 1px solid LightGray;"
| [[Component_Model#Constructable_DOM_Types | Constructable DOM Types]]
| 25%
| 50%
| 33%
| -
| 25%
| -
| -
|- valign="top" style="border-bottom: 1px solid LightGray;"
| [[Component_Model#Registering_Elements | Registering Elements]]
| 25%
| 50%
| 33%
| -
| 25%
| -
| -
|- valign="top" style="border-bottom: 1px solid LightGray;"
| [[Component_Model#Confinement_Primitives | Confinement Primitives]]
| -
| -
| -
| -
| 25%
| -
| -
|}

=Comparison With Existing Specs and Implementations=

Here's a brief overview of existing similar specifications and implementations:
* [http://msdn.microsoft.com/en-us/library/ms531018(v=vs.85).aspx HTML Components] is a [http://windows.microsoft.com/en-US/internet-explorer/products/ie/home Microsoft Internet Explorer]-specific method of creating custom DOM elements. Also see [http://www.w3.org/TR/NOTE-HTMLComponents HTML Components Note] (implemented in IE5+).
* [http://www.w3.org/TR/2001/NOTE-xbl-20010223/ XBL], currently implemented in Mozilla.
* [http://dev.w3.org/2006/xbl2/ XBL2], the ancestral spec of the Component Model, and a revision of XBL.

Here's a handy overview of how each of these specs satisfies the component model [[#Properties | properties]]:

{| cellpadding="10" cellspacing="0" style="border-collapse: collapse;"
|- valign="top" style="border-bottom: 1px solid LightGray;"
! align="left" width="12%" | Spec/Implementation
! align="left" width="12%" | [[#Extensibility | Extensibility]]
! align="left" width="12%" | [[#Consistency | Consistency]]
! align="left" width="12%" | [[#Encapsulation | Encapsulation]]
! align="left" width="12%" | [[#Composability | Composability]]
! align="left" width="12%" | [[#Desugaring | Desugaring]]
! align="left" width="12%" | [[#Performance | Performance]]
! align="left" width="12%" | [[#Confinement | Confinement]]
|- valign="top" style="border-bottom: 1px solid LightGray;"
! align="left" | HTML Components
| '''No'''. Components are magic, inextensible objects.
| '''Almost'''. Implementation provides ways to add properties, methods, events to element API, and the components are ''almost'' DOM elements. However, custom tags don't support all properties of a DOM element.
| '''Not much'''. There are some provisions for event encapsulation, nothing else.
| '''Not much'''. No provisions for handling document children vs. component-defined children.
| '''No'''.
| '''Not sure'''.
| '''No'''.
|- valign="top" style="border-bottom: 1px solid LightGray;"
! align="left" | XBL
| '''No'''. The mechanism for extending bindings is entirely independent of DOM type or Javascript extensibility.
| '''Yes-ish'''. Bindings can override properties on the DOM element, although the mechanism is highly unnatural (XML declarations).
| '''Yes'''? Hard to say looking at TR note.
| '''Yes'''
| '''Yes'''. Some HTML elements in Gecko are implemented using it.
| '''Not sure'''.
| '''No'''.
|- valign="top" style="border-bottom: 1px solid LightGray;"
! align="left" | XBL2
| '''No'''. Same as XBL.
| '''No'''. Bindings are discouraged from establishing an API surface on a bound element.
| '''Yes'''.
| '''Yes'''.
| '''No'''. The spec didn't intend to describe how native elements are built.
| '''Somewhat'''. The lifecycle of a binding is well-defined and initialization stages are well-decoupled. However, there is no way to build a binding imperatively without loading a binding document.
| '''No'''.
|}

The key differences between XBL2 and the Component Model are:
* The Component Model fully embraces the [[Behavior_Attachment#Behavior_Attachment_Methods | element behavior attachment]] by allowing creation of new types of DOM elements within a document. This is something Web Framework developers always wanted and repeatedly try to do with parallel object hierarchies. Eliminating ephemerality of the attachment simplifies and clarifies how things work conceptually -- there is no longer a place for "spooky action at a distance", caused by a change of a random CSS selector or even removing an element from the tree.
* The Component Model is strongly biased toward reusing existing bits of the platform and well-established techniques instead of inventing new ones. For instance, instead of bindings inheritance, we rely on prototype inheritance. Instead of endeavoring to solve the incredibly complex, yet dubious problem of multiple bindings or shadow DOM trees, we simply suggest composition.
* The Component Model strives to add capabilities in layers (see [[#Building_Blocks | building blocks]]), each able to function on its own. The omnibus nature of XBL2 removes opportunities for layering, particularly as element identity, life cycle, and scripting are concerned. Perhaps this could be repaired somehow, but Component Model solves these issues without further complicating an already large, difficult to understand spec.

[[Category:Proposals]]

Component Model Aspect-oriented Components Brainstorming

2011-10-29T01:38:15Z

Rolandsteiner: Initial stub

= Example =

component declaration:

<template name="x-base">
<template name="top">
<content select="X"></content>
</template>
<template name="center">
<content select="Y"></content>
</template>
<template name="bottom">
<content select="Z"></content>
</template>
<template> 
<use name="top"></use>
<use name="center"></use>
<use name="bottom"></use>
<content select="W"></content>
</template>
</template>

derived component overriding main template. Pattern derived components will use most often.

<template name="x-derived1" base="x-base">
<template>
<content select="Z"></content>
<use name="top"></use>
<use name="center"></use>
<use name="bottom"></use>
</template>
</template>

derived component overriding a part template. All <use> elements referring to "top" in the finalized component will now render below structure instead. Pattern decorators will use most often

<template name="x-derived2" base="x-base">
<template name="top">
<content select="X"></content>
<content select="Z"></content>
</template>
</template>

combination: derived component overriding main template and a part template, and adding a new template, all at once. Pattern derived components will use often.

<template name="x-derived1" base="x-base">
<template name="bottom">
<hr>
<content select="Z"></content>
</template>
<template name="left">
<content select="Y"></content>
</template>
<template>
<use name="top"></use>
<use name="bottom"></use>
</template>
</template>

= Issues =

* Splitting scripting among parts - how to "re-route" scripting to overriding parts? probably not possible -> rely on heavy messaging instead?
* Overriding parts again requires a certain knowledge of a components internals - at least which parts exist and what they do (then again, this is also the point)
* How to best apply & remove "decorators"?
* It's not possible to extend a template or part (adding or wrapping the base part, but also rendering it) - it's either leave the original or replace it completely. The ability to extend seems desirable in some cases, but would then re-raise the XBL inheritance questions. How to best reconcile this? (or ignore it?)
* In some sense all this creates a mother-of-all-flattened-trees
* Can this work if some parts are being isolated?

Component Model Decorator Brainstorming

2011-10-29T01:06:36Z

Rolandsteiner: /* Implementation Approaches */ divide shadow-DOM approaches, add aspect-oriented approach

= Overview =

== Considerations ==

=== Dynamic ===

A decorator can be applied and removed dynamically, as opposed to a component, which is applied statically and cannot change. Furthermore, an element can have 0-n decorators, but just 0-1 components.

=== Interface ===

A decorator cannot add additional interfaces to the decorated element.

=== Confinement ===

A decorator may come from an untrusted source. In case the decorated element is a component, that component may come from an untrusted source as well, which may be different than the decorator's.

=== Priority Inversion ===

An XBL-style <tt><inherited></tt> places the decorator(s) on top of the main component, making the decorator the root of the tree. This makes the decorator the "more important" part in the relation. Indeed, a decorator might omit the <tt><inherited></tt> element, hiding the component (and other decorators) entirely.

[[User:Rolandsteiner|RolandSteiner]] Decorators therefore should be rendered "around" the element or component. Cases where a tighter coupling is required are probably better handled by composition.

=== Decorating Component Parts ===

In some cases it may be desirable to have the ability to decorate specific parts of a component. E.g., the caps-lock indicator in an <tt><input></tt> field could be considered a decorator.

However, this clashes with the desire to not make the internals of components public. To reconcile this we'd need a better model of how to declare component parts, whether "aspect-oriented components" or something different.

== Triggers ==

We consider the following triggers for the application of decorators:

* element tag names
* attributes
* ARIA roles
* general CSS

If we can achieve decorator-assignment via generic CSS rules, this can handle all cases above.

== Questions ==

=== Recursiveness ===

Can a decorator be decorated itself?

=== Styling ===

Can a decorator affect the styling of the decorated element?

=== Layout ===

Can a decorator affect the layout of the decorated element and/or surrounding elements? For example, consider an element that is given a specific height and width:

* If the purpose of the dimensions is to fit, e.g., an image, then changing those dimensions to fit the decorator seems ill-advised
* If the purpose of the dimensions is for precise layouting, then shifting surrounding elements to fit the decorator seems ill-advised

(However, given that which decorators to consider is in the hands of the page author the above are only minor considerations.)

=== Multiple Decorators ===

It seems useful and straight-forward to allow multiple decorators on a single element. However, assigning decorators, e.g., via a CSS <tt>binding</tt> property and using the CSS cascade would leave only the decorator stemming from the most specific rule.

= Binding Approaches =

== CSS ==

=== XBL Approach ===

XBL uses a CSS attribute <tt>binding</tt> to assign bindings to elements, as well as allowing elements to add bindings explicitly via <tt>element.addBinding()</tt>. While XBL specifies implicit bindings, as would be used by decorators, the natural vehicle to apply decorators - CSS - only seems to allow one (?).

=== CSS Decorator Properties ===

Allow decorators to specify a CSS <tt>decorator-<xyz></tt> property with the values <tt>none</tt> and <tt>apply</tt>. Rules can then switch individual decorators on or off.

==== Advantages ====

* allows decorators to be switched on or off based on rules

==== Disadvantages ====

* requires probably controversial CSS extension
* does not define where decorator is rendered
* does not allow classification which decorators are applicable to which elements

=== CSS Decorator Pseudo-elements ===

Allow decorators to specify a CSS pseudo-element or - probably better - an ID that can be accessed via a pseudo-element function <tt>::decorator()</tt>.

==== Advantages ====

* potentially easier to get acceptance for <tt>::decorator()</tt> than for decorator properties.
* pseudo-element kinda makes sense, since the decorator can be considered becoming part of the decorated element
* allows further styling of the decorator
* classification what decorators can be applied to which elements in the realm of the possible (make 'illegal' decorators fail in the CSS selector matching).

==== Disadvantages ====

* what are the properties for the pseudo-element?
* how to turn off a set pseudo-element again?

= Implementation Approaches =

== Pure CSS ==

In this approach, the decorator is defined purely in CSS. To this end we'd need to extend the layout capabilities of CSS to allow the creation and arrangement of arbitrary render boxes.

=== Advantages ===

* Does not create inter-dependence between DOM and CSS applying decorators - everything is handled by CSS.
* Trivially allows for the application of decorators via generic CSS rules.
* Extending the layout capabilities of CSS can be useful - and has been asked for - in general.

=== Disadvantages ===

* Expressiveness seems limited.
* Open questions regarding interactivity, how to bind event listeners, etc.
* Long standardization to get there.

== Component-like shadow DOM, rendered as overlay ==

The decorators are declared similar to components and have their own DOM tree. A component is rendered in the specified position separately from the main DOM as an overlay to the "normal" rendering.

=== Advantages ===

* Expressiveness and scriptability of DOM
* Uses tools we already have or develop for components, no interaction between decorator and regular element rendering

=== Disadvantages ===

* Creates a inter-dependency between DOM and the triggers (e.g., CSS), but less of an issue than with XBL-inheritance approaches
* Overlays are quite limited in capabilities

== Component-like shadow DOM, with inheritance ==

The decorators are declared similar to components and have their own DOM tree. A component is rendered in the specified position separately from the main DOM.

=== Advantages ===

* Expressiveness and scriptability of DOM
* Uses tools we already have or develop for components, no interaction between decorator and regular element rendering

=== Disadvantages ===

* Creates a inter-dependency between DOM and the triggers (e.g., CSS)
* "Heavier" in application.
* (Re-)raises questions about (explicit or implicit) XBL-like inheritance, overriding and/or hiding of previously applied shadow trees

== Aspect-oriented components ==

Components are assembled from parts, which are essentially "micro-templates". Sub-classes and decorators can override any or all of those parts. What is rendered is an auto-flattening of all final parts.

=== Advantages ===

* Defines inner structure of components, makes individual parts decoratable/replaceable
* Parts can serve as pseudo-element targets naturally
* Individual parts should be responsible for a limited subset of the host element's children, reducing the potential conflict area between multiple parts vying for the same host elements

=== Disadvantages ===

* Best trigger mechanism undefined (questionable whether CSS is a good fit)
* Probably very heavy in application.
* Requires discipline from authors to set up effectively
* Scripts may hold references to elements in parts that "go away" on updates (may not be a problem in practice)

== In-between ==

Determine decorators in terms of CSS layout, but define that layout in terms of a DOM and open it up to scripting - e.g., auto-instantiate the DOM when a content-generating pseudo-element is used.

=== Advantages ===

* Simplicity of CSS application, but allowing for scripting
* Details what is currently "hidden"

=== Disadvantages ===

* Performance questions
* Content-generating pseudo-classes may not fit a single DOM template
* Defining things in terms of DOM may block future additions to CSS that then would no longer fit that definition (and thus break pages)
* Performant implementation may require multiple renderers per node

Component Model Strawman: Styling

2011-10-29T00:40:55Z

Rolandsteiner: /* Specified Styles and Inheritance */

= Overview =

There are 4 actors that may modify the style of (parts of) a component:

* the browser
* the component author
* the page author
* the user

We intend to use the ShadowScope to be the staging point for component styling

= Specified Styles and Inheritance =

To style the component in a way that meets expectations, we probably need an algorithm similar to the following:

# The shadow root inherits styles from host element's parent ([[User:Rolandsteiner|RolandSteiner]]: directly or via ShadowScope?)
# All styles set on the host element (+) all styles set on the shadow root are applied to the shadow root element. To this end, the cascade order is (from least to most important):
## browser styles
## user styles
## component author styles on shadow root
## page author styles on the host element
## <tt>!important</tt> page author styles on the host element
## <tt>!important</tt> component author styles on the shadow root
## <tt>!important</tt> user styles

= Issues and Questions =

'''''What does it mean if the host element is assigned, e.g., <tt>display: table</tt>?'''''

We could ignore that property value, but that seems rather arbitrary and requires a detailed spec on what is ignored when, how and why. Another (better?) approach could be to define a new value <tt>display: component</tt>. If this value is set, an element renders as if it was a component - i.e., the element itself is not rendered, nor are its children by default. If it has a component bound to it, it is rendered instead. Otherwise, this is effectively equivalent to <tt>display: none</tt> (or we could set a different fallback, e.g. <tt>display: inline</tt>, but IMHO this just complicates things).

To further facilitate this, we can add a pseudo-class <tt>:component</tt> that matches if the element is a component. With this, the UA stylesheet just needs an entry <tt>:component { display: component }</tt> to properly render components, while still allowing the page author to override specific elements he doesn't want to be rendered as components.

'''''In that case, what does it mean if a generated-content pseudo element such as <tt>::before</tt> sets <tt>display: component</tt>?'''''

We can either ignore this and treat it as equivalent to <tt>display: none</tt> - the generated content does not have a component assigned to it after all - or use that as a staging point for decorators somehow.

Component Model Progressive Enhancement

2011-10-29T00:37:12Z

Rolandsteiner:

A. While adding an element to a DOM tree:
# Check for existence of the <code>becomes</code> attribute. If the attribute exists:
## Check the value of the <code>becomes</code> attribute against the names of already defined elements.
### If such element exists, go to step X.
### Otherwise, store a reference to this instance in a "may-become" table.

B. When a new element is registered:
# Check to see if there are any instances waiting in the "may-become" table for this element's name
# If so, collect all these instances and, for each instance, go to step X.

C. When the "becomes" attribute is set:
# If the element is in tree, go to step A 1.1.

X. Becoming another element (in Element existing instance).
# Create the element by the name, specified in the <code>becomes</code> attribute of the existing instance
# If the existing instance is already in document tree:
## execute renameNode (or something better) to replace the old element with the newly created element.
## Otherwise, insert newly create element in DOM tree.
# Fire "<code>become</code>" event on the existing instance.
# Set <code>became</code> property on the existing instance to point to the newly created element.

[[User:Rolandsteiner|RolandSteiner]] Does this mean an author may need to duplicate CSS selectors, e.g., if we have <tt><div becomes="x-foo" class="c"></tt> and a selector <tt>div.c</tt>, don't we then also need an equivalent selector <tt>x-foo.c</tt>? OTOH, is it a problem? Perhaps more so in JS with querySelectorAll than in CSS?

Component Model Progressive Enhancement

2011-10-29T00:36:25Z

Rolandsteiner: add question

Component Model Strawman: Isolation

2011-10-29T00:33:11Z

Rolandsteiner: /* Overview */

= Overview =

== Terms ==

* '''Confined''': disallow a component from accessing the containing page. Useful when a page does not trust the component or its source.
* '''Encapsulated''': disallow the containing page from accessing the internals of the component. Useful when a component wants to prevent a page from meddling with it.
* '''Isolated''': a component that is both confined and encapsulated.

== Considerations ==

=== Autonomy ===

Components should be autonomous entities that can be loaded and applied as a single building block. Avoid requiring extensive manipulations on both side of the page <=> component divide.

This will also help in implementing decorators.

=== Interface ===

The interface of a component should be minimal and well defined. Embedding pages should not be required (nor able to in the case of encapsulation) to access, or even know about, the internals of a component. Conversely, the function of a component should not depend on being able to access the DOM or any other information of the hosting page that is not provided through an interface.

The component should be able to apply and filter data and styles passed in as it sees fit.

=== Transparency ===

Whether or not a component is isolated should ideally be transparent to both the component and the hosting DOM.

= Loading an External HTML Resource =

The element registration and template definition also can be done in an external, separate HTML resource.
Author can define a set of elements inside the external HTML and use it in different HTML pages.

Effective markup vocabulary for the external HTML is limited.
Agents only recognize the first <tt>head element</tt> and its descendant.

<pre>

<html>
<head>
<element name="x-comment">..</element>
</head>
</html>

</pre>

== The host document ==

The document which hosts an external HTML file is called a "host document".
Any HTML document can host be a host document.

If author add a <tt>link</tt> element with its <tt>rel</tt> attribute set to <tt>component</tt> to a apge,
the page hosts the linked HTML resource.

In this example, the document hosts <tt>comment.html</tt>.

<pre>

<html>
<head>
<link rel=”component” type=”text/html” href="comment.html">
</head>
</html>

</pre>

== The <tt>confined</tt> attribute ==

Author can add the <tt>confined</tt> attribute to confine the component definition.

<pre>

<html>
<head>
<link rel=”component” type=”text/html” href="comment.html" confined>
</head>
</html>

</pre>

= Shared Hosting =

If an author hosts an external HTML without specifying <tt>confined</tt> attribute,
the HTML is hosted as a shared resource.
That means, agents insert <tt>head</tt> children of the hosted document
into the host document's <tt>head</tt>.
Each script execution inside hosted HTML shares the global object with its host document.

In this example, the host document eventually has an <tt>element</tt> element named <tt>x-comment</tt>.

<pre>


<html>
<head>
<element name="x-comment">..</element>
</head>
</html>


<html>
<head>
<link rel=”component” type=”text/html” href="comment.html">
<script>
var shouldNotNull = document.querySelector("element[name=x-comment]");
</script>
</head>
</html>

</pre>

= Confined Hosting =

If an author hosts an external HTML without specifying <tt>confined</tt> attribute,
the HTML is hosted as a confined resource.

A confined resource has its document object. Any scripts inside the confined resource
are run on its own global object.

Conceptually, a confined resource is similar to a document in a cross-domain frame.
For example, the script on the confined resource can make a XMLHttpRequest to its own domain, instead of the host domain.

<pre>


<html>
<head>
<element name="x-comment">
<script>
console.log(document.location.toString()); // prints the url of comment.html
<script>
</element>
</head>
</html>


<html>
<head>
<link rel=”component” type=”text/html” href="comment.html" confined>
</head>
</html>

</pre>

== Registered Elements in a Confined Resource ==

The host document recognize an element name which is registered in the hosting confined documents, not only

Component Model Strawman: Isolation

2011-10-29T00:32:48Z

Rolandsteiner: /* Overview */

= Overview =

The isolated components definition is a <tt>provide</tt> attributed HTML file which is loaded in separate namespace.
It is basically a document loaded by an iframe. But it has different way for communicating with the host document.

== Terms ==

* '''Confined''': disallow a component from accessing the containing page. Useful when a page does not trust the component or its source.
* '''Encapsulated''': disallow the containing page from accessing the internals of the component. Useful when a component wants to prevent a page from meddling with it.
* '''Isolated''': a component that is both confined and encapsulated.

== Considerations ==

=== Autonomy ===

Components should be autonomous entities that can be loaded and applied as a single building block. Avoid requiring extensive manipulations on both side of the page <=> component divide.

This will also help in implementing decorators.

=== Interface ===

The interface of a component should be minimal and well defined. Embedding pages should not be required (nor able to in the case of encapsulation) to access, or even know about, the internals of a component. Conversely, the function of a component should not depend on being able to access the DOM or any other information of the hosting page that is not provided through an interface.

The component should be able to apply and filter data and styles passed in as it sees fit.

=== Transparency ===

Whether or not a component is isolated should ideally be transparent to both the component and the hosting DOM.

= Loading an External HTML Resource =

The element registration and template definition also can be done in an external, separate HTML resource.
Author can define a set of elements inside the external HTML and use it in different HTML pages.

Effective markup vocabulary for the external HTML is limited.
Agents only recognize the first <tt>head element</tt> and its descendant.

<pre>

<html>
<head>
<element name="x-comment">..</element>
</head>
</html>

</pre>

== The host document ==

The document which hosts an external HTML file is called a "host document".
Any HTML document can host be a host document.

If author add a <tt>link</tt> element with its <tt>rel</tt> attribute set to <tt>component</tt> to a apge,
the page hosts the linked HTML resource.

In this example, the document hosts <tt>comment.html</tt>.

<pre>

<html>
<head>
<link rel=”component” type=”text/html” href="comment.html">
</head>
</html>

</pre>

== The <tt>confined</tt> attribute ==

Author can add the <tt>confined</tt> attribute to confine the component definition.

<pre>

<html>
<head>
<link rel=”component” type=”text/html” href="comment.html" confined>
</head>
</html>

</pre>

= Shared Hosting =

If an author hosts an external HTML without specifying <tt>confined</tt> attribute,
the HTML is hosted as a shared resource.
That means, agents insert <tt>head</tt> children of the hosted document
into the host document's <tt>head</tt>.
Each script execution inside hosted HTML shares the global object with its host document.

In this example, the host document eventually has an <tt>element</tt> element named <tt>x-comment</tt>.

<pre>


<html>
<head>
<element name="x-comment">..</element>
</head>
</html>


<html>
<head>
<link rel=”component” type=”text/html” href="comment.html">
<script>
var shouldNotNull = document.querySelector("element[name=x-comment]");
</script>
</head>
</html>

</pre>

= Confined Hosting =

If an author hosts an external HTML without specifying <tt>confined</tt> attribute,
the HTML is hosted as a confined resource.

A confined resource has its document object. Any scripts inside the confined resource
are run on its own global object.

Conceptually, a confined resource is similar to a document in a cross-domain frame.
For example, the script on the confined resource can make a XMLHttpRequest to its own domain, instead of the host domain.

<pre>


<html>
<head>
<element name="x-comment">
<script>
console.log(document.location.toString()); // prints the url of comment.html
<script>
</element>
</head>
</html>


<html>
<head>
<link rel=”component” type=”text/html” href="comment.html" confined>
</head>
</html>

</pre>

== Registered Elements in a Confined Resource ==

The host document recognize an element name which is registered in the hosting confined documents, not only

Component Model Decorator Brainstorming

2011-10-29T00:31:38Z

Rolandsteiner: /* Implementation Approaches */

= Overview =

== Considerations ==

=== Dynamic ===

A decorator can be applied and removed dynamically, as opposed to a component, which is applied statically and cannot change. Furthermore, an element can have 0-n decorators, but just 0-1 components.

=== Interface ===

A decorator cannot add additional interfaces to the decorated element.

=== Confinement ===

A decorator may come from an untrusted source. In case the decorated element is a component, that component may come from an untrusted source as well, which may be different than the decorator's.

=== Priority Inversion ===

An XBL-style <tt><inherited></tt> places the decorator(s) on top of the main component, making the decorator the root of the tree. This makes the decorator the "more important" part in the relation. Indeed, a decorator might omit the <tt><inherited></tt> element, hiding the component (and other decorators) entirely.

[[User:Rolandsteiner|RolandSteiner]] Decorators therefore should be rendered "around" the element or component. Cases where a tighter coupling is required are probably better handled by composition.

=== Decorating Component Parts ===

In some cases it may be desirable to have the ability to decorate specific parts of a component. E.g., the caps-lock indicator in an <tt><input></tt> field could be considered a decorator.

However, this clashes with the desire to not make the internals of components public. To reconcile this we'd need a better model of how to declare component parts, whether "aspect-oriented components" or something different.

== Triggers ==

We consider the following triggers for the application of decorators:

* element tag names
* attributes
* ARIA roles
* general CSS

If we can achieve decorator-assignment via generic CSS rules, this can handle all cases above.

== Questions ==

=== Recursiveness ===

Can a decorator be decorated itself?

=== Styling ===

Can a decorator affect the styling of the decorated element?

=== Layout ===

Can a decorator affect the layout of the decorated element and/or surrounding elements? For example, consider an element that is given a specific height and width:

* If the purpose of the dimensions is to fit, e.g., an image, then changing those dimensions to fit the decorator seems ill-advised
* If the purpose of the dimensions is for precise layouting, then shifting surrounding elements to fit the decorator seems ill-advised

(However, given that which decorators to consider is in the hands of the page author the above are only minor considerations.)

=== Multiple Decorators ===

It seems useful and straight-forward to allow multiple decorators on a single element. However, assigning decorators, e.g., via a CSS <tt>binding</tt> property and using the CSS cascade would leave only the decorator stemming from the most specific rule.

= Binding Approaches =

== CSS ==

=== XBL Approach ===

XBL uses a CSS attribute <tt>binding</tt> to assign bindings to elements, as well as allowing elements to add bindings explicitly via <tt>element.addBinding()</tt>. While XBL specifies implicit bindings, as would be used by decorators, the natural vehicle to apply decorators - CSS - only seems to allow one (?).

=== CSS Decorator Properties ===

Allow decorators to specify a CSS <tt>decorator-<xyz></tt> property with the values <tt>none</tt> and <tt>apply</tt>. Rules can then switch individual decorators on or off.

==== Advantages ====

* allows decorators to be switched on or off based on rules

==== Disadvantages ====

* requires probably controversial CSS extension
* does not define where decorator is rendered
* does not allow classification which decorators are applicable to which elements

=== CSS Decorator Pseudo-elements ===

Allow decorators to specify a CSS pseudo-element or - probably better - an ID that can be accessed via a pseudo-element function <tt>::decorator()</tt>.

==== Advantages ====

* potentially easier to get acceptance for <tt>::decorator()</tt> than for decorator properties.
* pseudo-element kinda makes sense, since the decorator can be considered becoming part of the decorated element
* allows further styling of the decorator
* classification what decorators can be applied to which elements in the realm of the possible (make 'illegal' decorators fail in the CSS selector matching).

==== Disadvantages ====

* what are the properties for the pseudo-element?
* how to turn off a set pseudo-element again?

= Implementation Approaches =

== Pure CSS ==

In this approach, the decorator is defined purely in CSS. To this end we'd need to extend the layout capabilities of CSS to allow the creation and arrangement of arbitrary render boxes.

=== Advantages ===

* Does not create inter-dependence between DOM and CSS applying decorators - everything is handled by CSS.
* Trivially allows for the application of decorators via generic CSS rules.
* Extending the layout capabilities of CSS can be useful - and has been asked for - in general.

=== Disadvantages ===

* Expressiveness seems limited.
* Open questions regarding interactivity, how to bind event listeners, etc.
* Long standardization to get there.

== Component-like Shadow DOM ==

The decorators are declared similar to components and have their own DOM tree. A component is rendered in the specified position separately from the main DOM.

=== Advantages ===

* Greater expressiveness
* Uses tools we already have or develop for components.

=== Disadvantages ===

* Creates a inter-dependency between DOM and the triggers (e.g., CSS). Potential recursiveness.
* "Heavier" in application.
* (Re-)raises questions about (XBL-like) inheritance, overriding and/or hiding of previously applied shadow trees

== In-between ==

Determine decorators in terms of CSS layout, but define that layout in terms of a DOM and open it up to scripting - e.g., auto-instantiate the DOM when a content-generating pseudo-element is used.

=== Advantages ===

* Simplicity of CSS application, but allowing for scripting
* Details what is currently "hidden"

=== Disadvantages ===

* Performance questions
* Content-generating pseudo-classes may not fit a single DOM template
* Defining things in terms of DOM may block future additions to CSS that then would no longer fit that definition (and thus break pages)
* Performant implementation may require multiple renderers per node

Component Model Strawman: Styling

2011-10-29T00:22:13Z

Rolandsteiner: /* Issues and Questions */

= Overview =

There are 4 actors that may modify the style of (parts of) a component:

* the browser
* the component author
* the page author
* the user

We intend to use the ShadowScope to be the staging point for component styling

= Specified Styles and Inheritance =

To style the component in a way that meets expectations, we probably need an algorithm similar to the following:

# The shadow root node inherits all styles from the host element's parent
# All styles set on the host element (+) all styles set on the shadow root are applied to the shadow root element. To this end, the cascade order is (from least to most important):
## browser styles
## user styles
## component author styles on shadow root
## page author styles on the host element
## <tt>!important</tt> page author styles on the host element
## <tt>!important</tt> component author styles on the shadow root
## <tt>!important</tt> user styles

= Issues and Questions =

'''''What does it mean if the host element is assigned, e.g., <tt>display: table</tt>?'''''

We could ignore that property value, but that seems rather arbitrary and requires a detailed spec on what is ignored when, how and why. Another (better?) approach could be to define a new value <tt>display: component</tt>. If this value is set, an element renders as if it was a component - i.e., the element itself is not rendered, nor are its children by default. If it has a component bound to it, it is rendered instead. Otherwise, this is effectively equivalent to <tt>display: none</tt> (or we could set a different fallback, e.g. <tt>display: inline</tt>, but IMHO this just complicates things).

To further facilitate this, we can add a pseudo-class <tt>:component</tt> that matches if the element is a component. With this, the UA stylesheet just needs an entry <tt>:component { display: component }</tt> to properly render components, while still allowing the page author to override specific elements he doesn't want to be rendered as components.

'''''In that case, what does it mean if a generated-content pseudo element such as <tt>::before</tt> sets <tt>display: component</tt>?'''''

We can either ignore this and treat it as equivalent to <tt>display: none</tt> - the generated content does not have a component assigned to it after all - or use that as a staging point for decorators somehow.

Component Model Strawman: Isolation

2011-10-28T22:54:11Z

Rolandsteiner:

= Overview =

The isolated components definition is a <tt>provide</tt> attributed HTML file which is loaded in separate namespace.
It is basically a document loaded by an iframe. But it has different way for communicating with the host document.

See also the "Isolation" section on [[Component_Model_Strawman:_Declarative_Syntax]].

== Terms ==

* '''Confined''': disallow a component from accessing the containing page. Useful when a page does not trust the component or its source.
* '''Encapsulated''': disallow the containing page from accessing the internals of the component. Useful when a component wants to prevent a page from meddling with it.
* '''Isolated''': a component that is both confined and encapsulated.

== Considerations ==

=== Autonomy ===

Components should be autonomous entities that can be loaded and applied as a single building block. Avoid requiring extensive manipulations on both side of the page <=> component divide.

This will also help in implementing decorators.

=== Interface ===

The interface of a component should be minimal and well defined. Embedding pages should not be required (nor able to in the case of encapsulation) to access, or even know about, the internals of a component. Conversely, the function of a component should not depend on being able to access the DOM or any other information of the hosting page that is not provided through an interface.

The component should be able to apply and filter data and styles passed in as it sees fit.

=== Transparency ===

Whether or not a component is isolated should ideally be transparent to both the component and the hosting DOM.

= Loading an External HTML Resource =

The element registration and template definition also can be done in an external, separate HTML resource.
Author can define a set of elements inside the external HTML and use it in different HTML pages.

Effective markup vocabulary for the external HTML is limited.
Agents only recognize the first <tt>head element</tt> and its descendant.

<pre>

<html>
<head>
<element name="x-comment">..</element>
</head>
</html>

</pre>

== The host document ==

The document which hosts an external HTML file is called a "host document".
Any HTML document can host be a host document.

If author add a <tt>link</tt> element with its <tt>rel</tt> attribute set to <tt>component</tt> to a apge,
the page hosts the linked HTML resource.

In this example, the document hosts <tt>comment.html</tt>.

<pre>

<html>
<head>
<link rel=”component” type=”text/html” href="comment.html">
</head>
</html>

</pre>

== The <tt>confined</tt> attribute ==

Author can add the <tt>confined</tt> attribute to confine the component definition.

<pre>

<html>
<head>
<link rel=”component” type=”text/html” href="comment.html" confined>
</head>
</html>

</pre>

= Shared Hosting =

If an author hosts an external HTML without specifying <tt>confined</tt> attribute,
the HTML is hosted as a shared resource.
That means, agents insert <tt>head</tt> children of the hosted document
into the host document's <tt>head</tt>.
Each script execution inside hosted HTML shares the global object with its host document.

In this example, the host document eventually has an <tt>element</tt> element named <tt>x-comment</tt>.

<pre>


<html>
<head>
<element name="x-comment">..</element>
</head>
</html>


<html>
<head>
<link rel=”component” type=”text/html” href="comment.html">
<script>
var shouldNotNull = document.querySelector("element[name=x-comment]");
</script>
</head>
</html>

</pre>

= Confined Hosting =

If an author hosts an external HTML without specifying <tt>confined</tt> attribute,
the HTML is hosted as a confined resource.

A confined resource has its document object. Any scripts inside the confined resource
are run on its own global object.

Conceptually, a confined resource is similar to a document in a cross-domain frame.
For example, the script on the confined resource can make a XMLHttpRequest to its own domain, instead of the host domain.

<pre>


<html>
<head>
<element name="x-comment">
<script>
console.log(document.location.toString()); // prints the url of comment.html
<script>
</element>
</head>
</html>


<html>
<head>
<link rel=”component” type=”text/html” href="comment.html" confined>
</head>
</html>

</pre>

== Registered Elements in a Confined Resource ==

The host document recognize an element name which is registered in the hosting confined documents, not only

Component Model Strawman: Isolation

2011-10-28T22:53:51Z

Rolandsteiner: add Overview and Considerations

= Overview =

The isolated components definition is a <tt>provide</tt> attributed HTML file which is loaded in separate namespace.
It is basically a document loaded by an iframe. But it has different way for communicating with the host document.

See also the "Isolation" section on [[Component_Model_Strawman:_Declarative_Syntax]].

== Terms ==

* '''Confined''': disallow a component from accessing the containing page. Useful when a page does not trust the component or its source.
* '''Encapsulated''': disallow the containing page from accessing the internals of the component. Useful when a component wants to prevent a page from meddling with it.
* '''Isolated''': a component that is both confined and encapsulated.

== Considerations ==

=== Autonomy ===

Components should be autonomous entities that can be loaded and applied as a single building block. Avoid requiring extensive manipulations on both side of the page <=> component divide.

This will also help in implementing decorators.

=== Interface ===

The interface of a component should be minimal and well defined. Embedding pages should not be required (nor able to in the case of encapsulation) to access, or even know about, the internals of a component. Conversely, the function of a component should not depend on being able to access the DOM or any other information of the hosting page that is not provided through an interface.

The component should be able to apply and filter data and styles passed in as it sees fit.

=== Transparency ===

Whether or not a component is isolated should ideally be transparent to both the component and the hosting DOM.

= Approaches =

= Loading an External HTML Resource =

The element registration and template definition also can be done in an external, separate HTML resource.
Author can define a set of elements inside the external HTML and use it in different HTML pages.

Effective markup vocabulary for the external HTML is limited.
Agents only recognize the first <tt>head element</tt> and its descendant.

<pre>

<html>
<head>
<element name="x-comment">..</element>
</head>
</html>

</pre>

== The host document ==

The document which hosts an external HTML file is called a "host document".
Any HTML document can host be a host document.

If author add a <tt>link</tt> element with its <tt>rel</tt> attribute set to <tt>component</tt> to a apge,
the page hosts the linked HTML resource.

In this example, the document hosts <tt>comment.html</tt>.

<pre>

<html>
<head>
<link rel=”component” type=”text/html” href="comment.html">
</head>
</html>

</pre>

== The <tt>confined</tt> attribute ==

Author can add the <tt>confined</tt> attribute to confine the component definition.

<pre>

<html>
<head>
<link rel=”component” type=”text/html” href="comment.html" confined>
</head>
</html>

</pre>

= Shared Hosting =

If an author hosts an external HTML without specifying <tt>confined</tt> attribute,
the HTML is hosted as a shared resource.
That means, agents insert <tt>head</tt> children of the hosted document
into the host document's <tt>head</tt>.
Each script execution inside hosted HTML shares the global object with its host document.

In this example, the host document eventually has an <tt>element</tt> element named <tt>x-comment</tt>.

<pre>


<html>
<head>
<element name="x-comment">..</element>
</head>
</html>


<html>
<head>
<link rel=”component” type=”text/html” href="comment.html">
<script>
var shouldNotNull = document.querySelector("element[name=x-comment]");
</script>
</head>
</html>

</pre>

= Confined Hosting =

If an author hosts an external HTML without specifying <tt>confined</tt> attribute,
the HTML is hosted as a confined resource.

A confined resource has its document object. Any scripts inside the confined resource
are run on its own global object.

Conceptually, a confined resource is similar to a document in a cross-domain frame.
For example, the script on the confined resource can make a XMLHttpRequest to its own domain, instead of the host domain.

<pre>


<html>
<head>
<element name="x-comment">
<script>
console.log(document.location.toString()); // prints the url of comment.html
<script>
</element>
</head>
</html>


<html>
<head>
<link rel=”component” type=”text/html” href="comment.html" confined>
</head>
</html>

</pre>

== Registered Elements in a Confined Resource ==

The host document recognize an element name which is registered in the hosting confined documents, not only

Component Model Decorator Brainstorming

2011-10-27T00:07:54Z

Rolandsteiner:

Component Model Strawman: Styling

2011-10-26T20:29:35Z

Rolandsteiner: Styling part 1

= Overview =

There are 4 actors that may modify the style of (parts of) a component:

* the browser
* the component author
* the page author
* the user

We intend to use the ShadowScope to be the staging point for component styling

= Specified Styles and Inheritance =

To style the component in a way that meets expectations, we probably need an algorithm similar to the following:

# The shadow root node inherits all styles from the host element's parent
# All styles set on the host element (+) all styles set on the shadow root are applied to the shadow root element. To this end, the cascade order is (from least to most important):
## browser styles
## user styles
## component author styles on shadow root
## page author styles on the host element
## <tt>!important</tt> page author styles on the host element
## <tt>!important</tt> component author styles on the shadow root
## <tt>!important</tt> user styles

= Issues and Questions =

* What does it mean if the host element is assigned, e.g., <tt>display: table</tt>?

We could ignore that property value, but that seems rather arbitrary and requires a detailed spec on what is ignored when, how and why. Another (better?) approach could be to define a new value <tt>display: component</tt>. If this value is set, an element renders as if it was a component - i.e., the element itself is not rendered, nor are its children by default. If it has a component bound to it, it is rendered instead. Otherwise, this is effectively equivalent to <tt>display: none</tt> (or we could set a different fallback, e.g. <tt>display: inline</tt>, but IMHO this just complicates things).

To further facilitate this, we can add a pseudo-class <tt>:component</tt> that matches if the element is a component. With this, the UA stylesheet just needs an entry <tt>:component { display: component }</tt> to properly render components, while still allowing the page author to override specific elements he doesn't want to be rendered as components.

** In that case, what does it mean if a generated-content pseudo element such as <tt>::before</tt> sets <tt>display: component</tt>?

We can either ignore this and treat it as equivalent to <tt>display: none</tt> - the generated content does not have a component assigned to it after all - or use that as a staging point for decorators somehow.

Component Model Strawman: Decorators

2011-10-26T20:10:11Z

Rolandsteiner:

see also the [http://wiki.whatwg.org/wiki/Component_Model_Decorator_Brainstorming brainstorming page].

Stub

Component Model

2011-10-26T20:09:35Z

Rolandsteiner: /* Introduction */

Here's a good starting point for learning about the [https://github.com/dglazkov/component-model component model spec], which is being developed by applying a [[Component_Model_Methodology | defined methodology]].

=Introduction=

The '''Component Model''' introduces comprehensive support for creating DOM elements. [[Component_Model_Use_Cases | Examples]] include layout managers, combinations of Dojo and jQuery widgets, isolated widgets, such as Like/+1 buttons, and built-in HTML elements themselves. Reflecting on the experience of Mozilla's XBL and Microsoft Internet Explorer's HTML components, the Component Model formalizes the concept of loosely coupled, coherent units of [[Behavior Attachment | behavior]] in the [http://www.w3.org/wiki/Open_Web_Platform Web platform]. The functionality goals of the Component Model resemble the goals of [http://dev.w3.org/2006/xbl2/ XBL2]; unlike XBL2, the Component Model seeks to be more incremental and modular while leveraging and integrating with new technologies.

Strawman pages:

* [http://wiki.whatwg.org/wiki/Component_Model_Strawman:_Decorators Decorators]
* [http://wiki.whatwg.org/wiki/Component_Model_Strawman:_Element_Registration Element Registration]
* [http://wiki.whatwg.org/wiki/Component_Model_Strawman:_Declarative_Syntax Declarative Syntax]
* [http://wiki.whatwg.org/wiki/Component_Model_Strawman:_Styling Styling]
* [http://wiki.whatwg.org/wiki/Component_Model_Strawman:_Isolation Isolation]

Related links:

* [[Behavior_Attachment | Behavior Attachment]] -- a general overview of the behavior attachment problem
* [[Component_Model_Methodology | Component Model Methodology]]
* [[Component_Model_Use_Cases | Component Model Use Cases]]
* [[Component_Model_Declarative_Syntax | Component Model Declarative Syntax]]
* [https://github.com/dglazkov/component-model Component Model Spec on Github]
* [http://dglazkov.github.com/component-model/ Component Model Spec Snapshot on Github Pages]
* [[Component_Model_Progressive_Enhancement | Component Model Progressive Enhancement]]
* [[Custom_Tags_Analysis | Custom Tags Analysis]]

Discussion pages:

* [http://wiki.whatwg.org/wiki/Component_Model_Discussion Main discussion page with open questions]
* [http://wiki.whatwg.org/wiki/Component_Model_Discussion:_Rendering Rendering-specific discussion]
* [http://wiki.whatwg.org/wiki/Component_Model_CSS_Brainstorming brainstorming page about CSS and styling]
* [http://wiki.whatwg.org/wiki/Component_Model_Isolation_Brainstorming brainstorming page about isolation and confinement]
* [http://wiki.whatwg.org/wiki/Component_Model_Decorator_Brainstorming brainstorming page about decorators]
* [http://wiki.whatwg.org/wiki/Component_Model_IDL_Brainstorming brainstorming page about IDLs and communication across boundaries]

=Properties=

The component model aims to satisfy several key properties. These properties were extracted from the [[Component_Model_Use_Cases | 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:
<code>
<pre>
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>";
</pre>
</code>

The resulting <code>panel</code> 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 | Constructable DOM Types]]
* [[#Registering_Elements | Registering Elements]]

==Consistency==

Because components are just DOM objects, they inherently share the same traversal and manipulation APIs, as defined by the [http://dvcs.w3.org/hg/domcore/raw-file/tip/Overview.html DOM4]. The authors of components can extend these APIs by adding custom methods and properties on DOM objects, using standard JavaScript inheritance:
<code>
<pre>
Widget.prototype = Object.create(HTMLElement.prototype, {
update: {
value: function() { /* ... */ }
},
value: {
get: function() { /* ... */ },
set: function() { /* ... */ }
},
// ...
});
</pre>
</code>
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 | 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 [http://glazkov.com/2011/01/14/what-the-heck-is-shadow-dom/ shadow DOM]. The boundary between the document DOM tree and shadow DOM tree provides complete encapsulation, and ensures that:
* no shadow DOM tree nodes cross this boundary during event dispatch;
* document DOM tree has no access to nodes in the shadow DOM tree.

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 <code>ShadowRoot</code> 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:

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

Required Building Blocks:
* [[#Shadow_DOM | Shadow DOM]]

==Composability==

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

There can be more than one <code>content</code> element in the shadow tree. The <code>includes</code> attribute provides a convenient way to sort element's children by CSS selector. For example, a <code>DockLayoutPanel</code> component could be used like this in the document DOM tree:
<code>
<pre>
<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>
</pre>
</code>
Provided that its shadow DOM tree looks like this:
<code>
<pre>
<#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>
</pre>
</code>
The document DOM tree children on of <code>x-dock-layout-panel</code> will be rendered as if composed from this tree:
<code>
<pre>
<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>
</pre>
</code>

Required Building Blocks:
* [[#Content_Element | 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 [http://dev.w3.org/csswg/css3-lists/ lists]) are just components that have shadow DOM. Coincidentally, this also explains why you can't add shadow DOM subtrees to <code>input</code> or <code>details</code> elements -- their <code>ShadowRoot</code>s are claimed by <code>HTMLInputElement</code> and <code>HTMLDetailsElement</code> constructors, respectively.

Required Building Blocks:
* [[#Shadow_DOM | Shadow DOM]]
* [[#Content_Element | 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:

<code>
<pre>
// 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);
</pre>
</code>

In this situation, there is no room for error: <code>view.js</code> ''must'' wait for <code>layout.js</code> to load before executing. You can't load <code>layout.js</code> lazily or in any different order, since it defines the components that are used in <code>view.js</code>. 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 an unknown DOM element with an "x-"-prefixed <code>tagName</code> is encountered, we put a placeholder <code>HTMLUnknownElement</code> instance in its place. As soon as the element is defined, all placeholder instances are replaced ([http://www.w3.org/TR/DOM-Level-3-Core/core.html#Document3-renameNode Document.renameNode]) with the new, proper DOM element.

Required Building Blocks:
* [[#Registering_Elements | Registering Elements]]

== Confinement ==
Confinement refers to the document protecting its implementation details and state from the component and can be viewed as the inverse of [[#Encapsulation | encapsulation]].

Required Building Blocks:
* [[#Confinement_Primitives | Confinement Primitives]]

=Building Blocks=

The component model is comprised of the following building blocks.

==Shadow DOM==

Any DOM element can host a shadow DOM subtree. The shadow DOM subtree originates at <code>ShadowRoot</code>, which is coupled the hosting element at the time of its construction. You don't need any other building blocks in order to take advantage of the shadow DOM:
<code>
<pre>
var element = document.createElement("div");
var shadow = new ShadowRoot(element);
shadow.appendChild(document.createElement("p")).textContent = "weee!!';
</pre>
</code>

A <code>ShadowRoot</code> instance is a [http://dvcs.w3.org/hg/domcore/raw-file/tip/Overview.html#interface-node Node], and acts as the root of the element's shadow DOM subtree. The <code>ShadowRoot</code> itself is never rendered, nor has styles. In this regard, it's similar to the [http://dvcs.w3.org/hg/domcore/raw-file/tip/Overview.html#interface-documentfragment DocumentFragment]. It has two properties:
* <code>applyAuthorSheets</code>, which is either '''true''' (that is, apply author style sheets from the document), or '''false''' (don't);
* <code>shadowHost</code>, which points to the hosting element.

==Content Element==

The <code>content</code> element is used with [[#Shadow_DOM | Shadow DOM]] and provides a mechanism for distributing hosting element's children inside of its shadow subtree. To preserve the [[#Encapsulation | encapsulation]] property, the <code>content</code> elements act as insertion points and do not leak any information about hosting element's children to the shadow DOM subtree or vise versa.

==Constructable DOM Types==
The inability to construct DOM element using <code>new</code> (with some exceptions) or use them in the prototype inheritance chain had confounded many Web developers since the beginning of DOM. This building block intends to rectify at least the latter by allowing <code>HTMLElement.call</code> invocation and thus enabling creation of JavaScript objects with DOM elements in the prototype chain.

==Registering Elements==
Working in conjunction with [[#Constructable_DOM_Types | Constructable DOM Types]], this building block makes the list of valid markup tag names extensible by exposing <code>Element.register</code>:
<code>
<pre>
partial interface Element {
static void register(in String tagName, in Function constructor);
}
</pre>
</code>

It is possible to envisage a milder (though less elegant) version of element registration by keeping DOM element construction magical (thus decoupling it from [[#Constructable_DOM_Types | Constructable DOM Types]]) and making <code>Element.register</code> use a callback, rather than <code>constructor</code> as parameter. The callback would be invoked with an already-constructed DOM object with the specified <code>tagName</code>, leaving the work of setting up properties on this object to the callback.

==Confinement Primitives==

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 <code>window.postMessage</code>.

* 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 <code>Element.register</code> and <code>new ShadowRoot</code> 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 <code>confined</code> attribute to the <code>script</code> element. Presence of this attribute triggers loading scripts in the confined context.

Confinement of script execution could be useful outside of the component model and also could be related to [https://dvcs.w3.org/hg/content-security-policy/raw-file/tip/csp-specification.dev.html Content Security Policy].

* [[Component_Model_Isolation_Brainstorming | Isolation Brainstorm]]

=Building Blocks Use Case Coverage=

Here's a list of building blocks, tabulated against the [[Component_Model_Use_Cases | use cases]] and approximate percentage of satisfying them:

{| cellpadding="10" cellspacing="0" style="border-collapse: collapse;"
|- valign="top" style="border-bottom: 1px solid LightGray;"
! align="left" | Building Block
! align="left" | [[Component_Model_Use_Cases#Layout_Manager | Layout Manager]]
! align="left" | [[Component_Model_Use_Cases#Widget_Mix-and-Match | Mix-and-Match]]
! align="left" | [[Component_Model_Use_Cases#Rendering_Form_Controls_with_SVG | SVG Controls]]
! align="left" | [[Component_Model_Use_Cases#Contacts_Widget | Contacts Widget]]
! align="left" | [[Component_Model_Use_Cases#Like.2F.2B1_Button | Like/+1 Button]]
! align="left" | [[Component_Model_Use_Cases#Media_Controls_For_The_Video_Element | Media Controls for the Video Element]]
! align="left" | [[Component_Model_Use_Cases#Details.2FSummary_Elements | Details/Summary Element]]
|- valign="top" style="border-bottom: 1px solid LightGray;"
| [[Component_Model#Shadow_DOM | Shadow DOM]]
| 25%
| -
| 34%
| 100%
| 25%
| 100%
| 50%
|- valign="top" style="border-bottom: 1px solid LightGray;"
| [[Component_Model#Content_Element | Content Element]]
| 25%
| -
| -
| -
| -
| -
| 50%
|- valign="top" style="border-bottom: 1px solid LightGray;"
| [[Component_Model#Constructable_DOM_Types | Constructable DOM Types]]
| 25%
| 50%
| 33%
| -
| 25%
| -
| -
|- valign="top" style="border-bottom: 1px solid LightGray;"
| [[Component_Model#Registering_Elements | Registering Elements]]
| 25%
| 50%
| 33%
| -
| 25%
| -
| -
|- valign="top" style="border-bottom: 1px solid LightGray;"
| [[Component_Model#Confinement_Primitives | Confinement Primitives]]
| -
| -
| -
| -
| 25%
| -
| -
|}

=Comparison With Existing Specs and Implementations=

Here's a brief overview of existing similar specifications and implementations:
* [http://msdn.microsoft.com/en-us/library/ms531018(v=vs.85).aspx HTML Components] is a [http://windows.microsoft.com/en-US/internet-explorer/products/ie/home Microsoft Internet Explorer]-specific method of creating custom DOM elements. Also see [http://www.w3.org/TR/NOTE-HTMLComponents HTML Components Note] (implemented in IE5+).
* [http://www.w3.org/TR/2001/NOTE-xbl-20010223/ XBL], currently implemented in Mozilla.
* [http://dev.w3.org/2006/xbl2/ XBL2], the ancestral spec of the Component Model, and a revision of XBL.

Here's a handy overview of how each of these specs satisfies the component model [[#Properties | properties]]:

{| cellpadding="10" cellspacing="0" style="border-collapse: collapse;"
|- valign="top" style="border-bottom: 1px solid LightGray;"
! align="left" width="12%" | Spec/Implementation
! align="left" width="12%" | [[#Extensibility | Extensibility]]
! align="left" width="12%" | [[#Consistency | Consistency]]
! align="left" width="12%" | [[#Encapsulation | Encapsulation]]
! align="left" width="12%" | [[#Composability | Composability]]
! align="left" width="12%" | [[#Desugaring | Desugaring]]
! align="left" width="12%" | [[#Performance | Performance]]
! align="left" width="12%" | [[#Confinement | Confinement]]
|- valign="top" style="border-bottom: 1px solid LightGray;"
! align="left" | HTML Components
| '''No'''. Components are magic, inextensible objects.
| '''Almost'''. Implementation provides ways to add properties, methods, events to element API, and the components are ''almost'' DOM elements. However, custom tags don't support all properties of a DOM element.
| '''Not much'''. There are some provisions for event encapsulation, nothing else.
| '''Not much'''. No provisions for handling document children vs. component-defined children.
| '''No'''.
| '''Not sure'''.
| '''No'''.
|- valign="top" style="border-bottom: 1px solid LightGray;"
! align="left" | XBL
| '''No'''. The mechanism for extending bindings is entirely independent of DOM type or Javascript extensibility.
| '''Yes-ish'''. Bindings can override properties on the DOM element, although the mechanism is highly unnatural (XML declarations).
| '''Yes'''? Hard to say looking at TR note.
| '''Yes'''
| '''Yes'''. Some HTML elements in Gecko are implemented using it.
| '''Not sure'''.
| '''No'''.
|- valign="top" style="border-bottom: 1px solid LightGray;"
! align="left" | XBL2
| '''No'''. Same as XBL.
| '''No'''. Bindings are discouraged from establishing an API surface on a bound element.
| '''Yes'''.
| '''Yes'''.
| '''No'''. The spec didn't intend to describe how native elements are built.
| '''Somewhat'''. The lifecycle of a binding is well-defined and initialization stages are well-decoupled. However, there is no way to build a binding imperatively without loading a binding document.
| '''No'''.
|}

The key differences between XBL2 and the Component Model are:
* The Component Model fully embraces the [[Behavior_Attachment#Behavior_Attachment_Methods | element behavior attachment]] by allowing creation of new types of DOM elements within a document. This is something Web Framework developers always wanted and repeatedly try to do with parallel object hierarchies. Eliminating ephemerality of the attachment simplifies and clarifies how things work conceptually -- there is no longer a place for "spooky action at a distance", caused by a change of a random CSS selector or even removing an element from the tree.
* The Component Model is strongly biased toward reusing existing bits of the platform and well-established techniques instead of inventing new ones. For instance, instead of bindings inheritance, we rely on prototype inheritance. Instead of endeavoring to solve the incredibly complex, yet dubious problem of multiple bindings or shadow DOM trees, we simply suggest composition.
* The Component Model strives to add capabilities in layers (see [[#Building_Blocks | building blocks]]), each able to function on its own. The omnibus nature of XBL2 removes opportunities for layering, particularly as element identity, life cycle, and scripting are concerned. Perhaps this could be repaired somehow, but Component Model solves these issues without further complicating an already large, difficult to understand spec.

[[Category:Proposals]]

Component Model

2011-10-26T20:09:07Z

Rolandsteiner: /* Introduction */ add link to decorators brainstorming page

Here's a good starting point for learning about the [https://github.com/dglazkov/component-model component model spec], which is being developed by applying a [[Component_Model_Methodology | defined methodology]].

=Introduction=

The '''Component Model''' introduces comprehensive support for creating DOM elements. [[Component_Model_Use_Cases | Examples]] include layout managers, combinations of Dojo and jQuery widgets, isolated widgets, such as Like/+1 buttons, and built-in HTML elements themselves. Reflecting on the experience of Mozilla's XBL and Microsoft Internet Explorer's HTML components, the Component Model formalizes the concept of loosely coupled, coherent units of [[Behavior Attachment | behavior]] in the [http://www.w3.org/wiki/Open_Web_Platform Web platform]. The functionality goals of the Component Model resemble the goals of [http://dev.w3.org/2006/xbl2/ XBL2]; unlike XBL2, the Component Model seeks to be more incremental and modular while leveraging and integrating with new technologies.

Strawman pages:

* [http://wiki.whatwg.org/wiki/Component_Model_Strawman:_Decorators Decorators]
* [http://wiki.whatwg.org/wiki/Component_Model_Strawman:_Element_Registration Element Registration]
* [http://wiki.whatwg.org/wiki/Component_Model_Strawman:_Declarative_Syntax Declarative Syntax]
* [http://wiki.whatwg.org/wiki/Component_Model_Strawman:_Styling Styling]
* [http://wiki.whatwg.org/wiki/Component_Model_Strawman:_Isolation Isolation]

Related links:

* [[Behavior_Attachment | Behavior Attachment]] -- a general overview of the behavior attachment problem
* [[Component_Model_Methodology | Component Model Methodology]]
* [[Component_Model_Use_Cases | Component Model Use Cases]]
* [[Component_Model_Declarative_Syntax | Component Model Declarative Syntax]]
* [https://github.com/dglazkov/component-model Component Model Spec on Github]
* [http://dglazkov.github.com/component-model/ Component Model Spec Snapshot on Github Pages]
* [[Component_Model_Progressive_Enhancement | Component Model Progressive Enhancement]]
* [[Custom_Tags_Analysis | Custom Tags Analysis]]

Discussion pages:

* [http://wiki.whatwg.org/wiki/Component_Model_Discussion Main discussion page with open questions]
* [http://wiki.whatwg.org/wiki/Component_Model_Discussion:_Rendering Rendering-specific discussion]
* [http://wiki.whatwg.org/wiki/Component_Model_CSS_Brainstorming brainstorming page about CSS and styling]
* [http://wiki.whatwg.org/wiki/Component_Model_Isolation_Brainstorming brainstorming page about isolation and confinement]
* [http://wiki.whatwg.org/wiki/Component_Model_Decorator_Brainstorming brainstorming page on decorators]
* [http://wiki.whatwg.org/wiki/Component_Model_IDL_Brainstorming brainstorming page about IDLs and communication across boundaries]

=Properties=

The component model aims to satisfy several key properties. These properties were extracted from the [[Component_Model_Use_Cases | 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:
<code>
<pre>
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>";
</pre>
</code>

The resulting <code>panel</code> 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 | Constructable DOM Types]]
* [[#Registering_Elements | Registering Elements]]

==Consistency==

Because components are just DOM objects, they inherently share the same traversal and manipulation APIs, as defined by the [http://dvcs.w3.org/hg/domcore/raw-file/tip/Overview.html DOM4]. The authors of components can extend these APIs by adding custom methods and properties on DOM objects, using standard JavaScript inheritance:
<code>
<pre>
Widget.prototype = Object.create(HTMLElement.prototype, {
update: {
value: function() { /* ... */ }
},
value: {
get: function() { /* ... */ },
set: function() { /* ... */ }
},
// ...
});
</pre>
</code>
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 | 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 [http://glazkov.com/2011/01/14/what-the-heck-is-shadow-dom/ shadow DOM]. The boundary between the document DOM tree and shadow DOM tree provides complete encapsulation, and ensures that:
* no shadow DOM tree nodes cross this boundary during event dispatch;
* document DOM tree has no access to nodes in the shadow DOM tree.

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 <code>ShadowRoot</code> 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:

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

Required Building Blocks:
* [[#Shadow_DOM | Shadow DOM]]

==Composability==

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

There can be more than one <code>content</code> element in the shadow tree. The <code>includes</code> attribute provides a convenient way to sort element's children by CSS selector. For example, a <code>DockLayoutPanel</code> component could be used like this in the document DOM tree:
<code>
<pre>
<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>
</pre>
</code>
Provided that its shadow DOM tree looks like this:
<code>
<pre>
<#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>
</pre>
</code>
The document DOM tree children on of <code>x-dock-layout-panel</code> will be rendered as if composed from this tree:
<code>
<pre>
<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>
</pre>
</code>

Required Building Blocks:
* [[#Content_Element | 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 [http://dev.w3.org/csswg/css3-lists/ lists]) are just components that have shadow DOM. Coincidentally, this also explains why you can't add shadow DOM subtrees to <code>input</code> or <code>details</code> elements -- their <code>ShadowRoot</code>s are claimed by <code>HTMLInputElement</code> and <code>HTMLDetailsElement</code> constructors, respectively.

Required Building Blocks:
* [[#Shadow_DOM | Shadow DOM]]
* [[#Content_Element | 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:

<code>
<pre>
// 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);
</pre>
</code>

In this situation, there is no room for error: <code>view.js</code> ''must'' wait for <code>layout.js</code> to load before executing. You can't load <code>layout.js</code> lazily or in any different order, since it defines the components that are used in <code>view.js</code>. 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 an unknown DOM element with an "x-"-prefixed <code>tagName</code> is encountered, we put a placeholder <code>HTMLUnknownElement</code> instance in its place. As soon as the element is defined, all placeholder instances are replaced ([http://www.w3.org/TR/DOM-Level-3-Core/core.html#Document3-renameNode Document.renameNode]) with the new, proper DOM element.

Required Building Blocks:
* [[#Registering_Elements | Registering Elements]]

== Confinement ==
Confinement refers to the document protecting its implementation details and state from the component and can be viewed as the inverse of [[#Encapsulation | encapsulation]].

Required Building Blocks:
* [[#Confinement_Primitives | Confinement Primitives]]

=Building Blocks=

The component model is comprised of the following building blocks.

==Shadow DOM==

Any DOM element can host a shadow DOM subtree. The shadow DOM subtree originates at <code>ShadowRoot</code>, which is coupled the hosting element at the time of its construction. You don't need any other building blocks in order to take advantage of the shadow DOM:
<code>
<pre>
var element = document.createElement("div");
var shadow = new ShadowRoot(element);
shadow.appendChild(document.createElement("p")).textContent = "weee!!';
</pre>
</code>

A <code>ShadowRoot</code> instance is a [http://dvcs.w3.org/hg/domcore/raw-file/tip/Overview.html#interface-node Node], and acts as the root of the element's shadow DOM subtree. The <code>ShadowRoot</code> itself is never rendered, nor has styles. In this regard, it's similar to the [http://dvcs.w3.org/hg/domcore/raw-file/tip/Overview.html#interface-documentfragment DocumentFragment]. It has two properties:
* <code>applyAuthorSheets</code>, which is either '''true''' (that is, apply author style sheets from the document), or '''false''' (don't);
* <code>shadowHost</code>, which points to the hosting element.

==Content Element==

The <code>content</code> element is used with [[#Shadow_DOM | Shadow DOM]] and provides a mechanism for distributing hosting element's children inside of its shadow subtree. To preserve the [[#Encapsulation | encapsulation]] property, the <code>content</code> elements act as insertion points and do not leak any information about hosting element's children to the shadow DOM subtree or vise versa.

==Constructable DOM Types==
The inability to construct DOM element using <code>new</code> (with some exceptions) or use them in the prototype inheritance chain had confounded many Web developers since the beginning of DOM. This building block intends to rectify at least the latter by allowing <code>HTMLElement.call</code> invocation and thus enabling creation of JavaScript objects with DOM elements in the prototype chain.

==Registering Elements==
Working in conjunction with [[#Constructable_DOM_Types | Constructable DOM Types]], this building block makes the list of valid markup tag names extensible by exposing <code>Element.register</code>:
<code>
<pre>
partial interface Element {
static void register(in String tagName, in Function constructor);
}
</pre>
</code>

It is possible to envisage a milder (though less elegant) version of element registration by keeping DOM element construction magical (thus decoupling it from [[#Constructable_DOM_Types | Constructable DOM Types]]) and making <code>Element.register</code> use a callback, rather than <code>constructor</code> as parameter. The callback would be invoked with an already-constructed DOM object with the specified <code>tagName</code>, leaving the work of setting up properties on this object to the callback.

==Confinement Primitives==

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 <code>window.postMessage</code>.

* 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 <code>Element.register</code> and <code>new ShadowRoot</code> 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 <code>confined</code> attribute to the <code>script</code> element. Presence of this attribute triggers loading scripts in the confined context.

Confinement of script execution could be useful outside of the component model and also could be related to [https://dvcs.w3.org/hg/content-security-policy/raw-file/tip/csp-specification.dev.html Content Security Policy].

* [[Component_Model_Isolation_Brainstorming | Isolation Brainstorm]]

=Building Blocks Use Case Coverage=

Here's a list of building blocks, tabulated against the [[Component_Model_Use_Cases | use cases]] and approximate percentage of satisfying them:

{| cellpadding="10" cellspacing="0" style="border-collapse: collapse;"
|- valign="top" style="border-bottom: 1px solid LightGray;"
! align="left" | Building Block
! align="left" | [[Component_Model_Use_Cases#Layout_Manager | Layout Manager]]
! align="left" | [[Component_Model_Use_Cases#Widget_Mix-and-Match | Mix-and-Match]]
! align="left" | [[Component_Model_Use_Cases#Rendering_Form_Controls_with_SVG | SVG Controls]]
! align="left" | [[Component_Model_Use_Cases#Contacts_Widget | Contacts Widget]]
! align="left" | [[Component_Model_Use_Cases#Like.2F.2B1_Button | Like/+1 Button]]
! align="left" | [[Component_Model_Use_Cases#Media_Controls_For_The_Video_Element | Media Controls for the Video Element]]
! align="left" | [[Component_Model_Use_Cases#Details.2FSummary_Elements | Details/Summary Element]]
|- valign="top" style="border-bottom: 1px solid LightGray;"
| [[Component_Model#Shadow_DOM | Shadow DOM]]
| 25%
| -
| 34%
| 100%
| 25%
| 100%
| 50%
|- valign="top" style="border-bottom: 1px solid LightGray;"
| [[Component_Model#Content_Element | Content Element]]
| 25%
| -
| -
| -
| -
| -
| 50%
|- valign="top" style="border-bottom: 1px solid LightGray;"
| [[Component_Model#Constructable_DOM_Types | Constructable DOM Types]]
| 25%
| 50%
| 33%
| -
| 25%
| -
| -
|- valign="top" style="border-bottom: 1px solid LightGray;"
| [[Component_Model#Registering_Elements | Registering Elements]]
| 25%
| 50%
| 33%
| -
| 25%
| -
| -
|- valign="top" style="border-bottom: 1px solid LightGray;"
| [[Component_Model#Confinement_Primitives | Confinement Primitives]]
| -
| -
| -
| -
| 25%
| -
| -
|}

=Comparison With Existing Specs and Implementations=

Here's a brief overview of existing similar specifications and implementations:
* [http://msdn.microsoft.com/en-us/library/ms531018(v=vs.85).aspx HTML Components] is a [http://windows.microsoft.com/en-US/internet-explorer/products/ie/home Microsoft Internet Explorer]-specific method of creating custom DOM elements. Also see [http://www.w3.org/TR/NOTE-HTMLComponents HTML Components Note] (implemented in IE5+).
* [http://www.w3.org/TR/2001/NOTE-xbl-20010223/ XBL], currently implemented in Mozilla.
* [http://dev.w3.org/2006/xbl2/ XBL2], the ancestral spec of the Component Model, and a revision of XBL.

Here's a handy overview of how each of these specs satisfies the component model [[#Properties | properties]]:

{| cellpadding="10" cellspacing="0" style="border-collapse: collapse;"
|- valign="top" style="border-bottom: 1px solid LightGray;"
! align="left" width="12%" | Spec/Implementation
! align="left" width="12%" | [[#Extensibility | Extensibility]]
! align="left" width="12%" | [[#Consistency | Consistency]]
! align="left" width="12%" | [[#Encapsulation | Encapsulation]]
! align="left" width="12%" | [[#Composability | Composability]]
! align="left" width="12%" | [[#Desugaring | Desugaring]]
! align="left" width="12%" | [[#Performance | Performance]]
! align="left" width="12%" | [[#Confinement | Confinement]]
|- valign="top" style="border-bottom: 1px solid LightGray;"
! align="left" | HTML Components
| '''No'''. Components are magic, inextensible objects.
| '''Almost'''. Implementation provides ways to add properties, methods, events to element API, and the components are ''almost'' DOM elements. However, custom tags don't support all properties of a DOM element.
| '''Not much'''. There are some provisions for event encapsulation, nothing else.
| '''Not much'''. No provisions for handling document children vs. component-defined children.
| '''No'''.
| '''Not sure'''.
| '''No'''.
|- valign="top" style="border-bottom: 1px solid LightGray;"
! align="left" | XBL
| '''No'''. The mechanism for extending bindings is entirely independent of DOM type or Javascript extensibility.
| '''Yes-ish'''. Bindings can override properties on the DOM element, although the mechanism is highly unnatural (XML declarations).
| '''Yes'''? Hard to say looking at TR note.
| '''Yes'''
| '''Yes'''. Some HTML elements in Gecko are implemented using it.
| '''Not sure'''.
| '''No'''.
|- valign="top" style="border-bottom: 1px solid LightGray;"
! align="left" | XBL2
| '''No'''. Same as XBL.
| '''No'''. Bindings are discouraged from establishing an API surface on a bound element.
| '''Yes'''.
| '''Yes'''.
| '''No'''. The spec didn't intend to describe how native elements are built.
| '''Somewhat'''. The lifecycle of a binding is well-defined and initialization stages are well-decoupled. However, there is no way to build a binding imperatively without loading a binding document.
| '''No'''.
|}

The key differences between XBL2 and the Component Model are:
* The Component Model fully embraces the [[Behavior_Attachment#Behavior_Attachment_Methods | element behavior attachment]] by allowing creation of new types of DOM elements within a document. This is something Web Framework developers always wanted and repeatedly try to do with parallel object hierarchies. Eliminating ephemerality of the attachment simplifies and clarifies how things work conceptually -- there is no longer a place for "spooky action at a distance", caused by a change of a random CSS selector or even removing an element from the tree.
* The Component Model is strongly biased toward reusing existing bits of the platform and well-established techniques instead of inventing new ones. For instance, instead of bindings inheritance, we rely on prototype inheritance. Instead of endeavoring to solve the incredibly complex, yet dubious problem of multiple bindings or shadow DOM trees, we simply suggest composition.
* The Component Model strives to add capabilities in layers (see [[#Building_Blocks | building blocks]]), each able to function on its own. The omnibus nature of XBL2 removes opportunities for layering, particularly as element identity, life cycle, and scripting are concerned. Perhaps this could be repaired somehow, but Component Model solves these issues without further complicating an already large, difficult to understand spec.

[[Category:Proposals]]

Component Model Strawman: Decorators

2011-10-26T20:08:31Z

Rolandsteiner: re-stub decorators strawman page after moving discussion to brainstorming page

Stub

Component Model Strawman: Decorators

2011-10-26T20:07:51Z

Rolandsteiner: moved Component Model Strawman: Decorators to Component Model Decorator Brainstorming: Mostly brainstorming ATM, no concrete proposals yet

#REDIRECT [[Component Model Decorator Brainstorming]]

Component Model Decorator Brainstorming

2011-10-26T20:07:51Z

Rolandsteiner: moved Component Model Strawman: Decorators to Component Model Decorator Brainstorming: Mostly brainstorming ATM, no concrete proposals yet

= Overview =

== Considerations ==

=== Dynamic ===

A decorator can be applied and removed dynamically, as opposed to a component, which is applied statically and cannot change. Furthermore, an element can have 0-n decorators, but just 0-1 components.

=== Interface ===

A decorator cannot add additional interfaces to the decorated element.

=== Confinement ===

A decorator may come from an untrusted source. In case the decorated element is a component, that component may come from an untrusted source as well, which may be different than the decorator's.

Therefore, an approach that merges a decorator with a component's shadow tree, e.g., via <tt><inherited></tt> is undesirable. Similarly, collecting decorator's under a component's <tt>ShadowRoot</tt> does not work.

=== Priority Inversion ===

An XBL-style <tt><inherited></tt> places the decorator(s) on top of the main component, making the decorator the root of the tree. This inverts the priority that should exist between a decorator and the main component. Indeed, a decorator might omit the <tt><inherited></tt> element, hiding the component (and other decorators) entirely.

Decorators therefore should be rendered "around" the element or component. Cases where a tighter coupling is required are probably better handled by composition.

=== Decorating Component Parts ===

In some cases it may be desirable to have the ability to decorate specific parts of a component. E.g., the caps-lock indicator in an <tt><input></tt> field could be considered a decorator.

However, this clashes with the desire to not make the internals of components public. To reconcile this we'd need a better model of how to declare component parts, whether "aspect-oriented components" or something different.

== Triggers ==

We consider the following triggers for the application of decorators:

* element tag names
* attributes
* ARIA roles
* general CSS

If we can achieve decorator-assignment via generic CSS rules, this can handle all cases above.

== Questions ==

=== Recursiveness ===

Can a decorator be decorated itself?

=== Styling ===

Can a decorator affect the styling of the decorated element?

=== Layout ===

Can a decorator affect the layout of the decorated element and/or surrounding elements? For example, consider an element that is given a specific height and width:

* If the purpose of the dimensions is to fit, e.g., an image, then changing those dimensions to fit the decorator seems ill-advised
* If the purpose of the dimensions is for precise layouting, then shifting surrounding elements to fit the decorator seems ill-advised

(However, given that which decorators to consider is in the hands of the page author the above are only minor considerations.)

=== Multiple Decorators ===

It seems useful and straight-forward to allow multiple decorators on a single element. However, assigning decorators, e.g., via a CSS <tt>binding</tt> property and using the CSS cascade would leave only the decorator stemming from the most specific rule.

= Binding Approaches =

== CSS ==

=== XBL Approach ===

XBL uses a CSS attribute <tt>binding</tt> to assign bindings to elements, as well as allowing elements to add bindings explicitly via <tt>element.addBinding()</tt>. While XBL specifies implicit bindings, as would be used by decorators, the natural vehicle to apply decorators - CSS - only seems to allow one (?).

=== CSS Decorator Properties ===

Allow decorators to specify a CSS <tt>decorator-<xyz></tt> property with the values <tt>none</tt> and <tt>apply</tt>. Rules can then switch individual decorators on or off.

==== Advantages ====

* allows decorators to be switched on or off based on rules

==== Disadvantages ====

* requires probably controversial CSS extension
* does not define where decorator is rendered
* does not allow classification which decorators are applicable to which elements

=== CSS Decorator Pseudo-elements ===

Allow decorators to specify a CSS pseudo-element or - probably better - an ID that can be accessed via a pseudo-element function <tt>::decorator()</tt>.

==== Advantages ====

* potentially easier to get acceptance for <tt>::decorator()</tt> than for decorator properties.
* pseudo-element kinda makes sense, since the decorator can be considered becoming part of the decorated element
* allows further styling of the decorator
* classification what decorators can be applied to which elements in the realm of the possible (make 'illegal' decorators fail in the CSS selector matching).

==== Disadvantages ====

* what are the properties for the pseudo-element?
* how to turn off a set pseudo-element again?

= Implementation Approaches =

== Pure CSS ==

In this approach, the decorator is defined purely in CSS. To this end we'd need to extend the layout capabilities of CSS to allow the creation and arrangement of arbitrary render boxes.

=== Advantages ===

* Does not create inter-dependence between DOM and CSS applying decorators - everything is handled by CSS.
* Trivially allows for the application of decorators via generic CSS rules.
* Extending the layout capabilities of CSS can be useful - and has been asked for - in general.

=== Disadvantages ===

* Expressiveness seems limited.
* Open questions regarding interactivity, how to bind event listeners, etc.
* Long standardization to get there.

== Component-like Shadow DOM ==

The decorators are declared similar to components and have their own DOM tree. A component is rendered in the specified position separately from the main DOM.

=== Advantages ===

* Greater expressiveness
* Uses tools we already have or develop for components.

=== Disadvantages ===

* Creates a inter-dependency between DOM and the triggers (e.g., CSS). Potential recursiveness.
* "Heavier" in application.

Component Model Decorator Brainstorming

2011-10-26T20:06:33Z

Rolandsteiner: /* Advantages */

= Overview =

== Considerations ==

=== Dynamic ===

A decorator can be applied and removed dynamically, as opposed to a component, which is applied statically and cannot change. Furthermore, an element can have 0-n decorators, but just 0-1 components.

=== Interface ===

A decorator cannot add additional interfaces to the decorated element.

=== Confinement ===

A decorator may come from an untrusted source. In case the decorated element is a component, that component may come from an untrusted source as well, which may be different than the decorator's.

Therefore, an approach that merges a decorator with a component's shadow tree, e.g., via <tt><inherited></tt> is undesirable. Similarly, collecting decorator's under a component's <tt>ShadowRoot</tt> does not work.

=== Priority Inversion ===

An XBL-style <tt><inherited></tt> places the decorator(s) on top of the main component, making the decorator the root of the tree. This inverts the priority that should exist between a decorator and the main component. Indeed, a decorator might omit the <tt><inherited></tt> element, hiding the component (and other decorators) entirely.

Decorators therefore should be rendered "around" the element or component. Cases where a tighter coupling is required are probably better handled by composition.

=== Decorating Component Parts ===

In some cases it may be desirable to have the ability to decorate specific parts of a component. E.g., the caps-lock indicator in an <tt><input></tt> field could be considered a decorator.

However, this clashes with the desire to not make the internals of components public. To reconcile this we'd need a better model of how to declare component parts, whether "aspect-oriented components" or something different.

== Triggers ==

We consider the following triggers for the application of decorators:

* element tag names
* attributes
* ARIA roles
* general CSS

If we can achieve decorator-assignment via generic CSS rules, this can handle all cases above.

== Questions ==

=== Recursiveness ===

Can a decorator be decorated itself?

=== Styling ===

Can a decorator affect the styling of the decorated element?

=== Layout ===

Can a decorator affect the layout of the decorated element and/or surrounding elements? For example, consider an element that is given a specific height and width:

* If the purpose of the dimensions is to fit, e.g., an image, then changing those dimensions to fit the decorator seems ill-advised
* If the purpose of the dimensions is for precise layouting, then shifting surrounding elements to fit the decorator seems ill-advised

(However, given that which decorators to consider is in the hands of the page author the above are only minor considerations.)

=== Multiple Decorators ===

It seems useful and straight-forward to allow multiple decorators on a single element. However, assigning decorators, e.g., via a CSS <tt>binding</tt> property and using the CSS cascade would leave only the decorator stemming from the most specific rule.

= Binding Approaches =

== CSS ==

=== XBL Approach ===

XBL uses a CSS attribute <tt>binding</tt> to assign bindings to elements, as well as allowing elements to add bindings explicitly via <tt>element.addBinding()</tt>. While XBL specifies implicit bindings, as would be used by decorators, the natural vehicle to apply decorators - CSS - only seems to allow one (?).

=== CSS Decorator Properties ===

Allow decorators to specify a CSS <tt>decorator-<xyz></tt> property with the values <tt>none</tt> and <tt>apply</tt>. Rules can then switch individual decorators on or off.

==== Advantages ====

* allows decorators to be switched on or off based on rules

==== Disadvantages ====

* requires probably controversial CSS extension
* does not define where decorator is rendered
* does not allow classification which decorators are applicable to which elements

=== CSS Decorator Pseudo-elements ===

Allow decorators to specify a CSS pseudo-element or - probably better - an ID that can be accessed via a pseudo-element function <tt>::decorator()</tt>.

==== Advantages ====

* potentially easier to get acceptance for <tt>::decorator()</tt> than for decorator properties.
* pseudo-element kinda makes sense, since the decorator can be considered becoming part of the decorated element
* allows further styling of the decorator
* classification what decorators can be applied to which elements in the realm of the possible (make 'illegal' decorators fail in the CSS selector matching).

==== Disadvantages ====

* what are the properties for the pseudo-element?
* how to turn off a set pseudo-element again?

= Implementation Approaches =

== Pure CSS ==

In this approach, the decorator is defined purely in CSS. To this end we'd need to extend the layout capabilities of CSS to allow the creation and arrangement of arbitrary render boxes.

=== Advantages ===

* Does not create inter-dependence between DOM and CSS applying decorators - everything is handled by CSS.
* Trivially allows for the application of decorators via generic CSS rules.
* Extending the layout capabilities of CSS can be useful - and has been asked for - in general.

=== Disadvantages ===

* Expressiveness seems limited.
* Open questions regarding interactivity, how to bind event listeners, etc.
* Long standardization to get there.

== Component-like Shadow DOM ==

The decorators are declared similar to components and have their own DOM tree. A component is rendered in the specified position separately from the main DOM.

=== Advantages ===

* Greater expressiveness
* Uses tools we already have or develop for components.

=== Disadvantages ===

* Creates a inter-dependency between DOM and the triggers (e.g., CSS). Potential recursiveness.
* "Heavier" in application.

Component Model Decorator Brainstorming

2011-10-26T20:04:51Z

Rolandsteiner: /* CSS Decorator Properties */

= Overview =

== Considerations ==

=== Dynamic ===

A decorator can be applied and removed dynamically, as opposed to a component, which is applied statically and cannot change. Furthermore, an element can have 0-n decorators, but just 0-1 components.

=== Interface ===

A decorator cannot add additional interfaces to the decorated element.

=== Confinement ===

A decorator may come from an untrusted source. In case the decorated element is a component, that component may come from an untrusted source as well, which may be different than the decorator's.

Therefore, an approach that merges a decorator with a component's shadow tree, e.g., via <tt><inherited></tt> is undesirable. Similarly, collecting decorator's under a component's <tt>ShadowRoot</tt> does not work.

=== Priority Inversion ===

An XBL-style <tt><inherited></tt> places the decorator(s) on top of the main component, making the decorator the root of the tree. This inverts the priority that should exist between a decorator and the main component. Indeed, a decorator might omit the <tt><inherited></tt> element, hiding the component (and other decorators) entirely.

Decorators therefore should be rendered "around" the element or component. Cases where a tighter coupling is required are probably better handled by composition.

=== Decorating Component Parts ===

In some cases it may be desirable to have the ability to decorate specific parts of a component. E.g., the caps-lock indicator in an <tt><input></tt> field could be considered a decorator.

However, this clashes with the desire to not make the internals of components public. To reconcile this we'd need a better model of how to declare component parts, whether "aspect-oriented components" or something different.

== Triggers ==

We consider the following triggers for the application of decorators:

* element tag names
* attributes
* ARIA roles
* general CSS

If we can achieve decorator-assignment via generic CSS rules, this can handle all cases above.

== Questions ==

=== Recursiveness ===

Can a decorator be decorated itself?

=== Styling ===

Can a decorator affect the styling of the decorated element?

=== Layout ===

Can a decorator affect the layout of the decorated element and/or surrounding elements? For example, consider an element that is given a specific height and width:

* If the purpose of the dimensions is to fit, e.g., an image, then changing those dimensions to fit the decorator seems ill-advised
* If the purpose of the dimensions is for precise layouting, then shifting surrounding elements to fit the decorator seems ill-advised

(However, given that which decorators to consider is in the hands of the page author the above are only minor considerations.)

=== Multiple Decorators ===

It seems useful and straight-forward to allow multiple decorators on a single element. However, assigning decorators, e.g., via a CSS <tt>binding</tt> property and using the CSS cascade would leave only the decorator stemming from the most specific rule.

= Binding Approaches =

== CSS ==

=== XBL Approach ===

XBL uses a CSS attribute <tt>binding</tt> to assign bindings to elements, as well as allowing elements to add bindings explicitly via <tt>element.addBinding()</tt>. While XBL specifies implicit bindings, as would be used by decorators, the natural vehicle to apply decorators - CSS - only seems to allow one (?).

=== CSS Decorator Properties ===

Allow decorators to specify a CSS <tt>decorator-<xyz></tt> property with the values <tt>none</tt> and <tt>apply</tt>. Rules can then switch individual decorators on or off.

==== Advantages ====

* allows decorators to be switched on or off based on rules

==== Disadvantages ====

* requires probably controversial CSS extension
* does not define where decorator is rendered
* does not allow classification which decorators are applicable to which elements

=== CSS Decorator Pseudo-elements ===

Allow decorators to specify a CSS pseudo-element or - probably better - an ID that can be accessed via a pseudo-element function <tt>::decorator()</tt>.

==== Advantages ====

* potentially easier to get acceptance for <tt>::decorator()</tt> than for decorator properties.
* pseudo-element kinda makes sense, since the decorator can be considered becoming part of the decorated element
* allows further styling of the decorator

==== Disadvantages ====

* what are the properties for the pseudo-element?
* how to turn off a set pseudo-element again?

= Implementation Approaches =

== Pure CSS ==

In this approach, the decorator is defined purely in CSS. To this end we'd need to extend the layout capabilities of CSS to allow the creation and arrangement of arbitrary render boxes.

=== Advantages ===

* Does not create inter-dependence between DOM and CSS applying decorators - everything is handled by CSS.
* Trivially allows for the application of decorators via generic CSS rules.
* Extending the layout capabilities of CSS can be useful - and has been asked for - in general.

=== Disadvantages ===

* Expressiveness seems limited.
* Open questions regarding interactivity, how to bind event listeners, etc.
* Long standardization to get there.

== Component-like Shadow DOM ==

The decorators are declared similar to components and have their own DOM tree. A component is rendered in the specified position separately from the main DOM.

=== Advantages ===

* Greater expressiveness
* Uses tools we already have or develop for components.

=== Disadvantages ===

* Creates a inter-dependency between DOM and the triggers (e.g., CSS). Potential recursiveness.
* "Heavier" in application.

Component Model Decorator Brainstorming

2011-10-26T20:04:00Z

Rolandsteiner: /* CSS Decorator Properties */

Component Model Decorator Brainstorming

2011-10-26T20:02:29Z

Rolandsteiner: Binding approaches

Component Model Decorator Brainstorming

2011-10-26T19:45:17Z

Rolandsteiner: /* Considerations */

Component Model

2011-10-26T19:41:32Z

Rolandsteiner: /* Introduction */ Move strawman pages to top of introduction

Here's a good starting point for learning about the [https://github.com/dglazkov/component-model component model spec], which is being developed by applying a [[Component_Model_Methodology | defined methodology]].

=Introduction=

The '''Component Model''' introduces comprehensive support for creating DOM elements. [[Component_Model_Use_Cases | Examples]] include layout managers, combinations of Dojo and jQuery widgets, isolated widgets, such as Like/+1 buttons, and built-in HTML elements themselves. Reflecting on the experience of Mozilla's XBL and Microsoft Internet Explorer's HTML components, the Component Model formalizes the concept of loosely coupled, coherent units of [[Behavior Attachment | behavior]] in the [http://www.w3.org/wiki/Open_Web_Platform Web platform]. The functionality goals of the Component Model resemble the goals of [http://dev.w3.org/2006/xbl2/ XBL2]; unlike XBL2, the Component Model seeks to be more incremental and modular while leveraging and integrating with new technologies.

Strawman pages:

* [http://wiki.whatwg.org/wiki/Component_Model_Strawman:_Decorators Decorators]
* [http://wiki.whatwg.org/wiki/Component_Model_Strawman:_Element_Registration Element Registration]
* [http://wiki.whatwg.org/wiki/Component_Model_Strawman:_Declarative_Syntax Declarative Syntax]
* [http://wiki.whatwg.org/wiki/Component_Model_Strawman:_Styling Styling]
* [http://wiki.whatwg.org/wiki/Component_Model_Strawman:_Isolation Isolation]

Related links:

* [[Behavior_Attachment | Behavior Attachment]] -- a general overview of the behavior attachment problem
* [[Component_Model_Methodology | Component Model Methodology]]
* [[Component_Model_Use_Cases | Component Model Use Cases]]
* [[Component_Model_Declarative_Syntax | Component Model Declarative Syntax]]
* [https://github.com/dglazkov/component-model Component Model Spec on Github]
* [http://dglazkov.github.com/component-model/ Component Model Spec Snapshot on Github Pages]
* [[Component_Model_Progressive_Enhancement | Component Model Progressive Enhancement]]
* [[Custom_Tags_Analysis | Custom Tags Analysis]]

Discussion pages:

* [http://wiki.whatwg.org/wiki/Component_Model_Discussion Main discussion page with open questions]
* [http://wiki.whatwg.org/wiki/Component_Model_Discussion:_Rendering Rendering-specific discussion]
* [http://wiki.whatwg.org/wiki/Component_Model_CSS_Brainstorming brainstorming page about CSS and styling]
* [http://wiki.whatwg.org/wiki/Component_Model_Isolation_Brainstorming brainstorming page about isolation and confinement]
* [http://wiki.whatwg.org/wiki/Component_Model_IDL_Brainstorming brainstorming page about IDLs and communication across boundaries]

=Properties=

The component model aims to satisfy several key properties. These properties were extracted from the [[Component_Model_Use_Cases | 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:
<code>
<pre>
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>";
</pre>
</code>

The resulting <code>panel</code> 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 | Constructable DOM Types]]
* [[#Registering_Elements | Registering Elements]]

==Consistency==

Because components are just DOM objects, they inherently share the same traversal and manipulation APIs, as defined by the [http://dvcs.w3.org/hg/domcore/raw-file/tip/Overview.html DOM4]. The authors of components can extend these APIs by adding custom methods and properties on DOM objects, using standard JavaScript inheritance:
<code>
<pre>
Widget.prototype = Object.create(HTMLElement.prototype, {
update: {
value: function() { /* ... */ }
},
value: {
get: function() { /* ... */ },
set: function() { /* ... */ }
},
// ...
});
</pre>
</code>
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 | 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 [http://glazkov.com/2011/01/14/what-the-heck-is-shadow-dom/ shadow DOM]. The boundary between the document DOM tree and shadow DOM tree provides complete encapsulation, and ensures that:
* no shadow DOM tree nodes cross this boundary during event dispatch;
* document DOM tree has no access to nodes in the shadow DOM tree.

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 <code>ShadowRoot</code> 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:

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

Required Building Blocks:
* [[#Shadow_DOM | Shadow DOM]]

==Composability==

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

There can be more than one <code>content</code> element in the shadow tree. The <code>includes</code> attribute provides a convenient way to sort element's children by CSS selector. For example, a <code>DockLayoutPanel</code> component could be used like this in the document DOM tree:
<code>
<pre>
<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>
</pre>
</code>
Provided that its shadow DOM tree looks like this:
<code>
<pre>
<#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>
</pre>
</code>
The document DOM tree children on of <code>x-dock-layout-panel</code> will be rendered as if composed from this tree:
<code>
<pre>
<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>
</pre>
</code>

Required Building Blocks:
* [[#Content_Element | 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 [http://dev.w3.org/csswg/css3-lists/ lists]) are just components that have shadow DOM. Coincidentally, this also explains why you can't add shadow DOM subtrees to <code>input</code> or <code>details</code> elements -- their <code>ShadowRoot</code>s are claimed by <code>HTMLInputElement</code> and <code>HTMLDetailsElement</code> constructors, respectively.

Required Building Blocks:
* [[#Shadow_DOM | Shadow DOM]]
* [[#Content_Element | 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:

<code>
<pre>
// 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);
</pre>
</code>

In this situation, there is no room for error: <code>view.js</code> ''must'' wait for <code>layout.js</code> to load before executing. You can't load <code>layout.js</code> lazily or in any different order, since it defines the components that are used in <code>view.js</code>. 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 an unknown DOM element with an "x-"-prefixed <code>tagName</code> is encountered, we put a placeholder <code>HTMLUnknownElement</code> instance in its place. As soon as the element is defined, all placeholder instances are replaced ([http://www.w3.org/TR/DOM-Level-3-Core/core.html#Document3-renameNode Document.renameNode]) with the new, proper DOM element.

Required Building Blocks:
* [[#Registering_Elements | Registering Elements]]

== Confinement ==
Confinement refers to the document protecting its implementation details and state from the component and can be viewed as the inverse of [[#Encapsulation | encapsulation]].

Required Building Blocks:
* [[#Confinement_Primitives | Confinement Primitives]]

=Building Blocks=

The component model is comprised of the following building blocks.

==Shadow DOM==

Any DOM element can host a shadow DOM subtree. The shadow DOM subtree originates at <code>ShadowRoot</code>, which is coupled the hosting element at the time of its construction. You don't need any other building blocks in order to take advantage of the shadow DOM:
<code>
<pre>
var element = document.createElement("div");
var shadow = new ShadowRoot(element);
shadow.appendChild(document.createElement("p")).textContent = "weee!!';
</pre>
</code>

A <code>ShadowRoot</code> instance is a [http://dvcs.w3.org/hg/domcore/raw-file/tip/Overview.html#interface-node Node], and acts as the root of the element's shadow DOM subtree. The <code>ShadowRoot</code> itself is never rendered, nor has styles. In this regard, it's similar to the [http://dvcs.w3.org/hg/domcore/raw-file/tip/Overview.html#interface-documentfragment DocumentFragment]. It has two properties:
* <code>applyAuthorSheets</code>, which is either '''true''' (that is, apply author style sheets from the document), or '''false''' (don't);
* <code>shadowHost</code>, which points to the hosting element.

==Content Element==

The <code>content</code> element is used with [[#Shadow_DOM | Shadow DOM]] and provides a mechanism for distributing hosting element's children inside of its shadow subtree. To preserve the [[#Encapsulation | encapsulation]] property, the <code>content</code> elements act as insertion points and do not leak any information about hosting element's children to the shadow DOM subtree or vise versa.

==Constructable DOM Types==
The inability to construct DOM element using <code>new</code> (with some exceptions) or use them in the prototype inheritance chain had confounded many Web developers since the beginning of DOM. This building block intends to rectify at least the latter by allowing <code>HTMLElement.call</code> invocation and thus enabling creation of JavaScript objects with DOM elements in the prototype chain.

==Registering Elements==
Working in conjunction with [[#Constructable_DOM_Types | Constructable DOM Types]], this building block makes the list of valid markup tag names extensible by exposing <code>Element.register</code>:
<code>
<pre>
partial interface Element {
static void register(in String tagName, in Function constructor);
}
</pre>
</code>

It is possible to envisage a milder (though less elegant) version of element registration by keeping DOM element construction magical (thus decoupling it from [[#Constructable_DOM_Types | Constructable DOM Types]]) and making <code>Element.register</code> use a callback, rather than <code>constructor</code> as parameter. The callback would be invoked with an already-constructed DOM object with the specified <code>tagName</code>, leaving the work of setting up properties on this object to the callback.

==Confinement Primitives==

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 <code>window.postMessage</code>.

* 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 <code>Element.register</code> and <code>new ShadowRoot</code> 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 <code>confined</code> attribute to the <code>script</code> element. Presence of this attribute triggers loading scripts in the confined context.

Confinement of script execution could be useful outside of the component model and also could be related to [https://dvcs.w3.org/hg/content-security-policy/raw-file/tip/csp-specification.dev.html Content Security Policy].

* [[Component_Model_Isolation_Brainstorming | Isolation Brainstorm]]

=Building Blocks Use Case Coverage=

Here's a list of building blocks, tabulated against the [[Component_Model_Use_Cases | use cases]] and approximate percentage of satisfying them:

{| cellpadding="10" cellspacing="0" style="border-collapse: collapse;"
|- valign="top" style="border-bottom: 1px solid LightGray;"
! align="left" | Building Block
! align="left" | [[Component_Model_Use_Cases#Layout_Manager | Layout Manager]]
! align="left" | [[Component_Model_Use_Cases#Widget_Mix-and-Match | Mix-and-Match]]
! align="left" | [[Component_Model_Use_Cases#Rendering_Form_Controls_with_SVG | SVG Controls]]
! align="left" | [[Component_Model_Use_Cases#Contacts_Widget | Contacts Widget]]
! align="left" | [[Component_Model_Use_Cases#Like.2F.2B1_Button | Like/+1 Button]]
! align="left" | [[Component_Model_Use_Cases#Media_Controls_For_The_Video_Element | Media Controls for the Video Element]]
! align="left" | [[Component_Model_Use_Cases#Details.2FSummary_Elements | Details/Summary Element]]
|- valign="top" style="border-bottom: 1px solid LightGray;"
| [[Component_Model#Shadow_DOM | Shadow DOM]]
| 25%
| -
| 34%
| 100%
| 25%
| 100%
| 50%
|- valign="top" style="border-bottom: 1px solid LightGray;"
| [[Component_Model#Content_Element | Content Element]]
| 25%
| -
| -
| -
| -
| -
| 50%
|- valign="top" style="border-bottom: 1px solid LightGray;"
| [[Component_Model#Constructable_DOM_Types | Constructable DOM Types]]
| 25%
| 50%
| 33%
| -
| 25%
| -
| -
|- valign="top" style="border-bottom: 1px solid LightGray;"
| [[Component_Model#Registering_Elements | Registering Elements]]
| 25%
| 50%
| 33%
| -
| 25%
| -
| -
|- valign="top" style="border-bottom: 1px solid LightGray;"
| [[Component_Model#Confinement_Primitives | Confinement Primitives]]
| -
| -
| -
| -
| 25%
| -
| -
|}

=Comparison With Existing Specs and Implementations=

Here's a brief overview of existing similar specifications and implementations:
* [http://msdn.microsoft.com/en-us/library/ms531018(v=vs.85).aspx HTML Components] is a [http://windows.microsoft.com/en-US/internet-explorer/products/ie/home Microsoft Internet Explorer]-specific method of creating custom DOM elements. Also see [http://www.w3.org/TR/NOTE-HTMLComponents HTML Components Note] (implemented in IE5+).
* [http://www.w3.org/TR/2001/NOTE-xbl-20010223/ XBL], currently implemented in Mozilla.
* [http://dev.w3.org/2006/xbl2/ XBL2], the ancestral spec of the Component Model, and a revision of XBL.

Here's a handy overview of how each of these specs satisfies the component model [[#Properties | properties]]:

{| cellpadding="10" cellspacing="0" style="border-collapse: collapse;"
|- valign="top" style="border-bottom: 1px solid LightGray;"
! align="left" width="12%" | Spec/Implementation
! align="left" width="12%" | [[#Extensibility | Extensibility]]
! align="left" width="12%" | [[#Consistency | Consistency]]
! align="left" width="12%" | [[#Encapsulation | Encapsulation]]
! align="left" width="12%" | [[#Composability | Composability]]
! align="left" width="12%" | [[#Desugaring | Desugaring]]
! align="left" width="12%" | [[#Performance | Performance]]
! align="left" width="12%" | [[#Confinement | Confinement]]
|- valign="top" style="border-bottom: 1px solid LightGray;"
! align="left" | HTML Components
| '''No'''. Components are magic, inextensible objects.
| '''Almost'''. Implementation provides ways to add properties, methods, events to element API, and the components are ''almost'' DOM elements. However, custom tags don't support all properties of a DOM element.
| '''Not much'''. There are some provisions for event encapsulation, nothing else.
| '''Not much'''. No provisions for handling document children vs. component-defined children.
| '''No'''.
| '''Not sure'''.
| '''No'''.
|- valign="top" style="border-bottom: 1px solid LightGray;"
! align="left" | XBL
| '''No'''. The mechanism for extending bindings is entirely independent of DOM type or Javascript extensibility.
| '''Yes-ish'''. Bindings can override properties on the DOM element, although the mechanism is highly unnatural (XML declarations).
| '''Yes'''? Hard to say looking at TR note.
| '''Yes'''
| '''Yes'''. Some HTML elements in Gecko are implemented using it.
| '''Not sure'''.
| '''No'''.
|- valign="top" style="border-bottom: 1px solid LightGray;"
! align="left" | XBL2
| '''No'''. Same as XBL.
| '''No'''. Bindings are discouraged from establishing an API surface on a bound element.
| '''Yes'''.
| '''Yes'''.
| '''No'''. The spec didn't intend to describe how native elements are built.
| '''Somewhat'''. The lifecycle of a binding is well-defined and initialization stages are well-decoupled. However, there is no way to build a binding imperatively without loading a binding document.
| '''No'''.
|}

The key differences between XBL2 and the Component Model are:
* The Component Model fully embraces the [[Behavior_Attachment#Behavior_Attachment_Methods | element behavior attachment]] by allowing creation of new types of DOM elements within a document. This is something Web Framework developers always wanted and repeatedly try to do with parallel object hierarchies. Eliminating ephemerality of the attachment simplifies and clarifies how things work conceptually -- there is no longer a place for "spooky action at a distance", caused by a change of a random CSS selector or even removing an element from the tree.
* The Component Model is strongly biased toward reusing existing bits of the platform and well-established techniques instead of inventing new ones. For instance, instead of bindings inheritance, we rely on prototype inheritance. Instead of endeavoring to solve the incredibly complex, yet dubious problem of multiple bindings or shadow DOM trees, we simply suggest composition.
* The Component Model strives to add capabilities in layers (see [[#Building_Blocks | building blocks]]), each able to function on its own. The omnibus nature of XBL2 removes opportunities for layering, particularly as element identity, life cycle, and scripting are concerned. Perhaps this could be repaired somehow, but Component Model solves these issues without further complicating an already large, difficult to understand spec.

[[Category:Proposals]]

Component Model IDL Brainstorming

2011-10-26T19:40:03Z

Rolandsteiner:

[[User:Rolandsteiner|RolandSteiner]] This may be obsoleted by the Proxy approach for isolation.

= Overview =

Components, along with other web constructs such as workers and <code><iframe></code> elements, may benefit from having their interfaces declared explicitly.
This would be especially useful in the case of confined components, who cannot be trusted to run scripts to effect subclassing and forwarding function calls between the hosting element and the shadow DOM.
The following is therefore a proposal for a declarative way to define the interface, that the browser then can safely inspect and use as a basis to set up such forwarding automatically.

= Perceived Advantages =

All of the following may look very verbose, and could probably be implemented much quicker in pure JavaScript. However, this approach still conceivably has the following advantages:

* Can be used where JavaScript cannot be run, e.g. due to confinement
** Browser can automatically use the definitions to set up and abstract away <code>postMessage()</code> calls, etc., that are necessary to bridge the separation
** Browser can even use magic to handle the forwarding and does not have to rely on <code>postMessage()</code> or other functions available in JavaScript
* Not component-specific, could be used for workers, <code><iframes></code>, intents
* Same definitions can be used cross-language (not limited to JavaScript)

Component Model IDL Brainstorming

2011-10-26T19:38:40Z

Rolandsteiner: Remove examples (too complicated, perhaps obsoleted by Proxy approach)

= Overview =

Components, along with other web constructs such as workers and <code><iframe></code> elements, may benefit from having their interfaces declared explicitly.
This would be especially useful in the case of confined components, who cannot be trusted to run scripts to effect subclassing and forwarding function calls between the hosting element and the shadow DOM.
The following is therefore a proposal for a declarative way to define the interface, that the browser then can safely inspect and use as a basis to set up such forwarding automatically.

= Perceived Advantages =

All of the following may look very verbose, and could probably be implemented much quicker in pure JavaScript. However, this approach still conceivably has the following advantages:

* Can be used where JavaScript cannot be run, e.g. due to confinement
** Browser can automatically use the definitions to set up and abstract away <code>postMessage()</code> calls, etc., that are necessary to bridge the separation
** Browser can even use magic to handle the forwarding and does not have to rely on <code>postMessage()</code> or other functions available in JavaScript
* Not component-specific, could be used for workers, <code><iframes></code>, intents
* Same definitions can be used cross-language (not limited to JavaScript)

Component Model Strawman: Isolation

2011-10-26T19:13:23Z

Rolandsteiner:

= Overview =

The isolated components definition is a <tt>provide</tt> attributed HTML file which is loaded in separate namespace.
It is basically a document loaded by an iframe. But it has different way for communicating with the host document.

See also the "Isolation" section on [[Component_Model_Strawman:_Declarative_Syntax]].

== Terms ==

* '''Confined''': disallow a component from accessing the containing page. Useful when a page does not trust the component or its source.
* '''Encapsulated''': disallow the containing page from accessing the internals of the component. Useful when a component wants to prevent a page from meddling with it.
* '''Isolated''': a component that is both confined and encapsulated.

== Considerations ==

To facilitate component isolation:

=== Autonomy ===

Components should be autonomous entities that can be loaded and applied as a single building block. Avoid requiring extensive manipulations on both side of the page <=> component divide.

This will also help in implementing decorators.

=== Interface ===

The interface of a component should be minimal and well defined. Embedding pages should not be required (nor able to in the case of encapsulation) to access, or even know about, the internals of a component. Conversely, the function of a component should not depend on being able to access the DOM or any other information of the hosting page that is not provided through an interface.

The component should be able to apply and filter data and styles passed in as it sees fit.

= Approaches =

== Element Registration ==

* XXX: define the element name resolution order.

Isolated providing document can register new elements for the host document.
But in slightly different way: the lifecycle callbacks including <tt>open</tt> and <tt>close</tt> use
<tt>HTMLElementProxy</tt> instead of <tt>HTMLElement</tt>, that means <tt>open</tt> should return
an instance of <tt>HTMLElementProxy</tt> and <tt>close</tt> callback receives it as a parameter.

<pre>

<head>
<element for="x-comment">
<script>
HTMLElementElement.current.open = function() {
var element = return new HTMLElementProxy();
element.addEventListener("message", ...);
return element;
}});
</script>
</element>
</head>

</pre>

== HTMLElementProxy ==

An element on the host document is represented as a <tt>HTMLElementProxy</tt> object in the isolated document.
If an isolated-registered element is built on the host document, a set of lifecycle callback is invoked on the isolated document.
The <tt>open</tt> callback should return an <tt>HTMLElementProxy</tt> object, which is then connected to
associated element on the host document.
Scripts in both document can communicate through the proxy using MessageEvent.

<pre>

interface [
Constructor()
] HTMLElementProxy : EventTarget {
void postMessage(any message, optional sequence<Transferable> transfer);
}

// Should be implemented by HTMLElement family.
interface [
Constructor(),
NoInterfaceObject
] HTMLElementHost {
void postMessage(any message, optional sequence<Transferable> transfer);
}

</pre>

== Isolated ShadowRoot ==

Shadow Trees for the host document can live in the isolated document.
The <tt>ShadowRoot</tt> constructor can accept <tt>HTMLElementProxy</tt> instead of <tt>HTMLElement</tt>.

<pre>

<head>
<element for="x-comment">
<script>
HTMLElementElement.current.open = function() {
var element = return new HTMLElementProxy();
var shadow = new ShadowRoot(element);
// Build the shadow tree here...
return element;
}});
</script>
</element>
</head>

</pre>

Isolated <tt>ShadowRoot</tt> objects don't propagate events across two documents.

Component Model Decorator Brainstorming

2011-10-26T19:11:43Z

Rolandsteiner: /* Questions */ Styling Q

Component Model Decorator Brainstorming

2011-10-26T17:46:50Z

Rolandsteiner: /* Questions */

Component Model Decorator Brainstorming

2011-10-26T17:38:55Z

Rolandsteiner: Approaches, Questions

Component Model Decorator Brainstorming

2011-10-26T17:17:50Z

Rolandsteiner: /* Overview */ Triggers

Component Model Decorator Brainstorming

2011-10-26T17:05:44Z

Rolandsteiner: Considerations

= Overview =

== Considerations ==

=== Interface ===

A decorator cannot add additional interfaces to the decorated element.

=== Confinement ===

A decorator may come from an untrusted source. In case the decorated element is a component, that component may come from an untrusted source as well, which may be different than the decorator's.

Therefore, an approach that merges a decorator with a component's shadow tree, e.g., via <tt><inherited></tt> is undesirable. Similarly, collecting decorator's under a component's <tt>ShadowRoot</tt> does not work.

=== Priority Inversion ===

An XBL-style <tt><inherited></tt> places the decorator(s) on top of the main component, making the decorator the root of the tree. This inverts the priority that should exist between a decorator and the main component. Indeed, a decorator might omit the <tt><inherited></tt> element, hiding the component (and other decorators) entirely.

Decorators therefore should be rendered "around" the element or component. Cases where a tighter coupling is required are probably better handled by composition.

Component Model Strawman: Styling

2011-10-25T20:37:42Z

Rolandsteiner:

= Overview =

There are 4 actors that may modify the style of (parts of) a component:

* the browser
* the component author
* the page author
* the user

Component Model Strawman: Isolation

2011-10-25T19:56:31Z

Rolandsteiner: Add considerations section

Component Model Strawman: Declarative Syntax

2011-10-25T19:42:48Z

Rolandsteiner: /* Isolated definition */

= Element Registration =

Let’s start from the minimum form of the element registration.
Authors can use an <tt>element</tt> element to registering new element name.
Now agent recognizes <tt>x-comment</tt> as <tt>HTMLRegisteredElement</tt>.
This is just a plain old HTML element which has its own name.

<pre>

<head>
<element for="x-comment"></element>
</head>

</pre>

== Scripting ==

The <tt>element</tt> element also provides an opportunity to give a behavior for the instance of the registered element.

<pre>

<head>
<element for="x-comment"></element>
<script>
var e = document.head.querySelector(“[for=x-comment]”);
e.close = function(element) {
element.addEventListener(“click”, function(evt) {
..
});
};
</script>
</head>

</pre>

Using <tt>HTMLElementElement.register()</tt>, authors can register a set of lifecycle callbacks for each registered element.
There are two types of lifecycle event: <tt>open</tt> and <tt>close</tt>. The open is for creating the new instance of the <tt>Element</tt>.
You can override the constructor of the element by providing <tt>open</tt> callback.
The <tt>close</tt> callback provides the way to enhance created instance.
This is useful when you use given attributes to define the behavior.

To make the definition self-contained, we can put a <tt>script</tt> blocks inside an <tt>element</tt> element.

<pre>

<head>
<element for="x-comment">
<script>
class Comment : HTMLElement {
this.shadow = new ShawowRoot(this);
..;
}

HTMLElementElement.current.open = function() { return new Comment(); }});
</script>
</element>
</head>

</pre>

In this example, the script refers a static property called <tt>HTMLElementElement.current</tt>,
which points the enclosing <tt>element</tt> element.
This example also shows how we can provide an <tt>open</tt> lifecycle callback.

== Styling ==

The <tt>element</tt> element allows a <tt>style</tt> element as a child,
which accept <tt>:current</tt> pseudo-class to specify the registering element.

Following example gives "color: gray" to the <tt>x-comment</tt> element.

<pre>

<head>
<element for="x-comment">
<style>
:current {
color: gray;
}
</style>
</element>
</head>

</pre>

[[User:Rolandsteiner|RolandSteiner]] IMHO it's simpler to just create a 'x-comment' style rule in some style sheet within the head. This way we don't need to add a :current pseudo-class. Also, there's no way we could limit the style rules within <tt>element</tt> to only affect that element anyway.

= Shadow DOM Template =

An initial shape of new shadow tree can be defined using a <tt>template</tt> element.

<pre>

<head>
<template id=”comment-template”>
<div><content></content></div>
</template>
</head>

</pre>

A <tt>template</tt> is instantiated through

* <tt>ShadowRoot</tt> constructor and
* <tt>shadow-template</tt> CSS property.

== The ShadowRoot constructor ==

The <tt>ShadowRoot</tt> constructor accepts a <tt>template</tt> element to instantiate.

<pre>
..
this.shadow = new ShadowRoot(this, document.getElementById(“comment-template”));
..
</pre>

== The shadow-template CSS property (brainstorming) ==

The template for shadow root also can be applied using CSS property.

<pre>

.comment {
shadow-template: url('#comment-template');
}

</pre>

Note that imperatively-applied shadows always supersede shadows from the styling.
Also, there is no way to access style-originated shadows from the scripting environment.

== The Instantiation Event and Scripting ==

Even though the <tt>template</tt> can be used to define an extra visual representation for an element,
It would be useful if author can attach a script for the template-generated shadow tree.

The <tt>template</tt> element generates an <tt>instantiation</tt> event for
each template instantiation. Authors can listen it to setup event handlers for
generated elements by the template. The event doesn't bubble, and it isn't cancelable.

<pre>

<head>
<template id=”comment-template”>
<div><content></content></div>
</template>
<script>
var e = document.getElementById("comment-template");
e.addEventListener("instantiation", function(evt) {
evt.root.querySelector("div").addEventListener("click", function(evt) { ... });
});
</script>
</head>

</pre>

A <tt>template</tt> element also allows a <tt>script</tt> element as a child,
whose script block can access <tt>HTMLTemplateElement.current</tt> to refer the enclosing <tt>template</tt> element.

<pre>

<head>
<template id=”comment-template”>
<div><content></content></div>
<script>
HTMLTemplateElement.current.addEventListener("instantiation", function(evt) {
evt.root.querySelector("div").addEventListener("click", function(evt) { ... });
});
</script>
</template>
</head>

</pre>

= Isolation =

== Standalone Form ==

The element registration and template definition are also done in a separate HTML.
Each HTML file which provides the element registration should have a <tt>provide</tt> attribute on the root html element.
This attribute prevents accidental loading of existing HTML files.

Effective markup vocabulary for the providing HTML is limited.
Agents only recognize a head element as a child of the root element when the HTML document is loaded as required.

<pre>

<html provide>
<head>
<element for="x-comment">..</element>
</head>
</html>

</pre>

The host element can load the html with element definition using a <tt>link</tt> element with its <tt>rel</tt> attribute set to <tt>component</tt>.

<pre>

<html>
<head>
<link rel=”component” type=”text/html” href="comment.html">
</head>
</html>

</pre>

The standalone definition can be done by a script file.

<pre>

<html>
<head>
<link rel=”component” type=”text/javascript” href="comment.js">
</head>
</html>

</pre>

This is equivalent to linking to a HTML file of like:

<pre>

<html provide>
<head>
<script type=”text/javascript” src="comment.js"></script>
</head>
</html>

</pre>

== Shared definition ==

In the default, these definitions are coming into the host document.
That means a providing HTML doesn’t have its own document nor the global object. Agents use these of the host document.

== Isolated definition ==

If the <tt>rel</tt> attribute contains the term <tt>isolate</tt>, the linked HTML is loaded as a separate document object.
The script inside the document is given a separate global object.

For the host document, there is no way to access the loaded document directly.

<pre>

<html>
<head>
<link rel=”component; isolate” type=”text/html” href="comment.html">
</head>
</html>

</pre>

[[User:Rolandsteiner|RolandSteiner]] Should we make <tt>isolate</tt> an attribute on <tt>link</tt> rather than a <tt>rel</tt> value? As Dimitri mentioned, this could be useful in general and would allow us to branch it off into a separate spec.

Component Model Strawman: Declarative Syntax

2011-10-25T18:08:12Z

Rolandsteiner: /* Styling */

Component Model

2011-10-24T21:59:14Z

Rolandsteiner: /* Introduction */ add links to strawman pages

Here's a good starting point for learning about the [https://github.com/dglazkov/component-model component model spec], which is being developed by applying a [[Component_Model_Methodology | defined methodology]].

=Introduction=

The '''Component Model''' introduces comprehensive support for creating DOM elements. [[Component_Model_Use_Cases | Examples]] include layout managers, combinations of Dojo and jQuery widgets, isolated widgets, such as Like/+1 buttons, and built-in HTML elements themselves. Reflecting on the experience of Mozilla's XBL and Microsoft Internet Explorer's HTML components, the Component Model formalizes the concept of loosely coupled, coherent units of [[Behavior Attachment | behavior]] in the [http://www.w3.org/wiki/Open_Web_Platform Web platform]. The functionality goals of the Component Model resemble the goals of [http://dev.w3.org/2006/xbl2/ XBL2]; unlike XBL2, the Component Model seeks to be more incremental and modular while leveraging and integrating with new technologies.

Related links:
* [[Behavior_Attachment | Behavior Attachment]] -- a general overview of the behavior attachment problem
* [[Component_Model_Methodology | Component Model Methodology]]
* [[Component_Model_Use_Cases | Component Model Use Cases]]
* [[Component_Model_Declarative_Syntax | Component Model Declarative Syntax]]
* [https://github.com/dglazkov/component-model Component Model Spec on Github]
* [http://dglazkov.github.com/component-model/ Component Model Spec Snapshot on Github Pages]
* [[Component_Model_Progressive_Enhancement | Component Model Progressive Enhancement]]
* [[Custom_Tags_Analysis | Custom Tags Analysis]]

Discussion pages:

* [http://wiki.whatwg.org/wiki/Component_Model_Discussion Main discussion page with open questions]
* [http://wiki.whatwg.org/wiki/Component_Model_Discussion:_Rendering Rendering-specific discussion]
* [http://wiki.whatwg.org/wiki/Component_Model_CSS_Brainstorming brainstorming page about CSS and styling]
* [http://wiki.whatwg.org/wiki/Component_Model_Isolation_Brainstorming brainstorming page about isolation and confinement]
* [http://wiki.whatwg.org/wiki/Component_Model_IDL_Brainstorming brainstorming page about IDLs and communication across boundaries]

Strawman pages:

* [http://wiki.whatwg.org/wiki/Component_Model_Strawman:_Decorators Decorators]
* [http://wiki.whatwg.org/wiki/Component_Model_Strawman:_Declarative_Syntax Declarative Syntax]
* [http://wiki.whatwg.org/wiki/Component_Model_Strawman:_Styling Styling]
* [http://wiki.whatwg.org/wiki/Component_Model_Strawman:_Isolation Isolation]

=Properties=

The component model aims to satisfy several key properties. These properties were extracted from the [[Component_Model_Use_Cases | 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:
<code>
<pre>
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>";
</pre>
</code>

The resulting <code>panel</code> 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 | Constructable DOM Types]]
* [[#Registering_Elements | Registering Elements]]

==Consistency==

Because components are just DOM objects, they inherently share the same traversal and manipulation APIs, as defined by the [http://dvcs.w3.org/hg/domcore/raw-file/tip/Overview.html DOM4]. The authors of components can extend these APIs by adding custom methods and properties on DOM objects, using standard JavaScript inheritance:
<code>
<pre>
Widget.prototype = Object.create(HTMLElement.prototype, {
update: {
value: function() { /* ... */ }
},
value: {
get: function() { /* ... */ },
set: function() { /* ... */ }
},
// ...
});
</pre>
</code>
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 | 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 [http://glazkov.com/2011/01/14/what-the-heck-is-shadow-dom/ shadow DOM]. The boundary between the document DOM tree and shadow DOM tree provides complete encapsulation, and ensures that:
* no shadow DOM tree nodes cross this boundary during event dispatch;
* document DOM tree has no access to nodes in the shadow DOM tree.

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 <code>ShadowRoot</code> 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:

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

Required Building Blocks:
* [[#Shadow_DOM | Shadow DOM]]

==Composability==

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

There can be more than one <code>content</code> element in the shadow tree. The <code>includes</code> attribute provides a convenient way to sort element's children by CSS selector. For example, a <code>DockLayoutPanel</code> component could be used like this in the document DOM tree:
<code>
<pre>
<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>
</pre>
</code>
Provided that its shadow DOM tree looks like this:
<code>
<pre>
<#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>
</pre>
</code>
The document DOM tree children on of <code>x-dock-layout-panel</code> will be rendered as if composed from this tree:
<code>
<pre>
<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>
</pre>
</code>

Required Building Blocks:
* [[#Content_Element | 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 [http://dev.w3.org/csswg/css3-lists/ lists]) are just components that have shadow DOM. Coincidentally, this also explains why you can't add shadow DOM subtrees to <code>input</code> or <code>details</code> elements -- their <code>ShadowRoot</code>s are claimed by <code>HTMLInputElement</code> and <code>HTMLDetailsElement</code> constructors, respectively.

Required Building Blocks:
* [[#Shadow_DOM | Shadow DOM]]
* [[#Content_Element | 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:

<code>
<pre>
// 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);
</pre>
</code>

In this situation, there is no room for error: <code>view.js</code> ''must'' wait for <code>layout.js</code> to load before executing. You can't load <code>layout.js</code> lazily or in any different order, since it defines the components that are used in <code>view.js</code>. 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 an unknown DOM element with an "x-"-prefixed <code>tagName</code> is encountered, we put a placeholder <code>HTMLUnknownElement</code> instance in its place. As soon as the element is defined, all placeholder instances are replaced ([http://www.w3.org/TR/DOM-Level-3-Core/core.html#Document3-renameNode Document.renameNode]) with the new, proper DOM element.

Required Building Blocks:
* [[#Registering_Elements | Registering Elements]]

== Confinement ==
Confinement refers to the document protecting its implementation details and state from the component and can be viewed as the inverse of [[#Encapsulation | encapsulation]].

Required Building Blocks:
* [[#Confinement_Primitives | Confinement Primitives]]

=Building Blocks=

The component model is comprised of the following building blocks.

==Shadow DOM==

Any DOM element can host a shadow DOM subtree. The shadow DOM subtree originates at <code>ShadowRoot</code>, which is coupled the hosting element at the time of its construction. You don't need any other building blocks in order to take advantage of the shadow DOM:
<code>
<pre>
var element = document.createElement("div");
var shadow = new ShadowRoot(element);
shadow.appendChild(document.createElement("p")).textContent = "weee!!';
</pre>
</code>

A <code>ShadowRoot</code> instance is a [http://dvcs.w3.org/hg/domcore/raw-file/tip/Overview.html#interface-node Node], and acts as the root of the element's shadow DOM subtree. The <code>ShadowRoot</code> itself is never rendered, nor has styles. In this regard, it's similar to the [http://dvcs.w3.org/hg/domcore/raw-file/tip/Overview.html#interface-documentfragment DocumentFragment]. It has two properties:
* <code>applyAuthorSheets</code>, which is either '''true''' (that is, apply author style sheets from the document), or '''false''' (don't);
* <code>shadowHost</code>, which points to the hosting element.

==Content Element==

The <code>content</code> element is used with [[#Shadow_DOM | Shadow DOM]] and provides a mechanism for distributing hosting element's children inside of its shadow subtree. To preserve the [[#Encapsulation | encapsulation]] property, the <code>content</code> elements act as insertion points and do not leak any information about hosting element's children to the shadow DOM subtree or vise versa.

==Constructable DOM Types==
The inability to construct DOM element using <code>new</code> (with some exceptions) or use them in the prototype inheritance chain had confounded many Web developers since the beginning of DOM. This building block intends to rectify at least the latter by allowing <code>HTMLElement.call</code> invocation and thus enabling creation of JavaScript objects with DOM elements in the prototype chain.

==Registering Elements==
Working in conjunction with [[#Constructable_DOM_Types | Constructable DOM Types]], this building block makes the list of valid markup tag names extensible by exposing <code>Element.register</code>:
<code>
<pre>
partial interface Element {
static void register(in String tagName, in Function constructor);
}
</pre>
</code>

It is possible to envisage a milder (though less elegant) version of element registration by keeping DOM element construction magical (thus decoupling it from [[#Constructable_DOM_Types | Constructable DOM Types]]) and making <code>Element.register</code> use a callback, rather than <code>constructor</code> as parameter. The callback would be invoked with an already-constructed DOM object with the specified <code>tagName</code>, leaving the work of setting up properties on this object to the callback.

==Confinement Primitives==

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 <code>window.postMessage</code>.

* 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 <code>Element.register</code> and <code>new ShadowRoot</code> 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 <code>confined</code> attribute to the <code>script</code> element. Presence of this attribute triggers loading scripts in the confined context.

Confinement of script execution could be useful outside of the component model and also could be related to [https://dvcs.w3.org/hg/content-security-policy/raw-file/tip/csp-specification.dev.html Content Security Policy].

* [[Component_Model_Isolation_Brainstorming | Isolation Brainstorm]]

=Building Blocks Use Case Coverage=

Here's a list of building blocks, tabulated against the [[Component_Model_Use_Cases | use cases]] and approximate percentage of satisfying them:

{| cellpadding="10" cellspacing="0" style="border-collapse: collapse;"
|- valign="top" style="border-bottom: 1px solid LightGray;"
! align="left" | Building Block
! align="left" | [[Component_Model_Use_Cases#Layout_Manager | Layout Manager]]
! align="left" | [[Component_Model_Use_Cases#Widget_Mix-and-Match | Mix-and-Match]]
! align="left" | [[Component_Model_Use_Cases#Rendering_Form_Controls_with_SVG | SVG Controls]]
! align="left" | [[Component_Model_Use_Cases#Contacts_Widget | Contacts Widget]]
! align="left" | [[Component_Model_Use_Cases#Like.2F.2B1_Button | Like/+1 Button]]
! align="left" | [[Component_Model_Use_Cases#Media_Controls_For_The_Video_Element | Media Controls for the Video Element]]
! align="left" | [[Component_Model_Use_Cases#Details.2FSummary_Elements | Details/Summary Element]]
|- valign="top" style="border-bottom: 1px solid LightGray;"
| [[Component_Model#Shadow_DOM | Shadow DOM]]
| 25%
| -
| 34%
| 100%
| 25%
| 100%
| 50%
|- valign="top" style="border-bottom: 1px solid LightGray;"
| [[Component_Model#Content_Element | Content Element]]
| 25%
| -
| -
| -
| -
| -
| 50%
|- valign="top" style="border-bottom: 1px solid LightGray;"
| [[Component_Model#Constructable_DOM_Types | Constructable DOM Types]]
| 25%
| 50%
| 33%
| -
| 25%
| -
| -
|- valign="top" style="border-bottom: 1px solid LightGray;"
| [[Component_Model#Registering_Elements | Registering Elements]]
| 25%
| 50%
| 33%
| -
| 25%
| -
| -
|- valign="top" style="border-bottom: 1px solid LightGray;"
| [[Component_Model#Confinement_Primitives | Confinement Primitives]]
| -
| -
| -
| -
| 25%
| -
| -
|}

=Comparison With Existing Specs and Implementations=

Here's a brief overview of existing similar specifications and implementations:
* [http://msdn.microsoft.com/en-us/library/ms531018(v=vs.85).aspx HTML Components] is a [http://windows.microsoft.com/en-US/internet-explorer/products/ie/home Microsoft Internet Explorer]-specific method of creating custom DOM elements. Also see [http://www.w3.org/TR/NOTE-HTMLComponents HTML Components Note] (implemented in IE5+).
* [http://www.w3.org/TR/2001/NOTE-xbl-20010223/ XBL], currently implemented in Mozilla.
* [http://dev.w3.org/2006/xbl2/ XBL2], the ancestral spec of the Component Model, and a revision of XBL.

Here's a handy overview of how each of these specs satisfies the component model [[#Properties | properties]]:

{| cellpadding="10" cellspacing="0" style="border-collapse: collapse;"
|- valign="top" style="border-bottom: 1px solid LightGray;"
! align="left" width="12%" | Spec/Implementation
! align="left" width="12%" | [[#Extensibility | Extensibility]]
! align="left" width="12%" | [[#Consistency | Consistency]]
! align="left" width="12%" | [[#Encapsulation | Encapsulation]]
! align="left" width="12%" | [[#Composability | Composability]]
! align="left" width="12%" | [[#Desugaring | Desugaring]]
! align="left" width="12%" | [[#Performance | Performance]]
! align="left" width="12%" | [[#Confinement | Confinement]]
|- valign="top" style="border-bottom: 1px solid LightGray;"
! align="left" | HTML Components
| '''No'''. Components are magic, inextensible objects.
| '''Almost'''. Implementation provides ways to add properties, methods, events to element API, and the components are ''almost'' DOM elements. However, custom tags don't support all properties of a DOM element.
| '''Not much'''. There are some provisions for event encapsulation, nothing else.
| '''Not much'''. No provisions for handling document children vs. component-defined children.
| '''No'''.
| '''Not sure'''.
| '''No'''.
|- valign="top" style="border-bottom: 1px solid LightGray;"
! align="left" | XBL
| '''No'''. The mechanism for extending bindings is entirely independent of DOM type or Javascript extensibility.
| '''Yes-ish'''. Bindings can override properties on the DOM element, although the mechanism is highly unnatural (XML declarations).
| '''Yes'''? Hard to say looking at TR note.
| '''Yes'''
| '''Yes'''. Some HTML elements in Gecko are implemented using it.
| '''Not sure'''.
| '''No'''.
|- valign="top" style="border-bottom: 1px solid LightGray;"
! align="left" | XBL2
| '''No'''. Same as XBL.
| '''No'''. Bindings are discouraged from establishing an API surface on a bound element.
| '''Yes'''.
| '''Yes'''.
| '''No'''. The spec didn't intend to describe how native elements are built.
| '''Somewhat'''. The lifecycle of a binding is well-defined and initialization stages are well-decoupled. However, there is no way to build a binding imperatively without loading a binding document.
| '''No'''.
|}

The key differences between XBL2 and the Component Model are:
* The Component Model fully embraces the [[Behavior_Attachment#Behavior_Attachment_Methods | element behavior attachment]] by allowing creation of new types of DOM elements within a document. This is something Web Framework developers always wanted and repeatedly try to do with parallel object hierarchies. Eliminating ephemerality of the attachment simplifies and clarifies how things work conceptually -- there is no longer a place for "spooky action at a distance", caused by a change of a random CSS selector or even removing an element from the tree.
* The Component Model is strongly biased toward reusing existing bits of the platform and well-established techniques instead of inventing new ones. For instance, instead of bindings inheritance, we rely on prototype inheritance. Instead of endeavoring to solve the incredibly complex, yet dubious problem of multiple bindings or shadow DOM trees, we simply suggest composition.
* The Component Model strives to add capabilities in layers (see [[#Building_Blocks | building blocks]]), each able to function on its own. The omnibus nature of XBL2 removes opportunities for layering, particularly as element identity, life cycle, and scripting are concerned. Perhaps this could be repaired somehow, but Component Model solves these issues without further complicating an already large, difficult to understand spec.

[[Category:Proposals]]

Component Model Decorator Brainstorming

2011-10-24T21:57:27Z

Rolandsteiner: creating the page

Stub

Component Model Strawman: Styling

2011-10-24T21:57:02Z

Rolandsteiner: creating the page

Stub

Component Model Strawman: Declarative Syntax

2011-10-24T21:56:44Z

Rolandsteiner: creating the page

Stub

Component Model Strawman: Isolation

2011-10-24T21:56:20Z

Rolandsteiner: creating the page

Stub

Component Model Discussion: Rendering

2011-10-21T04:26:57Z

Rolandsteiner: /* [F2] neither host element nor shadow root rendered, shadow root has single child <R> as root element */

= Overview =

The question asked herein is how to best treat the following somewhat mutually exclusive requirements:

[1] The containing document "wants" to naturally style the host element (using <x-foo> notation here - see the [http://wiki.whatwg.org/index.php?title=Component_Model_Discussion:_Registration Component Registration page] for alternatives). E.g.,

x-foo {
background-color: yellow;
border: 1px solid blue;
}

[2] The component "wants" to be able to style its outermost rendering rectangle. Because of [http://wiki.whatwg.org/index.php?title=Component_Model_Discussion:_Isolation Isolation], this rectangle is ideally located within the component, i.e., within the shadow DOM.

and as a somewhat lesser concern:

[3] Every point between the rectangles should correspond to a valid DOM range.

ad [3]: Note that conversely, in no variant there is a mapping from a DOM range with anchor <x-foo> to a rectangle/screen position, since the children of <x-foo> may be rendered in arbitrary places, depending on <content> elements within the shadow DOM, or even not at all.

== Rendering ==

This consists of the following, more or less orthogonal, sub-questions

* is the host element rendered or not?
* is the shadow root rendered or not?
* is the shadow root an element or a separate node type?
* using <code>display: transparent</code>?

Almost all combinations of the above have their respective merits and problems. Assume we have the following DOM structure:

<A>
<x-foo> -----> [ShadowRoot (S)]
<B/> <Y/>
<C/> <Z/>
<D/>
</x-foo>
</A>

This could conceivably be rendered in the following ways:

=== [A] rendered host element, rendered shadow root, shadow root is element ===

A---------------------------------------------------------------------+
| x-foo-------------------------------------------------+ |
| | SR------------------------------------+ | |
| | | Y------+ Z------+ | | |
| [A,0] | ??? | [S,0] | | [S,1] | | [S,2] | ??? | [A,1] |
| | | +------+ +------+ | | |
| | +-------------------------------------+ | |
| +-----------------------------------------------------+ |
+---------------------------------------------------------------------+

Consequences:

* Shadow root as element requires separate TreeScope tree and host-element pointer

Issues:

* Styles set on <x-foo> such as <code>background-color</code> don't really affect the component's rendering if the component overrides them on the shadow root.
* The potential gaps between the shadow root's rectangle and the outer host element's rectangle don't directly map to a DOM position.

=== [B] rendered host element with default <code>display: transparent</code>, rendered shadow root, shadow root is element ===

A-------------------------------------------------------+
| x-foo - - - - - - - - - - - - - - - - - + |
| :SR------------------------------------+: |
| :| Z------+ +------+ |: |
| [A,0] :| [S,0] | | [S,1] | | [S,2] |: [A,1] |
| :| Z------+ +------+ |: |
| :+-------------------------------------+: |
| + - - - - - - - - - - - - - - - - - - - + |
+-------------------------------------------------------+

Consequences:

* Shadow root as element requires separate TreeScope tree and host-element pointer

Issues:

* Containing document can't style the shadow host, but this is more apparent because of <code>display: transparent</code>. Containing document could set <code>display</code> to something different if needed.
* If <code>display</code> is set to something different it becomes variant [A], with the associated issues.

=== [C] rendered host element, rendered shadow root, shadow root is separate node type, shadow root's rectangle always is the same as the host element's (no gap) ===

A-------------------------------------------------------+
| x-foo-----------------------------------+ |
| |SR------------------------------------+| |
| || Z------+ +------+ || |
| [A,0] || [S,0] | | [S,1] | | [S,2] || [A,1] |
| || Z------+ +------+ || |
| |+-------------------------------------+| |
| +---------------------------------------+ |
+-------------------------------------------------------+

This allows both the document to style <x-foo>, as well as allowing the component to have its own outer rectangle, but prevents any gap from forming between them. However, this raises more questions than it answers:

Issues:

* Need to spec how ShadowRoot node type is styleable
* <code>margin</code>, <code>padding</code>, <code>position</code> et al must not apply, so need to define how styles apply to ShadowRoot in detail.

=== [D] rendered host element, shadow root not rendered ===

A-----------------------------------------------------+
| x-foo---------------------------------+ |
| | Y------+ Z------+ | |
| [A,0] | ??? | | ??? | | ??? | [A,1] |
| | +------+ +------+ | |
| +-------------------------------------+ |
+-----------------------------------------------------+

Issues:

* Confinement requires separate style-sheet in order for the component to be able to style the host element.
* The potential gaps between the rectangles of the shadow root's children and the outer host element don't directly map to a DOM position.

=== [E] host element has <code>display: transparent</code> by default, shadow root not rendered ===

A---------------------------------------+
| x-foo - - - - - - - - - + |
| :Y------+ Z------+: |
| ??? :| | ??? | |: ??? |
| :+------+ +------+: |
| + - - - - - - - - - - - + |
+---------------------------------------+

Issues:

* Containing document can't style the shadow host, but this is more apparent because of <code>display: transparent</code>. Containing document could set <code>display</code> to something different if needed.
* If <code>display</code> is set to something different it becomes variant [D], with the associated issues.
* The potential gaps between the rectangles of the shadow root's children and the outer host element don't directly map to a DOM position.

=== [F] host element not rendered, rendered shadow root ===

In this scenario, the ShadowRoot most likely is an element.

A-----------------------------------------------------+
| SR------------------------------------+ |
| | Y------+ Z------+ | |
| [A,0] | [S,0] | | [S,1] | | [S,2] | [A,1] |
| | +------+ +------+ | |
| +-------------------------------------+ |
+-----------------------------------------------------+

Issues:

* Containing document can't style the shadow host. Because of Isolation it also can't style the ShadowRoot, unless styles styles set on <x-foo> are forwarded somehow. If so, mechanism of style forwarding needs to be specced.

=== [F2] neither host element nor shadow root rendered, shadow root has single child <R> as root element ===

Similar to [F], but the ShadowRoot doesn't have to be an element itself, can be extended towards [G] later on.

A-----------------------------------------------------+
| R-------------------------------------+ |
| | Y------+ Z------+ | |
| [A,0] | [S,0] | | [S,1] | | [S,2] | [A,1] |
| | +------+ +------+ | |
| +-------------------------------------+ |
+-----------------------------------------------------+

Issues:

* Containing document can't style the shadow host. Because of Isolation it also can't style the ShadowRoot nor the shadow root element, unless styles styles set on <x-foo> are forwarded somehow. If so, mechanism of style forwarding needs to be specced.

=== [G] neither host element nor shadow root rendered ===

A-------------------------------------+
| Y------+ Z------+ |
| ??? | | ??? | | ??? |
| +------+ +------+ |
+-------------------------------------+

Undoubtedly the most flexible from a layout perspective, as it allows a single element to "create" multiple renderers.

Issues:

* There is no single rendering rectangle corresponding to <x-foo>.
* Containing document can't style the host element. Styles set on <x-foo> could be forwarded to ALL children of the shadow root, but it's not clear this is useful.
* The potential gaps between the rectangles of the shadow root's children and the host element's parent don't directly map to a DOM position.

=== [Z] Other? ===

There is a marvelous variant that solves all issues and doesn't suffer any of the above drawbacks which this paragraph is too small to contain.

== Current State ==

Currently we implemented variant [D].

We probably want to go towards [F2].

Component Model Discussion: Rendering

2011-10-21T04:12:55Z

Rolandsteiner: /* Current State */

= Overview =

The question asked herein is how to best treat the following somewhat mutually exclusive requirements:

[1] The containing document "wants" to naturally style the host element (using <x-foo> notation here - see the [http://wiki.whatwg.org/index.php?title=Component_Model_Discussion:_Registration Component Registration page] for alternatives). E.g.,

x-foo {
background-color: yellow;
border: 1px solid blue;
}

[2] The component "wants" to be able to style its outermost rendering rectangle. Because of [http://wiki.whatwg.org/index.php?title=Component_Model_Discussion:_Isolation Isolation], this rectangle is ideally located within the component, i.e., within the shadow DOM.

and as a somewhat lesser concern:

[3] Every point between the rectangles should correspond to a valid DOM range.

ad [3]: Note that conversely, in no variant there is a mapping from a DOM range with anchor <x-foo> to a rectangle/screen position, since the children of <x-foo> may be rendered in arbitrary places, depending on <content> elements within the shadow DOM, or even not at all.

== Rendering ==

This consists of the following, more or less orthogonal, sub-questions

* is the host element rendered or not?
* is the shadow root rendered or not?
* is the shadow root an element or a separate node type?
* using <code>display: transparent</code>?

Almost all combinations of the above have their respective merits and problems. Assume we have the following DOM structure:

<A>
<x-foo> -----> [ShadowRoot (S)]
<B/> <Y/>
<C/> <Z/>
<D/>
</x-foo>
</A>

This could conceivably be rendered in the following ways:

=== [A] rendered host element, rendered shadow root, shadow root is element ===

A---------------------------------------------------------------------+
| x-foo-------------------------------------------------+ |
| | SR------------------------------------+ | |
| | | Y------+ Z------+ | | |
| [A,0] | ??? | [S,0] | | [S,1] | | [S,2] | ??? | [A,1] |
| | | +------+ +------+ | | |
| | +-------------------------------------+ | |
| +-----------------------------------------------------+ |
+---------------------------------------------------------------------+

Consequences:

* Shadow root as element requires separate TreeScope tree and host-element pointer

Issues:

* Styles set on <x-foo> such as <code>background-color</code> don't really affect the component's rendering if the component overrides them on the shadow root.
* The potential gaps between the shadow root's rectangle and the outer host element's rectangle don't directly map to a DOM position.

=== [B] rendered host element with default <code>display: transparent</code>, rendered shadow root, shadow root is element ===

A-------------------------------------------------------+
| x-foo - - - - - - - - - - - - - - - - - + |
| :SR------------------------------------+: |
| :| Z------+ +------+ |: |
| [A,0] :| [S,0] | | [S,1] | | [S,2] |: [A,1] |
| :| Z------+ +------+ |: |
| :+-------------------------------------+: |
| + - - - - - - - - - - - - - - - - - - - + |
+-------------------------------------------------------+

Consequences:

* Shadow root as element requires separate TreeScope tree and host-element pointer

Issues:

* Containing document can't style the shadow host, but this is more apparent because of <code>display: transparent</code>. Containing document could set <code>display</code> to something different if needed.
* If <code>display</code> is set to something different it becomes variant [A], with the associated issues.

=== [C] rendered host element, rendered shadow root, shadow root is separate node type, shadow root's rectangle always is the same as the host element's (no gap) ===

A-------------------------------------------------------+
| x-foo-----------------------------------+ |
| |SR------------------------------------+| |
| || Z------+ +------+ || |
| [A,0] || [S,0] | | [S,1] | | [S,2] || [A,1] |
| || Z------+ +------+ || |
| |+-------------------------------------+| |
| +---------------------------------------+ |
+-------------------------------------------------------+

This allows both the document to style <x-foo>, as well as allowing the component to have its own outer rectangle, but prevents any gap from forming between them. However, this raises more questions than it answers:

Issues:

* Need to spec how ShadowRoot node type is styleable
* <code>margin</code>, <code>padding</code>, <code>position</code> et al must not apply, so need to define how styles apply to ShadowRoot in detail.

=== [D] rendered host element, shadow root not rendered ===

A-----------------------------------------------------+
| x-foo---------------------------------+ |
| | Y------+ Z------+ | |
| [A,0] | ??? | | ??? | | ??? | [A,1] |
| | +------+ +------+ | |
| +-------------------------------------+ |
+-----------------------------------------------------+

Issues:

* Confinement requires separate style-sheet in order for the component to be able to style the host element.
* The potential gaps between the rectangles of the shadow root's children and the outer host element don't directly map to a DOM position.

=== [E] host element has <code>display: transparent</code> by default, shadow root not rendered ===

A---------------------------------------+
| x-foo - - - - - - - - - + |
| :Y------+ Z------+: |
| ??? :| | ??? | |: ??? |
| :+------+ +------+: |
| + - - - - - - - - - - - + |
+---------------------------------------+

Issues:

* Containing document can't style the shadow host, but this is more apparent because of <code>display: transparent</code>. Containing document could set <code>display</code> to something different if needed.
* If <code>display</code> is set to something different it becomes variant [D], with the associated issues.
* The potential gaps between the rectangles of the shadow root's children and the outer host element don't directly map to a DOM position.

=== [F] host element not rendered, rendered shadow root ===

In this scenario, the ShadowRoot most likely is an element.

A-----------------------------------------------------+
| SR------------------------------------+ |
| | Y------+ Z------+ | |
| [A,0] | [S,0] | | [S,1] | | [S,2] | [A,1] |
| | +------+ +------+ | |
| +-------------------------------------+ |
+-----------------------------------------------------+

Issues:

* Containing document can't style the shadow host. Because of Isolation it also can't style the ShadowRoot, unless styles styles set on <x-foo> are forwarded somehow. If so, mechanism of style forwarding needs to be specced.

=== [F2] neither host element nor shadow root rendered, shadow root has single child <R> as root element ===

A-----------------------------------------------------+
| R-------------------------------------+ |
| | Y------+ Z------+ | |
| [A,0] | [S,0] | | [S,1] | | [S,2] | [A,1] |
| | +------+ +------+ | |
| +-------------------------------------+ |
+-----------------------------------------------------+

Issues:

* Containing document can't style the shadow host. Because of Isolation it also can't style the ShadowRoot nor the shadow root element, unless styles styles set on <x-foo> are forwarded somehow. If so, mechanism of style forwarding needs to be specced.

=== [G] neither host element nor shadow root rendered ===

A-------------------------------------+
| Y------+ Z------+ |
| ??? | | ??? | | ??? |
| +------+ +------+ |
+-------------------------------------+

Undoubtedly the most flexible from a layout perspective, as it allows a single element to "create" multiple renderers.

Issues:

* There is no single rendering rectangle corresponding to <x-foo>.
* Containing document can't style the host element. Styles set on <x-foo> could be forwarded to ALL children of the shadow root, but it's not clear this is useful.
* The potential gaps between the rectangles of the shadow root's children and the host element's parent don't directly map to a DOM position.

=== [Z] Other? ===

There is a marvelous variant that solves all issues and doesn't suffer any of the above drawbacks which this paragraph is too small to contain.

== Current State ==

Currently we implemented variant [D].

We probably want to go towards [F2].

Component Model Discussion: Rendering

2011-10-21T04:00:12Z

Rolandsteiner: /* [F] host element not rendered, rendered shadow root */ add variant for [F]

= Overview =

The question asked herein is how to best treat the following somewhat mutually exclusive requirements:

[1] The containing document "wants" to naturally style the host element (using <x-foo> notation here - see the [http://wiki.whatwg.org/index.php?title=Component_Model_Discussion:_Registration Component Registration page] for alternatives). E.g.,

x-foo {
background-color: yellow;
border: 1px solid blue;
}

[2] The component "wants" to be able to style its outermost rendering rectangle. Because of [http://wiki.whatwg.org/index.php?title=Component_Model_Discussion:_Isolation Isolation], this rectangle is ideally located within the component, i.e., within the shadow DOM.

and as a somewhat lesser concern:

[3] Every point between the rectangles should correspond to a valid DOM range.

ad [3]: Note that conversely, in no variant there is a mapping from a DOM range with anchor <x-foo> to a rectangle/screen position, since the children of <x-foo> may be rendered in arbitrary places, depending on <content> elements within the shadow DOM, or even not at all.

== Rendering ==

This consists of the following, more or less orthogonal, sub-questions

* is the host element rendered or not?
* is the shadow root rendered or not?
* is the shadow root an element or a separate node type?
* using <code>display: transparent</code>?

Almost all combinations of the above have their respective merits and problems. Assume we have the following DOM structure:

<A>
<x-foo> -----> [ShadowRoot (S)]
<B/> <Y/>
<C/> <Z/>
<D/>
</x-foo>
</A>

This could conceivably be rendered in the following ways:

=== [A] rendered host element, rendered shadow root, shadow root is element ===

A---------------------------------------------------------------------+
| x-foo-------------------------------------------------+ |
| | SR------------------------------------+ | |
| | | Y------+ Z------+ | | |
| [A,0] | ??? | [S,0] | | [S,1] | | [S,2] | ??? | [A,1] |
| | | +------+ +------+ | | |
| | +-------------------------------------+ | |
| +-----------------------------------------------------+ |
+---------------------------------------------------------------------+

Consequences:

* Shadow root as element requires separate TreeScope tree and host-element pointer

Issues:

* Styles set on <x-foo> such as <code>background-color</code> don't really affect the component's rendering if the component overrides them on the shadow root.
* The potential gaps between the shadow root's rectangle and the outer host element's rectangle don't directly map to a DOM position.

=== [B] rendered host element with default <code>display: transparent</code>, rendered shadow root, shadow root is element ===

A-------------------------------------------------------+
| x-foo - - - - - - - - - - - - - - - - - + |
| :SR------------------------------------+: |
| :| Z------+ +------+ |: |
| [A,0] :| [S,0] | | [S,1] | | [S,2] |: [A,1] |
| :| Z------+ +------+ |: |
| :+-------------------------------------+: |
| + - - - - - - - - - - - - - - - - - - - + |
+-------------------------------------------------------+

Consequences:

* Shadow root as element requires separate TreeScope tree and host-element pointer

Issues:

* Containing document can't style the shadow host, but this is more apparent because of <code>display: transparent</code>. Containing document could set <code>display</code> to something different if needed.
* If <code>display</code> is set to something different it becomes variant [A], with the associated issues.

=== [C] rendered host element, rendered shadow root, shadow root is separate node type, shadow root's rectangle always is the same as the host element's (no gap) ===

A-------------------------------------------------------+
| x-foo-----------------------------------+ |
| |SR------------------------------------+| |
| || Z------+ +------+ || |
| [A,0] || [S,0] | | [S,1] | | [S,2] || [A,1] |
| || Z------+ +------+ || |
| |+-------------------------------------+| |
| +---------------------------------------+ |
+-------------------------------------------------------+

This allows both the document to style <x-foo>, as well as allowing the component to have its own outer rectangle, but prevents any gap from forming between them. However, this raises more questions than it answers:

Issues:

* Need to spec how ShadowRoot node type is styleable
* <code>margin</code>, <code>padding</code>, <code>position</code> et al must not apply, so need to define how styles apply to ShadowRoot in detail.

=== [D] rendered host element, shadow root not rendered ===

A-----------------------------------------------------+
| x-foo---------------------------------+ |
| | Y------+ Z------+ | |
| [A,0] | ??? | | ??? | | ??? | [A,1] |
| | +------+ +------+ | |
| +-------------------------------------+ |
+-----------------------------------------------------+

Issues:

* Confinement requires separate style-sheet in order for the component to be able to style the host element.
* The potential gaps between the rectangles of the shadow root's children and the outer host element don't directly map to a DOM position.

=== [E] host element has <code>display: transparent</code> by default, shadow root not rendered ===

A---------------------------------------+
| x-foo - - - - - - - - - + |
| :Y------+ Z------+: |
| ??? :| | ??? | |: ??? |
| :+------+ +------+: |
| + - - - - - - - - - - - + |
+---------------------------------------+

Issues:

* Containing document can't style the shadow host, but this is more apparent because of <code>display: transparent</code>. Containing document could set <code>display</code> to something different if needed.
* If <code>display</code> is set to something different it becomes variant [D], with the associated issues.
* The potential gaps between the rectangles of the shadow root's children and the outer host element don't directly map to a DOM position.

=== [F] host element not rendered, rendered shadow root ===

In this scenario, the ShadowRoot most likely is an element.

A-----------------------------------------------------+
| SR------------------------------------+ |
| | Y------+ Z------+ | |
| [A,0] | [S,0] | | [S,1] | | [S,2] | [A,1] |
| | +------+ +------+ | |
| +-------------------------------------+ |
+-----------------------------------------------------+

Issues:

* Containing document can't style the shadow host. Because of Isolation it also can't style the ShadowRoot, unless styles styles set on <x-foo> are forwarded somehow. If so, mechanism of style forwarding needs to be specced.

=== [F2] neither host element nor shadow root rendered, shadow root has single child <R> as root element ===

A-----------------------------------------------------+
| R-------------------------------------+ |
| | Y------+ Z------+ | |
| [A,0] | [S,0] | | [S,1] | | [S,2] | [A,1] |
| | +------+ +------+ | |
| +-------------------------------------+ |
+-----------------------------------------------------+

Issues:

* Containing document can't style the shadow host. Because of Isolation it also can't style the ShadowRoot nor the shadow root element, unless styles styles set on <x-foo> are forwarded somehow. If so, mechanism of style forwarding needs to be specced.

=== [G] neither host element nor shadow root rendered ===

A-------------------------------------+
| Y------+ Z------+ |
| ??? | | ??? | | ??? |
| +------+ +------+ |
+-------------------------------------+

Undoubtedly the most flexible from a layout perspective, as it allows a single element to "create" multiple renderers.

Issues:

* There is no single rendering rectangle corresponding to <x-foo>.
* Containing document can't style the host element. Styles set on <x-foo> could be forwarded to ALL children of the shadow root, but it's not clear this is useful.
* The potential gaps between the rectangles of the shadow root's children and the host element's parent don't directly map to a DOM position.

=== [Z] Other? ===

There is a marvelous variant that solves all issues and doesn't suffer any of the above drawbacks which this paragraph is too small to contain.

== Current State ==

Currently we implemented variant [D].

Component Model Discussion: Rendering

2011-10-21T01:58:21Z

Rolandsteiner: /* [F] host element not rendered, rendered shadow root */ Fix incorrect statement about DOM positions

= Overview =

The question asked herein is how to best treat the following somewhat mutually exclusive requirements:

[1] The containing document "wants" to naturally style the host element (using <x-foo> notation here - see the [http://wiki.whatwg.org/index.php?title=Component_Model_Discussion:_Registration Component Registration page] for alternatives). E.g.,

x-foo {
background-color: yellow;
border: 1px solid blue;
}

[2] The component "wants" to be able to style its outermost rendering rectangle. Because of [http://wiki.whatwg.org/index.php?title=Component_Model_Discussion:_Isolation Isolation], this rectangle is ideally located within the component, i.e., within the shadow DOM.

and as a somewhat lesser concern:

[3] Every point between the rectangles should correspond to a valid DOM range.

ad [3]: Note that conversely, in no variant there is a mapping from a DOM range with anchor <x-foo> to a rectangle/screen position, since the children of <x-foo> may be rendered in arbitrary places, depending on <content> elements within the shadow DOM, or even not at all.

== Rendering ==

This consists of the following, more or less orthogonal, sub-questions

* is the host element rendered or not?
* is the shadow root rendered or not?
* is the shadow root an element or a separate node type?
* using <code>display: transparent</code>?

Almost all combinations of the above have their respective merits and problems. Assume we have the following DOM structure:

<A>
<x-foo> -----> [ShadowRoot (S)]
<B/> <Y/>
<C/> <Z/>
<D/>
</x-foo>
</A>

This could conceivably be rendered in the following ways:

=== [A] rendered host element, rendered shadow root, shadow root is element ===

A---------------------------------------------------------------------+
| x-foo-------------------------------------------------+ |
| | SR------------------------------------+ | |
| | | Y------+ Z------+ | | |
| [A,0] | ??? | [S,0] | | [S,1] | | [S,2] | ??? | [A,1] |
| | | +------+ +------+ | | |
| | +-------------------------------------+ | |
| +-----------------------------------------------------+ |
+---------------------------------------------------------------------+

Consequences:

* Shadow root as element requires separate TreeScope tree and host-element pointer

Issues:

* Styles set on <x-foo> such as <code>background-color</code> don't really affect the component's rendering if the component overrides them on the shadow root.
* The potential gaps between the shadow root's rectangle and the outer host element's rectangle don't directly map to a DOM position.

=== [B] rendered host element with default <code>display: transparent</code>, rendered shadow root, shadow root is element ===

A-------------------------------------------------------+
| x-foo - - - - - - - - - - - - - - - - - + |
| :SR------------------------------------+: |
| :| Z------+ +------+ |: |
| [A,0] :| [S,0] | | [S,1] | | [S,2] |: [A,1] |
| :| Z------+ +------+ |: |
| :+-------------------------------------+: |
| + - - - - - - - - - - - - - - - - - - - + |
+-------------------------------------------------------+

Consequences:

* Shadow root as element requires separate TreeScope tree and host-element pointer

Issues:

* Containing document can't style the shadow host, but this is more apparent because of <code>display: transparent</code>. Containing document could set <code>display</code> to something different if needed.
* If <code>display</code> is set to something different it becomes variant [A], with the associated issues.

=== [C] rendered host element, rendered shadow root, shadow root is separate node type, shadow root's rectangle always is the same as the host element's (no gap) ===

A-------------------------------------------------------+
| x-foo-----------------------------------+ |
| |SR------------------------------------+| |
| || Z------+ +------+ || |
| [A,0] || [S,0] | | [S,1] | | [S,2] || [A,1] |
| || Z------+ +------+ || |
| |+-------------------------------------+| |
| +---------------------------------------+ |
+-------------------------------------------------------+

This allows both the document to style <x-foo>, as well as allowing the component to have its own outer rectangle, but prevents any gap from forming between them. However, this raises more questions than it answers:

Issues:

* Need to spec how ShadowRoot node type is styleable
* <code>margin</code>, <code>padding</code>, <code>position</code> et al must not apply, so need to define how styles apply to ShadowRoot in detail.

=== [D] rendered host element, shadow root not rendered ===

A-----------------------------------------------------+
| x-foo---------------------------------+ |
| | Y------+ Z------+ | |
| [A,0] | ??? | | ??? | | ??? | [A,1] |
| | +------+ +------+ | |
| +-------------------------------------+ |
+-----------------------------------------------------+

Issues:

* Confinement requires separate style-sheet in order for the component to be able to style the host element.
* The potential gaps between the rectangles of the shadow root's children and the outer host element don't directly map to a DOM position.

=== [E] host element has <code>display: transparent</code> by default, shadow root not rendered ===

A---------------------------------------+
| x-foo - - - - - - - - - + |
| :Y------+ Z------+: |
| ??? :| | ??? | |: ??? |
| :+------+ +------+: |
| + - - - - - - - - - - - + |
+---------------------------------------+

Issues:

* Containing document can't style the shadow host, but this is more apparent because of <code>display: transparent</code>. Containing document could set <code>display</code> to something different if needed.
* If <code>display</code> is set to something different it becomes variant [D], with the associated issues.
* The potential gaps between the rectangles of the shadow root's children and the outer host element don't directly map to a DOM position.

=== [F] host element not rendered, rendered shadow root ===

In this scenario, the ShadowRoot most likely is an element.

A-----------------------------------------------------+
| SR------------------------------------+ |
| | Y------+ Z------+ | |
| [A,0] | [S,0] | | [S,1] | | [S,2] | [A,1] |
| | +------+ +------+ | |
| +-------------------------------------+ |
+-----------------------------------------------------+

Issues:

* Containing document can't style the shadow host. Because of Isolation it also can't style the ShadowRoot, unless styles styles set on <x-foo> are forwarded somehow. If so, mechanism of style forwarding needs to be specced.

=== [G] neither host element nor shadow root rendered ===

A-------------------------------------+
| Y------+ Z------+ |
| ??? | | ??? | | ??? |
| +------+ +------+ |
+-------------------------------------+

Undoubtedly the most flexible from a layout perspective, as it allows a single element to "create" multiple renderers.

Issues:

* There is no single rendering rectangle corresponding to <x-foo>.
* Containing document can't style the host element. Styles set on <x-foo> could be forwarded to ALL children of the shadow root, but it's not clear this is useful.
* The potential gaps between the rectangles of the shadow root's children and the host element's parent don't directly map to a DOM position.

=== [Z] Other? ===

There is a marvelous variant that solves all issues and doesn't suffer any of the above drawbacks which this paragraph is too small to contain.

== Current State ==

Currently we implemented variant [D].