Declarative CSS Module Scripts

[justinfagnani]

Declarative shadow roots and constructible stylesheets need to be made to work together so that stylesheets added to shadow roots can be round-tripped through HTML serialization and deserialization.

As of now, SSR code will have to read a shadow root's adopted stylesheets and write them to HTML as <style> tags. While this will style they shadow roots correctly on first render, it results in bloated a HTML payload and breaks the shared stylehseet semantics. Hydration code would have to deduplicate <style> tags and create and attach constructed stylesheets in order to reconstruct the origin DOM structure.

To solve this we need a serialized form of constructible stylesheets. These are stylesheets that do not automatically apply to any scope, but can be associated and applied by reference.

Requirements:

1. Ability to serialize a constructed stylesheet to HTML (edit to clarify: on the server)
2. Styles don't automatically apply to the document or any shadow root
3. Styles are able to be associated with declarative shadow root instances (edit to clarify: which populate the shadow root's adoptedStyleSheets)
4. To support streaming SSR, the styles must be able to be written with the first scope that uses it and referenced in later scopes.

One idea is to add a new type for <style> tags that accepts CSS text and creates a new constructed stylesheet:

  <style type="adopted-css" id="style-one">
    :host {
      color: red
    }
  </style>

This style can then be associated with a declarative shadow root:

  <my-element>
    <template shadowroot="open" adopted-styles="style-one">
      <!-- ... -->
    </template>
  </my-element>

Having a type other than text/css means that the styles won't apply to the document scope even in older browsers. It's also what allows it to have an adoptable CSSStyleSheet .sheet, which replace() works on as well.

One problem that immediately come up is scopes and idrefs. If a declarative stylesheet is only addressable from within a single scope, it's no better than a plain <style> tag because it would have to be duplicated in every scope that uses it. We need some sort of cross-scope idref mechanism. With that we can write the styles with the first scope that uses them, and reference them in later scopes in the document:

  <my-element>
    <template shadowroot="open" adopted-styles="x61h8cys">
      <style type="adopted-css" xid="x61h8cys">
        :host {
          color: red
         }
      </style>
      <!-- ... -->
    </template>
  </my-element>
  <my-element>
    <template shadowroot="open" adopted-styles="x61h8cys">
      <!-- ... -->
    </template>
  </my-element>

Here xid is a stand-in for some kind of cross-scope ID. "x61h8cys" is a stand-in for a GUID or other globally unique value (such as a hash of the style text) that the SSR code would be responsible for generating.

There are other instances where we need cross-scope references, like ARIA and label/input associations. I'm not sure if these cases are similar enough to use the same mechanism or not.

[bkardell]

@justinfagnani is your xid conceptually a DOMTokenList or something similar -- that is, can you import 2? This feels related to at least some of the discussions in #909 - this "idea" at least would at least probably provide a way to achieve use cases for things like those which aren't even 'secret' as much as they are 'shorthand for well-known constructs' like an element that allows markdown, asciimath, or LaTeX and it similar to the thing I created and have used for my own takes on this..

[justinfagnani]

Yes, shadow roots need to be able to reference multiple style sheets.

I don't personally see this as that much related to #909 ("open-styleable" shadow roots). Rather than allowing anything from the outside to reach into a shadow root, this is just attempting to replicate JS references to these objects in HTML. it shouldn't be loosening encapsulation at all.

[justinfagnani]

Another option instead of - or maybe in addition to - cross-scope refs is to allow inlining of all module types, keying them by URL that adds them to the module cache as if they had been imported. This would allow a page to render with the necessary CSS modules, attach them to the correct scopes, and later to load JS modules that import them without double-loading them.

<script> tags with type values that match import assertion types would support a new attribute that gives the specifier/URL. Something like:

<script type="css" specifier="/foo.css">
  :host {
    color: red
   }
</script>

A later import: import styles from '/foo.css' assert {type: 'css'} would load the CSS module script defined by the tag.

Full example:

  <my-element>
    <template shadowroot="open" css-modules="/foo.css /bar.css">
      <script type="css" specifier="/foo.css">
        :host {
          color: red
         }
      </script>
      <!-- ... -->
    </template>
  </my-element>
  <my-element>
    <template shadowroot="open" css-modules="/foo.css /bar.css">
      <!-- ... -->
    </template>
  </my-element>

This would have to be made coherent with import maps, but it would allow a page to be rendered with correct scoped styles w/o FOUC and w/o duplication of CSS text.

[Westbrook]

Being <template shadowroot="open"> creates a shadow root that ID resolution from above does not have access to, should the "expected" version of:

  <my-element>
    <template shadowroot="open" adopted-styles="x61h8cys">
      <style type="adopted-css" xid="x61h8cys">
        :host {
          color: red
         }
      </style>
      <!-- ... -->
    </template>
  </my-element>

Actually be:

  <style type="adopted-css" id="x61h8cys">
    :host {
      color: red
     }
  </style>
  <my-element>
    <template shadowroot="open" adopted-styles="x61h8cys">
      <!-- ... -->
    </template>
  </my-element>

In this wa x61h8cys can be made available for other shadow roots without having to penetrate otherwise encapsulated DOM structures? Or do you think that all style[type="adopted-css"] would be made available globally by default?

How would you make these "declarative CSS modules" available in an imperative context? Should there be API to allow for resolution of the actual Stylesheet object from the x61h8cys identifier so that it can be adopted by shadow roots deeper within the DOM hierarchy or that might not be delivered declaratively?

Inversely, should stylesheets that are registered imperatively have API added by which to associate an ID (a la adopted-styles="x61h8cys") so that they could be leveraged in declarative code?

[Westbrook]

The example of

<script type="css" specifier="/foo.css">
  :host {
    color: red
   }
</script>

Seems like a large change for developers, would it make a shorter step from historic practices to apply this concept via <style> or <link>? E.G:

<style type="module" src="/foo.css">
  :host {
    color: red
   }
</style>

OR

<link rel="stylesheet-module" href="/foo.css" />

In this way we could leverage already existing blocking mechanisms while informing the browser not to apply these styles until adopted. It's possible that link[rel="stylesheet-module"] might fit right into the rel="modulepreload" cache once assert { type: 'css' } hit browsers allowing it to leverage even more pre-existing features.

Question that applies to both of these approaches, do you expect that values applied to adopted-styles or css-modules would resolve lazily? E.G. could I list these style in my declarative shadow DOM but then load those sheets in a non-blocking way and still have them apply to the shadow root?

[bicknellr]

+1, I think the idea of using an attribute to provide a URL / specifier is a really interesting thing to explore because it seems like it would generalize well to basically anything in HTML that describes some other resource and has either inline and external forms. (I'm writing it here as cacheas since I don't think it would really be a specifier anymore? Anyway, the name would need bikeshedding.)

So, not only could you have:

<script type="module" cacheas="./some-path">
export let aString = "Hello, World!"
</script>
<script type="module">
import {aString} from "./some-path";
console.log(aString);
</script>

and

<style cacheas="./some-path">
body::before {
  content: 'Hello, World!';
}
</style>
<link rel="stylesheet" href="./some-path">

But also things like:

<img cacheas="./some-path" src='data:image/svg+xml,<svg version="1.1" xmlns="http://www.w3.org/2000/svg" width="120" height="60"><text y="30" x="30">Hello, World!</text></svg>'>
<img src="./some-path">

[justinfagnani]

@mfreed7 if we wanted this to be a more general feature, should we move the issue to HTML?

[calebdwilliams]

Am I reading right that this idea is a form of declarative module blocks? A bit off-topic, but I'm wondering how that could play with import assertions and this concept, seems like a lot of the semantics are the same … 

[rniwa]

Yeah, URL based namespacing is exactly like JS modules. In theory, you should be able to define an inline (e.g. data URI) style inside import maps. So the only additional mechanism needed here is the ability to adopt it.

How about <style type="module" src="foo"></style>.

[matthewp]

@rniwa Would that <style> be resolved synchronously? I just see the word "module" and think async, but this needs to be sync to avoid FOUC.

---

cc @mfreed7, @justinfagnani what do you think of the idea @rniwa is proposing here?

[sashafirsov]

@justinfagnani , why to limit the adopted-styles concept to the CSS only?
It is a "library" concept with common scope as in CSS as in custom components registry and perhaps some other common things like import maps.

I.e. this proposal has to be converted to something like "custom elements library scope".

If agree, the name adopted-styles does not reflect the semantic meaning.