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

package/dist/hooks/useGridFocus.d.ts

@@ -8,10 +8,35 @@ 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.
@@ -34,6 +59,32 @@ 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;
 }
 /**
  * Return type for useGridFocus hook
@@ -47,6 +98,12 @@ export interface UseGridFocusReturn<T extends HTMLElement = HTMLElement> {
      * Key down handler to attach to the grid 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 a specific cell by index.
      */
@@ -71,6 +128,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({
@@ -83,6 +152,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 declare function useGridFocus<T extends HTMLElement = HTMLElement>(options: UseGridFocusOptions): UseGridFocusReturn<T>;
 //# sourceMappingURL=useGridFocus.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"useGridFocus.d.ts","sourceRoot":"","sources":["../../src/hooks/useGridFocus.ts"],"names":[],"mappings":"AAiBA;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC;;;OAGG;IACH,OAAO,EAAE,MAAM,CAAC;IAEhB;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB;;;;;OAKG;IACH,gBAAgB,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;IAE5D;;;;;OAKG;IACH,eAAe,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;IAE3D;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,IAAI,CAAC;IAEtB;;OAEG;IACH,UAAU,CAAC,EAAE,MAAM,IAAI,CAAC;CACzB;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB,CAAC,CAAC,SAAS,WAAW,GAAG,WAAW;IACrE;;OAEG;IACH,OAAO,EAAE,KAAK,CAAC,SAAS,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;IAEnC;;OAEG;IACH,aAAa,EAAE,CAAC,CAAC,EAAE,KAAK,CAAC,aAAa,KAAK,IAAI,CAAC;IAEhD;;OAEG;IACH,SAAS,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IAEnC;;OAEG;IACH,UAAU,EAAE,MAAM,IAAI,CAAC;IAEvB;;OAEG;IACH,SAAS,EAAE,MAAM,IAAI,CAAC;CACvB;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,YAAY,CAAC,CAAC,SAAS,WAAW,GAAG,WAAW,EAC9D,OAAO,EAAE,mBAAmB,GAC3B,kBAAkB,CAAC,CAAC,CAAC,CAgNvB"}
+{"version":3,"file":"useGridFocus.d.ts","sourceRoot":"","sources":["../../src/hooks/useGridFocus.ts"],"names":[],"mappings":"AAkBA;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC;;;OAGG;IACH,OAAO,EAAE,MAAM,CAAC;IAEhB;;;;;;;;;;;;OAYG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB;;;;;;OAMG;IACH,eAAe,CAAC,EAAE,CAAC,IAAI,EAAE,WAAW,KAAK,OAAO,CAAC;IAEjD;;;;;;OAMG;IACH,cAAc,CAAC,EAAE,CAAC,IAAI,EAAE,WAAW,KAAK,WAAW,GAAG,IAAI,CAAC;IAE3D;;;;;OAKG;IACH,gBAAgB,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;IAE5D;;;;;OAKG;IACH,eAAe,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;IAE3D;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,IAAI,CAAC;IAEtB;;OAEG;IACH,UAAU,CAAC,EAAE,MAAM,IAAI,CAAC;IAExB;;;;OAIG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;IAEhB;;;;;;;;;;;;;;;;;;OAkBG;IACH,iBAAiB,CAAC,EAAE,OAAO,CAAC;CAC7B;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB,CAAC,CAAC,SAAS,WAAW,GAAG,WAAW;IACrE;;OAEG;IACH,OAAO,EAAE,KAAK,CAAC,SAAS,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;IAEnC;;OAEG;IACH,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;;OAEG;IACH,SAAS,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IAEnC;;OAEG;IACH,UAAU,EAAE,MAAM,IAAI,CAAC;IAEvB;;OAEG;IACH,SAAS,EAAE,MAAM,IAAI,CAAC;CACvB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AACH,wBAAgB,YAAY,CAAC,CAAC,SAAS,WAAW,GAAG,WAAW,EAC9D,OAAO,EAAE,mBAAmB,GAC3B,kBAAkB,CAAC,CAAC,CAAC,CAuYvB"}

package/dist/hooks/useGridFocus.js

@@ -4,15 +4,16 @@
 
 /**
  * @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.js";
 
 /**
  * Configuration for grid focus behavior
@@ -33,6 +34,18 @@ import { useCallback, useRef } from 'react';
  * - 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({
@@ -45,20 +58,43 @@ import { useCallback, useRef } from 'react';
  *   {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(options) {
   const {
     columns,
     cellSelector = 'button:not([disabled]), [tabindex]:not([tabindex="-1"])',
+    isCellFocusable,
+    getFocusTarget,
     onNavigateBefore,
     onNavigateAfter,
     onPageUp,
-    onPageDown
+    onPageDown,
+    isRtl = false,
+    hasRovingTabIndex = false
   } = options;
   const gridRef = useRef(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(() => {
     if (!gridRef.current) {
@@ -68,7 +104,114 @@ export function useGridFocus(options) {
   }, [cellSelector]);
 
   /**
-   * Get the currently focused cell index.
+   * Whether a cell can receive focus.
+   */
+  const cellFocusable = useCallback(cell => {
+    if (!cell) {
+      return false;
+    }
+    return isCellFocusable ? isCellFocusable(cell) : true;
+  }, [isCellFocusable]);
+
+  /**
+   * Resolve the element that should actually receive focus for a cell.
+   */
+  const resolveFocusTarget = useCallback(cell => {
+    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, value) => {
+    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(() => {
+    return getCells().filter(cell => cellFocusable(cell)).map(cell => resolveFocusTarget(cell)).filter(el => 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();
+    }
+  });
+
+  /**
+   * 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 => {
+    if (!target) {
+      return;
+    }
+    if (hasRovingTabIndex) {
+      for (const el of getFocusTargets()) {
+        setTabIndex(el, el === target ? 0 : -1);
+      }
+    }
+    target.focus();
+  }, [hasRovingTabIndex, getFocusTargets, setTabIndex]);
+
+  /**
+   * Focus a cell by resolving and focusing its target, moving the roving tab
+   * stop when enabled.
+   */
+  const focusCellWithStop = useCallback(cell => {
+    const target = resolveFocusTarget(cell);
+    if (!target) {
+      return false;
+    }
+    focusTarget(target);
+    return true;
+  }, [resolveFocusTarget, focusTarget]);
+
+  /**
+   * 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(() => {
     const cells = getCells();
@@ -77,27 +220,25 @@ export function useGridFocus(options) {
   }, [getCells]);
 
   /**
-   * Focus a cell by index, clamping to valid range.
-   * Returns true if focus was successful, false if navigation callback was triggered.
+   * 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 focusCellInternal = useCallback((index, currentColumn, offset) => {
-    const cells = getCells();
-    if (cells.length === 0) {
-      return;
-    }
-    if (index < 0) {
-      onNavigateBefore?.(currentColumn, offset);
-      return;
+  const findFocusableInDirection = useCallback((cells, startIndex, step) => {
+    let index = startIndex;
+    while (index >= 0 && index < cells.length) {
+      if (cellFocusable(cells[index])) {
+        return index;
+      }
+      index += step;
     }
-    if (index >= cells.length) {
-      onNavigateAfter?.(currentColumn, offset);
-      return;
-    }
-    cells[index]?.focus();
-  }, [getCells, onNavigateBefore, onNavigateAfter]);
+    return -1;
+  }, [cellFocusable]);
 
   /**
-   * Public focusCell that doesn't trigger navigation callbacks
+   * 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 => {
     const cells = getCells();
@@ -105,86 +246,143 @@ export function useGridFocus(options) {
       return;
     }
     const clampedIndex = Math.max(0, Math.min(index, cells.length - 1));
-    cells[clampedIndex]?.focus();
-  }, [getCells]);
+    // 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, 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 => {
+    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) {
+
+    // 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':
-        // Horizontal navigation: offset = 1
-        focusCellInternal(currentIndex + 1, (currentCol + 1) % columns, 1);
-        break;
+        {
+          // 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);
-        break;
+        {
+          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)
-        if (currentRow < totalRows - 1) {
-          const nextIndex = currentIndex + columns;
-          if (nextIndex < cells.length) {
-            focusCellInternal(nextIndex, currentCol, columns);
+        {
+          if (currentRow < totalRows - 1) {
+            // 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 {
+              onNavigateAfter?.(currentCol, columns);
+            }
           } else {
-            // Last row might be partial, focus last cell
-            focusCellInternal(cells.length - 1, currentCol, columns);
+            onNavigateAfter?.(currentCol, columns);
           }
-        } else {
-          onNavigateAfter?.(currentCol, columns);
+          break;
         }
-        break;
       case 'ArrowUp':
-        // Vertical navigation: offset = columns (7 for calendar)
-        if (currentRow > 0) {
-          focusCellInternal(currentIndex - columns, currentCol, columns);
-        } else {
-          onNavigateBefore?.(currentCol, columns);
+        {
+          if (currentRow > 0) {
+            const target = findFocusableInDirection(cells, currentIndex - columns, -columns);
+            if (target !== -1) {
+              focusCellWithStop(cells[target]);
+            } else {
+              onNavigateBefore?.(currentCol, columns);
+            }
+          } else {
+            onNavigateBefore?.(currentCol, columns);
+          }
+          break;
         }
-        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;
       case 'PageUp':
@@ -200,10 +398,11 @@ export function useGridFocus(options) {
       e.preventDefault();
       e.stopPropagation();
     }
-  }, [columns, focusCell, focusCellInternal, focusFirst, focusLast, getCells, getCurrentIndex, onNavigateAfter, onNavigateBefore, onPageDown, onPageUp]);
+  }, [columns, findFocusableInDirection, focusCellWithStop, focusFirst, focusLast, getCells, getCurrentIndex, isRtl, onNavigateAfter, onNavigateBefore, onPageDown, onPageUp]);
   return {
     gridRef,
     handleKeyDown,
+    handleFocus,
     focusCell,
     focusFirst,
     focusLast

package/dist/hooks/useKeyboardHint.d.ts

@@ -0,0 +1,82 @@
+/**
+ * @file useKeyboardHint.tsx
+ * @input Uses React, StyleX, Kbd, useLayer
+ * @output Exports useKeyboardHint hook — ephemeral arrow-key navigation hint
+ * @position Core hook; shows sighted keyboard users how to navigate composite
+ *   widgets that use roving tabindex (single Tab stop, arrows inside)
+ *
+ * SYNC: When modified, update:
+ * - /packages/core/src/hooks/index.ts
+ * - /packages/core/src/hooks/useKeyboardHint.doc.mjs
+ * - /apps/storybook/stories/useKeyboardHint.stories.tsx
+ * - /packages/cli/templates/blocks/components/Hooks/useKeyboardHintHookUsage.tsx
+ */
+import React, { type ReactNode } from 'react';
+export type KeyboardHintOrientation = 'horizontal' | 'vertical' | 'both';
+export interface UseKeyboardHintOptions {
+    /**
+     * Orientation of the arrow-key navigation. Controls which arrow icons are
+     * shown in the hint badge.
+     * - `'horizontal'` → ← →
+     * - `'vertical'` → ↑ ↓
+     * - `'both'` → ← → ↑ ↓
+     * @default 'horizontal'
+     */
+    orientation?: KeyboardHintOrientation;
+    /**
+     * Milliseconds before the hint auto-dismisses after appearing.
+     * @default 3000
+     */
+    dismissAfterMs?: number;
+    /**
+     * Whether the hint is enabled. Set to false to disable for a specific
+     * instance (e.g. when the widget is read-only or the user has dismissed
+     * globally).
+     * @default true
+     */
+    isEnabled?: boolean;
+}
+export interface UseKeyboardHintReturn {
+    /**
+     * The popover hint element to render inside your component tree (portals to
+     * top layer via `popover="manual"`). Render unconditionally — it manages its
+     * own visibility.
+     */
+    hintElement: ReactNode;
+    /**
+     * Attach to the composite container's `onFocus`. Shows the hint on the first
+     * keyboard-focus (`:focus-visible`) entry from outside.
+     */
+    onFocus: (e: React.FocusEvent) => void;
+    /**
+     * Attach to the composite container's `onBlur`. Hides the hint when focus
+     * leaves the composite entirely.
+     */
+    onBlur: (e: React.FocusEvent) => void;
+    /**
+     * Attach to the composite container's `onKeyDown`. Dismisses the hint on the
+     * first arrow press (the user discovered the interaction).
+     */
+    onKeyDown: (e: React.KeyboardEvent) => void;
+}
+/**
+ * Shows an ephemeral visual hint ("← → to navigate") anchored to the focused
+ * item when a composite widget first receives keyboard focus. Teaches sighted
+ * keyboard users that arrows navigate within the group.
+ *
+ * The hint renders in the top layer (popover="manual") and is CSS-anchor-
+ * positioned to the currently focused element, so it is never clipped by
+ * overflow containers. It auto-dismisses on first arrow press, timeout, or
+ * blur, and does not re-show for that instance.
+ *
+ * @example
+ * ```
+ * const hint = useKeyboardHint({orientation: 'horizontal'});
+ * <div role="toolbar" onFocus={hint.onFocus} onBlur={hint.onBlur} onKeyDown={hint.onKeyDown}>
+ *   {children}
+ *   {hint.hintElement}
+ * </div>
+ * ```
+ */
+export declare function useKeyboardHint(options?: UseKeyboardHintOptions): UseKeyboardHintReturn;
+//# sourceMappingURL=useKeyboardHint.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"useKeyboardHint.d.ts","sourceRoot":"","sources":["../../src/hooks/useKeyboardHint.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,EAAiC,KAAK,SAAS,EAAC,MAAM,OAAO,CAAC;AAgB5E,MAAM,MAAM,uBAAuB,GAAG,YAAY,GAAG,UAAU,GAAG,MAAM,CAAC;AAEzE,MAAM,WAAW,sBAAsB;IACrC;;;;;;;OAOG;IACH,WAAW,CAAC,EAAE,uBAAuB,CAAC;IAEtC;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IAExB;;;;;OAKG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED,MAAM,WAAW,qBAAqB;IACpC;;;;OAIG;IACH,WAAW,EAAE,SAAS,CAAC;IAEvB;;;OAGG;IACH,OAAO,EAAE,CAAC,CAAC,EAAE,KAAK,CAAC,UAAU,KAAK,IAAI,CAAC;IAEvC;;;OAGG;IACH,MAAM,EAAE,CAAC,CAAC,EAAE,KAAK,CAAC,UAAU,KAAK,IAAI,CAAC;IAEtC;;;OAGG;IACH,SAAS,EAAE,CAAC,CAAC,EAAE,KAAK,CAAC,aAAa,KAAK,IAAI,CAAC;CAC7C;AAkED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,eAAe,CAC7B,OAAO,GAAE,sBAA2B,GACnC,qBAAqB,CA6JvB"}