@astryxdesign/core 0.1.2 → 0.1.3

package/src/hooks/useGridFocus.ts

@@ -4,16 +4,17 @@
 
 /**
  * @file useGridFocus.ts
- * @input Uses React useCallback, useRef
+ * @input Uses React useCallback, useRef, useIsomorphicLayoutEffect
  * @output Exports useGridFocus hook for grid keyboard navigation
  * @position Core hook; used by Calendar for date grid navigation
  *
  * SYNC: When modified, update:
  * - /packages/core/src/hooks/index.ts
- * - /packages/core/src/hooks/useGridFocus.test.ts
+ * - /packages/core/src/hooks/useGridFocus.test.tsx
  */
 
 import {useCallback, useRef} from 'react';
+import {useIsomorphicLayoutEffect} from './useIsomorphicLayoutEffect';
 
 /**
  * Configuration for grid focus behavior
@@ -26,11 +27,38 @@ export interface UseGridFocusOptions {
   columns: number;
 
   /**
-   * Selector for focusable cells within the grid.
+   * Selector for cells within the grid. This should match ALL grid cell
+   * positions in DOM order (including disabled/empty ones) so the hook can
+   * preserve the true grid geometry when computing rows and columns.
+   *
+   * Use {@link UseGridFocusOptions.isCellFocusable} to distinguish cells that
+   * can receive focus from those that cannot (disabled or empty). Navigation
+   * moves to a target row/column and, if that cell is not focusable, continues
+   * in the same direction to the next focusable cell — the geometry is never
+   * collapsed to only-focusable cells.
+   *
    * @default 'button:not([disabled]), [tabindex]:not([tabindex="-1"])'
    */
   cellSelector?: string;
 
+  /**
+   * Predicate determining whether a cell matched by {@link cellSelector} can
+   * receive focus. When omitted, every matched cell is considered focusable
+   * (backwards-compatible behavior).
+   *
+   * @param cell A cell element matched by `cellSelector`.
+   */
+  isCellFocusable?: (cell: HTMLElement) => boolean;
+
+  /**
+   * Resolves the element to focus for a given cell. Useful when the cell is a
+   * wrapper element (e.g. a `role="gridcell"` div) whose focusable content is a
+   * descendant (e.g. a `<button>`). When omitted, the cell itself is focused.
+   *
+   * @param cell A cell element matched by `cellSelector`.
+   */
+  getFocusTarget?: (cell: HTMLElement) => HTMLElement | null;
+
   /**
    * Callback when navigation would go before the first cell.
    * Useful for navigating to previous month in calendars.
@@ -56,6 +84,34 @@ export interface UseGridFocusOptions {
    * Callback for Page Down key (e.g., next month).
    */
   onPageDown?: () => void;
+
+  /**
+   * Whether the grid is in a right-to-left context. When true, ArrowLeft and
+   * ArrowRight are swapped so horizontal navigation follows visual direction.
+   * @default false
+   */
+  isRtl?: boolean;
+
+  /**
+   * Roving-tabindex ownership. When true, the hook manages a single tab stop
+   * across the grid: exactly one focusable cell carries `tabindex="0"` and the
+   * rest `tabindex="-1"`. The tab stop is stamped on mount and repaired
+   * whenever cells mount/unmount or toggle focusable, and moves with arrow
+   * navigation. Attach the returned {@link UseGridFocusReturn.handleFocus} to
+   * the container's `onFocus` to keep the stop in sync after clicks or
+   * programmatic focus.
+   *
+   * The tab stop is stamped on the resolved focus target (see
+   * {@link UseGridFocusOptions.getFocusTarget}), not the cell wrapper, so it
+   * works when the focusable element is a descendant of the cell. An existing
+   * `tabindex="0"` on a focus target is honored, letting the caller seed which
+   * cell is initially tabbable.
+   *
+   * When false (the default), the hook only *moves* focus (`.focus()`) and
+   * never touches `tabindex` — the caller owns tab-stop management.
+   * @default false
+   */
+  hasRovingTabIndex?: boolean;
 }
 
 /**
@@ -72,6 +128,13 @@ export interface UseGridFocusReturn<T extends HTMLElement = HTMLElement> {
    */
   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 a specific cell by index.
    */
@@ -99,6 +162,18 @@ export interface UseGridFocusReturn<T extends HTMLElement = HTMLElement> {
  * - Ctrl+End: Move to last cell in grid
  * - Page Up/Down: Custom callbacks (e.g., month navigation)
  *
+ * The hook enumerates ALL cells matched by `cellSelector` in DOM order and
+ * computes row/column over that full set, preserving the true grid geometry
+ * even when some cells are disabled or empty. When a move lands on a
+ * non-focusable cell (per `isCellFocusable`), it continues in the same
+ * direction to the next focusable cell.
+ *
+ * By default the hook only *moves* focus and leaves `tabindex` management to
+ * the caller. Opt into {@link UseGridFocusOptions.hasRovingTabIndex} for a hook
+ * that owns a single tab stop (roving tabindex) across the grid — stamping and
+ * repairing it as cells mount/unmount or toggle focusable, and moving it with
+ * arrow navigation.
+ *
  * @example
  * ```
  * const {gridRef, handleKeyDown} = useGridFocus({
@@ -111,6 +186,24 @@ export interface UseGridFocusReturn<T extends HTMLElement = HTMLElement> {
  *   {cells.map(cell => <button role="gridcell">{cell}</button>)}
  * </div>
  * ```
+ *
+ * Roving-tabindex grid (e.g. a date picker where the cell is a wrapper around
+ * a focusable button):
+ *
+ * @example
+ * ```
+ * const {gridRef, handleKeyDown, handleFocus} = useGridFocus({
+ *   columns: 7,
+ *   cellSelector: '[role="gridcell"]',
+ *   isCellFocusable: cell => cell.querySelector('button:not([disabled])') != null,
+ *   getFocusTarget: cell => cell.querySelector('button'),
+ *   hasRovingTabIndex: true,
+ * });
+ *
+ * <div ref={gridRef} role="grid" onKeyDown={handleKeyDown} onFocus={handleFocus}>
+ *   {cells}
+ * </div>
+ * ```
  */
 export function useGridFocus<T extends HTMLElement = HTMLElement>(
   options: UseGridFocusOptions,
@@ -118,16 +211,21 @@ export function useGridFocus<T extends HTMLElement = HTMLElement>(
   const {
     columns,
     cellSelector = 'button:not([disabled]), [tabindex]:not([tabindex="-1"])',
+    isCellFocusable,
+    getFocusTarget,
     onNavigateBefore,
     onNavigateAfter,
     onPageUp,
     onPageDown,
+    isRtl = false,
+    hasRovingTabIndex = false,
   } = options;
 
   const gridRef = useRef<T>(null);
 
   /**
-   * Get all focusable cells in the grid.
+   * Get all cells in the grid, in DOM order. This includes disabled and empty
+   * cells so the true grid geometry is preserved.
    */
   const getCells = useCallback((): HTMLElement[] => {
     if (!gridRef.current) {
@@ -139,41 +237,159 @@ export function useGridFocus<T extends HTMLElement = HTMLElement>(
   }, [cellSelector]);
 
   /**
-   * Get the currently focused cell index.
+   * Whether a cell can receive focus.
    */
-  const getCurrentIndex = useCallback((): number => {
-    const cells = getCells();
-    const active = document.activeElement;
-    return cells.findIndex(cell => cell === active || cell.contains(active));
-  }, [getCells]);
+  const cellFocusable = useCallback(
+    (cell: HTMLElement | undefined): boolean => {
+      if (!cell) {
+        return false;
+      }
+      return isCellFocusable ? isCellFocusable(cell) : true;
+    },
+    [isCellFocusable],
+  );
 
   /**
-   * Focus a cell by index, clamping to valid range.
-   * Returns true if focus was successful, false if navigation callback was triggered.
+   * Resolve the element that should actually receive focus for a cell.
    */
-  const focusCellInternal = useCallback(
-    (index: number, currentColumn: number, offset: number) => {
-      const cells = getCells();
-      if (cells.length === 0) {
-        return;
+  const resolveFocusTarget = useCallback(
+    (cell: HTMLElement | undefined): HTMLElement | null => {
+      if (!cell) {
+        return null;
       }
+      return getFocusTarget ? getFocusTarget(cell) : cell;
+    },
+    [getFocusTarget],
+  );
+
+  // --- Roving tabindex ownership (opt-in via `hasRovingTabIndex`) -------------
+
+  /**
+   * Set `tabindex` on an element, but only when it differs (avoids redundant
+   * DOM writes). Uses setAttribute so the value reflects even for elements
+   * (like `<button>`) whose default tabIndex is already 0.
+   */
+  const setTabIndex = useCallback((el: HTMLElement, value: 0 | -1) => {
+    if (el.getAttribute('tabindex') !== String(value)) {
+      el.setAttribute('tabindex', String(value));
+    }
+  }, []);
+
+  /**
+   * The resolved focus targets of all focusable cells, in DOM order. These are
+   * the elements that carry the roving tab stop (a descendant of each cell when
+   * `getFocusTarget` is provided, otherwise the cell itself).
+   */
+  const getFocusTargets = useCallback((): HTMLElement[] => {
+    return getCells()
+      .filter(cell => cellFocusable(cell))
+      .map(cell => resolveFocusTarget(cell))
+      .filter((el): el is HTMLElement => el !== null);
+  }, [getCells, cellFocusable, resolveFocusTarget]);
+
+  /**
+   * Stamp the roving tab stop: exactly one focus target is tabbable (0), the
+   * rest are -1. Prefer keeping the currently-tabbable target if it is still
+   * focusable; otherwise promote the first focusable one (tab-stop repair).
+   */
+  const syncTabStops = useCallback(() => {
+    const targets = getFocusTargets();
+    if (targets.length === 0) {
+      return;
+    }
+    const current = targets.find(el => el.getAttribute('tabindex') === '0');
+    const tabbable = current ?? targets[0];
+    for (const el of targets) {
+      setTabIndex(el, el === tabbable ? 0 : -1);
+    }
+  }, [getFocusTargets, setTabIndex]);
+
+  // Keep the tab stop valid across renders (cells added/removed, focusability
+  // toggled). Runs after every commit but only when roving tabindex is on.
+  useIsomorphicLayoutEffect(() => {
+    if (hasRovingTabIndex) {
+      syncTabStops();
+    }
+  });
 
-      if (index < 0) {
-        onNavigateBefore?.(currentColumn, offset);
+  /**
+   * Move the roving tab stop so `target` becomes the sole tabbable focus
+   * target, then focus it. No-op on tab stops unless roving tabindex is on.
+   */
+  const focusTarget = useCallback(
+    (target: HTMLElement | null) => {
+      if (!target) {
         return;
       }
-      if (index >= cells.length) {
-        onNavigateAfter?.(currentColumn, offset);
-        return;
+      if (hasRovingTabIndex) {
+        for (const el of getFocusTargets()) {
+          setTabIndex(el, el === target ? 0 : -1);
+        }
       }
+      target.focus();
+    },
+    [hasRovingTabIndex, getFocusTargets, setTabIndex],
+  );
 
-      cells[index]?.focus();
+  /**
+   * Focus a cell by resolving and focusing its target, moving the roving tab
+   * stop when enabled.
+   */
+  const focusCellWithStop = useCallback(
+    (cell: HTMLElement | undefined): boolean => {
+      const target = resolveFocusTarget(cell);
+      if (!target) {
+        return false;
+      }
+      focusTarget(target);
+      return true;
     },
-    [getCells, onNavigateBefore, onNavigateAfter],
+    [resolveFocusTarget, focusTarget],
   );
 
   /**
-   * Public focusCell that doesn't trigger navigation callbacks
+   * 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]);
+
+  /**
+   * Get the currently focused cell index within the full cell set.
+   */
+  const getCurrentIndex = useCallback((): number => {
+    const cells = getCells();
+    const active = document.activeElement;
+    return cells.findIndex(cell => cell === active || cell.contains(active));
+  }, [getCells]);
+
+  /**
+   * Find the next focusable cell starting at `startIndex`, moving by `step`.
+   * Returns the index of the focusable cell, or -1 if none exists in range
+   * (i.e. we ran off the start/end of the grid).
+   */
+  const findFocusableInDirection = useCallback(
+    (cells: HTMLElement[], startIndex: number, step: number): number => {
+      let index = startIndex;
+      while (index >= 0 && index < cells.length) {
+        if (cellFocusable(cells[index])) {
+          return index;
+        }
+        index += step;
+      }
+      return -1;
+    },
+    [cellFocusable],
+  );
+
+  /**
+   * Focus a cell by index, clamping to valid range. Skips non-focusable cells
+   * toward the nearest edge. Used by public focus helpers (no navigation
+   * callbacks).
    */
   const focusCell = useCallback(
     (index: number) => {
@@ -182,104 +398,162 @@ export function useGridFocus<T extends HTMLElement = HTMLElement>(
         return;
       }
       const clampedIndex = Math.max(0, Math.min(index, cells.length - 1));
-      cells[clampedIndex]?.focus();
+      // Prefer the requested cell; otherwise search forward, then backward.
+      let target = findFocusableInDirection(cells, clampedIndex, 1);
+      if (target === -1) {
+        target = findFocusableInDirection(cells, clampedIndex, -1);
+      }
+      if (target !== -1) {
+        focusCellWithStop(cells[target]);
+      }
     },
-    [getCells],
+    [getCells, findFocusableInDirection, focusCellWithStop],
   );
 
   /**
-   * Focus the first cell.
+   * Focus the first focusable cell.
    */
   const focusFirst = useCallback(() => {
     const cells = getCells();
-    cells[0]?.focus();
-  }, [getCells]);
+    const index = findFocusableInDirection(cells, 0, 1);
+    if (index !== -1) {
+      focusCellWithStop(cells[index]);
+    }
+  }, [getCells, findFocusableInDirection, focusCellWithStop]);
 
   /**
-   * Focus the last cell.
+   * Focus the last focusable cell.
    */
   const focusLast = useCallback(() => {
     const cells = getCells();
-    cells[cells.length - 1]?.focus();
-  }, [getCells]);
+    const index = findFocusableInDirection(cells, cells.length - 1, -1);
+    if (index !== -1) {
+      focusCellWithStop(cells[index]);
+    }
+  }, [getCells, findFocusableInDirection, focusCellWithStop]);
 
   /**
    * Handle keyboard navigation.
    */
   const handleKeyDown = useCallback(
     (e: React.KeyboardEvent) => {
+      const cells = getCells();
+      if (cells.length === 0) {
+        return;
+      }
+
       const currentIndex = getCurrentIndex();
       if (currentIndex === -1) {
         return;
       }
 
-      const cells = getCells();
       const currentRow = Math.floor(currentIndex / columns);
       const currentCol = currentIndex % columns;
       const totalRows = Math.ceil(cells.length / columns);
 
       let handled = true;
 
-      switch (e.key) {
-        case 'ArrowRight':
-          // Horizontal navigation: offset = 1
-          focusCellInternal(currentIndex + 1, (currentCol + 1) % columns, 1);
+      // In RTL, ArrowLeft/ArrowRight are swapped so horizontal navigation
+      // follows visual direction. Vertical keys (Up/Down) are unaffected.
+      let key = e.key;
+      if (isRtl) {
+        if (key === 'ArrowLeft') {
+          key = 'ArrowRight';
+        } else if (key === 'ArrowRight') {
+          key = 'ArrowLeft';
+        }
+      }
+
+      switch (key) {
+        case 'ArrowRight': {
+          // Move right, skipping non-focusable cells in the same direction.
+          const target = findFocusableInDirection(cells, currentIndex + 1, 1);
+          if (target !== -1) {
+            focusCellWithStop(cells[target]);
+          } else {
+            onNavigateAfter?.((currentCol + 1) % columns, 1);
+          }
           break;
+        }
 
-        case 'ArrowLeft':
-          // Horizontal navigation: offset = 1
-          focusCellInternal(
-            currentIndex - 1,
-            currentCol === 0 ? columns - 1 : currentCol - 1,
-            1,
-          );
+        case 'ArrowLeft': {
+          const target = findFocusableInDirection(cells, currentIndex - 1, -1);
+          if (target !== -1) {
+            focusCellWithStop(cells[target]);
+          } else {
+            onNavigateBefore?.(
+              currentCol === 0 ? columns - 1 : currentCol - 1,
+              1,
+            );
+          }
           break;
+        }
 
-        case 'ArrowDown':
-          // Vertical navigation: offset = columns (7 for calendar)
+        case 'ArrowDown': {
           if (currentRow < totalRows - 1) {
-            const nextIndex = currentIndex + columns;
-            if (nextIndex < cells.length) {
-              focusCellInternal(nextIndex, currentCol, columns);
+            // Move to the same column one row down, then continue downward
+            // (by whole rows) to the next focusable cell in that column.
+            const target = findFocusableInDirection(
+              cells,
+              currentIndex + columns,
+              columns,
+            );
+            if (target !== -1) {
+              focusCellWithStop(cells[target]);
             } else {
-              // Last row might be partial, focus last cell
-              focusCellInternal(cells.length - 1, currentCol, columns);
+              onNavigateAfter?.(currentCol, columns);
             }
           } else {
             onNavigateAfter?.(currentCol, columns);
           }
           break;
+        }
 
-        case 'ArrowUp':
-          // Vertical navigation: offset = columns (7 for calendar)
+        case 'ArrowUp': {
           if (currentRow > 0) {
-            focusCellInternal(currentIndex - columns, currentCol, columns);
+            const target = findFocusableInDirection(
+              cells,
+              currentIndex - columns,
+              -columns,
+            );
+            if (target !== -1) {
+              focusCellWithStop(cells[target]);
+            } else {
+              onNavigateBefore?.(currentCol, columns);
+            }
           } else {
             onNavigateBefore?.(currentCol, columns);
           }
           break;
+        }
 
         case 'Home':
           if (e.ctrlKey || e.metaKey) {
-            // Ctrl+Home: first cell in grid
+            // Ctrl+Home: first focusable cell in grid
             focusFirst();
           } else {
-            // Home: first cell in current row
-            focusCell(currentRow * columns);
+            // Home: first focusable cell in current row (searching rightward)
+            const rowStart = currentRow * columns;
+            const rowEnd = Math.min(rowStart + columns - 1, cells.length - 1);
+            const target = findFocusableInDirection(cells, rowStart, 1);
+            if (target !== -1 && target <= rowEnd) {
+              focusCellWithStop(cells[target]);
+            }
           }
           break;
 
         case 'End':
           if (e.ctrlKey || e.metaKey) {
-            // Ctrl+End: last cell in grid
+            // Ctrl+End: last focusable cell in grid
             focusLast();
           } else {
-            // End: last cell in current row
-            const rowEnd = Math.min(
-              (currentRow + 1) * columns - 1,
-              cells.length - 1,
-            );
-            focusCell(rowEnd);
+            // End: last focusable cell in current row (searching leftward)
+            const rowStart = currentRow * columns;
+            const rowEnd = Math.min(rowStart + columns - 1, cells.length - 1);
+            const target = findFocusableInDirection(cells, rowEnd, -1);
+            if (target !== -1 && target >= rowStart) {
+              focusCellWithStop(cells[target]);
+            }
           }
           break;
 
@@ -302,12 +576,13 @@ export function useGridFocus<T extends HTMLElement = HTMLElement>(
     },
     [
       columns,
-      focusCell,
-      focusCellInternal,
+      findFocusableInDirection,
+      focusCellWithStop,
       focusFirst,
       focusLast,
       getCells,
       getCurrentIndex,
+      isRtl,
       onNavigateAfter,
       onNavigateBefore,
       onPageDown,
@@ -318,6 +593,7 @@ export function useGridFocus<T extends HTMLElement = HTMLElement>(
   return {
     gridRef,
     handleKeyDown,
+    handleFocus,
     focusCell,
     focusFirst,
     focusLast,

package/src/hooks/useKeyboardHint.doc.mjs

@@ -0,0 +1,101 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../docs-types').HookDoc} */
+export const docs = {
+  name: 'useKeyboardHint',
+  displayName: 'useKeyboardHint',
+  keywords: ['keyboard', 'hint', 'arrow', 'navigation', 'roving', 'tabindex', 'focus', 'discoverability', 'toolbar', 'tabs', 'segmented', 'affordance', 'a11y'],
+  params: [
+    {
+      name: 'options',
+      type: 'UseKeyboardHintOptions',
+      description: 'Configuration object for the keyboard hint.',
+      required: false,
+    },
+    {
+      name: 'options.orientation',
+      type: "'horizontal' | 'vertical' | 'both'",
+      description: 'Which arrow-key axis the composite navigates, controlling which arrow icons the hint shows (← → for horizontal, ↑ ↓ for vertical, all four for both).',
+      default: "'horizontal'",
+      required: false,
+    },
+    {
+      name: 'options.dismissAfterMs',
+      type: 'number',
+      description: 'Milliseconds before the hint auto-dismisses after appearing.',
+      default: '3000',
+      required: false,
+    },
+    {
+      name: 'options.isEnabled',
+      type: 'boolean',
+      description: 'Whether the hint is enabled. Set to false to suppress it for a specific instance (e.g. a disabled or read-only widget).',
+      default: 'true',
+      required: false,
+    },
+  ],
+  returns: [
+    {
+      name: 'hintElement',
+      type: 'ReactNode',
+      description: 'The popover hint element to render inside the composite container (as the last child). Portals to the top layer via popover="manual", renders arrow keys with Kbd, and manages its own visibility — render it unconditionally.',
+    },
+    {
+      name: 'onFocus',
+      type: '(e: React.FocusEvent) => void',
+      description: 'Attach to the container onFocus. Shows the hint on the first keyboard-focus (:focus-visible) entry from outside the composite.',
+    },
+    {
+      name: 'onBlur',
+      type: '(e: React.FocusEvent) => void',
+      description: 'Attach to the container onBlur. Hides the hint when focus leaves the composite entirely, and re-anchors when focus moves within.',
+    },
+    {
+      name: 'onKeyDown',
+      type: '(e: React.KeyboardEvent) => void',
+      description: 'Attach to the container onKeyDown. Dismisses the hint on the first arrow press (the user has discovered the interaction). Never prevents default or stops propagation.',
+    },
+  ],
+  usage: {
+    description:
+      'Shows an ephemeral "← → to navigate" hint anchored to the focused item the first time a roving-tabindex composite (Toolbar, TabList, SegmentedControl, etc.) receives keyboard focus. It teaches sighted keyboard users that arrow keys move within the group. The hint renders arrow keys with Kbd in the top layer (popover="manual") and is CSS-anchor-positioned to the focused element, so overflow containers never clip it. It auto-dismisses on the first arrow press, on timeout, or on blur, and does not re-show for that instance. Toolbar, TabList, and SegmentedControl wire this in automatically — reach for the hook directly only when building a custom roving-tabindex widget.',
+    bestPractices: [
+      { guidance: true, description: 'Compose the returned onFocus/onKeyDown with your existing focus handlers rather than replacing them — call onKeyDown first (it only dismisses, never prevents), then your navigation handler.' },
+      { guidance: true, description: 'Render hintElement as the last child of the composite container; it is position:fixed in the top layer and aria-hidden, so it never affects layout or the accessibility tree.' },
+      { guidance: true, description: 'Match orientation to the arrow keys your widget actually responds to so the hint shows the correct icons.' },
+      { guidance: false, description: 'Use for single controls or widgets without roving-tabindex navigation — the hint only makes sense where arrows move focus within a group.' },
+    ],
+  },
+  relatedComponents: ['Toolbar', 'TabList', 'SegmentedControl'],
+  relatedHooks: ['useListFocus', 'useGridFocus', 'useTreeFocus'],
+  importPath: '@astryxdesign/core/hooks',
+  category: 'focus',
+};
+
+/** @type {import('../docs-types').HookTranslationDoc} */
+export const docsDense = {
+  description:
+    'Ephemeral "← → to navigate" hint anchored to the focused item on first keyboard focus of a roving-tabindex composite (Toolbar/TabList/SegmentedControl). Teaches sighted keyboard users that arrows move within the group. Kbd-rendered arrows in a top-layer popover="manual", CSS-anchor-positioned (never clipped by overflow), aria-hidden. Auto-dismisses on first arrow press, timeout, or blur; never re-shows for that instance.',
+  paramDescriptions: {
+    options: 'config for the keyboard hint.',
+    'options.orientation': "arrow axis: 'horizontal' (← →), 'vertical' (↑ ↓), 'both' (all four). Controls shown icons.",
+    'options.dismissAfterMs': 'ms before auto-dismiss after appearing.',
+    'options.isEnabled': 'whether the hint is enabled; false suppresses it (e.g. disabled/read-only widget).',
+  },
+  returnDescriptions: {
+    hintElement: 'popover hint to render as last child of the container. Kbd-rendered arrows, top-layer, self-managing — render unconditionally.',
+    onFocus: 'container onFocus: shows hint on first :focus-visible entry from outside.',
+    onBlur: 'container onBlur: hides on leaving the composite; re-anchors on internal moves.',
+    onKeyDown: 'container onKeyDown: dismisses on first arrow press. Never prevents default.',
+  },
+  usage: {
+    description:
+      'Ephemeral "← → to navigate" hint on first keyboard focus of a roving-tabindex composite. Top-layer anchored popover, aria-hidden. Auto-dismisses on first arrow press, timeout, or blur; no re-show. Toolbar/TabList/SegmentedControl wire it in automatically.',
+    bestPractices: [
+      { guidance: true, description: 'Compose returned onFocus/onKeyDown with existing handlers (call onKeyDown first — it only dismisses).' },
+      { guidance: true, description: 'Render hintElement as last child; top-layer + aria-hidden, no layout/a11y impact.' },
+      { guidance: true, description: 'Match orientation to the arrows the widget responds to.' },
+      { guidance: false, description: 'Use for single controls / non-roving widgets.' },
+    ],
+  },
+};