Overlays

/**
 * An overlay: a surface shown above the interface, attached to the control that
 * opened it — or to a point, as a context menu is. `popover="manual"` puts it in
 * the top layer, above everything, and CSS anchor positioning places it,
 * flipping when it does not fit.
 *
 * Dismissal is done here rather than by `popover="auto"`, whose light dismiss
 * differs between engines when an overlay opens on a press — which a menu must,
 * so the pointer can be dragged to an item. The open overlays of a document form
 * one stack:
 *
 * - Escape closes the topmost.
 * - A press closes every overlay above the one it lands in. The control that
 *   opened an overlay counts as inside it, so pressing it toggles.
 * - Focus that moves outside every overlay closes them all.
 * - Closing an overlay, however it is closed, closes every overlay above it.
 *
 * Focus moves in when an overlay opens and returns when it closes — to its
 * control, or with none to whatever had focus before — unless the person has
 * already put it somewhere else.
 *
 * On a phone an overlay is a sheet, and a sheet is modal: the rest of the page
 * is inert and does not scroll, a swipe down closes it, and so does the
 * platform's way back where the browser tells of it. An overlay that blocks —
 * a dialog — is modal in that way on every screen.
 */
import { useCallback, useId, useLayoutEffect, useMemo, useRef, useState, useSyncExternalStore } from "react";
import type { CSSProperties, RefCallback } from "react";
import { useControllableState } from "./use-controllable-state.ts";

/** Where an overlay sits relative to its anchor, in logical terms. */
export type Placement = "block-end" | "block-start" | "inline-end";

const FLIPS: Record<Placement, string> = {
  "block-end": "flip-block, flip-inline, flip-block flip-inline",
  "block-start": "flip-block, flip-inline, flip-block flip-inline",
  "inline-end": "flip-inline, flip-block, flip-inline flip-block",
};

const AREAS: Record<Placement, string> = {
  // Below, aligned to the anchor's start edge, extending toward its end.
  "block-end": "block-end span-inline-end",
  "block-start": "block-start span-inline-end",
  // Beside, aligned to the anchor's top: a submenu.
  "inline-end": "inline-end span-block-end",
};

/**
 * The anchoring, as classes reading the variables the content is given. Classes
 * rather than inline style so a presentation can override them — a sheet on a
 * phone sets its own `position-area` and insets.
 */
export const anchoredClassName =
  "[inset:var(--overlay-inset,auto)] m-0 [position-anchor:var(--overlay-anchor)] [position-area:var(--overlay-area)] [position-try-fallbacks:var(--overlay-fallbacks)]";

/** How near a viewport edge an overlay that fits on neither side of its point is held. */
const EDGE = 8;

type Insets = [top: string, right: string, bottom: string, left: string];

/**
 * A placement against a point, as insets from it. In physical terms chosen from
 * the overlay's own direction: a position area is resolved in the direction of
 * the page, which a part of it written the other way does not share.
 */
function insetsFor(placement: Placement, rtl: boolean): Insets {
  const insets: Insets = ["auto", "auto", "auto", "auto"];
  const inline = rtl ? 1 : 3;
  if (placement === "inline-end") {
    insets[0] = "anchor(top)";
    insets[inline] = rtl ? "anchor(left)" : "anchor(right)";
  } else {
    insets[placement === "block-end" ? 0 : 2] = placement === "block-end" ? "anchor(bottom)" : "anchor(top)";
    insets[inline] = rtl ? "anchor(right)" : "anchor(left)";
  }
  return insets;
}

interface Layer {
  readonly content: HTMLElement;
  readonly trigger: () => HTMLElement | null;
  readonly close: () => void;
  readonly modal: () => boolean;
  /** Whether the rest of the page is inert behind it on every screen, not only as a sheet. */
  readonly blocking: boolean;
  /** Whether a press outside closes it. */
  readonly dismissible: () => boolean;
  /** On a phone, whether it takes the place of the sheet it was opened from. */
  readonly replaces: boolean;
  /** Show it again, above whatever has been shown since: its parent, when both began open. */
  readonly raise: () => void;
  /** Undo what it did to the page around it, ahead of its closing. */
  release: () => void;
}

/** The open overlays of one document, lowest first, and what listens for them. */
interface Root {
  readonly document: Document;
  readonly stack: Layer[];
  // The rest of a press that only dismissed: its mouse events must not reach what was under it.
  consuming: AbortController | undefined;
  readonly listening: AbortController;
}

const roots = new WeakMap<Document, Root>();

function contains(layer: Layer, path: readonly EventTarget[]): boolean {
  const trigger = layer.trigger();
  return path.includes(layer.content) || (trigger !== null && path.includes(trigger));
}

/** Close a layer and everything above it, topmost first. */
function closeFrom(root: Root, index: number): void {
  for (const layer of root.stack.slice(Math.max(index, 0)).toReversed()) layer.close();
}

const SHEET = "(pointer: coarse) and (width < 40rem)";

/** Whether overlays are presented as sheets: on a phone. A sheet is always modal. */
function isSheet(document: Document): boolean {
  return document.defaultView?.matchMedia(SHEET).matches ?? false;
}

function subscribeToSheet(onChange: () => void): () => void {
  const media = matchMedia(SHEET);
  media.addEventListener("change", onChange);
  return () => media.removeEventListener("change", onChange);
}

/**
 * Whether overlays are sheets here, for a part that only a sheet has: a way
 * back, a button that closes. A server renders for a screen where they are not.
 */
export function useSheet(): boolean {
  return useSyncExternalStore(
    subscribeToSheet,
    () => matchMedia(SHEET).matches,
    () => false,
  );
}

function closeTopmost(root: Root, event: KeyboardEvent): void {
  event.preventDefault();
  event.stopPropagation();
  closeFrom(root, root.stack.length - 1);
}

function isEscape(event: KeyboardEvent): boolean {
  // While an input method is composing, Escape is its own: it cancels the composition.
  return event.key === "Escape" && !event.isComposing && event.keyCode !== 229;
}

/** A sheet's backdrop is the sheet's own pseudo-element: a press there is outside it. */
function onBackdrop(layer: Layer, event: { target: EventTarget | null; clientX: number; clientY: number }) {
  if (event.target !== layer.content) return false;
  const box = layer.content.getBoundingClientRect();
  return (
    event.clientX < box.left ||
    event.clientX > box.right ||
    event.clientY < box.top ||
    event.clientY > box.bottom
  );
}

function consume(root: Root): void {
  root.consuming?.abort();
  const controller = new AbortController();
  root.consuming = controller;
  const stop = (event: Event) => {
    event.preventDefault();
    event.stopImmediatePropagation();
    if (event.type === "click") controller.abort();
  };
  for (const type of ["mousedown", "mouseup", "click"]) {
    root.document.addEventListener(type, stop, { capture: true, signal: controller.signal });
  }
  root.document.addEventListener("pointercancel", () => controller.abort(), {
    capture: true,
    signal: controller.signal,
  });
}

function rootOf(document: Document): Root {
  const existing = roots.get(document);
  if (existing !== undefined) return existing;
  const listening = new AbortController();
  const root: Root = { document, stack: [], consuming: undefined, listening };
  const { stack } = root;
  const { signal } = listening;

  // Escape with focus outside the topmost overlay is the overlay's at once. With
  // focus inside, what is inside hears it first — a field abandons what was
  // typed — and the overlay closes only if nothing claimed it.
  document.addEventListener(
    "keydown",
    (event) => {
      const top = stack.at(-1);
      if (top === undefined || !isEscape(event)) return;
      if (!event.composedPath().includes(top.content)) closeTopmost(root, event);
    },
    { capture: true, signal },
  );
  document.addEventListener(
    "keydown",
    (event) => {
      if (stack.length > 0 && isEscape(event) && !event.defaultPrevented) closeTopmost(root, event);
    },
    { signal },
  );
  // Capture, so an open overlay hears a press before anything beneath it.
  document.addEventListener(
    "pointerdown",
    (event) => {
      root.consuming?.abort();
      const path = event.composedPath();
      const pressed = stack.findLastIndex((layer) => contains(layer, path) && !onBackdrop(layer, event));
      // One that a press outside does not close keeps open what lies beneath it.
      const inside = Math.max(
        pressed,
        stack.findLastIndex((layer) => !layer.dismissible()),
      );
      // A press outside what blocks the page goes nowhere: focus stays where it was.
      if (stack.slice(pressed + 1).some((layer) => layer.blocking) && event.button === 0) {
        event.preventDefault();
      }
      const closing = stack.slice(inside + 1);
      if (closing.length === 0) return;
      // A press that dismisses a menu does nothing else, as in a platform's own
      // menus — unless it is on another control that opens one, so that moving
      // from menu to menu takes one press.
      const modal = isSheet(document) || closing.some((layer) => layer.modal() || layer.blocking);
      // By what it is rather than by its class: an element of another document is not this one's `Element`.
      const opener = path.some(
        (node) => (node as Node).nodeType === 1 && (node as Element).hasAttribute("aria-haspopup"),
      );
      closeFrom(root, inside + 1);
      if (modal && !opener && event.button === 0) {
        event.preventDefault();
        consume(root);
      }
    },
    { capture: true, signal },
  );
  // Focus that goes outside every overlay — by Tab, or by a script — leaves them closed behind it.
  document.addEventListener(
    "focusin",
    (event) => {
      const path = event.composedPath();
      if (!stack.some((layer) => contains(layer, path))) closeFrom(root, 0);
    },
    { capture: true, signal },
  );
  roots.set(document, root);
  return root;
}

/** The layer this one was opened from: the nearest beneath it that holds it. */
function parentOf(root: Root, layer: Layer): Layer | undefined {
  const index = root.stack.indexOf(layer);
  return root.stack.slice(0, Math.max(index, 0)).findLast((below) => below.content.contains(layer.content));
}

/** A sheet and the sheets beneath whose place it has taken: to a finger, one sheet. */
function sheetOf(root: Root, layer: Layer): Layer[] {
  const layers = [layer];
  for (let current = layer; current.replaces;) {
    const parent = parentOf(root, current);
    if (parent === undefined) break;
    layers.push(parent);
    current = parent;
  }
  return layers;
}

const inert = new WeakMap<Element, number>();

/**
 * Make everything but the sheet inert, so assistive technology and the keyboard
 * stay within it as a pointer does. Counted, so sheets may nest, and what was
 * already inert by its owner's hand is left as it was found.
 */
function isolate(content: HTMLElement): () => void {
  const held: Element[] = [];
  const { body } = content.ownerDocument;
  for (let node: Element = content; node !== body && node.parentElement !== null; node = node.parentElement) {
    for (const sibling of node.parentElement.children) {
      const count = inert.get(sibling) ?? 0;
      if (sibling === node || (count === 0 && sibling.hasAttribute("inert"))) continue;
      sibling.setAttribute("inert", "");
      inert.set(sibling, count + 1);
      held.push(sibling);
    }
  }
  return () => {
    for (const element of held) {
      const count = (inert.get(element) ?? 1) - 1;
      if (count > 0) {
        inert.set(element, count);
      } else {
        inert.delete(element);
        element.removeAttribute("inert");
      }
    }
  };
}

const locks = new WeakMap<Document, { count: number; overflow: string; gutter: string }>();

/**
 * Keep the page behind a sheet or a dialog from scrolling, and put back exactly
 * what it had. A scrollbar that took room keeps its room, so that the page does
 * not shift sideways under the scrim.
 */
function lockScroll(document: Document): () => void {
  const root = document.documentElement;
  const view = document.defaultView;
  const lock = locks.get(document) ?? {
    count: 0,
    overflow: root.style.overflow,
    gutter: root.style.scrollbarGutter,
  };
  if (lock.count === 0 && view !== null && view.innerWidth > root.clientWidth) {
    root.style.scrollbarGutter = "stable";
  }
  locks.set(document, lock);
  lock.count += 1;
  root.style.overflow = "hidden";
  return () => {
    lock.count -= 1;
    if (lock.count > 0) return;
    root.style.overflow = lock.overflow;
    root.style.scrollbarGutter = lock.gutter;
    locks.delete(document);
  };
}

interface CloseWatcherLike extends EventTarget {
  destroy: () => void;
}

/** The platform's way back — the back gesture on Android — where the browser tells of it. */
function watchForBack(document: Document, close: () => void): () => void {
  const Watcher = (document.defaultView as { CloseWatcher?: new () => CloseWatcherLike } | null)
    ?.CloseWatcher;
  if (Watcher === undefined) return () => {};
  try {
    const watcher = new Watcher();
    watcher.addEventListener("close", close);
    return () => watcher.destroy();
  } catch {
    // A browser may refuse one: there is then no way back to hear of.
    return () => {};
  }
}

/** A finger that has travelled less than this was still, for a tap. */
const SLOP = 8;
/** Pixels per millisecond: a flick down closes a sheet that has not been dragged far. */
const FLICK = 0.5;
/** Milliseconds of a finger's path that say how fast it was going. */
const TRAIL = 100;

function scrolled(target: EventTarget | null, content: HTMLElement): boolean {
  for (let node = target as HTMLElement | null; node !== null; node = node.parentElement) {
    if (node.scrollTop > 0) return true;
    if (node === content) break;
  }
  return false;
}

/**
 * A sheet follows a finger that drags it down, and on release closes if it was
 * dragged past a threshold or flicked, and returns otherwise. Touch events, not
 * pointer events: a browser cancels a touch pointer once it decides to scroll,
 * and only a touch move can tell it not to.
 */
function swipe(root: Root, layer: Layer): () => void {
  const { content } = layer;
  const controller = new AbortController();
  const { signal } = controller;
  let from: { x: number; y: number; time: number } | null = null;
  let dragging = false;
  let offset = 0;
  // Where the finger has just been, for how fast it was going when it lifted.
  let trail: Array<{ y: number; time: number }> = [];

  const move = (translate: string, transition: string) => {
    for (const { content: surface } of sheetOf(root, layer)) {
      surface.style.transition = transition;
      surface.style.translate = translate;
    }
  };

  content.addEventListener(
    "touchstart",
    (event) => {
      const touch = event.touches[0];
      dragging = false;
      from =
        event.touches.length === 1 &&
        touch !== undefined &&
        // Its own, not that of an overlay opened from within it, whose touches pass through here.
        (event.target as Element).closest("[popover]") === content &&
        !onBackdrop(layer, { target: event.target, clientX: touch.clientX, clientY: touch.clientY }) &&
        // What has been scrolled down scrolls back up first.
        !scrolled(event.target, content)
          ? { x: touch.clientX, y: touch.clientY, time: event.timeStamp }
          : null;
      trail = [{ y: 0, time: event.timeStamp }];
    },
    { passive: true, signal },
  );
  content.addEventListener(
    "touchmove",
    (event) => {
      const touch = event.touches[0];
      if (touch === undefined) return;
      if (from === null) return;
      const dx = touch.clientX - from.x;
      const dy = touch.clientY - from.y;
      if (!dragging) {
        // Decided by the first move, which is the one a browser lets be refused: after it, a
        // scroll has begun. Upward or sideways, the gesture is something else's.
        if (dy <= 0 || Math.abs(dx) > dy || !event.cancelable) {
          from = null;
          return;
        }
        dragging = true;
      }
      if (event.cancelable) event.preventDefault();
      offset = Math.max(0, dy);
      trail = [
        ...trail.filter((sample) => event.timeStamp - sample.time < TRAIL),
        { y: dy, time: event.timeStamp },
      ];
      move(`0 ${offset}px`, "none");
    },
    { passive: false, signal },
  );
  const release = (event: TouchEvent) => {
    const began = from;
    from = null;
    if (began === null || !dragging) return;
    dragging = false;
    // The finger that dragged the sheet did not also tap what was under it.
    if (offset > SLOP && event.cancelable) event.preventDefault();
    const far = offset > Math.min(content.offsetHeight / 3, 160);
    const [first, last] = [trail.at(0), trail.at(-1)];
    trail = [];
    const flicked =
      first !== undefined &&
      last !== undefined &&
      last !== first &&
      event.timeStamp - last.time < TRAIL &&
      (last.y - first.y) / (last.time - first.time) > FLICK;
    if (event.type === "touchend" && (far || flicked)) {
      // Onward from where it was let go, rather than back up to fade.
      move("0 100%", "");
      closeFrom(root, root.stack.indexOf(sheetOf(root, layer).at(-1) ?? layer));
    } else {
      move("", "");
    }
  };
  content.addEventListener("touchend", release, { signal });
  content.addEventListener("touchcancel", release, { signal });
  return () => {
    controller.abort();
    if (dragging) move("", "");
  };
}

/** What makes an overlay modal: the page behind it inert and still. */
function block(root: Root, layer: Layer): () => void {
  const { content } = layer;
  const undo = [isolate(content), lockScroll(root.document)];
  // Only a dialog may say it is modal; the rest of the page being inert says it for any role.
  const role = content.getAttribute("role");
  if ((role === "dialog" || role === "alertdialog") && !content.hasAttribute("aria-modal")) {
    content.setAttribute("aria-modal", "true");
    undo.push(() => content.removeAttribute("aria-modal"));
  }
  return () => {
    for (const step of undo.toReversed()) step();
  };
}

/** What makes a sheet of an overlay, for as long as it is one. */
function sheet(root: Root, layer: Layer): () => void {
  const { content } = layer;
  const undo = [watchForBack(root.document, layer.close), swipe(root, layer)];
  // What blocks is modal already, sheet or not.
  if (!layer.blocking) undo.unshift(block(root, layer));
  const parent = layer.replaces ? parentOf(root, layer) : undefined;
  if (parent !== undefined) {
    // Over the whole of the sheet beneath, under that sheet's scrim. Left in
    // place on closing, so that it does not shrink as it fades.
    content.dataset.overlayLevel = "";
    content.style.minHeight = `${parent.content.getBoundingClientRect().height}px`;
  }
  return () => {
    for (const step of undo.toReversed()) step();
  };
}

/** A sheet where overlays are sheets, and not where they are not, as the screen changes. */
function present(root: Root, layer: Layer): () => void {
  const blocked = layer.blocking ? block(root, layer) : undefined;
  const media = root.document.defaultView?.matchMedia(SHEET);
  if (media === undefined) return () => blocked?.();
  let undo: (() => void) | undefined;
  const update = () => {
    undo?.();
    delete layer.content.dataset.overlayLevel;
    layer.content.style.minHeight = "";
    undo = media.matches ? sheet(root, layer) : undefined;
  };
  update();
  media.addEventListener("change", update);
  return () => {
    media.removeEventListener("change", update);
    undo?.();
    blocked?.();
  };
}

/** Where focus goes when the overlay opens. */
export type InitialFocus = "first" | "last" | "content" | "none";

/** A point in the viewport, or with a size a rectangle of it, to place an overlay against. */
export interface OverlayPoint {
  readonly x: number;
  readonly y: number;
  readonly width?: number;
  readonly height?: number;
}

export interface OverlayOptions {
  open?: boolean | undefined;
  defaultOpen?: boolean | undefined;
  onOpenChange?: ((open: boolean) => void) | undefined;
  placement?: Placement | undefined;
  /** The elements `first` and `last` choose among; defaults to anything focusable. */
  focusable?: ((content: HTMLElement) => HTMLElement[]) | undefined;
  /**
   * Whether a press outside only dismisses, as with a menu, rather than also
   * acting on what it lands on, as with a popover beside the work it serves.
   */
  modal?: boolean | undefined;
  /**
   * Whether, on a phone, it takes the place of the sheet it was opened from —
   * one sheet under one scrim, closed together by a swipe — rather than rising
   * as a second sheet: a level of the same thing, as a submenu is. Its owner
   * gives it a way back.
   */
  replaces?: boolean | undefined;
  /**
   * Whether the rest of the page is inert and does not scroll behind it on every
   * screen — not only on a phone, where every overlay is a sheet and so modal:
   * a dialog, which must be answered or dismissed before anything else. A press
   * outside it reaches nothing beneath.
   */
  blocking?: boolean | undefined;
  /** Whether a press outside closes it. An alert that must be answered is not closed by a stray press. */
  dismissOnPressOutside?: boolean | undefined;
  /** Where focus goes when it opens without being told: as its owner's state changes, say. */
  defaultFocus?: InitialFocus | undefined;
}

export interface Overlay {
  readonly open: boolean;
  /** Open, saying where focus should go, or close. */
  readonly setOpen: (open: boolean, focus?: InitialFocus) => void;
  /** Open against a point or a rectangle of the viewport rather than a control, or move there if open. */
  readonly openAt: (at: OverlayPoint, focus?: InitialFocus) => void;
  readonly contentId: string;
  /** Spread on the control that opens the overlay. */
  readonly triggerProps: {
    readonly ref: RefCallback<HTMLElement>;
    readonly "aria-expanded": boolean;
    readonly "aria-controls": string;
    readonly style: CSSProperties;
  };
  /** Spread on the overlay itself. */
  readonly contentProps: {
    readonly ref: RefCallback<HTMLElement>;
    readonly id: string;
    readonly popover: "manual";
    readonly style: CSSProperties;
    readonly tabIndex: -1;
  };
  /**
   * Spread on an empty element beside the overlay, for one that `openAt` opens:
   * what the overlay is anchored to, moved to the point. It joins the top layer,
   * so that it is where it says whatever it is rendered inside.
   */
  readonly anchorProps: {
    readonly ref: RefCallback<HTMLElement>;
    readonly popover: "manual";
    readonly "aria-hidden": true;
    readonly style: CSSProperties;
  };
}

const FOCUSABLE =
  'a[href], button:not([disabled]), input:not([disabled]), select:not([disabled]), textarea:not([disabled]), [tabindex]:not([tabindex="-1"])';

function defaultFocusable(content: HTMLElement): HTMLElement[] {
  return Array.from(content.querySelectorAll<HTMLElement>(FOCUSABLE));
}

function canTakeFocus(element: HTMLElement | null): element is HTMLElement {
  return (
    element !== null && element.isConnected && !element.matches(":disabled") && element.checkVisibility()
  );
}

let overlays = 0;
let salt: string | undefined;

function subscribeToNothing(): () => void {
  return () => {};
}

/**
 * A name no other overlay on the page has. `useId` alone repeats between two
 * React roots; a count kept by this module does not, nor does it between two
 * copies of the module once salted. A server cannot know either, so the name is
 * completed after hydration.
 */
function useAnchorName(id: string): string {
  const [serial] = useState(() => (overlays += 1));
  const suffix = useSyncExternalStore(
    subscribeToNothing,
    () => `-${(salt ??= Math.random().toString(36).slice(2, 8))}${serial}`,
    () => "",
  );
  return `--overlay-${id.replace(/[^\w-]/g, "")}${suffix}`;
}

interface Attached {
  readonly root: Root;
  readonly layer: Layer;
  readonly undo: () => void;
}

export function useOverlay({
  open: openProp,
  defaultOpen = false,
  onOpenChange,
  placement = "block-end",
  focusable = defaultFocusable,
  modal = false,
  replaces = false,
  blocking = false,
  dismissOnPressOutside = true,
  defaultFocus = "content",
}: OverlayOptions = {}): Overlay {
  const contentId = useId();
  const anchorName = useAnchorName(contentId);
  const triggerRef = useRef<HTMLElement>(null);
  const contentRef = useRef<HTMLElement>(null);
  const anchorRef = useRef<HTMLElement>(null);
  const focusIntent = useRef<InitialFocus>(defaultFocus);
  /** What had focus before the overlay opened: where focus returns when there is no control to return to. */
  const returnTo = useRef<HTMLElement>(null);
  const attached = useRef<Attached>(null);
  const [open, setOpenState] = useControllableState(openProp, defaultOpen, onOpenChange);
  const [point, setPoint] = useState<Required<OverlayPoint> | null>(null);

  // What the element is brought into step with. Kept current before any effect
  // below runs, and read by the refs, which hear of an element before effects do.
  const live = useRef({
    open,
    modal,
    replaces,
    blocking,
    dismissOnPressOutside,
    placement,
    point,
    focusable,
    close: setOpenState,
  });
  useLayoutEffect(() => {
    live.current = {
      open,
      modal,
      replaces,
      blocking,
      dismissOnPressOutside,
      placement,
      point,
      focusable,
      close: setOpenState,
    };
  });

  const focusInto = useCallback((intent: InitialFocus) => {
    const content = contentRef.current;
    if (content === null || intent === "none") return;
    const candidates = intent === "content" ? [] : live.current.focusable(content);
    const target = candidates.at(intent === "last" ? -1 : 0);
    // The overlay is in view wherever the page is scrolled to: focus on it is no reason to scroll the page.
    if (target === undefined) content.focus({ preventScroll: true });
    else target.focus();
  }, []);

  const restoreFocus = useCallback(() => {
    const target = [triggerRef.current, returnTo.current].find(canTakeFocus);
    target?.focus();
  }, []);

  /** Against a point: on the side its direction says, and held within the view where it fits on neither. */
  const place = useCallback((content: HTMLElement) => {
    const { point: at, placement: side } = live.current;
    if (at === null) {
      content.style.removeProperty("--overlay-inset");
      return;
    }
    const view = content.ownerDocument.defaultView;
    if (view === null) return;
    const rtl = view.getComputedStyle(content).direction === "rtl";
    const insets = insetsFor(side, rtl);
    content.style.setProperty("--overlay-inset", insets.join(" "));
    if (!content.matches(":popover-open") || isSheet(content.ownerDocument)) return;
    // Measured once the browser has flipped it where flipping is enough.
    const box = content.getBoundingClientRect();
    const { clientWidth, clientHeight } = content.ownerDocument.documentElement;
    if (box.top < 0 || box.bottom > clientHeight) {
      insets[0] = "auto";
      insets[2] = `${EDGE}px`;
    }
    if (box.left < 0 || box.right > clientWidth) {
      insets[rtl ? 1 : 3] = "auto";
      insets[rtl ? 3 : 1] = `${EDGE}px`;
    }
    content.style.setProperty("--overlay-inset", insets.join(" "));
  }, []);

  const detach = useCallback(() => {
    const current = attached.current;
    if (current === null) return;
    attached.current = null;
    const { root, layer, undo } = current;
    const index = root.stack.indexOf(layer);
    // What closes with it lets go of the page now, not when its own turn comes:
    // focus is about to return to something they may be holding inert.
    for (const above of root.stack.slice(index + 1)) above.release();
    closeFrom(root, index + 1);
    root.stack.splice(index, 1);
    undo();
    if (root.stack.length === 0) {
      root.listening.abort();
      roots.delete(root.document);
    }
  }, []);

  const showInTopLayer = useCallback(
    (content: HTMLElement) => {
      const anchor = anchorRef.current;
      // The anchor first: an element of the top layer is anchored only to what is beneath it there.
      if (live.current.point !== null && anchor !== null) {
        if (anchor.matches(":popover-open")) anchor.hidePopover();
        anchor.showPopover();
      }
      content.showPopover();
      place(content);
    },
    [place],
  );

  const attach = useCallback(
    (content: HTMLElement) => {
      detach();
      const root = rootOf(content.ownerDocument);
      const layer: Layer = {
        content,
        trigger: () => triggerRef.current,
        close: () => live.current.close(false),
        modal: () => live.current.modal,
        blocking: live.current.blocking,
        dismissible: () => live.current.dismissOnPressOutside,
        replaces: live.current.replaces,
        raise() {
          content.hidePopover();
          showInTopLayer(content);
          focusInto(focusIntent.current);
        },
        release() {},
      };
      // Beneath any opened from within it that was shown first, as when both begin open.
      const above = root.stack.findIndex((other) => {
        const trigger = other.trigger();
        return content.contains(other.content) || (trigger !== null && content.contains(trigger));
      });
      root.stack.splice(above === -1 ? root.stack.length : above, 0, layer);

      const undoSheet = present(root, layer);
      // A control that can no longer be used cannot hold an overlay open.
      const trigger = triggerRef.current;
      const observer = new MutationObserver(() => {
        if (trigger?.matches(":disabled")) layer.close();
      });
      if (trigger !== null) observer.observe(trigger, { attributes: true, attributeFilter: ["disabled"] });
      let released = false;
      layer.release = () => {
        if (released) return;
        released = true;
        observer.disconnect();
        undoSheet();
      };
      attached.current = { root, layer, undo: layer.release };
      return { root, layer };
    },
    [detach, focusInto, showInTopLayer],
  );

  /** Bring the element into step with the state. */
  const sync = useCallback(() => {
    const content = contentRef.current;
    if (content === null) return;
    const shown = content.matches(":popover-open");
    const active = content.ownerDocument.activeElement as HTMLElement | null;

    if (live.current.open && !shown) {
      returnTo.current = active === content.ownerDocument.body ? null : active;
      // What a swipe that closed it left behind.
      content.style.translate = "";
      content.style.transition = "";
      showInTopLayer(content);
      const { root, layer } = attach(content);
      const within = root.stack.slice(root.stack.indexOf(layer) + 1);
      for (const inner of within) inner.raise();
      if (within.length === 0) focusInto(focusIntent.current);
    } else if (live.current.open && attached.current?.layer.content !== content) {
      // Shown already, and let go of since: an effect run again.
      attach(content);
    } else if (!live.current.open && shown) {
      const focusInside = active !== null && content.contains(active);
      // First, so that what a sheet made inert can take focus again.
      detach();
      content.hidePopover();
      const anchor = anchorRef.current;
      if (anchor?.matches(":popover-open")) anchor.hidePopover();
      if (focusInside) restoreFocus();
    }
  }, [attach, detach, focusInto, restoreFocus, showInTopLayer]);

  const setOpen = useCallback(
    (next: boolean, focus: InitialFocus = defaultFocus) => {
      focusIntent.current = focus;
      // Asked to open when already open — a submenu the pointer opened, now
      // entered by a key — there is still focus to move.
      if (next && open) focusInto(focus);
      if (next && !open) setPoint(null);
      setOpenState(next);
    },
    [open, defaultFocus, focusInto, setOpenState],
  );

  const openAt = useCallback(
    (at: OverlayPoint, focus: InitialFocus = defaultFocus) => {
      focusIntent.current = focus;
      setPoint({ x: at.x, y: at.y, width: at.width ?? 0, height: at.height ?? 0 });
      if (open) focusInto(focus);
      setOpenState(true);
    },
    [open, defaultFocus, focusInto, setOpenState],
  );

  // React's state leads and the element follows — synchronously, so a close
  // caused by a press happens before the press moves focus anywhere.
  useLayoutEffect(() => {
    sync();
    // `open` is not read here: it is what there is to come into step with.
    // oxlint-disable-next-line react/exhaustive-effect-dependencies
  }, [open, sync]);

  // Moved while open: placed again against where it now is.
  useLayoutEffect(() => {
    const content = contentRef.current;
    if (content !== null) place(content);
    // Neither is read here: they are what a placing depends on.
    // oxlint-disable-next-line react/exhaustive-effect-dependencies
  }, [point, placement, place]);

  const mounted = useRef(false);
  useLayoutEffect(() => {
    mounted.current = true;
    return () => {
      mounted.current = false;
      detach();
    };
  }, [detach]);

  const triggerCallback = useCallback((node: HTMLElement | null) => {
    triggerRef.current = node;
    if (node !== null) return;
    // Gone for good, rather than a ref changing hands within one render: an
    // overlay cannot stay open over a control that is no longer there.
    queueMicrotask(() => {
      if (mounted.current && triggerRef.current === null && live.current.open) live.current.close(false);
    });
  }, []);

  const contentCallback = useCallback(
    (node: HTMLElement | null) => {
      const previous = contentRef.current;
      contentRef.current = node;
      if (node !== null) {
        // It may arrive after the overlay was opened.
        sync();
        return;
      }
      if (previous === null) return;
      // Heard before the element leaves the page, while focus can still be seen inside it.
      const document = previous.ownerDocument;
      const focusInside = previous.contains(document.activeElement);
      queueMicrotask(() => {
        if (contentRef.current !== null) return;
        detach();
        const active = document.activeElement;
        if (focusInside && (active === null || active === document.body)) restoreFocus();
      });
    },
    [sync, detach, restoreFocus],
  );

  const anchorCallback = useCallback((node: HTMLElement | null) => {
    anchorRef.current = node;
  }, []);

  return {
    open,
    setOpen,
    openAt,
    contentId,
    triggerProps: {
      ref: triggerCallback,
      "aria-expanded": open,
      "aria-controls": contentId,
      style: { anchorName },
    },
    contentProps: {
      ref: contentCallback,
      id: contentId,
      popover: "manual",
      style: {
        "--overlay-anchor": point === null ? anchorName : `${anchorName}-at`,
        "--overlay-area": point === null ? AREAS[placement] : "none",
        "--overlay-fallbacks": FLIPS[placement],
      } as CSSProperties,
      // Focusable, so focus has somewhere to go when nothing inside asks for it.
      tabIndex: -1,
    },
    anchorProps: {
      ref: anchorCallback,
      popover: "manual",
      "aria-hidden": true,
      style: {
        // Over what a browser gives a popover: nothing of it is to be seen or pressed.
        position: "fixed",
        inset: "auto",
        left: point?.x ?? 0,
        top: point?.y ?? 0,
        width: point?.width ?? 0,
        height: point?.height ?? 0,
        margin: 0,
        padding: 0,
        border: 0,
        background: "none",
        pointerEvents: "none",
        anchorName: `${anchorName}-at`,
      },
    },
  };
}

/**
 * Whether its owner gave an overlay a button that closes it — counted, as each
 * such button mounts and unmounts. A sheet given none needs one all the same:
 * with the page behind it inert and no Escape key, assistive technology needs a
 * control that closes it.
 */
export function useCloseButtons(): { readonly closable: boolean; readonly addClose: () => () => void } {
  const [closes, setCloses] = useState(0);
  const addClose = useCallback(() => {
    setCloses((count) => count + 1);
    return () => setCloses((count) => count - 1);
  }, []);
  return useMemo(() => ({ closable: closes > 0, addClose }), [closes, addClose]);
}