@astryxdesign/core 0.0.0-bootstrap.0 → 0.1.0-canary.0b5b49f

package/src/hooks/useFocusTrap.ts

@@ -0,0 +1,257 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file useFocusTrap.ts
+ * @input Uses React useCallback, useEffect, useRef
+ * @output Exports useFocusTrap hook for trapping focus within a container
+ * @position Core hook; used by dialogs, modals, date pickers
+ *
+ * Based on WAI-ARIA dialog pattern:
+ * https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/
+ *
+ * SYNC: When modified, update:
+ * - /packages/core/src/hooks/index.ts
+ */
+
+import {useCallback, useEffect, useRef} from 'react';
+
+/**
+ * Selector for commonly focusable elements.
+ */
+const FOCUSABLE_SELECTOR =
+  'button:not([disabled]), [href], input:not([disabled]), select:not([disabled]), textarea:not([disabled]), [tabindex]:not([tabindex="-1"]):not([disabled])';
+
+/**
+ * Get all focusable elements within a container.
+ */
+function getFocusableElements(container: HTMLElement): HTMLElement[] {
+  return Array.from(
+    container.querySelectorAll<HTMLElement>(FOCUSABLE_SELECTOR),
+  );
+}
+
+/**
+ * Attempt to focus an element. Returns true if focus was successful.
+ */
+function attemptFocus(element: HTMLElement): boolean {
+  try {
+    element.focus();
+  } catch {
+    // Some elements may throw on focus
+  }
+  return document.activeElement === element;
+}
+
+/**
+ * Focus the first focusable descendant of a container.
+ * Returns true if a focusable element was found and focused.
+ */
+function focusFirstDescendant(container: HTMLElement): boolean {
+  const focusable = getFocusableElements(container);
+  for (const element of focusable) {
+    if (attemptFocus(element)) {
+      return true;
+    }
+  }
+  return false;
+}
+
+/**
+ * Focus the last focusable descendant of a container.
+ * Returns true if a focusable element was found and focused.
+ */
+function focusLastDescendant(container: HTMLElement): boolean {
+  const focusable = getFocusableElements(container);
+  for (let i = focusable.length - 1; i >= 0; i--) {
+    if (attemptFocus(focusable[i])) {
+      return true;
+    }
+  }
+  return false;
+}
+
+/**
+ * Configuration for focus trap behavior
+ */
+export interface UseFocusTrapOptions {
+  /**
+   * Whether the focus trap is currently active.
+   */
+  isActive: boolean;
+
+  /**
+   * Callback when Escape key is pressed.
+   */
+  onEscape?: () => void;
+}
+
+/**
+ * Return type for useFocusTrap hook
+ */
+export interface UseFocusTrapReturn<T extends HTMLElement = HTMLElement> {
+  /**
+   * Ref to attach to the container element that should trap focus.
+   */
+  containerRef: React.RefObject<T | null>;
+
+  /**
+   * Focus the first focusable element in the container.
+   */
+  focusFirst: () => void;
+}
+
+/**
+ * Hook for trapping focus within a container element.
+ *
+ * Implements the WAI-ARIA dialog focus trap pattern:
+ * - Listens to focus events on the document
+ * - Redirects focus back into the container if it escapes
+ * - Handles both Tab and Shift+Tab navigation
+ *
+ * @example
+ * ```
+ * const {containerRef, focusFirst} = useFocusTrap({
+ *   isActive: isOpen,
+ *   onEscape: () => setIsOpen(false),
+ * });
+ *
+ * useEffect(() => {
+ *   if (isOpen) {
+ *     focusFirst();
+ *   }
+ * }, [isOpen, focusFirst]);
+ *
+ * <div ref={containerRef}>
+ *   <button>First</button>
+ *   <button>Last</button>
+ * </div>
+ * ```
+ */
+export function useFocusTrap<T extends HTMLElement = HTMLElement>(
+  options: UseFocusTrapOptions,
+): UseFocusTrapReturn<T> {
+  const {isActive, onEscape} = options;
+
+  const containerRef = useRef<T | null>(null);
+  const lastFocusRef = useRef<Element | null>(null);
+  // Track if focus change was triggered by keyboard (Tab key)
+  const isKeyboardNavigationRef = useRef(false);
+
+  /**
+   * Focus the first focusable element.
+   */
+  const focusFirst = useCallback(() => {
+    if (containerRef.current) {
+      focusFirstDescendant(containerRef.current);
+    }
+  }, []);
+
+  /**
+   * Handle focus events - redirect focus back into container if it escapes.
+   * Only redirects for keyboard navigation, not mouse clicks.
+   */
+  useEffect(() => {
+    if (!isActive) {
+      return;
+    }
+
+    const handleFocus = (event: FocusEvent) => {
+      const container = containerRef.current;
+      if (!container) {
+        return;
+      }
+
+      const target = event.target as Node;
+
+      if (container.contains(target)) {
+        // Focus is inside the container - track it
+        lastFocusRef.current = target as Element;
+      } else if (isKeyboardNavigationRef.current) {
+        // Focus escaped via keyboard - redirect it back
+        focusFirstDescendant(container);
+
+        // If we're back at the same element (Shift+Tab from first element),
+        // try focusing the last element instead
+        if (lastFocusRef.current === document.activeElement) {
+          focusLastDescendant(container);
+        }
+
+        lastFocusRef.current = document.activeElement;
+      }
+      // If focus escaped via mouse click, don't redirect - let light dismiss handle it
+
+      // Reset keyboard navigation flag
+      isKeyboardNavigationRef.current = false;
+    };
+
+    // Use capture phase to intercept focus before it settles
+    document.addEventListener('focus', handleFocus, true);
+
+    return () => {
+      document.removeEventListener('focus', handleFocus, true);
+    };
+  }, [isActive]);
+
+  /**
+   * Handle Tab key to wrap focus at boundaries, and Escape to close.
+   * Also tracks that keyboard navigation is occurring.
+   */
+  useEffect(() => {
+    if (!isActive) {
+      return;
+    }
+
+    const handleKeyDown = (event: KeyboardEvent) => {
+      const container = containerRef.current;
+      if (!container) {
+        return;
+      }
+
+      if (event.key === 'Escape' && onEscape) {
+        event.preventDefault();
+        onEscape();
+        return;
+      }
+
+      if (event.key === 'Tab') {
+        // Mark that keyboard navigation is happening
+        isKeyboardNavigationRef.current = true;
+
+        const focusable = getFocusableElements(container);
+        if (focusable.length === 0) {
+          return;
+        }
+
+        const first = focusable[0];
+        const last = focusable[focusable.length - 1];
+
+        if (event.shiftKey) {
+          // Shift+Tab: if on first element, wrap to last
+          if (document.activeElement === first) {
+            event.preventDefault();
+            last.focus();
+          }
+        } else {
+          // Tab: if on last element, wrap to first
+          if (document.activeElement === last) {
+            event.preventDefault();
+            first.focus();
+          }
+        }
+      }
+    };
+
+    document.addEventListener('keydown', handleKeyDown);
+
+    return () => {
+      document.removeEventListener('keydown', handleKeyDown);
+    };
+  }, [isActive, onEscape]);
+
+  return {
+    containerRef,
+    focusFirst,
+  };
+}

package/src/hooks/useGridFocus.doc.mjs

@@ -0,0 +1,124 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../docs-types').HookDoc} */
+export const docs = {
+  name: 'useGridFocus',
+  displayName: 'useGridFocus',
+  keywords: ['grid', 'focus', 'keyboard', 'navigation', 'arrow', 'calendar', 'a11y', 'wai-aria', 'cells'],
+  params: [
+    {
+      name: 'options',
+      type: 'UseGridFocusOptions',
+      description: 'Configuration object for grid focus behavior.',
+      required: true,
+    },
+    {
+      name: 'options.columns',
+      type: 'number',
+      description: 'Number of columns in the grid. Used for up/down navigation (moves by this many cells).',
+      required: true,
+    },
+    {
+      name: 'options.cellSelector',
+      type: 'string',
+      description: 'Selector for focusable cells within the grid.',
+      default: "'button:not([disabled]), [tabindex]:not([tabindex=\"-1\"])'",
+      required: false,
+    },
+    {
+      name: 'options.onNavigateBefore',
+      type: '(column: number, offset: number) => void',
+      description: 'Callback when navigation would go before the first cell. Receives the column index and offset (1 for horizontal, columns for vertical).',
+      required: false,
+    },
+    {
+      name: 'options.onNavigateAfter',
+      type: '(column: number, offset: number) => void',
+      description: 'Callback when navigation would go after the last cell. Receives the column index and offset.',
+      required: false,
+    },
+    {
+      name: 'options.onPageUp',
+      type: '() => void',
+      description: 'Callback for Page Up key (e.g., navigate to previous month in calendars).',
+      required: false,
+    },
+    {
+      name: 'options.onPageDown',
+      type: '() => void',
+      description: 'Callback for Page Down key (e.g., navigate to next month in calendars).',
+      required: false,
+    },
+  ],
+  returns: [
+    {
+      name: 'gridRef',
+      type: 'React.RefObject<HTMLElement | null>',
+      description: 'Ref to attach to the grid container element.',
+    },
+    {
+      name: 'handleKeyDown',
+      type: '(e: React.KeyboardEvent) => void',
+      description: 'Key down handler to attach to the grid container.',
+    },
+    {
+      name: 'focusCell',
+      type: '(index: number) => void',
+      description: 'Focus a specific cell by index (clamped to valid range).',
+    },
+    {
+      name: 'focusFirst',
+      type: '() => void',
+      description: 'Focus the first focusable cell in the grid.',
+    },
+    {
+      name: 'focusLast',
+      type: '() => void',
+      description: 'Focus the last focusable cell in the grid.',
+    },
+  ],
+  usage: {
+    description:
+      'Manages keyboard navigation within a 2D grid following the WAI-ARIA grid pattern. Supports arrow keys for cell-to-cell navigation, Home/End for row boundaries, Ctrl+Home/Ctrl+End for grid boundaries, and Page Up/Down for custom callbacks (e.g., month navigation in calendars). Boundary navigation callbacks allow cross-grid navigation.',
+    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: false, description: 'Use for simple linear lists; prefer useListFocus for 1D navigation.' },
+    ],
+  },
+  relatedComponents: ['Calendar'],
+  relatedHooks: ['useListFocus', 'useFocusTrap'],
+  importPath: '@astryxdesign/core/hooks',
+  category: 'focus',
+};
+
+/** @type {import('../docs-types').HookTranslationDoc} */
+export const docsDense = {
+  description:
+    'Manages keyboard navigation within 2D grid following WAI-ARIA grid pattern. Supports arrow keys for cell-to-cell navigation, Home/End for row boundaries, Ctrl+Home/Ctrl+End for grid boundaries, Page Up/Down for custom callbacks (e.g. month navigation in calendars). Boundary navigation callbacks allow cross-grid navigation.',
+  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.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).',
+  },
+  returnDescriptions: {
+    gridRef: 'ref to attach to grid container element.',
+    handleKeyDown: 'key down handler for grid container.',
+    focusCell: 'focus specific cell by index (clamped to valid range).',
+    focusFirst: 'focus first focusable cell in grid.',
+    focusLast: 'focus last focusable cell in grid.',
+  },
+  usage: {
+    description:
+      'Manages keyboard navigation within 2D grid following WAI-ARIA grid pattern. Supports arrow keys for cell-to-cell navigation, Home/End for row boundaries, Ctrl+Home/Ctrl+End for grid boundaries, Page Up/Down for custom callbacks (e.g. month navigation in calendars). Boundary navigation callbacks allow cross-grid navigation.',
+    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: false, description: 'Use for simple linear lists; prefer useListFocus for 1D navigation.' },
+    ],
+  },
+};

package/src/hooks/useGridFocus.ts

@@ -0,0 +1,325 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file useGridFocus.ts
+ * @input Uses React useCallback, useRef
+ * @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
+ */
+
+import {useCallback, useRef} from 'react';
+
+/**
+ * Configuration for grid focus behavior
+ */
+export interface UseGridFocusOptions {
+  /**
+   * Number of columns in the grid.
+   * Used for up/down navigation (moves by this many cells).
+   */
+  columns: number;
+
+  /**
+   * Selector for focusable cells within the grid.
+   * @default 'button:not([disabled]), [tabindex]:not([tabindex="-1"])'
+   */
+  cellSelector?: string;
+
+  /**
+   * Callback when navigation would go before the first cell.
+   * Useful for navigating to previous month in calendars.
+   * @param column The column index (0-based) that was focused when navigating
+   * @param offset Number of cells to move (1 for horizontal, columns for vertical)
+   */
+  onNavigateBefore?: (column: number, offset: number) => void;
+
+  /**
+   * Callback when navigation would go after the last cell.
+   * Useful for navigating to next month in calendars.
+   * @param column The column index (0-based) that was focused when navigating
+   * @param offset Number of cells to move (1 for horizontal, columns for vertical)
+   */
+  onNavigateAfter?: (column: number, offset: number) => void;
+
+  /**
+   * Callback for Page Up key (e.g., previous month).
+   */
+  onPageUp?: () => void;
+
+  /**
+   * Callback for Page Down key (e.g., next month).
+   */
+  onPageDown?: () => void;
+}
+
+/**
+ * Return type for useGridFocus hook
+ */
+export interface UseGridFocusReturn<T extends HTMLElement = HTMLElement> {
+  /**
+   * Ref to attach to the grid container element.
+   */
+  gridRef: React.RefObject<T | null>;
+
+  /**
+   * Key down handler to attach to the grid container.
+   */
+  handleKeyDown: (e: React.KeyboardEvent) => void;
+
+  /**
+   * Focus a specific cell by index.
+   */
+  focusCell: (index: number) => void;
+
+  /**
+   * Focus the first focusable cell.
+   */
+  focusFirst: () => void;
+
+  /**
+   * Focus the last focusable cell.
+   */
+  focusLast: () => void;
+}
+
+/**
+ * Hook for managing keyboard navigation within a grid.
+ *
+ * Implements WAI-ARIA grid pattern:
+ * - Arrow keys: Navigate between cells
+ * - Home: Move to first cell in row
+ * - End: Move to last cell in row
+ * - Ctrl+Home: Move to first cell in grid
+ * - Ctrl+End: Move to last cell in grid
+ * - Page Up/Down: Custom callbacks (e.g., month navigation)
+ *
+ * @example
+ * ```
+ * const {gridRef, handleKeyDown} = useGridFocus({
+ *   columns: 7,
+ *   onPageUp: () => navigateMonth(-1),
+ *   onPageDown: () => navigateMonth(1),
+ * });
+ *
+ * <div ref={gridRef} role="grid" onKeyDown={handleKeyDown}>
+ *   {cells.map(cell => <button role="gridcell">{cell}</button>)}
+ * </div>
+ * ```
+ */
+export function useGridFocus<T extends HTMLElement = HTMLElement>(
+  options: UseGridFocusOptions,
+): UseGridFocusReturn<T> {
+  const {
+    columns,
+    cellSelector = 'button:not([disabled]), [tabindex]:not([tabindex="-1"])',
+    onNavigateBefore,
+    onNavigateAfter,
+    onPageUp,
+    onPageDown,
+  } = options;
+
+  const gridRef = useRef<T>(null);
+
+  /**
+   * Get all focusable cells in the grid.
+   */
+  const getCells = useCallback((): HTMLElement[] => {
+    if (!gridRef.current) {
+      return [];
+    }
+    return Array.from(
+      gridRef.current.querySelectorAll<HTMLElement>(cellSelector),
+    );
+  }, [cellSelector]);
+
+  /**
+   * Get the currently focused cell index.
+   */
+  const getCurrentIndex = useCallback((): number => {
+    const cells = getCells();
+    const active = document.activeElement;
+    return cells.findIndex(cell => cell === active || cell.contains(active));
+  }, [getCells]);
+
+  /**
+   * Focus a cell by index, clamping to valid range.
+   * Returns true if focus was successful, false if navigation callback was triggered.
+   */
+  const focusCellInternal = useCallback(
+    (index: number, currentColumn: number, offset: number) => {
+      const cells = getCells();
+      if (cells.length === 0) {
+        return;
+      }
+
+      if (index < 0) {
+        onNavigateBefore?.(currentColumn, offset);
+        return;
+      }
+      if (index >= cells.length) {
+        onNavigateAfter?.(currentColumn, offset);
+        return;
+      }
+
+      cells[index]?.focus();
+    },
+    [getCells, onNavigateBefore, onNavigateAfter],
+  );
+
+  /**
+   * Public focusCell that doesn't trigger navigation callbacks
+   */
+  const focusCell = useCallback(
+    (index: number) => {
+      const cells = getCells();
+      if (cells.length === 0) {
+        return;
+      }
+      const clampedIndex = Math.max(0, Math.min(index, cells.length - 1));
+      cells[clampedIndex]?.focus();
+    },
+    [getCells],
+  );
+
+  /**
+   * Focus the first cell.
+   */
+  const focusFirst = useCallback(() => {
+    const cells = getCells();
+    cells[0]?.focus();
+  }, [getCells]);
+
+  /**
+   * Focus the last cell.
+   */
+  const focusLast = useCallback(() => {
+    const cells = getCells();
+    cells[cells.length - 1]?.focus();
+  }, [getCells]);
+
+  /**
+   * Handle keyboard navigation.
+   */
+  const handleKeyDown = useCallback(
+    (e: React.KeyboardEvent) => {
+      const currentIndex = getCurrentIndex();
+      if (currentIndex === -1) {
+        return;
+      }
+
+      const cells = getCells();
+      const currentRow = Math.floor(currentIndex / columns);
+      const currentCol = currentIndex % columns;
+      const totalRows = Math.ceil(cells.length / columns);
+
+      let handled = true;
+
+      switch (e.key) {
+        case 'ArrowRight':
+          // Horizontal navigation: offset = 1
+          focusCellInternal(currentIndex + 1, (currentCol + 1) % columns, 1);
+          break;
+
+        case 'ArrowLeft':
+          // Horizontal navigation: offset = 1
+          focusCellInternal(
+            currentIndex - 1,
+            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);
+            } else {
+              // Last row might be partial, focus last cell
+              focusCellInternal(cells.length - 1, currentCol, columns);
+            }
+          } else {
+            onNavigateAfter?.(currentCol, columns);
+          }
+          break;
+
+        case 'ArrowUp':
+          // Vertical navigation: offset = columns (7 for calendar)
+          if (currentRow > 0) {
+            focusCellInternal(currentIndex - columns, currentCol, columns);
+          } else {
+            onNavigateBefore?.(currentCol, columns);
+          }
+          break;
+
+        case 'Home':
+          if (e.ctrlKey || e.metaKey) {
+            // Ctrl+Home: first cell in grid
+            focusFirst();
+          } else {
+            // Home: first cell in current row
+            focusCell(currentRow * columns);
+          }
+          break;
+
+        case 'End':
+          if (e.ctrlKey || e.metaKey) {
+            // Ctrl+End: last cell in grid
+            focusLast();
+          } else {
+            // End: last cell in current row
+            const rowEnd = Math.min(
+              (currentRow + 1) * columns - 1,
+              cells.length - 1,
+            );
+            focusCell(rowEnd);
+          }
+          break;
+
+        case 'PageUp':
+          onPageUp?.();
+          break;
+
+        case 'PageDown':
+          onPageDown?.();
+          break;
+
+        default:
+          handled = false;
+      }
+
+      if (handled) {
+        e.preventDefault();
+        e.stopPropagation();
+      }
+    },
+    [
+      columns,
+      focusCell,
+      focusCellInternal,
+      focusFirst,
+      focusLast,
+      getCells,
+      getCurrentIndex,
+      onNavigateAfter,
+      onNavigateBefore,
+      onPageDown,
+      onPageUp,
+    ],
+  );
+
+  return {
+    gridRef,
+    handleKeyDown,
+    focusCell,
+    focusFirst,
+    focusLast,
+  };
+}