Skip to content

An open source design system that's fully customizable and agent ready

TypeScript
23.0 KB
Raw Blame
// Copyright (c) Meta Platforms, Inc. and affiliates.

'use client';

/**
 * @file useFocusTrap.ts
 * @input Uses React useCallback, useEffect, useRef
 * @output Exports useFocusTrap, the internal focus-region Tab containment it
 *   composes, the deprecated Escape-state shim, and an
 *   internal compatibility-signal hook
 * @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';
import {isFocusLost} from '../utils/focusReturn';
import {isHTMLElement} from '../utils/nodeType';

import {FOCUSABLE_SELECTOR} from './focusableSelector';
import {useLayerDismissal} from '../Layer/useLayerDismissal';

// Escape-dismissible focus traps currently mounted. This is the whole state
// behind `hasActiveFocusTrapEscape`, which predates the shared stack and must
// keep answering about focus traps alone — the stack now carries families that
// never trapped focus (tooltips, hover cards), and counting those would tell
// callers a trap is above them when none is.
let activeEscapeTrapCount = 0;

/**
 * Whether an Escape-dismissible focus trap is currently active — a Popover,
 * menu or other trapped layer that would take an Escape press.
 *
 * @deprecated The focus trap no longer owns Escape coordination — every overlay
 *   family shares one stack (`useLayerDismissal`), which routes each press to
 *   the top-most layer. A layer that wants the same ordering should join the
 *   stack rather than ask whether a trap exists.
 */
export function hasActiveFocusTrapEscape(): boolean {
  return activeEscapeTrapCount > 0;
}

/**
 * Keep the deprecated `hasActiveFocusTrapEscape` signal accurate for a focus
 * trap whose Escape is coordinated by another registration in the shared
 * stack. This hook is intentionally internal (not re-exported from `hooks`): it
 * preserves the released read-only compatibility signal without creating a
 * second dismissal owner.
 */
export function useFocusTrapEscapeCompatibilitySignal(isActive: boolean): void {
  // Syncs the module count of active Escape traps with `isActive`. The
  // compatibility signal reads this count.
  useEffect(() => {
    if (!isActive) {
      return;
    }
    activeEscapeTrapCount += 1;
    return () => {
      activeEscapeTrapCount -= 1;
    };
  }, [isActive]);
}

/**
 * Whether an element is shown as a popover. jsdom and browsers without the
 * Popover API do not recognize `:popover-open`, and nothing is popover-open
 * there.
 */
function isPopoverOpen(el: Element): boolean {
  try {
    return el.matches(':popover-open');
  } catch {
    return false;
  }
}

/**
 * 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, 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]')) {
    return false;
  }
  if (el.hidden || el.closest('[hidden]')) {
    return false;
  }
  // A closed <dialog> renders nothing, so nothing inside it can take focus.
  // A dialog shown with showPopover() (a non-modal sheet or drawer) never
  // sets `open`, so it counts as shown while it is popover-open.
  for (
    let dialog = el.closest('dialog');
    dialog != null;
    dialog = dialog.parentElement?.closest('dialog') ?? null
  ) {
    if (!dialog.open && !isPopoverOpen(dialog)) {
      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) {
    const style = window.getComputedStyle(el);
    if (style.visibility === 'hidden' || style.display === 'none') {
      return false;
    }
  }
  return true;
}

/**
 * Get all focusable elements within a container.
 *
 * Exported for menus that place their own Tab stops inside a trapped layer
 * (DropdownMenu's header and footer), so they judge reachability exactly as
 * the trap does. Not re-exported from the package's `hooks` entry.
 */
export function getFocusableElements(container: HTMLElement): HTMLElement[] {
  return Array.from(
    container.querySelectorAll<HTMLElement>(FOCUSABLE_SELECTOR),
  ).filter(isVisiblyFocusable);
}

/**
 * The name of a named native radio, or null for any other element and for an
 * unnamed radio, which is its own Tab stop.
 */
function radioNameOf(el: Element): string | null {
  if (!el.matches('input[type="radio"][name]')) {
    return null;
  }
  return (el as HTMLInputElement).name || null;
}

/**
 * Whether two radios are one group: the same name and the same form owner (or
 * both with no form).
 */
function isSameRadioGroup(a: Element, b: Element): boolean {
  const name = radioNameOf(a);
  return (
    name != null &&
    name === radioNameOf(b) &&
    (a as HTMLInputElement).form === (b as HTMLInputElement).form
  );
}

/**
 * Drop the radios the browser skips for Tab, leaving every other element, and
 * each kept radio, at its own place. In a named group the browser stops only at
 * the focused radio, else the checked one; a group with nothing checked keeps
 * every radio, so a forward entry reaches its first and a backward entry its
 * last.
 *
 * Exported for menus that walk their own Tab stops (DropdownMenu's header and
 * footer), so they skip radios exactly as the focus region does.
 */
export function collapseRadioGroups(
  elements: HTMLElement[],
  active: Element | null,
): HTMLElement[] {
  return elements.filter(el => {
    if (radioNameOf(el) == null) {
      return true;
    }
    if (active != null && isSameRadioGroup(el, active)) {
      return el === active;
    }
    return (
      (el as HTMLInputElement).checked ||
      !elements.some(
        other =>
          isSameRadioGroup(el, other) && (other as HTMLInputElement).checked,
      )
    );
  });
}

/**
 * The document a trap lives in: its container's. An app that renders into a
 * same-origin iframe or a Document Picture-in-Picture window through a portal
 * puts the trap in that window's document, whose key presses and focus
 * changes never reach this module's global `document`.
 */
function trapDocument(container: HTMLElement | null): Document {
  return container?.ownerDocument ?? document;
}

/**
 * Whether node `a` comes before node `b` in document order.
 */
function precedes(a: Node, b: Node): boolean {
  return (
    (a.compareDocumentPosition(b) & Node.DOCUMENT_POSITION_FOLLOWING) !== 0
  );
}

/**
 * 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 element.ownerDocument.activeElement === element;
}

/**
 * Wrap focus to `target` for a Tab press, and cancel the press only when the
 * target took focus. A target the browser refuses (inert behind a modal
 * layered over this region) leaves the press to the browser instead of
 * stranding focus where it was.
 */
function wrapFocus(event: KeyboardEvent, target: HTMLElement): void {
  if (attemptFocus(target)) {
    event.preventDefault();
  }
}

/**
 * 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;
}

// Containers of the focus regions currently active, in every document. A Tab
// is answered by the innermost region that holds focus, so regions that nest
// in the DOM never fight over one key press.
const activeRegionContainers = new Set<HTMLElement>();

function hasInnerRegionHolding(
  container: HTMLElement,
  active: Element,
): boolean {
  // An open <dialog> nested in the region that holds focus is its own focus
  // context (a modal step over a covered sheet): it answers Tab, not us.
  const dialog = active.closest('dialog[open]');
  if (dialog != null && dialog !== container && container.contains(dialog)) {
    return true;
  }
  for (const other of activeRegionContainers) {
    if (
      other !== container &&
      container.contains(other) &&
      other.contains(active)
    ) {
      return true;
    }
  }
  return false;
}

/**
 * Tab containment for a focus region: Tab and Shift+Tab pressed inside wrap at
 * either end, and a Tab that starts outside is left to the page. When regions
 * nest, the innermost one holding focus answers.
 *
 * `useFocusTrap` composes this. Dialog, BottomSheet and Lightbox call it
 * directly, because their native lifecycle already owns focus entry and
 * return. Internal: not re-exported from `hooks`.
 */
export function useFocusRegionContainment(
  containerRef: React.RefObject<HTMLElement | null>,
  isActive: boolean,
): void {
  const lastFocusRef = useRef<Element | null>(null);
  // Track if focus change was triggered by keyboard (Tab key)
  const isKeyboardNavigationRef = useRef(false);

  useEffect(() => {
    const container = containerRef.current;
    if (!isActive || container == null) {
      return;
    }
    activeRegionContainers.add(container);
    return () => {
      activeRegionContainers.delete(container);
    };
  }, [containerRef, isActive]);

  /**
   * Handle focus events - redirect focus back into container if it escapes.
   * Only redirects for keyboard navigation, not mouse clicks.
   */
  useEffect(() => {
    if (!isActive) {
      return;
    }

    const doc = trapDocument(containerRef.current);

    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
        const focusedFirst = focusFirstDescendant(container);

        // If we're back at the same element (Shift+Tab from first element),
        // try focusing the last element instead
        if (focusedFirst && lastFocusRef.current === doc.activeElement) {
          focusLastDescendant(container);
        } else if (
          !focusedFirst &&
          isHTMLElement(lastFocusRef.current) &&
          container.contains(lastFocusRef.current)
        ) {
          // A modal surface may intentionally have no tabbable controls and
          // place initial focus on a tabIndex={-1} heading or panel. Preserve
          // that programmatic focus target instead of letting Tab escape.
          attemptFocus(lastFocusRef.current);
        }

        lastFocusRef.current = doc.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
    doc.addEventListener('focus', handleFocus, true);

    return () => {
      doc.removeEventListener('focus', handleFocus, true);
    };
  }, [containerRef, isActive]);

  /**
   * Handle Tab key to wrap focus at boundaries. Also tracks that keyboard
   * navigation is occurring.
   *
   * No Escape here, and no IME guard: the shared layer dismissal stack owns
   * that press, and each surface that applies a region decides its own
   * dismissal (`useFocusTrap` through its `onEscape`).
   */
  useEffect(() => {
    if (!isActive) {
      return;
    }

    const doc = trapDocument(containerRef.current);

    const handleKeyDown = (event: KeyboardEvent) => {
      const container = containerRef.current;
      if (!container) {
        return;
      }

      if (event.key === 'Tab') {
        if (event.defaultPrevented) {
          // A control that handles Tab itself (an editor that indents) keeps
          // focus where it is.
          return;
        }
        const active = doc.activeElement;
        // Any focused node counts, not only HTML elements: an SVG control
        // inside the container is still inside.
        if (active == null || !container.contains(active)) {
          // The trap contains focus that is inside it; it does not pull in a
          // Tab pressed elsewhere on the page. A layer can be open while focus
          // legitimately sits outside it — a listbox popup anchored to its own
          // input, a non-modal popover beside the content it annotates — and
          // capturing that Tab would take the rest of the page away from
          // keyboard users.
          return;
        }

        if (hasInnerRegionHolding(container, active)) {
          // A region nested in this one (a Dialog opened from a Dialog, a
          // Popover inside a Drawer) holds focus; that region answers Tab.
          return;
        }

        // Mark that keyboard navigation is leaving from inside the trap, so a
        // focus that lands outside is redirected back in.
        isKeyboardNavigationRef.current = true;

        const focusable = getFocusableElements(container);
        if (focusable.length === 0) {
          // There is nowhere to advance to. Keep focus on the current
          // programmatic target (for example a dialog panel with tabIndex=-1)
          // rather than allowing the browser to move into background content.
          event.preventDefault();
          lastFocusRef.current = active;
          isKeyboardNavigationRef.current = false;
          return;
        }

        // jsdom groups a selector list by selector, not in document order.
        const stops = collapseRadioGroups(
          [...focusable].sort((a, b) => (precedes(a, b) ? -1 : 1)),
          active,
        );
        const first = stops[0];
        const last = stops[stops.length - 1];

        if (doc.activeElement === container) {
          // Programmatic initial focus can sit on the trap container itself
          // (for example a dialog panel with no content controls). Move into
          // the tabbable cycle instead of letting Tab escape to the page.
          wrapFocus(event, event.shiftKey ? last : first);
          return;
        }

        // Programmatic focus can also sit on an element that is not a Tab stop
        // (a dialog title with tabIndex -1). Its place in document order
        // decides the edge: nothing tabbable before it means Shift+Tab is
        // leaving the region, nothing after it means Tab is.
        const isProgrammaticStop = !(focusable as Element[]).includes(active);
        if (event.shiftKey) {
          // Shift+Tab: if on (or before) the first element, wrap to last
          if (
            active === first ||
            (isProgrammaticStop && precedes(active, first))
          ) {
            wrapFocus(event, last);
          }
        } else {
          // Tab: if on (or after) the last element, wrap to first
          if (
            active === last ||
            (isProgrammaticStop && precedes(last, active))
          ) {
            wrapFocus(event, first);
          }
        }
      }
    };

    doc.addEventListener('keydown', handleKeyDown);

    return () => {
      doc.removeEventListener('keydown', handleKeyDown);
    };
  }, [containerRef, isActive]);
}

/**
 * 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 container's document
 * - Redirects focus back into the container if it escapes
 * - Handles both Tab and Shift+Tab navigation
 * - Restores focus to the element that was focused before activation when the
 *   trap deactivates or unmounts, unless focus was already moved elsewhere
 *   (so consumers that restore focus themselves are unaffected) or focus
 *   never entered the trap (so popups that keep focus on their trigger, like
 *   comboboxes, are unaffected)
 *
 * @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> {
  return useFocusTrapInternal<T>(options);
}

/**
 * Package-internal options. Not re-exported from the package entry point.
 */
interface InternalFocusTrapOptions extends UseFocusTrapOptions {
  /**
   * The element to restore focus to on deactivation, read at activation. For
   * an overlay that may move focus inside before the trap activates (initial
   * focus within the opening event), the element focused at activation is
   * already inside, so the overlay names its opener instead. Returning `null`
   * falls back to the element focused at activation.
   */
  getRestoreTarget?: () => HTMLElement | null;
}

export function useFocusTrapInternal<T extends HTMLElement = HTMLElement>(
  options: InternalFocusTrapOptions,
): UseFocusTrapReturn<T> {
  const {isActive, onEscape, getRestoreTarget} = options;
  const getRestoreTargetRef = useRef(getRestoreTarget);
  getRestoreTargetRef.current = getRestoreTarget;

  const containerRef = useRef<T | null>(null);

  // Tab and Shift+Tab wrap inside the container while the trap is active.
  useFocusRegionContainment(containerRef, isActive);

  // Join the shared layer dismissal stack. The trap no longer listens for
  // Escape itself: the stack owns one listener and routes each press to the
  // top-most layer, so a popover inside a Dialog, a submenu inside a menu, and
  // a modal inside a modal all peel off one at a time. A trap with no
  // `onEscape` is not dismissible and stays off the stack, so a press flows
  // past it to whatever is underneath.
  // One expression drives both the stack registration and the deprecated
  // `hasActiveFocusTrapEscape` count, so the two can never disagree about
  // whether this trap is active.
  const isEscapeTrap = isActive && onEscape != null;

  useLayerDismissal({
    isActive: isEscapeTrap,
    onDismiss: () => {
      onEscape?.();
    },
    // The trap renders nothing, so it cannot push a depth provider around its
    // content; hand the stack the container instead so two DOM-nested traps
    // still resolve in the right order.
    getContainer: () => containerRef.current,
  });

  useFocusTrapEscapeCompatibilitySignal(isEscapeTrap);

  /**
   * Focus the first focusable element.
   */
  const focusFirst = useCallback(() => {
    if (containerRef.current) {
      focusFirstDescendant(containerRef.current);
    }
  }, []);

  /**
   * Capture the element focused before the trap activated, and restore focus to
   * it when the trap deactivates (or the component unmounts). Overlays are
   * opened imperatively (e.g. `showPopover()`), so the browser's declarative
   * popover focus restoration does not apply — without this, closing a Popover
   * via Escape or light dismiss drops keyboard focus to `<body>`.
   *
   * The restore is guarded so it never steals focus a consumer moved on
   * purpose: it only runs when focus would otherwise be lost — i.e. the active
   * element is nothing, the document body/root, or still inside the (possibly
   * now-unmounted) trap container. If focus already moved to some other element
   * outside the trap (the user clicked elsewhere, or a consumer such as
   * DropdownMenu already refocused its trigger), the restore is a no-op.
   *
   * The restore is also skipped when focus never entered the trap while it
   * was active. Some popups — a Typeahead/PowerSearch listbox anchored to its
   * own input — deliberately keep DOM focus on the trigger and never move it
   * into the trap container (they open with `role: "none"` and
   * `hasAutoFocus: false`). For those, the restore would cancel a blur the
   * user asked for on outside-click dismissal, re-focusing the trigger so a
   * second click no longer fires a `focus` event and cannot reopen the menu.
   * Tracking `focusin` inside the container distinguishes "focus was here and
   * we should rescue it" from "focus was never here and we should leave it
   * alone" — popups that do take focus (Dialog, DropdownMenu, a Typeahead
   * option click) are unaffected.
   */
  useEffect(() => {
    if (!isActive) {
      return;
    }

    // Snapshot the container now; by cleanup it may be detached or unmounted.
    const container = containerRef.current;
    const doc = trapDocument(container);
    const previouslyFocused =
      getRestoreTargetRef.current?.() ??
      (doc.activeElement as HTMLElement | null);

    // Whether focus ever entered the trap container while it was active.
    // Initialized from the current active element in case focus was already
    // inside at activation (e.g. a programmatic focus before the effect ran).
    let hadFocusInside =
      container != null && container.contains(doc.activeElement);

    const markFocusInside = (event: FocusEvent) => {
      const target = event.target as Node | null;
      if (target != null && containerRef.current?.contains(target)) {
        hadFocusInside = true;
      }
    };
    doc.addEventListener('focusin', markFocusInside, true);

    return () => {
      doc.removeEventListener('focusin', markFocusInside, true);

      if (!hadFocusInside) {
        return;
      }

      if (!isFocusLost(container, doc)) {
        return;
      }

      if (
        previouslyFocused != null &&
        previouslyFocused.isConnected &&
        typeof previouslyFocused.focus === 'function'
      ) {
        previouslyFocused.focus();
      }
    };
  }, [isActive]);

  return {
    containerRef,
    focusFirst,
  };
}