tree: fd1ed620e4c582ed19c0a468b93d97340e64be70 [path history] [tgz]
  1. events/
  2. ng/
  3. trustedtypes/
  4. AccessibleNode.cpp
  5. AccessibleNode.h
  6. AccessibleNode.idl
  7. AccessibleNodeList.cpp
  8. AccessibleNodeList.h
  9. AccessibleNodeList.idl
  10. AnimationWorkletProxyClient.cpp
  11. AnimationWorkletProxyClient.h
  12. Attr.cpp
  13. Attr.h
  14. Attr.idl
  15. Attribute.h
  16. AttributeCollection.h
  17. AttrTest.cpp
  18. AXObjectCache.cpp
  19. AXObjectCache.h
  20. AXObjectCacheBase.cpp
  21. AXObjectCacheBase.h
  22. BlinkCloneableMessage.cpp
  23. BlinkCloneableMessage.h
  24. BlinkCloneableMessage.typemap
  25. BlinkCloneableMessageStructTraits.cpp
  26. BlinkCloneableMessageStructTraits.h
  27. BlinkTransferableMessage.cpp
  28. BlinkTransferableMessage.h
  29. BlinkTransferableMessage.typemap
  30. BlinkTransferableMessageStructTraits.cpp
  31. BlinkTransferableMessageStructTraits.h
  32. BUILD.gn
  33. CDATASection.cpp
  34. CDATASection.h
  35. CDATASection.idl
  36. CharacterData.cpp
  37. CharacterData.h
  38. CharacterData.idl
  39. ChildFrameDisconnector.cpp
  40. ChildFrameDisconnector.h
  41. ChildListMutationScope.cpp
  42. ChildListMutationScope.h
  43. ChildNode.h
  44. ChildNode.idl
  45. ChildNodeList.cpp
  46. ChildNodeList.h
  47. ClassCollection.cpp
  48. ClassCollection.h
  49. ClassicPendingScript.cpp
  50. ClassicPendingScript.h
  51. ClassicScript.cpp
  52. ClassicScript.h
  53. CollectionIndexCache.h
  54. Comment.cpp
  55. Comment.h
  56. Comment.idl
  57. CommonDefinitions.idl
  58. ContainerNode.cpp
  59. ContainerNode.h
  60. ContextFeatures.cpp
  61. ContextFeatures.h
  62. ContextFeaturesClientImpl.cpp
  63. ContextFeaturesClientImpl.h
  64. ContextLifecycleNotifier.cpp
  65. ContextLifecycleNotifier.h
  66. ContextLifecycleObserver.cpp
  67. ContextLifecycleObserver.h
  68. DatasetDOMStringMap.cpp
  69. DatasetDOMStringMap.h
  70. DecodedDataDocumentParser.cpp
  71. DecodedDataDocumentParser.h
  72. DistributedNodes.cpp
  73. DistributedNodes.h
  74. Document.cpp
  75. Document.h
  76. Document.idl
  77. DocumentEncodingData.cpp
  78. DocumentEncodingData.h
  79. DocumentFragment.cpp
  80. DocumentFragment.h
  81. DocumentFragment.idl
  82. DocumentInit.cpp
  83. DocumentInit.h
  84. DocumentLifecycle.cpp
  85. DocumentLifecycle.h
  86. DocumentModulatorImpl.cpp
  87. DocumentModulatorImpl.h
  88. DocumentOrShadowRoot.h
  89. DocumentOrShadowRoot.idl
  90. DocumentParser.cpp
  91. DocumentParser.h
  92. DocumentParserClient.h
  93. DocumentParserTiming.cpp
  94. DocumentParserTiming.h
  95. DocumentShutdownNotifier.cpp
  96. DocumentShutdownNotifier.h
  97. DocumentShutdownObserver.cpp
  98. DocumentShutdownObserver.h
  99. DocumentStatisticsCollector.cpp
  100. DocumentStatisticsCollector.h
  101. DocumentStatisticsCollectorTest.cpp
  102. DocumentTest.cpp
  103. DocumentTiming.cpp
  104. DocumentTiming.h
  105. DocumentType.cpp
  106. DocumentType.h
  107. DocumentType.idl
  108. DocumentWriteIntervention.cpp
  109. DocumentWriteIntervention.h
  110. DOMException.cpp
  111. DOMException.h
  112. DOMException.idl
  113. DOMHighResTimeStamp.h
  114. DOMImplementation.cpp
  115. DOMImplementation.h
  116. DOMImplementation.idl
  117. DOMImplementationTest.cpp
  118. DOMNodeIds.cpp
  119. DOMNodeIds.h
  120. DOMStringList.cpp
  121. DOMStringList.h
  122. DOMStringList.idl
  123. DOMStringMap.cpp
  124. DOMStringMap.h
  125. DOMStringMap.idl
  126. DOMTimeStamp.h
  127. DOMTokenList.cpp
  128. DOMTokenList.h
  129. DOMTokenList.idl
  130. DynamicModuleResolver.cpp
  131. DynamicModuleResolver.h
  132. DynamicModuleResolverTest.cpp
  133. Element.cpp
  134. Element.h
  135. Element.idl
  136. ElementCreationOptions.idl
  137. ElementData.cpp
  138. ElementData.h
  139. ElementDataCache.cpp
  140. ElementDataCache.h
  141. ElementDefinitionOptions.idl
  142. ElementRareData.cpp
  143. ElementRareData.h
  144. ElementRegistrationOptions.idl
  145. ElementShadow.cpp
  146. ElementShadow.h
  147. ElementShadowV0.cpp
  148. ElementShadowV0.h
  149. ElementTest.cpp
  150. ElementTraversal.h
  151. ElementVisibilityObserver.cpp
  152. ElementVisibilityObserver.h
  153. ElementVisibilityObserverTest.cpp
  154. EmptyNodeList.cpp
  155. EmptyNodeList.h
  156. ExceptionCode.h
  157. ExecutionContext.cpp
  158. ExecutionContext.h
  159. FirstLetterPseudoElement.cpp
  160. FirstLetterPseudoElement.h
  161. FirstLetterPseudoElementTest.cpp
  162. FlatTreeTraversal.cpp
  163. FlatTreeTraversal.h
  164. FlatTreeTraversalTest.cpp
  165. FrameRequestCallback.idl
  166. FrameRequestCallbackCollection.cpp
  167. FrameRequestCallbackCollection.h
  168. FunctionStringCallback.idl
  169. GetRootNodeOptions.idl
  170. GlobalEventHandlers.h
  171. GlobalEventHandlers.idl
  172. IconURL.cpp
  173. IconURL.h
  174. IdleDeadline.cpp
  175. IdleDeadline.h
  176. IdleDeadline.idl
  177. IdleDeadlineTest.cpp
  178. IdleRequestCallback.idl
  179. IdleRequestOptions.idl
  180. IdTargetObserver.cpp
  181. IdTargetObserver.h
  182. IdTargetObserverRegistry.cpp
  183. IdTargetObserverRegistry.h
  184. IgnoreDestructiveWriteCountIncrementer.h
  185. IncrementLoadEventDelayCount.cpp
  186. IncrementLoadEventDelayCount.h
  187. Iterator.h
  188. Iterator.idl
  189. LayoutTreeBuilder.cpp
  190. LayoutTreeBuilder.h
  191. LayoutTreeBuilderTraversal.cpp
  192. LayoutTreeBuilderTraversal.h
  193. LayoutTreeBuilderTraversalTest.cpp
  194. LiveNodeList.cpp
  195. LiveNodeList.h
  196. LiveNodeListBase.cpp
  197. LiveNodeListBase.h
  198. LiveNodeListRegistry.cpp
  199. LiveNodeListRegistry.h
  200. LiveNodeListRegistryTest.cpp
  201. MessageChannel.cpp
  202. MessageChannel.h
  203. MessageChannel.idl
  204. MessagePort.cpp
  205. MessagePort.h
  206. MessagePort.idl
  207. MockScriptElementBase.h
  208. Modulator.cpp
  209. Modulator.h
  210. ModulatorImplBase.cpp
  211. ModulatorImplBase.h
  212. ModulatorTest.cpp
  213. ModuleImportMeta.h
  214. ModuleMap.cpp
  215. ModuleMap.h
  216. ModuleMapTest.cpp
  217. ModulePendingScript.cpp
  218. ModulePendingScript.h
  219. ModuleScript.cpp
  220. ModuleScript.h
  221. MutationObserver.cpp
  222. MutationObserver.h
  223. MutationObserver.idl
  224. MutationObserverInit.idl
  225. MutationObserverInterestGroup.cpp
  226. MutationObserverInterestGroup.h
  227. MutationObserverRegistration.cpp
  228. MutationObserverRegistration.h
  229. MutationObserverTest.cpp
  230. MutationRecord.cpp
  231. MutationRecord.h
  232. MutationRecord.idl
  233. NamedNodeMap.cpp
  234. NamedNodeMap.h
  235. NamedNodeMap.idl
  236. NameNodeList.cpp
  237. NameNodeList.h
  238. Node.cpp
  239. Node.h
  240. Node.idl
  241. NodeChildRemovalTracker.cpp
  242. NodeChildRemovalTracker.h
  243. NodeComputedStyle.h
  244. NodeFilter.h
  245. NodeFilter.idl
  246. NodeIterator.cpp
  247. NodeIterator.h
  248. NodeIterator.idl
  249. NodeIteratorBase.cpp
  250. NodeIteratorBase.h
  251. NodeList.h
  252. NodeList.idl
  253. NodeListsNodeData.cpp
  254. NodeListsNodeData.h
  255. NodeRareData.cpp
  256. NodeRareData.h
  257. NodeTest.cpp
  258. NodeTraversal.cpp
  259. NodeTraversal.h
  260. NodeTraversalStrategy.h
  261. NodeWithIndex.h
  262. NoncedElement.idl
  263. NonDocumentTypeChildNode.h
  264. NonDocumentTypeChildNode.idl
  265. NonElementParentNode.h
  266. NonElementParentNode.idl
  267. NthIndexCache.cpp
  268. NthIndexCache.h
  269. NthIndexCacheTest.cpp
  270. OWNERS
  271. ParentNode.h
  272. ParentNode.idl
  273. ParserContentPolicy.h
  274. PausableObject.cpp
  275. PausableObject.h
  276. PausableObjectTest.cpp
  277. PendingScript.cpp
  278. PendingScript.h
  279. Policy.cpp
  280. Policy.h
  281. Policy.idl
  282. PolicyTest.cpp
  283. PresentationAttributeStyle.cpp
  284. PresentationAttributeStyle.h
  285. ProcessingInstruction.cpp
  286. ProcessingInstruction.h
  287. ProcessingInstruction.idl
  288. PseudoElement.cpp
  289. PseudoElement.h
  290. PseudoElementData.h
  291. QualifiedName.cpp
  292. QualifiedName.h
  293. Range.cpp
  294. Range.h
  295. Range.idl
  296. RangeBoundaryPoint.h
  297. RangeTest.cpp
  298. RawDataDocumentParser.h
  299. README.md
  300. RemoteSecurityContext.cpp
  301. RemoteSecurityContext.h
  302. SandboxFlags.cpp
  303. SandboxFlags.h
  304. ScopedWindowFocusAllowedIndicator.h
  305. Script.h
  306. ScriptableDocumentParser.cpp
  307. ScriptableDocumentParser.h
  308. ScriptedAnimationController.cpp
  309. ScriptedAnimationController.h
  310. ScriptedAnimationControllerTest.cpp
  311. ScriptedIdleTaskController.cpp
  312. ScriptedIdleTaskController.h
  313. ScriptedIdleTaskControllerTest.cpp
  314. ScriptElementBase.cpp
  315. ScriptElementBase.h
  316. ScriptLoader.cpp
  317. ScriptLoader.h
  318. ScriptModuleResolver.h
  319. ScriptModuleResolverImpl.cpp
  320. ScriptModuleResolverImpl.h
  321. ScriptModuleResolverImplTest.cpp
  322. ScriptRunner.cpp
  323. ScriptRunner.h
  324. ScriptRunnerTest.cpp
  325. SecurityContext.cpp
  326. SecurityContext.h
  327. ShadowDOMV0Test.cpp
  328. ShadowRoot.cpp
  329. ShadowRoot.h
  330. ShadowRoot.idl
  331. ShadowRootInit.idl
  332. ShadowRootRareDataV0.h
  333. SinkDocument.cpp
  334. SinkDocument.h
  335. SlotAssignment.cpp
  336. SlotAssignment.h
  337. SpaceSplitString.cpp
  338. SpaceSplitString.h
  339. SpaceSplitStringTest.cpp
  340. StaticNodeList.h
  341. StaticRange.cpp
  342. StaticRange.h
  343. StaticRange.idl
  344. StaticRangeTest.cpp
  345. SynchronousMutationNotifier.cpp
  346. SynchronousMutationNotifier.h
  347. SynchronousMutationObserver.cpp
  348. SynchronousMutationObserver.h
  349. SyncReattachContext.cpp
  350. SyncReattachContext.h
  351. TagCollection.cpp
  352. TagCollection.h
  353. TaskTypeTraits.h
  354. TemplateContentDocumentFragment.h
  355. Text.cpp
  356. Text.h
  357. Text.idl
  358. TextLinkColors.cpp
  359. TextLinkColors.h
  360. TextTest.cpp
  361. ThrowOnDynamicMarkupInsertionCountIncrementer.h
  362. TransformSource.h
  363. TransformSourceLibxslt.cpp
  364. TreeOrderedList.cpp
  365. TreeOrderedList.h
  366. TreeOrderedMap.cpp
  367. TreeOrderedMap.h
  368. TreeScope.cpp
  369. TreeScope.h
  370. TreeScopeAdopter.cpp
  371. TreeScopeAdopter.h
  372. TreeScopeAdopterTest.cpp
  373. TreeScopeTest.cpp
  374. TreeWalker.cpp
  375. TreeWalker.h
  376. TreeWalker.idl
  377. UserActionElementSet.cpp
  378. UserActionElementSet.h
  379. UserGestureIndicator.cpp
  380. UserGestureIndicator.h
  381. UserGestureIndicatorTest.cpp
  382. V0InsertionPoint.cpp
  383. V0InsertionPoint.h
  384. ViewportDescription.cpp
  385. ViewportDescription.h
  386. VisitedLinkState.cpp
  387. VisitedLinkState.h
  388. WeakIdentifierMap.h
  389. WhitespaceAttacher.cpp
  390. WhitespaceAttacher.h
  391. WhitespaceAttacherTest.cpp
  392. WhitespaceLayoutObjects.md
  393. WorkerModulatorImpl.cpp
  394. WorkerModulatorImpl.h
  395. WorkletModulatorImpl.cpp
  396. WorkletModulatorImpl.h
  397. XMLDocument.cpp
  398. XMLDocument.h
  399. XMLDocument.idl
third_party/WebKit/Source/core/dom/README.md

DOM

Rendered

Author: hayato@chromium.org

The Source/core/dom directory contains the implementation of DOM.

Basically, this directory should contain only a file which is related to DOM Standard. However, for historical reasons, Source/core/dom directory has been used as if it were misc directory. As a result, unfortunately, this directory contains a lot of files which are not directly related to DOM.

Please don‘t add unrelated files to this directory any more. We are trying to organize the files so that developers wouldn’t get confused at seeing this directory.

  • See the spreadsheet, as a rough plan to organize Source/core/dom files.

    The classification in the spreadsheet might be wrong. Please update the spreadsheet, and move files if you can, if you know more appropriate places for each file.

  • See crbug.com/738794 for tracking our efforts.

Node and Node Tree

In this README, we draw a tree in left-to-right direction. A is the root of the tree.

A
├───B
├───C
   ├───D
   └───E
└───F

Node is a base class of all kinds of nodes in a node tree. Each Node has following 3 pointers (but not limited to):

  • parent_or_shadow_host_node_: Points to the parent (or the shadow host if it is a shadow root; explained later)
  • previous_: Points to the previous sibling
  • next_: Points to the next sibling

ContainerNode, from which Element extends, has additional pointers for its child:

  • first_child_: The meaning is obvious.
  • last_child_: Nit.

That means:

  • Siblings are stored as a linked list. It takes O(N) to access a parent's n-th child.
  • Parent can't tell how many children it has in O(1).

Further info:

  • Node, ContainerNode

C++11 range-based for loops for traversing a tree

You can traverse a tree manually:

// In C++

// Traverse a children.
for (Node* child = parent.firstChild(); child; child = child->nextSibling()) {
  ...
}

// ...

// Traverse nodes in tree order, depth-first traversal.
void foo(const Node& node) {
  ...
  for (Node* child = node.firstChild(); child; child = child->nextSibling()) {
    foo(*child);  // Recursively
  }
}

However, traversing a tree in this way might be error-prone. Instead, you can use NodeTraversal and ElementTraversal. They provides a C++11's range-based for loops, such as:

// In C++
for (Node& child : NodeTraversal::childrenOf(parent) {
  ...
}

e.g. Given a parent A, this traverses B, C, and F in this order.

// In C++
for (Node& node : NodeTraversal::startsAt(root)) {
  ...
}

e.g. Given the root A, this traverses A, B, C, D, E, and F in this order.

There are several other useful range-based for loops for each purpose. The cost of using range-based for loops is zero because everything can be inlined.

Further info:

  • NodeTraversal and ElementTraversal (more type-safe version)
  • The CL, which introduced these range-based for loops.

Shadow Tree

A shadow tree is a node tree whose root is a ShadowRoot. From web developer's perspective, a shadow root can be created by calling element.attachShadow{ ... } API. The element here is called a shadow host, or just a host if the context is clear.

  • A shadow root is always attached to another node tree through its host. A shadow tree is therefore never alone.
  • The node tree of a shadow root’s host is sometimes referred to as the light tree.

For example, given the example node tree:

A
├───B
├───C
   ├───D
   └───E
└───F

Web developers can create a shadow root, and manipulate the shadow tree in the following way:

// In JavaScript
const b = document.querySelector('#B');
const shadowRoot = b.attachShadow({ mode: 'open'} )
const sb = document.createElement('div');
shadowRoot.appendChild(sb);

The resulting shadow tree would be:

shadowRoot
└── sb

The shadowRoot has one child, sb. This shadow tree is being attached to B:

A
└── B
    ├──/shadowRoot
       └── sb
    ├── C
       ├── D
       └── E
    └── F

In this README, a notation (──/) is used to represent a shadowhost-shadowroot relationship, in a composed tree. A composed tree will be explained later. A shadowhost-shadowroot is 1:1 relationship.

Though a shadow root has always a corresponding shadow host element, a light tree and a shadow tree should be considered separately, from a node tree's perspective. (──/) is NOT a parent-child relationship in a node tree.

For example, even though B hosts the shadow tree, shadowRoot is not considered as a child of B. The means the following traversal:

// In C++
for (Node& node : NodeTraversal::startsAt(A)) {
  ...
}

traverses only A, B, C, D, E and F nodes. It never visits shadowRoot nor sb. NodeTraversal never cross a shadow boundary, ──/.

Further info:

  • ShadowRoot
  • Element#attachShadow

TreeScope

Document and ShadowRoot are always the root of a node tree. BothDocument and ShadowRoot implements TreeScope.

TreeScope maintains a lot of information about the underlying tree for efficiency. For example, TreeScope has a id-to-element mapping, as TreeOrderedMap, so that querySelector('#foo') can find an element whose id attribute is “foo” in O(1). In other words, root.querySelector('#foo') can be slow if that is used in a node tree whose root is not TreeScope.

Each Node has tree_scope_ pointer, which points to:

  • The root node: if the node's root is either Document or ShadowRoot.
  • owner document, otherwise.

The means tree_scope_ pointer is always non-null (except for while in a DOM mutation), but it doesn‘t always point to the node’s root.

Since each node doesn't have a pointer which always points to the root, Node::getRootNode(...) may take O(N) if the node is neither in a document tree nor in a shadow tree. If the node is in TreeScope (Node#IsInTreeScope() can tell it), we can get the root in O(1).

Each node has flags, which is updated in DOM mutation, so that we can tell whether the node is in a document tree, in a shadow tree, or in none of them, by using Node::IsInDocumentTree() and/or Node::IsInShadowTree().

If you want to add new features to Document, Document might be a wrong place to add. Instead, please consider to add functionality to TreeScope. We want to treat a document tree and a shadow tree equally as much as possible.

Example

document
└── a1
    ├──/shadowRoot1
       └── s1
    └── a2
        └── a3

document-fragment
└── b1
    ├──/shadowRoot2
       └── t2
    └── b2
        └── b3
  • Here, there are 4 node trees; The root node of each tree is document, shadowRoot1, document-fragment, and shadowRoot2.
  • Suppose that each node is created by document.createElement(...) (except for Document and ShadowRoot). That means each node's owner document is document.
nodenode's rootnode's _tree_scope points to:
documentdocument (self)document (self)
a1documentdocument
a2documentdocument
a3documentdocument
shadowRoot1shadowRoot1 (self)shadowRoot1 (self)
s1shadowRoot1shadowRoot1
document-fragmentdocument-fragment (self)document
b1document-fragmentdocument
b2document-fragmentdocument
b3document-fragmentdocument
shadowRoot2shadowRoot2 (self)shadowRoot2 (self)
t1shadowRoot2shadowRoot2

Further Info:

Composed Tree (a tree of node trees)

In the previous picture, you might think that more than one node trees, a document tree and a shadow tree, were connected to each other. That is true in some sense. The following is a more complex example:

document
├── a1 (host)
   ├──/shadowRoot1
      └── b1
   └── a2 (host)
       ├──/shadowRoot2
          ├── c1
             ├── c2
             └── c3
          └── c4
       ├── a3
       └── a4
└── a5
    └── a6 (host)
        └──/shadowRoot3
            └── d1
                ├── d2
                ├── d3 (host)
                   └──/shadowRoot4
                       ├── e1
                       └── e2
                └── d4 (host)
                    └──/shadowRoot5
                        ├── f1
                        └── f2

If you see this carefully, you can notice that this composed tree is composed of 6 node trees; 1 document tree and 5 shadow trees:

  • document tree

    document
    ├── a1 (host)
       └── a2 (host)
           ├── a3
           └── a4
    └── a5
        └── a6 (host)
    
  • shadow tree 1

    shadowRoot1
    └── b1
    
  • shadow tree 2

    shadowRoot2
    ├── c1
       ├── c2
       └── c3
    └── c4
    
  • shadow tree 3

    shadowRoot3
    └── d1
        ├── d2
        ├── d3 (host)
        └── d4 (host)
    
  • shadow tree 4

    shadowRoot4
    ├── e1
    └── e2
    
  • shadow tree 5

    shadowRoot5
    ├── f1
    └── f2
    

If we consider each node tree as node of a super-tree, we can draw a super-tree as such:

document
├── shadowRoot1
├── shadowRoot2
└── shadowRoot3
    ├── shadowRoot4
    └── shadowRoot5

Here, a root node is used as a representative of each node tree; A root node and a node tree itself can be sometimes exchangeable in explanations.

We call this kind of a super-tree (a tree of node trees) a composed tree. The concept of a composed tree is very useful to understand how Shadow DOM's encapsulation works.

DOM Standard defines the following terminologies:

For example,

  • d1's shadow-including ancestor nodes are shadowRoot3, a6, a5, and document
  • d1's shadow-including descendant nodes are d2, d3, shadowRoot4, e1, e2, d4, shadowRoot5, f1, and f2.

To honor Shadow DOM's encapsulation, we have a concept of visibility relationship between two nodes.

In the following table, “-” means that “node A is visible from node B”.

A \ Bdocumenta1a2b1c1d1d2e1f1
document---------
a1---------
a2---------
b1hiddenhiddenhidden-hiddenhiddenhiddenhiddenhidden
c1hiddenhiddenhiddenhidden-hiddenhiddenhiddenhidden
d1hiddenhiddenhiddenhiddenhidden----
d2hiddenhiddenhiddenhiddenhidden----
e1hiddenhiddenhiddenhiddenhiddenhiddenhidden-hidden
f1hiddenhiddenhiddenhiddenhiddenhiddenhiddenhidden-

For example, document is visible from any nodes.

To understand visibility relationship easily, here is a rule of thumb:

  • If node B can reach node A by traversing an edge (in the first picture of this section), recursively, A is visible from B.
  • However, an edge of (──/) ( shadowhost-shadowroot relationship) is one-directional:
    • From a shadow root to the shadow host -> Okay
    • From a shadow host to the shadow root -> Forbidden

In other words, a node in an inner tree can see a node in an outer tree in a composed tree, but the opposite is not true.

We have designed (or re-designed) a bunch of Web-facing APIs to honor this basic principle. If you add a new API to the web platform and Blink, please consider this rule and don't leak a node which should be hidden to web developers.

Warning: Unfortunately, a composed tree had a different meaning in the past; it was used to specify a flat tree (which will be explained later). If you find a wrong usage of a composed tree in Blink, please fix it.

Further Info:

  • TreeScope::ParentTreeScope()
  • Node::IsConnected()
  • DOM Standard: connected
  • DOM Standard: retarget

Flat tree

A composed tree itself can‘t be rendered as is. From the rendering’s perspective, Blink has to construct a layout tree, which would be used as an input to the paint phase. A layout tree is a tree whose node is LayoutObject, which points to Node in a node tree, plus additional calculated layout information.

Before the Web Platform got Shadow DOM, the structure of a layout tree is almost similar to the structure of a document tree; where only one node tree, document tree, is being involved there.

Since the Web Platform got Shadow DOM, we now have a composed tree which is composed of multiple node trees, instead of a single node tree. That means We have to flatten the composed tree to the one node tree, called a flat tree, from which a layout tree is constructed.

For example, given the following composed tree,

document
├── a1 (host)
   ├──/shadowRoot1
      └── b1
   └── a2 (host)
       ├──/shadowRoot2
          ├── c1
             ├── c2
             └── c3
          └── c4
       ├── a3
       └── a4
└── a5
    └── a6 (host)
        └──/shadowRoot3
            └── d1
                ├── d2
                ├── d3 (host)
                   └──/shadowRoot4
                       ├── e1
                       └── e2
                └── d4 (host)
                    └──/shadowRoot5
                        ├── f1
                        └── f2

This composed tree would be flattened into the following flat tree (assuming there are not <slot> elements there):

document
├── a1 (host)
   └── b1
└── a5
    └── a6 (host)
        └── d1
            ├── d2
            ├── d3 (host)
               ├── e1
               └── e2
            └── d4 (host)
                ├── f1
                └── f2

We can't explain the exact algorithm how to flatten a composed tree into a flat tree until I explain the concept of slots and node distribution If we are ignoring the effect of <slot>, we can have the following simple definition. A flat tree can be defined as:

  • A root of a flat tree: document
  • Given node A which is in a flat tree, its children are defined, recursively, as follows:
    • If A is a shadow host, its shadow root's children
    • Otherwise, A's children

Distribution and slots

TODO(hayato): Explain.

In the meantime, please see Incremental Shadow DOM.

FlatTreeTraversal

TODO(hayato): Explain.

DOM mutations

TODO(hayato): Explain.

Related flags

TODO(hayato): Explain.

Event path and Event Retargeting

TODO(hayato): Explain.