From 5e3cb7c4405256c4ad004986bbff622777b664b6 Mon Sep 17 00:00:00 2001 From: Dave Letorey Date: Tue, 12 Nov 2024 00:31:34 +0000 Subject: [PATCH] =?UTF-8?q?added=20api=20page=20for=20CSSNestedDeclaration?= =?UTF-8?q?=20and=20the=20style=20peroperty=20and=20a=E2=80=A6=20(#36430)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * added api page for CSSNestedDeclaration and the style peroperty and added explanation of The Nested Declaration rule on the nesting page * Update files/en-us/web/api/cssnesteddeclarations/index.md Co-authored-by: Hamish Willee * Update files/en-us/web/api/cssnesteddeclarations/index.md Co-authored-by: Hamish Willee * Update files/en-us/web/api/cssnesteddeclarations/index.md Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> * updated the see also links and the eamples on CSSNestedDeclaration * Update files/en-us/web/api/cssnesteddeclarations/index.md Co-authored-by: Hamish Willee * updated the .style property * updated the Nested declarations rule section to make it clearer * Update files/en-us/web/api/cssnesteddeclarations/index.md Co-authored-by: Hamish Willee * Update files/en-us/web/css/css_nesting/using_css_nesting/index.md Co-authored-by: Hamish Willee * fixed domxref link * Update files/en-us/web/css/css_nesting/using_css_nesting/index.md Co-authored-by: Hamish Willee * Update files/en-us/web/css/css_nesting/using_css_nesting/index.md Co-authored-by: Hamish Willee * Update files/en-us/web/css/css_nesting/using_css_nesting/index.md Co-authored-by: Hamish Willee * fleshed out the example and what the rules return * Update files/en-us/web/api/cssnesteddeclarations/index.md Co-authored-by: Hamish Willee * Update files/en-us/web/api/cssnesteddeclarations/index.md Co-authored-by: Hamish Willee * updated description of CSS and includesd the CSSOM representation * converted the note --------- Co-authored-by: Hamish Willee Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> --- files/en-us/web/api/css_object_model/index.md | 1 + .../web/api/cssnesteddeclarations/index.md | 83 +++++++++++++++++++ .../api/cssnesteddeclarations/style/index.md | 55 ++++++++++++ files/en-us/web/api/cssrule/index.md | 1 + .../css_nesting/using_css_nesting/index.md | 42 ++++++++++ 5 files changed, 182 insertions(+) create mode 100644 files/en-us/web/api/cssnesteddeclarations/index.md create mode 100644 files/en-us/web/api/cssnesteddeclarations/style/index.md diff --git a/files/en-us/web/api/css_object_model/index.md b/files/en-us/web/api/css_object_model/index.md index 3f143496026e9fd..a316d998a6d9a1c 100644 --- a/files/en-us/web/api/css_object_model/index.md +++ b/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")}} diff --git a/files/en-us/web/api/cssnesteddeclarations/index.md b/files/en-us/web/api/cssnesteddeclarations/index.md new file mode 100644 index 000000000000000..b4eefca2186e8d8 --- /dev/null +++ b/files/en-us/web/api/cssnesteddeclarations/index.md @@ -0,0 +1,83 @@ +--- +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 + +### CSS + +The CSS below includes a selector `.foo` that contains two declarations and a media query. + +```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] +> 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) + +### CSSOM (CSS Object Model) + +```txt +↳ CSSStyleRule + .style + - background-color: silver + ↳ CSSMediaRule + ↳ CSSNestedDeclarations + .style (CSSStyleDeclaration, 1) = + - color: tomato + ↳ CSSNestedDeclarations + .style (CSSStyleDeclaration, 1) = + - color: black +``` + +## 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) diff --git a/files/en-us/web/api/cssnesteddeclarations/style/index.md b/files/en-us/web/api/cssnesteddeclarations/style/index.md new file mode 100644 index 000000000000000..9f72d605cc245a0 --- /dev/null +++ b/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) diff --git a/files/en-us/web/api/cssrule/index.md b/files/en-us/web/api/cssrule/index.md index 641a69abac8d958..4c24cf4219a984e 100644 --- a/files/en-us/web/api/cssrule/index.md +++ b/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 diff --git a/files/en-us/web/css/css_nesting/using_css_nesting/index.md b/files/en-us/web/css/css_nesting/using_css_nesting/index.md index d4102552ee247c2..bf0006bbb657479 100644 --- a/files/en-us/web/css/css_nesting/using_css_nesting/index.md +++ b/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)