[Concept] Add support for css variables in Style

[Chrico]

Is your feature request related to a problem? Please describe.

[!] Note: CSS custom properties = CSS variables = CSS vars (used in issue, because i'm lazy).

All modern browsers (Edge, Firefox, Chrome, Safari, Opera) are supporting custom CSS properties and it could come handy when allowing customizing styles via CSS vars instead of overwriting them with own stylesheets and stronger selectors.

WordPress itself does support adding inline styles via wp_add_inline_style. Our library already supports adding custom inline CSS via Style::withInlineStyles($cssString), but this would be mean following code to allow adding CSS vars:

<?php
$cssVars = <<<CSS
:root {
	--padding: 16px;
	--white: #FFFFFF;
	--black: #000000;
}
element {
	--seashell: #F1F1F1;
}
CSS;

$style = (new Style('my-plugin', 'some.css'))
	->withInlineStyles($cssVars);

which would result into:

<link rel="stylesheet" id="my-plugin-css" href="some.css">
<style id="my-plugin-inline-css">
:root {
	--padding: 16px;
	--white: #FFFFFF;
	--black: #000000;
}
element {
	--seashell: #F1F1F1;
}
</style>

But this is not extendable and also does not allow any "overwriting" or configuration from outside.

---

Describe the solution you'd like

I would like to introduce a new method which is called Style::withCssVars(array $vars, string $location = ':root'); which would allow to add/change custom CSS variables to a location.

The example from above could look like following:

<?php
$style = (new Style('my-plugin', 'my-plugin.css'))
	->withCssVars(['padding' => '16px', 'white' => '#FFFFFF', 'black' => '#000000'])
	->withCssVars(['seashell' => 'F1F1F1'], 'element');

and would produce the same result with less to write.

Additionally we...

a) ... could support automatically prefixing variables with -- to have easier to read and accessible array keys.
b) ... have the possibility to overwrite those variables before they are printed out like following:

add_action(
	AssetManager::ACTION_SETUP,
	static function(AssetManager $assetManager) {

		// get the style from earlier on which is already registered
		// and change the padding of the CSS var to 20px

		$style = $assetManager->asset('my-plugin', Style::class);
		$style->withCssVars(['padding' => '20px']);
	}
);

---

Additional context

• Mozilla - Using CSS custom properties
• CanIUse CSS Variables
• W3C - CSS Custom Properties

[widoz]

If am I, just a doubt. Adding a :root element wouldn't be out of the scope? The idea is to allow a certain asset to get configured with Custom Properties, but if you allow :root you're permitting to set the Properties for all of the assets loaded in the page.

What if the withCssVars allows only a specific element or a set of elements but not :root and moving that selector at the asset manager level?

E.G.

\add_action(
	AssetManager::ACTION_SETUP,
	fn(AssetManager $assetManager) => $assetManager->withRootVars(['custom-property', '20px'])
);

It is more logic than say that an asset can define the configuration for the whole page.
Shouldn't an asset just configure it's own known things rather than influencing all of the selectors within the same page?
This proposed way would aslo avoid an asset wrongly configured affecting other elements which would lead to bugs difficult to spot.

[Chrico]

Thanks for your response @widoz :) While i kind of agree with you regarding the :root, i cannot agree with you about the implemetation on AssetManager.

The AssetManager itself just holds all registered Assets and takes care that they are registered/enqueued on the correct Hook. So this class is not able to print any script/style on itself.
If we now would implement AssetManager::withRootVars(), then we would loose the whole implementation of Asset which contains dependencies, locations, filters, version, ..... and the information if it should be enqueued at all. This would mean we need to re-implement such logic to allow printing "root vars" in the correct location (frontend, backend, editor, ...) and context (only archive pages in frontend, only settings page "x" in backend, only PostType "y" in Editor) and position (Asset dependencies). Also we cannot make use of the WP API of WP_Styles::print_inline_style() and need to re-implement that logic in our code.

I guess if someone really wants to register it's custom CSS properties (CSS vars) at :root, then those will be probably prefixed to avoid collisions.
What also comes into my mind is: It could be also possible that some Theme wants to e.G. overwrite defaults from a Plugin like Gutenberg. So the Style will define a dependency on "Gutenberg" and then overwrite those :root-vars with its inline Style.

Hm...you're not wrong with your note, i guess the :root should be even removed as "default" to have it like following: Style::withCssVars(array $vars, string $location); - what do you think?

[widoz]

@Chrico Thanks for the explanation.

While I understand the reason about AssetsManager I want to point out something regarding addressing third party styles.

It could be also possible that some Theme wants to e.G. overwrite defaults from a Plugin like Gutenberg.

I still think an Asset shouldn't override a third party asset because that means a more specific one is affecting something globally (for instance something like Gutenberg).

Reason is that this library isn't only consumed on a package which is allowed to interfer with the Application e.g. a Theme, it could be used on a small library. It's obvious this will not solve the problem but conceptually I think affecting global styles shouldn't done by a style attached to a specific asset.

Btw, does the Library allow to get WP registered assets? What I mean is, can I do something like below?

// Assuming `editor` is https://github.com/WordPress/WordPress/blob/master/wp-includes/css/dist/block-editor/style.css
$style = $assetManager->asset('block-editor', Style::class);
$style->withCssVars(['wp-admin-theme-color' => 'red']);

In that case could make sense but if I have to register a new style just to override editor styles wouldn't make it correct IMO.
A developer should struggle to understand which asset is affecting Gutenberg and how to prevent that, assuming it is possible.

Would instead a specific RootStyle a possible other solution? The library could allow to manipulate a Root registry where all of the :root properties are stored an despite how many packages are requiring this library all of them could affect the same Registry within the same Application.

Race condition wouldn't be a problem because it is intrinsic in the library but at least we could address the injecting of global and specific properties the right way.

I guess if someone really wants to register it's custom CSS properties (CSS vars) at :root, then those will be probably prefixed to avoid collisions.

This is even true, and probably could be even better than what I think but still the specificity couldn't only reside on a prefix, my concern is "Why pollutting the global space with Asset specific styles?"

Regarding the prefix to avoid collision. Let's assume you have a prefix like mh which is a generic prefix embracing a wide range of packages, a value like --mh-element-padding couldn't be enough since another package could introduce the same.

[Chrico]

I still think an Asset shouldn't override a third party asset because that means a more specific one is affecting something globally (for instance something like Gutenberg).

Same goes for me, but that's something which we shouldn't restrict/limit. inpsyde/assets is just a bridge to deal in an more object oriented way with WordPress "Dependency" API. I cannot block this when it is possible with the WP API. I mean you could even do Style::withInlineStyles('body { background: black; color: black; }');. 🤷

For me it is important, that inpsyde/assets enhances the WP API, not to limit/restrict it. And that's the goal of Script::withCssVar(): It will allow you to work in an easier and more maintainable way with CSS vars via wp_add_inline_script().

---

Btw, does the Library allow to get WP registered assets? What I mean is, can I do something like below?

Not yet, but maybe in future. The problem is the mapping/parsing and change of data over time. You cannot ensure the correct mapping of "external Asset via WP Dependency API" to "inpsyde/assets API".

---

This is even true, and probably could be even better than what I think but still the specificity couldn't only reside on a prefix, my concern is "Why pollutting the global space with Asset specific styles?"

But isn't that Gutenberg doing at well? 😬 They are registering at :root styles for the whole site. So a Plugin/Core specific style registers "globals".

[Chrico]

This was implemented with version 2.8. of inpsyde/assets. https://github.com/inpsyde/assets/releases/tag/2.8 I'll close this discussion now. Thanks all for input! :)