-
Notifications
You must be signed in to change notification settings - Fork 4.2k
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
Block.json: Refactor and stabilize selectors API #46496
Conversation
Size Change: +67 B (0%) Total Size: 1.34 MB
ℹ️ View Unchanged
|
c423b84
to
f2bb95a
Compare
I've updated this PR to be based on top of the work being done to bundle I'll be AFK for a couple of weeks although @glendaviesnz graciously offered to help keep this moving along. 🙇 |
f2bb95a
to
c2f5fd0
Compare
When the base branch was switched to |
c2f5fd0
to
0e08b6c
Compare
Flaky tests detected in 8aa8f24. 🔍 Workflow run URL: https://github.com/WordPress/gutenberg/actions/runs/4463329303
|
I'll do a full review tomorrow, but one thing I was thinking about was how the duotone filter previously expected just the __experimentalDuotone supports string to enable it, but now that the string is nested under selectors, we should probably add a duotone boolean to supports for enabling it in addition to the selector like the rest of the supports. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
It's great to see that you are working on stabilizing some of the APIs used currently as experiments nested inside the supports
field of block definition ❤️
I added in as an item to #41236 - Block API Tracking Issue.
I don't have a good context to comment on the details of the implementation, but I can share some general notes on how to integrate it better with WordPress core:
If the current approach is accepted we'll need a small patch to core to update the allowed properties during block registration.
It's going to be a bit more work inside WordPress core. All top-level block-type properties need to be included in the WP_Block_Type
class and exposed through the REST API endpoint for block types. Once you land this PR in Gutenberg, I'll be happy to help with all the necessary changes.
I also encourage you to document the new API at least inside Metadata in block.json document so everyone can see whether the name selectors
is the best way to express its intent compared to all other top-level settings. It's a different story when you refactor an existing code vs when someone discovers it for the first time. Maybe it is, we will find out later. It will also require a dev note when it merges into WordPress core (I assigned a related label).
As per this discussion, I've created a draft PR (#49393) to fix the Selectors API and remove the editor-only selectors functionality. |
return implode( ', ', $selectors_scoped ); | ||
} | ||
|
||
// Subfeature selector |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The sub-feature selector is something new, something the old experimental API didn't support, and we are introducing now. I think this is worth sharing in the developer note. See discussion for context on why it's necessary.
return wp_get_block_css_selector( $block_type, $target[0], $fallback ); | ||
} | ||
|
||
// We tried... |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
❤️
There is a follow-up PR open that exposes the new documentation page in the block editor handbook: #49471. |
Adds support for the new selectors property for block types. It adds it to the allowed metadata when registering a block type, makes the WP_Block_Type class aware of it, exposes it through the block types REST API, and the get_block_editor_server_block_settings function. Corresponding work in the Gutenberg plugin: WordPress/gutenberg#46496. Fixes #57585. Props aaronrobertshaw, hellofromTonya. git-svn-id: https://develop.svn.wordpress.org/trunk@55673 602fd350-edb4-49c9-b593-d223f7449a82
Adds support for the new selectors property for block types. It adds it to the allowed metadata when registering a block type, makes the WP_Block_Type class aware of it, exposes it through the block types REST API, and the get_block_editor_server_block_settings function. Corresponding work in the Gutenberg plugin: WordPress/gutenberg#46496. Fixes #57585. Props aaronrobertshaw, hellofromTonya. Built from https://develop.svn.wordpress.org/trunk@55673 git-svn-id: http://core.svn.wordpress.org/trunk@55185 1a063a9b-81f0-0310-95a4-ce76da25c4cd
Adds support for the new selectors property for block types. It adds it to the allowed metadata when registering a block type, makes the WP_Block_Type class aware of it, exposes it through the block types REST API, and the get_block_editor_server_block_settings function. Corresponding work in the Gutenberg plugin: WordPress/gutenberg#46496. Fixes #57585. Props aaronrobertshaw, hellofromTonya. Built from https://develop.svn.wordpress.org/trunk@55673 git-svn-id: https://core.svn.wordpress.org/trunk@55185 1a063a9b-81f0-0310-95a4-ce76da25c4cd
# Conflicts: # src/wp-includes/class-wp-theme-json.php
# Conflicts: # src/wp-includes/class-wp-theme-json.php
# Conflicts: # src/wp-includes/class-wp-theme-json.php
# Conflicts: # src/wp-includes/class-wp-theme-json.php
Related:
block.json
API: consider graduating__experimentalSelector
and__experimentalDuotone
from experimental to stable #45194WP_Theme_JSON
class instead of inheriting per WordPress version #46579What?
Refactors the block.json selectors API.
__experimentalSelector
props withinsupports
into their ownselectors
config.__experiementalSelector
prop is merged into the newselectors
config via theroot
prop.Why?
The experimental selectors have been around for a while now and are beginning to be relied upon more. There's also an increasing need for greater flexibility in setting selectors for individual block support styles.
For more info and history see: #45194
How?
d43c099
Updates Gutenberg’s block registration to polyfill the selectors prop until it is included in the server-provided definitions. Temporary unit test added for the polyfill.
43257ba
Adds theme.json unit tests for stylesheet generation using blocks leveraging the new selectors API. The old feature selectors test is maintained and could be deprecated as blocks migrate to the stabilised API.
Due to the updated block metadata, a test block needs to be registered during the phpunit bootstrap so that it is present before WordPress runs and the theme.json block metadata is cached.
A follow-up is currently looking at if we can invalidate the metadata cache and move the test block registrations to their respective tests.
9d073cf
Adds the
selectors
to the block.json schema. The available shape for the selectors API almost matches that of the block supports.An important difference is that it will accept a
root
selectors which replace the old__experimentalSelector
for the block as a whole as well as act as generic selector for each feature e.g. color, typography etc.b28fd4a
Updates the Image block.json to use the new selectors API instead of
__experimentalBorder.__experimentalSelector
.3edc22b
Add a global function that can be leveraged to retrieve selectors for specific block types and feature/subfeature.
c7e307d
Update theme.json class to leverage the new block CSS selector function.
1a3e557
Adds a
block_type_metadata_settings
filter to thelib/compat/wordpress-6.2/blocks.php
file ensuring that the selectors metadata is present in the block type settings. This will be required until the minimum supported WP version is >= 6.2.447de33
Add documentation for Block Selectors API.
Testing Instructions
npm run test:unit:php -- --filter WP_Theme_JSON_Gutenberg_Test
npm run test:unit:php -- --filter WP_Get_Block_CSS_Selector_Test
npm run test:unit packages/blocks/src/api/test/registration
core/image
block.Next Steps
If the current approach is accepted we'll need a small patch to core to update the allowed properties during block registration.
Trac Ticket: https://core.trac.wordpress.org/ticket/57585
GitHub PR: WordPress/wordpress-develop#3942