Block Supports: Add background gradient support that can combine with background image

Adds `background.gradient` as a new block support, enabling blocks to combine a background gradient with a background image via comma-separated `background-image` CSS values (e.g., `background-image: linear-gradient(...), url(...)`).

Before, the only way to apply a gradient is through `color.gradient`, which renders as a `background` CSS shorthand and conflicts with background image  
properties. By introducing `background.gradient` (stored at `style.background.gradient`), gradients become part of the background style group, allowing the style engine to combine gradient and image values without conflict.

Props aaronrobertshaw, ramonopoly, wildworks.

Fixes #64974.



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

Author: ramonjd

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

@@ -43,6 +43,7 @@ function wp_register_background_support( $block_type ) {
  * @since 6.5.0 Added support for `backgroundPosition` and `backgroundRepeat` output.
  * @since 6.6.0 Removed requirement for `backgroundImage.source`. A file/url is the default.
  * @since 6.7.0 Added support for `backgroundAttachment` output.
+ * @since 7.1.0 Added support for `background.gradient` output.
  *
  * @access private
  *
@@ -51,34 +52,49 @@ function wp_register_background_support( $block_type ) {
  * @return string Filtered block content.
  */
 function wp_render_background_support( $block_content, $block ) {
-	$block_type                   = WP_Block_Type_Registry::get_instance()->get_registered( $block['blockName'] );
-	$block_attributes             = ( isset( $block['attrs'] ) && is_array( $block['attrs'] ) ) ? $block['attrs'] : array();
-	$has_background_image_support = block_has_support( $block_type, array( 'background', 'backgroundImage' ), false );
+	$block_type                      = WP_Block_Type_Registry::get_instance()->get_registered( $block['blockName'] );
+	$block_attributes                = ( isset( $block['attrs'] ) && is_array( $block['attrs'] ) ) ? $block['attrs'] : array();
+	$has_background_image_support    = block_has_support( $block_type, array( 'background', 'backgroundImage' ), false );
+	$has_background_gradient_support = block_has_support( $block_type, array( 'background', 'gradient' ), false );
 
 	if (
-		! $has_background_image_support ||
-		wp_should_skip_block_supports_serialization( $block_type, 'background', 'backgroundImage' ) ||
+		( ! $has_background_image_support && ! $has_background_gradient_support ) ||
 		! isset( $block_attributes['style']['background'] )
 	) {
 		return $block_content;
 	}
 
-	$background_styles                         = array();
-	$background_styles['backgroundImage']      = $block_attributes['style']['background']['backgroundImage'] ?? null;
-	$background_styles['backgroundSize']       = $block_attributes['style']['background']['backgroundSize'] ?? null;
-	$background_styles['backgroundPosition']   = $block_attributes['style']['background']['backgroundPosition'] ?? null;
-	$background_styles['backgroundRepeat']     = $block_attributes['style']['background']['backgroundRepeat'] ?? null;
-	$background_styles['backgroundAttachment'] = $block_attributes['style']['background']['backgroundAttachment'] ?? null;
+	// Check serialization skip for each feature individually.
+	$skip_background_image    = ! $has_background_image_support || wp_should_skip_block_supports_serialization( $block_type, 'background', 'backgroundImage' );
+	$skip_background_gradient = ! $has_background_gradient_support || wp_should_skip_block_supports_serialization( $block_type, 'background', 'gradient' );
 
-	if ( ! empty( $background_styles['backgroundImage'] ) ) {
-		$background_styles['backgroundSize'] = $background_styles['backgroundSize'] ?? 'cover';
+	if ( $skip_background_image && $skip_background_gradient ) {
+		return $block_content;
+	}
+
+	$background_styles = array();
+
+	if ( ! $skip_background_image ) {
+		$background_styles['backgroundImage']      = $block_attributes['style']['background']['backgroundImage'] ?? null;
+		$background_styles['backgroundSize']       = $block_attributes['style']['background']['backgroundSize'] ?? null;
+		$background_styles['backgroundPosition']   = $block_attributes['style']['background']['backgroundPosition'] ?? null;
+		$background_styles['backgroundRepeat']     = $block_attributes['style']['background']['backgroundRepeat'] ?? null;
+		$background_styles['backgroundAttachment'] = $block_attributes['style']['background']['backgroundAttachment'] ?? null;
 
-		// If the background size is set to `contain` and no position is set, set the position to `center`.
-		if ( 'contain' === $background_styles['backgroundSize'] && ! $background_styles['backgroundPosition'] ) {
-			$background_styles['backgroundPosition'] = '50% 50%';
+		if ( ! empty( $background_styles['backgroundImage'] ) ) {
+			$background_styles['backgroundSize'] = $background_styles['backgroundSize'] ?? 'cover';
+
+			// If the background size is set to `contain` and no position is set, set the position to `center`.
+			if ( 'contain' === $background_styles['backgroundSize'] && ! $background_styles['backgroundPosition'] ) {
+				$background_styles['backgroundPosition'] = '50% 50%';
+			}
 		}
 	}
 
+	if ( ! $skip_background_gradient ) {
+		$background_styles['gradient'] = $block_attributes['style']['background']['gradient'] ?? null;
+	}
+
 	$styles = wp_style_engine_get_styles( array( 'background' => $background_styles ) );
 
 	if ( ! empty( $styles['css'] ) ) {

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

@@ -73,6 +73,7 @@ function wp_register_colors_support( $block_type ) {
  *
  * @since 5.6.0
  * @since 6.1.0 Implemented the style engine to generate CSS and classnames.
+ * @since 7.1.0 Suppresses color.gradient when background.gradient is supported and set.
  * @access private
  *
  * @param  WP_Block_Type $block_type       Block type.
@@ -114,7 +115,17 @@ function wp_apply_colors_support( $block_type, $block_attributes ) {
 	}
 
 	// Gradients.
-	if ( $has_gradients_support && ! wp_should_skip_block_supports_serialization( $block_type, 'color', 'gradients' ) ) {
+	// Suppress color.gradient CSS when background.gradient is supported and
+	// explicitly set. background.php owns CSS generation in that case, and
+	// emitting the background shorthand here would conflict with it.
+	$has_background_gradient_support = block_has_support( $block_type, array( 'background', 'gradient' ), false );
+	$has_background_gradient_value   = ! empty( $block_attributes['style']['background']['gradient'] );
+
+	if (
+		$has_gradients_support &&
+		! wp_should_skip_block_supports_serialization( $block_type, 'color', 'gradients' ) &&
+		! ( $has_background_gradient_support && $has_background_gradient_value )
+	) {
 		$preset_gradient_color          = array_key_exists( 'gradient', $block_attributes ) ? "var:preset|gradient|{$block_attributes['gradient']}" : null;
 		$custom_gradient_color          = $block_attributes['style']['color']['gradient'] ?? null;
 		$color_block_styles['gradient'] = $preset_gradient_color ? $preset_gradient_color : $custom_gradient_color;

src/wp-includes/class-wp-theme-json.php

@@ -330,6 +330,7 @@ class WP_Theme_JSON {
 	 *
 	 * @since 6.2.0
 	 * @since 6.6.0 Added background-image properties.
+	 * @since 7.1.0 Added `background.gradient` to `background-image` paths.
 	 * @var array
 	 */
 	const INDIRECT_PROPERTIES_METADATA = array(
@@ -348,6 +349,7 @@ class WP_Theme_JSON {
 		),
 		'background-image' => array(
 			array( 'background', 'backgroundImage', 'url' ),
+			array( 'background', 'gradient' ),
 		),
 	);
 
@@ -413,6 +415,7 @@ class WP_Theme_JSON {
 	 *              Added support for `dimensions.width` and `dimensions.height`.
 	 *              Added support for `typography.textIndent`.
 	 * @since 7.1.0 Added `viewport` property.
+	 *              Added support for `background.gradient`.
 	 * @var array
 	 */
 	const VALID_SETTINGS = array(
@@ -421,6 +424,7 @@ class WP_Theme_JSON {
 		'background'                    => array(
 			'backgroundImage' => null,
 			'backgroundSize'  => null,
+			'gradient'        => null,
 		),
 		'border'                        => array(
 			'color'       => null,
@@ -554,6 +558,7 @@ class WP_Theme_JSON {
 	 * @since 6.5.0 Added support for `dimensions.aspectRatio`.
 	 * @since 6.6.0 Added `background` sub properties to top-level only.
 	 * @since 7.0.0 Added support for `dimensions.width` and `dimensions.height`.
+	 * @since 7.1.0 Added `background.gradient`.
 	 * @var array
 	 */
 	const VALID_STYLES = array(
@@ -563,6 +568,7 @@ class WP_Theme_JSON {
 			'backgroundRepeat'     => null,
 			'backgroundSize'       => null,
 			'backgroundAttachment' => null,
+			'gradient'             => null,
 		),
 		'border'     => array(
 			'color'  => null,
@@ -1021,11 +1027,13 @@ public static function get_element_class_name( $element ) {
 	 * @since 6.4.0 Added `background.backgroundImage`.
 	 * @since 6.5.0 Added `background.backgroundSize` and `dimensions.aspectRatio`.
 	 * @since 7.0.0 Added `dimensions.width` and `dimensions.height`.
+	 * @since 7.1.0 Added `background.gradient`.
 	 * @var array
 	 */
 	const APPEARANCE_TOOLS_OPT_INS = array(
 		array( 'background', 'backgroundImage' ),
 		array( 'background', 'backgroundSize' ),
+		array( 'background', 'gradient' ),
 		array( 'border', 'color' ),
 		array( 'border', 'radius' ),
 		array( 'border', 'style' ),
@@ -2945,11 +2953,21 @@ protected static function compute_style_properties( $styles, $settings = array()
 			 * For uploaded image (images with a database ID), apply size and position defaults,
 			 * equal to those applied in block supports in lib/background.php.
 			 */
-			if ( 'background-image' === $css_property && ! empty( $value ) ) {
-				$background_styles = wp_style_engine_get_styles(
-					array( 'background' => array( 'backgroundImage' => $value ) )
-				);
-				$value             = $background_styles['declarations'][ $css_property ];
+			if ( 'background-image' === $css_property ) {
+				$background_image_input = array();
+				if ( ! empty( $value ) ) {
+					$background_image_input['backgroundImage'] = $value;
+				}
+				$gradient_value = $styles['background']['gradient'] ?? null;
+				if ( ! empty( $gradient_value ) ) {
+					$background_image_input['gradient'] = $gradient_value;
+				}
+				if ( ! empty( $background_image_input ) ) {
+					$background_styles = wp_style_engine_get_styles(
+						array( 'background' => $background_image_input )
+					);
+					$value             = $background_styles['declarations'][ $css_property ] ?? null;
+				}
 			}
 			if ( empty( $value ) && static::ROOT_BLOCK_SELECTOR !== $selector && ! empty( $styles['background']['backgroundImage']['id'] ) ) {
 				if ( 'background-size' === $css_property ) {

src/wp-includes/kses.php

@@ -2553,6 +2553,7 @@ function kses_init() {
  * @since 6.5.0 Added support for `background-repeat`.
  * @since 6.6.0 Added support for `grid-column`, `grid-row`, and `container-type`.
  * @since 6.9.0 Added support for `white-space`.
+ * @since 7.1.0 Extended gradient support to allow any single-level nested function.
  *
  * @param string $css        A string of CSS rules, decoded from an HTML `style` attribute.
  * @param string $deprecated Not used.
@@ -2900,10 +2901,16 @@ function safecss_filter_attr( $css, $deprecated = '' ) {
 		}
 
 		if ( $found && $gradient_attr ) {
-			$css_value = trim( $parts[1] );
-			if ( preg_match( '/^(repeating-)?(linear|radial|conic)-gradient\(([^()]|rgb[a]?\([^()]*\))*\)$/', $css_value ) ) {
-				// Remove the whole `gradient` bit that was matched above from the CSS.
-				$css_test_string = str_replace( $css_value, '', $css_test_string );
+			/*
+			 * Match every `*-gradient()` in the value, allowing one level of nested functions
+			 * (e.g. rgb(), hsl(), var()). Matching each occurrence, rather than requiring the
+			 * whole value to be a single gradient, lets a gradient combine with a url() image.
+			 */
+			preg_match_all( '/(?:repeating-)?(?:linear|radial|conic)-gradient\((?:[^()]|\([^()]*\))*\)/', $css_test_string, $gradient_matches );
+
+			foreach ( $gradient_matches[0] as $gradient_match ) {
+				// Remove each `gradient()` bit that was matched above from the CSS.
+				$css_test_string = str_replace( $gradient_match, '', $css_test_string );
 			}
 		}
 

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

@@ -48,6 +48,7 @@ final class WP_Style_Engine {
 	 *  - 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
+	 * @since 7.1.0 Added `background.gradient` property.
 	 * @var array
 	 */
 	const BLOCK_STYLE_DEFINITIONS_METADATA = array(
@@ -83,6 +84,18 @@ final class WP_Style_Engine {
 				),
 				'path'          => array( 'background', 'backgroundAttachment' ),
 			),
+			'gradient'             => array(
+				'property_keys' => array(
+					'default' => 'background-image',
+				),
+				'css_vars'      => array(
+					'gradient' => '--wp--preset--gradient--$slug',
+				),
+				'path'          => array( 'background', 'gradient' ),
+				'classnames'    => array(
+					'has-background' => true,
+				),
+			),
 		),
 		'color'      => array(
 			'text'       => array(
@@ -495,6 +508,13 @@ public static function parse_block_styles( $block_styles, $options ) {
 
 				$css_declarations = static::get_css_declarations( $style_value, $style_definition, $options );
 				if ( ! empty( $css_declarations ) ) {
+					/*
+					 * Combine background gradient and background image into a single
+					 * comma-separated background-image value, matching the JS style engine.
+					 */
+					if ( isset( $css_declarations['background-image'] ) && isset( $parsed_styles['declarations']['background-image'] ) ) {
+						$css_declarations['background-image'] = $css_declarations['background-image'] . ', ' . $parsed_styles['declarations']['background-image'];
+					}
 					$parsed_styles['declarations'] = array_merge( $parsed_styles['declarations'], $css_declarations );
 				}
 			}