@astryxdesign/core 0.1.9 → 0.2.0-canary.0e01213

package/src/hooks/useAnnounce.ts

@@ -7,7 +7,9 @@
  * @input Uses React useCallback; DOM APIs for a singleton live-region pair
  * @output Exports useAnnounce hook and AnnouncePoliteness type
  * @position Core a11y hook; provides imperative screen-reader announcements
- *   via persistently-mounted polite/assertive live regions
+ *   via persistently-mounted polite/assertive live regions; regions are
+ *   auto-cleared shortly after announcing so stale status text does not
+ *   linger in the accessibility tree
  *
  * SYNC: When modified, update:
  * - /packages/core/src/hooks/index.ts
@@ -47,6 +49,40 @@ interface LiveRegions {
   assertive: HTMLElement;
 }
 
+/**
+ * How long an announcement stays in its region before being auto-cleared.
+ * Long enough for screen readers to pick the message up and finish reading
+ * it; clearing afterwards keeps stale status text out of the accessibility
+ * tree for users who browse the DOM later. Each announce resets the timer.
+ */
+const CLEAR_DELAY_MS = 2000;
+
+const clearTimers: {
+  [K in AnnouncePoliteness]: ReturnType<typeof setTimeout> | null;
+} = {
+  polite: null,
+  assertive: null,
+};
+
+function cancelScheduledClear(politeness: AnnouncePoliteness): void {
+  const timer = clearTimers[politeness];
+  if (timer != null) {
+    clearTimeout(timer);
+    clearTimers[politeness] = null;
+  }
+}
+
+function scheduleClear(
+  politeness: AnnouncePoliteness,
+  target: HTMLElement,
+): void {
+  cancelScheduledClear(politeness);
+  clearTimers[politeness] = setTimeout(() => {
+    clearTimers[politeness] = null;
+    target.textContent = '';
+  }, CLEAR_DELAY_MS);
+}
+
 // Singleton: the live regions are created ONCE and stay mounted for the
 // lifetime of the document. This is the crux of reliable announcements — many
 // screen readers will not announce content injected into a live region that is
@@ -103,6 +139,10 @@ function announceMessage(
   requestAnimationFrame(() => {
     target.textContent = message;
   });
+  // Auto-clear so the last message does not linger in the accessibility tree
+  // indefinitely. Scheduled per announce, so a newer announcement always
+  // resets the countdown (the delay comfortably outlasts the rAF re-set).
+  scheduleClear(politeness, target);
 }
 
 /**
@@ -111,6 +151,7 @@ function announceMessage(
  * so stale status text does not linger in the accessibility tree.
  */
 function clearRegion(politeness: AnnouncePoliteness): void {
+  cancelScheduledClear(politeness);
   if (!regions) {
     return;
   }
@@ -126,6 +167,9 @@ function clearRegion(politeness: AnnouncePoliteness): void {
  * The polite and assertive regions are created once on first use and kept
  * mounted, so announcements are reliable even for messages that appear
  * immediately (unlike a live region rendered together with its content).
+ * Each message is automatically cleared a couple of seconds after being
+ * announced, so users browsing the DOM later do not encounter stale status
+ * text; announcing again before the clear simply resets the countdown.
  *
  * @example
  * ```
@@ -160,6 +204,8 @@ export function useAnnounce(): AnnounceFn {
  * @internal
  */
 export function __resetLiveRegionsForTest(): void {
+  cancelScheduledClear('polite');
+  cancelScheduledClear('assertive');
   if (regions) {
     regions.polite.remove();
     regions.assertive.remove();

package/src/hooks/useContainerReveal.test.tsx

@@ -0,0 +1,116 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file useContainerReveal.test.tsx
+ * @input Uses vitest, @testing-library/react, useContainerReveal
+ * @output Unit tests for the marker-pool free-list, per-instance scoping, the
+ *   inert (disabled) path, and the content-option → style-block mapping.
+ * @position Testing; validates useContainerReveal.ts and its pool.
+ *
+ * SYNC: When useContainerReveal.ts changes, update these tests.
+ */
+
+import {describe, it, expect} from 'vitest';
+import {renderHook, render, act} from '@testing-library/react';
+import {useContainerReveal} from './useContainerReveal';
+import {POOL_SIZE} from './containerReveal.pool.stylex';
+
+describe('useContainerReveal', () => {
+  it('returns spreadable getter props for container and content', () => {
+    const {result} = renderHook(() => useContainerReveal());
+    const container = result.current.getContainerProps();
+    const content = result.current.getContentRevealProps();
+    expect(container).toHaveProperty('className');
+    expect(content).toHaveProperty('className');
+    expect(typeof container.className).toBe('string');
+    expect(typeof content.className).toBe('string');
+  });
+
+  it('is inert when disabled: no marker class, empty content props', () => {
+    const {result} = renderHook(() =>
+      useContainerReveal({isEnabled: false}),
+    );
+    expect(result.current.getContainerProps()).toEqual({});
+    expect(result.current.getContentRevealProps()).toEqual({});
+  });
+
+  it('gives two concurrently mounted containers DISTINCT marker classes', () => {
+    // The core leak-safety property: nested/concurrent containers must never
+    // share a marker, or an ancestor container's :hover would reveal a
+    // descendant container's content.
+    const a = renderHook(() => useContainerReveal());
+    const b = renderHook(() => useContainerReveal());
+    const classA = a.result.current.getContainerProps().className;
+    const classB = b.result.current.getContainerProps().className;
+    expect(classA).toBeTruthy();
+    expect(classB).toBeTruthy();
+    expect(classA).not.toBe(classB);
+    a.unmount();
+    b.unmount();
+  });
+
+  it('recycles a slot after unmount (free-list release)', () => {
+    const first = renderHook(() => useContainerReveal());
+    const firstClass = first.result.current.getContainerProps().className;
+    first.unmount();
+    // A fresh mount should be able to reclaim the just-released slot.
+    const second = renderHook(() => useContainerReveal());
+    const secondClass = second.result.current.getContainerProps().className;
+    expect(secondClass).toBe(firstClass);
+    second.unmount();
+  });
+
+  it('reveal and conceal map to different style blocks', () => {
+    const {result} = renderHook(() => useContainerReveal());
+    const reveal = result.current.getContentRevealProps().className;
+    const conceal = result.current.getContentRevealProps({
+      isRevealInverted: true,
+    }).className;
+    expect(reveal).toBeTruthy();
+    expect(conceal).toBeTruthy();
+    expect(reveal).not.toBe(conceal);
+  });
+
+  it('layout-preserved reveal differs from clipped reveal', () => {
+    const {result} = renderHook(() => useContainerReveal());
+    const clipped = result.current.getContentRevealProps().className;
+    const preserved = result.current.getContentRevealProps({
+      isLayoutPreserved: true,
+    }).className;
+    expect(clipped).not.toBe(preserved);
+  });
+
+  it('assigns distinct markers across a full pool of concurrent containers', () => {
+    function Probe({onClass}: {onClass: (c: string) => void}) {
+      const {getContainerProps} = useContainerReveal();
+      onClass(getContainerProps().className ?? '');
+      return null;
+    }
+    const classes: string[] = [];
+    const {unmount} = render(
+      <>
+        {Array.from({length: POOL_SIZE}, (_, i) => (
+          <Probe key={i} onClass={(c) => classes.push(c)} />
+        ))}
+      </>,
+    );
+    const unique = new Set(classes.filter(Boolean));
+    expect(unique.size).toBe(POOL_SIZE);
+    unmount();
+  });
+
+  it('survives repeated mount/unmount without leaking the pool', () => {
+    // Mount and unmount a full pool several times; each cycle must still hand
+    // out POOL_SIZE distinct markers, proving slots are released.
+    for (let cycle = 0; cycle < 3; cycle++) {
+      const hooks = Array.from({length: POOL_SIZE}, () =>
+        renderHook(() => useContainerReveal()),
+      );
+      const classes = hooks.map(
+        (h) => h.result.current.getContainerProps().className,
+      );
+      expect(new Set(classes).size).toBe(POOL_SIZE);
+      act(() => hooks.forEach((h) => h.unmount()));
+    }
+  });
+});

package/src/hooks/useContainerReveal.ts

@@ -0,0 +1,180 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file useContainerReveal.ts
+ * @input Uses React, the generated marker pool, useDevWarning
+ * @output Exports useContainerReveal — a headless hover/focus reveal primitive
+ * @position Core hook. Consumed by any component that reveals (or conceals)
+ *   content when its container is hovered or focused — e.g. Thumbnail's remove
+ *   button, TreeList row actions.
+ *
+ * Gives a container a scoped hover/focus-within trigger that reveals or
+ * conceals content inside it, entirely in CSS (no hover state in JS, no
+ * re-render on hover). The caller authors NO StyleX: the hook hands out a
+ * marker + matching reveal styles from a pre-compiled pool.
+ *
+ * ACCESSIBILITY (WCAG 2.2 by construction):
+ * - Revealed content is visually hidden at rest via the clip recipe, so it
+ *   stays in the accessibility tree and tab order — never display:none.
+ * - Keyboard: revealed on :focus-within, so tabbing in shows it.
+ * - Touch: always visible on coarse pointers; never gated behind hover.
+ * - Concealed (inverted) content is a mouse-only visual swap: it ignores
+ *   :focus-within (a keyboard user must never watch content vanish) and stays
+ *   visible on touch and in the a11y tree.
+ * - Motion: honors prefers-reduced-motion.
+ *
+ * SYNC: When modified, update:
+ * - /packages/core/src/hooks/index.ts (export)
+ * - containerReveal.pool.stylex.ts (if the slot shape changes)
+ */
+
+import {useState, useEffect, type CSSProperties} from 'react';
+import * as stylex from '@stylexjs/stylex';
+import {POOL, POOL_SIZE, type RevealSlot} from './containerReveal.pool.stylex';
+import {useDevWarning} from './useDevWarning';
+
+// Module-level free-list. Each mounted, enabled useContainerReveal claims a
+// distinct pool slot so that any two CONCURRENTLY mounted containers — in
+// particular a nested container inside another's revealed content — get
+// different markers and cannot leak hover/focus into one another. Slots are
+// returned on unmount. Sibling containers that would only ever collide when
+// the pool is exhausted are harmless (a sibling is never an ancestor), so the
+// pool only needs to cover the number of concurrently mounted containers, not
+// instances over time.
+const claimed: boolean[] = new Array(POOL_SIZE).fill(false);
+
+interface Claim {
+  /** Pool index to use. */
+  index: number;
+  /** True when the pool was full and this claim fell back to a shared slot. */
+  isExhausted: boolean;
+}
+
+function claimSlot(): Claim {
+  for (let i = 0; i < POOL_SIZE; i++) {
+    if (!claimed[i]) {
+      claimed[i] = true;
+      return {index: i, isExhausted: false};
+    }
+  }
+  // Exhausted: fall back to slot 0. Safe for siblings (a sibling is never an
+  // ancestor); only nesting deeper than POOL_SIZE could reintroduce a leak.
+  // Surfaced via useDevWarning so the pool can be grown.
+  return {index: 0, isExhausted: true};
+}
+
+function releaseSlot(index: number, isExhausted: boolean): void {
+  // A fallback claim never owned the slot exclusively; leave it as-is.
+  if (!isExhausted) {
+    claimed[index] = false;
+  }
+}
+
+export interface UseContainerRevealOptions {
+  /**
+   * When false the hook is inert: no marker is applied and content getters
+   * return no styles, so content is always shown. Lets a component gate on its
+   * own prop (e.g. `revealOn === 'hover'`).
+   * @default true
+   */
+  isEnabled?: boolean;
+}
+
+export interface ContentRevealOptions {
+  /**
+   * Conceal-on-hover instead of reveal-on-hover: content is visible at rest
+   * and fades out while the container is hovered. Mouse-only and visual —
+   * stays in the a11y tree, ignores focus-within, stays visible on touch.
+   * @default false
+   */
+  isRevealInverted?: boolean;
+  /**
+   * Reserve the content's layout box while hidden (opacity-only) instead of
+   * collapsing it, to avoid layout shift when it appears.
+   * @default false
+   */
+  isLayoutPreserved?: boolean;
+}
+
+export interface UseContainerRevealReturn {
+  /** Spread onto the container whose hover/focus-within drives the reveal. */
+  getContainerProps: () => {className?: string; style?: CSSProperties};
+  /** Spread onto each revealed / concealed child. */
+  getContentRevealProps: (
+    options?: ContentRevealOptions,
+  ) => {className?: string; style?: CSSProperties};
+}
+
+const EMPTY = Object.freeze({});
+
+/**
+ * Scoped, CSS-only hover/focus reveal for content inside a container.
+ *
+ * @example
+ * ```tsx
+ * const {getContainerProps, getContentRevealProps} = useContainerReveal({
+ *   isEnabled: revealOn === 'hover',
+ * });
+ *
+ * <div {...mergeProps(getContainerProps(), stylex.props(styles.row))}>
+ *   {label}
+ *   <span {...mergeProps(getContentRevealProps(), stylex.props(styles.actions))}>
+ *     {actions}
+ *   </span>
+ * </div>
+ * ```
+ */
+export function useContainerReveal(
+  options: UseContainerRevealOptions = {},
+): UseContainerRevealReturn {
+  const {isEnabled = true} = options;
+
+  // Claim a slot for this container's lifetime. Assigned in the initializer
+  // (not the render body) and released on unmount so the free-list stays
+  // effect-scoped and StrictMode-safe.
+  const [claim] = useState<Claim | null>(() =>
+    isEnabled ? claimSlot() : null,
+  );
+
+  useEffect(() => {
+    if (claim == null) {
+      return;
+    }
+    return () => releaseSlot(claim.index, claim.isExhausted);
+  }, [claim]);
+
+  useDevWarning(
+    'useContainerReveal',
+    `More than ${POOL_SIZE} reveal containers are mounted at once; nested ` +
+      `containers beyond the pool may share a marker. Add markers to ` +
+      `containerReveal.pool.stylex.ts and raise POOL_SIZE.`,
+    claim?.isExhausted ?? false,
+  );
+
+  if (claim == null) {
+    return {
+      getContainerProps: () => EMPTY,
+      getContentRevealProps: () => EMPTY,
+    };
+  }
+
+  const slot: RevealSlot = POOL[claim.index];
+
+  return {
+    getContainerProps: () => stylex.props(slot.marker),
+    getContentRevealProps: (contentOptions: ContentRevealOptions = {}) => {
+      const {isRevealInverted = false, isLayoutPreserved = false} =
+        contentOptions;
+      const style = isRevealInverted
+        ? isLayoutPreserved
+          ? slot.concealLayoutPreserved
+          : slot.conceal
+        : isLayoutPreserved
+          ? slot.revealLayoutPreserved
+          : slot.reveal;
+      return stylex.props(style);
+    },
+  };
+}

package/src/hooks/useFocusTrap.test.tsx

@@ -50,6 +50,39 @@ function EscapeTrap({
   );
 }
 
+function NestedInnerTrap({onEscape}: {onEscape: () => void}) {
+  const {containerRef} = useFocusTrap<HTMLDivElement>({
+    isActive: true,
+    onEscape,
+  });
+  return (
+    <div ref={containerRef} data-testid="nested-inner">
+      <button type="button">inner-btn</button>
+    </div>
+  );
+}
+
+function NestedTraps({
+  onOuterEscape,
+  onInnerEscape,
+  showInner = true,
+}: {
+  onOuterEscape: () => void;
+  onInnerEscape: () => void;
+  showInner?: boolean;
+}) {
+  const {containerRef} = useFocusTrap<HTMLDivElement>({
+    isActive: true,
+    onEscape: onOuterEscape,
+  });
+  return (
+    <div ref={containerRef} data-testid="nested-outer">
+      <button type="button">outer-btn</button>
+      {showInner && <NestedInnerTrap onEscape={onInnerEscape} />}
+    </div>
+  );
+}
+
 function RestoreTrap({isActive}: {isActive: boolean}) {
   const {containerRef} = useFocusTrap<HTMLDivElement>({isActive});
   return (
@@ -118,6 +151,47 @@ describe('useFocusTrap tabbable model (infra-8)', () => {
     // Focus skips the inert button and lands on the real one.
     expect(screen.getByTestId('real-btn')).toHaveFocus();
   });
+
+  it('ignores an aria-hidden subtree when finding focusables', () => {
+    render(
+      <Trap>
+        <div aria-hidden="true">
+          <button type="button" data-testid="aria-hidden-btn">
+            Hidden from AT
+          </button>
+        </div>
+        <button type="button" data-testid="real-btn">
+          Real
+        </button>
+      </Trap>,
+    );
+    fireEvent.click(screen.getByTestId('focus-first'));
+    // An element AT cannot perceive must not be a trap tab stop (WCAG 4.1.2).
+    expect(screen.getByTestId('real-btn')).toHaveFocus();
+  });
+
+  it('excludes an aria-hidden focusable from the Tab wrap boundary', () => {
+    render(
+      <Trap>
+        <button type="button" data-testid="first">
+          First
+        </button>
+        <button type="button" data-testid="visible-last">
+          Visible last
+        </button>
+        <div aria-hidden="true">
+          <button type="button" data-testid="aria-hidden-btn">
+            Hidden from AT
+          </button>
+        </div>
+      </Trap>,
+    );
+    // The last VISIBLE-to-AT element is the wrap boundary: Tab from it wraps
+    // to the first element instead of landing on the aria-hidden button.
+    screen.getByTestId('visible-last').focus();
+    fireEvent.keyDown(document, {key: 'Tab'});
+    expect(screen.getByTestId('first')).toHaveFocus();
+  });
 });
 
 describe('FOCUSABLE_SELECTOR href matching', () => {
@@ -198,6 +272,36 @@ describe('useFocusTrap Escape coordination', () => {
     expect(onEscape).toHaveBeenCalledTimes(1);
   });
 
+  it('resolves Escape to the DOM-nested inner trap when both mount in one commit', () => {
+    const outer = vi.fn();
+    const inner = vi.fn();
+    // Outer and inner mount in the SAME React commit. React runs child
+    // effects before parent effects, so the inner trap is PUSHED first —
+    // DOM containment, not push order, must decide who answers Escape.
+    render(<NestedTraps onOuterEscape={outer} onInnerEscape={inner} />);
+    fireEvent.keyDown(document, {key: 'Escape'});
+    expect(inner).toHaveBeenCalledTimes(1);
+    expect(outer).not.toHaveBeenCalled();
+  });
+
+  it('falls back to the outer trap once the nested inner trap unmounts', () => {
+    const outer = vi.fn();
+    const inner = vi.fn();
+    const {rerender} = render(
+      <NestedTraps onOuterEscape={outer} onInnerEscape={inner} />,
+    );
+    rerender(
+      <NestedTraps
+        onOuterEscape={outer}
+        onInnerEscape={inner}
+        showInner={false}
+      />,
+    );
+    fireEvent.keyDown(document, {key: 'Escape'});
+    expect(outer).toHaveBeenCalledTimes(1);
+    expect(inner).not.toHaveBeenCalled();
+  });
+
   it('does not respond after the trap is deactivated', () => {
     const onEscape = vi.fn();
     const {rerender} = render(

package/src/hooks/useFocusTrap.ts

@@ -26,24 +26,62 @@ import {FOCUSABLE_SELECTOR} from './focusableSelector';
  * Every active `useFocusTrap` used to attach its own document-level `keydown`
  * listener with no coordination, so a single Escape press closed *every* open
  * layer at once (e.g. a popover nested inside a Dialog closed both). Tracking
- * traps in a shared stack lets only the most recently activated (top-most)
- * trap respond to Escape.
+ * traps in a shared stack lets only the top-most trap respond to Escape.
+ *
+ * "Top-most" is resolved by DOM containment first, push order second. Push
+ * order alone is not reliable: React runs child effects before parent
+ * effects, so when an outer and an inner (DOM-nested) trap mount in the SAME
+ * commit, the inner trap pushes first and the outer trap would wrongly win a
+ * pure last-pushed comparison.
  */
-const escapeStack: (() => void)[] = [];
+interface EscapeStackEntry {
+  handler: () => void;
+  getContainer: () => HTMLElement | null;
+}
 
-function pushEscapeHandler(handler: () => void): void {
-  escapeStack.push(handler);
+const escapeStack: EscapeStackEntry[] = [];
+
+function pushEscapeHandler(entry: EscapeStackEntry): void {
+  escapeStack.push(entry);
 }
 
 function removeEscapeHandler(handler: () => void): void {
-  const index = escapeStack.lastIndexOf(handler);
-  if (index !== -1) {
-    escapeStack.splice(index, 1);
+  for (let i = escapeStack.length - 1; i >= 0; i--) {
+    if (escapeStack[i].handler === handler) {
+      escapeStack.splice(i, 1);
+      return;
+    }
   }
 }
 
+/**
+ * Resolve the top-most trap: walk the stack in push order, keeping the
+ * deepest container by DOM containment. When a later entry's container
+ * contains the current candidate's container, the candidate is nested inside
+ * it and stays on top; otherwise the later push wins (containment for nested
+ * traps, push order as the tiebreaker for unrelated ones).
+ */
 function isTopEscapeHandler(handler: () => void): boolean {
-  return escapeStack[escapeStack.length - 1] === handler;
+  if (escapeStack.length === 0) {
+    return false;
+  }
+  let top = escapeStack[0];
+  for (let i = 1; i < escapeStack.length; i++) {
+    const entry = escapeStack[i];
+    const topContainer = top.getContainer();
+    const entryContainer = entry.getContainer();
+    if (
+      topContainer != null &&
+      entryContainer != null &&
+      entryContainer !== topContainer &&
+      entryContainer.contains(topContainer)
+    ) {
+      // The current top is nested inside this entry — it stays on top.
+      continue;
+    }
+    top = entry;
+  }
+  return top.handler === handler;
 }
 
 /**
@@ -73,7 +111,9 @@ export function isImeKeyEvent(event: {
 /**
  * Whether an element is currently perceivable/focusable — excludes ones hidden
  * via `display:none`/`visibility:hidden` or inside an `inert`/`hidden` subtree,
- * which the browser skips for Tab.
+ * which the browser skips for Tab, and ones inside an `aria-hidden="true"`
+ * subtree, which sighted-keyboard users could Tab to while AT skips them
+ * (WCAG 4.1.2 — focusable content must be exposed to assistive tech).
  */
 function isVisiblyFocusable(el: HTMLElement): boolean {
   if (el.hasAttribute('inert') || el.closest('[inert]')) {
@@ -82,6 +122,10 @@ function isVisiblyFocusable(el: HTMLElement): boolean {
   if (el.hidden || el.closest('[hidden]')) {
     return false;
   }
+  // closest() matches the element itself as well as any ancestor.
+  if (el.closest('[aria-hidden="true"]')) {
+    return false;
+  }
   // offsetParent is null for display:none (and fixed elements); pair with a
   // visibility check via getComputedStyle when available.
   if (typeof window !== 'undefined' && window.getComputedStyle) {
@@ -323,12 +367,17 @@ export function useFocusTrap<T extends HTMLElement = HTMLElement>(
 
     // Register this trap on the shared Escape stack so only the top-most
     // active trap responds to Escape. A stable identity per active period is
-    // enough — we push on activate and remove on cleanup.
+    // enough — we push on activate and remove on cleanup. The container is
+    // read lazily: the ref may not be attached yet at effect time, and the
+    // stack resolves top-most by DOM containment at keydown time.
     const escapeHandler = () => {
       onEscape?.();
     };
     if (onEscape) {
-      pushEscapeHandler(escapeHandler);
+      pushEscapeHandler({
+        handler: escapeHandler,
+        getContainer: () => containerRef.current,
+      });
     }
 
     const handleKeyDown = (event: KeyboardEvent) => {

package/src/hooks/useGridFocus.doc.mjs

@@ -64,8 +64,8 @@ export const docs = {
     {
       name: 'options.isRtl',
       type: 'boolean',
-      description: 'Swap ArrowLeft/ArrowRight so horizontal navigation follows visual direction in right-to-left contexts.',
-      default: 'false',
+      description: 'Swap ArrowLeft/ArrowRight so horizontal navigation follows visual direction in right-to-left contexts. When omitted, auto-detected from the container computed direction on keydown.',
+      default: "undefined (auto-detect from the container's computed direction)",
       required: false,
     },
     {
@@ -138,7 +138,7 @@ export const docsDense = {
     'options.onNavigateAfter': 'callback when navigation would go after last cell. Receives column index + offset.',
     'options.onPageUp': 'callback for Page Up key (e.g. navigate to previous month in calendars).',
     'options.onPageDown': 'callback for Page Down key (e.g. navigate to next month in calendars).',
-    'options.isRtl': 'swap ArrowLeft/ArrowRight for RTL horizontal navigation. default false.',
+    'options.isRtl': 'swap ArrowLeft/ArrowRight for RTL horizontal navigation. default: auto-detect from container computed direction; explicit boolean wins.',
     'options.hasRovingTabIndex': 'own a single roving tab stop across the grid (one focus target tabindex=0, rest -1); repaired on render + moved with arrows. Attach handleFocus to onFocus. default false.',
   },
   returnDescriptions: {