[selectors-4] Rename :matches() to :is() per WG resolution. #3258

selectors-4/Overview.bs

@@ -133,7 +133,7 @@ Selectors Overview</h2>
 				<td>[[#negation]]
 				<td>3/4
 			<tr>
-				<td><code>E:matches(<var>s1</var>, <var>s2</var>, &hellip;)</code>
+				<td><code>E:is(<var>s1</var>, <var>s2</var>, &hellip;)</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]]
@@ -913,7 +913,7 @@ Pseudo-classing Pseudo-elements</h4>
 	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 above-mentioned pseudos.
+	Issue: Clarify that '':not()'' and '':is()'' can be used when containing above-mentioned pseudos.
 
 	<div class="example">
 		For example, since the '':hover'' pseudo-class specifies
@@ -1108,31 +1108,31 @@ Selector Lists</h3>
 	</div>
 
 <h3 id="matches">
-The Matches-any Pseudo-class: '':matches()''</h3>
+The Matches-Any Pseudo-class: '':is()''</h3>
 
-	The matches-any pseudo-class, <dfn id='matches-pseudo'>:matches()</dfn>,
+	The matches-any pseudo-class, <dfn id='matches-pseudo'>:is()</dfn>,
 	is a functional pseudo-class taking a <a>selector list</a> as its argument.
 	It represents an element that is represented by its argument.
 
-	Note: The specificity of the '':matches()'' pseudo-class
+	Note: The specificity of the '':is()'' pseudo-class
 	is replaced by the specificity of its most specific argument.
-	Thus, a selector written with '':matches()''
+	Thus, a selector written with '':is()''
 	does not necessarily have equivalent specificity
-	to the equivalent selector written without '':matches()''
+	to the equivalent selector written without '':is()''
 	For example, if we have
-	'':matches(ul, ol, .list) > [hidden]'' and ''ul > [hidden], ol > [hidden], .list > [hidden]''
+	'':is(ul, ol, .list) > [hidden]'' and ''ul > [hidden], ol > [hidden], .list > [hidden]''
 	a ''[hidden]]'' child of an <{ol}> matches the first selector
 	with a specificity of (0,2,0)
 	whereas it matches the second selector
 	with a specificity of (0,1,1).
 	See [[#specificity-rules]].
 
 	Pseudo-elements cannot be represented by the matches-any pseudo-class;
-	they are not valid within '':matches()''.
+	they are not valid within '':is()''.
 
 	Default namespace declarations do not affect the <a>compound selector</a>
 	representing the <a>subject</a> of any selector
-	within a '':matches()'' pseudo-class,
+	within a '':is()'' pseudo-class,
 	unless that compound selector contains
 	an explicit <a>universal selector</a> or <a>type selector</a>.
 
@@ -1142,18 +1142,23 @@ The Matches-any Pseudo-class: '':matches()''</h3>
 		is not limited to only matching elements in the default namespace
 		that are being hovered or focused.
 
-		<pre>*|*:matches(:hover, :focus) </pre>
+		<pre>*|*:is(:hover, :focus) </pre>
 
 		The following selector, however, represents only hovered or focused
 		elements that are in the default namespace, because it uses an explicit
-		universal selector within the '':matches()'' notation:
+		universal selector within the '':is()'' notation:
 
-		<pre>*|*:matches(*:hover, *:focus) </pre>
+		<pre>*|*:is(*:hover, *:focus) </pre>
 	</div>
 
+	As previous drafts of this specification
+	used the name <dfn>:matches()</dfn> for this pseudo-class,
+	UAs may additionally implement this obsolete name
+	as an alias for '':is()''
+	if needed for backwards-compatibility.
 
 <h3 id="negation">
-The Negation Pseudo-class: '':not()''</h3>
+The Negation (Matches-None) Pseudo-class: '':not()''</h3>
 
 	The negation pseudo-class, <dfn id='negation-pseudo'>:not()</dfn>,
 	is a functional pseudo-class taking a <a>selector list</a> as an argument.
@@ -1164,7 +1169,7 @@ The Negation Pseudo-class: '':not()''</h3>
 
 	Note: The specificity of the '':not()'' pseudo-class
 	is replaced by the specificity of the most specific selector in its argument;
-	thus it has the exact behavior of '':not(:matches(<var>argument</var>))''.
+	thus it has the exact behavior of '':not(:is(<var>argument</var>))''.
 	See [[#specificity-rules]].
 
 	Pseudo-elements cannot be represented by the negation pseudo-class;
@@ -1186,13 +1191,13 @@ The Negation Pseudo-class: '':not()''</h3>
 		<pre>html|*:not(:link):not(:visited)</pre>
 	</div>
 
-	As with '':matches()'',
+	As with '':is()'',
 	default namespace declarations do not affect the <a>compound selector</a>
 	representing the <a>subject</a> of any selector
 	within a '':not()'' pseudo-class,
 	unless that compound selector contains
 	an explicit <a>universal selector</a> or <a>type selector</a>.
-	(See '':matches()'' for examples.)
+	(See '':is()'' for examples.)
 
 	Note: The '':not()'' pseudo-class allows useless selectors to be written.
 	For instance '':not(*|*)'', which represents no element at all,
@@ -1204,8 +1209,8 @@ The Specificity-adjustment Pseudo-class: '':where()''</h3>
 
 	The Specificity-adjustment pseudo-class, <dfn id="where-pseudo">:where()</dfn>,
 	is a functional pseudo-class
-	with the same syntax and functionality as '':matches()''.
-	Unlike '':matches()'', neither the '':where'' pseudo-class, nor any of its arguments
+	with the same syntax and functionality as '':is()''.
+	Unlike '':is()'', neither the '':where'' pseudo-class, nor any of its arguments
 	contribute to the specificity of the selector--
 	its specificity is always zero.
 
@@ -1982,7 +1987,7 @@ The Hyperlink Pseudo-class: '':any-link''</h3>
 	For example, in [[HTML5]], any <a element>a</a>, <a element>area</a>, or <a element>link</a> elements with an <code>href</code> attribute
 	are hyperlinks, and thus match <code>:any-link</code>.
 	It matches an element if the element would match either '':link'' or '':visited'',
-	and is equivalent to '':matches(:link, :visited)''.
+	and is equivalent to '':is(:link, :visited)''.
 
 
 <h3 id="link">
@@ -2407,7 +2412,7 @@ The Current-element Pseudo-class: '':current''</h3>
 	The <dfn id='current-pseudo'>:current</dfn> pseudo-class represents the
 	element, or an ancestor of the element, that is currently being displayed.
 
-	Its alternate form <dfn>:current()</dfn>, like '':matches()'',
+	Its alternate form <dfn>:current()</dfn>, like '':is()'',
 	takes a list of <a>compound selectors</a> as its argument: it represents the
 	'':current'' element that matches the argument or, if that does
 	not match, the innermost ancestor of the '':current'' element
@@ -3314,7 +3319,7 @@ Calculating a selector's specificity</h2>
 
 	<ul>
 		<li>
-			The specificity of a '':matches'', '':not()'', or '':has()'' pseudo-class
+			The specificity of a '':is'', '':not()'', or '':has()'' pseudo-class
 			is replaced by the specificity of
 			the most specific complex selector in its selector list argument.
 		<li>
@@ -3330,7 +3335,7 @@ Calculating a selector's specificity</h2>
 		For example:
 		<ul>
 			<li>
-				'':matches(em, #foo)'' has
+				'':is(em, #foo)'' has
 				a specificity of (1,0,0)--
 				like an ID selector--
 				when matched against any of
@@ -3379,7 +3384,7 @@ Calculating a selector's specificity</h2>
 		LI.red.level    /* a=0 b=2 c=1 */
 		#x34y           /* a=1 b=0 c=0 */
 		#s12:not(FOO)   /* a=1 b=0 c=1 */
-		.foo :matches(.bar, #baz)
+		.foo :is(.bar, #baz)
 		                /* a=1 b=1 c=0 */
 		</pre>
 	</div>
@@ -3792,7 +3797,7 @@ Appendix A: Guidance on Mapping Source Documents &amp; Data to an Element Tree</
 			that must be explicitly defined.
 
 			Issue: Some pseudo-classes are *syntactical*,
-			like '':has()'' and '':matches()'',
+			like '':has()'' and '':is()'',
 			and thus should always work.
 			Need to indicate that somewhere.
 			Probably the structural pseudos always work
@@ -3914,9 +3919,11 @@ Changes</h2>
 	<ul>
 		<li>Named the zero-specificity selector to '':where()''.
 		(<a href="https://github.com/w3c/csswg-drafts/issues/2143">Issue 2143</a>)
+		<li>Renamed '':matches()'' to '':is()''.
+		(<a href="https://github.com/w3c/csswg-drafts/issues/3258">Issue 3258</a>)
 		<li>Removed '':blank'' and defined '':empty'' to ignored white-space&ndash;only nodes.
 		(<a href="https://github.com/w3c/csswg-drafts/issues/1967">Issue 1967</a>)
-		<li>Changed the specificity of '':matches()'', '':where()'', and '':nth-child()''
+		<li>Changed the specificity of '':is()'', '':where()'', and '':nth-child()''
 		to not depend on which selector argument matched.
 		(<a href="https://github.com/w3c/csswg-drafts/issues/1027">Issue 1027</a>)
 	</ul>