Repository navigation
Widget Primitives: Let a host give widgets their translated title - #84738
Open
adamwoodnz wants to merge 9 commits into
Open
adamwoodnz wants to merge 9 commits into
adamwoodnz wants to merge 9 commits into
Conversation
🤖 PR meta 🤖🎉 PropsIf you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message. To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook. Updated as activity occurs, without notifying anyone named here. Add the |
github-actions
Bot
added
[Package] Widget primitives
Contributor
Author
Codex reviewThe title capability is passed per widget render and is shared by dashboard tiles and picker previews through WidgetFrame. No correctness, contract, accessibility, or regression issues were identified. |
adamwoodnz
marked this pull request as ready for review
October 14, 2026 22:07
adamwoodnz
force-pushed
the
add/widget-host-title
branch
from
October 15, 2026 22:15
aeeb9a3 to
4532cd9
Compare
A widget's render component could not read its own title, so content that needs an accessible name built from it, such as a focusable chart, had to hardcode a second copy with __(). That copy drifts from widget.json, and __( manifest.title ) is not a string literal, so the title never reaches the script's translation file. The host already holds the translated title. An optional title on WidgetHost lets it pass that string to the widget through context, reachable from any component below the render. A string, not an id, because aria-labelledby cannot reorder "<title> chart" for locales that put the noun first.
The dashboard renders widgetType.title in each header but did not pass it to the widget, so widgets on it could not use the new title host capability. The per-instance provider that binds actions now carries the title too. WidgetFrame mounts it for the tile, the drag preview and the Add widget preview, so all three get it.
The title example sat between the HostLink composition and the sentence that points at its story, so that sentence read as if it described the title snippet.
Gutenberg changelogs reference the PR that ships a change, not the issue that asked for it.
How a widget phrases a name around its title belongs to that widget and its translators. An example here would drift from what consumers actually ship.
The rationale for the title capability lives in the issue and PR. The docs only need to say what the value is.
The docs say what title is and who provides it. How a widget uses it is the widget's call.
Match the colon format consumers use, so the test does not model a word-order pattern that breaks in other locales.
Moving the title example earlier also moved the useWidgetHost note away from the HostLink section it belongs to. With the example gone, the note returns to its trunk position. The title doc comment drops a usage note the sibling capabilities do not carry.
adamwoodnz
force-pushed
the
add/widget-host-title
branch
from
October 19, 2026 19:43
4532cd9 to
87d0e52
Compare
This branch has not been deployed
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?
Closes #84204
Adds an optional, translated
titletoWidgetHost. The dashboard gives each widget its type's title through it.Why?
A widget can now name its own content from the title the dashboard already shows, in the user's language. A focusable chart can say "Sales by device chart" to a screen reader. Before, a widget had to hardcode a second copy of its title, which could drift from the title the widget declares and was never translated, so screen reader users heard English.
How?
@wordpress/widget-primitives:WidgetHost.title?: string. It rides the existing provider merge, so a per-widget provider keeps the host'slinks. Docs on the Widget Host Storybook page and in the README.@wordpress/widget-dashboard: theWidgetRenderadapter already nests a per-instanceWidgetHostProviderforactions. It now also setstitle: widgetType.title.WidgetFramemounts this adapter for the tile, the drag preview and the Add widget preview.The host passes a string, not the title element's id:
aria-labelledbyjoins text in a fixed order, so a translated name built around the title could not place it.Compatibility: additive and optional. A widget on an older host reads
titleasundefinedand uses its own name; an older widget ignores the field.titleshares the existingWidgetHostContext, so it has the same single-package-copy requirement aslinksandactions. Mixed-version combinations were not built in an isolated consumer.Review focus: the
titledoc comment inwidget-host.tsxand the contract wording inwidget-host.md.Testing Instructions
npm run test:unit:vitest -- packages/widget-dashboard packages/widget-primitives routes/dashboardwidget-host-title.jsdom.test.tsxmounts aWidgetDashboardwith a widget that labels afigurewith`Chart: ${ title }`and finds it by that name.Verified locally: 31 files, 277 tests pass (jsdom, node and browser). The new test fails without the adapter change (
aria-label="Chart: undefined").tsc --buildon both packages and eslint on the changed files are clean.Testing Instructions for Keyboard
No visible UI change.
Screenshots or screencast
None: no visible UI change.
Use of AI Tools
Implemented with Claude Code (Claude Opus), reviewed by the author.
🤖 Generated with Claude Code