@eifi1/ui-kit 0.33.0 → 0.34.0

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,28 @@
-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 { 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";
 
 /**
- * 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 +68,35 @@ 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.
+ *
+ * `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 +107,29 @@ 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.
+  useDismissLayer(open && escapeLayer, closeToTrigger);
   // 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);
@@ -137,7 +169,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 +178,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 +226,22 @@ 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) => {
+          runOwnKeyDown(e, onKeyDown);
+          // 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 +250,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,19 +269,32 @@ 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. */
   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";
+   *  the kit's own pickers pass; `left`/`right` are physical and deprecated
+   *  ({@link PhysicalAlign}). Default `end`, which is the old `right` in a
+   *  left-to-right page. */
+  align?: "start" | "end" | PhysicalAlign;
   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>;
 }
 
+/**
+ * @deprecated 0.34 — `"start"` / `"end"`, which follow the reading direction: `"right"`
+ * is `"end"` in a left-to-right page, the default; removed in 0.35 (refactor audit
+ * 2026-10, API-6e). The physical edges DropdownPanel's `align` still takes.
+ */
+type PhysicalAlign = "left" | "right";
+
 /**
  * The floating popover surface for the searchable dropdowns: bordered/shadowed
  * panel, an optional `header` slot (search box, plus any actions), and a
@@ -282,10 +334,19 @@ 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>) => {
+    runOwnKeyDown(e, onKeyDown);
+    takeEscape(e);
+  };
   const body = (
     <>
       {header}
@@ -298,7 +359,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 +369,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,26 +388,35 @@ 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 those five values are the panel's own.
-      style={{ ...style, position: "fixed", top: anchored.top, left, width, maxHeight: anchored.maxHeight }}
+      // away), so these values are the panel's own. Flipped above, it hangs from its
+      // bottom edge, so a list shorter than its cap still meets the trigger (keksdose
+      // K1); the edge not in use is cleared, a caller's included.
+      style={{
+        ...style,
+        position: "fixed",
+        top: anchored.above ? undefined : anchored.top,
+        bottom: anchored.above ? anchored.bottom : undefined,
+        left,
+        width,
+        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>
+  );
+}

package/src/components/entity-combobox.tsx

@@ -2,27 +2,30 @@ import { useCallback, useId } from "react";
 import type { ComponentPropsWithoutRef, ReactNode, Ref } from "react";
 import { X } from "lucide-react";
 import { cn } from "../lib/cn";
-import { FieldChevron, FieldLabel, FIELD_TRIGGER, FIELD_FLOATING_PAD, FIELD_INVALID } from "./ui";
+import { FieldChevron, FIELD_TRIGGER, FIELD_FLOATING_PAD, FIELD_INVALID } from "./field-base";
+import { FieldLabel } from "./field-parts";
 import {
   ComboboxPanel,
   endHintRowProps,
   offersCreate,
   useComboboxCore,
-  useComboboxFieldError,
   type ComboClearValue,
   type ComboOption,
 } from "./combobox-core";
 import { DEFAULT_COMBOBOX_LABELS, DEFAULT_COMMON_LABELS, useKitLabels } from "../i18n/kit-labels";
 import {
+  assignRef,
   EndHintRow,
   FieldCaption,
   LABEL_IN_ROW,
   LockedReason,
+  mergeDescribedBy,
   StaticLabelRow,
+  useFieldError,
   useFieldHint,
   useLockReason,
+  type DisabledReasonDisplay,
 } from "./field-parts";
-import { assignRef, mergeDescribedBy } from "./choice-parts";
 import { useCommitReason, type CommitScope } from "./write-lock";
 
 export type { ComboClearValue, ComboOption } from "./combobox-core";
@@ -90,6 +93,9 @@ export interface EntityComboboxProps<V extends string | number, C extends ComboC
    * off there and put `commit` on the Save. No provider, or an unlocked one: no effect.
    */
   commit?: CommitScope;
+  /** Where the reason shows — {@link Button}'s `disabledReasonDisplay`: a line under the
+   *  field at Large and on a touch screen by default, the tooltip otherwise (DUP-3). */
+  disabledReasonDisplay?: DisabledReasonDisplay;
   /** When set, a "create" row appears for a non-empty query with no exact match. */
   onCreate?: (query: string) => void;
   createLabel?: (query: string) => string;
@@ -166,6 +172,7 @@ export function EntityCombobox<V extends string | number, C extends ComboClearVa
     sheetTitle,
     disabled,
     disabledReason,
+    disabledReasonDisplay,
     commit,
     onCreate,
     createLabel,
@@ -200,11 +207,7 @@ export function EntityCombobox<V extends string | number, C extends ComboClearVa
     debounceMs,
   });
   const hintParts = useFieldHint(hint, ariaDescribedBy);
-  const field = useComboboxFieldError(
-    error,
-    invalid || ariaInvalid === true || ariaInvalid === "true",
-    hintParts.describedBy,
-  );
+  const field = useFieldError(error, invalid, hintParts.describedBy, ariaInvalid);
   // The props are the per-instance overrides, the provider the app-wide ones; a
   // prop left `undefined` falls through to the provider rather than masking it.
   const labels = useKitLabels("combobox", DEFAULT_COMBOBOX_LABELS, {
@@ -256,7 +259,7 @@ export function EntityCombobox<V extends string | number, C extends ComboClearVa
   // copy of the reason, Button's anatomy — `block` so a full-width field stays full width.
   const withLock = (trigger: ReactNode) =>
     lock.locked ? (
-      <LockedReason lock={lock} className="block">
+      <LockedReason lock={lock} display={disabledReasonDisplay} className="block">
         {trigger}
       </LockedReason>
     ) : (
@@ -344,7 +347,9 @@ export function EntityCombobox<V extends string | number, C extends ComboClearVa
               {selectedOption?.icon && <span className="shrink-0">{selectedOption.icon}</span>}
               <span
                 className={cn(
-                  "truncate",
+                  // One line at Normal; from Large up the value wraps and the trigger
+                  // grows, as DatePicker's does (text size §10.17, round 0.34 T1).
+                  "truncate-until-large",
                   // A chosen value is the field's VALUE, so it is set in the same ink an
                   // <input>'s value is — FIELD_BASE's own text colour, inherited rather
                   // than restated (Keksdose dev#477). It used to be one notch lighter
@@ -352,7 +357,7 @@ export function EntityCombobox<V extends string | number, C extends ComboClearVa
                   // and a text field share a form row. Nothing selected keeps the
                   // placeholder tone (`--text-placeholder`), which every field here
                   // agrees on.
-                  !selectedOption && "text-[var(--text-placeholder)]",
+                  !selectedOption && "text-placeholder",
                 )}
               >
                 {selectedOption?.label ?? placeholder ?? ""}
@@ -370,7 +375,7 @@ export function EntityCombobox<V extends string | number, C extends ComboClearVa
                   e.stopPropagation();
                   onChange(clearValue);
                 }}
-                className="absolute end-2 top-1/2 -translate-y-1/2 rounded p-0.5 text-[var(--text-placeholder)] hover:text-[var(--text-secondary)]"
+                className="absolute end-2 top-1/2 -translate-y-1/2 rounded p-0.5 text-placeholder hover:text-secondary"
               >
                 <X className="size-4" />
               </span>