# Roving Tabindex Utility

## Objective

Give composite widgets one tab stop, with arrow keys moving inside them.

A shared keyboard-navigation behaviour for toolbars, tab strips, menus, option lists, and grids.

## Before You Begin

This feature is being added to an application that already exists and already
works. Do not scaffold a new project, and do not assume a blank slate.

Inspect the codebase first and establish:

- The existing application structure and where code of this kind already lives.
- The framework and version in use.
- The existing design system — colours, spacing, typography, and component conventions.
- Existing UI components you can reuse instead of writing new ones.
- The existing database structure, if this feature needs to persist anything.
- The existing authentication and authorization system, if this feature is user-scoped.
- Dependencies already installed, so you don't add a library that duplicates one.
- The existing test setup and conventions.

Only start writing code once you understand the above. If the application
already implements part of this feature, extend it rather than replacing it.

## Implementation Instructions

1. Find the composite widgets where the keyboard currently steps through every child — toolbars, tab strips, menus, segmented controls, option lists, calendar grids, card grids — and give each a single tab stop with arrow keys operating inside it.
2. Track the active item by stable identity rather than by index, so items appearing, disappearing, or being reordered cannot move the active position onto an unrelated control.
3. Support the orientations these widgets genuinely take: a horizontal row, a vertical list, and a two-dimensional grid where up and down move between rows. Include Home and End, and decide explicitly whether the ends wrap.
4. Skip hidden and unavailable items when moving, and if the active item disappears, move to the nearest remaining one rather than leaving the widget with no tab stop at all.
5. Do not simply remove every child from the tab order and hope focus is managed elsewhere. Exactly one item must be reachable by tab at any moment, and returning to the widget must land on the item the user left rather than the first one. Which item is focused belongs here; which items are selected belongs to Selection State Pattern, and the two must be free to differ.

## UI and UX Requirements

Match the application's existing design system exactly. Reuse its components,
spacing, and typography. This feature should look like it was always there.

## Responsive Requirements

Works on mobile, tablet, and desktop. Touch targets are large enough to hit on a
phone, and nothing overflows horizontally at 320px.

## Accessibility Requirements

- Fully keyboard navigable.
- Correct semantic elements and ARIA roles.
- Visible focus states.
- Meets WCAG AA contrast.
- Dynamic changes are announced to screen readers.
- Respects prefers-reduced-motion.

## Edge Cases

- An active item that is filtered out, collapsed, or removed leaves the widget with nothing focusable, and the next tab press lands somewhere unrelated on the page.
- In a grid, arrow keys must move by row and column rather than through a flattened list, and rows of unequal length need a defined behaviour at the short end.
- A list that re-renders after a fetch or a filter must keep the same item active. Restoring by index quietly moves focus to a different control.
- Exactly one item carries the tab stop at any moment; letting two claim it produces a widget that is entered twice, and letting none claim it produces one that cannot be entered at all.
- Typing a letter in a menu or option list is expected to jump to the matching item, and that typeahead must not collide with a search field inside the same widget.
- Arrow keys pressed inside a text input or a native select belong to that control, so the utility has to yield rather than intercepting them.
- Moving the active item must scroll it into view within its own scrolling container without dragging the whole page along with it.

## Testing

Exercise the feature end to end in the running application. Cover every edge case
above, then run the existing test suite and confirm nothing regressed.

## Acceptance Criteria

- [ ] Each composite widget occupies exactly one stop in the tab order.
- [ ] Arrow keys, Home, and End move between items within a widget.
- [ ] The active item is tracked by identity and survives re-renders, sorting, and filtering.
- [ ] Hidden and unavailable items are skipped, and losing the active item never leaves the widget unreachable.
- [ ] Returning to a widget by tab restores the item the user last had active.
- [ ] Horizontal, vertical, and grid arrangements are all supported.
- [ ] Focus and selection are represented separately and may point at different items.
- [ ] The feature matches the existing design system.
- [ ] No existing functionality is broken.

## Adaptation Rules

- Match the existing design system. Do not introduce a new colour palette,
  spacing scale, or component library.
- Reuse existing components and utilities wherever they fit.
- Follow the naming, file layout, and code style already present.
- Do not upgrade, replace, or remove existing dependencies to make this
  feature fit. Adapt the feature to the app, not the app to the feature.
- Do not break existing functionality. If a change is genuinely required in
  existing code, make the smallest one that works and say so.
- If something in these instructions conflicts with how the application is
  built, follow the application and explain the deviation.

## Final Verification

Before you report the work as done:

1. Re-read the acceptance criteria above and check each one against what you
   actually built.
2. Run the application and exercise the feature end to end.
3. Run the existing test suite and confirm you have broken nothing.
4. Check the feature on mobile, tablet, and desktop widths.
5. Check keyboard navigation and focus handling.
6. Summarize what changed: files added, files modified, and anything you
   deliberately did differently because of how this application is built.

If any acceptance criterion is unmet, fix it before reporting completion.