@wordpress/style-engine 0.15.1-next.957ca95e4c.0 → 1.0.0

package/docs/using-the-style-engine-with-block-supports.md

@@ -0,0 +1,151 @@
+# Using the Style Engine to generate block supports styles
+
+[Block supports](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-supports/) is the API that allows a block to declare support for certain features.
+
+Where a block declares support for a specific style group or property, e.g., "spacing" or "spacing.padding", the block's attributes are extended to include a **style object**.
+
+For example:
+
+```json
+{
+    "attributes": {
+        "style": {
+            "spacing": {
+                "margin": {
+                    "top": "10px"
+                },
+                "padding": "1em"
+            },
+            "typography": {
+                "fontSize": "2.2rem"
+            }
+        }
+    }
+}
+```
+
+Using this object, the Style Engine can generate the classes and CSS required to style the block element.
+
+The global function `wp_style_engine_get_styles` accepts a style object as its first argument, and will output compiled CSS and an array of CSS declaration property/value pairs.
+
+```php
+$block_styles =  array(
+     'spacing' => array( 'padding' => '10px', 'margin' => array( 'top' => '1em') ),
+     'typography' => array( 'fontSize' => '2.2rem' ),
+);
+$styles = wp_style_engine_get_styles(
+    $block_styles
+);
+print_r( $styles );
+
+/*
+array(
+    'css'          => 'padding:10px;margin-top:1em;font-size:2.2rem',
+    'declarations' => array( 'padding' => '10px', 'margin-top' => '1em', 'font-size' => '2.2rem' )
+)
+*/
+```
+
+## Checking for block support and skip serialization
+
+Before passing the block style object to the Style Engine, it's important to take into account:
+
+1. whether the theme has elected to support a particular block style, and
+2. whether a block has elected to "skip serialization" of that particular block style, that is, opt-out of automatic application of styles to the block's element (usually in order to do it via the block's internals). See the [block API documentation](https://developer.wordpress.org/block-editor/explanations/architecture/styles/#block-supports-api) for further information.
+
+If a block either:
+
+- has no support for a specific style, or 
+- skips serialization of that style
+
+it's likely that you'll want to remove those style values from the style object.
+
+For example:
+
+```php
+// Check if a block has support using block_has_support (https://developer.wordpress.org/reference/functions/block_has_support/)
+$has_padding_support = block_has_support( $block_type, array( 'spacing', 'padding' ), false ); // Returns true.
+$has_margin_support  = block_has_support( $block_type, array( 'spacing', 'margin' ), false ); // Returns false.
+
+// Check skipping of serialization.
+$should_skip_padding = wp_should_skip_block_supports_serialization( $block_type, 'spacing', 'padding' ); // Returns true.
+$should_skip_margin  = wp_should_skip_block_supports_serialization( $block_type, 'spacing', 'margin' ); // Returns false.
+
+// Now build the styles object.
+$spacing_block_styles            = array();
+$spacing_block_styles['padding'] = $has_padding_support && ! $skip_padding ? _wp_array_get( $block_attributes['style'], array( 'spacing', 'padding' ), null ) : null;
+$spacing_block_styles['margin']  = $has_margin_support && ! $skip_margin ? _wp_array_get( $block_attributes['style'], array( 'spacing', 'margin' ), null ) : null;
+
+// Now get the styles.
+$styles = wp_style_engine_get_styles( array( 'spacing' => $spacing_block_styles ) );
+
+print_r( $styles );
+
+/*
+// Nothing, because there's no support for margin and the block skip's serialization for padding.
+array()
+*/
+```
+
+## Generating classnames and CSS custom selectors from presets
+
+Many of theme.json's presets will generate both CSS custom properties and CSS rules (consisting of a selector and the CSS declarations) on the frontend.
+
+Styling a block using these presets normally involves adding the selector to the "className" attribute of the block.
+
+For styles that can have preset values, such as text color and font family, the Style Engine knows how to construct the classnames using the preset slug.
+
+To discern CSS values from preset values however, the Style Engine expects a special format.
+
+Preset values must follow the pattern `var:preset|<PRESET_TYPE>|<PRESET_SLUG>`.
+
+When the Style Engine encounters these values, it will parse them and create a CSS value of `var(--wp--preset--font-size--small)` and/or generate a classname if required.
+
+Example:
+
+```php
+// Let's say the block attributes styles contain a fontSize preset slug of "small".
+$preset_font_size        = "var:preset|font-size|{$block_attributes['fontSize']}";
+// Now let's say the block attributes styles contain a backgroundColor preset slug of "blue".
+$preset_background_color = "var:preset|color|{$block_attributes['backgroundColor']}";
+
+$block_styles =  array(
+     'typography' => array( 'fontSize' => $preset_font_size ),
+     'color'      => array( 'background' => $preset_background_color )
+);
+
+$styles = wp_style_engine_get_styles(
+    $block_styles
+);
+print_r( $styles );
+
+/*
+array(
+    'css'        => 'background-color:var(--wp--preset--color--blue);font-size:var(--wp--preset--font-size--small);',
+    'classnames' => 'has-background-color has-blue-background-color has-small-font-size',
+)
+*/
+```
+
+If you don't want the Style Engine to output the CSS custom vars as well, which you might not if you're applying both the CSS and classnames to the block element, you can pass `'convert_vars_to_classnames' => true` in the options array.
+
+```php
+$options = array(
+    // Whether to skip converting CSS var:? values to var( --wp--preset--* ) values. Default is `false`.
+    'convert_vars_to_classnames' => 'true',
+);
+$styles = wp_style_engine_get_styles(
+    $block_styles,
+    $options
+);
+print_r( $styles );
+
+/*
+array(
+    'css'        => 'letter-spacing:12px;', // non-preset-based CSS will still be compiled.
+    'classnames' => 'has-background-color has-blue-background-color has-small-font-size',
+)
+*/
+```
+
+Read more about [global styles](https://developer.wordpress.org/block-editor/explanations/architecture/styles/#global-styles) and [preset CSS custom properties](https://developer.wordpress.org/block-editor/how-to-guides/themes/theme-json/#css-custom-properties-presets-custom) and [theme supports](https://developer.wordpress.org/block-editor/how-to-guides/themes/theme-support/).

package/package.json

@@ -1,13 +1,14 @@
 {
 	"name": "@wordpress/style-engine",
-	"version": "0.15.1-next.957ca95e4c.0",
-	"description": "WordPress Style engine.",
+	"version": "1.0.0",
+	"description": "A suite of parsers and compilers for WordPress styles.",
 	"author": "The WordPress Contributors",
 	"license": "GPL-2.0-or-later",
 	"keywords": [
 		"wordpress",
 		"gutenberg",
 		"styles",
+		"css",
 		"global styles"
 	],
 	"homepage": "https://github.com/WordPress/gutenberg/tree/HEAD/packages/style-engine/README.md",
@@ -34,5 +35,5 @@
 	"publishConfig": {
 		"access": "public"
 	},
-	"gitHead": "272a74bbbaab10ee24424eafe9578e705fbfbbb4"
+	"gitHead": "56ef3f5a754e44155ee79e827c7a1d0efc1ee5aa"
 }

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

@@ -6,16 +6,26 @@
  * @subpackage style-engine
  */
 
-require __DIR__ . '/../class-wp-style-engine-css-declarations.php';
+// Check for the existence of Style Engine classes and methods.
+// Once the Style Engine has been migrated to Core we can remove the if statements and require imports.
+// Testing new features from the Gutenberg package may require
+// testing against `gutenberg_` and `_Gutenberg` functions and methods in the future.
+if ( ! class_exists( 'WP_Style_Engine_CSS_Declarations' ) ) {
+	require __DIR__ . '/../class-wp-style-engine-css-declarations.php';
+}
 
 /**
- * Tests for registering, storing and generating CSS declarations.
+ * Tests registering, storing and generating CSS declarations.
+ *
+ * @coversDefaultClass WP_Style_Engine_CSS_Declarations
  */
 class WP_Style_Engine_CSS_Declarations_Test extends WP_UnitTestCase {
 	/**
-	 * Should set declarations on instantiation.
+	 * Tests setting declarations on instantiation.
+	 *
+	 * @covers ::__construct
 	 */
-	public function test_instantiate_with_declarations() {
+	public function test_should_instantiate_with_declarations() {
 		$input_declarations = array(
 			'margin-top' => '10px',
 			'font-size'  => '2rem',
@@ -25,22 +35,29 @@ class WP_Style_Engine_CSS_Declarations_Test extends WP_UnitTestCase {
 	}
 
 	/**
-	 * Should add declarations.
+	 * Tests that declarations are added.
+	 *
+	 * @covers ::add_declarations
+	 * @covers ::add_declaration
 	 */
-	public function test_add_declarations() {
+	public function test_should_add_declarations() {
 		$input_declarations = array(
 			'padding' => '20px',
 			'color'   => 'var(--wp--preset--elbow-patches)',
 		);
 		$css_declarations   = new WP_Style_Engine_CSS_Declarations();
 		$css_declarations->add_declarations( $input_declarations );
+
 		$this->assertSame( $input_declarations, $css_declarations->get_declarations() );
 	}
 
 	/**
-	 * Should add declarations.
+	 * Tests that new declarations are added to existing declarations.
+	 *
+	 * @covers ::add_declarations
+	 * @covers ::add_declaration
 	 */
-	public function test_add_a_single_declaration() {
+	public function test_should_add_new_declarations_to_existing() {
 		$input_declarations = array(
 			'border-width'     => '1%',
 			'background-color' => 'var(--wp--preset--english-mustard)',
@@ -50,13 +67,17 @@ class WP_Style_Engine_CSS_Declarations_Test extends WP_UnitTestCase {
 			'letter-spacing' => '1.5px',
 		);
 		$css_declarations->add_declarations( $extra_declaration );
+
 		$this->assertSame( array_merge( $input_declarations, $extra_declaration ), $css_declarations->get_declarations() );
 	}
 
 	/**
-	 * Should sanitize properties before storing.
+	 * Tests that properties are sanitized before storing.
+	 *
+	 * @covers ::filter_declaration
+	 * @covers ::sanitize_property
 	 */
-	public function test_sanitize_properties() {
+	public function test_should_sanitize_properties() {
 		$input_declarations = array(
 			'^--wp--style--sleepy-potato$' => '40px',
 			'<background-//color>'         => 'var(--wp--preset--english-mustard)',
@@ -73,123 +94,141 @@ class WP_Style_Engine_CSS_Declarations_Test extends WP_UnitTestCase {
 	}
 
 	/**
-	 * Should compile css declarations into a css declarations block string.
+	 * Tests that values with HTML tags are escaped, and CSS properties are run through safecss_filter_attr().
+	 *
+	 * @covers ::get_declarations_string
+	 * @covers ::filter_declaration
 	 */
-	public function test_generate_css_declarations_string() {
-		$input_declarations = array(
-			'color'                  => 'red',
-			'border-top-left-radius' => '99px',
-			'text-decoration'        => 'underline',
+	public function test_should_strip_html_tags_and_remove_unsafe_css_properties() {
+		$input_declarations         = array(
+			'font-size'    => '<red/>',
+			'padding'      => '</style>',
+			'potato'       => 'uppercase',
+			'cheese'       => '10px',
+			'margin-right' => '10em',
 		);
-		$css_declarations   = new WP_Style_Engine_CSS_Declarations( $input_declarations );
+		$css_declarations           = new WP_Style_Engine_CSS_Declarations( $input_declarations );
+		$safe_style_css_mock_action = new MockAction();
 
-		$this->assertSame(
-			'color:red;border-top-left-radius:99px;text-decoration:underline;',
-			$css_declarations->get_declarations_string()
-		);
-	}
+		// filter_declaration() is called in get_declarations_string().
+		add_filter( 'safe_style_css', array( $safe_style_css_mock_action, 'filter' ) );
+		$css_declarations_string = $css_declarations->get_declarations_string();
 
-	/**
-	 * Should compile css declarations into a prettified css declarations block string.
-	 */
-	public function test_generate_prettified_css_declarations_string() {
-		$input_declarations = array(
-			'color'                  => 'red',
-			'border-top-left-radius' => '99px',
-			'text-decoration'        => 'underline',
+		$this->assertSame(
+			3, // Values with HTML tags are removed first by wp_strip_all_tags().
+			$safe_style_css_mock_action->get_call_count(),
+			'"safe_style_css" filters were not applied to CSS declaration properties.'
 		);
-		$css_declarations   = new WP_Style_Engine_CSS_Declarations( $input_declarations );
 
 		$this->assertSame(
-			'color: red; border-top-left-radius: 99px; text-decoration: underline;',
-			$css_declarations->get_declarations_string( true )
+			'margin-right:10em;',
+			$css_declarations_string,
+			'Unallowed CSS properties or values with HTML tags were not removed.'
 		);
 	}
 
+
 	/**
-	 * Should compile css declarations into a prettified and indented css declarations block string.
+	 * Tests that calc, clamp, min, max, and minmax CSS functions are allowed.
+	 *
+	 * @covers ::get_declarations_string
+	 * @covers ::filter_declaration
 	 */
-	public function test_generate_prettified_with_indent_css_declarations_string() {
-		$input_declarations = array(
-			'color'                  => 'red',
-			'border-top-left-radius' => '99px',
-			'text-decoration'        => 'underline',
+	public function test_should_allow_css_functions_and_strip_unsafe_css_values() {
+		$input_declarations                        = array(
+			'background'       => 'var(--wp--preset--color--primary, 10px)', // Simple var().
+			'font-size'        => 'clamp(36.00rem, calc(32.00rem + 10.00vw), 40.00rem)', // Nested clamp().
+			'width'            => 'min(150vw, 100px)',
+			'min-width'        => 'max(150vw, 100px)',
+			'max-width'        => 'minmax(400px, 50%)',
+			'padding'          => 'calc(80px * -1)',
+			'background-image' => 'url("https://wordpress.org")',
+			'line-height'      => 'url("https://wordpress.org")',
+			'margin'           => 'illegalfunction(30px)',
 		);
-		$css_declarations   = new WP_Style_Engine_CSS_Declarations( $input_declarations );
+		$css_declarations                          = new WP_Style_Engine_CSS_Declarations( $input_declarations );
+		$safecss_filter_attr_allow_css_mock_action = new MockAction();
 
-		$this->assertSame(
-			'	color: red;
-	border-top-left-radius: 99px;
-	text-decoration: underline;',
-			$css_declarations->get_declarations_string( true, 1 )
-		);
-	}
+		// filter_declaration() is called in get_declarations_string().
+		add_filter( 'safecss_filter_attr_allow_css', array( $safecss_filter_attr_allow_css_mock_action, 'filter' ) );
+		$css_declarations_string = $css_declarations->get_declarations_string();
 
-	/**
-	 * Should compile css declarations into a css declarations block string.
-	 */
-	public function test_generate_prettified_with_more_indents_css_declarations_string() {
-		$input_declarations = array(
-			'color'                  => 'red',
-			'border-top-left-radius' => '99px',
-			'text-decoration'        => 'underline',
+		$this->assertSame(
+			9,
+			$safecss_filter_attr_allow_css_mock_action->get_call_count(),
+			'"safecss_filter_attr_allow_css" filters were not applied to CSS declaration values.'
 		);
-		$css_declarations   = new WP_Style_Engine_CSS_Declarations( $input_declarations );
 
 		$this->assertSame(
-			'		color: red;
-		border-top-left-radius: 99px;
-		text-decoration: underline;',
-			$css_declarations->get_declarations_string( true, 2 )
+			'background:var(--wp--preset--color--primary, 10px);font-size:clamp(36.00rem, calc(32.00rem + 10.00vw), 40.00rem);width:min(150vw, 100px);min-width:max(150vw, 100px);max-width:minmax(400px, 50%);padding:calc(80px * -1);background-image:url("https://wordpress.org");',
+			$css_declarations_string,
+			'Unsafe values were not removed'
 		);
 	}
 
 	/**
-	 * Should escape values and run the CSS through safecss_filter_attr.
+	 * Tests that CSS declarations are compiled into a CSS declarations block string.
+	 *
+	 * @covers ::get_declarations_string
+	 *
+	 * @dataProvider data_should_compile_css_declarations_to_css_declarations_string
+	 *
+	 * @param string $expected        The expected declarations block string.
+	 * @param bool   $should_prettify Optional. Whether to pretty the string. Default false.
+	 * @param int    $indent_count    Optional. The number of tab indents. Default false.
 	 */
-	public function test_remove_unsafe_properties_and_values() {
+	public function test_should_compile_css_declarations_to_css_declarations_string( $expected, $should_prettify = false, $indent_count = 0 ) {
 		$input_declarations = array(
-			'color'        => 'url("https://wordpress.org")',
-			'font-size'    => '<red/>',
-			'margin-right' => '10em',
-			'padding'      => '</style>',
-			'potato'       => 'uppercase',
+			'color'                  => 'red',
+			'border-top-left-radius' => '99px',
+			'text-decoration'        => 'underline',
 		);
 		$css_declarations   = new WP_Style_Engine_CSS_Declarations( $input_declarations );
 
 		$this->assertSame(
-			'margin-right:10em;',
-			$css_declarations->get_declarations_string()
+			$expected,
+			$css_declarations->get_declarations_string( $should_prettify, $indent_count )
 		);
 	}
 
 	/**
-	 * Should allow calc, clamp, min, max, and minmax CSS functions.
+	 * Data provider for test_should_compile_css_declarations_to_css_declarations_string().
+	 *
+	 * @return array
 	 */
-	public function test_allow_particular_css_functions() {
-		$input_declarations = array(
-			'background'       => 'var(--wp--preset--color--primary, 10px)', // Simple var().
-			'font-size'        => 'clamp(36.00rem, calc(32.00rem + 10.00vw), 40.00rem)', // Nested clamp().
-			'width'            => 'min(150vw, 100px)',
-			'min-width'        => 'max(150vw, 100px)',
-			'max-width'        => 'minmax(400px, 50%)',
-			'padding'          => 'calc(80px * -1)',
-			'background-image' => 'url("https://wordpress.org")',
-			'line-height'      => 'url("https://wordpress.org")',
-			'margin'           => 'illegalfunction(30px)',
-		);
-		$css_declarations   = new WP_Style_Engine_CSS_Declarations( $input_declarations );
-
-		$this->assertSame(
-			'background:var(--wp--preset--color--primary, 10px);font-size:clamp(36.00rem, calc(32.00rem + 10.00vw), 40.00rem);width:min(150vw, 100px);min-width:max(150vw, 100px);max-width:minmax(400px, 50%);padding:calc(80px * -1);background-image:url("https://wordpress.org");',
-			$css_declarations->get_declarations_string()
+	public function data_should_compile_css_declarations_to_css_declarations_string() {
+		return array(
+			'unprettified, no indent'  => array(
+				'expected' => 'color:red;border-top-left-radius:99px;text-decoration:underline;',
+			),
+			'unprettified, one indent' => array(
+				'expected'        => 'color:red;border-top-left-radius:99px;text-decoration:underline;',
+				'should_prettify' => false,
+				'indent_count'    => 1,
+			),
+			'prettified, no indent'    => array(
+				'expected'        => 'color: red; border-top-left-radius: 99px; text-decoration: underline;',
+				'should_prettify' => true,
+			),
+			'prettified, one indent'   => array(
+				'expected'        => "\tcolor: red;\n\tborder-top-left-radius: 99px;\n\ttext-decoration: underline;",
+				'should_prettify' => true,
+				'indent_count'    => 1,
+			),
+			'prettified, two indents'  => array(
+				'expected'        => "\t\tcolor: red;\n\t\tborder-top-left-radius: 99px;\n\t\ttext-decoration: underline;",
+				'should_prettify' => true,
+				'indent_count'    => 2,
+			),
 		);
 	}
 
 	/**
-	 * Should remove a declaration
+	 * Tests removing a single declaration.
+	 *
+	 * @covers ::remove_declaration
 	 */
-	public function test_remove_declaration() {
+	public function test_should_remove_single_declaration() {
 		$input_declarations = array(
 			'color'       => 'tomato',
 			'margin'      => '10em 10em 20em 1px',
@@ -199,20 +238,25 @@ class WP_Style_Engine_CSS_Declarations_Test extends WP_UnitTestCase {
 
 		$this->assertSame(
 			'color:tomato;margin:10em 10em 20em 1px;font-family:Happy Font serif;',
-			$css_declarations->get_declarations_string()
+			$css_declarations->get_declarations_string(),
+			'CSS declarations string does not match the values of `$declarations` passed to the constructor.'
 		);
 
 		$css_declarations->remove_declaration( 'color' );
+
 		$this->assertSame(
 			'margin:10em 10em 20em 1px;font-family:Happy Font serif;',
-			$css_declarations->get_declarations_string()
+			$css_declarations->get_declarations_string(),
+			'Output after removing "color" declaration via `remove_declaration()` does not match expectations'
 		);
 	}
 
 	/**
-	 * Should remove declarations
+	 * Tests that multiple declarations are removed.
+	 *
+	 * @covers ::remove_declarations
 	 */
-	public function test_remove_declarations() {
+	public function test_should_remove_multiple_declarations() {
 		$input_declarations = array(
 			'color'       => 'cucumber',
 			'margin'      => '10em 10em 20em 1px',
@@ -222,13 +266,16 @@ class WP_Style_Engine_CSS_Declarations_Test extends WP_UnitTestCase {
 
 		$this->assertSame(
 			'color:cucumber;margin:10em 10em 20em 1px;font-family:Happy Font serif;',
-			$css_declarations->get_declarations_string()
+			$css_declarations->get_declarations_string(),
+			'CSS declarations string does not match the values of `$declarations` passed to the constructor.'
 		);
 
 		$css_declarations->remove_declarations( array( 'color', 'margin' ) );
+
 		$this->assertSame(
 			'font-family:Happy Font serif;',
-			$css_declarations->get_declarations_string()
+			$css_declarations->get_declarations_string(),
+			'Output after removing "color" and "margin" declarations via `remove_declarations()` does not match expectations'
 		);
 	}
 }