Add block nesting governance for theme.json

[alecgeatches]

What?

Combined PR from @ingeniumed and @alecgeatches.

We have added the ability to govern individual block settings via theme.json when they are nested inside each other. This means a second set of settings can be applied to blocks based on the context in which it is used.

Why?

We want to be able to control what block settings are offered to the user in more ways than core currently allows

We only want certain colors to be available in specific places and the number of available options can be overwhelming in situations where only a couple of options would be appropriate.

@dabowman has a great explanation and examples of the reasoning behind these changes in #41547. We used this issue and our discussions with David as the basis for this PR. In short, we'd like to extend Gutenberg to support governance options used by design systems.

How?

We've made changes to the way theme.json parsing and validation is handled, and extended useSetting to take advantage of nested block settings:

• Switch the validation of theme.json → settings.blocks to recurse through each block and validate inner nested blocks rather than removing them. It now validates each block individually against the settings schema, and then assembles it all together. After parsing, all existing code continues to work but passes nested block settings relative to their parent into the block editor.

• Switch the parsing/generation of the get_setting_nodes() function to recurse through each block, and keep the parent in mind when generating selectors and paths to the respective block. This way, the settings output takes into account the nested blocks, applies PRESETS_METADATA transforms to sub-blocks correctly, and doesn't just process the top level parents.

• useSetting has been extended to apply settings in the block editor for nested blocks. This works by processing a block's parents in the block editor, finding nested settings, and applying those to the current block on useSetting calls. A few notes on the implementation:

  • Nested settings use a system similar to CSS specificity (with only one weight category) to determine which settings should apply to the current block. More-nested settings override less-nested settings, and when settings at the same nesting level disagree, the last setting wins.
  • There will be a small performance impact to useSetting based on the number of nested parents, but this impact should be small. The internal function getNestedSetting runs through each of a block's parents and only recurses further if relevant nested settings has been added to theme.json. For normal blocks nested a few times, the performance impact will be the same as the existing __experimentalSettings code that checks a block's parents.
  • Tests for useSetting have been added in packages/block-editor/src/components/use-setting/test/index.js. These tests document the current behavior and may be helpful in understanding the implementation.

Testing Instructions

• A theme.json resolver test has been added in test_theme_with_nested_block_settings() which uses this example theme.json. It can be run via the standard PHPUnit tests:

  npm run test:unit:php

• An end-to-end test has been added here to test nested options from a theme show up correctly in the block editor. This can be run via e2e tests:

  npm run test:e2e

• The test suite for useSetting can be run via:

  npm run test:unit -- use-setting/test/index.js

For manual testing, the theme.json linked above and in the Demo section below can be used as a starting point. Generally, you should be able to take any set of regular settings.block settings, add them nested below another block, and those settings should take priority in the block editor when a block is nested in the same way.

Demo

Here is an example of a core/heading block with different color palette options at different levels of nesting:

1. core/heading
2. core/quote → core/heading
3. core/quote → core/media-text →core/heading

Screen.Recording.2022-09-01.at.15.24.45.mov

A pared down version of the theme.json used for the demo can be found here.

[github-actions]

👋 Thanks for your first Pull Request and for helping build the future of Gutenberg and WordPress, @alecgeatches! In case you missed it, we'd love to have you join us in our Slack community, where we hold regularly weekly meetings open to anyone to coordinate with each other.

If you want to learn more about WordPress development in general, check out the Core Handbook full of helpful information.

[alecgeatches]

See related theme.json schema updates and discussion in #43801.

[annezazu]

cc @jorgefilipecosta and @mtias as this seems to greatly relate to the patterns as sections work. In particular, this PR #40318 From the FSE Outreach Program perspective, this would be a welcome area of control for agency types based on feedback I've heard and would fit in nicely with curation options as I know you all are well aware.

[alecgeatches]

Per feedback from @mcsf I'm going to close this issue. @ingeniumed has released a much smaller PR in #45089 that will allow us to address nesting governance within a plugin. Thank you!