@astryxdesign/core 0.1.1 → 0.1.2-canary.04e71b2

package/src/hooks/useListFocus.doc.mjs

@@ -34,11 +34,39 @@ export const docs = {
     },
     {
       name: 'options.orientation',
-      type: "'horizontal' | 'vertical'",
-      description: "navigation orientation. 'horizontal' uses ArrowLeft/ArrowRight, 'vertical' uses ArrowUp/ArrowDown.",
+      type: "'horizontal' | 'vertical' | 'both'",
+      description: "Navigation orientation. 'horizontal' uses ArrowLeft/ArrowRight, 'vertical' uses ArrowUp/ArrowDown, 'both' accepts all four arrows.",
       default: "'vertical'",
       required: false,
     },
+    {
+      name: 'options.hasHomeEnd',
+      type: 'boolean',
+      description: 'Whether Home/End jump to the first/last enabled item.',
+      default: 'true',
+      required: false,
+    },
+    {
+      name: 'options.isRtl',
+      type: 'boolean',
+      description: 'Whether the list is in a right-to-left context. When true, ArrowLeft/ArrowRight are swapped for horizontal navigation so it follows visual direction.',
+      default: 'false',
+      required: false,
+    },
+    {
+      name: 'options.hasRovingTabIndex',
+      type: 'boolean',
+      description: 'Opt into roving-tabindex ownership: the hook stamps a single tab stop (one item tabindex="0", the rest -1), repairs it as items mount/unmount or toggle disabled, and moves it with arrow navigation. When false, the hook only moves focus and never touches tabindex.',
+      default: 'false',
+      required: false,
+    },
+    {
+      name: 'options.hasCaretGuard',
+      type: 'boolean',
+      description: "When true, arrow keys are not stolen from a nested text input/textarea whose caret is not at the boundary in the direction of travel (or that has a selection), and are never stolen from a nested contenteditable (rich-text editor / chat composer). Preserves inline text editing within the list.",
+      default: 'false',
+      required: false,
+    },
   ],
   returns: [
     {
@@ -51,6 +79,11 @@ export const docs = {
       type: '(e: React.KeyboardEvent) => void',
       description: 'Key down handler to attach to the list container.',
     },
+    {
+      name: 'handleFocus',
+      type: '(e: React.FocusEvent) => void',
+      description: 'Focus handler for the container. Keeps the roving tab stop in sync when hasRovingTabIndex is enabled; a no-op otherwise, so it is always safe to attach.',
+    },
     {
       name: 'focusItem',
       type: '(index: number) => void',
@@ -58,21 +91,22 @@ export const docs = {
     },
     {
       name: 'focusFirst',
-      type: '() => void',
-      description: 'Focus the first focusable item in the list.',
+      type: '() => boolean',
+      description: 'Focus the first enabled item. Returns true when an item was focused.',
     },
     {
       name: 'focusLast',
-      type: '() => void',
-      description: 'Focus the last focusable item in the list.',
+      type: '() => boolean',
+      description: 'Focus the last enabled item. Returns true when an item was focused.',
     },
   ],
   usage: {
     description:
-      'Manages keyboard navigation within a linear list following WAI-ARIA menu/listbox/toolbar patterns. Supports arrow key navigation (vertical or horizontal), Home/End for boundaries, optional wrap-around, and Escape to close. Suitable for dropdown menus, toolbars, and any 1D focusable list.',
+      'Manages keyboard navigation within a linear list following WAI-ARIA menu/listbox/toolbar patterns. Supports arrow key navigation (vertical, horizontal, or both), Home/End for boundaries, optional wrap-around, RTL, and Escape to close. Opt into hasRovingTabIndex for composite widgets (toolbars, segmented controls, tab strips) that own a single tab stop. Suitable for dropdown menus, toolbars, and any 1D focusable list.',
     bestPractices: [
       { guidance: true, description: "Set orientation to 'horizontal' for toolbars and tab bars, 'vertical' for dropdown menus." },
       { guidance: true, description: 'Provide an onEscape callback for menus/dropdowns to return focus to the trigger.' },
+      { guidance: true, description: 'Enable hasRovingTabIndex (and hasCaretGuard when the widget can contain text inputs) for toolbar-style composites that should be a single tab stop.' },
       { guidance: false, description: 'Use for 2D grid navigation; prefer useGridFocus for grids and calendars.' },
     ],
   },
@@ -91,14 +125,19 @@ export const docsDense = {
     'options.itemSelector': 'selector for focusable items in list.',
     'options.wrap': 'whether arrow navigation wraps around at ends.',
     'options.onEscape': 'callback when Escape key pressed (e.g. close menu).',
-    'options.orientation': "navigation orientation. 'horizontal' uses ArrowLeft/ArrowRight, 'vertical' uses ArrowUp/ArrowDown.",
+    'options.orientation': "navigation orientation. 'horizontal' uses ArrowLeft/ArrowRight, 'vertical' uses ArrowUp/ArrowDown, 'both' accepts all four arrows.",
+    'options.hasHomeEnd': 'whether Home/End jump to first/last enabled item.',
+    'options.isRtl': 'when true, ArrowLeft/ArrowRight swap for horizontal nav (RTL).',
+    'options.hasRovingTabIndex': 'opt into roving-tabindex ownership: hook stamps + repairs a single tab stop across items.',
+    'options.hasCaretGuard': "when true, don't steal arrow keys from a nested text input/textarea mid-line or from a contenteditable.",
   },
   returnDescriptions: {
     listRef: 'ref to attach to list container element.',
     handleKeyDown: 'key down handler for list container.',
+    handleFocus: 'focus handler; keeps roving tab stop in sync when hasRovingTabIndex is on (else no-op).',
     focusItem: 'focus specific item by index (clamped to valid range).',
-    focusFirst: 'focus first focusable item in list.',
-    focusLast: 'focus last focusable item in list.',
+    focusFirst: 'focus first enabled item; returns true when focused.',
+    focusLast: 'focus last enabled item; returns true when focused.',
   },
   usage: {
     description:
@@ -106,6 +145,7 @@ export const docsDense = {
     bestPractices: [
       { guidance: true, description: "Set orientation to 'horizontal' for toolbars + tab bars, 'vertical' for dropdown menus." },
       { guidance: true, description: 'Provide onEscape callback for menus/dropdowns to return focus to trigger.' },
+      { guidance: true, description: 'Enable hasRovingTabIndex (+ hasCaretGuard when widget can contain text inputs) for toolbar-style composites that should be a single tab stop.' },
       { guidance: false, description: 'Use for 2D grid navigation; prefer useGridFocus for grids + calendars.' },
     ],
   },

package/src/hooks/useListFocus.test.tsx

@@ -0,0 +1,375 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file useListFocus.test.tsx
+ * @input Uses vitest, @testing-library/react, useListFocus hook
+ * @output Unit tests for useListFocus disabled-item skipping + navigation
+ * @position Testing; validates useListFocus.ts keyboard navigation
+ *
+ * SYNC: When useListFocus.ts changes, update tests to match new behavior
+ */
+
+import {describe, it, expect} from 'vitest';
+import {render, screen, fireEvent} from '@testing-library/react';
+import {useListFocus} from './useListFocus';
+
+const NO_DISABLED: string[] = [];
+
+function Menu({
+  wrap = true,
+  disabledLabels = NO_DISABLED,
+}: {
+  wrap?: boolean;
+  disabledLabels?: string[];
+}) {
+  const {listRef, handleKeyDown} = useListFocus<HTMLDivElement>({wrap});
+  const items = ['One', 'Two', 'Three', 'Four'];
+  return (
+    <div ref={listRef} role="menu" onKeyDown={handleKeyDown}>
+      {items.map(label => {
+        const disabled = disabledLabels.includes(label);
+        return (
+          <div
+            key={label}
+            role="menuitem"
+            tabIndex={disabled ? undefined : -1}
+            aria-disabled={disabled || undefined}
+            data-testid={label}>
+            {label}
+          </div>
+        );
+      })}
+    </div>
+  );
+}
+
+describe('useListFocus disabled-item skipping', () => {
+  it('ArrowDown skips a disabled item instead of stalling on it', () => {
+    render(<Menu disabledLabels={['Two']} />);
+    const menu = screen.getByRole('menu');
+    screen.getByTestId('One').focus();
+
+    fireEvent.keyDown(menu, {key: 'ArrowDown'});
+    // Should skip disabled "Two" and land on "Three".
+    expect(screen.getByTestId('Three')).toHaveFocus();
+  });
+
+  it('ArrowUp skips a disabled item', () => {
+    render(<Menu disabledLabels={['Three']} />);
+    const menu = screen.getByRole('menu');
+    screen.getByTestId('Four').focus();
+
+    fireEvent.keyDown(menu, {key: 'ArrowUp'});
+    // Should skip disabled "Three" and land on "Two".
+    expect(screen.getByTestId('Two')).toHaveFocus();
+  });
+
+  it('does not freeze at a leading disabled item (regression: menus-4)', () => {
+    render(<Menu disabledLabels={['One']} />);
+    const menu = screen.getByRole('menu');
+    // Focus starts nowhere; ArrowDown should reach the first ENABLED item.
+    fireEvent.keyDown(menu, {key: 'ArrowDown'});
+    expect(screen.getByTestId('Two')).toHaveFocus();
+  });
+
+  it('wraps past a disabled item at the end', () => {
+    render(<Menu disabledLabels={['Four']} wrap />);
+    const menu = screen.getByRole('menu');
+    screen.getByTestId('Three').focus();
+
+    fireEvent.keyDown(menu, {key: 'ArrowDown'});
+    // "Four" is disabled, wrap to "One".
+    expect(screen.getByTestId('One')).toHaveFocus();
+  });
+
+  it('does not wrap when wrap is false', () => {
+    render(<Menu disabledLabels={['Four']} wrap={false} />);
+    const menu = screen.getByRole('menu');
+    screen.getByTestId('Three').focus();
+
+    fireEvent.keyDown(menu, {key: 'ArrowDown'});
+    // "Four" disabled, no wrap -> focus stays on "Three".
+    expect(screen.getByTestId('Three')).toHaveFocus();
+  });
+
+  it('Home focuses the first enabled item, End the last enabled item', () => {
+    render(<Menu disabledLabels={['One', 'Four']} />);
+    const menu = screen.getByRole('menu');
+    screen.getByTestId('Two').focus();
+
+    fireEvent.keyDown(menu, {key: 'End'});
+    expect(screen.getByTestId('Three')).toHaveFocus();
+
+    fireEvent.keyDown(menu, {key: 'Home'});
+    expect(screen.getByTestId('Two')).toHaveFocus();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Roving-tabindex mode + composite navigation behaviors.
+// These exercise the opt-in `hasRovingTabIndex`, `isRtl`, `orientation: 'both'`,
+// `hasCaretGuard`, and shortcut-passthrough behaviors.
+// ---------------------------------------------------------------------------
+
+const ROVING_LABELS = ['A', 'B', 'C'];
+
+function RovingToolbar({
+  labels = ROVING_LABELS,
+  disabledLabels = NO_DISABLED,
+  ...opts
+}: {
+  labels?: string[];
+  disabledLabels?: string[];
+} & Parameters<typeof useListFocus>[0]) {
+  const {listRef, handleKeyDown, handleFocus} = useListFocus<HTMLDivElement>({
+    itemSelector: 'button, input, [tabindex]',
+    hasRovingTabIndex: true,
+    orientation: 'horizontal',
+    ...opts,
+  });
+  return (
+    <div
+      ref={listRef}
+      role="toolbar"
+      onKeyDown={handleKeyDown}
+      onFocus={handleFocus}>
+      {labels.map(label => (
+        <button
+          key={label}
+          type="button"
+          disabled={disabledLabels.includes(label)}
+          data-testid={label}>
+          {label}
+        </button>
+      ))}
+    </div>
+  );
+}
+
+describe('useListFocus roving tabindex (hasRovingTabIndex)', () => {
+  it('stamps a single tab stop (first enabled item is tabbable)', () => {
+    render(<RovingToolbar />);
+    expect(screen.getByTestId('A')).toHaveAttribute('tabindex', '0');
+    expect(screen.getByTestId('B')).toHaveAttribute('tabindex', '-1');
+    expect(screen.getByTestId('C')).toHaveAttribute('tabindex', '-1');
+  });
+
+  it('promotes the first ENABLED item when the first is disabled (repair)', () => {
+    render(<RovingToolbar disabledLabels={['A']} />);
+    expect(screen.getByTestId('B')).toHaveAttribute('tabindex', '0');
+    expect(screen.getByTestId('A')).toHaveAttribute('tabindex', '-1');
+  });
+
+  it('ArrowRight moves the tab stop to the next enabled item', () => {
+    render(<RovingToolbar />);
+    const toolbar = screen.getByRole('toolbar');
+    screen.getByTestId('A').focus();
+    fireEvent.keyDown(toolbar, {key: 'ArrowRight'});
+    expect(screen.getByTestId('B')).toHaveFocus();
+    expect(screen.getByTestId('B')).toHaveAttribute('tabindex', '0');
+    expect(screen.getByTestId('A')).toHaveAttribute('tabindex', '-1');
+  });
+
+  it('ArrowRight skips a disabled item', () => {
+    render(<RovingToolbar disabledLabels={['B']} />);
+    const toolbar = screen.getByRole('toolbar');
+    screen.getByTestId('A').focus();
+    fireEvent.keyDown(toolbar, {key: 'ArrowRight'});
+    expect(screen.getByTestId('C')).toHaveFocus();
+  });
+
+  it('wraps at the end by default', () => {
+    render(<RovingToolbar />);
+    const toolbar = screen.getByRole('toolbar');
+    screen.getByTestId('C').focus();
+    fireEvent.keyDown(toolbar, {key: 'ArrowRight'});
+    expect(screen.getByTestId('A')).toHaveFocus();
+  });
+
+  it('does not wrap when wrap=false', () => {
+    render(<RovingToolbar wrap={false} />);
+    const toolbar = screen.getByRole('toolbar');
+    screen.getByTestId('C').focus();
+    fireEvent.keyDown(toolbar, {key: 'ArrowRight'});
+    expect(screen.getByTestId('C')).toHaveFocus();
+  });
+
+  it('Home/End jump to first/last enabled items', () => {
+    render(<RovingToolbar />);
+    const toolbar = screen.getByRole('toolbar');
+    screen.getByTestId('B').focus();
+    fireEvent.keyDown(toolbar, {key: 'End'});
+    expect(screen.getByTestId('C')).toHaveFocus();
+    fireEvent.keyDown(toolbar, {key: 'Home'});
+    expect(screen.getByTestId('A')).toHaveFocus();
+  });
+
+  it('flips ArrowLeft/ArrowRight under RTL', () => {
+    render(<RovingToolbar isRtl />);
+    const toolbar = screen.getByRole('toolbar');
+    screen.getByTestId('A').focus();
+    // In RTL, ArrowLeft is "forward".
+    fireEvent.keyDown(toolbar, {key: 'ArrowLeft'});
+    expect(screen.getByTestId('B')).toHaveFocus();
+  });
+
+  it('orientation "both" navigates with all four arrows', () => {
+    render(<RovingToolbar orientation="both" />);
+    const toolbar = screen.getByRole('toolbar');
+    screen.getByTestId('A').focus();
+    fireEvent.keyDown(toolbar, {key: 'ArrowDown'});
+    expect(screen.getByTestId('B')).toHaveFocus();
+    fireEvent.keyDown(toolbar, {key: 'ArrowRight'});
+    expect(screen.getByTestId('C')).toHaveFocus();
+  });
+
+  it('vertical orientation ignores horizontal arrows', () => {
+    render(<RovingToolbar orientation="vertical" />);
+    const toolbar = screen.getByRole('toolbar');
+    screen.getByTestId('A').focus();
+    fireEvent.keyDown(toolbar, {key: 'ArrowDown'});
+    expect(screen.getByTestId('B')).toHaveFocus();
+    fireEvent.keyDown(toolbar, {key: 'ArrowRight'});
+    // ArrowRight is inert in vertical mode.
+    expect(screen.getByTestId('B')).toHaveFocus();
+  });
+
+  it('does not manage tabindex when hasRovingTabIndex is off', () => {
+    render(<RovingToolbar hasRovingTabIndex={false} />);
+    // No tabindex stamped — the buttons keep their intrinsic tab order.
+    expect(screen.getByTestId('A')).not.toHaveAttribute('tabindex');
+    expect(screen.getByTestId('B')).not.toHaveAttribute('tabindex');
+  });
+});
+
+function ToolbarWithInput(opts: Parameters<typeof useListFocus>[0]) {
+  const {listRef, handleKeyDown, handleFocus} = useListFocus<HTMLDivElement>({
+    itemSelector: 'button, input, [tabindex]',
+    hasRovingTabIndex: true,
+    orientation: 'horizontal',
+    hasCaretGuard: true,
+    ...opts,
+  });
+  return (
+    <div
+      ref={listRef}
+      role="toolbar"
+      onKeyDown={handleKeyDown}
+      onFocus={handleFocus}>
+      <button type="button" data-testid="before">
+        Before
+      </button>
+      <input type="text" defaultValue="hello" data-testid="field" />
+      <button type="button" data-testid="after">
+        After
+      </button>
+    </div>
+  );
+}
+
+describe('useListFocus caret-boundary guard (hasCaretGuard, navigation-4)', () => {
+  function getField(): HTMLInputElement {
+    const el = screen.getByTestId('field');
+    if (!(el instanceof HTMLInputElement)) {
+      throw new Error('expected an input');
+    }
+    return el;
+  }
+
+  it('does not steal ArrowRight from a text input mid-line', () => {
+    render(<ToolbarWithInput />);
+    const toolbar = screen.getByRole('toolbar');
+    const field = getField();
+    field.focus();
+    field.setSelectionRange(1, 1); // caret in the middle of "hello"
+    fireEvent.keyDown(toolbar, {key: 'ArrowRight'});
+    // Focus stays in the input; caret movement is left to the browser.
+    expect(field).toHaveFocus();
+  });
+
+  it('steals ArrowRight when the caret is at the end of the input', () => {
+    render(<ToolbarWithInput />);
+    const toolbar = screen.getByRole('toolbar');
+    const field = getField();
+    field.focus();
+    field.setSelectionRange(5, 5); // caret at end of "hello"
+    fireEvent.keyDown(toolbar, {key: 'ArrowRight'});
+    // Now the composite navigates to the next item.
+    expect(screen.getByTestId('after')).toHaveFocus();
+  });
+
+  it('does not steal an arrow key when the input has a selection', () => {
+    render(<ToolbarWithInput />);
+    const toolbar = screen.getByRole('toolbar');
+    const field = getField();
+    field.focus();
+    field.setSelectionRange(0, 5); // whole value selected
+    fireEvent.keyDown(toolbar, {key: 'ArrowRight'});
+    expect(field).toHaveFocus();
+  });
+
+  it('steals the key from a text input when hasCaretGuard is off', () => {
+    render(<ToolbarWithInput hasCaretGuard={false} />);
+    const toolbar = screen.getByRole('toolbar');
+    const field = getField();
+    field.focus();
+    field.setSelectionRange(1, 1); // caret mid-line, but no caret guard
+    fireEvent.keyDown(toolbar, {key: 'ArrowRight'});
+    expect(screen.getByTestId('after')).toHaveFocus();
+  });
+});
+
+function ToolbarWithEditable(opts: Parameters<typeof useListFocus>[0]) {
+  const {listRef, handleKeyDown, handleFocus} = useListFocus<HTMLDivElement>({
+    itemSelector: 'button, input, [contenteditable], [tabindex]',
+    hasRovingTabIndex: true,
+    orientation: 'horizontal',
+    hasCaretGuard: true,
+    ...opts,
+  });
+  return (
+    <div
+      ref={listRef}
+      role="toolbar"
+      onKeyDown={handleKeyDown}
+      onFocus={handleFocus}>
+      <button type="button" data-testid="before">
+        Before
+      </button>
+      <div
+        contentEditable
+        suppressContentEditableWarning
+        data-testid="composer">
+        hello world
+      </div>
+      <button type="button" data-testid="after">
+        After
+      </button>
+    </div>
+  );
+}
+
+describe('useListFocus caret-boundary guard: contenteditable (navigation-4)', () => {
+  it('does not steal arrow keys from a non-empty contenteditable', () => {
+    render(<ToolbarWithEditable />);
+    const toolbar = screen.getByRole('toolbar');
+    const composer = screen.getByTestId('composer');
+    composer.focus();
+    fireEvent.keyDown(toolbar, {key: 'ArrowRight'});
+    // Focus stays in the editor; list navigation must not hijack the arrow.
+    expect(composer).toHaveFocus();
+    fireEvent.keyDown(toolbar, {key: 'ArrowLeft'});
+    expect(composer).toHaveFocus();
+  });
+});
+
+describe('useListFocus shortcut passthrough', () => {
+  it('passes browser shortcut chords (Cmd/Ctrl/Alt) through', () => {
+    render(<RovingToolbar />);
+    const toolbar = screen.getByRole('toolbar');
+    screen.getByTestId('A').focus();
+    fireEvent.keyDown(toolbar, {key: 'ArrowRight', metaKey: true});
+    // Focus should not move on a modified chord.
+    expect(screen.getByTestId('A')).toHaveFocus();
+  });
+});