Skip to content

feat(ui5-toolbar): implement WCAG-compliant keyboard navigation#13231

Open
plamenivanov91 wants to merge 4 commits intomainfrom
tb-wacg-arrow-nav
Open

feat(ui5-toolbar): implement WCAG-compliant keyboard navigation#13231
plamenivanov91 wants to merge 4 commits intomainfrom
tb-wacg-arrow-nav

Conversation

@plamenivanov91
Copy link
Contributor

@plamenivanov91 plamenivanov91 commented Mar 9, 2026

Add comprehensive keyboard navigation to toolbar following WCAG toolbar pattern:

  • Arrow keys (Left/Right/Up/Down) navigate between toolbar items
  • Home/End jump to first/last item
  • Tab/Shift+Tab navigate within toolbar, exit at edges
  • Roving tabindex pattern
  • Focus entry: remembers last focused item on re-entry, defaults to first item on initial entry
  • Proper handling of complex nested controls (ToolbarSelect)

Resolves focus loss when pressing Shift+Tab on complex toolbar children. Ensures all toolbar items are reachable via keyboard navigation.

Optimizations:

  • Extracted _focusItem() helper to reduce code duplication
  • Simplified Tab/Shift+Tab navigation logic

Fixes: #12945

Add comprehensive keyboard navigation to toolbar following WCAG toolbar pattern:
- Arrow keys (Left/Right/Up/Down) navigate between toolbar items
- Home/End jump to first/last item
- Tab/Shift+Tab navigate within toolbar, exit at edges
- Roving tabindex pattern (single tab stop, toolbar is one stop)
- Focus entry: remembers last focused item on re-entry, defaults to first item on initial entry
- Proper handling of complex nested controls (ToolbarSelect)

Resolves focus loss when pressing Shift+Tab on complex toolbar children.
Ensures all toolbar items are reachable via keyboard navigation.

Optimizations:
- Extracted _focusItem() helper to reduce code duplication
- Simplified Tab/Shift+Tab navigation logic

Fixes: #12945
@ui5-webcomponents-bot
Copy link
Collaborator

ui5-webcomponents-bot commented Mar 9, 2026

@ui5-webcomponents-bot ui5-webcomponents-bot temporarily deployed to preview March 9, 2026 17:11 Inactive
@ui5-webcomponents-bot ui5-webcomponents-bot temporarily deployed to preview March 9, 2026 17:33 Inactive
@ui5-webcomponents-bot ui5-webcomponents-bot temporarily deployed to preview March 10, 2026 13:23 Inactive
@dobrinyonkov
Copy link
Contributor

Tested this PR. Good progress so far, but found a few issues we should fix before merge.

Most of them can be reproduced in the toolbar with toolbar items test page here

https://pr-13231--ui5-webcomponents-preview.netlify.app/packages/main/test/pages/toolbaritems

  1. Arrow navigation gets trapped on ToolbarSelect
  2. Arrow navigation does not work in the second sample
  3. Some of the items in the third sample are not reachable

RTL not handled
ArrowLeft always goes to the previous item and ArrowRight always goes to the next item. In RTL layouts this is backwards. ArrowLeft should go to the next item when the document is RTL. Other components in this repo like Menu swap directions based on this.effectiveDir. You can test this by setting dir="rtl" on the body

Do not check hardcoded tag names

Your _isFromComplexToolbarChild method checks element.tagName === "UI5-TOOLBAR-SELECT". This breaks when tag names are scoped.
BAD: element.tagName === "UI5-BUTTON"
GOOD: Use createInstanceChecker helper with duck-typing

Adviced is to use the createInstanceChecker but that we not work here so simple duck-type check would work

Add a property like handlesOwnKeyboardNavigation to ToolbarItemBase. Set it to true in ToolbarSelect. Check that property instead of the tag name:

// In ToolbarItemBase.ts
@property({ type: Boolean })
handlesOwnKeyboardNavigation = false;
// In ToolbarSelect.ts  
handlesOwnKeyboardNavigation = true; // Override in class

// In Toolbar.ts - check the property, not the tag
_shouldItemHandleOwnNavigation(item: ToolbarItemBase): boolean {
    return item.handlesOwnKeyboardNavigation;
}

Other complex toolbar items can opt-in without modifying the toolbar code.

Happy to discuss these over a call.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[ui5-toolbar][A11y]: toolbar keyboard interaction does not align with WCAG requirement

3 participants