@astryxdesign/core 0.1.2 → 0.1.3

package/src/hooks/useFocusTrap.test.tsx

@@ -0,0 +1,132 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file useFocusTrap.test.tsx
+ * @input Uses vitest, @testing-library/react, useFocusTrap hook
+ * @output Unit tests for useFocusTrap tabbable-element model + Escape/IME guard
+ * @position Testing; validates useFocusTrap.ts focusable detection + dismissal coordination
+ *
+ * SYNC: When useFocusTrap.ts changes, update tests to match new behavior
+ */
+
+import {describe, it, expect, vi} from 'vitest';
+import {render, screen, fireEvent} from '@testing-library/react';
+import {useFocusTrap} from './useFocusTrap';
+
+function Trap({children}: {children: React.ReactNode}) {
+  const {containerRef, focusFirst} = useFocusTrap<HTMLDivElement>({
+    isActive: true,
+  });
+  return (
+    <div>
+      <button type="button" data-testid="outside">
+        Outside
+      </button>
+      <div ref={containerRef} data-testid="trap">
+        {children}
+      </div>
+      <button type="button" onClick={focusFirst} data-testid="focus-first">
+        Focus first
+      </button>
+    </div>
+  );
+}
+
+function EscapeTrap({
+  isActive,
+  onEscape,
+  label,
+}: {
+  isActive: boolean;
+  onEscape: () => void;
+  label: string;
+}) {
+  const {containerRef} = useFocusTrap<HTMLDivElement>({isActive, onEscape});
+  return (
+    <div ref={containerRef} data-testid={label}>
+      <button type="button">{label}-btn</button>
+    </div>
+  );
+}
+
+describe('useFocusTrap tabbable model (infra-8)', () => {
+  it('treats a contenteditable as focusable (focusFirst lands on it)', () => {
+    render(
+      <Trap>
+        <div
+          contentEditable
+          data-testid="editor"
+          suppressContentEditableWarning>
+          Type here
+        </div>
+      </Trap>,
+    );
+    fireEvent.click(screen.getByTestId('focus-first'));
+    expect(screen.getByTestId('editor')).toHaveFocus();
+  });
+
+  it('ignores an inert subtree when finding focusables', () => {
+    render(
+      <Trap>
+        <div inert>
+          <button type="button" data-testid="inert-btn">
+            Inert
+          </button>
+        </div>
+        <button type="button" data-testid="real-btn">
+          Real
+        </button>
+      </Trap>,
+    );
+    fireEvent.click(screen.getByTestId('focus-first'));
+    // Focus skips the inert button and lands on the real one.
+    expect(screen.getByTestId('real-btn')).toHaveFocus();
+  });
+});
+
+describe('useFocusTrap Escape coordination', () => {
+  it('calls onEscape for a single active trap', () => {
+    const onEscape = vi.fn();
+    render(<EscapeTrap isActive onEscape={onEscape} label="only" />);
+    fireEvent.keyDown(document, {key: 'Escape'});
+    expect(onEscape).toHaveBeenCalledTimes(1);
+  });
+
+  it('only the top-most trap responds to Escape when nested', () => {
+    const outer = vi.fn();
+    const inner = vi.fn();
+    render(
+      <>
+        <EscapeTrap isActive onEscape={outer} label="outer" />
+        <EscapeTrap isActive onEscape={inner} label="inner" />
+      </>,
+    );
+    // The most recently activated trap (inner) is on top.
+    fireEvent.keyDown(document, {key: 'Escape'});
+    expect(inner).toHaveBeenCalledTimes(1);
+    expect(outer).not.toHaveBeenCalled();
+  });
+
+  it('ignores Escape during IME composition', () => {
+    const onEscape = vi.fn();
+    render(<EscapeTrap isActive onEscape={onEscape} label="ime" />);
+    fireEvent.keyDown(document, {key: 'Escape', isComposing: true});
+    expect(onEscape).not.toHaveBeenCalled();
+    // keyCode 229 (composition) is also ignored
+    fireEvent.keyDown(document, {key: 'Escape', keyCode: 229});
+    expect(onEscape).not.toHaveBeenCalled();
+    // a normal Escape still works
+    fireEvent.keyDown(document, {key: 'Escape'});
+    expect(onEscape).toHaveBeenCalledTimes(1);
+  });
+
+  it('does not respond after the trap is deactivated', () => {
+    const onEscape = vi.fn();
+    const {rerender} = render(
+      <EscapeTrap isActive onEscape={onEscape} label="toggle" />,
+    );
+    rerender(<EscapeTrap isActive={false} onEscape={onEscape} label="toggle" />);
+    fireEvent.keyDown(document, {key: 'Escape'});
+    expect(onEscape).not.toHaveBeenCalled();
+  });
+});

package/src/hooks/useFocusTrap.ts

@@ -17,11 +17,80 @@
 
 import {useCallback, useEffect, useRef} from 'react';
 
+import {FOCUSABLE_SELECTOR} from './focusableSelector';
+
+/**
+ * Module-level stack of active focus-trap Escape handlers.
+ *
+ * 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.
+ */
+const escapeStack: (() => void)[] = [];
+
+function pushEscapeHandler(handler: () => void): void {
+  escapeStack.push(handler);
+}
+
+function removeEscapeHandler(handler: () => void): void {
+  const index = escapeStack.lastIndexOf(handler);
+  if (index !== -1) {
+    escapeStack.splice(index, 1);
+  }
+}
+
+function isTopEscapeHandler(handler: () => void): boolean {
+  return escapeStack[escapeStack.length - 1] === handler;
+}
+
 /**
- * Selector for commonly focusable elements.
+ * Whether any focus-trap Escape handler is currently active (i.e. a popover
+ * layer is open). Other overlay primitives that manage their own Escape (e.g.
+ * Dialog) can consult this to defer to a popover layered on top of them,
+ * giving topmost-only dismissal until a full layer stack exists.
  */
-const FOCUSABLE_SELECTOR =
-  'button:not([disabled]), [href], input:not([disabled]), select:not([disabled]), textarea:not([disabled]), [tabindex]:not([tabindex="-1"]):not([disabled])';
+export function hasActiveFocusTrapEscape(): boolean {
+  return escapeStack.length > 0;
+}
+
+/**
+ * Whether an Escape keydown should be ignored because it is cancelling an
+ * in-progress IME composition. CJK/IME users press Escape to cancel
+ * composition; that must not close the surrounding overlay. `keyCode === 229`
+ * covers browsers that fire keydown before `isComposing` is set. Exported so
+ * other overlays (Dialog, Drawer, CommandPalette) share one definition.
+ */
+export function isImeKeyEvent(event: {
+  isComposing?: boolean;
+  keyCode?: number;
+}): boolean {
+  return event.isComposing === true || event.keyCode === 229;
+}
+
+/**
+ * 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.
+ */
+function isVisiblyFocusable(el: HTMLElement): boolean {
+  if (el.hasAttribute('inert') || el.closest('[inert]')) {
+    return false;
+  }
+  if (el.hidden || el.closest('[hidden]')) {
+    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) {
+    const style = window.getComputedStyle(el);
+    if (style.visibility === 'hidden' || style.display === 'none') {
+      return false;
+    }
+  }
+  return true;
+}
 
 /**
  * Get all focusable elements within a container.
@@ -29,7 +98,7 @@ const FOCUSABLE_SELECTOR =
 function getFocusableElements(container: HTMLElement): HTMLElement[] {
   return Array.from(
     container.querySelectorAll<HTMLElement>(FOCUSABLE_SELECTOR),
-  );
+  ).filter(isVisiblyFocusable);
 }
 
 /**
@@ -203,6 +272,16 @@ export function useFocusTrap<T extends HTMLElement = HTMLElement>(
       return;
     }
 
+    // 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.
+    const escapeHandler = () => {
+      onEscape?.();
+    };
+    if (onEscape) {
+      pushEscapeHandler(escapeHandler);
+    }
+
     const handleKeyDown = (event: KeyboardEvent) => {
       const container = containerRef.current;
       if (!container) {
@@ -210,7 +289,19 @@ export function useFocusTrap<T extends HTMLElement = HTMLElement>(
       }
 
       if (event.key === 'Escape' && onEscape) {
+        // Ignore Escape that is cancelling an IME composition, already handled
+        // by a nested handler, or not targeting the top-most trap.
+        if (
+          event.defaultPrevented ||
+          isImeKeyEvent(event) ||
+          !isTopEscapeHandler(escapeHandler)
+        ) {
+          return;
+        }
+        // Mark handled and stop propagation so an outer layer (e.g. a Dialog
+        // hosting this popover) does not also dismiss on the same press.
         event.preventDefault();
+        event.stopPropagation();
         onEscape();
         return;
       }
@@ -247,6 +338,9 @@ export function useFocusTrap<T extends HTMLElement = HTMLElement>(
 
     return () => {
       document.removeEventListener('keydown', handleKeyDown);
+      if (onEscape) {
+        removeEscapeHandler(escapeHandler);
+      }
     };
   }, [isActive, onEscape]);
 

package/src/hooks/useGridFocus.doc.mjs

@@ -21,10 +21,22 @@ export const docs = {
     {
       name: 'options.cellSelector',
       type: 'string',
-      description: 'Selector for focusable cells within the grid.',
+      description: 'Selector for cells within the grid. Should match ALL cell positions in DOM order (including disabled/empty) so grid geometry is preserved.',
       default: "'button:not([disabled]), [tabindex]:not([tabindex=\"-1\"])'",
       required: false,
     },
+    {
+      name: 'options.isCellFocusable',
+      type: '(cell: HTMLElement) => boolean',
+      description: 'Predicate for whether a matched cell can receive focus. Omit to treat every matched cell as focusable.',
+      required: false,
+    },
+    {
+      name: 'options.getFocusTarget',
+      type: '(cell: HTMLElement) => HTMLElement | null',
+      description: 'Resolves the element to focus for a cell, e.g. a button inside a role="gridcell" wrapper. Omit to focus the cell itself.',
+      required: false,
+    },
     {
       name: 'options.onNavigateBefore',
       type: '(column: number, offset: number) => void',
@@ -49,6 +61,20 @@ export const docs = {
       description: 'Callback for Page Down key (e.g., navigate to next month in calendars).',
       required: false,
     },
+    {
+      name: 'options.isRtl',
+      type: 'boolean',
+      description: 'Swap ArrowLeft/ArrowRight so horizontal navigation follows visual direction in right-to-left contexts.',
+      default: 'false',
+      required: false,
+    },
+    {
+      name: 'options.hasRovingTabIndex',
+      type: 'boolean',
+      description: 'Own a single roving tab stop across the grid: one focusable cell (its resolved focus target) carries tabindex="0", the rest -1. Stamped/repaired on render and moved with arrow navigation. Attach the returned handleFocus to the container onFocus.',
+      default: 'false',
+      required: false,
+    },
   ],
   returns: [
     {
@@ -61,6 +87,11 @@ export const docs = {
       type: '(e: React.KeyboardEvent) => void',
       description: 'Key down handler to attach to the grid container.',
     },
+    {
+      name: 'handleFocus',
+      type: '(e: React.FocusEvent) => void',
+      description: 'Focus handler for the grid container. Keeps the roving tab stop in sync when hasRovingTabIndex is enabled; a no-op otherwise, so always safe to attach.',
+    },
     {
       name: 'focusCell',
       type: '(index: number) => void',
@@ -83,6 +114,7 @@ export const docs = {
     bestPractices: [
       { guidance: true, description: 'Use for calendar date grids: wire onPageUp/onPageDown to month navigation and onNavigateBefore/onNavigateAfter for cross-month arrow key navigation.' },
       { guidance: true, description: 'Attach both gridRef and handleKeyDown to the grid container element.' },
+      { guidance: true, description: 'For roving-tabindex grids (e.g. Calendar), set hasRovingTabIndex: true and attach handleFocus to the container onFocus; seed one focus target with tabindex=0 and the hook repairs and moves it.' },
       { guidance: false, description: 'Use for simple linear lists; prefer useListFocus for 1D navigation.' },
     ],
   },
@@ -99,15 +131,20 @@ export const docsDense = {
   paramDescriptions: {
     options: 'config for grid focus behavior.',
     'options.columns': '# columns in grid. Used for up/down navigation (moves by this many cells).',
-    'options.cellSelector': 'selector for focusable cells in grid.',
+    'options.cellSelector': 'selector for grid cells in DOM order (incl. disabled/empty) so geometry is preserved.',
+    'options.isCellFocusable': 'predicate for whether a matched cell can take focus. Omit = all focusable.',
+    'options.getFocusTarget': 'resolve element to focus for a cell (e.g. button inside gridcell wrapper). Omit = focus the cell.',
     'options.onNavigateBefore': 'callback when navigation would go before first cell. Receives column index + offset (1 for horizontal, columns for vertical).',
     '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.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: {
     gridRef: 'ref to attach to grid container element.',
     handleKeyDown: 'key down handler for grid container.',
+    handleFocus: 'focus handler for grid container; syncs roving tab stop when hasRovingTabIndex on, else no-op.',
     focusCell: 'focus specific cell by index (clamped to valid range).',
     focusFirst: 'focus first focusable cell in grid.',
     focusLast: 'focus last focusable cell in grid.',
@@ -118,6 +155,7 @@ export const docsDense = {
     bestPractices: [
       { guidance: true, description: 'Use for calendar date grids: wire onPageUp/onPageDown to month navigation + onNavigateBefore/onNavigateAfter for cross-month arrow key navigation.' },
       { guidance: true, description: 'Attach both gridRef + handleKeyDown to grid container element.' },
+      { guidance: true, description: 'For roving-tabindex grids (e.g. Calendar): hasRovingTabIndex: true + attach handleFocus to onFocus; seed one focus target tabindex=0, hook repairs + moves it.' },
       { guidance: false, description: 'Use for simple linear lists; prefer useListFocus for 1D navigation.' },
     ],
   },

package/src/hooks/useGridFocus.test.tsx

@@ -0,0 +1,132 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file useGridFocus.test.tsx
+ * @input Uses vitest, @testing-library/react, useGridFocus hook
+ * @output Unit tests for useGridFocus roving tabindex + RTL navigation
+ * @position Testing; validates useGridFocus.ts roving-tabindex ownership
+ *
+ * SYNC: When useGridFocus.ts changes, update tests to match new behavior
+ */
+
+import {describe, it, expect} from 'vitest';
+import {render, screen, fireEvent} from '@testing-library/react';
+import {useGridFocus} from './useGridFocus';
+
+const NO_DISABLED: number[] = [];
+
+/**
+ * A 3x3 grid of cells shaped like Calendar: each `role="gridcell"` div wraps a
+ * focusable `<button>` (the focus target). `seed` marks which button starts
+ * tabbable (mirrors Calendar seeding the selected/today/first-enabled day).
+ */
+function Grid({
+  disabled = NO_DISABLED,
+  seed = 0,
+  ...opts
+}: {
+  disabled?: number[];
+  seed?: number;
+} & Partial<Parameters<typeof useGridFocus>[0]>) {
+  const {gridRef, handleKeyDown, handleFocus} = useGridFocus<HTMLDivElement>({
+    columns: 3,
+    cellSelector: '[role="gridcell"]',
+    isCellFocusable: cell =>
+      cell.querySelector('button:not([disabled])') !== null,
+    getFocusTarget: cell => cell.querySelector<HTMLElement>('button'),
+    hasRovingTabIndex: true,
+    ...opts,
+  });
+  return (
+    <div
+      ref={gridRef}
+      role="grid"
+      onKeyDown={handleKeyDown}
+      onFocus={handleFocus}>
+      {Array.from({length: 9}, (_, i) => (
+        <div role="gridcell" key={i}>
+          <button
+            type="button"
+            disabled={disabled.includes(i)}
+            tabIndex={i === seed ? 0 : -1}
+            data-testid={`cell-${i}`}>
+            {i}
+          </button>
+        </div>
+      ))}
+    </div>
+  );
+}
+
+describe('useGridFocus roving tabindex (hasRovingTabIndex)', () => {
+  it('honors the seeded tab stop and stamps -1 on the rest', () => {
+    render(<Grid seed={4} />);
+    expect(screen.getByTestId('cell-4')).toHaveAttribute('tabindex', '0');
+    expect(screen.getByTestId('cell-0')).toHaveAttribute('tabindex', '-1');
+    expect(screen.getByTestId('cell-8')).toHaveAttribute('tabindex', '-1');
+  });
+
+  it('repairs to the first focusable cell when no cell is seeded', () => {
+    render(<Grid seed={-1} />);
+    expect(screen.getByTestId('cell-0')).toHaveAttribute('tabindex', '0');
+    expect(screen.getByTestId('cell-1')).toHaveAttribute('tabindex', '-1');
+  });
+
+  it('promotes the first ENABLED cell when the seed is disabled', () => {
+    render(<Grid seed={-1} disabled={[0, 1]} />);
+    expect(screen.getByTestId('cell-2')).toHaveAttribute('tabindex', '0');
+    expect(screen.getByTestId('cell-0')).toHaveAttribute('tabindex', '-1');
+  });
+
+  it('ArrowRight moves the tab stop to the next cell', () => {
+    render(<Grid seed={0} />);
+    const grid = screen.getByRole('grid');
+    screen.getByTestId('cell-0').focus();
+    fireEvent.keyDown(grid, {key: 'ArrowRight'});
+    expect(screen.getByTestId('cell-1')).toHaveFocus();
+    expect(screen.getByTestId('cell-1')).toHaveAttribute('tabindex', '0');
+    expect(screen.getByTestId('cell-0')).toHaveAttribute('tabindex', '-1');
+  });
+
+  it('ArrowDown moves the tab stop one row down', () => {
+    render(<Grid seed={0} />);
+    const grid = screen.getByRole('grid');
+    screen.getByTestId('cell-0').focus();
+    fireEvent.keyDown(grid, {key: 'ArrowDown'});
+    expect(screen.getByTestId('cell-3')).toHaveFocus();
+    expect(screen.getByTestId('cell-3')).toHaveAttribute('tabindex', '0');
+  });
+
+  it('handleFocus repairs the stop when the tabbable cell became disabled', () => {
+    // Seed cell 0 as tabbable, then disable it and fire the container onFocus.
+    // syncTabStops should promote the first still-focusable cell (cell 1).
+    const {rerender} = render(<Grid seed={0} />);
+    const grid = screen.getByRole('grid');
+    expect(screen.getByTestId('cell-0')).toHaveAttribute('tabindex', '0');
+    rerender(<Grid seed={-1} disabled={[0]} />);
+    fireEvent.focus(grid);
+    expect(screen.getByTestId('cell-1')).toHaveAttribute('tabindex', '0');
+    expect(screen.getByTestId('cell-0')).toHaveAttribute('tabindex', '-1');
+  });
+
+  it('flips ArrowLeft/ArrowRight under RTL', () => {
+    render(<Grid seed={1} isRtl />);
+    const grid = screen.getByRole('grid');
+    screen.getByTestId('cell-1').focus();
+    // In RTL, ArrowLeft is "forward" (moves to the next cell in DOM order).
+    fireEvent.keyDown(grid, {key: 'ArrowLeft'});
+    expect(screen.getByTestId('cell-2')).toHaveFocus();
+  });
+
+  it('does not manage tabindex when hasRovingTabIndex is off', () => {
+    render(<Grid seed={0} hasRovingTabIndex={false} />);
+    // The seeded -1/0 values are left untouched (caller owns them), and
+    // navigation still works without stamping.
+    const grid = screen.getByRole('grid');
+    screen.getByTestId('cell-0').focus();
+    fireEvent.keyDown(grid, {key: 'ArrowRight'});
+    expect(screen.getByTestId('cell-1')).toHaveFocus();
+    // cell-1 kept its seeded -1; the hook did not promote it.
+    expect(screen.getByTestId('cell-1')).toHaveAttribute('tabindex', '-1');
+  });
+});