| [ Index ] |
PHP Cross Reference of WordPress Trunk (Updated Daily) |
[Summary view] [Print] [Text view]
1 <?php 2 /** 3 * WP_Theme_JSON class 4 * 5 * @package WordPress 6 * @subpackage Theme 7 * @since 5.8.0 8 */ 9 10 /** 11 * Class that encapsulates the processing of structures that adhere to the theme.json spec. 12 * 13 * This class is for internal core usage and is not supposed to be used by extenders (plugins and/or themes). 14 * This is a low-level API that may need to do breaking changes. Please, 15 * use get_global_settings, get_global_styles, and get_global_stylesheet instead. 16 * 17 * @access private 18 */ 19 #[AllowDynamicProperties] 20 class WP_Theme_JSON { 21 22 /** 23 * Container of data in theme.json format. 24 * 25 * @since 5.8.0 26 * @var array 27 */ 28 protected $theme_json = null; 29 30 /** 31 * Holds block metadata extracted from block.json 32 * to be shared among all instances so we don't 33 * process it twice. 34 * 35 * @since 5.8.0 36 * @since 6.1.0 Initialize as an empty array. 37 * @var array 38 */ 39 protected static $blocks_metadata = array(); 40 41 /** 42 * The CSS selector for the top-level preset settings. 43 * 44 * @since 6.6.0 45 * @var string 46 */ 47 const ROOT_CSS_PROPERTIES_SELECTOR = ':root'; 48 49 /** 50 * The CSS selector for the top-level styles. 51 * 52 * @since 5.8.0 53 * @var string 54 */ 55 const ROOT_BLOCK_SELECTOR = 'body'; 56 57 /** 58 * The sources of data this object can represent. 59 * 60 * @since 5.8.0 61 * @since 6.1.0 Added 'blocks'. 62 * @var string[] 63 */ 64 const VALID_ORIGINS = array( 65 'default', 66 'blocks', 67 'theme', 68 'custom', 69 ); 70 71 /** 72 * Presets are a set of values that serve 73 * to bootstrap some styles: colors, font sizes, etc. 74 * 75 * They are a unkeyed array of values such as: 76 * 77 * array( 78 * array( 79 * 'slug' => 'unique-name-within-the-set', 80 * 'name' => 'Name for the UI', 81 * <value_key> => 'value' 82 * ), 83 * ) 84 * 85 * This contains the necessary metadata to process them: 86 * 87 * - path => Where to find the preset within the settings section. 88 * - prevent_override => Disables override of default presets by theme presets. 89 * The relationship between whether to override the defaults 90 * and whether the defaults are enabled is inverse: 91 * - If defaults are enabled => theme presets should not be overridden 92 * - If defaults are disabled => theme presets should be overridden 93 * For example, a theme sets defaultPalette to false, 94 * making the default palette hidden from the user. 95 * In that case, we want all the theme presets to be present, 96 * so they should override the defaults by setting this false. 97 * - use_default_names => whether to use the default names 98 * - value_key => the key that represents the value 99 * - value_func => optionally, instead of value_key, a function to generate 100 * the value that takes a preset as an argument 101 * (either value_key or value_func should be present) 102 * - css_vars => template string to use in generating the CSS Custom Property. 103 * Example output: "--wp--preset--duotone--blue: <value>" will generate as many CSS Custom Properties as presets defined 104 * substituting the $slug for the slug's value for each preset value. 105 * - classes => array containing a structure with the classes to 106 * generate for the presets, where for each array item 107 * the key is the class name and the value the property name. 108 * The "$slug" substring will be replaced by the slug of each preset. 109 * For example: 110 * 'classes' => array( 111 * '.has-$slug-color' => 'color', 112 * '.has-$slug-background-color' => 'background-color', 113 * '.has-$slug-border-color' => 'border-color', 114 * ) 115 * - properties => array of CSS properties to be used by kses to 116 * validate the content of each preset 117 * by means of the remove_insecure_properties method. 118 * 119 * @since 5.8.0 120 * @since 5.9.0 Added the `color.duotone` and `typography.fontFamilies` presets, 121 * `use_default_names` preset key, and simplified the metadata structure. 122 * @since 6.0.0 Replaced `override` with `prevent_override` and updated the 123 * `prevent_override` value for `color.duotone` to use `color.defaultDuotone`. 124 * @since 6.2.0 Added 'shadow' presets. 125 * @since 6.3.0 Replaced value_func for duotone with `null`. Custom properties are handled by class-wp-duotone.php. 126 * @since 6.6.0 Added the `dimensions.aspectRatios` and `dimensions.defaultAspectRatios` presets. 127 * Updated the 'prevent_override' value for font size presets to use 'typography.defaultFontSizes' 128 * and spacing size presets to use `spacing.defaultSpacingSizes`. 129 * @var array 130 */ 131 const PRESETS_METADATA = array( 132 array( 133 'path' => array( 'dimensions', 'aspectRatios' ), 134 'prevent_override' => array( 'dimensions', 'defaultAspectRatios' ), 135 'use_default_names' => false, 136 'value_key' => 'ratio', 137 'css_vars' => '--wp--preset--aspect-ratio--$slug', 138 'classes' => array(), 139 'properties' => array( 'aspect-ratio' ), 140 ), 141 array( 142 'path' => array( 'color', 'palette' ), 143 'prevent_override' => array( 'color', 'defaultPalette' ), 144 'use_default_names' => false, 145 'value_key' => 'color', 146 'css_vars' => '--wp--preset--color--$slug', 147 'classes' => array( 148 '.has-$slug-color' => 'color', 149 '.has-$slug-background-color' => 'background-color', 150 '.has-$slug-border-color' => 'border-color', 151 ), 152 'properties' => array( 'color', 'background-color', 'border-color' ), 153 ), 154 array( 155 'path' => array( 'color', 'gradients' ), 156 'prevent_override' => array( 'color', 'defaultGradients' ), 157 'use_default_names' => false, 158 'value_key' => 'gradient', 159 'css_vars' => '--wp--preset--gradient--$slug', 160 'classes' => array( '.has-$slug-gradient-background' => 'background' ), 161 'properties' => array( 'background' ), 162 ), 163 array( 164 'path' => array( 'color', 'duotone' ), 165 'prevent_override' => array( 'color', 'defaultDuotone' ), 166 'use_default_names' => false, 167 'value_func' => null, // CSS Custom Properties for duotone are handled by block supports in class-wp-duotone.php. 168 'css_vars' => null, 169 'classes' => array(), 170 'properties' => array( 'filter' ), 171 ), 172 array( 173 'path' => array( 'typography', 'fontSizes' ), 174 'prevent_override' => array( 'typography', 'defaultFontSizes' ), 175 'use_default_names' => true, 176 'value_func' => 'wp_get_typography_font_size_value', 177 'css_vars' => '--wp--preset--font-size--$slug', 178 'classes' => array( '.has-$slug-font-size' => 'font-size' ), 179 'properties' => array( 'font-size' ), 180 ), 181 array( 182 'path' => array( 'typography', 'fontFamilies' ), 183 'prevent_override' => false, 184 'use_default_names' => false, 185 'value_key' => 'fontFamily', 186 'css_vars' => '--wp--preset--font-family--$slug', 187 'classes' => array( '.has-$slug-font-family' => 'font-family' ), 188 'properties' => array( 'font-family' ), 189 ), 190 array( 191 'path' => array( 'spacing', 'spacingSizes' ), 192 'prevent_override' => array( 'spacing', 'defaultSpacingSizes' ), 193 'use_default_names' => true, 194 'value_key' => 'size', 195 'css_vars' => '--wp--preset--spacing--$slug', 196 'classes' => array(), 197 'properties' => array( 'padding', 'margin' ), 198 ), 199 array( 200 'path' => array( 'shadow', 'presets' ), 201 'prevent_override' => array( 'shadow', 'defaultPresets' ), 202 'use_default_names' => false, 203 'value_key' => 'shadow', 204 'css_vars' => '--wp--preset--shadow--$slug', 205 'classes' => array(), 206 'properties' => array( 'box-shadow' ), 207 ), 208 ); 209 210 /** 211 * Metadata for style properties. 212 * 213 * Each element is a direct mapping from the CSS property name to the 214 * path to the value in theme.json & block attributes. 215 * 216 * @since 5.8.0 217 * @since 5.9.0 Added the `border-*`, `font-family`, `font-style`, `font-weight`, 218 * `letter-spacing`, `margin-*`, `padding-*`, `--wp--style--block-gap`, 219 * `text-decoration`, `text-transform`, and `filter` properties, 220 * simplified the metadata structure. 221 * @since 6.1.0 Added the `border-*-color`, `border-*-width`, `border-*-style`, 222 * `--wp--style--root--padding-*`, and `box-shadow` properties, 223 * removed the `--wp--style--block-gap` property. 224 * @since 6.2.0 Added `outline-*`, and `min-height` properties. 225 * @since 6.3.0 Added `column-count` property. 226 * @since 6.4.0 Added `writing-mode` property. 227 * @since 6.5.0 Added `aspect-ratio` property. 228 * @since 6.6.0 Added `background-[image|position|repeat|size]` properties. 229 * @since 6.7.0 Added `background-attachment` property. 230 * @var array 231 */ 232 const PROPERTIES_METADATA = array( 233 'aspect-ratio' => array( 'dimensions', 'aspectRatio' ), 234 'background' => array( 'color', 'gradient' ), 235 'background-color' => array( 'color', 'background' ), 236 'background-image' => array( 'background', 'backgroundImage' ), 237 'background-position' => array( 'background', 'backgroundPosition' ), 238 'background-repeat' => array( 'background', 'backgroundRepeat' ), 239 'background-size' => array( 'background', 'backgroundSize' ), 240 'background-attachment' => array( 'background', 'backgroundAttachment' ), 241 'border-radius' => array( 'border', 'radius' ), 242 'border-top-left-radius' => array( 'border', 'radius', 'topLeft' ), 243 'border-top-right-radius' => array( 'border', 'radius', 'topRight' ), 244 'border-bottom-left-radius' => array( 'border', 'radius', 'bottomLeft' ), 245 'border-bottom-right-radius' => array( 'border', 'radius', 'bottomRight' ), 246 'border-color' => array( 'border', 'color' ), 247 'border-width' => array( 'border', 'width' ), 248 'border-style' => array( 'border', 'style' ), 249 'border-top-color' => array( 'border', 'top', 'color' ), 250 'border-top-width' => array( 'border', 'top', 'width' ), 251 'border-top-style' => array( 'border', 'top', 'style' ), 252 'border-right-color' => array( 'border', 'right', 'color' ), 253 'border-right-width' => array( 'border', 'right', 'width' ), 254 'border-right-style' => array( 'border', 'right', 'style' ), 255 'border-bottom-color' => array( 'border', 'bottom', 'color' ), 256 'border-bottom-width' => array( 'border', 'bottom', 'width' ), 257 'border-bottom-style' => array( 'border', 'bottom', 'style' ), 258 'border-left-color' => array( 'border', 'left', 'color' ), 259 'border-left-width' => array( 'border', 'left', 'width' ), 260 'border-left-style' => array( 'border', 'left', 'style' ), 261 'color' => array( 'color', 'text' ), 262 'text-align' => array( 'typography', 'textAlign' ), 263 'column-count' => array( 'typography', 'textColumns' ), 264 'font-family' => array( 'typography', 'fontFamily' ), 265 'font-size' => array( 'typography', 'fontSize' ), 266 'font-style' => array( 'typography', 'fontStyle' ), 267 'font-weight' => array( 'typography', 'fontWeight' ), 268 'letter-spacing' => array( 'typography', 'letterSpacing' ), 269 'line-height' => array( 'typography', 'lineHeight' ), 270 'margin' => array( 'spacing', 'margin' ), 271 'margin-top' => array( 'spacing', 'margin', 'top' ), 272 'margin-right' => array( 'spacing', 'margin', 'right' ), 273 'margin-bottom' => array( 'spacing', 'margin', 'bottom' ), 274 'margin-left' => array( 'spacing', 'margin', 'left' ), 275 'min-height' => array( 'dimensions', 'minHeight' ), 276 'outline-color' => array( 'outline', 'color' ), 277 'outline-offset' => array( 'outline', 'offset' ), 278 'outline-style' => array( 'outline', 'style' ), 279 'outline-width' => array( 'outline', 'width' ), 280 'padding' => array( 'spacing', 'padding' ), 281 'padding-top' => array( 'spacing', 'padding', 'top' ), 282 'padding-right' => array( 'spacing', 'padding', 'right' ), 283 'padding-bottom' => array( 'spacing', 'padding', 'bottom' ), 284 'padding-left' => array( 'spacing', 'padding', 'left' ), 285 '--wp--style--root--padding' => array( 'spacing', 'padding' ), 286 '--wp--style--root--padding-top' => array( 'spacing', 'padding', 'top' ), 287 '--wp--style--root--padding-right' => array( 'spacing', 'padding', 'right' ), 288 '--wp--style--root--padding-bottom' => array( 'spacing', 'padding', 'bottom' ), 289 '--wp--style--root--padding-left' => array( 'spacing', 'padding', 'left' ), 290 'text-decoration' => array( 'typography', 'textDecoration' ), 291 'text-transform' => array( 'typography', 'textTransform' ), 292 'filter' => array( 'filter', 'duotone' ), 293 'box-shadow' => array( 'shadow' ), 294 'writing-mode' => array( 'typography', 'writingMode' ), 295 ); 296 297 /** 298 * Indirect metadata for style properties that are not directly output. 299 * 300 * Each element maps from a CSS property name to an array of 301 * paths to the value in theme.json & block attributes. 302 * 303 * Indirect properties are not output directly by `compute_style_properties`, 304 * but are used elsewhere in the processing of global styles. The indirect 305 * property is used to validate whether a style value is allowed. 306 * 307 * @since 6.2.0 308 * @since 6.6.0 Added background-image properties. 309 * @var array 310 */ 311 const INDIRECT_PROPERTIES_METADATA = array( 312 'gap' => array( 313 array( 'spacing', 'blockGap' ), 314 ), 315 'column-gap' => array( 316 array( 'spacing', 'blockGap', 'left' ), 317 ), 318 'row-gap' => array( 319 array( 'spacing', 'blockGap', 'top' ), 320 ), 321 'max-width' => array( 322 array( 'layout', 'contentSize' ), 323 array( 'layout', 'wideSize' ), 324 ), 325 'background-image' => array( 326 array( 'background', 'backgroundImage', 'url' ), 327 ), 328 ); 329 330 /** 331 * Protected style properties. 332 * 333 * These style properties are only rendered if a setting enables it 334 * via a value other than `null`. 335 * 336 * Each element maps the style property to the corresponding theme.json 337 * setting key. 338 * 339 * @since 5.9.0 340 * @var array 341 */ 342 const PROTECTED_PROPERTIES = array( 343 'spacing.blockGap' => array( 'spacing', 'blockGap' ), 344 ); 345 346 /** 347 * The top-level keys a theme.json can have. 348 * 349 * @since 5.8.0 As `ALLOWED_TOP_LEVEL_KEYS`. 350 * @since 5.9.0 Renamed from `ALLOWED_TOP_LEVEL_KEYS` to `VALID_TOP_LEVEL_KEYS`, 351 * added the `customTemplates` and `templateParts` values. 352 * @since 6.3.0 Added the `description` value. 353 * @since 6.6.0 Added `blockTypes` to support block style variation theme.json partials. 354 * @var string[] 355 */ 356 const VALID_TOP_LEVEL_KEYS = array( 357 'blockTypes', 358 'customTemplates', 359 'description', 360 'patterns', 361 'settings', 362 'slug', 363 'styles', 364 'templateParts', 365 'title', 366 'version', 367 ); 368 369 /** 370 * The valid properties under the settings key. 371 * 372 * @since 5.8.0 As `ALLOWED_SETTINGS`. 373 * @since 5.9.0 Renamed from `ALLOWED_SETTINGS` to `VALID_SETTINGS`, 374 * added new properties for `border`, `color`, `spacing`, 375 * and `typography`, and renamed others according to the new schema. 376 * @since 6.0.0 Added `color.defaultDuotone`. 377 * @since 6.1.0 Added `layout.definitions` and `useRootPaddingAwareAlignments`. 378 * @since 6.2.0 Added `dimensions.minHeight`, 'shadow.presets', 'shadow.defaultPresets', 379 * `position.fixed` and `position.sticky`. 380 * @since 6.3.0 Added support for `typography.textColumns`, removed `layout.definitions`. 381 * @since 6.4.0 Added support for `layout.allowEditing`, `background.backgroundImage`, 382 * `typography.writingMode`, `lightbox.enabled` and `lightbox.allowEditing`. 383 * @since 6.5.0 Added support for `layout.allowCustomContentAndWideSize`, 384 * `background.backgroundSize` and `dimensions.aspectRatio`. 385 * @since 6.6.0 Added support for 'dimensions.aspectRatios', 'dimensions.defaultAspectRatios', 386 * 'typography.defaultFontSizes', and 'spacing.defaultSpacingSizes'. 387 * @var array 388 */ 389 const VALID_SETTINGS = array( 390 'appearanceTools' => null, 391 'useRootPaddingAwareAlignments' => null, 392 'background' => array( 393 'backgroundImage' => null, 394 'backgroundSize' => null, 395 ), 396 'border' => array( 397 'color' => null, 398 'radius' => null, 399 'style' => null, 400 'width' => null, 401 ), 402 'color' => array( 403 'background' => null, 404 'custom' => null, 405 'customDuotone' => null, 406 'customGradient' => null, 407 'defaultDuotone' => null, 408 'defaultGradients' => null, 409 'defaultPalette' => null, 410 'duotone' => null, 411 'gradients' => null, 412 'link' => null, 413 'heading' => null, 414 'button' => null, 415 'caption' => null, 416 'palette' => null, 417 'text' => null, 418 ), 419 'custom' => null, 420 'dimensions' => array( 421 'aspectRatio' => null, 422 'aspectRatios' => null, 423 'defaultAspectRatios' => null, 424 'minHeight' => null, 425 ), 426 'layout' => array( 427 'contentSize' => null, 428 'wideSize' => null, 429 'allowEditing' => null, 430 'allowCustomContentAndWideSize' => null, 431 ), 432 'lightbox' => array( 433 'enabled' => null, 434 'allowEditing' => null, 435 ), 436 'position' => array( 437 'fixed' => null, 438 'sticky' => null, 439 ), 440 'spacing' => array( 441 'customSpacingSize' => null, 442 'defaultSpacingSizes' => null, 443 'spacingSizes' => null, 444 'spacingScale' => null, 445 'blockGap' => null, 446 'margin' => null, 447 'padding' => null, 448 'units' => null, 449 ), 450 'shadow' => array( 451 'presets' => null, 452 'defaultPresets' => null, 453 ), 454 'typography' => array( 455 'fluid' => null, 456 'customFontSize' => null, 457 'defaultFontSizes' => null, 458 'dropCap' => null, 459 'fontFamilies' => null, 460 'fontSizes' => null, 461 'fontStyle' => null, 462 'fontWeight' => null, 463 'letterSpacing' => null, 464 'lineHeight' => null, 465 'textAlign' => null, 466 'textColumns' => null, 467 'textDecoration' => null, 468 'textTransform' => null, 469 'writingMode' => null, 470 ), 471 ); 472 473 /** 474 * The valid properties for fontFamilies under settings key. 475 * 476 * @since 6.5.0 477 * @var array 478 */ 479 const FONT_FAMILY_SCHEMA = array( 480 array( 481 'fontFamily' => null, 482 'name' => null, 483 'slug' => null, 484 'fontFace' => array( 485 array( 486 'ascentOverride' => null, 487 'descentOverride' => null, 488 'fontDisplay' => null, 489 'fontFamily' => null, 490 'fontFeatureSettings' => null, 491 'fontStyle' => null, 492 'fontStretch' => null, 493 'fontVariationSettings' => null, 494 'fontWeight' => null, 495 'lineGapOverride' => null, 496 'sizeAdjust' => null, 497 'src' => null, 498 'unicodeRange' => null, 499 ), 500 ), 501 ), 502 ); 503 504 /** 505 * The valid properties under the styles key. 506 * 507 * @since 5.8.0 As `ALLOWED_STYLES`. 508 * @since 5.9.0 Renamed from `ALLOWED_STYLES` to `VALID_STYLES`, 509 * added new properties for `border`, `filter`, `spacing`, 510 * and `typography`. 511 * @since 6.1.0 Added new side properties for `border`, 512 * added new property `shadow`, 513 * updated `blockGap` to be allowed at any level. 514 * @since 6.2.0 Added `outline`, and `minHeight` properties. 515 * @since 6.3.0 Added support for `typography.textColumns`. 516 * @since 6.5.0 Added support for `dimensions.aspectRatio`. 517 * @since 6.6.0 Added `background` sub properties to top-level only. 518 * @var array 519 */ 520 const VALID_STYLES = array( 521 'background' => array( 522 'backgroundImage' => null, 523 'backgroundPosition' => null, 524 'backgroundRepeat' => null, 525 'backgroundSize' => null, 526 'backgroundAttachment' => null, 527 ), 528 'border' => array( 529 'color' => null, 530 'radius' => null, 531 'style' => null, 532 'width' => null, 533 'top' => null, 534 'right' => null, 535 'bottom' => null, 536 'left' => null, 537 ), 538 'color' => array( 539 'background' => null, 540 'gradient' => null, 541 'text' => null, 542 ), 543 'dimensions' => array( 544 'aspectRatio' => null, 545 'minHeight' => null, 546 ), 547 'filter' => array( 548 'duotone' => null, 549 ), 550 'outline' => array( 551 'color' => null, 552 'offset' => null, 553 'style' => null, 554 'width' => null, 555 ), 556 'shadow' => null, 557 'spacing' => array( 558 'margin' => null, 559 'padding' => null, 560 'blockGap' => null, 561 ), 562 'typography' => array( 563 'fontFamily' => null, 564 'fontSize' => null, 565 'fontStyle' => null, 566 'fontWeight' => null, 567 'letterSpacing' => null, 568 'lineHeight' => null, 569 'textAlign' => null, 570 'textColumns' => null, 571 'textDecoration' => null, 572 'textTransform' => null, 573 'writingMode' => null, 574 ), 575 'css' => null, 576 ); 577 578 /** 579 * Defines which pseudo selectors are enabled for which elements. 580 * 581 * The order of the selectors should be: link, any-link, visited, hover, focus, focus-visible, active. 582 * This is to ensure the user action (hover, focus and active) styles have a higher 583 * specificity than the visited styles, which in turn have a higher specificity than 584 * the unvisited styles. 585 * 586 * See https://core.trac.wordpress.org/ticket/56928. 587 * Note: this will affect both top-level and block-level elements. 588 * 589 * @since 6.1.0 590 * @since 6.2.0 Added support for ':link' and ':any-link'. 591 * @since 6.8.0 Added support for ':focus-visible'. 592 * @var array 593 */ 594 const VALID_ELEMENT_PSEUDO_SELECTORS = array( 595 'link' => array( ':link', ':any-link', ':visited', ':hover', ':focus', ':focus-visible', ':active' ), 596 'button' => array( ':link', ':any-link', ':visited', ':hover', ':focus', ':focus-visible', ':active' ), 597 ); 598 599 /** 600 * The valid elements that can be found under styles. 601 * 602 * @since 5.8.0 603 * @since 6.1.0 Added `heading`, `button`, and `caption` elements. 604 * @var string[] 605 */ 606 const ELEMENTS = array( 607 'link' => 'a:where(:not(.wp-element-button))', // The `where` is needed to lower the specificity. 608 'heading' => 'h1, h2, h3, h4, h5, h6', 609 'h1' => 'h1', 610 'h2' => 'h2', 611 'h3' => 'h3', 612 'h4' => 'h4', 613 'h5' => 'h5', 614 'h6' => 'h6', 615 // We have the .wp-block-button__link class so that this will target older buttons that have been serialized. 616 'button' => '.wp-element-button, .wp-block-button__link', 617 // The block classes are necessary to target older content that won't use the new class names. 618 'caption' => '.wp-element-caption, .wp-block-audio figcaption, .wp-block-embed figcaption, .wp-block-gallery figcaption, .wp-block-image figcaption, .wp-block-table figcaption, .wp-block-video figcaption', 619 'cite' => 'cite', 620 ); 621 622 const __EXPERIMENTAL_ELEMENT_CLASS_NAMES = array( 623 'button' => 'wp-element-button', 624 'caption' => 'wp-element-caption', 625 ); 626 627 /** 628 * List of block support features that can have their related styles 629 * generated under their own feature level selector rather than the block's. 630 * 631 * @since 6.1.0 632 * @var string[] 633 */ 634 const BLOCK_SUPPORT_FEATURE_LEVEL_SELECTORS = array( 635 '__experimentalBorder' => 'border', 636 'color' => 'color', 637 'spacing' => 'spacing', 638 'typography' => 'typography', 639 ); 640 641 /** 642 * Return the input schema at the root and per origin. 643 * 644 * @since 6.5.0 645 * 646 * @param array $schema The base schema. 647 * @return array The schema at the root and per origin. 648 * 649 * Example: 650 * schema_in_root_and_per_origin( 651 * array( 652 * 'fontFamily' => null, 653 * 'slug' => null, 654 * ) 655 * ) 656 * 657 * Returns: 658 * array( 659 * 'fontFamily' => null, 660 * 'slug' => null, 661 * 'default' => array( 662 * 'fontFamily' => null, 663 * 'slug' => null, 664 * ), 665 * 'blocks' => array( 666 * 'fontFamily' => null, 667 * 'slug' => null, 668 * ), 669 * 'theme' => array( 670 * 'fontFamily' => null, 671 * 'slug' => null, 672 * ), 673 * 'custom' => array( 674 * 'fontFamily' => null, 675 * 'slug' => null, 676 * ), 677 * ) 678 */ 679 protected static function schema_in_root_and_per_origin( $schema ) { 680 $schema_in_root_and_per_origin = $schema; 681 foreach ( static::VALID_ORIGINS as $origin ) { 682 $schema_in_root_and_per_origin[ $origin ] = $schema; 683 } 684 return $schema_in_root_and_per_origin; 685 } 686 687 /** 688 * Returns a class name by an element name. 689 * 690 * @since 6.1.0 691 * 692 * @param string $element The name of the element. 693 * @return string The name of the class. 694 */ 695 public static function get_element_class_name( $element ) { 696 $class_name = ''; 697 698 if ( isset( static::__EXPERIMENTAL_ELEMENT_CLASS_NAMES[ $element ] ) ) { 699 $class_name = static::__EXPERIMENTAL_ELEMENT_CLASS_NAMES[ $element ]; 700 } 701 702 return $class_name; 703 } 704 705 /** 706 * Options that settings.appearanceTools enables. 707 * 708 * @since 6.0.0 709 * @since 6.2.0 Added `dimensions.minHeight` and `position.sticky`. 710 * @since 6.4.0 Added `background.backgroundImage`. 711 * @since 6.5.0 Added `background.backgroundSize` and `dimensions.aspectRatio`. 712 * @var array 713 */ 714 const APPEARANCE_TOOLS_OPT_INS = array( 715 array( 'background', 'backgroundImage' ), 716 array( 'background', 'backgroundSize' ), 717 array( 'border', 'color' ), 718 array( 'border', 'radius' ), 719 array( 'border', 'style' ), 720 array( 'border', 'width' ), 721 array( 'color', 'link' ), 722 array( 'color', 'heading' ), 723 array( 'color', 'button' ), 724 array( 'color', 'caption' ), 725 array( 'dimensions', 'aspectRatio' ), 726 array( 'dimensions', 'minHeight' ), 727 array( 'position', 'sticky' ), 728 array( 'spacing', 'blockGap' ), 729 array( 'spacing', 'margin' ), 730 array( 'spacing', 'padding' ), 731 array( 'typography', 'lineHeight' ), 732 ); 733 734 /** 735 * The latest version of the schema in use. 736 * 737 * @since 5.8.0 738 * @since 5.9.0 Changed value from 1 to 2. 739 * @since 6.6.0 Changed value from 2 to 3. 740 * @var int 741 */ 742 const LATEST_SCHEMA = 3; 743 744 /** 745 * Constructor. 746 * 747 * @since 5.8.0 748 * @since 6.6.0 Key spacingScale by origin, and Pre-generate the spacingSizes from spacingScale. 749 * Added unwrapping of shared block style variations into block type variations if registered. 750 * 751 * @param array $theme_json A structure that follows the theme.json schema. 752 * @param string $origin Optional. What source of data this object represents. 753 * One of 'blocks', 'default', 'theme', or 'custom'. Default 'theme'. 754 */ 755 public function __construct( $theme_json = array( 'version' => self::LATEST_SCHEMA ), $origin = 'theme' ) { 756 if ( ! in_array( $origin, static::VALID_ORIGINS, true ) ) { 757 $origin = 'theme'; 758 } 759 760 $this->theme_json = WP_Theme_JSON_Schema::migrate( $theme_json, $origin ); 761 $blocks_metadata = static::get_blocks_metadata(); 762 $valid_block_names = array_keys( $blocks_metadata ); 763 $valid_element_names = array_keys( static::ELEMENTS ); 764 $valid_variations = static::get_valid_block_style_variations( $blocks_metadata ); 765 $this->theme_json = static::unwrap_shared_block_style_variations( $this->theme_json, $valid_variations ); 766 $this->theme_json = static::sanitize( $this->theme_json, $valid_block_names, $valid_element_names, $valid_variations ); 767 $this->theme_json = static::maybe_opt_in_into_settings( $this->theme_json ); 768 769 // Internally, presets are keyed by origin. 770 $nodes = static::get_setting_nodes( $this->theme_json ); 771 foreach ( $nodes as $node ) { 772 foreach ( static::PRESETS_METADATA as $preset_metadata ) { 773 $path = $node['path']; 774 foreach ( $preset_metadata['path'] as $subpath ) { 775 $path[] = $subpath; 776 } 777 $preset = _wp_array_get( $this->theme_json, $path, null ); 778 if ( null !== $preset ) { 779 // If the preset is not already keyed by origin. 780 if ( isset( $preset[0] ) || empty( $preset ) ) { 781 _wp_array_set( $this->theme_json, $path, array( $origin => $preset ) ); 782 } 783 } 784 } 785 } 786 787 // In addition to presets, spacingScale (which generates presets) is also keyed by origin. 788 $scale_path = array( 'settings', 'spacing', 'spacingScale' ); 789 $spacing_scale = _wp_array_get( $this->theme_json, $scale_path, null ); 790 if ( null !== $spacing_scale ) { 791 // If the spacingScale is not already keyed by origin. 792 if ( empty( array_intersect( array_keys( $spacing_scale ), static::VALID_ORIGINS ) ) ) { 793 _wp_array_set( $this->theme_json, $scale_path, array( $origin => $spacing_scale ) ); 794 } 795 } 796 797 // Pre-generate the spacingSizes from spacingScale. 798 $scale_path = array( 'settings', 'spacing', 'spacingScale', $origin ); 799 $spacing_scale = _wp_array_get( $this->theme_json, $scale_path, null ); 800 if ( isset( $spacing_scale ) ) { 801 $sizes_path = array( 'settings', 'spacing', 'spacingSizes', $origin ); 802 $spacing_sizes = _wp_array_get( $this->theme_json, $sizes_path, array() ); 803 $spacing_scale_sizes = static::compute_spacing_sizes( $spacing_scale ); 804 $merged_spacing_sizes = static::merge_spacing_sizes( $spacing_scale_sizes, $spacing_sizes ); 805 _wp_array_set( $this->theme_json, $sizes_path, $merged_spacing_sizes ); 806 } 807 } 808 809 /** 810 * Unwraps shared block style variations. 811 * 812 * It takes the shared variations (styles.variations.variationName) and 813 * applies them to all the blocks that have the given variation registered 814 * (styles.blocks.blockType.variations.variationName). 815 * 816 * For example, given the `core/paragraph` and `core/group` blocks have 817 * registered the `section-a` style variation, and given the following input: 818 * 819 * { 820 * "styles": { 821 * "variations": { 822 * "section-a": { "color": { "background": "backgroundColor" } } 823 * } 824 * } 825 * } 826 * 827 * It returns the following output: 828 * 829 * { 830 * "styles": { 831 * "blocks": { 832 * "core/paragraph": { 833 * "variations": { 834 * "section-a": { "color": { "background": "backgroundColor" } } 835 * }, 836 * }, 837 * "core/group": { 838 * "variations": { 839 * "section-a": { "color": { "background": "backgroundColor" } } 840 * } 841 * } 842 * } 843 * } 844 * } 845 * 846 * @since 6.6.0 847 * 848 * @param array $theme_json A structure that follows the theme.json schema. 849 * @param array $valid_variations Valid block style variations. 850 * @return array Theme json data with shared variation definitions unwrapped under appropriate block types. 851 */ 852 private static function unwrap_shared_block_style_variations( $theme_json, $valid_variations ) { 853 if ( empty( $theme_json['styles']['variations'] ) || empty( $valid_variations ) ) { 854 return $theme_json; 855 } 856 857 $new_theme_json = $theme_json; 858 $variations = $new_theme_json['styles']['variations']; 859 860 foreach ( $valid_variations as $block_type => $registered_variations ) { 861 foreach ( $registered_variations as $variation_name ) { 862 $block_level_data = $new_theme_json['styles']['blocks'][ $block_type ]['variations'][ $variation_name ] ?? array(); 863 $top_level_data = $variations[ $variation_name ] ?? array(); 864 $merged_data = array_replace_recursive( $top_level_data, $block_level_data ); 865 if ( ! empty( $merged_data ) ) { 866 _wp_array_set( $new_theme_json, array( 'styles', 'blocks', $block_type, 'variations', $variation_name ), $merged_data ); 867 } 868 } 869 } 870 871 unset( $new_theme_json['styles']['variations'] ); 872 873 return $new_theme_json; 874 } 875 876 /** 877 * Enables some opt-in settings if theme declared support. 878 * 879 * @since 5.9.0 880 * 881 * @param array $theme_json A theme.json structure to modify. 882 * @return array The modified theme.json structure. 883 */ 884 protected static function maybe_opt_in_into_settings( $theme_json ) { 885 $new_theme_json = $theme_json; 886 887 if ( 888 isset( $new_theme_json['settings']['appearanceTools'] ) && 889 true === $new_theme_json['settings']['appearanceTools'] 890 ) { 891 static::do_opt_in_into_settings( $new_theme_json['settings'] ); 892 } 893 894 if ( isset( $new_theme_json['settings']['blocks'] ) && is_array( $new_theme_json['settings']['blocks'] ) ) { 895 foreach ( $new_theme_json['settings']['blocks'] as &$block ) { 896 if ( isset( $block['appearanceTools'] ) && ( true === $block['appearanceTools'] ) ) { 897 static::do_opt_in_into_settings( $block ); 898 } 899 } 900 } 901 902 return $new_theme_json; 903 } 904 905 /** 906 * Enables some settings. 907 * 908 * @since 5.9.0 909 * 910 * @param array $context The context to which the settings belong. 911 */ 912 protected static function do_opt_in_into_settings( &$context ) { 913 foreach ( static::APPEARANCE_TOOLS_OPT_INS as $path ) { 914 /* 915 * Use "unset prop" as a marker instead of "null" because 916 * "null" can be a valid value for some props (e.g. blockGap). 917 */ 918 if ( 'unset prop' === _wp_array_get( $context, $path, 'unset prop' ) ) { 919 _wp_array_set( $context, $path, true ); 920 } 921 } 922 923 unset( $context['appearanceTools'] ); 924 } 925 926 /** 927 * Sanitizes the input according to the schemas. 928 * 929 * @since 5.8.0 930 * @since 5.9.0 Added the `$valid_block_names` and `$valid_element_name` parameters. 931 * @since 6.3.0 Added the `$valid_variations` parameter. 932 * @since 6.6.0 Updated schema to allow extended block style variations. 933 * 934 * @param array $input Structure to sanitize. 935 * @param array $valid_block_names List of valid block names. 936 * @param array $valid_element_names List of valid element names. 937 * @param array $valid_variations List of valid variations per block. 938 * @return array The sanitized output. 939 */ 940 protected static function sanitize( $input, $valid_block_names, $valid_element_names, $valid_variations ) { 941 $output = array(); 942 943 if ( ! is_array( $input ) ) { 944 return $output; 945 } 946 947 // Preserve only the top most level keys. 948 $output = array_intersect_key( $input, array_flip( static::VALID_TOP_LEVEL_KEYS ) ); 949 950 /* 951 * Remove any rules that are annotated as "top" in VALID_STYLES constant. 952 * Some styles are only meant to be available at the top-level (e.g.: blockGap), 953 * hence, the schema for blocks & elements should not have them. 954 */ 955 $styles_non_top_level = static::VALID_STYLES; 956 foreach ( array_keys( $styles_non_top_level ) as $section ) { 957 // array_key_exists() needs to be used instead of isset() because the value can be null. 958 if ( array_key_exists( $section, $styles_non_top_level ) && is_array( $styles_non_top_level[ $section ] ) ) { 959 foreach ( array_keys( $styles_non_top_level[ $section ] ) as $prop ) { 960 if ( 'top' === $styles_non_top_level[ $section ][ $prop ] ) { 961 unset( $styles_non_top_level[ $section ][ $prop ] ); 962 } 963 } 964 } 965 } 966 967 // Build the schema based on valid block & element names. 968 $schema = array(); 969 $schema_styles_elements = array(); 970 971 /* 972 * Set allowed element pseudo selectors based on per element allow list. 973 * Target data structure in schema: 974 * e.g. 975 * - top level elements: `$schema['styles']['elements']['link'][':hover']`. 976 * - block level elements: `$schema['styles']['blocks']['core/button']['elements']['link'][':hover']`. 977 */ 978 foreach ( $valid_element_names as $element ) { 979 $schema_styles_elements[ $element ] = $styles_non_top_level; 980 981 if ( isset( static::VALID_ELEMENT_PSEUDO_SELECTORS[ $element ] ) ) { 982 foreach ( static::VALID_ELEMENT_PSEUDO_SELECTORS[ $element ] as $pseudo_selector ) { 983 $schema_styles_elements[ $element ][ $pseudo_selector ] = $styles_non_top_level; 984 } 985 } 986 } 987 988 $schema_styles_blocks = array(); 989 $schema_settings_blocks = array(); 990 991 /* 992 * Generate a schema for blocks. 993 * - Block styles can contain `elements` & `variations` definitions. 994 * - Variations definitions cannot be nested. 995 * - Variations can contain styles for inner `blocks`. 996 * - Variation inner `blocks` styles can contain `elements`. 997 * 998 * As each variation needs a `blocks` schema but further nested 999 * inner `blocks`, the overall schema will be generated in multiple passes. 1000 */ 1001 foreach ( $valid_block_names as $block ) { 1002 $schema_settings_blocks[ $block ] = static::VALID_SETTINGS; 1003 $schema_styles_blocks[ $block ] = $styles_non_top_level; 1004 $schema_styles_blocks[ $block ]['elements'] = $schema_styles_elements; 1005 } 1006 1007 $block_style_variation_styles = static::VALID_STYLES; 1008 $block_style_variation_styles['blocks'] = $schema_styles_blocks; 1009 $block_style_variation_styles['elements'] = $schema_styles_elements; 1010 1011 foreach ( $valid_block_names as $block ) { 1012 // Build the schema for each block style variation. 1013 $style_variation_names = array(); 1014 if ( 1015 ! empty( $input['styles']['blocks'][ $block ]['variations'] ) && 1016 is_array( $input['styles']['blocks'][ $block ]['variations'] ) && 1017 isset( $valid_variations[ $block ] ) 1018 ) { 1019 $style_variation_names = array_intersect( 1020 array_keys( $input['styles']['blocks'][ $block ]['variations'] ), 1021 $valid_variations[ $block ] 1022 ); 1023 } 1024 1025 $schema_styles_variations = array(); 1026 if ( ! empty( $style_variation_names ) ) { 1027 $schema_styles_variations = array_fill_keys( $style_variation_names, $block_style_variation_styles ); 1028 } 1029 1030 $schema_styles_blocks[ $block ]['variations'] = $schema_styles_variations; 1031 } 1032 1033 $schema['styles'] = static::VALID_STYLES; 1034 $schema['styles']['blocks'] = $schema_styles_blocks; 1035 $schema['styles']['elements'] = $schema_styles_elements; 1036 $schema['settings'] = static::VALID_SETTINGS; 1037 $schema['settings']['blocks'] = $schema_settings_blocks; 1038 $schema['settings']['typography']['fontFamilies'] = static::schema_in_root_and_per_origin( static::FONT_FAMILY_SCHEMA ); 1039 1040 // Remove anything that's not present in the schema. 1041 foreach ( array( 'styles', 'settings' ) as $subtree ) { 1042 if ( ! isset( $input[ $subtree ] ) ) { 1043 continue; 1044 } 1045 1046 if ( ! is_array( $input[ $subtree ] ) ) { 1047 unset( $output[ $subtree ] ); 1048 continue; 1049 } 1050 1051 $result = static::remove_keys_not_in_schema( $input[ $subtree ], $schema[ $subtree ] ); 1052 1053 if ( empty( $result ) ) { 1054 unset( $output[ $subtree ] ); 1055 } else { 1056 $output[ $subtree ] = static::resolve_custom_css_format( $result ); 1057 } 1058 } 1059 1060 return $output; 1061 } 1062 1063 /** 1064 * Appends a sub-selector to an existing one. 1065 * 1066 * Given the compounded $selector "h1, h2, h3" 1067 * and the $to_append selector ".some-class" the result will be 1068 * "h1.some-class, h2.some-class, h3.some-class". 1069 * 1070 * @since 5.8.0 1071 * @since 6.1.0 Added append position. 1072 * @since 6.3.0 Removed append position parameter. 1073 * 1074 * @param string $selector Original selector. 1075 * @param string $to_append Selector to append. 1076 * @return string The new selector. 1077 */ 1078 protected static function append_to_selector( $selector, $to_append ) { 1079 if ( ! str_contains( $selector, ',' ) ) { 1080 return $selector . $to_append; 1081 } 1082 $new_selectors = array(); 1083 $selectors = explode( ',', $selector ); 1084 foreach ( $selectors as $sel ) { 1085 $new_selectors[] = $sel . $to_append; 1086 } 1087 return implode( ',', $new_selectors ); 1088 } 1089 1090 /** 1091 * Prepends a sub-selector to an existing one. 1092 * 1093 * Given the compounded $selector "h1, h2, h3" 1094 * and the $to_prepend selector ".some-class " the result will be 1095 * ".some-class h1, .some-class h2, .some-class h3". 1096 * 1097 * @since 6.3.0 1098 * 1099 * @param string $selector Original selector. 1100 * @param string $to_prepend Selector to prepend. 1101 * @return string The new selector. 1102 */ 1103 protected static function prepend_to_selector( $selector, $to_prepend ) { 1104 if ( ! str_contains( $selector, ',' ) ) { 1105 return $to_prepend . $selector; 1106 } 1107 $new_selectors = array(); 1108 $selectors = explode( ',', $selector ); 1109 foreach ( $selectors as $sel ) { 1110 $new_selectors[] = $to_prepend . $sel; 1111 } 1112 return implode( ',', $new_selectors ); 1113 } 1114 1115 /** 1116 * Returns the metadata for each block. 1117 * 1118 * Example: 1119 * 1120 * { 1121 * 'core/paragraph': { 1122 * 'selector': 'p', 1123 * 'elements': { 1124 * 'link' => 'link selector', 1125 * 'etc' => 'element selector' 1126 * } 1127 * }, 1128 * 'core/heading': { 1129 * 'selector': 'h1', 1130 * 'elements': {} 1131 * }, 1132 * 'core/image': { 1133 * 'selector': '.wp-block-image', 1134 * 'duotone': 'img', 1135 * 'elements': {} 1136 * } 1137 * } 1138 * 1139 * @since 5.8.0 1140 * @since 5.9.0 Added `duotone` key with CSS selector. 1141 * @since 6.1.0 Added `features` key with block support feature level selectors. 1142 * @since 6.3.0 Refactored and stabilized selectors API. 1143 * @since 6.6.0 Updated to include block style variations from the block styles registry. 1144 * 1145 * @return array Block metadata. 1146 */ 1147 protected static function get_blocks_metadata() { 1148 $registry = WP_Block_Type_Registry::get_instance(); 1149 $blocks = $registry->get_all_registered(); 1150 $style_registry = WP_Block_Styles_Registry::get_instance(); 1151 1152 // Is there metadata for all currently registered blocks? 1153 $blocks = array_diff_key( $blocks, static::$blocks_metadata ); 1154 if ( empty( $blocks ) ) { 1155 /* 1156 * New block styles may have been registered within WP_Block_Styles_Registry. 1157 * Update block metadata for any new block style variations. 1158 */ 1159 $registered_styles = $style_registry->get_all_registered(); 1160 foreach ( static::$blocks_metadata as $block_name => $block_metadata ) { 1161 if ( ! empty( $registered_styles[ $block_name ] ) ) { 1162 $style_selectors = $block_metadata['styleVariations'] ?? array(); 1163 1164 foreach ( $registered_styles[ $block_name ] as $block_style ) { 1165 if ( ! isset( $style_selectors[ $block_style['name'] ] ) ) { 1166 $style_selectors[ $block_style['name'] ] = static::get_block_style_variation_selector( $block_style['name'], $block_metadata['selector'] ); 1167 } 1168 } 1169 1170 static::$blocks_metadata[ $block_name ]['styleVariations'] = $style_selectors; 1171 } 1172 } 1173 return static::$blocks_metadata; 1174 } 1175 1176 foreach ( $blocks as $block_name => $block_type ) { 1177 $root_selector = wp_get_block_css_selector( $block_type ); 1178 1179 static::$blocks_metadata[ $block_name ]['selector'] = $root_selector; 1180 static::$blocks_metadata[ $block_name ]['selectors'] = static::get_block_selectors( $block_type, $root_selector ); 1181 1182 $elements = static::get_block_element_selectors( $root_selector ); 1183 if ( ! empty( $elements ) ) { 1184 static::$blocks_metadata[ $block_name ]['elements'] = $elements; 1185 } 1186 1187 // The block may or may not have a duotone selector. 1188 $duotone_selector = wp_get_block_css_selector( $block_type, 'filter.duotone' ); 1189 1190 // Keep backwards compatibility for support.color.__experimentalDuotone. 1191 if ( null === $duotone_selector ) { 1192 $duotone_support = isset( $block_type->supports['color']['__experimentalDuotone'] ) 1193 ? $block_type->supports['color']['__experimentalDuotone'] 1194 : null; 1195 1196 if ( $duotone_support ) { 1197 $root_selector = wp_get_block_css_selector( $block_type ); 1198 $duotone_selector = static::scope_selector( $root_selector, $duotone_support ); 1199 } 1200 } 1201 1202 if ( null !== $duotone_selector ) { 1203 static::$blocks_metadata[ $block_name ]['duotone'] = $duotone_selector; 1204 } 1205 1206 // If the block has style variations, append their selectors to the block metadata. 1207 $style_selectors = array(); 1208 if ( ! empty( $block_type->styles ) ) { 1209 foreach ( $block_type->styles as $style ) { 1210 $style_selectors[ $style['name'] ] = static::get_block_style_variation_selector( $style['name'], static::$blocks_metadata[ $block_name ]['selector'] ); 1211 } 1212 } 1213 1214 // Block style variations can be registered through the WP_Block_Styles_Registry as well as block.json. 1215 $registered_styles = $style_registry->get_registered_styles_for_block( $block_name ); 1216 foreach ( $registered_styles as $style ) { 1217 $style_selectors[ $style['name'] ] = static::get_block_style_variation_selector( $style['name'], static::$blocks_metadata[ $block_name ]['selector'] ); 1218 } 1219 1220 if ( ! empty( $style_selectors ) ) { 1221 static::$blocks_metadata[ $block_name ]['styleVariations'] = $style_selectors; 1222 } 1223 } 1224 1225 return static::$blocks_metadata; 1226 } 1227 1228 /** 1229 * Given a tree, removes the keys that are not present in the schema. 1230 * 1231 * It is recursive and modifies the input in-place. 1232 * 1233 * @since 5.8.0 1234 * 1235 * @param array $tree Input to process. 1236 * @param array $schema Schema to adhere to. 1237 * @return array The modified $tree. 1238 */ 1239 protected static function remove_keys_not_in_schema( $tree, $schema ) { 1240 if ( ! is_array( $tree ) ) { 1241 return $tree; 1242 } 1243 1244 foreach ( $tree as $key => $value ) { 1245 // Remove keys not in the schema or with null/empty values. 1246 if ( ! array_key_exists( $key, $schema ) ) { 1247 unset( $tree[ $key ] ); 1248 continue; 1249 } 1250 1251 if ( is_array( $schema[ $key ] ) ) { 1252 if ( ! is_array( $value ) ) { 1253 unset( $tree[ $key ] ); 1254 } elseif ( wp_is_numeric_array( $value ) ) { 1255 // If indexed, process each item in the array. 1256 foreach ( $value as $item_key => $item_value ) { 1257 if ( isset( $schema[ $key ][0] ) && is_array( $schema[ $key ][0] ) ) { 1258 $tree[ $key ][ $item_key ] = self::remove_keys_not_in_schema( $item_value, $schema[ $key ][0] ); 1259 } else { 1260 // If the schema does not define a further structure, keep the value as is. 1261 $tree[ $key ][ $item_key ] = $item_value; 1262 } 1263 } 1264 } else { 1265 // If associative, process as a single object. 1266 $tree[ $key ] = self::remove_keys_not_in_schema( $value, $schema[ $key ] ); 1267 1268 if ( empty( $tree[ $key ] ) ) { 1269 unset( $tree[ $key ] ); 1270 } 1271 } 1272 } 1273 } 1274 return $tree; 1275 } 1276 1277 /** 1278 * Returns the existing settings for each block. 1279 * 1280 * Example: 1281 * 1282 * { 1283 * 'root': { 1284 * 'color': { 1285 * 'custom': true 1286 * } 1287 * }, 1288 * 'core/paragraph': { 1289 * 'spacing': { 1290 * 'customPadding': true 1291 * } 1292 * } 1293 * } 1294 * 1295 * @since 5.8.0 1296 * 1297 * @return array Settings per block. 1298 */ 1299 public function get_settings() { 1300 if ( ! isset( $this->theme_json['settings'] ) ) { 1301 return array(); 1302 } else { 1303 return $this->theme_json['settings']; 1304 } 1305 } 1306 1307 /** 1308 * Returns the stylesheet that results of processing 1309 * the theme.json structure this object represents. 1310 * 1311 * @since 5.8.0 1312 * @since 5.9.0 Removed the `$type` parameter, added the `$types` and `$origins` parameters. 1313 * @since 6.3.0 Add fallback layout styles for Post Template when block gap support isn't available. 1314 * @since 6.6.0 Added boolean `skip_root_layout_styles` and `include_block_style_variations` options 1315 * to control styles output as desired. 1316 * 1317 * @param string[] $types Types of styles to load. Will load all by default. It accepts: 1318 * - `variables`: only the CSS Custom Properties for presets & custom ones. 1319 * - `styles`: only the styles section in theme.json. 1320 * - `presets`: only the classes for the presets. 1321 * - `base-layout-styles`: only the base layout styles. 1322 * - `custom-css`: only the custom CSS. 1323 * @param string[] $origins A list of origins to include. By default it includes VALID_ORIGINS. 1324 * @param array $options { 1325 * Optional. An array of options for now used for internal purposes only (may change without notice). 1326 * 1327 * @type string $scope Makes sure all style are scoped to a given selector 1328 * @type string $root_selector Overwrites and forces a given selector to be used on the root node 1329 * @type bool $skip_root_layout_styles Omits root layout styles from the generated stylesheet. Default false. 1330 * @type bool $include_block_style_variations Includes styles for block style variations in the generated stylesheet. Default false. 1331 * } 1332 * @return string The resulting stylesheet. 1333 */ 1334 public function get_stylesheet( $types = array( 'variables', 'styles', 'presets' ), $origins = null, $options = array() ) { 1335 if ( null === $origins ) { 1336 $origins = static::VALID_ORIGINS; 1337 } 1338 1339 if ( is_string( $types ) ) { 1340 // Dispatch error and map old arguments to new ones. 1341 _deprecated_argument( __FUNCTION__, '5.9.0' ); 1342 if ( 'block_styles' === $types ) { 1343 $types = array( 'styles', 'presets' ); 1344 } elseif ( 'css_variables' === $types ) { 1345 $types = array( 'variables' ); 1346 } else { 1347 $types = array( 'variables', 'styles', 'presets' ); 1348 } 1349 } 1350 1351 $blocks_metadata = static::get_blocks_metadata(); 1352 $style_nodes = static::get_style_nodes( $this->theme_json, $blocks_metadata, $options ); 1353 $setting_nodes = static::get_setting_nodes( $this->theme_json, $blocks_metadata ); 1354 1355 $root_style_key = array_search( static::ROOT_BLOCK_SELECTOR, array_column( $style_nodes, 'selector' ), true ); 1356 $root_settings_key = array_search( static::ROOT_BLOCK_SELECTOR, array_column( $setting_nodes, 'selector' ), true ); 1357 1358 if ( ! empty( $options['scope'] ) ) { 1359 foreach ( $setting_nodes as &$node ) { 1360 $node['selector'] = static::scope_selector( $options['scope'], $node['selector'] ); 1361 } 1362 foreach ( $style_nodes as &$node ) { 1363 $node = static::scope_style_node_selectors( $options['scope'], $node ); 1364 } 1365 unset( $node ); 1366 } 1367 1368 if ( ! empty( $options['root_selector'] ) ) { 1369 if ( false !== $root_settings_key ) { 1370 $setting_nodes[ $root_settings_key ]['selector'] = $options['root_selector']; 1371 } 1372 if ( false !== $root_style_key ) { 1373 $style_nodes[ $root_style_key ]['selector'] = $options['root_selector']; 1374 } 1375 } 1376 1377 $stylesheet = ''; 1378 1379 if ( in_array( 'variables', $types, true ) ) { 1380 $stylesheet .= $this->get_css_variables( $setting_nodes, $origins ); 1381 } 1382 1383 if ( in_array( 'styles', $types, true ) ) { 1384 if ( false !== $root_style_key && empty( $options['skip_root_layout_styles'] ) ) { 1385 $stylesheet .= $this->get_root_layout_rules( $style_nodes[ $root_style_key ]['selector'], $style_nodes[ $root_style_key ] ); 1386 } 1387 $stylesheet .= $this->get_block_classes( $style_nodes ); 1388 } elseif ( in_array( 'base-layout-styles', $types, true ) ) { 1389 $root_selector = static::ROOT_BLOCK_SELECTOR; 1390 $columns_selector = '.wp-block-columns'; 1391 $post_template_selector = '.wp-block-post-template'; 1392 if ( ! empty( $options['scope'] ) ) { 1393 $root_selector = static::scope_selector( $options['scope'], $root_selector ); 1394 $columns_selector = static::scope_selector( $options['scope'], $columns_selector ); 1395 $post_template_selector = static::scope_selector( $options['scope'], $post_template_selector ); 1396 } 1397 if ( ! empty( $options['root_selector'] ) ) { 1398 $root_selector = $options['root_selector']; 1399 } 1400 /* 1401 * Base layout styles are provided as part of `styles`, so only output separately if explicitly requested. 1402 * For backwards compatibility, the Columns block is explicitly included, to support a different default gap value. 1403 */ 1404 $base_styles_nodes = array( 1405 array( 1406 'path' => array( 'styles' ), 1407 'selector' => $root_selector, 1408 ), 1409 array( 1410 'path' => array( 'styles', 'blocks', 'core/columns' ), 1411 'selector' => $columns_selector, 1412 'name' => 'core/columns', 1413 ), 1414 array( 1415 'path' => array( 'styles', 'blocks', 'core/post-template' ), 1416 'selector' => $post_template_selector, 1417 'name' => 'core/post-template', 1418 ), 1419 ); 1420 1421 foreach ( $base_styles_nodes as $base_style_node ) { 1422 $stylesheet .= $this->get_layout_styles( $base_style_node, $types ); 1423 } 1424 } 1425 1426 if ( in_array( 'presets', $types, true ) ) { 1427 $stylesheet .= $this->get_preset_classes( $setting_nodes, $origins ); 1428 } 1429 1430 // Load the custom CSS last so it has the highest specificity. 1431 if ( in_array( 'custom-css', $types, true ) ) { 1432 // Add the global styles root CSS. 1433 $stylesheet .= _wp_array_get( $this->theme_json, array( 'styles', 'css' ) ); 1434 } 1435 1436 return $stylesheet; 1437 } 1438 1439 /** 1440 * Processes the CSS, to apply nesting. 1441 * 1442 * @since 6.2.0 1443 * @since 6.6.0 Enforced 0-1-0 specificity for block custom CSS selectors. 1444 * 1445 * @param string $css The CSS to process. 1446 * @param string $selector The selector to nest. 1447 * @return string The processed CSS. 1448 */ 1449 protected function process_blocks_custom_css( $css, $selector ) { 1450 $processed_css = ''; 1451 1452 if ( empty( $css ) ) { 1453 return $processed_css; 1454 } 1455 1456 // Split CSS nested rules. 1457 $parts = explode( '&', $css ); 1458 foreach ( $parts as $part ) { 1459 if ( empty( $part ) ) { 1460 continue; 1461 } 1462 $is_root_css = ( ! str_contains( $part, '{' ) ); 1463 if ( $is_root_css ) { 1464 // If the part doesn't contain braces, it applies to the root level. 1465 $processed_css .= ':root :where(' . trim( $selector ) . '){' . trim( $part ) . '}'; 1466 } else { 1467 // If the part contains braces, it's a nested CSS rule. 1468 $part = explode( '{', str_replace( '}', '', $part ) ); 1469 if ( count( $part ) !== 2 ) { 1470 continue; 1471 } 1472 $nested_selector = $part[0]; 1473 $css_value = $part[1]; 1474 1475 /* 1476 * Handle pseudo elements such as ::before, ::after etc. Regex will also 1477 * capture any leading combinator such as >, +, or ~, as well as spaces. 1478 * This allows pseudo elements as descendants e.g. `.parent ::before`. 1479 */ 1480 $matches = array(); 1481 $has_pseudo_element = preg_match( '/([>+~\s]*::[a-zA-Z-]+)/', $nested_selector, $matches ); 1482 $pseudo_part = $has_pseudo_element ? $matches[1] : ''; 1483 $nested_selector = $has_pseudo_element ? str_replace( $pseudo_part, '', $nested_selector ) : $nested_selector; 1484 1485 // Finalize selector and re-append pseudo element if required. 1486 $part_selector = str_starts_with( $nested_selector, ' ' ) 1487 ? static::scope_selector( $selector, $nested_selector ) 1488 : static::append_to_selector( $selector, $nested_selector ); 1489 $final_selector = ":root :where($part_selector)$pseudo_part"; 1490 1491 $processed_css .= $final_selector . '{' . trim( $css_value ) . '}'; 1492 } 1493 } 1494 return $processed_css; 1495 } 1496 1497 /** 1498 * Returns the global styles custom CSS. 1499 * 1500 * @since 6.2.0 1501 * @deprecated 6.7.0 Use {@see 'get_stylesheet'} instead. 1502 * 1503 * @return string The global styles custom CSS. 1504 */ 1505 public function get_custom_css() { 1506 _deprecated_function( __METHOD__, '6.7.0', 'get_stylesheet' ); 1507 // Add the global styles root CSS. 1508 $stylesheet = isset( $this->theme_json['styles']['css'] ) ? $this->theme_json['styles']['css'] : ''; 1509 1510 // Add the global styles block CSS. 1511 if ( isset( $this->theme_json['styles']['blocks'] ) ) { 1512 foreach ( $this->theme_json['styles']['blocks'] as $name => $node ) { 1513 $custom_block_css = isset( $this->theme_json['styles']['blocks'][ $name ]['css'] ) 1514 ? $this->theme_json['styles']['blocks'][ $name ]['css'] 1515 : null; 1516 if ( $custom_block_css ) { 1517 $selector = static::$blocks_metadata[ $name ]['selector']; 1518 $stylesheet .= $this->process_blocks_custom_css( $custom_block_css, $selector ); 1519 } 1520 } 1521 } 1522 1523 return $stylesheet; 1524 } 1525 1526 /** 1527 * Returns the page templates of the active theme. 1528 * 1529 * @since 5.9.0 1530 * 1531 * @return array 1532 */ 1533 public function get_custom_templates() { 1534 $custom_templates = array(); 1535 if ( ! isset( $this->theme_json['customTemplates'] ) || ! is_array( $this->theme_json['customTemplates'] ) ) { 1536 return $custom_templates; 1537 } 1538 1539 foreach ( $this->theme_json['customTemplates'] as $item ) { 1540 if ( isset( $item['name'] ) ) { 1541 $custom_templates[ $item['name'] ] = array( 1542 'title' => isset( $item['title'] ) ? $item['title'] : '', 1543 'postTypes' => isset( $item['postTypes'] ) ? $item['postTypes'] : array( 'page' ), 1544 ); 1545 } 1546 } 1547 return $custom_templates; 1548 } 1549 1550 /** 1551 * Returns the template part data of active theme. 1552 * 1553 * @since 5.9.0 1554 * 1555 * @return array 1556 */ 1557 public function get_template_parts() { 1558 $template_parts = array(); 1559 if ( ! isset( $this->theme_json['templateParts'] ) || ! is_array( $this->theme_json['templateParts'] ) ) { 1560 return $template_parts; 1561 } 1562 1563 foreach ( $this->theme_json['templateParts'] as $item ) { 1564 if ( isset( $item['name'] ) ) { 1565 $template_parts[ $item['name'] ] = array( 1566 'title' => isset( $item['title'] ) ? $item['title'] : '', 1567 'area' => isset( $item['area'] ) ? $item['area'] : '', 1568 ); 1569 } 1570 } 1571 return $template_parts; 1572 } 1573 1574 /** 1575 * Converts each style section into a list of rulesets 1576 * containing the block styles to be appended to the stylesheet. 1577 * 1578 * See glossary at https://developer.mozilla.org/en-US/docs/Web/CSS/Syntax 1579 * 1580 * For each section this creates a new ruleset such as: 1581 * 1582 * block-selector { 1583 * style-property-one: value; 1584 * } 1585 * 1586 * @since 5.8.0 As `get_block_styles()`. 1587 * @since 5.9.0 Renamed from `get_block_styles()` to `get_block_classes()` 1588 * and no longer returns preset classes. 1589 * Removed the `$setting_nodes` parameter. 1590 * @since 6.1.0 Moved most internal logic to `get_styles_for_block()`. 1591 * 1592 * @param array $style_nodes Nodes with styles. 1593 * @return string The new stylesheet. 1594 */ 1595 protected function get_block_classes( $style_nodes ) { 1596 $block_rules = ''; 1597 1598 foreach ( $style_nodes as $metadata ) { 1599 if ( null === $metadata['selector'] ) { 1600 continue; 1601 } 1602 $block_rules .= static::get_styles_for_block( $metadata ); 1603 } 1604 1605 return $block_rules; 1606 } 1607 1608 /** 1609 * Gets the CSS layout rules for a particular block from theme.json layout definitions. 1610 * 1611 * @since 6.1.0 1612 * @since 6.3.0 Reduced specificity for layout margin rules. 1613 * @since 6.5.1 Only output rules referencing content and wide sizes when values exist. 1614 * @since 6.5.3 Add types parameter to check if only base layout styles are needed. 1615 * @since 6.6.0 Updated layout style specificity to be compatible with overall 0-1-0 specificity in global styles. 1616 * 1617 * @param array $block_metadata Metadata about the block to get styles for. 1618 * @param array $types Optional. Types of styles to output. If empty, all styles will be output. 1619 * @return string Layout styles for the block. 1620 */ 1621 protected function get_layout_styles( $block_metadata, $types = array() ) { 1622 $block_rules = ''; 1623 $block_type = null; 1624 1625 // Skip outputting layout styles if explicitly disabled. 1626 if ( current_theme_supports( 'disable-layout-styles' ) ) { 1627 return $block_rules; 1628 } 1629 1630 if ( isset( $block_metadata['name'] ) ) { 1631 $block_type = WP_Block_Type_Registry::get_instance()->get_registered( $block_metadata['name'] ); 1632 if ( ! block_has_support( $block_type, 'layout', false ) && ! block_has_support( $block_type, '__experimentalLayout', false ) ) { 1633 return $block_rules; 1634 } 1635 } 1636 1637 $selector = isset( $block_metadata['selector'] ) ? $block_metadata['selector'] : ''; 1638 $has_block_gap_support = isset( $this->theme_json['settings']['spacing']['blockGap'] ); 1639 $has_fallback_gap_support = ! $has_block_gap_support; // This setting isn't useful yet: it exists as a placeholder for a future explicit fallback gap styles support. 1640 $node = _wp_array_get( $this->theme_json, $block_metadata['path'], array() ); 1641 $layout_definitions = wp_get_layout_definitions(); 1642 $layout_selector_pattern = '/^[a-zA-Z0-9\-\.\,\ *+>:\(\)]*$/'; // Allow alphanumeric classnames, spaces, wildcard, sibling, child combinator and pseudo class selectors. 1643 1644 /* 1645 * Gap styles will only be output if the theme has block gap support, or supports a fallback gap. 1646 * Default layout gap styles will be skipped for themes that do not explicitly opt-in to blockGap with a `true` or `false` value. 1647 */ 1648 if ( $has_block_gap_support || $has_fallback_gap_support ) { 1649 $block_gap_value = null; 1650 // Use a fallback gap value if block gap support is not available. 1651 if ( ! $has_block_gap_support ) { 1652 $block_gap_value = static::ROOT_BLOCK_SELECTOR === $selector ? '0.5em' : null; 1653 if ( ! empty( $block_type ) ) { 1654 $block_gap_value = isset( $block_type->supports['spacing']['blockGap']['__experimentalDefault'] ) 1655 ? $block_type->supports['spacing']['blockGap']['__experimentalDefault'] 1656 : null; 1657 } 1658 } else { 1659 $block_gap_value = static::get_property_value( $node, array( 'spacing', 'blockGap' ) ); 1660 } 1661 1662 // Support split row / column values and concatenate to a shorthand value. 1663 if ( is_array( $block_gap_value ) ) { 1664 if ( isset( $block_gap_value['top'] ) && isset( $block_gap_value['left'] ) ) { 1665 $gap_row = static::get_property_value( $node, array( 'spacing', 'blockGap', 'top' ) ); 1666 $gap_column = static::get_property_value( $node, array( 'spacing', 'blockGap', 'left' ) ); 1667 $block_gap_value = $gap_row === $gap_column ? $gap_row : $gap_row . ' ' . $gap_column; 1668 } else { 1669 // Skip outputting gap value if not all sides are provided. 1670 $block_gap_value = null; 1671 } 1672 } 1673 1674 // If the block should have custom gap, add the gap styles. 1675 if ( null !== $block_gap_value && false !== $block_gap_value && '' !== $block_gap_value ) { 1676 foreach ( $layout_definitions as $layout_definition_key => $layout_definition ) { 1677 // Allow outputting fallback gap styles for flex and grid layout types when block gap support isn't available. 1678 if ( ! $has_block_gap_support && 'flex' !== $layout_definition_key && 'grid' !== $layout_definition_key ) { 1679 continue; 1680 } 1681 1682 $class_name = isset( $layout_definition['className'] ) ? $layout_definition['className'] : false; 1683 $spacing_rules = isset( $layout_definition['spacingStyles'] ) ? $layout_definition['spacingStyles'] : array(); 1684 1685 if ( 1686 ! empty( $class_name ) && 1687 ! empty( $spacing_rules ) 1688 ) { 1689 foreach ( $spacing_rules as $spacing_rule ) { 1690 $declarations = array(); 1691 if ( 1692 isset( $spacing_rule['selector'] ) && 1693 preg_match( $layout_selector_pattern, $spacing_rule['selector'] ) && 1694 ! empty( $spacing_rule['rules'] ) 1695 ) { 1696 // Iterate over each of the styling rules and substitute non-string values such as `null` with the real `blockGap` value. 1697 foreach ( $spacing_rule['rules'] as $css_property => $css_value ) { 1698 $current_css_value = is_string( $css_value ) ? $css_value : $block_gap_value; 1699 if ( static::is_safe_css_declaration( $css_property, $current_css_value ) ) { 1700 $declarations[] = array( 1701 'name' => $css_property, 1702 'value' => $current_css_value, 1703 ); 1704 } 1705 } 1706 1707 if ( ! $has_block_gap_support ) { 1708 // For fallback gap styles, use lower specificity, to ensure styles do not unintentionally override theme styles. 1709 $format = static::ROOT_BLOCK_SELECTOR === $selector ? ':where(.%2$s%3$s)' : ':where(%1$s.%2$s%3$s)'; 1710 $layout_selector = sprintf( 1711 $format, 1712 $selector, 1713 $class_name, 1714 $spacing_rule['selector'] 1715 ); 1716 } else { 1717 $format = static::ROOT_BLOCK_SELECTOR === $selector ? ':root :where(.%2$s)%3$s' : ':root :where(%1$s-%2$s)%3$s'; 1718 $layout_selector = sprintf( 1719 $format, 1720 $selector, 1721 $class_name, 1722 $spacing_rule['selector'] 1723 ); 1724 } 1725 $block_rules .= static::to_ruleset( $layout_selector, $declarations ); 1726 } 1727 } 1728 } 1729 } 1730 } 1731 } 1732 1733 // Output base styles. 1734 if ( 1735 static::ROOT_BLOCK_SELECTOR === $selector 1736 ) { 1737 $valid_display_modes = array( 'block', 'flex', 'grid' ); 1738 foreach ( $layout_definitions as $layout_definition ) { 1739 $class_name = isset( $layout_definition['className'] ) ? $layout_definition['className'] : false; 1740 $base_style_rules = isset( $layout_definition['baseStyles'] ) ? $layout_definition['baseStyles'] : array(); 1741 1742 if ( 1743 ! empty( $class_name ) && 1744 is_array( $base_style_rules ) 1745 ) { 1746 // Output display mode. This requires special handling as `display` is not exposed in `safe_style_css_filter`. 1747 if ( 1748 ! empty( $layout_definition['displayMode'] ) && 1749 is_string( $layout_definition['displayMode'] ) && 1750 in_array( $layout_definition['displayMode'], $valid_display_modes, true ) 1751 ) { 1752 $layout_selector = sprintf( 1753 '%s .%s', 1754 $selector, 1755 $class_name 1756 ); 1757 $block_rules .= static::to_ruleset( 1758 $layout_selector, 1759 array( 1760 array( 1761 'name' => 'display', 1762 'value' => $layout_definition['displayMode'], 1763 ), 1764 ) 1765 ); 1766 } 1767 1768 foreach ( $base_style_rules as $base_style_rule ) { 1769 $declarations = array(); 1770 1771 // Skip outputting base styles for flow and constrained layout types if theme doesn't support theme.json. The 'base-layout-styles' type flags this. 1772 if ( in_array( 'base-layout-styles', $types, true ) && ( 'default' === $layout_definition['name'] || 'constrained' === $layout_definition['name'] ) ) { 1773 continue; 1774 } 1775 1776 if ( 1777 isset( $base_style_rule['selector'] ) && 1778 preg_match( $layout_selector_pattern, $base_style_rule['selector'] ) && 1779 ! empty( $base_style_rule['rules'] ) 1780 ) { 1781 foreach ( $base_style_rule['rules'] as $css_property => $css_value ) { 1782 // Skip rules that reference content size or wide size if they are not defined in the theme.json. 1783 if ( 1784 is_string( $css_value ) && 1785 ( str_contains( $css_value, '--global--content-size' ) || str_contains( $css_value, '--global--wide-size' ) ) && 1786 ! isset( $this->theme_json['settings']['layout']['contentSize'] ) && 1787 ! isset( $this->theme_json['settings']['layout']['wideSize'] ) 1788 ) { 1789 continue; 1790 } 1791 1792 if ( static::is_safe_css_declaration( $css_property, $css_value ) ) { 1793 $declarations[] = array( 1794 'name' => $css_property, 1795 'value' => $css_value, 1796 ); 1797 } 1798 } 1799 1800 $layout_selector = sprintf( 1801 '.%s%s', 1802 $class_name, 1803 $base_style_rule['selector'] 1804 ); 1805 $block_rules .= static::to_ruleset( $layout_selector, $declarations ); 1806 } 1807 } 1808 } 1809 } 1810 } 1811 return $block_rules; 1812 } 1813 1814 /** 1815 * Creates new rulesets as classes for each preset value such as: 1816 * 1817 * .has-value-color { 1818 * color: value; 1819 * } 1820 * 1821 * .has-value-background-color { 1822 * background-color: value; 1823 * } 1824 * 1825 * .has-value-font-size { 1826 * font-size: value; 1827 * } 1828 * 1829 * .has-value-gradient-background { 1830 * background: value; 1831 * } 1832 * 1833 * p.has-value-gradient-background { 1834 * background: value; 1835 * } 1836 * 1837 * @since 5.9.0 1838 * 1839 * @param array $setting_nodes Nodes with settings. 1840 * @param string[] $origins List of origins to process presets from. 1841 * @return string The new stylesheet. 1842 */ 1843 protected function get_preset_classes( $setting_nodes, $origins ) { 1844 $preset_rules = ''; 1845 1846 foreach ( $setting_nodes as $metadata ) { 1847 if ( null === $metadata['selector'] ) { 1848 continue; 1849 } 1850 1851 $selector = $metadata['selector']; 1852 $node = _wp_array_get( $this->theme_json, $metadata['path'], array() ); 1853 $preset_rules .= static::compute_preset_classes( $node, $selector, $origins ); 1854 } 1855 1856 return $preset_rules; 1857 } 1858 1859 /** 1860 * Converts each styles section into a list of rulesets 1861 * to be appended to the stylesheet. 1862 * These rulesets contain all the css variables (custom variables and preset variables). 1863 * 1864 * See glossary at https://developer.mozilla.org/en-US/docs/Web/CSS/Syntax 1865 * 1866 * For each section this creates a new ruleset such as: 1867 * 1868 * block-selector { 1869 * --wp--preset--category--slug: value; 1870 * --wp--custom--variable: value; 1871 * } 1872 * 1873 * @since 5.8.0 1874 * @since 5.9.0 Added the `$origins` parameter. 1875 * 1876 * @param array $nodes Nodes with settings. 1877 * @param string[] $origins List of origins to process. 1878 * @return string The new stylesheet. 1879 */ 1880 protected function get_css_variables( $nodes, $origins ) { 1881 $stylesheet = ''; 1882 foreach ( $nodes as $metadata ) { 1883 if ( null === $metadata['selector'] ) { 1884 continue; 1885 } 1886 1887 $selector = $metadata['selector']; 1888 1889 $node = _wp_array_get( $this->theme_json, $metadata['path'], array() ); 1890 $declarations = static::compute_preset_vars( $node, $origins ); 1891 $theme_vars_declarations = static::compute_theme_vars( $node ); 1892 foreach ( $theme_vars_declarations as $theme_vars_declaration ) { 1893 $declarations[] = $theme_vars_declaration; 1894 } 1895 1896 $stylesheet .= static::to_ruleset( $selector, $declarations ); 1897 } 1898 1899 return $stylesheet; 1900 } 1901 1902 /** 1903 * Given a selector and a declaration list, 1904 * creates the corresponding ruleset. 1905 * 1906 * @since 5.8.0 1907 * 1908 * @param string $selector CSS selector. 1909 * @param array $declarations List of declarations. 1910 * @return string The resulting CSS ruleset. 1911 */ 1912 protected static function to_ruleset( $selector, $declarations ) { 1913 if ( empty( $declarations ) ) { 1914 return ''; 1915 } 1916 1917 $declaration_block = array_reduce( 1918 $declarations, 1919 static function ( $carry, $element ) { 1920 return $carry .= $element['name'] . ': ' . $element['value'] . ';'; }, 1921 '' 1922 ); 1923 1924 return $selector . '{' . $declaration_block . '}'; 1925 } 1926 1927 /** 1928 * Given a settings array, returns the generated rulesets 1929 * for the preset classes. 1930 * 1931 * @since 5.8.0 1932 * @since 5.9.0 Added the `$origins` parameter. 1933 * @since 6.6.0 Added check for root CSS properties selector. 1934 * 1935 * @param array $settings Settings to process. 1936 * @param string $selector Selector wrapping the classes. 1937 * @param string[] $origins List of origins to process. 1938 * @return string The result of processing the presets. 1939 */ 1940 protected static function compute_preset_classes( $settings, $selector, $origins ) { 1941 if ( static::ROOT_BLOCK_SELECTOR === $selector || static::ROOT_CSS_PROPERTIES_SELECTOR === $selector ) { 1942 /* 1943 * Classes at the global level do not need any CSS prefixed, 1944 * and we don't want to increase its specificity. 1945 */ 1946 $selector = ''; 1947 } 1948 1949 $stylesheet = ''; 1950 foreach ( static::PRESETS_METADATA as $preset_metadata ) { 1951 if ( empty( $preset_metadata['classes'] ) ) { 1952 continue; 1953 } 1954 $slugs = static::get_settings_slugs( $settings, $preset_metadata, $origins ); 1955 foreach ( $preset_metadata['classes'] as $class => $property ) { 1956 foreach ( $slugs as $slug ) { 1957 $css_var = static::replace_slug_in_string( $preset_metadata['css_vars'], $slug ); 1958 $class_name = static::replace_slug_in_string( $class, $slug ); 1959 1960 // $selector is often empty, so we can save ourselves the `append_to_selector()` call then. 1961 $new_selector = '' === $selector ? $class_name : static::append_to_selector( $selector, $class_name ); 1962 $stylesheet .= static::to_ruleset( 1963 $new_selector, 1964 array( 1965 array( 1966 'name' => $property, 1967 'value' => 'var(' . $css_var . ') !important', 1968 ), 1969 ) 1970 ); 1971 } 1972 } 1973 } 1974 1975 return $stylesheet; 1976 } 1977 1978 /** 1979 * Function that scopes a selector with another one. This works a bit like 1980 * SCSS nesting except the `&` operator isn't supported. 1981 * 1982 * <code> 1983 * $scope = '.a, .b .c'; 1984 * $selector = '> .x, .y'; 1985 * $merged = scope_selector( $scope, $selector ); 1986 * // $merged is '.a > .x, .a .y, .b .c > .x, .b .c .y' 1987 * </code> 1988 * 1989 * @since 5.9.0 1990 * @since 6.6.0 Added early return if missing scope or selector. 1991 * 1992 * @param string $scope Selector to scope to. 1993 * @param string $selector Original selector. 1994 * @return string Scoped selector. 1995 */ 1996 public static function scope_selector( $scope, $selector ) { 1997 if ( ! $scope || ! $selector ) { 1998 return $selector; 1999 } 2000 2001 $scopes = explode( ',', $scope ); 2002 $selectors = explode( ',', $selector ); 2003 2004 $selectors_scoped = array(); 2005 foreach ( $scopes as $outer ) { 2006 foreach ( $selectors as $inner ) { 2007 $outer = trim( $outer ); 2008 $inner = trim( $inner ); 2009 if ( ! empty( $outer ) && ! empty( $inner ) ) { 2010 $selectors_scoped[] = $outer . ' ' . $inner; 2011 } elseif ( empty( $outer ) ) { 2012 $selectors_scoped[] = $inner; 2013 } elseif ( empty( $inner ) ) { 2014 $selectors_scoped[] = $outer; 2015 } 2016 } 2017 } 2018 2019 $result = implode( ', ', $selectors_scoped ); 2020 return $result; 2021 } 2022 2023 /** 2024 * Scopes the selectors for a given style node. 2025 * 2026 * This includes the primary selector, i.e. `$node['selector']`, as well as any custom 2027 * selectors for features and subfeatures, e.g. `$node['selectors']['border']` etc. 2028 * 2029 * @since 6.6.0 2030 * 2031 * @param string $scope Selector to scope to. 2032 * @param array $node Style node with selectors to scope. 2033 * @return array Node with updated selectors. 2034 */ 2035 protected static function scope_style_node_selectors( $scope, $node ) { 2036 $node['selector'] = static::scope_selector( $scope, $node['selector'] ); 2037 2038 if ( empty( $node['selectors'] ) ) { 2039 return $node; 2040 } 2041 2042 foreach ( $node['selectors'] as $feature => $selector ) { 2043 if ( is_string( $selector ) ) { 2044 $node['selectors'][ $feature ] = static::scope_selector( $scope, $selector ); 2045 } 2046 if ( is_array( $selector ) ) { 2047 foreach ( $selector as $subfeature => $subfeature_selector ) { 2048 $node['selectors'][ $feature ][ $subfeature ] = static::scope_selector( $scope, $subfeature_selector ); 2049 } 2050 } 2051 } 2052 2053 return $node; 2054 } 2055 2056 /** 2057 * Gets preset values keyed by slugs based on settings and metadata. 2058 * 2059 * <code> 2060 * $settings = array( 2061 * 'typography' => array( 2062 * 'fontFamilies' => array( 2063 * array( 2064 * 'slug' => 'sansSerif', 2065 * 'fontFamily' => '"Helvetica Neue", sans-serif', 2066 * ), 2067 * array( 2068 * 'slug' => 'serif', 2069 * 'colors' => 'Georgia, serif', 2070 * ) 2071 * ), 2072 * ), 2073 * ); 2074 * $meta = array( 2075 * 'path' => array( 'typography', 'fontFamilies' ), 2076 * 'value_key' => 'fontFamily', 2077 * ); 2078 * $values_by_slug = get_settings_values_by_slug(); 2079 * // $values_by_slug === array( 2080 * // 'sans-serif' => '"Helvetica Neue", sans-serif', 2081 * // 'serif' => 'Georgia, serif', 2082 * // ); 2083 * </code> 2084 * 2085 * @since 5.9.0 2086 * @since 6.6.0 Passing $settings to the callbacks defined in static::PRESETS_METADATA. 2087 * 2088 * @param array $settings Settings to process. 2089 * @param array $preset_metadata One of the PRESETS_METADATA values. 2090 * @param string[] $origins List of origins to process. 2091 * @return array Array of presets where each key is a slug and each value is the preset value. 2092 */ 2093 protected static function get_settings_values_by_slug( $settings, $preset_metadata, $origins ) { 2094 $preset_per_origin = _wp_array_get( $settings, $preset_metadata['path'], array() ); 2095 2096 $result = array(); 2097 foreach ( $origins as $origin ) { 2098 if ( ! isset( $preset_per_origin[ $origin ] ) ) { 2099 continue; 2100 } 2101 foreach ( $preset_per_origin[ $origin ] as $preset ) { 2102 $slug = _wp_to_kebab_case( $preset['slug'] ); 2103 2104 $value = ''; 2105 if ( isset( $preset_metadata['value_key'], $preset[ $preset_metadata['value_key'] ] ) ) { 2106 $value_key = $preset_metadata['value_key']; 2107 $value = $preset[ $value_key ]; 2108 } elseif ( 2109 isset( $preset_metadata['value_func'] ) && 2110 is_callable( $preset_metadata['value_func'] ) 2111 ) { 2112 $value_func = $preset_metadata['value_func']; 2113 $value = call_user_func( $value_func, $preset, $settings ); 2114 } else { 2115 // If we don't have a value, then don't add it to the result. 2116 continue; 2117 } 2118 2119 $result[ $slug ] = $value; 2120 } 2121 } 2122 return $result; 2123 } 2124 2125 /** 2126 * Similar to get_settings_values_by_slug, but doesn't compute the value. 2127 * 2128 * @since 5.9.0 2129 * 2130 * @param array $settings Settings to process. 2131 * @param array $preset_metadata One of the PRESETS_METADATA values. 2132 * @param string[] $origins List of origins to process. 2133 * @return array Array of presets where the key and value are both the slug. 2134 */ 2135 protected static function get_settings_slugs( $settings, $preset_metadata, $origins = null ) { 2136 if ( null === $origins ) { 2137 $origins = static::VALID_ORIGINS; 2138 } 2139 2140 $preset_per_origin = _wp_array_get( $settings, $preset_metadata['path'], array() ); 2141 2142 $result = array(); 2143 foreach ( $origins as $origin ) { 2144 if ( ! isset( $preset_per_origin[ $origin ] ) ) { 2145 continue; 2146 } 2147 foreach ( $preset_per_origin[ $origin ] as $preset ) { 2148 $slug = _wp_to_kebab_case( $preset['slug'] ); 2149 2150 // Use the array as a set so we don't get duplicates. 2151 $result[ $slug ] = $slug; 2152 } 2153 } 2154 return $result; 2155 } 2156 2157 /** 2158 * Transforms a slug into a CSS Custom Property. 2159 * 2160 * @since 5.9.0 2161 * 2162 * @param string $input String to replace. 2163 * @param string $slug The slug value to use to generate the custom property. 2164 * @return string The CSS Custom Property. Something along the lines of `--wp--preset--color--black`. 2165 */ 2166 protected static function replace_slug_in_string( $input, $slug ) { 2167 return strtr( $input, array( '$slug' => $slug ) ); 2168 } 2169 2170 /** 2171 * Given the block settings, extracts the CSS Custom Properties 2172 * for the presets and adds them to the $declarations array 2173 * following the format: 2174 * 2175 * array( 2176 * 'name' => 'property_name', 2177 * 'value' => 'property_value, 2178 * ) 2179 * 2180 * @since 5.8.0 2181 * @since 5.9.0 Added the `$origins` parameter. 2182 * 2183 * @param array $settings Settings to process. 2184 * @param string[] $origins List of origins to process. 2185 * @return array The modified $declarations. 2186 */ 2187 protected static function compute_preset_vars( $settings, $origins ) { 2188 $declarations = array(); 2189 foreach ( static::PRESETS_METADATA as $preset_metadata ) { 2190 if ( empty( $preset_metadata['css_vars'] ) ) { 2191 continue; 2192 } 2193 $values_by_slug = static::get_settings_values_by_slug( $settings, $preset_metadata, $origins ); 2194 foreach ( $values_by_slug as $slug => $value ) { 2195 $declarations[] = array( 2196 'name' => static::replace_slug_in_string( $preset_metadata['css_vars'], $slug ), 2197 'value' => $value, 2198 ); 2199 } 2200 } 2201 2202 return $declarations; 2203 } 2204 2205 /** 2206 * Given an array of settings, extracts the CSS Custom Properties 2207 * for the custom values and adds them to the $declarations 2208 * array following the format: 2209 * 2210 * array( 2211 * 'name' => 'property_name', 2212 * 'value' => 'property_value, 2213 * ) 2214 * 2215 * @since 5.8.0 2216 * 2217 * @param array $settings Settings to process. 2218 * @return array The modified $declarations. 2219 */ 2220 protected static function compute_theme_vars( $settings ) { 2221 $declarations = array(); 2222 $custom_values = isset( $settings['custom'] ) ? $settings['custom'] : array(); 2223 $css_vars = static::flatten_tree( $custom_values ); 2224 foreach ( $css_vars as $key => $value ) { 2225 $declarations[] = array( 2226 'name' => '--wp--custom--' . $key, 2227 'value' => $value, 2228 ); 2229 } 2230 2231 return $declarations; 2232 } 2233 2234 /** 2235 * Given a tree, it creates a flattened one 2236 * by merging the keys and binding the leaf values 2237 * to the new keys. 2238 * 2239 * It also transforms camelCase names into kebab-case 2240 * and substitutes '/' by '-'. 2241 * 2242 * This is thought to be useful to generate 2243 * CSS Custom Properties from a tree, 2244 * although there's nothing in the implementation 2245 * of this function that requires that format. 2246 * 2247 * For example, assuming the given prefix is '--wp' 2248 * and the token is '--', for this input tree: 2249 * 2250 * { 2251 * 'some/property': 'value', 2252 * 'nestedProperty': { 2253 * 'sub-property': 'value' 2254 * } 2255 * } 2256 * 2257 * it'll return this output: 2258 * 2259 * { 2260 * '--wp--some-property': 'value', 2261 * '--wp--nested-property--sub-property': 'value' 2262 * } 2263 * 2264 * @since 5.8.0 2265 * 2266 * @param array $tree Input tree to process. 2267 * @param string $prefix Optional. Prefix to prepend to each variable. Default empty string. 2268 * @param string $token Optional. Token to use between levels. Default '--'. 2269 * @return array The flattened tree. 2270 */ 2271 protected static function flatten_tree( $tree, $prefix = '', $token = '--' ) { 2272 $result = array(); 2273 foreach ( $tree as $property => $value ) { 2274 $new_key = $prefix . str_replace( 2275 '/', 2276 '-', 2277 strtolower( _wp_to_kebab_case( $property ) ) 2278 ); 2279 2280 if ( is_array( $value ) ) { 2281 $new_prefix = $new_key . $token; 2282 $flattened_subtree = static::flatten_tree( $value, $new_prefix, $token ); 2283 foreach ( $flattened_subtree as $subtree_key => $subtree_value ) { 2284 $result[ $subtree_key ] = $subtree_value; 2285 } 2286 } else { 2287 $result[ $new_key ] = $value; 2288 } 2289 } 2290 return $result; 2291 } 2292 2293 /** 2294 * Given a styles array, it extracts the style properties 2295 * and adds them to the $declarations array following the format: 2296 * 2297 * array( 2298 * 'name' => 'property_name', 2299 * 'value' => 'property_value', 2300 * ) 2301 * 2302 * @since 5.8.0 2303 * @since 5.9.0 Added the `$settings` and `$properties` parameters. 2304 * @since 6.1.0 Added `$theme_json`, `$selector`, and `$use_root_padding` parameters. 2305 * @since 6.5.0 Output a `min-height: unset` rule when `aspect-ratio` is set. 2306 * @since 6.6.0 Pass current theme JSON settings to wp_get_typography_font_size_value(), and process background properties. 2307 * @since 6.7.0 `ref` resolution of background properties, and assigning custom default values. 2308 * 2309 * @param array $styles Styles to process. 2310 * @param array $settings Theme settings. 2311 * @param array $properties Properties metadata. 2312 * @param array $theme_json Theme JSON array. 2313 * @param string $selector The style block selector. 2314 * @param boolean $use_root_padding Whether to add custom properties at root level. 2315 * @return array Returns the modified $declarations. 2316 */ 2317 protected static function compute_style_properties( $styles, $settings = array(), $properties = null, $theme_json = null, $selector = null, $use_root_padding = null ) { 2318 if ( empty( $styles ) ) { 2319 return array(); 2320 } 2321 2322 if ( null === $properties ) { 2323 $properties = static::PROPERTIES_METADATA; 2324 } 2325 $declarations = array(); 2326 $root_variable_duplicates = array(); 2327 $root_style_length = strlen( '--wp--style--root--' ); 2328 2329 foreach ( $properties as $css_property => $value_path ) { 2330 if ( ! is_array( $value_path ) ) { 2331 continue; 2332 } 2333 2334 $is_root_style = str_starts_with( $css_property, '--wp--style--root--' ); 2335 if ( $is_root_style && ( static::ROOT_BLOCK_SELECTOR !== $selector || ! $use_root_padding ) ) { 2336 continue; 2337 } 2338 2339 $value = static::get_property_value( $styles, $value_path, $theme_json ); 2340 2341 /* 2342 * Root-level padding styles don't currently support strings with CSS shorthand values. 2343 * This may change: https://github.com/WordPress/gutenberg/issues/40132. 2344 */ 2345 if ( '--wp--style--root--padding' === $css_property && is_string( $value ) ) { 2346 continue; 2347 } 2348 2349 if ( $is_root_style && $use_root_padding ) { 2350 $root_variable_duplicates[] = substr( $css_property, $root_style_length ); 2351 } 2352 2353 /* 2354 * Processes background image styles. 2355 * If the value is a URL, it will be converted to a CSS `url()` value. 2356 * For uploaded image (images with a database ID), apply size and position defaults, 2357 * equal to those applied in block supports in lib/background.php. 2358 */ 2359 if ( 'background-image' === $css_property && ! empty( $value ) ) { 2360 $background_styles = wp_style_engine_get_styles( 2361 array( 'background' => array( 'backgroundImage' => $value ) ) 2362 ); 2363 $value = $background_styles['declarations'][ $css_property ]; 2364 } 2365 if ( empty( $value ) && static::ROOT_BLOCK_SELECTOR !== $selector && ! empty( $styles['background']['backgroundImage']['id'] ) ) { 2366 if ( 'background-size' === $css_property ) { 2367 $value = 'cover'; 2368 } 2369 // If the background size is set to `contain` and no position is set, set the position to `center`. 2370 if ( 'background-position' === $css_property ) { 2371 $background_size = $styles['background']['backgroundSize'] ?? null; 2372 $value = 'contain' === $background_size ? '50% 50%' : null; 2373 } 2374 } 2375 2376 // Skip if empty and not "0" or value represents array of longhand values. 2377 $has_missing_value = empty( $value ) && ! is_numeric( $value ); 2378 if ( $has_missing_value || is_array( $value ) ) { 2379 continue; 2380 } 2381 2382 /* 2383 * Look up protected properties, keyed by value path. 2384 * Skip protected properties that are explicitly set to `null`. 2385 */ 2386 $path_string = implode( '.', $value_path ); 2387 if ( 2388 isset( static::PROTECTED_PROPERTIES[ $path_string ] ) && 2389 _wp_array_get( $settings, static::PROTECTED_PROPERTIES[ $path_string ], null ) === null 2390 ) { 2391 continue; 2392 } 2393 2394 // Calculates fluid typography rules where available. 2395 if ( 'font-size' === $css_property ) { 2396 /* 2397 * wp_get_typography_font_size_value() will check 2398 * if fluid typography has been activated and also 2399 * whether the incoming value can be converted to a fluid value. 2400 * Values that already have a clamp() function will not pass the test, 2401 * and therefore the original $value will be returned. 2402 * Pass the current theme_json settings to override any global settings. 2403 */ 2404 $value = wp_get_typography_font_size_value( array( 'size' => $value ), $settings ); 2405 } 2406 2407 if ( 'aspect-ratio' === $css_property ) { 2408 // For aspect ratio to work, other dimensions rules must be unset. 2409 // This ensures that a fixed height does not override the aspect ratio. 2410 $declarations[] = array( 2411 'name' => 'min-height', 2412 'value' => 'unset', 2413 ); 2414 } 2415 2416 $declarations[] = array( 2417 'name' => $css_property, 2418 'value' => $value, 2419 ); 2420 } 2421 2422 // If a variable value is added to the root, the corresponding property should be removed. 2423 foreach ( $root_variable_duplicates as $duplicate ) { 2424 $discard = array_search( $duplicate, array_column( $declarations, 'name' ), true ); 2425 if ( is_numeric( $discard ) ) { 2426 array_splice( $declarations, $discard, 1 ); 2427 } 2428 } 2429 2430 return $declarations; 2431 } 2432 2433 /** 2434 * Returns the style property for the given path. 2435 * 2436 * It also converts references to a path to the value 2437 * stored at that location, e.g. 2438 * { "ref": "style.color.background" } => "#fff". 2439 * 2440 * @since 5.8.0 2441 * @since 5.9.0 Added support for values of array type, which are returned as is. 2442 * @since 6.1.0 Added the `$theme_json` parameter. 2443 * @since 6.3.0 It no longer converts the internal format "var:preset|color|secondary" 2444 * to the standard form "--wp--preset--color--secondary". 2445 * This is already done by the sanitize method, 2446 * so every property will be in the standard form. 2447 * @since 6.7.0 Added support for background image refs. 2448 * 2449 * @param array $styles Styles subtree. 2450 * @param array $path Which property to process. 2451 * @param array $theme_json Theme JSON array. 2452 * @return string|array Style property value. 2453 */ 2454 protected static function get_property_value( $styles, $path, $theme_json = null ) { 2455 $value = _wp_array_get( $styles, $path, '' ); 2456 2457 if ( '' === $value || null === $value ) { 2458 // No need to process the value further. 2459 return ''; 2460 } 2461 2462 /* 2463 * This converts references to a path to the value at that path 2464 * where the value is an array with a "ref" key, pointing to a path. 2465 * For example: { "ref": "style.color.background" } => "#fff". 2466 * In the case of backgroundImage, if both a ref and a URL are present in the value, 2467 * the URL takes precedence and the ref is ignored. 2468 */ 2469 if ( is_array( $value ) && isset( $value['ref'] ) ) { 2470 $value_path = explode( '.', $value['ref'] ); 2471 $ref_value = _wp_array_get( $theme_json, $value_path ); 2472 // Background Image refs can refer to a string or an array containing a URL string. 2473 $ref_value_url = $ref_value['url'] ?? null; 2474 // Only use the ref value if we find anything. 2475 if ( ! empty( $ref_value ) && ( is_string( $ref_value ) || is_string( $ref_value_url ) ) ) { 2476 $value = $ref_value; 2477 } 2478 2479 if ( is_array( $ref_value ) && isset( $ref_value['ref'] ) ) { 2480 $path_string = json_encode( $path ); 2481 $ref_value_string = json_encode( $ref_value ); 2482 _doing_it_wrong( 2483 'get_property_value', 2484 sprintf( 2485 /* translators: 1: theme.json, 2: Value name, 3: Value path, 4: Another value name. */ 2486 __( 'Your %1$s file uses a dynamic value (%2$s) for the path at %3$s. However, the value at %3$s is also a dynamic value (pointing to %4$s) and pointing to another dynamic value is not supported. Please update %3$s to point directly to %4$s.' ), 2487 'theme.json', 2488 $ref_value_string, 2489 $path_string, 2490 $ref_value['ref'] 2491 ), 2492 '6.1.0' 2493 ); 2494 } 2495 } 2496 2497 if ( is_array( $value ) ) { 2498 return $value; 2499 } 2500 2501 return $value; 2502 } 2503 2504 /** 2505 * Builds metadata for the setting nodes, which returns in the form of: 2506 * 2507 * [ 2508 * [ 2509 * 'path' => ['path', 'to', 'some', 'node' ], 2510 * 'selector' => 'CSS selector for some node' 2511 * ], 2512 * [ 2513 * 'path' => [ 'path', 'to', 'other', 'node' ], 2514 * 'selector' => 'CSS selector for other node' 2515 * ], 2516 * ] 2517 * 2518 * @since 5.8.0 2519 * 2520 * @param array $theme_json The tree to extract setting nodes from. 2521 * @param array $selectors List of selectors per block. 2522 * @return array An array of setting nodes metadata. 2523 */ 2524 protected static function get_setting_nodes( $theme_json, $selectors = array() ) { 2525 $nodes = array(); 2526 if ( ! isset( $theme_json['settings'] ) ) { 2527 return $nodes; 2528 } 2529 2530 // Top-level. 2531 $nodes[] = array( 2532 'path' => array( 'settings' ), 2533 'selector' => static::ROOT_CSS_PROPERTIES_SELECTOR, 2534 ); 2535 2536 // Calculate paths for blocks. 2537 if ( ! isset( $theme_json['settings']['blocks'] ) ) { 2538 return $nodes; 2539 } 2540 2541 foreach ( $theme_json['settings']['blocks'] as $name => $node ) { 2542 $selector = null; 2543 if ( isset( $selectors[ $name ]['selector'] ) ) { 2544 $selector = $selectors[ $name ]['selector']; 2545 } 2546 2547 $nodes[] = array( 2548 'path' => array( 'settings', 'blocks', $name ), 2549 'selector' => $selector, 2550 ); 2551 } 2552 2553 return $nodes; 2554 } 2555 2556 /** 2557 * Builds metadata for the style nodes, which returns in the form of: 2558 * 2559 * [ 2560 * [ 2561 * 'path' => [ 'path', 'to', 'some', 'node' ], 2562 * 'selector' => 'CSS selector for some node', 2563 * 'duotone' => 'CSS selector for duotone for some node' 2564 * ], 2565 * [ 2566 * 'path' => ['path', 'to', 'other', 'node' ], 2567 * 'selector' => 'CSS selector for other node', 2568 * 'duotone' => null 2569 * ], 2570 * ] 2571 * 2572 * @since 5.8.0 2573 * @since 6.6.0 Added options array for modifying generated nodes. 2574 * 2575 * @param array $theme_json The tree to extract style nodes from. 2576 * @param array $selectors List of selectors per block. 2577 * @param array $options { 2578 * Optional. An array of options for now used for internal purposes only (may change without notice). 2579 * 2580 * @type bool $include_block_style_variations Includes style nodes for block style variations. Default false. 2581 * } 2582 * @return array An array of style nodes metadata. 2583 */ 2584 protected static function get_style_nodes( $theme_json, $selectors = array(), $options = array() ) { 2585 $nodes = array(); 2586 if ( ! isset( $theme_json['styles'] ) ) { 2587 return $nodes; 2588 } 2589 2590 // Top-level. 2591 $nodes[] = array( 2592 'path' => array( 'styles' ), 2593 'selector' => static::ROOT_BLOCK_SELECTOR, 2594 ); 2595 2596 if ( isset( $theme_json['styles']['elements'] ) ) { 2597 foreach ( self::ELEMENTS as $element => $selector ) { 2598 if ( ! isset( $theme_json['styles']['elements'][ $element ] ) ) { 2599 continue; 2600 } 2601 $nodes[] = array( 2602 'path' => array( 'styles', 'elements', $element ), 2603 'selector' => static::ELEMENTS[ $element ], 2604 ); 2605 2606 // Handle any pseudo selectors for the element. 2607 if ( isset( static::VALID_ELEMENT_PSEUDO_SELECTORS[ $element ] ) ) { 2608 foreach ( static::VALID_ELEMENT_PSEUDO_SELECTORS[ $element ] as $pseudo_selector ) { 2609 2610 if ( isset( $theme_json['styles']['elements'][ $element ][ $pseudo_selector ] ) ) { 2611 $nodes[] = array( 2612 'path' => array( 'styles', 'elements', $element ), 2613 'selector' => static::append_to_selector( static::ELEMENTS[ $element ], $pseudo_selector ), 2614 ); 2615 } 2616 } 2617 } 2618 } 2619 } 2620 2621 // Blocks. 2622 if ( ! isset( $theme_json['styles']['blocks'] ) ) { 2623 return $nodes; 2624 } 2625 2626 $block_nodes = static::get_block_nodes( $theme_json, $selectors, $options ); 2627 foreach ( $block_nodes as $block_node ) { 2628 $nodes[] = $block_node; 2629 } 2630 2631 /** 2632 * Filters the list of style nodes with metadata. 2633 * 2634 * This allows for things like loading block CSS independently. 2635 * 2636 * @since 6.1.0 2637 * 2638 * @param array $nodes Style nodes with metadata. 2639 */ 2640 return apply_filters( 'wp_theme_json_get_style_nodes', $nodes ); 2641 } 2642 2643 /** 2644 * A public helper to get the block nodes from a theme.json file. 2645 * 2646 * @since 6.1.0 2647 * 2648 * @return array The block nodes in theme.json. 2649 */ 2650 public function get_styles_block_nodes() { 2651 return static::get_block_nodes( $this->theme_json ); 2652 } 2653 2654 /** 2655 * Returns a filtered declarations array if there is a separator block with only a background 2656 * style defined in theme.json by adding a color attribute to reflect the changes in the front. 2657 * 2658 * @since 6.1.1 2659 * 2660 * @param array $declarations List of declarations. 2661 * @return array $declarations List of declarations filtered. 2662 */ 2663 private static function update_separator_declarations( $declarations ) { 2664 $background_color = ''; 2665 $border_color_matches = false; 2666 $text_color_matches = false; 2667 2668 foreach ( $declarations as $declaration ) { 2669 if ( 'background-color' === $declaration['name'] && ! $background_color && isset( $declaration['value'] ) ) { 2670 $background_color = $declaration['value']; 2671 } elseif ( 'border-color' === $declaration['name'] ) { 2672 $border_color_matches = true; 2673 } elseif ( 'color' === $declaration['name'] ) { 2674 $text_color_matches = true; 2675 } 2676 2677 if ( $background_color && $border_color_matches && $text_color_matches ) { 2678 break; 2679 } 2680 } 2681 2682 if ( $background_color && ! $border_color_matches && ! $text_color_matches ) { 2683 $declarations[] = array( 2684 'name' => 'color', 2685 'value' => $background_color, 2686 ); 2687 } 2688 2689 return $declarations; 2690 } 2691 2692 /** 2693 * An internal method to get the block nodes from a theme.json file. 2694 * 2695 * @since 6.1.0 2696 * @since 6.3.0 Refactored and stabilized selectors API. 2697 * @since 6.6.0 Added optional selectors and options for generating block nodes. 2698 * @since 6.7.0 Added $include_node_paths_only option. 2699 * 2700 * @param array $theme_json The theme.json converted to an array. 2701 * @param array $selectors Optional list of selectors per block. 2702 * @param array $options { 2703 * Optional. An array of options for now used for internal purposes only (may change without notice). 2704 * 2705 * @type bool $include_block_style_variations Include nodes for block style variations. Default false. 2706 * @type bool $include_node_paths_only Return only block nodes node paths. Default false. 2707 * } 2708 * @return array The block nodes in theme.json. 2709 */ 2710 private static function get_block_nodes( $theme_json, $selectors = array(), $options = array() ) { 2711 $nodes = array(); 2712 2713 if ( ! isset( $theme_json['styles']['blocks'] ) ) { 2714 return $nodes; 2715 } 2716 2717 $include_variations = $options['include_block_style_variations'] ?? false; 2718 $include_node_paths_only = $options['include_node_paths_only'] ?? false; 2719 2720 // If only node paths are to be returned, skip selector assignment. 2721 if ( ! $include_node_paths_only ) { 2722 $selectors = empty( $selectors ) ? static::get_blocks_metadata() : $selectors; 2723 } 2724 2725 foreach ( $theme_json['styles']['blocks'] as $name => $node ) { 2726 $node_path = array( 'styles', 'blocks', $name ); 2727 if ( $include_node_paths_only ) { 2728 $variation_paths = array(); 2729 if ( $include_variations && isset( $node['variations'] ) ) { 2730 foreach ( $node['variations'] as $variation => $variation_node ) { 2731 $variation_paths[] = array( 2732 'path' => array( 'styles', 'blocks', $name, 'variations', $variation ), 2733 ); 2734 } 2735 } 2736 $node = array( 2737 'path' => $node_path, 2738 ); 2739 if ( ! empty( $variation_paths ) ) { 2740 $node['variations'] = $variation_paths; 2741 } 2742 $nodes[] = $node; 2743 } else { 2744 $selector = null; 2745 if ( isset( $selectors[ $name ]['selector'] ) ) { 2746 $selector = $selectors[ $name ]['selector']; 2747 } 2748 2749 $duotone_selector = null; 2750 if ( isset( $selectors[ $name ]['duotone'] ) ) { 2751 $duotone_selector = $selectors[ $name ]['duotone']; 2752 } 2753 2754 $feature_selectors = null; 2755 if ( isset( $selectors[ $name ]['selectors'] ) ) { 2756 $feature_selectors = $selectors[ $name ]['selectors']; 2757 } 2758 2759 $variation_selectors = array(); 2760 if ( $include_variations && isset( $node['variations'] ) ) { 2761 foreach ( $node['variations'] as $variation => $node ) { 2762 $variation_selectors[] = array( 2763 'path' => array( 'styles', 'blocks', $name, 'variations', $variation ), 2764 'selector' => $selectors[ $name ]['styleVariations'][ $variation ], 2765 ); 2766 } 2767 } 2768 2769 $nodes[] = array( 2770 'name' => $name, 2771 'path' => $node_path, 2772 'selector' => $selector, 2773 'selectors' => $feature_selectors, 2774 'duotone' => $duotone_selector, 2775 'features' => $feature_selectors, 2776 'variations' => $variation_selectors, 2777 'css' => $selector, 2778 ); 2779 } 2780 2781 if ( isset( $theme_json['styles']['blocks'][ $name ]['elements'] ) ) { 2782 foreach ( $theme_json['styles']['blocks'][ $name ]['elements'] as $element => $node ) { 2783 $node_path = array( 'styles', 'blocks', $name, 'elements', $element ); 2784 if ( $include_node_paths_only ) { 2785 $nodes[] = array( 2786 'path' => $node_path, 2787 ); 2788 continue; 2789 } 2790 2791 $nodes[] = array( 2792 'path' => $node_path, 2793 'selector' => $selectors[ $name ]['elements'][ $element ], 2794 ); 2795 2796 // Handle any pseudo selectors for the element. 2797 if ( isset( static::VALID_ELEMENT_PSEUDO_SELECTORS[ $element ] ) ) { 2798 foreach ( static::VALID_ELEMENT_PSEUDO_SELECTORS[ $element ] as $pseudo_selector ) { 2799 if ( isset( $theme_json['styles']['blocks'][ $name ]['elements'][ $element ][ $pseudo_selector ] ) ) { 2800 $node_path = array( 'styles', 'blocks', $name, 'elements', $element ); 2801 if ( $include_node_paths_only ) { 2802 $nodes[] = array( 2803 'path' => $node_path, 2804 ); 2805 continue; 2806 } 2807 2808 $nodes[] = array( 2809 'path' => $node_path, 2810 'selector' => static::append_to_selector( $selectors[ $name ]['elements'][ $element ], $pseudo_selector ), 2811 ); 2812 } 2813 } 2814 } 2815 } 2816 } 2817 } 2818 2819 return $nodes; 2820 } 2821 2822 /** 2823 * Gets the CSS rules for a particular block from theme.json. 2824 * 2825 * @since 6.1.0 2826 * @since 6.6.0 Setting a min-height of HTML when root styles have a background gradient or image. 2827 * Updated general global styles specificity to 0-1-0. 2828 * Fixed custom CSS output in block style variations. 2829 * 2830 * @param array $block_metadata Metadata about the block to get styles for. 2831 * @return string Styles for the block. 2832 */ 2833 public function get_styles_for_block( $block_metadata ) { 2834 $node = _wp_array_get( $this->theme_json, $block_metadata['path'], array() ); 2835 $use_root_padding = isset( $this->theme_json['settings']['useRootPaddingAwareAlignments'] ) && true === $this->theme_json['settings']['useRootPaddingAwareAlignments']; 2836 $selector = $block_metadata['selector']; 2837 $settings = isset( $this->theme_json['settings'] ) ? $this->theme_json['settings'] : array(); 2838 $feature_declarations = static::get_feature_declarations_for_node( $block_metadata, $node ); 2839 $is_root_selector = static::ROOT_BLOCK_SELECTOR === $selector; 2840 2841 // If there are style variations, generate the declarations for them, including any feature selectors the block may have. 2842 $style_variation_declarations = array(); 2843 $style_variation_custom_css = array(); 2844 if ( ! empty( $block_metadata['variations'] ) ) { 2845 foreach ( $block_metadata['variations'] as $style_variation ) { 2846 $style_variation_node = _wp_array_get( $this->theme_json, $style_variation['path'], array() ); 2847 $clean_style_variation_selector = trim( $style_variation['selector'] ); 2848 2849 // Generate any feature/subfeature style declarations for the current style variation. 2850 $variation_declarations = static::get_feature_declarations_for_node( $block_metadata, $style_variation_node ); 2851 2852 // Combine selectors with style variation's selector and add to overall style variation declarations. 2853 foreach ( $variation_declarations as $current_selector => $new_declarations ) { 2854 /* 2855 * Clean up any whitespace between comma separated selectors. 2856 * This prevents these spaces breaking compound selectors such as: 2857 * - `.wp-block-list:not(.wp-block-list .wp-block-list)` 2858 * - `.wp-block-image img, .wp-block-image.my-class img` 2859 */ 2860 $clean_current_selector = preg_replace( '/,\s+/', ',', $current_selector ); 2861 $shortened_selector = str_replace( $block_metadata['selector'], '', $clean_current_selector ); 2862 2863 // Prepend the variation selector to the current selector. 2864 $split_selectors = explode( ',', $shortened_selector ); 2865 $updated_selectors = array_map( 2866 static function ( $split_selector ) use ( $clean_style_variation_selector ) { 2867 return $clean_style_variation_selector . $split_selector; 2868 }, 2869 $split_selectors 2870 ); 2871 $combined_selectors = implode( ',', $updated_selectors ); 2872 2873 // Add the new declarations to the overall results under the modified selector. 2874 $style_variation_declarations[ $combined_selectors ] = $new_declarations; 2875 } 2876 2877 // Compute declarations for remaining styles not covered by feature level selectors. 2878 $style_variation_declarations[ $style_variation['selector'] ] = static::compute_style_properties( $style_variation_node, $settings, null, $this->theme_json ); 2879 // Store custom CSS for the style variation. 2880 if ( isset( $style_variation_node['css'] ) ) { 2881 $style_variation_custom_css[ $style_variation['selector'] ] = $this->process_blocks_custom_css( $style_variation_node['css'], $style_variation['selector'] ); 2882 } 2883 } 2884 } 2885 /* 2886 * Get a reference to element name from path. 2887 * $block_metadata['path'] = array( 'styles','elements','link' ); 2888 * Make sure that $block_metadata['path'] describes an element node, like [ 'styles', 'element', 'link' ]. 2889 * Skip non-element paths like just ['styles']. 2890 */ 2891 $is_processing_element = in_array( 'elements', $block_metadata['path'], true ); 2892 2893 $current_element = $is_processing_element ? $block_metadata['path'][ count( $block_metadata['path'] ) - 1 ] : null; 2894 2895 $element_pseudo_allowed = array(); 2896 2897 if ( isset( static::VALID_ELEMENT_PSEUDO_SELECTORS[ $current_element ] ) ) { 2898 $element_pseudo_allowed = static::VALID_ELEMENT_PSEUDO_SELECTORS[ $current_element ]; 2899 } 2900 2901 /* 2902 * Check for allowed pseudo classes (e.g. ":hover") from the $selector ("a:hover"). 2903 * This also resets the array keys. 2904 */ 2905 $pseudo_matches = array_values( 2906 array_filter( 2907 $element_pseudo_allowed, 2908 static function ( $pseudo_selector ) use ( $selector ) { 2909 /* 2910 * Check if the pseudo selector is in the current selector, 2911 * ensuring it is not followed by a dash (e.g., :focus should not match :focus-visible). 2912 */ 2913 return preg_match( '/' . preg_quote( $pseudo_selector, '/' ) . '(?!-)/', $selector ) === 1; 2914 } 2915 ) 2916 ); 2917 2918 $pseudo_selector = isset( $pseudo_matches[0] ) ? $pseudo_matches[0] : null; 2919 2920 /* 2921 * If the current selector is a pseudo selector that's defined in the allow list for the current 2922 * element then compute the style properties for it. 2923 * Otherwise just compute the styles for the default selector as normal. 2924 */ 2925 if ( $pseudo_selector && isset( $node[ $pseudo_selector ] ) && 2926 isset( static::VALID_ELEMENT_PSEUDO_SELECTORS[ $current_element ] ) 2927 && in_array( $pseudo_selector, static::VALID_ELEMENT_PSEUDO_SELECTORS[ $current_element ], true ) 2928 ) { 2929 $declarations = static::compute_style_properties( $node[ $pseudo_selector ], $settings, null, $this->theme_json, $selector, $use_root_padding ); 2930 } else { 2931 $declarations = static::compute_style_properties( $node, $settings, null, $this->theme_json, $selector, $use_root_padding ); 2932 } 2933 2934 $block_rules = ''; 2935 2936 /* 2937 * 1. Bespoke declaration modifiers: 2938 * - 'filter': Separate the declarations that use the general selector 2939 * from the ones using the duotone selector. 2940 * - 'background|background-image': set the html min-height to 100% 2941 * to ensure the background covers the entire viewport. 2942 */ 2943 $declarations_duotone = array(); 2944 $should_set_root_min_height = false; 2945 2946 foreach ( $declarations as $index => $declaration ) { 2947 if ( 'filter' === $declaration['name'] ) { 2948 /* 2949 * 'unset' filters happen when a filter is unset 2950 * in the site-editor UI. Because the 'unset' value 2951 * in the user origin overrides the value in the 2952 * theme origin, we can skip rendering anything 2953 * here as no filter needs to be applied anymore. 2954 * So only add declarations to with values other 2955 * than 'unset'. 2956 */ 2957 if ( 'unset' !== $declaration['value'] ) { 2958 $declarations_duotone[] = $declaration; 2959 } 2960 unset( $declarations[ $index ] ); 2961 } 2962 2963 if ( $is_root_selector && ( 'background-image' === $declaration['name'] || 'background' === $declaration['name'] ) ) { 2964 $should_set_root_min_height = true; 2965 } 2966 } 2967 2968 /* 2969 * If root styles has a background-image or a background (gradient) set, 2970 * set the min-height to '100%'. Minus `--wp-admin--admin-bar--height` for logged-in view. 2971 * Setting the CSS rule on the HTML tag ensures background gradients and images behave similarly, 2972 * and matches the behavior of the site editor. 2973 */ 2974 if ( $should_set_root_min_height ) { 2975 $block_rules .= static::to_ruleset( 2976 'html', 2977 array( 2978 array( 2979 'name' => 'min-height', 2980 'value' => 'calc(100% - var(--wp-admin--admin-bar--height, 0px))', 2981 ), 2982 ) 2983 ); 2984 } 2985 2986 // Update declarations if there are separators with only background color defined. 2987 if ( '.wp-block-separator' === $selector ) { 2988 $declarations = static::update_separator_declarations( $declarations ); 2989 } 2990 2991 /* 2992 * Root selector (body) styles should not be wrapped in `:root where()` to keep 2993 * specificity at (0,0,1) and maintain backwards compatibility. 2994 * 2995 * Top-level element styles using element-only specificity selectors should 2996 * not get wrapped in `:root :where()` to maintain backwards compatibility. 2997 * 2998 * Pseudo classes, e.g. :hover, :focus etc., are a class-level selector so 2999 * still need to be wrapped in `:root :where` to cap specificity for nested 3000 * variations etc. Pseudo selectors won't match the ELEMENTS selector exactly. 3001 */ 3002 $element_only_selector = $is_root_selector || ( 3003 $current_element && 3004 isset( static::ELEMENTS[ $current_element ] ) && 3005 // buttons, captions etc. still need `:root :where()` as they are class based selectors. 3006 ! isset( static::__EXPERIMENTAL_ELEMENT_CLASS_NAMES[ $current_element ] ) && 3007 static::ELEMENTS[ $current_element ] === $selector 3008 ); 3009 3010 // 2. Generate and append the rules that use the general selector. 3011 $general_selector = $element_only_selector ? $selector : ":root :where($selector)"; 3012 $block_rules .= static::to_ruleset( $general_selector, $declarations ); 3013 3014 // 3. Generate and append the rules that use the duotone selector. 3015 if ( isset( $block_metadata['duotone'] ) && ! empty( $declarations_duotone ) ) { 3016 $block_rules .= static::to_ruleset( $block_metadata['duotone'], $declarations_duotone ); 3017 } 3018 3019 // 4. Generate Layout block gap styles. 3020 if ( 3021 ! $is_root_selector && 3022 ! empty( $block_metadata['name'] ) 3023 ) { 3024 $block_rules .= $this->get_layout_styles( $block_metadata ); 3025 } 3026 3027 // 5. Generate and append the feature level rulesets. 3028 foreach ( $feature_declarations as $feature_selector => $individual_feature_declarations ) { 3029 $block_rules .= static::to_ruleset( ":root :where($feature_selector)", $individual_feature_declarations ); 3030 } 3031 3032 // 6. Generate and append the style variation rulesets. 3033 foreach ( $style_variation_declarations as $style_variation_selector => $individual_style_variation_declarations ) { 3034 $block_rules .= static::to_ruleset( ":root :where($style_variation_selector)", $individual_style_variation_declarations ); 3035 if ( isset( $style_variation_custom_css[ $style_variation_selector ] ) ) { 3036 $block_rules .= $style_variation_custom_css[ $style_variation_selector ]; 3037 } 3038 } 3039 3040 // 7. Generate and append any custom CSS rules. 3041 if ( isset( $node['css'] ) && ! $is_root_selector ) { 3042 $block_rules .= $this->process_blocks_custom_css( $node['css'], $selector ); 3043 } 3044 3045 return $block_rules; 3046 } 3047 3048 /** 3049 * Outputs the CSS for layout rules on the root. 3050 * 3051 * @since 6.1.0 3052 * @since 6.6.0 Use `ROOT_CSS_PROPERTIES_SELECTOR` for CSS custom properties and improved consistency of root padding rules. 3053 * Updated specificity of body margin reset and first/last child selectors. 3054 * 3055 * @param string $selector The root node selector. 3056 * @param array $block_metadata The metadata for the root block. 3057 * @return string The additional root rules CSS. 3058 */ 3059 public function get_root_layout_rules( $selector, $block_metadata ) { 3060 $css = ''; 3061 $settings = isset( $this->theme_json['settings'] ) ? $this->theme_json['settings'] : array(); 3062 $use_root_padding = isset( $this->theme_json['settings']['useRootPaddingAwareAlignments'] ) && true === $this->theme_json['settings']['useRootPaddingAwareAlignments']; 3063 3064 /* 3065 * If there are content and wide widths in theme.json, output them 3066 * as custom properties on the body element so all blocks can use them. 3067 */ 3068 if ( isset( $settings['layout']['contentSize'] ) || isset( $settings['layout']['wideSize'] ) ) { 3069 $content_size = isset( $settings['layout']['contentSize'] ) ? $settings['layout']['contentSize'] : $settings['layout']['wideSize']; 3070 $content_size = static::is_safe_css_declaration( 'max-width', $content_size ) ? $content_size : 'initial'; 3071 $wide_size = isset( $settings['layout']['wideSize'] ) ? $settings['layout']['wideSize'] : $settings['layout']['contentSize']; 3072 $wide_size = static::is_safe_css_declaration( 'max-width', $wide_size ) ? $wide_size : 'initial'; 3073 $css .= static::ROOT_CSS_PROPERTIES_SELECTOR . ' { --wp--style--global--content-size: ' . $content_size . ';'; 3074 $css .= '--wp--style--global--wide-size: ' . $wide_size . '; }'; 3075 } 3076 3077 /* 3078 * Reset default browser margin on the body element. 3079 * This is set on the body selector **before** generating the ruleset 3080 * from the `theme.json`. This is to ensure that if the `theme.json` declares 3081 * `margin` in its `spacing` declaration for the `body` element then these 3082 * user-generated values take precedence in the CSS cascade. 3083 * @link https://github.com/WordPress/gutenberg/issues/36147. 3084 */ 3085 $css .= ':where(body) { margin: 0; }'; 3086 3087 if ( $use_root_padding ) { 3088 // Top and bottom padding are applied to the outer block container. 3089 $css .= '.wp-site-blocks { padding-top: var(--wp--style--root--padding-top); padding-bottom: var(--wp--style--root--padding-bottom); }'; 3090 // Right and left padding are applied to the first container with `.has-global-padding` class. 3091 $css .= '.has-global-padding { padding-right: var(--wp--style--root--padding-right); padding-left: var(--wp--style--root--padding-left); }'; 3092 // Alignfull children of the container with left and right padding have negative margins so they can still be full width. 3093 $css .= '.has-global-padding > .alignfull { margin-right: calc(var(--wp--style--root--padding-right) * -1); margin-left: calc(var(--wp--style--root--padding-left) * -1); }'; 3094 // Nested children of the container with left and right padding that are not full aligned do not get padding, unless they are direct children of an alignfull flow container. 3095 $css .= '.has-global-padding :where(:not(.alignfull.is-layout-flow) > .has-global-padding:not(.wp-block-block, .alignfull)) { padding-right: 0; padding-left: 0; }'; 3096 // Alignfull direct children of the containers that are targeted by the rule above do not need negative margins. 3097 $css .= '.has-global-padding :where(:not(.alignfull.is-layout-flow) > .has-global-padding:not(.wp-block-block, .alignfull)) > .alignfull { margin-left: 0; margin-right: 0; }'; 3098 } 3099 3100 $css .= '.wp-site-blocks > .alignleft { float: left; margin-right: 2em; }'; 3101 $css .= '.wp-site-blocks > .alignright { float: right; margin-left: 2em; }'; 3102 $css .= '.wp-site-blocks > .aligncenter { justify-content: center; margin-left: auto; margin-right: auto; }'; 3103 3104 // Block gap styles will be output unless explicitly set to `null`. See static::PROTECTED_PROPERTIES. 3105 if ( isset( $this->theme_json['settings']['spacing']['blockGap'] ) ) { 3106 $block_gap_value = static::get_property_value( $this->theme_json, array( 'styles', 'spacing', 'blockGap' ) ); 3107 $css .= ":where(.wp-site-blocks) > * { margin-block-start: $block_gap_value; margin-block-end: 0; }"; 3108 $css .= ':where(.wp-site-blocks) > :first-child { margin-block-start: 0; }'; 3109 $css .= ':where(.wp-site-blocks) > :last-child { margin-block-end: 0; }'; 3110 3111 // For backwards compatibility, ensure the legacy block gap CSS variable is still available. 3112 $css .= static::ROOT_CSS_PROPERTIES_SELECTOR . " { --wp--style--block-gap: $block_gap_value; }"; 3113 } 3114 $css .= $this->get_layout_styles( $block_metadata ); 3115 3116 return $css; 3117 } 3118 3119 /** 3120 * For metadata values that can either be booleans or paths to booleans, gets the value. 3121 * 3122 * $data = array( 3123 * 'color' => array( 3124 * 'defaultPalette' => true 3125 * ) 3126 * ); 3127 * 3128 * static::get_metadata_boolean( $data, false ); 3129 * // => false 3130 * 3131 * static::get_metadata_boolean( $data, array( 'color', 'defaultPalette' ) ); 3132 * // => true 3133 * 3134 * @since 6.0.0 3135 * 3136 * @param array $data The data to inspect. 3137 * @param bool|array $path Boolean or path to a boolean. 3138 * @param bool $default_value Default value if the referenced path is missing. 3139 * Default false. 3140 * @return bool Value of boolean metadata. 3141 */ 3142 protected static function get_metadata_boolean( $data, $path, $default_value = false ) { 3143 if ( is_bool( $path ) ) { 3144 return $path; 3145 } 3146 3147 if ( is_array( $path ) ) { 3148 $value = _wp_array_get( $data, $path ); 3149 if ( null !== $value ) { 3150 return $value; 3151 } 3152 } 3153 3154 return $default_value; 3155 } 3156 3157 /** 3158 * Merges new incoming data. 3159 * 3160 * @since 5.8.0 3161 * @since 5.9.0 Duotone preset also has origins. 3162 * @since 6.7.0 Replace background image objects during merge. 3163 * 3164 * @param WP_Theme_JSON $incoming Data to merge. 3165 */ 3166 public function merge( $incoming ) { 3167 $incoming_data = $incoming->get_raw_data(); 3168 $this->theme_json = array_replace_recursive( $this->theme_json, $incoming_data ); 3169 3170 /* 3171 * Recompute all the spacing sizes based on the new hierarchy of data. In the constructor 3172 * spacingScale and spacingSizes are both keyed by origin and VALID_ORIGINS is ordered, so 3173 * we can allow partial spacingScale data to inherit missing data from earlier layers when 3174 * computing the spacing sizes. 3175 * 3176 * This happens before the presets are merged to ensure that default spacing sizes can be 3177 * removed from the theme origin if $prevent_override is true. 3178 */ 3179 $flattened_spacing_scale = array(); 3180 foreach ( static::VALID_ORIGINS as $origin ) { 3181 $scale_path = array( 'settings', 'spacing', 'spacingScale', $origin ); 3182 3183 // Apply the base spacing scale to the current layer. 3184 $base_spacing_scale = _wp_array_get( $this->theme_json, $scale_path, array() ); 3185 $flattened_spacing_scale = array_replace( $flattened_spacing_scale, $base_spacing_scale ); 3186 3187 $spacing_scale = _wp_array_get( $incoming_data, $scale_path, null ); 3188 if ( ! isset( $spacing_scale ) ) { 3189 continue; 3190 } 3191 3192 // Allow partial scale settings by merging with lower layers. 3193 $flattened_spacing_scale = array_replace( $flattened_spacing_scale, $spacing_scale ); 3194 3195 // Generate and merge the scales for this layer. 3196 $sizes_path = array( 'settings', 'spacing', 'spacingSizes', $origin ); 3197 $spacing_sizes = _wp_array_get( $incoming_data, $sizes_path, array() ); 3198 $spacing_scale_sizes = static::compute_spacing_sizes( $flattened_spacing_scale ); 3199 $merged_spacing_sizes = static::merge_spacing_sizes( $spacing_scale_sizes, $spacing_sizes ); 3200 3201 _wp_array_set( $incoming_data, $sizes_path, $merged_spacing_sizes ); 3202 } 3203 3204 /* 3205 * The array_replace_recursive algorithm merges at the leaf level, 3206 * but we don't want leaf arrays to be merged, so we overwrite it. 3207 * 3208 * For leaf values that are sequential arrays it will use the numeric indexes for replacement. 3209 * We rather replace the existing with the incoming value, if it exists. 3210 * This is the case of spacing.units. 3211 * 3212 * For leaf values that are associative arrays it will merge them as expected. 3213 * This is also not the behavior we want for the current associative arrays (presets). 3214 * We rather replace the existing with the incoming value, if it exists. 3215 * This happens, for example, when we merge data from theme.json upon existing 3216 * theme supports or when we merge anything coming from the same source twice. 3217 * This is the case of color.palette, color.gradients, color.duotone, 3218 * typography.fontSizes, or typography.fontFamilies. 3219 * 3220 * Additionally, for some preset types, we also want to make sure the 3221 * values they introduce don't conflict with default values. We do so 3222 * by checking the incoming slugs for theme presets and compare them 3223 * with the equivalent default presets: if a slug is present as a default 3224 * we remove it from the theme presets. 3225 */ 3226 $nodes = static::get_setting_nodes( $incoming_data ); 3227 $slugs_global = static::get_default_slugs( $this->theme_json, array( 'settings' ) ); 3228 foreach ( $nodes as $node ) { 3229 // Replace the spacing.units. 3230 $path = $node['path']; 3231 $path[] = 'spacing'; 3232 $path[] = 'units'; 3233 3234 $content = _wp_array_get( $incoming_data, $path, null ); 3235 if ( isset( $content ) ) { 3236 _wp_array_set( $this->theme_json, $path, $content ); 3237 } 3238 3239 // Replace the presets. 3240 foreach ( static::PRESETS_METADATA as $preset_metadata ) { 3241 $prevent_override = $preset_metadata['prevent_override']; 3242 if ( is_array( $prevent_override ) ) { 3243 $prevent_override = _wp_array_get( $this->theme_json['settings'], $preset_metadata['prevent_override'] ); 3244 } 3245 3246 foreach ( static::VALID_ORIGINS as $origin ) { 3247 $base_path = $node['path']; 3248 foreach ( $preset_metadata['path'] as $leaf ) { 3249 $base_path[] = $leaf; 3250 } 3251 3252 $path = $base_path; 3253 $path[] = $origin; 3254 3255 $content = _wp_array_get( $incoming_data, $path, null ); 3256 if ( ! isset( $content ) ) { 3257 continue; 3258 } 3259 3260 // Set names for theme presets based on the slug if they are not set and can use default names. 3261 if ( 'theme' === $origin && $preset_metadata['use_default_names'] ) { 3262 foreach ( $content as $key => $item ) { 3263 if ( ! isset( $item['name'] ) ) { 3264 $name = static::get_name_from_defaults( $item['slug'], $base_path ); 3265 if ( null !== $name ) { 3266 $content[ $key ]['name'] = $name; 3267 } 3268 } 3269 } 3270 } 3271 3272 // Filter out default slugs from theme presets when defaults should not be overridden. 3273 if ( 'theme' === $origin && $prevent_override ) { 3274 $slugs_node = static::get_default_slugs( $this->theme_json, $node['path'] ); 3275 $preset_global = _wp_array_get( $slugs_global, $preset_metadata['path'], array() ); 3276 $preset_node = _wp_array_get( $slugs_node, $preset_metadata['path'], array() ); 3277 $preset_slugs = array_merge_recursive( $preset_global, $preset_node ); 3278 3279 $content = static::filter_slugs( $content, $preset_slugs ); 3280 } 3281 3282 _wp_array_set( $this->theme_json, $path, $content ); 3283 } 3284 } 3285 } 3286 3287 /* 3288 * Style values are merged at the leaf level, however 3289 * some values provide exceptions, namely style values that are 3290 * objects and represent unique definitions for the style. 3291 */ 3292 $style_nodes = static::get_block_nodes( 3293 $this->theme_json, 3294 array(), 3295 array( 'include_node_paths_only' => true ) 3296 ); 3297 3298 // Add top-level styles. 3299 $style_nodes[] = array( 'path' => array( 'styles' ) ); 3300 3301 foreach ( $style_nodes as $style_node ) { 3302 $path = $style_node['path']; 3303 /* 3304 * Background image styles should be replaced, not merged, 3305 * as they themselves are specific object definitions for the style. 3306 */ 3307 $background_image_path = array_merge( $path, static::PROPERTIES_METADATA['background-image'] ); 3308 $content = _wp_array_get( $incoming_data, $background_image_path, null ); 3309 if ( isset( $content ) ) { 3310 _wp_array_set( $this->theme_json, $background_image_path, $content ); 3311 } 3312 } 3313 } 3314 3315 /** 3316 * Converts all filter (duotone) presets into SVGs. 3317 * 3318 * @since 5.9.1 3319 * 3320 * @param array $origins List of origins to process. 3321 * @return string SVG filters. 3322 */ 3323 public function get_svg_filters( $origins ) { 3324 $blocks_metadata = static::get_blocks_metadata(); 3325 $setting_nodes = static::get_setting_nodes( $this->theme_json, $blocks_metadata ); 3326 3327 $filters = ''; 3328 foreach ( $setting_nodes as $metadata ) { 3329 $node = _wp_array_get( $this->theme_json, $metadata['path'], array() ); 3330 if ( empty( $node['color']['duotone'] ) ) { 3331 continue; 3332 } 3333 3334 $duotone_presets = $node['color']['duotone']; 3335 3336 foreach ( $origins as $origin ) { 3337 if ( ! isset( $duotone_presets[ $origin ] ) ) { 3338 continue; 3339 } 3340 foreach ( $duotone_presets[ $origin ] as $duotone_preset ) { 3341 $filters .= WP_Duotone::get_filter_svg_from_preset( $duotone_preset ); 3342 } 3343 } 3344 } 3345 3346 return $filters; 3347 } 3348 3349 /** 3350 * Determines whether a presets should be overridden or not. 3351 * 3352 * @since 5.9.0 3353 * @deprecated 6.0.0 Use {@see 'get_metadata_boolean'} instead. 3354 * 3355 * @param array $theme_json The theme.json like structure to inspect. 3356 * @param array $path Path to inspect. 3357 * @param bool|array $override Data to compute whether to override the preset. 3358 * @return bool 3359 */ 3360 protected static function should_override_preset( $theme_json, $path, $override ) { 3361 _deprecated_function( __METHOD__, '6.0.0', 'get_metadata_boolean' ); 3362 3363 if ( is_bool( $override ) ) { 3364 return $override; 3365 } 3366 3367 /* 3368 * The relationship between whether to override the defaults 3369 * and whether the defaults are enabled is inverse: 3370 * 3371 * - If defaults are enabled => theme presets should not be overridden 3372 * - If defaults are disabled => theme presets should be overridden 3373 * 3374 * For example, a theme sets defaultPalette to false, 3375 * making the default palette hidden from the user. 3376 * In that case, we want all the theme presets to be present, 3377 * so they should override the defaults. 3378 */ 3379 if ( is_array( $override ) ) { 3380 $value = _wp_array_get( $theme_json, array_merge( $path, $override ) ); 3381 if ( isset( $value ) ) { 3382 return ! $value; 3383 } 3384 3385 // Search the top-level key if none was found for this node. 3386 $value = _wp_array_get( $theme_json, array_merge( array( 'settings' ), $override ) ); 3387 if ( isset( $value ) ) { 3388 return ! $value; 3389 } 3390 3391 return true; 3392 } 3393 } 3394 3395 /** 3396 * Returns the default slugs for all the presets in an associative array 3397 * whose keys are the preset paths and the leaves is the list of slugs. 3398 * 3399 * For example: 3400 * 3401 * array( 3402 * 'color' => array( 3403 * 'palette' => array( 'slug-1', 'slug-2' ), 3404 * 'gradients' => array( 'slug-3', 'slug-4' ), 3405 * ), 3406 * ) 3407 * 3408 * @since 5.9.0 3409 * 3410 * @param array $data A theme.json like structure. 3411 * @param array $node_path The path to inspect. It's 'settings' by default. 3412 * @return array 3413 */ 3414 protected static function get_default_slugs( $data, $node_path ) { 3415 $slugs = array(); 3416 3417 foreach ( static::PRESETS_METADATA as $metadata ) { 3418 $path = $node_path; 3419 foreach ( $metadata['path'] as $leaf ) { 3420 $path[] = $leaf; 3421 } 3422 $path[] = 'default'; 3423 3424 $preset = _wp_array_get( $data, $path, null ); 3425 if ( ! isset( $preset ) ) { 3426 continue; 3427 } 3428 3429 $slugs_for_preset = array(); 3430 foreach ( $preset as $item ) { 3431 if ( isset( $item['slug'] ) ) { 3432 $slugs_for_preset[] = $item['slug']; 3433 } 3434 } 3435 3436 _wp_array_set( $slugs, $metadata['path'], $slugs_for_preset ); 3437 } 3438 3439 return $slugs; 3440 } 3441 3442 /** 3443 * Gets a `default`'s preset name by a provided slug. 3444 * 3445 * @since 5.9.0 3446 * 3447 * @param string $slug The slug we want to find a match from default presets. 3448 * @param array $base_path The path to inspect. It's 'settings' by default. 3449 * @return string|null 3450 */ 3451 protected function get_name_from_defaults( $slug, $base_path ) { 3452 $path = $base_path; 3453 $path[] = 'default'; 3454 $default_content = _wp_array_get( $this->theme_json, $path, null ); 3455 if ( ! $default_content ) { 3456 return null; 3457 } 3458 foreach ( $default_content as $item ) { 3459 if ( $slug === $item['slug'] ) { 3460 return $item['name']; 3461 } 3462 } 3463 return null; 3464 } 3465 3466 /** 3467 * Removes the preset values whose slug is equal to any of given slugs. 3468 * 3469 * @since 5.9.0 3470 * 3471 * @param array $node The node with the presets to validate. 3472 * @param array $slugs The slugs that should not be overridden. 3473 * @return array The new node. 3474 */ 3475 protected static function filter_slugs( $node, $slugs ) { 3476 if ( empty( $slugs ) ) { 3477 return $node; 3478 } 3479 3480 $new_node = array(); 3481 foreach ( $node as $value ) { 3482 if ( isset( $value['slug'] ) && ! in_array( $value['slug'], $slugs, true ) ) { 3483 $new_node[] = $value; 3484 } 3485 } 3486 3487 return $new_node; 3488 } 3489 3490 /** 3491 * Removes insecure data from theme.json. 3492 * 3493 * @since 5.9.0 3494 * @since 6.3.2 Preserves global styles block variations when securing styles. 3495 * @since 6.6.0 Updated to allow variation element styles and $origin parameter. 3496 * 3497 * @param array $theme_json Structure to sanitize. 3498 * @param string $origin Optional. What source of data this object represents. 3499 * One of 'blocks', 'default', 'theme', or 'custom'. Default 'theme'. 3500 * @return array Sanitized structure. 3501 */ 3502 public static function remove_insecure_properties( $theme_json, $origin = 'theme' ) { 3503 if ( ! in_array( $origin, static::VALID_ORIGINS, true ) ) { 3504 $origin = 'theme'; 3505 } 3506 3507 $sanitized = array(); 3508 3509 $theme_json = WP_Theme_JSON_Schema::migrate( $theme_json, $origin ); 3510 3511 $blocks_metadata = static::get_blocks_metadata(); 3512 $valid_block_names = array_keys( $blocks_metadata ); 3513 $valid_element_names = array_keys( static::ELEMENTS ); 3514 $valid_variations = static::get_valid_block_style_variations( $blocks_metadata ); 3515 3516 $theme_json = static::sanitize( $theme_json, $valid_block_names, $valid_element_names, $valid_variations ); 3517 3518 $blocks_metadata = static::get_blocks_metadata(); 3519 $style_options = array( 'include_block_style_variations' => true ); // Allow variations data. 3520 $style_nodes = static::get_style_nodes( $theme_json, $blocks_metadata, $style_options ); 3521 3522 foreach ( $style_nodes as $metadata ) { 3523 $input = _wp_array_get( $theme_json, $metadata['path'], array() ); 3524 if ( empty( $input ) ) { 3525 continue; 3526 } 3527 3528 // The global styles custom CSS is not sanitized, but can only be edited by users with 'edit_css' capability. 3529 if ( isset( $input['css'] ) && current_user_can( 'edit_css' ) ) { 3530 $output = $input; 3531 } else { 3532 $output = static::remove_insecure_styles( $input ); 3533 } 3534 3535 /* 3536 * Get a reference to element name from path. 3537 * $metadata['path'] = array( 'styles', 'elements', 'link' ); 3538 */ 3539 $current_element = $metadata['path'][ count( $metadata['path'] ) - 1 ]; 3540 3541 /* 3542 * $output is stripped of pseudo selectors. Re-add and process them 3543 * or insecure styles here. 3544 */ 3545 if ( isset( static::VALID_ELEMENT_PSEUDO_SELECTORS[ $current_element ] ) ) { 3546 foreach ( static::VALID_ELEMENT_PSEUDO_SELECTORS[ $current_element ] as $pseudo_selector ) { 3547 if ( isset( $input[ $pseudo_selector ] ) ) { 3548 $output[ $pseudo_selector ] = static::remove_insecure_styles( $input[ $pseudo_selector ] ); 3549 } 3550 } 3551 } 3552 3553 if ( ! empty( $output ) ) { 3554 _wp_array_set( $sanitized, $metadata['path'], $output ); 3555 } 3556 3557 if ( isset( $metadata['variations'] ) ) { 3558 foreach ( $metadata['variations'] as $variation ) { 3559 $variation_input = _wp_array_get( $theme_json, $variation['path'], array() ); 3560 if ( empty( $variation_input ) ) { 3561 continue; 3562 } 3563 3564 $variation_output = static::remove_insecure_styles( $variation_input ); 3565 3566 if ( isset( $variation_input['blocks'] ) ) { 3567 $variation_output['blocks'] = static::remove_insecure_inner_block_styles( $variation_input['blocks'] ); 3568 } 3569 3570 if ( isset( $variation_input['elements'] ) ) { 3571 $variation_output['elements'] = static::remove_insecure_element_styles( $variation_input['elements'] ); 3572 } 3573 3574 if ( ! empty( $variation_output ) ) { 3575 _wp_array_set( $sanitized, $variation['path'], $variation_output ); 3576 } 3577 } 3578 } 3579 } 3580 3581 $setting_nodes = static::get_setting_nodes( $theme_json ); 3582 foreach ( $setting_nodes as $metadata ) { 3583 $input = _wp_array_get( $theme_json, $metadata['path'], array() ); 3584 if ( empty( $input ) ) { 3585 continue; 3586 } 3587 3588 $output = static::remove_insecure_settings( $input ); 3589 if ( ! empty( $output ) ) { 3590 _wp_array_set( $sanitized, $metadata['path'], $output ); 3591 } 3592 } 3593 3594 if ( empty( $sanitized['styles'] ) ) { 3595 unset( $theme_json['styles'] ); 3596 } else { 3597 $theme_json['styles'] = $sanitized['styles']; 3598 } 3599 3600 if ( empty( $sanitized['settings'] ) ) { 3601 unset( $theme_json['settings'] ); 3602 } else { 3603 $theme_json['settings'] = $sanitized['settings']; 3604 } 3605 3606 return $theme_json; 3607 } 3608 3609 /** 3610 * Remove insecure element styles within a variation or block. 3611 * 3612 * @since 6.8.0 3613 * 3614 * @param array $elements The elements to process. 3615 * @return array The sanitized elements styles. 3616 */ 3617 protected static function remove_insecure_element_styles( $elements ) { 3618 $sanitized = array(); 3619 $valid_element_names = array_keys( static::ELEMENTS ); 3620 3621 foreach ( $valid_element_names as $element_name ) { 3622 $element_input = $elements[ $element_name ] ?? null; 3623 if ( $element_input ) { 3624 $element_output = static::remove_insecure_styles( $element_input ); 3625 3626 if ( isset( static::VALID_ELEMENT_PSEUDO_SELECTORS[ $element_name ] ) ) { 3627 foreach ( static::VALID_ELEMENT_PSEUDO_SELECTORS[ $element_name ] as $pseudo_selector ) { 3628 if ( isset( $element_input[ $pseudo_selector ] ) ) { 3629 $element_output[ $pseudo_selector ] = static::remove_insecure_styles( $element_input[ $pseudo_selector ] ); 3630 } 3631 } 3632 } 3633 3634 $sanitized[ $element_name ] = $element_output; 3635 } 3636 } 3637 return $sanitized; 3638 } 3639 3640 /** 3641 * Remove insecure styles from inner blocks and their elements. 3642 * 3643 * @since 6.8.0 3644 * 3645 * @param array $blocks The block styles to process. 3646 * @return array Sanitized block type styles. 3647 */ 3648 protected static function remove_insecure_inner_block_styles( $blocks ) { 3649 $sanitized = array(); 3650 foreach ( $blocks as $block_type => $block_input ) { 3651 $block_output = static::remove_insecure_styles( $block_input ); 3652 3653 if ( isset( $block_input['elements'] ) ) { 3654 $block_output['elements'] = static::remove_insecure_element_styles( $block_input['elements'] ); 3655 } 3656 3657 $sanitized[ $block_type ] = $block_output; 3658 } 3659 return $sanitized; 3660 } 3661 3662 /** 3663 * Processes a setting node and returns the same node 3664 * without the insecure settings. 3665 * 3666 * @since 5.9.0 3667 * 3668 * @param array $input Node to process. 3669 * @return array 3670 */ 3671 protected static function remove_insecure_settings( $input ) { 3672 $output = array(); 3673 foreach ( static::PRESETS_METADATA as $preset_metadata ) { 3674 foreach ( static::VALID_ORIGINS as $origin ) { 3675 $path_with_origin = $preset_metadata['path']; 3676 $path_with_origin[] = $origin; 3677 $presets = _wp_array_get( $input, $path_with_origin, null ); 3678 if ( null === $presets ) { 3679 continue; 3680 } 3681 3682 $escaped_preset = array(); 3683 foreach ( $presets as $preset ) { 3684 if ( 3685 esc_attr( esc_html( $preset['name'] ) ) === $preset['name'] && 3686 sanitize_html_class( $preset['slug'] ) === $preset['slug'] 3687 ) { 3688 $value = null; 3689 if ( isset( $preset_metadata['value_key'], $preset[ $preset_metadata['value_key'] ] ) ) { 3690 $value = $preset[ $preset_metadata['value_key'] ]; 3691 } elseif ( 3692 isset( $preset_metadata['value_func'] ) && 3693 is_callable( $preset_metadata['value_func'] ) 3694 ) { 3695 $value = call_user_func( $preset_metadata['value_func'], $preset ); 3696 } 3697 3698 $preset_is_valid = true; 3699 foreach ( $preset_metadata['properties'] as $property ) { 3700 if ( ! static::is_safe_css_declaration( $property, $value ) ) { 3701 $preset_is_valid = false; 3702 break; 3703 } 3704 } 3705 3706 if ( $preset_is_valid ) { 3707 $escaped_preset[] = $preset; 3708 } 3709 } 3710 } 3711 3712 if ( ! empty( $escaped_preset ) ) { 3713 _wp_array_set( $output, $path_with_origin, $escaped_preset ); 3714 } 3715 } 3716 } 3717 3718 // Ensure indirect properties not included in any `PRESETS_METADATA` value are allowed. 3719 static::remove_indirect_properties( $input, $output ); 3720 3721 return $output; 3722 } 3723 3724 /** 3725 * Processes a style node and returns the same node 3726 * without the insecure styles. 3727 * 3728 * @since 5.9.0 3729 * 3730 * @param array $input Node to process. 3731 * @return array 3732 */ 3733 protected static function remove_insecure_styles( $input ) { 3734 $output = array(); 3735 $declarations = static::compute_style_properties( $input ); 3736 3737 foreach ( $declarations as $declaration ) { 3738 if ( static::is_safe_css_declaration( $declaration['name'], $declaration['value'] ) ) { 3739 $path = static::PROPERTIES_METADATA[ $declaration['name'] ]; 3740 3741 /* 3742 * Check the value isn't an array before adding so as to not 3743 * double up shorthand and longhand styles. 3744 */ 3745 $value = _wp_array_get( $input, $path, array() ); 3746 if ( ! is_array( $value ) ) { 3747 _wp_array_set( $output, $path, $value ); 3748 } 3749 } 3750 } 3751 3752 // Ensure indirect properties not handled by `compute_style_properties` are allowed. 3753 static::remove_indirect_properties( $input, $output ); 3754 3755 return $output; 3756 } 3757 3758 /** 3759 * Checks that a declaration provided by the user is safe. 3760 * 3761 * @since 5.9.0 3762 * 3763 * @param string $property_name Property name in a CSS declaration, i.e. the `color` in `color: red`. 3764 * @param string $property_value Value in a CSS declaration, i.e. the `red` in `color: red`. 3765 * @return bool 3766 */ 3767 protected static function is_safe_css_declaration( $property_name, $property_value ) { 3768 $style_to_validate = $property_name . ': ' . $property_value; 3769 $filtered = esc_html( safecss_filter_attr( $style_to_validate ) ); 3770 return ! empty( trim( $filtered ) ); 3771 } 3772 3773 /** 3774 * Removes indirect properties from the given input node and 3775 * sets in the given output node. 3776 * 3777 * @since 6.2.0 3778 * 3779 * @param array $input Node to process. 3780 * @param array $output The processed node. Passed by reference. 3781 */ 3782 private static function remove_indirect_properties( $input, &$output ) { 3783 foreach ( static::INDIRECT_PROPERTIES_METADATA as $property => $paths ) { 3784 foreach ( $paths as $path ) { 3785 $value = _wp_array_get( $input, $path ); 3786 if ( 3787 is_string( $value ) && 3788 static::is_safe_css_declaration( $property, $value ) 3789 ) { 3790 _wp_array_set( $output, $path, $value ); 3791 } 3792 } 3793 } 3794 } 3795 3796 /** 3797 * Returns the raw data. 3798 * 3799 * @since 5.8.0 3800 * 3801 * @return array Raw data. 3802 */ 3803 public function get_raw_data() { 3804 return $this->theme_json; 3805 } 3806 3807 /** 3808 * Transforms the given editor settings according the 3809 * add_theme_support format to the theme.json format. 3810 * 3811 * @since 5.8.0 3812 * 3813 * @param array $settings Existing editor settings. 3814 * @return array Config that adheres to the theme.json schema. 3815 */ 3816 public static function get_from_editor_settings( $settings ) { 3817 $theme_settings = array( 3818 'version' => static::LATEST_SCHEMA, 3819 'settings' => array(), 3820 ); 3821 3822 // Deprecated theme supports. 3823 if ( isset( $settings['disableCustomColors'] ) ) { 3824 $theme_settings['settings']['color']['custom'] = ! $settings['disableCustomColors']; 3825 } 3826 3827 if ( isset( $settings['disableCustomGradients'] ) ) { 3828 $theme_settings['settings']['color']['customGradient'] = ! $settings['disableCustomGradients']; 3829 } 3830 3831 if ( isset( $settings['disableCustomFontSizes'] ) ) { 3832 $theme_settings['settings']['typography']['customFontSize'] = ! $settings['disableCustomFontSizes']; 3833 } 3834 3835 if ( isset( $settings['enableCustomLineHeight'] ) ) { 3836 $theme_settings['settings']['typography']['lineHeight'] = $settings['enableCustomLineHeight']; 3837 } 3838 3839 if ( isset( $settings['enableCustomUnits'] ) ) { 3840 $theme_settings['settings']['spacing']['units'] = ( true === $settings['enableCustomUnits'] ) ? 3841 array( 'px', 'em', 'rem', 'vh', 'vw', '%' ) : 3842 $settings['enableCustomUnits']; 3843 } 3844 3845 if ( isset( $settings['colors'] ) ) { 3846 $theme_settings['settings']['color']['palette'] = $settings['colors']; 3847 } 3848 3849 if ( isset( $settings['gradients'] ) ) { 3850 $theme_settings['settings']['color']['gradients'] = $settings['gradients']; 3851 } 3852 3853 if ( isset( $settings['fontSizes'] ) ) { 3854 $font_sizes = $settings['fontSizes']; 3855 // Back-compatibility for presets without units. 3856 foreach ( $font_sizes as $key => $font_size ) { 3857 if ( is_numeric( $font_size['size'] ) ) { 3858 $font_sizes[ $key ]['size'] = $font_size['size'] . 'px'; 3859 } 3860 } 3861 $theme_settings['settings']['typography']['fontSizes'] = $font_sizes; 3862 } 3863 3864 if ( isset( $settings['enableCustomSpacing'] ) ) { 3865 $theme_settings['settings']['spacing']['padding'] = $settings['enableCustomSpacing']; 3866 } 3867 3868 if ( isset( $settings['spacingSizes'] ) ) { 3869 $theme_settings['settings']['spacing']['spacingSizes'] = $settings['spacingSizes']; 3870 } 3871 3872 return $theme_settings; 3873 } 3874 3875 /** 3876 * Returns the current theme's wanted patterns(slugs) to be 3877 * registered from Pattern Directory. 3878 * 3879 * @since 6.0.0 3880 * 3881 * @return string[] 3882 */ 3883 public function get_patterns() { 3884 if ( isset( $this->theme_json['patterns'] ) && is_array( $this->theme_json['patterns'] ) ) { 3885 return $this->theme_json['patterns']; 3886 } 3887 return array(); 3888 } 3889 3890 /** 3891 * Returns a valid theme.json as provided by a theme. 3892 * 3893 * Unlike get_raw_data() this returns the presets flattened, as provided by a theme. 3894 * This also uses appearanceTools instead of their opt-ins if all of them are true. 3895 * 3896 * @since 6.0.0 3897 * 3898 * @return array 3899 */ 3900 public function get_data() { 3901 $output = $this->theme_json; 3902 $nodes = static::get_setting_nodes( $output ); 3903 3904 /** 3905 * Flatten the theme & custom origins into a single one. 3906 * 3907 * For example, the following: 3908 * 3909 * { 3910 * "settings": { 3911 * "color": { 3912 * "palette": { 3913 * "theme": [ {} ], 3914 * "custom": [ {} ] 3915 * } 3916 * } 3917 * } 3918 * } 3919 * 3920 * will be converted to: 3921 * 3922 * { 3923 * "settings": { 3924 * "color": { 3925 * "palette": [ {} ] 3926 * } 3927 * } 3928 * } 3929 */ 3930 foreach ( $nodes as $node ) { 3931 foreach ( static::PRESETS_METADATA as $preset_metadata ) { 3932 $path = $node['path']; 3933 foreach ( $preset_metadata['path'] as $preset_metadata_path ) { 3934 $path[] = $preset_metadata_path; 3935 } 3936 $preset = _wp_array_get( $output, $path, null ); 3937 if ( null === $preset ) { 3938 continue; 3939 } 3940 3941 $items = array(); 3942 if ( isset( $preset['theme'] ) ) { 3943 foreach ( $preset['theme'] as $item ) { 3944 $slug = $item['slug']; 3945 unset( $item['slug'] ); 3946 $items[ $slug ] = $item; 3947 } 3948 } 3949 if ( isset( $preset['custom'] ) ) { 3950 foreach ( $preset['custom'] as $item ) { 3951 $slug = $item['slug']; 3952 unset( $item['slug'] ); 3953 $items[ $slug ] = $item; 3954 } 3955 } 3956 $flattened_preset = array(); 3957 foreach ( $items as $slug => $value ) { 3958 $flattened_preset[] = array_merge( array( 'slug' => (string) $slug ), $value ); 3959 } 3960 _wp_array_set( $output, $path, $flattened_preset ); 3961 } 3962 } 3963 3964 /* 3965 * If all of the static::APPEARANCE_TOOLS_OPT_INS are true, 3966 * this code unsets them and sets 'appearanceTools' instead. 3967 */ 3968 foreach ( $nodes as $node ) { 3969 $all_opt_ins_are_set = true; 3970 foreach ( static::APPEARANCE_TOOLS_OPT_INS as $opt_in_path ) { 3971 $full_path = $node['path']; 3972 foreach ( $opt_in_path as $opt_in_path_item ) { 3973 $full_path[] = $opt_in_path_item; 3974 } 3975 /* 3976 * Use "unset prop" as a marker instead of "null" because 3977 * "null" can be a valid value for some props (e.g. blockGap). 3978 */ 3979 $opt_in_value = _wp_array_get( $output, $full_path, 'unset prop' ); 3980 if ( 'unset prop' === $opt_in_value ) { 3981 $all_opt_ins_are_set = false; 3982 break; 3983 } 3984 } 3985 3986 if ( $all_opt_ins_are_set ) { 3987 $node_path_with_appearance_tools = $node['path']; 3988 $node_path_with_appearance_tools[] = 'appearanceTools'; 3989 _wp_array_set( $output, $node_path_with_appearance_tools, true ); 3990 foreach ( static::APPEARANCE_TOOLS_OPT_INS as $opt_in_path ) { 3991 $full_path = $node['path']; 3992 foreach ( $opt_in_path as $opt_in_path_item ) { 3993 $full_path[] = $opt_in_path_item; 3994 } 3995 /* 3996 * Use "unset prop" as a marker instead of "null" because 3997 * "null" can be a valid value for some props (e.g. blockGap). 3998 */ 3999 $opt_in_value = _wp_array_get( $output, $full_path, 'unset prop' ); 4000 if ( true !== $opt_in_value ) { 4001 continue; 4002 } 4003 4004 /* 4005 * The following could be improved to be path independent. 4006 * At the moment it relies on a couple of assumptions: 4007 * 4008 * - all opt-ins having a path of size 2. 4009 * - there's two sources of settings: the top-level and the block-level. 4010 */ 4011 if ( 4012 ( 1 === count( $node['path'] ) ) && 4013 ( 'settings' === $node['path'][0] ) 4014 ) { 4015 // Top-level settings. 4016 unset( $output['settings'][ $opt_in_path[0] ][ $opt_in_path[1] ] ); 4017 if ( empty( $output['settings'][ $opt_in_path[0] ] ) ) { 4018 unset( $output['settings'][ $opt_in_path[0] ] ); 4019 } 4020 } elseif ( 4021 ( 3 === count( $node['path'] ) ) && 4022 ( 'settings' === $node['path'][0] ) && 4023 ( 'blocks' === $node['path'][1] ) 4024 ) { 4025 // Block-level settings. 4026 $block_name = $node['path'][2]; 4027 unset( $output['settings']['blocks'][ $block_name ][ $opt_in_path[0] ][ $opt_in_path[1] ] ); 4028 if ( empty( $output['settings']['blocks'][ $block_name ][ $opt_in_path[0] ] ) ) { 4029 unset( $output['settings']['blocks'][ $block_name ][ $opt_in_path[0] ] ); 4030 } 4031 } 4032 } 4033 } 4034 } 4035 4036 wp_recursive_ksort( $output ); 4037 4038 return $output; 4039 } 4040 4041 /** 4042 * Sets the spacingSizes array based on the spacingScale values from theme.json. 4043 * 4044 * @since 6.1.0 4045 * @deprecated 6.6.0 No longer used as the spacingSizes are automatically 4046 * generated in the constructor and merge methods instead 4047 * of manually after instantiation. 4048 * 4049 * @return null|void 4050 */ 4051 public function set_spacing_sizes() { 4052 _deprecated_function( __METHOD__, '6.6.0' ); 4053 4054 $spacing_scale = isset( $this->theme_json['settings']['spacing']['spacingScale'] ) 4055 ? $this->theme_json['settings']['spacing']['spacingScale'] 4056 : array(); 4057 4058 if ( ! isset( $spacing_scale['steps'] ) 4059 || ! is_numeric( $spacing_scale['steps'] ) 4060 || ! isset( $spacing_scale['mediumStep'] ) 4061 || ! isset( $spacing_scale['unit'] ) 4062 || ! isset( $spacing_scale['operator'] ) 4063 || ! isset( $spacing_scale['increment'] ) 4064 || ! isset( $spacing_scale['steps'] ) 4065 || ! is_numeric( $spacing_scale['increment'] ) 4066 || ! is_numeric( $spacing_scale['mediumStep'] ) 4067 || ( '+' !== $spacing_scale['operator'] && '*' !== $spacing_scale['operator'] ) ) { 4068 if ( ! empty( $spacing_scale ) ) { 4069 wp_trigger_error( 4070 __METHOD__, 4071 sprintf( 4072 /* translators: 1: theme.json, 2: settings.spacing.spacingScale */ 4073 __( 'Some of the %1$s %2$s values are invalid' ), 4074 'theme.json', 4075 'settings.spacing.spacingScale' 4076 ), 4077 E_USER_NOTICE 4078 ); 4079 } 4080 return null; 4081 } 4082 4083 // If theme authors want to prevent the generation of the core spacing scale they can set their theme.json spacingScale.steps to 0. 4084 if ( 0 === $spacing_scale['steps'] ) { 4085 return null; 4086 } 4087 4088 $spacing_sizes = static::compute_spacing_sizes( $spacing_scale ); 4089 4090 // If there are 7 or fewer steps in the scale revert to numbers for labels instead of t-shirt sizes. 4091 if ( $spacing_scale['steps'] <= 7 ) { 4092 for ( $spacing_sizes_count = 0; $spacing_sizes_count < count( $spacing_sizes ); $spacing_sizes_count++ ) { 4093 $spacing_sizes[ $spacing_sizes_count ]['name'] = (string) ( $spacing_sizes_count + 1 ); 4094 } 4095 } 4096 4097 _wp_array_set( $this->theme_json, array( 'settings', 'spacing', 'spacingSizes', 'default' ), $spacing_sizes ); 4098 } 4099 4100 /** 4101 * Merges two sets of spacing size presets. 4102 * 4103 * @since 6.6.0 4104 * 4105 * @param array $base The base set of spacing sizes. 4106 * @param array $incoming The set of spacing sizes to merge with the base. Duplicate slugs will override the base values. 4107 * @return array The merged set of spacing sizes. 4108 */ 4109 private static function merge_spacing_sizes( $base, $incoming ) { 4110 // Preserve the order if there are no base (spacingScale) values. 4111 if ( empty( $base ) ) { 4112 return $incoming; 4113 } 4114 $merged = array(); 4115 foreach ( $base as $item ) { 4116 $merged[ $item['slug'] ] = $item; 4117 } 4118 foreach ( $incoming as $item ) { 4119 $merged[ $item['slug'] ] = $item; 4120 } 4121 ksort( $merged, SORT_NUMERIC ); 4122 return array_values( $merged ); 4123 } 4124 4125 /** 4126 * Generates a set of spacing sizes by starting with a medium size and 4127 * applying an operator with an increment value to generate the rest of the 4128 * sizes outward from the medium size. The medium slug is '50' with the rest 4129 * of the slugs being 10 apart. The generated names use t-shirt sizing. 4130 * 4131 * Example: 4132 * 4133 * $spacing_scale = array( 4134 * 'steps' => 4, 4135 * 'mediumStep' => 16, 4136 * 'unit' => 'px', 4137 * 'operator' => '+', 4138 * 'increment' => 2, 4139 * ); 4140 * $spacing_sizes = static::compute_spacing_sizes( $spacing_scale ); 4141 * // -> array( 4142 * // array( 'name' => 'Small', 'slug' => '40', 'size' => '14px' ), 4143 * // array( 'name' => 'Medium', 'slug' => '50', 'size' => '16px' ), 4144 * // array( 'name' => 'Large', 'slug' => '60', 'size' => '18px' ), 4145 * // array( 'name' => 'X-Large', 'slug' => '70', 'size' => '20px' ), 4146 * // ) 4147 * 4148 * @since 6.6.0 4149 * 4150 * @param array $spacing_scale { 4151 * The spacing scale values. All are required. 4152 * 4153 * @type int $steps The number of steps in the scale. (up to 10 steps are supported.) 4154 * @type float $mediumStep The middle value that gets the slug '50'. (For even number of steps, this becomes the first middle value.) 4155 * @type string $unit The CSS unit to use for the sizes. 4156 * @type string $operator The mathematical operator to apply to generate the other sizes. Either '+' or '*'. 4157 * @type float $increment The value used with the operator to generate the other sizes. 4158 * } 4159 * @return array The spacing sizes presets or an empty array if some spacing scale values are missing or invalid. 4160 */ 4161 private static function compute_spacing_sizes( $spacing_scale ) { 4162 /* 4163 * This condition is intentionally missing some checks on ranges for the values in order to 4164 * keep backwards compatibility with the previous implementation. 4165 */ 4166 if ( 4167 ! isset( $spacing_scale['steps'] ) || 4168 ! is_numeric( $spacing_scale['steps'] ) || 4169 0 === $spacing_scale['steps'] || 4170 ! isset( $spacing_scale['mediumStep'] ) || 4171 ! is_numeric( $spacing_scale['mediumStep'] ) || 4172 ! isset( $spacing_scale['unit'] ) || 4173 ! isset( $spacing_scale['operator'] ) || 4174 ( '+' !== $spacing_scale['operator'] && '*' !== $spacing_scale['operator'] ) || 4175 ! isset( $spacing_scale['increment'] ) || 4176 ! is_numeric( $spacing_scale['increment'] ) 4177 ) { 4178 return array(); 4179 } 4180 4181 $unit = '%' === $spacing_scale['unit'] ? '%' : sanitize_title( $spacing_scale['unit'] ); 4182 $current_step = $spacing_scale['mediumStep']; 4183 $steps_mid_point = round( $spacing_scale['steps'] / 2, 0 ); 4184 $x_small_count = null; 4185 $below_sizes = array(); 4186 $slug = 40; 4187 $remainder = 0; 4188 4189 for ( $below_midpoint_count = $steps_mid_point - 1; $spacing_scale['steps'] > 1 && $slug > 0 && $below_midpoint_count > 0; $below_midpoint_count-- ) { 4190 if ( '+' === $spacing_scale['operator'] ) { 4191 $current_step -= $spacing_scale['increment']; 4192 } elseif ( $spacing_scale['increment'] > 1 ) { 4193 $current_step /= $spacing_scale['increment']; 4194 } else { 4195 $current_step *= $spacing_scale['increment']; 4196 } 4197 4198 if ( $current_step <= 0 ) { 4199 $remainder = $below_midpoint_count; 4200 break; 4201 } 4202 4203 $below_sizes[] = array( 4204 /* translators: %s: Digit to indicate multiple of sizing, eg. 2X-Small. */ 4205 'name' => $below_midpoint_count === $steps_mid_point - 1 ? __( 'Small' ) : sprintf( __( '%sX-Small' ), (string) $x_small_count ), 4206 'slug' => (string) $slug, 4207 'size' => round( $current_step, 2 ) . $unit, 4208 ); 4209 4210 if ( $below_midpoint_count === $steps_mid_point - 2 ) { 4211 $x_small_count = 2; 4212 } 4213 4214 if ( $below_midpoint_count < $steps_mid_point - 2 ) { 4215 ++$x_small_count; 4216 } 4217 4218 $slug -= 10; 4219 } 4220 4221 $below_sizes = array_reverse( $below_sizes ); 4222 4223 $below_sizes[] = array( 4224 'name' => __( 'Medium' ), 4225 'slug' => '50', 4226 'size' => $spacing_scale['mediumStep'] . $unit, 4227 ); 4228 4229 $current_step = $spacing_scale['mediumStep']; 4230 $x_large_count = null; 4231 $above_sizes = array(); 4232 $slug = 60; 4233 $steps_above = ( $spacing_scale['steps'] - $steps_mid_point ) + $remainder; 4234 4235 for ( $above_midpoint_count = 0; $above_midpoint_count < $steps_above; $above_midpoint_count++ ) { 4236 $current_step = '+' === $spacing_scale['operator'] 4237 ? $current_step + $spacing_scale['increment'] 4238 : ( $spacing_scale['increment'] >= 1 ? $current_step * $spacing_scale['increment'] : $current_step / $spacing_scale['increment'] ); 4239 4240 $above_sizes[] = array( 4241 /* translators: %s: Digit to indicate multiple of sizing, eg. 2X-Large. */ 4242 'name' => 0 === $above_midpoint_count ? __( 'Large' ) : sprintf( __( '%sX-Large' ), (string) $x_large_count ), 4243 'slug' => (string) $slug, 4244 'size' => round( $current_step, 2 ) . $unit, 4245 ); 4246 4247 if ( 1 === $above_midpoint_count ) { 4248 $x_large_count = 2; 4249 } 4250 4251 if ( $above_midpoint_count > 1 ) { 4252 ++$x_large_count; 4253 } 4254 4255 $slug += 10; 4256 } 4257 4258 $spacing_sizes = $below_sizes; 4259 foreach ( $above_sizes as $above_sizes_item ) { 4260 $spacing_sizes[] = $above_sizes_item; 4261 } 4262 4263 return $spacing_sizes; 4264 } 4265 4266 /** 4267 * This is used to convert the internal representation of variables to the CSS representation. 4268 * For example, `var:preset|color|vivid-green-cyan` becomes `var(--wp--preset--color--vivid-green-cyan)`. 4269 * 4270 * @since 6.3.0 4271 * 4272 * @param string $value The variable such as var:preset|color|vivid-green-cyan to convert. 4273 * @return string The converted variable. 4274 */ 4275 private static function convert_custom_properties( $value ) { 4276 $prefix = 'var:'; 4277 $prefix_len = strlen( $prefix ); 4278 $token_in = '|'; 4279 $token_out = '--'; 4280 if ( str_starts_with( $value, $prefix ) ) { 4281 $unwrapped_name = str_replace( 4282 $token_in, 4283 $token_out, 4284 substr( $value, $prefix_len ) 4285 ); 4286 $value = "var(--wp--$unwrapped_name)"; 4287 } 4288 4289 return $value; 4290 } 4291 4292 /** 4293 * Given a tree, converts the internal representation of variables to the CSS representation. 4294 * It is recursive and modifies the input in-place. 4295 * 4296 * @since 6.3.0 4297 * 4298 * @param array $tree Input to process. 4299 * @return array The modified $tree. 4300 */ 4301 private static function resolve_custom_css_format( $tree ) { 4302 $prefix = 'var:'; 4303 4304 foreach ( $tree as $key => $data ) { 4305 if ( is_string( $data ) && str_starts_with( $data, $prefix ) ) { 4306 $tree[ $key ] = self::convert_custom_properties( $data ); 4307 } elseif ( is_array( $data ) ) { 4308 $tree[ $key ] = self::resolve_custom_css_format( $data ); 4309 } 4310 } 4311 4312 return $tree; 4313 } 4314 4315 /** 4316 * Returns the selectors metadata for a block. 4317 * 4318 * @since 6.3.0 4319 * 4320 * @param object $block_type The block type. 4321 * @param string $root_selector The block's root selector. 4322 * @return array The custom selectors set by the block. 4323 */ 4324 protected static function get_block_selectors( $block_type, $root_selector ) { 4325 if ( ! empty( $block_type->selectors ) ) { 4326 return $block_type->selectors; 4327 } 4328 4329 $selectors = array( 'root' => $root_selector ); 4330 foreach ( static::BLOCK_SUPPORT_FEATURE_LEVEL_SELECTORS as $key => $feature ) { 4331 $feature_selector = wp_get_block_css_selector( $block_type, $key ); 4332 if ( null !== $feature_selector ) { 4333 $selectors[ $feature ] = array( 'root' => $feature_selector ); 4334 } 4335 } 4336 4337 return $selectors; 4338 } 4339 4340 /** 4341 * Generates all the element selectors for a block. 4342 * 4343 * @since 6.3.0 4344 * 4345 * @param string $root_selector The block's root CSS selector. 4346 * @return array The block's element selectors. 4347 */ 4348 protected static function get_block_element_selectors( $root_selector ) { 4349 /* 4350 * Assign defaults, then override those that the block sets by itself. 4351 * If the block selector is compounded, will append the element to each 4352 * individual block selector. 4353 */ 4354 $block_selectors = explode( ',', $root_selector ); 4355 $element_selectors = array(); 4356 foreach ( static::ELEMENTS as $el_name => $el_selector ) { 4357 $element_selector = array(); 4358 foreach ( $block_selectors as $selector ) { 4359 if ( $selector === $el_selector ) { 4360 $element_selector = array( $el_selector ); 4361 break; 4362 } 4363 $element_selector[] = static::prepend_to_selector( $el_selector, $selector . ' ' ); 4364 } 4365 $element_selectors[ $el_name ] = implode( ',', $element_selector ); 4366 } 4367 4368 return $element_selectors; 4369 } 4370 4371 /** 4372 * Generates style declarations for a node's features e.g., color, border, 4373 * typography etc. that have custom selectors in their related block's 4374 * metadata. 4375 * 4376 * @since 6.3.0 4377 * 4378 * @param object $metadata The related block metadata containing selectors. 4379 * @param object $node A merged theme.json node for block or variation. 4380 * @return array The style declarations for the node's features with custom 4381 * selectors. 4382 */ 4383 protected function get_feature_declarations_for_node( $metadata, &$node ) { 4384 $declarations = array(); 4385 4386 if ( ! isset( $metadata['selectors'] ) ) { 4387 return $declarations; 4388 } 4389 4390 $settings = isset( $this->theme_json['settings'] ) 4391 ? $this->theme_json['settings'] 4392 : array(); 4393 4394 foreach ( $metadata['selectors'] as $feature => $feature_selectors ) { 4395 /* 4396 * Skip if this is the block's root selector or the block doesn't 4397 * have any styles for the feature. 4398 */ 4399 if ( 'root' === $feature || empty( $node[ $feature ] ) ) { 4400 continue; 4401 } 4402 4403 if ( is_array( $feature_selectors ) ) { 4404 foreach ( $feature_selectors as $subfeature => $subfeature_selector ) { 4405 if ( 'root' === $subfeature || empty( $node[ $feature ][ $subfeature ] ) ) { 4406 continue; 4407 } 4408 4409 /* 4410 * Create temporary node containing only the subfeature data 4411 * to leverage existing `compute_style_properties` function. 4412 */ 4413 $subfeature_node = array( 4414 $feature => array( 4415 $subfeature => $node[ $feature ][ $subfeature ], 4416 ), 4417 ); 4418 4419 // Generate style declarations. 4420 $new_declarations = static::compute_style_properties( $subfeature_node, $settings, null, $this->theme_json ); 4421 4422 // Merge subfeature declarations into feature declarations. 4423 if ( isset( $declarations[ $subfeature_selector ] ) ) { 4424 foreach ( $new_declarations as $new_declaration ) { 4425 $declarations[ $subfeature_selector ][] = $new_declaration; 4426 } 4427 } else { 4428 $declarations[ $subfeature_selector ] = $new_declarations; 4429 } 4430 4431 /* 4432 * Remove the subfeature from the block's node now its 4433 * styles will be included under its own selector not the 4434 * block's. 4435 */ 4436 unset( $node[ $feature ][ $subfeature ] ); 4437 } 4438 } 4439 4440 /* 4441 * Now subfeatures have been processed and removed we can process 4442 * feature root selector or simple string selector. 4443 */ 4444 if ( 4445 is_string( $feature_selectors ) || 4446 ( isset( $feature_selectors['root'] ) && $feature_selectors['root'] ) 4447 ) { 4448 $feature_selector = is_string( $feature_selectors ) ? $feature_selectors : $feature_selectors['root']; 4449 4450 /* 4451 * Create temporary node containing only the feature data 4452 * to leverage existing `compute_style_properties` function. 4453 */ 4454 $feature_node = array( $feature => $node[ $feature ] ); 4455 4456 // Generate the style declarations. 4457 $new_declarations = static::compute_style_properties( $feature_node, $settings, null, $this->theme_json ); 4458 4459 /* 4460 * Merge new declarations with any that already exist for 4461 * the feature selector. This may occur when multiple block 4462 * support features use the same custom selector. 4463 */ 4464 if ( isset( $declarations[ $feature_selector ] ) ) { 4465 foreach ( $new_declarations as $new_declaration ) { 4466 $declarations[ $feature_selector ][] = $new_declaration; 4467 } 4468 } else { 4469 $declarations[ $feature_selector ] = $new_declarations; 4470 } 4471 4472 /* 4473 * Remove the feature from the block's node now its styles 4474 * will be included under its own selector not the block's. 4475 */ 4476 unset( $node[ $feature ] ); 4477 } 4478 } 4479 4480 return $declarations; 4481 } 4482 4483 /** 4484 * Replaces CSS variables with their values in place. 4485 * 4486 * @since 6.3.0 4487 * @since 6.5.0 Check for empty style before processing its value. 4488 * 4489 * @param array $styles CSS declarations to convert. 4490 * @param array $values key => value pairs to use for replacement. 4491 * @return array 4492 */ 4493 private static function convert_variables_to_value( $styles, $values ) { 4494 foreach ( $styles as $key => $style ) { 4495 if ( empty( $style ) ) { 4496 continue; 4497 } 4498 4499 if ( is_array( $style ) ) { 4500 $styles[ $key ] = self::convert_variables_to_value( $style, $values ); 4501 continue; 4502 } 4503 4504 if ( 0 <= strpos( $style, 'var(' ) ) { 4505 // find all the variables in the string in the form of var(--variable-name, fallback), with fallback in the second capture group. 4506 4507 $has_matches = preg_match_all( '/var\(([^),]+)?,?\s?(\S+)?\)/', $style, $var_parts ); 4508 4509 if ( $has_matches ) { 4510 $resolved_style = $styles[ $key ]; 4511 foreach ( $var_parts[1] as $index => $var_part ) { 4512 $key_in_values = 'var(' . $var_part . ')'; 4513 $rule_to_replace = $var_parts[0][ $index ]; // the css rule to replace e.g. var(--wp--preset--color--vivid-green-cyan). 4514 $fallback = $var_parts[2][ $index ]; // the fallback value. 4515 $resolved_style = str_replace( 4516 array( 4517 $rule_to_replace, 4518 $fallback, 4519 ), 4520 array( 4521 isset( $values[ $key_in_values ] ) ? $values[ $key_in_values ] : $rule_to_replace, 4522 isset( $values[ $fallback ] ) ? $values[ $fallback ] : $fallback, 4523 ), 4524 $resolved_style 4525 ); 4526 } 4527 $styles[ $key ] = $resolved_style; 4528 } 4529 } 4530 } 4531 4532 return $styles; 4533 } 4534 4535 /** 4536 * Resolves the values of CSS variables in the given styles. 4537 * 4538 * @since 6.3.0 4539 * 4540 * @param WP_Theme_JSON $theme_json The theme json resolver. 4541 * @return WP_Theme_JSON The $theme_json with resolved variables. 4542 */ 4543 public static function resolve_variables( $theme_json ) { 4544 $settings = $theme_json->get_settings(); 4545 $styles = $theme_json->get_raw_data()['styles']; 4546 $preset_vars = static::compute_preset_vars( $settings, static::VALID_ORIGINS ); 4547 $theme_vars = static::compute_theme_vars( $settings ); 4548 $vars = array_reduce( 4549 array_merge( $preset_vars, $theme_vars ), 4550 function ( $carry, $item ) { 4551 $name = $item['name']; 4552 $carry[ "var({$name})" ] = $item['value']; 4553 return $carry; 4554 }, 4555 array() 4556 ); 4557 4558 $theme_json->theme_json['styles'] = self::convert_variables_to_value( $styles, $vars ); 4559 return $theme_json; 4560 } 4561 4562 /** 4563 * Generates a selector for a block style variation. 4564 * 4565 * @since 6.5.0 4566 * 4567 * @param string $variation_name Name of the block style variation. 4568 * @param string $block_selector CSS selector for the block. 4569 * @return string Block selector with block style variation selector added to it. 4570 */ 4571 protected static function get_block_style_variation_selector( $variation_name, $block_selector ) { 4572 $variation_class = ".is-style-$variation_name"; 4573 4574 if ( ! $block_selector ) { 4575 return $variation_class; 4576 } 4577 4578 $limit = 1; 4579 $selector_parts = explode( ',', $block_selector ); 4580 $result = array(); 4581 4582 foreach ( $selector_parts as $part ) { 4583 $result[] = preg_replace_callback( 4584 '/((?::\([^)]+\))?\s*)([^\s:]+)/', 4585 function ( $matches ) use ( $variation_class ) { 4586 return $matches[1] . $matches[2] . $variation_class; 4587 }, 4588 $part, 4589 $limit 4590 ); 4591 } 4592 4593 return implode( ',', $result ); 4594 } 4595 4596 /** 4597 * Collects valid block style variations keyed by block type. 4598 * 4599 * @since 6.6.0 4600 * @since 6.8.0 Added the `$blocks_metadata` parameter. 4601 * 4602 * @param array $blocks_metadata Optional. List of metadata per block. Default is the metadata for all blocks. 4603 * @return array Valid block style variations by block type. 4604 */ 4605 protected static function get_valid_block_style_variations( $blocks_metadata = array() ) { 4606 $valid_variations = array(); 4607 $blocks_metadata = empty( $blocks_metadata ) ? static::get_blocks_metadata() : $blocks_metadata; 4608 foreach ( $blocks_metadata as $block_name => $block_meta ) { 4609 if ( ! isset( $block_meta['styleVariations'] ) ) { 4610 continue; 4611 } 4612 $valid_variations[ $block_name ] = array_keys( $block_meta['styleVariations'] ); 4613 } 4614 4615 return $valid_variations; 4616 } 4617 }
title
Description
Body
title
Description
Body
title
Description
Body
title
Body
| Generated : Thu Apr 3 08:20:01 2025 | Cross-referenced by PHPXref |