@wordpress/style-engine 0.16.0 → 1.0.0

package/class-wp-style-engine.php

@@ -12,12 +12,11 @@ if ( class_exists( 'WP_Style_Engine' ) ) {
 }
 
 /**
- * Singleton class representing the style engine.
+ * Class WP_Style_Engine.
  *
- * Consolidates rendering block styles to reduce duplication and streamline
- * CSS styles generation.
+ * The Style Engine aims to provide a consistent API for rendering styling for blocks across both client-side and server-side applications.
  *
- * This class is for internal core usage and is not supposed to be used by extenders (plugins and/or themes).
+ * This class is for internal Core usage and is not supposed to be used by extenders (plugins and/or themes).
  * This is a low-level API that may need to do breaking changes. Please, use wp_style_engine_get_styles instead.
  *
  * @access private
@@ -35,6 +34,8 @@ class WP_Style_Engine {
 	 *  - property_keys => (array) array of keys whose values represent a valid CSS property, e.g., "margin" or "border".
 	 *  - path          => (array) a path that accesses the corresponding style value in the block style object.
 	 *  - value_func    => (string) the name of a function to generate a CSS definition array for a particular style object. The output of this function should be `array( "$property" => "$value", ... )`.
+	 *
+	 * @var array
 	 */
 	const BLOCK_STYLE_DEFINITIONS_METADATA = array(
 		'color'      => array(
@@ -217,13 +218,13 @@ class WP_Style_Engine {
 	/**
 	 * Util: Extracts the slug in kebab case from a preset string, e.g., "heavenly-blue" from 'var:preset|color|heavenlyBlue'.
 	 *
-	 * @param string? $style_value  A single css preset value.
-	 * @param string  $property_key The CSS property that is the second element of the preset string. Used for matching.
+	 * @param string $style_value  A single CSS preset value.
+	 * @param string $property_key The CSS property that is the second element of the preset string. Used for matching.
 	 *
 	 * @return string The slug, or empty string if not found.
 	 */
 	protected static function get_slug_from_preset_value( $style_value, $property_key ) {
-		if ( is_string( $style_value ) && str_contains( $style_value, "var:preset|{$property_key}|" ) ) {
+		if ( is_string( $style_value ) && is_string( $property_key ) && str_contains( $style_value, "var:preset|{$property_key}|" ) ) {
 			$index_to_splice = strrpos( $style_value, '|' ) + 1;
 			return _wp_to_kebab_case( substr( $style_value, $index_to_splice ) );
 		}
@@ -231,10 +232,10 @@ class WP_Style_Engine {
 	}
 
 	/**
-	 * Util: Generates a css var string, eg var(--wp--preset--color--background) from a preset string, eg. `var:preset|space|50`.
+	 * Util: Generates a CSS var string, e.g., var(--wp--preset--color--background) from a preset string such as `var:preset|space|50`.
 	 *
-	 * @param string $style_value  A single css preset value.
-	 * @param array  $css_vars The css var patterns used to generate the var string.
+	 * @param string   $style_value  A single CSS preset value.
+	 * @param string[] $css_vars     An associate array of CSS var patterns used to generate the var string.
 	 *
 	 * @return string The css var, or an empty string if no match for slug found.
 	 */
@@ -257,7 +258,7 @@ class WP_Style_Engine {
 	 *
 	 * @param string? $style_value  A single css preset value.
 	 *
-	 * @return boolean
+	 * @return bool
 	 */
 	protected static function is_valid_style_value( $style_value ) {
 		return '0' === $style_value || ! empty( $style_value );
@@ -266,9 +267,9 @@ class WP_Style_Engine {
 	/**
 	 * Stores a CSS rule using the provided CSS selector and CSS declarations.
 	 *
-	 * @param string $store_name       A valid store key.
-	 * @param string $css_selector     When a selector is passed, the function will return a full CSS rule `$selector { ...rules }`, otherwise a concatenated string of properties and values.
-	 * @param array  $css_declarations An array of parsed CSS property => CSS value pairs.
+	 * @param string   $store_name       A valid store key.
+	 * @param string   $css_selector     When a selector is passed, the function will return a full CSS rule `$selector { ...rules }`, otherwise a concatenated string of properties and values.
+	 * @param string[] $css_declarations An associative array of CSS definitions, e.g., array( "$property" => "$value", "$property" => "$value" ).
 	 *
 	 * @return void.
 	 */
@@ -294,16 +295,21 @@ class WP_Style_Engine {
 	 * Returns classnames and CSS based on the values in a styles object.
 	 * Return values are parsed based on the instructions in BLOCK_STYLE_DEFINITIONS_METADATA.
 	 *
+	 * @since 6.1.0
+	 *
 	 * @param array $block_styles The style object.
-	 * @param array $options      array(
-	 *     'selector'                   => (string) When a selector is passed, `generate()` will return a full CSS rule `$selector { ...rules }`, otherwise a concatenated string of properties and values.
-	 *     'convert_vars_to_classnames' => (boolean) Whether to skip converting CSS var:? values to var( --wp--preset--* ) values. Default is `false`.
-	 * );.
+	 * @param array $options      {
+	 *     Optional. An array of options. Default empty array.
+	 *
+	 *     @type bool        $convert_vars_to_classnames Whether to skip converting incoming CSS var patterns, e.g., `var:preset|<PRESET_TYPE>|<PRESET_SLUG>`, to var( --wp--preset--* ) values. Default `false`.
+	 *     @type string      $selector                   Optional. When a selector is passed, the value of `$css` in the return value will comprise a full CSS rule `$selector { ...$css_declarations }`,
+	 *                                                   otherwise, the value will be a concatenated string of CSS declarations.
+	 * }
 	 *
-	 * @return array array(
-	 *     'declarations' => (array) An array of parsed CSS property => CSS value pairs.
-	 *     'classnames'   => (array) A flat array of classnames.
-	 * );
+	 * @return array {
+	 *     @type string   $classnames   Classnames separated by a space.
+	 *     @type string[] $declarations An associative array of CSS definitions, e.g., array( "$property" => "$value", "$property" => "$value" ).
+	 * }
 	 */
 	public static function parse_block_styles( $block_styles, $options ) {
 		$parsed_styles = array(
@@ -335,12 +341,12 @@ class WP_Style_Engine {
 	}
 
 	/**
-	 * Returns classnames, and generates classname(s) from a CSS preset property pattern, e.g., 'var:preset|color|heavenly-blue'.
+	 * Returns classnames, and generates classname(s) from a CSS preset property pattern, e.g., '`var:preset|<PRESET_TYPE>|<PRESET_SLUG>`'.
 	 *
-	 * @param array         $style_value      A single raw style value or css preset property from the generate() $block_styles array.
-	 * @param array<string> $style_definition A single style definition from BLOCK_STYLE_DEFINITIONS_METADATA.
+	 * @param array $style_value      A single raw style value or css preset property from the $block_styles array.
+	 * @param array $style_definition A single style definition from BLOCK_STYLE_DEFINITIONS_METADATA.
 	 *
-	 * @return array        An array of CSS classnames.
+	 * @return array|string[] An array of CSS classnames, or empty array.
 	 */
 	protected static function get_classnames( $style_value, $style_definition ) {
 		if ( empty( $style_value ) ) {
@@ -357,10 +363,12 @@ class WP_Style_Engine {
 				$slug = static::get_slug_from_preset_value( $style_value, $property_key );
 
 				if ( $slug ) {
-					// Right now we expect a classname pattern to be stored in BLOCK_STYLE_DEFINITIONS_METADATA.
-					// One day, if there are no stored schemata, we could allow custom patterns or
-					// generate classnames based on other properties
-					// such as a path or a value or a prefix passed in options.
+					/*
+					 * Right now we expect a classname pattern to be stored in BLOCK_STYLE_DEFINITIONS_METADATA.
+					 * One day, if there are no stored schemata, we could allow custom patterns or
+					 * generate classnames based on other properties
+					 * such as a path or a value or a prefix passed in options.
+					 */
 					$classnames[] = strtr( $classname, array( '$slug' => $slug ) );
 				}
 			}
@@ -372,15 +380,19 @@ class WP_Style_Engine {
 	/**
 	 * Returns an array of CSS declarations based on valid block style values.
 	 *
-	 * @param array         $style_value          A single raw style value from the generate() $block_styles array.
-	 * @param array<string> $style_definition     A single style definition from BLOCK_STYLE_DEFINITIONS_METADATA.
-	 * @param array         $options              array(
-	 *     'convert_vars_to_classnames' => (boolean) Whether to skip converting CSS var:? values to var( --wp--preset--* ) values. Default is `false`.
-	 * );.
+	 * @since 6.1.0
 	 *
-	 * @return array        An array of CSS definitions, e.g., array( "$property" => "$value" ).
+	 * @param array $style_value      A single raw style value from $block_styles array.
+	 * @param array $style_definition A single style definition from BLOCK_STYLE_DEFINITIONS_METADATA.
+	 * @param array $options          {
+	 *     Optional. An array of options. Default empty array.
+	 *
+	 *     @type bool $convert_vars_to_classnames Whether to skip converting incoming CSS var patterns, e.g., `var:preset|<PRESET_TYPE>|<PRESET_SLUG>`, to var( --wp--preset--* ) values. Default `false`.
+	 * }
+	 *
+	 * @return string[] An associative array of CSS definitions, e.g., array( "$property" => "$value", "$property" => "$value" ).
 	 */
-	protected static function get_css_declarations( $style_value, $style_definition, $options ) {
+	protected static function get_css_declarations( $style_value, $style_definition, $options = array() ) {
 		if ( isset( $style_definition['value_func'] ) && is_callable( $style_definition['value_func'] ) ) {
 			return call_user_func( $style_definition['value_func'], $style_value, $style_definition, $options );
 		}
@@ -389,8 +401,10 @@ class WP_Style_Engine {
 		$style_property_keys  = $style_definition['property_keys'];
 		$should_skip_css_vars = isset( $options['convert_vars_to_classnames'] ) && true === $options['convert_vars_to_classnames'];
 
-		// Build CSS var values from var:? values, e.g, `var(--wp--css--rule-slug )`
-		// Check if the value is a CSS preset and there's a corresponding css_var pattern in the style definition.
+		/*
+		 * Build CSS var values from `var:preset|<PRESET_TYPE>|<PRESET_SLUG>` values, e.g, `var(--wp--css--rule-slug )`.
+		 * Check if the value is a CSS preset and there's a corresponding css_var pattern in the style definition.
+		 */
 		if ( is_string( $style_value ) && str_contains( $style_value, 'var:' ) ) {
 			if ( ! $should_skip_css_vars && ! empty( $style_definition['css_vars'] ) ) {
 				$css_var = static::get_css_var_value( $style_value, $style_definition['css_vars'] );
@@ -401,9 +415,11 @@ class WP_Style_Engine {
 			return $css_declarations;
 		}
 
-		// Default rule builder.
-		// If the input contains an array, assume box model-like properties
-		// for styles such as margins and padding.
+		/*
+		 * Default rule builder.
+		 * If the input contains an array, assume box model-like properties
+		 * for styles such as margins and padding.
+		 */
 		if ( is_array( $style_value ) ) {
 			// Bail out early if the `'individual'` property is not defined.
 			if ( ! isset( $style_property_keys['individual'] ) ) {
@@ -436,22 +452,26 @@ class WP_Style_Engine {
 	 * "border-{top|right|bottom|left}-{color|width|style}: {value};" or,
 	 * "border-image-{outset|source|width|repeat|slice}: {value};"
 	 *
-	 * @param array $style_value                    A single raw Gutenberg style attributes value for a CSS property.
-	 * @param array $individual_property_definition A single style definition from BLOCK_STYLE_DEFINITIONS_METADATA.
-	 * @param array $options                        array(
-	 *     'convert_vars_to_classnames' => (boolean) Whether to skip converting CSS var:? values to var( --wp--preset--* ) values. Default is `false`.
-	 * );.
+	 * @param array $style_value                    A single raw style value from $block_styles array.
+	 * @param array $individual_property_definition A single style definition from BLOCK_STYLE_DEFINITIONS_METADATA representing an individual property of a CSS property, e.g., 'top' in 'border-top'.
+	 * @param array $options                        {
+	 *     Optional. An array of options. Default empty array.
 	 *
-	 * @return array An array of CSS definitions, e.g., array( "$property" => "$value" ).
+	 *     @type bool $convert_vars_to_classnames Whether to skip converting incoming CSS var patterns, e.g., `var:preset|<PRESET_TYPE>|<PRESET_SLUG>`, to var( --wp--preset--* ) values. Default `false`.
+	 * }
+	 *
+	 * @return string[] An associative array of CSS definitions, e.g., array( "$property" => "$value", "$property" => "$value" ).
 	 */
-	protected static function get_individual_property_css_declarations( $style_value, $individual_property_definition, $options ) {
+	protected static function get_individual_property_css_declarations( $style_value, $individual_property_definition, $options = array() ) {
 		if ( ! is_array( $style_value ) || empty( $style_value ) || empty( $individual_property_definition['path'] ) ) {
 			return array();
 		}
 
-		// The first item in $individual_property_definition['path'] array tells us the style property, e.g., "border".
-		// We use this to get a corresponding CSS style definition such as "color" or "width" from the same group.
-		// The second item in $individual_property_definition['path'] array refers to the individual property marker, e.g., "top".
+		/*
+		 * The first item in $individual_property_definition['path'] array tells us the style property, e.g., "border".
+		 * We use this to get a corresponding CSS style definition such as "color" or "width" from the same group.
+		 * The second item in $individual_property_definition['path'] array refers to the individual property marker, e.g., "top".
+		 */
 		$definition_group_key    = $individual_property_definition['path'][0];
 		$individual_property_key = $individual_property_definition['path'][1];
 		$should_skip_css_vars    = isset( $options['convert_vars_to_classnames'] ) && true === $options['convert_vars_to_classnames'];
@@ -481,8 +501,8 @@ class WP_Style_Engine {
 	/**
 	 * Returns compiled CSS from css_declarations.
 	 *
-	 * @param array  $css_declarations An array of parsed CSS property => CSS value pairs.
-	 * @param string $css_selector     When a selector is passed, the function will return a full CSS rule `$selector { ...rules }`, otherwise a concatenated string of properties and values.
+	 * @param string[] $css_declarations An associative array of CSS definitions, e.g., array( "$property" => "$value", "$property" => "$value" ).
+	 * @param string   $css_selector     When a selector is passed, the function will return a full CSS rule `$selector { ...rules }`, otherwise a concatenated string of properties and values.
 	 *
 	 * @return string A compiled CSS string.
 	 */
@@ -505,10 +525,12 @@ class WP_Style_Engine {
 	 * Returns a compiled stylesheet from stored CSS rules.
 	 *
 	 * @param WP_Style_Engine_CSS_Rule[] $css_rules An array of WP_Style_Engine_CSS_Rule objects from a store or otherwise.
-	 * @param array                      $options array(
-	 *    'optimize' => (boolean) Whether to optimize the CSS output, e.g., combine rules.
-	 *    'prettify' => (boolean) Whether to add new lines to output.
-	 * );.
+	 * @param array                      $options   {
+	 *     Optional. An array of options. Default empty array.
+	 *
+	 *     @type bool $optimize Whether to optimize the CSS output, e.g., combine rules. Default is `false`.
+	 *     @type bool $prettify Whether to add new lines and indents to output. Default is the test of whether the global constant `SCRIPT_DEBUG` is defined.
+	 * }
 	 *
 	 * @return string A compiled stylesheet from stored CSS rules.
 	 */
@@ -518,137 +540,3 @@ class WP_Style_Engine {
 		return $processor->get_css( $options );
 	}
 }
-
-/**
- * Global public interface method 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.
- * See: https://developer.wordpress.org/block-editor/reference-guides/theme-json-reference/theme-json-living/#styles and
- * https://developer.wordpress.org/block-editor/reference-guides/block-api/block-supports/
- *
- * Example usage:
- *
- * $styles = wp_style_engine_get_styles( array( 'color' => array( 'text' => '#cccccc' ) ) );
- * // Returns `array( 'css' => 'color: #cccccc', 'declarations' => array( 'color' => '#cccccc' ), 'classnames' => 'has-color' )`.
- *
- * @access public
- *
- * @param array                 $block_styles The style object.
- * @param array<string|boolean> $options      array(
- *     'context' => (string|null) An identifier describing the origin of the style object, e.g., 'block-supports' or 'global-styles'. Default is 'block-supports'.
- *                  When set, the style engine will attempt to store the CSS rules, where a selector is also passed.
- *     '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.
- * );.
- *
- * @return array<string|array> 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.
- * );
- */
-function wp_style_engine_get_styles( $block_styles, $options = array() ) {
-	if ( ! class_exists( 'WP_Style_Engine' ) ) {
-		return array();
-	}
-
-	$options = wp_parse_args(
-		$options,
-		array(
-			'selector'                   => null,
-			'context'                    => null,
-			'convert_vars_to_classnames' => false,
-		)
-	);
-
-	$parsed_styles = WP_Style_Engine::parse_block_styles( $block_styles, $options );
-
-	// Output.
-	$styles_output = array();
-
-	if ( ! empty( $parsed_styles['declarations'] ) ) {
-		$styles_output['css']          = WP_Style_Engine::compile_css( $parsed_styles['declarations'], $options['selector'] );
-		$styles_output['declarations'] = $parsed_styles['declarations'];
-		if ( ! empty( $options['context'] ) ) {
-			WP_Style_Engine::store_css_rule( $options['context'], $options['selector'], $parsed_styles['declarations'] );
-		}
-	}
-
-	if ( ! empty( $parsed_styles['classnames'] ) ) {
-		$styles_output['classnames'] = implode( ' ', array_unique( $parsed_styles['classnames'] ) );
-	}
-
-	return array_filter( $styles_output );
-}
-
-/**
- * Returns compiled CSS from a collection of selectors and declarations.
- * This won't add to any store, but is useful for returning a compiled style sheet from any CSS selector + declarations combos.
- *
- * @access public
- *
- * @param array<array>  $css_rules array(
- *      array(
- *          'selector'    => (string) A CSS selector.
- *          declarations' => (boolean) An array of CSS definitions, e.g., array( "$property" => "$value" ).
- *      )
- *  );.
- * @param array<string> $options array(
- *     'context' => (string|null) An identifier describing the origin of the style object, e.g., 'block-supports' or 'global-styles'. Default is 'block-supports'.
- *                  When set, the style engine will attempt to store the CSS rules.
- *    'optimize' => (boolean) Whether to optimize the CSS output, e.g., combine rules.
- *    'prettify' => (boolean) Whether to add new lines to output.
- * );.
- *
- * @return string A compiled CSS string.
- */
-function wp_style_engine_get_stylesheet_from_css_rules( $css_rules, $options = array() ) {
-	if ( ! class_exists( 'WP_Style_Engine' ) || empty( $css_rules ) ) {
-		return '';
-	}
-
-	$options = wp_parse_args(
-		$options,
-		array(
-			'context' => null,
-		)
-	);
-
-	$css_rule_objects = array();
-	foreach ( $css_rules as $css_rule ) {
-		if ( empty( $css_rule['selector'] ) || empty( $css_rule['declarations'] ) || ! is_array( $css_rule['declarations'] ) ) {
-			continue;
-		}
-
-		if ( ! empty( $options['context'] ) ) {
-			WP_Style_Engine::store_css_rule( $options['context'], $css_rule['selector'], $css_rule['declarations'] );
-		}
-
-		$css_rule_objects[] = new WP_Style_Engine_CSS_Rule( $css_rule['selector'], $css_rule['declarations'] );
-	}
-
-	if ( empty( $css_rule_objects ) ) {
-		return '';
-	}
-
-	return WP_Style_Engine::compile_stylesheet_from_css_rules( $css_rule_objects, $options );
-}
-
-/**
- * Returns compiled CSS from a store, if found.
- *
- * @access public
- *
- * @param string $store_name A valid store name.
- * @param array  $options    array(
- *    'optimize' => (boolean) Whether to optimize the CSS output, e.g., combine rules.
- *    'prettify' => (boolean) Whether to add new lines to output.
- * );.
- * @return string A compiled CSS string.
- */
-function wp_style_engine_get_stylesheet_from_context( $store_name, $options = array() ) {
-	if ( ! class_exists( 'WP_Style_Engine' ) || empty( $store_name ) ) {
-		return '';
-	}
-
-	return WP_Style_Engine::compile_stylesheet_from_css_rules( WP_Style_Engine::get_store( $store_name )->get_all_rules(), $options );
-}

package/docs/using-the-style-engine-with-block-supports.md

@@ -0,0 +1,151 @@
+# Using the Style Engine to generate block supports styles
+
+[Block supports](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-supports/) is the API that allows a block to declare support for certain features.
+
+Where a block declares support for a specific style group or property, e.g., "spacing" or "spacing.padding", the block's attributes are extended to include a **style object**.
+
+For example:
+
+```json
+{
+    "attributes": {
+        "style": {
+            "spacing": {
+                "margin": {
+                    "top": "10px"
+                },
+                "padding": "1em"
+            },
+            "typography": {
+                "fontSize": "2.2rem"
+            }
+        }
+    }
+}
+```
+
+Using this object, the Style Engine can generate the classes and CSS required to style the block element.
+
+The global function `wp_style_engine_get_styles` accepts a style object as its first argument, and will output compiled CSS and an array of CSS declaration property/value pairs.
+
+```php
+$block_styles =  array(
+     'spacing' => array( 'padding' => '10px', 'margin' => array( 'top' => '1em') ),
+     'typography' => array( 'fontSize' => '2.2rem' ),
+);
+$styles = wp_style_engine_get_styles(
+    $block_styles
+);
+print_r( $styles );
+
+/*
+array(
+    'css'          => 'padding:10px;margin-top:1em;font-size:2.2rem',
+    'declarations' => array( 'padding' => '10px', 'margin-top' => '1em', 'font-size' => '2.2rem' )
+)
+*/
+```
+
+## Checking for block support and skip serialization
+
+Before passing the block style object to the Style Engine, it's important to take into account:
+
+1. whether the theme has elected to support a particular block style, and
+2. whether a block has elected to "skip serialization" of that particular block style, that is, opt-out of automatic application of styles to the block's element (usually in order to do it via the block's internals). See the [block API documentation](https://developer.wordpress.org/block-editor/explanations/architecture/styles/#block-supports-api) for further information.
+
+If a block either:
+
+- has no support for a specific style, or 
+- skips serialization of that style
+
+it's likely that you'll want to remove those style values from the style object.
+
+For example:
+
+```php
+// Check if a block has support using block_has_support (https://developer.wordpress.org/reference/functions/block_has_support/)
+$has_padding_support = block_has_support( $block_type, array( 'spacing', 'padding' ), false ); // Returns true.
+$has_margin_support  = block_has_support( $block_type, array( 'spacing', 'margin' ), false ); // Returns false.
+
+// Check skipping of serialization.
+$should_skip_padding = wp_should_skip_block_supports_serialization( $block_type, 'spacing', 'padding' ); // Returns true.
+$should_skip_margin  = wp_should_skip_block_supports_serialization( $block_type, 'spacing', 'margin' ); // Returns false.
+
+// Now build the styles object.
+$spacing_block_styles            = array();
+$spacing_block_styles['padding'] = $has_padding_support && ! $skip_padding ? _wp_array_get( $block_attributes['style'], array( 'spacing', 'padding' ), null ) : null;
+$spacing_block_styles['margin']  = $has_margin_support && ! $skip_margin ? _wp_array_get( $block_attributes['style'], array( 'spacing', 'margin' ), null ) : null;
+
+// Now get the styles.
+$styles = wp_style_engine_get_styles( array( 'spacing' => $spacing_block_styles ) );
+
+print_r( $styles );
+
+/*
+// Nothing, because there's no support for margin and the block skip's serialization for padding.
+array()
+*/
+```
+
+## Generating classnames and CSS custom selectors from presets
+
+Many of theme.json's presets will generate both CSS custom properties and CSS rules (consisting of a selector and the CSS declarations) on the frontend.
+
+Styling a block using these presets normally involves adding the selector to the "className" attribute of the block.
+
+For styles that can have preset values, such as text color and font family, the Style Engine knows how to construct the classnames using the preset slug.
+
+To discern CSS values from preset values however, the Style Engine expects a special format.
+
+Preset values must follow the pattern `var:preset|<PRESET_TYPE>|<PRESET_SLUG>`.
+
+When the Style Engine encounters these values, it will parse them and create a CSS value of `var(--wp--preset--font-size--small)` and/or generate a classname if required.
+
+Example:
+
+```php
+// Let's say the block attributes styles contain a fontSize preset slug of "small".
+$preset_font_size        = "var:preset|font-size|{$block_attributes['fontSize']}";
+// Now let's say the block attributes styles contain a backgroundColor preset slug of "blue".
+$preset_background_color = "var:preset|color|{$block_attributes['backgroundColor']}";
+
+$block_styles =  array(
+     'typography' => array( 'fontSize' => $preset_font_size ),
+     'color'      => array( 'background' => $preset_background_color )
+);
+
+$styles = wp_style_engine_get_styles(
+    $block_styles
+);
+print_r( $styles );
+
+/*
+array(
+    'css'        => 'background-color:var(--wp--preset--color--blue);font-size:var(--wp--preset--font-size--small);',
+    'classnames' => 'has-background-color has-blue-background-color has-small-font-size',
+)
+*/
+```
+
+If you don't want the Style Engine to output the CSS custom vars as well, which you might not if you're applying both the CSS and classnames to the block element, you can pass `'convert_vars_to_classnames' => true` in the options array.
+
+```php
+$options = array(
+    // Whether to skip converting CSS var:? values to var( --wp--preset--* ) values. Default is `false`.
+    'convert_vars_to_classnames' => 'true',
+);
+$styles = wp_style_engine_get_styles(
+    $block_styles,
+    $options
+);
+print_r( $styles );
+
+/*
+array(
+    'css'        => 'letter-spacing:12px;', // non-preset-based CSS will still be compiled.
+    'classnames' => 'has-background-color has-blue-background-color has-small-font-size',
+)
+*/
+```
+
+Read more about [global styles](https://developer.wordpress.org/block-editor/explanations/architecture/styles/#global-styles) and [preset CSS custom properties](https://developer.wordpress.org/block-editor/how-to-guides/themes/theme-json/#css-custom-properties-presets-custom) and [theme supports](https://developer.wordpress.org/block-editor/how-to-guides/themes/theme-support/).

package/package.json

@@ -1,13 +1,14 @@
 {
 	"name": "@wordpress/style-engine",
-	"version": "0.16.0",
-	"description": "WordPress Style engine.",
+	"version": "1.0.0",
+	"description": "A suite of parsers and compilers for WordPress styles.",
 	"author": "The WordPress Contributors",
 	"license": "GPL-2.0-or-later",
 	"keywords": [
 		"wordpress",
 		"gutenberg",
 		"styles",
+		"css",
 		"global styles"
 	],
 	"homepage": "https://github.com/WordPress/gutenberg/tree/HEAD/packages/style-engine/README.md",
@@ -34,5 +35,5 @@
 	"publishConfig": {
 		"access": "public"
 	},
-	"gitHead": "0d732d4b184adcb28cc83087603e81b764390d4b"
+	"gitHead": "56ef3f5a754e44155ee79e827c7a1d0efc1ee5aa"
 }