@eifi1/ui-kit 0.33.1 → 0.35.0

package/src/components/dialog-frame.tsx

@@ -7,13 +7,15 @@ import { FOCUS_RING } from "./focus-ring";
 import { Modal, ModalCloseContext } from "./modal";
 import type { ModalProps } from "./modal";
 import { useKitLabels } from "../i18n/kit-labels";
+import { DEFAULT_DIALOG_FRAME_LABELS } from "./dialog-frame-labels";
 
 export interface DialogFrameLabels {
   /** Accessible name of the header's X, when {@link DialogFrameProps.closeButton} shows it. */
   close: string;
 }
 
-export const DEFAULT_DIALOG_FRAME_LABELS: DialogFrameLabels = { close: "Close" };
+// Defined in ./dialog-frame-labels, which holds no component code (0.34, KS U8).
+export { DEFAULT_DIALOG_FRAME_LABELS };
 
 /**
  * `ModalProps` minus the three this component owns: the NAME (`labelledBy` — the
@@ -21,7 +23,9 @@ export const DEFAULT_DIALOG_FRAME_LABELS: DialogFrameLabels = { close: "Close" }
  * (`children` is the body here, not the whole panel) and `title`, which is the dialog's
  * HEADING and a ReactNode rather than the browser's tooltip string — the collision
  * `PickerSheet` met first. Everything else, `size`, `draggable`, `fullBleed`,
- * `onKeyDown`, a `data-tour` anchor, still reaches the `Modal`.
+ * `onKeyDown`, a `data-tour` anchor, still reaches the `Modal` — and since 0.35 `ref`
+ * (round 0.35 R4): the panel, the `role="dialog"` element the frame's header, body and
+ * actions sit in.
  */
 export interface DialogFrameProps extends Omit<ModalProps, "labelledBy" | "children" | "title"> {
   /** The heading, and therefore the dialog's accessible name (`aria-labelledby`). */
@@ -158,7 +162,7 @@ export function DialogFrame({
         className={cn(
           // `last:pb-4`: a frame with neither body nor actions closes on its header.
           "flex shrink-0 items-start justify-between gap-2 px-4 pt-4 pb-3 last:pb-4",
-          headerDivider && "border-b border-[var(--border)]",
+          headerDivider && "border-b border-subtle",
           headerClassName,
         )}
       >
@@ -167,11 +171,11 @@ export function DialogFrame({
             while the X stays outside it, pinned to the top-end corner. */}
         <div className="flex min-w-0 flex-1 flex-wrap items-start justify-between gap-x-3 gap-y-2">
           <div className="min-w-0 grow basis-48">
-            <Heading id={titleId} className="text-lg font-semibold leading-snug text-[var(--text-primary)]">
+            <Heading id={titleId} className="text-lg font-semibold leading-snug text-primary">
               {title}
             </Heading>
             {hasDescription && (
-              <p id={descriptionId} className="mt-0.5 text-sm text-[var(--text-muted)]">
+              <p id={descriptionId} className="mt-0.5 text-sm text-muted">
                 {description}
               </p>
             )}
@@ -212,7 +216,7 @@ function FrameClose({ label, onClose }: { label?: string; onClose: () => void })
       type="button"
       onClick={close}
       aria-label={labels.close}
-      className={cn("-me-1.5 -mt-1 shrink-0 rounded p-1.5 text-[var(--text-muted)] outline-none hover:bg-[var(--bg-hover)] hover:text-[var(--text-secondary)]", FOCUS_RING)}
+      className={cn("-me-1.5 -mt-1 shrink-0 rounded p-1.5 text-muted outline-none hover:bg-hover hover:text-secondary", FOCUS_RING)}
     >
       <X aria-hidden className="size-5" />
     </button>
@@ -253,7 +257,7 @@ function FrameActions({
     <div
       className={cn(
         "flex shrink-0 flex-wrap items-center justify-end gap-2 px-4 py-3",
-        divider && "border-t border-[var(--border)]",
+        divider && "border-t border-subtle",
       )}
     >
       {typeof actions === "function" ? actions(close) : actions}

package/src/components/disclosure.tsx

@@ -1,12 +1,12 @@
 import { useEffect, useId, useState } from "react";
-import type { ComponentPropsWithoutRef, ReactNode } from "react";
+import type { ComponentPropsWithoutRef, ComponentPropsWithRef, ReactNode } from "react";
 import { ChevronDown } from "lucide-react";
 
 import { cn } from "../lib/cn";
 import { FOCUS_RING } from "./focus-ring";
 // Read at the moment of closing, as `useCloseTransition` does: the setting can change
 // under a long-lived page.
-import { prefersReducedMotion } from "../hooks/use-close-transition";
+import { skipsExitAnimation } from "../hooks/use-close-transition";
 
 /** How long the fold takes, in ms. The same number as the `duration-200` below and as
  *  the unmount timer, because they are the same movement. */
@@ -16,7 +16,7 @@ const COLLAPSE_MS = 200;
  * `extends` the div's props so an `id` (what a trigger's `aria-controls` points at), a
  * `data-tour` anchor or a test id reaches the element that folds.
  */
-export interface CollapseProps extends ComponentPropsWithoutRef<"div"> {
+export interface CollapseProps extends ComponentPropsWithRef<"div"> {
   open: boolean;
   /**
    * Keep the children mounted while shut (hidden and `inert`) instead of unmounting
@@ -63,7 +63,7 @@ export function Collapse({ open, keepMounted = false, children, className, style
   const [prevOpen, setPrevOpen] = useState(open);
   if (open !== prevOpen) {
     setPrevOpen(open);
-    setLingering(!open && !prefersReducedMotion());
+    setLingering(!open && !skipsExitAnimation());
   }
   useEffect(() => {
     if (!lingering) return;
@@ -113,7 +113,7 @@ export type DisclosureTriggerProps = Omit<
  * name: here it is the header's content (and a ReactNode), not the browser's tooltip.
  * Everything else reaches the outer element.
  */
-export interface DisclosureProps extends Omit<ComponentPropsWithoutRef<"div">, "title"> {
+export interface DisclosureProps extends Omit<ComponentPropsWithRef<"div">, "title"> {
   /** What the header says. A node, so a status chip or a count can sit in it. */
   title: ReactNode;
   /** The smaller line under the title — what is inside, for a reader deciding whether
@@ -346,22 +346,22 @@ export function Disclosure({
             // card's hover paint on the stretched area / the row, not the text box.
             cn(
               "min-w-0 flex-1 after:absolute after:inset-0 after:content-['']",
-              "focus-visible:after:ring-[length:var(--focus-ring-width)] focus-visible:after:ring-inset focus-visible:after:ring-[var(--brand)]",
+              "focus-visible:after:ring-focus focus-visible:after:ring-inset focus-visible:after:ring-brand",
               card ? cn("after:rounded-lg", joined && "after:rounded-b-none") : !menu && "after:rounded-sm",
             )
           : FOCUS_RING,
         card
           ? cn(
               "items-center justify-between rounded-lg p-4",
-              trailingBeside ? "pe-0" : "hover:bg-[var(--bg-hover)] focus-visible:ring-inset",
+              trailingBeside ? "pe-0" : "hover:bg-hover focus-visible:ring-inset",
               joined && "rounded-b-none",
             )
           : menu
             ? // TOPBAR_MENU_ITEM_CLASS's row, spelled out rather than imported: a
               // component does not reach up into the shell. A test holds the two to
               // the same classes.
-              "items-center justify-between gap-3 px-3 py-2 text-sm text-[var(--text-secondary)] hover:bg-[var(--bg-hover)] focus-visible:ring-inset"
-            : "items-center rounded-sm text-sm font-medium text-[var(--text-secondary)] hover:text-[var(--text-primary)]",
+              "items-center justify-between gap-3 px-3 py-2 text-sm text-secondary hover:bg-hover focus-visible:ring-inset"
+            : "items-center rounded-sm text-sm font-medium text-secondary hover:text-primary",
         headerClassName,
       )}
     >
@@ -377,10 +377,10 @@ export function Disclosure({
             <Chevron open={open} small />
           </span>
         ) : (
-          <span className={cn("block", card && "text-sm font-semibold text-[var(--text-primary)]")}>{title}</span>
+          <span className={cn("block", card && "text-sm font-semibold text-primary")}>{title}</span>
         )}
         {hint !== undefined && (
-          <span className="mt-0.5 block text-xs font-normal text-[var(--text-muted)]">{hint}</span>
+          <span className="mt-0.5 block text-xs font-normal text-muted">{hint}</span>
         )}
       </span>
       {/* The space is for the accessible name — "Net profit 1,234.50", not
@@ -402,7 +402,7 @@ export function Disclosure({
   return (
     <div
       {...rest}
-      className={cn(card && "rounded-lg border border-[var(--border)] bg-[var(--bg-surface)] shadow-sm", className)}
+      className={cn(card && "rounded-lg border border-subtle bg-surface shadow-sm", className)}
     >
       {trailingBeside ? (
         <div
@@ -410,7 +410,7 @@ export function Disclosure({
             "relative flex items-center gap-2",
             card &&
               cn(
-                "rounded-lg pe-4 has-[[data-disclosure-trigger]:enabled:hover]:bg-[var(--bg-hover)]",
+                "rounded-lg pe-4 has-[[data-disclosure-trigger]:enabled:hover]:bg-hover",
                 joined && "rounded-b-none",
               ),
           )}
@@ -454,7 +454,7 @@ function Chevron({
     <ChevronDown
       aria-hidden
       className={cn(
-        "shrink-0 text-[var(--text-muted)] transition-transform duration-200 ease-out motion-reduce:transition-none",
+        "shrink-0 text-muted transition-transform duration-200 ease-out motion-reduce:transition-none",
         small ? "size-3.5" : "size-4",
         leading ? !open && "-rotate-90 rtl:rotate-90" : open && "rotate-180",
       )}

package/src/components/dropdown.tsx

@@ -1,23 +1,35 @@
-import { useCallback, useEffect, useRef, useState } from "react";
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import type {
   ComponentPropsWithoutRef,
+  ComponentPropsWithRef,
   KeyboardEvent as ReactKeyboardEvent,
   ReactNode,
+  Ref,
   RefObject,
 } from "react";
 import { createPortal } from "react-dom";
 import { Search } from "lucide-react";
-import { useAnchoredPanel } from "../hooks/use-anchored-panel";
-import { useEscapeKey, useOutsideClick } from "../hooks/use-dismiss";
+import { anchoredInline, useAnchoredPanel } from "../hooks/use-anchored-panel";
+import { runOwnKeyDown, takeEscape, useDismissLayer, useOutsideClick } from "../hooks/use-dismiss";
+import type { DismissLayer } from "../hooks/use-dismiss";
 import { useOverlayHistory } from "../hooks/use-overlay-history";
 import { cn } from "../lib/cn";
-import { FIELD_TOUCH_TEXT } from "./ui";
+import { FIELD_TOUCH_TEXT } from "./field-base";
+import { mergeRefs } from "./field-parts";
 import { FOCUS_RING } from "./focus-ring";
 import { useAnchorDir } from "./use-anchor-dir";
 
+/** Each list's Escape layer, filed under the refs {@link useDropdown} and
+ *  {@link useDropdownSearch} hand out (`panelRef`, `inputRef`), for the panel and the
+ *  search box those refs are passed to — see "The caller's own handler" on
+ *  {@link useDropdown} (round 0.35 R2). Weak: a list's refs go with its component. */
+const listLayers = new WeakMap<object, DismissLayer>();
+
 /**
- * Open state + close-on-outside-click for the custom dropdowns (MultiSelect,
- * CurrencySelect, AmountInput's currency picker, Combobox). Attach `wrapperRef`
+ * Open state + close-on-outside-click for a custom dropdown — the two input-shaped
+ * comboboxes, and an app's own panel. (MultiSelect, CurrencySelect, GroupedPicker and
+ * AmountInput's currency picker moved onto `useComboboxCore` + `ComboboxPanel` in round
+ * 0.34, Wave 2 DUP-4, for the phone sheet and the portal.) Attach `wrapperRef`
  * to the relatively-positioned container; the popover lives inside it so a click
  * anywhere else closes it.
  *
@@ -63,20 +75,45 @@ import { useAnchorDir } from "./use-anchor-dir";
  * This hook had no Escape at all (the audit's §a11y): Back closed these lists, an
  * outside press closed them, and the one key every other dismissible surface in the
  * package answers to did nothing — so a keyboard user who opened a list had no way
- * out of it that did not also choose something. {@link useEscapeKey} is the listener
- * `Modal`, `Popover` and `useComboboxCore` already dismiss through, so the package
- * keeps one answer to "what does Escape do" rather than growing a fifth.
+ * out of it that did not also choose something. An open list is a layer on the kit's
+ * one Escape stack ({@link useDismissLayer}), as `Modal`, `Popover` and
+ * `useComboboxCore` are, so the package keeps one answer to "what does Escape do".
  *
  * Escape RESTORES FOCUS; an outside press does not. A press has already put focus
  * where the user pointed, and dragging it back from there would be the bug. Attach
  * `triggerRef` to the control that opens the panel and the keyboard paths — Escape,
- * Tab, a commit — hand focus back to it; leave it unattached and they simply close,
- * which is what the callers written before this get.
+ * Tab, a commit — hand focus back to it; leave it unattached and they hand it back to
+ * whatever held focus when the list opened, which is the control that was pressed.
+ *
+ * ## Escape inside a dialog (round 0.34 BUG-1, Wave 2 DUP-1)
+ *
+ * One press in an open list inside a `Modal` or a `FullBleedDialog` used to close the
+ * DIALOG, form and all, and leave the list open: the dialog took Escape in its own
+ * `onKeyDown` before a document listener could. On the stack the list is above the
+ * dialog, so the list closes and the dialog stays. {@link DropdownPanel} and
+ * {@link DropdownSearchHeader} take the key on their own elements, where focus is,
+ * and stop it there — so a caller passes nothing new, AmountInput's currency chip
+ * included.
+ *
+ * ## The caller's own handler (round 0.35 R2)
+ *
+ * A caller's `onKeyDown` on {@link DropdownPanel} or {@link DropdownSearchHeader} hears
+ * Escape only while this list is the layer on top — the rule the dialogs got first. A
+ * tooltip over a row takes that press first, and the next one is the handler's, whose
+ * `preventDefault()` still keeps the list. The two find the list's layer through the
+ * refs this hook hands out — the panel through `panelRef`, the search box through
+ * {@link useDropdownSearch}'s `inputRef` — so a caller passes nothing new. One handed
+ * neither (an un-anchored panel may leave `panelRef` off) hears every key, as before.
+ *
+ * `escapeLayer: false` is for a caller that registers its own layer: the editable
+ * comboboxes, whose list can be "open" with nothing in it to show — an Escape there
+ * belongs to the dialog.
  */
 export function useDropdown<T extends HTMLElement = HTMLDivElement>({
   backCloses = true,
   panelIsSheet = !backCloses,
-}: { backCloses?: boolean; panelIsSheet?: boolean } = {}) {
+  escapeLayer = true,
+}: { backCloses?: boolean; panelIsSheet?: boolean; escapeLayer?: boolean } = {}) {
   const [open, setOpen] = useState(false);
   const wrapperRef = useRef<T>(null);
   // The control that opens the panel — see the note above on why only the keyboard
@@ -87,17 +124,33 @@ export function useDropdown<T extends HTMLElement = HTMLDivElement>({
   // the wrapper" answers no for every click on the list itself and the first option a
   // user picked closed the dropdown without picking anything.
   const panelRef = useRef<HTMLDivElement>(null);
+  // Where focus was as the list opened — the trigger focus goes back to when the
+  // caller attached none. Read in an effect, before `useDropdownSearch`'s frame moves
+  // focus into the search box.
+  const openerRef = useRef<HTMLElement | null>(null);
+  useEffect(() => {
+    if (!open) return;
+    const el = document.activeElement;
+    openerRef.current = el instanceof HTMLElement && el !== document.body ? el : null;
+  }, [open]);
   const close = useCallback(() => setOpen(false), []);
   // Closing unmounts whatever held focus — the search box, the row the keyboard was
   // on — and the browser then drops focus on <body>: the caret vanishes and the next
-  // Tab restarts at the top of the document. Whoever closed the list with a key gets
-  // it handed back to the trigger they opened it from.
+  // Tab restarts at the top of the document, and inside a dialog the next Escape goes
+  // nowhere. Whoever closed the list with a key gets focus handed back to the trigger
+  // they opened it from.
   const closeToTrigger = useCallback(() => {
     setOpen(false);
-    triggerRef.current?.focus();
+    const back = triggerRef.current ?? openerRef.current;
+    if (back?.isConnected) back.focus();
   }, []);
   useOutsideClick([wrapperRef, panelRef], close, open && !panelIsSheet);
-  useEscapeKey(closeToTrigger, open);
+  // See "Escape inside a dialog" above.
+  const layer = useDismissLayer(open && escapeLayer, closeToTrigger);
+  // Filed under `panelRef` for the panel's own handler — "The caller's own handler" above.
+  useEffect(() => {
+    listLayers.set(panelRef, layer);
+  }, [panelRef, layer]);
   // Same close path Escape and an outside click take, so a list dismissed by Back
   // cannot end up in a different state from one dismissed any other way.
   useOverlayHistory(open && backCloses, close);
@@ -113,6 +166,12 @@ export function useDropdownSearch<T extends HTMLElement = HTMLDivElement>() {
     useDropdown<T>();
   const [query, setQuery] = useState("");
   const inputRef = useRef<HTMLInputElement>(null);
+  // The list's layer again, under `inputRef` for the search box's handler (round 0.35
+  // R2). `useDropdown`'s effect, which runs first, has filed it under `panelRef`.
+  useEffect(() => {
+    const layer = listLayers.get(panelRef);
+    if (layer) listLayers.set(inputRef, layer);
+  }, [panelRef]);
   useEffect(() => {
     if (open) {
       // eslint-disable-next-line react-hooks/set-state-in-effect -- reset the query on open
@@ -137,7 +196,7 @@ export function useDropdownSearch<T extends HTMLElement = HTMLDivElement>() {
  *  where the focus is (see the note above), so the div's own handler signature is
  *  omitted in favour of it. */
 export interface DropdownSearchHeaderProps
-  extends Omit<ComponentPropsWithoutRef<"div">, "onKeyDown"> {
+  extends Omit<ComponentPropsWithRef<"div">, "onKeyDown"> {
   query: string;
   onQueryChange: (v: string) => void;
   inputRef: RefObject<HTMLInputElement | null>;
@@ -146,7 +205,9 @@ export interface DropdownSearchHeaderProps
   listboxId?: string;
   /** The id of the option the arrow keys are currently on, if any. */
   activeId?: string;
-  /** Arrow/Home/End/Enter/Tab — the list's keyboard, handled where the focus is. */
+  /** Arrow/Home/End/Enter/Tab — the list's keyboard, handled where the focus is.
+   *  Escape closes the list (the topmost layer on the kit's Escape stack); call
+   *  `preventDefault()` on it here to keep it. */
   onKeyDown?: (e: ReactKeyboardEvent<HTMLInputElement>) => void;
 }
 
@@ -192,17 +253,24 @@ export function DropdownSearchHeader({
     <div
       {...rest}
       className={cn(
-        "flex items-center gap-2 border-b border-[var(--border)] px-2 py-1.5",
+        "flex items-center gap-2 border-b border-subtle px-2 py-1.5",
         className,
       )}
     >
-      <Search className="size-4 text-[var(--text-placeholder)]" />
+      <Search className="size-4 text-placeholder" />
       <input
         ref={inputRef}
         type="text"
         value={query}
         onChange={(e) => onQueryChange(e.target.value)}
-        onKeyDown={onKeyDown}
+        onKeyDown={(e) => {
+          // The caller's handler hears Escape only while the list is on top (round 0.35
+          // R2) — the layer filed under `inputRef`, when {@link useDropdownSearch} made it.
+          runOwnKeyDown(e, onKeyDown, listLayers.get(inputRef));
+          // Focus is in this box while the list is up, so this is where Escape lands
+          // first — see "Escape inside a dialog" on {@link useDropdown}.
+          takeEscape(e);
+        }}
         placeholder={placeholder}
         aria-label={ariaLabel}
         aria-controls={listboxId}
@@ -211,7 +279,7 @@ export function DropdownSearchHeader({
         // FIELD_TOUCH_TEXT: a search box is a field — at least 16 px on touch, or iOS zooms
         // the page the moment a picker opens and focuses it (§10.1).
         className={cn(
-          "w-full rounded-sm bg-transparent text-sm outline-none placeholder:text-[var(--text-placeholder)] text-[var(--text-primary)]",
+          "w-full rounded-sm bg-transparent text-sm outline-none placeholder:text-placeholder text-primary",
           FOCUS_RING,
           FIELD_TOUCH_TEXT,
         )}
@@ -230,17 +298,23 @@ export interface DropdownPanelProps extends ComponentPropsWithoutRef<"div"> {
   listProps?: ComponentPropsWithoutRef<"ul">;
   /** The trigger to hang off. Given, the panel portals and goes `fixed`. */
   anchorRef?: RefObject<HTMLElement | null>;
-  /** {@link useDropdown}'s `panelRef`, so an outside-click sees this as inside. */
+  /** {@link useDropdown}'s `panelRef`, so an outside-click sees this as inside. Escape
+   *  anywhere in the panel, on a row as in the search box, closes the list rather than
+   *  a dialog around it. It is also how the panel finds the list's Escape layer, for
+   *  its `onKeyDown` (round 0.35 R2: see "The caller's own handler" there). */
   panelRef?: RefObject<HTMLDivElement | null>;
   /** Panel width in px, for the anchored form (the CSS `w-*` cannot be measured). */
   width?: number;
-  /** Which of the panel's edges lines up with the trigger's, room permitting.
-   *  `start`/`end` follow the trigger's reading direction — `end` is the right edge
-   *  in a left-to-right form and the left one in a right-to-left form — and are what
-   *  the kit's own pickers pass; `left`/`right` stay physical. Default `end`, which
-   *  is the old `right` in a left-to-right page. */
-  align?: "left" | "right" | "start" | "end";
+  /** Which of the panel's edges lines up with the trigger's, room permitting, by the
+   *  trigger's reading direction — `end` is the right edge in a left-to-right form and
+   *  the left one in a right-to-left form. Default `end`. The physical `left` / `right`
+   *  went in 0.35 (round 0.35 R1, refactor audit 2026-10, API-6e): `right` is `end` in a
+   *  left-to-right page, `left` is `start`. */
+  align?: "start" | "end";
   children: ReactNode;
+  /** The panel, where the rest of the props go (0.34, API-2, refactor audit 2026-10) —
+   *  merged with `panelRef`, so the outside-click still sees it. */
+  ref?: Ref<HTMLDivElement>;
 }
 
 /**
@@ -282,10 +356,21 @@ export function DropdownPanel({
   align = "end",
   children,
   style,
+  onKeyDown,
+  ref,
   ...rest
 }: DropdownPanelProps) {
+  const setPanel = useMemo(() => mergeRefs(panelRef, ref), [panelRef, ref]);
   const anchored = useAnchoredPanel(anchorRef ?? EMPTY_REF, Boolean(anchorRef));
   const dir = useAnchorDir(anchorRef ?? EMPTY_REF, Boolean(anchorRef));
+  // A row the keyboard reached by Tab holds focus too, and its Escape has to close the
+  // list as the search box's does (BUG-1). The caller's handler first, as everywhere.
+  const handleKeyDown = (e: ReactKeyboardEvent<HTMLDivElement>) => {
+    // It hears Escape only while the list is on top, a tooltip over a row taking the
+    // press first (round 0.35 R2) — the layer filed under `panelRef`, when handed one.
+    runOwnKeyDown(e, onKeyDown, panelRef && listLayers.get(panelRef));
+    takeEscape(e);
+  };
   const body = (
     <>
       {header}
@@ -298,7 +383,7 @@ export function DropdownPanel({
             end up with one child that is not an option. The em dash still reads — it
             is the row's semantics that are dropped, not its text. */}
         {empty && (
-          <li role="presentation" className="px-3 py-2 text-sm text-[var(--text-muted)]">
+          <li role="presentation" className="px-3 py-2 text-sm text-muted">
             —
           </li>
         )}
@@ -308,12 +393,14 @@ export function DropdownPanel({
 
   if (!anchorRef) {
     return (
+      // eslint-disable-next-line jsx-a11y/no-static-element-interactions -- never focused itself: it catches Escape bubbling from the search box or a row inside it.
       <div
         {...rest}
         style={style}
-        ref={panelRef}
+        ref={setPanel}
+        onKeyDown={handleKeyDown}
         className={cn(
-          "absolute z-30 mt-1 rounded-md border border-[var(--border)] bg-[var(--bg-surface)] shadow-lg",
+          "absolute z-30 mt-1 rounded-md border border-subtle bg-surface shadow-lg",
           "[&>ul]:max-h-64",
           className,
         )}
@@ -325,20 +412,19 @@ export function DropdownPanel({
 
   const rect = anchored.rect;
   if (!rect) return null;
-  // Clamped exactly as `Popover` clamps: the panel may leave the trigger's edge to
-  // stay on screen, because a list half off the viewport is the bug this exists for.
-  // The portal leaves the subtree the trigger's `dir` came from, so it is read off
-  // the trigger — for the alignment here, and for the panel's own `dir` below,
-  // without which a right-to-left form got a left-to-right list.
-  const physical =
-    align === "start" ? (dir === "rtl" ? "right" : "left") : align === "end" ? (dir === "rtl" ? "left" : "right") : align;
-  const wanted = physical === "right" ? rect.right - width : rect.left;
-  const left = Math.min(Math.max(8, wanted), window.innerWidth - width - 8);
+  // Clamped to the glass as `Popover` is (Wave 2, DUP-7): the panel may leave the
+  // trigger's edge to stay on screen, because a list half off the viewport is the bug
+  // this exists for. The portal leaves the subtree the trigger's `dir` came from, so it
+  // is read off the trigger — for the alignment here, and for the panel's own `dir`
+  // below, without which a right-to-left form got a left-to-right list.
+  const { left } = anchoredInline(rect, width, { dir, align });
   return createPortal(
+    // eslint-disable-next-line jsx-a11y/no-static-element-interactions -- never focused itself: it catches Escape bubbling from the search box or a row inside it.
     <div
       {...rest}
-      ref={panelRef}
+      ref={setPanel}
       dir={dir}
+      onKeyDown={handleKeyDown}
       // The caller's `style` is kept underneath, but the placement is measured rather
       // than chosen (dev#548: an `overflow` ancestor clipped a third of this panel
       // away), so these values are the panel's own. Flipped above, it hangs from its
@@ -354,7 +440,7 @@ export function DropdownPanel({
         maxHeight: anchored.maxHeight,
       }}
       className={cn(
-        "z-50 flex flex-col overflow-hidden rounded-md border border-[var(--border)] bg-[var(--bg-surface)] shadow-lg",
+        "z-50 flex flex-col overflow-hidden rounded-md border border-subtle bg-surface shadow-lg",
         // The list, not the panel, is what scrolls: the search header has to stay put
         // while the options move under it.
         "[&>ul]:min-h-0 [&>ul]:flex-1",

package/src/components/empty-state.tsx

@@ -0,0 +1,137 @@
+import type { ComponentPropsWithRef, ReactNode } from "react";
+import { cn } from "../lib/cn";
+
+export interface EmptyStateProps extends Omit<ComponentPropsWithRef<"div">, "children" | "title"> {
+  /** The box renders `title` and `hint` in its own two-line rhythm, which is what makes
+   *  every empty state in three apps look like the same thing — so there is no
+   *  `children` slot to put arbitrary content in. The two slots below are the only
+   *  other things an empty state has turned out to need, and each has a fixed place. */
+  /** Nodes rather than strings, so a title can carry a code, a link or an emphasised
+   *  word — keksdose's error boundary shows the error's name in `<code>` — while the
+   *  box still sets the type. */
+  title: ReactNode;
+  hint?: ReactNode;
+  /**
+   * Render the title as a heading of this level. Left out it is a `<div>`, as before:
+   * most empty states are a message inside a section that already has its heading.
+   * keksdose's error boundary IS the page when it trips, and its `<h2>` went missing
+   * when it moved onto EmptyState — so the page's heading outline lost the one line
+   * that says what happened. Only the element changes; the look is the box's.
+   */
+  headingAs?: "h2" | "h3" | "h4" | "h5" | "h6";
+  /** A glyph ABOVE the title — kastlan's InboxEmptyState (an inbox), keksdose's
+   *  offline card (a cloud with a slash). Sized by the box (`[&_svg]:size-8`) and
+   *  muted, so five call sites cannot pick five sizes; hidden from assistive tech,
+   *  because the title already says what it shows. */
+  icon?: ReactNode;
+  /** What to do about it, BELOW the hint: keksdose's query-state cards (Retry), its
+   *  error boundary (Retry / Reload / Go home — pass all three in a fragment, they
+   *  wrap and centre as one row), kastlan's "Create a rule". Buttons or links the
+   *  caller renders; the box only places them. */
+  action?: ReactNode;
+  /**
+   * `box` (default): the dashed, padded card that stands in for a whole section.
+   * `inline`: one quiet line with no box — for the empty state INSIDE something that
+   * already has its own frame, where a dashed card would be a box in a box. keksdose
+   * writes that line by hand five times as a muted `<p className="py-6 text-center">`:
+   * the notification inbox (notification-inbox:140), a support thread
+   * (support-thread:144), the assistant (assistant-page:321), the admin support panel
+   * (support-panel:265) and the funding dialog (funding-dialog:89). The icon shrinks
+   * to the text's size and sits before the title, the hint follows on the same line,
+   * and the row wraps only when it must. Centred like the box; `className="justify-start"`
+   * for a list that reads from the start edge (funding-dialog).
+   */
+  variant?: "box" | "inline";
+  /**
+   * Colour the icon and the title: `danger` for an error standing where the content
+   * should be — kastlan's ErrorState (shared/components/feedback/error-state.tsx) and
+   * its error boundary's fallback (error-boundary.tsx:16), both a red triangle over a
+   * message — and `success` for an empty state that is GOOD news, kastlan's "No defects
+   * recorded for this room" (handover defects-step.tsx:142, a green check). Left out,
+   * both stay muted. The hint stays muted either way: it is the explanation, not the
+   * verdict.
+   */
+  tone?: "danger" | "success";
+  /**
+   * `inline` only (0.11.0). `sm`: 12px, start-aligned and tight (`py-1`) — the empty
+   * line INSIDE a detail panel, under a panel heading and among `text-xs` rows, where
+   * the default's 14px centred line with `py-4` read as a section of its own.
+   * keksdose's holdings panel (holdings-panel:563), asset-loan panel
+   * (asset-loan-panel:108) and loan-payment panel (loan-payment-panel:191) each wrote
+   * `className="justify-start py-1"` over it and still got body-size text. Default `md`,
+   * the look it had. Ignored by the box.
+   */
+  size?: "sm" | "md";
+}
+
+const EMPTY_STATE_TONE: Record<"danger" | "success", string> = {
+  danger: "text-danger",
+  success: "text-success",
+};
+
+export function EmptyState({
+  title,
+  hint,
+  icon,
+  action,
+  headingAs,
+  variant = "box",
+  tone,
+  size = "md",
+  className,
+  ...rest
+}: EmptyStateProps) {
+  const Title = headingAs ?? "div";
+  const toneClass = tone ? EMPTY_STATE_TONE[tone] : undefined;
+  const hasHint = hint != null && hint !== false && hint !== "";
+  if (variant === "inline") {
+    const sm = size === "sm";
+    return (
+      <div
+        {...rest}
+        className={cn(
+          "flex flex-wrap items-center text-muted",
+          sm
+            ? "justify-start gap-x-1.5 gap-y-0.5 py-1 text-start text-xs"
+            : "justify-center gap-x-2 gap-y-1 py-4 text-center text-sm",
+          className,
+        )}
+      >
+        {icon != null && (
+          <span
+            aria-hidden
+            className={cn("flex text-placeholder", sm ? "[&_svg]:size-3.5" : "[&_svg]:size-4", toneClass)}
+          >
+            {icon}
+          </span>
+        )}
+        {/* No weight of its own: one muted line is what these sites were, and a
+            bold title would turn a quiet "nothing here" into a heading. */}
+        <Title className={cn(sm ? "text-xs" : "text-sm", toneClass)}>{title}</Title>
+        {hasHint && <span className="text-xs">{hint}</span>}
+        {action != null && <span className="flex flex-wrap items-center gap-2">{action}</span>}
+      </div>
+    );
+  }
+  return (
+    <div
+      {...rest}
+      className={cn(
+        "flex flex-col items-center justify-center rounded-lg border border-dashed border-strong bg-surface-2 px-4 py-10 text-center text-sm text-muted",
+        className,
+      )}
+    >
+      {icon != null && (
+        <div aria-hidden className={cn("mb-3 text-placeholder [&_svg]:size-8", toneClass)}>
+          {icon}
+        </div>
+      )}
+      {/* `text-sm`: a heading keeps the box's size, not whatever a stylesheet gives h2. */}
+      <Title className={cn("text-sm font-medium text-secondary", toneClass)}>{title}</Title>
+      {hasHint && <div className="mt-1 text-xs">{hint}</div>}
+      {action != null && (
+        <div className="mt-4 flex flex-wrap items-center justify-center gap-2">{action}</div>
+      )}
+    </div>
+  );
+}