| [ Index ] |
PHP Cross Reference of WordPress Trunk (Updated Daily) |
[Summary view] [Print] [Text view]
1 <?php 2 /** 3 * Block state support for frontend CSS generation. 4 * 5 * Generates scoped CSS for per-instance state styles declared in block attributes, 6 * including pseudo-states (e.g., `style[':hover']`) and responsive states 7 * (e.g., `style['@mobile']` and `style['@mobile'][':hover']`). 8 * 9 * @package WordPress 10 * @since 7.1.0 11 */ 12 13 /** 14 * Converts internal preset references to CSS custom property references. 15 * 16 * State styles are emitted as CSS rules and cannot rely on preset classnames. 17 * Converting `var:preset|color|contrast` to 18 * `var(--wp--preset--color--contrast)` ensures preset values are emitted as 19 * declarations by the style engine. 20 * 21 * @since 7.1.0 22 * 23 * @param mixed $value Style value to normalize. 24 * @return mixed Normalized style value. 25 */ 26 function wp_normalize_state_preset_vars( $value ) { 27 if ( is_array( $value ) ) { 28 foreach ( $value as $key => $nested_value ) { 29 $value[ $key ] = wp_normalize_state_preset_vars( $nested_value ); 30 } 31 return $value; 32 } 33 34 if ( ! is_string( $value ) || ! str_starts_with( $value, 'var:preset|' ) ) { 35 return $value; 36 } 37 38 $parts = explode( '|', substr( $value, strlen( 'var:' ) ) ); 39 40 /* 41 * The slug is kebab-cased when the preset's custom property is generated, 42 * so a reference has to be converted the same way or it points at a 43 * property that does not exist (`--wp--preset--font-size--3xl` for a preset 44 * generated as `--wp--preset--font-size--3-xl`). Mirrors 45 * `WP_Theme_JSON::convert_custom_properties()` and the JavaScript style 46 * engine's `getCSSValueFromRawStyle()`. 47 */ 48 if ( 3 === count( $parts ) ) { 49 $parts[2] = _wp_to_kebab_case( $parts[2] ); 50 } 51 52 return 'var(--wp--' . implode( '--', $parts ) . ')'; 53 } 54 55 /** 56 * Normalizes a state style object before generating CSS declarations. 57 * 58 * @since 7.1.0 59 * 60 * @param array $style State style object. 61 * @return array Normalized state style object. 62 */ 63 function wp_normalize_state_style_for_css_output( $style ) { 64 // Layout is processed separately by wp_render_layout_support_flag(), so we remove it before declaration generation. 65 unset( $style['layout'] ); 66 $style = wp_normalize_state_preset_vars( $style ); 67 return $style; 68 } 69 70 /** 71 * Adds fallback border-style declarations for visible border declarations. 72 * 73 * CSS does not render border color or width unless a border style is also set. 74 * State styles are emitted as stylesheet rules rather than inline styles, so 75 * they cannot rely on the block-library inline-style attribute fallback rules. 76 * 77 * @since 7.1.0 78 * 79 * @param array $declarations CSS declarations generated by the style engine. 80 * @return array CSS declarations with fallback border styles applied where needed. 81 */ 82 function wp_get_state_declarations_with_fallback_border_styles( $declarations ) { 83 if ( ! is_array( $declarations ) ) { 84 return $declarations; 85 } 86 87 $has_border_style = isset( $declarations['border-style'] ) && '' !== $declarations['border-style']; 88 $has_border_color = isset( $declarations['border-color'] ) && '' !== $declarations['border-color']; 89 $has_border_width = isset( $declarations['border-width'] ) && '' !== $declarations['border-width']; 90 91 if ( ! $has_border_style && ( $has_border_color || $has_border_width ) ) { 92 $declarations['border-style'] = 'solid'; 93 } 94 95 $sides = array( 'top', 'right', 'bottom', 'left' ); 96 foreach ( $sides as $side ) { 97 $side_style_property = "border-$side-style"; 98 $side_color_property = "border-$side-color"; 99 $side_width_property = "border-$side-width"; 100 101 $has_side_style = isset( $declarations[ $side_style_property ] ) && '' !== $declarations[ $side_style_property ]; 102 $has_side_color = isset( $declarations[ $side_color_property ] ) && '' !== $declarations[ $side_color_property ]; 103 $has_side_width = isset( $declarations[ $side_width_property ] ) && '' !== $declarations[ $side_width_property ]; 104 105 if ( ! $has_border_style && ! $has_side_style && ( $has_side_color || $has_side_width ) ) { 106 $declarations[ $side_style_property ] = 'solid'; 107 } 108 } 109 110 return $declarations; 111 } 112 113 /** 114 * Adds background reset declarations to prevent gradient/solid color conflicts. 115 * 116 * When a state sets a solid background-color, any gradient applied to the 117 * default state (via `background` shorthand or `background-image`) must be 118 * explicitly cleared. Without this, the gradient image layer remains visible 119 * on top of the solid hover color even when `!important` is used, because 120 * `background-color` and `background-image` are separate CSS properties. 121 * 122 * @since 7.1.0 123 * 124 * @param array $declarations CSS declarations generated by the style engine. 125 * @return array CSS declarations with background resets applied where needed. 126 */ 127 function wp_get_state_declarations_with_background_resets( $declarations ) { 128 if ( ! is_array( $declarations ) ) { 129 return $declarations; 130 } 131 132 $has_background_color = isset( $declarations['background-color'] ) && '' !== $declarations['background-color']; 133 $has_background = isset( $declarations['background'] ) && '' !== $declarations['background']; 134 $has_background_image = isset( $declarations['background-image'] ) && '' !== $declarations['background-image']; 135 136 /* 137 * When the state sets a solid background-color but no gradient of its own, 138 * emit `background-image: unset` to clear any gradient (whether stored as 139 * the `background` shorthand or as `background-image`) that was applied to 140 * the default / normal state via an inline style attribute. The declaration 141 * is marked important when the state rule is registered with the style engine. 142 */ 143 if ( $has_background_color && ! $has_background && ! $has_background_image ) { 144 $declarations['background-image'] = 'unset'; 145 } 146 147 return $declarations; 148 } 149 150 /** 151 * Merges one state style object over another. 152 * 153 * Mirror of `mergeStyleObjects` in packages/block-editor/src/hooks/style.jsx. 154 * 155 * @since 7.2.0 156 * 157 * @param array<string, mixed> $target Styles underneath. 158 * @param array<string, mixed> $source Styles layered over them. 159 * @return array<string, mixed> Merged style object. 160 */ 161 function wp_merge_state_style_objects( $target, $source ) { 162 $target = is_array( $target ) ? $target : array(); 163 $source = is_array( $source ) ? $source : array(); 164 $merged = $target; 165 166 foreach ( $source as $key => $value ) { 167 $merged[ $key ] = is_array( $value ) && isset( $merged[ $key ] ) && is_array( $merged[ $key ] ) 168 ? wp_merge_state_style_objects( $merged[ $key ], $value ) 169 : $value; 170 } 171 172 return $merged; 173 } 174 175 /** 176 * Checks whether a state paints its own background. 177 * 178 * @since 7.2.0 179 * @access private 180 * 181 * @param array<string, mixed> $state_style State style object. 182 * @return bool Whether the state sets a gradient or background image. 183 */ 184 function wp_state_paints_own_background( array $state_style ): bool { 185 return ! empty( $state_style['background']['gradient'] ) || 186 ! empty( $state_style['background']['backgroundImage'] ) || 187 ! empty( $state_style['color']['gradient'] ); 188 } 189 190 /** 191 * Returns the declarations that unclip a text clip when a state sets a different clip. 192 * 193 * Mirror of `getStateTextClipEscapeCSS` in packages/block-editor/src/hooks/style.jsx. 194 * 195 * @since 7.2.0 196 * 197 * @param array<string, mixed> $state_style State style object. 198 * @param string $base_clip Background clip of the styles the state layers over. 199 * @return array<string, string> CSS declarations, empty when no escape is needed. 200 * 201 * @phpstan-return array<non-falsy-string, non-falsy-string> 202 */ 203 function wp_get_state_text_clip_escape( array $state_style, string $base_clip ): array { 204 $state_clip = $state_style['background']['backgroundClip'] ?? ''; 205 if ( ! in_array( $state_clip, WP_Style_Engine::VALID_BACKGROUND_CLIP_VALUES, true ) ) { 206 $state_clip = ''; 207 } 208 if ( empty( $state_clip ) || 'text' === $state_clip || 'text' !== $base_clip || wp_state_paints_own_background( $state_style ) ) { 209 return array(); 210 } 211 return array( 'background-image' => 'unset' ); 212 } 213 214 /** 215 * Returns the declarations that refill the letters when a state sets a text color but no clip. 216 * 217 * The fill is added even without a known text clip, since a block instance 218 * cannot see a clip set in global styles. It does nothing when no clip applies. 219 * 220 * Mirror of `getStateTextFillResetCSS` in packages/block-editor/src/hooks/style.jsx. 221 * 222 * @since 7.2.0 223 * 224 * @param array<string, mixed> $state_style State style object. 225 * @return array<string, string> CSS declarations, empty when no reset is needed. 226 * 227 * @phpstan-return array<non-falsy-string, non-falsy-string> 228 */ 229 function wp_get_state_text_fill_reset( array $state_style ): array { 230 $state_clip = $state_style['background']['backgroundClip'] ?? ''; 231 if ( ! in_array( $state_clip, WP_Style_Engine::VALID_BACKGROUND_CLIP_VALUES, true ) ) { 232 $state_clip = ''; 233 } 234 if ( ! empty( $state_clip ) || empty( $state_style['color']['text'] ) || wp_state_paints_own_background( $state_style ) ) { 235 return array(); 236 } 237 return array( '-webkit-text-fill-color' => 'currentColor' ); 238 } 239 240 /** 241 * Adds fallback dimension styles for aspectRatio and height block-support values. 242 * 243 * @since 7.1.0 244 * 245 * @param array $state_style State style object. 246 * @return array State style object with fallback dimension styles applied where needed. 247 */ 248 function wp_get_state_style_with_fallback_dimension_styles( $state_style ) { 249 if ( ! is_array( $state_style ) ) { 250 return $state_style; 251 } 252 253 $dimensions = isset( $state_style['dimensions'] ) && is_array( $state_style['dimensions'] ) 254 ? $state_style['dimensions'] 255 : array(); 256 257 if ( empty( $dimensions ) ) { 258 return $state_style; 259 } 260 261 if ( wp_is_explicit_aspect_ratio_value( $dimensions['aspectRatio'] ?? null ) ) { 262 return array_replace_recursive( 263 $state_style, 264 array( 265 'dimensions' => array( 266 'minHeight' => 'unset', 267 'height' => 'unset', 268 ), 269 ) 270 ); 271 } 272 273 $has_min_height = isset( $dimensions['minHeight'] ) && ( is_string( $dimensions['minHeight'] ) || is_numeric( $dimensions['minHeight'] ) ) && '' !== trim( (string) $dimensions['minHeight'] ); 274 $has_height = isset( $dimensions['height'] ) && ( is_string( $dimensions['height'] ) || is_numeric( $dimensions['height'] ) ) && '' !== trim( (string) $dimensions['height'] ); 275 276 if ( $has_min_height || $has_height ) { 277 return array_replace_recursive( 278 $state_style, 279 array( 280 'dimensions' => array( 281 'aspectRatio' => 'unset', 282 ), 283 ) 284 ); 285 } 286 287 return $state_style; 288 } 289 290 /** 291 * Adds a style fragment to a selector-keyed state style group. 292 * 293 * @since 7.1.0 294 * 295 * @param array $groups Selector-keyed style groups. 296 * @param string|null $selector Block or feature selector. 297 * @param array $style Style fragment. 298 */ 299 function wp_add_state_style_group( &$groups, $selector, $style ) { 300 $key = is_string( $selector ) ? $selector : ''; 301 302 if ( ! isset( $groups[ $key ] ) ) { 303 $groups[ $key ] = array( 304 'selector' => $selector, 305 'style' => array(), 306 ); 307 } 308 309 $groups[ $key ]['style'] = array_replace_recursive( $groups[ $key ]['style'], $style ); 310 } 311 312 /** 313 * Splits a state style object into groups based on block feature selectors. 314 * 315 * @since 7.1.0 316 * 317 * @param array<string, mixed> $state_style State style object. 318 * @param array<string, string|array<string, string>> $block_selectors Block selectors metadata. 319 * @return array[] Selector/style groups. 320 * 321 * @phpstan-param array{ root?: string, ...<string, string|array<string, string>> } $block_selectors 322 */ 323 function wp_get_state_style_groups( $state_style, $block_selectors ) { 324 $groups = array(); 325 326 foreach ( $state_style as $feature => $feature_styles ) { 327 $feature_selectors = $block_selectors[ $feature ] ?? null; 328 329 if ( is_string( $feature_selectors ) ) { 330 wp_add_state_style_group( 331 $groups, 332 $feature_selectors, 333 array( $feature => $feature_styles ) 334 ); 335 continue; 336 } 337 338 if ( is_array( $feature_selectors ) && is_array( $feature_styles ) ) { 339 $remaining_styles = $feature_styles; 340 341 foreach ( $feature_selectors as $subfeature => $subfeature_selector ) { 342 if ( 343 'root' === $subfeature || 344 ! is_string( $subfeature_selector ) || 345 ! array_key_exists( $subfeature, $feature_styles ) 346 ) { 347 continue; 348 } 349 350 wp_add_state_style_group( 351 $groups, 352 $subfeature_selector, 353 array( 354 $feature => array( 355 $subfeature => $feature_styles[ $subfeature ], 356 ), 357 ) 358 ); 359 unset( $remaining_styles[ $subfeature ] ); 360 } 361 362 if ( array() !== $remaining_styles ) { 363 wp_add_state_style_group( 364 $groups, 365 $feature_selectors['root'] ?? ( $block_selectors['root'] ?? null ), 366 array( $feature => $remaining_styles ) 367 ); 368 } 369 continue; 370 } 371 372 wp_add_state_style_group( 373 $groups, 374 $block_selectors['root'] ?? null, 375 array( $feature => $feature_styles ) 376 ); 377 } 378 379 return array_values( $groups ); 380 } 381 382 /** 383 * Returns a style object with nested state keys removed. 384 * 385 * @since 7.1.0 386 * 387 * @param array $state_style State style object. 388 * @param array $nested_keys Keys to remove from the root style object. 389 * @return array Root-only style object. 390 */ 391 function wp_get_root_state_style( $state_style, $nested_keys ) { 392 if ( ! is_array( $state_style ) ) { 393 return $state_style; 394 } 395 396 $root_style = $state_style; 397 foreach ( $nested_keys as $key ) { 398 unset( $root_style[ $key ] ); 399 } 400 401 return $root_style; 402 } 403 404 /** 405 * Generates all element selectors for a block root selector. 406 * 407 * @since 7.1.0 408 * 409 * @param string $root_selector The block root CSS selector. 410 * @return string[] Element selectors keyed by element name. 411 */ 412 function wp_get_block_state_element_selectors( $root_selector ) { 413 if ( ! is_string( $root_selector ) || '' === trim( $root_selector ) ) { 414 return array(); 415 } 416 417 $block_selectors = wp_split_selector_list( $root_selector ); 418 $element_selectors = array(); 419 420 foreach ( WP_Theme_JSON::ELEMENTS as $element_name => $element_selector ) { 421 $selectors = array(); 422 423 foreach ( $block_selectors as $block_selector ) { 424 $block_selector = trim( $block_selector ); 425 if ( '' === $block_selector ) { 426 continue; 427 } 428 429 if ( $block_selector === $element_selector ) { 430 $selectors = array( $element_selector ); 431 break; 432 } 433 434 $selector_prefix = "$block_selector "; 435 if ( ! str_contains( $element_selector, ',' ) ) { 436 $selectors[] = $selector_prefix . $element_selector; 437 continue; 438 } 439 440 $prepended_selectors = array(); 441 foreach ( wp_split_selector_list( $element_selector ) as $selector ) { 442 $prepended_selectors[] = $selector_prefix . $selector; 443 } 444 $selectors[] = implode( ',', $prepended_selectors ); 445 } 446 447 if ( ! empty( $selectors ) ) { 448 $element_selectors[ $element_name ] = implode( ',', $selectors ); 449 } 450 } 451 452 return $element_selectors; 453 } 454 455 /** 456 * Adds a compiled state style rule to a rule list. 457 * 458 * @since 7.1.0 459 * @since 7.2.0 Added fallback dimension styles. 460 * Added the `$base_style` parameter. 461 * 462 * @param array[] $css_rules Style rules. 463 * @param string $state Pseudo-state selector. 464 * @param string|null $selector Block, feature, or element selector. 465 * @param array<string, mixed> $style Style object. 466 * @param string|null $rules_group Optional CSS grouping rule, e.g. a media query. 467 * @param array<string, mixed>|null $base_style Optional styles the state layers over. 468 */ 469 function wp_add_block_state_style_rule( &$css_rules, $state, $selector, $style, $rules_group = null, $base_style = null ) { 470 if ( empty( $style ) || ! is_array( $style ) ) { 471 return; 472 } 473 474 $style = wp_get_state_style_with_fallback_dimension_styles( $style ); 475 476 $compiled = wp_style_engine_get_styles( 477 wp_normalize_state_style_for_css_output( $style ) 478 ); 479 $declarations = $compiled['declarations'] ?? array(); 480 $text_align = $style['typography']['textAlign'] ?? null; 481 // Base text alignment is class-based, so state styles need a declaration. 482 if ( is_string( $text_align ) && '' !== trim( $text_align ) ) { 483 $declarations['text-align'] = $text_align; 484 } 485 486 // Only block states pass a base; element states match the editor and skip it. 487 if ( null !== $base_style ) { 488 $base_clip = $base_style['background']['backgroundClip'] ?? ''; 489 $declarations = array_merge( 490 $declarations, 491 wp_get_state_text_clip_escape( $style, is_string( $base_clip ) ? $base_clip : '' ), 492 wp_get_state_text_fill_reset( $style ) 493 ); 494 } 495 496 if ( empty( $declarations ) ) { 497 return; 498 } 499 500 $css_rules[] = array( 501 'state' => $state, 502 'selector' => $selector, 503 'declarations' => $declarations, 504 ); 505 if ( ! empty( $rules_group ) ) { 506 $css_rules[ count( $css_rules ) - 1 ]['rules_group'] = $rules_group; 507 } 508 } 509 510 /** 511 * Builds compiled state style rules, preserving the selector each rule targets. 512 * 513 * @since 7.1.0 514 * @since 7.2.0 Added the `$base_style` parameter. 515 * 516 * @param array<string, mixed> $state_styles Map of state to style array. 517 * @param WP_Block_Type $block_type Block type. 518 * @param string|null $rules_group Optional CSS grouping rule, e.g. a media query. 519 * @param array<string, mixed>|null $base_style Optional styles the state layers over. 520 * @return array[] State style rules. 521 */ 522 function wp_get_block_state_style_rules( $state_styles, $block_type, $rules_group = null, $base_style = null ) { 523 // Only a block that supports the clip can sit under a text clip to escape. 524 if ( ! block_has_support( $block_type, array( 'background', 'backgroundClip' ), false ) ) { 525 $base_style = null; 526 } 527 528 $css_rules = array(); 529 $block_selectors = is_array( $block_type->selectors ) 530 ? $block_type->selectors 531 : array(); 532 533 foreach ( $state_styles as $state => $state_style ) { 534 if ( empty( $state_style ) || ! is_array( $state_style ) ) { 535 continue; 536 } 537 538 foreach ( wp_get_state_style_groups( $state_style, $block_selectors ) as $group ) { 539 wp_add_block_state_style_rule( 540 $css_rules, 541 $state, 542 $group['selector'], 543 $group['style'], 544 $rules_group, 545 $base_style 546 ); 547 } 548 } 549 550 return $css_rules; 551 } 552 553 /** 554 * Returns a unique class for a set of state style rules. 555 * 556 * @since 7.1.0 557 * 558 * @param string $block_name Block name. 559 * @param array $css_rules State style rules. 560 * @return string Unique class name. 561 */ 562 function wp_get_block_state_unique_class( $block_name, $css_rules ) { 563 return 'wp-states-' . substr( 564 md5( 565 wp_json_encode( 566 array( 567 'blockName' => $block_name, 568 'rules' => $css_rules, 569 ) 570 ) 571 ), 572 0, 573 8 574 ); 575 } 576 577 /** 578 * Splits a selector list by top-level commas. 579 * 580 * @since 7.1.0 581 * 582 * @param string $selector CSS selector list. 583 * @return string[] Selectors. 584 */ 585 function wp_split_selector_list( $selector ) { 586 if ( ! str_contains( $selector, ',' ) ) { 587 return array( $selector ); 588 } 589 590 $selectors = array(); 591 $current_selector = ''; 592 $parentheses_depth = 0; 593 $selector_length = strlen( $selector ); 594 595 for ( $i = 0; $i < $selector_length; $i++ ) { 596 $char = $selector[ $i ]; 597 598 if ( '(' === $char ) { 599 ++$parentheses_depth; 600 } elseif ( ')' === $char && $parentheses_depth > 0 ) { 601 --$parentheses_depth; 602 } elseif ( ',' === $char && 0 === $parentheses_depth ) { 603 $selectors[] = $current_selector; 604 $current_selector = ''; 605 continue; 606 } 607 608 $current_selector .= $char; 609 } 610 611 $selectors[] = $current_selector; 612 613 return $selectors; 614 } 615 616 /** 617 * Returns the ancestor part of a block selector whose leading compound names 618 * a different block, e.g. `.wp-block-list > ` in List Item's `.wp-block-list > li`. 619 * 620 * The block-instance class is on the block's own wrapper, so a leading compound 621 * naming another block must be kept rather than swapped for that class. When the 622 * next compound carries a `wp-block-*` class (`.wp-block-button .wp-block-button__link`), 623 * the selector describes a nested element and keeps the leading swap. 624 * 625 * @since 7.2.0 626 * 627 * @param string $selector A single block or feature selector. 628 * @param string|null $block_name Name of the block being scoped. 629 * @return string The leading compound and its combinator, or an empty string. 630 */ 631 function wp_get_state_selector_ancestor( $selector, $block_name ) { 632 if ( 633 ! is_string( $block_name ) || 634 '' === $block_name || 635 ! preg_match( '/^\.(wp-block-[-_a-zA-Z0-9]+)/', $selector, $matches ) || 636 wp_get_block_default_classname( $block_name ) === $matches[1] 637 ) { 638 return ''; 639 } 640 641 $ancestor_length = 0; 642 $next_compound = ''; 643 $depth = 0; 644 $selector_length = strlen( $selector ); 645 646 for ( $i = 0; $i < $selector_length; $i++ ) { 647 $char = $selector[ $i ]; 648 649 if ( '(' === $char || '[' === $char ) { 650 ++$depth; 651 } elseif ( ( ')' === $char || ']' === $char ) && $depth > 0 ) { 652 --$depth; 653 } elseif ( 0 === $depth && str_contains( " \t\n\r\f>+~", $char ) ) { 654 if ( $ancestor_length ) { 655 break; 656 } 657 $ancestor_length = $i + strspn( $selector, " \t\n\r\f>+~", $i ); 658 $i = $ancestor_length - 1; 659 } elseif ( 0 === $depth && $ancestor_length ) { 660 $next_compound .= $char; 661 } 662 } 663 664 if ( '' === $next_compound || str_contains( $next_compound, '.wp-block-' ) ) { 665 return ''; 666 } 667 668 return substr( $selector, 0, $ancestor_length ); 669 } 670 671 /** 672 * Builds a scoped selector from a block selector and optional pseudo-state. 673 * 674 * @since 7.1.0 675 * @since 7.2.0 Added the `$block_name` parameter. 676 * 677 * @param string $base_selector Block-instance scoping selector. 678 * @param string|null $block_selector Block or feature selector from metadata. 679 * @param string $state Pseudo-state selector. 680 * @param string|null $block_name Optional. Name of the block being scoped. 681 * @return string Scoped selector. 682 */ 683 function wp_build_state_selector( $base_selector, $block_selector, $state, $block_name = null ) { 684 if ( ! is_string( $block_selector ) || '' === trim( $block_selector ) ) { 685 return $base_selector . $state; 686 } 687 688 $selectors = wp_split_selector_list( $block_selector ); 689 $scoped_selectors = array(); 690 691 foreach ( $selectors as $selector ) { 692 $selector = trim( $selector ); 693 if ( '' === $selector ) { 694 continue; 695 } 696 697 $ancestor = wp_get_state_selector_ancestor( $selector, $block_name ); 698 $selector = substr( $selector, strlen( $ancestor ) ); 699 700 /* 701 * Replace only the leading block selector part (e.g. class name, 702 * attribute selector, ID, or tag name) with the block instance selector. 703 * Preserve anything after that prefix, including modifier classes on the 704 * same element and combinators without spaces. 705 */ 706 if ( preg_match( '/^([.#]?[-_a-zA-Z0-9]+|\[[^\]]+\])/', $selector, $matches ) ) { 707 $scoped_selectors[] = $ancestor . $base_selector . substr( $selector, strlen( $matches[0] ) ) . $state; 708 continue; 709 } 710 711 $scoped_selectors[] = $ancestor . $base_selector . $state; 712 } 713 714 return empty( $scoped_selectors ) 715 ? $base_selector . $state 716 : implode( ', ', $scoped_selectors ); 717 } 718 719 /** 720 * Renders per-instance state styles on the frontend. 721 * 722 * @since 7.1.0 723 * 724 * @param string $block_content The block's rendered HTML. 725 * @param array $block The block data including blockName and attrs. 726 * @return string Modified block content with injected state styles. 727 */ 728 function wp_render_block_states_support( $block_content, $block ) { 729 if ( empty( $block['blockName'] ) || empty( $block_content ) ) { 730 return $block_content; 731 } 732 733 /* 734 * Every CSS rule this function can produce is keyed off the block's `style` 735 * attribute. Without it there is nothing to generate, so bail before doing 736 * any of the lookups below — this runs for every block on every request. 737 */ 738 $style = $block['attrs']['style'] ?? array(); 739 if ( empty( $style ) || ! is_array( $style ) ) { 740 return $block_content; 741 } 742 743 $block_name = $block['blockName']; 744 $block_type = WP_Block_Type_Registry::get_instance()->get_registered( $block_name ); 745 if ( ! $block_type ) { 746 return $block_content; 747 } 748 749 $supported_pseudo_states = WP_Theme_JSON::VALID_BLOCK_PSEUDO_SELECTORS[ $block_name ] ?? array(); 750 $css_rules = array(); 751 $default_root_style = wp_get_root_state_style( 752 $style, 753 array_merge( array( 'elements' ), $supported_pseudo_states ) 754 ); 755 $viewport_settings = wp_get_global_settings( array( 'viewport' ) ); 756 $responsive_media_queries = WP_Theme_JSON::get_viewport_media_queries( $viewport_settings ); 757 758 foreach ( $supported_pseudo_states as $pseudo_state ) { 759 if ( empty( $style[ $pseudo_state ] ) || ! is_array( $style[ $pseudo_state ] ) ) { 760 continue; 761 } 762 763 $css_rules = array_merge( 764 $css_rules, 765 wp_get_block_state_style_rules( 766 array( $pseudo_state => $style[ $pseudo_state ] ), 767 $block_type, 768 null, 769 $default_root_style 770 ) 771 ); 772 } 773 774 foreach ( $responsive_media_queries as $breakpoint => $media_query ) { 775 if ( empty( $style[ $breakpoint ] ) || ! is_array( $style[ $breakpoint ] ) ) { 776 continue; 777 } 778 779 $root_state_style = wp_get_root_state_style( 780 $style[ $breakpoint ], 781 array_merge( array( 'elements' ), $supported_pseudo_states ) 782 ); 783 784 if ( ! empty( $root_state_style ) ) { 785 $css_rules = array_merge( 786 $css_rules, 787 wp_get_block_state_style_rules( 788 array( '' => $root_state_style ), 789 $block_type, 790 $media_query, 791 $default_root_style 792 ) 793 ); 794 } 795 796 if ( 797 ! empty( $style[ $breakpoint ]['elements'] ) && 798 is_array( $style[ $breakpoint ]['elements'] ) 799 ) { 800 $element_selectors = wp_get_block_state_element_selectors( 801 wp_get_block_css_selector( $block_type ) 802 ); 803 804 foreach ( $style[ $breakpoint ]['elements'] as $element_name => $element_style ) { 805 if ( 806 empty( $element_style ) || 807 ! is_array( $element_style ) || 808 empty( $element_selectors[ $element_name ] ) 809 ) { 810 continue; 811 } 812 813 $element_pseudo_states = WP_Theme_JSON::VALID_ELEMENT_PSEUDO_SELECTORS[ $element_name ] 814 ?? array(); 815 $root_element_style = wp_get_root_state_style( 816 $element_style, 817 $element_pseudo_states 818 ); 819 820 wp_add_block_state_style_rule( 821 $css_rules, 822 '', 823 $element_selectors[ $element_name ], 824 $root_element_style, 825 $media_query 826 ); 827 828 foreach ( $element_pseudo_states as $pseudo_state ) { 829 if ( 830 empty( $element_style[ $pseudo_state ] ) || 831 ! is_array( $element_style[ $pseudo_state ] ) 832 ) { 833 continue; 834 } 835 836 wp_add_block_state_style_rule( 837 $css_rules, 838 $pseudo_state, 839 $element_selectors[ $element_name ], 840 $element_style[ $pseudo_state ], 841 $media_query 842 ); 843 } 844 } 845 } 846 847 foreach ( $supported_pseudo_states as $pseudo_state ) { 848 if ( empty( $style[ $breakpoint ][ $pseudo_state ] ) || ! is_array( $style[ $breakpoint ][ $pseudo_state ] ) ) { 849 continue; 850 } 851 852 $css_rules = array_merge( 853 $css_rules, 854 wp_get_block_state_style_rules( 855 array( $pseudo_state => $style[ $breakpoint ][ $pseudo_state ] ), 856 $block_type, 857 $media_query, 858 wp_merge_state_style_objects( 859 $default_root_style, 860 $root_state_style 861 ) 862 ) 863 ); 864 } 865 } 866 867 if ( empty( $css_rules ) ) { 868 return $block_content; 869 } 870 871 $unique_class = wp_get_block_state_unique_class( $block_name, $css_rules ); 872 873 /* 874 * Register each state's CSS rules with the block-supports style engine store. 875 * The store deduplicates rules by selector — two block instances with identical 876 * state styles share the same hash class and therefore the same selector, 877 * so only one CSS rule is emitted. The store is flushed to the page by 878 * wp_enqueue_stored_styles() rather than injected inline here. 879 * 880 * State declarations need !important to apply reliably over inline styles and 881 * preset utility classes such as .has-accent-3-background-color. 882 * 883 * Layout-driven state styles (responsive layout, blockGap, child layout) are 884 * handled by wp_render_layout_support_flag() so they share a selector with 885 * the base layout and target the correct (inner) wrapper element. 886 */ 887 $style_rules = array(); 888 foreach ( $css_rules as $rule ) { 889 $declarations = $rule['declarations']; 890 $important_declaration_values = wp_get_state_declarations_with_background_resets( $declarations ); 891 $important_declarations = new WP_Style_Engine_CSS_Declarations(); 892 foreach ( $important_declaration_values as $property => $value ) { 893 $important_declarations->add_declaration( 894 $property, 895 $value, 896 array( 897 'important' => true, 898 ) 899 ); 900 } 901 $selector = wp_build_state_selector( 902 ".$unique_class", 903 $rule['selector'], 904 $rule['state'], 905 $block_name 906 ); 907 $important_style_rule = array( 908 'selector' => $selector, 909 'declarations' => $important_declarations, 910 ); 911 if ( ! empty( $rule['rules_group'] ) ) { 912 $important_style_rule['rules_group'] = $rule['rules_group']; 913 } 914 $style_rules[] = $important_style_rule; 915 916 $fallback_declarations = wp_get_state_declarations_with_fallback_border_styles( $declarations ); 917 foreach ( array_keys( $declarations ) as $property ) { 918 unset( $fallback_declarations[ $property ] ); 919 } 920 921 if ( empty( $fallback_declarations ) ) { 922 continue; 923 } 924 925 $fallback_style_rule = array( 926 'selector' => $selector, 927 'declarations' => $fallback_declarations, 928 ); 929 if ( ! empty( $rule['rules_group'] ) ) { 930 $fallback_style_rule['rules_group'] = $rule['rules_group']; 931 } 932 $style_rules[] = $fallback_style_rule; 933 } 934 935 wp_style_engine_get_stylesheet_from_css_rules( 936 $style_rules, 937 array( 938 'context' => 'block-supports', 939 'prettify' => false, 940 ) 941 ); 942 943 $processor = new WP_HTML_Tag_Processor( $block_content ); 944 if ( $processor->next_tag() ) { 945 $processor->add_class( $unique_class ); 946 } 947 return $processor->get_updated_html(); 948 } 949 add_filter( 'render_block', 'wp_render_block_states_support', 10, 2 );
title
Description
Body
title
Description
Body
title
Description
Body
title
Body
| Generated : Sat Nov 21 08:20:02 2026 | Cross-referenced by PHPXref |