@wordpress/style-engine 2.50.0 → 2.51.0

package/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 ## Unreleased
 
+## 2.51.0 (2026-07-14)
+
+### Enhancements
+
+-   Widen React peer dependency ranges to `^18 || ^19` to support both React 18 and React 19 environments ([#80024](https://github.com/WordPress/gutenberg/pull/80024)).
+
 ## 2.50.0 (2026-07-01)
 
 ## 2.49.0 (2026-06-24)

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@wordpress/style-engine",
-	"version": "2.50.0",
+	"version": "2.51.0",
 	"description": "A suite of parsers and compilers for WordPress styles.",
 	"author": "The WordPress Contributors",
 	"license": "GPL-2.0-or-later",
@@ -67,7 +67,7 @@
 		"change-case": "^4.1.2"
 	},
 	"peerDependencies": {
-		"@types/react": "^18.3.27"
+		"@types/react": "^18 || ^19"
 	},
 	"peerDependenciesMeta": {
 		"@types/react": {
@@ -77,5 +77,5 @@
 	"publishConfig": {
 		"access": "public"
 	},
-	"gitHead": "fee6e24e8e63d36f6bbcf487c193461e9bd79753"
+	"gitHead": "e9a74f9c14095a34398ecd4d1f7a908e55051205"
 }

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

@@ -22,6 +22,13 @@ if ( ! class_exists( 'WP_Style_Engine_CSS_Declarations' ) ) {
 		 */
 		protected $declarations = array();
 
+		/**
+		 * CSS declaration options keyed by property name.
+		 *
+		 * @var array
+		 */
+		protected $declaration_options = array();
+
 		/**
 		 * Constructor for this object.
 		 *
@@ -39,10 +46,15 @@ if ( ! class_exists( 'WP_Style_Engine_CSS_Declarations' ) ) {
 		 *
 		 * @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.
@@ -59,8 +71,22 @@ if ( ! class_exists( 'WP_Style_Engine_CSS_Declarations' ) ) {
 				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;
 		}
@@ -74,6 +100,7 @@ if ( ! class_exists( 'WP_Style_Engine_CSS_Declarations' ) ) {
 		 */
 		public function remove_declaration( $property ) {
 			unset( $this->declarations[ $property ] );
+			unset( $this->declaration_options[ $property ] );
 			return $this;
 		}
 
@@ -114,20 +141,48 @@ if ( ! class_exists( 'WP_Style_Engine_CSS_Declarations' ) ) {
 			return $this->declarations;
 		}
 
+		/**
+		 * Gets declaration options keyed by property name.
+		 *
+		 * @return array
+		 */
+		public function get_declaration_options() {
+			return $this->declaration_options;
+		}
+
 		/**
 		 * Filters a CSS property + value pair.
 		 *
 		 * @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 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 '';
 		}
@@ -149,7 +204,12 @@ if ( ! class_exists( 'WP_Style_Engine_CSS_Declarations' ) ) {
 			$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";
 				}

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

@@ -77,15 +77,23 @@ if ( ! class_exists( 'WP_Style_Engine_CSS_Rule' ) ) {
 		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;
 		}

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

@@ -142,9 +142,23 @@ if ( ! class_exists( 'WP_Style_Engine_Processor' ) ) {
 			// 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.

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

@@ -417,8 +417,9 @@ if ( ! class_exists( 'WP_Style_Engine' ) ) {
 		 *
 		 * @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`.
+		 * @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`.
 		 *
 		 * @return void.
 		 */

package/src/style-engine.php

@@ -85,7 +85,8 @@ function wp_style_engine_get_styles( $block_styles, $options = array() ) {
  *     @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[]|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 {
@@ -113,16 +114,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 ) ) {