@wordpress/style-engine 0.13.0 → 0.14.0

package/CHANGELOG.md

@@ -2,6 +2,8 @@
 
 ## Unreleased
 
+## 0.14.0 (2022-08-10)
+
 ## 0.13.0 (2022-07-27)
 
 ## 0.12.0 (2022-07-13)

package/README.md

@@ -2,6 +2,158 @@
 
 The Style Engine powering global styles and block customizations.
 
+## 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](https://developer.wordpress.org/block-editor/reference-guides/theme-json-reference/theme-json-living/#styles)
+or
+the [top level styles in theme.json](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-supports/)
+.
+
+_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.
+    -   _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`
+
+```php
+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
+    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.
+
+`wp_style_engine_get_styles` will return the compiled CSS and CSS declarations array.
+
+#### Usage
+
+```php
+$block_styles =  array(
+     'spacing' => array( 'padding' => '100px' )
+);
+$styles = wp_style_engine_get_styles(
+    $block_styles,
+    array(
+        'selector' => '.a-selector',
+        'context'  => 'block-supports',
+        'enqueue'  => true,
+    )
+);
+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'. Default is 'block-supports'.
+    -   _enqueue_ `boolean` When `true` will store using the `context` value as a key.
+
+_Returns_
+`string` A compiled CSS string based on `$css_rules`.
+
+#### Usage
+
+```php
+$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.
+        'enqueue'  => true, // Render the styles for output.
+    )
+);
+print_r( $stylesheet ); // .wp-pumpkin, .wp-kumquat {color:orange}.wp-tomato{color:red;padding:100px}
+```
+
+### wp_style_engine_get_stylesheet_from_store()
+
+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'.
+
+_Returns_
+`string` A compiled CSS string from the stored CSS rules.
+
+#### Usage
+
+```php
+// 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 store.
+$stylesheet = gutenberg_style_engine_get_stylesheet_from_store( 'fruit-styles' );
+print_r( $stylesheet ); // .wp-apple{color:green;}
+```
+
 ## Installation (JS only)
 
 Install the module
@@ -10,13 +162,18 @@ 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`](https://github.com/WordPress/gutenberg/tree/HEAD/packages/babel-preset-default#polyfill) in your code._
+_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`](https://github.com/WordPress/gutenberg/tree/HEAD/packages/babel-preset-default#polyfill)
+in your code._
 
 ## 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.
+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:
+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:**
 
@@ -26,7 +183,8 @@ Because this package is experimental and still in development it does not yet ge
 -   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).
+-   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)
 

package/class-wp-style-engine-css-declarations.php

@@ -113,18 +113,42 @@ class WP_Style_Engine_CSS_Declarations {
 		return $this->declarations;
 	}
 
+	/**
+	 * Filters a CSS property + value pair.
+	 *
+	 * @param string $property The CSS property.
+	 * @param string $value    The value to be filtered.
+	 * @param string $spacer   The spacer between the colon and the value. Defaults to an empty string.
+	 *
+	 * @return string The filtered declaration as a single string.
+	 */
+	protected static function filter_declaration( $property, $value, $spacer = '' ) {
+		if ( isset( $property ) && isset( $value ) ) {
+			return safecss_filter_attr( "{$property}:{$spacer}{$value}" );
+		}
+		return '';
+	}
+
 	/**
 	 * Filters and compiles the CSS declarations.
 	 *
+	 * @param boolean $should_prettify Whether to add spacing, new lines and indents.
+	 * @param number  $indent_count    The number of tab indents to apply to the rule. Applies if `prettify` is `true`.
+	 *
 	 * @return string The CSS declarations.
 	 */
-	public function get_declarations_string() {
+	public function get_declarations_string( $should_prettify = false, $indent_count = 0 ) {
 		$declarations_array  = $this->get_declarations();
 		$declarations_output = '';
+		$indent              = $should_prettify ? str_repeat( "\t", $indent_count ) : '';
+		$suffix              = $should_prettify ? ' ' : '';
+		$suffix              = $should_prettify && $indent_count > 0 ? "\n" : $suffix;
+
 		foreach ( $declarations_array as $property => $value ) {
-			$filtered_declaration = esc_html( safecss_filter_attr( "{$property}: {$value}" ) );
+			$spacer               = $should_prettify ? ' ' : '';
+			$filtered_declaration = static::filter_declaration( $property, $value, $spacer );
 			if ( $filtered_declaration ) {
-				$declarations_output .= $filtered_declaration . '; ';
+				$declarations_output .= "{$indent}{$filtered_declaration};$suffix";
 			}
 		}
 		return rtrim( $declarations_output );

package/class-wp-style-engine-css-rule.php

@@ -51,7 +51,7 @@ class WP_Style_Engine_CSS_Rule {
 	 *
 	 * @param string $selector The CSS selector.
 	 *
-	 * @return WP_Style_Engine_CSS_Rule Returns the object to allow chaining of methods.
+	 * @return WP_Style_Engine_CSS_Rule|void Returns the object to allow chaining of methods.
 	 */
 	public function set_selector( $selector ) {
 		if ( empty( $selector ) ) {
@@ -107,9 +107,23 @@ class WP_Style_Engine_CSS_Rule {
 	/**
 	 * Get the CSS.
 	 *
+	 * @param boolean $should_prettify Whether to add spacing, new lines and indents.
+	 * @param number  $indent_count    The number of tab indents to apply to the rule. Applies if `prettify` is `true`.
+	 *
 	 * @return string
 	 */
-	public function get_css() {
-		return $this->get_selector() . ' {' . $this->declarations->get_declarations_string() . '}';
+	public function get_css( $should_prettify = false, $indent_count = 0 ) {
+		$rule_indent         = $should_prettify ? str_repeat( "\t", $indent_count ) : '';
+		$declarations_indent = $should_prettify ? $indent_count + 1 : 0;
+		$new_line            = $should_prettify ? "\n" : '';
+		$space               = $should_prettify ? ' ' : '';
+		$selector            = $should_prettify ? str_replace( ',', ",\n", $this->get_selector() ) : $this->get_selector();
+		$css_declarations    = $this->declarations->get_declarations_string( $should_prettify, $declarations_indent );
+
+		if ( empty( $css_declarations ) ) {
+			return '';
+		}
+
+		return "{$rule_indent}{$selector}{$space}{{$new_line}{$css_declarations}{$new_line}{$rule_indent}}";
 	}
 }

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

@@ -27,6 +27,14 @@ class WP_Style_Engine_CSS_Rules_Store {
 	 */
 	protected static $stores = array();
 
+
+	/**
+	 * The store name.
+	 *
+	 * @var string
+	 */
+	protected $name = '';
+
 	/**
 	 * An array of CSS Rules objects assigned to the store.
 	 *
@@ -44,9 +52,50 @@ class WP_Style_Engine_CSS_Rules_Store {
 	public static function get_store( $store_name = 'default' ) {
 		if ( ! isset( static::$stores[ $store_name ] ) ) {
 			static::$stores[ $store_name ] = new static();
+			// Set the store name.
+			static::$stores[ $store_name ]->set_name( $store_name );
 		}
 		return static::$stores[ $store_name ];
 	}
+
+	/**
+	 * Get an array of all available stores.
+	 *
+	 * @return WP_Style_Engine_CSS_Rules_Store[]
+	 */
+	public static function get_stores() {
+		return static::$stores;
+	}
+
+	/**
+	 * Clears all stores from static::$stores.
+	 *
+	 * @return void
+	 */
+	public static function remove_all_stores() {
+		static::$stores = array();
+	}
+
+	/**
+	 * Set the store name.
+	 *
+	 * @param string $name The store name.
+	 *
+	 * @return void
+	 */
+	public function set_name( $name ) {
+		$this->name = $name;
+	}
+
+	/**
+	 * Get the store name.
+	 *
+	 * @return string
+	 */
+	public function get_name() {
+		return $this->name;
+	}
+
 	/**
 	 * Get an array of all rules.
 	 *

package/class-wp-style-engine-processor.php

@@ -2,7 +2,7 @@
 /**
  * WP_Style_Engine_Processor
  *
- * Compiles styles from a store of CSS rules.
+ * Compiles styles from stores or collection of CSS rules.
  *
  * @package Gutenberg
  */
@@ -12,42 +12,86 @@ if ( class_exists( 'WP_Style_Engine_Processor' ) ) {
 }
 
 /**
- * Compiles styles from a store of CSS rules.
+ * Compiles styles from stores or collection of CSS rules.
  *
  * @access private
  */
 class WP_Style_Engine_Processor {
 
 	/**
-	 * The Style-Engine Store object.
+	 * The Style-Engine Store objects
 	 *
-	 * @var WP_Style_Engine_CSS_Rules_Store
+	 * @var WP_Style_Engine_CSS_Rules_Store[]
 	 */
-	protected $store;
+	protected $stores = array();
 
 	/**
-	 * Constructor.
+	 * The set of CSS rules that this processor will work on.
 	 *
-	 * @param WP_Style_Engine_CSS_Rules_Store $store The store to render.
+	 * @var WP_Style_Engine_CSS_Rule[]
 	 */
-	public function __construct( WP_Style_Engine_CSS_Rules_Store $store ) {
-		$this->store = $store;
+	protected $css_rules = array();
+
+	/**
+	 * Add a store to the processor.
+	 *
+	 * @param WP_Style_Engine_CSS_Rules_Store $store The store to add.
+	 */
+	public function add_store( WP_Style_Engine_CSS_Rules_Store $store ) {
+		$this->stores[ $store->get_name() ] = $store;
+	}
+
+	/**
+	 * Adds rules to be processed.
+	 *
+	 * @param WP_Style_Engine_CSS_Rule|WP_Style_Engine_CSS_Rule[] $css_rules A single, or an array of, WP_Style_Engine_CSS_Rule objects from a store or otherwise.
+	 */
+	public function add_rules( $css_rules ) {
+		if ( ! is_array( $css_rules ) ) {
+			$css_rules = array( $css_rules );
+		}
+		foreach ( $css_rules as $rule ) {
+			$selector = $rule->get_selector();
+			if ( isset( $this->css_rules[ $selector ] ) ) {
+				$this->css_rules[ $selector ]->add_declarations( $rule->get_declarations() );
+				continue;
+			}
+			$this->css_rules[ $rule->get_selector() ] = $rule;
+		}
 	}
 
 	/**
 	 * Get the CSS rules as a string.
 	 *
+	 * @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 The computed CSS.
 	 */
-	public function get_css() {
+	public function get_css( $options = array() ) {
+		$defaults = array(
+			'optimize' => true,
+			'prettify' => false,
+		);
+		$options  = wp_parse_args( $options, $defaults );
+
+		// If we have stores, get the rules from them.
+		foreach ( $this->stores as $store ) {
+			$this->add_rules( $store->get_all_rules() );
+		}
+
 		// Combine CSS selectors that have identical declarations.
-		$this->combine_rules_selectors();
+		if ( true === $options['optimize'] ) {
+			$this->combine_rules_selectors();
+		}
 
 		// Build the CSS.
-		$css   = '';
-		$rules = $this->store->get_all_rules();
-		foreach ( $rules as $rule ) {
-			$css .= $rule->get_css();
+		$css = '';
+		foreach ( $this->css_rules as $rule ) {
+			$css .= $rule->get_css( $options['prettify'] );
+			$css .= $options['prettify'] ? "\n" : '';
 		}
 		return $css;
 	}
@@ -58,14 +102,12 @@ class WP_Style_Engine_Processor {
 	 * @return void
 	 */
 	private function combine_rules_selectors() {
-		$rules = $this->store->get_all_rules();
-
 		// Build an array of selectors along with the JSON-ified styles to make comparisons easier.
 		$selectors_json = array();
-		foreach ( $rules as $selector => $rule ) {
+		foreach ( $this->css_rules as $rule ) {
 			$declarations = $rule->get_declarations()->get_declarations();
 			ksort( $declarations );
-			$selectors_json[ $selector ] = json_encode( $declarations );
+			$selectors_json[ $rule->get_selector() ] = wp_json_encode( $declarations );
 		}
 
 		// Combine selectors that have the same styles.
@@ -76,18 +118,18 @@ class WP_Style_Engine_Processor {
 			if ( 1 >= count( $duplicates ) ) {
 				continue;
 			}
+
+			$declarations = $this->css_rules[ $selector ]->get_declarations();
+
 			foreach ( $duplicates as $key ) {
 				// Unset the duplicates from the $selectors_json array to avoid looping through them as well.
 				unset( $selectors_json[ $key ] );
-				// Remove the rules from the store.
-				$this->store->remove_rule( $key );
+				// Remove the rules from the rules collection.
+				unset( $this->css_rules[ $key ] );
 			}
 			// Create a new rule with the combined selectors.
-			$new_rule = $this->store->add_rule( implode( ',', $duplicates ) );
-			// Set the declarations. The extra check is in place because `add_rule` in the store can return `null`.
-			if ( $new_rule ) {
-				$new_rule->add_declarations( $rules[ $selector ]->get_declarations() );
-			}
+			$duplicate_selectors                     = implode( ',', $duplicates );
+			$this->css_rules[ $duplicate_selectors ] = new WP_Style_Engine_CSS_Rule( $duplicate_selectors, $declarations );
 		}
 	}
 }