[css-syntax][css-nesting] Design of @nest rule

[LeaVerou]

Opening this as requested by @astearns

In #8738 we resolved to stop hoisting interleaved declarations and introduce an @nest rule that means "exactly the same thing as the parent" instead of wrapping in :is(), which is how interleaved declarations will be represented in the CSS OM. Since we were not able to get consensus on the specifics, but we had consensus that any solution along these lines is better than the status quo, we agreed that Tab would spec whatever (commit here), and we'd discuss the details later, since fixing the specifics is more web compatible than changing the current behavior after even longer.

Note

An interleaved declaration is a declaration that comes after one or more nested rules.

The issues around which we could not reach consensus were:

1. If authors have no reason to write @nest and it’s only introduced to represent interleaved declarations and rules, should they even be able to?
2. If @nest rules are magically added around interleaved declarations should they also be removed during serialization?
   1. If they are removed during serialization, does this happen always, or only when part of a larger rule (e.g. as part of .cssText)?
3. Do we even need a new @nest rule? What if we simply use the existing CSSStyleDeclaration object to represent interleaved rules? (proposed by @mdubet)
4. How does setProperty() work if we go with one of the designs that involve more magic?
5. What happens when a rule is removed and thus two sets of interleaved declarations become adjacent?
   1. Similar issue not brought up in the call: what about the case when these rules are first? Should they be merged with rule.style?

These are not orthogonal decisions: it seems clear that if @nest serializes to include an actual @nest {} rule, that @nest rule needs to also be valid author code. So essentially there are three possible designs:

1. Magic-minimizing @nest (proposed by @tabatkins, supported by @emilio @andruud @Loirooriol): The rule is automatically added around interleaved declarations, but there is no more magic besides that.
2. Author-exposure minimizing @nest (proposed by @LeaVerou, supported by @fantasai @astearns): The rule becomes a CSS OM detail, with no corresponding CSS syntax, and is removed on serialization (regardless of how serialization happens).
3. No @nest, just CSSStyleDeclaration in the CSSOM (proposed by @mdubet, supported by @LeaVerou @fantasai).
   • Criticism: That means .cssRules will also return non-rules? Would .insertRule() also accept CSSStyleDeclaration?

For 2 and 3, there are also design variations based on the answer to 4 and 5 above.

My position:

• As a design principle, I don't think CSS should have author-facing syntax that provides no benefit to authors. Either we should come up with actual use cases for @nest or make it an internal detail. That said, there could conceivably be use cases for it. E.g. one of the problems with IACVT is that fallbacks are thrown away by the time the declaration becomes invalid. What if this was a way to preserve fallbacks?
• Despite proposing 2, I actually now support 3 as I realized this version of @nest is functionally equivalent to CSSStyleDeclaration and we should not be introducing new interfaces with philosophical purity being the only motivation (i.e. "but otherwise .cssRules would be returning a non-rule?!?")
• Some voices are arguing for less magic as a goal in itself. I don't think avoiding magic at all costs should be a goal; the right magic can make a huge usability difference (at the cost of implementation complexity). It’s the wrong kind of magic that becomes problematic: magic that rarely predicts user intent well, and especially when they cannot opt-out of it. Neither seems to be the case here, at least if we design this well.
• I think authors should be able to interact with the CSS OM predictably without having to care whether there are interleaved declarations or not. This means that setProperty() on the base rule should just work, without them having to do tree walking to find the last nested rule. Like, setProperty() is an incredibly common operation, and an API where calls to setProperty() have no effect are exactly the kind of dreadful APIs that make utility libraries proliferate.
• I strongly disagree with Tab that reading and modifying the CSS OM only affects about a hundred developers in the entire world (!). Reading and modifying the CSS OM is at the core of a ton of very widespread libraries (e.g. jQuery, D3, etc). Even if most authors do not use it directly, I assure you almost every developer reads and modifies the CSS OM regularly, it's just done through several layers of abstractions.

So I would propose a design that would minimize author exposure to all of this, and would just try to do what's reasonable when reading and modifying the CSS OM:

• .cssRules would contain CSSStyleDeclaration objects with interleaved declarations
• insertRule() would accept CSSStyleDeclaration objects
• No nonsensical or redundant structures:
  • Adjacent CSSStyleDeclaration objects would be merged.
  • A CSSStyleDeclaration object cannot be at the start of cssRules. Inserting one should simply merge the declarations with rule.style.

Should rule.style be magic?

One thing I'm ambivalent about is whether rule.style should be magic too.
This would mean:

• rule.style returns the union of all interleaved declarations (we can introduce another property to only get the non-interleaved ones)
• rule.style.setProperty() (and accessors) adds to the last interleaved CSSStyleDeclaration (if any are present). The third argument is turned into a dictionary with a priority property and another property (name TBD) to reverse this behavior and actually add it to the first block of declarations.

Pros & Cons:

• 👍🏼 Max compatibility with existing code
• 👍🏼 Fewer footguns for authors (minimize bugs if authors forget to handle the case of interleaved declarations)
• 👍🏼 More sensible API for when inline styles also support nesting.
• 👀 Would this work or would it end up not predicting author intent well? What cases am I missing?

If we decide to avoid magic here, we can make the API more palatable by:

• Introducing a new rule property that returns a CSSStyleDeclaration for the union of rule.style and interleaved declarations
• Introducing a rule.setProperty() method that would add the property at the end of the last interleaved declaration. rule.style.setProperty() would continue to do what it currently does. Same for removeProperty(), getPropertyValue() etc.

[romainmenke]

Thank you @LeaVerou.

As a design principle, I don't think CSS should have author-facing syntax that provides no benefit to authors. Either we should come up with actual use cases for @nest

I actually want the @nest rule but as a more generic organizational tool.

In JavaScript it is possible to write blocks without any condition. I use this very frequently to group bits of code in a larger section.

This new at-rule could serve a similar purpose. Most authors will never use it but they could to organise and structure their code.

Today we use either multiple rules with the same selector, or comments when we want to group lists of declarations. Neither is really good.

This is our list of custom props when we start a new project :

:root {
	/* #region Colors */
	--color-foreground: rgb(0 0 0);
	--color-background: rgb(255 255 255);
	--color-grey-40: rgb(108 112 108);
	--color-warning: rgb(242 149 0);
	--color-error: rgb(207 0 0);
	/* #endregion Colors */

	/* #region Typography */
	--font-sans: "Helvetica Neue", sans-serif;
	--font-serif: "Georgia", serif;
	/* #endregion Typography */

	/* #region Spacers */
	--space-1--px: 1px;
	--space-1--rem: 0.0625rem;
	--space-8--px: 8px;
	--space-8--rem: 0.5rem;
	--space-16--px: 16px;
	--space-16--rem: 1rem;
	--space-32--px: 32px;
	--space-32--rem: 2rem;
	--space-48--px: 48px;
	--space-48--rem: 3rem;
	/* #endregion Spacers */
}

We need to add comments before and after each group so that we can have folding regions in code editors.

@tabatkins has also stated that they aren't attached to the name of this at-rule. Something that isn't tied to nesting would be nice.

---

If on the other hand, this can all be implementation details, then I prefer that.
I however fear that we can only kick this bucket further down the road and that some API will surface the warts.

[andruud]

In JavaScript it is possible to write blocks without any condition. I use this very frequently to group bits of code in a larger section.

@tabatkins has also stated that they aren't attached to the name of this at-rule. Something that isn't tied to nesting would be nice.

Do we need the @nest part of the rule? Can we use naked {}? Looking at css-syntax, I don't immediately see why not. In other words:

:root {
  /* #region Colors */
  {
    --color-foreground: rgb(0 0 0);
    --color-background: rgb(255 255 255);
    --color-grey-40: rgb(108 112 108);
    --color-warning: rgb(242 149 0);
    --color-error: rgb(207 0 0);
  }

  /* ... etc ... */
}

fixing the specifics is more web compatible than changing the current behavior after even longer.

To be clear, this issue blocks actually carrying out #8738. The more we mess around with the details here, the higher the risk that no change will happen at all.

[LeaVerou]

To be clear, this issue blocks actually carrying out #8738. The more we mess around with the details here, the higher the risk that no change will happen at all.

That was not the resolution at all. Please implement the @nest rule as currently specced by @tabatkins. It is far, far easier to change the details of that than to change the current behavior of nesting later. That's the whole point of the resolution we made on Wednesday!

[andruud]

@LeaVerou Oh. I thought the point of the resolution was to focus the discussion and hopefully converge on something.

Unfortunately I can't make a move on @nest until this issue is resolved. I will likely not be able to ship a breaking change with the intent to break it again later, especially when there's no consensus on what the follow-up change would be.

It is far, far easier to change the details of that than to change the current behavior of nesting later.

The specific changes we're discussing here can not necessarily be made later at all. It is sometimes very hard to understand the risk of changing CSSOM APIs.

[Loirooriol]

@andruud It's not with the "intent to break it again later". It's with the intent to keep @nest as a better option than the "shifting up", but leaving the door open to explore other possibilities.

The specific changes we're discussing here can not necessarily be made later at all.

If later on we prefer to switch to something else but it's not compatible, then so be it, we can stay with @nest.

The point is that there was consensus that @nest is better than "shifting up". Exploring other possible approaches shouldn't block @nest, since delaying it will just make it not compatible.

[tabatkins]

As I said in my final comment in 8738, when considering any new feature, or additional complexity in an existing feature, it's worth paying attention to both the size of the affected audience and the size of the benefit that audience will receive.

The existence of an @nest rule is visible solely to authors who are crawling the CSSOM, or serializing the OM and then looking at it. Both of these are advanced use-cases, they're not something that 99% (and I think that's a very conservative percentage) of authors will ever do. I, myself, have never inspected the CSSOM in my entire webdev career except when writing WPTs.

So, the audience of people affected by any change here is very tiny, I'll argue, and that audience is composed of relatively skilled authors. (I think this audience can be reasonably summarized as "people who are writing CSS tooling".)

Do any of these changes allow that audience to do something currently difficult or impossible? No, these are solely attempting to improve the consistency of how the OM is represented in certain aspects.

Do they improve this audience's experience in a meaningful way? Arguable. While they improve the consistency in some ways (making the OM and/or the reserialized string more closely resemble the originally authored code), they reduce consistency in other ways (unusual serialization rules; edge cases that require restrictions on where rules can be moved around; widening of the possible types in certain attributes).

For example, right now you can, in theory, take any of the objects in an MQ's .cssRules list and move it out of that MQ, appending it to the stylesheet itself. If the object here is a CSSStyleDeclaration, what happens? Is that an error? If it's a CSSNestRule, but we have special serialization rules that make it look like raw declarations, how does it serialize in this case? (Or, again, maybe it causes an error?)

Or take .insertRule(). Its first argument is a string, which is parsed to obtain a rule to insert. (You can pass a rule object directly, but it's serialized and then re-parsed.) If you can't write @nest directly in a stylesheet, how do you insert such a rule? Do we have to now accept code like x.insertRule("color: blue;"), which is invalid today?

Or a parsed stylesheet will never have an @nest at the start of a style rule, or next to each other. But via CSSOM manipulation you can construct such situations. How do they serialize? Will you still end up with a stylesheet that parses into a different OM than it started from

Whatever we do, if it's "magic" in some way, it'll spawn corner cases like this. Magic like this can be justified, by sufficient benefit to a sufficient audience. I don't think that it qualifies on either metric in this case, however.

In summary, we should just do the simplest possible thing, with the least amount of magic possible, because all of the suggested magic (beyond the initial parser magic) won't actually pay for itself.

[tabatkins]

Do we need the @nest part of the rule? Can we use naked {}? Looking at css-syntax, I don't immediately see why not.

We could, it would just be a new syntax construct to define. Relying on the existing at-rule syntax just makes for a slightly simpler model. And since we don't anticipate authors actually writing this themselves, I don't think the length of the name actually matter in any meaningful way.

[LeaVerou]

@andruud

@LeaVerou Oh. I thought the point of the resolution was to focus the discussion and hopefully converge on something.

Unfortunately I can't make a move on @nest until this issue is resolved. I will likely not be able to ship a breaking change with the intent to break it again later, especially when there's no consensus on what the follow-up change would be.

It is far, far easier to change the details of that than to change the current behavior of nesting later.

The specific changes we're discussing here can not necessarily be made later at all. It is sometimes very hard to understand the risk of changing CSSOM APIs.

We are trying to avoid a breaking change by shipping @nest in some shape or form. @tabatkins is arguing right under your comment that how we implement this in the OM only affects a tiny fraction of authors. You are saying that it would be a breaking change and that "it’s very hard to understand the risk of changing CSSOM APIs". It may be productive if you two have a breakout to align on this, since you work at the same company? Because unless I’m missing something, I don't see how both statements can be true (it is both impactful and not impactful).

@tabatkins

As I said in my final comment in 8738, when considering any new feature, or additional complexity in an existing feature, it's worth paying attention to both the size of the affected audience and the size of the benefit that audience will receive.

Tab, nobody is disagreeing that I/E matters, we’re disagreeing on what the I is.

The existence of an @nest rule is visible solely to authors who are crawling the CSSOM, or serializing the OM and then looking at it. Both of these are advanced use-cases, they're not something that 99% (and I think that's a very conservative percentage) of authors will ever do. I, myself, have never inspected the CSSOM in my entire webdev career except when writing WPTs.

I have responded to this point in the OP:

I strongly disagree with Tab that reading and modifying the CSS OM only affects about a hundred developers in the entire world (!). Reading and modifying the CSS OM is at the core of a ton of very widespread libraries (e.g. jQuery, D3, etc). Even if most authors do not use it directly, I assure you almost every developer reads and modifies the CSS OM regularly, it's just done through several layers of abstractions.

Also, since we’re sharing anecdotes, I have crawled and modified the CSS OM dozens of times in my web dev career, none of which was while writing WPTs. I did not mention it earlier because as an anecdote, I didn’t think it was that relevant.

So, the audience of people affected by any change here is very tiny, I'll argue, and that audience is composed of relatively skilled authors. (I think this audience can be reasonably summarized as "people who are writing CSS tooling".)

Again, the users of these tools are not a small audience.

For example, right now you can, in theory, take any of the objects in an MQ's .cssRules list and move it out of that MQ, appending it to the stylesheet itself. If the object here is a CSSStyleDeclaration, what happens? Is that an error? If it's a CSSNestRule, but we have special serialization rules that make it look like raw declarations, how does it serialize in this case? (Or, again, maybe it causes an error?)

I don’t see how this is different than defining what @nest {} does in the root scope. We’ll have to define something however you look at it. And if anything, defining what root-level declarations do is actually quite useful (anecdotally, I’ve written special code to handle raw declarations at the root level several times when coding CSS demos).

Actually, depending on how we define it root-level declarations could even solve all these use cases that require setting stuff on the document node.

Or take .insertRule(). Its first argument is a string, which is parsed to obtain a rule to insert. (You can pass a rule object directly, but it's serialized and then re-parsed.) If you can't write @nest directly in a stylesheet, how do you insert such a rule? Do we have to now accept code like x.insertRule("color: blue;"), which is invalid today?

Yes! Which again seems like a win and more broadly useful.

Or a parsed stylesheet will never have an @nest at the start of a style rule, or next to each other. But via CSSOM manipulation you can construct such situations. How do they serialize? Will you still end up with a stylesheet that parses into a different OM than it started from

I’m not married to the details, but I was envisioning that these nodes would be merged automatically by the CSS OM, not during serialization. All the Web Platform’s OMs are full of these kinds of normalizations, so I don’t see what the problem is.

[tabatkins]

The users of tools that crawl/modify the CSSOM only matter for this proposal insofar as those tools expose the CSSOM to them (or this proposal makes those tools work better, thus improving the experience of their users). Do you have examples of that?

I don’t see how this is different than defining what @nest {} does in the root scope.

Sure, we have to define what @nest does in the global scope, in exactly the same way we defined what & matches in the global scope. (And it's currently defined to act exactly the same.) But these additional things are more corner cases to define.

Yes! Which again seems like a win and more broadly useful.

How is this a meaningful win over x.insertRule("@nest { color: blue; }")? I mean, it's very slightly shorter, sure. But does it matter otherwise? Is it worth the consistency loss of insertRule() no longer being restricted to taking rules?

I’m not married to the details, but I was envisioning that these nodes would be merged automatically by the CSS OM, not during serialization. All the Web Platform’s OMs are full of these kinds of normalizations, so I don’t see what the problem is.

I don't think that's accurate to say. For example, in the following:

<!DOCTYPE html>
<p>
<script>
var p = document.querySelector("p");
p.appendChild(new Text("foo"));
p.appendChild(new Text("bar"));
console.log(p.childNodes);
</script>

You'll get two Text nodes, despite that being essentially identical to just having a single Text node with "foobar". Having nodes magically merge underneath you as a side-effect of doing something unrelated (like removing a rule that previously happened to separate two of them) is the sort of thing that causes bugs in author code very easily, since objects disappear, indexes change, etc. in an unpredictable manner.

[andruud]

Do we need the @nest part of the rule? Can we use naked {}? Looking at css-syntax, I don't immediately see why not.

We could, it would just be a new syntax construct to define. Relying on the existing at-rule syntax just makes for a slightly simpler model. And since we don't anticipate authors actually writing this themselves, I don't think the length of the name actually matter in any meaningful way.

Yeah, sure. {} was a response to @romainmenke's world where authors might actually want to write it themselves. If @nest{} basically does nothing (except add structure), perhaps {} is a better way to represent it (and more in line with other languages).

Because unless I’m missing something, I don't see how both statements can be true (it is both impactful and not impactful).

That is not what I'm saying. I'm saying it's not always easy to prove that CSSOM changes won't break sites, even if you strongly believe it won't.

---

But OK, if shipping @nest ASAP is indeed what everyone wants here, I can try. I'll need positions from Apple and Mozilla. (EDIT: mozilla/standards-positions#1013, WebKit/standards-positions#337).

[LeaVerou]

If we have author facing syntax for this, I'd prefer it's not {} so we can reserve {} for something that is actually useful (of course this changes if we can figure out a way to make @nest {} useful).

---

But OK, if shipping @nest ASAP is indeed what everyone wants here, I can try. I'll need positions from Apple and Mozilla. (EDIT: mozilla/standards-positions#1013, WebKit/standards-positions#337).

Thank you!

[dbaron]

One question that would affect my opinion of whether the CSSOM questions here matter: what's the chance that at some point in the future we'll allow the nesting syntax inside the style attribute? (This sort of syntax has been proposed and specified in the past, but it didn't get traction at the time.) I think the CSSOM is much more relevant for the style attribute than it is for style sheets, since it's more widely used there.

[cdoublev]

3. No @nest, just CSSStyleDeclaration in the CSSOM
   • Criticism: That means .cssRules will also return non-rules? Would .insertRule() also accept CSSStyleDeclaration?

I am not sure I understood the whole conversation between mdubet and emilio about this in #8738, but intermixing list of declarations (or CSSStyleDeclarations) and rules in specified order in an internal property (eg. contents) seemed like an idiomatic solution.

The first list of declarations in contents should be exposed by style. .cssRules and .insertRule() should ignore lists of declarations in contents. .deleteRule() should eventually move declarations into the first list. It does not seem that painfull.

I did not understood why contents would need to be exposed by the public .cssRules. I guess in order to add declarations after rules via the CSSOM. Assuming there is a need for this, a new interface like .insertDeclaration() and/or styles could be defined.

But accepting declarations in .insertRule(), ugh. 😬

[LeaVerou]

One question that would affect my opinion of whether the CSSOM questions here matter: what's the chance that at some point in the future we'll allow the nesting syntax inside the style attribute? (This sort of syntax has been proposed and specified in the past, but it didn't get traction at the time.) I think the CSSOM is much more relevant for the style attribute than it is for style sheets, since it's more widely used there.

My understanding is that this is basically planned, and it's just a matter of resource allocation. Inline style nesting is a huge use case.

---

Since it seems hard to get consensus on making this rule less author facing, could we explore going the other way? I.e. keeping is as author-facing, and trying to make it useful in some way.

Some ideas:

• Someone mentioned that it could be used for grouping. That definitely makes sense. Other threads discuss a potential @sheet rule that basically does named grouping. I wonder if these two could be combined.
• Keeping fallbacks around that can be used for IACVT
• Simple style() conditionals on the current element? Or some other way to toggle these groups on or off or pick among two?

Just brainstorming here. What would be some low hanging, easy-ish to implement functionality that could make this rule actually useful?

Perhaps we should simply name it @group and allow an optional <dashed-ident> before the {, then we can figure out later what these can be used for.

[emilio]

I did not understood why contents would need to be exposed by the public .cssRules. I guess in order to add declarations after rules via the CSSOM. Assuming there is a need for this, a new interface like .insertDeclaration() and/or styles could be defined.

You really want authors to be able to see all the styles in the stylesheet, in the right order. If cssRules doesn't do that you need something else.

[emilio]

Another thing to note, not sure how well this interacts with @scope... @andruud / @dshin-moz / @tabatkins / @mirisuzanne, do you know off-hand?

IIRC we either stash an implicit :scope in the selector (but we can't with @nest, because there's no selector), or use the & which now includes the start bound, right? At least I recall a weird interaction between nesting and @scope, but I don't recall the specifics...

That is, what does:

#a {
  ...

  @scope (#b) {
    color: red;
  }

desugar to now? What would desugar to with @nest and would it work correctly?

[mdubet]

@emilio Nothing different for @scope than the other nested group rules : we currently wrap the declarations in & which desugar to :is(#b) (because the <scope-start> acts as a parent selector).

Exploring the use cases for a more general @group rule is a good path forward (even just changing the name to anything less specific than @nest is a progression imho)

[emilio]

Oh, so the fact that the scope rule is inside the #a selector is completely lost already? That's a bit weird / unintuitive but ok I guess

[andruud]

completely lost

Maybe it's not what you meant, but it's not completely lost, it's in the implicit & in the <scope-start>:

#a {
  ...
  @scope (& #b) {
    @nest {
      color: red;
    }
  }

I think that will be just fine.

---

Perhaps we should simply name it @group and allow an optional <dashed-ident> before the {, then we can figure out later what these can be used for.

I support this too.

Although we could easily add a <dashed-ident> to the prelude later, if/when we have a good reason for it. Maybe we just ship @group {} for now, leaving the prelude wide open for whatever we come up with later.

[emilio]

Ah, cool, It's added to the start of the scope, that seems fine then I agree.

I don't mind calling it @group (but if we do so then it probably should be a grouping rule after all, and not be restricted to declarations...)

[andruud]

I don't mind calling it @group (but if we do so then it probably should be a grouping rule after all, and not be restricted to declarations...)

Yes, agree.

[romainmenke]

So authors could (but likely won't) write :

:root {
  @group {
    --color-a: pink;

    @media screen { --color-a: red; }

    --color-b: lime;
  }
}

Which would be equivalent to :

:root {
  @group {
    --color-a: pink;

    @media screen { --color-a: red; }

    @group { --color-b: lime; }
  }
}

[LeaVerou]

Although we could easily add a <dashed-ident> to the prelude later, if/when we have a good reason for it. Maybe we just ship @group {} for now, leaving the prelude wide open for whatever we come up with later.

The thinking was to support this kind of usage.

It would be nice though if we could come up with some actual useful functionality for these groups other than simple grouping. Are any of the things I mentioned here feasible?

[andruud]

To be clear, this issue blocks actually carrying out #8738. The more we mess around with the details here, the higher the risk that no change will happen at all.

That was not the resolution at all. Please implement the @nest rule as currently specced by @tabatkins. It is far, far easier to change the details of that than to change the current behavior of nesting later. That's the whole point of the resolution we made on Wednesday!

With WebKit's position now clarified, and after some feedback on the Blink Intent-to-Ship, it's pretty clear that this issue is in fact blocking #8738.

[mirisuzanne]

This is a long-shot, not well thought-through - but is there a way for named-group declarations to be available as a form of name-spaced custom property. I don't think this would provide actual new functionality, but some syntax shortcuts for name-spacing and declaring a custom/standard property at the same time:

.now {
  --base-padding: 1em;
  padding: var(--base-padding);

  --color-primary: teal;
  --color-secondary: hotPink;
}

.groups {
  @group --base {
    padding: 1em;
  }

  @group --color {
    --primary: teal;
    --secondary: hotPink;    
  }
  
  .access {
    margin: var(--base.padding);
    border-color: var(--color.--primary);
  }
}

(Hope I'm not straying too far from the question at hand - but it seems like an otherwise-useful rule might help with WebKit's concerns?)

[css-meeting-bot]

The CSS Working Group just discussed [css-syntax][css-nesting] Design of `@nest` rule, and agreed to the following:

• RESOLVED: 1. Introduce a CSSNestedDeclarations object inheriting from CSSRule and having a .style accessor, and use that to represent the declaration lists in a CSSStyleRule. It serializes as a raw declaration list. 2. Extend .insertRule() to parse declarations (or, if Web-compat requires, add .insertDeclarations()) into a CSSNestedDeclarations Object. 3. Open a new issue wrt the first declarations block.

The full IRC log of that discussion

<keithamus> emilio: Leah added this, I can introduce it a bit
<keithamus> ... there still seems to be some disagreement on best path forward
<astearns> could we resolve on @some-long-weird-name?
<Rossen4> s/Leah/Lea/
<keithamus> lea: the gist is another issue we resolved to stop hosting decls coming after nested rules, with decls inside a rule coming after get hoisted to the top which results in strange conflict resolution
<keithamus> lea: Tab proposed the @ rule which avoid this. There was push back as it only exists in the OM and has no purpose for authors, only exists to make spec editors lives easier
<fantasai> s/in the OM/for the purpose of the OM/
<Rossen4> q
<keithamus> ... there are some challenges to not introducing. One proposal to have the @nest rule but not serialize, so you only get plain decls.
<keithamus> ... Tabs opposition is that CSSOM isn't used that much so whats the point
<keithamus> ... another proposal to make a new object to represent the interleaved decls.
<keithamus> ... Blink is strongly opposing not having the rule
<keithamus> ... On the grounds that CSSOM is not used frequently
<keithamus> ... also that syntax is pointless from author perspective
<keithamus> ... what if we call it @group then extend it later with functionality? What if we can give this rule a purpose?
<TabAtkins> q+
<kizu> +1 to "<@astearns> could we resolve on @some-long-weird-name?"
<keithamus> ... my position is that I tend to agree with webkit. Against priority of constituencies. People will find some weird ways to use it
<keithamus> ... I disagree with Tab's assertion that CSSOM is infrequently used.
<keithamus> ... We do plan to eventually add nesting & author styles - extremely author facing.
<emilio> q+
<keithamus> ... many devs modify css properties on the fly, indirectly or not. It's extremely author facing
<keithamus> ... I worry if we can't reach consensus we're stuck with status quo - the hoisting behavior, which is worse than any solutions proposed
<keithamus> ... I'd be happier with @nest vs hoisting
<keithamus> ... even though I'm opposed
<miriam> +1 current behavior is worse than any of the proposals
<keithamus> Rossen4: we can bikeshed later on naming. Prefer path forward suggested by Alan with @some-long-weird-name and bikeshed later
<Rossen4> ack fantasai
<keithamus> fantasai: webkit is opposed to new @ rule for the purpose of making it easier to specify CSSOM. Only reason this rule is being proposed. We don't think that's good for authors
<keithamus> ... flexible to what form the OM does take.
<keithamus> ... we posted one that we think gives some useful interfaces for authors. If people don't like it we're flexible
<keithamus> ... but one thing we're opposed to is this thing that gets parsed out
<Rossen4> ack TabAtkins
<keithamus> TabAtkins: lea's characterization of my position is incomplete. Creating things in the OM is vary rarely used. Crawling via .style or other - there's no meaningful difference. Creating an OM from scratch is only where you'd see the difference. That's incredibly rare to do. Only CSS tooling does it
<keithamus> ... the set of authors we're effecting positively or negatively is minuscule, and these authors are advances. We don't want to give them bad stuff just because, but we trust them to navigate this
<keithamus> ... webkit proposal give us genuinely worse tradeoffs. When you serialize you get something useful but insert rule or manip gets magical in a bad way, where insertrule might merge or insert before or after. Deleting rules has odd behavior as well
<keithamus> ... two decls next to eachother need to be resolved.
<keithamus> ... unexpected tree structure munging is difficult to work with as a user of the API
<keithamus> ... bikeshed represents HTML structure of the doc with a well used XML library but it sucks for HTML. APIs are hard to predict and has inconsistent behavior with text nodes as you're moving around element nodes
<keithamus> ... I used to have bugs in bikeshed due to this. I reimplemented the DOM and used the DOM wrapper just because DOM treats text and other nodes the same, a predictable behavior.
<keithamus> ... similar using an @ rule of some kind means we don't do any weird magic with OM manip.
<keithamus> ... We have consistent behavior, nothing weird needs to happen with add/remove. No cleanup
<keithamus> ... simplifies impl and specs. Importantly it makes manipulation predictable for the author which is far more important to maintain
<keithamus> ... if necessary we're fine with having a serialization rule which most of the time omits @ nest. Anything you parse in can always serialize back out without showing the rule. It just relies on adding one serialization quirk, which you'll never notice unless you're creating rules which couldn't be produced by the parser.
<keithamus> ... in all other cases it'll be invisible. This is acceptable to us
<keithamus> ... I think it's a bad idea to complicate the data model with magic.
<Rossen4> ack emilio
<keithamus> emilio: I wanted to say similar. What lea said implied the model consistent only helps browser/spec editors, I don't think that's true. Let's not overcomplicate the solution.
<lea> q?
<keithamus> ... having extra @ rule vs having to invent weird stuff... the trade-off is clear for me.
<Rossen4> ack fantasai
<Zakim> fantasai, you wanted to clarify that a bunch of what Tab objects to is not something we're requiring and to clarify that most of what Tab objects to is not something we're
<Zakim> ... requiring
<fantasai> https://github.com//issues/10234
<keithamus> fantasai: Tab is referring to this
<fantasai> https://github.com//issues/10234#issuecomment-2116380146
<keithamus> fantasai: which is one proposal which we suggested as a possibility. We clearly said we're flexible how it's represented in the CSSOM
<TabAtkins> q+
<emilio> q+
<keithamus> ... so the long spiel about merging, that's objectionable, we can drop it
<keithamus> ... what we were proposing is that we introducing a CSS Nested Declaration object inherit from CSSStyleRule, it has accessors... when you use insertrule, and there happens to be an adjacent rule, you'd merge the declarations into that.
<keithamus> ... if that's a problem we don't have to do that.
<keithamus> ... the only thing we're stating is that it serializes without an at-rule. Consequence is not merging in CSSOM when you serailize and parse it back in 2 objects get merged together.
<keithamus> ... we think this is acceptable vs a new at-rule to avoid it.
<fantasai> "We would also be OK with alternative solutions that don't introduce an at-rule"
<fantasai> idk how to get more explicit than that
<keithamus> TabAtkins: if that's the constraint it would be good to express it. It seemed like it was requiring more magic. Serialization & reparsing.. I don't care too much about that, as long as tree manip doesn't do unpredictable magic
<Rossen4> ack TabAtkins
<keithamus> ... changing behavior of insert rule to allow declaration lists... currently it throws but the OM API is old. It's always unpredictable if things like this are compat issues.
<keithamus> ... if it's purely a matter of producing some sort of object, call is CSSDeclarationList, and it serializes declarations, and you're ok with it changing structure when you roundtrip, I'm okay with that
<Rossen4> ack emilio
<keithamus> ... but all the magic proposed in thread was what I was objecting to
<keithamus> emilio: I still prefer avoiding rounttripping. Apples proposal without the extra magic is basically @nest without saying @nest.
<TabAtkins> Note again that "just doing an at-rule" also always serializes as bare declarations *as long as you haven't used OM manipulation to do something funky*.
<keithamus> ... that's not amazing but that seems way better than the original tree-monkeying stuff
<Rossen4> ack dbaron
<TabAtkins> Or network packet delays can cause separate text nodes, I think, directly from the parser.
<keithamus> dbaron: Wanted to point out the idea you get a different OM when you serialize and reparse is something we already have with HTML: emtpy text nodes or adjacent text nodes. DOM has an API to normalize these.
<Rossen4> q?
<dbaron> https://developer.mozilla.org/en-US/docs/Web/API/Node/normalize
<keithamus> Rossen4: are we getting close? The original proposal in IRC seems to be landing okay?
<Rossen4> ack fantasai
<fantasai> PROPOSAL:
<fantasai> 1. Introduce a CSSNestedDeclarations object inheriting from CSSRule and having a .style accessor, and use that to represent all the declaration lists in a CSSStyleRule. It serializes as a raw declaration list.
<fantasai> 2. Extend .insertRule() to parse declarations (or, if Web-compat requires it, add .insertDeclarations())
<fantasai> 3. Open question about the first declaration block.
<keithamus> fantasai: we should handle 3 as a follow up
<emilio> q+
<keithamus> emilio: to be honest I still prefer a regular rule than bare decls, but this is a fine compromise if people are unwilling
<Rossen4> ack emilio
<fantasai> s/())/()) into a CSSNestedDeclarations object/
<keithamus> TabAtkins: I don't think first decl block is an open question. We still have weird magic behavior. The first block of stuff is definitely put in a stylerules.style not reflected in child rules
<keithamus> fantasai: 100%. I think theres a question about if its also represented in CSS rules.
<keithamus> emilio: I don't think putting it in 2 places is great
<keithamus> TabAtkins: I don't think we can. If you delete the first block you'll be invoking magic behaviour
<keithamus> ... we'll have to re-create at some point. Exactly the magical behavior I want to avoid
<keithamus> emilio: that's true.. calling delete rule would be weird
<keithamus> fantasai: if we do this authors can have a single consistent API for all of the contents of the style rule
<keithamus> TabAtkins: If we were designing these from scratch I'd agree
<keithamus> ... but with history, the only way to maintain it safely would be additional magic with delete rule. I want to avoid the tree magic as much as possible
<keithamus> fantasai: can we open that conversation separately?
<keithamus> TabAtkins: I can guarantee my position but the others, mild objections, but this is acceptable
<keithamus> Rossen4: Can we summarise the compromise?
<keithamus> TabAtkins: In the proposal
<keithamus> Rossen4: all 3?
<keithamus> fantasai: 3rd isn't really a thing
<keithamus> Rossen4: any additional points or objections>?
<keithamus> s/>?/?
<fantasai> 1. Introduce a CSSNestedDeclarations object inheriting from CSSRule and having a .style accessor, and use that to represent all the declaration lists in a CSSStyleRule. It serializes as a raw declaration list.
<keithamus> lea: can someone restate the proposal?
<fantasai> 2. Extend .insertRule() to parse declarations (or, if Web-compat requires it, add .insertDeclarations())
<fantasai> s/())/()) into a CSSNestedDeclarations object/
<keithamus> lea: that seems great
<keithamus> Rossen4: I'll call this resolved
<fantasai> RESOLVED: 1. Introduce a CSSNestedDeclarations object inheriting from CSSRule and having a .style accessor, and use that to represent the declaration lists in a CSSStyleRule. It serializes as a raw declaration list. 2. Extend .insertRule() to parse declarations (or, if Web-compat requires, add .insertDeclarations()) into a CSSNestedDeclarations Object. 3. Open a new issue wrt the first declarations block.

[LeaVerou]

Possibly too late to change the design, but I just had an idea: What if we do introduce the rule, call it @group, and instead of introducing identifiers in the preamble, we have a revert-group value that would work similarly to revert-layer, i.e. would revert the declaration to what it would have been if the group was not applied.
Then groups have a purpose that is not turned on by default (making them suitable for representing nested declarations) but is still super useful: they allow authors to override the IACVT behavior with an actual fallback! This is especially useful in combination with something like if():

@group {
	border-radius: if(style(--button-shape: pill), infinity, revert-group);
}