@wordpress/style-engine 0.5.1 → 0.8.0

package/class-wp-style-engine.php

@@ -16,6 +16,11 @@ if ( class_exists( 'WP_Style_Engine' ) ) {
  *
  * Consolidates rendering block styles to reduce duplication and streamline
  * 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.
+ *
+ * @access private
  */
 class WP_Style_Engine {
 	/**
@@ -29,23 +34,87 @@ class WP_Style_Engine {
 	 * Style definitions that contain the instructions to
 	 * parse/output valid Gutenberg styles from a block's attributes.
 	 * For every style definition, the follow properties are valid:
-	 *
+	 *  - classnames   => an array of classnames to be returned for block styles. The key is a classname or pattern.
+	 *                    A value of `true` means the classname should be applied always. Otherwise a valid CSS property
+	 *                    to match the incoming value, e.g., "color" to match var:preset|color|somePresetName.
 	 *  - property_key => the key that represents a valid CSS property, e.g., "margin" or "border".
 	 *  - path         => a path that accesses the corresponding style value in the block style object.
-	 *  - value_func   => a function to generate an array of valid CSS rules for a particular style object.
-	 *                    For example, `'padding' => 'array( 'top' => '1em' )` will return `array( 'padding-top' => '1em' )`
 	 */
 	const BLOCK_STYLE_DEFINITIONS_METADATA = array(
-		'spacing' => array(
+		'color'      => array(
+			'text'       => array(
+				'property_key' => 'color',
+				'path'         => array( 'color', 'text' ),
+				'classnames'   => array(
+					'has-text-color' => true,
+					'has-%s-color'   => 'color',
+				),
+			),
+			'background' => array(
+				'property_key' => 'background-color',
+				'path'         => array( 'color', 'background' ),
+				'classnames'   => array(
+					'has-background'          => true,
+					'has-%s-background-color' => 'color',
+				),
+			),
+			'gradient'   => array(
+				'property_key' => 'background',
+				'path'         => array( 'color', 'gradient' ),
+				'classnames'   => array(
+					'has-background'             => true,
+					'has-%s-gradient-background' => 'gradient',
+				),
+			),
+		),
+		'spacing'    => array(
 			'padding' => array(
 				'property_key' => 'padding',
 				'path'         => array( 'spacing', 'padding' ),
-				'value_func'   => 'static::get_css_box_rules',
 			),
 			'margin'  => array(
 				'property_key' => 'margin',
 				'path'         => array( 'spacing', 'margin' ),
-				'value_func'   => 'static::get_css_box_rules',
+			),
+		),
+		'typography' => array(
+			'fontSize'       => array(
+				'property_key' => 'font-size',
+				'path'         => array( 'typography', 'fontSize' ),
+				'classnames'   => array(
+					'has-%s-font-size' => 'font-size',
+				),
+			),
+			'fontFamily'     => array(
+				'property_key' => 'font-family',
+				'path'         => array( 'typography', 'fontFamily' ),
+				'classnames'   => array(
+					'has-%s-font-family' => 'font-family',
+				),
+			),
+			'fontStyle'      => array(
+				'property_key' => 'font-style',
+				'path'         => array( 'typography', 'fontStyle' ),
+			),
+			'fontWeight'     => array(
+				'property_key' => 'font-weight',
+				'path'         => array( 'typography', 'fontWeight' ),
+			),
+			'lineHeight'     => array(
+				'property_key' => 'line-height',
+				'path'         => array( 'typography', 'lineHeight' ),
+			),
+			'textDecoration' => array(
+				'property_key' => 'text-decoration',
+				'path'         => array( 'typography', 'textDecoration' ),
+			),
+			'textTransform'  => array(
+				'property_key' => 'text-transform',
+				'path'         => array( 'typography', 'textTransform' ),
+			),
+			'letterSpacing'  => array(
+				'property_key' => 'letter-spacing',
+				'path'         => array( 'typography', 'letterSpacing' ),
 			),
 		),
 	);
@@ -66,26 +135,68 @@ class WP_Style_Engine {
 	}
 
 	/**
-	 * Returns a CSS ruleset based on the instructions in BLOCK_STYLE_DEFINITIONS_METADATA.
+	 * 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.
+	 *
+	 * @return string|null The slug, or null if not found.
+	 */
+	protected static function get_slug_from_preset_value( $style_value, $property_key ) {
+		if ( is_string( $style_value ) && strpos( $style_value, "var:preset|{$property_key}|" ) !== false ) {
+			$index_to_splice = strrpos( $style_value, '|' ) + 1;
+			return _wp_to_kebab_case( substr( $style_value, $index_to_splice ) );
+		}
+		return null;
+	}
+
+	/**
+	 * Returns classnames, and generates classname(s) from a CSS preset property pattern, e.g., 'var:preset|color|heavenly-blue'.
 	 *
-	 * @param string|array  $style_value A single raw Gutenberg style attributes value for a CSS property.
-	 * @param array<string> $path        An array of strings representing a path to the style value.
+	 * @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.
 	 *
-	 * @return array A CSS ruleset compatible with generate().
+	 * @return array        An array of CSS classnames.
 	 */
-	protected function get_block_style_css_rules( $style_value, $path ) {
-		$style_definition = _wp_array_get( static::BLOCK_STYLE_DEFINITIONS_METADATA, $path, null );
-
-		if ( ! empty( $style_definition ) ) {
-			if (
-				isset( $style_definition['value_func'] ) &&
-				is_callable( $style_definition['value_func'] )
-			) {
-				return call_user_func( $style_definition['value_func'], $style_value, $style_definition['property_key'] );
+	protected static function get_classnames( $style_value, $style_definition ) {
+		$classnames = array();
+		if ( ! empty( $style_definition['classnames'] ) ) {
+			foreach ( $style_definition['classnames'] as $classname => $property_key ) {
+				if ( true === $property_key ) {
+					$classnames[] = $classname;
+				}
+
+				$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.
+					$classnames[] = sprintf( $classname, $slug );
+				}
 			}
 		}
 
-		return array();
+		return $classnames;
+	}
+
+	/**
+	 * Returns CSS rules 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.
+	 *
+	 * @return array        An array of CSS rules.
+	 */
+	protected static function get_css( $style_value, $style_definition ) {
+		// Low-specificity check to see if the value is a CSS preset.
+		if ( is_string( $style_value ) && strpos( $style_value, 'var:' ) !== false ) {
+			return array();
+		}
+
+		// If required in the future, style definitions could define a callable `value_func` to generate custom CSS rules.
+		return static::get_css_rules( $style_value, $style_definition['property_key'] );
 	}
 
 	/**
@@ -93,72 +204,78 @@ class WP_Style_Engine {
 	 * Styles are bundled based on the instructions in BLOCK_STYLE_DEFINITIONS_METADATA.
 	 *
 	 * @param array $block_styles An array of styles from a block's attributes.
-	 * @param array $options = array(
-	 *     'inline' => (boolean) Whether to return inline CSS rules destined to be inserted in an HTML `style` attribute.
-	 *     'path'   => (array)   Specify a block style to generate, otherwise it'll try all in BLOCK_STYLE_DEFINITIONS_METADATA.
-	 * );.
 	 *
-	 * @return string A CSS ruleset formatted to be placed in an HTML `style` attribute.
+	 * @return array|null array(
+	 *     'styles'     => (string) A CSS ruleset formatted to be placed in an HTML `style` attribute or tag.
+	 *     'classnames' => (string) Classnames separated by a space.
+	 * );
 	 */
-	public function generate( $block_styles, $options = array() ) {
-		$output = '';
-
-		if ( empty( $block_styles ) ) {
-			return $output;
+	public function generate( $block_styles ) {
+		if ( empty( $block_styles ) || ! is_array( $block_styles ) ) {
+			return null;
 		}
 
-		$rules = array();
+		$css_rules     = array();
+		$classnames    = array();
+		$styles_output = array();
 
-		// If a path to a specific block style is defined, only return rules for that style.
-		if ( isset( $options['path'] ) && is_array( $options['path'] ) ) {
-			$style_value = _wp_array_get( $block_styles, $options['path'], null );
-			if ( empty( $style_value ) ) {
-				return $output;
-			}
-			$rules = array_merge( $rules, $this->get_block_style_css_rules( $style_value, $options['path'] ) );
-		} else {
-			// Otherwise build them all.
-			foreach ( self::BLOCK_STYLE_DEFINITIONS_METADATA as $definition_group ) {
-				foreach ( $definition_group as $style_definition ) {
-					$style_value = _wp_array_get( $block_styles, $style_definition['path'], null );
-					if ( empty( $style_value ) ) {
-						continue;
-					}
-					$rules = array_merge( $rules, $this->get_block_style_css_rules( $style_value, $style_definition['path'] ) );
+		// Collect CSS and classnames.
+		foreach ( self::BLOCK_STYLE_DEFINITIONS_METADATA as $definition_group ) {
+			foreach ( $definition_group as $style_definition ) {
+				$style_value = _wp_array_get( $block_styles, $style_definition['path'], null );
+
+				if ( empty( $style_value ) ) {
+					continue;
 				}
+
+				$classnames = array_merge( $classnames, static::get_classnames( $style_value, $style_definition ) );
+				$css_rules  = array_merge( $css_rules, static::get_css( $style_value, $style_definition ) );
 			}
 		}
 
-		if ( ! empty( $rules ) ) {
+		// Build CSS rules output.
+		$css_output = '';
+		if ( ! empty( $css_rules ) ) {
 			// Generate inline style rules.
-			if ( isset( $options['inline'] ) && true === $options['inline'] ) {
-				foreach ( $rules as $rule => $value ) {
-					$filtered_css = esc_html( safecss_filter_attr( "{$rule}:{$value}" ) );
-					if ( ! empty( $filtered_css ) ) {
-						$output .= $filtered_css . ';';
-					}
+			// In the future there might be a flag in the option to output
+			// inline CSS rules (for HTML style attributes) vs selectors + rules for style tags.
+			foreach ( $css_rules as $rule => $value ) {
+				$filtered_css = esc_html( safecss_filter_attr( "{$rule}: {$value}" ) );
+				if ( ! empty( $filtered_css ) ) {
+					$css_output .= $filtered_css . '; ';
 				}
 			}
 		}
 
-		return $output;
+		if ( ! empty( $css_output ) ) {
+			$styles_output['css'] = trim( $css_output );
+		}
+
+		if ( ! empty( $classnames ) ) {
+			$styles_output['classnames'] = implode( ' ', array_unique( $classnames ) );
+		}
+
+		return $styles_output;
 	}
 
 	/**
-	 * Returns a CSS ruleset for box model styles such as margins, padding, and borders.
+	 * Default style value parser that returns a CSS ruleset.
+	 * If the input contains an array, it will be treated like a box model
+	 * for styles such as margins and padding
 	 *
 	 * @param string|array $style_value    A single raw Gutenberg style attributes value for a CSS property.
 	 * @param string       $style_property The CSS property for which we're creating a rule.
 	 *
 	 * @return array The class name for the added style.
 	 */
-	public static function get_css_box_rules( $style_value, $style_property ) {
+	protected static function get_css_rules( $style_value, $style_property ) {
 		$rules = array();
 
 		if ( ! $style_value ) {
 			return $rules;
 		}
 
+		// We assume box model-like properties.
 		if ( is_array( $style_value ) ) {
 			foreach ( $style_value as $key => $value ) {
 				$rules[ "$style_property-$key" ] = $value;
@@ -166,17 +283,28 @@ class WP_Style_Engine {
 		} else {
 			$rules[ $style_property ] = $style_value;
 		}
+
 		return $rules;
 	}
 }
 
 /**
- * This function returns the Style Engine instance.
+ * Global public interface method to WP_Style_Engine->generate.
+ *
+ * Returns an CSS ruleset.
+ * Styles are bundled based on the instructions in BLOCK_STYLE_DEFINITIONS_METADATA.
+ *
+ * @param array $block_styles An array of styles from a block's attributes.
  *
- * @return WP_Style_Engine
+ * @return array|null array(
+ *     'styles'     => (string) A CSS ruleset formatted to be placed in an HTML `style` attribute or tag.
+ *     'classnames' => (string) Classnames separated by a space.
+ * );
  */
-function wp_get_style_engine() {
+function wp_style_engine_generate( $block_styles ) {
 	if ( class_exists( 'WP_Style_Engine' ) ) {
-		return WP_Style_Engine::get_instance();
+		$style_engine = WP_Style_Engine::get_instance();
+		return $style_engine->generate( $block_styles );
 	}
+	return null;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@wordpress/style-engine",
-	"version": "0.5.1",
+	"version": "0.8.0",
 	"description": "WordPress Style engine.",
 	"author": "The WordPress Contributors",
 	"license": "GPL-2.0-or-later",
@@ -34,5 +34,5 @@
 	"publishConfig": {
 		"access": "public"
 	},
-	"gitHead": "446565ecaa40370173c18926535e975ec5652b71"
+	"gitHead": "198fa129cf1af8dc615918987ea6795cd40ab7df"
 }

package/phpunit/class-wp-style-engine-test.php

@@ -13,16 +13,12 @@ require __DIR__ . '/../class-wp-style-engine.php';
  */
 class WP_Style_Engine_Test extends WP_UnitTestCase {
 	/**
-	 * Tests various manifestations of the $block_styles argument.
+	 * Tests generating styles and classnames based on various manifestations of the $block_styles argument.
 	 *
-	 * @dataProvider data_block_styles_fixtures
+	 * @dataProvider data_generate_styles_fixtures
 	 */
-	function test_generate_css( $block_styles, $options, $expected_output ) {
-		$style_engine     = WP_Style_Engine::get_instance();
-		$generated_styles = $style_engine->generate(
-			$block_styles,
-			$options
-		);
+	function test_generate_styles( $block_styles, $expected_output ) {
+		$generated_styles = wp_style_engine_generate( $block_styles );
 		$this->assertSame( $expected_output, $generated_styles );
 	}
 
@@ -31,42 +27,30 @@ class WP_Style_Engine_Test extends WP_UnitTestCase {
 	 *
 	 * @return array
 	 */
-	public function data_block_styles_fixtures() {
+	public function data_generate_styles_fixtures() {
 		return array(
 			'default_return_value'                         => array(
 				'block_styles'    => array(),
-				'options'         => null,
-				'expected_output' => '',
+				'expected_output' => null,
 			),
 
 			'inline_invalid_block_styles_empty'            => array(
-				'block_styles'    => array(),
-				'options'         => array(
-					'path'   => array( 'spacing', 'padding' ),
-					'inline' => true,
-				),
-				'expected_output' => '',
+				'block_styles'    => 'hello world!',
+				'expected_output' => null,
 			),
 
 			'inline_invalid_block_styles_unknown_style'    => array(
 				'block_styles'    => array(
 					'pageBreakAfter' => 'verso',
 				),
-				'options'         => array(
-					'inline' => true,
-				),
-				'expected_output' => '',
+				'expected_output' => array(),
 			),
 
 			'inline_invalid_block_styles_unknown_definition' => array(
 				'block_styles'    => array(
 					'pageBreakAfter' => 'verso',
 				),
-				'options'         => array(
-					'path'   => array( 'pageBreakAfter', 'verso' ),
-					'inline' => true,
-				),
-				'expected_output' => '',
+				'expected_output' => array(),
 			),
 
 			'inline_invalid_block_styles_unknown_property' => array(
@@ -75,39 +59,25 @@ class WP_Style_Engine_Test extends WP_UnitTestCase {
 						'gap' => '1000vw',
 					),
 				),
-				'options'         => array(
-					'path'   => array( 'spacing', 'padding' ),
-					'inline' => true,
-				),
-				'expected_output' => '',
+				'expected_output' => array(),
 			),
 
-			'inline_invalid_multiple_style_unknown_property' => array(
+			'valid_inline_css_and_classnames'              => array(
 				'block_styles'    => array(
-					'spacing' => array(
-						'gavin' => '1000vw',
+					'color'   => array(
+						'text' => 'var:preset|color|texas-flood',
 					),
-				),
-				'options'         => array(
-					'inline' => true,
-				),
-				'expected_output' => '',
-			),
-
-			'inline_valid_single_style_string'             => array(
-				'block_styles'    => array(
 					'spacing' => array(
 						'margin' => '111px',
 					),
 				),
-				'options'         => array(
-					'path'   => array( 'spacing', 'margin' ),
-					'inline' => true,
+				'expected_output' => array(
+					'css'        => 'margin: 111px;',
+					'classnames' => 'has-text-color has-texas-flood-color',
 				),
-				'expected_output' => 'margin:111px;',
 			),
 
-			'inline_valid_single_style'                    => array(
+			'inline_valid_box_model_style'                 => array(
 				'block_styles'    => array(
 					'spacing' => array(
 						'padding' => array(
@@ -124,34 +94,83 @@ class WP_Style_Engine_Test extends WP_UnitTestCase {
 						),
 					),
 				),
-				'options'         => array(
-					'path'   => array( 'spacing', 'padding' ),
-					'inline' => true,
+				'expected_output' => array(
+					'css' => 'padding-top: 42px; padding-left: 2%; padding-bottom: 44px; padding-right: 5rem; margin-top: 12rem; margin-left: 2vh; margin-bottom: 2px; margin-right: 10em;',
 				),
-				'expected_output' => 'padding-top:42px;padding-left:2%;padding-bottom:44px;padding-right:5rem;',
 			),
 
-			'inline_valid_multiple_style'                  => array(
+			'inline_valid_typography_style'                => array(
+				'block_styles'    => array(
+					'typography' => array(
+						'fontSize'       => 'clamp(2em, 2vw, 4em)',
+						'fontFamily'     => 'Roboto,Oxygen-Sans,Ubuntu,sans-serif',
+						'fontStyle'      => 'italic',
+						'fontWeight'     => '800',
+						'lineHeight'     => '1.3',
+						'textDecoration' => 'underline',
+						'textTransform'  => 'uppercase',
+						'letterSpacing'  => '2',
+					),
+				),
+				'expected_output' => array(
+					'css' => 'font-family: Roboto,Oxygen-Sans,Ubuntu,sans-serif; font-style: italic; font-weight: 800; line-height: 1.3; text-decoration: underline; text-transform: uppercase; letter-spacing: 2;',
+				),
+			),
+			'valid_classnames_deduped'                     => array(
+				'block_styles'    => array(
+					'color'      => array(
+						'text'       => 'var:preset|color|copper-socks',
+						'background' => 'var:preset|color|splendid-carrot',
+						'gradient'   => 'var:preset|gradient|like-wow-dude',
+					),
+					'typography' => array(
+						'fontSize'   => 'var:preset|font-size|fantastic',
+						'fontFamily' => 'var:preset|font-family|totally-awesome',
+					),
+				),
+				'expected_output' => array(
+					'classnames' => 'has-text-color has-copper-socks-color has-background has-splendid-carrot-background-color has-like-wow-dude-gradient-background has-fantastic-font-size has-totally-awesome-font-family',
+				),
+			),
+			'valid_classnames_with_null_style_values'      => array(
 				'block_styles'    => array(
+					'color' => array(
+						'text'       => '#fff',
+						'background' => null,
+					),
+				),
+				'expected_output' => array(
+					'css'        => 'color: #fff;',
+					'classnames' => 'has-text-color',
+				),
+			),
+			'invalid_classnames_preset_value'              => array(
+				'block_styles'    => array(
+					'color'   => array(
+						'text'       => 'var:cheese|color|fantastic',
+						'background' => 'var:preset|fromage|fantastic',
+					),
 					'spacing' => array(
-						'padding' => array(
-							'top'    => '42px',
-							'left'   => '2%',
-							'bottom' => '44px',
-							'right'  => '5rem',
+						'margin'  => 'var:cheese|spacing|margin',
+						'padding' => 'var:preset|spacing|padding',
+					),
+				),
+				'expected_output' => array(
+					'classnames' => 'has-text-color has-background',
+				),
+			),
+			'invalid_classnames_options'                   => array(
+				'block_styles'    => array(
+					'typography' => array(
+						'fontSize'   => array(
+							'tomodachi' => 'friends',
 						),
-						'margin'  => array(
-							'top'    => '12rem',
-							'left'   => '2vh',
-							'bottom' => '2px',
-							'right'  => '10em',
+						'fontFamily' => array(
+							'oishii' => 'tasty',
 						),
 					),
 				),
-				'options'         => array(
-					'inline' => true,
-				),
-				'expected_output' => 'padding-top:42px;padding-left:2%;padding-bottom:44px;padding-right:5rem;margin-top:12rem;margin-left:2vh;margin-bottom:2px;margin-right:10em;',
+				'expected_output' => array(),
 			),
 		);
 	}

package/src/index.ts

@@ -24,6 +24,16 @@ import { styleDefinitions } from './styles';
  */
 export function generate( style: Style, options: StyleOptions ): string {
 	const rules = getCSSRules( style, options );
+
+	// If no selector is provided, treat generated rules as inline styles to be returned as a single string.
+	if ( ! options?.selector ) {
+		const inlineRules: string[] = [];
+		rules.forEach( ( rule ) => {
+			inlineRules.push( `${ kebabCase( rule.key ) }: ${ rule.value };` );
+		} );
+		return inlineRules.join( ' ' );
+	}
+
 	const groupedRules = groupBy( rules, 'selector' );
 	const selectorRules = Object.keys( groupedRules ).reduce(
 		( acc: string[], subSelector: string ) => {
@@ -57,7 +67,9 @@ export function getCSSRules(
 ): GeneratedCSSRule[] {
 	const rules: GeneratedCSSRule[] = [];
 	styleDefinitions.forEach( ( definition: StyleDefinition ) => {
-		rules.push( ...definition.generate( style, options ) );
+		if ( typeof definition.generate === 'function' ) {
+			rules.push( ...definition.generate( style, options ) );
+		}
 	} );
 
 	return rules;

package/src/styles/color/background.ts

@@ -0,0 +1,19 @@
+/**
+ * Internal dependencies
+ */
+import type { Style, StyleOptions } from '../../types';
+import { generateRule } from '../utils';
+
+const background = {
+	name: 'background',
+	generate: ( style: Style, options: StyleOptions ) => {
+		return generateRule(
+			style,
+			options,
+			[ 'color', 'background' ],
+			'backgroundColor'
+		);
+	},
+};
+
+export default background;

package/src/styles/color/gradient.ts

@@ -0,0 +1,19 @@
+/**
+ * Internal dependencies
+ */
+import type { Style, StyleOptions } from '../../types';
+import { generateRule } from '../utils';
+
+const gradient = {
+	name: 'gradient',
+	generate: ( style: Style, options: StyleOptions ) => {
+		return generateRule(
+			style,
+			options,
+			[ 'color', 'gradient' ],
+			'background'
+		);
+	},
+};
+
+export default gradient;

package/src/styles/color/index.ts

@@ -0,0 +1,8 @@
+/**
+ * Internal dependencies
+ */
+import background from './background';
+import gradient from './gradient';
+import text from './text';
+
+export default [ text, gradient, background ];

package/src/styles/color/text.ts

@@ -0,0 +1,14 @@
+/**
+ * Internal dependencies
+ */
+import type { Style, StyleOptions } from '../../types';
+import { generateRule } from '../utils';
+
+const text = {
+	name: 'text',
+	generate: ( style: Style, options: StyleOptions ) => {
+		return generateRule( style, options, [ 'color', 'text' ], 'color' );
+	},
+};
+
+export default text;