[Declarative Shadow DOM Style Sharing] Use fragment URLs instead of global specifiers

[nicolo-ribaudo]

I'm worried about the choice of using a global namespace for inline stylesheets. We have been generally regretting the usage of global namespaces, as they make adoption significantly harder because they require global coordination across the whole application. I'm especially worried in the context of https://github.com/WICG/webcomponents/blob/gh-pages/proposals/html-modules-explainer.md, which allows developers to publish self-contained HTML files (different from the "root" one) that contain a template with the corresponding style.

I understand that there are benefits to using global specifiers, since it means you can reach them from anywhere. However, I'd like to suggest an alternative that should retain the same benefit while avoiding the global namespace problem: using URL fragments. They have been designed exactly to refer to a part of a larger document.

For context, this idea also came up in the context of https://github.com/tc39/proposal-module-declarations, which also introduces a single file that internally defines multiple (JavaScript in that case, instead of CSS) modules.

Specifically, https://example.com/index.html#foo would be the fully resolved URL for the <style type="module" specifier="foo"> defined inside https://example.com/index.html#foo. We can make URL resolution work like it does for new URL("#foo", <this file's URL>), so that you can reference that inline stylesheet:

• using #foo from inside https://example.com/index.html:

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

• using, for example, ../index.html#foo from a hypotetical https://example.com/js/bundle.js#foo:

  import styles from "../index.html#foo" with { type: "css" }

• using absolute URLs whenever you want, like you can do for "external" files

If users do want to have a global alias, they can use an import map for it. But it's opt-in, like for any other module. They could also use imoprt map scopes, to have an absolute-like specifier that is not actually absolute.

<script type="importmap">
{
  "imports": {
    "foo": "#foo"
  }
}
</script>

There is one drawback to this approach: it's that import "./something#foo" is already valid, and it currently resolves to the same module as ./something. There are two possible solutions to this:

1. When doing import "./something#foo":
   • if ./something exposes a #foo sub-module we return it
   • otherwise we return ./something's whole thing
2. When doing import "./something#foo":
   • if ./something exposes a #foo sub-module we return it
   • otherwise, if ./something exposes any sub-module, we error
   • otherwise we return ./something's whole thing

---

EDIT: This approach also suggests a consistent way to directly import "sub-modules exported from a module", which assuming https://github.com/WICG/webcomponents/blob/gh-pages/proposals/html-modules-explainer.md + https://github.com/MicrosoftEdge/MSEdgeExplainers/blob/main/AtSheet/explainer.md + https://github.com/tc39/proposal-module-declarations can happen with:

• an HTML module exporting a bunch of CSS modules
• a CSS module exporting a bunch of CSS modules
• a JS module exporting a bunch of JS modules

[nicolo-ribaudo]

This would probably also avoid needing @import module, since then we are just dealing with URLs.

[LeaVerou]

This looks great. It solves a lot of the issues:

• Well defined existing semantics for specifiers rather than reinventing the wheel
• Specifiers cannot be mutated, because they're in import maps
• You have a regular URL you can @import without changes.

One issue is that authors expect that #foo will match an element with id=foo (or name=foo in some legacy cases). I wonder if there's any way we can make it work with id on the <style> element. Is that too much magic?
This also works nicely with the @sheet proposal, to define these fragments within CSS files.

There is one drawback to this approach: it's that import "./something#foo" is already valid, and it currently resolves to the same module as ./something. There are two possible solutions to this:

I think 1 is more robust. Might be good to do some compat research on how many import statements import URLs with hashes today. I suspect it's going to be a very low number.

[LeaVerou]

Discussing this with @keithamus, one issue that came up is that this is an unprecedented use case for fragment identifiers, as it actually changes the media type.
Also that there is no reliable way to know that in import foo from "./foo.html#foo"; is the same as a local #foo`, and it could trigger refetching and reparsing the HTML page.

[nicolo-ribaudo]

An alternative instead of using fragment URLs would be to use the module's exports. The HTML part of the proposal would remain untouched:

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

However, the semantics of how it interacts with the module system would be different. Those specifier="foo" declarations would be scoped to the file, so shadowrootadoptedstylesheets="foo" doesn't mean "look in the global import map for a foo alias" but it would mean "look for the style for the foo specifier declared in this same file".

foo is then exposed to other modules as an export of the HTML file. The "JS module" version of this would be

export const foo = new CSSStyleSheet();
foo.replaceSync(`
  #content {
    color: red;
  }
`);

And so you would do import { foo } from "./somewhere.html". Calling it a specifier would still be a very good fit, since that's how JS calls the items in an export { ... } declaration (https://tc39.es/ecma262/#prod-ExportsList), as well as many JS build tools (https://github.com/estree/estree/blob/master/es2015.md#importspecifier).

To avoid the double-fetching/parsing problem (which I don't fully understand, I think the module can already solve that even when using fragments?) it would reuse the same system already used when loading a JS module from two different places.

This would be the same as what is proposed in https://github.com/MicrosoftEdge/MSEdgeExplainers/blob/main/AtSheet/explainer.md: in both cases we have a file that exposes multiple CSS stylesheets, and we import them in the same way.

It also composes nicely with https://github.com/WICG/webcomponents/blob/gh-pages/proposals/html-modules-explainer.md: an HTML module could have different types of exports, some of which are DOM nodes and others are style sheets (probably distinguished by using different attributes to export them).

[nicolo-ribaudo]

Also that there is no reliable way to know that in import foo from "./foo.html#foo"; is the same as a local #foo, and it could trigger refetching and reparsing the HTML page.

Why is it the case? I would expect that in the two cases we do the equivalent of new URL("./foo.html#foo", import.meta.url) (inside the JS module) or new URL("#foo", location.href) (inside the HTML file). In both cases they resolve to http://exaple.com/foo.html#foo, and from there we handle them the same way:

• We check if we have already a document loaded at http://exaple.com/foo.html. If we do, we return its #foo
• If we don't have it already loaded, we could either throw or (which would make sense in the context of WICG/webcomponents@gh-pages/proposals/html-modules-explainer.md) parse it, save the parsed result for that document somewhere for further imports, and return its #foo