Introduce a theme.json property for auto-injection of component styles in V24

Describe your motivation

In V24, components will be stylable without themablemixin-based injection of css into components’ shadow DOM thanks to support for the ::part() selector.

This means that there will no longer be a need for the themes/themename/components folder, and the associated mechanism of automatically injecting stylesheets placed there into components with the corresponding name.

In fact, this mechanism will cause problems for developers who want to have a folder called components in their theme folders (which is quite common) without using the current css injection system.

Thus, a way of disabling this special folder mechanism is needed.

Describe the solution you’d like

Introduce a property in theme.json for enabling/disabling the mechanism.

With the mechanism disabled, the components folder does not have any magical features, and is treated as any other subfolder in the theme folder. With the mechanism enabled, the components folder works like in V23.

In its simplest form, this could be simply a boolean property for enabling/disabling the mechanism, e.g. "autoInjectComponents" : true.

Alternatively, it could be a property for setting the name of the folder that is used for auto-injection, e.g. "autoInjectFolder" : "components" which, if set to null, would disable the mechanism.

In either case, a decision must be made of the default setting:

• Mechanism disabled by default (i.e. defaulting autoInjectComponents to false, or defaulting autoInjectFolder to null) would ensure that developers using the new ::part() based styling could have a folder called components without having to adjust theme.json.
• Mechanism enabled by default (i.e. defaulting autoInjectComponents to true, or defaulting autoInjectFolder to "components") would make it easier to migrate apps that currently utilize the components folder based auto-injection.

Both are problematic, but I suspect that keeping the components folder mechanism enabled by default in V24 is the lesser evil. We can later change this default in V25.

Describe alternatives you’ve considered

A feature flag would be the other option, but as both ways will probably be supported for several more major versions, it doesn’t feel like the correct approach to me. Also, as this is a theme-specific setting, having it as a theme.json property makes it possible for an app to use multiple themes (e.g. through parent-theme inheritance) that use different approaches.

Additional context

Note that this property should not affect @CssImport(...themeFor) – this is only about the special functionality of the components folder.

[Artur-]

Yes, with a boolean you would have to name the new “components” folder something else than components like … new-components or rename the files inside the folder e.g. from vaadin-button.css to button.css when you migrate.

The implementation where undefined and null mean different things does not sound super compelling though

[MarcinVaadin]

Implementation updated to support ‘autoInjectComponents’ flag with default value ‘true’ to preserve backwards compatibility.