@idealyst/components 1.1.4 → 1.1.5

package/src/utils/accessibility/useFocusTrap.ts

@@ -0,0 +1,265 @@
+import { useEffect, useRef, useCallback } from 'react';
+
+/**
+ * Options for the useFocusTrap hook.
+ */
+export interface UseFocusTrapOptions {
+  /** Whether the focus trap is active */
+  active: boolean;
+  /** Ref to the container element that traps focus */
+  containerRef: React.RefObject<HTMLElement>;
+  /** Whether to restore focus to the previously focused element when deactivated */
+  restoreFocus?: boolean;
+  /** Whether to auto-focus the first focusable element when activated */
+  autoFocus?: boolean;
+  /** CSS selector for the element to focus initially (overrides autoFocus) */
+  initialFocus?: string;
+  /** CSS selector for the element to focus when closing (overrides restoreFocus) */
+  returnFocus?: string;
+  /** Callback when Escape key is pressed */
+  onEscape?: () => void;
+}
+
+/**
+ * Return type for the useFocusTrap hook.
+ */
+export interface UseFocusTrapReturn {
+  /** Manually focus the first focusable element in the container */
+  focusFirst: () => void;
+  /** Manually focus the last focusable element in the container */
+  focusLast: () => void;
+  /** Get all focusable elements within the container */
+  getFocusableElements: () => HTMLElement[];
+}
+
+/**
+ * Selector for focusable elements.
+ */
+const FOCUSABLE_SELECTOR = [
+  'a[href]',
+  'button:not([disabled])',
+  'textarea:not([disabled])',
+  'input:not([disabled]):not([type="hidden"])',
+  'select:not([disabled])',
+  '[tabindex]:not([tabindex="-1"])',
+  '[contenteditable="true"]',
+].join(',');
+
+/**
+ * Hook for implementing WCAG-compliant focus trapping in dialogs and modals.
+ *
+ * Features:
+ * - Traps focus within a container element
+ * - Tab cycles through focusable elements
+ * - Shift+Tab cycles in reverse
+ * - Auto-focuses first element on activation
+ * - Restores focus on deactivation
+ * - Escape key handling
+ *
+ * @example
+ * ```tsx
+ * const containerRef = useRef<HTMLDivElement>(null);
+ * const [isOpen, setIsOpen] = useState(false);
+ *
+ * const { focusFirst } = useFocusTrap({
+ *   active: isOpen,
+ *   containerRef,
+ *   onEscape: () => setIsOpen(false),
+ * });
+ *
+ * return (
+ *   <div
+ *     ref={containerRef}
+ *     role="dialog"
+ *     aria-modal="true"
+ *   >
+ *     <button>Focusable</button>
+ *     <button onClick={() => setIsOpen(false)}>Close</button>
+ *   </div>
+ * );
+ * ```
+ */
+export function useFocusTrap({
+  active,
+  containerRef,
+  restoreFocus = true,
+  autoFocus = true,
+  initialFocus,
+  returnFocus,
+  onEscape,
+}: UseFocusTrapOptions): UseFocusTrapReturn {
+  // Store the element that was focused before the trap was activated
+  const previousActiveElement = useRef<HTMLElement | null>(null);
+
+  /**
+   * Get all focusable elements within the container.
+   */
+  const getFocusableElements = useCallback((): HTMLElement[] => {
+    if (!containerRef.current) return [];
+
+    const elements = Array.from(
+      containerRef.current.querySelectorAll<HTMLElement>(FOCUSABLE_SELECTOR)
+    );
+
+    // Filter out elements that are not visible or are disabled
+    return elements.filter((el) => {
+      // Check if element is visible
+      if (el.offsetParent === null && el.style.position !== 'fixed') {
+        return false;
+      }
+      // Check computed visibility
+      const style = window.getComputedStyle(el);
+      if (style.visibility === 'hidden' || style.display === 'none') {
+        return false;
+      }
+      return true;
+    });
+  }, [containerRef]);
+
+  /**
+   * Focus the first focusable element in the container.
+   */
+  const focusFirst = useCallback(() => {
+    const container = containerRef.current;
+    if (!container) return;
+
+    // Try to focus the initial focus element first
+    if (initialFocus) {
+      const initialElement = container.querySelector<HTMLElement>(initialFocus);
+      if (initialElement) {
+        initialElement.focus();
+        return;
+      }
+    }
+
+    // Otherwise focus the first focusable element
+    const focusable = getFocusableElements();
+    if (focusable.length > 0) {
+      focusable[0].focus();
+    } else {
+      // If no focusable elements, focus the container itself
+      container.setAttribute('tabindex', '-1');
+      container.focus();
+    }
+  }, [containerRef, initialFocus, getFocusableElements]);
+
+  /**
+   * Focus the last focusable element in the container.
+   */
+  const focusLast = useCallback(() => {
+    const focusable = getFocusableElements();
+    if (focusable.length > 0) {
+      focusable[focusable.length - 1].focus();
+    }
+  }, [getFocusableElements]);
+
+  /**
+   * Handle Tab key to trap focus within the container.
+   */
+  const handleKeyDown = useCallback(
+    (event: KeyboardEvent) => {
+      if (!active) return;
+
+      if (event.key === 'Escape') {
+        event.preventDefault();
+        onEscape?.();
+        return;
+      }
+
+      if (event.key !== 'Tab') return;
+
+      const focusable = getFocusableElements();
+      if (focusable.length === 0) return;
+
+      const firstFocusable = focusable[0];
+      const lastFocusable = focusable[focusable.length - 1];
+      const activeElement = document.activeElement;
+
+      if (event.shiftKey) {
+        // Shift + Tab - going backwards
+        if (activeElement === firstFocusable || !containerRef.current?.contains(activeElement)) {
+          event.preventDefault();
+          lastFocusable.focus();
+        }
+      } else {
+        // Tab - going forwards
+        if (activeElement === lastFocusable || !containerRef.current?.contains(activeElement)) {
+          event.preventDefault();
+          firstFocusable.focus();
+        }
+      }
+    },
+    [active, getFocusableElements, containerRef, onEscape]
+  );
+
+  /**
+   * Handle clicks outside the container (optional - for click-away to close).
+   */
+  const handleFocusIn = useCallback(
+    (event: FocusEvent) => {
+      if (!active || !containerRef.current) return;
+
+      // If focus moves outside the container, bring it back
+      if (!containerRef.current.contains(event.target as Node)) {
+        focusFirst();
+      }
+    },
+    [active, containerRef, focusFirst]
+  );
+
+  // Set up and tear down the focus trap
+  useEffect(() => {
+    if (active) {
+      // Store currently focused element before trapping
+      previousActiveElement.current = document.activeElement as HTMLElement;
+
+      // Add event listeners
+      document.addEventListener('keydown', handleKeyDown);
+      document.addEventListener('focusin', handleFocusIn);
+
+      // Auto-focus after a short delay to ensure the container is rendered
+      if (autoFocus) {
+        requestAnimationFrame(() => {
+          focusFirst();
+        });
+      }
+    }
+
+    return () => {
+      document.removeEventListener('keydown', handleKeyDown);
+      document.removeEventListener('focusin', handleFocusIn);
+
+      // Restore focus when deactivating
+      if (active && restoreFocus) {
+        if (returnFocus) {
+          const returnElement = document.querySelector<HTMLElement>(returnFocus);
+          if (returnElement) {
+            returnElement.focus();
+            return;
+          }
+        }
+        if (previousActiveElement.current && previousActiveElement.current.focus) {
+          previousActiveElement.current.focus();
+        }
+      }
+    };
+  }, [active, autoFocus, restoreFocus, returnFocus, handleKeyDown, handleFocusIn, focusFirst]);
+
+  return {
+    focusFirst,
+    focusLast,
+    getFocusableElements,
+  };
+}
+
+/**
+ * Native version of useFocusTrap - no-op since React Native handles
+ * modal focus differently via the Modal component.
+ */
+export function useFocusTrapNative(): UseFocusTrapReturn {
+  return {
+    focusFirst: () => {},
+    focusLast: () => {},
+    getFocusableElements: () => [],
+  };
+}

package/src/utils/accessibility/useKeyboardNavigation.ts

@@ -0,0 +1,292 @@
+import { useCallback, useRef } from 'react';
+
+/**
+ * Options for the useKeyboardNavigation hook.
+ */
+export interface UseKeyboardNavigationOptions {
+  /** Refs to the navigable items */
+  itemRefs: React.RefObject<(HTMLElement | null)[]>;
+  /** Currently focused item index */
+  focusedIndex: number;
+  /** Callback to update the focused index */
+  setFocusedIndex: (index: number) => void;
+  /** Total number of items */
+  itemCount: number;
+  /** Navigation orientation - determines which arrow keys are used */
+  orientation?: 'horizontal' | 'vertical' | 'both';
+  /** Whether navigation wraps from last to first and vice versa */
+  wrap?: boolean;
+  /** Callback when an item is selected (Enter/Space pressed) */
+  onSelect?: (index: number) => void;
+  /** Callback when Escape is pressed */
+  onEscape?: () => void;
+  /** Function to get the text label of an item for type-ahead search */
+  getItemLabel?: (index: number) => string;
+  /** Whether navigation is disabled */
+  disabled?: boolean;
+  /** Whether to auto-select on navigation (like tabs with automatic activation) */
+  autoSelect?: boolean;
+}
+
+/**
+ * Return type for the useKeyboardNavigation hook.
+ */
+export interface UseKeyboardNavigationReturn {
+  /** Keyboard event handler to attach to the container or items */
+  handleKeyDown: (event: React.KeyboardEvent) => void;
+  /** Programmatically focus an item by index */
+  focusItem: (index: number) => void;
+  /** Navigate to the next item */
+  navigateNext: () => void;
+  /** Navigate to the previous item */
+  navigatePrevious: () => void;
+  /** Navigate to the first item */
+  navigateFirst: () => void;
+  /** Navigate to the last item */
+  navigateLast: () => void;
+}
+
+/**
+ * Hook for implementing WCAG-compliant keyboard navigation in lists, menus, tabs, etc.
+ *
+ * Features:
+ * - Arrow key navigation (horizontal, vertical, or both)
+ * - Home/End for first/last item
+ * - Enter/Space for selection
+ * - Escape for closing/canceling
+ * - Type-ahead search for quick navigation
+ * - Optional wrap-around navigation
+ * - Auto-select on navigation (for tabs)
+ *
+ * @example
+ * ```tsx
+ * const itemRefs = useRef<(HTMLElement | null)[]>([]);
+ * const [focusedIndex, setFocusedIndex] = useState(0);
+ *
+ * const { handleKeyDown, focusItem } = useKeyboardNavigation({
+ *   itemRefs,
+ *   focusedIndex,
+ *   setFocusedIndex,
+ *   itemCount: items.length,
+ *   orientation: 'vertical',
+ *   onSelect: (index) => handleItemSelect(items[index]),
+ * });
+ *
+ * return (
+ *   <div role="listbox" onKeyDown={handleKeyDown}>
+ *     {items.map((item, i) => (
+ *       <div
+ *         key={i}
+ *         ref={(el) => { itemRefs.current[i] = el; }}
+ *         role="option"
+ *         tabIndex={i === focusedIndex ? 0 : -1}
+ *       >
+ *         {item}
+ *       </div>
+ *     ))}
+ *   </div>
+ * );
+ * ```
+ */
+export function useKeyboardNavigation({
+  itemRefs,
+  focusedIndex,
+  setFocusedIndex,
+  itemCount,
+  orientation = 'vertical',
+  wrap = true,
+  onSelect,
+  onEscape,
+  getItemLabel,
+  disabled = false,
+  autoSelect = false,
+}: UseKeyboardNavigationOptions): UseKeyboardNavigationReturn {
+  // Buffer for type-ahead search
+  const searchBuffer = useRef('');
+  const searchTimeout = useRef<ReturnType<typeof setTimeout>>();
+
+  /**
+   * Focus a specific item by index.
+   */
+  const focusItem = useCallback(
+    (index: number) => {
+      const items = itemRefs.current;
+      if (items && items[index]) {
+        items[index]?.focus();
+        setFocusedIndex(index);
+        if (autoSelect) {
+          onSelect?.(index);
+        }
+      }
+    },
+    [itemRefs, setFocusedIndex, autoSelect, onSelect]
+  );
+
+  /**
+   * Navigate to the next item.
+   */
+  const navigateNext = useCallback(() => {
+    if (disabled || itemCount === 0) return;
+    const nextIndex = focusedIndex + 1;
+    if (nextIndex >= itemCount) {
+      if (wrap) focusItem(0);
+    } else {
+      focusItem(nextIndex);
+    }
+  }, [disabled, itemCount, focusedIndex, wrap, focusItem]);
+
+  /**
+   * Navigate to the previous item.
+   */
+  const navigatePrevious = useCallback(() => {
+    if (disabled || itemCount === 0) return;
+    const prevIndex = focusedIndex - 1;
+    if (prevIndex < 0) {
+      if (wrap) focusItem(itemCount - 1);
+    } else {
+      focusItem(prevIndex);
+    }
+  }, [disabled, itemCount, focusedIndex, wrap, focusItem]);
+
+  /**
+   * Navigate to the first item.
+   */
+  const navigateFirst = useCallback(() => {
+    if (disabled || itemCount === 0) return;
+    focusItem(0);
+  }, [disabled, itemCount, focusItem]);
+
+  /**
+   * Navigate to the last item.
+   */
+  const navigateLast = useCallback(() => {
+    if (disabled || itemCount === 0) return;
+    focusItem(itemCount - 1);
+  }, [disabled, itemCount, focusItem]);
+
+  /**
+   * Handle type-ahead search - jump to item starting with typed character(s).
+   */
+  const handleTypeAhead = useCallback(
+    (char: string) => {
+      if (!getItemLabel || disabled) return;
+
+      // Clear existing timeout
+      if (searchTimeout.current) {
+        clearTimeout(searchTimeout.current);
+      }
+
+      // Append character to search buffer
+      searchBuffer.current += char.toLowerCase();
+
+      // Find matching item starting from current index + 1
+      for (let i = 0; i < itemCount; i++) {
+        const index = (focusedIndex + i + 1) % itemCount;
+        const label = getItemLabel(index).toLowerCase();
+        if (label.startsWith(searchBuffer.current)) {
+          focusItem(index);
+          break;
+        }
+      }
+
+      // Clear buffer after 500ms of inactivity (standard type-ahead delay)
+      searchTimeout.current = setTimeout(() => {
+        searchBuffer.current = '';
+      }, 500);
+    },
+    [getItemLabel, disabled, itemCount, focusedIndex, focusItem]
+  );
+
+  /**
+   * Main keyboard event handler.
+   */
+  const handleKeyDown = useCallback(
+    (event: React.KeyboardEvent) => {
+      if (disabled) return;
+
+      const { key } = event;
+
+      // Handle arrow keys based on orientation
+      if (orientation === 'vertical' || orientation === 'both') {
+        if (key === 'ArrowDown') {
+          event.preventDefault();
+          navigateNext();
+          return;
+        }
+        if (key === 'ArrowUp') {
+          event.preventDefault();
+          navigatePrevious();
+          return;
+        }
+      }
+
+      if (orientation === 'horizontal' || orientation === 'both') {
+        if (key === 'ArrowRight') {
+          event.preventDefault();
+          navigateNext();
+          return;
+        }
+        if (key === 'ArrowLeft') {
+          event.preventDefault();
+          navigatePrevious();
+          return;
+        }
+      }
+
+      // Common navigation keys
+      switch (key) {
+        case 'Home':
+          event.preventDefault();
+          navigateFirst();
+          break;
+
+        case 'End':
+          event.preventDefault();
+          navigateLast();
+          break;
+
+        case 'Enter':
+        case ' ':
+          // Space should only select if we're not in a text input
+          if (key === ' ' && event.target instanceof HTMLInputElement) {
+            return; // Let the input handle the space
+          }
+          event.preventDefault();
+          onSelect?.(focusedIndex);
+          break;
+
+        case 'Escape':
+          event.preventDefault();
+          onEscape?.();
+          break;
+
+        default:
+          // Type-ahead for printable characters
+          if (key.length === 1 && /[a-zA-Z0-9]/.test(key)) {
+            handleTypeAhead(key);
+          }
+      }
+    },
+    [
+      disabled,
+      orientation,
+      navigateNext,
+      navigatePrevious,
+      navigateFirst,
+      navigateLast,
+      onSelect,
+      onEscape,
+      focusedIndex,
+      handleTypeAhead,
+    ]
+  );
+
+  return {
+    handleKeyDown,
+    focusItem,
+    navigateNext,
+    navigatePrevious,
+    navigateFirst,
+    navigateLast,
+  };
+}

package/src/utils/index.ts

@@ -18,3 +18,6 @@ export {
 
 // General style helpers
 export { deepMerge, isPlainObject } from './styleHelpers';
+
+// Accessibility utilities
+export * from './accessibility';