[css-properties-values] CSSOM for multi-name and shorthand `@property`

[LeaVerou]

In #7523 (comment) we resolved to adopt a comma-separated syntax for <custom-property-name> to support registering multiple properties that share the same descriptors in one go.

However, we do not seem to have consensus on the best CSSOM to represent this.

Opening this so we can discuss without clobbering the shorthand syntax discussed in #7523, though the design should also take it into account.

Discussion

Requirements

• Existing single-name @property rules MUST produce the same CSSOM
• Any syntax that only fans out on name only (e.g. CSSPropertyRule.prototype.names) will have trouble once the shorthand syntax syntax is introduced ([css-properties-values-api] Shorthand for custom property declaration #7523)

Nice to haves

• Roundtripping. Plenty of places where CSS doesn't roundtrip, so not a biggie if it doesn't, but it's nice if it does.
• Authors should not need to parse property names and split by commas. This will get very awkward once [css-properties-values-api] Shorthand for custom property declaration #7523 is introduced, as they'll now need to parse a full blown microsyntax.
• CSSPropertyRule.prototype.name is read-only so we don't need to answer the question "how does the setter behave?". That said, it would be nice if the design did not actively get in the way of making it writable later.

Options

Option 1: Expand to multiple CSSPropertyRule rules at parse time

No CSSPropertyRule changes. The rule just expands to multiple CSSPropertyRule rules at parse time.

Pros:

• No CSSOM changes
• Supports almost any future syntax
• Authors don't need to parse any microsyntax
• Backwards compatible with existing consumers

Cons:

• No roundtripping
• Making name writable later would be hard
• insertRule() can insert multiple rules, which is weird

Option 2: name/names

This includes:

1. name includes the full comma-separated list, no other change
2. name includes the full comma-separated list, names as a FrozenArray
3. name is empty when multiple names, names as a FrozenArray

Pros:

• Serialization roundtrips

Cons:

• All of these special case the name fanout, unclear how this expands to the syntax shorthand. In theory we could add plural versions of all descriptors as shorthands are added (syntaxes etc), but we need to keep multiple arrays in sync, which is awkward
• For 2.1: Authors need to do their own parsing, which will get even more complex with the shorthand expansions

Option 3: Nested CSSPropertyRule

CSSPropertyRule gains a cssRules property which is a CSSPropertyRule[]. Its properties represent base values as specified in the actual rule, but child rules can override them.

Single-property usage is backwards compatible, consumers need to be updated to read multi-property rules correctly.

Pros:

• Most faithful representation, objects correspond exactly to what was written
• Roundtrips correctly
• Scales better to future syntax extensions like shorthand types, nesting etc
• Even supports a future writable name — it would just generate cssRules.

Cons:

• Biggest lift, incompatible with code consuming the existing schema
• Requires additional design decisions for every single descriptor on the root object
  • What would name be? Empty? A comma-separated list? The first name?
  • What would syntax be once we have the shorthand syntax? Empty? A union of all? The first one?
  • etc

---

I’m moderately strongly against 2, but I'm fine with 1 or 3.

I originally recommended 1 as I think it would be unfortunate to gate this feature on a big CSSOM change, but 3 is the "proper" way, and can scale to cover a lot of future expansion.

[emilio]

There are other options, like 2 but multiple names return empty for name. That's somewhat similar to what we did for @container when we added multiple conditions: #13635. We could do something like that? It's pretty simple. Not sure what the 'authors need to do their own parsing' concern is about?

Potential writable names and so on are also not a concern, IMO. These interfaces should be kept read-only unless there's extremely good reason to do otherwise, we resolved on making the OM as readonly as possible quite a while ago.

[LeaVerou]

There are other options, like 2 but multiple names return empty for name.

I added this to the post. Is this an example or do you have more options in mind?

That's somewhat similar to what we did for @container when we added multiple conditions: #13635. We could do something like that? It's pretty simple.

That works for @container because the prelude is a separate thing from the contents, similarly to a media query or even a regular CSS rule. Here once we add the shorthand syntax, the prelude is basically setting descriptors that normally live in the rule itself (which also brings up a question about serialization…).

Not sure what the 'authors need to do their own parsing' concern is about?

It was specific to the option where name holds the whole thing. Clarified in the OP.

Potential writable names and so on are also not a concern, IMO. These interfaces should be kept read-only unless there's extremely good reason to do otherwise, we resolved on making the OM as readonly as possible quite a while ago.

Yes, I don't see it happening anytime soon, but still good to keep options open. We've reversed many things we said we'd never do. It's only a nice-to-have, and I'd give it pretty low weight.

[Loirooriol]

unclear how this expands to the syntax shorthand

What do you mean with the syntax shorthand?

[LeaVerou]

unclear how this expands to the syntax shorthand

What do you mean with the syntax shorthand?

The @property --name <syntax>: initial-value, --name2 <syntax2>: initial-value2, ... shorthand discussed in #7523

[Loirooriol]

Isn't it the other way round, that the shorthand statement syntax would expand to the normal rule syntax? So I'm not sure why it would be a concern here. I'm not getting the "plural versions of all descriptors" thing.