@astryxdesign/core 0.1.2-canary.bfcbf64 → 0.1.2-canary.c395fca

package/src/TreeList/TreeList.tsx

@@ -99,12 +99,13 @@ function collectExpandedKeys(items: TreeListItemData[]): string[] {
 }
 
 /**
- * Compute the initial roving-tabindex owner: the first selected enabled item
- * in document order, else the first enabled item, else the first item.
- * Only the top-level candidates are considered for the default so the tab stop
- * is reachable even when the tree is fully collapsed.
+ * Compute the initial roving-tabindex seed: the first selected enabled item in
+ * document order, else the first enabled item, else the first item. The hook
+ * (useTreeFocus with hasRovingTabIndex) takes ownership after mount — it
+ * preserves this seeded `tabindex="0"` on its repair pass and moves the stop
+ * with keyboard navigation.
  */
-function findDefaultActiveId(items: TreeListItemData[]): string | undefined {
+function findInitialTabbableId(items: TreeListItemData[]): string | undefined {
   let firstEnabled: string | undefined;
   const walk = (list: TreeListItemData[]): string | undefined => {
     for (const item of list) {
@@ -193,28 +194,15 @@ export function TreeList({
   // Roving tabindex + APG tree keyboard model (via useTreeFocus)
   // ---------------------------------------------------------------------------
 
-  // The treeitem that currently owns the tree's single tab stop. The hook moves
-  // it around via onActiveChange; a data-driven default seeds it (selected item
-  // or first enabled).
-  const [activeId, setActiveId] = useState<string | undefined>(() =>
-    findDefaultActiveId(items),
+  // The hook (hasRovingTabIndex) owns the tree's single tab stop: it repairs
+  // the stop on mount and moves it with keyboard navigation. We only seed the
+  // initially-tabbable treeitem in the render (selected item or first enabled);
+  // the hook's repair pass preserves that seeded `tabindex="0"`.
+  const initialTabbableId = useMemo(
+    () => findInitialTabbableId(items),
+    [items],
   );
 
-  // If the seed id is no longer present (items changed), fall back to a valid
-  // default so the tree always has exactly one reachable tab stop.
-  const resolvedActiveId = useMemo(() => {
-    if (activeId == null) {
-      return findDefaultActiveId(items);
-    }
-    const exists = (list: TreeListItemData[]): boolean =>
-      list.some(
-        item =>
-          item.id === activeId ||
-          (item.children != null && exists(item.children)),
-      );
-    return exists(items) ? activeId : findDefaultActiveId(items);
-  }, [activeId, items]);
-
   // Enter/Space activation: prefer the treeitem's own inner action (link or
   // button); return true when handled so the hook does not also toggle. Scoped
   // to this treeitem's own row — never a descendant treeitem's action inside an
@@ -232,10 +220,10 @@ export function TreeList({
     return false;
   }, []);
 
-  const {treeRef, handleKeyDown} = useTreeFocus<HTMLUListElement>({
+  const {treeRef, handleKeyDown, handleFocus} = useTreeFocus<HTMLUListElement>({
     onToggleExpand: handleToggle,
     onActivate: activateItem,
-    onActiveChange: setActiveId,
+    hasRovingTabIndex: true,
   });
 
   function renderItems(
@@ -286,7 +274,7 @@ export function TreeList({
           renderedChildren={renderedChildren}
           posInSet={index + 1}
           setSize={items.length}
-          isTabbable={item.id === resolvedActiveId}
+          isTabbable={item.id === initialTabbableId}
         />
       );
     });
@@ -312,6 +300,7 @@ export function TreeList({
         role="tree"
         aria-labelledby={header != null ? headerId : undefined}
         onKeyDown={handleKeyDown}
+        onFocus={handleFocus}
         {...stylex.props(styles.list)}>
         {renderItems(items, 0, [])}
       </ul>

package/src/TreeList/TreeListItem.tsx

@@ -265,8 +265,9 @@ export interface TreeListItemInternalProps {
   /** Number of siblings at this level (aria-setsize). */
   setSize: number;
   /**
-   * Whether this treeitem currently owns the tree's single tab stop
-   * (roving tabindex). Exactly one visible treeitem is tabbable at a time.
+   * Whether this treeitem is the initial roving-tabindex seed. Exactly one
+   * treeitem is seeded tabbable at mount; useTreeFocus (hasRovingTabIndex)
+   * then owns the tab stop dynamically.
    */
   isTabbable: boolean;
 }

package/src/VisuallyHidden/VisuallyHidden.doc.mjs

@@ -23,12 +23,12 @@ export const docs = {
     },
   ],
   usage: {
-    description: 'Renders content in the accessibility tree while hiding it visually. Use for accessible names on icon-only controls, aria-live announcement regions, and supplementary screen-reader context. Deliberately has no styling props — the whole point is to stay invisible.',
+    description: 'Renders content in the accessibility tree while hiding it visually. Use for accessible names on icon-only controls, aria-live announcement regions, and supplementary screen-reader context. Deliberately has no styling props; the whole point is to stay invisible.',
     bestPractices: [
       { guidance: true, description: 'Use to give icon-only buttons and controls an accessible name that screen readers announce.' },
       { guidance: true, description: 'Render as a block element (as="div") with aria-live to announce dynamic updates like drag-and-drop or result counts.' },
-      { guidance: false, description: 'Use it to hide content from everyone — it stays in the accessibility tree; use conditional rendering or `hidden` to remove content entirely.' },
-      { guidance: false, description: 'Put interactive controls inside it — the content is not visible and cannot receive pointer input.' },
+      { guidance: false, description: 'Use it to hide content from everyone; it stays in the accessibility tree; use conditional rendering or `hidden` to remove content entirely.' },
+      { guidance: false, description: 'Put interactive controls inside it; the content is not visible and cannot receive pointer input.' },
     ],
   },
 };
@@ -55,8 +55,8 @@ export const docsZh = {
     bestPractices: [
       { guidance: true, description: 'Use to give icon-only buttons and controls an accessible name that screen readers announce.' },
       { guidance: true, description: 'Render as a block element (as="div") with aria-live to announce dynamic updates like drag-and-drop or result counts.' },
-      { guidance: false, description: 'Use it to hide content from everyone — it stays in the accessibility tree; use conditional rendering or `hidden` to remove content entirely.' },
-      { guidance: false, description: 'Put interactive controls inside it — the content is not visible and cannot receive pointer input.' },
+      { guidance: false, description: 'Use it to hide content from everyone; it stays in the accessibility tree; use conditional rendering or `hidden` to remove content entirely.' },
+      { guidance: false, description: 'Put interactive controls inside it; the content is not visible and cannot receive pointer input.' },
     ],
   },
 };
@@ -69,8 +69,8 @@ export const docsDense = {
     bestPractices: [
       { guidance: true, description: 'Use to give icon-only buttons and controls an accessible name that screen readers announce.' },
       { guidance: true, description: 'Render as a block element (as="div") with aria-live to announce dynamic updates like drag-and-drop or result counts.' },
-      { guidance: false, description: 'Use it to hide content from everyone — it stays in the accessibility tree; use conditional rendering or `hidden` to remove content entirely.' },
-      { guidance: false, description: 'Put interactive controls inside it — the content is not visible and cannot receive pointer input.' },
+      { guidance: false, description: 'Use it to hide content from everyone; it stays in the accessibility tree; use conditional rendering or `hidden` to remove content entirely.' },
+      { guidance: false, description: 'Put interactive controls inside it; the content is not visible and cannot receive pointer input.' },
     ],
   },
   propDescriptions: {

package/src/hooks/index.ts

@@ -31,6 +31,13 @@ export {useTreeFocus} from './useTreeFocus';
 export type {UseTreeFocusOptions, UseTreeFocusReturn} from './useTreeFocus';
 
 export {useTypeahead} from './useTypeahead';
+
+export {useKeyboardHint} from './useKeyboardHint';
+export type {
+  UseKeyboardHintOptions,
+  UseKeyboardHintReturn,
+  KeyboardHintOrientation,
+} from './useKeyboardHint';
 export type {UseTypeaheadOptions, UseTypeaheadReturn} from './useTypeahead';
 
 export {useMediaQuery} from './useMediaQuery';
@@ -54,7 +61,10 @@ export type {
 export {useImageMode} from './useImageMode';
 export type {ImageSampleRegion, UseImageModeOptions} from './useImageMode';
 
-export {useClickableContainer, INTERACTIVE_SELECTORS} from './useClickableContainer';
+export {
+  useClickableContainer,
+  INTERACTIVE_SELECTORS,
+} from './useClickableContainer';
 export type {
   UseClickableContainerOptions,
   ClickableContainerResult,
@@ -70,7 +80,4 @@ export type {
 } from './useInteractiveRole';
 
 export {useLongPress} from './useLongPress';
-export type {
-  UseLongPressOptions,
-  UseLongPressHandlers,
-} from './useLongPress';
+export type {UseLongPressOptions, UseLongPressHandlers} from './useLongPress';

package/src/hooks/useGridFocus.doc.mjs

@@ -21,10 +21,22 @@ export const docs = {
     {
       name: 'options.cellSelector',
       type: 'string',
-      description: 'Selector for focusable cells within the grid.',
+      description: 'Selector for cells within the grid. Should match ALL cell positions in DOM order (including disabled/empty) so grid geometry is preserved.',
       default: "'button:not([disabled]), [tabindex]:not([tabindex=\"-1\"])'",
       required: false,
     },
+    {
+      name: 'options.isCellFocusable',
+      type: '(cell: HTMLElement) => boolean',
+      description: 'Predicate for whether a matched cell can receive focus. Omit to treat every matched cell as focusable.',
+      required: false,
+    },
+    {
+      name: 'options.getFocusTarget',
+      type: '(cell: HTMLElement) => HTMLElement | null',
+      description: 'Resolves the element to focus for a cell, e.g. a button inside a role="gridcell" wrapper. Omit to focus the cell itself.',
+      required: false,
+    },
     {
       name: 'options.onNavigateBefore',
       type: '(column: number, offset: number) => void',
@@ -49,6 +61,20 @@ export const docs = {
       description: 'Callback for Page Down key (e.g., navigate to next month in calendars).',
       required: false,
     },
+    {
+      name: 'options.isRtl',
+      type: 'boolean',
+      description: 'Swap ArrowLeft/ArrowRight so horizontal navigation follows visual direction in right-to-left contexts.',
+      default: 'false',
+      required: false,
+    },
+    {
+      name: 'options.hasRovingTabIndex',
+      type: 'boolean',
+      description: 'Own a single roving tab stop across the grid: one focusable cell (its resolved focus target) carries tabindex="0", the rest -1. Stamped/repaired on render and moved with arrow navigation. Attach the returned handleFocus to the container onFocus.',
+      default: 'false',
+      required: false,
+    },
   ],
   returns: [
     {
@@ -61,6 +87,11 @@ export const docs = {
       type: '(e: React.KeyboardEvent) => void',
       description: 'Key down handler to attach to the grid container.',
     },
+    {
+      name: 'handleFocus',
+      type: '(e: React.FocusEvent) => void',
+      description: 'Focus handler for the grid container. Keeps the roving tab stop in sync when hasRovingTabIndex is enabled; a no-op otherwise, so always safe to attach.',
+    },
     {
       name: 'focusCell',
       type: '(index: number) => void',
@@ -83,6 +114,7 @@ export const docs = {
     bestPractices: [
       { guidance: true, description: 'Use for calendar date grids: wire onPageUp/onPageDown to month navigation and onNavigateBefore/onNavigateAfter for cross-month arrow key navigation.' },
       { guidance: true, description: 'Attach both gridRef and handleKeyDown to the grid container element.' },
+      { guidance: true, description: 'For roving-tabindex grids (e.g. Calendar), set hasRovingTabIndex: true and attach handleFocus to the container onFocus; seed one focus target with tabindex=0 and the hook repairs and moves it.' },
       { guidance: false, description: 'Use for simple linear lists; prefer useListFocus for 1D navigation.' },
     ],
   },
@@ -99,15 +131,20 @@ export const docsDense = {
   paramDescriptions: {
     options: 'config for grid focus behavior.',
     'options.columns': '# columns in grid. Used for up/down navigation (moves by this many cells).',
-    'options.cellSelector': 'selector for focusable cells in grid.',
+    'options.cellSelector': 'selector for grid cells in DOM order (incl. disabled/empty) so geometry is preserved.',
+    'options.isCellFocusable': 'predicate for whether a matched cell can take focus. Omit = all focusable.',
+    'options.getFocusTarget': 'resolve element to focus for a cell (e.g. button inside gridcell wrapper). Omit = focus the cell.',
     'options.onNavigateBefore': 'callback when navigation would go before first cell. Receives column index + offset (1 for horizontal, columns for vertical).',
     'options.onNavigateAfter': 'callback when navigation would go after last cell. Receives column index + offset.',
     'options.onPageUp': 'callback for Page Up key (e.g. navigate to previous month in calendars).',
     'options.onPageDown': 'callback for Page Down key (e.g. navigate to next month in calendars).',
+    'options.isRtl': 'swap ArrowLeft/ArrowRight for RTL horizontal navigation. default false.',
+    'options.hasRovingTabIndex': 'own a single roving tab stop across the grid (one focus target tabindex=0, rest -1); repaired on render + moved with arrows. Attach handleFocus to onFocus. default false.',
   },
   returnDescriptions: {
     gridRef: 'ref to attach to grid container element.',
     handleKeyDown: 'key down handler for grid container.',
+    handleFocus: 'focus handler for grid container; syncs roving tab stop when hasRovingTabIndex on, else no-op.',
     focusCell: 'focus specific cell by index (clamped to valid range).',
     focusFirst: 'focus first focusable cell in grid.',
     focusLast: 'focus last focusable cell in grid.',
@@ -118,6 +155,7 @@ export const docsDense = {
     bestPractices: [
       { guidance: true, description: 'Use for calendar date grids: wire onPageUp/onPageDown to month navigation + onNavigateBefore/onNavigateAfter for cross-month arrow key navigation.' },
       { guidance: true, description: 'Attach both gridRef + handleKeyDown to grid container element.' },
+      { guidance: true, description: 'For roving-tabindex grids (e.g. Calendar): hasRovingTabIndex: true + attach handleFocus to onFocus; seed one focus target tabindex=0, hook repairs + moves it.' },
       { guidance: false, description: 'Use for simple linear lists; prefer useListFocus for 1D navigation.' },
     ],
   },

package/src/hooks/useGridFocus.test.tsx

@@ -0,0 +1,132 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file useGridFocus.test.tsx
+ * @input Uses vitest, @testing-library/react, useGridFocus hook
+ * @output Unit tests for useGridFocus roving tabindex + RTL navigation
+ * @position Testing; validates useGridFocus.ts roving-tabindex ownership
+ *
+ * SYNC: When useGridFocus.ts changes, update tests to match new behavior
+ */
+
+import {describe, it, expect} from 'vitest';
+import {render, screen, fireEvent} from '@testing-library/react';
+import {useGridFocus} from './useGridFocus';
+
+const NO_DISABLED: number[] = [];
+
+/**
+ * A 3x3 grid of cells shaped like Calendar: each `role="gridcell"` div wraps a
+ * focusable `<button>` (the focus target). `seed` marks which button starts
+ * tabbable (mirrors Calendar seeding the selected/today/first-enabled day).
+ */
+function Grid({
+  disabled = NO_DISABLED,
+  seed = 0,
+  ...opts
+}: {
+  disabled?: number[];
+  seed?: number;
+} & Partial<Parameters<typeof useGridFocus>[0]>) {
+  const {gridRef, handleKeyDown, handleFocus} = useGridFocus<HTMLDivElement>({
+    columns: 3,
+    cellSelector: '[role="gridcell"]',
+    isCellFocusable: cell =>
+      cell.querySelector('button:not([disabled])') !== null,
+    getFocusTarget: cell => cell.querySelector<HTMLElement>('button'),
+    hasRovingTabIndex: true,
+    ...opts,
+  });
+  return (
+    <div
+      ref={gridRef}
+      role="grid"
+      onKeyDown={handleKeyDown}
+      onFocus={handleFocus}>
+      {Array.from({length: 9}, (_, i) => (
+        <div role="gridcell" key={i}>
+          <button
+            type="button"
+            disabled={disabled.includes(i)}
+            tabIndex={i === seed ? 0 : -1}
+            data-testid={`cell-${i}`}>
+            {i}
+          </button>
+        </div>
+      ))}
+    </div>
+  );
+}
+
+describe('useGridFocus roving tabindex (hasRovingTabIndex)', () => {
+  it('honors the seeded tab stop and stamps -1 on the rest', () => {
+    render(<Grid seed={4} />);
+    expect(screen.getByTestId('cell-4')).toHaveAttribute('tabindex', '0');
+    expect(screen.getByTestId('cell-0')).toHaveAttribute('tabindex', '-1');
+    expect(screen.getByTestId('cell-8')).toHaveAttribute('tabindex', '-1');
+  });
+
+  it('repairs to the first focusable cell when no cell is seeded', () => {
+    render(<Grid seed={-1} />);
+    expect(screen.getByTestId('cell-0')).toHaveAttribute('tabindex', '0');
+    expect(screen.getByTestId('cell-1')).toHaveAttribute('tabindex', '-1');
+  });
+
+  it('promotes the first ENABLED cell when the seed is disabled', () => {
+    render(<Grid seed={-1} disabled={[0, 1]} />);
+    expect(screen.getByTestId('cell-2')).toHaveAttribute('tabindex', '0');
+    expect(screen.getByTestId('cell-0')).toHaveAttribute('tabindex', '-1');
+  });
+
+  it('ArrowRight moves the tab stop to the next cell', () => {
+    render(<Grid seed={0} />);
+    const grid = screen.getByRole('grid');
+    screen.getByTestId('cell-0').focus();
+    fireEvent.keyDown(grid, {key: 'ArrowRight'});
+    expect(screen.getByTestId('cell-1')).toHaveFocus();
+    expect(screen.getByTestId('cell-1')).toHaveAttribute('tabindex', '0');
+    expect(screen.getByTestId('cell-0')).toHaveAttribute('tabindex', '-1');
+  });
+
+  it('ArrowDown moves the tab stop one row down', () => {
+    render(<Grid seed={0} />);
+    const grid = screen.getByRole('grid');
+    screen.getByTestId('cell-0').focus();
+    fireEvent.keyDown(grid, {key: 'ArrowDown'});
+    expect(screen.getByTestId('cell-3')).toHaveFocus();
+    expect(screen.getByTestId('cell-3')).toHaveAttribute('tabindex', '0');
+  });
+
+  it('handleFocus repairs the stop when the tabbable cell became disabled', () => {
+    // Seed cell 0 as tabbable, then disable it and fire the container onFocus.
+    // syncTabStops should promote the first still-focusable cell (cell 1).
+    const {rerender} = render(<Grid seed={0} />);
+    const grid = screen.getByRole('grid');
+    expect(screen.getByTestId('cell-0')).toHaveAttribute('tabindex', '0');
+    rerender(<Grid seed={-1} disabled={[0]} />);
+    fireEvent.focus(grid);
+    expect(screen.getByTestId('cell-1')).toHaveAttribute('tabindex', '0');
+    expect(screen.getByTestId('cell-0')).toHaveAttribute('tabindex', '-1');
+  });
+
+  it('flips ArrowLeft/ArrowRight under RTL', () => {
+    render(<Grid seed={1} isRtl />);
+    const grid = screen.getByRole('grid');
+    screen.getByTestId('cell-1').focus();
+    // In RTL, ArrowLeft is "forward" (moves to the next cell in DOM order).
+    fireEvent.keyDown(grid, {key: 'ArrowLeft'});
+    expect(screen.getByTestId('cell-2')).toHaveFocus();
+  });
+
+  it('does not manage tabindex when hasRovingTabIndex is off', () => {
+    render(<Grid seed={0} hasRovingTabIndex={false} />);
+    // The seeded -1/0 values are left untouched (caller owns them), and
+    // navigation still works without stamping.
+    const grid = screen.getByRole('grid');
+    screen.getByTestId('cell-0').focus();
+    fireEvent.keyDown(grid, {key: 'ArrowRight'});
+    expect(screen.getByTestId('cell-1')).toHaveFocus();
+    // cell-1 kept its seeded -1; the hook did not promote it.
+    expect(screen.getByTestId('cell-1')).toHaveAttribute('tabindex', '-1');
+  });
+});