[Theme] Allow Theme component to provide custom styles

[stanvladut]

In order for our application to scale properly, we would need the same sp-theme functionality not with Spectrum CSS variables, since the sp-theme component already provides them, but with our custom variables that we use across our components, that might or might not depend on some Spectrum CSS variables.

Expected Behaviour

The expected behavior is to have a possibility to provide some application related styles via sp-theme component, not only Spectrum CSS styles.

For example:
Locally, for our app, depending on the scale & color combination, we compute a list of local variables to be used across our app like this:

.app-container[scale="medium"] {
       --label-size: 0.75rem;
       --spacing-unit: 0.5rem;
       --header-height: calc(2.5rem + 1px);
}
.app-container[color="light"] {
      --label-color: var(--spectrum-alias-label-text-color);
}       

This CSS has to be attached to a child of the <sp-theme> in the DOM hierarchy to be able to also reference Spectrum variables.
What we would need is a way to have this local computed CSSResult provided by the sp-theme in order for us not to create a new local provider for the app's theme.

Actual Behaviour

The actual behavior only allows us to send a combination of color and scale attributes depending on which the sp-theme provides the Spectrum CSS variables to be used in the app.

[Westbrook]

Currently, we apply "themes" to the sp-theme element as registered "fragments" that are made available based on the scale and color attributes of that element. These fragments are registered via:

Theme.registerThemeFragment(FragmentName, FragmentType, CSSResult);

In that way we register the "dark" color with:

Theme.registerThemeFragment('dark', 'color', darkStyles);

I could see expanding on this to include the ability to register:

Theme.registerThemeFragment('app-styles-1', 'app', appStyles);

Some questions that arise from that:

• Does an application want/need to register styles like this in more than one fragment? Why?
• Is there ever a need to "turn off" a fragment of application styles across the application lifecycle?
• Can we assume that a consuming developer could attain access to Theme.registerThemeFragment in the JS context or would we want to be able to handle this in the DOM context? E.G. via DOM events or the like.

---

@stanvladut, as an aside, other than the pending update to REM are the mitigating factors that would prevent your scalar Custom Properties from being bound the Spectrum variables? This would allow them to scale between medium and large without additional input from a consuming application, a la:

:host {
       --label-size: var(--spectrum-global-dimension-size-150);
       --spacing-unit: var(--spectrum-global-dimension-size-100);
       --header-height: calc(var(--spectrum-global-dimension-size-500) + 1px);
}

[stanvladut]

To answer your questions:

1. As I see it, I don't think an application would need to register styles like this in more than one fragment. I think each application can internally compute a single fragment (that of course can depend on scale or color or something else) to be registered for distribution via sp-theme.
   For example, we would mostly need to compute our styles depending on scale, which can be medium or large, but for colors, we are already using Spectrum values that change between light or dark, so no additional work here in splitting our internal variables on separate color schemes. This might not be the case for everyone, but at this point, I think the styles can be internally computed into a single Theme fragment.
2. Right now I don't see a case where we would need to "turn off" the fragment providing us all the variables we need to properly set the layout in our application, so I would say no.
3. I think we can assume that a consuming developer could attain access to Theme.registerThemeFragment. As of right now, we're planning to do a workaround for this by:

import darkStyles from "@spectrum-web-components/theme/src/theme-dark.css.js";
const style = css`
    ${darkStyles}
    :host,:root {
        --hz-foo-bar: #FF0000;
    }
`;
Theme.registerThemeFragment("dark", "color", someStyles);

As for the last off-topic question: At this moment, I see no other reason for no using Spectrum variables for sizing matters.

[stanvladut]

Is there a way for checking the progress on the px to rem update?

[Westbrook]

@stanvladut I've added adobe/spectrum-css#1201 to track that so it's not just "in conversation" going forward. Last sync with their team put us maybe 2-3 months out, based on other in progress work. Once it's in their output, it should little more than updating dependency versions to consume it here, however.

[stanvladut]

Thank you, @Westbrook, I really appreciate!

[moisadoru]

I could see expanding on this to include the ability to register:

Theme.registerThemeFragment('app-styles-1', 'app', appStyles);

This is exactly what is needed.

• Does an application want/need to register styles like this in more than one fragment? Why?

This should be possible, because not all apps are monoliths, where everything is known at startup. A properly modularized application could decide to load a module or a bundle of modules at runtime, and some of the newly loaded modules could require some "theme fragments" to be added to the current theme.

• Is there ever a need to "turn off" a fragment of application styles across the application lifecycle?

Following the same assumption as the above, if some application decides to "unload" specific modules so they do not needlessly consume resources (maybe they only can be used once, then discarded, like for instance some startup tips popover), I would say that unloading should also be possible.

• Can we assume that a consuming developer could attain access to Theme.registerThemeFragment in the JS context or would we want to be able to handle this in the DOM context? E.G. via DOM events or the like.

Theme.registerThemeFragment could be wrapped and exposed as an extension API by the host application to consuming developers, if needed. But the mechanics to allow for theme extensions should be there, regardless of the API used to expose it.

[Westbrook]

This should be possible, because not all apps are monoliths, where everything is known at startup. A properly modularized application could decide to load a module or a bundle of modules at runtime, and some of the newly loaded modules could require some "theme fragments" to be added to the current theme.

This is an interesting are of need. Could you expand on it some more. While I agree that an app should be as modular as possible, I'm not sure I understand where styling in one modular piece of functionality effecting the styling of the entire system isn't a sign of leakage in the code architecture. In that we deal with shadow boundaries in many and varied levels of an application build from SWC elements, this system can (and should) only reason with CSS custom properties. Even the idea of this API as proposed in merely a nicety, and not a "style my whole system" approach in that I expect the majority of consumers beyond trivial implementation will likely be shipping <sp-theme> internal to their initial shadow root, and have full control of handing styles on it as they need: (<style> tag leveraged for simplicity, but this can more readily be achieved by the static style getter for consumers of lit-element based application elements)

<app-root>
  #shadow-root
    <sp-theme color="dark" scale="large">
      <slot></slot>
      <!-- OR -->
      ${this.renderApp()}
    </sp-theme>
    <style>
      sp-theme {
        /* A lengths calculated from Spectrum Custom Properties so that it responds to changes in the `scale` attribute.
        --app-custom-length: calc(var(--spectrum-global-dimension-size-100) + var(--spectrum-global-dimension-size-250));
      }
    </style>
</app-root>

@moisadoru I feel that the above applies to you point about "unloading" as well. Styles in a "single use" context shouldn't be "unloaded" so much as they should be encapsulated to their use point, and the elements that this represents should be removed if that's the correct usage of memory and runtime. While UI that serves this purpose will absolutely consume CSS Custom Properties defining both the Spectrum and application language, not containing the actual style rules that are build on top of that foundation within those elements is a lost opportunity, IMO. Further, while these elements may go the additional step of establishing local CSS Custom Properties for ease of reuse, I don't see it as a good idea to do additional work to apply those to the application when they are only mean for the specific context from which they would originate.

However, there are always more use cases than any one person can think up, so if you have something concrete that you think the above is still too constricting to support, I'd love to hear it so we can find a way to support, whether we do so via this API or via something else.

[moisadoru]

Yes, I think the whole dynamic loading/unloading would only make sense relative to the css variables that would be be added to <sp-theme> by some dynamically loaded app module. Although maybe css variables would not cause significant resources consumption, the fact that once loaded they cannot be unloaded could be considered itself to be a form of "leakage".