@wordpress/style-engine 0.8.0 → 0.11.0

package/class-wp-style-engine.php

@@ -34,87 +34,183 @@ 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.
+	 *  - classnames    => (array) 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 (string)
+	 *                    to match the incoming value, e.g., "color" to match var:preset|color|somePresetSlug.
+	 *  - css_vars      => (array) an array of key value pairs used to generate CSS var values. The key is a CSS var pattern, whose `$slug` fragment will be replaced with a preset slug.
+	 *                    The value should be a valid CSS property (string) to match the incoming value, e.g., "color" to match var:preset|color|somePresetSlug.
+	 *  - 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", ... )`.
 	 */
 	const BLOCK_STYLE_DEFINITIONS_METADATA = array(
 		'color'      => array(
 			'text'       => array(
-				'property_key' => 'color',
-				'path'         => array( 'color', 'text' ),
-				'classnames'   => array(
-					'has-text-color' => true,
-					'has-%s-color'   => 'color',
+				'property_keys' => array(
+					'default' => 'color',
+				),
+				'path'          => array( 'color', 'text' ),
+				'css_vars'      => array(
+					'--wp--preset--color--$slug' => 'color',
+				),
+				'classnames'    => array(
+					'has-text-color'  => true,
+					'has-$slug-color' => 'color',
 				),
 			),
 			'background' => array(
-				'property_key' => 'background-color',
-				'path'         => array( 'color', 'background' ),
-				'classnames'   => array(
-					'has-background'          => true,
-					'has-%s-background-color' => 'color',
+				'property_keys' => array(
+					'default' => 'background-color',
+				),
+				'path'          => array( 'color', 'background' ),
+				'classnames'    => array(
+					'has-background'             => true,
+					'has-$slug-background-color' => 'color',
 				),
 			),
 			'gradient'   => array(
-				'property_key' => 'background',
-				'path'         => array( 'color', 'gradient' ),
-				'classnames'   => array(
-					'has-background'             => true,
-					'has-%s-gradient-background' => 'gradient',
+				'property_keys' => array(
+					'default' => 'background',
+				),
+				'path'          => array( 'color', 'gradient' ),
+				'classnames'    => array(
+					'has-background'                => true,
+					'has-$slug-gradient-background' => 'gradient',
+				),
+			),
+		),
+		'border'     => array(
+			'color'  => array(
+				'property_keys' => array(
+					'default'    => 'border-color',
+					'individual' => 'border-%s-color',
+				),
+				'path'          => array( 'border', 'color' ),
+				'classnames'    => array(
+					'has-border-color'       => true,
+					'has-$slug-border-color' => 'color',
+				),
+			),
+			'radius' => array(
+				'property_keys' => array(
+					'default'    => 'border-radius',
+					'individual' => 'border-%s-radius',
+				),
+				'path'          => array( 'border', 'radius' ),
+			),
+			'style'  => array(
+				'property_keys' => array(
+					'default'    => 'border-style',
+					'individual' => 'border-%s-style',
+				),
+				'path'          => array( 'border', 'style' ),
+			),
+			'width'  => array(
+				'property_keys' => array(
+					'default'    => 'border-width',
+					'individual' => 'border-%s-width',
+				),
+				'path'          => array( 'border', 'width' ),
+			),
+			'top'    => array(
+				'value_func' => 'static::get_individual_property_css_declarations',
+				'path'       => array( 'border', 'top' ),
+				'css_vars'   => array(
+					'color' => '--wp--preset--color--$slug',
+				),
+			),
+			'right'  => array(
+				'value_func' => 'static::get_individual_property_css_declarations',
+				'path'       => array( 'border', 'right' ),
+				'css_vars'   => array(
+					'color' => '--wp--preset--color--$slug',
+				),
+			),
+			'bottom' => array(
+				'value_func' => 'static::get_individual_property_css_declarations',
+				'path'       => array( 'border', 'bottom' ),
+				'css_vars'   => array(
+					'color' => '--wp--preset--color--$slug',
+				),
+			),
+			'left'   => array(
+				'value_func' => 'static::get_individual_property_css_declarations',
+				'path'       => array( 'border', 'left' ),
+				'css_vars'   => array(
+					'color' => '--wp--preset--color--$slug',
 				),
 			),
 		),
 		'spacing'    => array(
 			'padding' => array(
-				'property_key' => 'padding',
-				'path'         => array( 'spacing', 'padding' ),
+				'property_keys' => array(
+					'default'    => 'padding',
+					'individual' => 'padding-%s',
+				),
+				'path'          => array( 'spacing', 'padding' ),
 			),
 			'margin'  => array(
-				'property_key' => 'margin',
-				'path'         => array( 'spacing', 'margin' ),
+				'property_keys' => array(
+					'default'    => 'margin',
+					'individual' => 'margin-%s',
+				),
+				'path'          => array( 'spacing', 'margin' ),
 			),
 		),
 		'typography' => array(
 			'fontSize'       => array(
-				'property_key' => 'font-size',
-				'path'         => array( 'typography', 'fontSize' ),
-				'classnames'   => array(
-					'has-%s-font-size' => 'font-size',
+				'property_keys' => array(
+					'default' => 'font-size',
+				),
+				'path'          => array( 'typography', 'fontSize' ),
+				'classnames'    => array(
+					'has-$slug-font-size' => 'font-size',
 				),
 			),
 			'fontFamily'     => array(
-				'property_key' => 'font-family',
-				'path'         => array( 'typography', 'fontFamily' ),
-				'classnames'   => array(
-					'has-%s-font-family' => 'font-family',
+				'property_keys' => array(
+					'default' => 'font-family',
+				),
+				'path'          => array( 'typography', 'fontFamily' ),
+				'classnames'    => array(
+					'has-$slug-font-family' => 'font-family',
 				),
 			),
 			'fontStyle'      => array(
-				'property_key' => 'font-style',
-				'path'         => array( 'typography', 'fontStyle' ),
+				'property_keys' => array(
+					'default' => 'font-style',
+				),
+				'path'          => array( 'typography', 'fontStyle' ),
 			),
 			'fontWeight'     => array(
-				'property_key' => 'font-weight',
-				'path'         => array( 'typography', 'fontWeight' ),
+				'property_keys' => array(
+					'default' => 'font-weight',
+				),
+				'path'          => array( 'typography', 'fontWeight' ),
 			),
 			'lineHeight'     => array(
-				'property_key' => 'line-height',
-				'path'         => array( 'typography', 'lineHeight' ),
+				'property_keys' => array(
+					'default' => 'line-height',
+				),
+				'path'          => array( 'typography', 'lineHeight' ),
 			),
 			'textDecoration' => array(
-				'property_key' => 'text-decoration',
-				'path'         => array( 'typography', 'textDecoration' ),
+				'property_keys' => array(
+					'default' => 'text-decoration',
+				),
+				'path'          => array( 'typography', 'textDecoration' ),
 			),
 			'textTransform'  => array(
-				'property_key' => 'text-transform',
-				'path'         => array( 'typography', 'textTransform' ),
+				'property_keys' => array(
+					'default' => 'text-transform',
+				),
+				'path'          => array( 'typography', 'textTransform' ),
 			),
 			'letterSpacing'  => array(
-				'property_key' => 'letter-spacing',
-				'path'         => array( 'typography', 'letterSpacing' ),
+				'property_keys' => array(
+					'default' => 'letter-spacing',
+				),
+				'path'          => array( 'typography', 'letterSpacing' ),
 			),
 		),
 	);
@@ -137,8 +233,8 @@ class WP_Style_Engine {
 	/**
 	 * 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|null The slug, or null if not found.
 	 */
@@ -150,6 +246,25 @@ class WP_Style_Engine {
 		return null;
 	}
 
+	/**
+	 * Checks whether an incoming block style value is valid.
+	 *
+	 * @param string? $style_value  A single css preset value.
+	 *
+	 * @return boolean
+	 */
+	protected static function is_valid_style_value( $style_value ) {
+		if ( '0' === $style_value ) {
+			return true;
+		}
+
+		if ( empty( $style_value ) ) {
+			return false;
+		}
+
+		return true;
+	}
+
 	/**
 	 * Returns classnames, and generates classname(s) from a CSS preset property pattern, e.g., 'var:preset|color|heavenly-blue'.
 	 *
@@ -160,6 +275,11 @@ class WP_Style_Engine {
 	 */
 	protected static function get_classnames( $style_value, $style_definition ) {
 		$classnames = array();
+
+		if ( empty( $style_value ) ) {
+			return $classnames;
+		}
+
 		if ( ! empty( $style_definition['classnames'] ) ) {
 			foreach ( $style_definition['classnames'] as $classname => $property_key ) {
 				if ( true === $property_key ) {
@@ -173,7 +293,7 @@ class WP_Style_Engine {
 					// 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 );
+					$classnames[] = strtr( $classname, array( '$slug' => $slug ) );
 				}
 			}
 		}
@@ -182,75 +302,130 @@ class WP_Style_Engine {
 	}
 
 	/**
-	 * Returns CSS rules based on valid block style values.
+	 * 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 boolean       $should_return_css_vars Whether to try to build and return CSS var values.
 	 *
-	 * @return array        An array of CSS rules.
+	 * @return array        An array of CSS definitions, e.g., array( "$property" => "$value" ).
 	 */
-	protected static function get_css( $style_value, $style_definition ) {
-		// Low-specificity check to see if the value is a CSS preset.
+	protected static function get_css_declarations( $style_value, $style_definition, $should_return_css_vars ) {
+		if (
+			isset( $style_definition['value_func'] ) &&
+			is_callable( $style_definition['value_func'] )
+		) {
+			return call_user_func( $style_definition['value_func'], $style_value, $style_definition );
+		}
+
+		$css_declarations    = array();
+		$style_property_keys = $style_definition['property_keys'];
+
+		// 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.
 		if ( is_string( $style_value ) && strpos( $style_value, 'var:' ) !== false ) {
-			return array();
+			if ( $should_return_css_vars && ! empty( $style_definition['css_vars'] ) ) {
+				foreach ( $style_definition['css_vars'] as $css_var_pattern => $property_key ) {
+					$slug = static::get_slug_from_preset_value( $style_value, $property_key );
+					if ( $slug ) {
+						$css_var = strtr(
+							$css_var_pattern,
+							array( '$slug' => $slug )
+						);
+						$css_declarations[ $style_property_keys['default'] ] = "var($css_var)";
+					}
+				}
+			}
+			return $css_declarations;
+		}
+
+		// 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 ) ) {
+			foreach ( $style_value as $key => $value ) {
+				$individual_property                      = sprintf( $style_property_keys['individual'], _wp_to_kebab_case( $key ) );
+				$css_declarations[ $individual_property ] = $value;
+			}
+		} else {
+			$css_declarations[ $style_property_keys['default'] ] = $style_value;
 		}
 
-		// 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'] );
+		return $css_declarations;
 	}
 
 	/**
-	 * Returns an CSS ruleset.
-	 * Styles are bundled based on the instructions in BLOCK_STYLE_DEFINITIONS_METADATA.
+	 * Returns classname and CSS from a block styles object.
+	 * Return values are parsed 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(
+	 *     'selector' => (string) When a selector is passed, `generate()` will return a full CSS rule `$selector { ...rules }`, otherwise a concatenated string of properties and values.
+	 *     'css_vars' => (boolean) Whether to covert CSS values to var() values. If `true` the style engine will try to parse var:? values and output var( --wp--preset--* ) rules. Default is `false`.
+	 * );.
 	 *
 	 * @return array|null array(
-	 *     'styles'     => (string) A CSS ruleset formatted to be placed in an HTML `style` attribute or tag.
+	 *     'css'        => (string) A CSS ruleset formatted to be placed in an HTML `style` attribute or tag.  Default is a string of inline styles.
 	 *     'classnames' => (string) Classnames separated by a space.
 	 * );
 	 */
-	public function generate( $block_styles ) {
+	public function generate( $block_styles, $options ) {
 		if ( empty( $block_styles ) || ! is_array( $block_styles ) ) {
 			return null;
 		}
 
-		$css_rules     = array();
-		$classnames    = array();
-		$styles_output = array();
+		$css_declarations       = array();
+		$classnames             = array();
+		$should_return_css_vars = isset( $options['css_vars'] ) && true === $options['css_vars'];
 
 		// Collect CSS and classnames.
-		foreach ( self::BLOCK_STYLE_DEFINITIONS_METADATA as $definition_group ) {
-			foreach ( $definition_group as $style_definition ) {
+		foreach ( self::BLOCK_STYLE_DEFINITIONS_METADATA as $definition_group_key => $definition_group_style ) {
+			if ( empty( $block_styles[ $definition_group_key ] ) ) {
+				continue;
+			}
+			foreach ( $definition_group_style as $style_definition ) {
 				$style_value = _wp_array_get( $block_styles, $style_definition['path'], null );
 
-				if ( empty( $style_value ) ) {
+				if ( ! static::is_valid_style_value( $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 ) );
+				$classnames       = array_merge( $classnames, static::get_classnames( $style_value, $style_definition ) );
+				$css_declarations = array_merge( $css_declarations, static::get_css_declarations( $style_value, $style_definition, $should_return_css_vars ) );
 			}
 		}
 
 		// Build CSS rules output.
-		$css_output = '';
-		if ( ! empty( $css_rules ) ) {
-			// Generate inline style rules.
-			// 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 . '; ';
+		$css_selector              = isset( $options['selector'] ) ? $options['selector'] : null;
+		$filtered_css_declarations = array();
+
+		if ( ! empty( $css_declarations ) ) {
+			// Generate inline style declarations.
+			foreach ( $css_declarations as $css_property => $css_value ) {
+				$filtered_css_declaration = esc_html( safecss_filter_attr( "{$css_property}: {$css_value}" ) );
+				if ( ! empty( $filtered_css_declaration ) ) {
+					$filtered_css_declarations[] = $filtered_css_declaration . ';';
 				}
 			}
 		}
 
-		if ( ! empty( $css_output ) ) {
-			$styles_output['css'] = trim( $css_output );
+		// The return object.
+		$styles_output = array();
+
+		// Return css, if any.
+		if ( ! empty( $filtered_css_declarations ) ) {
+			// Return an entire rule if there is a selector.
+			if ( $css_selector ) {
+				$css_rule             = "$css_selector { ";
+				$css_rule            .= implode( ' ', $filtered_css_declarations );
+				$css_rule            .= ' }';
+				$styles_output['css'] = $css_rule;
+			} else {
+				$styles_output['css'] = implode( ' ', $filtered_css_declarations );
+			}
 		}
 
+		// Return classnames, if any.
 		if ( ! empty( $classnames ) ) {
 			$styles_output['classnames'] = implode( ' ', array_unique( $classnames ) );
 		}
@@ -258,33 +433,56 @@ class WP_Style_Engine {
 		return $styles_output;
 	}
 
+
 	/**
-	 * 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
+	 * Style value parser that returns a CSS definition array comprising style properties
+	 * that have keys representing individual style properties, otherwise known as longhand CSS properties.
+	 * e.g., "$style_property-$individual_feature: $value;", which could represent the following:
+	 * "border-{top|right|bottom|left}-{color|width|style}: {value};" or,
+	 * "border-image-{outset|source|width|repeat|slice}: {value};"
 	 *
-	 * @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.
+	 * @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.
 	 *
-	 * @return array The class name for the added style.
+	 * @return array An array of CSS definitions, e.g., array( "$property" => "$value" ).
 	 */
-	protected static function get_css_rules( $style_value, $style_property ) {
-		$rules = array();
+	protected static function get_individual_property_css_declarations( $style_value, $individual_property_definition ) {
+		$css_declarations = array();
 
-		if ( ! $style_value ) {
-			return $rules;
+		if ( ! is_array( $style_value ) || empty( $style_value ) || empty( $individual_property_definition['path'] ) ) {
+			return $css_declarations;
 		}
 
-		// We assume box model-like properties.
-		if ( is_array( $style_value ) ) {
-			foreach ( $style_value as $key => $value ) {
-				$rules[ "$style_property-$key" ] = $value;
+		// 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];
+
+		foreach ( $style_value as $css_property => $value ) {
+			if ( empty( $value ) ) {
+				continue;
 			}
-		} else {
-			$rules[ $style_property ] = $style_value;
-		}
 
-		return $rules;
+			// Build a path to the individual rules in definitions.
+			$style_definition_path = array( $definition_group_key, $css_property );
+			$style_definition      = _wp_array_get( self::BLOCK_STYLE_DEFINITIONS_METADATA, $style_definition_path, null );
+
+			if ( $style_definition && isset( $style_definition['property_keys']['individual'] ) ) {
+				// Set a CSS var if there is a valid preset value.
+				$slug = isset( $individual_property_definition['css_vars'][ $css_property ] ) ? static::get_slug_from_preset_value( $value, $css_property ) : null;
+				if ( $slug ) {
+					$css_var = strtr(
+						$individual_property_definition['css_vars'][ $css_property ],
+						array( '$slug' => $slug )
+					);
+					$value   = "var($css_var)";
+				}
+				$individual_css_property                      = sprintf( $style_definition['property_keys']['individual'], $individual_property_key );
+				$css_declarations[ $individual_css_property ] = $value;
+			}
+		}
+		return $css_declarations;
 	}
 }
 
@@ -294,17 +492,25 @@ class WP_Style_Engine {
  * Returns an CSS ruleset.
  * Styles are bundled based on the instructions in BLOCK_STYLE_DEFINITIONS_METADATA.
  *
+ * Example usage:
+ *
+ * $styles = wp_style_engine_generate( array( 'color' => array( 'text' => '#cccccc' ) ) );
+ * // Returns `'color: #cccccc'`.
+ *
+ * @access public
+ *
  * @param array $block_styles An array of styles from a block's attributes.
+ * @param array $options An array of options to determine the output.
  *
  * @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_style_engine_generate( $block_styles ) {
+function wp_style_engine_generate( $block_styles, $options = array() ) {
 	if ( class_exists( 'WP_Style_Engine' ) ) {
 		$style_engine = WP_Style_Engine::get_instance();
-		return $style_engine->generate( $block_styles );
+		return $style_engine->generate( $block_styles, $options );
 	}
 	return null;
 }

package/package.json

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