[cssom] allow text in CSSStyleSheet constructor

[jonathantneal]

May we consider allowing CSSStyleSheetInit to accept a text property that synchronously assigns rules to the constructed sheet?

dictionary CSSStyleSheetInit {
  DOMString baseURL = null;
  (MediaList or DOMString) media = "";
  boolean disabled = false;
  DOMString text = "";
};

Example usage:

new CSSStyleSheet(":host{ /* styles */ }")

Example in adoptedStyleSheets:

shadowRoot.adoptedStyleSheets = [ new CSSStyleSheet(":host { /* styles */ }") ]

The goal is to improve the authoring experience for constructed stylesheets, especially within custom elements, by enabling inline creation without needing to call replaceSync() separately. This would be a small but meaningful ergonomic improvement and a low-barrier enhancement that could benefit many developers working with adoptedStyleSheets.

Would this be appropriate for inclusion in the spec, or is it better suited for discussion elsewhere?

[Loirooriol]

Presumably the example would be

new CSSStyleSheet({ text: ":host{ /* styles */ }" })

Or do you want the parameter to be either a CSSStyleSheetInit or a string?

[castastrophe]

I quite like this idea for dynamic interpolation for systems with design data stored in JSON for example.

new CSSStyleSheet({ text: `:host{ background: ${token.colors.blue.100} }` })

[justinfagnani]

To give some context, at least as far as I remember it, for how the current API came to be:

1. Modern DOM APIs are trying to at least make it possible, if not the path of least resistance, to do work off the main-thread. CSS parsing is a perfect example: it's expensive, sync parsing blocks the main thread, which can lead to jank and underutilizing multi-core CPUs. So implementors want this API to be non-blocking.
2. Constructors can't be async, so we need some other API for async parsing style text. There could be something like an async factory, but given the need to replace text, something like an instance method was needed anyway.
3. To nudge developers towards the better-for-users async API, the async method got the plain name replace() and the worse-for-users sync method got the name replaceSync().
4. Since constructors can't be async, the constructor could only enable the worse-for-users sync parser. In order to still nudge developers towards the better-for-users method, the constructor doesn't take style text at all.

Without changing the opinions on expensive blocking APIs, I'm not sure that the spec group will endorse allowing style text in the constructor.

I do think with addition of top-level await since then, it might be kind of nice to have static factories, which would combing the constructor and replace calls. ie:

const styles = await CSSStyleSheet.parse(...);

or:

const styles = CSSStyleSheet.parseSync(...);

Of course, these factories are pretty trivial to write yourself:

const parseCSS = async (text: string) => {
  const stylesheet = new CSSStyleSheet();
  await stylesheet.replace(text);
  return stylesheet;
};

Note: one advantage of the separate construction and async parsing APIs is that you can construct your stylesheet object eagerly, initiate the parsing, and continue to use it to build your required DOM structures while the text is being parsed, and only block on the parsing promise(s) later on.