From c14343ba256832a7321f6d7dd0de353ad95746be Mon Sep 17 00:00:00 2001 From: Sergey Biryukov Date: Wed, 17 May 2023 11:58:26 +0000 Subject: [PATCH] Docs: Improve Style Engine DocBlocks per the documentation standards. Follow-up to [54156], [55719], [55733]. See #57840. Built from https://develop.svn.wordpress.org/trunk@55819 git-svn-id: http://core.svn.wordpress.org/trunk@55331 1a063a9b-81f0-0310-95a4-ce76da25c4cd --- wp-includes/script-loader.php | 9 +- wp-includes/style-engine.php | 76 +++++++--- ...class-wp-style-engine-css-declarations.php | 18 ++- .../class-wp-style-engine-css-rule.php | 18 ++- .../class-wp-style-engine-css-rules-store.php | 3 +- .../class-wp-style-engine-processor.php | 10 +- .../style-engine/class-wp-style-engine.php | 134 ++++++++++++------ wp-includes/version.php | 2 +- 8 files changed, 184 insertions(+), 86 deletions(-) diff --git a/wp-includes/script-loader.php b/wp-includes/script-loader.php index 14dbb2db15..4fb9f3059f 100644 --- a/wp-includes/script-loader.php +++ b/wp-includes/script-loader.php @@ -3016,10 +3016,13 @@ function wp_enqueue_block_support_styles( $style, $priority = 10 ) { * @since 6.1.0 * * @param array $options { - * Optional. An array of options to pass to wp_style_engine_get_stylesheet_from_context(). Default empty array. + * Optional. An array of options to pass to wp_style_engine_get_stylesheet_from_context(). + * Default empty array. * - * @type bool $optimize Whether to optimize the CSS output, e.g., combine rules. Default is `false`. - * @type bool $prettify Whether to add new lines and indents to output. Default is the test of whether the global constant `SCRIPT_DEBUG` is defined. + * @type bool $optimize Whether to optimize the CSS output, e.g., combine rules. + * Default false. + * @type bool $prettify Whether to add new lines and indents to output. + * Default to whether the `SCRIPT_DEBUG` constant is defined. * } */ function wp_enqueue_stored_styles( $options = array() ) { diff --git a/wp-includes/style-engine.php b/wp-includes/style-engine.php index 377f1a1b68..5b5545c85e 100644 --- a/wp-includes/style-engine.php +++ b/wp-includes/style-engine.php @@ -11,35 +11,52 @@ */ /** - * Global public interface method to generate styles from a single style object, e.g., - * the value of a block's attributes.style object or the top level styles in theme.json. - * See: https://developer.wordpress.org/block-editor/reference-guides/theme-json-reference/theme-json-living/#styles and - * https://developer.wordpress.org/block-editor/reference-guides/block-api/block-supports/ + * Global public interface method to generate styles from a single style object, + * e.g. the value of a block's attributes.style object or the top level styles in theme.json. * * Example usage: * - * $styles = wp_style_engine_get_styles( array( 'color' => array( 'text' => '#cccccc' ) ) ); + * $styles = wp_style_engine_get_styles( + * array( + * 'color' => array( 'text' => '#cccccc' ), + * ) + * ); * * Returns: * - * array( 'css' => 'color: #cccccc', 'declarations' => array( 'color' => '#cccccc' ), 'classnames' => 'has-color' ) + * array( + * 'css' => 'color: #cccccc', + * 'declarations' => array( 'color' => '#cccccc' ), + * 'classnames' => 'has-color', + * ) * - * @access public * @since 6.1.0 * + * @see https://developer.wordpress.org/block-editor/reference-guides/theme-json-reference/theme-json-living/#styles + * @see https://developer.wordpress.org/block-editor/reference-guides/block-api/block-supports/ + * * @param array $block_styles The style object. * @param array $options { * Optional. An array of options. Default empty array. * - * @type string|null $context An identifier describing the origin of the style object, e.g., 'block-supports' or 'global-styles'. Default is `null`. - * When set, the style engine will attempt to store the CSS rules, where a selector is also passed. - * @type bool $convert_vars_to_classnames Whether to skip converting incoming CSS var patterns, e.g., `var:preset||`, to `var( --wp--preset--* )` values. Default `false`. - * @type string $selector Optional. When a selector is passed, the value of `$css` in the return value will comprise a full CSS rule `$selector { ...$css_declarations }`, - * otherwise, the value will be a concatenated string of CSS declarations. + * @type string|null $context An identifier describing the origin of the style object, + * e.g. 'block-supports' or 'global-styles'. Default null. + * When set, the style engine will attempt to store the CSS rules, + * where a selector is also passed. + * @type bool $convert_vars_to_classnames Whether to skip converting incoming CSS var patterns, + * e.g. `var:preset||`, + * to `var( --wp--preset--* )` values. Default false. + * @type string $selector Optional. When a selector is passed, + * the value of `$css` in the return value will comprise + * a full CSS rule `$selector { ...$css_declarations }`, + * otherwise, the value will be a concatenated string + * of CSS declarations. * } * @return array { - * @type string $css A CSS ruleset or declarations block formatted to be placed in an HTML `style` attribute or tag. - * @type string[] $declarations An associative array of CSS definitions, e.g., `array( "$property" => "$value", "$property" => "$value" )`. + * @type string $css A CSS ruleset or declarations block + * formatted to be placed in an HTML `style` attribute or tag. + * @type string[] $declarations An associative array of CSS definitions, + * e.g. `array( "$property" => "$value", "$property" => "$value" )`. * @type string $classnames Classnames separated by a space. * } */ @@ -79,8 +96,17 @@ function wp_style_engine_get_styles( $block_styles, $options = array() ) { * * Example usage: * - * $css_rules = array( array( 'selector' => '.elephant-are-cool', 'declarations' => array( 'color' => 'gray', 'width' => '3em' ) ) ); - * $css = wp_style_engine_get_stylesheet_from_css_rules( $css_rules ); + * $css_rules = array( + * array( + * 'selector' => '.elephant-are-cool', + * 'declarations' => array( + * 'color' => 'gray', + * 'width' => '3em', + * ), + * ), + * ); + * + * $css = wp_style_engine_get_stylesheet_from_css_rules( $css_rules ); * * Returns: * @@ -93,16 +119,20 @@ function wp_style_engine_get_styles( $block_styles, $options = array() ) { * * @type array ...$0 { * @type string $selector A CSS selector. - * @type string[] $declarations An associative array of CSS definitions, e.g., `array( "$property" => "$value", "$property" => "$value" )`. + * @type string[] $declarations An associative array of CSS definitions, + * e.g. `array( "$property" => "$value", "$property" => "$value" )`. * } * } * @param array $options { * Optional. An array of options. Default empty array. * - * @type string|null $context An identifier describing the origin of the style object, e.g., 'block-supports' or 'global-styles'. Default is 'block-supports'. + * @type string|null $context An identifier describing the origin of the style object, + * e.g. 'block-supports' or 'global-styles'. Default 'block-supports'. * When set, the style engine will attempt to store the CSS rules. - * @type bool $optimize Whether to optimize the CSS output, e.g., combine rules. Default is `false`. - * @type bool $prettify Whether to add new lines and indents to output. Default is the test of whether the global constant `SCRIPT_DEBUG` is defined. + * @type bool $optimize Whether to optimize the CSS output, e.g. combine rules. + * Default false. + * @type bool $prettify Whether to add new lines and indents to output. + * Defaults to whether the `SCRIPT_DEBUG` constant is defined. * } * @return string A string of compiled CSS declarations, or empty string. */ @@ -147,8 +177,10 @@ function wp_style_engine_get_stylesheet_from_css_rules( $css_rules, $options = a * @param array $options { * Optional. An array of options. Default empty array. * - * @type bool $optimize Whether to optimize the CSS output, e.g., combine rules. Default is `false`. - * @type bool $prettify Whether to add new lines and indents to output. Default is the test of whether the global constant `SCRIPT_DEBUG` is defined. + * @type bool $optimize Whether to optimize the CSS output, e.g. combine rules. + * Default false. + * @type bool $prettify Whether to add new lines and indents to output. + * Defaults to whether the `SCRIPT_DEBUG` constant is defined. * } * @return string A compiled CSS string. */ diff --git a/wp-includes/style-engine/class-wp-style-engine-css-declarations.php b/wp-includes/style-engine/class-wp-style-engine-css-declarations.php index ae12dd1abf..fbcb54b73a 100644 --- a/wp-includes/style-engine/class-wp-style-engine-css-declarations.php +++ b/wp-includes/style-engine/class-wp-style-engine-css-declarations.php @@ -30,11 +30,13 @@ class WP_Style_Engine_CSS_Declarations { * Constructor for this object. * * If a `$declarations` array is passed, it will be used to populate - * the initial $declarations prop of the object by calling add_declarations(). + * the initial `$declarations` prop of the object by calling add_declarations(). * * @since 6.1.0 * - * @param string[] $declarations An associative array of CSS definitions, e.g., `array( "$property" => "$value", "$property" => "$value" )`. + * @param string[] $declarations Optional. An associative array of CSS definitions, + * e.g. `array( "$property" => "$value", "$property" => "$value" )`. + * Default empty array. */ public function __construct( $declarations = array() ) { $this->add_declarations( $declarations ); @@ -102,7 +104,7 @@ class WP_Style_Engine_CSS_Declarations { * * @since 6.1.0 * - * @param string[] $properties An array of properties. + * @param string[] $properties Optional. An array of properties. Default empty array. * @return WP_Style_Engine_CSS_Declarations Returns the object to allow chaining methods. */ public function remove_declarations( $properties = array() ) { @@ -130,7 +132,8 @@ class WP_Style_Engine_CSS_Declarations { * * @param string $property The CSS property. * @param string $value The value to be filtered. - * @param string $spacer The spacer between the colon and the value. Defaults to an empty string. + * @param string $spacer Optional. The spacer between the colon and the value. + * Default empty string. * @return string The filtered declaration or an empty string. */ protected static function filter_declaration( $property, $value, $spacer = '' ) { @@ -146,8 +149,10 @@ class WP_Style_Engine_CSS_Declarations { * * @since 6.1.0 * - * @param bool $should_prettify Whether to add spacing, new lines and indents. - * @param int $indent_count The number of tab indents to apply to the rule. Applies if `prettify` is `true`. + * @param bool $should_prettify Optional. Whether to add spacing, new lines and indents. + * Default false. + * @param int $indent_count Optional. The number of tab indents to apply to the rule. + * Applies if `prettify` is `true`. Default 0. * @return string The CSS declarations. */ public function get_declarations_string( $should_prettify = false, $indent_count = 0 ) { @@ -164,6 +169,7 @@ class WP_Style_Engine_CSS_Declarations { $declarations_output .= "{$indent}{$filtered_declaration};$suffix"; } } + return rtrim( $declarations_output ); } diff --git a/wp-includes/style-engine/class-wp-style-engine-css-rule.php b/wp-includes/style-engine/class-wp-style-engine-css-rule.php index a109668cd9..2b31cff0b4 100644 --- a/wp-includes/style-engine/class-wp-style-engine-css-rule.php +++ b/wp-includes/style-engine/class-wp-style-engine-css-rule.php @@ -36,13 +36,15 @@ class WP_Style_Engine_CSS_Rule { protected $declarations; /** - * Constructor + * Constructor. * * @since 6.1.0 * - * @param string $selector The CSS selector. - * @param string[]|WP_Style_Engine_CSS_Declarations $declarations An associative array of CSS definitions, e.g., `array( "$property" => "$value", "$property" => "$value" )`, + * @param string $selector Optional. The CSS selector. Default empty string. + * @param string[]|WP_Style_Engine_CSS_Declarations $declarations Optional. An associative array of CSS definitions, + * e.g. `array( "$property" => "$value", "$property" => "$value" )`, * or a WP_Style_Engine_CSS_Declarations object. + * Default empty array. */ public function __construct( $selector = '', $declarations = array() ) { $this->set_selector( $selector ); @@ -67,8 +69,8 @@ class WP_Style_Engine_CSS_Rule { * * @since 6.1.0 * - * @param array|WP_Style_Engine_CSS_Declarations $declarations An array of declarations (property => value pairs), - * or a WP_Style_Engine_CSS_Declarations object. + * @param string[]|WP_Style_Engine_CSS_Declarations $declarations An array of declarations (property => value pairs), + * or a WP_Style_Engine_CSS_Declarations object. * @return WP_Style_Engine_CSS_Rule Returns the object to allow chaining of methods. */ public function add_declarations( $declarations ) { @@ -114,8 +116,10 @@ class WP_Style_Engine_CSS_Rule { * * @since 6.1.0 * - * @param bool $should_prettify Whether to add spacing, new lines and indents. - * @param int $indent_count The number of tab indents to apply to the rule. Applies if `prettify` is `true`. + * @param bool $should_prettify Optional. Whether to add spacing, new lines and indents. + * Default false. + * @param int $indent_count Optional. The number of tab indents to apply to the rule. + * Applies if `prettify` is `true`. Default 0. * @return string */ public function get_css( $should_prettify = false, $indent_count = 0 ) { diff --git a/wp-includes/style-engine/class-wp-style-engine-css-rules-store.php b/wp-includes/style-engine/class-wp-style-engine-css-rules-store.php index ee1f229ea8..371e59fb8b 100644 --- a/wp-includes/style-engine/class-wp-style-engine-css-rules-store.php +++ b/wp-includes/style-engine/class-wp-style-engine-css-rules-store.php @@ -123,7 +123,8 @@ class WP_Style_Engine_CSS_Rules_Store { * @since 6.1.0 * * @param string $selector The CSS selector. - * @return WP_Style_Engine_CSS_Rule|void Returns a WP_Style_Engine_CSS_Rule object, or void if the selector is empty. + * @return WP_Style_Engine_CSS_Rule|void Returns a WP_Style_Engine_CSS_Rule object, + * or void if the selector is empty. */ public function add_rule( $selector ) { $selector = trim( $selector ); diff --git a/wp-includes/style-engine/class-wp-style-engine-processor.php b/wp-includes/style-engine/class-wp-style-engine-processor.php index 693ec18488..05827e41af 100644 --- a/wp-includes/style-engine/class-wp-style-engine-processor.php +++ b/wp-includes/style-engine/class-wp-style-engine-processor.php @@ -59,7 +59,9 @@ class WP_Style_Engine_Processor { * * @since 6.1.0 * - * @param WP_Style_Engine_CSS_Rule|WP_Style_Engine_CSS_Rule[] $css_rules A single, or an array of, WP_Style_Engine_CSS_Rule objects from a store or otherwise. + * @param WP_Style_Engine_CSS_Rule|WP_Style_Engine_CSS_Rule[] $css_rules A single, or an array of, + * WP_Style_Engine_CSS_Rule objects + * from a store or otherwise. * @return WP_Style_Engine_Processor Returns the object to allow chaining methods. */ public function add_rules( $css_rules ) { @@ -87,8 +89,10 @@ class WP_Style_Engine_Processor { * @param array $options { * Optional. An array of options. Default empty array. * - * @type bool $optimize Whether to optimize the CSS output, e.g., combine rules. Default is `false`. - * @type bool $prettify Whether to add new lines and indents to output. Default is the test of whether the global constant `SCRIPT_DEBUG` is defined. + * @type bool $optimize Whether to optimize the CSS output, e.g. combine rules. + * Default false. + * @type bool $prettify Whether to add new lines and indents to output. + * Defaults to whether the `SCRIPT_DEBUG` constant is defined. * } * @return string The computed CSS. */ diff --git a/wp-includes/style-engine/class-wp-style-engine.php b/wp-includes/style-engine/class-wp-style-engine.php index 393b0bdf28..9a9da37e69 100644 --- a/wp-includes/style-engine/class-wp-style-engine.php +++ b/wp-includes/style-engine/class-wp-style-engine.php @@ -10,11 +10,14 @@ /** * The main class integrating all other WP_Style_Engine_* classes. * - * The Style Engine aims to provide a consistent API for rendering styling for blocks across both client-side and server-side applications. + * The Style Engine aims to provide a consistent API for rendering styling for blocks + * across both client-side and server-side applications. * * This class is final and should not be extended. - * 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 wp_style_engine_get_styles() instead. + * + * 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 wp_style_engine_get_styles() instead. * * @access private * @since 6.1.0 @@ -24,15 +27,24 @@ final 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 => (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", ... )`. + * + * For every style definition, the following properties are valid: + * + * - 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) An 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", ... )`. * * @since 6.1.0 * @var array @@ -227,16 +239,20 @@ final class WP_Style_Engine { ); /** - * Util: Extracts the slug in kebab case from a preset string, e.g., `heavenly-blue` from `var:preset|color|heavenlyBlue`. + * Util: Extracts the slug in kebab case from a preset string, + * e.g. `heavenly-blue` from `var:preset|color|heavenlyBlue`. * * @since 6.1.0 * * @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 $property_key The CSS property that is the second element of the preset string. + * Used for matching. * @return string The slug, or empty string if not found. */ protected static function get_slug_from_preset_value( $style_value, $property_key ) { - if ( is_string( $style_value ) && is_string( $property_key ) && str_contains( $style_value, "var:preset|{$property_key}|" ) ) { + if ( is_string( $style_value ) && is_string( $property_key ) + && str_contains( $style_value, "var:preset|{$property_key}|" ) + ) { $index_to_splice = strrpos( $style_value, '|' ) + 1; return _wp_to_kebab_case( substr( $style_value, $index_to_splice ) ); } @@ -244,12 +260,14 @@ final class WP_Style_Engine { } /** - * Util: Generates a CSS var string, e.g., `var(--wp--preset--color--background)` from a preset string such as `var:preset|space|50`. + * Util: Generates a CSS var string, e.g. `var(--wp--preset--color--background)` + * from a preset string such as `var:preset|space|50`. * * @since 6.1.0 * * @param string $style_value A single CSS preset value. - * @param string[] $css_vars An associate array of CSS var patterns used to generate the var string. + * @param string[] $css_vars An associate array of CSS var patterns + * used to generate the var string. * @return string The CSS var, or an empty string if no match for slug found. */ protected static function get_css_var_value( $style_value, $css_vars ) { @@ -284,8 +302,11 @@ final class WP_Style_Engine { * @since 6.1.0 * * @param string $store_name A valid store key. - * @param string $css_selector When a selector is passed, the function will return a full CSS rule `$selector { ...rules }`, otherwise a concatenated string of properties and values. - * @param string[] $css_declarations An associative array of CSS definitions, e.g., `array( "$property" => "$value", "$property" => "$value" )`. + * @param string $css_selector When a selector is passed, the function will return + * a full CSS rule `$selector { ...rules }` + * otherwise a concatenated string of properties and values. + * @param string[] $css_declarations An associative array of CSS definitions, + * e.g. `array( "$property" => "$value", "$property" => "$value" )`. */ public static function store_css_rule( $store_name, $css_selector, $css_declarations ) { if ( empty( $store_name ) || empty( $css_selector ) || empty( $css_declarations ) ) { @@ -308,6 +329,7 @@ final class WP_Style_Engine { /** * Returns classnames and CSS based on the values in a styles object. + * * Return values are parsed based on the instructions in BLOCK_STYLE_DEFINITIONS_METADATA. * * @since 6.1.0 @@ -316,13 +338,19 @@ final class WP_Style_Engine { * @param array $options { * Optional. An array of options. Default empty array. * - * @type bool $convert_vars_to_classnames Whether to skip converting incoming CSS var patterns, e.g., `var:preset||`, to `var( --wp--preset--* )` values. Default false. - * @type string $selector Optional. When a selector is passed, the value of `$css` in the return value will comprise a full CSS rule `$selector { ...$css_declarations }`, - * otherwise, the value will be a concatenated string of CSS declarations. + * @type bool $convert_vars_to_classnames Whether to skip converting incoming CSS var patterns, + * e.g. `var:preset||`, + * to `var( --wp--preset--* )` values. Default false. + * @type string $selector Optional. When a selector is passed, + * the value of `$css` in the return value will comprise + * a full CSS rule `$selector { ...$css_declarations }`, + * otherwise, the value will be a concatenated string + * of CSS declarations. * } * @return array { * @type string[] $classnames Array of class names. - * @type string[] $declarations An associative array of CSS definitions, e.g., `array( "$property" => "$value", "$property" => "$value" )`. + * @type string[] $declarations An associative array of CSS definitions, + * e.g. `array( "$property" => "$value", "$property" => "$value" )`. * } */ public static function parse_block_styles( $block_styles, $options ) { @@ -355,11 +383,13 @@ final class WP_Style_Engine { } /** - * Returns classnames, and generates classname(s) from a CSS preset property pattern, e.g., `var:preset||`. + * Returns classnames, and generates classname(s) from a CSS preset property pattern, + * e.g. `var:preset||`. * * @since 6.1.0 * - * @param string $style_value A single raw style value or CSS preset property from the `$block_styles` array. + * @param string $style_value A single raw style value or CSS preset property + * from the `$block_styles` array. * @param array $style_definition A single style definition from BLOCK_STYLE_DEFINITIONS_METADATA. * @return string[] An array of CSS classnames, or empty array if there are none. */ @@ -402,11 +432,11 @@ final class WP_Style_Engine { * @param array $options { * Optional. An array of options. Default empty array. * - * @type bool $convert_vars_to_classnames Whether to skip converting incoming CSS var patterns, e.g., - * `var:preset||`, to `var( --wp--preset--* )` values. - * Default false. + * @type bool $convert_vars_to_classnames Whether to skip converting incoming CSS var patterns, + * e.g. `var:preset||`, + * to `var( --wp--preset--* )` values. Default false. * } - * @return string[] An associative array of CSS definitions, e.g., `array( "$property" => "$value", "$property" => "$value" )`. + * @return string[] An associative array of CSS definitions, e.g. `array( "$property" => "$value", "$property" => "$value" )`. */ protected static function get_css_declarations( $style_value, $style_definition, $options = array() ) { if ( isset( $style_definition['value_func'] ) && is_callable( $style_definition['value_func'] ) ) { @@ -480,13 +510,17 @@ final class WP_Style_Engine { * @since 6.1.0 * * @param array $style_value A single raw style value from `$block_styles` array. - * @param array $individual_property_definition A single style definition from BLOCK_STYLE_DEFINITIONS_METADATA representing an individual property of a CSS property, e.g., 'top' in 'border-top'. + * @param array $individual_property_definition A single style definition from BLOCK_STYLE_DEFINITIONS_METADATA + * representing an individual property of a CSS property, + * e.g. 'top' in 'border-top'. * @param array $options { * Optional. An array of options. Default empty array. * - * @type bool $convert_vars_to_classnames Whether to skip converting incoming CSS var patterns, e.g., `var:preset||`, to `var( --wp--preset--* )` values. Default false. + * @type bool $convert_vars_to_classnames Whether to skip converting incoming CSS var patterns, + * e.g. `var:preset||`, + * to `var( --wp--preset--* )` values. Default false. * } - * @return string[] An associative array of CSS definitions, e.g., `array( "$property" => "$value", "$property" => "$value" )`. + * @return string[] An associative array of CSS definitions, e.g. `array( "$property" => "$value", "$property" => "$value" )`. */ protected static function get_individual_property_css_declarations( $style_value, $individual_property_definition, $options = array() ) { if ( ! is_array( $style_value ) || empty( $style_value ) || empty( $individual_property_definition['path'] ) ) { @@ -494,9 +528,12 @@ final class WP_Style_Engine { } /* - * 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". + * 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]; @@ -514,10 +551,14 @@ final class WP_Style_Engine { if ( $style_definition && isset( $style_definition['property_keys']['individual'] ) ) { // Set a CSS var if there is a valid preset value. - if ( is_string( $value ) && str_contains( $value, 'var:' ) && ! $should_skip_css_vars && ! empty( $individual_property_definition['css_vars'] ) ) { + if ( is_string( $value ) && str_contains( $value, 'var:' ) + && ! $should_skip_css_vars && ! empty( $individual_property_definition['css_vars'] ) + ) { $value = static::get_css_var_value( $value, $individual_property_definition['css_vars'] ); } - $individual_css_property = sprintf( $style_definition['property_keys']['individual'], $individual_property_key ); + + $individual_css_property = sprintf( $style_definition['property_keys']['individual'], $individual_property_key ); + $css_declarations[ $individual_css_property ] = $value; } } @@ -529,8 +570,11 @@ final class WP_Style_Engine { * * @since 6.1.0 * - * @param string[] $css_declarations An associative array of CSS definitions, e.g., `array( "$property" => "$value", "$property" => "$value" )`. - * @param string $css_selector When a selector is passed, the function will return a full CSS rule `$selector { ...rules }`, otherwise a concatenated string of properties and values. + * @param string[] $css_declarations An associative array of CSS definitions, + * e.g. `array( "$property" => "$value", "$property" => "$value" )`. + * @param string $css_selector When a selector is passed, the function will return + * a full CSS rule `$selector { ...rules }`, + * otherwise a concatenated string of properties and values. * @return string A compiled CSS string. */ public static function compile_css( $css_declarations, $css_selector ) { @@ -553,14 +597,18 @@ final class WP_Style_Engine { * * @since 6.1.0 * - * @param WP_Style_Engine_CSS_Rule[] $css_rules An array of WP_Style_Engine_CSS_Rule objects from a store or otherwise. + * @param WP_Style_Engine_CSS_Rule[] $css_rules An array of WP_Style_Engine_CSS_Rule objects + * from a store or otherwise. * @param array $options { * Optional. An array of options. Default empty array. * - * @type string|null $context An identifier describing the origin of the style object, e.g., 'block-supports' or 'global-styles'. Default is 'block-supports'. + * @type string|null $context An identifier describing the origin of the style object, + * e.g. 'block-supports' or 'global-styles'. Default 'block-supports'. * When set, the style engine will attempt to store the CSS rules. - * @type bool $optimize Whether to optimize the CSS output, e.g., combine rules. Default is `false`. - * @type bool $prettify Whether to add new lines and indents to output. Default is the test of whether the global constant `SCRIPT_DEBUG` is defined. + * @type bool $optimize Whether to optimize the CSS output, e.g. combine rules. + * Default false. + * @type bool $prettify Whether to add new lines and indents to output. + * Defaults to whether the `SCRIPT_DEBUG` constant is defined. * } * @return string A compiled stylesheet from stored CSS rules. */ diff --git a/wp-includes/version.php b/wp-includes/version.php index 05eb5b160c..5a8e95c264 100644 --- a/wp-includes/version.php +++ b/wp-includes/version.php @@ -16,7 +16,7 @@ * * @global string $wp_version */ -$wp_version = '6.3-alpha-55818'; +$wp_version = '6.3-alpha-55819'; /** * Holds the WordPress DB revision, increments when changes are made to the WordPress DB schema.