@eifi1/ui-kit 0.33.0 → 0.34.0

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

@@ -2,6 +2,7 @@ import { useLayoutEffect, useState } from "react";
 import type { RefObject } from "react";
 import { useAnchoredRect, type AnchorRect } from "./use-anchored-rect";
 import { useTextSize } from "../theme/text-size";
+import type { Direction } from "../lib/direction";
 
 /**
  * Vertical placement for a portalled, `position: fixed` panel anchored to a trigger.
@@ -21,6 +22,13 @@ import { useTextSize } from "../theme/text-size";
 export interface ViewportBox {
   top: number;
   height: number;
+  /**
+   * The height of the LAYOUT viewport itself, which `position: fixed`'s `bottom` is
+   * measured from. Only {@link anchoredPanelPlacement} reads it, for a flipped panel's
+   * `bottom`. Defaults to `top + height`: the two are the same box whenever no keyboard
+   * and no zoom shrink the visible region.
+   */
+  layoutHeight?: number;
 }
 
 /**
@@ -71,9 +79,21 @@ export function readKeyboardInset({ minimum = MIN_KEYBOARD_PX }: KeyboardInsetOp
 function readViewport(): ViewportBox {
   if (typeof window === "undefined") return { top: 0, height: 0 };
   const vv = window.visualViewport;
+  // The layout viewport's height is `innerHeight`, the reference `readKeyboardInset`
+  // measures the keyboard against. The keyboard leaves it alone (it shrinks only the
+  // VISUAL viewport; under `interactive-widget=resizes-content` it shrinks both, the
+  // fixed box with them), and it follows the mobile URL bar as it slides away, as a
+  // fixed box's `bottom` does. Not `documentElement.clientHeight`: on mobile Chrome and
+  // Safari that stays at the small, URL-bar-shown height, so with the bar scrolled away
+  // a flipped panel would sit that much too low, over its own field. `innerHeight`'s one
+  // error is a desktop page with a horizontal scrollbar, which it counts and the fixed
+  // box does not: the gap widens by the bar's thickness, and never closes.
+  const layoutHeight = window.innerHeight;
   // 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 };
+  return vv
+    ? { top: vv.offsetTop, height: vv.height, layoutHeight }
+    : { top: 0, height: window.innerHeight, layoutHeight };
 }
 
 export interface AnchoredPanelOptions {
@@ -90,11 +110,24 @@ export interface AnchoredPanelOptions {
   minHeight?: number;
 }
 
+/**
+ * `top` and `bottom` are the two edges of a panel exactly `maxHeight` tall. A panel is
+ * sized by its content and `maxHeight` only caps it, so apply the edge on the trigger's
+ * side, the one that holds whatever the height: `top` while the panel is below,
+ * `bottom` (and no `top`) once it is flipped `above`.
+ */
 export interface AnchoredPanel {
   /** The trigger's rect, or null while closed/unmeasured. */
   rect: AnchorRect | null;
-  /** Viewport-space `top` for the panel. */
+  /** Viewport-space `top` for the panel — the one to apply while it is below. Flipped,
+   *  it is where a FULL-height panel's top would be, and a three-row list placed by it
+   *  floated far above its field (keksdose K1, live #401); place that one by `bottom`. */
   top: number;
+  /** CSS `bottom` for a `position: fixed` panel: the distance from the layout
+   *  viewport's bottom edge up to the panel's. The one to apply once it is flipped
+   *  `above`: it keeps the panel's foot `gap` above the trigger however short its
+   *  content, and while a filtered list shrinks or grows under the user's typing. */
+  bottom: number;
   /** Cap that keeps the panel inside the VISIBLE viewport — apply as `maxHeight`. */
   maxHeight: number;
   /** Whether the panel was flipped above the trigger. */
@@ -122,6 +155,14 @@ const FLIP_GAIN = 48;
  * 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.
  *
+ * A flipped panel hangs from its BOTTOM edge, `gap` above the trigger, and is placed by
+ * `bottom` (keksdose K1, live #401). It used to be placed by a `top` worked out as
+ * though the panel were `maxHeight` tall, and a panel is only as tall as its content:
+ * a three-row address list under a 256 px cap sat ~176 px above its field, on a phone
+ * with the keyboard up. Only when even the {@link FLOOR} does not fit above does that
+ * edge give way, as `top` always did, so the panel's head (a search box, often) stays
+ * on screen rather than above it.
+ *
  * 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.
  */
@@ -140,19 +181,115 @@ export function anchoredPanelPlacement(
       (spaceBelow < preferredHeight && (spaceAbove >= preferredHeight || spaceAbove - spaceBelow >= FLIP_GAIN)));
   const space = Math.max(FLOOR, above ? spaceAbove : spaceBelow);
   const maxHeight = Math.min(preferredHeight, space);
+  // Unchanged, for the apps that call the hook and apply it: the edge to use below, and
+  // a full-height panel's top above. In layout-viewport space, like the rect.
+  const top = above ? Math.max(viewTop, rect.top - gap - maxHeight) : rect.bottom + gap;
+  // `bottom` counts up from the LAYOUT viewport's bottom edge, not the visible region's:
+  // `position: fixed` is laid out in the layout viewport, which runs on behind the
+  // keyboard, exactly as the rect is measured in it. The keyboard, the pan and the zoom
+  // are already in `maxHeight`, which keeps the panel's top inside what is on screen.
+  const layoutHeight = viewport.layoutHeight ?? viewport.top + viewport.height;
+  return { top, bottom: layoutHeight - (top + maxHeight), maxHeight, above };
+}
+
+/**
+ * The glass a panel has to stay on, in CSS pixels — `window.innerWidth` is the wrong
+ * width on a phone (keksdose run 72, live #381). There it is the LAYOUT viewport, and
+ * that grows to the page's width as soon as anything sticks out past the screen: 430 on
+ * a 406px screen in Chromium's mobile emulation, with `position: fixed` layers laid out
+ * against the 430. A panel that had widened the page then measured itself as inside it.
+ * The root element's client width is the initial containing block instead — the screen,
+ * the width `100vw` and the media queries see — whatever overflows, and on a desktop it
+ * also leaves a classic scrollbar out, which is where a fixed box's `right` is measured
+ * from. It is 0 where nothing is laid out (jsdom), and the window is the answer there.
+ * The height stays the window's: nothing measured grows it, and a phone's collapsing
+ * toolbar makes the window the truer of the two.
+ *
+ * Tooltip's lesson, moved here so every anchored panel reads the same width (round 0.34
+ * Wave 2, DUP-7).
+ */
+export function viewportSize(): { width: number; height: number } {
   return {
-    top: above ? Math.max(viewTop, rect.top - gap - maxHeight) : rect.bottom + gap,
-    maxHeight,
-    above,
+    width: document.documentElement.clientWidth || window.innerWidth,
+    height: window.innerHeight,
   };
 }
 
+export interface AnchoredInlineOptions {
+  /** The trigger's reading direction, which `start`, `end` and `after` follow. Default
+   *  `ltr`. A portalled panel has left the subtree it would inherit `dir` from, so read
+   *  it off the trigger (`dirOf`). */
+  dir?: Direction;
+  /**
+   * Which of the panel's edges lines up with which of the trigger's:
+   * - `start` / `end` — the panel's start (end) edge on the trigger's start (end) edge,
+   *   by reading direction: a picker hangs from its field's start, a popover from its
+   *   button's end;
+   * - `left` / `right` — the same, physically;
+   * - `after` — the panel's start edge on the trigger's END edge: beside it, as the
+   *   sidebar's flyout opens.
+   *
+   * Default `start`.
+   */
+  align?: "start" | "end" | "left" | "right" | "after";
+  /** The room kept from either edge of the glass, in px. Default 8. */
+  edge?: number;
+  /** The glass's width. Default {@link viewportSize}'s. */
+  viewportWidth?: number;
+}
+
+/** The horizontal place of a `position: fixed` panel: its `left`, and the `right` of the
+ *  same box for a panel hung from its right edge (both in px, from the glass's edges). */
+export interface InlinePlacement {
+  left: number;
+  right: number;
+}
+
 /**
- * Where to put a panel anchored under `ref`, tracking the visible viewport.
+ * The horizontal half of an anchored panel, beside {@link anchoredPanelPlacement}'s
+ * vertical one (round 0.34 Wave 2, DUP-7): where a panel `panelWidth` wide goes against
+ * the trigger's `rect`, kept `edge` px inside the glass ({@link viewportSize}).
+ *
+ * Popover, DropdownPanel, ComboboxPanel, HoverMenu and the AppShell flyout each wrote
+ * this themselves, against three different widths: `innerWidth`, which on a phone is
+ * the grown layout viewport and on a desktop counts the scrollbar; the root's client
+ * width; and, for the entity picker's panel in a left-to-right form, no clamp at all.
  *
- * 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`.
+ * A panel wider than the room keeps its START on the glass — its left edge in a
+ * left-to-right form, its right in a right-to-left one — as Tooltip's slide does: the
+ * start of a row of text is the half worth keeping.
  */
+export function anchoredInline(
+  rect: Pick<AnchorRect, "left" | "right">,
+  panelWidth: number,
+  { dir = "ltr", align = "start", edge = 8, viewportWidth = viewportSize().width }: AnchoredInlineOptions = {},
+): InlinePlacement {
+  const rtl = dir === "rtl";
+  // Where the panel's LEFT edge goes, before the clamp.
+  let wanted: number;
+  switch (align) {
+    case "left":
+      wanted = rect.left;
+      break;
+    case "right":
+      wanted = rect.right - panelWidth;
+      break;
+    case "start":
+      wanted = rtl ? rect.right - panelWidth : rect.left;
+      break;
+    case "end":
+      wanted = rtl ? rect.left : rect.right - panelWidth;
+      break;
+    case "after":
+      wanted = rtl ? rect.left - panelWidth : rect.right;
+      break;
+  }
+  const min = edge;
+  const max = viewportWidth - edge - panelWidth;
+  const left = max < min ? (rtl ? max : min) : Math.min(Math.max(wanted, min), max);
+  return { left, right: viewportWidth - left - panelWidth };
+}
+
 /**
  * The region actually on screen, tracked while `active` (Keksdose live #328).
  *
@@ -204,6 +341,15 @@ export function useVisualViewport(active: boolean): ViewportBox | null {
   return box;
 }
 
+/**
+ * Where to put a panel anchored under `ref`, tracking the visible viewport.
+ *
+ * Callers own horizontal placement, through {@link anchoredInline} — the pickers align
+ * to the trigger's start edge, the popovers to its end — and must apply `maxHeight` with
+ * an internal `overflow-y`.
+ * Vertically, apply `top` while the panel is below and `bottom` (with no `top`) once it
+ * is `above`; see {@link AnchoredPanel}.
+ */
 export function useAnchoredPanel<T extends HTMLElement>(
   ref: RefObject<T | null>,
   open: boolean,
@@ -236,7 +382,7 @@ export function useAnchoredPanel<T extends HTMLElement>(
   }, [open]);
 
   if (!rect) {
-    return { rect: null, top: 0, maxHeight: preferredHeight, above: false };
+    return { rect: null, top: 0, bottom: 0, maxHeight: preferredHeight, above: false };
   }
   return { rect, ...anchoredPanelPlacement(rect, viewport, { ...options, preferredHeight, minHeight }) };
 }

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

@@ -11,17 +11,19 @@ export interface AnchorRect {
   height: number;
 }
 
-function sameRect(a: AnchorRect | null, b: AnchorRect | null): boolean {
+/**
+ * Whether two measurements are the same box, so a re-measure that moved nothing keeps the
+ * state it had (no render). Top, left, width and height decide it: an `AnchorRect`'s
+ * right and bottom are those sums. The kit's one copy — the tour's spotlight asks it too
+ * (DUP-11, refactor audit 2026-10).
+ */
+export function sameRect<R extends { top: number; left: number; width: number; height: number }>(
+  a: R | null,
+  b: R | 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
-  );
+  return a.top === b.top && a.left === b.left && a.width === b.width && a.height === b.height;
 }
 
 /**

package/src/hooks/use-authed-src.ts

@@ -68,6 +68,8 @@ interface State {
   type: string | undefined;
 }
 
+const NO_STATE: State = { key: null, src: null, status: "idle", error: undefined, type: undefined };
+
 async function toBlob(res: Blob | Response): Promise<Blob> {
   if (typeof Response !== "undefined" && res instanceof Response) {
     if (!res.ok) throw new Error(`HTTP ${res.status}`);
@@ -99,13 +101,17 @@ export function useAuthedSrc(
   const hasFetcher = !!fetcher;
   const [attempt, setAttempt] = useState(0);
   const key = url && enabled && hasFetcher ? `${attempt}|${url}` : null;
-  const [state, setState] = useState<State>({
-    key: null,
-    src: null,
-    status: "idle",
-    error: undefined,
-    type: undefined,
-  });
+  const [state, setState] = useState<State>(NO_STATE);
+  // The state answers one key, and only while that key is current. Once the key moves
+  // on, that request's effect is cleaned up and its object URL revoked, and a key can
+  // come back: Lightbox passes `enabled: open`, so closing and reopening a photo goes
+  // K → null → K, and paging back before the next picture loaded goes A → B → A. Kept,
+  // the state would answer the returning key with the revoked `blob:` as "ready" (or
+  // with the old error) until the refetch lands (BUG-3, refactor audit 2026-10).
+  // Dropped here, while rendering, rather than in the cleanup: a setState from a
+  // cleanup lands at a lower priority than the click that reopens, so that render
+  // could still see the old state.
+  if (state.key !== null && state.key !== key) setState(NO_STATE);
 
   useEffect(() => {
     const fetchFn = fetcherRef.current;

package/src/hooks/use-breakpoint.ts

@@ -99,9 +99,9 @@ export function lengthPx(length: number | RemLength | undefined, rootRemPx: numb
  * inside the floor the kit already sets: tokens.css's breakpoint variants are written in
  * it, and Tailwind v4 itself needs Safari 16.4, Chrome 111 and Firefox 128.
  *
- * A test's `matchMedia` stub that keyed on the old string (`"max-width: 767px"`, the
- * deprecated `PHONE_QUERY`) has to answer `(width < 768px)` now. `min-*` is unchanged,
- * character for character.
+ * A test's `matchMedia` stub that keyed on the old string (`"max-width: 767px"`,
+ * `PHONE_QUERY`'s, which went in 0.34) has to answer `(width < 768px)` now. `min-*` is
+ * unchanged, character for character.
  */
 export function breakpointQuery(variant: BreakpointVariant, scale = 1, remPx: number = readBrowserRemPx()): string {
   const max = variant.startsWith("max-");
@@ -125,7 +125,8 @@ export function useBreakpoint(variant: BreakpointVariant, fallback = false): boo
  * The phone layout: below `md` at the text size in force — `max-md:` in CSS. The single
  * answer for "is this the phone layout" (§10.4): the kit's own sheets and cards use it,
  * and an app's phone checks must too, so a tablet at 150 % gets every phone treatment
- * at once or none of them. Replaces `useMediaQuery(PHONE_QUERY)`.
+ * at once or none of them. Replaced `useMediaQuery(PHONE_QUERY)` in 0.32; that string
+ * went in 0.34.
  */
 export function usePhoneLayout(fallback = false): boolean {
   return useBreakpoint("max-md", fallback);

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

@@ -1,4 +1,5 @@
 import { useCallback, useEffect, useRef, useState } from "react";
+import { prefersReducedMotion } from "../lib/reduced-motion";
 
 /** 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
@@ -7,16 +8,14 @@ import { useCallback, useEffect, useRef, useState } from "react";
 export const OVERLAY_EXIT_MS = 220;
 
 /**
- * Whether the user has asked for no motion, read NOW. `true` where `matchMedia` is
- * absent (jsdom, SSR): nothing is painting there, so "no animation" is the only
- * correct answer. Shared by every exit timer in the package, so they agree.
+ * Whether an exit animation is skipped, read NOW: the user asked for no motion, or there
+ * is no `matchMedia` (jsdom, SSR) — nothing is painting there, so "no animation" is the
+ * only correct answer, and a closed overlay is gone at once in every test suite. Shared
+ * by every exit timer in the package, so they agree. The kit's one `prefersReducedMotion`
+ * (lib/reduced-motion), asked with that answer for the unknown case (DUP-11).
  */
-export function prefersReducedMotion(): boolean {
-  return (
-    typeof window === "undefined" ||
-    typeof window.matchMedia !== "function" ||
-    window.matchMedia("(prefers-reduced-motion: reduce)").matches
-  );
+export function skipsExitAnimation(): boolean {
+  return prefersReducedMotion(true);
 }
 
 /**
@@ -79,7 +78,7 @@ export function useCloseTransition(
     // 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.
-    if (prefersReducedMotion() || ms <= 0) {
+    if (skipsExitAnimation() || ms <= 0) {
       latest.current();
       return;
     }

package/src/hooks/use-debounce.ts

@@ -10,6 +10,15 @@ import { useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState } fr
  *
  * The first render returns `value` itself, not `undefined`: a list filtered by the
  * debounced query must render its initial state immediately, not after `ms`.
+ *
+ * **It re-arms when `value`'s IDENTITY changes** (an effect on `[value, ms]`), not its
+ * content. Pass a primitive — the typed query, a JSON string — or a value whose
+ * identity is stable (state, a `useMemo`). An object or array built in render is a new
+ * one every render, so the timer is re-armed on every render and the value never
+ * settles — or, when the debounced value feeds the render that built it, settles,
+ * renders, builds another and fires again, every `ms`, with nobody typing
+ * (Kurvenschmiede's control page, KS U9). Debounce `JSON.stringify(body)`, or a key that
+ * changes exactly when the content does, and build the object from that.
  */
 export function useDebounce<T>(value: T, ms: number): T {
   const [debounced, setDebounced] = useState(value);

package/src/hooks/use-dismiss.ts

@@ -1,31 +1,188 @@
 import { useEffect, useRef } from "react";
-import type { RefObject } from "react";
+import type { KeyboardEvent as ReactKeyboardEvent, RefObject } from "react";
+import { isComposing } from "../lib/ime";
+
+/*
+ * # One Escape stack (round 0.34 Wave 2, DUP-1)
+ *
+ * Escape closes the TOPMOST thing on screen, and only that: a list open in a dialog
+ * closes and the dialog stays; the next press closes the dialog.
+ *
+ * "Who owns Escape" used to be decided five ways. The anchored pickers listened on the
+ * document; Modal, FullBleedDialog, PickerSheet and Popover closed in their own panel's
+ * `onKeyDown` and stopped the key; CommandPalette closed without stopping it. A dialog's
+ * handler sits earlier on the key's path than any document listener, so Escape in an
+ * open list inside a Modal closed the MODAL and threw the form away (BUG-1, sev 4,
+ * kastlan's lease dialog), and HoverMenu, the numpad and a tooltip could not be
+ * dismissed inside a dialog at all. And Modal and FullBleedDialog disagreed on when a
+ * child had "claimed" the key: a ChipInput clearing its draft kept a Modal open and
+ * closed a FullBleedDialog.
+ *
+ * Now every overlay and picker pushes a layer while it is open ({@link useDismissLayer}),
+ * last in, first out, the way `use-overlay-history` stacks the Back gesture. One
+ * capture-phase listener on the document notes which layer is on top as each Escape
+ * goes down — before any handler on the page runs, so a layer that closes on the way
+ * cannot pass the key on to the one beneath it. That layer, and only that one, is
+ * handed the key:
+ *
+ * - at the first layer element the key passes on its way back up ({@link takeEscape},
+ *   which Modal's panel, a picker's search box and the rest call from their
+ *   `onKeyDown`). The key is stopped there, so nothing around the layers — a
+ *   FloatingPanel, an app's own panel — closes with it;
+ * - or, when focus is in none of them (a hover menu, a tooltip, the numpad over its
+ *   field, a press on the page), at the document once the key has been everywhere else.
+ *
+ * Layers stack in the order they OPEN, which is the order their effects run. Two that
+ * open in the same commit stack child first — the one case that order gets wrong, and
+ * one no overlay in the kit does: each opens on a press, after whatever it sits in.
+ *
+ * ## Claiming the key: one rule
+ *
+ * An Escape that means "undo this step" is not a dismissal: ChipInput clearing its
+ * draft, InlineEditField cancelling its edit, the date picker's month grid going back to
+ * the days. Those call {@link claimEscape}, and no layer is handed the key. The only
+ * other claim is the layer owner's OWN handler — a dialog's `onKeyDown` prop calling
+ * `preventDefault()` on Escape (a busy reauth dialog holding itself open, Kurvenschmiede's
+ * gear wizard asking first), through {@link runOwnKeyDown}. A `preventDefault()`
+ * anywhere else claims nothing: a search box keeping Chromium from clearing itself
+ * must not hold a dialog open (FullBleedDialog's 0.8.0 fix, which Modal never had).
+ *
+ * A handler that STOPS the key before it reaches a layer element has taken it too —
+ * that is the DOM, and it is what the kit's cell editors and confirm buttons do.
+ */
+
+/** A layer's handler, read through a ref so the stack holds one stable entry per open. */
+interface Layer {
+  escape: (e: KeyboardEvent) => void;
+}
+
+/** Open layers, oldest first. Module-level, because the order is ACROSS instances. */
+const layers: Layer[] = [];
+
+/** Escapes a claimant has taken — see {@link claimEscape}. Weak: an event is garbage
+ *  once its dispatch is over. */
+const claimed = new WeakSet<Event>();
+
+/** The Escape on its way through the page: the layer that was topmost as it went down,
+ *  and whether that layer has been handed it yet. */
+let inFlight: { event: KeyboardEvent; layer: Layer; done: boolean } | null = null;
+
+function nativeOf(e: KeyboardEvent | ReactKeyboardEvent): KeyboardEvent {
+  return "nativeEvent" in e ? e.nativeEvent : e;
+}
+
+function onCapture(e: KeyboardEvent): void {
+  if (e.key !== "Escape") return;
+  // An Escape inside an IME composition cancels the composition and nothing else.
+  const top = isComposing(e) ? undefined : layers[layers.length - 1];
+  inFlight = top ? { event: e, layer: top, done: false } : null;
+}
+
+/** The fallback: no layer element was on the key's path, or none took it. */
+function onBubble(e: KeyboardEvent): void {
+  handOver(e, false);
+}
+
+function handOver(e: KeyboardEvent | ReactKeyboardEvent, stop: boolean): boolean {
+  const native = nativeOf(e);
+  const flight = inFlight;
+  if (native.key !== "Escape" || !flight || flight.event !== native || flight.done) return false;
+  if (claimed.has(native)) return false;
+  flight.done = true;
+  // Consumed: a type="search" box does not clear itself as well, and a handler further
+  // out that checks `defaultPrevented` (FloatingPanel, an app's own panel) leaves it.
+  e.preventDefault();
+  if (stop) e.stopPropagation();
+  // A layer that closed on the way, by a handler of its own, has had its Escape.
+  if (layers.includes(flight.layer)) flight.layer.escape(native);
+  return true;
+}
+
+function push(layer: Layer): void {
+  if (layers.length === 0) {
+    document.addEventListener("keydown", onCapture, true);
+    document.addEventListener("keydown", onBubble);
+  }
+  layers.push(layer);
+}
+
+function pop(layer: Layer): void {
+  const at = layers.indexOf(layer);
+  if (at >= 0) layers.splice(at, 1);
+  if (layers.length > 0) return;
+  document.removeEventListener("keydown", onCapture, true);
+  document.removeEventListener("keydown", onBubble);
+  inFlight = null;
+}
 
 /**
- * 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).
+ * An Escape layer on the stack while `open`: the topmost layer is handed the next
+ * Escape and calls `onEscape`, every layer under it waits its turn. A list opened inside
+ * a dialog is above the dialog; a popover opened from a list, above the list.
+ *
+ * Where focus can be INSIDE the layer, its element's `onKeyDown` calls
+ * {@link takeEscape} too, so the key stops there — see the module note. `onEscape` is
+ * read live, so it need not be memoised; the layer is pushed and popped only when
+ * `open` flips.
  */
-export function useEscapeKey(handler: () => void, enabled = true): void {
-  const handlerRef = useRef(handler);
+export function useDismissLayer(open: boolean, onEscape: (e: KeyboardEvent) => void): void {
+  const handlerRef = useRef(onEscape);
   // 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.
+  // and the stack 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;
+    handlerRef.current = onEscape;
   });
   useEffect(() => {
-    if (!enabled) return;
-    const onKey = (e: KeyboardEvent) => {
-      if (e.key === "Escape") handlerRef.current();
-    };
-    document.addEventListener("keydown", onKey);
-    return () => document.removeEventListener("keydown", onKey);
-  }, [enabled]);
+    if (!open || typeof document === "undefined") return;
+    const layer: Layer = { escape: (e) => handlerRef.current(e) };
+    push(layer);
+    return () => pop(layer);
+  }, [open]);
+}
+
+/**
+ * For a layer's own element, in its `onKeyDown`: hands an Escape on its way up to the
+ * topmost layer — this one, unless something opened over it without taking focus (a
+ * tooltip, the numpad) — and stops it here. True when it did; false for any other key,
+ * a claimed Escape, or one already handed over.
+ */
+export function takeEscape(e: KeyboardEvent | ReactKeyboardEvent): boolean {
+  return handOver(e, true);
+}
+
+/**
+ * For an Escape that means "undo this step", not "close": the key is the caller's, and
+ * no layer is handed it. `preventDefault()`s it as well, so a handler further out that
+ * checks `defaultPrevented` leaves it alone, as before.
+ */
+export function claimEscape(e: KeyboardEvent | ReactKeyboardEvent): void {
+  claimed.add(nativeOf(e));
+  e.preventDefault();
+}
+
+/**
+ * Runs a layer owner's own key handler — a dialog's `onKeyDown` prop — and turns a
+ * `preventDefault()` it makes on Escape into a claim: the one way, beside
+ * {@link claimEscape}, to keep a layer open.
+ */
+export function runOwnKeyDown<E extends ReactKeyboardEvent>(e: E, handler: ((e: E) => void) | undefined): void {
+  if (!handler) return;
+  const before = e.defaultPrevented;
+  handler(e);
+  if (e.key === "Escape" && !before && e.defaultPrevented) claimed.add(nativeOf(e));
+}
+
+/**
+ * Calls `handler` on an Escape while `enabled` — as an Escape layer. Since 0.34 this is
+ * {@link useDismissLayer} with its arguments the other way round: it hears the key only
+ * while nothing opened above it, and inside a dialog it no longer loses the key to the
+ * dialog (Wave 2, DUP-1). `handler` is read live, so it need not be memoised.
+ */
+export function useEscapeKey(handler: () => void, enabled = true): void {
+  useDismissLayer(enabled, handler);
 }
 
 /**
@@ -56,7 +213,7 @@ export function useOutsideClick(
 ): void {
   const refsRef = useRef(refs);
   const handlerRef = useRef(handler);
-  // In an effect rather than during render — see the note on useEscapeKey.
+  // In an effect rather than during render — see the note in useDismissLayer.
   useEffect(() => {
     refsRef.current = refs;
     handlerRef.current = handler;

package/src/hooks/use-file-drop.ts

@@ -1,7 +1,7 @@
 import { useRef, useState } from "react";
 import type { DragEvent, ReactElement } from "react";
-import { useFilePicker } from "../components/file-button";
-import type { UseFilePickerOptions } from "../components/file-button";
+import { useFilePicker } from "./use-file-picker";
+import type { UseFilePickerOptions } from "./use-file-picker";
 
 /**
  * Turn ANY element into a file drop target — kastlan's ask, for the document list of

package/src/hooks/use-file-picker-labels.ts

@@ -0,0 +1,29 @@
+// The English words of the file pickers (./use-file-picker), in a module with no component
+// code: the English catalogue (src/i18n/defaults.ts) imports them without the component, so
+// `en` loads as one chunk like the other languages (0.34, KS U8). In hooks/ beside the hook
+// since 0.34 (MOD-8); components/file-button re-exports them.
+
+import type { FilePickerLabels } from "./use-file-picker";
+
+export const DEFAULT_FILE_PICKER_LABELS: FilePickerLabels = {
+  rejectedType: (name) => `“${name}” is not a supported file type`,
+  rejectedTypeOnly: (accept) => `Only ${accept} files`,
+  rejectedSize: (name, maxSize) => `“${name}” is larger than ${maxSize}`,
+  rejectedCount: (name, maxFiles) =>
+    `“${name}” was not added: at most ${maxFiles} ${maxFiles === 1 ? "file" : "files"}`,
+  rejectedInvalid: (name) => `“${name}” cannot be used here`,
+  rejectedMany: (count) => `${count} files were not added`,
+  rejectedPick: (count) =>
+    count === 1 ? "The file was not added" : `None of the ${count} files were added`,
+  selected: (count, firstName) => (count === 1 ? `“${firstName}” selected` : `${count} files selected`),
+  remove: (name) => `Remove “${name}”`,
+  clearAll: "Remove all files",
+  removed: (name) => `“${name}” removed`,
+  cleared: "All files removed",
+  dropzone: "File upload",
+  browse: "Browse",
+  empty: "Drop a file here",
+  emptyMultiple: "Drop files here",
+  hint: (accept) => (accept ? `Accepted: ${accept}` : "Any file type"),
+  busy: "Uploading…",
+};