feat(ui): build accessible Toolbar component

[dev-susa]

Summary

Implements DS-081: Build an accessible Toolbar component (#492)

Implements a fully accessible WAI-ARIA Toolbar pattern with roving tabindex navigation, supporting horizontal/vertical orientations, keyboard controls, and dynamic items.

Implementation

Components

• Toolbar.Root: Main toolbar container with orientation support ( | )
• Toolbar.Group: Semantic grouping with optional
• Toolbar.Button: Interactive button with toggle state support ( prop)
• Toolbar.Link: Navigation link participating in keyboard flow
• Toolbar.Separator: Visual divider respecting toolbar orientation

Keyboard Navigation

• Arrow keys: Navigate between controls based on orientation
  • Horizontal: Left/Right arrows
  • Vertical: Up/Down arrows
• Home: Jump to first enabled control
• End: Jump to last enabled control
• Tab: Only one control in tab order (roving tabindex pattern)
• Wrapping: Arrow keys wrap around at boundaries
• Skip disabled: Automatically skip disabled controls

Features

✅ Roving tabindex with only one control in tab order
✅ Full arrow key navigation following orientation
✅ Home/End key support
✅ Disabled control handling (skipped during navigation)
✅ Toggle button states with aria-pressed
✅ Mixed controls (buttons + links)
✅ Dynamic item support (add/remove at runtime)
✅ Proper ARIA semantics (role="toolbar", role="group")
✅ Visual variants: default, outline, ghost
✅ Size variants: default, sm, icon, icon-sm

Testing

• 25 comprehensive tests covering:
  • Accessibility (axe violations)
  • ARIA roles and attributes
  • Roving tabindex behavior
  • Arrow key navigation (all directions)
  • Home/End key navigation
  • Boundary wrapping
  • Disabled control skipping
  • Toggle states
  • Mixed button/link controls
  • Dynamic item changes
  • Variants and sizes

Usage Example

<Toolbar.Root aria-label="Text formatting">
  <Toolbar.Group aria-label="Font style">
    <Toolbar.Button pressed={isBold} onClick={toggleBold}>
      Bold
    </Toolbar.Button>
    <Toolbar.Button pressed={isItalic} onClick={toggleItalic}>
      Italic
    </Toolbar.Button>
  </Toolbar.Group>
  
  <Toolbar.Separator />
  
  <Toolbar.Group aria-label="Alignment">
    <Toolbar.Button>Left</Toolbar.Button>
    <Toolbar.Button>Center</Toolbar.Button>
    <Toolbar.Button>Right</Toolbar.Button>
  </Toolbar.Group>
  
  <Toolbar.Link href="/help">Help</Toolbar.Link>
</Toolbar.Root>

Acceptance Criteria

• Only one enabled toolbar control participates in the tab order at a time
• Arrow keys follow orientation and skip disabled controls
• Home and End move to the first and last enabled control
• Buttons, links, and separators retain correct native semantics
• Tests cover orientations, disabled controls, focus movement, and dynamic items

Out of Scope (as specified)

• Defining chart or table business actions
• Implementing a rich-text editor

Closes #492

[vercel]

@dev-susa is attempting to deploy a commit to the Ijai's projects Team on Vercel.

A member of the Team first needs to authorize it.

[drips-wave]

@dev-susa Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits