Rename wp_style_engine_get_block_supports_styles to wp_style_engine_g…

…et_styles and document a 'context' option that will determine how we treat incoming style object. (#42719)

lib/block-supports/border.php

@@ -119,7 +119,7 @@ function gutenberg_apply_border_support( $block_type, $block_attributes ) {
 
 	// Collect classes and styles.
 	$attributes = array();
-	$styles     = gutenberg_style_engine_get_block_supports_styles( array( 'border' => $border_block_styles ) );
+	$styles     = gutenberg_style_engine_get_styles( array( 'border' => $border_block_styles ) );
 
 	if ( ! empty( $styles['classnames'] ) ) {
 		$attributes['class'] = $styles['classnames'];

lib/block-supports/colors.php

@@ -102,7 +102,7 @@ function gutenberg_apply_colors_support( $block_type, $block_attributes ) {
 	}
 
 	$attributes = array();
-	$styles     = gutenberg_style_engine_get_block_supports_styles( array( 'color' => $color_block_styles ), array( 'convert_vars_to_classnames' => true ) );
+	$styles     = gutenberg_style_engine_get_styles( array( 'color' => $color_block_styles ), array( 'convert_vars_to_classnames' => true ) );
 
 	if ( ! empty( $styles['classnames'] ) ) {
 		$attributes['class'] = $styles['classnames'];

lib/block-supports/elements.php

@@ -105,7 +105,7 @@ function gutenberg_render_elements_support_styles( $pre_render, $block ) {
 	$link_block_styles = isset( $element_block_styles['link'] ) ? $element_block_styles['link'] : null;
 
 	if ( $link_block_styles ) {
-		$styles = gutenberg_style_engine_get_block_supports_styles(
+		$styles = gutenberg_style_engine_get_styles(
 			$link_block_styles,
 			array(
 				'selector' => ".$class_name a",

lib/block-supports/layout.php

@@ -65,7 +65,7 @@ function gutenberg_get_layout_style( $selector, $layout, $has_block_gap_support
 			$style .= "$selector .alignfull { max-width: none; }";
 
 			if ( isset( $block_spacing ) ) {
-				$block_spacing_values = gutenberg_style_engine_get_block_supports_styles(
+				$block_spacing_values = gutenberg_style_engine_get_styles(
 					array(
 						'spacing' => $block_spacing,
 					)

lib/block-supports/spacing.php

@@ -57,7 +57,7 @@ function gutenberg_apply_spacing_support( $block_type, $block_attributes ) {
 	$spacing_block_styles            = array();
 	$spacing_block_styles['padding'] = $has_padding_support && ! $skip_padding ? _wp_array_get( $block_styles, array( 'spacing', 'padding' ), null ) : null;
 	$spacing_block_styles['margin']  = $has_margin_support && ! $skip_margin ? _wp_array_get( $block_styles, array( 'spacing', 'margin' ), null ) : null;
-	$styles                          = gutenberg_style_engine_get_block_supports_styles( array( 'spacing' => $spacing_block_styles ) );
+	$styles                          = gutenberg_style_engine_get_styles( array( 'spacing' => $spacing_block_styles ) );
 
 	if ( ! empty( $styles['css'] ) ) {
 		$attributes['style'] = $styles['css'];

lib/block-supports/typography.php

@@ -141,7 +141,7 @@ function gutenberg_apply_typography_support( $block_type, $block_attributes ) {
 	}
 
 	$attributes = array();
-	$styles     = gutenberg_style_engine_get_block_supports_styles(
+	$styles     = gutenberg_style_engine_get_styles(
 		array( 'typography' => $typography_block_styles ),
 		array( 'convert_vars_to_classnames' => true )
 	);

packages/style-engine/class-wp-style-engine.php

@@ -382,10 +382,10 @@ protected static function get_css_declarations( $style_value, $style_definition,
 	}
 
 	/**
-	 * Returns classnames and CSS based on the values in a block attributes.styles object.
+	 * Returns classnames and CSS based on the values in a styles object.
 	 * Return values are parsed based on the instructions in BLOCK_STYLE_DEFINITIONS_METADATA.
 	 *
-	 * @param array $block_styles Styles from a block's attributes object.
+	 * @param array $block_styles The style object.
 	 * @param array $options      array(
 	 *     'selector'                   => (string) When a selector is passed, `generate()` will return a full CSS rule `$selector { ...rules }`, otherwise a concatenated string of properties and values.
 	 *     'convert_vars_to_classnames' => (boolean) Whether to skip converting CSS var:? values to var( --wp--preset--* ) values. Default is `false`.
@@ -396,7 +396,7 @@ protected static function get_css_declarations( $style_value, $style_definition,
 	 *     'classnames' => (string) Classnames separated by a space.
 	 * );
 	 */
-	public function get_block_supports_styles( $block_styles, $options ) {
+	public function get_styles( $block_styles, $options ) {
 		if ( empty( $block_styles ) || ! is_array( $block_styles ) ) {
 			return null;
 		}
@@ -497,29 +497,35 @@ protected static function get_individual_property_css_declarations( $style_value
 }
 
 /**
- * Global public interface method to WP_Style_Engine->get_block_supports_styles to generate block styles from a single block style object.
- * See: https://developer.wordpress.org/block-editor/reference-guides/block-api/block-supports/
+ * Global public interface method to WP_Style_Engine->get_styles to generate styles from a single style object, e.g.,
+ * the value of a block's attributes.style object or the top level styles in theme.json.
+ * See: https://developer.wordpress.org/block-editor/reference-guides/theme-json-reference/theme-json-living/#styles and
+ * https://developer.wordpress.org/block-editor/reference-guides/block-api/block-supports/
  *
  * Example usage:
  *
- * $styles = wp_style_engine_get_block_supports_styles( array( 'color' => array( 'text' => '#cccccc' ) ) );
+ * $styles = wp_style_engine_get_styles( array( 'color' => array( 'text' => '#cccccc' ) ) );
  * // Returns `array( 'css' => 'color: #cccccc', 'declarations' => array( 'color' => '#cccccc' ), 'classnames' => 'has-color' )`.
  *
  * @access public
  *
- * @param array         $block_styles The value of a block's attributes.style.
- * @param array<string> $options      An array of options to determine the output.
+ * @param array         $block_styles The style object.
+ * @param array<string> $options      array(
+ *     'selector'                   => (string) When a selector is passed, `generate()` will return a full CSS rule `$selector { ...rules }`, otherwise a concatenated string of properties and values.
+ *     'context'                    => (string) An identifier describing the origin of the style object, e.g., 'block-supports' or 'global-styles'. Default is 'block-supports'.
+ *     'convert_vars_to_classnames' => (boolean) Whether to skip converting CSS var:? values to var( --wp--preset--* ) values. Default is `false`.
+ * );.
  *
  * @return array<string>|null array(
  *     'css'          => (string) A CSS ruleset or declarations block formatted to be placed in an HTML `style` attribute or tag.
  *     'declarations' => (array) An array of property/value pairs representing parsed CSS declarations.
  *     'classnames'   => (string) Classnames separated by a space.
  * );
  */
-function wp_style_engine_get_block_supports_styles( $block_styles, $options = array() ) {
+function wp_style_engine_get_styles( $block_styles, $options = array() ) {
 	if ( class_exists( 'WP_Style_Engine' ) ) {
 		$style_engine = WP_Style_Engine::get_instance();
-		return $style_engine->get_block_supports_styles( $block_styles, $options );
+		return $style_engine->get_styles( $block_styles, $options );
 	}
 	return null;
 }

packages/style-engine/phpunit/class-wp-style-engine-test.php

@@ -23,7 +23,7 @@ class WP_Style_Engine_Test extends WP_UnitTestCase {
 	 * @param string $expected_output The expected output.
 	 */
 	public function test_generate_block_supports_styles( $block_styles, $options, $expected_output ) {
-		$generated_styles = wp_style_engine_get_block_supports_styles( $block_styles, $options );
+		$generated_styles = wp_style_engine_get_styles( $block_styles, $options );
 		$this->assertSame( $expected_output, $generated_styles );
 	}