Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add block nesting governance for theme.json #43796

Closed
wants to merge 61 commits into from
Closed

Add block nesting governance for theme.json #43796

wants to merge 61 commits into from

Conversation

alecgeatches
Copy link
Contributor

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

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/quotecore/heading
  3. core/quotecore/media-textcore/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.

alecgeatches and others added 30 commits August 22, 2022 16:13
This works by baking in all the possible blocks, under each block
when constructing the settings.block schema.

It works one layer deep at the moment.
Add useSetting multiple level nesting support, specificity, and tests
…port

Add support for parsing nested block settings from the theme.json
@github-actions github-actions bot added the First-time Contributor Pull request opened by a first-time contributor to Gutenberg repository label Sep 2, 2022
@github-actions
Copy link

github-actions bot commented Sep 2, 2022

👋 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
Copy link
Contributor Author

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

@annezazu
Copy link
Contributor

annezazu commented Sep 2, 2022

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.

@annezazu annezazu added the Global Styles Anything related to the broader Global Styles efforts, including Styles Engine and theme.json label Sep 2, 2022
@alecgeatches
Copy link
Contributor Author

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!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
First-time Contributor Pull request opened by a first-time contributor to Gutenberg repository Global Styles Anything related to the broader Global Styles efforts, including Styles Engine and theme.json
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants