feat(ui5-toolbar): implement WAI-ARIA toolbar keyboard navigation

[plamenivanov91]

Replace Tab-through-every-item with a proper arrow-key navigation pattern
per the WAI-ARIA toolbar pattern.

Keyboard handling

• [Left]/[Right] — navigate between toolbar items (RTL-aware); absorbed at the first/last item (no wrap)
• [Home]/[End] — jump to first/last item, unless the focused item manages its own internal navigation (e.g. Input caret, Breadcrumbs), in which case the item handles the key
• [Tab]/[Shift+Tab] — exit the toolbar via the browser's natural tab order; no roving tabindex, items keep their own natural tabindex
• Overflow popover is fully isolated: arrow keys and focusin handling are suppressed while the popover is open. On open, the first interactive overflow item receives focus.

Focus tracking

_lastFocusedItem tracks the current navigation target for re-entry (e.g. Shift+Tab back into the toolbar). It never mutates tabindex and is reconciled after reflow — a tracked item that moves to overflow or is removed no longer causes navigation to restart from the first item. When the overflow button disappears (items move back into the toolbar), focus moves to the last navigable item via focusForToolbarNavigation.

Interactivity detection

An item counts as interactive (and toward role="toolbar") only when its resolved focus target is actually focusable:

• Text-only content (ui5-text, ui5-title) is skipped
• Focus-delegating hosts (ui5-date-picker) are resolved through getFocusDomRef and remain navigable
• href-less anchors that opt in via an explicit tabindex (e.g. ui5-link rendered as a button, used by the Breadcrumbs overflow arrow) stay navigable

ToolbarItemBase — hook API for complex items

New overridable members (no-ops in base):

• getArrowNavState() — reports { atLeftEnd, atRightEnd } so the toolbar knows when a key press is at an internal boundary and should be handled by the item rather than moving to the next item
• focusForToolbarNavigation(isForward) — direction-aware focus entry point

ToolbarItem — three navigation paths

• _itemNavigation introspection — components that use ItemNavigation internally (e.g. Breadcrumbs, SegmentedButton) are detected via duck-typing; currentIndex/itemCount derive the boundary state
• IToolbarArrowNavProvider interface — components that expose caret/selection position as boundary info explicitly implement IToolbarArrowNavProvider and its mandatory getArrowNavState() method
• Multi-child fallback — ToolbarItems with more than one slotted child (radio/checkbox groups) are treated as a navigable group; Left/Right and Home/End move within the group, exiting only at its boundary

IToolbarArrowNavProvider

New public interface (IToolbarArrowNavProvider.ts) with ToolbarArrowNavState type and isToolbarArrowNavProvider() type guard. Components that manage an internal text cursor implement this interface explicitly — the method's purpose is self-documenting at the declaration site.

Input — caret-aware boundary

Input implements IToolbarArrowNavProvider, reporting atLeftEnd/atRightEnd from the caret position and only when the selection is collapsed — a non-collapsed selection is not treated as a boundary, so Left/Right collapse it natively instead of exiting to the next toolbar item.

Accessibility docs

• Updated keyboard-handling JSDoc on ui5-toolbar
• Added WCAG 2.1 notes to accessibleName / accessibleNameRef

Tests (Toolbar.cy.tsx, ToolbarSelect.cy.tsx)

• Arrow Left/Right navigation; no-wrap at the ends; Home/End to first/last
• Tab traverses items via natural tab order
• Input caret-aware: Left/Right exits only at the caret boundary; a range selection at a boundary stays in the field
• Home not intercepted by the toolbar when an Input has focus
• RTL reverses Left/Right direction
• Checkbox group: arrow traversal within the group, Home/End within the group, and boundary exit
• Text-only items non-interactive; focus-delegating hosts interactive; self-overflowed Breadcrumbs stays navigable
• First overflow item focused on popover open; overflow button ArrowLeft navigates to the last visible toolbar item
• ToolbarSelect programmatic selection stabilised against the light-DOM option / rendered select value

JIRA: BGSOFUIPIRIN-7018
Fixes: #12945

[ui5-webcomponents-bot]

🧹 Preview deployment cleaned up: https://pr-13622--ui5-webcomponents.netlify.app

[plamenivanov91]

Hello, @MapTo0 , @niyap

Can somebody from your team review Input and TextArea files please?

Regards,
Plamen

[MapTo0]

Honestly, I do not understand the TA use case. Someone places a TA in the toolbar?

Implementation looks a bit like a magic. Can we implement an interface in the components that might be placed within a toolbar? something like IToolbarCompatible. Tomorrow if someone see this method, he/she would not know why its there at all.

Furthermore, considering all native inputs should be tackled you can also check other components: ComboBox, MultiComboBox, FileUploader (not sure), SearchField.

What about non ui5-webcomponents elements placed within a toolbar? Can users also mix components?

[plamenivanov91]

Honestly, I do not understand the TA use case. Someone places a TA in the toolbar?

Implementation looks a bit like a magic. Can we implement an interface in the components that might be placed within a toolbar? something like IToolbarCompatible. Tomorrow if someone see this method, he/she would not know why its there at all.

Furthermore, considering all native inputs should be tackled you can also check other components: ComboBox, MultiComboBox, FileUploader (not sure), SearchField.

What about non ui5-webcomponents elements placed within a toolbar? Can users also mix components?

Hello there,

We've discussed this implementation approach on the architecture round and there is nothing magical about it.

We have three mechanisms used to decide whether or not we are on the first/last index inside a complex control nested in the ToolbarItem and they are all explained in the commit message.

ToolbarItem — three navigation paths
_itemNavigation introspection — components that use ItemNavigation internally (e.g. Breadcrumbs, SegmentedButton) are detected via duck-typing; currentIndex/itemCount derive the boundary state
getArrowNavState interface — explicit opt-in for components that expose caret/selection position as boundary info (e.g. Input, TextArea)
Multi-child fallback — ToolbarItems with more than one slotted child (radio/checkbox groups) are treated as a navigable group; Left/Right and Home/End move within the group, exiting only at its boundary

The adaptation of the rest of controls you mentioned is not a Toolbar responsibility. The ones we altered are for demonstration purposes. Also they cover most of our sample code.

For non ui5-webcomponents (like groups) placed within a ToolbarItem we have different mechanism as you can see in the code and in the commit message.

Regards,
Plamen Ivanov

[sap-ui5-webcomponents-release]

🎉 This PR is included in version v2.25.0 🎉

The release is available on v2.25.0

Your semantic-release bot 📦🚀