/
index.html
1552 lines (1297 loc) · 127 KB
/
index.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<!DOCTYPE html>
<html>
<head>
<meta charset='utf-8'/>
<title>Shadow DOM</title>
<link rel="stylesheet" href="../../assets/styles/respec-complement.css" type="text/css" />
<script src='//www.w3.org/Tools/respec/respec-w3c-common' async class='remove'></script>
<script class='remove'>
var respecConfig = {
specStatus: "ED"
, shortName: "shadow-dom"
, editors: [{ name: "Dimitri Glazkov", url: "mailto:dglazkov@chromium.org", company: "Google, Inc." },
{ name: "Hayato Ito", url: "mailto:hayato@google.com", company: "Google, Inc." }]
, wg: "W3C Web Applications (WebApps)"
, wgURI: "http://www.w3.org/2008/webapps/"
, wgPublicList: "public-webapps"
, wgPatentURI: ""
, edDraftURI: "http://w3c.github.io/webcomponents/spec/shadow/"
, otherLinks: [{
key: "Revision history",
href: "https://github.com/w3c/webcomponents/commits/gh-pages/spec/shadow/"
}
]
};
</script>
<script src="../../assets/scripts/bug-assist.js"></script>
<script src="../../assets/scripts/spec-assist.js"></script>
<meta name="bug.blocked" content="14978"/>
<meta name="bug.short_desc" content="[Shadow]: "/>
<meta name="bug.product" content="WebAppsWG"/>
<meta name="bug.component" content="Component Model"/>
</head>
<body>
<section id='abstract'>
<p>
This specification describes a method of establishing and maintaining functional boundaries between DOM trees
and how these trees interact with each other within a document, thus enabling better functional encapsulation
within the DOM.
</p>
</section>
<section id='sotd'>
<p class="warning">This specification is under heavy refactoring. Use the latest <a href="http://www.w3.org/TR/shadow-dom/">Working Draft</a> as a normative reference.</p>
</section>
<section id="about">
<h2>About this Document</h2>
<p>All diagrams, examples, notes, are non-normative, as well as sections explicitly marked as non-normative. Everything else in this specification is normative.</p>
<p>The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in the normative parts of this document are to be interpreted as described in <a href="http://dev.w3.org/2006/xbl2/#refsRFC2119">RFC2119</a>. For readability, these words do not appear in all uppercase letters in this specification.</p>
<p>To help with layering and to avoid circular dependencies between various parts of specification, this document consists of three consecutive narratives:
<ol>
<li>setting up the stage for the specification,</li>
<li>explaining of the conceptual model and algorithms behind it, and</li>
<li>expressing this model with DOM interfaces and HTML elements.</li>
</ol>
</p>
<p>In a sense, these parts can be viewed as <em>math</em>, which sets up the reasoning environment, <em>physics</em>, which is the theoretical reasoning about the concept, and <em>mechanics</em>, which is the practical application of this reasoning.</p>
<p>Any point, at which a conforming UA must make decisions about the state or reaction to the state of the conceptual model, is captured as <a href="http://en.wikipedia.org/wiki/Algorithm">algorithm</a>. The algorithms are defined in terms of processing equivalence. The <dfn id="dfn-processing-equivalence">processing equivalence</dfn> is a constraint imposed on the algorithm implementors, requiring the output of the both UA-implemented and the specified algorithm to be exactly the same for all inputs.</p>
</section>
<section id="dependencies">
<h2>Dependencies</h2>
<p>This document relies on the following specifications:</p>
<ul>
<li><a href="http://www.w3.org/TR/CSS2/">CSS Level 2 Revision 1</a></li>
<li><a href="http://www.w3.org/TR/cssom/">CSSOM</a></li>
<li><a href="http://www.w3.org/TR/DOM-Level-3-Events/">DOM Level 3 Events</a></li>
<li><a href="http://www.w3.org/TR/touch-events/">Touch Events version 1</a></li>
<li><a href="http://www.w3.org/TR/domcore/">DOM4 (DOM Core)</a></li>
<li><a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/">HTML</a></li>
<li><a href="http://html5.org/specs/dom-parsing.html">DOM Parsing and Serialization</a></li>
<li><a href="http://www.w3.org/TR/selectors4/">Selectors Level 4</a></li>
<li><a href="http://www.w3.org/TR/selectors-api2/">Selectors API Level 2</a></li>
</ul>
<p class="issue">In order to solve the problem of mysterious definitions, we may have to make a concise, complete introduction here. It should explain what shadowing means, how it relates rendering, and what problem shadow DOM solves.</p>
</section>
<section id="concepts">
<h2>Concepts</h2>
<section>
<h3>Shadow trees</h3>
<p>A <dfn id="dfn-document-tree">document tree</dfn> is a <a href="http://dom.spec.whatwg.org/#concept-node-tree">node tree</a> whose <a href="http://dom.spec.whatwg.org/#concept-tree-root">root</a> <a href="http://www.3.org/TR/domcore/#concept-node">node</a> is a <a href="http://dom.spec.whatwg.org/#concept-document">document</a>.</p>
<p>Any element can have an <dfn id="dfn-shadow-roots-list">associated ordered list</dfn> of zero or more <a href="http://dom.spec.whatwg.org/#concept-node-tree">node trees</a>.</p>
<p>An element <dfn id="dfn-verb-host">hosts</dfn> a <a href="http://dom.spec.whatwg.org/#concept-node-tree">node tree</a> if the <a href="http://dom.spec.whatwg.org/#concept-node-tree">node tree</a> is a member of this associated list.</p>
<p>A <dfn id="dfn-shadow-host">shadow host</dfn> is an element that <a href="#dfn-verb-host">hosts</a> one or more <a href="http://dom.spec.whatwg.org/#concept-node-tree">node trees</a>.</p>
<p>A <dfn id="dfn-shadow-tree">shadow tree</dfn> is a <a href="http://dom.spec.whatwg.org/#concept-node-tree">node tree</a> <a href="#dfn-verb-host">hosted</a> by a <a href="#dfn-shadow-host">shadow host</a>.</p>
<p>A <dfn id="dfn-shadow-root">shadow root</dfn> is the <a href="http://dom.spec.whatwg.org/#concept-tree-root">root</a> <a href="http://www.3.org/TR/domcore/#concept-node">node</a> of a shadow tree.</p>
<p>If more than one <a href="#dfn-shadow-root">shadow root</a> is <a href="#dfn-verb-host">hosted</a> by the same <a href="#dfn-shadow-host">shadow host</a>, the more recently added <a href="#dfn-shadow-root">shadow root</a> is called the <dfn id="dfn-younger-shadow-root">younger shadow root</dfn>, and the less recently added <a href="#dfn-shadow-root">shadow root</a> is called the <dfn id="dfn-older-shadow-root">older shadow root</dfn>.</p>
<p>If there is no <a href="#dfn-older-shadow-root">older shadow root</a> than a given <a href="#dfn-shadow-root">shadow root</a>,
the <a href="#dfn-shadow-root">shadow root</a> is called the <dfn id="dfn-oldest-shadow-root">oldest shadow root</dfn>.</p>
<p>If there is no <a href="#dfn-yonger-shadow-root">younger shadow root</a> than a given <a href="#dfn-shadow-root">shadow root</a>,
the <a href="#dfn-shadow-root">shadow root</a> is called the <dfn id="dfn-youngest-shadow-root">youngest shadow root</dfn>.</p>
</section>
<section>
<h3>Trees of trees</h3>
<p>A <dfn id="dfn-tree-of-trees">tree of trees</dfn> is a <a href="http://dom.spec.whatwg.org/#trees">tree</a> of <a href="http://dom.spec.whatwg.org/#concept-node-tree">node trees</a>.</p>
<figure>
<object data="../../assets/images/tree-of-trees.svg" width="650" height="823"></object>
<figcaption>Fig. A tree of trees</figcaption>
</figure>
<p>Just like a <a href="http://dom.spec.whatwg.org/#concept-node-tree">node tree</a> is defined as <a href="http://dom.spec.whatwg.org/#trees">a set of relationships</a> between <a href="http://www.3.org/TR/domcore/#concept-node">nodes</a>,
a <a href="#dfn-tree-of-trees">tree of trees</a> is similarly defined as a set of relationships between <a href="http://dom.spec.whatwg.org/#concept-node-tree">node trees</a>:
<ul>
<li>A <a href="http://dom.spec.whatwg.org/#concept-node-tree">node tree</a> <var>A</var> is called a <dfn id="dfn-parent-tree">parent tree</dfn> of a <a href="http://dom.spec.whatwg.org/#concept-node-tree">node tree</a> <var>B</var> if the <a href="#dfn-shadow-host">shadow host</a> of <var>B</var> <a href="http://dom.spec.whatwg.org/#concept-tree-participate">participates</a> in <var>A</var>.</li>
<li>If there is more than one <a href="http://dom.spec.whatwg.org/#concept-node-tree">node tree</a> that shares the same <a href="#dfn-parent-tree">parent tree</a>, the <a href="http://dom.spec.whatwg.org/#concept-tree-order">tree order</a> between them in the <a href="#dfn-tree-of-trees">tree of trees</a> is defined as follows:
<ol>
<li>Let <var>A</var> and <var>B</var> be <a href="http://dom.spec.whatwg.org/#concept-node-tree">node trees</a> that share the same <a href="#dfn-parent-tree">parent tree</a>.</li>
<li><var>A</var> comes before <var>B</var> if either of the following conditions is satisfied:
<ul>
<li>Both <var>A</var> and <var>B</var> are <a href="#dfn-verb-host">hosted</a> by the same <a href="#dfn-shadow-host">shadow host</a> and <var>A</var> is <a href="#dfn-older-shadow-root">older</a> than <var>B</var>.</li>
<li>The <a href="#dfn-shadow-host">shadow host</a> which <a href="#dfn-verb-host">hosts</a> <var>A</var> is <a href="http://dom.spec.whatwg.org/#concept-tree-preceding">preceding</a> the <a href="#dfn-shadow-host">shadow host</a> which <a href="#dfn-verb-host">hosts</a> <var>B</var>.</li>
</ul>
</li>
</ol>
</li>
<li>Other relationships and terms, such as <dfn id="dfn-root-tree">root tree</dfn>, <dfn id="dfn-child-tree" class="no-backreference">child tree</dfn>,
<dfn id="dfn-descendant-tree">descendant tree</dfn>, <dfn id="dfn-inclusive-descendant-tree">inclusive descendant tree</dfn>,
<dfn id="dfn-ancestor-tree">ancestor tree</dfn>, <dfn id="dfn-inclusive-ancestor-tree">inclusive ancestor tree</dfn>,
<dfn id="dfn-preceding-tree">preceding tree</dfn>
are defined in the similar way as defined in <a href="http://dom.spec.whatwg.org/#trees">trees</a>.</li>
</ul>
</p>
<div class="note">The <a href="#dfn-document-tree">document tree</a> is always the <a href="#dfn-root-tree">root tree</a> of a <a href="#dfn-tree-of-trees">tree of trees</a>.</div>
</section>
<section>
<h3>Composed trees</h3>
<p>A <dfn id="dfn-composed-tree">composed tree</dfn> is a <a href="http://dom.spec.whatwg.org/#concept-node-tree">node tree</a> which is constructed out of <a href="http://www.3.org/TR/domcore/#concept-node">nodes</a> from multiple <a href="http://dom.spec.whatwg.org/#concept-node-tree">node trees</a> in a <a href="#dfn-tree-of-trees">tree of trees</a>.
The exact algorithm of constructing a composed tree is specified later.</p>
<figure>
<object data="../../assets/images/composed-tree.svg" width="654" height="606"></object>
<figcaption>Fig. A composed tree</figcaption>
</figure>
<p>In <dfn id="dfn-rendering">rendering</dfn> a <a href="#dfn-document-tree">document tree</a>, or presenting it visually, the <a href="#dfn-composed-tree">composed tree</a> <strong>must</strong> be used instead of the <a href="#dfn-document-tree">document tree</a>.</p>
<p>If any condition which affects a <a href="#dfn-distribution-map">composed tree</a> has changed, the <a href="#dfn-distribution-map">composed tree</a> <strong>must</strong> be updated before the <a href="#dfn-rendering">rendering</a> occurs.</p>
<p class="issue">We should probably enumerate these conditions, here or later.</p>
</section>
<section>
<h3>Distributions</h3>
<p>An <dfn id="dfn-insertion-point">insertion point</dfn> is a defined location where <a href="http://www.3.org/TR/domcore/#concept-node">nodes</a> in a different <a href="http://dom.spec.whatwg.org/#concept-node-tree">node tree</a> appear instead of the nodes's original position when constructing a <a href="#dfn-composed-tree">composed tree</a>.</p>
<figure>
<object data="../../assets/images/distributions.svg" width="663" height="598"></object>
<figcaption>Fig. A distribution</figcaption>
</figure>
<p>A <dfn id="dfn-distribution">distribution</dfn> is the mechanism that determines which <a href="http://www.3.org/TR/domcore/#concept-node">nodes</a> appear at each <a href="#dfn-insertion-point">insertion point</a>. The exact algorithm of a <a href="#dfn-distribution">distribution</a> is specified later.</p>
</section>
</section>
<section id="encapsulation">
<h2>Encapsulation</h2>
<p>The <a href="http://www.w3.org/TR/domcore/#dom-node-ownerdocument"><code>ownerDocument</code></a> property of a <a href="http://www.3.org/TR/domcore/#concept-node">node</a> in a shadow tree <strong>must</strong> refers to the <a href="http://dom.spec.whatwg.org/#concept-document">document</a> of the <a href="#dfn-shadow-host">shadow host</a> which <a href="#dfn-verb-host">hosts</a> the shadow tree.</p>
<p><a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/browsers.html#window"><code>Window</code></a> object <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/browsers.html#named-access-on-the-window-object">named properties</a> <strong>must</strong> access the <a href="http://www.3.org/TR/domcore/#concept-node">nodes</a> in the <a href="#dfn-root-tree">root tree</a>.</p>
<div class="note">For convenience, the <a href="#dfn-shadow-root">shadow root</a> provides its own set of <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/dom.html#dom-tree-accessors">DOM tree accessor</a> methods. No <a href="http://www.w3.org/TR/domcore/#concept-node">nodes</a> other than the <a href="#dfn-shadow-root">shadow root</a> descendants are accessible with these methods.</div>
<p class="issue">This section is tiny. Maybe we could merge it into some other place? Encapsulation is effectively a natural property of having multiple trees.</p>
</section>
<section id="distributions">
<h2>Distributions</h2>
<section id="content-insertion-points">
<h3>Content Insertion Points</h3>
<p>A <dfn id="dfn-content-insertion-point">content insertion point</dfn> is an <a href="#dfn-insertion-point">insertion point</a> to where the child <a href="http://www.3.org/TR/domcore/#concept-node">nodes</a> of the <a href="#dfn-shadow-host">shadow host</a> are distributed.
The <a href="#dfn-content-element">content HTML element</a> that satisfies all of the following conditions represents a <a href="#dfn-content-insertion-point">content insertion point</a>:
<ul>
<li>The <a href="http://dom.spec.whatwg.org/#concept-tree-root">root</a> <a href="http://www.3.org/TR/domcore/#concept-node">node</a> of the <a href="#dfn-content-element">content HTML element</a> is a <a href="#dfn-shadow-root">shadow root</a></li>
<li>There is at most one <a href="#dfn-shadow-element">shadow HTML element</a> in the <a href="http://dom.spec.whatwg.org/#concept-tree-ancestor">ancestors</a> of the <a href="#dfn-content-element">content HTML element</a></li>
<li>There is no other <a href="#dfn-content-element">content HTML element</a> in the <a href="http://dom.spec.whatwg.org/#concept-tree-ancestor">ancestors</a> of the <a href="#dfn-content-element">content HTML element</a></li>
</ul>
</p>
<p class="issue">Bring in HTML element and interface definitions here</p>
</section>
<section id="shadow-insertion-points">
<h3>Shadow Insertion Points</h3>
<p>A <dfn id="dfn-shadow-insertion-point">shadow insertion point</dfn> is an <a href="#dfn-insertion-point">insertion point</a> to where the children of the <a href="#dfn-older-shadow-root">older shadow root</a> are distributed.
The <a href="#dfn-shadow-element">shadow HTML element</a> that satisfies of the following conditions represents a <a href="#dfn-shadow-insertion-point">shadow insertion point</a>:
<ul>
<li>The <a href="http://dom.spec.whatwg.org/#concept-tree-root">root</a> <a href="http://www.3.org/TR/domcore/#concept-node">node</a> of the <a href="#dfn-shadow-element">shadow HTML element</a> is a <a href="#dfn-shadow-root">shadow root</a></li>
<li>There is no other <a href="#dfn-shadow-element">shadow HTML element</a> which is <a href="http://dom.spec.whatwg.org/#concept-tree-preceding">preceding</a> the <a href="#dfn-shadow-element">shadow HTML element</a></li>
<li>There is no other <a href="#dfn-content-element">content HTML element</a> in the <a href="http://dom.spec.whatwg.org/#concept-tree-ancestor">ancestors</a> of the <a href="#dfn-shadow-element">shadow HTML element</a></li>
</ul>
</p>
<p class="issue">Bring in HTML element and interface definitions here</p>
</section>
<section id="distribution-results">
<h3>Distribution Results</h3>
<p>Each <a href="#dfn-tree-of-trees">tree of trees</a> has the <dfn id="dfn-distribution-result">distribution result</dfn> which describes the result of distributions.
The <a href="#dfn-distribution-result">distribution result</a> <strong>must</strong> be <a href="#dfn-processing-equivalence">equivalent</a> of the following:
<ol>
<li>Each <a href="#dfn-insertion-point">insertion point</a> has an ordered list, called <dfn id="dfn-distributed-nodes">distributed nodes</dfn>, which consists of <a href="http://www.3.org/TR/domcore/#concept-node">nodes</a> which are distributed into the <a href="#dfn-insertion-point">insertion point</a>.</li>
<li>Each <a href="http://www.3.org/TR/domcore/#concept-node">node</a> that is not an <a href="#dfn-insertion-point">insertion point</a> has an ordered list, called <dfn id="dfn-destination-insertion-points">destination insertion points</dfn>, which consists of <a href="#dfn-insertion-point">insertion points</a> to where the <a href="http://www.3.org/TR/domcore/#concept-node">node</a> is distributed</li>
</ol>
</p>
<div class="note"><p>One case that deserves special consideration is the situation when an <a href="#dfn-insertion-point">insertion point</a> is a child <a href="http://www.w3.org/TR/domcore/#concept-node">node</a> of another <a href="#dfn-shadow-host">shadow host</a>. In such situations, the <a href="http://www.w3.org/TR/domcore/#concept-node">nodes</a> <a href="#dfn-distribution">distributed</a> into that <a href="#dfn-insertion-point">insertion point</a> appear as if they were child <a href="http://www.w3.org/TR/domcore/#concept-node">nodes</a> of the <a href="#dfn-shadow-host">shadow host</a> in the context of <a href="#dfn-distribution">distribution</a>. Thus, the <a href="http://www.w3.org/TR/domcore/#concept-node">nodes</a> <a href="#dfn-distribution">distributed</a> to a <a href="#dfn-shadow-tree">shadow tree</a> could have already been <a href="#dfn-distribution">distributed</a> from its parent tree.</p>
<p>Despite being distributed to more than one insertion point, a node still only appears once in the composed tree at the final destination.</p>
</div>
<figure>
<object data="../../assets/images/re-distributions.svg" width="693" height="822"></object>
<figcaption>Fig. A re-distribution</figcaption>
<p>In the figure, a node <em>child 1</em> is distributed into <em>insertion point 1</em>. Then <em>child1</em> is re-distributed into <em>insertion point 3</em>.
The destination insertion points of <em>child 1</em> is [<em>insertion point 1</em>, <em>insertion point 3</em>] and <em>insertion point 3</em> is the final destination of <em>child 1</em>.
The distributed nodes of <em>insertion point 1</em> and <em>insertion point 3</em> is [<em>child 1</em>] and [<em>child 1</em>, <em>child 3</em>], respectively.</p>
</figure>
<p>When a <a href="http://www.3.org/TR/domcore/#concept-node">node</a> <var>A</var> is <dfn id="dfn-distribute">distributed</dfn> into an <a href="#dfn-insertion-point">insertion point</a> <var>B</var>, the following steps <strong>must</strong> happen:
<ul>
<li>Add <var>A</var> to the <a href="#dfn-distributed-nodes">distributed nodes</a> of <var>B</var></li>
<li>Add <var>B</var> to the <a href="#dfn-destination-insertion-points">destination insertion points</a> of <var>A</var></li>
</ul>
</p>
<p>An <a href="#dfn-insertion-point">insertion point</a> <var>A</var> is the <dfn id="dfn-final-destination">final destination</dfn> of a <a href="http://www.3.org/TR/domcore/#concept-node">node</a> <var>B</var> if <var>A</var> is the last item of the <a href="#dfn-destination-insertion-points">destination insertion points</a> of <var>B</var>.</p>
</section>
<section id="distribution-algorithms">
<h3>Distribution Algorithms</h3>
<p>The <dfn id="dfn-distribution-algorithm">distribution algorithm</dfn> <strong>must</strong> be used to determine the <a href="#dfn-distribution-result">distribution result</a> for a <a href="#dfn-tree-of-trees">tree of trees</a> and <strong>must</strong> be <a href="#dfn-processing-equivalence">equivalent</a> to processing the following steps:</p>
<div class="algorithm">
<dl>
<dt>Input</dt>
<dd><var>TREE-OF-TREES</var>, a <a href="#dfn-tree-of-trees">tree of trees</a></dd>
<dt>Output</dt>
<dd>The <a href="#dfn-distribution-result">distribution result</a> of <var>TREE-OF-TREES</var> is updated</dd>
</dl>
<ol>
<li>Let all <a href="#dfn-distributed-nodes">distributed nodes</a> and <a href="#dfn-destination-insertion-points">destination insertion points</a> owned by <a href="http://www.3.org/TR/domcore/#concept-node">nodes</a> in <var>TREE-OF-TREES</var> be empty</li>
<li>Let <var>ROOT</var> be the <a href="http://dom.spec.whatwg.org/#concept-tree-root">root</a> <a href="http://www.3.org/TR/domcore/#concept-node">node</a> of the <a href="#dfn-root-tree">root tree</a> of <var>TREE-OF-TREES</var></li>
<li>Run the <a href="#dfn-distribution-resolution-algorithm">distribution resolution algorithm</a> with <var>ROOT</var> as input</li>
</ol>
</div>
<p>The <dfn id="dfn-distribution-resolution-algorithm">distribution resolution algorithm</dfn> <strong>must</strong> be used to determine the <a href="#dfn-distribution-result">distribution result</a> for a given <a href="http://dom.spec.whatwg.org/#concept-node-tree">node tree</a> and its <a href="#dfn-descendant-tree">descendant trees</a>, and <strong>must</strong> be <a href="#dfn-processing-equivalence">equivalent</a> to processing the following steps:</p>
<div class="algorithm">
<dl>
<dt>Input</dt>
<dd><var>ROOT</var>, the <a href="http://dom.spec.whatwg.org/#concept-tree-root">root</a> <a href="http://www.3.org/TR/domcore/#concept-node">node</a> of a <a href="http://dom.spec.whatwg.org/#concept-node-tree">node tree</a></dd>
<dt>Output</dt>
<dd>The <a href="#dfn-distribution-result">distribution result</a> is updated for the <a href="#dfn-inclusive-descendant-tree">inclusive descendant trees</a> of <var>ROOT</var></dd>
</dl>
<ol>
<li>For each <a href="#dfn-shadow-host">shadow host</a>, <var>SHADOW-HOST</var>, that is a <a href="http://dom.spec.whatwg.org/#concept-tree-descendant">descendant</a> of <var>ROOT</var>, in <a href="http://dom.spec.whatwg.org/#concept-tree-order">tree order</a>:
<ol>
<li>Let <var>POOL</var> be the result of the <a href="#dfn-pool-population-algorithm">pool population algorithm</a> with <var>SHADOW-HOST</var> as input</li>
<li>For each <a href="#dfn-shadow-root">shadow root</a>, <var>SHADOW-ROOT</var>, which <var>SHADOW-HOST</var> <a href="#dfn-verb-host">hosts</a>, in order from the <a href="#dfn-youngest-shadow-root">youngest shadow root</a> to the <a href="#dfn-oldest-shadow-root">oldest shadow root</a>:
<ol>
<li>Run the <a href="#dfn-pool-distribution-algorithm">pool distribution algorithm</a> with <var>SHADOW-ROOT</var> and <var>POOL</var> as input</li>
<li>Let <var>SHADOW</var> be the <a href="#dfn-shadow-insertion-point">shadow insertion point</a> which is a <a href="http://dom.spec.whatwg.org/#concept-tree-descendant">descendant</a> of <var>SHADOW-ROOT</var></li>
<li>If such a <var>SHADOW</var> exits:
<ol>
<li>If <var>SHADOW</var> has child <a href="http://www.3.org/TR/domcore/#concept-node">nodes</a>:
<ol>
<li>Let <var>POOL</var> be the result of the <a href="#dfn-pool-population-algorithm">pool population algorithm</a> with <var>SHADOW</var> as input</li>
</ol></li>
</ol></li>
<li>Otherwise:
<ol>
<li>Let <var>POOL</var> be an empty ordered list.</li>
</ol></li>
</ol></li>
<li>For each <a href="#dfn-shadow-root">shadow root</a>, <var>SHADOW-ROOT</var>, that <var>SHADOW-HOST</var> <a href="#dfn-verb-host">hosts</a>, in order from the <a href="#dfn-oldest-shadow-root">oldest shadow root</a> to the <a href="#dfn-youngest-shadow-root">youngest shadow root</a>:
<ol>
<li>Let <var>SHADOW</var> be the <a href="#dfn-shadow-insertion-point">shadow insertion point</a> which is a <a href="http://dom.spec.whatwg.org/#concept-tree-descendant">descendant</a> of <var>SHADOW-ROOT</var></li>
<li>If such a <var>SHADOW</var> exits:
<ol>
<li>If <var>SHADOW-ROOT</var> is the <a href="#dfn-oldest-shadow-root">oldest shadow root</a>:
<ol>
<li>If <var>SHADOW</var> has child <a href="http://www.3.org/TR/domcore/#concept-node">nodes</a>:
<ol>
<li>Let <var>SHADOW-POOL</var> be the result of the <a href="#dfn-pool-population-algorithm">pool population algorithm</a> with <var>SHADOW</var> as input.</li>
</ol></li>
<li>Otherwise:
<ol>
<li>Let <var>SHADOW-POOL</var> be <var>POOL</var>.</li>
</ol></li>
</ol></li>
<li>Otherwise:
<ol>
<li>Let <var>SHADOW-POOL</var> be the result of the <a href="#dfn-pool-population-algorithm">pool population algorithm</a> with the <a href="#dfn-older-shadow-root">older shadow root</a> relative to <var>SHADOW-ROOT</var> as input.</li>
</ol></li>
<li>For each <a href="http://www.3.org/TR/domcore/#concept-node">node</a>, <var>CHILD</var>, in <var>SHADOW-POOL</var>
<ol>
<li><a href="#dfn-distribute">Distribute</a> <var>CHILD</var> into <var>SHADOW</var></li>
</ol></li>
</ol></li>
<li>Run the <a href="#dfn-distribution-resolution-algorithm">distribution resolution algorithm</a>, recursively, with <var>SHADOW-ROOT</var> as input</li>
</ol></li>
</ol></li>
</ol>
</div>
<p>The <dfn id="dfn-pool-population-algorithm">pool population algorithm</dfn> <strong>must</strong> be used to populate <a href="http://www.3.org/TR/domcore/#concept-node">nodes</a> from the child <a href="http://www.3.org/TR/domcore/#concept-node">nodes</a> of a given <a href="http://www.3.org/TR/domcore/#concept-node">node</a> and <strong>must</strong> be <a href="#dfn-processing-equivalence">equivalent</a> to processing the following steps:</p>
<div class="algorithm">
<dl>
<dt>Input</dt>
<dd><var>NODE</var>, a node</dd>
<dt>Output</dt>
<dd><var>POOL</var>, an ordered list of nodes</dd>
</dl>
<ol>
<li>Let <var>POOL</var> be an empty ordered list.</li>
<li>For each child <a href="http://www.3.org/TR/domcore/#concept-node">node</a>, <var>CHILD</var>, of <var>NODE</var>:
<ol>
<li>If <var>CHILD</var> is an <a href="#dfn-insertion-point">insertion point</a>:
<ol>
<li>Add all <a href="http://www.3.org/TR/domcore/#concept-node">nodes</a> in the <a href="#dfn-distributed-nodes">distributed nodes</a> of <var>CHILD</var> to <var>POOL</var></li>
</ol></li>
<li>Otherwise:
<ol>
<li>Add <var>CHILD</var> to <var>POOL</var></li>
</ol></li>
</ol></li>
</ol>
</div>
<p>The <dfn id="dfn-pool-distribution-algorithm">pool distribution algorithm</dfn> <strong>must</strong> be used to distribute <a href="http://www.3.org/TR/domcore/#concept-node">nodes</a> in a pool into the <a href="#dfn-content-insertion-point">content insertion points</a> in a <a href="#dfn-tree">tree</a> and <strong>must</strong> be <a href="#dfn-processing-equivalence">equivalent</a> to processing the following steps:</p>
<div class="algorithm">
<dl>
<dt>Input</dt>
<dd><var>SHADOW-ROOT</var>, a shadow root</dd>
<dd><var>POOL</var>, an ordered list of nodes</dd>
<dt>Output</dt>
<dd>Nodes in POOL are distributed into the content insertion points in the tree.</dd>
</dl>
<ol>
<li>For each <a href="#dfn-content-insertion-point">content insertion point</a>, <var>CONTENT</var>, which is descendant of <var>SHADOW-ROOT</var>, in <a href="#dfn-tree">tree</a> order:
<ol>
<li>For each <a href="http://www.3.org/TR/domcore/#concept-node">node</a>, <var>NODE</var>, in <var>POOL</var>
<ol>
<li>If <var>NODE</var> satisfies <var>CONTENT</var>'s matching criteria:
<ol>
<li><a href="#dfn-distribute">Distribute</a> <var>NODE</var> into <var>CONTENT</var></li>
<li>Remove <var>NODE</var> from <var>POOL</var></li>
</ol></li>
</ol></li>
<li>If there is no <a href="http://www.3.org/TR/domcore/#concept-node">nodes</a> distributed to <var>CONTENT</var>:
<ol>
<li>For each child, <var>CHILD</var>, of <var>CONTENT</var>
<ol>
<li><a href="#dfn-distribute">Distribute</a> <var>CHILD</var> into <var>CONTENT</var></li>
</ol></li>
</ol></li>
</ol></li>
</ol>
</div>
<div class="note">When there is no nodes distributed into a <a href="#dfn-content-insertion-point">content insertion point</a> <var>CONTENT</var>, the child <a href="http://www.3.org/TR/domcore/#concept-node">nodes</a> of <var>CONTENT</var> are distributed into <var>CONTENT</var> as fallback nodes.</div>
</section>
<section id="satisfying-matching-criteria">
<h3>Satisfying Matching Criteria</h3>
<p>The <a href="#dfn-matching-criteria">matching criteria</a> for an <a href="#dfn-insertion-point">insertion point</a> is a set of <a href="http://dev.w3.org/csswg/selectors4/#compound">compound selectors</a>. These <a href="http://dev.w3.org/csswg/selectors4/#compound">compound selectors</a> are restricted to contain only these <a href="http://dev.w3.org/csswg/selectors4/#simple">simple selectors</a>:</p>
<ul>
<li>A <a href="http://dev.w3.org/csswg/selectors4/#type-selector">type selector</a> or a <a href="http://dev.w3.org/csswg/selectors4/#universal-selector0">universal selector</a></li>
<li><a href="http://dev.w3.org/csswg/selectors4/#class-selector">class selector(s)</a></li>
<li>An <a href="http://dev.w3.org/csswg/selectors4/#id-selector">ID selector</a></li>
<li><a href="http://dev.w3.org/csswg/selectors4/#attribute-selector">attribute selector(s)</a></li>
</ul>
<p>A <a href="http://www.w3.org/TR/domcore/#concept-node">node</a> <dfn id="dfn-satisfies-matching-criteria">satisfies</dfn> a <a href="#dfn-matching-criteria">matching criteria</a> only if:
<ol>
<li>all <a href="http://dev.w3.org/csswg/selectors4/#compound">compound selectors</a> in the set, contain only the <a href="http://dev.w3.org/csswg/selectors4/#simple">simple selectors</a> specified above; and</li>
<li>a <a href="http://www.w3.org/TR/domcore/#concept-node">node</a> matches at least one <a href="http://dev.w3.org/csswg/selectors4/#compound">compound selectors</a> in the set or the set is empty.</li>
</ol>
</p>
</section>
<section id="content-pseudo-element">
<h3><code>::content</code> pseudo-element</h3>
<p>The <dfn id="dfn-content-pseudo-element">::content</dfn> is a pseudo-element that represents a relationship between a <a href="#dfn-content-insertion-point">content insertion point</a> in a <a href="#dfn-shadow-tree">shadow tree</a> and an <a href="http://dom.spec.whatwg.org/#concept-element">element</a> whose <a href="http://dom.spec.whatwg.org/#concept-tree-inclusive-ancestor">inclusive ancestor</a> is <a href="#dfn-distribution">distributed</a> into that <a href="#dfn-content-insertion-point">content insertion point</a>. The <a href="http://dev.w3.org/csswg/selectors4/#relative-selectors">relative selector</a> following <a href="#dfn-content-pseudo-element"><code>::content</code></a> pseudo-element is <a href="http://dev.w3.org/csswg/selectors4/#scope-contained-selectors">scope-contained</a>, with the <a href="http://dev.w3.org/csswg/selectors4/#reference-element-set">reference element set</a> initialized to the <a href="http://dom.spec.whatwg.org/#concept-tree-parent">parent</a> of the <a href="">element</a>, distributed to the <a href="#dfn-content-insertion-point">content insertion point</a>.</p>
<div class="note">
<p>For example, the following selector represents the all <code>div</code> elements that are descendants of an element, distributed into a <a href="#dfn-content-insertion-point">content insertion point</a></p>
<pre class="highlight">
::content div
</pre>
<p>This selector represents all child <code>span</code> elements that are distributed into <a href="#dfn-content-insertion-point">content insertion points</a> with class attribute <code>victory</code></p>
<pre class="highlight">
.victory::content > span
</pre>
</div>
<p class="issue">Should reference element set be insertion point or parent?</p>
</section>
</section>
<section id="composition">
<h2>Composition</h2>
<p>The <dfn id="dfn-composed-tree-children-calculation-algorithm">composed tree children calculation algorithm</dfn> <strong>must</strong> be used to determine the child <a href="http://www.3.org/TR/domcore/#concept-node">nodes</a> of a <a href="http://www.3.org/TR/domcore/#concept-node">node</a> in the <a href="#dfn-composed-tree">composed tree</a> and <strong>must</strong> be <a href="#dfn-processing-equivalence">equivalent</a> to processing the following steps:</p>
<div class="algorithm">
<dl>
<dt>Input</dt>
<dd><var>NODE</var>, a <a href="http://www.3.org/TR/domcore/#concept-node">node</a> which participates in a composed tree</dd>
<dt>Output</dt>
<dd><var>CHILDREN</var>, the child nodes of <var>NODE</var> in the <a href="#dfn-composed-tree">composed tree</a>.</dd>
</dl>
<ol>
<li>Let <var>CHILDREN</var> be an empty ordered list of nodes</li>
<li>If <var>NODE</var> is a <a href="#dfn-shadow-host">shadow host</a>:
<ol>
<li>Let <var>CHILD-POOL</var> be the children of the <a href="#dfn-youngest-shadow-root">youngest shadow root</a> which <var>NODE</var> <a href="#dfn-verb-host">hosts</a>.</li>
</ol></li>
<li>Otherwise:
<ol>
<li>Let <var>CHILD-POOL</var> be the child <a href="http://www.3.org/TR/domcore/#concept-node">nodes</a> of NODE</li>
</ol></li>
<li>For each <a href="http://www.3.org/TR/domcore/#concept-node">node</a>, <var>CHILD</var>, in <var>CHILD-POOL</var>:
<ol>
<li>If <var>CHILD</var> is an <a href="#dfn-insertion-point">insertion point</a>:
<ol>
<li>For each <a href="http://www.3.org/TR/domcore/#concept-node">node</a>, <var>DISTRIBUTED-NODE</var>, in the <a href="#dfn-distributed-nodes">distributed nodes</a> of the <a href="#dfn-insertion-point">insertion point</a> <var>CHILD</var>:
<ol>
<li>If <var>CHILD</var> is the <a href="#dfn-final-destination">final destination</a> of <var>DISTRIBUTED-NODE</var>, add <var>DISTRIBUTED-NODE</var> to <var>CHILDREN</var></li>
</ol></li>
</ol></li>
<li>Otherwise:
<ol>
<li>Add <var>CHILD</var> to <var>CHILDREN</var></li>
</ol></li>
</ol></li>
</ol>
</div>
<p>For a given <a href="#dfn-tree-of-trees">tree of trees</a> <var>TREE-OF-TREES</var>, the <a href="#dfn-composed-tree">composed tree</a> constructed from <var>TREE-OF-TREES</var> <strong>must</strong> be <a href="#dfn-processing-equivalence">equivalent</a> to the following tree:
<ul>
<li>The <a href="http://dom.spec.whatwg.org/#concept-tree-root">root</a> <a href="http://www.3.org/TR/domcore/#concept-node">node</a> of the <a href="#dfn-composed-tree">composed tree</a> is the <a href="http://dom.spec.whatwg.org/#concept-tree-root">root</a> <a href="http://www.3.org/TR/domcore/#concept-node">node</a> of the <a href="#dfn-root-tree">root tree</a> of <var>TREE-OF-TREES</var>.</li>
<li>For a given <a href="http://www.3.org/TR/domcore/#concept-node">node</a> which <a href="http://dom.spec.whatwg.org/#concept-tree-participate">participates</a> in the <a href="#dfn-composed-tree">composed tree</a>, the child <a href="http://www.3.org/TR/domcore/#concept-node">nodes</a> of the <a href="http://www.3.org/TR/domcore/#concept-node">node</a> is the result of the <a href="#dfn-composed-tree-children-calculation-algorithm">composed tree children calculation algorithm</a> with the <a href="http://www.3.org/TR/domcore/#concept-node">node</a> as input.
</li>
</ul>
</p>
</section>
<section id="events">
<h2>Events</h2>
<p>When an <a href="http://www.w3.org/TR/domcore/#events">event</a> is <a href="http://www.w3.org/TR/domcore/#dispatching-events">dispatched</a> in a <a href="#dfn-shadow-tree">shadow tree</a>, its path either crosses the <a href="#dfn-shadow-boundary">shadow boundary</a> or is terminated at the <a href="#dfn-shadow-boundary">shadow boundary</a>. One exception are the mutation events. The <a href="http://www.w3.org/TR/DOM-Level-2-Events/events.html#Events-eventgroupings-mutationevents">mutation event types</a> <strong>must</strong> never be dispatched in a <a href="#dfn-shadow-tree">shadow tree</a>.</p>
<section id="events-that-are-always-stopped">
<h3>Events that are Always Stopped</h3>
<p>The <dfn id="dfn-events-always-stopped">following events</dfn> <strong>must</strong> always be stopped at the <a href="http://dom.spec.whatwg.org/#concept-tree-root">root</a> <a href="http://www.3.org/TR/domcore/#concept-node">node</a> of the <a href="http://dom.spec.whatwg.org/#concept-node-tree">node tree</a>:</p>
<ul>
<li><code>abort</code></li>
<li><code>error</code></li>
<li><code>select</code></li>
<li><code>change</code></li>
<li><code>load</code></li>
<li><code>reset</code></li>
<li><code>resize</code></li>
<li><code>scroll</code></li>
<li><code>selectstart</code></li>
</ul>
</section>
<section id="event-paths">
<h3>Event Paths</h3>
<p>The <dfn id="dfn-event-path-calculation-algorithm">event path calculation algorithm</dfn> must be used to determine event path and <strong>must</strong> be <a href="#dfn-processing-equivalence">equivalent</a> to processing the following steps:</p>
<div class="algorithm">
<dl>
<dt>Input</dt>
<dd><var>NODE</var>, a node</dd>
<dd><var>EVENT</var>, an event</dd>
<dt>Output</dt>
<dd><var>PATH</var>, an event path, a ordered list of an event target</dd>
</dl>
<ol>
<li>Let <var>PATH</var> be the empty ordered list of nodes</li>
<li>Let <var>CURRENT</var> be <var>NODE</var></li>
<li>Add <var>CURRENT</var> to <var>PATH</var></li>
<li><dfn id="event-path-calculation-algorithm-repeat">Repeat</dfn> while <var>CURRENT</var> exists:
<ol>
<li>If the <a href="#dfn-destination-insertion-points">destination insertion points</a> of <var>CURRENT</var> is not empty:
<ol>
<li>For each <a href="#dfn-insertion-point">insertion point</a>, <var>INSERTION-POINT</var>, in the <a href="#dfn-destination-insertion-points">destination insertion points</a> of <var>CURRENT</var>:
<ol>
<li>If <var>INSERTION-POINT</var> is a <a href="#dfn-shadow-insertion-point">shadow insertion point</a>:
<ol>
<li>Let <var>SHADOW-ROOT</var> be the <a href="http://dom.spec.whatwg.org/#concept-tree-root">root</a> <a href="http://www.3.org/TR/domcore/#concept-node">node</a> of <var>INSERTION-POINT</var></li>
<li>If <var>SHADOW-ROOT</var> is not the olderst <a href="#dfn-shadow-root">shadow root</a>:
<ol>
<li>Add the <a href="#dfn-older-shadow-root">older shadow root</a> relative to <var>SHADOW-ROOT</var> to <var>PATH</var></li>
</ol></li>
</ol></li>
<li>Add <var>INSERTION-POINT</var> to <var>PATH</var></li>
</ol></li>
<li>Let <var>CURRENT</var> be the <a href="#dfn-final-destination">final destination</a> of <var>CURRENT</var></li>
</ol></li>
<li>Otherwise:
<ol>
<li>If <var>CURRENT</var> is a <a href="#dfn-shadow-root">shadow root</a>:
<ol>
<li>If <var>NODE</var> and <var>CURRENT</var> are in the same <a href="http://dom.spec.whatwg.org/#concept-node-tree">node tree</a> and <var>EVENT</var> is one of the <a href="#dfn-events-always-stopped">events which must be stopped</a>:
<ol>
<li>Stop this algorithm</li>
</ol></li>
<li>Let <var>CURRENT</var> be the <a href="#dfn-shadow-host">shadow host</a> which <a href="#dfn-verb-host">hosts</a> <var>CURRENT</var></li>
<li>Add <var>CURRENT</var> to <var>PATH</var></li>
</ol></li>
<li>Otherwise:
<ol>
<li>Let <var>CURRENT</var> be the <a href="http://dom.spec.whatwg.org/#concept-tree-parent">parent</a> <a href="http://www.3.org/TR/domcore/#concept-node">node</a> of <var>CURRENT</var></li>
<li>If <var>CURRENT</var> exists:
<ol>
<li>Add <var>CURRENT</var> to <var>PATH</var></li>
</ol></li>
</ol></li>
</ol></li>
</ol></li>
</ol>
</div>
<div class="note">For convenience, an event path may include shadow roots or <a href="#dfn-insertion-point">insertion points</a> so that event listeners registered on the shadow roots or the <a href="#dfn-insertion-point">insertion points</a> would be invoked.</div>
</section>
<section id="event-retargeting">
<h3>Event Retargeting</h3>
<p>In the cases where event path is across multiple node trees, the event's information about the target of the event is adjusted in order to maintain <a href="#dfn-encapsulation">encapsulation</a>. Event <dfn id="dfn-retargeting">retargeting</dfn> is a process of computing relative targets for each ancestor of the <a href="http://www.w3.org/TR/domcore/#concept-node">node</a> at which the event is dispatched. A <dfn id="dfn-relative-target">relative target</dfn> is a <a href="http://www.w3.org/TR/domcore/#concept-node">node</a> that most accurately represents the target of a dispatched event at a given ancestor while maintaining the <a href="#dfn-encapsulation">encapsulation</a>.</p>
<p>The <dfn id="dfn-retargeting-algorithm">retargeting algorithm</dfn> is used to determine relative targets, and it <strong>must</strong> be <a href="#dfn-processing-equivalence">equivalent</a> to processing the following steps:</p>
<div class="algorithm">
<dl>
<dt>Input</dt>
<dd><var>PATH</var>, an event path</dd>
<dd><var>CURRENT-TARGET</var>, a <a href="http://www.3.org/TR/domcore/#concept-node">node</a> where the event listener is invoked.</dd>
<dt>Output</dt>
<dd><var>RELATIVE-TARGET</var>, adjusted target</dd>
</dl>
<ol>
<li>Let <var>CURRENT-TARGET-TREE</var> be the <a href="http://dom.spec.whatwg.org/#concept-node-tree">node tree</a> which <var>CURRENT-TARGET</var> <a href="http://dom.spec.whatwg.org/#concept-tree-participate">participates</a> in</li>
<li>Let <var>TARGET</var> be the first item in PATH</li>
<li>Let <var>TARGET-TREE</var> be the <a href="http://dom.spec.whatwg.org/#concept-node-tree">node tree</a> which ORIGINAL-TARGET <a href="http://dom.spec.whatwg.org/#concept-tree-participate">participates</a> in</li>
<li>Let <var>RELATIVE-TARGET-TREE</var> be the lowest common <a href="http://dom.spec.whatwg.org/#concept-tree-inclusive-ancestor">inclusive ancestor</a> tree of CURRENT-TARGET-TREE and TARGET-TREE</li>
<li>Let <var>RELATIVE-TARGET</var> be the <a href="http://www.3.org/TR/domcore/#concept-node">node</a> which satisfies all the following conditions:
<ol>
<li>The <a href="http://www.3.org/TR/domcore/#concept-node">node</a> <a href="http://dom.spec.whatwg.org/#concept-tree-participate">participates</a> in RELATIVE-TARGET-TREE</li>
<li>The <a href="http://www.3.org/TR/domcore/#concept-node">node</a> is a member of PATH</li>
<li>There is no other descendant <a href="http://www.3.org/TR/domcore/#concept-node">node</a> which satisfies the conditions.</li>
</ol></li>
</ol>
</div>
<p>The retargeting process <strong>must</strong> occur prior to dispatch of an event.</p>
</section>
<section id="retargeting-related-target">
<h3>Retargeting <code>relatedTarget</code></h3>
<p>Some events have a <a href="http://www.w3.org/TR/DOM-Level-3-Events/#events-MouseEvent-relatedTarget"><code>relatedTarget</code></a> property, which holds a <a href="http://www.w3.org/TR/domcore/#concept-node">node</a> that's not the event's target, but is related to the event.</p>
<p>For instance, a <code>mouseover</code> event's <a href="http://www.w3.org/TR/DOM-Level-3-Events/#events-MouseEvent-relatedTarget"><code>relatedTarget</code></a> may hold the <a href="http://www.w3.org/TR/domcore/#concept-node">node</a> from which the mouse has moved to event's <code>target</code>. In the case where <code>relatedTarget</code> is in a <a href="#dfn-shadow-tree">shadow tree</a>, the conforming UAs <strong>must</strong> not leak its actual value outside of this tree. In cases where both <code>relatedTarget</code> and <code>target</code> are part of the same <a href="#dfn-shadow-tree">shadow tree</a>, the conforming UAs <strong>must</strong> <em>stop</em> events at the <a href="#dfn-shadow-boundary">shadow boundary</a> to avoid the appearance of spurious <code>mouseover</code> and <code>mouseout</code> events firing from the same node.</p>
<p>Thus, if an event has a <code>relatedTarget</code>, its value and extent of event dispatch <strong>must</strong> be adjusted. In general:</p>
<ol>
<li>For a given node, the <code>relatedTarget</code> <strong>must</strong> be changed to its ancestor (or self) that is in the same <a href="#dfn-shadow-tree">shadow tree</a> as the node</li>
<li>Event listeners <strong>must not</strong> be invoked on a <a href="http://www.w3.org/TR/domcore/#concept-node">node</a> for which the <code>target</code> and <code>relatedTarget</code> are the same.</li>
</ol>
<p>The <dfn id="dfn-related-target-algorithm">related target resolution</dfn> algorithm <strong>must</strong> be used to determine the value of the <a href="http://www.w3.org/TR/DOM-Level-3-Events/#events-MouseEvent-relatedTarget"><code>relatedTarget</code></a> property and <strong>must</strong> be <a href="#dfn-processing-equivalence">equivalent</a> to processing the following steps:</p>
<div class="algorithm">
<dl>
<dt>Input</dt>
<dd><var>CURRENT-TARGET</var>, the <a href="http://www.w3.org/TR/domcore/#concept-node">node</a> on which event listeners would be invoked</dd>
<dd><var>RELATED-TARGET</var>, the related target for the event</dd>
<dt>Output</dt>
<dd><var>ADJUSTED-RELATED-TARGET</var>, the <dfn id="dfn-adjusted-related-target">adjusted related target</dfn> for <var>NODE</var></dd>
</dl>
<ol>
<li>Let <var>ADJUSTED-RELATED-TARGET</var> be null</li>
<li>Let <var>RELATED-TARGET-PATH</var> be the result of the event path calculation algorithm with <var>RELATED-TARGET</var> as input</li>
<li>For each <a href="http://dom.spec.whatwg.org/#concept-tree-inclusive-ancestor">inclusive ancestor</a> tree, <var>CURRENT-TREE</var>, of the <a href="http://dom.spec.whatwg.org/#concept-node-tree">node tree</a> which <var>CURRENT-TARGET</var> <a href="http://dom.spec.whatwg.org/#concept-tree-participate">participates</a> in, in ascending order:
<ol>
<li>For each <a href="http://www.3.org/TR/domcore/#concept-node">node</a>, <var>RELATED-PATH-ANCESTOR</var>, in the <var>RELATED-PATH</var>:
<ol>
<li>If <var>RELATED-PATH-ANCESTOR</var> <a href="http://dom.spec.whatwg.org/#concept-tree-participate">participates</a> in <var>CURRENT-TREE</var>:
<ol>
<li>Let <var>ADJUSTED-RELATED-TARGET</var> be RELATED-PATH-ANCESTOR</li>
<li>Stops</li>
</ol></li>
</ol></li>
</ol></li>
</ol>
</div>
<div class="note">The result of the related target resolution algorithm is not always null. Unless that, you should file a bug for this specification.</div>
</section>
<section id="retargeting-touch-events">
<h3>Retargeting Touch Events</h3>
<p>The <a href="http://www.w3.org/TR/touch-events/#touch-interface"><code>Touch</code></a> <a href="http://www.w3.org/TR/touch-events/#widl-Touch-target"><code>target</code></a> attribute must be adjusted in the same way as an event with a <a href="http://www.w3.org/TR/DOM-Level-3-Events/#events-MouseEvent-relatedTarget"><code>relatedTarget</code></a>. Each <a href="http://www.w3.org/TR/touch-events/#touch-interface"><code>Touch</code></a> <a href="http://www.w3.org/TR/touch-events/#widl-Touch-target"><code>target</code></a> in the <a href="http://www.w3.org/TR/touch-events/#touchlist-interface"><code>TouchList</code></a> returned from <a href="http://www.w3.org/TR/touch-events/#touchevent-interface"><code>TouchEvent</code></a> <a href="http://www.w3.org/TR/touch-events/#widl-TouchEvent-touches"><code>touches()</code></a>, <a href="http://www.w3.org/TR/touch-events/#widl-TouchEvent-changedTouches"><code>changedTouches()</code></a> and <a href="http://www.w3.org/TR/touch-events/#widl-TouchEvent-targetTouches"><code>targetTouches()</code></a> must be the result of <a href="#dfn-related-target-algorithm">related target resolution algorithm</a>, given <var>NODE</var> and <a href="http://www.w3.org/TR/touch-events/#touch-interface"><code>Touch</code></a> <a href="http://www.w3.org/TR/touch-events/#widl-Touch-target"><code>target</code></a> as arguments.</p>
</section>
<section id="retargeting-focus-events">
<h3>Retargeting Focus Events</h3>
<p>The <code>focus</code>, <code>DOMFocusIn</code>, <code>blur</code>, and <code>DOMFocusOut</code> events <strong>must</strong> be treated in the same way as events with a <code>relatedTarget</code>, where the corresponding <a href="http://www.w3.org/TR/domcore/#concept-node">node</a> that is losing focus as a result of <code>target</code> gaining focus or the <a href="http://www.w3.org/TR/domcore/#concept-node">node</a> that is gaining focus, and thus causing the blurring of <code>target</code> acts as the related target.</p>
</section>
<section id="event-dispatch">
<h3>Event Dispatch</h3>
<p>At the time of event dispatch:</p>
<ul>
<li>The <a href="http://www.w3.org/TR/domcore/#event"><code>Event</code></a> <a href="http://www.w3.org/TR/domcore/#dom-event-target"><code>target</code></a> and <a href="http://www.w3.org/TR/domcore/#dom-event-currenttarget"><code>currentTarget</code></a> attributes <strong>must</strong> return the <a href="#dfn-relative-target">relative target</a> for the <a href="http://www.w3.org/TR/domcore/#concept-node">node</a> on which event listeners are <a href="http://www.w3.org/TR/domcore/#concept-event-listener-invoke">invoked</a></li>
<li>The <a href="http://www.w3.org/TR/DOM-Level-3-Events/#events-MouseEvent"><code>MouseEvent</code></a> <a href="http://www.w3.org/TR/DOM-Level-3-Events/#events-MouseEvent-relatedTarget"><code>relatedTarget</code></a> attribute <strong>must</strong> return the <a href="#dfn-adjusted-related-target">adjusted related target</a></li>
<li>The <a href="http://www.w3.org/TR/DOM-Level-3-Events/#events-MouseEvent"><code>MouseEvent</code></a> <a href="http://dev.w3.org/csswg/cssom-view/#widl-MouseEvent-offsetX"><code>offsetX</code></a> and <a href="http://dev.w3.org/csswg/cssom-view/#widl-MouseEvent-offsetY"><code>offsetY</code></a> attributes <strong>must</strong> return the coordinates relative to the origin of the <a href="http://dev.w3.org/csswg/cssom-view/#padding-edge">padding edge</a> of the <a href="#dfn-relative-target">relative target</a></li>
<li>The <a href="http://www.w3.org/TR/touch-events/#touch-interface"><code>Touch</code></a> <a href="http://www.w3.org/TR/touch-events/#widl-Touch-target"><code>target</code></a> attribute <strong>must</strong> return the <a href="#dfn-adjusted-related-target">adjusted related target</a></li>
<li>If the <a href="http://www.w3.org/TR/DOM-Level-3-Events/#events-MouseEvent-relatedTarget"><code>relatedTarget</code></a> and <a href="http://www.w3.org/TR/domcore/#dom-event-target"><code>target</code></a> are the same for a given node, its the event listeners <strong>must not</strong> be invoked. <a href="http://www.w3.org/TR/touch-events/#touchevent-interface"><code>TouchEvent</code></a> is not subject to this rule.</li>
<li>When <em>capturing</em>, which entails processing step 6 of the <a href="http://dom.spec.whatwg.org/#concept-event-dispatch">event dispatch algorithm</a>, the event listeners <strong>must not</strong> be <a href="http://dom.spec.whatwg.org/#concept-event-listener-invoke">invoked</a> on a <a href="http://dom.spec.whatwg.org/#concept-node">node</a> <strong>if</strong> it is the same as its <a href="#dfn-relative-target">relative target</a></li>
<li>When <em>bubbling</em>, which entails processing step 9 of the <a href="http://dom.spec.whatwg.org/#concept-event-dispatch">event dispatch algorithm</a>, the <a href="http://dom.spec.whatwg.org/#event"><code>Event</code></a> <a href="http://dom.spec.whatwg.org/#dom-event-eventphase">eventPhase</a> attribute <strong>must</strong> return <a href="http://dom.spec.whatwg.org/#dom-event-at_target">AT_TARGET</a> <strong>if</strong> the <a href="#dfn-relative-target">relative target</a> is same as the <a href="http://dom.spec.whatwg.org/#concept-node">node</a> on which event listeners are <a href="http://dom.spec.whatwg.org/#concept-event-listener-invoke">invoked</a></li>
<li>If the event's <a href="http://dom.spec.whatwg.org/#dom-event-bubbles"><code>bubbles</code></a> attribute value is <strong>false</strong>, run these substeps:
<ol>
<li>Reverse the order of <em>event path</em></li>
<li>Initialize event's <a href="http://dom.spec.whatwg.org/#dom-event-eventphase"><code>eventPhase</code></a> attribute to <a href="http://dom.spec.whatwg.org/#dom-event-at_target"><code>AT_TARGET</code></a></li>
<li>For each object in <em>event path</em> where the <a href="#dfn-relative-target">relative target</a> is same as the object, <a href="http://dom.spec.whatwg.org/#concept-event-listener-invoke">invoke</a> its <a href="http://dom.spec.whatwg.org/#concept-event-listener">event listeners</a>, with event <em>event</em>, as long as <em>event</em>'s <a href="http://dom.spec.whatwg.org/#stop-propagation-flag">stop propagation flag</a> is unset</li>
</ol></li>
</ul>
<p>Upon completion of the event dispatch, the <a href="http://www.w3.org/TR/domcore/#event"><code>Event</code></a> object's <a href="http://www.w3.org/TR/domcore/#dom-event-target"><code>target</code></a> and <a href="http://www.w3.org/TR/domcore/#dom-event-currenttarget"><code>currentTarget</code></a> <strong>must</strong> be to the highest ancestor's <a href="#dfn-relative-target">relative target</a>. Since it is possible for a script to hold on to the <code>Event</code> object past the scope of event dispatch, this step is necessary to avoid revealing the <a href="http://www.w3.org/TR/domcore/#concept-node">nodes</a> in <a href="#dfn-shadow-tree">shadow trees</a>.</p>
</section>
<section id="event-retargeting-example">
<h3>Event Retargeting Example</h3>
<p>Suppose we have a user interface for a media controller, represented by this tree, composed of both <a href="#dfn-document-tree">document tree</a> and the <a href="#dfn-shadow-tree">shadow trees</a>. In this example, we will assume that selectors are allowed to cross the shadow boundaries and we will use these selectors to identify the <a href="http://www.w3.org/TR/domcore/#concept-element">elements</a>. Also, we will invent a fictional <code>shadow-root</code> <a href="http://www.w3.org/TR/domcore/#concept-element">element</a> to demarcate the <a href="#dfn-shadow-boundary">shadow boundaries</a> and represent <a href="#dfn-shadow-root">shadow roots</a>:</p>
<pre class="example">
<div id="player">
<span class=shadow-boundary><shadow-root id="player-shadow-root"></span>
<div id="controls">
<button class="play-button">PLAY</button>
<input type="range" id="timeline">
<span class=shadow-boundary><shadow-root id="timeline-shadow-root"></span>
<div class="slider-thumb" id="timeline-slider-thumb"></div>
<span class=shadow-boundary></shadow-root></span>
</input>
<div class="volume-slider-container">
<input type="range" class="volume-slider">
<span class=shadow-boundary><shadow-root id="volume-shadow-root"></span>
<div class="slider-thumb" id="volume-slider-thumb"></div>
<span class=shadow-boundary></shadow-root></span>
</input>
</div>
</div>
<span class=shadow-boundary></shadow-root></span>
</div>
</pre>
<p>Let's have a user position their pointing device over the volume slider's thumb (<code>#volume-slider-thumb</code>), thus triggering a <code>mouseover</code> event on that node. For this event, let's pretend it has no associated <code>relatedTarget</code>.</p>
<p>Just before the event is dispatched, we perform <a href="#dfn-retargeting">retargeting</a>:</p>
<ol>
<li>Since <code>#volume-slider-thumb</code> is not an <a href="#dfn-insertion-point">insertion point</a>, we push it onto <var>STACK</var>, and add the first tuple to <var>TARGETS</var> as (<code>#volume-slider-thumb</code>, <code>#volume-slider-thumb</code>)</li>
<li>We then <a href="#dfn-parent-calculation-algorithm">calculate parent</a> as <code>#volume-shadow-root</code> and proceed to second iteration, adding (<code>#volume-slider-thumb</code>, <code>#volume-shadow-root</code>) tuple to <var>TARGETS</var></li>
<li>Because <code>#volume-shadow-root</code> is a <a href="#dfn-shadow-root">shadow root</a>, we pop <var>STACK</var>, thus emptying it</li>
<li>Next <a href="#dfn-parent-calculation-algorithm">parent calculation</a> yields <code>#volume-slider</code>, and so we begin the third iteration</li>
<li>Here, <var>STACK</var> is empty again, so we push <code>#volume-slider</code> into it and add (<code>#volume-slider</code>, <code>#volume-slider</code>) to <var>TARGETS</var></li>
<li>The <a href="#dfn-parent-calculation-algorithm">parent</a> of <code>#volume-slider</code> is <code>#volume-slider-container</code> not a <a href="#dfn-shadow-root">shadow root</a> and not an <a href="#dfn-insertion-point">insertion point</a>, which dictates that we add (<code>#volume-slider</code>, <code>#volume-slider-container</code>) to <var>TARGETS</var></li>
<li>Next <a href="#dfn-parent-calculation-algorithm">up</a>, we see <code>#controls</code>, again neither a <a href="#dfn-shadow-root">shadow root</a> nor an <a href="#dfn-insertion-point">insertion point</a>, which means we add (<code>##volume-slider</code>, <code>#controls</code>) to <var>TARGETS</var></li>
<li>The <a href="#dfn-parent-calculation-algorithm">next ancestor</a> is <code>#player-shadow-root</code>, a <a href="#dfn-shadow-root">shadow root</a>, and thus we add it (<code>#volume-slider</code>, <code>#player-shadow-root</code>) to <var>TARGETS</var>, then pop <var>STACK</var>, emptying it</li>
<li>Its <a href="#dfn-parent-calculation-algorithm">parent</a> is <code>#player</code>, neither <a href="#dfn-shadow-root">shadow root</a> nor <a href="#dfn-insertion-point">insertion point</a>, and <var>STACK</var> is empty, so we push <code>#player</code> to <var>STACK</var>, then add (<code>#player</code>, <code>#player</code>) to <var>TARGETS</var></li>
<li>In our example, there are no further <a href="#dfn-parent-calculation-algorithm">parents</a>, causing us to exit the <a href="#algo-reatargeting-repeat">loop</a> and stop.</li>
</ol>
<p>At the end of this process, we should have the following set of ancestors and relative targets:</p>
<table>
<thead>
<tr>
<th>Ancestor</th>
<th>Relative Target</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>#player</code></td>
<td><code><strong>#player</strong></code></td>
</tr>
<tr>
<td><code>#player-shadow-root</code></td>
<td><code>#volume-slider</code></td>
</tr>
<tr>
<td><code>#controls</code></td>
<td><code>#volume-slider</code></td>
</tr>
<tr>
<td><code>#volume-slider-container</code></td>
<td><code>#volume-slider</code></td>
</tr>
<tr>
<td><code>#volume-slider</code></td>
<td><code><strong>#volume-slider</strong></code></td>
</tr>
<tr>
<td><code>#volume-shadow-root</code></td>
<td><code>#volume-slider-thumb</code></td>
</tr>
<tr>
<td><code>#volume-slider-thumb</code></td>
<td><code><strong>#volume-slider-thumb</strong></code></td>
</tr>
</tbody>
</table>
<p>After we dispatch the <code>mouseover</code> event using these newly computed relative targets, the user decides to move their pointing device over the thumb of the timeline
(<code>#timeline-slider-thumb</code>). This triggers both a <code>mouseout</code> event for the volume slider thumb and the <code>mouseover</code> event for the timeline thumb.</p>
<p>Let's study how the <code>relatedTarget</code> value of the volume thumb's <code>mouseout</code> event is affected. For this event, the <code>relatedTarget</code> is the timeline thumb (<code>#timeline-slider-thumb</code>). Per <a href="#dfn-related-target-algorithm">algorithm</a>:</p>
<ol>
<li>Starting with <var>NODE</var> as <code>#volume-slider-thumb</code> and <var>RELATED</var> as <code>#timeline-slider-thumb</code>,</li>
<li>We <a href="#algo-ancestor-repeat">examine</a> ancestors of <var>RELATED</var>:
<ol>
<li>First <a href="#dfn-parent-calculation-algorithm">up</a> is <code>#timeline-slider-thumb</code>, and we push it into <var>STACK</var></li>
<li>Then it's <code>#timeline-shadow-root</code>, a <a href="#dfn-shadow-root">shadow root</a>, so we pop <var>STACK</var>, emptying it</li>
<li>Next is <code>#timeline</code>, we push it into <var>STACK</var></li>
<li>Then comes <code>#controls</code> and after it, <code>#player-shadow-root</code>, a <a href="#dfn-shadow-root">shadow root</a>, so we pop <var>STACK</var>, emptying it</li>
<li>Final ancestor is <code>#player</code>, we push it into <var>STACK</var></li>
</ol></li>
<li>Set <var>TARGET</var> to <code>#volume-shadow-root</code></li>
<li>We again <a href="#algo-ancestor-repeat">examine</a> ancestors of <var>RELATED</var> and notice that it produces the same result as our previous such examination</li>
<li>We then set <var>TARGET</var> to <code>#volume-slider</code> and</li>
<li>Repeat <a href="#algo-ancestor-repeat">examination</a> of ancestors once more—and realize that when <var>ANCESTOR</var> value is <code>#timeline</code>, the <var>ANCESTOR</var> and <var>TARGET</var> are in the same tree, and thus</li>
<li>Return <code>#timeline</code> as the adjusted <code>relatedTarget</code> value.</li>
</ol>
<p>Performing this computation with <var>NODE</var> as <code>#player</code> yields the result of both <code>target</code> and <code>relatedTarget</code> being the same value (<code>#player</code>), which means that we do not dispatch the event on this <a href="http://www.w3.org/TR/domcore/#concept-node">node</a> and its ancestors.</p>
</section>
</section>
<section id="styles">
<h2>Styles</h2>
<p>Each <a href="#dfn-shadow-root">shadow root</a> has an associated list of zero or more <a href="http://www.w3.org/TR/cssom/#style-sheet">style sheets</a>, named <dfn id="dfn-shadow-root-style-sheets">shadow root style sheets</dfn>. This is an ordered list that contains all <a href="http://www.w3.org/TR/cssom/#style-sheet">style sheets</a>, associated with the <a href="#dfn-shadow-root">shadow root</a>, in <a href="http://www.w3.org/TR/dom/#concept-tree-order">tree order</a>.</p>
<p>When a <a href="#dfn-shadow-host">shadow host</a> has multiple <a href="#dfn-shadow-root">shadow roots</a>, the <a href="http://dev.w3.org/csswg/css3-cascade/#cascade">cascade order</a> of <a href="http://www.w3.org/TR/CSS2/syndata.html#rule-sets">CSS rules</a>, defined in <a href="#dfn-shadow-root-style-sheets">shadow root style sheets</a>, in ascending order of precedence <strong>must</strong> match the order of the <a href="#dfn-tree-stack">tree stack</a>, ending with the <a href="#dfn-youngest-tree">youngest tree</a>.</p>
<p><a href="http://www.w3.org/TR/CSS2/syndata.html#rule-sets">CSS rules</a> declared in an <a href="#dfn-ancestor-tree">ancestor tree</a> <strong>must not</strong> apply in a <a href="#dfn-shadow-tree">shadow tree</a>, except when the <dfn id="dfn-apply-author-styles">apply-author-styles</dfn> flag is set for this tree. The flag signals that the rules declared in the <a href="#dfn-ancestor-tree">ancestor trees</a> are applicable in the <a href="#dfn-shadow-tree">shadow tree</a>.</p>
<p>Even when the <a href="#dfn-apply-author-styles">apply-author-styles</a> is set, the <a href="http://www.w3.org/TR/selectors4/">selectors</a> still <strong>must not</strong> cross the <a href="#dfn-shadow-boundary">shadow boundary</a> per <a href="#dfn-scoping-constraints">scoping constraints</a>. In other words, with <a href="#dfn-apply-author-styles">apply-author-styles</a> set, the <a href="http://www.w3.org/TR/domcore/#concept-document">document</a> CSS rules only match wholly inside or outside of the <a href="#dfn-shadow-tree">shadow tree</a>.</p>
<p>For the purposes of the <a href="http://dev.w3.org/csswg/css3-cascade/#cascade">cascade order</a>, the <a href="http://www.w3.org/TR/CSS2/syndata.html#rule-sets">CSS rules</a> for <a href="#dfn-shadow-tree">shadow trees</a> that have the <a href="#dfn-apply-author-styles">apply-author-styles</a> flag set <strong>must</strong> be treated as <a href="http://www.w3.org/TR/selectors4/#scoping">scoped</a> selectors with <a href="#dfn-shadow-root">shadow root</a> as their scope. In this context, for <a href="#dfn-shadow-tree">shadow trees</a> <em>A</em> and <em>B</em>, the <em>A</em>'s <a href="#dfn-shadow-root">shadow root</a> is treated as <em>descendant</em> of <em>B</em>'s <a href="#dfn-shadow-root">shadow root</a> if <em>A</em> is a <a href="#dfn-descendant-tree">descendant tree</a> of <em>B</em>.</p>
<p>If a <a href="http://www.w3.org/TR/CSS2/syndata.html#rule-sets">CSS rule</a> in the parent tree ends with a <a href="http://www.w3.org/TR/selectors4/#compound">compound selector</a> that contains a <a href="#dfn-part-pseudo-element">part pseudo-element</a> whose parameter value equals to a <a href="#dfn-part-pseudo-element-value">value</a> of a <a href="#dfn-part-pseudo-element">part pseudo-element</a> that exists in a <a href="#dfn-shadow-tree">shadow tree</a>, this <a href="#dfn-part-pseudo-element">part pseudo-element</a> <strong>must</strong> match the <a href="http://www.w3.org/TR/domcore/#concept-element">element</a>, associated with this <a href="#dfn-part-pseudo-element">part pseudo-element</a>.</p>
<p>Conversely, <a href="http://www.w3.org/TR/CSS2/syndata.html#rule-sets">CSS rules</a> declared in a <a href="#dfn-shadow-root-style-sheets">shadow root style sheets</a> <strong>must not</strong> apply in the <a href="#dfn-ancestor-tree">ancestor trees</a>, with two exceptions:</p>
<ol>
<li>Rules that contain a <a href="#dfn-content-pseudo-element"><code>::content</code> pseudo-element</a> match <a href="http://www.w3.org/TR/domcore/#concept-element">elements</a> in the <a href="#dfn-ancestor-tree">ancestor</a> trees;</li>
<li>The <a href="#host-at-rule"><code>@host</code> @-rule</a> matches a <a href="#dfn-shadow-host">shadow host</a> in the <a href="#dfn-parent-tree">parent tree</a>.</li>
</ol>
<p>In a <a href="http://www.w3.org/TR/domcore/#concept-document">document</a> that contains <a href="#dfn-shadow-tree">shadow trees</a>, the CSS properties <strong>must</strong> be inherited from parent nodes, produced using the <a href="#dfn-parent-calculation-algorithm">parent calculation algorithm</a>. This requirement has the following effects:</p>
<ul>
<li>the styles of the <a href="#dfn-shadow-host">shadow host</a> are inherited by the children of the <a href="#dfn-shadow-root">shadow root</a></li>
<li>the styles of the <a href="#dfn-insertion-point">insertion point</a> <a href="http://www.w3.org/TR/domcore/#concept-node">nodes</a> are inherited by those child <a href="http://www.w3.org/TR/domcore/#concept-node">nodes</a> of the <a href="#dfn-shadow-host">shadow host</a> that are <a href="#dfn-assigned">assigned</a> to this <a href="#dfn-insertion-point">insertion point</a></li>
<li>the styles of the <a href="#dfn-shadow-insertion-point">shadow insertion point</a> <a href="http://www.w3.org/TR/domcore/#concept-node">node</a> are inherited by the child <a href="http://www.w3.org/TR/domcore/#concept-node">nodes</a> of the <a href="#dfn-shadow-root">shadow root</a> of the <a href="#dfn-shadow-tree">shadow tree</a>, <a href="#dfn-distribution">distributed</a> to this <a href="#dfn-shadow-insertion-point">shadow insertion point</a></li>
</ul>
<p>If the <dfn id="dfn-reset-style-inheritance">reset-style-inheritance</dfn> flag is set for a <a href="#dfn-shadow-tree">shadow tree</a>, all <a href="http://www.w3.org/TR/2005/WD-css3-cascade-20051215/#inheritance">inheritable</a> CSS properties <strong>must</strong> behave as if they were explicitly set to the <a href="http://www.w3.org/TR/2005/WD-css3-cascade-20051215/#initial0">initial value</a> at the <a href="#dfn-shadow-root">shadow root</a>.</p>
<p>If the <a href="#dfn-reset-style-inheritance">reset-style-inheritance</a> flag is set for an <a href="#dfn-insertion-point">insertion point</a> in a <a href="#dfn-shadow-tree">shadow tree</a>, all <a href="http://www.w3.org/TR/2005/WD-css3-cascade-20051215/#inheritance">inheritable</a> CSS properties <strong>must</strong> behave as if they were explicitly set to the <a href="http://www.w3.org/TR/2005/WD-css3-cascade-20051215/#initial0">initial value</a> at the <a href="#dfn-insertion-point">insertion point</a>.</p>
<section id="css-variables">
<h3>CSS Variables</h3>
<p>The <a href="#dfn-shadow-host">shadow host</a> styles being inherited by the children of the <a href="#dfn-shadow-root">shadow root</a> <strong>must</strong> also apply to <a href="http://dev.w3.org/csswg/css-variables/">CSS Variables</a>. This provides a way for <a href="#dfn-document-tree">document tree</a> styles to send signals into the <a href="#dfn-shadow-tree">shadow trees</a>, and for the <a href="#dfn-shadow-tree">shadow trees</a> to receive these signals with the use of the <a href="http://dev.w3.org/csswg/css-variables/#using-variables"><code>var()</code></a> function.</p>
</section>
<section id="text-decoration-property">
<h3><code>text-decoration</code> Property</h3>
<p>The text decorations, specified by the <a href="http://www.w3.org/TR/CSS2/text.html#lining-striking-props"><code>text-decoration</code></a> property <strong>must not</strong> be propagated from <a href="#dfn-shadow-host">shadow hosts</a> to <a href="#dfn-shadow-tree">shadow trees</a>.</p>
</section>
<section id="host-at-rule">
<h3><code>@host</code> @-rule</h3>
<p>Within styles, specified in <a href="#dfn-shadow-tree">shadow trees</a>, the author may use a <code>@host</code> @-rule. The syntax of this rule is defined as this addition to <a href="http://www.w3.org/TR/CSS21/grammar.html">CSS Grammar</a>:</p>
<p>The following production is added to the <a href="http://www.w3.org/TR/CSS21/grammar.html#grammar">grammar</a>:</p>
<pre>
host
: HOST_SYM S* '{' S* ruleset* '}' S*
;
</pre>
<p>The following rule is added to the <a href="http://www.w3.org/TR/CSS21/grammar.html#scanner">tokenizer</a>:</p>
<pre>
@{H}{O}{S}{T} {return HOST_SYM;}
</pre>
<p>The <a href="http://www.w3.org/TR/CSS21/syndata.html#x19">declarations</a> of the rules in a <code>@host</code> @-rule <strong>must</strong> only be matched against the <a href="#dfn-shadow-host">shadow host</a> of the <a href="#dfn-shadow-tree">shadow tree</a> in which the style is specified, but only if this <a href="#dfn-shadow-tree">shadow tree</a> is <a href="#dfn-rendering">rendered</a>. When the <a href="#dfn-shadow-tree">shadow tree</a> is not <a href="#dfn-rendering">rendered</a> (when it's an older <a href="http://www.w3.org/TR/domcore/#trees">tree</a> that is not <a href="#dfn-assigned">assigned</a> to a <a href="#dfn-shadow-insertion-point">shadow insertion point</a>), the <a href="http://www.w3.org/TR/CSS21/syndata.html#x19">declarations</a> <strong>must not</strong> be applied.</p>
<p>When a rule in <a href="#host-at-rule"><code>@host</code> @-rule</a> matches an <a href="http://www.w3.org/TR/domcore/#concept-element">element</a>, it <strong>must</strong> have higher <a href="http://www.w3.org/TR/CSS2/cascade.html#specificity">specificity</a> than any <a href="http://www.w3.org/TR/selectors4/">selector</a>, but lower <a href="http://www.w3.org/TR/CSS2/cascade.html#specificity">specificity</a> than <a href="http://www.w3.org/TR/CSS21/syndata.html#x19">declarations</a> from a <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/elements.html#the-style-attribute"><code>style</code></a> attribute.</p>
</section>
<section id="part-pseudo-elements">
<h3>Part Pseudo-Elements</h3>
<p>In certain situations, the author of a <a href="#dfn-shadow-tree">shadow tree</a> may wish to designate one or more <a href="http://www.w3.org/TR/domcore/#concept-element">elements</a> from that <a href="http://www.w3.org/TR/domcore/#trees">tree</a> as a structural abstraction that provides additional information about the contents of the <a href="#dfn-shadow-tree">shadow tree</a>.</p>
<div class="note">
For example, when developing a 2-dimensional range slider widget, which offers a thumb that could be moved in 2 directions in a rectangular space, the author decides to allow the widget users to style the thumb directly.
</div>
<p>The <dfn id="dfn-part-pseudo-element">part pseudo-elements</dfn> enable this scenario. A <a href="#dfn-part-pseudo-element">part pseudo-element</a> is an association between an <a href="http://www.w3.org/TR/domcore/#concept-element">element</a> in a <a href="#dfn-shadow-tree">shadow tree</a> and a string value. This string value is called a <dfn id="dfn-part-pseudo-element-value">part pseudo-element value</dfn>.</p>
<div class="note">
<p>In the case of the aforementioned 2-dimensional slider widget, the author could build the widget's shadow tree as follows:</p>
<pre class="highlight">
var widget = document.createElement('div');
var root = widget.createShadowRoot();
var thumb = document.createElement('div');
thumb.part = 'thumb';
root.appendChild(thumb);
</pre>
<p>Once the <code>part</code> property is set, the consumer of the widget could style the widget's thumb using the part pseudo-element with <code>thumb</code> as a parameter, reaching into the widget's shadow tree directly to the thumb:</p>
<pre class="highlight">
div::part(thumb) {
width: 10px;
height: 10px;
color: bisque;
}
</pre>
</div>
</section>
</section>
<section id="user-interaction">
<h2>User Interaction</h2>
<section id="ranges-and-selection">
<h3>Ranges and Selections</h3>
<p>Since <a href="http://www.w3.org/TR/domcore/#concept-node">nodes</a> which are in the different <a href="http://dom.spec.whatwg.org/#concept-node-tree">node trees</a> never have the same <a href="http://www.w3.org/TR/domcore/#concept-tree-root">root</a>, there may never exist a valid <a href="http://www.w3.org/TR/domcore/#range">DOM range</a> that spans multiple <a href="http://dom.spec.whatwg.org/#concept-node-tree">node trees</a>.</p>
<p>Accordingly, <a href="http://dvcs.w3.org/hg/editing/raw-file/tip/editing.html#concept-selection">selections</a> may only exist within one <a href="http://dom.spec.whatwg.org/#concept-node-tree">node tree</a>, because they are defined by a single <a href="http://www.w3.org/TR/domcore/#range">range</a>. The <a href="http://dvcs.w3.org/hg/editing/raw-file/tip/editing.html#concept-selection">selection</a>, returned by the <a href="http://dvcs.w3.org/hg/editing/raw-file/tip/editing.html#dom-window-getselection"><code>window.getSelection()</code></a> method <strong>must</strong> never return a <a href="http://dvcs.w3.org/hg/editing/raw-file/tip/editing.html#concept-selection">selection</a> within a <a href="#dfn-shadow-tree">shadow tree</a>.</p>
<p>The <code>getSelection()</code> method of the <a href="#dfn-shadow-root">shadow root</a> object <strong>must</strong> return the current <a href="http://dvcs.w3.org/hg/editing/raw-file/tip/editing.html#concept-selection">selection</a> in this <a href="#dfn-shadow-tree">shadow tree</a>.</p>
</section>
<section id="focus-navigation">
<h3>Focus Navigation</h3>
<p>If a <a href="http://www.3.org/TR/domcore/#concept-node">node</a> doesn’t <a href="http://dom.spec.whatwg.org/#concept-tree-participate">participate</a> in the <a href="#dfn-composed-tree">composed tree</a>, the <a href="http://www.3.org/TR/domcore/#concept-node">node</a> <strong>must</strong> be skipped from the <a href="http://www.w3.org/TR/css3-ui/#keyboard">navigation order</a> sequence.</p>
<p>The <a href="http://www.w3.org/TR/css3-ui/#keyboard">navigation order</a> within a <a href="#dfn-shadow-tree">shadow tree</a> <strong>must</strong> be computed as a list of <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/editing.html#focusable">focusable</a> <a href="http://www.w3.org/TR/domcore/#concept-element">elements</a> in <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/infrastructure.html#tree-order">tree order</a>, and is called <dfn id="dfn-shadow-tree-navigation-order">shadow tree navigation order</dfn>.</p>
<p>For <a href="http://www.w3.org/TR/css3-ui/#keyboard">sequential focus navigation</a>, the <a href="#dfn-shadow-tree-navigation-order">shadow tree navigation order</a> sequence for a given <a href="#dfn-shadow-tree">shadow tree</a> <var>A</var> <strong>must</strong> be inserted into other <a href="http://www.w3.org/TR/css3-ui/#keyboard">navigation order</a> as follow:
<ol>
<li>If the <a href="http://dom.spec.whatwg.org/#concept-tree-root">root</a> <a href="http://www.3.org/TR/domcore/#concept-node">node</a> of <var>A</var> is the <a href="#dfn-youngest-shadow-root">youngest shadow root</a>:
<ol>
<li>Let <var>B</var> be the <a href="#dfn-parent-tree">parent tree</a> of <var>A</var></li>
<li>Let <var>HOST</var> be the <a href="#dfn-shadow-host">shadow host</a> which <a href="#dfn-verb-host">hosts</a> A</li>
<li>The <a href="#dfn-shadow-tree-navigation-order">shadow tree navigation order</a> for A <strong>must</strong> be inserted into the <a href="http://www.w3.org/TR/css3-ui/#keyboard">navigation order</a> for <var>B</var>:
<ol>
<li>immediately after <var>HOST</var>, if <var>HOST</var> is <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/editing.html#focusable">focusable</a>; or</li>
<li>in place of the <var>HOST</var> as if <var>HOST</var> were assigned the value of <a href="http://www.w3.org/TR/css3-ui/#keyboard"><code>auto</code></a> for determining its position.</li>
</ol></li>
</ol></li>
<li>Otherwise:
<ol>
<li>Let <var>B</var> be the <a href="#dfn-younger-shadow-root">younger shadow root</a> relative to <var>A</var></li>
<li>Let <var>SHADOW</var> be the <a href="#dfn-shadow-insertion-point">shadow insertion point</a> in <var>B</var></li>
<li>If <var>SHADOW</var> exists, the <a href="#dfn-shadow-tree-navigation-order">shadow tree navigation order</a> for <var>A</var> <strong>must</strong> be inserted into the <a href="http://www.w3.org/TR/css3-ui/#keyboard">navigation order</a> for <var>B</var> immediately after <var>SHADOW</var> as if <var>SHADOW</var> were assigned the value of <a href="http://www.w3.org/TR/css3-ui/#keyboard"><code>auto</code></a> for determining its position.</li>
</ol></li>
</ol>
</p>
<p>For <a href="http://www.w3.org/TR/css3-ui/#keyboard">directional focus navigation</a>, it is up to the user agent to integrate the <a href="#dfn-shadow-tree-navigation-order">shadow tree navigation orders</a> into the <a href="http://www.w3.org/TR/domcore/#concept-document">document</a> <a href="http://www.w3.org/TR/css3-ui/#keyboard">navigation order</a>.</p>
</section>
<section id="active-element">
<h3>Active Element</h3>
<p>To maintain encapsulation, the value of the <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/dom.html#document">Document</a> object's focus API property <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/editing.html#dom-document-activeelement">activeElement</a> <strong>must</strong> be adjusted. To prevent loss of information when adjusting this value, each <a href="#dfn-shadow-root">shadow root</a> <strong>must</strong> also have an <code>activeElement</code> property to store the value of the focused <a href="http://www.w3.org/TR/domcore/#concept-element">element</a> in the <a href="#dfn-shadow-tree">shadow tree</a>.</p>
<p>The <dfn id="active-element-adjustment-algorithm">active <a href="http://www.w3.org/TR/domcore/#concept-element">element</a> adjustment algorithm</dfn> is used to determine the value of the <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/editing.html#dom-document-activeelement">activeElement</a> property, and it <strong>must</strong> be equivalent to processing the following steps:</p>
<div class="algorithm">
<dl>
<dt>Input</dt>
<dd><var>ELEMENT</var>, the focused <a href="http://www.w3.org/TR/domcore/#concept-element">element</a></dd>
<dd><var>ROOT</var>, either a <a href="http://dom.spec.whatwg.org/#concept-document">document</a> or a <a href="#dfn-shadow-root">shadow root</a></dd>
<dt>Output</dt>
<dd><var>ADJUSTED</var>, an adjusted <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/editing.html#dom-document-activeelement">activeElement</a> property of <var>ROOT</var>.</dd>
</dl>
<ol>
<li>Let <var>PATH</var> be the result of the <a href="#dfn-event-path-calculation-algorithm">event path calculation algorithm</a> with <var>ELEMENT</var> and null as input</li>
<li>Let <var>ADJUSTED</var> be the result of the <a href="#dfn-retargeting-algorithm">retargeting algorithm</a> with <var>PATH</var> and <var>ROOT</var> as input</li>
</ol>
</div>
</section>
<section id="editing">
<h3>Editing</h3>
<p>The value of the <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/editing.html#attr-contenteditable"><code>contenteditable</code></a> attribute <strong>must not</strong> propagate from <a href="#dfn-shadow-host">shadow host</a> to its <a href="#dfn-shadow-tree">shadow trees</a>.</p>
</section>
<section id="assistive-technology">
<h3>Assistive Technology</h3>
<p>User agents with assistive technology traverse the <a href="#dfn-composed-tree">composed tree</a>, and thus enable full use of of <a href="http://www.w3.org/WAI/PF/aria/">WAI-ARIA</a> semantics in the <a href="#dfn-shadow-tree">shadow trees</a>.</p>
</section>
</section>
<section id="html-elements">
<h2>HTML Elements in Shadow Trees</h2>
<p>Comparatively, a <a href="#dfn-shadow-tree">shadow tree</a> can be seen as somewhere between <em>just part of a <a href="http://www.w3.org/TR/domcore/#concept-document">document</a></em> and itself being a <a href="http://www.w3.org/TR/domcore/#interface-documentfragment">document fragment</a>. Since it is rendered, a <a href="#dfn-shadow-tree">shadow tree</a> aims to retain the traits of a typical <a href="http://www.w3.org/TR/domcore/#trees">tree</a> in a <a href="http://www.w3.org/TR/domcore/#concept-document">document</a>. At the same time, it is an encapsulation abstraction, so it has to avoid affecting the <a href="#dfn-document-tree">document tree</a>. Thus, the <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/semantics.html#semantics">HTML elements</a> <strong>must</strong> behave <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/">as specified</a> in the <a href="#dfn-shadow-tree">shadow trees</a>, with a few exceptions.</p>
<section id="inert-html-elements">
<h3>Inert HTML Elements</h3>
<p>A subset of <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/semantics.html#semantics">HTML elements</a> <strong>must</strong> behave as <dfn id="dfn-inert">inert</dfn>, or not part of the <a href="#dfn-document-tree">document tree</a>. This is consistent how the <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/semantics.html#semantics">HTML elements</a> would behave in a <a href="http://www.w3.org/TR/domcore/#interface-documentfragment">document fragment</a>. These <a href="http://www.w3.org/TR/domcore/#concept-element">elements</a> are:</p>
<ul>
<li><a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/semantics.html#the-base-element"><code>base</code></a></li>
<li><a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/semantics.html#the-link-element"><code>link</code></a></li>
</ul>
<p>All other <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/semantics.html#semantics">HTML elements</a> in the <a href="#dfn-shadow-tree">shadow trees</a> <strong>must</strong> behave as if they were part of the <a href="#dfn-document-tree">document tree</a>.</p>
</section>