-
Notifications
You must be signed in to change notification settings - Fork 790
Expand file tree
/
Copy pathOverview.bs
More file actions
3517 lines (2826 loc) · 133 KB
/
Overview.bs
File metadata and controls
3517 lines (2826 loc) · 133 KB
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
<h1>Selectors Level 4</h1>
<pre class='metadata'>
Group: CSSWG
Shortname: selectors
Level: 4
Status: ED
Work Status: Revising
ED: https://drafts.csswg.org/selectors
TR: https://www.w3.org/TR/selectors/
Previous Version: https://www.w3.org/TR/2013/WD-selectors4-20130502/
Previous Version: https://www.w3.org/TR/2012/WD-selectors4-20120823/
Previous Version: https://www.w3.org/TR/2011/WD-selectors4-20110929/
Editor: Elika J. Etemad / fantasai, Invited Expert, http://fantasai.inkedblade.net/contact
Editor: Tab Atkins Jr., Google, http://xanthir.com/contact/
Former Editor: Tantek Çelik, http://www.tantek.com
Former Editor: Daniel Glazman
Former Editor: Ian Hickson
Former Editor: Peter Linss
Former Editor: John Williams
Abstract: <b>Selectors</b> are patterns that match against elements in a tree, and as such form one of several technologies that can be used to select nodes in a document. Selectors have been optimized for use with HTML and XML, and are designed to be usable in performance-critical code. They are a core component of <abbr title="Cascading Style Sheets">CSS</abbr> (Cascading Style Sheets), which uses Selectors to bind style properties to elements in the document.
Abstract: Selectors Level 4 describes the selectors that already exist in [[!SELECT]], and further introduces new selectors for CSS and other languages that may need them.
At Risk: the column combinator
At Risk: the '':drop()'' pseudo-class
At Risk: the '':read-write'' pseudo-class
Ignored Terms: function token, Document, DocumentFragment, math, h1, shadow tree, query(), quirks mode, button, a, span, object, p, div, q, area, link, label, input, html, em, li, ol, pre, CSS Value Definition Syntax
Ignored Vars: identifier, extended filtering
Link Defaults: dom-core-ls (interface) Document
</pre>
<style>
#selector-examples td:first-child {
white-space: nowrap;
}
</style>
<h2 id="context">
Introduction</h2>
<em>This section is not normative.</em>
A <dfn>selector</dfn> is a boolean predicate
that takes an element in a tree structure
and tests whether the element matches the selector or not.
These expressions may be used for many things:
<ul>
<li>
directly on an element to test whether it matches some criteria,
such as in the <code>element.matches()</code> function defined in [[DOM]]
<li>
applied to an entire tree of elements
to filter it into a set of elements that match the criteria,
such as in the <code>document.queryAll()</code> function defined in [[DOM]]
or the selector of a CSS style rule.
<li>
used "in reverse" to generate markup that would match a given selector,
such as in <a href="http://haml.info/">HAML</a> or <a href="http://en.wikipedia.org/wiki/Zen_Coding">Zen Coding</a>
</ul>
Selectors Levels 1, 2, and 3 are defined as the subsets of selector
functionality defined in the <a href="https://www.w3.org/TR/REC-CSS1">CSS1</a>,
<a href="https://www.w3.org/TR/CSS21/">CSS2.1</a>, and
<a href="https://www.w3.org/TR/css3-selectors/">Selectors Level 3</a>
specifications, respectively. This module defines Selectors Level 4.
<h3 id="placement">Module Interactions</h3>
This module replaces the definitions of
and extends the set of selectors defined for CSS in [[SELECT]] and [[CSS21]].
Pseudo-element selectors,
which define abstract elements in a rendering tree,
are not part of this specification:
their generic syntax is described here,
but, due to their close integration with the rendering model and irrelevance to other uses such as DOM queries,
they will be defined in other modules.
<h2 id="overview">
Selectors Overview</h2>
<em>This section is non-normative, as it merely summarizes the
following sections.</em>
A selector represents a structure. This structure can be used as a
condition (e.g. in a CSS rule) that determines which elements a
selector matches in the document tree, or as a flat description of the
HTML or XML fragment corresponding to that structure.
Selectors may range from simple element names to rich contextual
representations.
The following table summarizes the Selector syntax:
<table class="data" id="selector-examples">
<col class="pattern">
<col class="meaning">
<col class="section">
<col class="level">
<thead>
<tr>
<th>Pattern
<th>Represents
<th>Section
<th>Level
<tbody>
<tr>
<td><code>*</code>
<td>any element
<td>[[#the-universal-selector]]
<td>2
<tr>
<td><code>E</code>
<td>an element of type E
<td>[[#type-selectors]]
<td>1
<tbody>
<tr>
<td><code>E:not(<var>s1</var>, <var>s2</var>)</code>
<td>an E element that does not match either <a>compound selector</a> <var>s1</var>
or <a>compound selector</a> <var>s2</var>
<td>[[#negation]]
<td>3/4
<tr>
<td><code>E:matches(<var>s1</var>, <var>s2</var>)</code>
<td>an E element that matches <a>compound selector</a> <var>s1</var>
and/or <a>compound selector</a> <var>s2</var>
<td>[[#matches]]
<td>4
<tr>
<td><code>E:has(<var>rs1</var>, <var>rs2</var>)</code>
<td>an E element,
if either of the <a>relative selectors</a> <var>rs1</var> or <var>rs2</var>,
when evaluated with E as the <a>:scope elements</a>,
match an element
<td>[[#relational]]
<td>4
<tbody>
<tr>
<td><code>E.warning</code>
<td>an E element belonging to the class <code>warning</code>
(the document language specifies how class is determined).
<td>[[#class-html]]
<td>1
<tr>
<td><code>E#myid</code>
<td>an E element with ID equal to <code>myid</code>.
<td>[[#id-selectors]]
<td>1
<tr>
<td><code>E[foo]</code>
<td>an E element with a <code>foo</code> attribute
<td>[[#attribute-selectors]]
<td>2
<tr>
<td><code>E[foo="bar"]</code>
<td>an E element whose <code>foo</code> attribute value is
exactly equal to <code>bar</code>
<td>[[#attribute-selectors]]
<td>2
<tr>
<td><code>E[foo="bar" i]</code>
<td>an E element whose <code>foo</code> attribute value is
exactly equal to any (ASCII-range) case-permutation of <code>bar</code>
<td>[[#attribute-case]]
<td>4
<tr>
<td><code>E[foo~="bar"]</code>
<td>an E element whose <code>foo</code> attribute value is
a list of whitespace-separated values, one of which is
exactly equal to <code>bar</code>
<td>[[#attribute-selectors]]
<td>2
<tr>
<td><code>E[foo^="bar"]</code>
<td>an E element whose <code>foo</code> attribute value
begins exactly with the string <code>bar</code>
<td>[[#attribute-substrings]]
8889
<td>3
<tr>
<td><code>E[foo$="bar"]</code>
<td>an E element whose <code>foo</code> attribute value
ends exactly with the string <code>bar</code>
<td>[[#attribute-substrings]]
<td>3
<tr>
<td><code>E[foo*="bar"]</code>
<td>an E element whose <code>foo</code> attribute value
contains the substring <code>bar</code>
<td>[[#attribute-substrings]]
<td>3
<tr>
<td><code>E[foo|="en"]</code>
<td>an E element whose <code>foo</code> attribute value is
a hyphen-separated list of values beginning with <code>en</code>
<td>[[#attribute-selectors]]
<td>2
<tbody>
<tr>
<td><code>E:dir(ltr)</code>
<td>an element of type E in with left-to-right directionality
(the document language specifies how directionality is determined)
<td>[[#the-dir-pseudo]]
<td>4
<tr>
<td><code>E:lang(zh, "*-hant")</code>
<td>an element of type E tagged as being either in Chinese
(any dialect or writing system)
or othewise written with traditional Chinese characters
<td>[[#the-lang-pseudo]]
<td>2/4
<tbody>
<tr>
<td><code>E:any-link</code>
<td>an E element being the source anchor of a hyperlink
<td>[[#the-any-link-pseudo]]
<td>4
<tr>
<td><code>E:link</code>
<td>an E element being the source anchor of a hyperlink
of which the target is not yet visited
<td>[[#link]]
<td>1
<tr>
<td><code>E:visited</code>
<td>an E element being the source anchor of a hyperlink
of which the target is already visited
<td>[[#link]]
<td>1
<tr>
<td><code>E:target</code>
<td>an E element being the target of the referring URL
<td>[[#the-target-pseudo]]
<td>3
<tr>
<td><code>E:scope</code>
<td>an E element being a designated reference element
<td>[[#the-scope-pseudo]]
<td>4
<tbody>
<tr>
<td><code>E:current</code>
<td>an E element that is currently presented in a time-dimensional canvas
<td>[[#time-pseudos]]
<td>4
<tr>
<td><code>E:current(<var>s</var>)</code>
<td>an E element that is the deepest '':current'' element that
matches selector <var>s</var>
<td>[[#time-pseudos]]
<td>4
<tr>
<td><code>E:past</code>
<td>an E element that is in the past in a time-dimensional canvas
<td>[[#time-pseudos]]
<td>4
<tr>
<td><code>E:future</code>
<td>an E element that is in the future in a time-dimensional canvas
<td>[[#time-pseudos]]
<td>4
<tbody>
<tr>
<td><code>E:active</code>
<td>an E element that is in an activated state
<td>[[#useraction-pseudos]]
<td>1
<tr>
<td><code>E:hover</code>
<td>an E element that is under the cursor,
or that has a descendant under the cursor
<td>[[#useraction-pseudos]]
<td>2
<tr>
<td><code>E:focus</code>
<td>an E element that has user input focus
<td>[[#useraction-pseudos]]
<td>2
<tr>
<td><code>E:drop</code>
<td>an E element that can possibly receieve a drop
<td>[[#drag-pseudos]]
<td>4
<tr>
<td><code>E:drop(active)</code>
<td>an E element that is the current drop target for the item being dragged
<td>[[#drag-pseudos]]
<td>4
<tr>
<td><code>E:drop(valid)</code>
<td>an E element that could receive the item currently being dragged
<td>[[#drag-pseudos]]
<td>4
<tr>
<td><code>E:drop(invalid)</code>
<td>an E element that cannot receive the item currently being dragged, but could receive some other item
<td>[[#drag-pseudos]]
<td>4
<tbody>
<tr>
<td><code>E:enabled<br>E:disabled</code>
<td>a user interface element E that is enabled or disabled, respectively
<td>[[#enableddisabled]]
<td>3
<tr>
<td><code>E:read-write</code><br><code>E:read-only</code>
<td>a user interface element E that is user alterable, or not
<td>[[#rw-pseudos]]
<td>3-UI/4
<tr>
<td><code>E:placeholder-shown</code>
<td>an input control currently showing placeholder text
<td>[[#rw-pseudos]]
<td>3-UI/4
<tr>
<td><code>E:default</code>
<td>a user interface element E that is the default item in a group of related choices
<td>[[#the-default-pseudo]]
<td>3-UI/4
<tr>
<td><code>E:checked</code>
<td>a user interface element E that is checked/selected
(for instance a radio-button or checkbox)
<td>[[#checked]]
<td>3
<tr>
<td><code>E:indeterminate</code>
<td>a user interface element E that is in an indeterminate state
(neither checked nor unchecked)
<td>[[#indeterminate]]
<td>4
<tr>
<td><code>E:valid</code><br><code>E:invalid</code>
<td>a user-input element E that meets, or doesn't, its data validity semantics
<td>[[#range-pseudos]]
<td>3-UI/4
<tr>
<td><code>E:in-range</code><br><code>E:out-of-range</code>
<td>a user-input element E whose value is in-range/out-of-range
<td>[[#range-pseudos]]
<td>3-UI/4
<tr>
<td><code>E:required</code><br><code>E:optional</code>
<td>a user-input element E that requires/does not require input
<td>[[#opt-pseudos]]
<td>3-UI/4
<tr>
<td><code>E:user-error</code>
<td>a user-altered user-input element E with incorrect input (invalid, out-of-range, omitted-but-required)
<td>[[#user-pseudos]]
<td>4
<tbody>
<tr>
<td><code>E:root</code>
<td>an E element, root of the document
<td>[[#structural-pseudos]]
<td>3
<tr>
<td><code>E:empty</code>
<td>an E element that has no children (not even text nodes)
<td>[[#structural-pseudos]]
<td>3
<tr>
<td><code>E:blank</code>
<td>an E element that has no content except maybe white space
<td>[[#structural-pseudos]]
<td>4
<tr>
<td><code>E:nth-child(<var>n</var> [of <var>S</var>]?)</code>
<td>an E element, the <var>n</var>-th child of its parent matching <var>S</var>
<td>[[#child-index]]
<td>3
<tr>
<td><code>E:nth-last-child(<var>n</var> [of <var>S</var>]?)</code>
<td>an E element, the <var>n</var>-th child of its parent matching <var>S</var>,
counting from the last one
<td>[[#child-index]]
<td>3
<tr>
<td><code>E:first-child</code>
<td>an E element, first child of its parent
<td>[[#child-index]]
<td>2
<tr>
<td><code>E:last-child</code>
<td>an E element, last child of its parent
<td>[[#child-index]]
<td>3
<tr>
<td><code>E:only-child</code>
<td>an E element, only child of its parent
<td>[[#child-index]]
<td>3
<tr>
<td><code>E:nth-of-type(<var>n</var>)</code>
<td>an E element, the <var>n</var>-th sibling of its type
<td>[[#typed-child-index]]
<td>3
<tr>
<td><code>E:nth-last-of-type(<var>n</var>)</code>
<td>an E element, the <var>n</var>-th sibling of its type,
counting from the last one
<td>[[#typed-child-index]]
<td>3
<tr>
<td><code>E:first-of-type</code>
<td>an E element, first sibling of its type
<td>[[#typed-child-index]]
<td>3
<tr>
<td><code>E:last-of-type</code>
<td>an E element, last sibling of its type
<td>[[#typed-child-index]]
<td>3
<tr>
<td><code>E:only-of-type</code>
<td>an E element, only sibling of its type
<td>[[#typed-child-index]]
<td>3
<tbody>
<tr>
<td><code>E F</code> <em>or</em> <code>E >> F</code>
<td>an F element descendant of an E element
<td>[[#descendant-combinators]]
<td>1 <em>or</em> 4
<tr>
<td><code>E > F</code>
<td>an F element child of an E element
<td>[[#child-combinators]]
<td>2
<tr>
<td><code>E + F</code>
<td>an F element immediately preceded by an E element
<td>[[#adjacent-sibling-combinators]]
<td>2
<tr>
<td><code>E ~ F</code>
<td>an F element preceded by an E element
<td>[[#general-sibling-combinators]]
<td>3
<tbody>
<tr>
<td><code>F || E</code>
<td>an E element that represents a cell in a grid/table
belonging to a column represented by an element F
<td>[[#table-pseudos]]
<td>4
<tr>
<td><code>E:nth-column(<var>n</var>)</code>
<td>an E element that represents a cell belonging to the
<var>n</var>th column in a grid/table
<td>[[#table-pseudos]]
<td>4
<tr>
<td><code>E:nth-last-column(<var>n</var>)</code>
<td>an E element that represents a cell belonging to the
<var>n</var>th column in a grid/table, counting from the last one
<td>[[#table-pseudos]]
<td>4
</table>
Note: Some Level 4 selectors (noted above as "3-UI") were introduced in [[CSS3UI]].
<h3 id="profiles">
<a>Dynamic</a> vs <a>Static</a> Selector Profiles</h3>
Selectors are used in many different contexts,
with wildly varying performance characteristics.
Some powerful selectors are unfortu
EE4C
nately too slow
to realistically include in the more performance-sensitive contexts.
To accommodate this, two profiles of the Selectors spec are defined:
<dl>
<dt><dfn local-lt="dynamic">dynamic profile</dfn>
<dd>
The <a>dynamic</a> profile is appropriate for use in any context,
including dynamic browser CSS selector matching.
It includes every selector defined in this document,
except for:
<ul>
<li>The '':has()'' pseudo-class
</ul>
<dt><dfn local-lt="static">static profile</dfn>
<dd>
The <a>static</a> profile is appropriate for contexts which aren't extremely performance sensitive;
in particular, it's appropriate for contexts which evaluate selectors against a static document tree.
For example, the {{Element/query()}} method defined in [[DOM]] should use the <a>static</a> profile.
It includes all of the selectors defined in this document.
</dl>
CSS implementations conformant to Selectors Level 4 must use the <a>dynamic</a> profile for CSS selection.
Implementations using the <a>dynamic</a> profile must treat selectors that are not included in the profile
as unknown and invalid.
<p class='issue'>
The categorization of things into the "dynamic" or "static" profiles needs implementor review.
If some things currently not in the dynamic profile can reasonably be done in CSS Selectors,
we should move them.
<h2 id="syntax">
Selector Syntax and Structure</h2>
<h3 id="structure">
Structure and Terminology</h3>
The term <a>selector</a> can refer to a <a>simple selector</a>,
<a>compound selector</a>, <a>complex selector</a>, or <a>selector list</a>.
A <dfn id="simple" export>simple selector</dfn>
represents an element matched by a particular aspect.
A <a>type selector</a>,
<a>universal selector</a>,
<a>attribute selector</a>,
<a>class selector</a>,
<a>ID selector</a>,
or <a>pseudo-class</a>
is a <a>simple selector</a>.
A <dfn id="compound" export>compound selector</dfn>
is a sequence of <a>simple selectors</a>
that are not separated by a <a>combinator</a>.
It represents an element that matches all of the <a>simple selectors</a> it contains.
If it contains a <a>type selector</a> or <a>universal selector</a>,
that selector must come first in the sequence.
Only one type selector or universal selector is allowed in the sequence.
Note: As whitespace is a valid <a>combinator</a>,
no whitespace is allowed between the <a>simple selectors</a>
in a <a>compound selector</a>.
A <dfn id="complex" export>complex selector</dfn> is a sequence of one or more <a>compound selectors</a>
separated by <a>combinators</a>.
A <dfn export>combinator</dfn> represents a particular kind of relationship
between the elements matched by the <a>compound selectors</a> on either side.
Combinators in Selectors level 4 include:
the <a>descendant combinator</a> (white space),
the <a>child combinator</a> (U+003E, <code>></code>),
the <a>next-sibling combinator</a> (U+002B, <code>+</code>),
and the <a>following-sibling combinator</a> (U+007E, <code>~</code>).
A <dfn export lt="list of simple selectors|list of compound selectors|list of complex selectors">list of simple/compound/complex selectors</dfn>
is a comma-separated list of
<a lt="simple selector">simple</a>,
<a lt="compound selector">compound</a>,
or <a>complex selectors</a>.
This is also called just a <dfn export lt="selector list|list of selectors">selector list</dfn>
when the type is either unimportant or specified in the surrounding prose;
if the type is important and unspecified,
it defaults to meaning a <a>list of complex selectors</a>.
See [[#grouping]] for further details on <a>selector lists</a>.
The <dfn export local-lt="subject">subject of a selector</dfn> is
the element(s) that selector is defined to be about:
<ul>
<li>For a <a>simple selector</a>, it is any element represented by that selector.
<li>For a <a>compound selector</a>, it is any element that matches all of its composite <a>simple selectors</a>.
<li>For a <a>complex selector</a>, it is any element that matches the last <a>compound selector</a> in the selector.
<li>For a <a>selector list</a>, it is any element that matches any of the <a>selectors</a> in the list.
</ul>
An element is said to <dfn export>match</dfn> a selector
if it is a <a>subject</a> of that selector.
Thus a selector consisting of a single <a>compound selector</a>
matches any element satisfying its requirements.
Prepending another <a>compound selector</a> and a <a>combinator</a>
to a sequence imposes additional matching constraints,
so the <a>subjects</a> of a <a>complex selector</a> are always a subset of
the elements represented by its last <a>compound selector</a>.
Issue: Can we make this less wishy-washy by saying that a complex selector “represents” its last compound selector?
Or do we need to have ''a + b'' “represent” both an "a" and a "b" in a sibling relationship?
Issue: Pseudo-elements aren't handled here, and should be.
<h3 id='data-model'>
Data Model</h3>
Selectors are evaluated against an element tree such as the DOM. [[!DOM]]
Within this specification,
this may be referred to as the "document tree" or "source document".
Each element may have any of the following five aspects,
which can be selected against,
all of which are matched as strings:
<ul>
<li>The element's type (also known as its tag name).
<li>The element's namespace.
<li>An ID.
<li>Classes (named groups) to which it belongs.
<li>Attributes, which are name-value pairs.
</ul>
While individual elements may lack any of the above features,
some elements are <dfn export>featureless</dfn>.
A <a>featureless</a> element does not match any selector at all,
except those it is explicitly defined to match.
If a given selector <em>is</em> allowed to match a <a>featureless</a> element,
it must do so while ignoring the default namespace. [[CSS3NAMESPACE]]
<div class='example'>
For example, the <a>host element</a> in a <a>shadow tree</a> is <a>featureless</a>,
and can't be matched by <em>any</em> <a>pseudo-class</a> except for '':host'' and '':host-context()''.)
</div>
Many of the selectors depend on the semantics of the <dfn>document language</dfn>
(i.e. the language and semantics of the document tree)
and/or the semantics of the <dfn>host language</dfn>
(i.e. the language that is using selectors syntax).
For example, the '':lang()'' selector depends on the <a>document language</a> (e.g. HTML)
to define how an element is associated with a language.
As a slightly different example, the ''::first-line'' pseudo-element
depends on the <a>host language</a> (e.g. CSS)
to define what a ''::first-line'' pseudo-element represents
and what it can do.
<h3 id="scoping">
Scoped Selectors</h3>
Some host applications may choose to <dfn export lt="scoped selector" local-lt="scope">scope</dfn> selectors
to a particular subtree or fragment of the document.
The root of the scoping subtree is called the <dfn export>scoping root</dfn>,
and may be either a true element (the <dfn export>scoping element</dfn>)
or a <dfn export lt="virtual scoping root">virtual</dfn> one (such as a <a interface>DocumentFragment</a>).
There are two <dfn export lt="scoping method | selector scoping method">scoping methods</dfn> for selectors:
<dl>
<dt><dfn export id="scope-contained" lt="scope-contained | scope-contained selector">scope-contained</dfn>
<dd>
With this method of scoping, selectors match as if
the <a>scoping root</a> were the root of the document:
all <a>compound selectors</a> must be represented within the scope.
(The '':root'' pseudo-class, however,
still only matches the actual root of the document.)
<dt><dfn export id="scope-filtered" lt="scope-filtered | scope-filtered selector">scope-filtered</dfn>
<dd>
With this method of scoping, a selector matches an element only if the element is within the scope,
even if other components of the selector are outside the scope.
(A <a>scoping element</a> is considered to be in scope.)
</dl>
<div class='example'>
For example,
the <code>element.querySelector()</code> function defined in [[DOM]]
allows the author to define a <a>scope-filtered</a> selector.
On the other hand, the selectors within an [[HTML5]] scoped stylesheet
define <a>scope-contained</a> selectors.
</div>
Note: If there are no <a>:scope elements</a> when a selector is evaluated,
the <a>scoping root</a> acts like a <a>:scope element</a>.
<h3 id="relative">
Relative Selectors</h3>
Certain contexts may accept <dfn lt="relative selector | relative | scope-relative" export>relative selectors</dfn>,
which are a shorthand for selectors that represent elements relative to a <a>:scope element</a>
(i.e. an element that matches '':scope'').
In a <a>relative selector</a>,
“:scope ” (the '':scope'' pseudo-class followed by a space)
is implied at the beginning of each <a>complex selector</a>
that does not already contain the '':scope'' pseudo-class.
This allows the selector to begin syntactically with a <a>combinator</a>.
However, it must be <a href="#absolutize">absolutized</a> before matching.
Relative selectors, once absolutized,
can additionally be <a>scope-contained</a> or <a>scope-filtered</a>.
<h4 id='absolutizing'>
Absolutizing a Relative Selector</h4>
To <dfn id='absolutize' export>absolutize a relative selector</dfn>:
If there are no <a>:scope elements</a>
and the selector is <a>scoped</a> to a <a>virtual scoping root</a>:
<ol>
<li>
If the selector starts with a <a>child combinator</a>,
remove the child combinator.
The selector is now absolute,
with the additional constraint that the first compound selector in the selector
only matches elements without a parent.
<li>
Otherwise, if the selector starts with any combinator other than the white space form of the <a>descendant combinator</a>,
change the selector to '':not(*)''.
<span class='note'>This is the shortest selector that is valid, but guaranteed to match nothing.</span>
<li>
Otherwise, the selector is already absolute.
</ol>
Otherwise:
<ol>
<li>
If the selector starts with a <a>combinator</a> other than the white space form of the <a>descendant combinator</a>,
prepend '':scope'' as the initial <a>compound selector</a>.
<li>
Otherwise, if the selector does not contain any instance of the '':scope'' pseudo-class
(either at the top-level or as an argument to a functional pseudo-class),
prepend '':scope'' followed by the white space form of the <a>descendant combinator</a>.
<li>
Otherwise, the selector is already absolute.
</ol>
To <dfn id='absolutize-list' export>absolutize a relative selector list</dfn>,
absolutize each relative selector in the list.
<h3 id="pseudo-classes">
Pseudo-classes</h3>
<dfn export id="pseudo-class" lt="pseudo-class">Pseudo-classes</dfn> are <a>simple selectors</a>
that permit selection based on
information that lies outside of the document tree
or that can be awkward or impossible to express using the other simple selectors.
They can also be dynamic,
in the sense that an element can acquire or lose a pseudo-class
while a user interacts with the document,
without the document itself changing.
<a>Pseudo-classes</a> do not appear in or modify the document source or document tree.
The syntax of a <a>pseudo-class</a>
consists of a ":" (U+003A COLON)
followed by the name of the <a>pseudo-class</a>
as a CSS <a>identifier</a>,
and, in the case of a <dfn export id="functional-pseudo-class">functional pseudo-class</dfn>,
a pair of parentheses containing its arguments.
<p class="example">
For example, '':valid'' is a regular pseudo-class,
and '':lang()'' is a <a>functional pseudo-class</a>.
Like all CSS keywords, <a>pseudo-class</a> names are <a>ASCII case-insensitive</a>.
No <a>white space</a> is allowed between the colon and the name of the <a>pseudo-class</a>,
nor, as usual for CSS syntax,
between a <a>functional pseudo-class</a>’s name and its opening parenthesis
(which thus form a CSS <a>function token</a>).
Also as usual,
<a>white space</a> is allowed around the arguments inside the parentheses
of a functional pseudo-class
unless otherwise specified.
Like other <a>simple selectors</a>,
<a>pseudo-classes</a> are allowed in all <a>compound selectors</a> contained in a selector,
and must follow the <a>type selector</a> or <a>universal selector</a>, if present.
Note: Some <a>pseudo-classes</a> are mutually exclusive
(such that a <a>compound selector</a> containing them, while valid, will never match anything),
while others can apply simultaneously to the same element.
<h3 id="pseudo-elements">Pseudo-elements</h3>
Similar to how certain <a>pseudo-classes</a> represent additional state information
not directly present in the document tree,
a <dfn export id="pseudo-element">pseudo-element</dfn> represents an <em>element</em>
not directly present in the document tree.
They are used to create abstractions about the document tree
beyond those provided by the document tree.
For example,
pseudo-elements can be used to select portions of the document
that do not correspond to a document-language element
(including such ranges as don't align to element boundaries or fit within its tree structure);
that represent content not in the document tree or in an alternate projection of the document tree;
or that rely on information provided by styling, layout, user interaction, and other processes that are not reflected in the document tree.
<div class="example">
For instance, document languages do not offer mechanisms to access
the first letter or first line of an element's content,
but there exist <a>pseudo-elements</a>
(''::first-letter'' and ''::first-line'')
that allow those things to be styled.
Notice especially that in the case of ''::first-line'',
which portion of content is represented by the pseudo-element
depends on layout information
that cannot be inferred from the document tree.
<a>Pseudo-elements</a> can also represent content that doesn't exist in the source document at all,
such as the ''::before'' and ''::after'' pseudo-elements
which allow additional content to be inserted before or after the contents of any element.
</div>
Like <a>pseudo-classes</a>
<a>pseudo-elements</a> do not appear in or modify the document source or document tree.
Accordingly, they also do not affect the interpretation of <a>structural pseudo-classes</a>
or other selectors pertaining to their <a>originating element</a> or its tree.
The host language defines which pseudo-elements exist, their type, and their abilities.
Pseudo-elements that exist in CSS
are defined in [[CSS21]] (Level 2), [[SELECT]] (Level 3), and [[CSS-PSEUDO-4]] (Level 4).
<h4 id="pseudo-element syntax">
Syntax</h4>
The syntax of a <a>pseudo-element</a>
is "::" (two U+003A COLON characters)
followed by the name of the <a>pseudo-element</a> as an <a>identifier</a>.
<a>Pseudo-element</a> names are <a>ASCII case-insensitive</a>.
No <a>white space</a> is allowed between the two colons, or between the colons and the name.
Because <a href="https://www.w3.org/TR/CSS1">CSS Level 1</a> and <a href="https://www.w3.org/TR/CSS2">CSS Level 2</a>
conflated pseudo-elements and pseudo-classes by sharing a single-colon syntax for both,
user agents must also accept the previous one-colon notation
for the Level 1 & 2 pseudo-elements
(''::before'', ''::after'', ''::first-line'', and ''::first-letter'').
This compatibility notation is not allowed any other <a>pseudo-elements</a>.
However, as this syntax is deprecated,
authors should use the Level 3+ double-colon syntax for these <a>pseudo-elements</a>.
<a>Pseudo-elements</a> are <a>featureless</a>,
and so can't be matched by any other selector.
<h4 id="pseudo-element-attachment">
Binding to the Document Tree</h4>
<a>Pseudo-elements</a> do not exist independently in the tree:
they are always bound to another element on the page,
called their <dfn export>originating element</dfn>.
Syntactically, a <a>pseudo-element</a> immediately follows
the <a>compound selector</a> representing its <a>originating element</a>.
If this <a>compound selector</a> is omitted,
it is assumed to be the <a>universal selector</a> ''*''.
<div class='example'>
For example, in the selector ''div a::before'',
the ''a'' elements matched by the selector are the <a>originating elements</a>
for the ''::before'' pseudo-elements attached to them.
The selector ''::first-line'' is equivalent to ''*::first-line'',
which selects the ''::first-line'' pseudo-element on <em>every</em> element in the document.
</div>
When a <a>pseudo-element</a> is encountered in a selector,
the part of the selector before the <a>pseudo-element</a> selects the <a>originating element</a> for the <a>pseudo-element</a>;
the part of the selector after it, if any, applies to the <a>pseudo-element</a> itself.
(See below.)
<h4 id="pseudo-element-states">
Pseudo-classing Pseudo-elements</h4>
A <a>pseudo-element</a> may be immediately followed
by any combination of the <a href="#useraction-pseudos">user action pseudo-classes</a>,
in which case the <a>pseudo-element</a> is represented only when it is in the corresponding state.
Whether these pseudo-classes can match on the <a>pseudo-element</a>
depends on the <a>pseudo-class</a> and <a>pseudo-element</a>”s definitions:
unless otherwise-specified, none of these <a>pseudo-classes</a>
will match on the <a>pseudo-element</a>.
Issue: Clarify that '':not()'' and '':matches()'' can be used when containing abovementioned pseudos.
<div class="example">
For
4D9A
example, since the '':hover'' pseudo-class specifies
that it can apply to any pseudo-element,
''::first-line:hover'' will match when the first line is hovered.
However, since neither '':focus'' nor ''::first-line''
define that '':focus'' can apply to ''::first-line'',
the selector ''::first-line:focus'' will never match anything.
Issue: Does ''::first-line:not(:focus)'' match anything?
Notice that ''::first-line:hover'' is is very different from '':hover::first-line'',
which matches the first line of any originating element that is hovered!
For example, '':hover::first-line'' also matches the first line of a paragraph
when the second line of the paragraph is hovered,
whereas ''::first-line:hover'' only matches if the first line itself is hovered.
</div>
Note: Note that, unless otherwise specified in a future specification,
pseudo-classes other than the <a href="#useraction-pseudos">user action pseudo-classes</a>
are not valid when compounded to a pseudo-element;
so, for example, ''::before:first-child'' is an invalid selector.
<h4 id="pseudo-element-structure">
Internal Structure</h4>
Some <a>pseudo-elements</a> are defined to have internal structure.
These <a>pseudo-elements</a> may be followed by child/descendant combinators
to express those relationships.
Selectors containing <a>combinators</a> after the pseudo-element
are otherwise invalid.
<div class="example">
For example, ''::first-letter + span'' and ''::first-letter em'' are invalid selectors.
However, since ''::shadow'' is defined to have internal structure,
''::shadow > p'' is a valid selector.
</div>
Note: A future specification may expand the capabilities of existing pseudo-elements,
so some of these currently-invalid selectors (e.g. ''::first-line :any-link'')
may become valid in the future.
The children of such <a>pseudo-elements</a> can simultaneously be children of other elements, too,
turning the <a>selector match list</a> into a directed acyclic graph.
However, at least in CSS, their rendering must be defined so as to maintain the tree-ness of the <a>box tree</a>.
<div class='example'>
For example,
the ''::content'' pseudo-element treats elements distributed to it as its children.
This means that, given the following fragment:
<pre>
<div>
<span>foo</span>
<"shadow root">
<content></content>
</"shadow root">
</div>
</pre>
the selectors ''div > span'' and ''div::shadow ::content > span'' select the same element via different paths.
However, when rendered,
the <code><span></code> element generates boxes as if it were the child of the <code><content></code> element,
rather than the <code><div></code> element,
so the tree structure of the <a>box tree</a> is maintained.
</div>
<h3 id="case-sensitive">
Characters and case sensitivity</h3>
All Selectors syntax is case-insensitive within the ASCII range
(i.e. [a-z] and \[A-Z] are equivalent),
except for the following parts,
which are not under the control of Selectors:
the case-sensitivity of
document language element names,
attribute names,
and attribute values
depends on the document language.
<div class=example>
For example,
<a href="http://www.whatwg.org/html/selectors.html#case-sensitivity">in HTML, element and attribute names are ASCII case-insensitive</a>,
but in XML, they are case-sensitive.
</div>
Case sensitivity of namespace prefixes is defined in [[!CSS3NAMESPACE]].
Case sensitivity of <a>language ranges</a> is defined in the '':lang()'' section.
<dfn id="whitespace">White space</dfn> in Selectors consists of the
code points SPACE (U+0020), TAB (U+0009), LINE FEED (U+000A),
CARRIAGE RETURN (U+000D), and FORM FEED (U+000C) can occur in whitespace.
Other space-like code points, such as EM SPACE (U+2003) and
IDEOGRAPHIC SPACE (U+3000), are never part of white space.
Code points in Selectors can be escaped with a backslash
according to the same <a href="https://www.w3.org/TR/CSS21/syndata.html#characters">escaping rules</a> as CSS. [[!CSS21]]
Note that escaping a code point "cancels out" any special meaning it may have in Selectors.
For example, the selector ''#foo>a'' contains a combinator,
but ''#foo\>a'' instead selects an element with the id <code>foo>a</code>.
<h3 id="namespaces">
Declaring Namespace Prefixes</h3>
Certain selectors support namespace prefixes.
The mechanism by which namespace prefixes are <dfn id="nsdecl">declared</dfn>
should be specified by the language that uses Selectors.
If the language does not specify a namespace prefix declaration mechanism,
then no prefixes are declared.
In CSS, namespace prefixes are declared with the ''@namespace''rule. [[!CSS3NAMESPACE]]
<h3 id="invalid">
Invalid Selectors and Error Handling</h3>
User agents must observe the rules for handling
<dfn export lt="invalid selector" local-lt="invalid">invalid selectors</dfn>:
<ul>
<li>a parsing error in a selector,
e.g. an unrecognized token or a token which is not allowed at the current parsing point,
causes that selector to be invalid.
<li>a simple selector containing an <a href="#namespaces">undeclared namespace prefix</a> is invalid
<li>a selector containing an invalid simple selector, an invalid combinator
or an invalid token is invalid.
<li>a selector list containing an invalid selector is invalid.
<li>an empty selector, i.e. one that contains no <a>compound selector</a>, is invalid.
</ul>
An <a>invalid selector</a> represents, and therefore matches, nothing.
<h2 id="logical-combination">
Logical Combinations</h2>
<h3 id="grouping">
Selector Lists</h3>