<?php
/**
* Block state support for frontend CSS generation.
*
* Generates scoped CSS for per-instance state styles declared in block attributes,
* including pseudo-states (e.g., `style[':hover']`) and responsive states
* (e.g., `style['mobile']` and `style['mobile'][':hover']`).
*
* @package WordPress
*/
/**
* Converts internal preset references to CSS custom property references.
*
* State styles are emitted as CSS rules and cannot rely on preset classnames.
* Converting `var:preset|color|contrast` to
* `var(--wp--preset--color--contrast)` ensures preset values are emitted as
* declarations by the style engine.
*
* @param mixed $value Style value to normalize.
* @return mixed Normalized style value.
*/
function gutenberg_normalize_state_preset_vars( $value ) {
if ( is_array( $value ) ) {
foreach ( $value as $key => $nested_value ) {
$value[ $key ] = gutenberg_normalize_state_preset_vars( $nested_value );
}
return $value;
}
if ( ! is_string( $value ) || ! str_starts_with( $value, 'var:preset|' ) ) {
return $value;
}
$unwrapped_name = str_replace( '|', '--', substr( $value, strlen( 'var:' ) ) );
return "var(--wp--$unwrapped_name)";
}
/**
* Normalizes a state style object before generating CSS declarations.
*
* @param array $style State style object.
* @return array Normalized state style object.
*/
function gutenberg_normalize_state_style_for_css_output( $style ) {
// Layout is processed separately by gutenberg_render_layout_support_flag(), so we remove it before declaration generation.
unset( $style['layout'] );
$style = gutenberg_normalize_state_preset_vars( $style );
return $style;
}
/**
* Adds fallback border-style declarations for visible border declarations.
*
* CSS does not render border color or width unless a border style is also set.
* State styles are emitted as stylesheet rules rather than inline styles, so
* they cannot rely on the block-library inline-style attribute fallback rules.
*
* @param array $declarations CSS declarations generated by the style engine.
* @return array CSS declarations with fallback border styles applied where needed.
*/
function gutenberg_get_state_declarations_with_fallback_border_styles( $declarations ) {
if ( ! is_array( $declarations ) ) {
return $declarations;
}
$has_border_style = isset( $declarations['border-style'] ) && '' !== $declarations['border-style'];
$has_border_color = isset( $declarations['border-color'] ) && '' !== $declarations['border-color'];
$has_border_width = isset( $declarations['border-width'] ) && '' !== $declarations['border-width'];
if ( ! $has_border_style && ( $has_border_color || $has_border_width ) ) {
$declarations['border-style'] = 'solid';
}
$sides = array( 'top', 'right', 'bottom', 'left' );
foreach ( $sides as $side ) {
$side_style_property = "border-$side-style";
$side_color_property = "border-$side-color";
$side_width_property = "border-$side-width";
$has_side_style = isset( $declarations[ $side_style_property ] ) && '' !== $declarations[ $side_style_property ];
$has_side_color = isset( $declarations[ $side_color_property ] ) && '' !== $declarations[ $side_color_property ];
$has_side_width = isset( $declarations[ $side_width_property ] ) && '' !== $declarations[ $side_width_property ];
if ( ! $has_border_style && ! $has_side_style && ( $has_side_color || $has_side_width ) ) {
$declarations[ $side_style_property ] = 'solid';
}
}
return $declarations;
}
/**
* Adds a style fragment to a selector-keyed state style group.
*
* @param array $groups Selector-keyed style groups.
* @param string|null $selector Block or feature selector.
* @param array $style Style fragment.
*/
function gutenberg_add_state_style_group( &$groups, $selector, $style ) {
$key = is_string( $selector ) ? $selector : '';
if ( ! isset( $groups[ $key ] ) ) {
$groups[ $key ] = array(
'selector' => $selector,
'style' => array(),
);
}
$groups[ $key ]['style'] = array_replace_recursive( $groups[ $key ]['style'], $style );
}
/**
* Splits a state style object into groups based on block feature selectors.
*
* @param array $state_style State style object.
* @param array $block_selectors Block selectors metadata.
* @return array[] Selector/style groups.
*/
function gutenberg_get_state_style_groups( $state_style, $block_selectors ) {
$groups = array();
foreach ( $state_style as $feature => $feature_styles ) {
$feature_selectors = $block_selectors[ $feature ] ?? null;
if ( is_string( $feature_selectors ) ) {
gutenberg_add_state_style_group(
$groups,
$feature_selectors,
array( $feature => $feature_styles )
);
continue;
}
if ( is_array( $feature_selectors ) && is_array( $feature_styles ) ) {
$remaining_styles = $feature_styles;
foreach ( $feature_selectors as $subfeature => $subfeature_selector ) {
if (
'root' === $subfeature ||
! is_string( $subfeature_selector ) ||
! array_key_exists( $subfeature, $feature_styles )
) {
continue;
}
gutenberg_add_state_style_group(
$groups,
$subfeature_selector,
array(
$feature => array(
$subfeature => $feature_styles[ $subfeature ],
),
)
);
unset( $remaining_styles[ $subfeature ] );
}
if ( array() !== $remaining_styles ) {
gutenberg_add_state_style_group(
$groups,
$feature_selectors['root'] ?? ( $block_selectors['root'] ?? null ),
array( $feature => $remaining_styles )
);
}
continue;
}
gutenberg_add_state_style_group(
$groups,
$block_selectors['root'] ?? null,
array( $feature => $feature_styles )
);
}
return array_values( $groups );
}
/**
* Returns a style object with nested state keys removed.
*
* @param array $state_style State style object.
* @param array $nested_keys Keys to remove from the root style object.
* @return array Root-only style object.
*/
function gutenberg_get_root_state_style( $state_style, $nested_keys ) {
if ( ! is_array( $state_style ) ) {
return $state_style;
}
$root_style = $state_style;
foreach ( $nested_keys as $key ) {
unset( $root_style[ $key ] );
}
return $root_style;
}
/**
* Builds compiled state style rules, preserving the selector each rule targets.
*
* @param array $state_styles Map of state to style array.
* @param WP_Block_Type $block_type Block type.
* @param string|null $rules_group Optional CSS grouping rule, e.g. a media query.
* @return array[] State style rules.
*/
function gutenberg_get_block_state_style_rules( $state_styles, $block_type, $rules_group = null ) {
$css_rules = array();
$block_selectors = isset( $block_type->selectors ) && is_array( $block_type->selectors )
? $block_type->selectors
: array();
foreach ( $state_styles as $state => $state_style ) {
if ( empty( $state_style ) || ! is_array( $state_style ) ) {
continue;
}
foreach ( gutenberg_get_state_style_groups( $state_style, $block_selectors ) as $group ) {
$compiled = gutenberg_style_engine_get_styles(
gutenberg_normalize_state_style_for_css_output( $group['style'] )
);
if ( ! empty( $compiled['declarations'] ) ) {
$css_rules[] = array(
'state' => $state,
'selector' => $group['selector'],
'declarations' => $compiled['declarations'],
);
if ( ! empty( $rules_group ) ) {
$css_rules[ count( $css_rules ) - 1 ]['rules_group'] = $rules_group;
}
}
}
}
return $css_rules;
}
/**
* Returns a unique class for a set of state style rules.
*
* @param string $block_name Block name.
* @param array $css_rules State style rules.
* @return string Unique class name.
*/
function gutenberg_get_block_state_unique_class( $block_name, $css_rules ) {
return 'wp-states-' . substr(
md5(
wp_json_encode(
array(
'blockName' => $block_name,
'rules' => $css_rules,
)
)
),
0,
8
);
}
/**
* Splits a selector list by top-level commas.
*
* @param string $selector CSS selector list.
* @return string[] Selectors.
*/
function gutenberg_split_selector_list( $selector ) {
if ( ! str_contains( $selector, ',' ) ) {
return array( $selector );
}
$selectors = array();
$current_selector = '';
$parentheses_depth = 0;
$selector_length = strlen( $selector );
for ( $i = 0; $i < $selector_length; $i++ ) {
$char = $selector[ $i ];
if ( '(' === $char ) {
++$parentheses_depth;
} elseif ( ')' === $char && $parentheses_depth > 0 ) {
--$parentheses_depth;
} elseif ( ',' === $char && 0 === $parentheses_depth ) {
$selectors[] = $current_selector;
$current_selector = '';
continue;
}
$current_selector .= $char;
}
$selectors[] = $current_selector;
return $selectors;
}
/**
* Builds a scoped selector from a block selector and optional pseudo-state.
*
* @param string $base_selector Block-instance scoping selector.
* @param string|null $block_selector Block or feature selector from metadata.
* @param string $state Pseudo-state selector.
* @return string Scoped selector.
*/
function gutenberg_build_state_selector( $base_selector, $block_selector, $state ) {
if ( ! is_string( $block_selector ) || '' === trim( $block_selector ) ) {
return $base_selector . $state;
}
$selectors = gutenberg_split_selector_list( $block_selector );
$scoped_selectors = array();
foreach ( $selectors as $selector ) {
$selector = trim( $selector );
if ( '' === $selector ) {
continue;
}
/*
* Replace only the leading block selector part (e.g. class name,
* attribute selector, ID, or tag name) with the block instance selector.
* Preserve anything after that prefix, including modifier classes on the
* same element and combinators without spaces.
*/
if ( preg_match( '/^([.#]?[-_a-zA-Z0-9]+|\[[^\]]+\])/', $selector, $matches ) ) {
$scoped_selectors[] = $base_selector . substr( $selector, strlen( $matches[0] ) ) . $state;
continue;
}
$scoped_selectors[] = $base_selector . $state;
}
return empty( $scoped_selectors )
? $base_selector . $state
: implode( ', ', $scoped_selectors );
}
/**
* Renders per-instance state styles on the frontend.
*
* @param string $block_content The block's rendered HTML.
* @param array $block The block data including blockName and attrs.
* @return string Modified block content with injected state styles.
*/
function gutenberg_render_block_states_support( $block_content, $block ) {
if ( empty( $block['blockName'] ) || empty( $block_content ) ) {
return $block_content;
}
$block_name = $block['blockName'];
$block_type = WP_Block_Type_Registry::get_instance()->get_registered( $block_name );
if ( ! $block_type ) {
return $block_content;
}
$supported_pseudo_states = WP_Theme_JSON_Gutenberg::VALID_BLOCK_PSEUDO_SELECTORS[ $block_name ] ?? array();
$style = $block['attrs']['style'] ?? array();
$css_rules = array();
foreach ( $supported_pseudo_states as $pseudo_state ) {
if ( empty( $style[ $pseudo_state ] ) || ! is_array( $style[ $pseudo_state ] ) ) {
continue;
}
$css_rules = array_merge(
$css_rules,
gutenberg_get_block_state_style_rules(
array( $pseudo_state => $style[ $pseudo_state ] ),
$block_type
)
);
}
foreach ( WP_Theme_JSON_Gutenberg::RESPONSIVE_BREAKPOINTS as $breakpoint => $media_query ) {
if ( empty( $style[ $breakpoint ] ) || ! is_array( $style[ $breakpoint ] ) ) {
continue;
}
$root_state_style = gutenberg_get_root_state_style(
$style[ $breakpoint ],
array_merge( array( 'elements' ), $supported_pseudo_states )
);
if ( ! empty( $root_state_style ) ) {
$css_rules = array_merge(
$css_rules,
gutenberg_get_block_state_style_rules(
array( '' => $root_state_style ),
$block_type,
$media_query
)
);
}
foreach ( $supported_pseudo_states as $pseudo_state ) {
if ( empty( $style[ $breakpoint ][ $pseudo_state ] ) || ! is_array( $style[ $breakpoint ][ $pseudo_state ] ) ) {
continue;
}
$css_rules = array_merge(
$css_rules,
gutenberg_get_block_state_style_rules(
array( $pseudo_state => $style[ $breakpoint ][ $pseudo_state ] ),
$block_type,
$media_query
)
);
}
}
if ( empty( $css_rules ) ) {
return $block_content;
}
$unique_class = gutenberg_get_block_state_unique_class( $block_name, $css_rules );
/*
* Register each state's CSS rules with the block-supports style engine store.
* The store deduplicates rules by selector — two block instances with identical
* state styles share the same hash class and therefore the same selector,
* so only one CSS rule is emitted. The store is flushed to the page by
* gutenberg_enqueue_stored_styles() rather than injected inline here.
*
* State declarations need !important to apply reliably over inline styles and
* preset utility classes such as .has-accent-3-background-color.
*
* Layout-driven state styles (responsive layout, blockGap, child layout) are
* handled by gutenberg_render_layout_support_flag() so they share a selector
* with the base layout and target the correct (inner) wrapper element.
*/
$style_rules = array();
foreach ( $css_rules as $rule ) {
$declarations = array();
foreach ( $rule['declarations'] as $property => $value ) {
$declarations[ $property ] = is_string( $value ) && str_contains( $value, '!important' )
? $value
: $value . ' !important';
}
$declarations = gutenberg_get_state_declarations_with_fallback_border_styles( $declarations );
$style_rule = array(
'selector' => gutenberg_build_state_selector(
".$unique_class",
$rule['selector'],
$rule['state']
),
'declarations' => $declarations,
);
if ( ! empty( $rule['rules_group'] ) ) {
$style_rule['rules_group'] = $rule['rules_group'];
}
$style_rules[] = $style_rule;
}
gutenberg_style_engine_get_stylesheet_from_css_rules(
$style_rules,
array(
'context' => 'block-supports',
'prettify' => false,
)
);
$processor = new WP_HTML_Tag_Processor( $block_content );
if ( $processor->next_tag() ) {
$processor->add_class( $unique_class );
}
return $processor->get_updated_html();
}
add_filter( 'render_block', 'gutenberg_render_block_states_support', 10, 2 );