Skip to content

AI media harness for planning, generating, and editing locally

TypeScript
4.4 KB
Raw Blame
/* useModalFocus — the focus half of a modal surface.

   While `active`:
   - focus moves into `ref` (to `initialFocus`, else the first element marked
     [data-autofocus], else the first focusable element in the container's
     body region [data-modal-body], else the first focusable at all, else the
     container itself);
   - Tab and Shift+Tab wrap inside the container;
   - focus that escapes (a click on the page behind, a script) is pulled back,
     except into a popup layer opened from inside the modal (a ComboBox list,
     a menu), which lives in its own portal;
   - when it ends, focus returns to whatever had it before, if that is still
     in the document.

   ContentDialog uses it; any other modal surface (a full-screen editor, a
   wizard) can too:

     const panel = useRef<HTMLDivElement>(null);
     useModalFocus(panel, { active: open });
*/

import { useLayoutEffect, useRef, type RefObject } from "react";
import { LAYER_ATTR, focusSafely, focusables } from "./internal";

export interface ModalFocusOptions {
  /** Default true. */
  active?: boolean;
  /** Element to focus first. */
  initialFocus?: RefObject<HTMLElement | null>;
  /** Fallback when the body has nothing focusable (ContentDialog: its default button). */
  fallbackFocus?: () => HTMLElement | null | undefined;
  /** Default true. */
  restoreFocus?: boolean;
}

export function useModalFocus(ref: RefObject<HTMLElement | null>, options: ModalFocusOptions = {}) {
  const { active = true, restoreFocus = true } = options;
  const opts = useRef(options);
  opts.current = options;

  useLayoutEffect(() => {
    if (!active) return;
    const container = ref.current;
    if (!container) return;
    const previous = document.activeElement as HTMLElement | null;

    const initial =
      opts.current.initialFocus?.current ??
      container.querySelector<HTMLElement>("[data-autofocus]") ??
      (() => {
        const body = container.querySelector<HTMLElement>("[data-modal-body]");
        return body ? focusables(body)[0] : undefined;
      })() ??
      opts.current.fallbackFocus?.() ??
      focusables(container)[0] ??
      container;
    if (initial === container && !container.hasAttribute("tabindex")) container.setAttribute("tabindex", "-1");
    focusSafely(initial);

    const onKeyDown = (event: KeyboardEvent) => {
      if (event.key !== "Tab" || event.defaultPrevented) return;
      const items = focusables(container);
      if (!items.length) { event.preventDefault(); return; }
      const first = items[0];
      const last = items[items.length - 1];
      const current = document.activeElement;
      if (event.shiftKey && (current === first || !container.contains(current))) {
        event.preventDefault();
        focusSafely(last);
      } else if (!event.shiftKey && (current === last || !container.contains(current))) {
        event.preventDefault();
        focusSafely(first);
      }
    };
    const onFocusIn = (event: FocusEvent) => {
      const target = event.target as Node | null;
      if (!target || container.contains(target)) return;
      // A popup layer opened later than this modal belongs to it.
      const layer = target instanceof Element ? target.closest(`[${LAYER_ATTR}]`) : null;
      if (layer && layer !== container && container.compareDocumentPosition(layer) & Node.DOCUMENT_POSITION_FOLLOWING) return;
      // Another modal stacked on top of this one owns focus.
      const modals = document.querySelectorAll('[aria-modal="true"]');
      const top = modals[modals.length - 1];
      if (top && top !== container && !top.contains(container)) return;
      focusSafely(focusables(container)[0] ?? container);
    };
    container.addEventListener("keydown", onKeyDown);
    document.addEventListener("focusin", onFocusIn);
    return () => {
      container.removeEventListener("keydown", onKeyDown);
      document.removeEventListener("focusin", onFocusIn);
      // Synchronously: during unmount the dialog is still in the document,
      // so focus moves straight from it to the opener with no stop at <body>.
      // A modal opened on top of this one keeps the focus it took.
      if (restoreFocus && previous && previous !== document.body && previous.isConnected) {
        const now = document.activeElement;
        const stolen = now && now !== document.body && !container.contains(now) && now.closest('[aria-modal="true"]');
        if (!stolen) focusSafely(previous);
      }
    };
  }, [active, ref, restoreFocus]);
}