@eifi1/ui-kit 0.4.0 → 0.5.0

package/src/hooks/use-anchored-panel.ts

@@ -0,0 +1,169 @@
+import { useLayoutEffect, useState } from "react";
+import type { RefObject } from "react";
+import { useAnchoredRect, type AnchorRect } from "./use-anchored-rect";
+
+/**
+ * Vertical placement for a portalled, `position: fixed` panel anchored to a trigger.
+ *
+ * The problem it solves (feedback #135): on a phone, opening a picker focuses its
+ * search box, the on-screen keyboard slides up, and a panel pinned below a trigger in
+ * the lower half of the screen ends up entirely behind that keyboard — with nothing
+ * the user can do about it, because `position: fixed` does not scroll.
+ *
+ * The keyboard is invisible to the usual measurements: on Android Chrome the LAYOUT
+ * viewport (`window.innerHeight`, and the origin `getBoundingClientRect` and
+ * `position: fixed` are relative to) does not shrink when it opens. Only
+ * `visualViewport` reports the region actually on screen, so that is what this reads.
+ */
+
+/** The on-screen region, in layout-viewport coordinates. */
+export interface ViewportBox {
+  top: number;
+  height: number;
+}
+
+function readViewport(): ViewportBox {
+  if (typeof window === "undefined") return { top: 0, height: 0 };
+  const vv = window.visualViewport;
+  // offsetTop, not 0: with the keyboard up the user can also pan the visual viewport
+  // within the layout viewport, which shifts where "visible" starts.
+  return vv ? { top: vv.offsetTop, height: vv.height } : { top: 0, height: window.innerHeight };
+}
+
+export interface AnchoredPanelOptions {
+  /** Space between trigger and panel. */
+  gap?: number;
+  /** Space kept clear at the viewport edges. */
+  margin?: number;
+  /** The height the panel would like, when there is room. */
+  preferredHeight?: number;
+  /** Below this, the space under the trigger counts as unusable and a flip is considered. */
+  minHeight?: number;
+}
+
+export interface AnchoredPanel {
+  /** The trigger's rect, or null while closed/unmeasured. */
+  rect: AnchorRect | null;
+  /** Viewport-space `top` for the panel. */
+  top: number;
+  /** Cap that keeps the panel inside the VISIBLE viewport — apply as `maxHeight`. */
+  maxHeight: number;
+  /** Whether the panel was flipped above the trigger. */
+  above: boolean;
+}
+
+/** Absolute floor: below this a list is useless, so overflow the margin instead. */
+const FLOOR = 96;
+
+/**
+ * The pure half of {@link useAnchoredPanel}: where a panel goes, given the trigger's
+ * rect and the region actually on screen.
+ *
+ * Prefers below the trigger — the conventional direction, and the one that keeps the
+ * trigger's own value visible. Flips above only when below cannot show a usable list
+ * AND above is roomier, so a panel never jumps sides for a few pixels' gain. The
+ * returned `maxHeight` is what makes the flip sufficient rather than merely different:
+ * without it a tall panel placed above just runs off the top instead of the bottom.
+ *
+ * Split out so the geometry is testable without a DOM and a fake keyboard — @hb/ui has
+ * no test runner of its own, so this is exercised from the consuming app.
+ */
+export function anchoredPanelPlacement(
+  rect: Pick<AnchorRect, "top" | "bottom">,
+  viewport: ViewportBox,
+  { gap = 4, margin = 8, preferredHeight = 320, minHeight = 160 }: AnchoredPanelOptions = {},
+): Omit<AnchoredPanel, "rect"> {
+  const viewTop = viewport.top + margin;
+  const viewBottom = viewport.top + viewport.height - margin;
+  const spaceBelow = viewBottom - (rect.bottom + gap);
+  const spaceAbove = rect.top - gap - viewTop;
+  const above = spaceBelow < minHeight && spaceAbove > spaceBelow;
+  const space = Math.max(FLOOR, above ? spaceAbove : spaceBelow);
+  const maxHeight = Math.min(preferredHeight, space);
+  return {
+    top: above ? Math.max(viewTop, rect.top - gap - maxHeight) : rect.bottom + gap,
+    maxHeight,
+    above,
+  };
+}
+
+/**
+ * Where to put a panel anchored under `ref`, tracking the visible viewport.
+ *
+ * Callers own horizontal placement — the pickers align to the trigger's left edge, the
+ * popovers to its right — and must apply `maxHeight` with an internal `overflow-y`.
+ */
+/**
+ * The region actually on screen, tracked while `active` (Keksdose live #328).
+ *
+ * The same measurement {@link useAnchoredPanel} caps a dropdown with, for the callers
+ * that need the box itself rather than a placement: a FULL-SCREEN sheet cannot use
+ * `inset-0`, because on Android the on-screen keyboard shrinks only the VISUAL
+ * viewport — `inset-0` still spans the whole screen, so the bottom of the sheet, and
+ * the end of whatever list is scrolling inside it, live behind the keyboard where no
+ * gesture reaches them.
+ *
+ * Returns `null` where there is nothing to correct: no `visualViewport` (jsdom, SSR,
+ * older browsers) or no keyboard taking a bite out of it. A caller then keeps its
+ * static layout, which is right at every width where this does not apply — and is why
+ * the desktop and the test suite see exactly the markup they saw before.
+ */
+export function useVisualViewport(active: boolean): ViewportBox | null {
+  const [box, setBox] = useState<ViewportBox | null>(null);
+
+  useLayoutEffect(() => {
+    if (!active) return;
+    const update = () => {
+      const vv = typeof window === "undefined" ? undefined : window.visualViewport;
+      // The 1px slack is not superstition: `visualViewport.height` is fractional on a
+      // device-pixel-ratio that is not an integer (his phone reports 1.25), so a
+      // strict comparison would report a "keyboard" of 0.4px on every phone and pin
+      // a height where none was needed.
+      setBox(vv && vv.height < window.innerHeight - 1 ? { top: vv.offsetTop, height: vv.height } : null);
+    };
+    update();
+    const vv = window.visualViewport;
+    vv?.addEventListener("resize", update);
+    vv?.addEventListener("scroll", update);
+    window.addEventListener("resize", update);
+    return () => {
+      vv?.removeEventListener("resize", update);
+      vv?.removeEventListener("scroll", update);
+      window.removeEventListener("resize", update);
+    };
+  }, [active]);
+
+  return box;
+}
+
+export function useAnchoredPanel<T extends HTMLElement>(
+  ref: RefObject<T | null>,
+  open: boolean,
+  options: AnchoredPanelOptions = {},
+): AnchoredPanel {
+  const rect = useAnchoredRect(ref, open);
+  const [viewport, setViewport] = useState<ViewportBox>(readViewport);
+
+  useLayoutEffect(() => {
+    if (!open) return;
+    const update = () => setViewport(readViewport());
+    update();
+    const vv = window.visualViewport;
+    // The visualViewport events are the ones that fire when the keyboard opens;
+    // window.resize is the fallback for browsers without the API (and for a genuine
+    // window resize on desktop).
+    vv?.addEventListener("resize", update);
+    vv?.addEventListener("scroll", update);
+    window.addEventListener("resize", update);
+    return () => {
+      vv?.removeEventListener("resize", update);
+      vv?.removeEventListener("scroll", update);
+      window.removeEventListener("resize", update);
+    };
+  }, [open]);
+
+  if (!rect) {
+    return { rect: null, top: 0, maxHeight: options.preferredHeight ?? 320, above: false };
+  }
+  return { rect, ...anchoredPanelPlacement(rect, viewport, options) };
+}

package/src/hooks/use-anchored-rect.ts

@@ -0,0 +1,78 @@
+import { useLayoutEffect, useState } from "react";
+import type { RefObject } from "react";
+
+/** The subset of an element's viewport rect used for anchored positioning. */
+export interface AnchorRect {
+  top: number;
+  left: number;
+  right: number;
+  bottom: number;
+  width: number;
+  height: number;
+}
+
+function sameRect(a: AnchorRect | null, b: AnchorRect | null): boolean {
+  if (a === b) return true;
+  if (!a || !b) return false;
+  return (
+    a.top === b.top &&
+    a.left === b.left &&
+    a.right === b.right &&
+    a.bottom === b.bottom &&
+    a.width === b.width &&
+    a.height === b.height
+  );
+}
+
+/**
+ * Tracks an anchor element's viewport rect while `open`, re-measuring on scroll
+ * (capture phase, so nested scroll containers are caught too) and resize, and
+ * returning null when closed or unmeasured. Callers derive their own panel
+ * position from the rect — this hook owns only the measure + listener lifecycle
+ * that every portalled, position:fixed popover/flyout otherwise re-implements.
+ *
+ * Measured in a layout effect so the position is ready before paint (no flicker
+ * on open).
+ */
+export function useAnchoredRect<T extends HTMLElement>(
+  ref: RefObject<T | null>,
+  open: boolean,
+): AnchorRect | null {
+  const [rect, setRect] = useState<AnchorRect | null>(null);
+
+  useLayoutEffect(() => {
+    if (!open) {
+      // eslint-disable-next-line react-hooks/set-state-in-effect -- reset when closed
+      setRect(null);
+      return;
+    }
+    const measure = () => {
+      const r = ref.current?.getBoundingClientRect();
+      if (!r) return;
+      const next = {
+        top: r.top,
+        left: r.left,
+        right: r.right,
+        bottom: r.bottom,
+        width: r.width,
+        height: r.height,
+      };
+      // Only publish a rect that actually MOVED. Every measurement allocates a fresh
+      // object and React compares state by identity, so an unguarded `setRect` here
+      // re-rendered the anchored panel on every scroll and resize event whether or not
+      // the anchor had moved — and this listens on the capture phase, so that is every
+      // ancestor scroll container, roughly per frame through a momentum scroll.
+      // `tour.tsx` already does exactly this on the same problem.
+      setRect((prev) => (sameRect(prev, next) ? prev : next));
+    };
+    measure();
+    window.addEventListener("resize", measure);
+    window.addEventListener("scroll", measure, true);
+    return () => {
+      window.removeEventListener("resize", measure);
+      window.removeEventListener("scroll", measure, true);
+    };
+  }, [open, ref]);
+
+  return rect;
+}

package/src/hooks/use-announce.ts

@@ -0,0 +1,85 @@
+import { useCallback, useEffect, useRef, useState } from "react";
+
+/**
+ * Announce a state change that produces no focus change.
+ *
+ * Sorting a column, applying a filter, moving to the next page: the rows under the
+ * cursor silently become different rows, and nothing tells a screen-reader user. There
+ * is no focus move to carry the news, because the control they activated is still the
+ * control they are on. A live region is the only channel.
+ *
+ * Two details that are the whole reason this is a hook rather than a `<div aria-live>`
+ * written inline at each call site:
+ *
+ *  1. **The region must already be in the DOM before the message arrives.** Screen
+ *     readers subscribe to a live region when they encounter it; a region that mounts
+ *     *with* its first message is usually missed entirely. So `regionProps` is spread
+ *     onto an element that renders empty from the start and never unmounts.
+ *  2. **Re-announcing the same string must still speak.** Assistive tech diffs the
+ *     region's content, so setting "12 results" when it already says "12 results" is a
+ *     no-op — which is exactly the case that matters when a user re-applies a filter
+ *     and needs confirmation that something happened. Clearing first and setting on the
+ *     next tick forces a diff.
+ */
+
+export interface AnnounceRegionProps {
+  role: "status" | "alert";
+  "aria-live": "polite" | "assertive";
+  "aria-atomic": true;
+  /** `sr-only-fixed` — visually hidden without inflating the document height. */
+  className: string;
+  children: string;
+}
+
+export interface UseAnnounceReturn {
+  /** Speak `message`. Passing the same string twice still speaks twice. */
+  announce: (message: string) => void;
+  /** Spread onto an element that is rendered unconditionally. */
+  regionProps: AnnounceRegionProps;
+}
+
+export interface UseAnnounceOptions {
+  /**
+   * `polite` (default) waits for a pause; `assertive` interrupts. Sorting and paging
+   * are polite — interrupting someone mid-sentence to tell them a table re-sorted is
+   * worse than telling them a moment later. Reserve assertive for failures.
+   */
+  politeness?: "polite" | "assertive";
+}
+
+export function useAnnounce({ politeness = "polite" }: UseAnnounceOptions = {}): UseAnnounceReturn {
+  const [message, setMessage] = useState("");
+  const timerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  useEffect(
+    () => () => {
+      if (timerRef.current) clearTimeout(timerRef.current);
+    },
+    [],
+  );
+
+  const announce = useCallback((next: string) => {
+    if (timerRef.current) clearTimeout(timerRef.current);
+    // Clear, then set on a later tick. A 0ms timeout is enough: it puts the two
+    // mutations in separate frames, which is what makes the second one a diff.
+    setMessage("");
+    timerRef.current = setTimeout(() => setMessage(next), 50);
+  }, []);
+
+  return {
+    announce,
+    regionProps: {
+      role: politeness === "assertive" ? "alert" : "status",
+      "aria-live": politeness,
+      // Read the whole region, not just the changed words — "Page 3 of 14" is a
+      // sentence, and an atomic=false region can announce a bare "3".
+      "aria-atomic": true,
+      // `sr-only-fixed`, not `sr-only`: this region is rendered by the KIT inside a
+      // consumer's component, so there is no wrapper we can require to be `relative`.
+      // Tailwind's `sr-only` is `position: absolute` and would extend the document
+      // height from wherever it landed — see the note on the class in tokens.css.
+      className: "sr-only-fixed",
+      children: message,
+    },
+  };
+}

package/src/hooks/use-body-scroll-lock.ts

@@ -0,0 +1,94 @@
+import { useEffect } from "react";
+
+/**
+ * How many locks are currently held, and what `body.style.overflow` was before the
+ * first of them. Module scope on purpose: the whole point is that the lockers do not
+ * know about each other, so the only place they can agree is here.
+ *
+ * This used to be per-locker — each one saved the previous value and restored it on
+ * cleanup — and five places in this package do that (Modal, PickerSheet,
+ * NumberPadSheet, and the DataTable's row dialog and settings panel). Save/restore
+ * composes only if the releases are strictly nested in reverse order of the
+ * acquisitions, and React runs unmount cleanups PARENT FIRST, which is the opposite
+ * of what the idiom needs.
+ *
+ * The gesture that broke it is an ordinary one: open the transaction dialog, tap the
+ * amount — the numpad sheet opens on focus, in a later commit, capturing the
+ * "hidden" the dialog had already set — then press Save. Both unmount together, the
+ * dialog restores "" first, the sheet then puts "hidden" back, and the page is left
+ * unscrollable with no overlay on screen. The only way out was a reload.
+ *
+ * A count has neither failure: the first acquire records the real previous value, the
+ * last release restores it, and the order in between does not matter.
+ */
+let lockCount = 0;
+let previousOverflow = "";
+let previousPaddingRight = "";
+
+/**
+ * How much width the scrollbar of the DOCUMENT is currently taking.
+ *
+ * Zero on every platform with overlay scrollbars (macOS, most Linux, every phone) and
+ * zero whenever the page does not scroll; ~15px on Windows with classic ones. Read
+ * BEFORE `overflow: hidden` is applied, because applying it is what makes it vanish.
+ */
+function scrollbarWidth(): number {
+  return Math.max(0, window.innerWidth - document.documentElement.clientWidth);
+}
+
+function acquire(): void {
+  if (lockCount === 0) {
+    // ⚠️ Hiding the document's overflow REMOVES its scrollbar, and on a platform where
+    // that scrollbar occupied layout space the page gets ~15px wider for as long as the
+    // dialog is open — then snaps back on close. Keksdose dev #561 from a 500px-wide
+    // desktop window: *"remove the scroll bar to stop horizontal resizing when opening
+    // edit tx and closing"*.
+    //
+    // Replacing the width we are about to take away is the standard fix and the narrow
+    // one. The alternatives both cost more than the bug: `scrollbar-gutter` on `html`
+    // shrinks the initial containing block, so every `position: fixed` overlay stops
+    // 15px short on each edge (measured, and documented in tokens.css), and moving the
+    // scroll container to `main` below `md` stops a phone's URL bar collapsing. This
+    // touches neither — only the element already being modified, only while locked.
+    //
+    // Note this fixes the DIALOG jump specifically. The separate page-to-page width
+    // change, where one route scrolls and the next does not, is the open decision
+    // recorded in tokens.css and is untouched here.
+    const gap = scrollbarWidth();
+    previousOverflow = document.body.style.overflow;
+    previousPaddingRight = document.body.style.paddingRight;
+    document.body.style.overflow = "hidden";
+    if (gap > 0) {
+      // Added to whatever the body already had rather than assigned, so a consumer
+      // that sets its own padding keeps it.
+      const existing = parseFloat(getComputedStyle(document.body).paddingRight) || 0;
+      document.body.style.paddingRight = `${existing + gap}px`;
+    }
+  }
+  lockCount += 1;
+}
+
+function release(): void {
+  if (lockCount === 0) return;
+  lockCount -= 1;
+  if (lockCount === 0) {
+    document.body.style.overflow = previousOverflow;
+    document.body.style.paddingRight = previousPaddingRight;
+    previousOverflow = "";
+    previousPaddingRight = "";
+  }
+}
+
+/**
+ * Lock background scrolling while `locked` is true, restoring the prior value once
+ * the LAST holder releases. Composable with every other caller of this hook — see
+ * the note above for why that has to be a property of the hook rather than of each
+ * caller's discipline.
+ */
+export function useBodyScrollLock(locked: boolean): void {
+  useEffect(() => {
+    if (!locked) return;
+    acquire();
+    return release;
+  }, [locked]);
+}

package/src/hooks/use-close-transition.ts

@@ -0,0 +1,99 @@
+import { useCallback, useEffect, useRef, useState } from "react";
+
+/** How long the exit animation runs, in ms. Mirrors `.animate-sheet-out` in
+ *  tokens.css — the sheet is the slower of the two, so it is what the unmount waits
+ *  for. Exported so a test can advance a fake clock by the real number rather than
+ *  by a copy of it. */
+export const OVERLAY_EXIT_MS = 220;
+
+/**
+ * The state machine an exit animation needs, written once for every overlay in this
+ * package (Keksdose live #320 rework: *"Recognized the opening transition. Choose
+ * transition should be the same, only backwards"*).
+ *
+ * ## Why a hook and not a class on the panel
+ *
+ * An enter animation is free: the element mounts, the keyframes run. An exit is not —
+ * by the time the state says "closed" the element is already gone, so something has to
+ * hold it on screen for exactly as long as the animation lasts. That something cannot
+ * be the caller (every caller would need the same timer) and it cannot be the panel's
+ * markup. It is this: the overlay's own affordances call {@link requestClose} instead
+ * of `onClose`, render the `-out` classes while `closing` is true, and the real
+ * `onClose` — the one that unmounts them — fires when the animation has finished.
+ *
+ * ## What it deliberately does not do
+ *
+ * It does not intercept a close the CALLER decides on. A dialog that closes itself
+ * after a successful save sets its own state and unmounts, with no exit animation, and
+ * that is the right trade: making it otherwise would mean every overlay owning an
+ * `open` prop and every caller waiting on a callback to learn when its own state took
+ * effect. What is animated is what the user dismissed — the X, the backdrop, Escape,
+ * the Back gesture — which is the motion the row was about.
+ *
+ * ## Reduced motion
+ *
+ * Closes immediately, without the delay. A user who has asked for no motion must not
+ * be made to wait 220ms for an animation they are not being shown, and the `-out`
+ * classes are never applied, so tokens.css needs no reduced-motion rule for them.
+ */
+export function useCloseTransition(
+  onClose: () => void,
+  ms: number = OVERLAY_EXIT_MS,
+): { closing: boolean; requestClose: () => void } {
+  const [closing, setClosing] = useState(false);
+  const timer = useRef<ReturnType<typeof setTimeout> | null>(null);
+  // Latest-ref rather than a dependency: callers pass inline arrows, so a dependency
+  // would hand every render a new `requestClose` — and this one is read once, by a
+  // timer that has already been scheduled. Assigned in an effect, never during render
+  // (`react-hooks/refs`), matching `use-long-press.ts` next door.
+  const latest = useRef(onClose);
+  useEffect(() => {
+    latest.current = onClose;
+  });
+
+  // One timer, ever. A second Escape while the panel is already leaving must not
+  // schedule a second unmount — two `onClose` calls is a caller's state machine being
+  // run twice, which is how a "close" ends up also discarding the row behind it.
+  useEffect(
+    () => () => {
+      if (timer.current) clearTimeout(timer.current);
+    },
+    [],
+  );
+
+  const requestClose = useCallback(() => {
+    if (timer.current) return;
+    // Read at close time, not at mount: the setting can change under a long-lived
+    // page, and `matchMedia` is absent in jsdom and in SSR — where "no animation" is
+    // also the only correct answer, since nothing is painting.
+    const reduced =
+      typeof window === "undefined" ||
+      typeof window.matchMedia !== "function" ||
+      window.matchMedia("(prefers-reduced-motion: reduce)").matches;
+    if (reduced || ms <= 0) {
+      latest.current();
+      return;
+    }
+    setClosing(true);
+    timer.current = setTimeout(() => {
+      timer.current = null;
+      // ⚠️ Reset BEFORE handing control back — reported from a phone within the hour
+      // of the 0.4.52 deploy that first shipped this hook, against every table at once.
+      // A panel that returns `null` while closed is still MOUNTED — `FullBleedDialog`
+      // early-returns after its hooks, and DataTable renders it once and flips `open`
+      // — so this state outlives the panel it describes. Left true, the NEXT open
+      // rendered `animate-*-out` with `animation-fill-mode: forwards` on a sheet that
+      // had only just arrived: it lowered itself off the screen in 220ms and stayed
+      // there, invisible but still holding the backdrop's pointer events. Every table
+      // on every phone, first open fine and every one after it not, until a route
+      // change remounted the component.
+      //
+      // Batched with the `onClose` below, so a caller that unmounts on close still
+      // renders exactly once and nothing flashes.
+      setClosing(false);
+      latest.current();
+    }, ms);
+  }, [ms]);
+
+  return { closing, requestClose };
+}

package/src/hooks/use-dismiss.ts

@@ -0,0 +1,77 @@
+import { useEffect, useRef } from "react";
+import type { RefObject } from "react";
+
+/**
+ * Calls `handler` on an Escape keydown while `enabled`. A single document-level
+ * listener owns the "press Escape to dismiss" behaviour that popovers, flyouts
+ * and menus otherwise each re-implement. `handler` is read live at event time,
+ * so it need not be memoised and the listener only re-subscribes when `enabled`
+ * flips (typically the open/closed transition).
+ */
+export function useEscapeKey(handler: () => void, enabled = true): void {
+  const handlerRef = useRef(handler);
+  // Written in an effect, not during render, so it satisfies react-hooks/refs: a
+  // render that React starts and then discards — a transition, a Suspense retry —
+  // would otherwise leave this holding a handler from a tree that never committed,
+  // and the document listener below would go on to call it. Keydown events fire
+  // after the commit, so the ref is always current by the time one arrives.
+  useEffect(() => {
+    handlerRef.current = handler;
+  });
+  useEffect(() => {
+    if (!enabled) return;
+    const onKey = (e: KeyboardEvent) => {
+      if (e.key === "Escape") handlerRef.current();
+    };
+    document.addEventListener("keydown", onKey);
+    return () => document.removeEventListener("keydown", onKey);
+  }, [enabled]);
+}
+
+/**
+ * Calls `handler` on a press that lands outside every supplied element, while
+ * `enabled` — the outside-click-to-close half of the same dismissal story. Pass one
+ * ref or several (trigger + panel); a press inside any of them is ignored. Refs and
+ * `handler` are read live, so an inline `[triggerRef, panelRef]` array is fine and
+ * won't churn the listener.
+ *
+ * **`pointerdown`, not `mousedown`** — one event covering mouse, touch and pen.
+ * This listened for `mousedown` alone, which on a touch platform is a SYNTHESISED
+ * event: the browser emits it for most taps, which is why nothing obviously broke,
+ * but the synthesis is not guaranteed. A tap that begins a scroll, or one that lands
+ * on an element which preventDefaults the touch sequence, may never produce one — and
+ * on a phone-first PWA whose pickers, menus and flyouts all dismiss through this hook,
+ * inheriting that is worse than choosing it.
+ *
+ * The one behaviour this changes deliberately: a touch-drag that starts outside an
+ * open panel now dismisses it at touch-down, where before it did not dismiss at all
+ * (a drag synthesises no mousedown). That matches every other platform surface, and
+ * the anchored panels re-measure on scroll precisely because the page moves under
+ * them.
+ */
+export function useOutsideClick(
+  refs: RefObject<HTMLElement | null> | RefObject<HTMLElement | null>[],
+  handler: () => void,
+  enabled = true,
+): void {
+  const refsRef = useRef(refs);
+  const handlerRef = useRef(handler);
+  // In an effect rather than during render — see the note on useEscapeKey.
+  useEffect(() => {
+    refsRef.current = refs;
+    handlerRef.current = handler;
+  });
+  useEffect(() => {
+    if (!enabled) return;
+    const onPointerDown = (e: Event) => {
+      const target = e.target as Node;
+      const list = Array.isArray(refsRef.current) ? refsRef.current : [refsRef.current];
+      for (const r of list) {
+        if (r.current?.contains(target)) return;
+      }
+      handlerRef.current();
+    };
+    document.addEventListener("pointerdown", onPointerDown);
+    return () => document.removeEventListener("pointerdown", onPointerDown);
+  }, [enabled]);
+}