Skip to content

Commit d6049b3

Browse files
tabatkinstabatkins
committed
[selectors] Rename 'reference element set' to ':scope elements', per Anne's suggestion.
--HG-- extra : rebase_source : e6d5c3c1055b0c579d930f884656098379ce669d
1 parent 2d72b11 commit d6049b3

2 files changed

Lines changed: 96 additions & 111 deletions

File tree

‎selectors/Overview.html‎

Lines changed: 58 additions & 65 deletions
Original file line numberDiff line numberDiff line change
@@ -1569,10 +1569,10 @@ <h3 id=scoping><span class=secno>3.5. </span> Scoped Selectors</h3>
15691569
href="#scope-contained"><i>scope-contained</i></a> selectors.
15701570
</div>
15711571

1572-
<p>Unless otherwise specified, the <a href="#scoping-root"><i>scoping
1573-
root</i></a> also forms the <a href="#reference-element-set"><i>reference
1574-
element set</i></a> and matches the <a
1575-
href="#scope-pseudo"><code>:scope</code></a> pseudo-class.
1572+
<p class=note> Note that if there are no <a
1573+
href="#scope-elements"><i>:scope elements</i></a> when a selector is
1574+
evaluated, the <a href="#scoping-root"><i>scoping root</i></a> acts like a
1575+
<a href="#scope-elements"><i>:scope element</i></a>.
15761576

15771577
<h3 id=relative><span class=secno>3.6. </span> Relative Selectors</h3>
15781578

@@ -1601,8 +1601,26 @@ <h4 id=absolutizing><span class=secno>3.6.1. </span> Absolutizing a
16011601

16021602
<p> To <dfn id=absolutize>absolutize a relative selector</dfn>:
16031603

1604-
<p> If the <a href="#reference-element-set"><i>reference element
1605-
set</i></a> is empty or consists of one or more elements:
1604+
<p> If there are no <a href="#scope-elements"><i>:scope elements</i></a>
1605+
and the selector is <i>scoped</i> to a <a href="#virtual"><i>virtual
1606+
scoping root</i></a>:
1607+
1608+
<ol>
1609+
<li> If the selector starts with a <a href="#child-combinator"><i>child
1610+
combinator</i></a>, remove the child combinator. The selector is now
1611+
absolute, with the additional constraint that the first compound selector
1612+
in the selector only matches elements without a parent.
1613+
1614+
<li> Otherwise, if the selector starts with any combinator other than the
1615+
<a href="#descendant-combinator"><i>descendant combinator</i></a>, change
1616+
the selector to ‘<a href="#negation-pseudo"><code
1617+
class=css>:not(*)</code></a>’. <span class=note>This is the shortest
1618+
selector that is valid, but guaranteed to match nothing.</span>
1619+
1620+
<li> Otherwise, the selector is already absolute.
1621+
</ol>
1622+
1623+
<p> Otherwise:
16061624

16071625
<ol>
16081626
<li> If the selector starts with a <a
@@ -1621,35 +1639,13 @@ <h4 id=absolutizing><span class=secno>3.6.1. </span> Absolutizing a
16211639
</ol>
16221640

16231641
<p class=issue> The above algorithm is different from Selectors API: its
1624-
step 2, which bailed if the reference element set was empty, has been
1625-
removed. This is because handling an explicitly empty list should return
1626-
nothing; if a reference element set was not given at all, Selectors API 2
1627-
should be amended to say that the selector must be absolute already.
1628-
(Broken example: doing <code>document.find('img', [list-of-links]))</code>
1629-
finds images that are descendants of links normally, but instead finds all
1630-
images in the document if the list-of-links is empty.)
1631-
1632-
<p> Otherwise, if the <a href="#reference-element-set"><i>reference element
1633-
set</i></a> consists of only a <a href="#virtual"><i>virtual scoping
1634-
root</i></a>:
1635-
1636-
<ol>
1637-
<li> If the selector starts with a <a href="#child-combinator"><i>child
1638-
combinator</i></a>, remove the child combinator. The selector is now
1639-
absolute, with the additional constraint that the first compound selector
1640-
in the selector only matches elements without a parent.
1641-
1642-
<li> Otherwise, if the selector starts with any combinator other than the
1643-
<a href="#descendant-combinator"><i>descendant combinator</i></a>, change
1644-
the selector to ‘<a href="#negation-pseudo"><code
1645-
class=css>:not(*)</code></a>’. <span class=note>This is the shortest
1646-
selector that is valid, but guaranteed to match nothing.</span>
1647-
1648-
<li> Otherwise, the selector is already absolute.
1649-
</ol>
1650-
1651-
<p> Otherwise, this is a spec error. Please report it to the relevant
1652-
standards body.
1642+
step 2, which bailed if there were no :scope elements, has been removed.
1643+
This is because handling an explicitly empty list should return nothing;
1644+
if no :scope elements were given at all, Selectors API 2 should be amended
1645+
to say that the selector must be absolute already. (Broken example: doing
1646+
<code>document.find('img', [list-of-links]))</code> finds images that are
1647+
descendants of links normally, but instead finds all images in the
1648+
document if the list-of-links is empty.)
16531649

16541650
<p> To <dfn id=absolutize-list>absolutize a relative selector list</dfn>,
16551651
absolutize each relative selector in the list.
@@ -2961,31 +2957,31 @@ <h3 id=the-target-pseudo><span class=secno>8.4. </span> The target
29612957
<h3 id=the-scope-pseudo><span class=secno>8.5. </span> The reference
29622958
element pseudo-class <a href="#scope-pseudo"><code>:scope</code></a></h3>
29632959

2964-
<p> The <dfn id=scope-pseudo>:scope</dfn> pseudo-class represents any
2965-
element that is in the <dfn id=reference-element-set>reference element
2966-
set</dfn>. This is is a (potentially empty) set of elements that provide a
2967-
reference point for selectors to match against, such as that specified by
2968-
the <code>querySelector()</code> call in <a href="#ref-SELECTORS-API2"
2960+
<p> In some contexts, selectors can be matched with an explicit set of <dfn
2961+
data-export=data-export id=scope-elements title=":scope element">:scope
2962+
elements</dfn>. This is is a (potentially empty) set of elements that
2963+
provide a reference point for selectors to match against, such as that
2964+
specified by the <code>querySelector()</code> call in <a
2965+
href="#ref-SELECTORS-API2"
29692966
rel=biblioentry>[SELECTORS-API2]<!--{{SELECTORS-API2}}--></a>, or the
29702967
parent element of a <a
29712968
href="http://www.whatwg.org/specs/web-apps/current-work/multipage/semantics.html#the-style-element">scoped
29722969
<code>&lt;style></code> element</a> in <a href="#ref-HTML5"
29732970
rel=biblioentry>[HTML5]<!--{{HTML5}}--></a>.
29742971

2975-
<p> If the <a href="#reference-element-set"><i>reference element
2976-
set</i></a> is not explicitly specified, it defaults to representing the
2977-
<a href="#scoping-root"><i>scoping root</i></a> (if any), else represents
2978-
the root of the document (i.e. matches <a
2979-
href="#roo-pseudo"><code>:root</code></a>). Specifications intending for
2980-
this pseudo-class to match specific elements rather than the document's
2981-
root element must define either a <a href="#scoping-root"><i>scoping
2972+
<p> The <dfn id=scope-pseudo>:scope</dfn> pseudo-class represents any
2973+
element that is a <a href="#scope-elements"><i>:scope element</i></a>. If
2974+
the <a href="#scope-elements"><i>:scope elements</i></a> are not
2975+
explicitly specified, but the selector is <i>scoped</i> and the <a
2976+
href="#scoping-root"><i>scoping root</i></a> is an element, then ‘<a
2977+
href="#scope-pseudo"><code class=css>:scope</code></a>’ represents the
2978+
<a href="#scoping-root"><i>scoping root</i></a>; otherwise, it represents
2979+
the root of the document (equivalent to ‘<a href="#roo-pseudo"><code
2980+
class=css>:root</code></a>’). Specifications intending for this
2981+
pseudo-class to match specific elements rather than the document's root
2982+
element must define either a <a href="#scoping-root"><i>scoping
29822983
root</i></a> (if using <a href="#scope"><i>scoped selectors</i></a>) or an
2983-
explicit <a href="#reference-element-set"><i>reference element
2984-
set</i></a>.
2985-
2986-
<p class=note> Note that since this pseudo-class only represents elements,
2987-
a virtual <a href="#scoping-root"><i>scoping root</i></a> cannot be the
2988-
subject of a selector; such a selector effectively represents nothing.
2984+
explicit set of <a href="#scope-elements"><i>:scope elements</i></a>.
29892985

29902986
<h2 id=useraction-pseudos><span class=secno>9. </span> User Action
29912987
Pseudo-classes</h2>
@@ -4375,12 +4371,9 @@ <h3 id=parse-a-relative-selector><span class=secno>17.2. </span> Parse A
43754371
Relative Selector</h3>
43764372

43774373
<p> This section defines how to <dfn id=parse-a-relative-selector0>parse a
4378-
relative selector</dfn> from a string <var>source</var>, against a <a
4379-
href="#reference-element-set"><i>reference element set</i></a>
4380-
<var>refs</var>. The reference element set must contain zero or more
4381-
elements, or a single virtual scoping root, such as a
4382-
<code>Document</code> or <code>Document Fragment</code>. It returns either
4383-
a complex selector list, or failure.
4374+
relative selector</dfn> from a string <var>source</var>, against <a
4375+
href="#scope-elements"><i>:scope elements</i></a> <var>refs</var>. It
4376+
returns either a complex selector list, or failure.
43844377

43854378
<ol>
43864379
<li> Let <var title="">selector</var> be the result of parsing
@@ -4396,7 +4389,7 @@ <h3 id=parse-a-relative-selector><span class=secno>17.2. </span> Parse A
43964389
<li> Otherwise, <a href="#absolutize-list"><i
43974390
title="absolutize a relative selector list">absolutize <var
43984391
title="">selector</var></i></a> with <var>refs</var> as the <a
4399-
href="#reference-element-set"><i>reference element set</i></a>.
4392+
href="#scope-elements"><i>:scope elements</i></a>.
44004393

44014394
<li> Return <var title="">selector</var>.
44024395
</ol>
@@ -4412,17 +4405,17 @@ <h3 id=match-a-selector><span class=secno>17.3. </span> Match A Selector</h3>
44124405
root</i></a> and <a href="#scoping-methods"><i>scoping method</i></a> (<a
44134406
href="#scope-contained"><i>scope-contained</i></a> or <a
44144407
href="#scope-filtered"><i>scope-filtered</i></a>) may be provided.
4415-
Optionally, an explicit <a href="#reference-element-set"><i>reference
4416-
element set</i></a> <var>element set</var> (which may be empty) may be
4408+
Optionally, an explicit <a href="#scope-elements"><i>:scope
4409+
elements</i></a> <var>element set</var> (which may be empty) may be
44174410
provided. It returns a list of zero or more elements.
44184411

44194412
<p> <a href="#evaluate-a-selector"><i>Evaluate a selector</i></a> <var
44204413
title="">selector</var> against <var>nodes</var> with the <a
44214414
href="#scoping-root"><i>scoping root</i></a>, <a
44224415
href="#scoping-methods"><i>scoping method</i></a>, and <a
4423-
href="#reference-element-set"><i>reference element set</i></a> if they
4424-
were provided, and return the elements that match the selector. Return the
4425-
nodes matched by the selector.
4416+
href="#scope-elements"><i>:scope elements</i></a> if they were provided,
4417+
and return the elements that match the selector. Return the nodes matched
4418+
by the selector.
44264419

44274420
<h2 id=changes><span class=secno>18. </span> Changes</h2>
44284421

‎selectors/Overview.src.html‎

Lines changed: 38 additions & 46 deletions
Original file line numberDiff line numberDiff line change
@@ -814,9 +814,9 @@ <h3 id="scoping">
814814
define <i>scope-contained</i> selectors.
815815
</div>
816816

817-
<p>Unless otherwise specified,
818-
the <i>scoping root</i> also forms the <i>reference element set</i>
819-
and matches the <code>:scope</code> pseudo-class.
817+
<p class='note'>
818+
Note that if there are no <i>:scope elements</i> when a selector is evaluated,
819+
the <i>scoping root</i> acts like a <i>:scope element</i>.
820820

821821
<h3 id="relative">
822822
Relative Selectors</h3>
@@ -844,52 +844,50 @@ <h4 id='absolutizing'>
844844
To <dfn id='absolutize'>absolutize a relative selector</dfn>:
845845

846846
<p>
847-
If the <i>reference element set</i> is empty or consists of one or more elements:
847+
If there are no <i>:scope elements</i>
848+
and the selector is <i>scoped</i> to a <i>virtual scoping root</i>:
848849

849850
<ol>
850851
<li>
851-
If the selector starts with a <i>combinator</i> other than the <i>descendant combinator</i>,
852-
prepend <code>:scope</code> as the initial <i>compound selector</i>.
852+
If the selector starts with a <i>child combinator</i>,
853+
remove the child combinator.
854+
The selector is now absolute,
855+
with the additional constraint that the first compound selector in the selector
856+
only matches elements without a parent.
853857

854858
<li>
855-
Otherwise, if the selector does not contain any instance of the <code>:scope</code> pseudo-class
856-
(either at the top-level or as an argument to a functional pseudo-class),
857-
prepend <code>:scope</code> followed by the <i>descendant combinator</i>.
859+
Otherwise, if the selector starts with any combinator other than the <i>descendant combinator</i>,
860+
change the selector to '':not(*)''.
861+
<span class='note'>This is the shortest selector that is valid, but guaranteed to match nothing.</span>
858862

859863
<li>
860864
Otherwise, the selector is already absolute.
861865
</ol>
862866

863-
<p class='issue'>
864-
The above algorithm is different from Selectors API: its step 2, which bailed if the reference element set was empty, has been removed.
865-
This is because handling an explicitly empty list should return nothing;
866-
if a reference element set was not given at all,
867-
Selectors API 2 should be amended to say that the selector must be absolute already.
868-
(Broken example: doing <code>document.find('img', [list-of-links]))</code> finds images that are descendants of links normally,
869-
but instead finds all images in the document if the list-of-links is empty.)
870-
871867
<p>
872-
Otherwise, if the <i>reference element set</i> consists of only a <i>virtual scoping root</i>:
868+
Otherwise:
873869

874870
<ol>
875871
<li>
876-
If the selector starts with a <i>child combinator</i>,
877-
remove the child combinator.
878-
The selector is now absolute,
879-
with the additional constraint that the first compound selector in the selector
880-
only matches elements without a parent.
872+
If the selector starts with a <i>combinator</i> other than the <i>descendant combinator</i>,
873+
prepend <code>:scope</code> as the initial <i>compound selector</i>.
881874

882875
<li>
883-
Otherwise, if the selector starts with any combinator other than the <i>descendant combinator</i>,
884-
change the selector to '':not(*)''.
885-
<span class='note'>This is the shortest selector that is valid, but guaranteed to match nothing.</span>
876+
Otherwise, if the selector does not contain any instance of the <code>:scope</code> pseudo-class
877+
(either at the top-level or as an argument to a functional pseudo-class),
878+
prepend <code>:scope</code> followed by the <i>descendant combinator</i>.
886879

887880
<li>
888881
Otherwise, the selector is already absolute.
889882
</ol>
890883

891-
<p>
892-
Otherwise, this is a spec error. Please report it to the relevant standards body.
884+
<p class='issue'>
885+
The above algorithm is different from Selectors API: its step 2, which bailed if there were no :scope elements, has been removed.
886+
This is because handling an explicitly empty list should return nothing;
887+
if no :scope elements were given at all,
888+
Selectors API 2 should be amended to say that the selector must be absolute already.
889+
(Broken example: doing <code>document.find('img', [list-of-links]))</code> finds images that are descendants of links normally,
890+
but instead finds all images in the document if the list-of-links is empty.)
893891

894892
<p>
895893
To <dfn id='absolutize-list'>absolutize a relative selector list</dfn>,
@@ -2018,25 +2016,22 @@ <h3 id="the-scope-pseudo">
20182016
The reference element pseudo-class <code>:scope</code></h3>
20192017

20202018
<p>
2021-
The <dfn id='scope-pseudo'>:scope</dfn> pseudo-class represents any element that is in
2022-
the <dfn>reference element set</dfn>.
2019+
In some contexts, selectors can be matched with an explicit set of <dfn data-export title=":scope element">:scope elements</dfn>.
20232020
This is is a (potentially empty) set of elements
20242021
that provide a reference point for selectors to match against,
20252022
such as that specified by the <code>querySelector()</code> call in [[SELECTORS-API2]],
20262023
or the parent element of a <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/semantics.html#the-style-element">scoped <code>&lt;style></code> element</a> in [[HTML5]].
20272024

20282025
<p>
2029-
If the <i>reference element set</i> is not explicitly specified,
2030-
it defaults to representing the <i>scoping root</i> (if any),
2031-
else represents the root of the document (i.e. matches <code>:root</code>).
2026+
The <dfn id='scope-pseudo'>:scope</dfn> pseudo-class represents any element that is a <i>:scope element</i>.
2027+
If the <i>:scope elements</i> are not explicitly specified,
2028+
but the selector is <i>scoped</i> and the <i>scoping root</i> is an element,
2029+
then '':scope'' represents the <i>scoping root</i>;
2030+
otherwise, it represents the root of the document
2031+
(equivalent to '':root'').
20322032
Specifications intending for this pseudo-class to match specific elements
20332033
rather than the document's root element
2034-
must define either a <i>scoping root</i> (if using <i>scoped selectors</i>) or an explicit <i>reference element set</i>.
2035-
2036-
<p class="note">
2037-
Note that since this pseudo-class only represents elements,
2038-
a virtual <i>scoping root</i> cannot be the subject of a selector;
2039-
such a selector effectively represents nothing.
2034+
must define either a <i>scoping root</i> (if using <i>scoped selectors</i>) or an explicit set of <i>:scope elements</i>.
20402035

20412036
<h2 id="useraction-pseudos">
20422037
User Action Pseudo-classes</h2>
@@ -3194,10 +3189,7 @@ <h3 id='parse-a-relative-selector'>
31943189

31953190
<p>
31963191
This section defines how to <dfn>parse a relative selector</dfn> from a string <var>source</var>,
3197-
against a <i>reference element set</i> <var>refs</var>.
3198-
The reference element set must contain zero or more elements,
3199-
or a single virtual scoping root,
3200-
such as a <code>Document</code> or <code>Document Fragment</code>.
3192+
against <i>:scope elements</i> <var>refs</var>.
32013193
It returns either a complex selector list,
32023194
or failure.
32033195

@@ -3216,7 +3208,7 @@ <h3 id='parse-a-relative-selector'>
32163208

32173209
<li>
32183210
Otherwise,
3219-
<i title="absolutize a relative selector list">absolutize <var title=''>selector</var></i> with <var>refs</var> as the <i>reference element set</i>.
3211+
<i title="absolutize a relative selector list">absolutize <var title=''>selector</var></i> with <var>refs</var> as the <i>:scope elements</i>.
32203212

32213213
<li>
32223214
Return <var title=''>selector</var>.
@@ -3230,14 +3222,14 @@ <h3 id='match-a-selector'>
32303222
Optionally, a tree of nodes <var>nodes</var> to be matched against may be provided;
32313223
if not, the default <i>initial selector match list</i> for selectors in the given context is used as <var>nodes</var>.
32323224
Optionally, a <i>scoping root</i> and <i>scoping method</i> (<i>scope-contained</i> or <i>scope-filtered</i>) may be provided.
3233-
Optionally, an explicit <i>reference element set</i> <var>element set</var> (which may be empty) may be provided.
3225+
Optionally, an explicit <i>:scope elements</i> <var>element set</var> (which may be empty) may be provided.
32343226
It returns a list of zero or more elements.
32353227

32363228
<p>
32373229
<i>Evaluate a selector</i> <var title=''>selector</var> against <var>nodes</var>
32383230
with the <i>scoping root</i>,
32393231
<i>scoping method</i>,
3240-
and <i>reference element set</i>
3232+
and <i>:scope elements</i>
32413233
if they were provided,
32423234
and return the elements that match the selector.
32433235
Return the nodes matched by the selector.

0 commit comments

Comments
 (0)