Style engine: functionality and design

[ramonjd]

Related:

• Tracking: Add a Style Engine to manage rendering block styles #38167
• Tracking: extend layout options in Gutenberg #39336
• [WIP] Style engine: register styles for enqueuing and rendering #41424

This discussion thread is an attempt to break down the scope of functionality in order to help determine a suitable and flexible code structure and public interface.

The outcome should be general agreement about target quality, what lives where and how the world might interact with the style engine.

We can't tell the future, so we're not looking to sculpture Michelangelo's David, rather, something we're happy to ship now that has the most potential to align with our goals.

Given that the style engine is not yet in WordPress core, but is planned for 6.1, it's a great time to sort this out! Kudos to @aristath and @andrewserong for lighting the fires.

❗ To keep things focussed, this discussion does not cover:

• what the frontend output should look like, e.g., how the CSS is structured in the document, how many style tags and so on
• theoretical or practical use cases, e.g., how to approach layout CSS or preset generation
• the appropriateness of the name "style engine" 😄

New discussion threads are welcome.

The usual caveat: this is a brain dump. Nothing about what I write, ever, should be set in stone.

Context

The style engine has a single purpose at the moment: to bring together where we generate styles. For more information see: https://make.wordpress.org/core/2022/06/24/block-editor-styles-initiatives-and-goals/

Down the road, the intention is that the style engine will be responsible for not only generating CSS in Gutenberg but also outputting that CSS to the page with some stuff going on in between. :)

A general example flow might be the following:

'Something, somewhere' in Gutenberg needs to convert style information to valid CSS that needs to be available on the frontend. This 'something somewhere' passes style information to the style engine, which:

1. Parses and sanitizes the incoming values
2. Stores these values in a central location
3. Registers the styles to be enqueued/printed to the page via a WordPress hook
4. When the hook callback fires, retrieves the stored values and gets them ready for publishing by:
   a. Processing/optimization (if any)
   b. Generating/compiling output-ready CSS declarations
   c. Using these CSS declarations, construct CSS rules
   d. Enqueuing those CSS rules as a stylesheet for printing to the page.

It's likely that only some of the above steps are needed, for instance, where a block asks for CSS declarations for an element's style attribute, we'd only fire steps 1 and 4.b.

Below is a diagram of the flow. No, I didn't make the cut for Disney 🤣

The boxes are color-coded to indicate possible class groups.

Overview of required functionality

Parsing

The initial step of parsing raw input (see below) and creating styles ready for registration/storage and, eventually, conversion to CSS.

Parsing may involve:

• validation of style properties (we only parse valid styles)
• sanitization of values
• conversion of Gutenberg CSS property identifiers (var:preset|color|salami) into CSS values (var(--wp--preset--color--salami))
• bundling styles in a storable format

Store

A centralized store of all styles accessible by unique keys (mostly likely a CSS selector). Stored in memory and rebuilt every page refresh.

For example:

array(
	'.selector-1' => array(
		'margin-left' => '20rem',
		'color'       => '#000000',
	),
	'.selector-3' => array(
		'padding'      => '10rem',
		'border-width' => '1px',
	),
)

To store additional metadata in the future, we might elect to turn the store value into a collection.

For example, if, later down the line, we want to support CSS nesting then the selector key could be the root selector. During processing, we'd group and nest rules using this information.

array(
	'.selector-1' => array(
		'nested_selector' => '& > .nested',       
		'definitions'     => array(
			'color'  => 'pink',
		),
	),
	'.selector-1' => array(
		'definitions' => array(
			'padding' => '10rem',
		),
	),
	'& > .nested' => array(
		'nested_selector' => '& > p',       
		'definitions'     => array(
			'font-size'  => '10rem',
		),
	),
)

To output something like:

.selector-1 {
	padding: 10rem;
	& > .nested {
		color: pink;
		& > p {
			font-size: 10rem;
		}
	}
}

Further grouping may be required to represent individual layers in the style hierarchy, especially if we are to support cascade layers.

array(
	'block-supports' => array(
		'.selector-1' => array(
			'definitions' => array(
				'color'  => 'pink',
			),
		),
	)
	'global-styles' => array(
		'.selector-2' => array(
			'definitions' => array(
				'font-size'  => '10rem',
			),
		),
	)
)

In order to output something like:

@layer global-styles, block-supports;

@layer global-styles {
	.selector-2 {
		font-size: 10rem;
	}
}
@layer block-supports {
	.selector-1 {
		color: pink;
	}
}

Registration

One or more functions that register WordPress hook callbacks that enqueue CSS stylesheets.

We'll need the flexibility to separate and group categories of styles, for example, block support styles may need to be enqueued in a separate stylesheet to global styles.

Processing

This is where the style engine accesses and processes stored styles immediately before generating CSS and printing it to the page.

This may involve:

• deduplication by identifying CSS rules that share declarations,
• checking specificity ???
• other optimizations

Processing takes place before, or as part of generation, whereby we convert parsed and/or stored values to CSS.

Generating

Contains a set of functions that generates valid CSS from parsed and/or stored values.

The style engine should be at least able to build:

• CSS declaration blocks such as margin: 10px; background-color: orange; border-radius: 2rem;
• CSS rules like .selector { margin: 10px; background-color: orange; border-radius: 2rem; }
• (Possibly) classnames if and when we start looking at semantic classnames
• And have an option to output prettified CSS, e.g., where it adds indents and carriage returns

These methods could probably be added to the public interface for use throughout Gutenberg.

Enqueuing and printing

Contains functionality to:

• construct stylesheets (sets of CSS rules) from generated CSS.
• enqueue stylesheets with WordPress hooks so that they are printed to our page.

Input

The style engine is opinionated in that it will manage and create styles for content created with the block editor. Therefore it should ultimately accept current block style objects.

Block styles

These are styles that are valid for blocks and elements. The style engine supports these as a minimum. Every block or element might have one or a combination of these rules.

They are defined in WP_Theme_JSON within VALID_STYLES. See: https://github.com/WordPress/gutenberg/blob/trunk/lib/compat/wordpress-6.0/class-wp-theme-json-6-0.php#L256

For every block or element that requires CSS, a call to the public style engine parser/generator/other cool name function will be required.

array(
	'border'     => array(
		'color'  => '',
		'radius' => '',
		'style'  => '',
		'width'  => '',
		'top'    => '',
		'right'  => '',
		'bottom' => '',
		'left'   => '',
	),
	'color'      => array(
		'background' => '',
		'gradient'   => '',
		'text'       => '',
	),
	'filter'     => array(
		'duotone' => '',
	),
	'spacing'    => array(
		'margin'   => '',
		'padding'  => '',
		'blockGap' => '',
	),
	'typography' => array(
		'fontFamily'     => '',
		'fontSize'       => '',
		'fontStyle'      => '',
		'fontWeight'     => '',
		'letterSpacing'  => '',
		'lineHeight'     => '',
		'textDecoration' => '',
		'textTransform'  => '',
	),
);

Architecture

What do folks think? Is the flow diagram a passable representation, and enough to guide how we build out the style engine?

We don't have to come up with a final blueprint here - it'll be at least enough to gain confidence about a short-term direction that won't lead us into too many dead ends despite the lack of clarity surrounding long-term tasks and goals.

[aristath]

A centralized store of all styles accessible by unique keys (mostly likely a CSS selector). Stored in memory and rebuilt every page refresh.

For example:

array(
	'.selector-1' => array(
		'margin-left' => '20rem',
		'color'       => '#000000',
	),
	'.selector-3' => array(
		'padding'      => '10rem',
		'border-width' => '1px',
	),
)

I was thinking... What if we have an object for the rules declarations? So each selector can have its own object which can hold all the declarations and methods needed to compile the styles. In #42043 (proof of concept PR) I implemented that, and I think we can use an implementation like that to move all the parsing/optimizing etc logic for per-selector CSS in there 🤔

[ramonjd]

What if we have an object for the rules? So each selector can have its own object which can hold all the rules and methods needed to compile the styles.

Interesting! I think sounds pretty neat to have a rule object with member utility functions.

I like the idea of being able to do something like:

$my_style = new WP_Style_Engine_Rule( $selector, $rules_and_other_metadata );

$inline_css_declaration = $my_style->get_inline_css_declarations();

$css_rule = $my_style->get_css_rule( array( 'prettify' => true ) );

It might even be helpful to a have an abstract CSS_Rule class that we can extend to create custom rules if we desire.

class WP_Style_Engine_Nested_Rule extends WP_Style_Engine_Rule {}
...
$my_style = new WP_Style_Engine_Nested_Rule( $root_selector, $rules_and_other_metadata );
$nested_css_rule = $my_style->get_css_rule( array( 'prettify' => true ) );

Thanks for putting up code to demonstrate it! I'll take a look at #42043

[ramonjd]

I threw up #42061 to illustrate what I was yapping on about above. It's just for show!

[ramonjd]

@getdave might be interested in this discussion too.

[ramonjd]

cc @mtias and @draganescu for a bit of perspective in case we're getting ahead of ourselves.

[getdave]

A centralized store of all styles accessible by unique keys (mostly likely a CSS selector). Stored in memory and rebuilt every page refresh.

If we're storing by selector we need a way to tie back pseudo selectors to their "parent" selector.

Basically ensuring that a:hover doesn't become divorced.

I think that there's a chance the selector might be :hover and thus we'd loose the information on which selector this is "bound" to. We should be sure to store the entire selector (e.g. a:hover).

PS: not sure why this has to be an "answer". I'm just leaving a note.

[adamziel]

The nesting idea could help:

array(
	'&:hover' => array(
		'definitions'     => array(
			'font-size'  => '10rem',
		),
	)
)

[ramonjd]

This might be a "note to self" more than anything.

I'm also thinking the wp_style_engine_generate function, which aims to the primary public interface to the style engine to generate styles (for now 😄) should return CSS (a string) only.

At the moment, because the first incarnation was heavily influenced by block supports, wp_style_engine_generate () returns an array of a block's CSS + classnames. array( 'css' => '', 'classnames' => '' )

This seemed neat and "optimal" at the time. The majority of cases however, at least for the foreseeable future and until we look at semantic classnames, will only need CSS.

Maybe if we separate concerns now, and provide a method for getting a block's CSS and one for generating any necessary classnames, it'll be easier to optimize and tinker about under the hood later, especially when we start talking about generating semantic classnames.

E.g., gutenberg_style_engine_generate_css() and gutenberg_style_engine_generate_classnames()

Would that make sense? I've been staring into the abyss for too long 😱

Edit: Furthermore, I wonder if we should have a facade class in Gutenberg under lib/experimental, e.g., WP_Styles_Controller_Gutenberg, that provides the interface to the style engine package's modules/classes.

The reason is because I've been testing the style engine by plugging it into global styles and have come up against a few challenges due to idiosyncratic exceptions (Hello --wp--style--block-gap!!), that might require some special rules, and only for global styles! 😄 This is something that @aristath cleverly foresaw over in #41965.

There'll probably be more highly specific rules coming too.

Should the style engine care about these? Or just provide a toolbox to generate, process and enqueue?

[abder]

@ramonjd

I am thinking of another approach where the editor will have 2 artifacts, HTML and CSS, not just HTML as it is now, the generated CSS can be stored in the database and then used on Front End, with that approach we will have a single implementation on the editor only avoiding another implementation on backend.

Just a fleeting thought

What do you think?

[ramonjd]

Thanks for the idea @douara !

That sounds interesting idea, I'm not sure how big the scope would be, but something like that sounds like it would take over a lot of the backend works and potentially ensure 1:1 CSS between editor and frontend.

I'm not certain about the consequences for performance, or even about how we'd store it. I think storing CSS might come with its own challenges. Encoding, decoding, sanitization. If you have suggestions about how something might work it'd be a good idea to record it in an issue or discussion.

I was just about to close this thread as there's been quite a bit of work on the class structure, which has now satisfied this discussions' terms of reference.

[abder]

@ramonjd
Thank you for your reply.

I actually don't know yet how this could be implemented, but:
Why do you think that storing CSS would be challenging? Encoding, Decoding, Sanitization? isn't it possible to just store it as is, i mean as a string? Or is there any security consequences for that?

Thanks!

[ramonjd]

I was just about to close this thread as there's been quite a bit of work on the class structure, which has now satisfied this discussions' terms of reference.

Oh, it looks like I can't 🤣

https://github.com/orgs/community/discussions/3097