added api page for CSSNestedDeclaration and the style peroperty and a…

files/en-us/web/api/css_object_model/index.md

@@ -41,6 +41,7 @@ The values of CSS are represented untyped, that is using {{JSxRef("String")}} ob
 - {{DOMxRef("CSSStyleSheet")}}
 - {{DOMxRef("CSSStyleRule")}}
 - {{DOMxRef("CSSSupportsRule")}}
+- {{DOMXRef("CSSNestedDeclarations")}}
 - {{DOMxRef("FontFace")}}
 - {{DOMxRef("FontFaceSet")}}
 - {{DOMxRef("FontFaceSetLoadEvent")}}

files/en-us/web/api/cssnesteddeclarations/index.md

@@ -0,0 +1,64 @@
+---
+title: CSSNestedDeclarations
+slug: Web/API/CSSNestedDeclarations
+page-type: web-api-interface
+browser-compat: api.CSSNestedDeclarations
+---
+
+{{APIRef("CSSOM")}}
+
+The **`CSSNestedDeclarations`** interface of the [CSS Rule API](/en-US/docs/Web/API/CSSRule) is used to group nested {{domxref("CSSRule")}}s.
+
+The interface allows the [CSS Object Model (CSSOM](/en-US/docs/Web/API/CSS_Object_Model) to mirror the structure of CSS documents with nested CSS rules, and ensure that rules are parsed and evaluated in the order that they are declared.
+
+> [!NOTE] > [Browser versions](#browser_compatibility) with implementations that do not support this interface may parse nested rules in the wrong order.
+
+{{InheritanceDiagram}}
+
+## Instance properties
+
+_Inherits properties from its ancestor {{domxref("CSSRule")}}._
+
+- {{domxref("CSSNestedDeclarations.style")}} {{ReadOnlyInline}}
+  - : Returns the values of the nested rules.
+
+## Instance methods
+
+_No specific methods; inherits methods from its ancestor {{domxref("CSSRule")}}._
+
+## Examples
+
+The CSS below includes a selector `.foo` that contains three nested rules.
+
+```css
+.foo {
+  background-color: silver;
+  @media (screen) {
+    color: tomato;
+  }
+  color: black;
+}
+```
+
+This is represented by a number of JavaScript objects in the [CSS Object Model](/en-US/docs/Web/API/CSS_Object_Model):
+
+- A {{domxref("CSSStyleRule")}} object that represents the `background-color: silver` rule.
+  This can be returned via `document.styleSheets[0].cssRules[0]`.
+- A {{domxref("CSSMediaRule")}} object  that represents the `@media (screen)` rule, and which can be returned via `document.styleSheets[0].cssRules[0].cssRules[0]`.
+   - The `CSSMediaRule` object contains a `CSSNestedDeclaration` object which represents the  `color: tomato` rule nested by the `@media (screen)` rule.
+     This can be returned via `document.styleSheets[0].cssRules[0].cssRules[0].cssRules[0]`.
+- The final rule is a `CSSNestedDeclaration` object that represents the `color: black` rule in the stylesheet, and which can be returned via `document.styleSheets[0].cssRules[0].cssRules[1]`.
+
+  Note that all top-level styles after the first `CSSNestedDeclaration` must also be represented as `CSSNestedDeclaration` objects in order to follow the [CSS nested declarations rule](/en-US/docs/Web/CSS/CSS_nesting/Using_CSS_nesting#nested_declarations_rule)
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See Also
+
+- {{domxref("CSSNestedDeclarations.style")}}
+- [The Nested Declarations Rule](/en-US/docs/Web/CSS/CSS_nesting/Using_CSS_nesting#nested_declarations_rule)

files/en-us/web/api/cssnesteddeclarations/style/index.md

@@ -0,0 +1,55 @@
+---
+title: "CSSNestedDeclarations: style property"
+short-title: style
+slug: Web/API/CSSNestedDeclarations/style
+page-type: web-api-instance-property
+browser-compat: api.CSSNestedDeclarations.style
+---
+
+{{APIRef("CSSOM")}}
+
+The read-only **`style`** property of the {{domxref("CSSNestedDeclarations")}} interface represents the styles associated with the nested rules.
+
+## Value
+
+An object.
+
+## Examples
+
+This stylesheet contains a nested {{domxref("cssRule","cssRules")}}.
+
+The first `console.log` shows the top-level `style`, the second shows the nested `@media` query with its nested style and the final shows the nested style declared after the `@media` query.
+
+```css
+.foo {
+  font-size: 1.2rem;
+  @media (screen) {
+    color: tomato;
+    background-color: darkgrey;
+  }
+  color: black;
+}
+```
+
+```js
+let myRules = document.styleSheets[0].cssRules;
+console.log(myRules[0].style);
+// { "0": "font-size" }
+console.log(myRules[0].cssRules[0].cssRules[0].style);
+// { "0": "color", "1": "background-color" }
+console.log(myRules[0].cssRules[1].style);
+// { "0": "color" }
+```
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See Also
+
+- {{domxref("CSSNestedDeclarations")}}
+- [The Nested Declarations Rule](/en-US/docs/Web/CSS/CSS_nesting/Using_CSS_nesting#nested_declarations_rule)

files/en-us/web/api/cssrule/index.md

@@ -25,6 +25,7 @@ The **`CSSRule`** interface represents a single CSS rule. There are several type
 - {{DOMXRef("CSSLayerBlockRule")}}
 - {{DOMXRef("CSSLayerStatementRule")}}
 - {{DOMXRef("CSSPropertyRule")}}
+- {{DOMXRef("CSSNestedDeclarations")}}
 
 ## Instance properties
 

files/en-us/web/css/css_nesting/using_css_nesting/index.md

@@ -386,6 +386,46 @@ In the following CSS, we are creating the styles for `.card` and `.card h2`. The
 
 {{EmbedLiveSample('Appending_nesting_selector','100%','250')}}
 
+## Nested declarations rule
+
+The nested declaration rule is that CSS rules are parsed in the order that they are written in the CSS document.
+
+With the following CSS:
+
+```css
+.foo {
+  background-color: silver;
+  @media (screen) {
+    color: tomato;
+  }
+  color: black;
+}
+```
+
+The `background-color` is parsed first and set to silver, then the `@media` rule is evaluated, and finally the `color`.
+
+The CSSOM parses the CSS in the following way:
+
+```txt
+↳ CSSStyleRule
+  .style
+    - background-color: silver
+  ↳ CSSMediaRule
+    ↳ CSSNestedDeclarations
+      .style (CSSStyleDeclaration, 1) =
+      - color: tomato
+  ↳ CSSNestedDeclarations
+    .style (CSSStyleDeclaration, 1) =
+      - color: black
+```
+
+Note that in order to preserve the parsing order, all the rules before nesting are handled as top-level `CSSRules`, while any top level rules after nesting are represented as `CSSNestedDeclarations`.
+That's why the `color-black` is inside a nested declaration even though it is a top level declaration in the original document.
+
+> [!NOTE]
+> Support for the rule was added with {{domxref("CSSNestedDeclarations")}}.
+> Browsers that [do not support this interface](/en-US/docs/Web/API/CSSNestedDeclarations#browser_compatibility) this interface may parse nested rules in the wrong order.
+
 ## Concatenation (is not possible)
 
 In CSS preprocessors such as [Sass](https://sass-lang.com/), it is possible to use nesting to join strings to create new classes. This is common in CSS methodologies such as [BEM](https://getbem.com/naming/).
@@ -442,3 +482,5 @@ In the following example, there is an invalid selector (`%` is not a valid chara
 - [`&` nesting selector](/en-US/docs/Web/CSS/Nesting_selector)
 - [Nesting `@` at-rules](/en-US/docs/Web/CSS/CSS_nesting/Nesting_at-rules)
 - [Nesting and specificity](/en-US/docs/Web/CSS/CSS_nesting/Nesting_and_specificity)
+- {{domxref("CSSNestedDeclarations")}}
+- [The Nested Declarations Rule](https://drafts.csswg.org/css-nesting-1/#nested-declarations-rule)