@eifi1/ui-kit 0.33.0 → 0.34.0

package/src/components/file-dropzone.tsx

@@ -1,18 +1,19 @@
 import { useId, useRef, useState } from "react";
-import type { ComponentPropsWithoutRef, MouseEvent, ReactNode } from "react";
+import type { ComponentPropsWithRef, MouseEvent, ReactNode } from "react";
 import { Upload, X } from "lucide-react";
-import { Button, IconButton, Spinner } from "./ui";
+import { Button } from "./button";
+import { IconButton } from "./icon-button";
+import { Spinner } from "./spinner";
+import { FIELD_ERROR_CLASS } from "./field-parts";
 import { cn } from "../lib/cn";
+import { hasContent } from "../lib/presence";
 import { useAnnounce } from "../hooks/use-announce";
-import { useKitFileLabels, useKitLabels } from "../i18n/kit-labels";
-import {
-  DEFAULT_FILE_PICKER_LABELS,
-  formatAccept,
-  judgePick,
-  screenFiles,
-  summariseRejections,
-} from "./file-button";
-import type { FilePickHandler, FilePickerLabels, FileRejection } from "./file-button";
+import { useKitFileLabels, useKitLabels, type LabelOverride } from "../i18n/kit-labels";
+// The picker's words and screening from their own modules, not through FileButton's
+// re-export (MOD-8): the dropzone renders no FileButton.
+import { DEFAULT_FILE_PICKER_LABELS } from "../hooks/use-file-picker-labels";
+import { formatAccept, judgePick, screenFiles, summariseRejections } from "../hooks/use-file-picker";
+import type { FilePickHandler, FilePickerLabels, FileRejection } from "../hooks/use-file-picker";
 import { useDragTarget } from "../hooks/use-file-drop";
 import { toast } from "./toast";
 import { useCommitReason, type CommitScope } from "./write-lock";
@@ -65,7 +66,7 @@ export interface FileDropzoneState {
  * `FileDropzoneProps` stays an interface a caller can extend; a single-mode pick also
  * reaches `onFilesSelected` as a one-element array, so one handler can serve both.
  */
-export interface FileDropzoneProps extends Omit<ComponentPropsWithoutRef<"div">, "onInvalid"> {
+export interface FileDropzoneProps extends Omit<ComponentPropsWithRef<"div">, "onInvalid"> {
   /** Single mode: the chosen file, echoed with its size. */
   file?: File | null;
   /** Single mode: called with the accepted file. */
@@ -119,7 +120,7 @@ export interface FileDropzoneProps extends Omit<ComponentPropsWithoutRef<"div">,
    *  `onInvalid` nor `onReject` is given, `"none"` when one is. */
   rejectionFeedback?: FileDropzoneRejectionFeedback;
   /** Per-instance overrides of the `filePicker` label namespace. */
-  labels?: Partial<FilePickerLabels>;
+  labels?: LabelOverride<FilePickerLabels>;
   /** The dropzone's accessible name. A caller's own `aria-label` wins over it — see
    *  the root element below. Optional since 0.8, like the three below: each falls back
    *  to its `filePicker` string from `<UiKitProvider labels>`, then to English. They
@@ -214,7 +215,7 @@ export function FileDropzone({
 }: FileDropzoneProps) {
   const [error, setError] = useState<string | null>(null);
   const disabledReason = useCommitReason(commit, ownDisabledReason);
-  const locked = hasReason(disabledReason);
+  const locked = hasContent(disabledReason);
   // Locked counts as inert for every file path (drop, click, Browse, remove); only the
   // LOOK and the native `disabled` keep it apart, so its controls stay focusable.
   const inert = Boolean(disabled || busy) || locked;
@@ -313,7 +314,7 @@ export function FileDropzone({
   const controlDisabled = Boolean(disabled || busy);
   const controlReason = locked ? disabledReason : undefined;
   const reasonLine = locked && (
-    <div data-slot="file-dropzone-reason" className="text-xs text-[var(--text-muted)]">
+    <div data-slot="file-dropzone-reason" className="text-xs text-muted">
       {disabledReason}
     </div>
   );
@@ -371,16 +372,16 @@ export function FileDropzone({
           // Inert zones keep the resting hairline and lose the hover pull: a border that
           // answers the pointer promises a drop the zone will refuse.
           disabled
-            ? "cursor-not-allowed border-[var(--border)] opacity-60"
+            ? "cursor-not-allowed border-subtle opacity-60"
             : busy
-              ? "cursor-progress border-[var(--border)]"
+              ? "cursor-progress border-subtle"
               : locked
-                ? "cursor-not-allowed border-[var(--border)]"
+                ? "cursor-not-allowed border-subtle"
                 : dragOver
-                ? "cursor-pointer border-[var(--border-strong)] bg-[var(--bg-active)]"
+                ? "cursor-pointer border-strong bg-active"
                 : showError
-                  ? "cursor-pointer border-[var(--danger-border-strong)]"
-                  : "cursor-pointer border-[var(--border)] hover:border-[var(--border-strong)]",
+                  ? "cursor-pointer border-danger-strong"
+                  : "cursor-pointer border-subtle hover:border-strong",
           className,
         )}
       >
@@ -401,11 +402,11 @@ export function FileDropzone({
             {/* `label={null}`: the zone is `aria-busy` and the line below says the
                 same in words; a spoken "Loading" would only run into it. */}
             <Spinner label={null} className="size-5" />
-            <div className="text-sm text-[var(--text-secondary)]">{labels.busy}</div>
+            <div className="text-sm text-secondary">{labels.busy}</div>
           </>
         ) : (
           <>
-            <Upload aria-hidden className="size-5 text-[var(--text-muted)]" />
+            <Upload aria-hidden className="size-5 text-muted" />
             {multiple && chosen.length > 0 ? (
               <>
                 <ul className="flex w-full max-w-sm flex-col gap-1 text-start">
@@ -414,10 +415,10 @@ export function FileDropzone({
                       // Name + size + position: two files may share a name, and the index
                       // alone would re-key every row below a removal.
                       key={`${f.name}-${f.size}-${i}`}
-                      className="flex items-center gap-2 text-sm text-[var(--text-secondary)]"
+                      className="flex items-center gap-2 text-sm text-secondary"
                     >
                       <span className="min-w-0 flex-1 truncate font-medium">{f.name}</span>
-                      <span className="shrink-0 text-xs text-[var(--text-muted)]">{fileText.size(f.size)}</span>
+                      <span className="shrink-0 text-xs text-muted">{fileText.size(f.size)}</span>
                       {onRemove && (
                         <IconButton
                           type="button"
@@ -441,7 +442,7 @@ export function FileDropzone({
               </>
             ) : (
               <>
-                <div className="flex items-center gap-1 text-sm text-[var(--text-secondary)]">
+                <div className="flex items-center gap-1 text-sm text-secondary">
                   {/* `!multiple`: in multiple mode an empty `files` list is "nothing chosen",
                       whatever a stray `file` prop says — it used to show that file's name. */}
                   {!multiple && file ? <span className="font-medium">{file.name}</span> : emptyLabel}
@@ -467,7 +468,7 @@ export function FileDropzone({
                 {locked && !(file && !multiple) ? (
                   reasonLine
                 ) : (
-                  <div className="text-xs text-[var(--text-muted)]">
+                  <div className="text-xs text-muted">
                     {file && !multiple ? fileText.size(file.size) : hint}
                   </div>
                 )}
@@ -507,7 +508,9 @@ export function FileDropzone({
           )}
         </div>
         {showError && (
-          <p id={errorId} className="text-xs text-[var(--danger)]">
+          // Every field's error type (DUP-8: this was `text-xs`); the zone's `gap-2`
+          // spaces it, so not the class's own `mt-1` as well.
+          <p id={errorId} className={cn(FIELD_ERROR_CLASS, "mt-0")}>
             {error}
           </p>
         )}
@@ -536,6 +539,11 @@ export function FileDropzone({
           // handler again would open the dialog a second time.
           onClick={(e) => e.stopPropagation()}
           className="sr-only"
+          // Out of the tab order and the accessibility tree, as useFilePicker's: Browse
+          // is the way in, and this was a second, nameless stop beside it (round 0.34,
+          // the showcase's axe check).
+          tabIndex={-1}
+          aria-hidden
         />
       </div>
       {/* Outside the zone, where they have always been (the zone used to be a
@@ -547,11 +555,6 @@ export function FileDropzone({
   );
 }
 
-/** A reason that is really there — `null`, `false` and `""` are no reason. */
-function hasReason(reason: ReactNode): boolean {
-  return reason !== undefined && reason !== null && reason !== false && reason !== "";
-}
-
 /** A click that landed on a control inside the zone (a custom body's own button, a
  *  link in the hint) is that control's, not a request to open the picker. */
 function fromControl(e: MouseEvent<HTMLElement>): boolean {

package/src/components/floating-panel-labels.ts

@@ -0,0 +1,10 @@
+// The English words of ./floating-panel, 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). ./floating-panel re-exports them.
+
+import type { FloatingPanelLabels } from "./floating-panel";
+
+export const DEFAULT_FLOATING_PANEL_LABELS: FloatingPanelLabels = {
+  close: "Close",
+  badge: (count) => `${count} new`,
+};

package/src/components/floating-panel.tsx

@@ -17,10 +17,13 @@ import { cn } from "../lib/cn";
 import { FOCUS_RING } from "./focus-ring";
 import { dirOf, type Direction } from "../lib/direction";
 import { registerFloating } from "../lib/floating-stack";
+import { isComposing } from "../lib/ime";
+import { takeEscape } from "../hooks/use-dismiss";
 import { useKitLabels, useKitLink } from "../i18n/kit-labels";
-import { assignRef } from "./choice-parts";
+import { assignRef } from "./field-parts";
 import { pickLinkRenderer } from "./text-link";
 import { Tooltip, type TooltipSide } from "./tooltip";
+import { DEFAULT_FLOATING_PANEL_LABELS } from "./floating-panel-labels";
 
 export interface FloatingPanelLabels {
   /** Accessible name of the panel header's X. */
@@ -33,10 +36,8 @@ export interface FloatingPanelLabels {
   badge: (count: number) => string;
 }
 
-export const DEFAULT_FLOATING_PANEL_LABELS: FloatingPanelLabels = {
-  close: "Close",
-  badge: (count) => `${count} new`,
-};
+// Defined in ./floating-panel-labels, which holds no component code (0.34, KS U8).
+export { DEFAULT_FLOATING_PANEL_LABELS };
 
 /** A LOGICAL corner: `bottom-end` is bottom-right in LTR and bottom-left in RTL. */
 export type FloatingCorner = "bottom-end" | "bottom-start";
@@ -233,17 +234,17 @@ export function FloatingActionButton({
               "shadow-lg transition-colors disabled:cursor-default",
               !toggle &&
                 variant === "primary" &&
-                "bg-[var(--brand)] text-[var(--brand-contrast)] hover:bg-[var(--brand-hover)]",
+                "bg-brand text-brand-contrast hover:bg-brand-hover",
               !toggle &&
                 variant === "surface" &&
-                "border border-[var(--border)] bg-[var(--bg-surface)] text-[var(--text-primary)] hover:bg-[var(--bg-hover)] disabled:hover:bg-[var(--bg-surface)]",
+                "border border-subtle bg-surface text-primary hover:bg-hover disabled:hover:bg-surface",
               // A toggle sits on the page's surface — a solid brand disc would read as
               // "on" in both states — and says "on" in the brand family.
-              toggle && "border border-[var(--border)]",
+              toggle && "border border-subtle",
               pressed === false &&
-                "bg-[var(--bg-surface)] text-[var(--text-secondary)] hover:bg-[var(--bg-hover)] hover:text-[var(--text-primary)]",
+                "bg-surface text-secondary hover:bg-hover hover:text-primary",
               pressed === true &&
-                "border-[var(--brand)] bg-[var(--brand-bg)] text-[var(--brand)] hover:bg-[var(--brand-bg-hover)] hover:text-brand-muted",
+                "border-brand bg-brand-soft text-brand hover:bg-brand-soft-hover hover:text-brand-muted",
               "outline-none focus-visible:ring-offset-2",
               FOCUS_RING,
               className,
@@ -353,7 +354,8 @@ export interface FloatingPanelProps {
  * closed from the page (a controlled owner) never pulls focus out of the field the
  * user is typing in. Escape closes it while focus is inside, and only then: on the
  * panel element, not the document, so Escape in the page keeps meaning whatever the
- * page means by it.
+ * page means by it. A layer of the kit's Escape stack open over it — a tooltip, a list —
+ * is handed the key first.
  *
  * ## Layout
  *
@@ -427,7 +429,16 @@ export function FloatingPanel({
   }, [open]);
 
   const onPanelKeyDown = (e: KeyboardEvent<HTMLDivElement>) => {
-    if (e.key !== "Escape" || e.defaultPrevented) return;
+    if (e.key !== "Escape") return;
+    // The kit's one Escape stack first (round 0.34 Wave 2, DUP-1): a layer open above the
+    // panel without focus — a tooltip, the numpad, a hover menu — is the topmost thing on
+    // screen and is handed the key. This took it for itself and stopped it, so the
+    // tooltip never heard it and one press closed the whole panel instead.
+    if (takeEscape(e)) return;
+    // Not a layer itself: it answers only while focus is inside it, and a layer would
+    // also be handed an Escape pressed in the page. Kept by a child's claim (ChipInput
+    // clearing its draft, `claimEscape`), and by an IME composition, as a layer is.
+    if (e.defaultPrevented || isComposing(e)) return;
     // Stopped here, so an overlay underneath with a document-level Escape listener does
     // not close too — the innermost thing that has focus is the one that closes.
     e.stopPropagation();
@@ -486,7 +497,7 @@ export function FloatingPanel({
             }
             className={cn(
               "animate-sheet fixed z-40 flex flex-col overflow-hidden outline-none",
-              "border border-[var(--border)] bg-[var(--bg-surface)] shadow-2xl",
+              "border border-subtle bg-surface shadow-2xl",
               // Phone: full width, docked, rounded only where it meets the page.
               "inset-x-0 bottom-[var(--fp-bottom)] max-h-[min(85dvh,calc(100dvh_-_var(--fp-bottom)_-_1rem))] rounded-t-xl border-x-0 border-b-0",
               "pb-[env(safe-area-inset-bottom,0px)] md:pb-0",
@@ -496,8 +507,8 @@ export function FloatingPanel({
               className,
             )}
           >
-            <div className="flex shrink-0 items-center justify-between gap-2 border-b border-[var(--border)] px-4 py-3">
-              <h2 id={titleId} className="min-w-0 truncate text-base font-semibold text-[var(--text-primary)]">
+            <div className="flex shrink-0 items-center justify-between gap-2 border-b border-subtle px-4 py-3">
+              <h2 id={titleId} className="min-w-0 truncate text-base font-semibold text-primary">
                 {title}
               </h2>
               <button
@@ -507,7 +518,7 @@ export function FloatingPanel({
                   setOpen(false);
                 }}
                 aria-label={labels.close}
-                className={cn("-me-1.5 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 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>
@@ -574,11 +585,11 @@ export function FloatingActionGroup({
             style={{ ...cornerStyle(corner, offset), ...style }}
             className={cn(
               "fixed z-40 inline-flex flex-row overflow-hidden rounded-2xl",
-              "border border-[var(--border)] bg-[var(--bg-surface)] shadow-lg",
+              "border border-subtle bg-surface shadow-lg",
               // Dividers on the logical start edge of every member but the first, so
               // they sit between the same two members in RTL. The member is the
               // tooltip's wrapper span, which is the direct child.
-              "[&>*:not(:first-child)]:border-s [&>*]:border-[var(--border)]",
+              "[&>*:not(:first-child)]:border-s [&>*]:border-subtle",
               className,
             )}
           >
@@ -695,10 +706,10 @@ export function FloatingAction({
     FOCUS_RING,
     "disabled:cursor-not-allowed disabled:opacity-50 [&_svg]:size-5",
     variant === "primary"
-      ? "bg-[var(--brand)] text-[var(--brand-contrast)] hover:bg-[var(--brand-hover)]"
+      ? "bg-brand text-brand-contrast hover:bg-brand-hover"
       : pressed && !isLink && pressedStyle === "tint"
-        ? "bg-[var(--brand-bg)] text-[var(--brand)] hover:bg-[var(--brand-bg-hover)] hover:text-brand-muted"
-        : "text-[var(--text-secondary)] hover:bg-[var(--bg-hover)] hover:text-[var(--text-primary)]",
+        ? "bg-brand-soft text-brand hover:bg-brand-soft-hover hover:text-brand-muted"
+        : "text-secondary hover:bg-hover hover:text-primary",
     className,
   );
   const body = (

package/src/components/focus-ring.ts

@@ -2,11 +2,16 @@
  * The kit's focus frame (§5): a brand ring `--focus-ring-width` wide — 2 px, 3 px under
  * More contrast (tokens.css) — on keyboard focus only. ONE frame instead of the hundred
  * spelled-out `focus-visible:ring-2` copies, so the contrast setting can thicken all of
- * them at once. Compose with `ring-inset` or `ring-offset-*` where a component needs it.
+ * them at once. Compose with `ring-inset` or `ring-offset-surface` where a component needs it.
+ *
+ * The width is the `ring-focus` utility (tokens.css, 0.34): where this constant's variant
+ * does not fit — a ring on an `after:` overlay, on links inside a footer, an outline on a
+ * card — write `focus-visible:after:ring-focus` or `has-[:focus-visible]:outline-focus`
+ * rather than spelling the width out.
  */
 export const FOCUS_RING =
-  "focus-visible:outline-none focus-visible:ring-[length:var(--focus-ring-width)] focus-visible:ring-[var(--brand)]";
+  "focus-visible:outline-none focus-visible:ring-focus focus-visible:ring-brand";
 
 /** Just the width of {@link FOCUS_RING}, for a ring in another colour (a danger control's,
- *  `--brand-contrast` on a filled button): `cn(FOCUS_RING_WIDTH, "focus-visible:ring-[var(--danger)]")`. */
-export const FOCUS_RING_WIDTH = "focus-visible:ring-[length:var(--focus-ring-width)]";
+ *  `--brand-contrast` on a filled button): `cn(FOCUS_RING_WIDTH, "focus-visible:ring-brand-contrast")`. */
+export const FOCUS_RING_WIDTH = "focus-visible:ring-focus";

package/src/components/form-actions-labels.ts

@@ -0,0 +1,11 @@
+// The English words of ./form-actions, 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). ./form-actions re-exports them.
+
+import type { FormActionsLabels } from "./form-actions";
+
+export const DEFAULT_FORM_ACTIONS_LABELS: FormActionsLabels = {
+  save: "Save",
+  cancel: "Cancel",
+  submitShortcut: (apple) => (apple ? "⌘ Enter" : "Ctrl+Enter"),
+};

package/src/components/form-actions.tsx

@@ -1,4 +1,4 @@
-import { isValidElement, useCallback, useEffect, useRef } from "react";
+import { isValidElement, useEffect, useMemo, useRef } from "react";
 import type { ComponentPropsWithoutRef, ReactNode, Ref } from "react";
 import type { LucideIcon } from "lucide-react";
 import { cn } from "../lib/cn";
@@ -6,9 +6,13 @@ import { useKitLabels } from "../i18n/kit-labels";
 import { useBreakpoint, usePhoneLayout } from "../hooks/use-breakpoint";
 import { useLargeText } from "../hooks/use-large-text";
 import { isApplePlatform } from "../hooks/use-hotkey";
-import { Button, Spinner, type ButtonProps, type ButtonSize, type ButtonVariant } from "./ui";
+import { Button, type ButtonProps } from "./button";
+import { Spinner } from "./spinner";
+import type { ButtonSize, ButtonVariant } from "./button-look";
+import { mergeRefs } from "./field-parts";
 import { useWriteLock } from "./write-lock";
 import type { CommitScope } from "./write-lock";
+import { DEFAULT_FORM_ACTIONS_LABELS } from "./form-actions-labels";
 
 /** The words {@link FormActions} renders on its own behalf — the `form` namespace. */
 export interface FormActionsLabels {
@@ -23,11 +27,8 @@ export interface FormActionsLabels {
   submitShortcut: (apple: boolean) => string;
 }
 
-export const DEFAULT_FORM_ACTIONS_LABELS: FormActionsLabels = {
-  save: "Save",
-  cancel: "Cancel",
-  submitShortcut: (apple) => (apple ? "⌘ Enter" : "Ctrl+Enter"),
-};
+// Defined in ./form-actions-labels, which holds no component code (0.34, KS U8).
+export { DEFAULT_FORM_ACTIONS_LABELS };
 
 /** See {@link FormActionsProps.submitShortcut}. */
 export type FormActionsSubmitShortcut = "mod-enter";
@@ -148,7 +149,7 @@ const ALIGN_CLASS: Record<FormActionsAlign, string> = {
 
 const PLACEMENT_CLASS: Record<FormActionsPlacement, string> = {
   inline: "pt-4",
-  sticky: "sticky bottom-0 z-10 border-t border-[var(--border)] bg-[var(--bg-surface)] pt-3",
+  sticky: "sticky bottom-0 z-10 border-t border-subtle bg-surface pt-3",
   dialog: "",
 };
 
@@ -321,13 +322,12 @@ export interface FormActionsProps extends Omit<ComponentPropsWithoutRef<"div">,
   stack?: FormActionsStack;
   /** Extra actions, placed before Cancel. */
   children?: ReactNode;
+  /** The row, where the rest of the props go (0.34, API-2, refactor audit 2026-10) —
+   *  merged with its own ref, which `submitShortcut` finds its form from. It rode the
+   *  rest props before, after the row's own, and a caller's ref took the shortcut's. */
+  ref?: Ref<HTMLDivElement>;
 }
 
-/** Hand `el` to a caller's ref, whichever kind it is. */
-function assignRef<E>(ref: Ref<E> | undefined, el: E | null): void {
-  if (typeof ref === "function") ref(el);
-  else if (ref) (ref as { current: E | null }).current = el;
-}
 
 /**
  * Where {@link FormActionsProps.submitShortcut} listens: the form Save submits (named
@@ -387,6 +387,7 @@ export function FormActions({
   children,
   className,
   style,
+  ref,
   ...rest
 }: FormActionsProps) {
   const phone = usePhoneLayout();
@@ -400,16 +401,11 @@ export function FormActions({
   // `COMMIT_EXCEPT_BILLING` form's shortcut live too.
   const lock = useWriteLock(commit);
   const rootRef = useRef<HTMLDivElement>(null);
+  const setRoot = useMemo(() => mergeRefs(rootRef, ref), [ref]);
   const saveRef = useRef<HTMLButtonElement | null>(null);
   // The caller's own `submitProps.ref` still gets the element.
   const callerSaveRef = submitProps?.ref;
-  const setSaveRef = useCallback(
-    (el: HTMLButtonElement | null) => {
-      saveRef.current = el;
-      assignRef(callerSaveRef, el);
-    },
-    [callerSaveRef],
-  );
+  const setSaveRef = useMemo(() => mergeRefs(saveRef, callerSaveRef), [callerSaveRef]);
   // The save settled and the form is still here — it failed, and the user retries. The
   // button was natively disabled while it ran, and a focused button that turns disabled
   // drops the focus to <body> (DangerConfirm's 0.24 fix, keksdose). Only after a press
@@ -476,7 +472,7 @@ export function FormActions({
 
   return (
     <div
-      ref={rootRef}
+      ref={setRoot}
       data-slot="form-actions"
       data-placement={placement}
       data-sticky-within={placement === "sticky" ? stickyWithin : undefined}

package/src/components/full-bleed-dialog.tsx

@@ -1,14 +1,16 @@
-import { useId, useRef } from "react";
+import { useId, useMemo, useRef } from "react";
 import { createPortal } from "react-dom";
-import type { ComponentPropsWithoutRef, KeyboardEvent, ReactNode } from "react";
+import type { ComponentPropsWithoutRef, KeyboardEvent, ReactNode, Ref } from "react";
 import { X } from "lucide-react";
 
 import { cn } from "../lib/cn";
+import { mergeRefs } from "./field-parts";
 import { useBackdropClose } from "./modal";
 import { useBodyScrollLock } from "../hooks/use-body-scroll-lock";
 import { useOverlayHistory } from "../hooks/use-overlay-history";
 import { useCloseTransition } from "../hooks/use-close-transition";
 import { useFocusTrap } from "../hooks/use-focus-trap";
+import { runOwnKeyDown, takeEscape, useDismissLayer } from "../hooks/use-dismiss";
 
 /**
  * The padding around the dialog's scrolling body, as a CSS length (0.32,
@@ -82,6 +84,9 @@ export interface FullBleedDialogProps extends Omit<ComponentPropsWithoutRef<"div
    * last field); padded for the home indicator, since it is the panel's bottom edge.
    */
   footer?: ReactNode;
+  /** The `role="dialog"` element, where the rest of the props go (0.34, API-2, refactor
+   *  audit 2026-10) — merged with its own ref, which the focus trap holds. */
+  ref?: Ref<HTMLDivElement>;
 }
 
 /**
@@ -128,6 +133,7 @@ export function FullBleedDialog({
   onMouseDown,
   onMouseUp,
   onKeyDown,
+  ref,
   ...rest
 }: FullBleedDialogProps) {
   // Every way OUT goes through `requestClose`, so the panel lowers itself before the
@@ -140,6 +146,7 @@ export function FullBleedDialog({
   useOverlayHistory(open && backCloses, requestClose);
 
   const dialogRef = useRef<HTMLDivElement>(null);
+  const setDialog = useMemo(() => mergeRefs(dialogRef, ref), [ref]);
   const titleId = useId();
   const hasTitle = title !== undefined && title !== null && title !== false;
   const hasHeader = header !== undefined && header !== null && header !== false;
@@ -154,27 +161,28 @@ export function FullBleedDialog({
   // This is the phone's row EDITOR and its first child is usually an input; focusing it
   // would pull the software keyboard up over half the form before the user has said
   // which field they came for. `Modal` made the same call for the same reason.
+  //
+  // That default only decides when nothing inside asked for focus. A field the app
+  // autofocuses on purpose keeps it (0.33.1): keksdose's create card autofocuses its
+  // amount, and the trap used to take focus straight back to the dialog — and on a
+  // phone the numpad sheet, which shows only while the field is focused, went with it
+  // (live #402). Closing still hands focus back to whatever opened the dialog.
   useFocusTrap(dialogRef, { active: open });
 
+  // A layer on the Escape stack while open (Wave 2, DUP-1). This dialog is what a
+  // `PickerSheet`, a list or the numpad opens on top of, and the stack hands the key
+  // to whichever of them is topmost — one press dismissing the sheet AND the edit
+  // behind it was Keksdose live #309 (*"Mouse Back does not only close the select but
+  // also the whole edit or create dialog"*) on a different key.
+  useDismissLayer(open, requestClose);
   const handleKeyDown = (e: KeyboardEvent<HTMLDivElement>) => {
     // The caller's handler first (keksdose's transaction-search keeps its list keys on
-    // the dialog); a `preventDefault()` IN THAT HANDLER claims the key, Escape included.
-    // Only there: a descendant's preventDefault does not count. A SearchField in the
-    // header prevents Escape to stop Chromium clearing a type=search input, and in
-    // 0.8.0 that silently stopped Escape from closing the dialog (keksdose).
-    const preventedBefore = e.defaultPrevented;
-    onKeyDown?.(e);
-    const claimedByCaller = !preventedBefore && e.defaultPrevented;
-    if (claimedByCaller || e.key !== "Escape") return;
-    // On the panel, the way `Modal` does it, and NOT through `useEscapeKey`: this
-    // dialog is the thing a `PickerSheet` opens on top of, and a document-level
-    // listener cannot tell which of the two the user meant. One press would dismiss
-    // the sheet AND throw away the edit behind it — Keksdose live #309 (*"Mouse Back
-    // does not only close the select but also the whole edit or create dialog"*) on a
-    // different key. The sheet's own handler stops the event here, so the innermost
-    // overlay is the one that closes, which is only true because focus is now in it.
-    e.stopPropagation();
-    requestClose();
+    // the dialog); a `preventDefault()` IN THAT HANDLER claims Escape. Only there: a
+    // descendant's does not count. A SearchField in the header prevents Escape to stop
+    // Chromium clearing a type=search input, and in 0.8.0 that silently stopped Escape
+    // from closing the dialog (keksdose). The one rule `Modal` now shares.
+    runOwnKeyDown(e, onKeyDown);
+    takeEscape(e);
   };
 
   if (!open || typeof document === "undefined") return null;
@@ -212,7 +220,7 @@ export function FullBleedDialog({
       // `tabIndex={-1}` is what makes the line above more than a claim: without it the
       // container cannot take focus and `useFocusTrap` silently does nothing.
       tabIndex={-1}
-      ref={dialogRef}
+      ref={setDialog}
       onKeyDown={handleKeyDown}
       // COMPOSED with the backdrop's, not overridden by them. These two used to ride
       // `...rest` and then lose to `{...backdropClose}` spread after it, silently —
@@ -232,15 +240,15 @@ export function FullBleedDialog({
     >
       <div
         className={cn(
-          "flex h-full w-full flex-col overflow-hidden bg-[var(--bg-surface)] shadow-xl",
+          "flex h-full w-full flex-col overflow-hidden bg-surface shadow-xl",
           closing ? "animate-sheet-out" : "animate-sheet",
           className,
         )}
       >
-        <div className="flex items-center justify-between gap-2 border-b border-[var(--border)] px-3 py-3">
+        <div className="flex items-center justify-between gap-2 border-b border-subtle px-3 py-3">
           {hasTitle ? (
             <div className="flex min-w-0 flex-1 items-center gap-2">
-              <Heading id={titleId} className="min-w-0 break-words text-base font-semibold leading-snug text-[var(--text-primary)]">
+              <Heading id={titleId} className="min-w-0 break-words text-base font-semibold leading-snug text-primary">
                 {title}
               </Heading>
               {hasHeader && <div className="min-w-0 flex-1 font-medium">{header}</div>}
@@ -252,7 +260,7 @@ export function FullBleedDialog({
             type="button"
             onClick={requestClose}
             aria-label={closeLabel}
-            className="-me-1 shrink-0 rounded p-1.5 text-[var(--text-muted)] hover:bg-[var(--bg-hover)] hover:text-[var(--text-secondary)]"
+            className="-me-1 shrink-0 rounded p-1.5 text-muted hover:bg-hover hover:text-secondary"
           >
             <X className="size-5" />
           </button>
@@ -269,7 +277,7 @@ export function FullBleedDialog({
         {footer !== undefined && footer !== null && footer !== false && (
           <div
             data-full-bleed-footer=""
-            className="flex shrink-0 flex-wrap items-center justify-end gap-2 border-t border-[var(--border)] px-3 pt-3"
+            className="flex shrink-0 flex-wrap items-center justify-end gap-2 border-t border-subtle px-3 pt-3"
             style={{ paddingBottom: "max(0.75rem, env(safe-area-inset-bottom))" }}
           >
             {footer}