Style Engine

The Style Engine powering global styles and block customizations.

Important

This Package is considered experimental at the moment. The idea is to have a package used to generate styles based on a style object that is consistent between: backend, frontend, block style object and theme.json.

Because this package is experimental and still in development it does not yet generate a wp.styleEngine global. To get there, the following tasks need to be completed:

TODO List:

• Add style definitions for all the currently supported styles in blocks and theme.json.
• The CSS variable shortcuts for values (for presets...)
• Support generating styles in the frontend. (Ongoing)
• Support generating styles in the backend (block supports and theme.json stylesheet). (Ongoing)
• Refactor all block styles to use the style engine server side. (Ongoing)
• Consolidate global and block style rendering and enqueuing
• Refactor all blocks to consistently use the "style" attribute for all customizations (get rid of the preset specific attributes).

See Tracking: Add a Style Engine to manage rendering block styles #38167

Backend API

wp_style_engine_get_styles()

Global public function to generate styles from a single style object, e.g., the value of a block's attributes.style object or the top level styles in theme.json .

Parameters

• $block_styles array A block's attributes.style object or the top level styles in theme.json
• $options array<string|boolean> An array of options to determine the output.
  • context string An identifier describing the origin of the style object, e.g., 'block-supports' or ' global-styles'. Default is 'block-supports'. When both context and selector are set, the style engine will store the CSS rules using the context as a key.
  • convert_vars_to_classnames boolean Whether to skip converting CSS var:? values to var( --wp--preset--* ) values. Default is false.
  • selector string When a selector is passed, generate() will return a full CSS rule $selector { ...rules }, otherwise a concatenated string of properties and values.

Returns array<string|array>|null

array(
    'css'           => (string) A CSS ruleset or declarations block formatted to be placed in an HTML `style` attribute or tag.
    'declarations'  => (array) An array of property/value pairs representing parsed CSS declarations.
    'classnames'    => (string) Classnames separated by a space.
);

It will return compiled CSS declarations for inline styles, or, where a selector is provided, a complete CSS rule.

To enqueue a style for rendering in the site's frontend, the $options array requires the following:

1. selector (string) - this is the CSS selector for your block style CSS declarations.
2. context (string) - this tells the style engine where to store the styles. Styles in the same context will be stored together.

wp_style_engine_get_styles will return the compiled CSS and CSS declarations array.

Usage

$block_styles =  array(
     'spacing' => array( 'padding' => '100px' )
);
$styles = wp_style_engine_get_styles(
    $block_styles,
    array(
        'selector' => '.a-selector',
        'context'  => 'block-supports',
    )
);
print_r( $styles );

/*
array(
    'css'                 => '.a-selector{padding:10px}'
    'declarations'  => array( 'padding' => '100px' )
)
*/

wp_style_engine_get_stylesheet_from_css_rules()

Use this function to compile and return a stylesheet for any CSS rules. The style engine will automatically merge declarations and combine selectors.

This function acts as a CSS compiler, but will also enqueue styles for rendering where enqueue and context strings are passed in the options.

Parameters

• $css_rules array<array>
• $options array<string|boolean> An array of options to determine the output.
  • context string An identifier describing the origin of the style object, e.g., 'block-supports' or ' global-styles'. When set, the style engine will store the CSS rules using the context value as a key.

Returns string A compiled CSS string based on $css_rules.

Usage

$styles = array(
    array(
        'selector'.       => '.wp-pumpkin',
        'declarations' => array( 'color' => 'orange' )
    ),
    array(
        'selector'.       => '.wp-tomato',
        'declarations' => array( 'color' => 'red' )
    ),
    array(
        'selector'.       => '.wp-tomato',
        'declarations' => array( 'padding' => '100px' )
    ),
    array(
        'selector'.       => '.wp-kumquat',
        'declarations' => array( 'color' => 'orange' )
    ),
);

$stylesheet = wp_style_engine_get_stylesheet_from_css_rules(
    $styles,
    array(
        'context'  => 'block-supports', // Indicates that these styles should be stored with block supports CSS.
    )
);
print_r( $stylesheet ); // .wp-pumpkin, .wp-kumquat {color:orange}.wp-tomato{color:red;padding:100px}

wp_style_engine_get_stylesheet_from_context()

Returns compiled CSS from a stored context, if found.

Parameters

• $store_name string An identifier describing the origin of the style object, e.g., 'block-supports' or ' global-styles'. Default is 'block-supports'.

Returns string A compiled CSS string from the stored CSS rules.

Usage

A use case would be to fetch the stylesheet, which contains all the compiled CSS rules from the store, and enqueue it for rendering on the frontend.

// First register some styles.
$styles = array(
    array(
        'selector'.       => '.wp-apple',
        'declarations' => array( 'color' => 'green' )
    ),
);

$stylesheet = wp_style_engine_get_stylesheet_from_css_rules(
    $styles,
    array(
        'context'  => 'fruit-styles',
        'enqueue'  => true,
    )
);

// Later, fetch compiled rules from context store.
$stylesheet = gutenberg_style_engine_get_stylesheet_from_context( 'fruit-styles' );
print_r( $stylesheet ); // .wp-apple{color:green;}
if ( ! empty( $stylesheet ) ) {
    wp_register_style( 'my-stylesheet', false, array(), true, true );
    wp_add_inline_style( 'my-stylesheet', $stylesheet );
    wp_enqueue_style( 'my-stylesheet' );
}

Installation (JS only)

Install the module

npm install @wordpress/style-engine --save

This package assumes that your code will run in an ES2015+ environment. If you're using an environment that has limited or no support for such language features and APIs, you should include the polyfill shipped in @wordpress/babel-preset-default in your code.

Usage

compileCSS

Generates a stylesheet for a given style object and selector.

Parameters

• style Style: Style object, for example, the value of a block's attributes.style object or the top level styles in theme.json
• options StyleOptions: Options object with settings to adjust how the styles are generated.

Returns

• string: generated stylesheet.

getCSSRules

Returns a JSON representation of the generated CSS rules.

Parameters

• style Style: Style object, for example, the value of a block's attributes.style object or the top level styles in theme.json
• options StyleOptions: Options object with settings to adjust how the styles are generated.

Returns

• GeneratedCSSRule[]: generated styles.

Glossary

A guide to the terms and variable names referenced by the Style Engine package.

Block style (Gutenberg internal)

An object comprising a block's style attribute that contains a block's style values. E.g., { spacing: { margin: '10px' }, color: { ... }, ... }

Context

An identifier for a group of styles that share a common origin or purpose, e.g., 'block-supports' or 'global-styles'. The context is also used as a key to fetch CSS rules from the store.

CSS declaration or (CSS property declaration)

A CSS property paired with a CSS value. E.g., color: pink

CSS declarations block

A set of CSS declarations usually paired with a CSS selector to create a CSS rule.

CSS property

Identifiers that describe stylistic, modifiable features of an HTML element. E.g., border, font-size, width...

CSS rule

A CSS selector followed by a CSS declarations block inside a set of curly braces. Usually found in a CSS stylesheet.

CSS selector

The first component of a CSS rule, a CSS selector is a pattern of elements, classnames or other terms that define the element to which the rule’s CSS definitions apply. E.g., p.my-cool-classname > span. See MDN CSS selectors article.

CSS stylesheet

A collection of CSS rules contained within a file or within an HTML style tag.

CSS value

The value of a CSS property. The value determines how the property is modified. E.g., the 10vw in height: 10vw.

CSS variables (vars) or CSS custom properties

Properties, whose values can be reused in other CSS declarations. Set using custom property notation (e.g., --wp--preset--olive: #808000;) and accessed using the var() function (e.g., color: var( --wp--preset--olive );). See MDN article on CSS custom properties.

Global styles (Gutenberg internal)

A merged block styles object containing values from a theme's theme.json and user styles settings.

Inline styles

Inline styles are CSS declarations that affect a single HTML element, contained within a style attribute

Processor

Performs compilation and optimization on stored CSS rules. See the class `WP_Style_Engine_Processor`.

Store

A data object that contains related styles. See the class `WP_Style_Engine_CSS_Rules_Store`.