Declarative CSS Modules

[KurtCattiSchmidt]

Adds support for Declarative CSS Modules via <style type="module" specifier="specifiername">. shadowrootadoptedstylesheets is handled in this PR: #12339

• At least two implementers are interested (and none opposed):
  • Chromium
  • …
• Tests are written and can be reviewed and commented upon at:
  • wpt/html/semantics/document-metadata/the-style-element/tentative (see https://wpt.fyi/results/html/semantics/document-metadata/the-style-element/tentative)
• Implementation bugs are filed:
  • Chromium: https://issues.chromium.org/issues/448174611
  • Gecko: https://bugzilla.mozilla.org/show_bug.cgi?id=2037650
  • WebKit: https://bugs.webkit.org/show_bug.cgi?id=314242
  • Deno (only for timers, structured clone, base64 utils, channel messaging, module resolution, web workers, and web storage): N/A
  • Node.js (only for timers, structured clone, base64 utils, channel messaging, and module resolution): N/A
• Corresponding HTML AAM & ARIA in HTML issues & PRs: N/A
• MDN issue is filed: Declarative CSS Module Scripts mdn/mdn#824
• The top of this comment includes a clear commit message to use.

(See WHATWG Working Mode: Changes for more details.)

Addresses #10673

---

/acknowledgements.html ( diff )
/indices.html ( diff )
/infrastructure.html ( diff )
/obsolete.html ( diff )
/scripting.html ( diff )
/semantics.html ( diff )

[Copilot]

Pull Request Overview

This PR introduces declarative CSS modules support to HTML, allowing CSS to be imported as modules through <style> elements with a specifier attribute and <template> elements with a shadowrootadoptedstylesheets attribute.

• Adds a specifier attribute to <style> elements that creates module import maps for CSS content
• Introduces a shadowrootadoptedstylesheets attribute for <template> elements to declaratively adopt CSS modules
• Implements algorithms for creating declarative CSS module scripts and stylesheet adoption

Comments suppressed due to low confidence (5)

source:1

• Missing attribute name in IDL definition. Should be [SameObject, PutForwards=value, Reflect] readonly attribute DOMString <dfn attribute for="HTMLStyleElement" data-x="dom-style-specifier">specifier</dfn>; to match the pattern used for other attributes in this interface.

<!-- -*- mode: Text; fill-column: 100 -*- vim: set textwidth=100 :

source:1

• Grammar error: 'is defines' should be 'defines' - remove the word 'is'.

<!-- -*- mode: Text; fill-column: 100 -*- vim: set textwidth=100 :

source:1

• Grammar error: 'appended with the of the' should be 'appended with the' - remove the duplicate 'the of'.

<!-- -*- mode: Text; fill-column: 100 -*- vim: set textwidth=100 :

source:1

• Logic error: The algorithm references <var>specifier</var> but this variable is not defined in the algorithm. It should reference the value of the shadowrootadoptedstylesheets attribute instead.

<!-- -*- mode: Text; fill-column: 100 -*- vim: set textwidth=100 :

source:1

• Incorrect data-x reference: Should be data-x=\"attr-style-specifier\" not data-x=\"attr-style-blocking\" for the specifier attribute row.

<!-- -*- mode: Text; fill-column: 100 -*- vim: set textwidth=100 :

---

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

[Copilot]

Pull Request Overview

Copilot reviewed 1 out of 1 changed files in this pull request and generated no new comments.

Comments suppressed due to low confidence (9)

source:1

• The IDL attribute should be named to match the content attribute. The content attribute is specifier but the IDL should use camelCase convention: [SameObject, PutForwards=value, Reflect] readonly attribute DOMString specifier; should have a data-x attribute defining the DOM property name.

<!-- -*- mode: Text; fill-column: 100 -*- vim: set textwidth=100 :

source:1

• The shadowrootadoptedstylesheets attribute is listed twice in the content attributes section for the template element. This duplication should be removed.

<!-- -*- mode: Text; fill-column: 100 -*- vim: set textwidth=100 :

source:1

• The shadowrootadoptedstylesheets attribute is listed twice in the content attributes section for the template element. This duplication should be removed.

<!-- -*- mode: Text; fill-column: 100 -*- vim: set textwidth=100 :

source:1

• The algorithm step is missing proper HTML structure. It should end with </li> and the nested <ol> should be properly closed with </ol>.

<!-- -*- mode: Text; fill-column: 100 -*- vim: set textwidth=100 :

source:1

• The variable moduleScript is referenced but never defined in this algorithm. This should likely be the current module script or settings object context.

<!-- -*- mode: Text; fill-column: 100 -*- vim: set textwidth=100 :

source:1

• These variable assignments are missing closing </p> tags. Each should end with </p></li>.

<!-- -*- mode: Text; fill-column: 100 -*- vim: set textwidth=100 :

source:1

• Missing spaces after commas in the parameter list. Should be <var>fetchClient</var>, <var>destination</var>, <var>options</var>, <var>settingsObject</var>, <var>referrer</var> for consistency.

<!-- -*- mode: Text; fill-column: 100 -*- vim: set textwidth=100 :

source:1

• Incorrect data-x reference in the table. Line 148289 should reference data-x=\"element-template\" or similar, not data-x=\"attr-template-shadowrootclonable\".

<!-- -*- mode: Text; fill-column: 100 -*- vim: set textwidth=100 :

source:1

• Incorrect data-x reference in the table. Line 148363 should reference data-x=\"element-style\" instead of data-x=\"attr-style-blocking\".

<!-- -*- mode: Text; fill-column: 100 -*- vim: set textwidth=100 :

---

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

[dandclark]

Review in progress, sharing feedback so far.

[mhochk]

LGTM (No permissions to actually Approve)

[dandclark]

This is coming together nicely. I think the biggest thing still to figure out is to prevent a given <style type=module> from being processed twice. I'm about to head out on leave so I'm going to Approve this since I'm supportive of the direction and I trust that the remaining open issues will be handled appropriately.

[dandclark]

I guess this is also the point where we'd also check a new equivalent of the already started flag to ensure a given <style type=module> only ever gets processed once?

[KurtCattiSchmidt]

Yeah I'll have to think about this a little more. I will likely bring this up soon with the WHATWG.

[annevk]

It doesn't seem like this got addressed one way or another?

[KurtCattiSchmidt]

I'll bring this part up at the next meeting

[dandclark]

Create an import map parse result can throw -- do we need to handle any of those cases? The one I particularly had in mind to watch for is does it throw when a given specifier is invalid? If not, do we need to handle an invalid specifier some other way?

[KurtCattiSchmidt]

Good question. For now I added a step to look at the importMapParseResult's error to rethrow and to continue if that happens. In practice, we probably want to log something in the console, but this might be enough for the spec.

[KurtCattiSchmidt]

@annevk - I believe the last two commits addressed all of the issues you brought up this morning, so please take a look when you get a chance. And also let me know if I missed anything else you mentioned today.

[annevk]

I think the most substantive issue I raised was not addressed: #10673 (comment). I think we either need something like blob: URLs or allow the module map to contain element references. Not sure.

[KurtCattiSchmidt]

I think the most substantive issue I raised was not addressed: #10673 (comment). I think we either need something like blob: URLs or allow the module map to contain element references. Not sure.

@annevk - I just pushed an update that switches the dataURI to a Blob URI. I think this approach is much simpler than expanding the module map to contain element references.

I've been thinking about the Blob approach and haven't come up with any major reasons not to go this route. The lifetime of the Blob object is an interesting one, and it would be nice to give developers a way to revoke the Blob URL. I don't think removing the <style> tag is a good method anymore though, because you would expect that re-inserting it would re-activate it and Blob URL's cannot be reactivated after revoking them. So maybe exposing the Blob URL somewhere is a better option.

[KurtCattiSchmidt]

@keithamus - here is the split PR with just the declarative modules

[noamr]

I still think that we can have declarative CSS modules with URLs before we go down the rabbit hole of supporting them in inline styles with something like specifier.

The main issue with re-importing CSS URLs in shadow DOM is that they are duplicate.
We can support de-duping them in module-style regardless of supporting them in inline styles, e.g.:

<script type=importmap>
  { "mytheme": { type: "css", href: "theme.css" } }
</script>
<my-element>
  <template shadowrootadoptedstylesheets="mytheme">...</theme>
</my-element>

Or something like:

<script type=importmap>
  { "mytheme": { type: "css", href: "theme.css" } }
</script>
<my-element>
  <link rel=stylesheetmodule href="theme.css">
  <!-- or -->
  <link rel=stylesheetmodule href="mytheme">
</my-element>

This decouples the issue of deduping stylesheet references from the issue of importing inline styles.
The former is a stylesheet-specific problem and the latter, while valid, relates to script modules as well, while this proposal is stylesheet specific.

[KurtCattiSchmidt]

I still think that we can have declarative CSS modules with URLs before we go down the rabbit hole of supporting them in inline styles with something like specifier.

Thanks @noamr. I've recently split the URL version into its own explainer, see https://github.com/MicrosoftEdge/MSEdgeExplainers/blob/main/ShadowDOMAdoptedStyleSheets/explainer.md.

The main issue with re-importing CSS URLs in shadow DOM is that they are duplicate. We can support de-duping them in module-style regardless of supporting them in inline styles, e.g.:
...
This decouples the issue of deduping stylesheet references from the issue of importing inline styles. The former is a stylesheet-specific problem and the latter, while valid, relates to script modules as well, while this proposal is stylesheet specific.

This proposal creates an import map entry under-the-hood for the specifier attribute on <style>, mapping to a generated Blob URL so there's no duplication involved for a given specifier. This approach could easily be expanded to <script> for script and JSON modules. There's nothing in this proposal that needs to be limited to stylesheets. Happy to chat about this at the sync tomorrow of you're available.

[annevk]

This still looks far from ready to me. I'm also wondering if we have a good story as to how we eventually want to make this consistent with the script element. Will that get a specifier attribute too?

[annevk]

This doesn't make sense.

[KurtCattiSchmidt]

Can you elaborate on this? Are you saying that specifier should be parser-only?

[annevk]

The IDL is incorrect.

[KurtCattiSchmidt]

I believe it's correct now

[annevk]

Is this just a subset of the next condition?

[KurtCattiSchmidt]

The next condition is inverted - "The element is not on the..."

This language already exists in https://html.spec.whatwg.org/#the-style-element:update-a-style-block

[annevk]

This is not how this works. A Blob isn't automatically in a store and concept-url-blob-entry doesn't belong to Blob objects either. (Also, a blob URL entry is a struct, not a URL.)

[KurtCattiSchmidt]

This is super helpful, thank you! I updated it to account for this, but it could use another look.

[annevk]

This is wrong. We should be using Infra primitives for JSON.

[KurtCattiSchmidt]

But "create an import map parse result" takes a string, should we change that to allow raw JSON?

[annevk]

It doesn't seem like this got addressed one way or another?

[noamr]

I think that the main issue with this solution, beyond it being tailor-made for styles and ignored for scripts, is that "shadow roots are able to export styles directly to the import map" using an attribute is exotic, as in inconsistent with both how shadow roots work and with how the import map work.

Usually shadow roots should not be able to implicitly affect what's outside of them, and this changes that: any shadow root can import something from a specifier and any shadow root can populate the style that corresponds to that specifier.

I understand the performance-driven use case for this (sharing styles between custom elements that are nested deep in the DOM without duplicating them) but I think we need to find a design that's less radical in terms of breaking shadow DOM encapsulation.

A solution I've brought up before for this was being able to somehow share a style based on an integrity digest, which guarantees that the key and values have some relationship between them, or alternatively having some sort of namespace for CSS modules that is overridable from inside shadow-roots (kind of like data- attributes).

[KurtCattiSchmidt]

I'm also wondering if we have a good story as to how we eventually want to make this consistent with the script element. Will that get a specifier attribute too?

@annevk - yeah, that is addressed in the explainer - see the table under https://github.com/MicrosoftEdge/MSEdgeExplainers/blob/main/ShadowDOM/explainer.md#other-declarative-modules

[KurtCattiSchmidt]

I think that the main issue with this solution, beyond it being tailor-made for styles and ignored for scripts, is that "shadow roots are able to export styles directly to the import map" using an attribute is exotic, as in inconsistent with both how shadow roots work and with how the import map work.

Usually shadow roots should not be able to implicitly affect what's outside of them, and this changes that: any shadow root can import something from a specifier and any shadow root can populate the style that corresponds to that specifier.

I understand the performance-driven use case for this (sharing styles between custom elements that are nested deep in the DOM without duplicating them) but I think we need to find a design that's less radical in terms of breaking shadow DOM encapsulation.

A solution I've brought up before for this was being able to somehow share a style based on an integrity digest, which guarantees that the key and values have some relationship between them, or alternatively having some sort of namespace for CSS modules that is overridable from inside shadow-roots (kind of like data- attributes).

I don't consider this as breaking encapsulation - the module map is already global and any element in a nested tree scope can already access the global map. Encapsulation is still preserved when styles are applied. This feature just adds ergonomics for style modules without needing a fetch or executing script, which is super useful to developers who want to stream declarative content.

[noamr]

I think that the main issue with this solution, beyond it being tailor-made for styles and ignored for scripts, is that "shadow roots are able to export styles directly to the import map" using an attribute is exotic, as in inconsistent with both how shadow roots work and with how the import map work.

Usually shadow roots should not be able to implicitly affect what's outside of them, and this changes that: any shadow root can import something from a specifier and any shadow root can populate the style that corresponds to that specifier.

I understand the performance-driven use case for this (sharing styles between custom elements that are nested deep in the DOM without duplicating them) but I think we need to find a design that's less radical in terms of breaking shadow DOM encapsulation.

A solution I've brought up before for this was being able to somehow share a style based on an integrity digest, which guarantees that the key and values have some relationship between them, or alternatively having some sort of namespace for CSS modules that is overridable from inside shadow-roots (kind of like data- attributes).

I don't consider this as breaking encapsulation - the module map is already global and any element in a nested tree scope can already access the global map. Encapsulation is still preserved when styles are applied. This feature just adds ergonomics for style modules without needing a fetch or executing script, which is super useful to developers who want to stream declarative content.

This is different though. The import map is shared between styles and scripts and here you allow an in-shadow non-script markup to register entries into a map that is generally defined in the head. Eg <style specifier="app.js"> can allow a style to prevent a script from loading in certain situations. Not sure if it's a security risk but at the very least it seems messy for something that is mostly a performance optimization.

[KurtCattiSchmidt]

I think that the main issue with this solution, beyond it being tailor-made for styles and ignored for scripts, is that "shadow roots are able to export styles directly to the import map" using an attribute is exotic, as in inconsistent with both how shadow roots work and with how the import map work.
Usually shadow roots should not be able to implicitly affect what's outside of them, and this changes that: any shadow root can import something from a specifier and any shadow root can populate the style that corresponds to that specifier.
I understand the performance-driven use case for this (sharing styles between custom elements that are nested deep in the DOM without duplicating them) but I think we need to find a design that's less radical in terms of breaking shadow DOM encapsulation.
A solution I've brought up before for this was being able to somehow share a style based on an integrity digest, which guarantees that the key and values have some relationship between them, or alternatively having some sort of namespace for CSS modules that is overridable from inside shadow-roots (kind of like data- attributes).

I don't consider this as breaking encapsulation - the module map is already global and any element in a nested tree scope can already access the global map. Encapsulation is still preserved when styles are applied. This feature just adds ergonomics for style modules without needing a fetch or executing script, which is super useful to developers who want to stream declarative content.

This is different though. The import map is shared between styles and scripts and here you allow an in-shadow non-script markup to register entries into a map that is generally defined in the head. Eg <style specifier="app.js"> can allow a style to prevent a script from loading in certain situations. Not sure if it's a security risk but at the very least it seems messy for something that is mostly a performance optimization.

Agreed, that's the biggest issue with this proposal. I wouldn't consider blocking a script a security problem though. And this can be avoided via CSP. The shadow-piercing aspect is super important for the scenarios that are streaming out SSR content.

[noamr]

This is different though. The import map is shared between styles and scripts and here you allow an in-shadow non-script markup to register entries into a map that is generally defined in the head. Eg <style specifier="app.js"> can allow a style to prevent a script from loading in certain situations. Not sure if it's a security risk but at the very least it seems messy for something that is mostly a performance optimization.

Agreed, that's the biggest issue with this proposal. I wouldn't consider blocking a script a security problem though.

I consider this a blocker for this proposal.

And this can be avoided via CSP.

How? I don't get it.

The shadow-piercing aspect is super important for the scenarios that are streaming out SSR content.

I think we need an alternate design where those in-shadow styles are scoped in a way that doesn't interfere with light DOM imports. One way to do this is to scope it to a particular custom element registry.

e.g. you can use the specifier attribute but it doesn't register in the main importmap.
Instead, it registered in a style-specific import map of sorts that is specific to the custom element registry this element belongs to.
when you import a style inside a custom element's shadow root, it would look up in that registry's style import map and only then refer to the document's global import map.

This would need some development but I think we need something like that and that giving each in-shadow style element a free for all write permission on the head's importmap is a no-go.

[KurtCattiSchmidt]

I consider this a blocker for this proposal.

It isn't actually a security issue though. In your scenario of <style specifier="app.js">, a subsequent import "app.js" will fail due to mismatched Import Attributes ("css" vs "javascript-or-wasm"). The only possible outcome is a failed fetch due to specifier overloading, which is already possible with Import Maps (including from in shadow roots).

And this can be avoided via CSP.

How? I don't get it.

The <style> tag already supports nonce - if you want to block certain style tags from adding specifiers, you can add a CSP and only set the nonce for known/supported <style> tags that you want to allow permission to update the Import Map.

As currently spec'd, this falls under the style-src CSP, but we could take the strictest subset between style-src and script-src to also block Import Map entries as script-src currently does. I brought this up at a prior WHATNOT meeting and it wasn't considered necessary, but that might have been incorrect. Would that behavior address this concern?

I think we need an alternate design where those in-shadow styles are scoped in a way that doesn't interfere with light DOM imports. One way to do this is to scope it to a particular custom element registry.

e.g. you can use the specifier attribute but it doesn't register in the main importmap. Instead, it registered in a style-specific import map of sorts that is specific to the custom element registry this element belongs to. when you import a style inside a custom element's shadow root, it would look up in that registry's style import map and only then refer to the document's global import map.

This would need some development but I think we need something like that and that giving each in-shadow style element a free for all write permission on the head's importmap is a no-go.

This is an interesting idea, I'll ask if it meets the needs of the parties interested in this feature. I am also unsure if it's necessary though - Import Maps aren't currently scoped by shadow root or custom element registries.

[noamr]

I consider this a blocker for this proposal.

It isn't actually a security issue though. In your scenario of <style specifier="app.js">, a subsequent import "app.js" will fail due to mismatched Import Attributes ("css" vs "javascript-or-wasm"). The only possible outcome is a failed fetch due to specifier overloading, which is already possible with Import Maps (including from in shadow roots).
The <style> tag already supports nonce - if you want to block certain style tags from adding specifiers, you can add a CSP and only set the nonce for known/supported <style> tags that you want to allow permission to update the Import Map.

This proposal allows a <style> tag to prevent certain scripts from loading by corrupting an import map. It circumvents CSP script-src in that sense. Sure developers can add additional style-src protections for this but I think it makes the whole concept of import maps messier and more difficult to govern. I think this does make it a security issue.

btw would the work:

<template shadowrootmode=open>
  <script type=importmap>{ "theme": "data:text/css,* { color: red}"}</script>
</template>

If so, what does putting this in a style element attribute add here?

If we really want inline styles (and scripts) we can do something with IDs, like:

<template shadowrootmode=open>
  <script type=importmap>{ "theme": "#theme"}</script>
  <style id=theme>* { color: red; } </style>
</template>

... with some semantics about when the ID lookup is resolved. This can work for scripts as well and doesn't break the CSP protection of import maps.

btw a lot of these concerns were raised in #10673 and I'm surprised that this PR keeps being raised on WHATNOT when these weren't addressed in any satisfactory way.