Overview.bs

<pre class='metadata'>
Title: CSS Nesting Module
Shortname: css-nesting
Level: 1
Status: ED
Work Status: Exploring
Group: CSSWG
ED: https://drafts.csswg.org/css-nesting/
Editor: Tab Atkins-Bittner, Google, http://xanthir.com/contact/, w3cid 42199
Editor: Adam Argyle, Google, https://nerdy.dev, w3cid 112669
Abstract: This module introduces the ability to nest one style rule inside another, with the selector of the child rule relative to the selector of the parent rule.  This increases the modularity and maintainability of CSS stylesheets.
</pre>

<pre class=link-defaults>
spec:css-color-4; type:property; text:color
spec:cssom-1; type:dfn;
	text:child css rules
	text:specified order
</pre>

<h2 id="intro">
Introduction</h2>

	<em>This section is not normative.</em>

	This module describes support for nesting a style rule within another style rule,
	allowing the inner rule's selector to reference the elements matched by the outer rule.
	This feature allows related styles to be aggregated into a single structure within the CSS document,
	improving readability and maintainability.

<h3 id="placement">
Module Interactions</h3>

	This module introduces new parser rules that extend the [[!CSS21]] parser model.
	This module introduces selectors that extend the [[SELECTORS4]] module.

<h3 id="values">
Values</h3>

	This specification does not define any new properties or values.

<h3 id="motivation">
Motivation</h3>

	The CSS for even moderately complicated web pages
	often include lots of duplication
	for the purpose of styling related content.
	For example, here is a portion of the CSS markup for one version of the [[CSS-COLOR-3]] module:

	<div class='example'>
		<pre class=lang-css>
			table.colortable td {
				text-align:center;
			}
			table.colortable td.c {
				text-transform:uppercase;
			}
			table.colortable td:first-child, table.colortable td:first-child+td {
				border:1px solid black;
			}
			table.colortable th {
				text-align:center;
				background:black;
				color:white;
			}
		</pre>
	</div>

	Nesting allows the grouping of related style rules, like this:

	<div class='example'>
		<pre class=lang-css>
			table.colortable {
				& td {
					text-align:center;
					&.c { text-transform:uppercase }
					&:first-child, &:first-child + td { border:1px solid black }
				}
				& th {
					text-align:center;
					background:black;
					color:white;
				}
			}
		</pre>
	</div>

	Besides removing duplication,
	the grouping of related rules improves the readability and maintainability of the resulting CSS.

Nesting Style Rules {#nesting}
==============================

	Style rules can be nested inside of other styles rules.
	These <dfn export lt="nested style rule|nesting style rule">nested style rules</dfn>
	act exactly like ordinary style rules--
	associating properties with elements via selectors--
	but they "inherit" their parent rule's selector context,
	allowing them to further build on the parent's selector
	without having to repeat it,
	possibly multiple times.

	There are two closely-related syntaxes for creating [=nested style rules=]:

	* [=Direct nesting=], where the [=nested style rule=] is written normally inside the parent rule,
		but with the requirement that the [=nested style rule's=] selector
		is [=nest-prefixed=].
	* The ''@nest'' rule, which imposes less constraints on the [=nested style rule's=] selector.

	Aside from the slight difference in how they're written,
	both methods are exactly equivalent in functionality.

	<details class=note>
		<summary>Why can't everything be directly nested?</summary>

		Nesting style rules naively inside of other style rules is, unfortunately, ambiguous--
		the syntax of a selector overlaps with the syntax of a declaration,
		so an implementation requires unbounded lookahead
		to tell whether a given bit of text is a declaration or the start of a style rule.

		For example, if a parser starts by seeing ''color:hover ...'',
		it can't tell whether that's the 'color' property
		(being set to an invalid value...)
		or a selector for a <code>&lt;color></code> element.
		It can't even rely on looking for valid properties to tell the difference;
		this would cause parsing to depend on which properties the implementation supported,
		and could change over time.

		Requiring directly-nested style rules to use [=nest-prefixed=] selectors
		works around this problem--
		an ''&'' can <em>never</em> be part of a declaration,
		so the parser can immediately tell it's going to be parsing a selector,
		and thus a nested style rule.

		Some non-browser implementations of nested rules do not impose this requirement.
		It <em>is</em>, in most cases, <em>eventually</em> possible
		to tell properties and selectors apart,
		but doing so requires unbounded lookahead in the parser;
		that is, the parser might have to hold onto an unknown amount of content
		before it can tell which way it's supposed to be interpreting it.
		CSS to date requires only a small, known amount of lookahead in its parsing,
		which allows for more efficient parsing algorithms,
		so unbounded lookahead is generally considered unacceptable among browser implementations of CSS.
	</details>


<!--
████████  ████ ████████  ████████  ██████  ████████
██     ██  ██  ██     ██ ██       ██    ██    ██
██     ██  ██  ██     ██ ██       ██          ██
██     ██  ██  ████████  ██████   ██          ██
██     ██  ██  ██   ██   ██       ██          ██
██     ██  ██  ██    ██  ██       ██    ██    ██
████████  ████ ██     ██ ████████  ██████     ██
-->

Direct Nesting {#direct}
------------------------

	A style rule can be <dfn lt="direct nesting|directly nested">directly nested</dfn>
	within another style rule if its selector is <a>nest-prefixed</a>.

	To be <dfn>nest-prefixed</dfn>,
	a <a>nesting selector</a> must be the first <a>simple selector</a>
	in the first <a>compound selector</a>
	of the selector.
	If the selector is a list of selectors,
	every <a>complex selector</a> in the list must be <a>nest-prefixed</a>
	for the selector as a whole to be <a>nest-prefixed</a>.

	<div class="example">
		For example, the following nestings are valid:

		<pre class=lang-css>
		<b>/* & can be used on its own */</b>
		.foo {
			color: blue;
			& > .bar { color: red; }
		}
		/* equivalent to
			.foo { color: blue; }
			.foo > .bar { color: red; }
		*/


		<b>/* or in a compound selector,
		   refining the parent's selector */</b>
		.foo {
			color: blue;
			&.bar { color: red; }
		}
		/* equivalent to
			.foo { color: blue; }
			.foo.bar { color: red; }
		*/

		<b>/* multiple selectors in the list must all
		   start with & */</b>
		.foo, .bar {
			color: blue;
			& + .baz, &.qux { color: red; }
		}
		/* equivalent to
			.foo, .bar { color: blue; }
			:is(.foo, .bar) + .baz,
			:is(.foo, .bar).qux { color: red; }
		*/

		<b>/* & can be used multiple times in a single selector */</b>
		.foo {
			color: blue;
			& .bar & .baz & .qux { color: red; }
		}
		/* equivalent to
			.foo { color: blue; }
			.foo .bar .foo .baz .foo .qux { color: red; }
		*/

		<b>/* Somewhat silly, but can be used all on its own, as well. */</b>
		.foo {
			color: blue;
			& { padding: 2ch; }
		}
		/* equivalent to
			.foo { color: blue; }
			.foo { padding: 2ch; }

			// or

			.foo {
				color: blue;
				padding: 2ch;
			}
		*/

		<b>/* Again, silly, but can even be doubled up. */</b>
		.foo {
			color: blue;
			&& { padding: 2ch; }
		}
		/* equivalent to
			.foo { color: blue; }
			.foo.foo { padding: 2ch; }
		*/

		<b>/* The parent selector can be arbitrarily complicated */</b>
		.error, #404 {
			&:hover > .baz { color: red; }
		}
		/* equivalent to
			:is(.error, #404):hover > .baz { color: red; }
		*/

		<b>/* As can the nested selector */</b>
		.foo {
			&:is(.bar, &.baz) { color: red; }
		}
		/* equivalent to
			.foo:is(.bar, .foo.baz) { color: red; }
		*/

		<b>/* Multiple levels of nesting "stack up" the selectors */</b>
		figure {
			margin: 0;

			& > figcaption {
				background: hsl(0 0% 0% / 50%);

				& > p {
					font-size: .9rem;
				}
			}
		}
		/* equivalent to
			figure { margin: 0; }
			figure > figcaption { background: hsl(0 0% 0% / 50%); }
			figure > figcaption > p { font-size: .9rem; }
		*/
		</pre>

		But these are not:

		<pre class=lang-css>
		<b>/* No & at all */</b>
		.foo {
			color: blue;
			.bar {
				color: red;
			}
		}

		<b>/* & isn't the first simple selector */</b>
		.foo {
			color: blue;
			.bar& {
				color: red;
			}
		}

		<b>/* & isn't the first selector of every one in the list */</b>
		.foo, .bar {
			color: blue;
			& + .baz, .qux { color: red; }
		}
		</pre>

		The last example here isn't technically ambiguous,
		since the selector as a whole does start with an ''&'',
		but it's an editing hazard--
		if the rule is refactored to remove the first selector
		or rearrange the selectors in the list,
		which normally would always remain valid,
		it would result in a now-ambiguous invalid selector.
	</div>

	<div class=note>
		Some CSS-generating tools will concatenate selectors like strings,
		allowing authors to build up a single simple selector
		across nesting levels.
		This is sometimes used by selector-organization methods
		like <a href="https://en.wikipedia.org/wiki/CSS#:~:text=bem%20(block%2C%20element%2C%20modifier)">BEM</a>
		to reduce repetition across a file,
		when the selectors themselves have significant repetition internally.

		For example, if one component uses the class ''.foo'',
		and a nested component uses ''.foo__bar'',
		you could write this in <a href="https://sass-lang.com/">Sass</a> as:

		<pre class="lang-css">
		.foo {
			color: blue;
			&__bar { color: red; }
		}
		/* In Sass, this is equivalent to
		   .foo { color: blue; }
		   .foo__bar { color: red; }
		*/
		</pre>

		Unfortunately, this method is inconsistent with selector syntax in general,
		and at best requires heuristics tuned to particularly selector-writing practices
		to recognize when the author wants it,
		versus the author attempting to add a type selector in the nested rule.
		''__bar'', for example,
		<em>is</em> a valid <a href="https://html.spec.whatwg.org/multipage/custom-elements.html">custom element name</a> in HTML.

		As such, CSS can't do this;
		the nested selector components are interpreted on their own,
		and not "concatenated":

		<pre class="lang-css">
		.foo {
			color: blue;
			&__bar { color: red; }
		}
		/* In CSS, this is instead equivalent to
		   .foo { color: blue; }
		   __bar.foo { color: red; }
		*/
		</pre>
	</div>


<!--
 ███████  ██    ██ ████████  ██████  ████████
██     ██ ███   ██ ██       ██    ██    ██
██ ███ ██ ████  ██ ██       ██          ██
██ ███ ██ ██ ██ ██ ██████    ██████     ██
██ █████  ██  ████ ██             ██    ██
██        ██   ███ ██       ██    ██    ██
 ███████  ██    ██ ████████  ██████     ██
-->

The Nesting At-Rule: ''@nest'' {#at-nest}
-----------------------------------------

	While <a>direct nesting</a> looks nice,
	it is somewhat fragile.
	Some valid nesting selectors,
	like ''.foo &'',
	are disallowed,
	and editing the selector in certain ways can make the rule invalid unexpectedly.
	As well,
	some authors find the nesting challenging to distinguish visually
	from the surrounding declarations.

	To aid in all these issues,
	this specification defines the ''@nest'' rule,
	which imposes fewer restrictions on how to validly nest style rules.
	Its syntax is:

	<pre class=prod>
		<dfn>@nest</dfn> = @nest <<selector-list>> { <<declaration-list>> }
	</pre>

	The ''@nest'' rule is only valid inside of a [=style rule=].
	If used in any other context
	(particularly, at the top-level of a stylesheet)
	the rule is invalid.

	The ''@nest'' rule functions identically to a [=nested style rule=]:
	it starts with a selector,
	and contains a block of declarations that apply to the elements the selector matches.
	That block is treated identically to a [=style rule's=] block,
	so anything valid in a [=style rule=]
	(such as additional ''@nest'' rules)
	is also valid here.

	The only difference between ''@nest'' and a [=directly nested=] [=style rule=]
	is that the selector used in a ''@nest'' rule
	is less constrained:
	it only must be <dfn>nest-containing</dfn>,
	which means it contains a [=nesting selector=] in it <em>somewhere</em>,
	rather than requiring it to be at the start of each selector.
	A list of selectors is <a>nest-containing</a> if all of its individual <a>complex selectors</a>
	are <a>nest-containing</a>.

	<div class="example">
		Anything you can do with [=direct nesting=],
		you can do with an ''@nest'' rule,
		so the following is valid:

		<pre class="lang-css">
		.foo {
			color: red;
			@nest & > .bar {
				color: blue;
			}
		}
		/* equivalent to
			.foo { color: red; }
			.foo > .bar { color: blue; }
		*/
		</pre>

		But ''@nest'' allows selectors that don't start with an ''&'',
		so the following are also valid:

		<pre class="lang-css">
		.foo {
			color: red;
			@nest .parent & {
				color: blue;
			}
		}
		/* equivalent to
			.foo { color: red; }
			.parent .foo { color: blue; }
		*/

		.foo {
			color: red;
			@nest :not(&) {
				color: blue;
			}
		}
		/* equivalent to
			.foo { color: red; }
			:not(.foo) { color: blue; }
		*/
		</pre>

		But the following are invalid:

		<pre class=lang-css>
		.foo {
			color: red;
			@nest .bar {
				color: blue;
			}
		}
		/* Invalid because there's no nesting selector */

		.foo {
			color: red;
			@nest & .bar, .baz {
				color: blue;
			}
		}
		/* Invalid because not all selectors in the list
			contain a nesting selector */
		</pre>
	</div>

	<div class=example>
		[=Directly nested=] [=style rules=] and ''@nest'' rules can be arbitrarily mixed.
		For example:

		<pre class=lang-css>
		.foo {
			color: blue;
			@nest .bar & {
				color: red;
				&.baz {
					color: green;
				}
			}
		}
		/* equivalent to
			.foo { color: blue; }
			.bar .foo { color: red; }
			.bar .foo.baz { color: green; }
		</pre>
	</div>


<!--
 ██████   ███████  ██    ██ ████████
██    ██ ██     ██ ███   ██ ██     ██
██       ██     ██ ████  ██ ██     ██
██       ██     ██ ██ ██ ██ ██     ██
██       ██     ██ ██  ████ ██     ██
██    ██ ██     ██ ██   ███ ██     ██
 ██████   ███████  ██    ██ ████████
-->

Nesting Conditional Rules {#conditionals}
-----------------------------------------

	In addition to ''@nest'' rules and [=directly nested=] style rules,
	this specification allows <dfn export>nested conditional group rules</dfn>
	inside of [=style rules=].

	When nested in this way,
	the contents of a [=conditional group rule=] are parsed the same as a [=style rule's=] contents:

	* Properties can be directly used,
		applying to the same elements as the parent rule
		(when the [=conditional group rule=] matches)
	* [=Style rules=] are treated as [=directly nested=],
		and so must have [=nest-prefixed=] selectors,
		with their [=nesting selector=] taking its definition
		from the nearest ancestor [=style rule=].
	* ''@nest'' rules are allowed,
		again with their [=nesting selector=] taking its definition
		from the nearest ancestor [=style rule=].

	Note: This implies that "normal" style rules,
	without a [=nesting selector=],
	are invalid in a [=nested conditional group rule=].

	<div class="example">
		For example, the following conditional nestings are valid:

		<pre class="lang-css">
		<b>/* Properties can be directly used */</b>
		.foo {
			display: grid;

			@media (orientation: landscape) {
				grid-auto-flow: column;
			}
		}
		/* equivalent to
			.foo { display: grid; }

			@media (orientation: landscape) {
				& {
					grid-auto-flow: column;
				}
			}
		*/

		/* finally equivalent to
			.foo { display: grid; }

			@media (orientation: landscape) {
				.foo {
					grid-auto-flow: column;
				}
			}
		*/

		<b>/* Conditionals can be further nested */</b>
		.foo {
			display: grid;

			@media (orientation: landscape) {
				grid-auto-flow: column;

				@media (min-inline-size > 1024px) {
					max-inline-size: 1024px;
				}
			}
		}

		/* equivalent to
			.foo { display: grid; }

			@media (orientation: landscape) {
				.foo {
					grid-auto-flow: column;
				}
			}

			@media (orientation: landscape) and (min-inline-size > 1024px) {
				.foo {
					max-inline-size: 1024px;
				}
			}
		*/
		</pre>

		But the following are invalid:

		<pre class=lang-css>
		.foo {
			color: red;

			@media (min-width: 480px) {
				& h1, h2 { color: blue; }
			}
		}
		/* Invalid because not all selectors in the list
			contain a nesting selector */

		.foo {
			color: red;

			@nest @media (min-width: 480px) {
				& { color: blue; }
			}
		}
		/* Invalid because @nest expects a selector prelude,
			instead a conditional group rule was provided */
		</pre>
	</div>


<!--
██     ██ ████ ██     ██ ████ ██    ██  ██████
███   ███  ██   ██   ██   ██  ███   ██ ██    ██
████ ████  ██    ██ ██    ██  ████  ██ ██
██ ███ ██  ██     ███     ██  ██ ██ ██ ██   ████
██     ██  ██    ██ ██    ██  ██  ████ ██    ██
██     ██  ██   ██   ██   ██  ██   ███ ██    ██
██     ██ ████ ██     ██ ████ ██    ██  ██████
-->

Mixing Nesting Rules and Declarations {#mixing}
-----------------------------------------------

	When a style rule contains both declarations
	and [=nested style rules=] or [=nested conditional group rules=],
	the declarations must come first,
	followed by the nested rules.
	Declarations occuring <em>after</em> a nested rule
	are invalid and ignored.

	<div class=example>
		For example,
		in the following code:

		<pre highlight=css>
		article {
			color: green;
			& { color: blue; }
			color: red;
		}
		</pre>

		The ''color: red'' declaration is invalid and ignored,
		since it occurs after the [=nested style rule=].

		However, further nested rules are still valid,
		as in this example:

		<pre highlight=css>
		article {
			color: green;
			& { color: blue; }
			color: red;
			&.foo { color: yellow; } /* valid! */
		}
		</pre>
	</div>

	For the purpose of determining the [[css-cascade-4#cascade-sort|Order Of Appearance]],
	[=nested style rules=] and [=nested conditional group rules=]
	are considered to come <em>after</em> their parent rule.

	<div>
		For example:

		<xmp highlight=css>
			article {
				color: blue;
				& { color: red; }
			}
		</xmp>

		Both declarations have the same specificity (0,0,1),
		but the nested rule is considered to come <em>after</em> its parent rule,
		so the ''color: red'' declarations wins the cascade.

		On the other hand, in this example:

		<xmp highlight=css>
			article {
				color: blue;
				@nest :where(&) { color: red; }
			}
		</xmp>

		The '':where()'' pseudoclass reduces the specificity of the [=nesting selector=] to 0,
		so the ''color: red'' declaration now has a specificity of (0,0,0),
		and loses to the ''color: blue'' declaration
		before "Order Of Appearance" comes into consideration.
	</div>


<!--
  ████
 ██  ██
  ████
 ████
██  ██ ██
██   ██
 ████  ██
-->

Nesting Selector: the ''&'' selector {#nest-selector}
=====================================================

	When using a <a>nested style rule</a>,
	one must be able to refer to the elements matched by the parent rule;
	that is, after all, <em>the entire point of nesting</em>.
	To accomplish that,
	this specification defines a new selector,
	the <dfn export>nesting selector</dfn>,
	written as <dfn selector>&</dfn> (U+0026 AMPERSAND).

	When used in the selector of a <a>nested style rule</a>,
	the <a>nesting selector</a> represents the elements matched by the parent rule.
	When used in any other context,
	it represents nothing.
	(That is, it's valid, but matches no elements.)

	<div class="note">
		The <a>nesting selector</a> can be desugared
		by replacing it with the parent style rule's selector,
		wrapped in an '':is()'' selector.
		For example,

		<pre class=lang-css>
		a, b {
			& c { color: blue; }
		}
		</pre>

		is equivalent to

		<pre class=lang-css>
		:is(a, b) c { color: blue; }
		</pre>
	</div>

	The <a>specificity</a> of the <a>nesting selector</a>
	is equal to the largest specificity among the complex selectors
	in the parent style rule's selector list
	(identical to the behavior of '':is()'').

	<div class="example">
		For example, given the following style rules:

		<pre class=lang-css>
		#a, b {
			& c { color: blue; }
		}
		.foo c { color: red; }
		</pre>

		Then in a DOM structure like

		<xmp class="lang-html">
			<b class=foo>
				<c>Blue text</c>
			</b>
		</xmp>

		The text will be blue, rather than red.
		The specificity of the ''&''
		is the larger of the specificities of ''#a'' ([1,0,0])
		and <css>b</css> ([0,0,1]),
		so it's [1,0,0],
		and the entire ''& c'' selector thus has specificity [1,0,1],
		which is larger than the specificity of ''.foo c'' ([0,1,1]).

		Notably, this is <em>different</em> than the result you'd get
		if the nesting were manually expanded out
		into non-nested rules,
		since the ''color: blue'' declaration would then be matching
		due to the ''b c'' selector ([0,0,2])
		rather than ''#a c'' ([1,0,1]).
	</div>

	<details class=note>
		<summary>Why is the specificity different than non-nested rules?</summary>

		The [=nesting selector=] intentionally uses the same specificity rules
		as the '':is()'' pseudoclass,
		which just uses the largest specificity among its arguments,
		rather than tracking <em>which</em> selector actually matched.

		This is required for performance reasons;
		if a selector has multiple possible specificities,
		depending on how precisely it was matched,
		it makes selector matching much more complicated and slower.

		That skirts the question, tho:
		why <em>do</em> we define ''&'' in terms of '':is()''?
		Some non-browser implementations of Nesting-like functionality
		do <em>not</em> desugar to '':is()'',
		largely because they predate the introduction of '':is()'' as well.
		Instead, they desugar directly;
		however, this comes with its own <em>significant</em> problems,
		as some (reasonably common) cases can accidentally produce <em>massive</em> selectors,
		due to the exponential explosion of possibilities.

		<pre class=lang-css>
		.a1, .a2, .a3 {
			& .b1, & .b3, & .b3 {
				& .c1, & .c2, & .c3 {
					...;
				}
			}
		}

		/* naively desugars to */
		.a1 .b1 .c1,
		.a1 .b1 .c2,
		.a1 .b1 .c3,
		.a1 .b2 .c1,
		.a1 .b2 .c2,
		.a1 .b2 .c3,
		.a1 .b3 .c1,
		.a1 .b3 .c2,
		.a1 .b3 .c3,
		.a2 .b1 .c1,
		.a2 .b1 .c2,
		.a2 .b1 .c3,
		.a2 .b2 .c1,
		.a2 .b2 .c2,
		.a2 .b2 .c3,
		.a2 .b3 .c1,
		.a2 .b3 .c2,
		.a2 .b3 .c3,
		.a3 .b1 .c1,
		.a3 .b1 .c2,
		.a3 .b1 .c3,
		.a3 .b2 .c1,
		.a3 .b2 .c2,
		.a3 .b2 .c3,
		.a3 .b3 .c1,
		.a3 .b3 .c2,
		.a3 .b3 .c3 {...}
		</pre>

		Here, three levels of nesting,
		each with three selectors in their lists,
		produced 27 desugared selectors.
		Adding more selectors to the lists,
		adding more levels of nesting,
		or making the nested rules more complex
		can make a relatively small rule
		expand into multiple megabytes of selectors
		(or much, much more!).

		Some CSS tools avoid the worst of this
		by heuristically discarding some variations,
		so they don't have to output as much
		but are still <em>probably</em> correct,
		but that's not an option available to UAs.

		Desugaring with '':is()'' instead eliminates this problem entirely,
		at the cost of making specificity slightly less useful,
		which was judged a reasonable trade-off.
	</details>

	The <a>nesting selector</a> is allowed anywhere in a <a>compound selector</a>,
	even before a <a>type selector</a>,
	violating the normal restrictions on ordering within a <a>compound selector</a>.

	<div class='example'>
		For example, ''&div'' is a valid nesting selector,
		meaning "whatever the parent rules matches,
		but only if it's also a <{div}> element".

		It could also be written as ''div&'' with the same meaning,
		but that wouldn't be valid to start a [=directly nested=] [=style rule=].
	</div>


<!--
 ██████   ██████   ██████   ███████  ██     ██
██    ██ ██    ██ ██    ██ ██     ██ ███   ███
██       ██       ██       ██     ██ ████ ████
██        ██████   ██████  ██     ██ ██ ███ ██
██             ██       ██ ██     ██ ██     ██
██    ██ ██    ██ ██    ██ ██     ██ ██     ██
 ██████   ██████   ██████   ███████  ██     ██
-->

CSSOM {#cssom}
==============

Modifications to {{CSSStyleRule}} {#cssom-style}
---------------------------------------------

CSS style rules gain the ability to have nested rules:

<pre class=idl>
partial interface CSSStyleRule {
	[SameObject] readonly attribute CSSRuleList cssRules;
	unsigned long insertRule(CSSOMString rule, optional unsigned long index = 0);
	undefined deleteRule(unsigned long index);
};
</pre>

The <dfn attribute for=CSSStyleRule>cssRules</dfn> attribute
must return a {{CSSRuleList}} object for the [=CSSRule/child CSS rules=].

The <dfn method for=CSSStyleRule>insertRule(<var>rule</var>, <var>index</var>)</dfn> method
must return the result of
invoking [=insert a CSS rule=] <var>rule</var>
into the [=CSSRule/child CSS rules=] at <var>index</var>.

The <dfn method for=CSSStyleRule>deleteRule(<var>index</var>)</dfn> method
must [=remove a CSS rule=] from the [=CSSRule/child CSS rules=] at <var>index</var>.


The {{CSSNestingRule}} Interface {#cssom-nesting}
-------------------------------------------------

The {{CSSNestingRule}} interfaces represents a ''@nest'' rule:

<pre class=idl>
[Exposed=Window]
interface CSSNestingRule : CSSRule {
	attribute CSSOMString selectorText;
	[SameObject, PutForwards=cssText] readonly attribute CSSStyleDeclaration style;
	[SameObject] readonly attribute CSSRuleList cssRules;
	unsigned long insertRule(CSSOMString rule, optional unsigned long index = 0);
	undefined deleteRule(unsigned long index);
};
</pre>

The <dfn attribute for=CSSNestingRule>selectorText</dfn> attribute,
on getting,
must return the result of [=serialize a group of selectors|serializing=]
the associated [=selector list=].
On setting the {{CSSStyleRule/selectorText}} attribute these steps must be run:

1. Run the <a>parse a group of selectors</a> algorithm on the given value.
2. If the algorithm returns a non-null value replace the associated [=selector list=] with the returned value.
3. Otherwise, if the algorithm returns a null value, do nothing.

The <dfn attribute for=CSSNestingRule>style</dfn> attribute
must return a {{CSSStyleDeclaration}} object for the style rule,
with the following properties:

<dl>
	: [=CSSStyleDeclaration/computed flag=]
	:: Unset.
	: [=CSSStyleDeclaration/declarations=]
	:: The declared declarations in the rule, in <a>specified order</a>.
	: [=CSSStyleDeclaration/parent CSS rule=]
	:: The [=this=] object.
	: [=CSSStyleDeclaration/owner node=]
	:: Null.
</dl>

The <dfn attribute for=CSSNestingRule>cssRules</dfn> attribute
must return a {{CSSRuleList}} object for the [=CSSRule/child CSS rules=].

The <dfn method for=CSSNestingRule>insertRule(<var>rule</var>, <var>index</var>)</dfn> method
must return the result of
invoking [=insert a CSS rule=] <var>rule</var>
into the [=CSSRule/child CSS rules=] at <var>index</var>.

The <dfn method for=CSSNestingRule>deleteRule(<var>index</var>)</dfn> method
must [=remove a CSS rule=] from the [=CSSRule/child CSS rules=] at <var>index</var>.

To serialize a {{CSSNestingRule}}:
return the result of the following steps:

<ol>
	<li>Let |s| initially be the string "<code>@nest</code>" followed by a single SPACE (U+0020).
	<li>Append to |s| the result of performing <a>serialize a group of selectors</a> on the rule's associated selectors,
		followed by the string "<code> {</code>", i.e., a single SPACE (U+0020), followed by LEFT CURLY BRACKET (U+007B).
	<li>Let |decls| be the result of performing <a>serialize a CSS declaration block</a> on the rule's associated declarations, or null if there are no such declarations.
	<li>Let |rules| be the result of performing [=serialize a CSS rule=] on each rule in the rule's {{CSSStyleRule/cssRules}} list, or null if there are no such rules.
	<li>If |decls| and |rules| are both null, append " }" to |s| (i.e. a single SPACE (U+0020) followed by RIGHT CURLY BRACKET (U+007D)) and return |s|.
	<li>If |rules| is null:
		<ol>
			<li>Append a single SPACE (U+0020) to |s|
			<li>Append |decls| to |s|
			<li>Append " }" to |s| (i.e. a single SPACE (U+0020) followed by RIGHT CURLY BRACKET (U+007D)).
			<li>Return |s|.
		</ol>
	<li>Otherwise:
		<ol>
			<li>If |decls| is not null, prepend it to |rules|.
			<li>For each |rule| in |rules|:
				<ol>
					<li>Append a newline followed by two spaces to |s|.
					<li>Append |rule| to |s|.
				</ol>
			<li>Append a newline followed by RIGHT CURLY BRACKET (U+007D) to |s|.
			<li>Return |s|.
</ol>