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

[dletorey]

Description

• Added API page for CSSNestedDeclarations
• Added property page for CSSNestedDeclarations.style
• Added link from CSSOM page to CSSNestedDeclarations page
• Added link from CSSRule page to CSSNestedDeclarations page
• Added explanation of CSSNestedDeclarations on Using CSS Nesting

Motivation

• Working on issue #36115

Related issues and pull requests

• BCD PR Firefox
• BCD PR Chrome
• Yari PR
• FF Release note PR

[github-actions]

Preview URLs

• /en-US/docs/Web/API/CSSNestedDeclarations/style
• /en-US/docs/Web/API/CSSNestedDeclarations
• /en-US/docs/Web/API/CSSRule
• /en-US/docs/Web/API/CSS_Object_Model
• /en-US/docs/Web/CSS/CSS_nesting/Using_CSS_nesting

Flaws (2)

Note! 4 documents with no flaws that don't need to be listed. 🎉

URL: /en-US/docs/Web/API/CSS_Object_Model
Title: CSS Object Model (CSSOM)
Flaw count: 2

• macros:
  • /en-US/docs/Web/API/CSSFontFeatureValuesMap does not exist
  • /en-US/docs/Web/API/CSSMarginRule does not exist

External URLs (1)

URL: /en-US/docs/Web/CSS/CSS_nesting/Using_CSS_nesting
Title: Using CSS nesting

• https://drafts.csswg.org/css-nesting-1/ (1 time) (Note! This may be a new URL 👀)

(comment last updated: 2024-11-11 16:00:38)

[dipikabh]

Hi Hamish, could you review this PR?

[hamishwillee]

As above, this really doesn't tell me anything because I don't see what the types are.

[dletorey]

See #36430 (comment)

[hamishwillee]

See my response #36430 (comment)

What do you think a reader can learn from this? I don't particularly might what you show, but it has to show something related to the API we are demonstrating, and really this does not.

If I had to do this I would either have a live example that shows the structure, or add pseudo code. Assuming the second, then something like.

---

Consider the following

.foo {
  background-color: silver;
  @media (screen) {
    color: tomato;
  }
  color: black;
}

This would be parsed into a structure similar to the one shown below. Note that blah blah.

[Note, that I am not sure this is correct - I just copied it from your original. Probably it isn't - ie. I don't think the last declaration is nested]

↳ CSSStyleRule
  .style
    - background-color: silver
  ↳ CSSMediaRule
    ↳ CSSNestedDeclarations
      .style (CSSStyleDeclaration, 1) =
      - color: tomato
  ↳ CSSNestedDeclarations
    .style (CSSStyleDeclaration, 1) =
      - color: black

[dletorey]

Yes it is, as this is how the order of the rules are retained.

• https://codepen.io/CodeRedDigital/pen/zYgdaWy
• https://web.dev/blog/css-nesting-cssnesteddeclarations

[hamishwillee]

What do you think a reader can learn from this? I don't particularly might what you show, but it has to show something related to the API we are demonstrating, and really this does not.

Still not answered.

[hamishwillee]

What I would do here is write code that creates this structure. I'd do it for you but your repo is locked for edits. So something like:

---

This example shows how to construct the following stylesheet using the CSSDOM API.

.foo {
  background-color: silver;
  @media (screen) {
    color: tomato;
  }
  color: black;
}

[Insert the code here]

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 that point at the end that you gave me in the other note - this is relevant to usage of this API.

[dletorey]

I am not sure that this is correct, either.
The CSSNestedDeclarations API only returns that the there is an object of type CSSNestedDeclarations which in turn are cssRules with styles
https://codepen.io/CodeRedDigital/pen/vYozyrG?editors=0112

Although I believe I has managed to explain this better now

[hamishwillee]

Is this nested?

[dletorey]

See comment
All the rules before nesting or at-properties are added at the top-level CSSRules anything after nesting or at-properties are added as nested declarations as that is how the order is preserved. Before CSSNestedDeclarations rules at the same level were hoisted up to the top with other rules whcih changed the order and effected the cascade.

[hamishwillee]

That's really useful thanks! Reading that I think it is more before and after nesting, and the at-rules is just a form of nesting right?

Anyway, if I can have this misunderstanding others can, so I have added proposals https://github.com/mdn/content/pull/36430/files#r1828495475 , https://github.com/mdn/content/pull/36430/files#r1828504825, #36430 (comment)

[hamishwillee]

Thanks very much @dletorey ! All done.