@multiplatform.one/forms 6.0.0

package/src/hooks/useFocusManagement.spec.tsx

@@ -0,0 +1,289 @@
+/**
+ * @vitest-environment jsdom
+ */
+
+import { act } from "@testing-library/react";
+import { beforeAll, describe, expect, it, vi } from "vitest";
+import { renderWithProviders } from "@multiplatform.one/test-utils";
+import {
+  useFocusManagement,
+  useOTPFocusManagement,
+  useSearchableDropdownFocus,
+} from "./useFocusManagement";
+
+// Mock HTMLElement methods
+const mockFocus = vi.fn();
+const mockContains = vi.fn();
+
+beforeAll(() => {
+  // Mock HTMLElement.prototype.focus
+  Object.defineProperty(HTMLElement.prototype, "focus", {
+    writable: true,
+    value: mockFocus,
+  });
+
+  // Mock HTMLElement.prototype.contains
+  Object.defineProperty(HTMLElement.prototype, "contains", {
+    writable: true,
+    value: mockContains,
+  });
+
+  // Mock document.activeElement
+  Object.defineProperty(document, "activeElement", {
+    writable: true,
+    value: null,
+  });
+
+  // Mock querySelectorAll
+  const mockQuerySelectorAll = vi.fn();
+  Object.defineProperty(HTMLElement.prototype, "querySelectorAll", {
+    writable: true,
+    value: mockQuerySelectorAll,
+  });
+});
+
+describe("useFocusManagement", () => {
+  describe("basic functionality", () => {
+    it("should return the correct interface", () => {
+      const TestComponent = () => {
+        const focusManagement = useFocusManagement();
+
+        expect(focusManagement).toHaveProperty("containerRef");
+        expect(focusManagement).toHaveProperty("focusedElement");
+        expect(focusManagement).toHaveProperty("focusNext");
+        expect(focusManagement).toHaveProperty("focusPrevious");
+        expect(focusManagement).toHaveProperty("focusElement");
+        expect(focusManagement).toHaveProperty("getFocusableElements");
+        expect(focusManagement).toHaveProperty("setFocusTrap");
+
+        expect(typeof focusManagement.containerRef).toBe("object");
+        expect(typeof focusManagement.focusNext).toBe("function");
+        expect(typeof focusManagement.focusPrevious).toBe("function");
+        expect(typeof focusManagement.focusElement).toBe("function");
+        expect(typeof focusManagement.getFocusableElements).toBe("function");
+        expect(typeof focusManagement.setFocusTrap).toBe("function");
+
+        return null;
+      };
+
+      renderWithProviders(<TestComponent />);
+    });
+
+    it("should initialize with default options", () => {
+      const TestComponent = () => {
+        const focusManagement = useFocusManagement();
+
+        expect(focusManagement.containerRef.current).toBeNull();
+        expect(focusManagement.focusedElement).toBeNull();
+
+        return null;
+      };
+
+      renderWithProviders(<TestComponent />);
+    });
+  });
+
+  describe("container ref", () => {
+    it("should provide a container ref", () => {
+      let refValue: any = null;
+
+      const TestComponent = () => {
+        const focusManagement = useFocusManagement();
+        refValue = focusManagement.containerRef;
+
+        return (
+          <div ref={focusManagement.containerRef as any} data-testid="container">
+            <button type="button">Test Button</button>
+          </div>
+        );
+      };
+
+      renderWithProviders(<TestComponent />);
+
+      expect(refValue).toHaveProperty("current");
+    });
+  });
+
+  describe("focusable elements detection", () => {
+    it("should return empty array when no container", () => {
+      const TestComponent = () => {
+        const focusManagement = useFocusManagement();
+
+        const elements = focusManagement.getFocusableElements();
+        expect(elements).toHaveLength(0);
+
+        return null;
+      };
+
+      renderWithProviders(<TestComponent />);
+    });
+  });
+
+  describe("initial focus", () => {
+    it("should not set initial focus when set to none", () => {
+      const TestComponent = () => {
+        const focusManagement = useFocusManagement({
+          initialFocus: "none",
+        });
+
+        return <div ref={focusManagement.containerRef as any}>Test</div>;
+      };
+
+      renderWithProviders(<TestComponent />);
+      expect(mockFocus).not.toHaveBeenCalled();
+    });
+  });
+
+  describe("auto focus delay", () => {
+    it("should delay initial focus", () => {
+      vi.useFakeTimers();
+
+      const mockElement = { focus: vi.fn() };
+
+      HTMLElement.prototype.querySelectorAll = vi.fn(() => ({
+        [Symbol.iterator]: function* () {
+          yield mockElement;
+        },
+      })) as any;
+
+      const TestComponent = () => {
+        const focusManagement = useFocusManagement({
+          initialFocus: "first",
+          autoFocusDelay: 1000,
+        });
+
+        return <div ref={focusManagement.containerRef as any}>Test</div>;
+      };
+
+      renderWithProviders(<TestComponent />);
+
+      expect(mockElement.focus).not.toHaveBeenCalled();
+
+      act(() => {
+        vi.advanceTimersByTime(1000);
+      });
+
+      expect(mockElement.focus).toHaveBeenCalled();
+
+      vi.useRealTimers();
+    });
+  });
+
+  describe("focus change callback", () => {
+    it("should call onFocusChange when focus changes", () => {
+      const onFocusChange = vi.fn();
+      let testFocusManagement: any;
+
+      const TestComponent = () => {
+        testFocusManagement = useFocusManagement({
+          onFocusChange,
+        });
+
+        return <div ref={testFocusManagement.containerRef as any}>Test</div>;
+      };
+
+      renderWithProviders(<TestComponent />);
+
+      const mockElement = { focus: vi.fn() };
+      act(() => {
+        testFocusManagement.focusElement(mockElement as any);
+      });
+
+      expect(onFocusChange).toHaveBeenCalledWith(mockElement);
+    });
+  });
+
+  describe("restore focus", () => {
+    it("should restore focus when enabled", () => {
+      const mockPreviouslyFocused = { focus: vi.fn() };
+      Object.defineProperty(document, "activeElement", {
+        value: mockPreviouslyFocused,
+      });
+
+      const TestComponent = () => {
+        const focusManagement = useFocusManagement({
+          restoreFocus: true,
+        });
+
+        return <div ref={focusManagement.containerRef as any}>Test</div>;
+      };
+
+      const { unmount } = renderWithProviders(<TestComponent />);
+      unmount();
+
+      expect(mockPreviouslyFocused.focus).toHaveBeenCalled();
+    });
+
+    it("should not restore focus when disabled", () => {
+      const mockPreviouslyFocused = { focus: vi.fn() };
+      Object.defineProperty(document, "activeElement", {
+        value: mockPreviouslyFocused,
+      });
+
+      const TestComponent = () => {
+        const focusManagement = useFocusManagement({
+          restoreFocus: false,
+        });
+
+        return <div ref={focusManagement.containerRef as any}>Test</div>;
+      };
+
+      const { unmount } = renderWithProviders(<TestComponent />);
+      unmount();
+
+      expect(mockPreviouslyFocused.focus).not.toHaveBeenCalled();
+    });
+  });
+});
+
+describe("useOTPFocusManagement", () => {
+  it("should return the correct interface", () => {
+    const TestComponent = () => {
+      const otpFocus = useOTPFocusManagement(6);
+
+      expect(otpFocus).toHaveProperty("focusedIndex");
+      expect(otpFocus).toHaveProperty("focusInput");
+      expect(otpFocus).toHaveProperty("handleKeyPress");
+      expect(otpFocus).toHaveProperty("setInputRef");
+
+      expect(typeof otpFocus.focusInput).toBe("function");
+      expect(typeof otpFocus.handleKeyPress).toBe("function");
+      expect(typeof otpFocus.setInputRef).toBe("function");
+
+      return null;
+    };
+
+    renderWithProviders(<TestComponent />);
+  });
+});
+
+describe("useSearchableDropdownFocus", () => {
+  it("should return the correct interface", () => {
+    const TestComponent = () => {
+      const dropdownFocus = useSearchableDropdownFocus(true, []);
+
+      expect(dropdownFocus).toHaveProperty("highlightedIndex");
+      expect(dropdownFocus).toHaveProperty("setHighlightedIndex");
+      expect(dropdownFocus).toHaveProperty("handleKeyDown");
+
+      expect(typeof dropdownFocus.setHighlightedIndex).toBe("function");
+      expect(typeof dropdownFocus.handleKeyDown).toBe("function");
+
+      return null;
+    };
+
+    renderWithProviders(<TestComponent />);
+  });
+
+  it("should reset highlighted index when closed", () => {
+    const TestComponent = () => {
+      const dropdownFocus = useSearchableDropdownFocus(false, ["Item 1"]);
+
+      expect(dropdownFocus.highlightedIndex).toBe(-1);
+
+      return null;
+    };
+
+    renderWithProviders(<TestComponent />);
+  });
+});

package/src/hooks/useFocusManagement.ts

@@ -0,0 +1,384 @@
+import { type RefObject, useCallback, useEffect, useRef, useState } from "react";
+import { isWeb } from "tamagui";
+
+export interface FocusManagementOptions {
+  /**
+   * Whether to trap focus within the container
+   */
+  trapFocus?: boolean;
+
+  /**
+   * Whether to restore focus to the previously focused element when unmounting
+   */
+  restoreFocus?: boolean;
+
+  /**
+   * Initial focus behavior
+   */
+  initialFocus?: "first" | "none" | HTMLElement;
+
+  /**
+   * Auto-focus delay in milliseconds
+   */
+  autoFocusDelay?: number;
+
+  /**
+   * Callback when focus changes
+   */
+  onFocusChange?: (element: HTMLElement | null) => void;
+}
+
+export interface FocusManagementReturn {
+  /**
+   * Ref to attach to the container element
+   */
+  containerRef: RefObject<HTMLElement | null>;
+
+  /**
+   * Current focused element
+   */
+  focusedElement: HTMLElement | null;
+
+  /**
+   * Focus the next focusable element
+   */
+  focusNext: () => void;
+
+  /**
+   * Focus the previous focusable element
+   */
+  focusPrevious: () => void;
+
+  /**
+   * Focus a specific element
+   */
+  focusElement: (element: HTMLElement) => void;
+
+  /**
+   * Get all focusable elements within the container
+   */
+  getFocusableElements: () => HTMLElement[];
+
+  /**
+   * Manually set focus trap
+   */
+  setFocusTrap: (enabled: boolean) => void;
+}
+
+/**
+ * Hook for advanced focus management within a container
+ */
+export function useFocusManagement(options: FocusManagementOptions = {}): FocusManagementReturn {
+  const {
+    trapFocus = false,
+    restoreFocus = true,
+    initialFocus = "none",
+    autoFocusDelay = 0,
+    onFocusChange,
+  } = options;
+
+  const containerRef = useRef<HTMLElement>(null);
+  const [focusedElement, setFocusedElement] = useState<HTMLElement | null>(null);
+  const [isFocusTrapped, setIsFocusTrapped] = useState(trapFocus);
+  const previouslyFocusedElement = useRef<HTMLElement | null>(null);
+  const hasAppliedInitialFocus = useRef(false);
+  const focusableSelectors = useRef([
+    "a[href]",
+    "button:not([disabled])",
+    "textarea:not([disabled])",
+    "input:not([disabled])",
+    "select:not([disabled])",
+    "[tabindex]:not([tabindex='-1'])",
+    "[contenteditable='true']",
+  ]);
+
+  // Get all focusable elements within the container, respecting tabIndex={-1}
+  // and the data-focus-skip attribute for elements that should be excluded
+  const getFocusableElements = useCallback((): HTMLElement[] => {
+    if (!containerRef.current) return [];
+
+    const elements = containerRef.current.querySelectorAll(focusableSelectors.current.join(", "));
+
+    return (Array.from(elements) as HTMLElement[]).filter((el) => {
+      if (el.tabIndex === -1) return false;
+      if (typeof el.closest === "function" && el.closest("[data-focus-skip]")) return false;
+      return true;
+    });
+  }, []);
+
+  // Focus a specific element
+  const focusElement = useCallback(
+    (element: HTMLElement) => {
+      if (element && typeof element.focus === "function") {
+        element.focus();
+        setFocusedElement(element);
+        onFocusChange?.(element);
+      }
+    },
+    [onFocusChange],
+  );
+
+  // Focus the next element
+  const focusNext = useCallback(() => {
+    const focusableElements = getFocusableElements();
+    if (focusableElements.length === 0) return;
+
+    const currentIndex = focusedElement ? focusableElements.indexOf(focusedElement) : -1;
+    const nextIndex = currentIndex < focusableElements.length - 1 ? currentIndex + 1 : 0;
+
+    focusElement(focusableElements[nextIndex]);
+  }, [focusedElement, getFocusableElements, focusElement]);
+
+  // Focus the previous element
+  const focusPrevious = useCallback(() => {
+    const focusableElements = getFocusableElements();
+    if (focusableElements.length === 0) return;
+
+    const currentIndex = focusedElement ? focusableElements.indexOf(focusedElement) : 0;
+    const prevIndex = currentIndex > 0 ? currentIndex - 1 : focusableElements.length - 1;
+
+    focusElement(focusableElements[prevIndex]);
+  }, [focusedElement, getFocusableElements, focusElement]);
+
+  // Handle keyboard navigation
+  const handleKeyDown = useCallback(
+    (event: KeyboardEvent) => {
+      if (!isFocusTrapped) return;
+
+      switch (event.key) {
+        case "Tab":
+          event.preventDefault();
+          if (event.shiftKey) {
+            focusPrevious();
+          } else {
+            focusNext();
+          }
+          break;
+        case "ArrowDown":
+          event.preventDefault();
+          focusNext();
+          break;
+        case "ArrowUp":
+          event.preventDefault();
+          focusPrevious();
+          break;
+        case "Home": {
+          event.preventDefault();
+          const firstElement = getFocusableElements()[0];
+          if (firstElement) focusElement(firstElement);
+          break;
+        }
+        case "End": {
+          event.preventDefault();
+          const focusableElements = getFocusableElements();
+          const lastElement = focusableElements[focusableElements.length - 1];
+          if (lastElement) focusElement(lastElement);
+          break;
+        }
+      }
+    },
+    [isFocusTrapped, focusNext, focusPrevious, getFocusableElements, focusElement],
+  );
+
+  // Handle focus events
+  const handleFocusIn = useCallback(
+    (event: FocusEvent) => {
+      const target = event.target as HTMLElement;
+      if (containerRef.current?.contains(target)) {
+        setFocusedElement(target);
+        onFocusChange?.(target);
+      }
+    },
+    [onFocusChange],
+  );
+
+  const handleFocusOut = useCallback(
+    (event: FocusEvent) => {
+      const relatedTarget = event.relatedTarget as HTMLElement;
+      if (!containerRef.current?.contains(relatedTarget)) {
+        setFocusedElement(null);
+        onFocusChange?.(null);
+      }
+    },
+    [onFocusChange],
+  );
+
+  // Set up focus trap
+  const setFocusTrap = useCallback((enabled: boolean) => {
+    setIsFocusTrapped(enabled);
+  }, []);
+
+  // Initialize focus management (web only)
+  useEffect(() => {
+    if (!isWeb) return;
+
+    const container = containerRef.current;
+    if (!container) return;
+
+    // Store previously focused element
+    if (restoreFocus && typeof document !== "undefined") {
+      previouslyFocusedElement.current = document.activeElement as HTMLElement;
+    }
+
+    // Add event listeners
+    container.addEventListener("keydown", handleKeyDown);
+    container.addEventListener("focusin", handleFocusIn);
+    container.addEventListener("focusout", handleFocusOut);
+
+    // Set initial focus only once per mount - effect re-runs when handlers change
+    // (e.g. when focusedElement updates) and must not steal focus from the user
+    let focusTimer: ReturnType<typeof setTimeout> | undefined;
+    if (initialFocus !== "none" && !hasAppliedInitialFocus.current) {
+      hasAppliedInitialFocus.current = true;
+      focusTimer = setTimeout(() => {
+        if (initialFocus === "first") {
+          const firstElement = getFocusableElements()[0];
+          if (firstElement) focusElement(firstElement);
+        } else if (initialFocus instanceof HTMLElement) {
+          focusElement(initialFocus);
+        }
+      }, autoFocusDelay);
+    }
+
+    return () => {
+      if (focusTimer !== undefined) clearTimeout(focusTimer);
+      container.removeEventListener("keydown", handleKeyDown);
+      container.removeEventListener("focusin", handleFocusIn);
+      container.removeEventListener("focusout", handleFocusOut);
+    };
+  }, [
+    handleKeyDown,
+    handleFocusIn,
+    handleFocusOut,
+    initialFocus,
+    autoFocusDelay,
+    getFocusableElements,
+    focusElement,
+    restoreFocus,
+  ]);
+
+  // Restore focus when unmounting (web only)
+  useEffect(() => {
+    if (!isWeb) return;
+    return () => {
+      if (restoreFocus && previouslyFocusedElement.current) {
+        previouslyFocusedElement.current.focus();
+      }
+    };
+  }, [restoreFocus]);
+
+  return {
+    containerRef,
+    focusedElement,
+    focusNext,
+    focusPrevious,
+    focusElement,
+    getFocusableElements,
+    setFocusTrap,
+  };
+}
+
+/**
+ * Hook for managing focus within OTP input groups
+ */
+export function useOTPFocusManagement(length: number, _onComplete?: (code: string) => void) {
+  const [focusedIndex, setFocusedIndex] = useState(-1);
+  const inputRefs = useRef<(HTMLInputElement | null)[]>(Array(length).fill(null));
+
+  const focusInput = useCallback(
+    (index: number) => {
+      if (index >= 0 && index < length && inputRefs.current[index]) {
+        inputRefs.current[index]?.focus();
+        setFocusedIndex(index);
+      }
+    },
+    [length],
+  );
+
+  const handleKeyPress = useCallback(
+    (index: number, key: string, value: string) => {
+      switch (key) {
+        case "Backspace":
+          if (!value && index > 0) {
+            focusInput(index - 1);
+          }
+          break;
+        case "ArrowLeft":
+          if (index > 0) focusInput(index - 1);
+          break;
+        case "ArrowRight":
+          if (index < length - 1) focusInput(index + 1);
+          break;
+        default:
+          // Auto-advance for digit input
+          if (/^\d$/.test(key) && value && index < length - 1) {
+            focusInput(index + 1);
+          }
+          break;
+      }
+    },
+    [length, focusInput],
+  );
+
+  const setInputRef = useCallback((index: number, ref: HTMLInputElement | null) => {
+    inputRefs.current[index] = ref;
+  }, []);
+
+  return {
+    focusedIndex,
+    focusInput,
+    handleKeyPress,
+    setInputRef,
+  };
+}
+
+/**
+ * Hook for managing focus in searchable dropdowns
+ */
+export function useSearchableDropdownFocus<TItem = unknown>(
+  isOpen: boolean,
+  items: TItem[],
+  onSelect?: (item: TItem) => void,
+) {
+  const [highlightedIndex, setHighlightedIndex] = useState(-1);
+
+  useEffect(() => {
+    if (!isOpen) {
+      setHighlightedIndex(-1);
+    }
+  }, [isOpen]);
+
+  const handleKeyDown = useCallback(
+    (event: KeyboardEvent) => {
+      if (!isOpen || items.length === 0) return;
+
+      switch (event.key) {
+        case "ArrowDown":
+          event.preventDefault();
+          setHighlightedIndex((prev) => (prev < items.length - 1 ? prev + 1 : 0));
+          break;
+        case "ArrowUp":
+          event.preventDefault();
+          setHighlightedIndex((prev) => (prev > 0 ? prev - 1 : items.length - 1));
+          break;
+        case "Enter":
+          event.preventDefault();
+          if (highlightedIndex >= 0 && highlightedIndex < items.length) {
+            onSelect?.(items[highlightedIndex]);
+          }
+          break;
+        case "Escape":
+          event.preventDefault();
+          setHighlightedIndex(-1);
+          break;
+      }
+    },
+    [isOpen, items, highlightedIndex, onSelect],
+  );
+
+  return {
+    highlightedIndex,
+    setHighlightedIndex,
+    handleKeyDown,
+  };
+}