Shadow DOM: Specification
Andrei Glazkov, Ito Hayato from Google, as well as other experts on Github, are working on drafting the Shadow DOM specification. A lot of work has already been done, but much remains to be done. As part of supporting work in this area, a translation of the existing version of the specification of July 7 has been created.
This specification describes how to combine several DOM trees into one hierarchy, and the interaction of these trees with each other in one document, which allows you to build the DOM more correctly.
This specification describes how to combine several DOM trees into one hierarchy, and the interaction of these trees with each other in one document, which allows you to build the DOM more correctly.
1. Compliance
All diagrams, examples, notes, as well as sections clearly marked as non-normative are not normative. Everything else in this specification is normative.
In the original version of the specification, the keywords "should", "should not", "need", "will", "not be", "should", "should not", "recommended", "can" and "optionally" in normative Parts of this document should be interpreted as described in [RFC 2119] . For readability, these words are not used in upper case in the original of this specification.
To simplify references and in order to avoid circular dependencies between different parts of a specification, this document is composed of three consecutive parts:
')
1. Creating conditions for specification.
2. Explanation of the idea of the model and the algorithms underlying it.
3. Description of this model using DOM-interfaces and HTML-elements.
In a sense, these parts can be considered as mathematics, establishing the environment in which the model will operate, physics, describing how theoretically this model should work, and mechanics, showing how the model is put into practice.
Any point at which the corresponding client application must make state decisions or respond to the state of the conceptual model is described as an algorithm.
Algorithms are described in terms of uniformity of processing.
Uniformity of processing is a limitation imposed on the implementers of the algorithm, which is that the output for all algorithms implemented on the client and described in the specification must be absolutely identical for any input.
In the original version of the specification, the keywords "should", "should not", "need", "will", "not be", "should", "should not", "recommended", "can" and "optionally" in normative Parts of this document should be interpreted as described in [RFC 2119] . For readability, these words are not used in upper case in the original of this specification.
To simplify references and in order to avoid circular dependencies between different parts of a specification, this document is composed of three consecutive parts:
')
1. Creating conditions for specification.
2. Explanation of the idea of the model and the algorithms underlying it.
3. Description of this model using DOM-interfaces and HTML-elements.
In a sense, these parts can be considered as mathematics, establishing the environment in which the model will operate, physics, describing how theoretically this model should work, and mechanics, showing how the model is put into practice.
Any point at which the corresponding client application must make state decisions or respond to the state of the conceptual model is described as an algorithm.
Algorithms are described in terms of uniformity of processing.
Uniformity of processing is a limitation imposed on the implementers of the algorithm, which is that the output for all algorithms implemented on the client and described in the specification must be absolutely identical for any input.
2. Concepts
2.1 Introduction
This part is non-standard.
Shadow DOM 101 should be considered as a non-normative .
2.2 Shadow Trees
The document tree is a DOM node structure whose root element is a document.
The shadow tree has a corresponding flag for the encapsulation mode, which can be open or closed.
The shadow root is the root element of the shadow tree.
A node A is called a child (deep child) or a nested shadow root of node B, if A is a child node B or A is the root node of the shadow tree contained in B.
Node A is called a deep descendant of node B if A is a child or nested shadow root of node B or A is a child or nested shadow root of node C, which is in turn the deep descendant of node B.
The contained descendant (inclusive deep descendant) can be a node or one of its deep descendants.
A node A is called a deep parent of a node B only if B is a deep descendant of A.
Node A is called a deep ancestor (deep ancestor) of node B only if B is a deep descendant of A.
Inclusive deep ancestor - a node or one of its deep ancestors.
When an element is a contained descendant of an element of a document, it is in the document at the depth of that element.
2.3 Trees of trees
A tree of trees is a tree consisting of node trees.
The definition of the term “tree of trees” is given in this place in order to facilitate the definition of algorithms in the subsequent sections. This designation method should simplify this specification.
Just as a node tree can be represented as a set of relationships between these nodes, a tree of trees can be represented as a set of relationships between node trees.
● Tree A is the parent tree of tree B in case one of these conditions is satisfied:
1. A and B are next to each other in the same ordered list and tree A is the oldest in relation to B.
2. B is the most senior shadow tree and the leading element of the shadow tree B is also the leader for A.
● Other relationships and conditions, such as the root tree, the child tree, the descendant tree containing the descendant tree, the ancestor tree containing the ancestor tree, the preceding tree are defined in a manner similar to the definition of trees.
The property ownerDocument in the shadow tree must refer to the document of the host element containing this shadow tree.
The named properties of the Window object [HTML] must have access to the nodes in the document tree.
2.3.1 Example of a tree
This part is non-standard.
Fig. 1 Tree trees.
The figure shows 6 tree nodes with the names A, B, C, D, E, and F. The trees of nodes C, D, and B have a common leading element that is part of the node tree A. Shadow trees E and F have a common leading element, which is part of the node tree D.
The figure also shows the following relationships:
● The list of child trees of the tree A is [B, C, D].
● The list of child trees of tree B is [].
● The list of child trees of the C tree is [].
● The list of child trees of the tree D is [E, F].
● The list of child trees of the E tree is [].
● The list of child trees of the tree F is [].
● Document Tree A is the root tree of the tree of trees.
As for the relations between nodes, it is worth noting that there are no ancestor / descendant relations between two nodes if they consist of different node trees. The root element of a shadow tree is not a child of the host element of a shadow tree. There is no parent node for the root element of the shadow tree. For this reason, most existing APIs have their own scope, and do not affect other node trees, despite the fact that they form one tree of trees. For example, document.getElementById (elementId) will never return an element from the shadow tree, even if it has the specified elementId.
The same applies to the work of CSS selectors: a combined selector that descends down the DOM tree will not affect the elements of the shadow tree, because the root element of this tree is not a child node of its leading element. If a special CSS shadow DOM selector is used, which is mentioned later, it will not match an element in another node tree.
Because ShadowRoot inherits a DocumentFragment, as will be explained later, you can use ShadowRoot.getElementByID (elementId) to get a node from a shadow tree.
2.4 Composed trees
A composed tree is a tree of nodes constructed from nodes of several node trees in a tree. The exact algorithm for constructing such a tree will be given below.
Fig. 2 Composed tree
If the element is not part of a compiled tree whose root node is a document, this element should not appear in the formatting structure [CSS21] or create any block. This behavior should not be overridden by explicitly specifying the 'display' property.
When defining CSS inheritance rules, an element must inherit from the parent node in the composed tree, if applicable.
The working draft of the CSS Scoping specification [css-scoping-1] defines selectors related to the shadow model of the document. For those who will search for this specification of the shadow model of the document with these selectors, we denote these selectors here:
●: shadow pseudo-element
● / deep / combinator that was replaced by a combinator >>> (shadow combinator of partial descendants)
● :: content pseudo-element
●: host-context () functional pseudo-class
This part is non-standard.
Shadow DOM 101 should be considered as a non-normative .
2.2 Shadow Trees
The document tree is a DOM node structure whose root element is a document.
The shadow tree has a corresponding flag for the encapsulation mode, which can be open or closed.
The shadow root is the root element of the shadow tree.
A node A is called a child (deep child) or a nested shadow root of node B, if A is a child node B or A is the root node of the shadow tree contained in B.
Node A is called a deep descendant of node B if A is a child or nested shadow root of node B or A is a child or nested shadow root of node C, which is in turn the deep descendant of node B.
The contained descendant (inclusive deep descendant) can be a node or one of its deep descendants.
A node A is called a deep parent of a node B only if B is a deep descendant of A.
Node A is called a deep ancestor (deep ancestor) of node B only if B is a deep descendant of A.
Inclusive deep ancestor - a node or one of its deep ancestors.
When an element is a contained descendant of an element of a document, it is in the document at the depth of that element.
2.3 Trees of trees
A tree of trees is a tree consisting of node trees.
The definition of the term “tree of trees” is given in this place in order to facilitate the definition of algorithms in the subsequent sections. This designation method should simplify this specification.
Just as a node tree can be represented as a set of relationships between these nodes, a tree of trees can be represented as a set of relationships between node trees.
● Tree A is the parent tree of tree B in case one of these conditions is satisfied:
1. A and B are next to each other in the same ordered list and tree A is the oldest in relation to B.
2. B is the most senior shadow tree and the leading element of the shadow tree B is also the leader for A.
● Other relationships and conditions, such as the root tree, the child tree, the descendant tree containing the descendant tree, the ancestor tree containing the ancestor tree, the preceding tree are defined in a manner similar to the definition of trees.
The property ownerDocument in the shadow tree must refer to the document of the host element containing this shadow tree.
The named properties of the Window object [HTML] must have access to the nodes in the document tree.
2.3.1 Example of a tree
This part is non-standard.
Fig. 1 Tree trees.
The figure shows 6 tree nodes with the names A, B, C, D, E, and F. The trees of nodes C, D, and B have a common leading element that is part of the node tree A. Shadow trees E and F have a common leading element, which is part of the node tree D.
The figure also shows the following relationships:
● The list of child trees of the tree A is [B, C, D].
● The list of child trees of tree B is [].
● The list of child trees of the C tree is [].
● The list of child trees of the tree D is [E, F].
● The list of child trees of the E tree is [].
● The list of child trees of the tree F is [].
● Document Tree A is the root tree of the tree of trees.
As for the relations between nodes, it is worth noting that there are no ancestor / descendant relations between two nodes if they consist of different node trees. The root element of a shadow tree is not a child of the host element of a shadow tree. There is no parent node for the root element of the shadow tree. For this reason, most existing APIs have their own scope, and do not affect other node trees, despite the fact that they form one tree of trees. For example, document.getElementById (elementId) will never return an element from the shadow tree, even if it has the specified elementId.
The same applies to the work of CSS selectors: a combined selector that descends down the DOM tree will not affect the elements of the shadow tree, because the root element of this tree is not a child node of its leading element. If a special CSS shadow DOM selector is used, which is mentioned later, it will not match an element in another node tree.
Because ShadowRoot inherits a DocumentFragment, as will be explained later, you can use ShadowRoot.getElementByID (elementId) to get a node from a shadow tree.
2.4 Composed trees
A composed tree is a tree of nodes constructed from nodes of several node trees in a tree. The exact algorithm for constructing such a tree will be given below.
Fig. 2 Composed tree
If the element is not part of a compiled tree whose root node is a document, this element should not appear in the formatting structure [CSS21] or create any block. This behavior should not be overridden by explicitly specifying the 'display' property.
When defining CSS inheritance rules, an element must inherit from the parent node in the composed tree, if applicable.
The working draft of the CSS Scoping specification [css-scoping-1] defines selectors related to the shadow model of the document. For those who will search for this specification of the shadow model of the document with these selectors, we denote these selectors here:
●: shadow pseudo-element
● / deep / combinator that was replaced by a combinator >>> (shadow combinator of partial descendants)
● :: content pseudo-element
●: host-context () functional pseudo-class
3. Distributions
3.1 Points of Inclusion
The point of inclusion is the place where the nodes appear in another node tree instead of their original position when building a composed tree.
Fig. 3 Distribution
Distribution is a mechanism that determines which nodes appear at which switching point. A detailed distribution algorithm will be described later.
3.2 Content inclusion points
Content inclusion points are the inclusion points to which the child nodes of the leading shadow element are distributed. A content element that satisfies the following conditions is a content inclusion point:
● The root node of the content item is the root node of the shadow tree
● There are no other content elements among the ancestors of the content item.
3.3 Distribution Results
Each tree of trees has distribution results describing a consequence of this process. The result of the distribution should be as follows:
1. Each point of inclusion must have an ordered list, called distributed nodes, consisting of nodes distributed at the point of inclusion.
2. Each node that is not an inclusion point has an ordered list called assignment point assignments and consisting of the inclusion points in which the nodes are distributed.
3. The inclusion point A is the final destination of node B if A is the last item in the list of assignment points for inclusion B.
When Node A is distributed to the enable point B, the following should occur:
● A will be added to distributed nodes B
● B is added to the final switch points A
There is a case that deserves special attention - a situation where the inclusion point is a child of another leading shadow element. In such situations, the nodes distributed at this point of inclusion appear in such a way as if they are children of the leading shadow element in the context of the distribution. Then, the nodes distributed in the shadow tree may already be distributed from their parent tree.
Although the node is distributed to more than one switching point, it appears only once in the composed tree - at the place of its final destination.
Fig. 4 Redistribution.
In the figure, child node 1 is distributed to switch on point 1. Then child 1 is redistributed to switch on point 3. Final switch points on child 1 - [switch on point 1, point on switch 3] and point of switch 3 are the final assignments of child 1. Distributed switch point nodes 1 and the points of inclusion 3 are [descendant 1] and [descendant 1, descendant 3], respectively.
3.5 Algorithms distribution
To calculate the result of the tree distribution of trees, it is necessary to use the distribution algorithm, which should be equivalent to performing the following steps sequentially:
Input
TREE OF TREES - tree of trees
Conclusion
Updated result of TREE TREES distribution
1. All distributed nodes and final switching points belonging to TREE TREES must be empty.
2. The ROOT TREE must be the TREE TREE tree.
3. It is necessary to run the algorithm for calculating the distribution with the ROOT TREE as input data.
To determine the distribution result for a given tree of nodes and its descendant trees, an algorithm for calculating the distribution result should be used, consisting in performing the following steps:
Input
TREE NODES - node tree
Conclusion
Updated distribution result for containing tree-descendants of the TREE OF NODES
1. For each leading element of the shadow tree, the LEADING SHADOW ELEMENT (SHADOW-HOST), which is the leading element of the NODE TREE, in the current tree structure:
The pool must be the result of the algorithm for filling the pool with a leading shadow element as input
A SHADOW TREE is a shady tree contained in the LEADING SHADOW ELEMENT.
Run a pool allocation algorithm with a TEMPLE TREE and a POOL as input
Run the algorithm to calculate the result of the distribution recursively, with the SHADOW TREE as input
The algorithm for filling the pool should also be used to obtain nodes from the child nodes of this node and consists in performing the following actions:
Input
KNOT (NODE) node
Conclusion
POOL (POOL) ordered list of nodes
1. The pool must be an empty ordered list.
2. For each node, node knockout:
1. If the CHILD is the point of activation:
1. Add all nodes to the distributed nodes.
2. Otherwise:
1. Add CASTING TO POOL
The pool distribution algorithm must be used to distribute nodes in the pool to the inclusion points of the content in the shadow tree and consists of the following actions:
Input
Shade Tree, Shadow Tree
PUL, ordered list of nodes
Conclusion
Nodes in the BULLET are distributed to the inclusion points of the contents in the tree.
1. For each content inclusion point, CONTENT, consisting in the SHADOW TREE in the tree structure:
1. For each node knot in the bullet
1. If the KNOT satisfies the criterion of compliance CONTENTS:
1. Distribute the KNOT in the CONTENT
2. Remove the KNOT from the pool
2. If in the CONTENT no node is distributed:
1. For each descendant, CONTROL of CONTENTS
1. DISTRIBUTE CASTING IN THE CONTENT
If no node has been distributed to the point of inclusion of the CONTENT content, the child nodes of CONTENT are distributed to the CONTENT as backup nodes.
If there is any condition that affects changes in distribution results, the distribution result must be updated before it can be used.
3.5 Satisfaction of eligibility criteria
The criterion for matching the point of inclusion is a set of composite selectors [SELECTORS4]. These composite selectors can contain only such simple selectors:
● Type selector or universal selector
● class selector (s)
● ID selector
● attribute selector (s)
● Negative pseudo-class:: not ()
A node satisfies the matching criterion only if:
1. all complex selectors in the sample consist only of allowed simple selectors; and
2. The node corresponds to at least one composite selector in the sample, or the sample is empty.
The point of inclusion is the place where the nodes appear in another node tree instead of their original position when building a composed tree.
Fig. 3 Distribution
Distribution is a mechanism that determines which nodes appear at which switching point. A detailed distribution algorithm will be described later.
3.2 Content inclusion points
Content inclusion points are the inclusion points to which the child nodes of the leading shadow element are distributed. A content element that satisfies the following conditions is a content inclusion point:
● The root node of the content item is the root node of the shadow tree
● There are no other content elements among the ancestors of the content item.
3.3 Distribution Results
Each tree of trees has distribution results describing a consequence of this process. The result of the distribution should be as follows:
1. Each point of inclusion must have an ordered list, called distributed nodes, consisting of nodes distributed at the point of inclusion.
2. Each node that is not an inclusion point has an ordered list called assignment point assignments and consisting of the inclusion points in which the nodes are distributed.
3. The inclusion point A is the final destination of node B if A is the last item in the list of assignment points for inclusion B.
When Node A is distributed to the enable point B, the following should occur:
● A will be added to distributed nodes B
● B is added to the final switch points A
There is a case that deserves special attention - a situation where the inclusion point is a child of another leading shadow element. In such situations, the nodes distributed at this point of inclusion appear in such a way as if they are children of the leading shadow element in the context of the distribution. Then, the nodes distributed in the shadow tree may already be distributed from their parent tree.
Although the node is distributed to more than one switching point, it appears only once in the composed tree - at the place of its final destination.
Fig. 4 Redistribution.
In the figure, child node 1 is distributed to switch on point 1. Then child 1 is redistributed to switch on point 3. Final switch points on child 1 - [switch on point 1, point on switch 3] and point of switch 3 are the final assignments of child 1. Distributed switch point nodes 1 and the points of inclusion 3 are [descendant 1] and [descendant 1, descendant 3], respectively.
3.5 Algorithms distribution
To calculate the result of the tree distribution of trees, it is necessary to use the distribution algorithm, which should be equivalent to performing the following steps sequentially:
Input
TREE OF TREES - tree of trees
Conclusion
Updated result of TREE TREES distribution
1. All distributed nodes and final switching points belonging to TREE TREES must be empty.
2. The ROOT TREE must be the TREE TREE tree.
3. It is necessary to run the algorithm for calculating the distribution with the ROOT TREE as input data.
To determine the distribution result for a given tree of nodes and its descendant trees, an algorithm for calculating the distribution result should be used, consisting in performing the following steps:
Input
TREE NODES - node tree
Conclusion
Updated distribution result for containing tree-descendants of the TREE OF NODES
1. For each leading element of the shadow tree, the LEADING SHADOW ELEMENT (SHADOW-HOST), which is the leading element of the NODE TREE, in the current tree structure:
The pool must be the result of the algorithm for filling the pool with a leading shadow element as input
A SHADOW TREE is a shady tree contained in the LEADING SHADOW ELEMENT.
Run a pool allocation algorithm with a TEMPLE TREE and a POOL as input
Run the algorithm to calculate the result of the distribution recursively, with the SHADOW TREE as input
The algorithm for filling the pool should also be used to obtain nodes from the child nodes of this node and consists in performing the following actions:
Input
KNOT (NODE) node
Conclusion
POOL (POOL) ordered list of nodes
1. The pool must be an empty ordered list.
2. For each node, node knockout:
1. If the CHILD is the point of activation:
1. Add all nodes to the distributed nodes.
2. Otherwise:
1. Add CASTING TO POOL
The pool distribution algorithm must be used to distribute nodes in the pool to the inclusion points of the content in the shadow tree and consists of the following actions:
Input
Shade Tree, Shadow Tree
PUL, ordered list of nodes
Conclusion
Nodes in the BULLET are distributed to the inclusion points of the contents in the tree.
1. For each content inclusion point, CONTENT, consisting in the SHADOW TREE in the tree structure:
1. For each node knot in the bullet
1. If the KNOT satisfies the criterion of compliance CONTENTS:
1. Distribute the KNOT in the CONTENT
2. Remove the KNOT from the pool
2. If in the CONTENT no node is distributed:
1. For each descendant, CONTROL of CONTENTS
1. DISTRIBUTE CASTING IN THE CONTENT
If no node has been distributed to the point of inclusion of the CONTENT content, the child nodes of CONTENT are distributed to the CONTENT as backup nodes.
If there is any condition that affects changes in distribution results, the distribution result must be updated before it can be used.
3.5 Satisfaction of eligibility criteria
The criterion for matching the point of inclusion is a set of composite selectors [SELECTORS4]. These composite selectors can contain only such simple selectors:
● Type selector or universal selector
● class selector (s)
● ID selector
● attribute selector (s)
● Negative pseudo-class:: not ()
A node satisfies the matching criterion only if:
1. all complex selectors in the sample consist only of allowed simple selectors; and
2. The node corresponds to at least one composite selector in the sample, or the sample is empty.
4. Drafting
To determine the descendants of each node in the composed tree, it is necessary to apply an algorithm for calculating the descendants of the composed tree, which consists in performing the following actions:
Input
KNOTE (NODE), a node located in a composed tree
Conclusion
CURRENT (CHILDREN), child node of the KNOTT in the composed tree.
1. CREATURE should be an empty ordered list of nodes
2. If the NODE is the leading shadow element:
1. The pool-costs should be the youngest shadow root contained in the node.
3. Otherwise:
1. The pool-flow should be a node of the node
4. For each child node, CASTING, in CASTING BULLET:
1. If the CASH is the point of inclusion:
1. For each node, DISTRIBUTED NODE (DISTRIBUTED-NODE), in the list of distributed nodes at the point of inclusion of the CASH:
1. If the CASH is the final destination of the DISTRIBUTED KNOT, add the DISTRIBUTED KNOT to the DESCENT
2. Otherwise:
1. Add CREATE TO CREATE
For a given tree of TREE TREES, a composed tree constructed from TREE TREES must correspond to the following tree:
● The root node of the composed tree is the root node of the root tree in the TREE TREE.
For a given node in the composed tree, the child nodes of this node are the result of the algorithm for calculating the composed tree with the node as input
Input
KNOTE (NODE), a node located in a composed tree
Conclusion
CURRENT (CHILDREN), child node of the KNOTT in the composed tree.
1. CREATURE should be an empty ordered list of nodes
2. If the NODE is the leading shadow element:
1. The pool-costs should be the youngest shadow root contained in the node.
3. Otherwise:
1. The pool-flow should be a node of the node
4. For each child node, CASTING, in CASTING BULLET:
1. If the CASH is the point of inclusion:
1. For each node, DISTRIBUTED NODE (DISTRIBUTED-NODE), in the list of distributed nodes at the point of inclusion of the CASH:
1. If the CASH is the final destination of the DISTRIBUTED KNOT, add the DISTRIBUTED KNOT to the DESCENT
2. Otherwise:
1. Add CREATE TO CREATE
For a given tree of TREE TREES, a composed tree constructed from TREE TREES must correspond to the following tree:
● The root node of the composed tree is the root node of the root tree in the TREE TREE.
For a given node in the composed tree, the child nodes of this node are the result of the algorithm for calculating the composed tree with the node as input
5. Events
In each algorithm in this section, the Window must be treated as if it were the parent node of the document — so that the Window can also receive events.
When an event is distributed into a shadow tree, its path either passes through shadow trees or ends at the shadow root. The only exception is change events (mutations). These types of events should never be distributed into a shadow tree.
5.1 Always stopped events
The following events should always be stopped at the lowest shadow root:
● abort
● error
● select
● change
● load
● reset
● resize
● scroll
● selectstart
The exact algorithm will be given below.
5.2 Ways of events
To determine the event path, it is necessary to use the event path calculation algorithm, which consists in performing the following actions:
Input
KNOT, node
EVENT, event (event)
Conclusion
PATH, event path, ordered list of event targets.
1. The PATH should be an empty ordered list.
2. THE CURRENT ITEM MUST BE A NODE
3. Repeat until CURRENT ELEMENT exists:
1. Add POWER ON POINT
2. If the final points of the CURRENT ELEMENT are not empty:
1. Add each switching point to the final switching points of the CURRENT ELEMENT, from the first, including, to the last, exclusive, to the PATH.
2 ... THE CURRENT ITEM must be the final destination of the CURRENT ITEM
3. Otherwise, if all the following conditions are met, stop this algorithm:
1. If the CURRENT ITEM is a shadow root:
2. If the CURRENT ITEM is the root node of the NODE
3. Installed scoped flag.
4. Otherwise: THE CURRENT ITEM must be a deep parent of the CURRENT ITEM.
5.3 Examples of event paths
This section is non-normative.
Suppose we have the following tree trees:
Fig. 5 Example of a tree. Nodes that are not participating in the event path in question, described below, are omitted.
● A is a document.
● E, J, N, Q, S are shadow roots.
● I, M, P, R, and U content inclusion points.
This tree of trees consists of the following six trees: one document tree and five shadow trees:
● Document tree 1. It consists of nodes A, B, C, and D.
● Shadow Tree 2 contained in B. It includes nodes E, F, G, H, and I.
● Shadow Tree 3 contained in H. It includes nodes J, K, L, and M.
● Shadow Tree 4 contained in K. It includes nodes N, O, and P.
● Shadow Tree 5 contained in O. It includes nodes Q and R.
● Shadow Tree 6 contained in F. It includes nodes S, T and U.
Let's assume that the result of the distribution of this tree is:
● Assignment of the switching points C is [I, M] (C is redistributed)
● Assignments of the switching points L is [P, R] (L is redistributed)
● The assignment points of the switch G is [U]
In this case, if the event is sent to node D, the event path will be as follows:
[D, C, I, M, L, P, R, Q, O, N, K, J, H, G, U, T, S, F, E, B, A] (Excluding Window)
Please note that the algorithm for calculating the event path is designed to achieve the following goals:
1. If there is a CENTRAL node in the event path and it has a PARENT in the node tree, the event path will also include the PARENT. PARENT always appears somewhere after a HELP in the event path.
2. Nodes along the way events form a linear chain of ancestors in each node tree. No node tree has branch points.
Fig. 6 In this figure, the number on the left of each node represents the initial position of each node in the event path. At the parent node, this figure is always greater than that of any of its descendants in each node tree.
This suggests that if we focus on one node tree and forget about all the others, the event path will look as if the event occurred only in the node tree in question. This is an important aspect in the sense that the presence of a shadow tree does not in any way affect the event path within the node tree containing the leading shadow element until the event is stopped in any of the descendant trees.
For example, from the point of view of the document tree 1, the event path should look like this: [D, C, B, A]. From the point of view of the shadow tree 2, the event path should look like [I, H, G, F, E]. Other node trees obey the same rules.
It is also worth noting that if we exclude all points of inclusion and shadow roots from the event path, the result would be equivalent to the containing ancestors of the node in the compiled tree on which the event occurs.
Fig. 7 The relationship between the event path and the constructed tree. The event path used in the example is shown in the figure on the left, and the composed tree is shown on the right. If we exclude all inclusion points and shadow roots from the event path, the result will correspond to the containing ancestors of node D in the constructed tree.
5.4 Event Forwarding
In cases where the event path passes through several node trees, the event information about its target can be adjusted depending on the order in which the encapsulation is processed. Event forwarding is the process of calculating the corresponding target elements for each ancestor of the node where the event occurs. A relative target element is the node that most accurately represents the target element of a given ancestor’s event while maintaining encapsulation.
The redirection algorithm should be used to determine relative goals and consist of the following steps:
Input
CURRENT WAY, event path
CURRENT GOAL, the node on which the event listener is triggered.
Conclusion
RELATIVE PURPOSE, adjusted target element
1. THE TREE OF THE CURRENT GOAL should be the node tree containing the CURRENT GOAL
2. THE ORIGINAL PURPOSE MUST BE THE FIRST ELEMENT IN THE WAY OF THE EVENT
3. TREE OF THE ORIGINAL PURPOSE should be the node tree containing the ORIGINAL PURPOSE
4. The TREE OF THE RELATIVE PURPOSE should be the closest common containing tree of the descendants of the TREE OF THE CURRENT GOAL and the TREE OF THE RELATIVE GOAL.
5. RELATIVE TARGET ELEMENT should be the first node in the EVENT WAY, satisfying the following conditions:
1. The node must be contained in the TREE OF THE RELATIVE TARGET ELEMENT
The redirection process must occur before the event is delivered to the element.
5.5 Redirect relatedTarget
Some events have a property relatedTarget [DOM-Level-3-Events] , which contains a node that is not the purpose of the event, but related to it.
For example, for a mouseover event, relatedTarget may point to the node from which the mouse pointer moved to the current element. In the case when relatedTarget is in a shadow tree, the corresponding user agents should not allow leakage of its actual value beyond the limits of this tree. In cases where both the relatedTarget and the target belong to the same shadow tree, the corresponding user agents must stop the events in the shadow root to avoid the appearance of side mouseover and mouseout events from the same node at the same time.
Thus, if an event has a relatedTarget property, its value and the element that it must match must be adjusted.
The relatedTarget redirection process must occur before the event is delivered to the element.
5.6 Forwarding touch events
The Touch target attribute [TOUCH EVENTS] should be adjusted in the same way as an event with a relatedTarget. Each Touch target attribute in the TouchList list returned by a call to TouchEvent touches (), changedTouches (), and targetTouches () must be the result of executing the relative target calculation algorithm with the KNOT and Touch target as input data.
5.7 Redirect Focus Events
The focus, DOMFocusIn, blur, and DOMFocusOut events must be handled in the same way as events with relatedTarget, where a node loses focus as a result of receiving this focus by another node or event target element, which causes the node that has lost focus to become a relative target. with respect to the node that received it.
5.8 Event Transfer
At the time of the transfer event:
● The Event target and currentTarget attributes should return a relative target for the node on which the event listeners fired.
● The MouseOvent relatedTarget attribute of the event must return the corrected relative target
● The offsetX and offsetY attributes of the MouseEvent event should return the value of the origin point of the relative target, taking into account the internal indents.
● The Touch target attribute must return the adjusted relative target.
● If relatedTarget and target are the same element for a given node, event listeners should not work on it. TouchEvent does not obey this rule.
● If a node is its own relative goal, event listeners should not operate on it during the capture phase, which entails step 6 of the event transmission algorithm.
● If the node where the event listener was triggered is its own relative target, the eventPhase attribute of the event should return AT_TARGET during the ascent phase, which entails step 9 of the event transmission algorithm.
● If the value of the bubbles attribute of the event is false, the following should be done:
1. The event path must be sorted in reverse order.
2. The value of the eventPhase event attribute must be set to AT_TARGET
3. For each object in the event path, whose relative goal is equal to the object itself, the event listener must be called with the event itself as an argument until the event stop flag is disabled
After the event transfer is completed, the target and currentTarget event objects must indicate the relative target of the highest parent.
This step is necessary in order to avoid detection of nodes in the shadow tree, since it is possible for the script to transfer the event object beyond its scope.
5.9 Example of event redirection
This section is non-standard.
, , , . , , . :
1
, (#volume-slider-thumb), mouseover . relatedTarget.
, :
(Ancestor) (Relative Target)
mouseover , (#timeline-slider-thumb). mouseout mouseover .
, relatedTarget mouseout . , relatedTarget (#timeline-slider-thumb). , , :
(Ancestor) (Relative Target) (Adjusted related Target)
, #player, target relatedTarget (#player), , .
When an event is distributed into a shadow tree, its path either passes through shadow trees or ends at the shadow root. The only exception is change events (mutations). These types of events should never be distributed into a shadow tree.
5.1 Always stopped events
The following events should always be stopped at the lowest shadow root:
● abort
● error
● select
● change
● load
● reset
● resize
● scroll
● selectstart
The exact algorithm will be given below.
5.2 Ways of events
To determine the event path, it is necessary to use the event path calculation algorithm, which consists in performing the following actions:
Input
KNOT, node
EVENT, event (event)
Conclusion
PATH, event path, ordered list of event targets.
1. The PATH should be an empty ordered list.
2. THE CURRENT ITEM MUST BE A NODE
3. Repeat until CURRENT ELEMENT exists:
1. Add POWER ON POINT
2. If the final points of the CURRENT ELEMENT are not empty:
1. Add each switching point to the final switching points of the CURRENT ELEMENT, from the first, including, to the last, exclusive, to the PATH.
2 ... THE CURRENT ITEM must be the final destination of the CURRENT ITEM
3. Otherwise, if all the following conditions are met, stop this algorithm:
1. If the CURRENT ITEM is a shadow root:
2. If the CURRENT ITEM is the root node of the NODE
3. Installed scoped flag.
4. Otherwise: THE CURRENT ITEM must be a deep parent of the CURRENT ITEM.
5.3 Examples of event paths
This section is non-normative.
Suppose we have the following tree trees:
Fig. 5 Example of a tree. Nodes that are not participating in the event path in question, described below, are omitted.
● A is a document.
● E, J, N, Q, S are shadow roots.
● I, M, P, R, and U content inclusion points.
This tree of trees consists of the following six trees: one document tree and five shadow trees:
● Document tree 1. It consists of nodes A, B, C, and D.
● Shadow Tree 2 contained in B. It includes nodes E, F, G, H, and I.
● Shadow Tree 3 contained in H. It includes nodes J, K, L, and M.
● Shadow Tree 4 contained in K. It includes nodes N, O, and P.
● Shadow Tree 5 contained in O. It includes nodes Q and R.
● Shadow Tree 6 contained in F. It includes nodes S, T and U.
Let's assume that the result of the distribution of this tree is:
● Assignment of the switching points C is [I, M] (C is redistributed)
● Assignments of the switching points L is [P, R] (L is redistributed)
● The assignment points of the switch G is [U]
In this case, if the event is sent to node D, the event path will be as follows:
[D, C, I, M, L, P, R, Q, O, N, K, J, H, G, U, T, S, F, E, B, A] (Excluding Window)
Please note that the algorithm for calculating the event path is designed to achieve the following goals:
1. If there is a CENTRAL node in the event path and it has a PARENT in the node tree, the event path will also include the PARENT. PARENT always appears somewhere after a HELP in the event path.
2. Nodes along the way events form a linear chain of ancestors in each node tree. No node tree has branch points.
Fig. 6 In this figure, the number on the left of each node represents the initial position of each node in the event path. At the parent node, this figure is always greater than that of any of its descendants in each node tree.
This suggests that if we focus on one node tree and forget about all the others, the event path will look as if the event occurred only in the node tree in question. This is an important aspect in the sense that the presence of a shadow tree does not in any way affect the event path within the node tree containing the leading shadow element until the event is stopped in any of the descendant trees.
For example, from the point of view of the document tree 1, the event path should look like this: [D, C, B, A]. From the point of view of the shadow tree 2, the event path should look like [I, H, G, F, E]. Other node trees obey the same rules.
It is also worth noting that if we exclude all points of inclusion and shadow roots from the event path, the result would be equivalent to the containing ancestors of the node in the compiled tree on which the event occurs.
Fig. 7 The relationship between the event path and the constructed tree. The event path used in the example is shown in the figure on the left, and the composed tree is shown on the right. If we exclude all inclusion points and shadow roots from the event path, the result will correspond to the containing ancestors of node D in the constructed tree.
5.4 Event Forwarding
In cases where the event path passes through several node trees, the event information about its target can be adjusted depending on the order in which the encapsulation is processed. Event forwarding is the process of calculating the corresponding target elements for each ancestor of the node where the event occurs. A relative target element is the node that most accurately represents the target element of a given ancestor’s event while maintaining encapsulation.
The redirection algorithm should be used to determine relative goals and consist of the following steps:
Input
CURRENT WAY, event path
CURRENT GOAL, the node on which the event listener is triggered.
Conclusion
RELATIVE PURPOSE, adjusted target element
1. THE TREE OF THE CURRENT GOAL should be the node tree containing the CURRENT GOAL
2. THE ORIGINAL PURPOSE MUST BE THE FIRST ELEMENT IN THE WAY OF THE EVENT
3. TREE OF THE ORIGINAL PURPOSE should be the node tree containing the ORIGINAL PURPOSE
4. The TREE OF THE RELATIVE PURPOSE should be the closest common containing tree of the descendants of the TREE OF THE CURRENT GOAL and the TREE OF THE RELATIVE GOAL.
5. RELATIVE TARGET ELEMENT should be the first node in the EVENT WAY, satisfying the following conditions:
1. The node must be contained in the TREE OF THE RELATIVE TARGET ELEMENT
The redirection process must occur before the event is delivered to the element.
5.5 Redirect relatedTarget
Some events have a property relatedTarget [DOM-Level-3-Events] , which contains a node that is not the purpose of the event, but related to it.
For example, for a mouseover event, relatedTarget may point to the node from which the mouse pointer moved to the current element. In the case when relatedTarget is in a shadow tree, the corresponding user agents should not allow leakage of its actual value beyond the limits of this tree. In cases where both the relatedTarget and the target belong to the same shadow tree, the corresponding user agents must stop the events in the shadow root to avoid the appearance of side mouseover and mouseout events from the same node at the same time.
Thus, if an event has a relatedTarget property, its value and the element that it must match must be adjusted.
The relatedTarget redirection process must occur before the event is delivered to the element.
5.6 Forwarding touch events
The Touch target attribute [TOUCH EVENTS] should be adjusted in the same way as an event with a relatedTarget. Each Touch target attribute in the TouchList list returned by a call to TouchEvent touches (), changedTouches (), and targetTouches () must be the result of executing the relative target calculation algorithm with the KNOT and Touch target as input data.
5.7 Redirect Focus Events
The focus, DOMFocusIn, blur, and DOMFocusOut events must be handled in the same way as events with relatedTarget, where a node loses focus as a result of receiving this focus by another node or event target element, which causes the node that has lost focus to become a relative target. with respect to the node that received it.
5.8 Event Transfer
At the time of the transfer event:
● The Event target and currentTarget attributes should return a relative target for the node on which the event listeners fired.
● The MouseOvent relatedTarget attribute of the event must return the corrected relative target
● The offsetX and offsetY attributes of the MouseEvent event should return the value of the origin point of the relative target, taking into account the internal indents.
● The Touch target attribute must return the adjusted relative target.
● If relatedTarget and target are the same element for a given node, event listeners should not work on it. TouchEvent does not obey this rule.
● If a node is its own relative goal, event listeners should not operate on it during the capture phase, which entails step 6 of the event transmission algorithm.
● If the node where the event listener was triggered is its own relative target, the eventPhase attribute of the event should return AT_TARGET during the ascent phase, which entails step 9 of the event transmission algorithm.
● If the value of the bubbles attribute of the event is false, the following should be done:
1. The event path must be sorted in reverse order.
2. The value of the eventPhase event attribute must be set to AT_TARGET
3. For each object in the event path, whose relative goal is equal to the object itself, the event listener must be called with the event itself as an argument until the event stop flag is disabled
After the event transfer is completed, the target and currentTarget event objects must indicate the relative target of the highest parent.
This step is necessary in order to avoid detection of nodes in the shadow tree, since it is possible for the script to transfer the event object beyond its scope.
5.9 Example of event redirection
This section is non-standard.
, , , . , , . :
1
, (#volume-slider-thumb), mouseover . relatedTarget.
, :
(Ancestor) (Relative Target)
mouseover , (#timeline-slider-thumb). mouseout mouseover .
, relatedTarget mouseout . , relatedTarget (#timeline-slider-thumb). , , :
(Ancestor) (Relative Target) (Adjusted related Target)
, #player, target relatedTarget (#player), , .
6. User interaction
6.1
.
[ ] . . , , , :
, , , DOM, .
, , . , window.getSelection() , .
getSelection() .
6.2
, [CSS3UI].
, :
1. ,
2. :
1. , — focusable; or
2. .
, .
6.3
, activeElement focus API . , activeElement .
activeElement, :
(ELEMENT),
,
Conclusion
(ADJUSTED), activeElement .
1. null
2.
6.4
contenteditable .
6.5
, WAI-ARIA [WAI-ARIA] .
.
[ ] . . , , , :
, , , DOM, .
, , . , window.getSelection() , .
getSelection() .
6.2
, [CSS3UI].
, :
1. ,
2. :
1. , — focusable; or
2. .
, .
6.3
, activeElement focus API . , activeElement .
activeElement, :
(ELEMENT),
,
Conclusion
(ADJUSTED), activeElement .
1. null
2.
6.4
contenteditable .
6.5
, WAI-ARIA [WAI-ARIA] .
7. HTML Elements in Shadow Trees
7.1 HTML
, - . , . . , HTML , [HTML] , .
[HTML], HTML , , , . , , , . , , HTML , , , . W3C 26365 27406. . HTML . HTML , . [HTML] , .
HTML :
●
● HTML , , , , , .
● HTML :
○ dialog
○ iframe
○ style
● :
● HTML , , , . HTML
● HTML :
○ base
○ link
● , :
● HTML , , , . , , — , .
● HTML :
○ applet
○ embed
○ object
, , object , — . , , , — . , , .
7.2
[HTML] , , .
● dir
● draggable
● dropzone
● hidden
● lang xml:lang
● spellcheck
● title
, - . :
● tabindex autofocus .
● role ARIA .
, - . , . . , HTML , [HTML] , .
[HTML], HTML , , , . , , , . , , HTML , , , . W3C 26365 27406. . HTML . HTML , . [HTML] , .
HTML :
●
● HTML , , , , , .
● HTML :
○ dialog
○ iframe
○ style
● :
● HTML , , , . HTML
● HTML :
○ base
○ link
● , :
● HTML , , , . , , — , .
● HTML :
○ applet
○ embed
○ object
, , object , — . , , , — . , , .
7.2
[HTML] , , .
● dir
● draggable
● dropzone
● hidden
● lang xml:lang
● spellcheck
● title
, - . :
● tabindex autofocus .
● role ARIA .
8. Elements and DOM interfaces. Examples of Shadow Dom. Links
8.1 ShadowRoot
ShadowRoot .
8.1.1
activeElement : Element, readonly, nullable
.
, , .
host : Element, readonly
,
, .
innerHTML : DOMString,
ShadowRoot.
HTML shadow host.
:
1. [DOM-PARSING] shadow host
2. .
olderShadowRoot : ShadowRoot, readonly, nullable
StyleSheetList, .
8.1.2
caretPositionFromPoint
, caretPositionFromPoint [CSSOM-VIEW] . CSSOM View Module [CSSOM-VIEW]. W3C 27829.
: CaretPosition, nullable
elementFromPoint
.
CSSOM View Module [CSSOM-VIEW] . W3C 27829 .
:
1. — ShadowRoot — InvalidNodeTypeError.
2. - , x ( ), y ( ), null.
3. x y ,
4. null
5.
: Element, nullable
elementsFromPoint
, elementFromPoint. CSSOM View Module [CSSOM-VIEW] . W3C 27829 .
: getSelection
.
.
.
: Selection, nullable
nodeType ShadowRoot DOCUMENT_FRAGMENT_NODE. nodeName ShadowRoot "#document-fragment".
cloneNode() ShadowRoot DATA_CLONE_ERR.
8.2 Element
8.2.1
shadowRoot : ShadowRoot, readonly, nullable
, .
, , . null.
8.2.2
createShadowRoot
:
1. ShadowRoot, .
2. ShadowRoot
3. ShadowRoot.
.
: ShadowRoot
getDestinationInsertionPoints
NodeList, , .
.
: NodeList
8.3 Text
partial interface Text {
NodeList getDestinationInsertionPoints ();
};
8.3.1
getDestinationInsertionPoints
NodeList, , .
.
: NodeList
8.4 content
content .
content , HTMLUnknownElement.
Context
.
,
select, ,
. .
DOM
select : DOMString,
select.
getDistributedNodes
:
1. — :
1. NodeList , , .
2. :
1. NodeList.
.
: NodeList
8.5 shadow
shadow .
shadow , HTMLUnknownElement.
Context
.
Shadow DOM
, : . :
DOM. , . Green Eye, , ul:
, :
, , :
, ! - , . , Puyo Puyo.
.
. , , , , , . , , , , , . , :
shadow . «, , , , », — , .
Links
[CSS21]
Bert Bos; Tantek Çelik; Ian Hickson; Håkon Wium Lie et al. Cascading Style Sheets Level 2 Revision 1 (CSS 2.1) Specification. 7 June 2011. W3C Recommendation.
[CSS3UI]
Tantek Çelik; Florian Rivoal. CSS Basic User Interface Module Level 3 (CSS3 UI). 7 July 2015. W3C Candidate Recommendation.
[CSSOM-VIEW]
Simon Pieters; Glenn Adams. CSSOM View Module. 17 December 2013. W3C Working Draft.
[DOM]
Anne van Kesteren; Aryeh Gregor; Ms2ger; Alex Russell; Robin Berjon. W3C DOM4 . 18 June 2015. W3C Last Call Working Draft.
[DOM-Level-3-Events]
Gary Kacmarcik; Travis Leithead. UI Events (formerly DOM Level 3 Events) . 28 April 2015. W3C Working Draft.
[DOM-PARSING]
Travis Leithead. DOM Parsing and Serialization. 17 June 2014. W3C Candidate Recommendation.
[EDITING]
Aryeh Gregor. HTML Editing APIs.
[HTML]
Ian Hickson. HTML Standard. Living Standard.
S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Best Current Practice.
[SELECTORS4]
Elika Etemad; Tab Atkins Jr… Selectors Level 4. 2 May 2013. W3C Working Draft.
[TOUCH-EVENTS]
Doug Schepers; Sangwhan Moon; Matt Brubeck; Arthur Barstow. Touch Events. 10 October 2013. W3C Recommendation.
[WAI-ARIA]
James Craig; Michael Cooper et al. Accessible Rich Internet Applications (WAI-ARIA) 1.0. 20 March 2014. W3C Recommendation.
ShadowRoot .
8.1.1
activeElement : Element, readonly, nullable
.
, , .
host : Element, readonly
,
, .
innerHTML : DOMString,
ShadowRoot.
HTML shadow host.
:
1. [DOM-PARSING] shadow host
2. .
olderShadowRoot : ShadowRoot, readonly, nullable
StyleSheetList, .
8.1.2
caretPositionFromPoint
, caretPositionFromPoint [CSSOM-VIEW] . CSSOM View Module [CSSOM-VIEW]. W3C 27829.
: CaretPosition, nullable
elementFromPoint
.
CSSOM View Module [CSSOM-VIEW] . W3C 27829 .
:
1. — ShadowRoot — InvalidNodeTypeError.
2. - , x ( ), y ( ), null.
3. x y ,
4. null
5.
: Element, nullable
elementsFromPoint
, elementFromPoint. CSSOM View Module [CSSOM-VIEW] . W3C 27829 .
: getSelection
.
.
.
: Selection, nullable
nodeType ShadowRoot DOCUMENT_FRAGMENT_NODE. nodeName ShadowRoot "#document-fragment".
cloneNode() ShadowRoot DATA_CLONE_ERR.
8.2 Element
8.2.1
shadowRoot : ShadowRoot, readonly, nullable
, .
, , . null.
8.2.2
createShadowRoot
:
1. ShadowRoot, .
2. ShadowRoot
3. ShadowRoot.
.
: ShadowRoot
getDestinationInsertionPoints
NodeList, , .
.
: NodeList
8.3 Text
partial interface Text {
NodeList getDestinationInsertionPoints ();
};
8.3.1
getDestinationInsertionPoints
NodeList, , .
.
: NodeList
8.4 content
content .
content , HTMLUnknownElement.
Context
.
,
select, ,
. .
DOM
select : DOMString,
select.
getDistributedNodes
:
1. — :
1. NodeList , , .
2. :
1. NodeList.
.
: NodeList
8.5 shadow
shadow .
shadow , HTMLUnknownElement.
Context
.
Shadow DOM
, : . :
DOM. , . Green Eye, , ul:
, :
, , :
, ! - , . , Puyo Puyo.
.
. , , , , , . , , , , , . , :
shadow . «, , , , », — , .
Links
[CSS21]
Bert Bos; Tantek Çelik; Ian Hickson; Håkon Wium Lie et al. Cascading Style Sheets Level 2 Revision 1 (CSS 2.1) Specification. 7 June 2011. W3C Recommendation.
[CSS3UI]
Tantek Çelik; Florian Rivoal. CSS Basic User Interface Module Level 3 (CSS3 UI). 7 July 2015. W3C Candidate Recommendation.
[CSSOM-VIEW]
Simon Pieters; Glenn Adams. CSSOM View Module. 17 December 2013. W3C Working Draft.
[DOM]
Anne van Kesteren; Aryeh Gregor; Ms2ger; Alex Russell; Robin Berjon. W3C DOM4 . 18 June 2015. W3C Last Call Working Draft.
[DOM-Level-3-Events]
Gary Kacmarcik; Travis Leithead. UI Events (formerly DOM Level 3 Events) . 28 April 2015. W3C Working Draft.
[DOM-PARSING]
Travis Leithead. DOM Parsing and Serialization. 17 June 2014. W3C Candidate Recommendation.
[EDITING]
Aryeh Gregor. HTML Editing APIs.
[HTML]
Ian Hickson. HTML Standard. Living Standard.
S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Best Current Practice.
[SELECTORS4]
Elika Etemad; Tab Atkins Jr… Selectors Level 4. 2 May 2013. W3C Working Draft.
[TOUCH-EVENTS]
Doug Schepers; Sangwhan Moon; Matt Brubeck; Arthur Barstow. Touch Events. 10 October 2013. W3C Recommendation.
[WAI-ARIA]
James Craig; Michael Cooper et al. Accessible Rich Internet Applications (WAI-ARIA) 1.0. 20 March 2014. W3C Recommendation.
Source: https://habr.com/ru/post/262017/
All Articles