@wordpress/style-engine 1.33.1 → 1.34.0

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

@@ -7,163 +7,162 @@
  * @package Gutenberg
  */
 
-if ( class_exists( 'WP_Style_Engine_CSS_Declarations' ) ) {
-	return;
-}
+if ( ! class_exists( 'WP_Style_Engine_CSS_Declarations' ) ) {
 
-/**
- * Holds, sanitizes, processes and prints CSS declarations for the Style Engine.
- *
- * @access private
- */
-class WP_Style_Engine_CSS_Declarations {
 	/**
-	 * An array of CSS declarations (property => value pairs).
+	 * Holds, sanitizes, processes and prints CSS declarations for the Style Engine.
 	 *
-	 * @var array
+	 * @access private
 	 */
-	protected $declarations = array();
+	class WP_Style_Engine_CSS_Declarations {
+		/**
+		 * An array of CSS declarations (property => value pairs).
+		 *
+		 * @var array
+		 */
+		protected $declarations = array();
+
+		/**
+		 * 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().
+		 *
+		 * @param string[] $declarations An associative array of CSS definitions, e.g., array( "$property" => "$value", "$property" => "$value" ).
+		 */
+		public function __construct( $declarations = array() ) {
+			$this->add_declarations( $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().
-	 *
-	 * @param string[] $declarations An associative array of CSS definitions, e.g., array( "$property" => "$value", "$property" => "$value" ).
-	 */
-	public function __construct( $declarations = array() ) {
-		$this->add_declarations( $declarations );
-	}
+		/**
+		 * Adds a single declaration.
+		 *
+		 * @param string $property The CSS property.
+		 * @param string $value    The CSS value.
+		 *
+		 * @return WP_Style_Engine_CSS_Declarations Returns the object to allow chaining methods.
+		 */
+		public function add_declaration( $property, $value ) {
+			// Sanitizes the property.
+			$property = $this->sanitize_property( $property );
+			// Bails early if the property is empty.
+			if ( empty( $property ) ) {
+				return $this;
+			}
+
+			// Trims the value. If empty, bail early.
+			$value = trim( $value );
+			if ( '' === $value ) {
+				return $this;
+			}
+
+			// Adds the declaration property/value pair.
+			$this->declarations[ $property ] = $value;
 
-	/**
-	 * Adds a single declaration.
-	 *
-	 * @param string $property The CSS property.
-	 * @param string $value    The CSS value.
-	 *
-	 * @return WP_Style_Engine_CSS_Declarations Returns the object to allow chaining methods.
-	 */
-	public function add_declaration( $property, $value ) {
-		// Sanitizes the property.
-		$property = $this->sanitize_property( $property );
-		// Bails early if the property is empty.
-		if ( empty( $property ) ) {
 			return $this;
 		}
 
-		// Trims the value. If empty, bail early.
-		$value = trim( $value );
-		if ( '' === $value ) {
+		/**
+		 * Removes a single declaration.
+		 *
+		 * @param string $property The CSS property.
+		 *
+		 * @return WP_Style_Engine_CSS_Declarations Returns the object to allow chaining methods.
+		 */
+		public function remove_declaration( $property ) {
+			unset( $this->declarations[ $property ] );
 			return $this;
 		}
 
-		// Adds the declaration property/value pair.
-		$this->declarations[ $property ] = $value;
-
-		return $this;
-	}
-
-	/**
-	 * Removes a single declaration.
-	 *
-	 * @param string $property The CSS property.
-	 *
-	 * @return WP_Style_Engine_CSS_Declarations Returns the object to allow chaining methods.
-	 */
-	public function remove_declaration( $property ) {
-		unset( $this->declarations[ $property ] );
-		return $this;
-	}
-
-	/**
-	 * Adds multiple declarations.
-	 *
-	 * @param array $declarations An array of declarations.
-	 *
-	 * @return WP_Style_Engine_CSS_Declarations Returns the object to allow chaining methods.
-	 */
-	public function add_declarations( $declarations ) {
-		foreach ( $declarations as $property => $value ) {
-			$this->add_declaration( $property, $value );
+		/**
+		 * Adds multiple declarations.
+		 *
+		 * @param array $declarations An array of declarations.
+		 *
+		 * @return WP_Style_Engine_CSS_Declarations Returns the object to allow chaining methods.
+		 */
+		public function add_declarations( $declarations ) {
+			foreach ( $declarations as $property => $value ) {
+				$this->add_declaration( $property, $value );
+			}
+			return $this;
 		}
-		return $this;
-	}
 
-	/**
-	 * Removes multiple declarations.
-	 *
-	 * @param array $properties An array of properties.
-	 *
-	 * @return WP_Style_Engine_CSS_Declarations Returns the object to allow chaining methods.
-	 */
-	public function remove_declarations( $properties = array() ) {
-		foreach ( $properties as $property ) {
-			$this->remove_declaration( $property );
+		/**
+		 * Removes multiple declarations.
+		 *
+		 * @param array $properties An array of properties.
+		 *
+		 * @return WP_Style_Engine_CSS_Declarations Returns the object to allow chaining methods.
+		 */
+		public function remove_declarations( $properties = array() ) {
+			foreach ( $properties as $property ) {
+				$this->remove_declaration( $property );
+			}
+			return $this;
 		}
-		return $this;
-	}
-
-	/**
-	 * Gets the declarations array.
-	 *
-	 * @return array
-	 */
-	public function get_declarations() {
-		return $this->declarations;
-	}
 
-	/**
-	 * 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.
-	 *
-	 * @return string The filtered declaration or an empty string.
-	 */
-	protected static function filter_declaration( $property, $value, $spacer = '' ) {
-		$filtered_value = wp_strip_all_tags( $value, true );
+		/**
+		 * Gets the declarations array.
+		 *
+		 * @return array
+		 */
+		public function get_declarations() {
+			return $this->declarations;
+		}
 
-		if ( '' !== $filtered_value ) {
-			return safecss_filter_attr( "{$property}:{$spacer}{$filtered_value}" );
+		/**
+		 * 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.
+		 *
+		 * @return string The filtered declaration or an empty string.
+		 */
+		protected static function filter_declaration( $property, $value, $spacer = '' ) {
+			$filtered_value = wp_strip_all_tags( $value, true );
+
+			if ( '' !== $filtered_value ) {
+				return safecss_filter_attr( "{$property}:{$spacer}{$filtered_value}" );
+			}
+			return '';
 		}
-		return '';
-	}
 
-	/**
-	 * Filters and compiles the CSS declarations.
-	 *
-	 * @param bool   $should_prettify Whether to add spacing, new lines and indents.
-	 * @param number $indent_count    The number of tab indents to apply to the rule. Applies if `prettify` is `true`.
-	 *
-	 * @return string The CSS declarations.
-	 */
-	public function get_declarations_string( $should_prettify = false, $indent_count = 0 ) {
-		$declarations_array  = $this->get_declarations();
-		$declarations_output = '';
-		$indent              = $should_prettify ? str_repeat( "\t", $indent_count ) : '';
-		$suffix              = $should_prettify ? ' ' : '';
-		$suffix              = $should_prettify && $indent_count > 0 ? "\n" : $suffix;
-		$spacer              = $should_prettify ? ' ' : '';
-
-		foreach ( $declarations_array as $property => $value ) {
-			$filtered_declaration = static::filter_declaration( $property, $value, $spacer );
-			if ( $filtered_declaration ) {
-				$declarations_output .= "{$indent}{$filtered_declaration};$suffix";
+		/**
+		 * Filters and compiles the CSS declarations.
+		 *
+		 * @param bool   $should_prettify Whether to add spacing, new lines and indents.
+		 * @param number $indent_count    The number of tab indents to apply to the rule. Applies if `prettify` is `true`.
+		 *
+		 * @return string The CSS declarations.
+		 */
+		public function get_declarations_string( $should_prettify = false, $indent_count = 0 ) {
+			$declarations_array  = $this->get_declarations();
+			$declarations_output = '';
+			$indent              = $should_prettify ? str_repeat( "\t", $indent_count ) : '';
+			$suffix              = $should_prettify ? ' ' : '';
+			$suffix              = $should_prettify && $indent_count > 0 ? "\n" : $suffix;
+			$spacer              = $should_prettify ? ' ' : '';
+
+			foreach ( $declarations_array as $property => $value ) {
+				$filtered_declaration = static::filter_declaration( $property, $value, $spacer );
+				if ( $filtered_declaration ) {
+					$declarations_output .= "{$indent}{$filtered_declaration};$suffix";
+				}
 			}
+			return rtrim( $declarations_output );
 		}
-		return rtrim( $declarations_output );
-	}
 
-	/**
-	 * Sanitizes property names.
-	 *
-	 * @param string $property The CSS property.
-	 *
-	 * @return string The sanitized property name.
-	 */
-	protected function sanitize_property( $property ) {
-		return sanitize_key( $property );
+		/**
+		 * Sanitizes property names.
+		 *
+		 * @param string $property The CSS property.
+		 *
+		 * @return string The sanitized property name.
+		 */
+		protected function sanitize_property( $property ) {
+			return sanitize_key( $property );
+		}
 	}
 }

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

@@ -7,121 +7,161 @@
  * @package Gutenberg
  */
 
-if ( class_exists( 'WP_Style_Engine_CSS_Rule' ) ) {
-	return;
-}
-
-/**
- * Holds, sanitizes, processes and prints CSS declarations for the Style Engine.
- *
- * @access private
- */
-class WP_Style_Engine_CSS_Rule {
+if ( ! class_exists( 'WP_Style_Engine_CSS_Rule' ) ) {
 
 	/**
-	 * The selector.
+	 * Holds, sanitizes, processes and prints CSS declarations for the Style Engine.
 	 *
-	 * @var string
+	 * @access private
 	 */
-	protected $selector;
+	class WP_Style_Engine_CSS_Rule {
 
-	/**
-	 * The selector declarations.
-	 *
-	 * Contains a WP_Style_Engine_CSS_Declarations object.
-	 *
-	 * @var WP_Style_Engine_CSS_Declarations
-	 */
-	protected $declarations;
+		/**
+		 * The selector.
+		 *
+		 * @var string
+		 */
+		protected $selector;
 
-	/**
-	 * Constructor
-	 *
-	 * @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.
-	 */
-	public function __construct( $selector = '', $declarations = array() ) {
-		$this->set_selector( $selector );
-		$this->add_declarations( $declarations );
-	}
+		/**
+		 * The selector declarations.
+		 *
+		 * Contains a WP_Style_Engine_CSS_Declarations object.
+		 *
+		 * @var WP_Style_Engine_CSS_Declarations
+		 */
+		protected $declarations;
 
-	/**
-	 * Sets the selector.
-	 *
-	 * @param string $selector The CSS selector.
-	 *
-	 * @return WP_Style_Engine_CSS_Rule Returns the object to allow chaining of methods.
-	 */
-	public function set_selector( $selector ) {
-		$this->selector = $selector;
-		return $this;
-	}
+		/**
+		 * The CSS nested @rule, such as `@media (min-width: 80rem)` or `@layer module`.
+		 *
+		 * @var string
+		 */
+		protected $at_rule;
 
-	/**
-	 * Sets the declarations.
-	 *
-	 * @param array|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 ) {
-		$is_declarations_object = ! is_array( $declarations );
-		$declarations_array     = $is_declarations_object ? $declarations->get_declarations() : $declarations;
-
-		if ( null === $this->declarations ) {
-			if ( $is_declarations_object ) {
-				$this->declarations = $declarations;
-				return $this;
+
+		/**
+		 * Constructor
+		 *
+		 * @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`.
+		 *
+		 */
+		public function __construct( $selector = '', $declarations = array(), $at_rule = '' ) {
+			$this->set_selector( $selector );
+			$this->add_declarations( $declarations );
+			$this->set_at_rule( $at_rule );
+		}
+
+		/**
+		 * Sets the selector.
+		 *
+		 * @param string $selector The CSS selector.
+		 *
+		 * @return WP_Style_Engine_CSS_Rule Returns the object to allow chaining of methods.
+		 */
+		public function set_selector( $selector ) {
+			$this->selector = $selector;
+			return $this;
+		}
+
+		/**
+		 * Sets the declarations.
+		 *
+		 * @param array|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 ) {
+			$is_declarations_object = ! is_array( $declarations );
+			$declarations_array     = $is_declarations_object ? $declarations->get_declarations() : $declarations;
+
+			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( $declarations_array );
+			$this->declarations->add_declarations( $declarations_array );
+
+			return $this;
 		}
-		$this->declarations->add_declarations( $declarations_array );
 
-		return $this;
-	}
+		/**
+		 * Sets the at_rule.
+		 *
+		 * @param string $at_rule 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;
+			return $this;
+		}
 
-	/**
-	 * Gets the declarations object.
-	 *
-	 * @return WP_Style_Engine_CSS_Declarations The declarations object.
-	 */
-	public function get_declarations() {
-		return $this->declarations;
-	}
+		/**
+		 * Gets the declarations object.
+		 *
+		 * @return WP_Style_Engine_CSS_Declarations The declarations object.
+		 */
+		public function get_declarations() {
+			return $this->declarations;
+		}
 
-	/**
-	 * Gets the full selector.
-	 *
-	 * @return string
-	 */
-	public function get_selector() {
-		return $this->selector;
-	}
+		/**
+		 * Gets the full selector.
+		 *
+		 * @return string
+		 */
+		public function get_selector() {
+			return $this->selector;
+		}
 
-	/**
-	 * Gets the CSS.
-	 *
-	 * @param bool   $should_prettify Whether to add spacing, new lines and indents.
-	 * @param number $indent_count    The number of tab indents to apply to the rule. Applies if `prettify` is `true`.
-	 *
-	 * @return string
-	 */
-	public function get_css( $should_prettify = false, $indent_count = 0 ) {
-		$rule_indent         = $should_prettify ? str_repeat( "\t", $indent_count ) : '';
-		$declarations_indent = $should_prettify ? $indent_count + 1 : 0;
-		$suffix              = $should_prettify ? "\n" : '';
-		$spacer              = $should_prettify ? ' ' : '';
-		// 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;
-		$css_declarations = $this->declarations->get_declarations_string( $should_prettify, $declarations_indent );
-
-		if ( empty( $css_declarations ) ) {
-			return '';
+		/**
+		 * Gets the at_rule.
+		 *
+		 * @return string
+		 */
+		public function get_at_rule() {
+			return $this->at_rule;
 		}
 
-		return "{$rule_indent}{$selector}{$spacer}{{$suffix}{$css_declarations}{$suffix}{$rule_indent}}";
+		/**
+		 * Gets the CSS.
+		 *
+		 * @param bool   $should_prettify Whether to add spacing, new lines and indents.
+		 * @param number $indent_count    The number of tab indents to apply to the rule. Applies if `prettify` is `true`.
+		 *
+		 * @return string
+		 */
+		public function get_css( $should_prettify = false, $indent_count = 0 ) {
+			$rule_indent                = $should_prettify ? str_repeat( "\t", $indent_count ) : '';
+			$nested_rule_indent         = $should_prettify ? str_repeat( "\t", $indent_count + 1 ) : '';
+			$declarations_indent        = $should_prettify ? $indent_count + 1 : 0;
+			$nested_declarations_indent = $should_prettify ? $indent_count + 2 : 0;
+			$suffix                     = $should_prettify ? "\n" : '';
+			$spacer                     = $should_prettify ? ' ' : '';
+			// 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 );
+
+			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}}";
+				return $selector;
+			}
+
+			return "{$rule_indent}{$selector}{$spacer}{{$suffix}{$css_declarations}{$suffix}{$rule_indent}}";
+		}
 	}
 }