[ Index ]

PHP Cross Reference of WordPress Trunk (Updated Daily)

Search

title

Body

[close]

/wp-includes/block-supports/ -> states.php (source)

   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 );


Generated : Sat Nov 21 08:20:02 2026 Cross-referenced by PHPXref