Style engine: remove enqueue flag (#43103)

* Removing `enqueue` flag in favour of `context` to indicate that the style engine should store CSS rules.
Renaming $store_key to $store_name for consistency
Updating tests and README.md
Checking for valid $store_name in WP_Style_Engine_CSS_Rules_Store

* Don't need to pass context to gutenberg_style_engine_get_styles in layout.php because there's no selector and we dont want these styles to be stored anyway

lib/block-supports/elements.php

@@ -106,7 +106,6 @@ function gutenberg_render_elements_support_styles( $pre_render, $block ) {
 		array(
 			'selector' => ".$class_name a",
 			'context'  => 'block-supports',
-			'enqueue'  => true,
 		)
 	);
 

lib/block-supports/layout.php

@@ -210,7 +210,6 @@ function gutenberg_get_layout_style( $selector, $layout, $has_block_gap_support
 			$layout_styles,
 			array(
 				'context' => 'block-supports',
-				'enqueue' => true,
 			)
 		);
 	}

packages/style-engine/README.md

@@ -2,6 +2,27 @@
 
 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](https://github.com/WordPress/gutenberg/issues/38167)
+
 ## Backend API
 
 ### wp_style_engine_get_styles()
@@ -17,8 +38,7 @@ _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'.
-    -   _enqueue_ `boolean` When `true` will attempt to store and enqueue for rendering in a `style` tag on the site frontend.
+        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 }`,
@@ -41,8 +61,7 @@ To enqueue a style for rendering in the site's frontend, the `$options` array re
 
 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
-    batched together and printed in the same HTML style tag. The default is `'block-supports'`.
-3.  **enqueue (boolean)** - tells the style engine to store the styles.
+    stored together.
 
 `wp_style_engine_get_styles` will return the compiled CSS and CSS declarations array.
 
@@ -57,7 +76,6 @@ $styles = wp_style_engine_get_styles(
     array(
         'selector' => '.a-selector',
         'context'  => 'block-supports',
-        'enqueue'  => true,
     )
 );
 print_r( $styles );
@@ -81,8 +99,7 @@ _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'. Default is 'block-supports'.
-    -   _enqueue_ `boolean` When `true` will store using the `context` value as a key.
+        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`.
@@ -113,7 +130,6 @@ $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.
-        'enqueue'  => true, // Render the styles for output.
     )
 );
 print_r( $stylesheet ); // .wp-pumpkin, .wp-kumquat {color:orange}.wp-tomato{color:red;padding:100px}
@@ -125,13 +141,15 @@ Returns compiled CSS from a store, if found.
 
 _Parameters_
 
--   _$store_key_ `string` An identifier describing the origin of the style object, e.g., 'block-supports' or ' global-styles'. Default is 'block-supports'.
+-   _$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.
+
 ```php
 // First register some styles.
 $styles = array(
@@ -152,6 +170,11 @@ $stylesheet = wp_style_engine_get_stylesheet_from_css_rules(
 // Later, fetch compiled rules from store.
 $stylesheet = gutenberg_style_engine_get_stylesheet_from_store( '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)
@@ -167,26 +190,37 @@ limited or no support for such language features and APIs, you should
 include [the polyfill shipped in `@wordpress/babel-preset-default`](https://github.com/WordPress/gutenberg/tree/HEAD/packages/babel-preset-default#polyfill)
 in your code._
 
-## Important
+## Usage
 
-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.
+<!-- START TOKEN(Autogenerated API docs) -->
 
-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:
+### generate
 
-**TODO List:**
+Generates a stylesheet for a given style object and selector.
 
--   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).
+_Parameters_
 
-See [Tracking: Add a Style Engine to manage rendering block styles #38167](https://github.com/WordPress/gutenberg/issues/38167)
+-   _style_ `Style`: Style object.
+-   _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.
+-   _options_ `StyleOptions`: Options object with settings to adjust how the styles are generated.
+
+_Returns_
+
+-   `GeneratedCSSRule[]`: generated styles.
+
+<!-- END TOKEN(Autogenerated API docs) -->
 
 ## Glossary
 
@@ -195,8 +229,6 @@ A guide to the terms and variable names referenced by the Style Engine package.
 <dl>
   <dt>Block style (Gutenberg internal)</dt>
   <dd>An object comprising a block's style attribute that contains a block's style values. E.g., <code>{ spacing: { margin: '10px' }, color: { ... }, ...  }</code></dd>
-  <dt>Global styles (Gutenberg internal)</dt>
-  <dd>A merged block styles object containing values from a theme's theme.json and user styles settings.</dd>
   <dt>CSS declaration or (CSS property declaration)</dt>
   <dd>A CSS property paired with a CSS value. E.g., <code>color: pink</code> </dd>
   <dt>CSS declarations block</dt>
@@ -213,40 +245,14 @@ A guide to the terms and variable names referenced by the Style Engine package.
   <dd>The value of a CSS property. The value determines how the property is modified. E.g., the <code>10vw</code> in <code>height: 10vw</code>.</dd>
   <dt>CSS variables (vars) or CSS custom properties</dt>
   <dd>Properties, whose values can be reused in other CSS declarations. Set using custom property notation (e.g., <code>--wp--preset--olive: #808000;</code>) and  accessed using the <code>var()</code> function (e.g., <code>color: var( --wp--preset--olive );</code>). See <a href="https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties" target="_blank">MDN article on CSS custom properties</a>.</dd>
+  <dt>Global styles (Gutenberg internal)</dt>
+  <dd>A merged block styles object containing values from a theme's theme.json and user styles settings.</dd>
   <dt>Inline styles</dt>
   <dd>Inline styles are CSS declarations that affect a single HTML element, contained within a style attribute</dd>
+  <dt>Processor</dt>
+  <dd>Performs compilation and optimization on stored CSS rules. See the class `WP_Style_Engine_Processor`.</dd>
+  <dt>Store</dt>
+  <dd>A data object that contains related styles. See the class `WP_Style_Engine_CSS_Rules_Store`.</dd>
 </dl>
 
-## Usage
-
-<!-- START TOKEN(Autogenerated API docs) -->
-
-### generate
-
-Generates a stylesheet for a given style object and selector.
-
-_Parameters_
-
--   _style_ `Style`: Style object.
--   _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.
--   _options_ `StyleOptions`: Options object with settings to adjust how the styles are generated.
-
-_Returns_
-
--   `GeneratedCSSRule[]`: generated styles.
-
-<!-- END TOKEN(Autogenerated API docs) -->
-
 <br/><br/><p align="center"><img src="https://s.w.org/style/images/codeispoetry.png?1" alt="Code is Poetry." /></p>

packages/style-engine/class-wp-style-engine-css-rules-store.php

@@ -46,9 +46,12 @@ class WP_Style_Engine_CSS_Rules_Store {
 	 *
 	 * @param string $store_name The name of the store.
 	 *
-	 * @return WP_Style_Engine_CSS_Rules_Store
+	 * @return WP_Style_Engine_CSS_Rules_Store|void
 	 */
 	public static function get_store( $store_name = 'default' ) {
+		if ( ! is_string( $store_name ) || empty( $store_name ) ) {
+			return;
+		}
 		if ( ! isset( static::$stores[ $store_name ] ) ) {
 			static::$stores[ $store_name ] = new static();
 			// Set the store name.
@@ -110,7 +113,7 @@ public function get_all_rules() {
 	 *
 	 * @param string $selector The CSS selector.
 	 *
-	 * @return WP_Style_Engine_CSS_Rule|null Returns a WP_Style_Engine_CSS_Rule object, or null if the selector is empty.
+	 * @return WP_Style_Engine_CSS_Rule|void Returns a WP_Style_Engine_CSS_Rule object, or null if the selector is empty.
 	 */
 	public function add_rule( $selector ) {
 		$selector = trim( $selector );

packages/style-engine/class-wp-style-engine.php

@@ -18,7 +18,7 @@
  * CSS styles generation.
  *
  * 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 gutenberg_style_engine_get_styles instead.
+ * This is a low-level API that may need to do breaking changes. Please, use wp_style_engine_get_styles instead.
  *
  * @access private
  */
@@ -268,30 +268,30 @@ protected static function is_valid_style_value( $style_value ) {
 	}
 
 	/**
-	 * Stores a CSS rule using the provide CSS selector and CSS declarations.
+	 * Stores a CSS rule using the provided CSS selector and CSS declarations.
 	 *
-	 * @param string $store_key        A valid store key.
+	 * @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.
 	 *
 	 * @return void.
 	 */
-	public static function store_css_rule( $store_key, $css_selector, $css_declarations ) {
-		if ( empty( $store_key ) || empty( $css_selector ) || empty( $css_declarations ) ) {
+	public static function store_css_rule( $store_name, $css_selector, $css_declarations ) {
+		if ( empty( $store_name ) || empty( $css_selector ) || empty( $css_declarations ) ) {
 			return;
 		}
-		static::get_store( $store_key )->add_rule( $css_selector )->add_declarations( $css_declarations );
+		static::get_store( $store_name )->add_rule( $css_selector )->add_declarations( $css_declarations );
 	}
 
 	/**
 	 * Returns a store by store key.
 	 *
-	 * @param string $store_key A store key.
+	 * @param string $store_name A store key.
 	 *
 	 * @return WP_Style_Engine_CSS_Rules_Store
 	 */
-	public static function get_store( $store_key ) {
-		return WP_Style_Engine_CSS_Rules_Store::get_store( $store_key );
+	public static function get_store( $store_name ) {
+		return WP_Style_Engine_CSS_Rules_Store::get_store( $store_name );
 	}
 
 	/**
@@ -532,8 +532,8 @@ public static function compile_stylesheet_from_css_rules( $css_rules ) {
  *
  * @param array                 $block_styles The style object.
  * @param array<string|boolean> $options      array(
- *     'context'                    => (string) An identifier describing the origin of the style object, e.g., 'block-supports' or 'global-styles'. Default is 'block-supports'.
- *     'enqueue'                    => (boolean) When `true` will attempt to store and enqueue for rendering on the frontend.
+ *     '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.
  * );.
@@ -550,18 +550,12 @@ function wp_style_engine_get_styles( $block_styles, $options = array() ) {
 	}
 	$defaults = array(
 		'selector'                   => null,
-		'context'                    => 'block-supports',
+		'context'                    => null,
 		'convert_vars_to_classnames' => false,
-		'enqueue'                    => false,
 	);
 
 	$options       = wp_parse_args( $options, $defaults );
-	$parsed_styles = null;
-
-	// Block supports styles.
-	if ( 'block-supports' === $options['context'] ) {
-		$parsed_styles = WP_Style_Engine::parse_block_styles( $block_styles, $options );
-	}
+	$parsed_styles = WP_Style_Engine::parse_block_styles( $block_styles, $options );
 
 	// Output.
 	$styles_output = array();
@@ -573,7 +567,7 @@ function wp_style_engine_get_styles( $block_styles, $options = 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 ( true === $options['enqueue'] ) {
+		if ( ! empty( $options['context'] ) ) {
 			WP_Style_Engine::store_css_rule( $options['context'], $options['selector'], $parsed_styles['declarations'] );
 		}
 	}
@@ -598,8 +592,8 @@ function wp_style_engine_get_styles( $block_styles, $options = array() ) {
  *      )
  *  );.
  * @param array<string> $options array(
- *     'context' => (string) An identifier describing the origin of the style object, e.g., 'block-supports' or 'global-styles'. Default is 'block-supports'.
- *     'enqueue' => (boolean) When `true` will attempt to store and enqueue for rendering on the frontend.
+ *     '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.
  * );.
  *
  * @return string A compiled CSS string.
@@ -610,8 +604,7 @@ function wp_style_engine_get_stylesheet_from_css_rules( $css_rules, $options = a
 	}
 
 	$defaults         = array(
-		'context' => 'block-supports',
-		'enqueue' => false,
+		'context' => null,
 	);
 	$options          = wp_parse_args( $options, $defaults );
 	$css_rule_objects = array();
@@ -621,7 +614,7 @@ function wp_style_engine_get_stylesheet_from_css_rules( $css_rules, $options = a
 			continue;
 		}
 
-		if ( true === $options['enqueue'] ) {
+		if ( ! empty( $options['context'] ) ) {
 			WP_Style_Engine::store_css_rule( $options['context'], $css_rule['selector'], $css_rule['declarations'] );
 		}
 
@@ -640,16 +633,16 @@ function wp_style_engine_get_stylesheet_from_css_rules( $css_rules, $options = a
  *
  * @access public
  *
- * @param string $store_key A valid store key.
+ * @param string $store_name A valid store name.
  *
  * @return string A compiled CSS string.
  */
-function wp_style_engine_get_stylesheet_from_store( $store_key ) {
-	if ( ! class_exists( 'WP_Style_Engine' ) || empty( $store_key ) ) {
+function wp_style_engine_get_stylesheet_from_store( $store_name ) {
+	if ( ! class_exists( 'WP_Style_Engine' ) || empty( $store_name ) ) {
 		return '';
 	}
 
-	$store = WP_Style_Engine::get_store( $store_key );
+	$store = WP_Style_Engine::get_store( $store_name );
 
 	return WP_Style_Engine::compile_stylesheet_from_css_rules( $store->get_all_rules() );
 }