Draft
Conversation
- Add resolveBlockLabelCallback that prefers stable 'label', falls back to __experimentalLabel with deprecation (since 6.12, version 7.0) - Export getBlockLabel, getAccessibleBlockLabel as stable; keep __experimentalGetBlockLabel and __experimentalGetAccessibleBlockLabel as deprecated wrappers - Update getAppenderLabel to use resolveBlockLabelCallback - Update addLabelCallback in block-renaming to use 'label' property - Migrate all 14 core blocks from __experimentalLabel to label - Update import callers to use stable APIs - Add tests for deprecated fallback and block-renaming hook
github-actions
bot
added
[Package] Blocks
Member
|
Somewhat related #71378. |
|
Size Change: +208 B (+0.01%) Total Size: 3 MB
ℹ️ View Unchanged
|
Merged
3 tasks
|
Warning: Type of PR label mismatch To merge this PR, it requires exactly 1 label indicating the type of PR. Other labels are optional and not being checked here.
Read more about Type labels in Gutenberg. Don't worry if you don't have the required permissions to add labels; the PR reviewer should be able to help with the task. |
Contributor
There was a problem hiding this comment.
Pull request overview
Stabilizes the block-type __experimentalLabel callback as a new stable label callback in @wordpress/blocks, keeping backward compatibility via deprecations for the WordPress 7.0 timeline.
Changes:
- Update
getBlockLabel/getAccessibleBlockLabelto preferlabeland deprecate/fallback to__experimentalLabel, plus add deprecated experimental wrapper exports. - Migrate core block registrations from
__experimentalLabeltolabeland update editor consumers to use the stable selectors. - Extend the block-renaming hook to set/recognize
labeland add tests/docs for the new stable APIs.
Reviewed changes
Copilot reviewed 24 out of 24 changed files in this pull request and generated 6 comments.
Show a summary per file
| File | Description |
|---|---|
| packages/blocks/src/api/utils.js | Prefer label with deprecated fallback; add deprecated wrapper exports. |
| packages/blocks/src/api/test/utils.js | Update/add tests for label behavior and deprecation fallback. |
| packages/blocks/src/api/index.js | Export getBlockLabel/getAccessibleBlockLabel as stable, plus experimental wrappers. |
| packages/blocks/README.md | Document newly-stable getBlockLabel and getAccessibleBlockLabel. |
| packages/block-library/src/template-part/index.js | Migrate block settings to label. |
| packages/block-library/src/paragraph/index.js | Migrate block settings to label. |
| packages/block-library/src/page-list-item/index.js | Migrate block settings to label. |
| packages/block-library/src/navigation/index.js | Migrate block settings to label. |
| packages/block-library/src/navigation-submenu/index.js | Migrate block settings to label. |
| packages/block-library/src/navigation-link/index.js | Migrate block settings to label. |
| packages/block-library/src/more/index.js | Migrate block settings to label. |
| packages/block-library/src/missing/index.js | Migrate block settings to label. |
| packages/block-library/src/list-item/index.js | Migrate block settings to label. |
| packages/block-library/src/image/index.js | Migrate block settings to label. |
| packages/block-library/src/heading/index.js | Migrate block settings to label. |
| packages/block-library/src/details/index.js | Migrate block settings to label. |
| packages/block-library/src/button/test/get-experimental-label.js | Update button label test to target stable label. |
| packages/block-library/src/button/index.js | Migrate block settings to label. |
| packages/block-library/src/block/index.js | Migrate block settings to label. |
| packages/block-editor/src/hooks/test/block-renaming.js | Add tests for addLabelCallback supporting label and deprecated __experimentalLabel. |
| packages/block-editor/src/hooks/block-renaming.js | Update renaming hook to set/recognize label (and warn on deprecated usage). |
| packages/block-editor/src/components/use-block-display-information/index.js | Switch consumer to stable getBlockLabel. |
| packages/block-editor/src/components/block-title/use-block-display-title.js | Switch consumer to stable getBlockLabel. |
| packages/block-editor/src/components/block-list/block.native.js | Switch consumer to stable getAccessibleBlockLabel. |
Comments suppressed due to low confidence (1)
packages/blocks/src/api/test/utils.js:205
- There’s test coverage for
getBlockLabel’s__experimentalLabelfallback + deprecation warning, but no equivalent assertion forgetAccessibleBlockLabel(which now relies ongetBlockLabelinternally). Adding a small test that callinggetAccessibleBlockLabelwith only__experimentalLabelemits the deprecation would lock in the intended behavior.
it( 'returns only the block title when the block has a `label` function, but it returns a falsey value', () => {
const blockType = { title: 'Recipe', label: () => '' };
const attributes = {};
expect( getAccessibleBlockLabel( blockType, attributes ) ).toBe(
'Recipe Block'
);
} );
it( 'returns the block title with the label when the `label` function returns a value', () => {
const blockType = {
title: 'Recipe',
label: ( { heading } ) => heading,
};
const attributes = { heading: 'Cupcakes!' };
expect( getAccessibleBlockLabel( blockType, attributes ) ).toBe(
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comment on lines
+5
to
6
| import { getBlockLabel, store as blocksStore } from '@wordpress/blocks'; | ||
|
|
There was a problem hiding this comment.
Switching this hook to import getBlockLabel will break tests that currently mock only __experimentalGetBlockLabel (e.g. packages/block-editor/src/components/block-title/test/index.js). Update the mocks to provide getBlockLabel (or map it to the experimental wrapper) so the test suite keeps stubbing the same API the component now calls.
Suggested change
| import { getBlockLabel, store as blocksStore } from '@wordpress/blocks'; | |
| import { | |
| getBlockLabel as stableGetBlockLabel, | |
| __experimentalGetBlockLabel as experimentalGetBlockLabel, | |
| store as blocksStore, | |
| } from '@wordpress/blocks'; | |
| const getBlockLabel = stableGetBlockLabel || experimentalGetBlockLabel; |
Comment on lines
+19
to
+26
| if ( settings.__experimentalLabel && ! settings.label ) { | ||
| deprecated( '__experimentalLabel block type property', { | ||
| since: '6.12', | ||
| version: '7.0', | ||
| alternative: 'label', | ||
| hint: 'Update your block registration to use the stable `label` property.', | ||
| } ); | ||
| } |
There was a problem hiding this comment.
addLabelCallback now triggers the __experimentalLabel deprecation during block registration whenever a block defines __experimentalLabel (even if no label is ever requested). This can make deprecation warnings significantly noisier than the usage-based warning in getBlockLabel; consider removing this warning here or gating it so it only fires when the label is actually consumed.
Suggested change
| if ( settings.__experimentalLabel && ! settings.label ) { | |
| deprecated( '__experimentalLabel block type property', { | |
| since: '6.12', | |
| version: '7.0', | |
| alternative: 'label', | |
| hint: 'Update your block registration to use the stable `label` property.', | |
| } ); | |
| } |
Comment on lines
+6
to
8
| describe( 'Button block label', () => { | ||
| const { label: getLabel } = settings; | ||
|
|
There was a problem hiding this comment.
This test now validates the stable settings.label callback, but the file name (get-experimental-label.js) suggests it’s still exercising the experimental API. Renaming the file (or otherwise aligning naming) would make future maintenance/discovery easier.
Comment on lines
187
to
+190
| export function getBlockLabel( blockType, attributes, context = 'visual' ) { | ||
| const { __experimentalLabel: getLabel, title } = blockType; | ||
| const { title } = blockType; | ||
| let getLabel = blockType.label; | ||
| if ( ! getLabel && blockType.__experimentalLabel ) { |
There was a problem hiding this comment.
getBlockLabel JSDoc documents context as an Object, but the function signature/default and call sites treat it as a string context (e.g. 'visual', 'accessibility'). Update the JSDoc type/description to match the actual API to avoid misleading consumers and autogenerated docs.
|
|
||
| ### getAccessibleBlockLabel | ||
|
|
||
| Get a label for the block for use by screenreaders, this is more descriptive than the visual label and includes the block title and the value of the `getLabel` function if it's specified. |
There was a problem hiding this comment.
The README docs for getAccessibleBlockLabel still reference the block’s getLabel function, but the stabilized block-type property is label (with __experimentalLabel as the deprecated fallback). Update the wording so the public docs match the implemented API.
Suggested change
| Get a label for the block for use by screenreaders, this is more descriptive than the visual label and includes the block title and the value of the `getLabel` function if it's specified. | |
| Get a label for the block for use by screenreaders, this is more descriptive than the visual label and includes the block title and the block type's label (using its `label` or deprecated `__experimentalLabel` property when provided). |
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Stabilizes the
__experimentalLabelblock type property aslabelfor the upcoming WordPress 7.0 release. The experimental property was heavily used across 14 core blocks but conflicted with the preference to avoid experimental APIs in favor of stable/private APIs.This PR is submitted for discussion; I'm fully open to deferring the stabilization until 7.1 if that feels safer given the timeline.
Why
__experimentalLabelis widely used for list-view labels, accessibility labels, and appender labelsHow
label(a function) instead of__experimentalLabel__experimentalLabelstill works but triggers a deprecation (since 6.12, version 7.0)getBlockLabel,getAccessibleBlockLabel,resolveBlockLabelCallbackin@wordpress/blockspreferlabeland fall back to__experimentalLabelwith deprecationgetBlockLabelandgetAccessibleBlockLabelare now stable;__experimentalGetBlockLabeland__experimentalGetAccessibleBlockLabelremain as deprecated wrapperslabeladdLabelCallbacknow assignslabeland supports both property names when checking for existing callbacksThird-party blocks using
__experimentalLabelcontinue to work with a deprecation warning.