@wordpress/style-engine 1.34.0 → 1.35.0

package/CHANGELOG.md

@@ -2,6 +2,8 @@
 
 ## Unreleased
 
+## 1.35.0 (2024-02-21)
+
 ## 1.34.0 (2024-02-09)
 
 ## 1.33.0 (2024-01-24)

package/README.md

@@ -126,10 +126,31 @@ $styles = array(
         'selector'     => '.wp-tomato',
         'declarations' => array( 'padding' => '100px' )
     ),
+);
+
+$stylesheet = wp_style_engine_get_stylesheet_from_css_rules(
+    $styles,
     array(
-        'selector'     => '.wp-kumquat',
+        'context' => 'block-supports', // Indicates that these styles should be stored with block supports CSS.
+    )
+);
+print_r( $stylesheet ); // .wp-pumpkin{color:orange}.wp-tomato{color:red;padding:100px}
+```
+
+It's also possible to build simple, nested CSS rules using the `rules_group` key.
+
+```php
+$styles = array(
+    array(
+        'rules_group'  => '@media (min-width: 80rem)',
+        'selector'     => '.wp-carrot',
         'declarations' => array( 'color' => 'orange' )
     ),
+    array(
+        'rules_group'  => '@media (min-width: 80rem)',
+        'selector'     => '.wp-tomato',
+        'declarations' => array( 'color' => 'red' )
+    ),
 );
 
 $stylesheet = wp_style_engine_get_stylesheet_from_css_rules(
@@ -138,7 +159,7 @@ $stylesheet = wp_style_engine_get_stylesheet_from_css_rules(
         'context' => 'block-supports', // Indicates that these styles should be stored with block supports CSS.
     )
 );
-print_r( $stylesheet ); // .wp-pumpkin,.wp-kumquat{color:orange}.wp-tomato{color:red;padding:100px}
+print_r( $stylesheet ); // @media (min-width: 80rem){.wp-carrot{color:orange}}@media (min-width: 80rem){.wp-tomato{color:red;}}
 ```
 
 ### wp_style_engine_get_stylesheet_from_context()

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

@@ -33,12 +33,11 @@ if ( ! class_exists( 'WP_Style_Engine_CSS_Rule' ) ) {
 		protected $declarations;
 
 		/**
-		 * The CSS nested @rule, such as `@media (min-width: 80rem)` or `@layer module`.
+		 * A parent CSS selector in the case of nested CSS, or a CSS nested @rule, such as `@media (min-width: 80rem)` or `@layer module`..
 		 *
 		 * @var string
 		 */
-		protected $at_rule;
-
+		protected $rules_group;
 
 		/**
 		 * Constructor
@@ -46,13 +45,13 @@ if ( ! class_exists( 'WP_Style_Engine_CSS_Rule' ) ) {
 		 * @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" ),
 		 *                                                                or a WP_Style_Engine_CSS_Declarations object.
-		 * @param string                                    $at_rule      A CSS nested @rule, such as `@media (min-width: 80rem)` or `@layer module`.
+		 * @param 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`.
 		 *
 		 */
-		public function __construct( $selector = '', $declarations = array(), $at_rule = '' ) {
+		public function __construct( $selector = '', $declarations = array(), $rules_group = '' ) {
 			$this->set_selector( $selector );
 			$this->add_declarations( $declarations );
-			$this->set_at_rule( $at_rule );
+			$this->set_rules_group( $rules_group );
 		}
 
 		/**
@@ -92,17 +91,26 @@ if ( ! class_exists( 'WP_Style_Engine_CSS_Rule' ) ) {
 		}
 
 		/**
-		 * Sets the at_rule.
+		 * Sets the rules group.
 		 *
-		 * @param string $at_rule A CSS nested @rule, such as `@media (min-width: 80rem)` or `@layer module`.
+		 * @param 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`.
 		 *
 		 * @return WP_Style_Engine_CSS_Rule Returns the object to allow chaining of methods.
 		 */
-		public function set_at_rule( $at_rule ) {
-			$this->at_rule = $at_rule;
+		public function set_rules_group( $rules_group ) {
+			$this->rules_group = $rules_group;
 			return $this;
 		}
 
+		/**
+		 * Gets the rules group.
+		 *
+		 * @return string
+		 */
+		public function get_rules_group() {
+			return $this->rules_group;
+		}
+
 		/**
 		 * Gets the declarations object.
 		 *
@@ -121,15 +129,6 @@ if ( ! class_exists( 'WP_Style_Engine_CSS_Rule' ) ) {
 			return $this->selector;
 		}
 
-		/**
-		 * Gets the at_rule.
-		 *
-		 * @return string
-		 */
-		public function get_at_rule() {
-			return $this->at_rule;
-		}
-
 		/**
 		 * Gets the CSS.
 		 *
@@ -148,16 +147,16 @@ if ( ! class_exists( 'WP_Style_Engine_CSS_Rule' ) ) {
 			// Trims any multiple selectors strings.
 			$selector         = $should_prettify ? implode( ',', array_map( 'trim', explode( ',', $this->get_selector() ) ) ) : $this->get_selector();
 			$selector         = $should_prettify ? str_replace( array( ',' ), ",\n", $selector ) : $selector;
-			$at_rule          = $this->get_at_rule();
-			$has_at_rule      = ! empty( $at_rule );
-			$css_declarations = $this->declarations->get_declarations_string( $should_prettify, $has_at_rule ? $nested_declarations_indent : $declarations_indent );
+			$rules_group      = $this->get_rules_group();
+			$has_rules_group  = ! empty( $rules_group );
+			$css_declarations = $this->declarations->get_declarations_string( $should_prettify, $has_rules_group ? $nested_declarations_indent : $declarations_indent );
 
 			if ( empty( $css_declarations ) ) {
 				return '';
 			}
 
-			if ( $has_at_rule ) {
-				$selector = "{$rule_indent}{$at_rule}{$spacer}{{$suffix}{$nested_rule_indent}{$selector}{$spacer}{{$suffix}{$css_declarations}{$suffix}{$nested_rule_indent}}{$suffix}{$rule_indent}}";
+			if ( $has_rules_group ) {
+				$selector = "{$rule_indent}{$rules_group}{$spacer}{{$suffix}{$nested_rule_indent}{$selector}{$spacer}{{$suffix}{$css_declarations}{$suffix}{$nested_rule_indent}}{$suffix}{$rule_indent}}";
 				return $selector;
 			}
 

package/class-wp-style-engine-css-rules-store.php

@@ -109,25 +109,25 @@ if ( ! class_exists( 'WP_Style_Engine_CSS_Rules_Store' ) ) {
 		 * Gets a WP_Style_Engine_CSS_Rule object by its selector.
 		 * If the rule does not exist, it will be created.
 		 *
-		 * @param string $selector The CSS selector.
-		 * @param string $at_rule  The CSS nested @rule, such as `@media (min-width: 80rem)` or `@layer module`.
+		 * @param string $selector    The CSS selector.
+		 * @param 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`..
 		 *
 		 * @return WP_Style_Engine_CSS_Rule|void Returns a WP_Style_Engine_CSS_Rule object, or null if the selector is empty.
 		 */
-		public function add_rule( $selector, $at_rule = '' ) {
-			$selector = trim( $selector );
-			$at_rule  = trim( $at_rule );
+		public function add_rule( $selector, $rules_group = '' ) {
+			$selector    = $selector ? trim( $selector ) : '';
+			$rules_group = $rules_group ? trim( $rules_group ) : '';
 
 			// Bail early if there is no selector.
 			if ( empty( $selector ) ) {
 				return;
 			}
 
-			if ( ! empty( $at_rule ) ) {
-				if ( empty( $this->rules[ "$at_rule $selector" ] ) ) {
-					$this->rules[ "$at_rule $selector" ] = new WP_Style_Engine_CSS_Rule( $selector, array(), $at_rule );
+			if ( ! empty( $rules_group ) ) {
+				if ( empty( $this->rules[ "$rules_group $selector" ] ) ) {
+					$this->rules[ "$rules_group $selector" ] = new WP_Style_Engine_CSS_Rule( $selector, array(), $rules_group );
 				}
-				return $this->rules[ "$at_rule $selector" ];
+				return $this->rules[ "$rules_group $selector" ];
 			}
 
 			// Create the rule if it doesn't exist.

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

@@ -65,20 +65,20 @@ if ( ! class_exists( 'WP_Style_Engine_Processor' ) ) {
 			}
 
 			foreach ( $css_rules as $rule ) {
-				$selector = $rule->get_selector();
-				$at_rule  = $rule->get_at_rule();
+				$selector    = $rule->get_selector();
+				$rules_group = $rule->get_rules_group();
 
 				/**
 				 * If there is an at_rule and it already exists in the css_rules array,
 				 * add the rule to it.
 				 * Otherwise, create a new entry for the at_rule
 				 */
-				if ( ! empty( $at_rule ) ) {
-					if ( isset( $this->css_rules[ "$at_rule $selector" ] ) ) {
-						$this->css_rules[ "$at_rule $selector" ]->add_declarations( $rule->get_declarations() );
+				if ( ! empty( $rules_group ) ) {
+					if ( isset( $this->css_rules[ "$rules_group $selector" ] ) ) {
+						$this->css_rules[ "$rules_group $selector" ]->add_declarations( $rule->get_declarations() );
 						continue;
 					}
-					$this->css_rules[ "$at_rule $selector" ] = $rule;
+					$this->css_rules[ "$rules_group $selector" ] = $rule;
 					continue;
 				}
 

package/class-wp-style-engine.php

@@ -355,14 +355,15 @@ 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`.
 		 *
 		 * @return void.
 		 */
-		public static function store_css_rule( $store_name, $css_selector, $css_declarations, $css_at_rule = '' ) {
+		public static function store_css_rule( $store_name, $css_selector, $css_declarations, $rules_group = '' ) {
 			if ( empty( $store_name ) || empty( $css_selector ) || empty( $css_declarations ) ) {
 				return;
 			}
-			static::get_store( $store_name )->add_rule( $css_selector, $css_at_rule )->add_declarations( $css_declarations );
+			static::get_store( $store_name )->add_rule( $css_selector, $rules_group )->add_declarations( $css_declarations );
 		}
 
 		/**

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@wordpress/style-engine",
-	"version": "1.34.0",
+	"version": "1.35.0",
 	"description": "A suite of parsers and compilers for WordPress styles.",
 	"author": "The WordPress Contributors",
 	"license": "GPL-2.0-or-later",
@@ -35,5 +35,5 @@
 	"publishConfig": {
 		"access": "public"
 	},
-	"gitHead": "eb796371e9630636a4a8837033807b0c4a06ed67"
+	"gitHead": "c139588f4c668b38bafbc5431f2f4e3903dbe683"
 }

package/style-engine.php

@@ -83,7 +83,7 @@ function wp_style_engine_get_styles( $block_styles, $options = array() ) {
  *     Required. A collection of CSS rules.
  *
  *     @type array ...$0 {
- *         @type string   $at_rule      A CSS nested @rule, such as `@media (min-width: 80rem)` or `@layer module`.
+ *         @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" ).
  *     }
@@ -117,13 +117,12 @@ function wp_style_engine_get_stylesheet_from_css_rules( $css_rules, $options = a
 			continue;
 		}
 
-		$at_rule = ! empty( $css_rule['at_rule'] ) ? $css_rule['at_rule'] : '';
-
+		$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'], $at_rule );
+			WP_Style_Engine::store_css_rule( $options['context'], $css_rule['selector'], $css_rule['declarations'], $rules_group );
 		}
 
-		$css_rule_objects[] = new WP_Style_Engine_CSS_Rule( $css_rule['selector'], $css_rule['declarations'], $at_rule );
+		$css_rule_objects[] = new WP_Style_Engine_CSS_Rule( $css_rule['selector'], $css_rule['declarations'], $rules_group );
 	}
 
 	if ( empty( $css_rule_objects ) ) {