[RRFC] Provide styling API supporting dynamic changes, theming, and applying document styling

[sorvell]

• [X ] I searched for an existing RRFC which might be relevant to my RRFC

Motivation

There are many longstanding requests to improve Lit's styling API to better support things like (1) dynamic style changes, (2) theming, (3) application of document styles, (4) slightly relaxing the restrictions of Shadow DOM's style scoping.

Related

• [RRFC] Add ability to set dynamic styles programatically after render #13
• [RRFC] LitElement theming API #10

This is a complex topic and a lot of customization is possible using css custom properties, shadow parts, and shared constructible CSSStyleSheets. However, it would be nice if Lit provided some convenient helpers and guidance/best practices for these needs. This would probably make sense as a lit-labs package that could be iterated on via extensive feedback.

How

Here is a prototype of new capability to support these needs. It includes:

1. a new sheet TTL to use instead of css which mainly is less restrictive around accepting values and has customizable caching behavior via including an inline storeAs({key, scope}) value. This makes stylesheets shareable by key, without having to explicitly pass around the sheet itself.
2. sheet mutation API: hasSheet, addSheets, removeSheets, toggleSheets. These helpers just make it more convenient to work with adoptedStyleSheets.
3. getDocumentStyles: retrieves and tracks document styles/links and auto-convert them to adoptable sheets and Lit renderable link template results. This makes it possible easily to include document styles in elements. Caveats: only styles available when the element is defined are available and tracked.
4. themeSheet({...part: "css"}): intended for theming this let's users provide styles for parts and custom properties that are not necessarily restricted by the DOM tree or export parts.
5. fromSelectors({...class: "css"}): this provides type-safe access to a set of css classes defined by name, returning {sheet, selectors} where sheet is intended to be included in the element's styles and class=${selectors.name} is included in the template. The advantage is that TS will ensure only defined class selectors can be included.

[sorvell]

It's an open question how to integrate these capabilities and in particular document styles (aka open-stylable) with with SSR and DSD. In general, the more dynamic styling is, the harder it is to regularize for SSR.

One possibility would involve changing SSR generally to support style hydration, meaning giving it the ability to move styles from somewhere else in the document into a DSD. With that capability, document styles could be copied into DSD, supporting open-stylable.

Currently Lit SSR renders element static styles directly into the element's DSD.

Optionally, these could be rendered only 1x relying on hydration code to copy them as needed. This could be done with an id-ref e.g. (data-style-ids on host elements and just a matching id on style|link elements). These hydrating styles could be given a type="hydrate" to avoid applying where defined.

This is a prototype of this approach.