Declarative CSS Modules and Declarative Shadow DOM `adoptedstylesheets` attribute

[KurtCattiSchmidt]

What problem are you trying to solve?

Developers using Declarative Shadow DOM (DSD) do not have a way to share declarative stylesheets without using script. There are many workarounds, but none are ideal.

What solutions exist today?

If a developer wants to share styles between the light DOM and DSD, they can either:

a. Duplicate individual inline style rules between shadow roots. This is problematic because it often leads to lots of duplicated style definitions.
b. Use <link rel> tags for shared CSS files in each shadow root. This is problematic because external stylesheets are an asynchronous render-blocking resource, and could cause an FOUC.
c. Use the Javascript adoptedStyleSheets property on the declarative shadow root to share stylesheets. This is problematic because it can cause an FOUC and only works with Javascript enabled.

None of these options are ideal.

How would you solve it?

Declarative CSS Modules allow developers to define style sheets that by default do not apply to the main document, but instead are stored in the global Module Map. An adoptedstylesheets attribute on the <template> element will allow developers to opt Declarative Shadow DOM elements into sharing these stylesheets via module syntax.

Proposed syntax:

<script type="css-module" specifier="/foo.css">
  #content { 
    color: red; 
  }
</script>
<my-element> 
   <template shadowrootmode="open" adoptedstylesheets="/foo.css"> 
     <!-- ... -->
   </template>
</my-element>

The <script> tag allows for styles to be defined without impacting the main document. The adoptedstylesheets attribute on the <template> element will look up the module specifier and associate it with the referenced <style> block.

Explainer: https://github.com/MicrosoftEdge/MSEdgeExplainers/blob/main/ShadowDOM/explainer.md

Anything else?

No response

[domenic]

The most alarming part of this proposal to me is introducing the specifier="" attribute. That seems like it would have significant implications for the module system.

How necessary is that to this idea? Could you instead use, e.g., the id="" attribute?

[rniwa]

The most alarming part of this proposal to me is introducing the specifier="" attribute. That seems like it would have significant implications for the module system.

That's the most noble part of this proposal. It's a feature which allows CSS module to be defined inline.

How necessary is that to this idea? Could you instead use, e.g., the id="" attribute?

I don't think we want to use id for this purpose since id's are not shared across shadow boundaries.

[domenic]

I saw this was discussed at WHATNOT and some new issues were opened. Let it be clear that I don't consider my above objections resolved and I would not be OK with this proceeding further in its current state. This completely new way of manipulating the module map needs significant further discussion and ideally an alternative should be found that either generalizes beyond this specific new feature, or avoids manipulating the module map entirely.

If you want to open a new issue to start that discussion that might be good.

I don't think we want to use id for this purpose since id's are not shared across shadow boundaries.

This doesn't seem like a blocker to me.

Ultimately you have to decide whether you want to pierce shadow boundaries by using a global shared namespace, like the module map / global ID map, or whether you want to use a per-shadow root namespace. The current proposal wants a global shared namespace. So assuming that, some potential workarounds are:

• Have the web developer hoist the shared stylesheets out into the global space, to make it more obvious that they're doing something that is not constrained by shadow DOM instead of having this implicit shadow-crossing behavior of populating the module map.
• Have some new syntax, e.g. globalid="", for populating the global ID map while inside the shadow tree. This seems like a bad idea to me, but so does populating the global module map, and I'd rather we have DOM elements populate the global ID map than the global module map, since they're DOM elements.
• Use some of the more esoteric techniques that people use to forward IDs across shadow boundaries, e.g. for ::part(), or the recent ARIA proposals.

[KurtCattiSchmidt]

If you want to open a new issue to start that discussion that might be good.

The module map behavior is probably the largest piece of this proposal, so I think it makes sense to discuss here.

Have the web developer hoist the shared stylesheets out into the global space, to make it more obvious that they're doing something that is not constrained by shadow DOM instead of having this implicit shadow-crossing behavior of populating the module map.

The module map is already global when done via script, and it already supports stylesheets. The only difference with this proposal is that it's being done with markup instead of script. See https://web.dev/articles/css-module-scripts.

@domenic, can you clarify why you're opposed to using the module map for this? Note that this was also discussed in two TPAC breakout sessions, where the discussions included all 3 implementers and people from the WC developer community, and feedback was generally favorable towards the module approach.

It's certainly possible that the specifier attribute is too vague. @robglidden suggested export instead of specifier and import instead of adoptedstylesheets in order to generalize and provide intent (see linked slides here).

Have some new syntax, e.g. globalid="", for populating the global ID map while inside the shadow tree. This seems like a bad idea to me, but so does populating the global module map, and I'd rather we have DOM elements populate the global ID map than the global module map, since they're DOM elements.

The module map is already global when accessed via script (and already supports global stylesheets), so I don't see the advantage of introducing another global map. I would also expect a globalid to work anywhere an IDREF is expected, which might be too broad.

Use some of the more esoteric techniques that people use to forward IDs across shadow boundaries, e.g. for ::part(), or the recent ARIA proposals.

Are you referring to shadowrootreferencetarget? It is somewhat similar, but only allows references to propagate inside the shadow root - https://github.com/WICG/webcomponents/blob/gh-pages/proposals/reference-target-explainer.md, so styles defined in shadow roots couldn't be added to the global map (i.e. it could allow the shadow root to access global styles, but it wouldn't allow shadow roots to define styles that can be used globally).

We also probably don't want to diverge too far from the existing script-based CSS Module Scripts. Requiring dependencies on other features (especially esoteric ones) seems counter to that.

[annevk]

Note that this was also discussed in two TPAC breakout sessions, where the discussions included all 3 implementers and people from the WC developer community, and feedback was generally favorable towards the module approach.

Having attended at least one of those I don't think that's an accurate characterization. There was quite a bit of confusion as to how this would work, that it was different from everything else we have in HTML to date, and that this would warrant further discussion.