From 018440e918b59633eb0a6b9033528f612f84aa49 Mon Sep 17 00:00:00 2001 From: Anne van Kesteren Date: Fri, 18 Mar 2016 15:11:40 +0100 Subject: [PATCH] Editorial: add sections on document and shadow trees --- dom.bs | 51 +++++++++------- dom.html | 174 +++++++++++++++++++++++++++++-------------------------- 2 files changed, 121 insertions(+), 104 deletions(-) diff --git a/dom.bs b/dom.bs index 6cd096d1a..08686e39b 100644 --- a/dom.bs +++ b/dom.bs @@ -228,10 +228,10 @@ or null, and an ordered list of zero or more parent is object B is a child of B. -The root of an object is itself, if its -parent is null, or else it is the -root of its -parent. +

The root of an object is itself, if its +parent is null, or else it is the root of its parent. The +root of a tree is any object participating in that +tree whose parent is null. An object A is called a descendant of an object @@ -1430,6 +1430,27 @@ A node is considered length is zero. +

Document tree

+ +

A document tree is a node tree whose +root is a document. + +

The document element of a document is the element whose +parent is that document, if it exists, and null otherwise. + +

Per the node tree constraints, there can be only one such +element. + +

An element is in a document if its root is a +document. + + +

Shadow tree

+ +

A shadow tree is a node tree whose root is +a shadow root. + +

Mutation algorithms

To ensure pre-insertion validity @@ -4999,12 +5020,12 @@ interface ShadowRoot : DocumentFragment {

In shadow-including tree order, is -shadow-including preorder, depth-first traversal of a tree. -shadow-including preorder, depth-first traversal of a tree +shadow-including preorder, depth-first traversal of a node tree. +shadow-including preorder, depth-first traversal of a node tree tree is preorder, depth-first traversal of tree, with for each -element element encountered in tree, whose -shadow root is non-null, shadow-including preorder, depth-first traversal -of the element's shadow root's tree just after it is +element element encountered in tree with a non-null +shadow root, shadow-including preorder, depth-first traversal of that +element's shadow root's node tree just after it is encountered.

An object A is a @@ -5361,18 +5382,6 @@ A node's parent of a different type, its parent element is null. -The document element of a -document is the -element whose -parent is that -document, if it exists, and null otherwise. - -

Per the node tree constraints, there can only be one -such element. - -

An element is in a document if its root is a -document. -

diff --git a/dom.html b/dom.html index 8a762be29..62b9e9771 100644 --- a/dom.html +++ b/dom.html @@ -127,18 +127,20 @@

Table of Contents

  • 4.2 Node tree
      -
    1. 4.2.1 Mutation algorithms -
    2. 4.2.2 Mixin NonElementParentNode -
    3. 4.2.3 Mixin DocumentOrShadowRoot -
    4. 4.2.4 Mixin ParentNode -
    5. 4.2.5 Mixin NonDocumentTypeChildNode -
    6. 4.2.6 Mixin ChildNode -
    7. 4.2.7 Collections: Elements +
    8. 4.2.1 Document tree +
    9. 4.2.2 Shadow tree +
    10. 4.2.3 Mutation algorithms +
    11. 4.2.4 Mixin NonElementParentNode +
    12. 4.2.5 Mixin DocumentOrShadowRoot +
    13. 4.2.6 Mixin ParentNode +
    14. 4.2.7 Mixin NonDocumentTypeChildNode +
    15. 4.2.8 Mixin ChildNode +
    16. 4.2.9 Collections: Elements
    17. - 4.2.8 Old-style collections: NodeList and HTMLCollection + 4.2.10 Old-style collections: NodeList and HTMLCollection
        -
      1. 4.2.8.1 Interface NodeList -
      2. 4.2.8.2 Interface HTMLCollection +
      3. 4.2.10.1 Interface NodeList +
      4. 4.2.10.2 Interface HTMLCollection
  • @@ -285,7 +287,7 @@

    2.1.

    An object that participates in a tree has a parent, which is either another object or null, and an ordered list of zero or more child objects. An object A whose parent is object B is a child of B.

    -

    The root of an object is itself, if its parent is null, or else it is the root of its parent.

    +

    The root of an object is itself, if its parent is null, or else it is the root of its parent. The root of a tree is any object participating in that tree whose parent is null.

    An object A is called a descendant of an object B, if either A is a child of B or A is a child of an object C that is a descendant of B.

    An inclusive descendant is @@ -1013,7 +1015,15 @@

    Its number of children.

    • A node is considered empty if its length is zero.

    -

    4.2.1. Mutation algorithms

    +

    4.2.1. Document tree

    +

    A document tree is a node tree whose root is a document.

    +

    The document element of a document is the element whose parent is that document, if it exists, and null otherwise.

    +

    Per the node tree constraints, there can be only one such element.

    +

    An element is in a document if its root is a document.

    +

    4.2.2. Shadow tree

    +

    A shadow tree is a node tree whose root is +a shadow root.

    +

    4.2.3. Mutation algorithms

    To ensure pre-insertion validity of a node into a parent before a child, run these steps:

    1. If parent is not a Document, DocumentFragment, or Element node, throw a HierarchyRequestError. @@ -1172,7 +1182,7 @@

      If suppress observers flag is unset, queue a mutation record of "childList" for parent with removedNodes a list solely containing node, nextSibling oldNextSibling, and previousSibling oldPreviousSibling.

    -

    4.2.2. Mixin NonElementParentNode

    +

    4.2.4. Mixin NonElementParentNode

    The getElementById() method is not on elements for compatibility with older versions of jQuery. If a time comes where that version of jQuery has disappeared, we might be able to support it. 

    [NoInterfaceObject,
@@ -1190,7 +1200,7 @@ 
    getElementById(elementId) method, when invoked, must return the first element, in tree order, within context object’s descendants, whose ID is elementId, and null if
 there is no such element otherwise. 
    
-   
    4.2.3. Mixin DocumentOrShadowRoot
    
+   
    4.2.5. Mixin DocumentOrShadowRoot
    
 
    [NoInterfaceObject,
  Exposed=Window]
 interface DocumentOrShadowRoot {
@@ -1200,7 +1210,7 @@ 
    <
 
    
    
    The DocumentOrShadowRoot mixin is expected to be used by other
 standards that want to define APIs shared between documents and shadow roots. 
    
-   
    4.2.4. Mixin ParentNode
    
+   
    4.2.6. Mixin ParentNode
    
    
    To convert nodes into a node,
 run these steps:
    
    
      
@@ -1286,7 +1296,7 @@ 
      The querySelector(selectors) method, when invoked, must return the first result of running scope-match a selectors string selectors against the context object, and null if the result is an empty list otherwise.
      
    
      The querySelectorAll(selectors) method, when invoked, must return the static result of
 running scope-match a selectors string selectors against the context object.
      
-   
      4.2.5. Mixin NonDocumentTypeChildNode
      
+   
      4.2.7. Mixin NonDocumentTypeChildNode
      
    
      The previousElementSibling and nextElementSibling attributes have
 been removed from DocumentType nodes for compatibility reasons. If these additions are deemed
 compatible enough in the future, they could be reinstated. 
      
@@ -1311,7 +1321,7 @@ 
      nextElementSibling attribute must return the first following sibling that is an element,
 and null otherwise.
      
-   
      4.2.6. Mixin ChildNode
      
+   
      4.2.8. Mixin ChildNode
      
 
      [NoInterfaceObject,
  Exposed=Window]
 interface ChildNode {
@@ -1398,7 +1408,7 @@ 
      
      
      Remove the context object from context object’s parent. 
      
    
    
-   
    4.2.7. Collections: Elements
    
+   
    4.2.9. Collections: Elements
    
 
    class Elements extends Array {
   Element? query(DOMString relativeSelectors);
   Elements queryAll(DOMString relativeSelectors);
@@ -1420,7 +1430,7 @@ 
    
    
    The query(relativeSelectors) method, when invoked, must return the first result of running match a relative selectors string relativeSelectors against the context object, and null if the result is an empty list.
    
    
    The queryAll(relativeSelectors) method, when invoked, must return the result of running this.constructor with the result of running match a relative selectors string relativeSelectors against the context object.
    
-   
    4.2.8. Old-style collections: NodeList and HTMLCollection
    
+   
    4.2.10. Old-style collections: NodeList and HTMLCollection
    
    
    A collection is an object that
 represents a lists of DOM nodes. A collection can be either live or static. Unless otherwise stated,
 a collection must be live.
    
@@ -1432,7 +1442,7 @@ 
    The collection then represents a view of the subtree rooted at the collection’s root, containing only nodes that match the
 given filter. The view is linear. In the absence of specific requirements to the contrary, the nodes
 within the collection must be sorted in tree order.
    
-   
    4.2.8.1. Interface NodeList
    
+   
    4.2.10.1. Interface NodeList
    
    
    A NodeList object is a collection of nodes.
    
 
    [Exposed=Window]
 interface NodeList {
@@ -1457,7 +1467,7 @@ 
    indexth node in the collection. If there is no indexth node in the collection, then the method must
 return null.
    
    
-   
    4.2.8.2. Interface HTMLCollection
    
+   
    4.2.10.2. Interface HTMLCollection
    
 
    [Exposed=Window, LegacyUnenumerableNamedProperties]
 interface HTMLCollection {
   readonly attribute unsigned long length;
@@ -2779,7 +2789,7 @@ 
    Shadow roots have an associated encapsulation mode ("open" or "closed").
    
    
    The host attribute’s getter must return the context object’s host. 
    
    
    
-   
    In shadow-including tree order, is shadow-including preorder, depth-first traversal of a tree. shadow-including preorder, depth-first traversal of a tree tree is preorder, depth-first traversal of tree, with for each element element encountered in tree, whose shadow root is non-null, shadow-including preorder, depth-first traversal of the element’s shadow root’s tree just after it is
+   
    In shadow-including tree order, is shadow-including preorder, depth-first traversal of a node tree. shadow-including preorder, depth-first traversal of a node tree tree is preorder, depth-first traversal of tree, with for each element element encountered in tree with a non-null shadow root, shadow-including preorder, depth-first traversal of that element’s shadow root’s node tree just after it is
 encountered. 
    
    
    An object A is a shadow-including descendant of an object B, if A is a descendant of B, or A’s root is a shadow root and A’s root’s host is a shadow-including inclusive descendant of B. 
    
    
    A shadow-including inclusive descendant is an object or one of its shadow-including descendants. 
    
@@ -2957,10 +2967,6 @@ 
    
    
    
    
    A node’s parent of type Element is known as a parent element. If the node has a parent of a different type, its parent element is null.
    
-   
    The document element of a document is the element whose parent is that document, if it exists, and null otherwise.
    
-   
    Per the node tree constraints, there can only be one
-such element. 
    
-   
    An element is in a document if its root is a document. 
    
    
    
    
    
     
    namespace = element . namespaceURI 
@@ -4795,15 +4801,15 @@ 
    adopting steps, in §4.5
    
  • adoptNode(node), in §4.5
    
  • after, in §5.2
-   
  • after(nodes), in §4.2.6
-   
  • after(nodes...), in §4.2.6
+   
  • after(nodes), in §4.2.8
+   
  • after(nodes...), in §4.2.8
    
  • ancestor, in §2.1
-   
  • append, in §4.2.1
+   
  • append, in §4.2.3
    
  • append an attribute, in §4.9
    
  • appendChild(node), in §4.4
    
  • appendData(data), in §4.10
-   
  • append(nodes), in §4.2.4
-   
  • append(nodes...), in §4.2.4
+   
  • append(nodes), in §4.2.6
+   
  • append(nodes...), in §4.2.6
    
  • ASCII case-insensitive, in §2.2
    
  • ASCII case-insensitively, in §2.2
    
  • attachShadow(init), in §4.9
@@ -4835,8 +4841,8 @@ 
    baseURI, in §4.4
    
  • base URL, in §4.5
    
  • before, in §5.2
-   
  • before(nodes), in §4.2.6
-   
  • before(nodes...), in §4.2.6
+   
  • before(nodes), in §4.2.8
+   
  • before(nodes...), in §4.2.8
    
  • boundary point, in §5.2
    
  • 
     bubbles
@@ -4866,15 +4872,15 @@ 
    characterSet, in §4.5
    
  • charset, in §4.5
    
  • child, in §2.1
-   
  • childElementCount, in §4.2.4
+   
  • childElementCount, in §4.2.6
    
  • childList, in §4.3.1
-   
  • ChildNode, in §4.2.6
+   
  • ChildNode, in §4.2.8
    
  • childNodes, in §4.4
    
  • 
     children
     
    
  • class, in §4.9
    
  • classList, in §4.9
@@ -4892,7 +4898,7 @@ 
    collapsed, in §5.2
    
  • collapse(toStart), in §5.2
    
  • collect a code point sequence, in §2.3
-   
  • collection, in §4.2.8
+   
  • collection, in §4.2.10
    
  • Comment, in §4.13
    
  • Comment(data), in §4.13
    
  • COMMENT_NODE, in §4.4
@@ -4911,7 +4917,7 @@ 
    contiguous Text nodes, in §4.11
    
  • converted to ASCII lowercase, in §2.2
    
  • converted to ASCII uppercase, in §2.2
-   
  • converting nodes into a node, in §4.2.4
+   
  • converting nodes into a node, in §4.2.6
    
  • createAttribute(localName), in §4.5
    
  • createAttributeNS(namespace, qualifiedName), in §4.5
    
  • createCDATASection(), in §8.2
@@ -4977,18 +4983,19 @@ 
    Document, in §4.5
    
  • document, in §4.5
    
  • documentElement, in §4.5
-   
  • document element, in §4.9
+   
  • document element, in §4.2.1
    
  • DocumentFragment, in §4.7
    
  • DocumentFragment(), in §4.7
    
  • DOCUMENT_FRAGMENT_NODE, in §4.4
    
  • DOCUMENT_NODE, in §4.4
-   
  • DocumentOrShadowRoot, in §4.2.3
+   
  • DocumentOrShadowRoot, in §4.2.5
    
  • DOCUMENT_POSITION_CONTAINED_BY, in §4.4
    
  • DOCUMENT_POSITION_CONTAINS, in §4.4
    
  • DOCUMENT_POSITION_DISCONNECTED, in §4.4
    
  • DOCUMENT_POSITION_FOLLOWING, in §4.4
    
  • DOCUMENT_POSITION_IMPLEMENTATION_SPECIFIC, in §4.4
    
  • DOCUMENT_POSITION_PRECEDING, in §4.4
+   
  • document tree, in §4.2.1
    
  • DocumentType, in §4.6
    
  • DOCUMENT_TYPE_NODE, in §4.4
    
  • documentURI, in §4.5
@@ -5014,7 +5021,7 @@ 
    Element, in §4.9
    
  • element interface, in §4.5
    
  • ELEMENT_NODE, in §4.4
-   
  • Elements, in §4.2.7
+   
  • Elements, in §4.2.9
    
  • empty, in §4.2
    
  • encapsulation mode, in §4.8
    
  • encoding, in §4.5
@@ -5025,7 +5032,7 @@ 
    endOffset, in §5.2
    
  • END_TO_END, in §5.2
    
  • END_TO_START, in §5.2
-   
  • ensure pre-insertion validity, in §4.2.1
+   
  • ensure pre-insertion validity, in §4.2.3
    
  • entities, in §8.2
    
  • Entity, in §8.2
    
  • ENTITY_NODE, in §4.4
@@ -5062,7 +5069,7 @@ 
    firstChild(), in §6.2
    
  • firstChild, in §4.4
    
  • first child, in §2.1
-   
  • firstElementChild, in §4.2.4
+   
  • firstElementChild, in §4.2.6
    
  • flatten, in §3.6
    
  • following, in §2.1
    
  • get an attribute by name, in §4.9
@@ -5072,7 +5079,7 @@ 
    getAttributeNode(qualifiedName), in §4.9
    
  • getAttributeNS(namespace, localName), in §4.9
    
  • getAttribute(qualifiedName), in §4.9
-   
  • getElementById(elementId), in §4.2.2
+   
  • getElementById(elementId), in §4.2.4
    
  • 
     getElementsByClassName(classNames)
     
      
@@ -5120,7 +5127,7 @@ 
      attribute for ShadowRoot, in §4.8
     
    
    
  • host-including inclusive ancestor, in §4.7
-   
  • HTMLCollection, in §4.2.8.2
+   
  • HTMLCollection, in §4.2.10.2
    
  • HTML document, in §4.5
    
  • HTML namespace, in §2.5
    
  • id, in §4.9
@@ -5128,7 +5135,7 @@ 
    implementation, in §4.5
    
  • importNode(node), in §4.5
    
  • importNode(node, deep), in §4.5
-   
  • in a document, in §4.9
+   
  • in a document, in §4.2.1
    
  • inclusive ancestor, in §2.1
    
  • inclusive descendant, in §2.1
    
  • inclusive sibling, in §2.1
@@ -5143,7 +5150,7 @@ 
    dfn for Node, in §4.2.1
+     
  • dfn for Node, in §4.2.3
      
  • dfn for Range, in §5.2
     
    
  • insert adjacent, in §4.9
@@ -5151,7 +5158,7 @@ 
    insertAdjacentText(where, data), in §4.9
    
  • insertBefore(node, child), in §4.4
    
  • insertData(offset, data), in §4.10
-   
  • insertion steps, in §4.2.1
+   
  • insertion steps, in §4.2.3
    
  • insertNode(node), in §5.2
    
  • internalSubset, in §8.2
    
  • intersectsNode(node), in §5.2
@@ -5166,8 +5173,8 @@ 
    method for NodeList, in §4.2.8.1
-     
  • method for HTMLCollection, in §4.2.8.2
+     
  • method for NodeList, in §4.2.10.1
+     
  • method for HTMLCollection, in §4.2.10.2
      
  • method for NamedNodeMap, in §4.9.1
      
  • method for DOMTokenList, in §7.1
     
@@ -5175,13 +5182,13 @@ 
    last child, in §2.1
    
  • lastChild(), in §6.2
    
  • lastChild, in §4.4
-   
  • lastElementChild, in §4.2.4
+   
  • lastElementChild, in §4.2.6
    
  • 
     length
     
-   
  • nextElementSibling, in §4.2.5
+   
  • nextElementSibling, in §4.2.7
    
  • 
     nextNode()
     
    
  • prefix match, in §2.2
-   
  • pre-insert, in §4.2.1
-   
  • prepend(nodes...), in §4.2.4
-   
  • prepend(nodes), in §4.2.4
-   
  • pre-remove, in §4.2.1
+   
  • pre-insert, in §4.2.3
+   
  • prepend(nodes...), in §4.2.6
+   
  • prepend(nodes), in §4.2.6
+   
  • pre-remove, in §4.2.3
    
  • preventDefault(), in §3.2
-   
  • previousElementSibling, in §4.2.5
+   
  • previousElementSibling, in §4.2.7
    
  • 
     previousNode()
     
      
@@ -5362,22 +5369,22 @@ 
      dfn for Element, in §4.9
      
    • dfn for Attr, in §4.9.2
     
    
-   
  • queryAll(DOMString relativeSelectors), in §4.2.7
+   
  • queryAll(DOMString relativeSelectors), in §4.2.9
    
  • 
     queryAll(relativeSelectors)
     
-   
  • query(DOMString relativeSelectors), in §4.2.7
+   
  • query(DOMString relativeSelectors), in §4.2.9
    
  • 
     query(relativeSelectors)
     
-   
  • querySelectorAll(selectors), in §4.2.4
-   
  • querySelector(selectors), in §4.2.4
+   
  • querySelectorAll(selectors), in §4.2.6
+   
  • querySelector(selectors), in §4.2.6
    
  • queue a mutation observer compound microtask, in §4.3
    
  • queue a mutation record, in §4.3.2
    
  • quirks mode, in §4.5
@@ -5392,10 +5399,10 @@ 
    method for ChildNode, in §4.2.6
+     
  • method for ChildNode, in §4.2.8
      
  • method for DOMTokenList, in §7.1
     
-   
  • remove, in §4.2.1
+   
  • remove, in §4.2.3
    
  • remove an attribute, in §4.9
    
  • remove an attribute by name, in §4.9
    
  • remove an attribute by namespace and local name, in §4.9
@@ -5409,19 +5416,19 @@ 
    removeNamedItemNS(namespace, localName), in §4.9.1
    
  • removeNamedItem(qualifiedName), in §4.9.1
    
  • remove(tokens), in §7.1
-   
  • removing steps, in §4.2.1
+   
  • removing steps, in §4.2.3
    
  • renameNode(), in §8.2
-   
  • replace, in §4.2.1
-   
  • replace all, in §4.2.1
+   
  • replace, in §4.2.3
+   
  • replace all, in §4.2.3
    
  • replace an attribute, in §4.9
    
  • replaceChild(node, child), in §4.4
    
  • replace data, in §4.10
    
  • replaceData(offset, count, data), in §4.10
    
  • replace(token, newToken), in §7.1
    
  • replaceWholeText(), in §8.2
-   
  • replaceWith(nodes...), in §4.2.6
-   
  • replaceWith(nodes), in §4.2.6
-   
  • represented by the collection, in §4.2.8
+   
  • replaceWith(nodes...), in §4.2.8
+   
  • replaceWith(nodes), in §4.2.8
+   
  • represented by the collection, in §4.2.10
    
  • 
     root