@astryxdesign/core 0.1.2 → 0.1.3-canary.6d57c8d

package/dist/hooks/useTreeFocus.d.ts

@@ -0,0 +1,157 @@
+/**
+ * Configuration for tree focus behavior.
+ *
+ * The tree keyboard model differs from a linear list (useListFocus): while
+ * ArrowUp/ArrowDown/Home/End roam linearly over the *visible* treeitems,
+ * ArrowRight/ArrowLeft carry tree semantics (expand/collapse, move to
+ * first-child / parent). The hook stays generic by taking callbacks for the
+ * tree-specific bits (expansion toggling, activation) — mirroring how
+ * useGridFocus takes `isCellFocusable` rather than hardcoding disabled logic.
+ */
+export interface UseTreeFocusOptions {
+    /**
+     * Selector for treeitems within the tree. Matches ALL visible treeitems in
+     * DOM order (collapsed subtrees are not rendered, so they are naturally
+     * excluded). Disabled treeitems are still matched and then skipped via
+     * {@link UseTreeFocusOptions.isItemDisabled}.
+     * @default '[role="treeitem"]'
+     */
+    itemSelector?: string;
+    /**
+     * Predicate determining whether a treeitem matched by `itemSelector` is
+     * disabled and must be skipped during arrow/Home/End navigation. A `.focus()`
+     * on a disabled item silently no-ops, so navigation would otherwise stall.
+     *
+     * @default reads `data-tree-disabled` (present ⇒ disabled)
+     */
+    isItemDisabled?: (item: HTMLElement) => boolean;
+    /**
+     * Reads the nesting level (aria-level style, 1-based) of a treeitem. Used to
+     * resolve first-child (ArrowRight) and parent (ArrowLeft) targets from the
+     * flat visible-item list.
+     *
+     * @default reads the `aria-level` attribute (falling back to `1`)
+     */
+    getLevel?: (item: HTMLElement) => number;
+    /**
+     * Whether a treeitem is an expanded parent. Read DOM-side (aria-expanded)
+     * by default so it reflects the rendered tree without prop plumbing.
+     *
+     * @default `aria-expanded === 'true'`
+     */
+    isExpanded?: (item: HTMLElement) => boolean;
+    /**
+     * Whether a treeitem is a collapsed parent (has children but is closed).
+     *
+     * @default `aria-expanded === 'false'`
+     */
+    isCollapsed?: (item: HTMLElement) => boolean;
+    /**
+     * Resolve the stable id for a treeitem, passed to `onToggleExpand` /
+     * `onActivate`. Returns `undefined` when the element carries no id.
+     *
+     * @default reads the `data-tree-id` attribute
+     */
+    getItemId?: (item: HTMLElement) => string | undefined;
+    /**
+     * Called to expand/collapse the treeitem with the given id (ArrowRight on a
+     * collapsed parent, ArrowLeft on an expanded parent, and Enter/Space on a
+     * parent that has no inner action).
+     */
+    onToggleExpand?: (id: string) => void;
+    /**
+     * Called when Enter/Space activates a treeitem. Return `true` if the
+     * activation was handled (e.g. an inner link/button was clicked); return
+     * `false`/`undefined` to let the hook fall back to toggling expansion for a
+     * parent. When omitted, the hook falls straight through to expansion
+     * toggling for parents.
+     *
+     * @param item The focused treeitem element.
+     * @param id The treeitem's id (per `getItemId`), if any.
+     */
+    onActivate?: (item: HTMLElement, id: string | undefined) => boolean | undefined;
+    /**
+     * Whether typeahead (jump to next item whose text starts with the typed
+     * characters) is enabled.
+     * @default true
+     */
+    typeahead?: boolean;
+    /** Reset delay for the typeahead buffer, in ms. @default 500 */
+    typeaheadResetMs?: number;
+    /**
+     * Notified whenever the hook moves focus to a treeitem, with its id (if any).
+     * TreeList uses this to move its single roving tab stop.
+     */
+    onActiveChange?: (id: string | undefined) => void;
+    /**
+     * Roving-tabindex ownership. When true, the hook manages a single tab stop
+     * across the visible treeitems: exactly one enabled treeitem carries
+     * `tabindex="0"` and the rest `tabindex="-1"`. The tab stop is repaired on
+     * mount and whenever items mount/unmount or toggle disabled, and moves with
+     * keyboard navigation. Attach the returned {@link UseTreeFocusReturn.handleFocus}
+     * to the container's `onFocus` to keep the stop in sync after clicks or
+     * programmatic focus.
+     *
+     * On mount the hook preserves an existing `tabindex="0"` treeitem (so a
+     * consumer can seed the active item in its render); if none exists it
+     * promotes the first enabled treeitem.
+     *
+     * When false (the default), the hook only *moves* focus (`.focus()`) and
+     * never touches `tabindex` — the caller owns tab-stop management.
+     * @default false
+     */
+    hasRovingTabIndex?: boolean;
+}
+/**
+ * Return type for useTreeFocus hook.
+ */
+export interface UseTreeFocusReturn<T extends HTMLElement = HTMLElement> {
+    /** Ref to attach to the tree container element (role="tree"). */
+    treeRef: React.RefObject<T | null>;
+    /** Key down handler to attach to the tree container. */
+    handleKeyDown: (e: React.KeyboardEvent) => void;
+    /**
+     * Focus handler to attach to the container's `onFocus`. Keeps the roving tab
+     * stop in sync when `hasRovingTabIndex` is enabled; a no-op otherwise, so it
+     * is always safe to attach.
+     */
+    handleFocus: (e: React.FocusEvent) => void;
+    /** Focus the first enabled visible treeitem. */
+    focusFirst: () => void;
+    /** Focus the last enabled visible treeitem. */
+    focusLast: () => void;
+}
+/**
+ * Hook for managing roving-tabindex focus + the WAI-ARIA tree keyboard model.
+ *
+ * A tree is not a linear list: ArrowUp/ArrowDown/Home/End roam linearly over
+ * the *visible* treeitems (skipping disabled ones), but ArrowRight/ArrowLeft
+ * carry tree semantics. This is why a tree needs its own hook rather than
+ * reusing `useListFocus` — the same reason 2D grids get `useGridFocus`.
+ *
+ * - ArrowDown / ArrowUp: move to next/previous visible treeitem (skip disabled)
+ * - ArrowRight: collapsed parent → expand; expanded parent → first child;
+ *   leaf → no-op
+ * - ArrowLeft: expanded parent → collapse; otherwise → move to parent treeitem
+ * - Home / End: first / last visible treeitem
+ * - Enter / Space: activate (`onActivate`), falling back to expansion toggle
+ * - Printable characters: typeahead to the next matching treeitem
+ *
+ * The hook is DOM-query based (reads aria-expanded/aria-level and data-*
+ * attributes) and stays generic via option callbacks for the tree-specific
+ * bits (`onToggleExpand`, `onActivate`, `getLevel`, `isItemDisabled`, …).
+ *
+ * @example
+ * ```
+ * const {treeRef, handleKeyDown, handleFocus} = useTreeFocus<HTMLUListElement>({
+ *   onToggleExpand: id => toggle(id),
+ *   hasRovingTabIndex: true,
+ * });
+ *
+ * <ul ref={treeRef} role="tree" onKeyDown={handleKeyDown} onFocus={handleFocus}>
+ *   {items.map(item => <li role="treeitem" tabIndex={-1}>{item.label}</li>)}
+ * </ul>
+ * ```
+ */
+export declare function useTreeFocus<T extends HTMLElement = HTMLElement>(options?: UseTreeFocusOptions): UseTreeFocusReturn<T>;
+//# sourceMappingURL=useTreeFocus.d.ts.map

package/dist/hooks/useTreeFocus.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useTreeFocus.d.ts","sourceRoot":"","sources":["../../src/hooks/useTreeFocus.ts"],"names":[],"mappings":"AAkCA;;;;;;;;;GASG;AACH,MAAM,WAAW,mBAAmB;IAClC;;;;;;OAMG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB;;;;;;OAMG;IACH,cAAc,CAAC,EAAE,CAAC,IAAI,EAAE,WAAW,KAAK,OAAO,CAAC;IAEhD;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,CAAC,IAAI,EAAE,WAAW,KAAK,MAAM,CAAC;IAEzC;;;;;OAKG;IACH,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE,WAAW,KAAK,OAAO,CAAC;IAE5C;;;;OAIG;IACH,WAAW,CAAC,EAAE,CAAC,IAAI,EAAE,WAAW,KAAK,OAAO,CAAC;IAE7C;;;;;OAKG;IACH,SAAS,CAAC,EAAE,CAAC,IAAI,EAAE,WAAW,KAAK,MAAM,GAAG,SAAS,CAAC;IAEtD;;;;OAIG;IACH,cAAc,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,IAAI,CAAC;IAEtC;;;;;;;;;OASG;IACH,UAAU,CAAC,EAAE,CACX,IAAI,EAAE,WAAW,EACjB,EAAE,EAAE,MAAM,GAAG,SAAS,KACnB,OAAO,GAAG,SAAS,CAAC;IAEzB;;;;OAIG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;IAEpB,gEAAgE;IAChE,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAE1B;;;OAGG;IACH,cAAc,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,GAAG,SAAS,KAAK,IAAI,CAAC;IAElD;;;;;;;;;;;;;;;;OAgBG;IACH,iBAAiB,CAAC,EAAE,OAAO,CAAC;CAC7B;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB,CAAC,CAAC,SAAS,WAAW,GAAG,WAAW;IACrE,iEAAiE;IACjE,OAAO,EAAE,KAAK,CAAC,SAAS,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;IAEnC,wDAAwD;IACxD,aAAa,EAAE,CAAC,CAAC,EAAE,KAAK,CAAC,aAAa,KAAK,IAAI,CAAC;IAEhD;;;;OAIG;IACH,WAAW,EAAE,CAAC,CAAC,EAAE,KAAK,CAAC,UAAU,KAAK,IAAI,CAAC;IAE3C,gDAAgD;IAChD,UAAU,EAAE,MAAM,IAAI,CAAC;IAEvB,+CAA+C;IAC/C,SAAS,EAAE,MAAM,IAAI,CAAC;CACvB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,YAAY,CAAC,CAAC,SAAS,WAAW,GAAG,WAAW,EAC9D,OAAO,GAAE,mBAAwB,GAChC,kBAAkB,CAAC,CAAC,CAAC,CA2VvB"}

package/dist/hooks/useTreeFocus.js

@@ -0,0 +1,337 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file useTreeFocus.ts
+ * @input Uses React useCallback, useRef, useIsomorphicLayoutEffect
+ * @output Exports useTreeFocus hook for WAI-ARIA tree keyboard navigation
+ * @position Core hook; used by TreeList for roving tabindex + APG tree keyboard model
+ *
+ * SYNC: When modified, update:
+ * - /packages/core/src/hooks/index.ts
+ * - /packages/core/src/hooks/useTreeFocus.doc.mjs
+ * - /packages/core/src/hooks/useTreeFocus.test.tsx
+ */
+import { useCallback, useRef } from 'react';
+import { useIsomorphicLayoutEffect } from "./useIsomorphicLayoutEffect.js";
+
+/** Keys handled by the tree keyboard model (used to gate typeahead). */
+const NAVIGATION_KEYS = new Set(['ArrowDown', 'ArrowUp', 'ArrowRight', 'ArrowLeft', 'Home', 'End', 'Enter', ' ']);
+
+/** Default reset delay for the typeahead buffer. */
+const DEFAULT_TYPEAHEAD_RESET_MS = 500;
+
+/**
+ * Configuration for tree focus behavior.
+ *
+ * The tree keyboard model differs from a linear list (useListFocus): while
+ * ArrowUp/ArrowDown/Home/End roam linearly over the *visible* treeitems,
+ * ArrowRight/ArrowLeft carry tree semantics (expand/collapse, move to
+ * first-child / parent). The hook stays generic by taking callbacks for the
+ * tree-specific bits (expansion toggling, activation) — mirroring how
+ * useGridFocus takes `isCellFocusable` rather than hardcoding disabled logic.
+ */
+
+/**
+ * Return type for useTreeFocus hook.
+ */
+
+/**
+ * Hook for managing roving-tabindex focus + the WAI-ARIA tree keyboard model.
+ *
+ * A tree is not a linear list: ArrowUp/ArrowDown/Home/End roam linearly over
+ * the *visible* treeitems (skipping disabled ones), but ArrowRight/ArrowLeft
+ * carry tree semantics. This is why a tree needs its own hook rather than
+ * reusing `useListFocus` — the same reason 2D grids get `useGridFocus`.
+ *
+ * - ArrowDown / ArrowUp: move to next/previous visible treeitem (skip disabled)
+ * - ArrowRight: collapsed parent → expand; expanded parent → first child;
+ *   leaf → no-op
+ * - ArrowLeft: expanded parent → collapse; otherwise → move to parent treeitem
+ * - Home / End: first / last visible treeitem
+ * - Enter / Space: activate (`onActivate`), falling back to expansion toggle
+ * - Printable characters: typeahead to the next matching treeitem
+ *
+ * The hook is DOM-query based (reads aria-expanded/aria-level and data-*
+ * attributes) and stays generic via option callbacks for the tree-specific
+ * bits (`onToggleExpand`, `onActivate`, `getLevel`, `isItemDisabled`, …).
+ *
+ * @example
+ * ```
+ * const {treeRef, handleKeyDown, handleFocus} = useTreeFocus<HTMLUListElement>({
+ *   onToggleExpand: id => toggle(id),
+ *   hasRovingTabIndex: true,
+ * });
+ *
+ * <ul ref={treeRef} role="tree" onKeyDown={handleKeyDown} onFocus={handleFocus}>
+ *   {items.map(item => <li role="treeitem" tabIndex={-1}>{item.label}</li>)}
+ * </ul>
+ * ```
+ */
+export function useTreeFocus(options = {}) {
+  const {
+    itemSelector = '[role="treeitem"]',
+    isItemDisabled,
+    getLevel,
+    isExpanded,
+    isCollapsed,
+    getItemId,
+    onToggleExpand,
+    onActivate,
+    typeahead = true,
+    typeaheadResetMs = DEFAULT_TYPEAHEAD_RESET_MS,
+    onActiveChange,
+    hasRovingTabIndex = false
+  } = options;
+  const treeRef = useRef(null);
+  const typeaheadRef = useRef({
+    buffer: '',
+    timer: null
+  });
+
+  /** Visible treeitems in DOM order (collapsed subtrees are not rendered). */
+  const getItems = useCallback(() => {
+    const root = treeRef.current;
+    if (root == null) {
+      return [];
+    }
+    return Array.from(root.querySelectorAll(itemSelector));
+  }, [itemSelector]);
+  const itemDisabled = useCallback(el => isItemDisabled ? isItemDisabled(el) : el.dataset.treeDisabled != null || el.getAttribute('aria-disabled') === 'true', [isItemDisabled]);
+  const levelOf = useCallback(el => getLevel ? getLevel(el) : Number(el.getAttribute('aria-level') ?? '1'), [getLevel]);
+  const expandedOf = useCallback(el => isExpanded ? isExpanded(el) : el.getAttribute('aria-expanded') === 'true', [isExpanded]);
+  const collapsedOf = useCallback(el => isCollapsed ? isCollapsed(el) : el.getAttribute('aria-expanded') === 'false', [isCollapsed]);
+  const idOf = useCallback(el => getItemId ? getItemId(el) : el.dataset.treeId, [getItemId]);
+
+  // --- Roving tabindex ownership (opt-in via `hasRovingTabIndex`) -------------
+
+  /**
+   * Set `tabindex` on a treeitem, but only when it differs (avoids redundant
+   * DOM writes).
+   */
+  const setTabIndex = useCallback((el, value) => {
+    if (el.getAttribute('tabindex') !== String(value)) {
+      el.setAttribute('tabindex', String(value));
+    }
+  }, []);
+
+  /**
+   * Make `target` the sole tabbable treeitem: 0 on it, -1 on every other
+   * visible treeitem.
+   */
+  const moveTabStop = useCallback((items, target) => {
+    for (const el of items) {
+      setTabIndex(el, el === target ? 0 : -1);
+    }
+  }, [setTabIndex]);
+
+  /**
+   * Repair the roving tab stop: exactly one enabled treeitem is tabbable (0),
+   * the rest are -1. Prefer an existing `tabindex="0"` treeitem (so a consumer
+   * can seed the active item in its render); otherwise promote the first
+   * enabled treeitem.
+   */
+  const syncTabStops = useCallback(() => {
+    const items = getItems();
+    const enabled = items.filter(el => !itemDisabled(el));
+    if (enabled.length === 0) {
+      return;
+    }
+    const current = enabled.find(el => el.getAttribute('tabindex') === '0');
+    moveTabStop(items, current ?? enabled[0]);
+  }, [getItems, itemDisabled, moveTabStop]);
+
+  // Keep the tab stop valid across renders (items added/removed, disabled
+  // toggled). Runs after every commit but only when roving tabindex is on.
+  useIsomorphicLayoutEffect(() => {
+    if (hasRovingTabIndex) {
+      syncTabStops();
+    }
+  });
+
+  /** Move focus to a treeitem and notify the active-change listener. */
+  const focusItem = useCallback(el => {
+    if (el == null) {
+      return;
+    }
+    if (hasRovingTabIndex) {
+      moveTabStop(getItems(), el);
+    }
+    onActiveChange?.(idOf(el));
+    el.focus();
+  }, [idOf, onActiveChange, hasRovingTabIndex, moveTabStop, getItems]);
+
+  /**
+   * Focus the first enabled treeitem from `start`, moving by `dir`. No wrap —
+   * a tree's linear roam clamps at the ends.
+   */
+  const focusEnabledFrom = useCallback((items, start, dir) => {
+    for (let i = start; i >= 0 && i < items.length; i += dir) {
+      const candidate = items[i];
+      if (candidate != null && !itemDisabled(candidate)) {
+        focusItem(candidate);
+        return;
+      }
+    }
+  }, [itemDisabled, focusItem]);
+  const focusFirst = useCallback(() => {
+    focusEnabledFrom(getItems(), 0, 1);
+  }, [getItems, focusEnabledFrom]);
+  const focusLast = useCallback(() => {
+    const items = getItems();
+    focusEnabledFrom(items, items.length - 1, -1);
+  }, [getItems, focusEnabledFrom]);
+  const runTypeahead = useCallback((e, items, currentIndex) => {
+    const state = typeaheadRef.current;
+    if (state.timer != null) {
+      clearTimeout(state.timer);
+    }
+    state.buffer += e.key.toLowerCase();
+    state.timer = setTimeout(() => {
+      typeaheadRef.current.buffer = '';
+    }, typeaheadResetMs);
+    const query = state.buffer;
+    const start = currentIndex < 0 ? 0 : currentIndex;
+    const ordered = [...items.slice(start + 1), ...items.slice(0, start + 1)];
+    const match = ordered.find(item => !itemDisabled(item) && (item.textContent ?? '').trim().toLowerCase().startsWith(query));
+    if (match != null) {
+      e.preventDefault();
+      focusItem(match);
+    }
+  }, [typeaheadResetMs, itemDisabled, focusItem]);
+  const handleKeyDown = useCallback(e => {
+    const items = getItems();
+    if (items.length === 0) {
+      return;
+    }
+    const active = document.activeElement;
+    // Resolve the treeitem that owns focus: the nearest treeitem ancestor of
+    // the active element (never an outer treeitem that merely contains it).
+    const activeItem = active instanceof Element ? active.closest('[role="treeitem"]') : null;
+    const currentIndex = items.findIndex(item => item === activeItem);
+    const current = currentIndex >= 0 ? items[currentIndex] : undefined;
+
+    // Typeahead: printable single characters jump to the next matching item.
+    if (typeahead && e.key.length === 1 && !e.ctrlKey && !e.metaKey && !e.altKey && NAVIGATION_KEYS.has(e.key) === false) {
+      runTypeahead(e, items, currentIndex);
+      return;
+    }
+    if (!NAVIGATION_KEYS.has(e.key)) {
+      return;
+    }
+    switch (e.key) {
+      case 'ArrowDown':
+        {
+          e.preventDefault();
+          focusEnabledFrom(items, currentIndex < 0 ? 0 : currentIndex + 1, 1);
+          break;
+        }
+      case 'ArrowUp':
+        {
+          e.preventDefault();
+          focusEnabledFrom(items, currentIndex < 0 ? items.length - 1 : currentIndex - 1, -1);
+          break;
+        }
+      case 'ArrowRight':
+        {
+          if (current == null) {
+            break;
+          }
+          e.preventDefault();
+          if (collapsedOf(current)) {
+            // Collapsed parent → expand.
+            const id = idOf(current);
+            if (id != null) {
+              onToggleExpand?.(id);
+            }
+          } else if (expandedOf(current)) {
+            // Expanded parent → move to first child.
+            const next = items[currentIndex + 1];
+            if (next != null && levelOf(next) > levelOf(current)) {
+              focusItem(next);
+            }
+          }
+          // Leaf → no-op.
+          break;
+        }
+      case 'ArrowLeft':
+        {
+          if (current == null) {
+            break;
+          }
+          e.preventDefault();
+          if (expandedOf(current)) {
+            // Expanded parent → collapse.
+            const id = idOf(current);
+            if (id != null) {
+              onToggleExpand?.(id);
+            }
+          } else {
+            // Otherwise → move to parent treeitem (nearest shallower item
+            // scanning upward in visible order).
+            const currentLevel = levelOf(current);
+            for (let i = currentIndex - 1; i >= 0; i--) {
+              const candidate = items[i];
+              if (candidate != null && levelOf(candidate) < currentLevel) {
+                focusItem(candidate);
+                break;
+              }
+            }
+          }
+          break;
+        }
+      case 'Home':
+        {
+          e.preventDefault();
+          focusEnabledFrom(items, 0, 1);
+          break;
+        }
+      case 'End':
+        {
+          e.preventDefault();
+          focusEnabledFrom(items, items.length - 1, -1);
+          break;
+        }
+      case 'Enter':
+      case ' ':
+        {
+          if (current == null || itemDisabled(current)) {
+            break;
+          }
+          e.preventDefault();
+          const id = idOf(current);
+          // Activate the item: prefer the consumer's onActivate (e.g. click an
+          // inner link/button). Fall back to toggling expansion for a parent
+          // without its own action.
+          const handled = onActivate ? onActivate(current, id) === true : false;
+          if (!handled && current.getAttribute('aria-expanded') != null) {
+            if (id != null) {
+              onToggleExpand?.(id);
+            }
+          }
+          break;
+        }
+      default:
+        break;
+    }
+  }, [getItems, typeahead, runTypeahead, focusEnabledFrom, focusItem, collapsedOf, expandedOf, idOf, levelOf, itemDisabled, onToggleExpand, onActivate]);
+
+  /**
+   * Keep the roving stop pointing at whatever ended up focused (e.g. a click
+   * or programmatic focus) so the next Tab behaves correctly. No-op unless
+   * roving tabindex is enabled.
+   */
+  const handleFocus = useCallback(() => {
+    if (hasRovingTabIndex) {
+      syncTabStops();
+    }
+  }, [hasRovingTabIndex, syncTabStops]);
+  return {
+    treeRef,
+    handleKeyDown,
+    handleFocus,
+    focusFirst,
+    focusLast
+  };
+}

package/dist/hooks/useTypeahead.d.ts

@@ -0,0 +1,63 @@
+export interface UseTypeaheadOptions {
+    /**
+     * Returns the current, in-DOM-order list of item labels to match against.
+     * An entry may be `null`/empty to mark a non-matchable slot (its index is
+     * preserved so it maps 1:1 to the caller's items).
+     */
+    getItemLabels: () => ReadonlyArray<string | null | undefined>;
+    /**
+     * Called with the index of the matched item so the caller can focus/select
+     * it (e.g. `useListFocus`'s `focusItem`).
+     */
+    onMatch: (index: number) => void;
+    /**
+     * The index to start searching from — typically the currently focused item,
+     * so repeated presses of the same letter cycle through matches. Defaults to
+     * -1 (search from the top).
+     */
+    getCurrentIndex?: () => number;
+    /**
+     * Milliseconds of inactivity after which the typed buffer resets.
+     * @default 750
+     */
+    resetMs?: number;
+    /**
+     * Whether an index should be skipped (e.g. disabled items).
+     */
+    isDisabled?: (index: number) => boolean;
+}
+export interface UseTypeaheadReturn {
+    /**
+     * Keydown handler. Call it (or let it fall through) from the collection's
+     * own key handler. Returns `true` when it handled a printable character (so
+     * the caller can `preventDefault`/stop further handling), `false` otherwise.
+     */
+    onKeyDown: (e: React.KeyboardEvent | KeyboardEvent) => boolean;
+    /** Clear the pending buffer (e.g. on close). */
+    reset: () => void;
+}
+/**
+ * First-character ("type-ahead") search for a collection.
+ *
+ * Buffers printable keystrokes (resetting after `resetMs` of inactivity),
+ * matches items whose label starts with the buffer, and cycles from the
+ * current index — so pressing "s" repeatedly walks through the "s" items
+ * instead of sticking on the first. Space is reserved for activation and is
+ * only treated as typeahead while a buffer is already active.
+ *
+ * Additive and collection-agnostic: it does not move focus itself; the caller
+ * wires `onMatch` to its own focus/selection (e.g. `useListFocus.focusItem`).
+ *
+ * @example
+ * ```
+ * const {listRef, handleKeyDown, focusItem, getItems} = useListFocus(...);
+ * const typeahead = useTypeahead({
+ *   getItemLabels: () => getItems().map(el => el.textContent),
+ *   onMatch: focusItem,
+ *   getCurrentIndex: () => getItems().findIndex(el => el === document.activeElement),
+ * });
+ * const onKeyDown = (e) => { if (!typeahead.onKeyDown(e)) handleKeyDown(e); };
+ * ```
+ */
+export declare function useTypeahead(options: UseTypeaheadOptions): UseTypeaheadReturn;
+//# sourceMappingURL=useTypeahead.d.ts.map

package/dist/hooks/useTypeahead.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useTypeahead.d.ts","sourceRoot":"","sources":["../../src/hooks/useTypeahead.ts"],"names":[],"mappings":"AAkBA,MAAM,WAAW,mBAAmB;IAClC;;;;OAIG;IACH,aAAa,EAAE,MAAM,aAAa,CAAC,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC,CAAC;IAE9D;;;OAGG;IACH,OAAO,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IAEjC;;;;OAIG;IACH,eAAe,CAAC,EAAE,MAAM,MAAM,CAAC;IAE/B;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;OAEG;IACH,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC;CACzC;AAED,MAAM,WAAW,kBAAkB;IACjC;;;;OAIG;IACH,SAAS,EAAE,CAAC,CAAC,EAAE,KAAK,CAAC,aAAa,GAAG,aAAa,KAAK,OAAO,CAAC;IAC/D,gDAAgD;IAChD,KAAK,EAAE,MAAM,IAAI,CAAC;CACnB;AAiBD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,mBAAmB,GAAG,kBAAkB,CAkF7E"}

package/dist/hooks/useTypeahead.js

@@ -0,0 +1,117 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file useTypeahead.ts
+ * @input Uses React useCallback/useRef
+ * @output Exports useTypeahead hook for first-character (type-to-focus) search
+ * @position Core hook; adds APG typeahead to menus, listboxes, and other
+ *   collections. Composes with useListFocus/useGridFocus (or any collection)
+ *   via a caller-supplied getItemLabels + onMatch.
+ *
+ * SYNC: When modified, update:
+ * - /packages/core/src/hooks/index.ts
+ */
+import { useCallback, useRef } from 'react';
+/**
+ * Whether a key event represents a single printable character (a type-to-focus
+ * candidate) rather than a control/navigation key or a shortcut chord.
+ */
+function isPrintableCharacter(e) {
+  return e.key.length === 1 && !e.ctrlKey && !e.metaKey && !e.altKey &&
+  // A lone space is used for activation in menus, not typeahead-from-empty.
+  e.key !== ' ';
+}
+
+/**
+ * First-character ("type-ahead") search for a collection.
+ *
+ * Buffers printable keystrokes (resetting after `resetMs` of inactivity),
+ * matches items whose label starts with the buffer, and cycles from the
+ * current index — so pressing "s" repeatedly walks through the "s" items
+ * instead of sticking on the first. Space is reserved for activation and is
+ * only treated as typeahead while a buffer is already active.
+ *
+ * Additive and collection-agnostic: it does not move focus itself; the caller
+ * wires `onMatch` to its own focus/selection (e.g. `useListFocus.focusItem`).
+ *
+ * @example
+ * ```
+ * const {listRef, handleKeyDown, focusItem, getItems} = useListFocus(...);
+ * const typeahead = useTypeahead({
+ *   getItemLabels: () => getItems().map(el => el.textContent),
+ *   onMatch: focusItem,
+ *   getCurrentIndex: () => getItems().findIndex(el => el === document.activeElement),
+ * });
+ * const onKeyDown = (e) => { if (!typeahead.onKeyDown(e)) handleKeyDown(e); };
+ * ```
+ */
+export function useTypeahead(options) {
+  const {
+    getItemLabels,
+    onMatch,
+    getCurrentIndex,
+    resetMs = 750,
+    isDisabled
+  } = options;
+  const bufferRef = useRef('');
+  const timeoutRef = useRef(undefined);
+  const reset = useCallback(() => {
+    bufferRef.current = '';
+    if (timeoutRef.current) {
+      clearTimeout(timeoutRef.current);
+      timeoutRef.current = undefined;
+    }
+  }, []);
+  const scheduleReset = useCallback(() => {
+    if (timeoutRef.current) {
+      clearTimeout(timeoutRef.current);
+    }
+    timeoutRef.current = setTimeout(() => {
+      bufferRef.current = '';
+      timeoutRef.current = undefined;
+    }, resetMs);
+  }, [resetMs]);
+  const onKeyDown = useCallback(e => {
+    // A bare Space with no active buffer is not typeahead (menus activate on
+    // Space); once the user is mid-typing, Space extends the query.
+    const isSpaceMidType = e.key === ' ' && bufferRef.current.length > 0;
+    if (!isPrintableCharacter(e) && !isSpaceMidType) {
+      return false;
+    }
+    const labels = getItemLabels();
+    if (labels.length === 0) {
+      return false;
+    }
+
+    // Pressing the SAME single character repeatedly cycles to the next match
+    // rather than filtering deeper (APG behavior).
+    const char = e.key.toLowerCase();
+    const isRepeatSameChar = bufferRef.current.length > 0 && bufferRef.current.split('').every(c => c === char);
+    const nextBuffer = isRepeatSameChar ? char : bufferRef.current + char;
+    bufferRef.current = nextBuffer;
+    scheduleReset();
+    const start = getCurrentIndex?.() ?? -1;
+    const count = labels.length;
+    // When repeating a single char, start the search AFTER the current item
+    // so we advance; otherwise include the current item.
+    const offset = isRepeatSameChar ? 1 : 0;
+    for (let i = 0; i < count; i++) {
+      const index = (start + offset + i + count) % count;
+      if (isDisabled?.(index)) {
+        continue;
+      }
+      const label = labels[index];
+      if (label != null && label.trim().toLowerCase().startsWith(nextBuffer)) {
+        onMatch(index);
+        return true;
+      }
+    }
+    return true;
+  }, [getItemLabels, onMatch, getCurrentIndex, scheduleReset, isDisabled]);
+  return {
+    onKeyDown,
+    reset
+  };
+}

package/dist/index.d.ts

@@ -34,6 +34,7 @@ export * from './Collapsible';
 export * from './RadioList';
 export * from './Resizable';
 export * from './Divider';
+export * from './VisuallyHidden';
 export * from './EmptyState';
 export * from './Lightbox';
 export * from './Link';