[css-cascade-5] Add a R/W `CSSStyleSheet.layer` attribute for the layer name

[xiaochengh]

(Edit: fixed some details on settings)

I'm proposing extending the CSSStyleSheet interface with a new attribute, layer.

On getting, it should return the layer name if the sheet is entirely in some cascade layer. In particular:

• If this is an @import-ed stylesheet, return the layerName attribute value of the CSSImportRule
• If this stylesheet is added via a <link> element (depending on Allow authors to apply new css features (like cascade layers) while linking stylesheets whatwg/html#7540), then return the name of that layer
• If this is a constructed stylesheet with a layer name previous set by JS (see below), return that layer name
• Otherwise, return null

On setting:

• If this is a constructed stylesheet and the new value is a non-null string, then the attribute value can be modified, and the stylesheet is treated as entirely in the given layer
• If this is a constructed stylesheet and the new value is null, then the attribute value can be modified, and the stylesheet is treated as unlayered
• Otherwise, throws a NotAllowedError DOMException

The primary use case is to allow adding layered constructed stylesheets, especially if the stylesheet is a 3rd party CSS module, and we want to use that to set up a web component (which we currently don't have a good way to make it layered):

import sheet from 3p-foo.css;

sheet.layer = 'new-layer';
shadowRoot.adoptedStylesheets = [sheet];

[tabatkins]

Sounds good to me; this is an obvious hole currently both on the reading side (can't tell from inspection if a stylesheet was imported or linked with a layer) and on the writing side (can't have constructed sheets with the equivalent functionality of importing/linking into a particular layer).

[fantasai]

How should anonymous layers work? Maybe represent them with the empty string?

[xiaochengh]

How should anonymous layers work? Maybe represent them with the empty string?

Yes. This is also consistent with how CSSImportRule.layerName distinguishes importing into an anonymous layer (empty string) vs. not importing into any layer (null).

[tabatkins]

Ah, we should match that name, too, and use .layerName on CSSStyleSheet.

[tabatkins]

(Or switch them both to .layer.)

[css-meeting-bot]

The CSS Working Group just discussed Add a .layer attribute to CSSSTyleSheet, and agreed to the following:

• RESOLVED: Add .layerName to CSSStyleSheet as a readonly attribute.

The full IRC log of that discussion

<TabAtkins> Topic: Add a .layer attribute to CSSSTyleSheet
<TabAtkins> github: https://github.com//issues/7002
<TabAtkins> fantasai: So it just seemed reasonable to add, and discussion suggests it should be called .layerName to match the CSSLayerRule
<TabAtkins> astearns: And using .layerName is preferable to switching both to .layer?
<TabAtkins> fantasai: I'm open to both.
<smfr> prefer layerName
<TabAtkins> astearns: I think .layerName does suggest a string rather than an object, so it seems slightly more clear
<emilio> q+
<astearns> ack emilio
<TabAtkins> emilio: does @import allow us to set this on import, so we can make it immutable?
<fantasai_> TabAtkins: If this stylesheet is reflecting from a <link>, that's changeable in HTML
<fantasai_> TabAtkins: maybe we could make it immutable in the API?
<TabAtkins> emilio: Link mutations already have steps to recreate the stylesheet object
<TabAtkins> emilio: So that would trigger the same as changing media=''
<TabAtkins> emilio: Which creates a new stylesheet
<TabAtkins> TabAtkins: What about constructed stylesheets?
<TabAtkins> emilio: Hopefully we can set it in the constructor - it already has an option bag for things like baseURI, which also is immutable. Hopefully we can follow the same pattern.
<TabAtkins> TabAtkins: I'm fine with that.
<TabAtkins> emilio: The original issue uses @import syntax, which requires using an extra argument object somewhere to preserve the mime type...
<TabAtkins> TabAtkins: Don't understand
<TabAtkins> emilio: When you use importSheet()
<TabAtkins> scratch last line
<TabAtkins> emilio: When you use `import sheet from style.css`, can you set the layer there?
<TabAtkins> emilio: I think in JS you have a trailing object that lets you set the mimetype?
<TabAtkins> TabAtkins: Yes, but I'm unsure whether that's meant to be just assertions or can have extra data
<TabAtkins> astearns: Sounds like we can resolve on .layerName?
<TabAtkins> TabAtkins: And on makign it readonly unless that's killer for the JS ipmort syntax
<TabAtkins> emilio: Agreed
<TabAtkins> astearns: objections?
<TabAtkins> RESOLVED: Add .layerName to CSSStyleSheet as a readonly attribute.
<emeyer> scribenick emeyer

[xiaochengh]

If it's a readonly attribute, how do we support the JS import syntax (which is the major use case I'd like to support)? We don't explicitly call its constructor so we can't pass the layer name in that way.

<TabAtkins> emilio: When you use import sheet from style.css, can you set the layer there?
<TabAtkins> emilio: I think in JS you have a trailing object that lets you set the mimetype?
<TabAtkins> TabAtkins: Yes, but I'm unsure whether that's meant to be just assertions or can have extra data

@tabatkins When you said "yes", were you talking about setting the layer or the mimetype?

[tabatkins]

"yes" to trailing object; I just wasn't sure if it's meant to be able to carry additional data beyond the mime type.

[xiaochengh]

Then the resolution is inadequate. We still need a way to make it work on the JS-imported style modules. The easiest way that I can see is still to make it writable on constructed stylesheets.

[emilio]

@xiaochengh can't the trailing object carry the layer name? If not, why not?

[xiaochengh]

Sorry I misunderstood. Didn't realize you were talking about import assertion. Yeah, we can pass a layer name there.

There's also one thing that I think we missed in the previous discussion. The same sheet can be imported for multiple times into different layers (e.g., when used by different modules), which means we need to make sure that each import creates a different CSSStyleSheet object. Is this already guaranteed, or do we need more work?