Style engine: pre-core migration documentation and house keeping (#43840

)

* Initial commit. Adding further documentation, cleaning up changelog ready to populate with real changes :P

* Typos, formatting

* Typos, formatting

* Sorting out change log and formatting

* Remove enqueue option. It does nothing.

* Update packages/style-engine/docs/using-the-style-engine-with-block-supports.md

No empty lines! :D

Co-authored-by: Ari Stathopoulos <aristath@gmail.com>

* Update README.md

typo

* Updating manifest.json to include new style engine docs
Splitting the global functions out of the class files
Checking for the directory when loading rather than each individual file

* Adding type annotation

* Updating CHANGELOG.md

* Updated version to prerelease
Reverted JS comments for TS types and rebuilt docs
Removed style engine from bundle exception array

* Rebase after #43886

* Updating change logs and emphasizing that new global JS methods are available since 6.1

* Checking for functions and classes in tests so that Gutenberg tests don't fail during the backport to Core.
This is valid for 6.1. After that, developing the packages might require another solution, such as testing against `gutenberg_` prefixed functions.

* Formatting PHP doc comments and params that describe associative arrays

Updating test function names and annotations.

* Formatting

* Combining tests for get_declarations_string
Updating php doc params

* Adding message parameter to assertions where more than one assertion is used in a test method.

* Updating PHP docs
Testing for WP_Style_Engine_CSS_Rules_Store in WP_Style_Engine_Processor->add_store

* Text domain added to __()

* Refactoring sanitization tests for CSS declarations
Counting calls to mock filters executed in safecss_filter_attr() (kses.php)

* Formatting styleEngine tests
Removing duplicated test (we were already testing context below)

* My blod is typo

* Active voice rather than imperative

* Remove Gutenberg suffix

* Adding message to script loader block support enqueuing expectations

* Grammar, formatting, removing class_exists checks

* Ignore unused variable. This is a common test pattern in Core.

* Remove unusued var in tests

Co-authored-by: Ari Stathopoulos <aristath@gmail.com>

lib/load.php

@@ -115,19 +115,12 @@ function gutenberg_is_experiment_enabled( $name ) {
 require __DIR__ . '/experiments-page.php';
 
 // Copied package PHP files.
-if ( file_exists( __DIR__ . '/../build/style-engine/class-wp-style-engine-gutenberg.php' ) ) {
+if ( is_dir( __DIR__ . '/../build/style-engine' ) ) {
+	require_once __DIR__ . '/../build/style-engine/style-engine-gutenberg.php';
 	require_once __DIR__ . '/../build/style-engine/class-wp-style-engine-gutenberg.php';
-}
-if ( file_exists( __DIR__ . '/../build/style-engine/class-wp-style-engine-css-declarations-gutenberg.php' ) ) {
 	require_once __DIR__ . '/../build/style-engine/class-wp-style-engine-css-declarations-gutenberg.php';
-}
-if ( file_exists( __DIR__ . '/../build/style-engine/class-wp-style-engine-css-rule-gutenberg.php' ) ) {
 	require_once __DIR__ . '/../build/style-engine/class-wp-style-engine-css-rule-gutenberg.php';
-}
-if ( file_exists( __DIR__ . '/../build/style-engine/class-wp-style-engine-css-rules-store-gutenberg.php' ) ) {
 	require_once __DIR__ . '/../build/style-engine/class-wp-style-engine-css-rules-store-gutenberg.php';
-}
-if ( file_exists( __DIR__ . '/../build/style-engine/class-wp-style-engine-processor-gutenberg.php' ) ) {
 	require_once __DIR__ . '/../build/style-engine/class-wp-style-engine-processor-gutenberg.php';
 }
 

packages/dependency-extraction-webpack-plugin/CHANGELOG.md

@@ -2,6 +2,10 @@
 
 ## Unreleased
 
+### New Features
+
+-   Include `@wordpress/style-engine` on the list of external dependencies to allow using `wp.styleEngine` global with WordPress 6.1 and beyond ([#43840](https://github.com/WordPress/gutenberg/pull/43840)).
+
 ## 4.0.0 (2022-08-24)
 
 ### Breaking Change

packages/dependency-extraction-webpack-plugin/lib/util.js

@@ -1,9 +1,5 @@
 const WORDPRESS_NAMESPACE = '@wordpress/';
-const BUNDLED_PACKAGES = [
-	'@wordpress/icons',
-	'@wordpress/interface',
-	'@wordpress/style-engine',
-];
+const BUNDLED_PACKAGES = [ '@wordpress/icons', '@wordpress/interface' ];
 
 /**
  * Default request to global transformation

packages/style-engine/CHANGELOG.md

@@ -2,36 +2,22 @@
 
 ## Unreleased
 
-## 0.16.0 (2022-09-13)
-
-## 0.15.0 (2022-08-24)
-
-## 0.14.0 (2022-08-10)
-
-## 0.13.0 (2022-07-27)
-
-## 0.12.0 (2022-07-13)
-
-## 0.11.0 (2022-06-29)
-
-## 0.10.0 (2022-06-15)
-
-## 0.9.0 (2022-06-01)
-
-## 0.8.0 (2022-05-18)
-
-## 0.7.0 (2022-05-04)
-
-## 0.6.0 (2022-04-21)
-
-## 0.5.0 (2022-04-08)
-
-## 0.4.0 (2022-03-23)
-
-## 0.3.0 (2022-03-11)
-
-## 0.2.0 (2022-02-23)
-
-### New Feature
-
+### Enhancement
+-   Allow for prettified output ([#42909](https://github.com/WordPress/gutenberg/pull/42909)).
+-   Enqueue block supports styles in Gutenberg ([#42880](https://github.com/WordPress/gutenberg/pull/42880)).
+
+### Internal
+-   Move backend scripts to package ([#39736](https://github.com/WordPress/gutenberg/pull/39736)).
+-   Updating docs, formatting, and separating global functions from the main class file ([#43840](https://github.com/WordPress/gutenberg/pull/43840)).
+
+### New Features
+-   Add a WP_Style_Engine_Processor object ([#42463](https://github.com/WordPress/gutenberg/pull/42463)).
+-   Add a WP_Style_Engine_CSS_Declarations object ([#42043](https://github.com/WordPress/gutenberg/pull/42043)).
+-   Add Rules and Store objects ([#42222](https://github.com/WordPress/gutenberg/pull/42222)).
+-   Add elements styles support ([#41732](https://github.com/WordPress/gutenberg/pull/41732)) and ([#40987](https://github.com/WordPress/gutenberg/pull/40987)).
+-   Add typography and color support ([#40665](https://github.com/WordPress/gutenberg/pull/40987)) and ([#40332](https://github.com/WordPress/gutenberg/pull/40332)).
+-   Add border support ([#41803](https://github.com/WordPress/gutenberg/pull/40332)) and ([#40531](https://github.com/WordPress/gutenberg/pull/40531)).
+-   Add margin support to frontend ([#39790](https://github.com/WordPress/gutenberg/pull/39790)).
+-   Add basic block supports to backend ([#39446](https://github.com/WordPress/gutenberg/pull/39446)).
 -   Added initial version of the style engine ([#37978](https://github.com/WordPress/gutenberg/pull/37978)).
+-   Include `@wordpress/style-engine` on the list of external dependencies to allow using `wp.styleEngine` global with WordPress 6.1 and beyond ([#43840](https://github.com/WordPress/gutenberg/pull/43840)).

packages/style-engine/README.md

@@ -1,27 +1,23 @@
 # Style Engine
 
-The Style Engine powering global styles and block customizations.
+The Style Engine aims to provide a consistent API for rendering styling for blocks across both client-side and server-side applications.
 
-## Important
+Initially, it will offer a single, centralized agent responsible for generating block styles, and, in later phases, it will also assume the responsibility of processing and rendering optimized frontend CSS.
 
-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.
+## Important
 
-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:
+This package is new as of WordPress 6.1 and therefore in its infancy.
 
-**TODO List:**
+Upcoming tasks on the roadmap include, but are not limited to, the following:
 
--   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).
+-   Consolidate global and block style rendering and enqueuing (ongoing)
+-   Explore pre-render CSS rule processing with the intention of deduplicating other common and/or repetitive block styles. (ongoing)
+-   Extend the scope of semantic class names and/or design token expression, and encapsulate rules into stable utility classes.
+-   Explore pre-render CSS rule processing with the intention of deduplicating other common and/or repetitive block styles.
+-   Propose a way to control hierarchy and specificity, and make the style hierarchy cascade accessible and predictable. This might include preparing for CSS cascade layers until they become more widely supported, and allowing for opt-in support in Gutenberg via theme.json.
+-   Refactor all blocks to consistently use the "style" attribute for all customizations, that is, deprecate preset-specific attributes such as `attributes.fontSize`.
 
-See [Tracking: Add a Style Engine to manage rendering block styles #38167](https://github.com/WordPress/gutenberg/issues/38167)
+For more information about the roadmap, please refer to [Block editor styles: initiatives and goals](https://make.wordpress.org/core/2022/06/24/block-editor-styles-initiatives-and-goals/) and the [Github project board](https://github.com/orgs/WordPress/projects/19).
 
 ## Backend API
 
@@ -30,8 +26,9 @@ See [Tracking: Add a Style Engine to manage rendering block styles #38167](https
 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/)
-.
+the [top level styles in theme.json](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-supports/).
+
+See also [Using the Style Engine to generate block supports styles](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-style-engine/using-the-style-engine-with-block-supports).
 
 _Parameters_
 
@@ -82,7 +79,7 @@ print_r( $styles );
 
 /*
 array(
-    'css'                 => '.a-selector{padding:10px}'
+    'css'                 => '.a-selector{padding:100px}'
     'declarations'  => array( 'padding' => '100px' )
 )
 */
@@ -132,7 +129,7 @@ $stylesheet = wp_style_engine_get_stylesheet_from_css_rules(
         '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}
+print_r( $stylesheet ); // .wp-pumpkin,.wp-kumquat{color:orange}.wp-tomato{color:red;padding:100px}
 ```
 
 ### wp_style_engine_get_stylesheet_from_context()
@@ -185,10 +182,7 @@ 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._
 
 ## Usage
 
@@ -205,7 +199,11 @@ _Parameters_
 
 _Returns_
 
--   `string`: generated stylesheet.
+-   `string`: A generated stylesheet or inline style declarations.
+
+_Changelog_
+
+`6.1.0` Introduced in WordPress core.
 
 ### getCSSRules
 
@@ -218,7 +216,11 @@ _Parameters_
 
 _Returns_
 
--   `GeneratedCSSRule[]`: generated styles.
+-   `GeneratedCSSRule[]`: A collection of objects containing the selector, if any, the CSS property key (camelcase) and parsed CSS value.
+
+_Changelog_
+
+`6.1.0` Introduced in WordPress core.
 
 <!-- END TOKEN(Autogenerated API docs) -->
 
@@ -239,8 +241,8 @@ A guide to the terms and variable names referenced by the Style Engine package.
   <dd>Identifiers that describe stylistic, modifiable features of an HTML element. E.g., <code>border</code>, <code>font-size</code>, <code>width</code>...</dd>
   <dt>CSS rule</dt>
   <dd>A CSS selector followed by a CSS declarations block inside a set of curly braces. Usually found in a CSS stylesheet.</dd>
-  <dt>CSS selector</dt>
-   <dd>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&rsquo;s CSS definitions apply. E.g., <code>p.my-cool-classname > span</code>. See <a href="https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors" target="_blank">MDN CSS selectors article</a>.</dd>
+  <dt>CSS selector (or CSS class selector)</dt>
+   <dd>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&rsquo;s CSS definitions apply. E.g., <code>p.my-cool-classname > span</code>. A CSS selector matches HTML elements based on the contents of the "class" attribute. See <a href="https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors" target="_blank">MDN CSS selectors article</a>.</dd>
   <dt>CSS stylesheet</dt>
   <dd>A collection of CSS rules contained within a file or within an <a href="https://developer.mozilla.org/en-US/docs/Web/HTML/Element/style" target="_blank">HTML style tag</a>.</dd>
   <dt>CSS value</dt>

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

@@ -31,43 +31,42 @@ class WP_Style_Engine_CSS_Declarations {
 	 * If a `$declarations` array is passed, it will be used to populate
 	 * the initial $declarations prop of the object by calling add_declarations().
 	 *
-	 * @param array $declarations An array of declarations (property => value pairs).
+	 * @param string[] $declarations An associative array of CSS definitions, e.g., array( "$property" => "$value", "$property" => "$value" ).
 	 */
 	public function __construct( $declarations = array() ) {
 		$this->add_declarations( $declarations );
 	}
 
 	/**
-	 * Add a single declaration.
+	 * Adds a single declaration.
 	 *
 	 * @param string $property The CSS property.
 	 * @param string $value    The CSS value.
 	 *
 	 * @return WP_Style_Engine_CSS_Declarations Returns the object to allow chaining methods.
 	 */
 	public function add_declaration( $property, $value ) {
-
-		// Sanitize the property.
+		// Sanitizes the property.
 		$property = $this->sanitize_property( $property );
-		// Bail early if the property is empty.
+		// Bails early if the property is empty.
 		if ( empty( $property ) ) {
 			return $this;
 		}
 
-		// Trim the value. If empty, bail early.
+		// Trims the value. If empty, bail early.
 		$value = trim( $value );
 		if ( '' === $value ) {
 			return $this;
 		}
 
-		// Add the declaration property/value pair.
+		// Adds the declaration property/value pair.
 		$this->declarations[ $property ] = $value;
 
 		return $this;
 	}
 
 	/**
-	 * Remove a single declaration.
+	 * Removes a single declaration.
 	 *
 	 * @param string $property The CSS property.
 	 *
@@ -79,7 +78,7 @@ public function remove_declaration( $property ) {
 	}
 
 	/**
-	 * Add multiple declarations.
+	 * Adds multiple declarations.
 	 *
 	 * @param array $declarations An array of declarations.
 	 *
@@ -93,7 +92,7 @@ public function add_declarations( $declarations ) {
 	}
 
 	/**
-	 * Remove multiple declarations.
+	 * Removes multiple declarations.
 	 *
 	 * @param array $properties An array of properties.
 	 *
@@ -107,7 +106,7 @@ public function remove_declarations( $properties = array() ) {
 	}
 
 	/**
-	 * Get the declarations array.
+	 * Gets the declarations array.
 	 *
 	 * @return array
 	 */
@@ -122,7 +121,7 @@ public function get_declarations() {
 	 * @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.
+	 * @return string The filtered declaration or an empty string.
 	 */
 	protected static function filter_declaration( $property, $value, $spacer = '' ) {
 		$filtered_value = wp_strip_all_tags( $value, true );
@@ -135,8 +134,8 @@ protected static function filter_declaration( $property, $value, $spacer = '' )
 	/**
 	 * 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`.
+	 * @param bool   $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.
 	 */
@@ -158,7 +157,7 @@ public function get_declarations_string( $should_prettify = false, $indent_count
 	}
 
 	/**
-	 * Sanitize property names.
+	 * Sanitizes property names.
 	 *
 	 * @param string $property The CSS property.
 	 *