Style Engine: Preserve important state declarations

Before, state styles appended `!important` directly to CSS values before Style Engine sanitization. For gradient values, this caused `safecss_filter_attr(`) to reject otherwise valid declarations, so responsive/state gradient CSS might not have been emitted

This commit stores `!important` as declaration metadata in the Style Engine, preserves it through rule generation and optimization, and appends it only after sanitization.

Props andrewserong, ramonopoly, wildworks.

Fixes #65561.



git-svn-id: https://develop.svn.wordpress.org/trunk@62720 602fd350-edb4-49c9-b593-d223f7449a82

Author: ramonjd

src/wp-includes/block-supports/states.php

@@ -122,12 +122,13 @@ function wp_get_state_declarations_with_background_resets( $declarations ) {
 
 	/*
 	 * When the state sets a solid background-color but no gradient of its own,
-	 * emit `background-image: unset !important` to clear any gradient (whether
-	 * stored as the `background` shorthand or as `background-image`) that was
-	 * applied to the default / normal state via an inline style attribute.
+	 * emit `background-image: unset` to clear any gradient (whether stored as
+	 * the `background` shorthand or as `background-image`) that was applied to
+	 * the default / normal state via an inline style attribute. The declaration
+	 * is marked important when the state rule is registered with the style engine.
 	 */
 	if ( $has_background_color && ! $has_background && ! $has_background_image ) {
-		$declarations['background-image'] = 'unset !important';
+		$declarations['background-image'] = 'unset';
 	}
 
 	return $declarations;
@@ -677,26 +678,49 @@ function wp_render_block_states_support( $block_content, $block ) {
 	 */
 	$style_rules = array();
 	foreach ( $css_rules as $rule ) {
-		$declarations = $rule['declarations'];
-		foreach ( $declarations as $property => $value ) {
-			$declarations[ $property ] = is_string( $value ) && str_contains( $value, '!important' )
-				? $value
-				: $value . ' !important';
+		$declarations                 = $rule['declarations'];
+		$important_declaration_values = wp_get_state_declarations_with_background_resets( $declarations );
+		$important_declarations       = new WP_Style_Engine_CSS_Declarations();
+		foreach ( $important_declaration_values as $property => $value ) {
+			$important_declarations->add_declaration(
+				$property,
+				$value,
+				array(
+					'important' => true,
+				)
+			);
+		}
+		$selector             = wp_build_state_selector(
+			".$unique_class",
+			$rule['selector'],
+			$rule['state']
+		);
+		$important_style_rule = array(
+			'selector'     => $selector,
+			'declarations' => $important_declarations,
+		);
+		if ( ! empty( $rule['rules_group'] ) ) {
+			$important_style_rule['rules_group'] = $rule['rules_group'];
 		}
-		$declarations = wp_get_state_declarations_with_fallback_border_styles( $declarations );
-		$declarations = wp_get_state_declarations_with_background_resets( $declarations );
-		$style_rule   = array(
-			'selector'     => wp_build_state_selector(
-				".$unique_class",
-				$rule['selector'],
-				$rule['state']
-			),
-			'declarations' => $declarations,
+		$style_rules[] = $important_style_rule;
+
+		$fallback_declarations = wp_get_state_declarations_with_fallback_border_styles( $declarations );
+		foreach ( array_keys( $declarations ) as $property ) {
+			unset( $fallback_declarations[ $property ] );
+		}
+
+		if ( empty( $fallback_declarations ) ) {
+			continue;
+		}
+
+		$fallback_style_rule = array(
+			'selector'     => $selector,
+			'declarations' => $fallback_declarations,
 		);
 		if ( ! empty( $rule['rules_group'] ) ) {
-			$style_rule['rules_group'] = $rule['rules_group'];
+			$fallback_style_rule['rules_group'] = $rule['rules_group'];
 		}
-		$style_rules[] = $style_rule;
+		$style_rules[] = $fallback_style_rule;
 	}
 
 	wp_style_engine_get_stylesheet_from_css_rules(

src/wp-includes/style-engine.php

@@ -114,16 +114,18 @@ function wp_style_engine_get_styles( $block_styles, $options = array() ) {
  *
  * @since 6.1.0
  * @since 6.6.0 Added support for `$rules_group` in the `$css_rules` array.
+ * @since 7.1.0 Extended `declarations` in `$css_rules` array to accept `WP_Style_Engine_CSS_Declarations` object.
  *
  * @param array $css_rules {
  *     Required. A collection of CSS rules.
  *
  *     @type array ...$0 {
- *         @type string   $rules_group  A parent CSS selector in the case of nested CSS,
- *                                      or a CSS nested @rule, such as `@media (min-width: 80rem)` or `@layer module`.
- *         @type string   $selector     A CSS selector.
- *         @type string[] $declarations An associative array of CSS definitions,
- *                                      e.g. `array( "$property" => "$value", "$property" => "$value" )`.
+ *         @type string                                    $rules_group  A parent CSS selector in the case of nested CSS,
+ *                                                                       or a CSS nested @rule, such as `@media (min-width: 80rem)` or `@layer module`.
+ *         @type string                                    $selector     A CSS selector.
+ *         @type string[]|WP_Style_Engine_CSS_Declarations $declarations An associative array of CSS definitions,
+ *                                                                       e.g. `array( "$property" => "$value", "$property" => "$value" )`,
+ *                                                                       or a WP_Style_Engine_CSS_Declarations object.
  *     }
  * }
  * @param array $options {
@@ -153,16 +155,21 @@ function wp_style_engine_get_stylesheet_from_css_rules( $css_rules, $options = a
 
 	$css_rule_objects = array();
 	foreach ( $css_rules as $css_rule ) {
-		if ( empty( $css_rule['selector'] ) || empty( $css_rule['declarations'] ) || ! is_array( $css_rule['declarations'] ) ) {
+		$declarations = $css_rule['declarations'] ?? null;
+		if (
+			empty( $css_rule['selector'] ) ||
+			empty( $declarations ) ||
+			( ! is_array( $declarations ) && ! $declarations instanceof WP_Style_Engine_CSS_Declarations )
+		) {
 			continue;
 		}
 
 		$rules_group = $css_rule['rules_group'] ?? null;
 		if ( ! empty( $options['context'] ) ) {
-			WP_Style_Engine::store_css_rule( $options['context'], $css_rule['selector'], $css_rule['declarations'], $rules_group );
+			WP_Style_Engine::store_css_rule( $options['context'], $css_rule['selector'], $declarations, $rules_group );
 		}
 
-		$css_rule_objects[] = new WP_Style_Engine_CSS_Rule( $css_rule['selector'], $css_rule['declarations'], $rules_group );
+		$css_rule_objects[] = new WP_Style_Engine_CSS_Rule( $css_rule['selector'], $declarations, $rules_group );
 	}
 
 	if ( empty( $css_rule_objects ) ) {

src/wp-includes/style-engine/class-wp-style-engine-css-declarations.php

@@ -26,6 +26,15 @@ class WP_Style_Engine_CSS_Declarations {
 	 */
 	protected $declarations = array();
 
+	/**
+	 * CSS declaration options keyed by property name.
+	 *
+	 * @since 7.1.0
+	 *
+	 * @var array
+	 */
+	protected $declaration_options = array();
+
 	/**
 	 * Constructor for this object.
 	 *
@@ -46,12 +55,18 @@ public function __construct( $declarations = array() ) {
 	 * Adds a single declaration.
 	 *
 	 * @since 6.1.0
+	 * @since 7.1.0 Added the `$options` parameter.
 	 *
 	 * @param string $property The CSS property.
 	 * @param string $value    The CSS value.
+	 * @param array  $options  {
+	 *     Optional. An array of options. Default empty array.
+	 *
+	 *     @type bool $important Whether to output the declaration with !important. Default false.
+	 * }
 	 * @return WP_Style_Engine_CSS_Declarations Returns the object to allow chaining methods.
 	 */
-	public function add_declaration( $property, $value ) {
+	public function add_declaration( $property, $value, $options = array() ) {
 		// Sanitizes the property.
 		$property = $this->sanitize_property( $property );
 		// Bails early if the property is empty.
@@ -70,8 +85,21 @@ public function add_declaration( $property, $value ) {
 			return $this;
 		}
 
+		$options = wp_parse_args(
+			$options,
+			array(
+				'important' => false,
+			)
+		);
+		$options = array_filter( $options );
+
 		// Adds the declaration property/value pair.
 		$this->declarations[ $property ] = $value;
+		if ( $options ) {
+			$this->declaration_options[ $property ] = $options;
+		} else {
+			unset( $this->declaration_options[ $property ] );
+		}
 
 		return $this;
 	}
@@ -86,6 +114,7 @@ public function add_declaration( $property, $value ) {
 	 */
 	public function remove_declaration( $property ) {
 		unset( $this->declarations[ $property ] );
+		unset( $this->declaration_options[ $property ] );
 		return $this;
 	}
 
@@ -130,21 +159,52 @@ public function get_declarations() {
 		return $this->declarations;
 	}
 
+	/**
+	 * Gets declaration options keyed by property name.
+	 *
+	 * @since 7.1.0
+	 *
+	 * @return array Declaration options keyed by property name.
+	 */
+	public function get_declaration_options() {
+		return $this->declaration_options;
+	}
+
 	/**
 	 * Filters a CSS property + value pair.
 	 *
 	 * @since 6.1.0
+	 * @since 7.1.0 Added the `$options` parameter.
 	 *
 	 * @param string $property The CSS property.
 	 * @param string $value    The value to be filtered.
 	 * @param string $spacer   Optional. The spacer between the colon and the value.
 	 *                         Default empty string.
+	 * @param array  $options  {
+	 *     Optional. An array of options. Default empty array.
+	 *
+	 *     @type bool $important Whether to output the declaration with !important. Default false.
+	 * }
 	 * @return string The filtered declaration or an empty string.
 	 */
-	protected static function filter_declaration( $property, $value, $spacer = '' ) {
+	protected static function filter_declaration( $property, $value, $spacer = '', $options = array() ) {
 		$filtered_value = wp_strip_all_tags( $value, true );
 		if ( '' !== $filtered_value ) {
-			return safecss_filter_attr( "{$property}:{$spacer}{$filtered_value}" );
+			$options = wp_parse_args(
+				$options,
+				array(
+					'important' => false,
+				)
+			);
+
+			$filtered_declaration = safecss_filter_attr( "{$property}:{$spacer}{$filtered_value}" );
+
+			// Only append !important in the presence of an option value and when sanitization returns a single declaration.
+			if ( true === $options['important'] && '' !== $filtered_declaration && ! str_contains( $filtered_declaration, ';' ) ) {
+				return "$filtered_declaration !important";
+			}
+
+			return $filtered_declaration;
 		}
 		return '';
 	}
@@ -169,7 +229,7 @@ public function get_declarations_string( $should_prettify = false, $indent_count
 		$spacer              = $should_prettify ? ' ' : '';
 
 		foreach ( $declarations_array as $property => $value ) {
-			$filtered_declaration = static::filter_declaration( $property, $value, $spacer );
+			$filtered_declaration = static::filter_declaration( $property, $value, $spacer, $this->declaration_options[ $property ] ?? array() );
 			if ( $filtered_declaration ) {
 				$declarations_output .= "{$indent}{$filtered_declaration};$suffix";
 			}

src/wp-includes/style-engine/class-wp-style-engine-css-rule.php

@@ -81,6 +81,7 @@ public function set_selector( $selector ) {
 	 * Sets the declarations.
 	 *
 	 * @since 6.1.0
+	 * @since 7.1.0 Preserves declaration options when declarations are provided as 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.
@@ -89,15 +90,23 @@ public function set_selector( $selector ) {
 	public function add_declarations( $declarations ) {
 		$is_declarations_object = ! is_array( $declarations );
 		$declarations_array     = $is_declarations_object ? $declarations->get_declarations() : $declarations;
+		$declaration_options    = $is_declarations_object ? $declarations->get_declaration_options() : array();
 
 		if ( null === $this->declarations ) {
 			if ( $is_declarations_object ) {
 				$this->declarations = $declarations;
 				return $this;
 			}
-			$this->declarations = new WP_Style_Engine_CSS_Declarations( $declarations_array );
+			$this->declarations = new WP_Style_Engine_CSS_Declarations();
+		}
+
+		foreach ( $declarations_array as $property => $value ) {
+			$this->declarations->add_declaration(
+				$property,
+				$value,
+				$declaration_options[ $property ] ?? array()
+			);
 		}
-		$this->declarations->add_declarations( $declarations_array );
 
 		return $this;
 	}

src/wp-includes/style-engine/class-wp-style-engine-processor.php

@@ -151,9 +151,23 @@ private function combine_rules_selectors() {
 		// Build an array of selectors along with the JSON-ified styles to make comparisons easier.
 		$selectors_json = array();
 		foreach ( $this->css_rules as $rule ) {
-			$declarations = $rule->get_declarations()->get_declarations();
+			$declarations        = $rule->get_declarations()->get_declarations();
+			$declaration_options = $rule->get_declarations()->get_declaration_options();
 			ksort( $declarations );
-			$selectors_json[ $rule->get_selector() ] = wp_json_encode( $declarations );
+			// Declaration options are keyed by property and are part of the rule identity.
+			ksort( $declaration_options );
+			foreach ( $declaration_options as $property => $options ) {
+				if ( is_array( $options ) ) {
+					ksort( $options );
+					$declaration_options[ $property ] = $options;
+				}
+			}
+			$selectors_json[ $rule->get_selector() ] = wp_json_encode(
+				array(
+					'declarations'        => $declarations,
+					'declaration_options' => $declaration_options,
+				)
+			);
 		}
 
 		// Combine selectors that have the same styles.

src/wp-includes/style-engine/class-wp-style-engine.php

@@ -425,15 +425,18 @@ protected static function is_valid_style_value( $style_value ) {
 	 *
 	 * @since 6.1.0
 	 * @since 6.6.0 Added the `$rules_group` parameter.
-	 *
-	 * @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 $rules_group        Optional. A parent CSS selector in the case of nested CSS, or a CSS nested @rule,
-	 *                                   such as `@media (min-width: 80rem)` or `@layer module`.
+	 * @since 7.1.0 Extended `$css_declarations` parameter to accept `WP_Style_Engine_CSS_Declarations` object.
+	 *
+	 * @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[]|WP_Style_Engine_CSS_Declarations $css_declarations An associative array of CSS definitions,
+	 *                                                                    e.g. `array( "$property" => "$value", "$property" => "$value" )`,
+	 *                                                                    or a WP_Style_Engine_CSS_Declarations object.
+	 * @param string                                    $rules_group      Optional. A parent CSS selector in the case of nested CSS,
+	 *                                                                    or a CSS nested @rule, such as `@media (min-width: 80rem)`
+	 *                                                                    or `@layer module`.
 	 */
 	public static function store_css_rule( $store_name, $css_selector, $css_declarations, $rules_group = '' ) {
 		if ( empty( $store_name ) || empty( $css_selector ) || empty( $css_declarations ) ) {