From 5e9d8f893cf3f91977d851b8e3744bd2c9fccb96 Mon Sep 17 00:00:00 2001 From: ramon Date: Sun, 26 Nov 2023 16:32:27 +1100 Subject: [PATCH 1/3] - Loading style engine files that use utils classes after the utils classes have loaded - Adding CSS var parsing capability to fontSize and fontFamily. The JS package does this, theme.json has these presets, why not the Style Engine? I think it wasn't a deliberate omission. - Updating docs in relation to CSS var names --- lib/load.php | 4 +- .../style-engine/class-wp-style-engine.php | 6 ++ ...ng-the-style-engine-with-block-supports.md | 55 ++++++++++++------- phpunit/style-engine/style-engine-test.php | 15 +++-- 4 files changed, 55 insertions(+), 25 deletions(-) diff --git a/lib/load.php b/lib/load.php index 745dddd8ab107..e2d804befe7d7 100644 --- a/lib/load.php +++ b/lib/load.php @@ -224,12 +224,12 @@ function () { // Copied package PHP files. 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'; require_once __DIR__ . '/../build/style-engine/class-wp-style-engine-css-declarations-gutenberg.php'; require_once __DIR__ . '/../build/style-engine/class-wp-style-engine-css-rule-gutenberg.php'; require_once __DIR__ . '/../build/style-engine/class-wp-style-engine-css-rules-store-gutenberg.php'; require_once __DIR__ . '/../build/style-engine/class-wp-style-engine-processor-gutenberg.php'; + require_once __DIR__ . '/../build/style-engine/class-wp-style-engine-gutenberg.php'; + require_once __DIR__ . '/../build/style-engine/style-engine-gutenberg.php'; } // Block supports overrides. diff --git a/packages/style-engine/class-wp-style-engine.php b/packages/style-engine/class-wp-style-engine.php index a8935fc5ef14b..fdb0083ad9eec 100644 --- a/packages/style-engine/class-wp-style-engine.php +++ b/packages/style-engine/class-wp-style-engine.php @@ -210,6 +210,9 @@ final class WP_Style_Engine { 'property_keys' => array( 'default' => 'font-size', ), + 'css_vars' => array( + 'font-size' => '--wp--preset--font-size--$slug', + ), 'path' => array( 'typography', 'fontSize' ), 'classnames' => array( 'has-$slug-font-size' => 'font-size', @@ -219,6 +222,9 @@ final class WP_Style_Engine { 'property_keys' => array( 'default' => 'font-family', ), + 'css_vars' => array( + 'font-family' => '--wp--preset--font-family--$slug', + ), 'path' => array( 'typography', 'fontFamily' ), 'classnames' => array( 'has-$slug-font-family' => 'font-family', diff --git a/packages/style-engine/docs/using-the-style-engine-with-block-supports.md b/packages/style-engine/docs/using-the-style-engine-with-block-supports.md index 07d91c54a28d6..44a8af820aff1 100644 --- a/packages/style-engine/docs/using-the-style-engine-with-block-supports.md +++ b/packages/style-engine/docs/using-the-style-engine-with-block-supports.md @@ -51,7 +51,7 @@ When [registering a block support](https://developer.wordpress.org/reference/cla If a block has opted into the block support, the values of "class" and "style" will be applied to the block element's "class" and "style" attributes accordingly when rendered in the frontend HTML. Note, this applies only to server-side rendered blocks, for example, the [Site Title block](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/#site-title). -The callback receives `$block_type` and `$block_attributes` as arguments. The `style` attribute within `$block_attributes` only contains the raw style object, if any styles have been set for the block, and not any CSS or classnames to be applied to the block's HTML elements. +The callback receives `$block_type` and `$block_attributes` as arguments. The `style` attribute within `$block_attributes` only contains the raw style object, if any styles have been set for the block, and not any CSS or classnames to be applied to the block's HTML elements. Here is where `wp_style_engine_get_styles` comes in handy: it will generate CSS and, if appropriate, classnames to be added to the "style" and "class" HTML attributes in the final rendered block markup. @@ -100,7 +100,7 @@ Before passing the block style object to the Style Engine, you'll need to take i If a block either: -- has no support for a style, or +- has no support for a style, or - skips serialization of that style it's likely that you'll want to remove those style values from the style object before passing it to the Style Engine with help of two functions: @@ -108,24 +108,24 @@ it's likely that you'll want to remove those style values from the style object - wp_should_skip_block_supports_serialization() - block_has_support() -We can now update the apply callback code above so that we'll only return "style" and "class", where a block has support and it doesn't skip serialization: +We can now update the "apply" callback code above so that we'll only return "style" and "class", where a block has support, and it doesn't skip serialization: ```php function gutenberg_apply_colors_support( $block_type, $block_attributes ) { // The return value. $attributes = array(); - + // Return early if the block skips all serialization for block supports. if ( gutenberg_should_skip_block_supports_serialization( $block_type, 'color' ) ) { return $attributes; } // Checks for support and skip serialization. - $has_text_support = block_has_support( $block_type, array( 'color', 'text' ), false ); + $has_text_support = block_has_support( $block_type, array( 'color', 'text' ), false ); $has_background_support = block_has_support( $block_type, array( 'color', 'background' ), false ); - $skips_serialization_of_color_text = wp_should_skip_block_supports_serialization( $block_type, 'color', 'text' ); - $skips_serialization_of_color_background = wp_should_skip_block_supports_serialization( $block_type, 'color', 'background' ); - + $skips_serialization_of_color_text = wp_should_skip_block_supports_serialization( $block_type, 'color', 'text' ); + $skips_serialization_of_color_background = wp_should_skip_block_supports_serialization( $block_type, 'color', 'background' ); + // Get the color styles from the style object. $block_color_styles = isset( $block_attributes['style']['color'] ) ? $block_attributes['style']['color'] : null; @@ -161,7 +161,7 @@ Styling a block using these presets normally involves adding the selector to the 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. +To discern CSS values from preset values, the Style Engine expects a special format. Preset values must follow the pattern `var:preset||`. @@ -171,13 +171,16 @@ Example: ```php // Let's say the block attributes styles contain a fontSize preset slug of "small". +// $block_attributes['fontSize'] = 'var:preset|font-size|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". +// $block_attributes['backgroundColor'] = 'var:preset|color|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 ) + 'color' => array( 'background' => $preset_background_color ), + 'spacing' => array( 'padding' => '10px', 'margin' => array( 'top' => '1em') ), ); $styles = wp_style_engine_get_styles( @@ -187,29 +190,43 @@ 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', + 'css' => 'background-color:var(--wp--preset--color--blue);padding:10px;margin-top:1em;font-size:var(--wp--preset--font-size--small);', + 'declarations' => array( + 'background-color' => 'var(--wp--preset--color--blue)', + 'padding' => '10px', + 'margin-top' => '1em', + 'font-size' => 'var(--wp--preset--font-size--small)', + ), + 'classnames' => 'has-background 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. +If you don't want the Style Engine to output the CSS custom vars in the generated CSS string as well, which you might not if you're applying both the CSS rules and classnames to the block element, you can pass `'convert_vars_to_classnames' => true` in the options array. + +This flag means "covert the vars to classnames and don't output the vars to the CSS". The Style Engine will therefore **only** generate the required classnames and omit the CSS custom vars in the CSS. + +Using the above example code, observe the different output when we pass the option: ```php $options = array( - // Whether to skip converting CSS var:? values to var( --wp--preset--* ) values. Default is `false`. - 'convert_vars_to_classnames' => 'true', + 'convert_vars_to_classnames' => true, ); + $styles = wp_style_engine_get_styles( - $block_styles, - $options + $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', + 'css' => 'padding:10px;margin-top:1em;', + 'declarations' => array( + 'padding' => '10px', + 'margin-top' => '1em', + ), + 'classnames' => 'has-background has-blue-background-color has-small-font-size', ) */ ``` diff --git a/phpunit/style-engine/style-engine-test.php b/phpunit/style-engine/style-engine-test.php index 6fb485e9a6f31..d8ded749c640b 100644 --- a/phpunit/style-engine/style-engine-test.php +++ b/phpunit/style-engine/style-engine-test.php @@ -238,19 +238,26 @@ public function data_wp_style_engine_get_styles() { 'elements_with_css_var_value' => array( 'block_styles' => array( - 'color' => array( + 'color' => array( 'text' => 'var:preset|color|my-little-pony', ), + 'typography' => array( + 'fontSize' => 'var:preset|font-size|cabbage-patch', + 'fontFamily' => 'var:preset|font-family|transformers', + ), ), 'options' => array( 'selector' => '.wp-selector', ), 'expected_output' => array( - 'css' => '.wp-selector{color:var(--wp--preset--color--my-little-pony);}', + 'css' => '.wp-selector{color:var(--wp--preset--color--my-little-pony);font-size:var(--wp--preset--font-size--cabbage-patch);font-family:var(--wp--preset--font-family--transformers);}', 'declarations' => array( - 'color' => 'var(--wp--preset--color--my-little-pony)', + 'color' => 'var(--wp--preset--color--my-little-pony)', + 'font-size' => 'var(--wp--preset--font-size--cabbage-patch)', + 'font-family' => 'var(--wp--preset--font-family--transformers)', + ), - 'classnames' => 'has-text-color has-my-little-pony-color', + 'classnames' => 'has-text-color has-my-little-pony-color has-cabbage-patch-font-size has-transformers-font-family', ), ), From a84dc330cbd47e48a4184a3c434ccdc3885615d5 Mon Sep 17 00:00:00 2001 From: Ramon Date: Mon, 27 Nov 2023 12:27:54 +1100 Subject: [PATCH 2/3] Apply suggestions from code review Spelling fix Co-authored-by: Andrew Serong <14988353+andrewserong@users.noreply.github.com> --- .../docs/using-the-style-engine-with-block-supports.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/style-engine/docs/using-the-style-engine-with-block-supports.md b/packages/style-engine/docs/using-the-style-engine-with-block-supports.md index 44a8af820aff1..b43896c83c097 100644 --- a/packages/style-engine/docs/using-the-style-engine-with-block-supports.md +++ b/packages/style-engine/docs/using-the-style-engine-with-block-supports.md @@ -204,7 +204,7 @@ array( If you don't want the Style Engine to output the CSS custom vars in the generated CSS string as well, which you might not if you're applying both the CSS rules and classnames to the block element, you can pass `'convert_vars_to_classnames' => true` in the options array. -This flag means "covert the vars to classnames and don't output the vars to the CSS". The Style Engine will therefore **only** generate the required classnames and omit the CSS custom vars in the CSS. +This flag means "convert the vars to classnames and don't output the vars to the CSS". The Style Engine will therefore **only** generate the required classnames and omit the CSS custom vars in the CSS. Using the above example code, observe the different output when we pass the option: From 7a5198eca88300fbbdce6108228becf60f5ad412 Mon Sep 17 00:00:00 2001 From: ramon Date: Mon, 27 Nov 2023 12:33:14 +1100 Subject: [PATCH 3/3] Replacing spacing indents with tabs. Disclaimer: This commit does not necessarily reflect the views or positions of the author in relation to tabs vs spaces. --- ...using-the-style-engine-with-block-supports.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/packages/style-engine/docs/using-the-style-engine-with-block-supports.md b/packages/style-engine/docs/using-the-style-engine-with-block-supports.md index b43896c83c097..42350a17ffcd6 100644 --- a/packages/style-engine/docs/using-the-style-engine-with-block-supports.md +++ b/packages/style-engine/docs/using-the-style-engine-with-block-supports.md @@ -30,11 +30,11 @@ The global function `wp_style_engine_get_styles` accepts a style object as its f ```php $block_styles = array( - 'spacing' => array( 'padding' => '10px', 'margin' => array( 'top' => '1em') ), - 'typography' => array( 'fontSize' => '2.2rem' ), + 'spacing' => array( 'padding' => '10px', 'margin' => array( 'top' => '1em') ), + 'typography' => array( 'fontSize' => '2.2rem' ), ); $styles = wp_style_engine_get_styles( - $block_styles + $block_styles ); print_r( $styles ); @@ -190,7 +190,7 @@ print_r( $styles ); /* array( - 'css' => 'background-color:var(--wp--preset--color--blue);padding:10px;margin-top:1em;font-size:var(--wp--preset--font-size--small);', + 'css' => 'background-color:var(--wp--preset--color--blue);padding:10px;margin-top:1em;font-size:var(--wp--preset--font-size--small);', 'declarations' => array( 'background-color' => 'var(--wp--preset--color--blue)', 'padding' => '10px', @@ -214,19 +214,19 @@ $options = array( ); $styles = wp_style_engine_get_styles( - $block_styles, - $options + $block_styles, + $options ); print_r( $styles ); /* array( - 'css' => 'padding:10px;margin-top:1em;', + 'css' => 'padding:10px;margin-top:1em;', 'declarations' => array( 'padding' => '10px', 'margin-top' => '1em', ), - 'classnames' => 'has-background has-blue-background-color has-small-font-size', + 'classnames' => 'has-background has-blue-background-color has-small-font-size', ) */ ```