[css-nesting] Retire @nest, introduce the 'nested declarations rule'

Resolves w3c#10234.

Author: andruud

css-nesting-1/Overview.bs

@@ -636,7 +636,7 @@ Nesting Other At-Rules {#conditionals}
 		with their [=nesting selector=] taking its definition
 		from the nearest ancestor [=style rule=].
 	* Properties can be directly used,
-		acting as if they were nested in an ''@nest'' rule.
+		acting as if they were nested in a [=nested declarations rule=].
 
 	<div class=note>
 		Specifically, these rules are capable of being [=nested group rules=]:
@@ -667,11 +667,10 @@ Nesting Other At-Rules {#conditionals}
 		/* equivalent to: */
 		.foo {
 			display: grid;
-
-			@media (orientation: landscape) {
-				@nest {
-					grid-auto-flow: column;
-				}
+		}
+		@media (orientation: landscape) {
+			.foo {
+				grid-auto-flow: column
 			}
 		}
 
@@ -754,46 +753,9 @@ Nesting Other At-Rules {#conditionals}
 	</div>
 
 	Runs of consecutive directly-nested properties
-	are automatically wrapped in ''@nest'' rules.
+	are automatically wrapped in [=nested declarations rules=].
 	(This is observable in the CSSOM.)
 
-	<div class=example>
-
-		For example, the earlier example:
-
-		<pre highlight=css>
-		.foo {
-			display: grid;
-
-			@media (orientation: landscape) {
-				grid-auto-flow: column;
-			}
-		}
-		/* equivalent to */
-		.foo {
-			display: grid;
-
-			@media (orientation: landscape) {
-				@nest {
-					grid-auto-flow: column;
-				}
-			}
-		}
-		</pre>
-
-		is in fact <em>exactly</em> equivalent,
-		producing the exact same CSSOM structure.
-		The {{CSSMediaRule}} object
-		will have a single {{CSSNestRule}} object
-		in its <code highlight=js>.childRules</code> attribute,
-		containing the 'grid-auto-flow' property.
-	</div>
-
-	Note: This does mean that the serialization of such rules will differ
-	from how they were originally written,
-	with <em>no</em> directly-nested properties in the serialization.
-
-
 <h4 id=nesting-at-scope>
 Nested ''@scope'' Rules</h4>
 
@@ -852,7 +814,7 @@ Mixing Nesting Rules and Declarations {#mixing}
 	and [=nested style rules=] or [=nested group rules=],
 	all three can be arbitrarily mixed.
 	Declarations coming after or between rules
-	are implicitly wrapped in ''@nest'' rules,
+	are implicitly wrapped in [=nested declarations rules=],
 	to preserve their order relative to the other rules.
 
 	<div class=example>
@@ -867,18 +829,14 @@ Mixing Nesting Rules and Declarations {#mixing}
 		}
 
 		/* equivalent to */
-		article {
-			color: green;
-			& { color: blue; }
-			@nest { color: red; }
-		}
+		article { color: green; }
+		:is(article) { color: blue; }
+		article { color: red; }
 
 		/* NOT equivalent to */
-		article {
-			color: green;
-			color: red;
-			& { color: blue; }
-		}
+		article { color: green; }
+		article { color: red; }
+		:is(article) { color: blue; }
 		</pre>
 	</div>
 
@@ -917,7 +875,7 @@ Mixing Nesting Rules and Declarations {#mixing}
 
 	Note: While one <em>can</em> freely intermix declarations and nested rules,
 	it's harder to read and somewhat confusing to do so,
-	since the later properties are automatically wrapped in an ''@nest'' rule
+	since the later properties are automatically wrapped in a [=nested declarations rule=]
 	that doesn't appear in the source text.
 	For readability's sake,
 	it's recommended that authors put all their properties first in a style rule,
@@ -1139,19 +1097,19 @@ Nesting Selector: the ''&'' selector {#nest-selector}
 	(that is, ''&div'' is illegal, and must be written ''div&'' instead).
 
 
-<!-- Big Text: @nest
+<!-- Big Text: Nested Decl
 
- ████▌  █    █▌ █████▌  ███▌  █████▌
-█▌   █▌ █▌   █▌ █▌     █▌  █▌   █▌
-█▌▐█ █▌ ██▌  █▌ █▌     █▌       █▌
-█▌▐█ █▌ █▌▐█ █▌ ████    ███▌    █▌
-█▌ ██▌  █▌  ██▌ █▌         █▌   █▌
-█▌      █▌   █▌ █▌     █▌  █▌   █▌
- ████▌  █▌   ▐▌ █████▌  ███▌    █▌
+█    █▌ █████▌  ███▌  █████▌ █████▌ ████▌      ████▌  █████▌  ███▌  █▌
+█▌   █▌ █▌     █▌  █▌   █▌   █▌     █▌  █▌     █▌  █▌ █▌     █▌  █▌ █▌
+██▌  █▌ █▌     █▌       █▌   █▌     █▌  █▌     █▌  █▌ █▌     █▌     █▌
+█▌▐█ █▌ ████    ███▌    █▌   ████   █▌  █▌     █▌  █▌ ████   █▌     █▌
+█▌  ██▌ █▌         █▌   █▌   █▌     █▌  █▌     █▌  █▌ █▌     █▌     █▌
+█▌   █▌ █▌     █▌  █▌   █▌   █▌     █▌  █▌     █▌  █▌ █▌     █▌  █▌ █▌
+█▌   ▐▌ █████▌  ███▌    █▌   █████▌ ████▌      ████▌  █████▌  ███▌  █████
 -->
 
-<h2 id=nest-rule>
-The ''@nest'' Rule</h2>
+<h2 id=nested-declarations-rule>
+The Nested Declarations Rule</h2>
 
 	For somewhat-technical reasons,
 	it's important to be able to distinguish properties
@@ -1205,34 +1163,21 @@ The ''@nest'' Rule</h2>
 	These run into the same problems as above.
 
 	To address all of these issue,
-	the <dfn at-rule>@nest</dfn> rule is defined:
-
-	<pre class=prod>
-	&lt;@nest> = @nest { <<block-contents>> }
-	</pre>
+	we instead wrap runs of consecutive directly-nested properties
+	in a <dfn export>nested declarations rule</dfn>.
 
 	Unless otherwise specified,
-	an ''@nest'' rule is a [=nested style rule=],
+	a [=nested declarations rule=] is a [=nested style rule=],
 	and acts identically to any other style rule.
 	It matches the exact same elements and pseudo-elements
 	as its parent style rule,
 	with the same specificity behavior.
 	<span class=note>(This is <em>similar to</em> being a style rule with an ''&'' selector,
 	but slightly more powerful,
 	as explained above.)</span>
-	If it does not have a parent style rule,
-	it matches elements as if it were a [=style rule=] with a '':scope'' selector.
-
-	Note: While it is <em>possible</em> to manually specify an ''@nest'' rule in a stylesheet,
-	there's never any reason to.
-	The parser automatically produces them when needed.
-
-	Issue: It's possible that we might make changes to further hide the existence of ''@nest'',
-	such as serializing as just its declarations when possible.
-	See <a href="https://github.com/w3c/csswg-drafts/issues/8738#issuecomment-2061777236">Issue 8738</a>.
 
 	<details class=note>
-		<summary>Why does the ''@nest'' rule exist?</summary>
+		<summary>Why does the [=nested declarations rule=] exist?</summary>
 
 		Originally, this specification grouped all declarations in style rules together,
 		"moving" them from their original location
@@ -1241,15 +1186,15 @@ The ''@nest'' Rule</h2>
 		in plain style rules,
 		using the ''&'' selector.
 
-		There are two major reasons we switched to instead use the ''@nest'' rule.
+		There are two major reasons we switched to instead use the [=nested declarations rule=].
 
 		First, using an ''& {...}'' rule to implicitly wrap declarations in a [=nested group rule=]
 		also changed the behavior.
 		As shown in the example following this note,
 		it breaks cases where the parent style rule contains pseudo-elements,
 		and even when that's not the case,
 		it potentially changes the specificity behavior of the nested declarations.
-		Switching to ''@nest'' avoids these problems,
+		Switching to the [=nested declarations rule=] avoids these problems,
 		making the behavior of nested ''@media''/etc
 		identical to the behavior of *non*-nested ''@media''/etc.
 
@@ -1262,7 +1207,7 @@ The ''@nest'' Rule</h2>
 		and in order to actually make that representable in the CSSOM,
 		that means they have to be wrapped in some kind of rule.
 		The same issues as the previous paragraph apply if we just use a normal ''& {...}'' rule,
-		so ''@nest'' lets us do so without side effects.
+		so the [=nested declarations rule=] lets us do so without side effects.
 	</details>
 
 	<div class=example>
@@ -1295,14 +1240,14 @@ The ''@nest'' Rule</h2>
 		}
 		```
 
-		Then the ''color: white'' is implicitly wrapped in an ''@nest'',
+		Then the ''color: white'' is implicitly wrapped in a [=nested declarations rule=],
 		which is guaranteed to match <em>exactly</em> the same as its parent style rule,
 		so the element <em>and</em> its pseudo-elements
 		would all have white text in a darkmode page.
 	</div>
 
 	<div class=example>
-		Declarations interleaved with rules get implicitly wrapped in an ''@nest'',
+		Declarations interleaved with rules get implicitly wrapped in a [=nested declarations rule=],
 		which makes them part of a separate style rule.
 		For example, given this CSS:
 
@@ -1320,7 +1265,7 @@ The ''@nest'' Rule</h2>
 		the ''color: black'' one.
 
 		The ''background: silver'' declaration
-		will instead be found in the implicitly-created ''@nest'' child rule,
+		will instead be found in the implicitly-created [=nested declarations rule|nested declarations child rule=],
 		at <code highlight=js>fooRule.cssRules[1].style</code>.
 	</div>
 
@@ -1354,20 +1299,20 @@ with the implied [=nesting selector=] inserted.
 	will serialize as ''& > .foo''.
 </div>
 
-The {{CSSNestRule}} Interface {#the-cssnestrule}
+The {{CSSNestedDeclarations}} Interface {#the-cssnestrule}
 -----------------------------
 
-The {{CSSNestRule}} interface represents an ''@nest'' rule.
+The {{CSSNestedDeclarations}} interface represents a [=nested declarations rule=].
 
 <xmp class=idl>
 [Exposed=Window]
-interface CSSNestRule : CSSGroupingRule {
+interface CSSNestedDeclarations : CSSRule {
 	[SameObject, PutForwards=cssText] readonly attribute CSSStyleProperties style;
 };
 </xmp>
 
 <div algorithm>
-	The <dfn attribute for=CSSNestRule>style</dfn> attribute
+	The <dfn attribute for=CSSNestedDeclarations>style</dfn> attribute
 	must return a {{CSSStyleProperties}} object for the rule,
 	with the following properties:
 
@@ -1383,35 +1328,13 @@ interface CSSNestRule : CSSGroupingRule {
 	:: Null
 </div>
 
-<div class=example>
-	Note that interleaved declarations,
-	or all declarations in [=nested group rules=],
-	will be implicitly wrapped in ''@nest'' rules,
-	which will affect the serialization.
-	A [=nested group rule=] like:
-
-	<pre class=lang-css>
-	.foo {
-		@media (prefers-color-scheme: dark) {
-			color: white;
-			background: black;
-		}
-	}
-	</pre>
+The {{CSSNestedDeclarations}} rule [=serialize a CSS rule|serializes=]
+as if its [=CSS declaration block|declaration block=]
+had been [=serialize a CSS declaration block|serialized=] directly.
 
-	will serialize as:
-
-	<pre class=lang-css>
-	.foo {
-		@media (prefers-color-scheme: dark) {
-			@nest {
-				color: white;
-				background: black;
-			}
-		}
-	}
-	</pre>
-</div>
+Note: This means that multiple adjacent [=nested declarations rules=]
+(which is possible to create with e.g. {{CSSGroupingRule/insertRule}})
+will collapse into a single rule when serialized and parsed again.
 
 
 <!-- Big Text: changes -->
@@ -1439,6 +1362,9 @@ Significant changes since the
 	(<a href="https://github.com/w3c/csswg-drafts/issues/9069">Issue 9069</a>)
 
 * Declarations intermixed with rules (or all declarations in nested group rules)
-	are now automatically wrapped in ''@nest'' rules.
-	(Also the ''@nest'' rule was added.)
-	(<a href="https://github.com/w3c/csswg-drafts/issues/8738">Issue 8738</a>)
+	are now automatically wrapped in <code>@nest</code> rules.
+	(Also the <code>@nest</code> rule was added.)
+	(<a href="https://github.com/w3c/csswg-drafts/issues/8738">Issue 8738</a>)
+
+* Replaced <code>@nest</code> with [=nested declarations rules=].
+	(<a href="https://github.com/w3c/csswg-drafts/issues/10234">Issue 10234</a>)

css-syntax-3/Overview.bs

@@ -2629,7 +2629,7 @@ Consume an at-rule</h4>
 			Note: If the result contains [=lists=] of [=declarations=],
 			how they're materialized in the CSSOM
 			depends on the rule.
-			Some turn them all into ''@nest'' rules,
+			Some turn them all into [=nested declarations rules=],
 			others will treat them all as declarations,
 			and others will treat the first item differently from the rest.
 
@@ -2758,7 +2758,7 @@ Consume a qualified rule</h4>
 			remove it from |child rules|
 			and assign it to |rule|'s declarations.
 			If any remaining items of |child rules| are [=lists=] of [=declarations=],
-			replace them with ''@nest'' [=at-rules=]
+			replace them with [=nested declarations rules=]
 			containing the [=list=] as its sole child.
 			Assign |child rules| to |rule|'s child [=rules=].
 
@@ -2802,7 +2802,7 @@ Consume a block's contents</h4>
 	a [=list=] of [=declarations=]
 	might be materialized in the CSSOM as either
 	a {{CSSStyleDeclaration}},
-	or as a {{CSSNestRule}}.
+	or as a {{CSSNestedDeclarations}} rule.
 
 	Let |rules| be an empty [=list=],
 	containing either [=rules=]

cssom-1/Overview.bs

@@ -1845,13 +1845,24 @@ To <dfn export>serialize a CSS rule</dfn>, perform one of the following in accor
 
 Issue: The "indented by two spaces" bit matches browsers, but needs work, see <a href="https://github.com/w3c/csswg-drafts/issues/5494">#5494</a>
 
-To <dfn export>insert a CSS rule</dfn> <var>rule</var> in a CSS rule list <var>list</var> at index <var>index</var>, follow these steps:
+To <dfn export>insert a CSS rule</dfn> <var>rule</var> in a CSS rule list <var>list</var> at index <var>index</var>,
+with a flag <var>nested</var>,
+follow these steps:
 <ol>
  <li>Set <var>length</var> to the number of items in <var>list</var>.
  <li>If <var>index</var> is greater than <var>length</var>, then <a>throw</a>
  an {{IndexSizeError}} exception.
  <li>Set <var>new rule</var> to the results of performing <a>parse a CSS rule</a>
  on argument <var>rule</var>.
+ <li>If <var>new rule</var> is a syntax error, and <var>nested</var> is set,
+ perform the following substeps:
+  <ul>
+   <li> Set <var>declarations</var> to the results of performing <a>parse a CSS declaration block</a>,
+   on argument <var>rule</var>.
+   <li> If <var>declarations</var> is a syntax error, <a>throw</a> a {{SyntaxError}} exception.
+   <li> Otherwise, set <var>new rule</var> to a new [=nested declarations rule=]
+   with <var>declarations</var> as it contents.
+  </ul>
  <li>If <var>new rule</var> is a syntax error, <a>throw</a>
  a {{SyntaxError}} exception.
  <li>If <var>new rule</var> cannot be inserted into <var>list</var> at the zero-index position <var>index</var> due to constraints
@@ -2087,7 +2098,7 @@ The <dfn attribute for=CSSGroupingRule>cssRules</dfn> attribute must return a <c
 
 The <dfn method for=CSSGroupingRule>insertRule(<var>rule</var>, <var>index</var>)</dfn> method must return the result of
 invoking <a>insert a CSS rule</a> <var>rule</var> into the <a for=CSSRule>child CSS rules</a> at
-<var>index</var>.
+<var>index</var>, with the <var>nested</var> flag set.
 
 The <dfn method for=CSSGroupingRule>deleteRule(<var>index</var>)</dfn> method must <a>remove a CSS rule</a> from the
 <a for=CSSRule>child CSS rules</a> at <var>index</var>.