Repository navigation
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. Props Bot commandsYou can trigger Props Bot actions by commenting on this PR:
Updated as activity occurs, without notifying anyone named here. Add the 🏷️ LabelsThis pull request needs exactly one label indicating its type, and has 0.
Read more about Type labels in Gutenberg. If you cannot add labels yourself, a reviewer can do it for you. 📦 Bundle sizeSize Change: +198 B (0%) Total Size: 8.68 MB 📦 View Changed
⚡ PerformanceShow the resultsClient side metrics exclude the server response time. front-end-block-theme
front-end-classic-theme
media-processing
media-upload
post-editor
site-editor
🏁 Flaky testsSome tests passed with failed attempts. The failures may not be related to this commit but are still reported for visibility. See the documentation for more information. As a site builder, I want to insert a core navigation overlay pattern with CTA and see it on the frontend in
|
There was a problem hiding this comment.
🟢 Approval recommended
No active review issues remain for the navigation-focus restoration change.
No open issues 🎉
What changed in this PR
Extends Boot’s page-region focus fallback to restore focus to the equivalent navigation control after a route replaces page content, helping keyboard and screen reader users keep their place.
Changes:
- Records
data-focus-keybefore navigation and restores focus to a matching element afterward. - Adds stable focus keys to Admin UI navigation links.
- Adds regression tests, shared navigation fixtures, and documentation.
| File | Description |
|---|---|
| packages/boot/src/components/app/use-route-focus.ts | Captures and restores keyed focus across navigation. |
| packages/boot/src/components/app/test/navigation-focus.browser.test.tsx | Tests targeted restoration and controls blurred before navigation. |
| packages/boot/src/components/app/test/fixtures/settings.tsx | Adds section navigation to the settings fixture. |
| packages/boot/src/components/app/test/fixtures/settings-general.tsx | Adds section navigation to the general settings fixture. |
| packages/boot/src/components/app/test/fixtures/section-navigation.tsx | Provides shared navigation items and a router link adapter. |
| packages/boot/README.md | Documents focus restoration and fallback behavior. |
| packages/boot/CHANGELOG.md | Records targeted focus restoration. |
| packages/admin-ui/src/navigation/test/index.jsdom.test.tsx | Verifies navigation links receive href-based focus keys. |
| packages/admin-ui/src/navigation/index.tsx | Adds stable focus keys to navigation links. |
| packages/admin-ui/CHANGELOG.md | Records section-navigation focus support. |
Review effort: Balanced
17fb731 to
e25781e
Compare
What?
Updates
@wordpress/bootand@wordpress/admin-uito coordinate focus restoration after navigation results in the page re-rendering, otherwise resulting in focus loss on the activated link.This builds upon #86701 , which improves the status quo by focusing the page region as a fallback. This goes further to improve it such that navigation stays on the same effective navigation link element after navigation has completed.
Why?
Focus loss is very disruptive to accessibility and user experience, as the user would have to find their way back to the content to continue from where they left off.
#86701 improved this slightly when a route was re-rendered. But in the case of links, it's more obvious that the focus should stay on the link from which the navigation resulted.
How?
The solution here introduces a
data-focus-keyattribute that elements within@wordpress/bootcan use to assign a unique identifier that is meant to identify an element across navigation transitions. At the time that a navigation is about to occur,@wordpress/bootrecords if focus is currently within an element with this attribute, and restores focus after navigation completes to the element with matching attribute value after routing is complete.This is in line with recommendations from spec authors around the Navigation API, which also highlight that this is not something that browsers natively support and requires some custom coordination:
In #86701 (comment), I had mentioned that ideally this would be a situation where the navigation would not be unmounted so that focus could remain on the same element. However, the design of
@wordpress/bootand routes are such that each route is responsible for rendering its full content when matched, and rendering<Page />results in a new element each time.Testing Instructions
There isn't currently anywhere in the application that uses navigation to demonstrate the fix here. Repeating steps from #86700 will show the effective improvement in #86701 by keeping focus within the page.
Use of AI Tools
Researched and implemented in coordination with Claude Code + Opus 5.5.