[css-nesting-1] Add CSSOM stuff

Author: tabatkins

css-nesting-1/Overview.bs

@@ -9,7 +9,13 @@ ED: https://drafts.csswg.org/css-nesting/
 Editor: Tab Atkins Jr., 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.
-Link Defaults: css-color-4 (property) color
+</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">
@@ -28,17 +34,6 @@ Module Interactions</h3>
 	This module introduces new parser rules that extend the [[!CSS21]] parser model.
 	This module introduces selectors that extend the [[SELECTORS4]] module.
 
-<pre class=idl>
-[Exposed=Window]
-interface CSSNestingRule : CSSRule {
-  attribute CSSOMString selectorText;
-  [SameObject] readonly attribute CSSRuleList cssRules;
-  [SameObject, PutForwards=cssText] readonly attribute CSSStyleDeclaration style;
-  unsigned long insertRule(CSSOMString rule, optional unsigned long index = 0);
-  undefined deleteRule(unsigned long index);
-};
-</pre>
-
 <h3 id="values">
 Values</h3>
 
@@ -256,8 +251,8 @@ Direct Nesting {#direct}
 
 			 // and
 
-			 .foo { 
-				 color: blue; 
+			 .foo {
+				 color: blue;
 				 padding: 2ch;
 			 }
 		 */
@@ -328,7 +323,7 @@ Direct Nesting {#direct}
 			color: red;
 			&&.bar { color: blue; }
 		}
-		/* Invalid because the second & is no longer 
+		/* Invalid because the second & is no longer
 			 at the start of a compound selector */
 
 		.foo {
@@ -449,9 +444,9 @@ Nesting Conditional Rules {#conditionals}
   A style rule can have any number of <a>conditional rules</a> inside of it, of any type,
   intermixed with any number of declarations, in any order.
 
-  The presence of a nested conditional engages the same logic as if ''@nest'' was present. 
-  The nested conditional rules must contain a <a>nesting selector</a> and follow the same 
-  rules as outlined in <a href="#direct">direct nesting</a>. 
+  The presence of a nested conditional engages the same logic as if ''@nest'' was present.
+  The nested conditional rules must contain a <a>nesting selector</a> and follow the same
+  rules as outlined in <a href="#direct">direct nesting</a>.
 
   <div class="example">
     For example, the following conditional nestings are valid:
@@ -461,17 +456,17 @@ Nesting Conditional Rules {#conditionals}
       display: grid;
 
       @media (orientation: landscape) {
-        & { 
-          grid-auto-flow: column; 
+        & {
+          grid-auto-flow: column;
         }
       }
     }
     /* equivalent to
        .foo { display: grid; }
 
        @media (orientation: landscape) {
-         .foo { 
-           grid-auto-flow: column; 
+         .foo {
+           grid-auto-flow: column;
          }
        }
      */
@@ -480,8 +475,8 @@ Nesting Conditional Rules {#conditionals}
       display: grid;
 
       @media (orientation: landscape) {
-        & { 
-          grid-auto-flow: column; 
+        & {
+          grid-auto-flow: column;
         }
 
         @media (min-inline-size > 1024px) {
@@ -496,13 +491,13 @@ Nesting Conditional Rules {#conditionals}
        .foo { display: grid; }
 
        @media (orientation: landscape) {
-         .foo { 
-           grid-auto-flow: column; 
+         .foo {
+           grid-auto-flow: column;
          }
        }
 
        @media (orientation: landscape) and (min-inline-size > 1024px) {
-         .foo { 
+         .foo {
            max-inline-size: 1024px;
          }
        }
@@ -513,7 +508,7 @@ Nesting Conditional Rules {#conditionals}
 
       @media (min-width: 480px) {
         & > .bar,
-        & > .baz { 
+        & > .baz {
           color: blue;
         }
       }
@@ -522,7 +517,7 @@ Nesting Conditional Rules {#conditionals}
        .foo { color: red; }
 
        @media (min-width: 480px) {
-         .foo > :is(.bar, .baz) { 
+         .foo > :is(.bar, .baz) {
            color: blue;
          }
        }
@@ -543,7 +538,7 @@ Nesting Conditional Rules {#conditionals}
 
     .foo {
       color: red;
-      
+
       @media (min-width: 480px) {
         & h1, h2 { color: blue; }
       }
@@ -553,12 +548,12 @@ Nesting Conditional Rules {#conditionals}
 
     .foo {
       color: red;
-      
+
       @nest @media (min-width: 480px) {
         & { color: blue; }
       }
     }
-    /* Invalid because @nest expects a selector prelude, 
+    /* Invalid because @nest expects a selector prelude,
        instead a conditional rule was provided */
     </pre>
   </div>
@@ -571,15 +566,15 @@ Mixing Nesting Rules and Declarations {#mixing}
 	intermixed with any number of declarations,
 	in any order.
 
-	The relative ordering of <a>nested style rules</a>, <a>nested conditional rules</a> and 
+	The relative ordering of <a>nested style rules</a>, <a>nested conditional rules</a> and
 	other declarations <strong>is</strong> important;
 	it's possible for a given style rule and a <a>nested style rule</a> within it to match the same element,
 	and if the specificity of the two rules is otherwise equivalent,
 	the relative order in the stylesheet of the applicable declarations
 	determines which declaration "wins" the <a>cascade</a>.
 
   <div class="example">
-    For example, consider the following where the specificity is the same and the 
+    For example, consider the following where the specificity is the same and the
     cascade is used for value resolution:
 
     <pre class="lang-css">
@@ -626,9 +621,9 @@ Mixing Nesting Rules and Declarations {#mixing}
     &#60;!-- div text color is blue --&#62;
     </pre>
 
-    ''article :is(.blue, #gotcha)'' now has a specificity score of (1,1,1). 
-    Nesting uses '':is()'' which assumes the specificity of it's highest selector. 
-    
+    ''article :is(.blue, #gotcha)'' now has a specificity score of (1,1,1).
+    Nesting uses '':is()'' which assumes the specificity of it's highest selector.
+
 
     To work around it, the following could be written instead:
 
@@ -657,10 +652,92 @@ Mixing Nesting Rules and Declarations {#mixing}
   </div>
 
 
-CSS Object Model Modifications {#cssom}
-=======================================
+<!--
+ ██████   ██████   ██████   ███████  ██     ██
+██    ██ ██    ██ ██    ██ ██     ██ ███   ███
+██       ██       ██       ██     ██ ████ ████
+██        ██████   ██████  ██     ██ ██ ███ ██
+██             ██       ██ ██     ██ ██     ██
+██    ██ ██    ██ ██    ██ ██     ██ ██     ██
+ ██████   ██████   ██████   ███████  ██     ██
+-->
 
-	<div class=issue>
-		1. Add an interface for the @nest rule.
-		2. Tie into the general work needed to let rules be nested into style rules.
-	</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 <a>context object</a>.
+	: [=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>.