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

package/dist/hooks/index.d.ts

@@ -17,6 +17,8 @@ export type { UseListFocusOptions, UseListFocusReturn, ListFocusOrientation, } f
 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';
 export { useOverflow } from './useOverflow';
@@ -30,12 +32,12 @@ export { useStreamingText } from './useStreamingText';
 export type { StreamingTextSpeed, UseStreamingTextOptions, } from './useStreamingText';
 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, } from './useClickableContainer';
 export { useInputContainer } from './useInputContainer';
 export type { UseInputContainerOptions } from './useInputContainer';
 export { useInteractiveRole } from './useInteractiveRole';
 export type { InteractiveRole, UseInteractiveRoleOptions, } from './useInteractiveRole';
 export { useLongPress } from './useLongPress';
-export type { UseLongPressOptions, UseLongPressHandlers, } from './useLongPress';
+export type { UseLongPressOptions, UseLongPressHandlers } from './useLongPress';
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/hooks/index.ts"],"names":[],"mappings":"AAIA;;;;;;;GAOG;AAEH,OAAO,EAAC,YAAY,EAAC,MAAM,gBAAgB,CAAC;AAC5C,YAAY,EAAC,mBAAmB,EAAE,kBAAkB,EAAC,MAAM,gBAAgB,CAAC;AAE5E,OAAO,EAAC,WAAW,EAAC,MAAM,eAAe,CAAC;AAC1C,YAAY,EAAC,UAAU,EAAE,kBAAkB,EAAC,MAAM,eAAe,CAAC;AAElE,OAAO,EAAC,YAAY,EAAC,MAAM,gBAAgB,CAAC;AAC5C,YAAY,EAAC,mBAAmB,EAAE,kBAAkB,EAAC,MAAM,gBAAgB,CAAC;AAE5E,OAAO,EAAC,YAAY,EAAC,MAAM,gBAAgB,CAAC;AAC5C,YAAY,EACV,mBAAmB,EACnB,kBAAkB,EAClB,oBAAoB,GACrB,MAAM,gBAAgB,CAAC;AAExB,OAAO,EAAC,YAAY,EAAC,MAAM,gBAAgB,CAAC;AAC5C,YAAY,EAAC,mBAAmB,EAAE,kBAAkB,EAAC,MAAM,gBAAgB,CAAC;AAE5E,OAAO,EAAC,YAAY,EAAC,MAAM,gBAAgB,CAAC;AAC5C,YAAY,EAAC,mBAAmB,EAAE,kBAAkB,EAAC,MAAM,gBAAgB,CAAC;AAE5E,OAAO,EAAC,aAAa,EAAC,MAAM,iBAAiB,CAAC;AAE9C,OAAO,EAAC,WAAW,EAAC,MAAM,eAAe,CAAC;AAC1C,YAAY,EAAC,kBAAkB,EAAE,iBAAiB,EAAC,MAAM,eAAe,CAAC;AAEzE,OAAO,EAAC,iBAAiB,EAAC,MAAM,qBAAqB,CAAC;AACtD,YAAY,EAAC,mBAAmB,EAAC,MAAM,qBAAqB,CAAC;AAE7D,OAAO,EAAC,aAAa,EAAC,MAAM,iBAAiB,CAAC;AAE9C,OAAO,EAAC,iBAAiB,EAAC,MAAM,qBAAqB,CAAC;AACtD,YAAY,EAAC,oBAAoB,EAAC,MAAM,qBAAqB,CAAC;AAE9D,OAAO,EAAC,gBAAgB,EAAC,MAAM,oBAAoB,CAAC;AACpD,YAAY,EACV,kBAAkB,EAClB,uBAAuB,GACxB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAC,YAAY,EAAC,MAAM,gBAAgB,CAAC;AAC5C,YAAY,EAAC,iBAAiB,EAAE,mBAAmB,EAAC,MAAM,gBAAgB,CAAC;AAE3E,OAAO,EAAC,qBAAqB,EAAE,qBAAqB,EAAC,MAAM,yBAAyB,CAAC;AACrF,YAAY,EACV,4BAA4B,EAC5B,wBAAwB,GACzB,MAAM,yBAAyB,CAAC;AAEjC,OAAO,EAAC,iBAAiB,EAAC,MAAM,qBAAqB,CAAC;AACtD,YAAY,EAAC,wBAAwB,EAAC,MAAM,qBAAqB,CAAC;AAElE,OAAO,EAAC,kBAAkB,EAAC,MAAM,sBAAsB,CAAC;AACxD,YAAY,EACV,eAAe,EACf,yBAAyB,GAC1B,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EAAC,YAAY,EAAC,MAAM,gBAAgB,CAAC;AAC5C,YAAY,EACV,mBAAmB,EACnB,oBAAoB,GACrB,MAAM,gBAAgB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/hooks/index.ts"],"names":[],"mappings":"AAIA;;;;;;;GAOG;AAEH,OAAO,EAAC,YAAY,EAAC,MAAM,gBAAgB,CAAC;AAC5C,YAAY,EAAC,mBAAmB,EAAE,kBAAkB,EAAC,MAAM,gBAAgB,CAAC;AAE5E,OAAO,EAAC,WAAW,EAAC,MAAM,eAAe,CAAC;AAC1C,YAAY,EAAC,UAAU,EAAE,kBAAkB,EAAC,MAAM,eAAe,CAAC;AAElE,OAAO,EAAC,YAAY,EAAC,MAAM,gBAAgB,CAAC;AAC5C,YAAY,EAAC,mBAAmB,EAAE,kBAAkB,EAAC,MAAM,gBAAgB,CAAC;AAE5E,OAAO,EAAC,YAAY,EAAC,MAAM,gBAAgB,CAAC;AAC5C,YAAY,EACV,mBAAmB,EACnB,kBAAkB,EAClB,oBAAoB,GACrB,MAAM,gBAAgB,CAAC;AAExB,OAAO,EAAC,YAAY,EAAC,MAAM,gBAAgB,CAAC;AAC5C,YAAY,EAAC,mBAAmB,EAAE,kBAAkB,EAAC,MAAM,gBAAgB,CAAC;AAE5E,OAAO,EAAC,YAAY,EAAC,MAAM,gBAAgB,CAAC;AAE5C,OAAO,EAAC,eAAe,EAAC,MAAM,mBAAmB,CAAC;AAClD,YAAY,EACV,sBAAsB,EACtB,qBAAqB,EACrB,uBAAuB,GACxB,MAAM,mBAAmB,CAAC;AAC3B,YAAY,EAAC,mBAAmB,EAAE,kBAAkB,EAAC,MAAM,gBAAgB,CAAC;AAE5E,OAAO,EAAC,aAAa,EAAC,MAAM,iBAAiB,CAAC;AAE9C,OAAO,EAAC,WAAW,EAAC,MAAM,eAAe,CAAC;AAC1C,YAAY,EAAC,kBAAkB,EAAE,iBAAiB,EAAC,MAAM,eAAe,CAAC;AAEzE,OAAO,EAAC,iBAAiB,EAAC,MAAM,qBAAqB,CAAC;AACtD,YAAY,EAAC,mBAAmB,EAAC,MAAM,qBAAqB,CAAC;AAE7D,OAAO,EAAC,aAAa,EAAC,MAAM,iBAAiB,CAAC;AAE9C,OAAO,EAAC,iBAAiB,EAAC,MAAM,qBAAqB,CAAC;AACtD,YAAY,EAAC,oBAAoB,EAAC,MAAM,qBAAqB,CAAC;AAE9D,OAAO,EAAC,gBAAgB,EAAC,MAAM,oBAAoB,CAAC;AACpD,YAAY,EACV,kBAAkB,EAClB,uBAAuB,GACxB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAC,YAAY,EAAC,MAAM,gBAAgB,CAAC;AAC5C,YAAY,EAAC,iBAAiB,EAAE,mBAAmB,EAAC,MAAM,gBAAgB,CAAC;AAE3E,OAAO,EACL,qBAAqB,EACrB,qBAAqB,GACtB,MAAM,yBAAyB,CAAC;AACjC,YAAY,EACV,4BAA4B,EAC5B,wBAAwB,GACzB,MAAM,yBAAyB,CAAC;AAEjC,OAAO,EAAC,iBAAiB,EAAC,MAAM,qBAAqB,CAAC;AACtD,YAAY,EAAC,wBAAwB,EAAC,MAAM,qBAAqB,CAAC;AAElE,OAAO,EAAC,kBAAkB,EAAC,MAAM,sBAAsB,CAAC;AACxD,YAAY,EACV,eAAe,EACf,yBAAyB,GAC1B,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EAAC,YAAY,EAAC,MAAM,gBAAgB,CAAC;AAC5C,YAAY,EAAC,mBAAmB,EAAE,oBAAoB,EAAC,MAAM,gBAAgB,CAAC"}

package/dist/hooks/index.js

@@ -16,6 +16,7 @@ export { useGridFocus } from "./useGridFocus.js";
 export { useListFocus } from "./useListFocus.js";
 export { useTreeFocus } from "./useTreeFocus.js";
 export { useTypeahead } from "./useTypeahead.js";
+export { useKeyboardHint } from "./useKeyboardHint.js";
 export { useMediaQuery } from "./useMediaQuery.js";
 export { useOverflow } from "./useOverflow.js";
 export { useScrollOverflow } from "./useScrollOverflow.js";

package/dist/hooks/useGridFocus.d.ts

@@ -59,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
@@ -72,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.
      */
@@ -102,6 +134,12 @@ export interface UseGridFocusReturn<T extends HTMLElement = HTMLElement> {
  * 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({
@@ -114,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;;;;;;;;;;;;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;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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,YAAY,CAAC,CAAC,SAAS,WAAW,GAAG,WAAW,EAC9D,OAAO,EAAE,mBAAmB,GAC3B,kBAAkB,CAAC,CAAC,CAAC,CAuSvB"}
+{"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
@@ -39,6 +40,12 @@ import { useCallback, useRef } from 'react';
  * 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({
@@ -51,6 +58,24 @@ 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 {
@@ -61,7 +86,9 @@ export function useGridFocus(options) {
     onNavigateBefore,
     onNavigateAfter,
     onPageUp,
-    onPageDown
+    onPageDown,
+    isRtl = false,
+    hasRovingTabIndex = false
   } = options;
   const gridRef = useRef(null);
 
@@ -96,17 +123,92 @@ export function useGridFocus(options) {
     return getFocusTarget ? getFocusTarget(cell) : cell;
   }, [getFocusTarget]);
 
+  // --- Roving tabindex ownership (opt-in via `hasRovingTabIndex`) -------------
+
   /**
-   * Focus a cell (resolving to its focus target).
+   * 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 focusCellElement = useCallback(cell => {
+  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) {
-      target.focus();
-      return true;
+    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();
     }
-    return false;
-  }, [resolveFocusTarget]);
+  }, [hasRovingTabIndex, syncTabStops]);
 
   /**
    * Get the currently focused cell index within the full cell set.
@@ -150,9 +252,9 @@ export function useGridFocus(options) {
       target = findFocusableInDirection(cells, clampedIndex, -1);
     }
     if (target !== -1) {
-      focusCellElement(cells[target]);
+      focusCellWithStop(cells[target]);
     }
-  }, [getCells, findFocusableInDirection, focusCellElement]);
+  }, [getCells, findFocusableInDirection, focusCellWithStop]);
 
   /**
    * Focus the first focusable cell.
@@ -161,9 +263,9 @@ export function useGridFocus(options) {
     const cells = getCells();
     const index = findFocusableInDirection(cells, 0, 1);
     if (index !== -1) {
-      focusCellElement(cells[index]);
+      focusCellWithStop(cells[index]);
     }
-  }, [getCells, findFocusableInDirection, focusCellElement]);
+  }, [getCells, findFocusableInDirection, focusCellWithStop]);
 
   /**
    * Focus the last focusable cell.
@@ -172,9 +274,9 @@ export function useGridFocus(options) {
     const cells = getCells();
     const index = findFocusableInDirection(cells, cells.length - 1, -1);
     if (index !== -1) {
-      focusCellElement(cells[index]);
+      focusCellWithStop(cells[index]);
     }
-  }, [getCells, findFocusableInDirection, focusCellElement]);
+  }, [getCells, findFocusableInDirection, focusCellWithStop]);
 
   /**
    * Handle keyboard navigation.
@@ -192,13 +294,24 @@ export function useGridFocus(options) {
     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':
         {
           // Move right, skipping non-focusable cells in the same direction.
           const target = findFocusableInDirection(cells, currentIndex + 1, 1);
           if (target !== -1) {
-            focusCellElement(cells[target]);
+            focusCellWithStop(cells[target]);
           } else {
             onNavigateAfter?.((currentCol + 1) % columns, 1);
           }
@@ -208,7 +321,7 @@ export function useGridFocus(options) {
         {
           const target = findFocusableInDirection(cells, currentIndex - 1, -1);
           if (target !== -1) {
-            focusCellElement(cells[target]);
+            focusCellWithStop(cells[target]);
           } else {
             onNavigateBefore?.(currentCol === 0 ? columns - 1 : currentCol - 1, 1);
           }
@@ -221,7 +334,7 @@ export function useGridFocus(options) {
             // (by whole rows) to the next focusable cell in that column.
             const target = findFocusableInDirection(cells, currentIndex + columns, columns);
             if (target !== -1) {
-              focusCellElement(cells[target]);
+              focusCellWithStop(cells[target]);
             } else {
               onNavigateAfter?.(currentCol, columns);
             }
@@ -235,7 +348,7 @@ export function useGridFocus(options) {
           if (currentRow > 0) {
             const target = findFocusableInDirection(cells, currentIndex - columns, -columns);
             if (target !== -1) {
-              focusCellElement(cells[target]);
+              focusCellWithStop(cells[target]);
             } else {
               onNavigateBefore?.(currentCol, columns);
             }
@@ -254,7 +367,7 @@ export function useGridFocus(options) {
           const rowEnd = Math.min(rowStart + columns - 1, cells.length - 1);
           const target = findFocusableInDirection(cells, rowStart, 1);
           if (target !== -1 && target <= rowEnd) {
-            focusCellElement(cells[target]);
+            focusCellWithStop(cells[target]);
           }
         }
         break;
@@ -268,7 +381,7 @@ export function useGridFocus(options) {
           const rowEnd = Math.min(rowStart + columns - 1, cells.length - 1);
           const target = findFocusableInDirection(cells, rowEnd, -1);
           if (target !== -1 && target >= rowStart) {
-            focusCellElement(cells[target]);
+            focusCellWithStop(cells[target]);
           }
         }
         break;
@@ -285,10 +398,11 @@ export function useGridFocus(options) {
       e.preventDefault();
       e.stopPropagation();
     }
-  }, [columns, findFocusableInDirection, focusCellElement, 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"}