Shadow DOM

This specification describes a method of combining multiple DOM trees into one hierarchy and how these trees interact with each other within a document, thus enabling better composition of the DOM.

Conformance

All diagrams, examples, notes, are non-normative, as well as sections explicitly marked as non-normative. Everything else in this specification is normative.

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in the normative parts of this document are to be interpreted as described in [[!RFC2119]]. For readability, these words do not appear in all uppercase letters in this specification.

To help with layering and to avoid circular dependencies between various parts of specification, this document consists of three consecutive narratives:

setting up the stage for the specification,
explaining of the conceptual model and algorithms behind it, and
expressing this model with DOM interfaces and HTML elements.

In a sense, these parts can be viewed as math, which sets up the reasoning environment, physics, which is the theoretical reasoning about the concept, and mechanics, which is the practical application of this reasoning.

Any point, at which a conforming UA must make decisions about the state or reaction to the state of the conceptual model, is captured as algorithm. The algorithms are defined in terms of processing equivalence. The processing equivalence is a constraint imposed on the algorithm implementors, requiring the output of the both UA-implemented and the specified algorithm to be exactly the same for all inputs.

Concepts

Introduction

See the Shadow DOM 101 as a non-normative introduction.

Shadow trees

A document tree is a node tree [[!DOM]] whose root node is a document.

Any element can host zero or one associated node trees, called a shadow tree.

A shadow host is an element that hosts one shadow tree.

A shadow tree has an associated flag, called an encapsulation mode, which is either open or closed.

A shadow root is the root node of a shadow tree.

A node A is called a deep child of a node B, if either A is a child of B or A is the root node of the shadow tree that B hosts.

A node A is called a deep descendant of a node B, if either A is a deep child of B or A is a deep child of a node C that is a deep descendant of B.

An inclusive deep descendant is a node or one of its deep descendants.

A node A is called a deep parent of a node B if and only if B is a deep child of A.

A node A is called a deep ancestor of a node B if and only if B is a deep descendant of A.

An inclusive deep ancestor is a node or one of its deep ancestors.

When an element is an inclusive deep descendant of a document element, it is in a document deeply.

Trees of trees

A tree of trees is a tree of node trees.

The purpose of introducing a tree of trees here is to define algorithms easily in the following sections. This is a kind of a notation techchique to make the this specification simpler.

Just like a node tree is defined as a set of relationships between nodes, a tree of trees is similarly defined as a set of relationships between node trees:

A node tree A is called a parent tree of a node tree B if B is a shadow tree and the shadow host which hosts B partitipates in A.
If there is more than one node tree that shares the same parent tree, the tree order between them in the tree of trees is defined as follows:
1. Let A and B be node trees that share the same parent tree.
2. A comes before B if the shadow host which hosts A is preceding the shadow host which hosts B.
Other relationships and terms, such as root tree, child tree, descendant tree, inclusive descendant tree, ancestor tree, inclusive ancestor tree, preceding tree are defined in the similar way as defined in trees.

A node tree A is called an unclosed tree of a node tree B if and only if one, at least, of the following conditions is satisfied:

A is an inclusive ancestor tree of B.
The encapsulation mode of A is open and A is a child tree of B.
A is an unclosed tree of a node tree C that is an unclosed tree of B.

A node A is called an unclosed node of a node B if and only if the node tree that A participates in is an unclosed tree of the node tree that B participates in.

The ownerDocument property of a node in a shadow tree must refers to the document of the shadow host which hosts the shadow tree.

Window object named properties [[!HTML]] must access the nodes in the document tree.

Example tree of trees

A tree of trees.

In the figure, there are six node trees, named A, B, C, D, E and F. The shadow trees, B, C and D, are hosted by elements which participate in the document tree A. The shadow trees, E and F, are hosted by elements which participates in the shadow tree D. The following set of relationships holds in the figure:

The ordered list of A's child trees is [B, C, D].
The ordered list of B's child trees is [].
The ordered list of C's child trees is [].
The ordered list of D's child trees is [E, F].
The ordered list of E's child trees is [].
The ordered list of F's child trees is [].
The document tree, A, is the root tree of the tree of trees.

As for a relationship between nodes, it's worth mentioning that there is no ancestor/descendant relationships between two nodes if they participate in different node trees. A shadow root is not a child node of the shadow host. The parent node of a shadow root doesn't exist. Because of this nature, most of existing APIs are scoped and don't affect other node trees, even though they are forming one tree of trees. For example, document.getElementById(elementId) never returns an element in a shadow tree, even when the element has the given elementId.

The same thing also applies to CSS Selectors matching. For example, a descendant combinator never descends into a node in a child shadow tree because a shadow root is not a child node of the shadow host. Unless a special CSS Selector for Shadow DOM, which is mentioned later, is used, a CSS Selector never matches an element in a different node tree.

Because ShadowRoot inherits DocumentFragment, as specified later, you can use ShadowRoot.getElementByID(elementId) to get a node in the shadow tree.

Composed trees

A composed tree is a node tree which is constructed out of nodes from multiple node trees in a tree of trees. The exact algorithm of constructing a composed tree is specified later.

A composed tree

If an element doesn't participate in a composed tree whose root node is a document, the element must not appear in the formating structure [[!CSS21]] nor create any CSS box. This behavior must not be overridden by setting the 'display' property.

In resolving CSS inheritance, an element must inherit from the parent node in the composed tree, if applicable.

The editor's draft of CSS Scoping specification [[css-scoping-1]] defines the selectors which are related to Shadow DOM. For those who would search this Shadow DOM specifaction with the name of these selectors, mentioning these selectores here:

:shadow pseudo element
/deep/ combinator, which was replaced with a >>> combinator (or shadow piecing descendant combinator)
::content pseudo-element
:host-context() functional pseudo-class

Distributions

Insertion Points

An insertion point is a defined location where nodes in a different node tree appear instead of the nodes's original position when constructing a composed tree.

A distribution

A distribution is the mechanism that determines which nodes appear at each insertion point. The exact algorithm of a distribution is specified later.

Content Insertion Points

A content insertion point is an insertion point to where the child nodes of the shadow host are distributed. The content element that satisfies all of the following conditions represents a content insertion point:

The root node of the content element is a shadow root
There is no other content element in the ancestors of the content element

Distribution Results

Each tree of trees has the distribution result which describes the result of distributions. The distribution result must be equivalent of the following:

Each insertion point has an ordered list, called distributed nodes, which consists of nodes which are distributed into the insertion point.
Each node that is not an insertion point has an ordered list, called destination insertion points, which consists of insertion points to where the node is distributed

An insertion point A is the final destination of a node B if A is the last item of the destination insertion points of B.

When a node A is distributed into an insertion point B, the following steps must happen:

Add A to the distributed nodes of B
Add B to the destination insertion points of A

One case that deserves special consideration is the situation when an insertion point is a child node of another shadow host. In such situations, the nodes distributed into that insertion point appear as if they were child nodes of the shadow host in the context of distribution. Thus, the nodes distributed to a shadow tree could have already been distributed from its parent tree.

Despite being distributed to more than one insertion point, a node still only appears once in the composed tree at the final destination.

A re-distribution. In the figure, a node child 1 is distributed into insertion point 1. Then child1 is re-distributed into insertion point 3. The destination insertion points of child 1 is [insertion point 1, insertion point 3] and insertion point 3 is the final destination of child 1. The distributed nodes of insertion point 1 and insertion point 3 is [child 1] and [child 1, child 3], respectively.

Distribution Algorithms

The distribution algorithm must be used to determine the distribution result for a tree of trees and must be equivalent to processing the following steps:

Input: TREE-OF-TREES, a tree of trees
Output: The distribution result of TREE-OF-TREES is updated

Let all distributed nodes and destination insertion points owned by nodes in TREE-OF-TREES be empty
Let ROOT-TREE be the root tree of TREE-OF-TREES
Run the distribution resolution algorithm with ROOT-TREE as input

The distribution resolution algorithm must be used to determine the distribution result for a given node tree and its descendant trees, and must be equivalent to processing the following steps:

Input: NODE-TREE, a node tree
Output: The distribution result is updated for the inclusive descendant trees of NODE-TREE

For each shadow host, SHADOW-HOST, which participates in NODE-TREE, in tree order:
1. Let POOL be the result of the pool population algorithm with SHADOW-HOST as input
2. Let SHADOW-TREE be the shadow tree which SHADOW_HOST hosts
3. Run the pool distribution algorithm with SHADOW-TREE and POOL as input
4. Run the distribution resolution algorithm, recursively, with SHADOW-TREE as input

The pool population algorithm must be used to populate nodes from the child nodes of a given node and must be equivalent to processing the following steps:

Input: NODE, a node
Output: POOL, an ordered list of nodes

Let POOL be an empty ordered list.
For each child node, CHILD, of NODE:
1. If CHILD is an insertion point:
  1. Add all nodes in the distributed nodes of CHILD to POOL
2. Otherwise:
  1. Add CHILD to POOL

The pool distribution algorithm must be used to distribute nodes in a pool into the content insertion points in a shadow tree and must be equivalent to processing the following steps:

Input: SHADOW-TREE, a shadow tree; POOL, an ordered list of nodes
Output: Nodes in POOL are distributed into the content insertion points in the tree.

For each content insertion point, CONTENT, which participates in SHADOW-TREE, in tree order:
1. For each node, NODE, in POOL
  1. If NODE satisfies CONTENT's matching criteria:
    1. Distribute NODE into CONTENT
    2. Remove NODE from POOL
2. If no nodes are distributed to CONTENT:
  1. For each child, CHILD, of CONTENT
    1. Distribute CHILD into CONTENT

If no nodes are distributed into a content insertion point CONTENT, the child nodes of CONTENT are distributed into CONTENT as fallback nodes.

If any condition which affects the distribution result changes, the distribution result must be updated before any use of the distribution result.

Satisfying Matching Criteria

The matching criteria for an insertion point is a set of compound selectors [[!SELECTORS4]]. These compound selectors are restricted to contain only these simple selectors:

A type selector or a universal selector
class selector(s)
An ID selector
attribute selector(s)
A negation pseudo-class, :not()

A node satisfies a matching criteria only if:

all compound selectors in the set, contain only the simple selectors specified above; and
a node matches at least one compound selectors in the set or the set is empty.

Composition

The composed tree children calculation algorithm must be used to determine the child nodes of a node in the composed tree and must be equivalent to processing the following steps:

Input: NODE, a node which participates in a composed tree
Output: CHILDREN, the child nodes of NODE in the composed tree.

Let CHILDREN be an empty ordered list of nodes
If NODE is a shadow host:
1. Let CHILD-POOL be the children of the shadow root which NODE hosts.
Otherwise:
1. Let CHILD-POOL be the child nodes of NODE
For each node, CHILD, in CHILD-POOL:
1. If CHILD is an insertion point:
  1. For each node, DISTRIBUTED-NODE, in the distributed nodes of the insertion point CHILD:
    1. If CHILD is the final destination of DISTRIBUTED-NODE, add DISTRIBUTED-NODE to CHILDREN
2. Otherwise:
  1. Add CHILD to CHILDREN

For a given tree of trees TREE-OF-TREES, the composed tree constructed from TREE-OF-TREES must be equivalent to the following tree:

The root node of the composed tree is the root node of the root tree of TREE-OF-TREES.
For a given node which participates in the composed tree, the child nodes of the node is the result of the composed tree children calculation algorithm with the node as input.

Events

In each algorithm in this section, the Window must be considered as if it were the parent node of the Document so that the Window also receives an event.

When an event is dispatched in a shadow tree, its path either crosses the shadow trees or is terminated at the shadow root. One exception are the mutation events. The mutation event types must never be dispatched in a shadow tree.

Changes to Dispatching Events

Insert the following item after item 3 of Constructing events:

Initialize event's scoped flag as defined in Events that are not leaked into ancestor trees.

The item 4 of Dispatching events is changed to:

If event’s target attribute value is participating in a tree, let event path be the output of the event path calculation algorithm with target and event as inputs ~~a static ordered list of all its ancestors in tree order~~, and let event path be the empty list otherwise.

Events that are not leaked into ancestor trees

For the following events, scoped flag is initialized to true by default if the events are dispatched by the user agent:

abort
error
select
change
load
reset
resize
scroll
selectstart

Upstream this section into relevant specs, instead of having a fixed list here.

Event Paths

The event path calculation algorithm must be used to determine event path and must be equivalent to processing the following steps:

Input: NODE, a node; EVENT, an event
Output: PATH, an event path, a ordered list of an event target

Let PATH be the empty ordered list of nodes
Let CURRENT be NODE
Repeat while CURRENT exists:
1. Append CURRENT to PATH
2. If the destination insertion points of CURRENT is not empty:
  1. Append each insertion point in the destination insertion points of CURRENT, from the first, inclusive, to the last, exclusive, to PATH
  2. Let CURRENT be the final destination of CURRENT
3. Otherwise if all of the following conditions are satisfied, stop this algorithm:
  1. CURRENT is a shadow root
  2. CURRENT is the root node of NODE
  3. EVENT's scoped flag is set
4. Otherwise:
  1. Let CURRENT be the deep parent of CURRENT

For a trusted event that has a relatedTarget attribute, the event path would be trimmed. See the event path trimming algorithm, which is specified later.

Event Paths Example

Suppose we have the following tree of trees:

An example tree of trees. Nodes which are not involved in the example event path, which is explained later, are omitted.

A is a document.
E, J, N, Q and S are shadow roots.
I, M, P, R and U are content insertion points.

This tree of trees has the following 6 node trees, 1 document tree and 5 shadow trees:

The document tree 1. Node A, B, C and D participate in that.
The shadow tree 2 hosted by B. Node E, F, G, H and I participate in that.
The shadow tree 3 hosted by H. Node J, K, L and M participate in that.
The shadow tree 4 hosted by K. Node N, O and P participate in that.
The shadow tree 5 hosted by O. Node Q and R participate in that.
The shadow tree 6 hosted by F. Node S, T and U participate in that.

Let's assume that the distribution result of this tree of trees is:

The destination insertion points of C are [I, M] (C is re-distributed)
The destination insertion points of L are [P, R] (L is re-distributed)
The destination insertion points of G are [U]

In this case, if an event is dispatched on node D, the event path will be:

[D, C, I, M, L, P, R, Q, O, N, K, J, H, G, U, T, S, F, E, B, A] (Window is omitted)

Note that the event path calculation algorithm is designed to achieve the following goals:

If there is a node, CHILD, in the event path and CHILD has a parent node, PARENT, in the node tree, the event path also includes PARENT. PARENT always appears somewhere after CHILD in the event path.
Nodes in the event path form a linear ancestor chain in each node tree. There are no branch points in each node tree.

The relationship between an event path and node trees. In the figure, a number shown in a left-side of each node represents a zero-based position of each node in the event path. A parent node always has a larger number than that of its child node in each node tree.

That means if we focus on one node tree and forget all other node trees, the event path would be seen as if the event happened only on the node tree which we are focused on. This is an important aspect in a sense that hosting shadow trees doesn't have any effect to the event path within the node tree the shadow host participate in as long as the event is not stopped somewhere in the descendant trees.

For example, from the view of the document tree 1, the event path would be seen as [D, C, B, A]. From the view of the shadow tree 2, the event path would be seen as [I, H, G, F, E]. The similar things also apply to other node trees.

It is also worth pointing out that if we exclude all insertion points and shadow roots from an event path, the result would be equivalent to the inclusive ancestors of the node on which the event is dispatched, in the composed tree.

The relationship between an event path and the composed tree. The event path used in the example is shown in the left-hand side and the composed tree is shown in the right-hand side. If we exclude all insertion points and shadow roots from the event path, the result would be equivalent to the inclusive ancestors of the node, D, in the composed tree.

Event Retargeting

In the cases where event path is across multiple node trees, the event's information about the target of the event is adjusted in order to maintain encapsulation. Event retargeting is a process of computing relative targets for each ancestor of the node at which the event is dispatched. A relative target is a node that most accurately represents the target of a dispatched event at a given ancestor while maintaining the encapsulation.

The retargeting algorithm is used to determine relative targets and must be equivalent to processing the following steps:

Input: BASE, a base node for which a target node should be adjusted; TARGET, a target node which should be adjusted
Output: RELATIVE-TARGET, a relative target, the result of adjusting TARGET for BASE

Let BASE-TREE be the node tree which BASE participates in
Let TARGET-TREE be the node tree which TARGET participates in
If BASE-TREE and TARGET-TREE participate in the same tree of trees:
1. Let COMMON-ANCESTOR-TREE be the lowest common inclusive ancestor tree of BASE-TREE and TARGET-TREE
Otherwise:
1. Let COMMON-ANCESTOR-TREE be the root tree of TARGET-TREE
For each node, ANCETOR, in an inclusive deep ancestor nodes of TARGET, from descendants to ancestors:
1. If ANCESTOR participates in COMMON-ANCESTOR-TREE:
  1. Let RELATIVE-TARGET be ANCESTOR
  2. Stop this algorithm

The value of the Event object's target attribute must be the result of the retargeting algorithm with the event's currentTarget and target as input.

The event target retargeting process must occur prior to dispatch of an event.

Retargeting `relatedTarget`

Some events have a relatedTarget [[!DOM-Level-3-Events]] property, which holds a node that's not the event's target, but is related to the event.

For instance, a mouseover event's relatedTarget may hold the node from which the mouse has moved to event's target. In the case where relatedTarget is in a shadow tree, the conforming UAs must not leak its actual value outside of this tree.

The value of the Event object's relatedTarget attribute must be the result of the retargeting algorithm with the event's currentTarget and relatedTarget as input. The result is called a relative related target.

The event relatedTarget retargeting process must occur prior to dispatch of an event.

Retargeting Touch Events

The Touch target [[!TOUCH-EVENTS]] attribute must be adjusted in the same way as an event with a relatedTarget. Each Touch target in the TouchList returned from TouchEvent touches(), changedTouches() and targetTouches() must be the result of the retargeting algorithm with a current target and Touch target as input.

Retargeting Focus Events

The focus, DOMFocusIn, blur, and DOMFocusOut events must be treated in the same way as events with a relatedTarget, where the corresponding node that is losing focus as a result of target gaining focus or the node that is gaining focus, and thus causing the blurring of target acts as the related target.

Event Path Trimming

In cases where both relatedTarget and target of a trusted event are part of the same shadow tree, the conforming UAs must stop events at the shadow root to avoid the appearance of spurious mouseover and mouseout events firing from the same node.

Thus, event listeners for trusted events must not be invoked on a node for which the target and relatedTarget are the same.

The event path trimming algorithm must be used to trim the event path for a trusted event that has a relatedTarget attribute and must be equivalent to processing the following steps:

Input: EVENT-PATH, the event path, which is the result of the event path calculation algorithm
Output: EVENT-PATH is trimmed so that event listeners aren't invoked on a node for which the target and relatedTarget are the same.

For each object, A, in EVENT-PATH:
1. Let RELATIVE-TARGET be the relative target for A
2. Let RELATIVE-RELATED-TARGET be the relative related target for A
3. If RELATIVE-TARGET and RELATIVE-RELATED-TARGET are the same, remove A from EVENT-PATH.

For an untrusted event, the event path trimming algorithm is not used.

Event Dispatch

At the time of event dispatch:

The MouseEvent offsetX and offsetY attributes must return the coordinates relative to the origin of the padding edge of the relative target
When capturing, which entails processing step 6 of the event dispatch algorithm, the event listeners must not be invoked on a node if it is the same as its relative target
When bubbling, which entails processing step 9 of the event dispatch algorithm, the Event eventPhase attribute must return AT_TARGET if the relative target is same as the node on which event listeners are invoked
If the event's bubbles attribute value is false, run these substeps:
1. Reverse the order of event path
2. Initialize event's eventPhase attribute to AT_TARGET
3. For each object in event path where the relative target is same as the object, invoke its event listeners, with event event, as long as event's stop propagation flag is unset

Upon completion of the event dispatch, the Event object's target and relatedTarget must be to the highest ancestor's relative target. Since it is possible for a script to hold on to the Event object past the scope of event dispatch, this step is necessary to avoid revealing the nodes in shadow trees.

Event Retargeting Example

Suppose we have a user interface for a media controller, represented by this tree, composed of both document tree and the shadow trees. In this example, we will assume that selectors are allowed to cross the shadow boundaries and we will use these selectors to identify the elements. Also, we will invent a fictional shadow-root element to demarcate the shadow boundaries and represent shadow roots:

<div id="player">
    <shadow-root id="player-shadow-root">
        <div id="controls">
            <button id="play-button">PLAY</button>
            <input type="range" id="timeline">
                <shadow-root id="timeline-shadow-root">
                    <div id="slider-thumb" id="timeline-slider-thumb"></div>
                </shadow-root>
            </input>
            <div id="volume-slider-container">
                <input type="range" id="volume-slider">
                    <shadow-root id="volume-shadow-root">
                        <div id="slider-thumb" id="volume-slider-thumb"></div>
                    </shadow-root>
                </input>
            </div>
        </div>
    </shadow-root>
</div>

Let's have a user position their pointing device over the volume slider's thumb (#volume-slider-thumb), thus triggering a mouseover event on that node. For this event, let's pretend it has no associated relatedTarget.

Per the retargeting algorithm, we should have the following set of ancestors and relative targets:

Ancestor	Relative Target
`#player`	`#player`
`#player-shadow-root`	`#volume-slider`
`#controls`	`#volume-slider`
`#volume-slider-container`	`#volume-slider`
`#volume-slider`	`#volume-slider`
`#volume-shadow-root`	`#volume-slider-thumb`
`#volume-slider-thumb`	`#volume-slider-thumb`

After we dispatch the mouseover event using these newly computed relative targets, the user decides to move their pointing device over the thumb of the timeline (#timeline-slider-thumb). This triggers both a mouseout event for the volume slider thumb and the mouseover event for the timeline thumb.

Let's see how the relatedTarget value of the volume thumb's mouseout event is affected. For this event, the relatedTarget is the timeline thumb (#timeline-slider-thumb). Per the relatedTarget retargeting, we should have the following set of ancestors and adjusted related targets:

Ancestor	Relative Target	Adjusted related Target
`#player`	`#player`	`#player`
`#player-shadow-root`	`#volume-slider`	`#timeline`
`#controls`	`#volume-slider`	`#timeline`
`#volume-slider-container`	`#volume-slider`	`#timeline`
`#volume-slider`	`#volume-slider`	`#timeline`
`#volume-shadow-root`	`#volume-slider-thumb`	`#timeline`
`#volume-slider-thumb`	`#volume-slider-thumb`	`#timeline`

The node, #player, has both target and relatedTarget being the same value (#player), which means that we do not dispatch the event on this node and its ancestors.

User Interaction

Ranges and Selections

Selection [[!EDITING]] is not defined. Implementation should do their best to do what's best for them. Here's one possible, admittedly naive way:

Since nodes which are in the different node trees never have the same root, there may never exist a valid DOM range that spans multiple node trees.

Accordingly, selections may only exist within one node tree, because they are defined by a single range. The selection, returned by the window.getSelection() method never returns a selection within a shadow tree.

The getSelection() method of the shadow root object returns the current selection in this shadow tree.

Focus Navigation

If a node doesn’t participate in the composed tree, the node must be skipped from the navigation order [[!CSS3UI]] sequence.

For sequential focus navigation, the navigation order sequence for a given shadow tree A must be inserted into the navigation order for the parent tree B as follow:

Let HOST be the shadow host which hosts A
The navigation order for A must be inserted into the navigation order for B:
1. immediately after HOST, if HOST is focusable; or
2. in place of the HOST as if HOST were assigned the value of auto for determining its position.

For directional focus navigation, it is up to the user agent to integrate the navigation orders for shadow trees into the document navigation order.

Active Element

To maintain encapsulation, the value of the Document object's focus API property activeElement must be adjusted. To prevent loss of information when adjusting this value, each shadow root must also have an activeElement property to store the value of the focused element in the shadow tree.

The active element adjustment algorithm must be used to determine the value of activeElement property, and it must be equivalent to processing the following steps:

Input: ROOT, either a document or a shadow root; ELEMENT, the focused element
Output: ADJUSTED, an adjusted activeElement property of ROOT.

Let ADJUSTED be the result of the retargeting algorithm with ROOT and ELEMENT as input

Editing

The value of the contenteditable attribute must not propagate from shadow host to its shadow trees.

Assistive Technology

User agents with assistive technology traverse the composed tree, and thus enable full use of WAI-ARIA [[!WAI-ARIA]] semantics in the shadow trees.

HTML Elements in Shadow Trees

Inertness of HTML Elements in a shadow tree

Comparatively, a shadow tree can be seen as somewhere between just part of a document and itself being a document fragment. Since it is rendered, a shadow tree aims to retain the traits of a typical tree in a document. At the same time, it is an encapsulation abstraction, so it has to avoid affecting the document tree. Thus, the HTML elements must behave as specified [[!HTML]] in the shadow trees, with a few exceptions.

According to the [[!HTML]], some HTML Elements would have different behavior if they participate in a shadow tree, instead of a document tree, because their definitions require the elements to be in a document as a necessary condition for them to work. In other words, they shouldn't work if they participate in a shadow tree, even when they are in a document deeply. We must fill this gap because we expect that most of HTML Elements behave in the same way as in a document, as long as they are in a document deeply. See W3C Bug 26365 and Bug 27406 for the details. The following is the tentative summary of the discussions in the W3C bugs. We, however, haven't covered all HTML Elements and their behaviors here yet. For HTML Elements which are not explicitly stated here, they should be considered as active in a shadow tree. We are trying to update [[!HTML]] itself, instead of having monkey patches here.

HTML Elements are classified into the following categories:

Active in a shadow tree

A subset of HTML elements which must behave as if they were in the document tree, even when they participate in a shadow tree, as long as they are in a document deeply.

The following HTML elements must be classified to this category:
- dialog
- iframe
- style
Inert in a shadow tree:

A subset of HTML elements which must behave as inert, or not part of the document tree, if they participate in a shadow tree. This is consistent how the HTML elements would behave in a document fragment.

The following HTML elements must be classified to this category:
- base
- link
Inert unless being rendered:

A subset of HTML elements which must behave as inert, or not part of the document tree, unless they are being rendered. In other words, if they don't particitpate in a composed tree whose root node is a document, they must behave as inert.

The following HTML elements must be classified to this category:
- applet
- embed
- object
For example, suppose that an object element is a child node of a shadow host, but the object element's destination insertion points is empty. In this case, according to the distribution algorithm and composed tree children calculation algorithm, this element never participate in a composed tree whose root node is a document. Therefore, this element is inert because this element is not being rendered. .

Attributes

When [[!HTML]] defines the processing algorithms to traverse trees for the following attributes, they must use the composed tree.

dir
draggable
dropzone
hidden
lang and xml:lang
spellcheck
title

This list does not include attributes that are defined elsewhere in this specification. Such attributes include:

tabindex is defined in Focus Navigation.
role and ARIA are defined in Assistive Technology.

Elements and DOM interfaces

The `ShadowRoot` interface

The ShadowRoot interface represents the shadow root.

Selection? getSelection()

Returns the current selection in the shadow tree.

When invoked, it must return the selection in the shadow tree.

Element? elementFromPoint(double x, double y)

Returns an element at specified coordinates.

Eventually, this needs to be part of CSSOM View Module specification [[!CSSOM-VIEW]]. See also W3C bug 27829.

When invoked, it must return result of running the following steps:

If context object is not a ShadowRoot instance, throw an InvalidNodeTypeError.
If either argument is negative, x is greater than the viewport width excluding the size of a rendered scroll bar (if any), or if y is greater than the viewport height excluding the size of a rendered scroll bar (if any), return null.
Let HIT be the element at coordinates x and y in the viewport, determined through hit testing
Let PATH be the result of running the event path calculation algorithm with HIT and null as input
Return the result of running the retargeting algorithm with PATH and context object as input

sequence<Element> elementsFromPoint(double x, double y)

It could be defined in roughly the same way as elementFromPoint. Eventually, this needs to be part of CSSOM View Module specification [[!CSSOM-VIEW]]. See also W3C bug 27829.

CaretPosition? caretPositionFromPoint(double x, double y)

It could be defined in roughly the same way as caretPositionFromPoint [[!CSSOM-VIEW]]. Eventually, this needs to be part of CSSOM View Module specification [[!CSSOM-VIEW]]. See also W3C bug 27829.

readonly attribute Element? activeElement

Represents the currently focused element in the shadow tree.

On getting, the attribute must return the currently focused element in the shadow tree or null, if there is none.

readonly attribute Element host

Represents the shadow host which hosts the context object.

On getting, the attribute must return the shadow host which hosts the context object.

[TreatNullAs=EmptyString] attribute DOMString innerHTML

Represents the markup of ShadowRoot's contents.

On getting, the attribute must return the result of running the HTML fragment serialization algorithm with the context object as shadow host.

On setting, these steps must be run:

Let FRAGMENT be the result of invoking the fragment parsing algorithm [[!DOM-PARSING]] with the new value as MARKUP, and the context object as shadow host
Replace all with FRAGMENT within the shadow root.

readonly attribute StyleSheetList styleSheets

Represents the shadow root style sheets.

On getting, the attribute must return a StyleSheetList sequence containing the shadow root style sheets.

The nodeType attribute of a ShadowRoot instance must return DOCUMENT_FRAGMENT_NODE. Accordingly, the nodeName attribute of a ShadowRoot instance must return "#document-fragment".

Invoking the cloneNode() method on a ShadowRoot instance must always throw a DATA_CLONE_ERR exception.

Extensions to `Element` Interface

ShadowRoot createShadowRoot(ShadowRootInit shadowRootInitDict)

When invoked, these steps must be run:

If the context object is an element which has a binding property, throws NotSupportedError exception.
If the context object already hosts the shadow tree, throws InvalidStateError exception.
Create a new instance of the ShadowRoot object. The shadowRootInitDict argument allows for setting the encapsulation mode.
Let the content object host the ShadowRoot object.
Return ShadowRoot object.

NodeList getDestinationInsertionPoints()

When invoked, the method must return a static NodeList consisting of unclosed insertion points of the context object in the destination insertion points of the context object.

readonly attribute ShadowRoot? shadowRoot

Represents the shadow root that context object hosts.

On getting, the attribute must return the shadow root that context object hosts if there is and it is open. Otherwise must return null.

`ShadowRootInit` dictionary

ShadowRootMode mode: Specifies the encapsulation mode of ShadowRoot

`ShadowRootMode` enum

open: Specifies open encapsulation mode
closed: Specifies closed encapsulation mode

Extensions to `Text` Interface

NodeList getDestinationInsertionPoints(): When invoked, the method must return a static NodeList consisting of insertion points in the destination insertion points of the context object, excluding an insertion point which participates in a closed shadow tree.

The `content` element

The content element represents an insertion point in the shadow tree.

If a content element does not satisfy the condition of an insertion point, it must have the same rendering behavior as the HTMLUnknownElement.

Context

Where flow content is expected.

Content model

Transparent

Children

Anything as fallback content

Content attributes

Global attributes

select, a set of comma-separated tokens: Represents the matching criteria for distributing child nodes of the shadow host. Each token must be a compound selector.

DOM Interface

attribute DOMString select

Must reflect the select attribute.

sequence<Node> getDistributedNodes()

When invoked, it must return result of running the following steps:

If the context object is a content insertion point:
1. Return a sequence consisting of nodes in the distributed nodes of the context object.
Otherwise:
1. Return an empty sequence.

Extensions to `EventInit` Dictionary

boolean scoped = false: Specifies the scoped flag of Event

Extensions to `Event` Interface

readonly attribute object deepPath

Represents the event path.

On getting, the attribute must create and return a new JavaScript Array object, that must be equivalent to processing the following steps:

Input: EVENT, a context object
Output: PATH, an array of nodes

If EVENT hasn't been dispatched, return a new empty array.
Otherwise:
1. Let PATH be the event path of EVENT.
2. If EVENT is being dispatched:
  1. Let CURRENT-TARGET be the current target of EVENT.
3. Otherwise:
  1. Let CURRENT-TARGET be the last node of PATH.
4. Let PATH contain only a node which is an unclosed node of CURRENT-TARGET.

The API is not stable and may change. Use FrozenArray as the return type of the deepPath attribute in WebIDL. See Issue #101

readonly attribute boolean scoped

Returns the scoped flag.

Shadow DOM Example

Bob was asked to turn a simple list of links into a News Widget, which has links organized into two categories: breaking news and just news. The current document markup for the stories looks like this:

<ul class="stories">
    <li><a href="//example.com/stories/1">A story</a></li>
    <li><a href="//example.com/stories/2">Another story</a></li>
    <li class="breaking"><a href="//example.com/stories/3">Also a story</a></li>
    <li><a href="//example.com/stories/4">Yet another story</a></li>
    <li><a href="//example.com/stories/4">Awesome story</a></li>
    <li class="breaking"><a href="//example.com/stories/5">Horrible story</a></li>
</ul>

To organize the stories, Bob decides to use shadow DOM. Doing so will allow Bob to keep the document markup uncluttered, and harnessing the power of insertion point makes sorting stories by class name a very simple task. After getting another cup of Green Eye, he quickly mocks up the following shadow tree, to be hosted by the ul element:

<div class="breaking">
    <ul>
        <content select=".breaking"></content> <!-- insertion point for breaking news -->
    </ul>
</div>
<div class="other">
    <ul>
        <content></content> <!-- insertion point for the rest of the news -->
    </ul>
</div>

Bob then styles the newborn widget according to comps from the designer by adding this to the shadow tree mockup:

<style>
    div.breaking {
        color: Red;
        font-size: 20px;
        border: 1px dashed Purple;
    }
    div.other {
        padding: 2px 0 0 0;
        border: 1px solid Cyan;
    }
</style>

While pondering if his company should start looking for a new designer, Bob converts the mockup to code:

function createStoryGroup(className, contentSelector)
{
    var group = document.createElement('div');
    group.className = className;
    // Empty string in select attribute or absence thereof work the same, so no need for special handling.
    group.innerHTML = '<ul><content select="' + contentSelector + '"></content></ul>';
    return group;
}

function createStyle()
{
    var style = document.createElement('style');
    style.textContent = 'div.breaking { color: Red;font-size: 20px; border: 1px dashed Purple; }' +
        'div.other { padding: 2px 0 0 0; border: 1px solid Cyan; }';
    return style;
}

function makeShadowTree(storyList)
{
    var root = storyList.createShadowRoot({mode: 'open'});
    root.appendChild(createStyle());
    root.appendChild(createStoryGroup('breaking', '.breaking'));
    root.appendChild(createStoryGroup('other', ''));
}

document.addEventListener('DOMContentLoaded', function() {
    [].forEach.call(document.querySelectorAll('ul.stories'), makeShadowTree);
});

Well done, Bob! With the cup of coffee still half-full, the work is complete. Recognizing his awesomeness, Bob returns to teaching n00bs the ways of Puyo Puyo.

A few months pass.

It's election time. With Bob at his annual conference, Alice is charged with adding another, temporary box to the news widget, filled with election-related stories. Alice studies Bob's code, reads up on the shadow DOM spec and realizes that, thanks to multiple shadow tree support, she doesn't have to touch his code. As usual, her solution is elegant and simple, fitting neatly right under Bob's code:

// TODO(alice): BEGIN -- DELETE THIS CODE AFTER ELECTIONS ARE OVER.
var ELECTION_BOX_REMOVAL_DEADLINE = ...;

function createElectionStyle()
{
    var style = document.createElement('style');
    // TODO(alice): Check designer's desk for hallucinogens.
    style.textContent = 'div.election { color: Magenta; font-size: 24px; border: 2px dotted Fuchsia; }';
    return style;
}

function makeElectionShadowTree(storyList)
{
    var root = storyList.createShadowRoot({mode: 'open'});
    // Add and style election story box.
    root.appendChild(createElectionStyle());
    root.appendChild(createStoryGroup('election', '.election'));
    // Insert Bob's shadow tree under the election story box.
    root.appendChild(document.createElement('shadow'));
}

if (Date.now() < ELECTION_BOX_REMOVAL_DEADLINE) {
    document.addEventListener('DOMContentLoaded', function() {
        [].forEach.call(document.querySelectorAll('ul.stories'), makeElectionShadowTree);
    });
}
// TODO(alice): END -- DELETE THIS CODE AFTER ELECTIONS ARE OVER.

Using the shadow element allows Alice to compose Bob's widget inside of hers—without having to change a line of production code. Smiling to herself, Alice realizes that Bob may have come up with a way to keep the document markup clean, but she is the one who takes the cake for using shadow tree composition in such a cool way.