[css-extensions] Start upgrading custom selectors based on ML feedback.

Author: tabatkins

css-extensions/Overview.bs

@@ -42,11 +42,34 @@ Extension Names</h2>
 	without ever having to worry about colliding with CSS-defined names.
 
 <h2 id='custom-selectors'>
-Custom Selectors</h2>
+<dfn lt="custom selector">Custom Selectors</dfn></h2>
 
-	A <dfn>custom selector</dfn> is defined with the ''@custom-selector'' rule:
+	A <dfn>declarative custom selector</dfn> is defined with the ''@custom-selector'' rule:
 
-	<pre class='prod'><dfn>@custom-selector</dfn> = @custom-selector <<extension-name>> <<selector>> ;</pre>
+	<pre class='prod'>
+	<dfn>@custom-selector</dfn> = @custom-selector <<custom-selector>> <<selector>> ;
+	<dfn>&lt;custom-selector></dfn> = <<custom-arg>>? : <<extension-name>> [ ( <<custom-arg>>+#? ) ]? ;
+	<dfn>&lt;custom-arg></dfn> = $ <<ident-token>> ;
+	</pre>
+
+	Where there must be no whitespace
+	between <code>:</code> and <<extension-name>>
+	or between <code>$</code> and <<ident-token>>
+	in the above definitions.
+
+	<div class='issue'>
+		<pre>
+		// Arguments are specified with $foo.
+		// An arg before the pseudo-class captures the rest of the compound selector.
+		@custom-selector $rest:--n-siblings($n, $sel) {
+			specificity: $sel;
+			// assumes $sel is a selector, parses it and uses its specificity
+			// otherwise, specificity is [0,1,0]
+			expansion: $rest:nth-child(1 of $sel):nth-last-child($n of $sel),
+				:nth-child(1 of $sel):nth-last-child($n of $sel) ~ $rest;
+		}
+		</pre>
+	</div>
 
 	This defines a <a>custom selector</a> which is written as a <a spec=selectors>pseudo-class</a> with the given <<extension-name>>,
 	and represents a '':matches()'' selector using the provided <<selector>> as its argument.