| [ 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 $state_style State style object. 318 * @param array $block_selectors Block selectors metadata. 319 * @return array[] Selector/style groups. 320 */ 321 function wp_get_state_style_groups( $state_style, $block_selectors ) { 322 $groups = array(); 323 324 foreach ( $state_style as $feature => $feature_styles ) { 325 $feature_selectors = $block_selectors[ $feature ] ?? null; 326 327 if ( is_string( $feature_selectors ) ) { 328 wp_add_state_style_group( 329 $groups, 330 $feature_selectors, 331 array( $feature => $feature_styles ) 332 ); 333 continue; 334 } 335 336 if ( is_array( $feature_selectors ) && is_array( $feature_styles ) ) { 337 $remaining_styles = $feature_styles; 338 339 foreach ( $feature_selectors as $subfeature => $subfeature_selector ) { 340 if ( 341 'root' === $subfeature || 342 ! is_string( $subfeature_selector ) || 343 ! array_key_exists( $subfeature, $feature_styles ) 344 ) { 345 continue; 346 } 347 348 wp_add_state_style_group( 349 $groups, 350 $subfeature_selector, 351 array( 352 $feature => array( 353 $subfeature => $feature_styles[ $subfeature ], 354 ), 355 ) 356 ); 357 unset( $remaining_styles[ $subfeature ] ); 358 } 359 360 if ( array() !== $remaining_styles ) { 361 wp_add_state_style_group( 362 $groups, 363 $feature_selectors['root'] ?? ( $block_selectors['root'] ?? null ), 364 array( $feature => $remaining_styles ) 365 ); 366 } 367 continue; 368 } 369 370 wp_add_state_style_group( 371 $groups, 372 $block_selectors['root'] ?? null, 373 array( $feature => $feature_styles ) 374 ); 375 } 376 377 return array_values( $groups ); 378 } 379 380 /** 381 * Returns a style object with nested state keys removed. 382 * 383 * @since 7.1.0 384 * 385 * @param array $state_style State style object. 386 * @param array $nested_keys Keys to remove from the root style object. 387 * @return array Root-only style object. 388 */ 389 function wp_get_root_state_style( $state_style, $nested_keys ) { 390 if ( ! is_array( $state_style ) ) { 391 return $state_style; 392 } 393 394 $root_style = $state_style; 395 foreach ( $nested_keys as $key ) { 396 unset( $root_style[ $key ] ); 397 } 398 399 return $root_style; 400 } 401 402 /** 403 * Generates all element selectors for a block root selector. 404 * 405 * @since 7.1.0 406 * 407 * @param string $root_selector The block root CSS selector. 408 * @return string[] Element selectors keyed by element name. 409 */ 410 function wp_get_block_state_element_selectors( $root_selector ) { 411 if ( ! is_string( $root_selector ) || '' === trim( $root_selector ) ) { 412 return array(); 413 } 414 415 $block_selectors = wp_split_selector_list( $root_selector ); 416 $element_selectors = array(); 417 418 foreach ( WP_Theme_JSON::ELEMENTS as $element_name => $element_selector ) { 419 $selectors = array(); 420 421 foreach ( $block_selectors as $block_selector ) { 422 $block_selector = trim( $block_selector ); 423 if ( '' === $block_selector ) { 424 continue; 425 } 426 427 if ( $block_selector === $element_selector ) { 428 $selectors = array( $element_selector ); 429 break; 430 } 431 432 $selector_prefix = "$block_selector "; 433 if ( ! str_contains( $element_selector, ',' ) ) { 434 $selectors[] = $selector_prefix . $element_selector; 435 continue; 436 } 437 438 $prepended_selectors = array(); 439 foreach ( wp_split_selector_list( $element_selector ) as $selector ) { 440 $prepended_selectors[] = $selector_prefix . $selector; 441 } 442 $selectors[] = implode( ',', $prepended_selectors ); 443 } 444 445 if ( ! empty( $selectors ) ) { 446 $element_selectors[ $element_name ] = implode( ',', $selectors ); 447 } 448 } 449 450 return $element_selectors; 451 } 452 453 /** 454 * Adds a compiled state style rule to a rule list. 455 * 456 * @since 7.1.0 457 * @since 7.2.0 Added fallback dimension styles. 458 * Added the `$base_style` parameter. 459 * 460 * @param array[] $css_rules Style rules. 461 * @param string $state Pseudo-state selector. 462 * @param string|null $selector Block, feature, or element selector. 463 * @param array<string, mixed> $style Style object. 464 * @param string|null $rules_group Optional CSS grouping rule, e.g. a media query. 465 * @param array<string, mixed>|null $base_style Optional styles the state layers over. 466 */ 467 function wp_add_block_state_style_rule( &$css_rules, $state, $selector, $style, $rules_group = null, $base_style = null ) { 468 if ( empty( $style ) || ! is_array( $style ) ) { 469 return; 470 } 471 472 $style = wp_get_state_style_with_fallback_dimension_styles( $style ); 473 474 $compiled = wp_style_engine_get_styles( 475 wp_normalize_state_style_for_css_output( $style ) 476 ); 477 $declarations = $compiled['declarations'] ?? array(); 478 $text_align = $style['typography']['textAlign'] ?? null; 479 // Base text alignment is class-based, so state styles need a declaration. 480 if ( is_string( $text_align ) && '' !== trim( $text_align ) ) { 481 $declarations['text-align'] = $text_align; 482 } 483 484 // Only block states pass a base; element states match the editor and skip it. 485 if ( null !== $base_style ) { 486 $base_clip = $base_style['background']['backgroundClip'] ?? ''; 487 $declarations = array_merge( 488 $declarations, 489 wp_get_state_text_clip_escape( $style, is_string( $base_clip ) ? $base_clip : '' ), 490 wp_get_state_text_fill_reset( $style ) 491 ); 492 } 493 494 if ( empty( $declarations ) ) { 495 return; 496 } 497 498 $css_rules[] = array( 499 'state' => $state, 500 'selector' => $selector, 501 'declarations' => $declarations, 502 ); 503 if ( ! empty( $rules_group ) ) { 504 $css_rules[ count( $css_rules ) - 1 ]['rules_group'] = $rules_group; 505 } 506 } 507 508 /** 509 * Builds compiled state style rules, preserving the selector each rule targets. 510 * 511 * @since 7.1.0 512 * @since 7.2.0 Added the `$base_style` parameter. 513 * 514 * @param array<string, mixed> $state_styles Map of state to style array. 515 * @param WP_Block_Type $block_type Block type. 516 * @param string|null $rules_group Optional CSS grouping rule, e.g. a media query. 517 * @param array<string, mixed>|null $base_style Optional styles the state layers over. 518 * @return array[] State style rules. 519 */ 520 function wp_get_block_state_style_rules( $state_styles, $block_type, $rules_group = null, $base_style = null ) { 521 // Only a block that supports the clip can sit under a text clip to escape. 522 if ( ! block_has_support( $block_type, array( 'background', 'backgroundClip' ), false ) ) { 523 $base_style = null; 524 } 525 526 $css_rules = array(); 527 $block_selectors = is_array( $block_type->selectors ) 528 ? $block_type->selectors 529 : array(); 530 531 foreach ( $state_styles as $state => $state_style ) { 532 if ( empty( $state_style ) || ! is_array( $state_style ) ) { 533 continue; 534 } 535 536 foreach ( wp_get_state_style_groups( $state_style, $block_selectors ) as $group ) { 537 wp_add_block_state_style_rule( 538 $css_rules, 539 $state, 540 $group['selector'], 541 $group['style'], 542 $rules_group, 543 $base_style 544 ); 545 } 546 } 547 548 return $css_rules; 549 } 550 551 /** 552 * Returns a unique class for a set of state style rules. 553 * 554 * @since 7.1.0 555 * 556 * @param string $block_name Block name. 557 * @param array $css_rules State style rules. 558 * @return string Unique class name. 559 */ 560 function wp_get_block_state_unique_class( $block_name, $css_rules ) { 561 return 'wp-states-' . substr( 562 md5( 563 wp_json_encode( 564 array( 565 'blockName' => $block_name, 566 'rules' => $css_rules, 567 ) 568 ) 569 ), 570 0, 571 8 572 ); 573 } 574 575 /** 576 * Splits a selector list by top-level commas. 577 * 578 * @since 7.1.0 579 * 580 * @param string $selector CSS selector list. 581 * @return string[] Selectors. 582 */ 583 function wp_split_selector_list( $selector ) { 584 if ( ! str_contains( $selector, ',' ) ) { 585 return array( $selector ); 586 } 587 588 $selectors = array(); 589 $current_selector = ''; 590 $parentheses_depth = 0; 591 $selector_length = strlen( $selector ); 592 593 for ( $i = 0; $i < $selector_length; $i++ ) { 594 $char = $selector[ $i ]; 595 596 if ( '(' === $char ) { 597 ++$parentheses_depth; 598 } elseif ( ')' === $char && $parentheses_depth > 0 ) { 599 --$parentheses_depth; 600 } elseif ( ',' === $char && 0 === $parentheses_depth ) { 601 $selectors[] = $current_selector; 602 $current_selector = ''; 603 continue; 604 } 605 606 $current_selector .= $char; 607 } 608 609 $selectors[] = $current_selector; 610 611 return $selectors; 612 } 613 614 /** 615 * Returns the ancestor part of a block selector whose leading compound names 616 * a different block, e.g. `.wp-block-list > ` in List Item's `.wp-block-list > li`. 617 * 618 * The block-instance class is on the block's own wrapper, so a leading compound 619 * naming another block must be kept rather than swapped for that class. When the 620 * next compound carries a `wp-block-*` class (`.wp-block-button .wp-block-button__link`), 621 * the selector describes a nested element and keeps the leading swap. 622 * 623 * @since 7.2.0 624 * 625 * @param string $selector A single block or feature selector. 626 * @param string|null $block_name Name of the block being scoped. 627 * @return string The leading compound and its combinator, or an empty string. 628 */ 629 function wp_get_state_selector_ancestor( $selector, $block_name ) { 630 if ( 631 ! is_string( $block_name ) || 632 '' === $block_name || 633 ! preg_match( '/^\.(wp-block-[-_a-zA-Z0-9]+)/', $selector, $matches ) || 634 wp_get_block_default_classname( $block_name ) === $matches[1] 635 ) { 636 return ''; 637 } 638 639 $ancestor_length = 0; 640 $next_compound = ''; 641 $depth = 0; 642 $selector_length = strlen( $selector ); 643 644 for ( $i = 0; $i < $selector_length; $i++ ) { 645 $char = $selector[ $i ]; 646 647 if ( '(' === $char || '[' === $char ) { 648 ++$depth; 649 } elseif ( ( ')' === $char || ']' === $char ) && $depth > 0 ) { 650 --$depth; 651 } elseif ( 0 === $depth && str_contains( " \t\n\r\f>+~", $char ) ) { 652 if ( $ancestor_length ) { 653 break; 654 } 655 $ancestor_length = $i + strspn( $selector, " \t\n\r\f>+~", $i ); 656 $i = $ancestor_length - 1; 657 } elseif ( 0 === $depth && $ancestor_length ) { 658 $next_compound .= $char; 659 } 660 } 661 662 if ( '' === $next_compound || str_contains( $next_compound, '.wp-block-' ) ) { 663 return ''; 664 } 665 666 return substr( $selector, 0, $ancestor_length ); 667 } 668 669 /** 670 * Builds a scoped selector from a block selector and optional pseudo-state. 671 * 672 * @since 7.1.0 673 * @since 7.2.0 Added the `$block_name` parameter. 674 * 675 * @param string $base_selector Block-instance scoping selector. 676 * @param string|null $block_selector Block or feature selector from metadata. 677 * @param string $state Pseudo-state selector. 678 * @param string|null $block_name Optional. Name of the block being scoped. 679 * @return string Scoped selector. 680 */ 681 function wp_build_state_selector( $base_selector, $block_selector, $state, $block_name = null ) { 682 if ( ! is_string( $block_selector ) || '' === trim( $block_selector ) ) { 683 return $base_selector . $state; 684 } 685 686 $selectors = wp_split_selector_list( $block_selector ); 687 $scoped_selectors = array(); 688 689 foreach ( $selectors as $selector ) { 690 $selector = trim( $selector ); 691 if ( '' === $selector ) { 692 continue; 693 } 694 695 $ancestor = wp_get_state_selector_ancestor( $selector, $block_name ); 696 $selector = substr( $selector, strlen( $ancestor ) ); 697 698 /* 699 * Replace only the leading block selector part (e.g. class name, 700 * attribute selector, ID, or tag name) with the block instance selector. 701 * Preserve anything after that prefix, including modifier classes on the 702 * same element and combinators without spaces. 703 */ 704 if ( preg_match( '/^([.#]?[-_a-zA-Z0-9]+|\[[^\]]+\])/', $selector, $matches ) ) { 705 $scoped_selectors[] = $ancestor . $base_selector . substr( $selector, strlen( $matches[0] ) ) . $state; 706 continue; 707 } 708 709 $scoped_selectors[] = $ancestor . $base_selector . $state; 710 } 711 712 return empty( $scoped_selectors ) 713 ? $base_selector . $state 714 : implode( ', ', $scoped_selectors ); 715 } 716 717 /** 718 * Renders per-instance state styles on the frontend. 719 * 720 * @since 7.1.0 721 * 722 * @param string $block_content The block's rendered HTML. 723 * @param array $block The block data including blockName and attrs. 724 * @return string Modified block content with injected state styles. 725 */ 726 function wp_render_block_states_support( $block_content, $block ) { 727 if ( empty( $block['blockName'] ) || empty( $block_content ) ) { 728 return $block_content; 729 } 730 731 /* 732 * Every CSS rule this function can produce is keyed off the block's `style` 733 * attribute. Without it there is nothing to generate, so bail before doing 734 * any of the lookups below — this runs for every block on every request. 735 */ 736 $style = $block['attrs']['style'] ?? array(); 737 if ( empty( $style ) || ! is_array( $style ) ) { 738 return $block_content; 739 } 740 741 $block_name = $block['blockName']; 742 $block_type = WP_Block_Type_Registry::get_instance()->get_registered( $block_name ); 743 if ( ! $block_type ) { 744 return $block_content; 745 } 746 747 $supported_pseudo_states = WP_Theme_JSON::VALID_BLOCK_PSEUDO_SELECTORS[ $block_name ] ?? array(); 748 $css_rules = array(); 749 $default_root_style = wp_get_root_state_style( 750 $style, 751 array_merge( array( 'elements' ), $supported_pseudo_states ) 752 ); 753 $viewport_settings = wp_get_global_settings( array( 'viewport' ) ); 754 $responsive_media_queries = WP_Theme_JSON::get_viewport_media_queries( $viewport_settings ); 755 756 foreach ( $supported_pseudo_states as $pseudo_state ) { 757 if ( empty( $style[ $pseudo_state ] ) || ! is_array( $style[ $pseudo_state ] ) ) { 758 continue; 759 } 760 761 $css_rules = array_merge( 762 $css_rules, 763 wp_get_block_state_style_rules( 764 array( $pseudo_state => $style[ $pseudo_state ] ), 765 $block_type, 766 null, 767 $default_root_style 768 ) 769 ); 770 } 771 772 foreach ( $responsive_media_queries as $breakpoint => $media_query ) { 773 if ( empty( $style[ $breakpoint ] ) || ! is_array( $style[ $breakpoint ] ) ) { 774 continue; 775 } 776 777 $root_state_style = wp_get_root_state_style( 778 $style[ $breakpoint ], 779 array_merge( array( 'elements' ), $supported_pseudo_states ) 780 ); 781 782 if ( ! empty( $root_state_style ) ) { 783 $css_rules = array_merge( 784 $css_rules, 785 wp_get_block_state_style_rules( 786 array( '' => $root_state_style ), 787 $block_type, 788 $media_query, 789 $default_root_style 790 ) 791 ); 792 } 793 794 if ( 795 ! empty( $style[ $breakpoint ]['elements'] ) && 796 is_array( $style[ $breakpoint ]['elements'] ) 797 ) { 798 $element_selectors = wp_get_block_state_element_selectors( 799 wp_get_block_css_selector( $block_type ) 800 ); 801 802 foreach ( $style[ $breakpoint ]['elements'] as $element_name => $element_style ) { 803 if ( 804 empty( $element_style ) || 805 ! is_array( $element_style ) || 806 empty( $element_selectors[ $element_name ] ) 807 ) { 808 continue; 809 } 810 811 $element_pseudo_states = WP_Theme_JSON::VALID_ELEMENT_PSEUDO_SELECTORS[ $element_name ] 812 ?? array(); 813 $root_element_style = wp_get_root_state_style( 814 $element_style, 815 $element_pseudo_states 816 ); 817 818 wp_add_block_state_style_rule( 819 $css_rules, 820 '', 821 $element_selectors[ $element_name ], 822 $root_element_style, 823 $media_query 824 ); 825 826 foreach ( $element_pseudo_states as $pseudo_state ) { 827 if ( 828 empty( $element_style[ $pseudo_state ] ) || 829 ! is_array( $element_style[ $pseudo_state ] ) 830 ) { 831 continue; 832 } 833 834 wp_add_block_state_style_rule( 835 $css_rules, 836 $pseudo_state, 837 $element_selectors[ $element_name ], 838 $element_style[ $pseudo_state ], 839 $media_query 840 ); 841 } 842 } 843 } 844 845 foreach ( $supported_pseudo_states as $pseudo_state ) { 846 if ( empty( $style[ $breakpoint ][ $pseudo_state ] ) || ! is_array( $style[ $breakpoint ][ $pseudo_state ] ) ) { 847 continue; 848 } 849 850 $css_rules = array_merge( 851 $css_rules, 852 wp_get_block_state_style_rules( 853 array( $pseudo_state => $style[ $breakpoint ][ $pseudo_state ] ), 854 $block_type, 855 $media_query, 856 wp_merge_state_style_objects( 857 $default_root_style, 858 $root_state_style 859 ) 860 ) 861 ); 862 } 863 } 864 865 if ( empty( $css_rules ) ) { 866 return $block_content; 867 } 868 869 $unique_class = wp_get_block_state_unique_class( $block_name, $css_rules ); 870 871 /* 872 * Register each state's CSS rules with the block-supports style engine store. 873 * The store deduplicates rules by selector — two block instances with identical 874 * state styles share the same hash class and therefore the same selector, 875 * so only one CSS rule is emitted. The store is flushed to the page by 876 * wp_enqueue_stored_styles() rather than injected inline here. 877 * 878 * State declarations need !important to apply reliably over inline styles and 879 * preset utility classes such as .has-accent-3-background-color. 880 * 881 * Layout-driven state styles (responsive layout, blockGap, child layout) are 882 * handled by wp_render_layout_support_flag() so they share a selector with 883 * the base layout and target the correct (inner) wrapper element. 884 */ 885 $style_rules = array(); 886 foreach ( $css_rules as $rule ) { 887 $declarations = $rule['declarations']; 888 $important_declaration_values = wp_get_state_declarations_with_background_resets( $declarations ); 889 $important_declarations = new WP_Style_Engine_CSS_Declarations(); 890 foreach ( $important_declaration_values as $property => $value ) { 891 $important_declarations->add_declaration( 892 $property, 893 $value, 894 array( 895 'important' => true, 896 ) 897 ); 898 } 899 $selector = wp_build_state_selector( 900 ".$unique_class", 901 $rule['selector'], 902 $rule['state'], 903 $block_name 904 ); 905 $important_style_rule = array( 906 'selector' => $selector, 907 'declarations' => $important_declarations, 908 ); 909 if ( ! empty( $rule['rules_group'] ) ) { 910 $important_style_rule['rules_group'] = $rule['rules_group']; 911 } 912 $style_rules[] = $important_style_rule; 913 914 $fallback_declarations = wp_get_state_declarations_with_fallback_border_styles( $declarations ); 915 foreach ( array_keys( $declarations ) as $property ) { 916 unset( $fallback_declarations[ $property ] ); 917 } 918 919 if ( empty( $fallback_declarations ) ) { 920 continue; 921 } 922 923 $fallback_style_rule = array( 924 'selector' => $selector, 925 'declarations' => $fallback_declarations, 926 ); 927 if ( ! empty( $rule['rules_group'] ) ) { 928 $fallback_style_rule['rules_group'] = $rule['rules_group']; 929 } 930 $style_rules[] = $fallback_style_rule; 931 } 932 933 wp_style_engine_get_stylesheet_from_css_rules( 934 $style_rules, 935 array( 936 'context' => 'block-supports', 937 'prettify' => false, 938 ) 939 ); 940 941 $processor = new WP_HTML_Tag_Processor( $block_content ); 942 if ( $processor->next_tag() ) { 943 $processor->add_class( $unique_class ); 944 } 945 return $processor->get_updated_html(); 946 } 947 add_filter( 'render_block', 'wp_render_block_states_support', 10, 2 );
title
Description
Body
title
Description
Body
title
Description
Body
title
Body
| Generated : Sun Nov 1 08:20:35 2026 | Cross-referenced by PHPXref |