@eifi1/ui-kit 0.33.1 → 0.34.0

package/dist/components/full-bleed-dialog.d.ts

@@ -1,6 +1,4 @@
-import * as react from 'react';
-import { ComponentPropsWithoutRef, ReactNode } from 'react';
-
+import type { ComponentPropsWithoutRef, ReactNode, Ref } from "react";
 /**
  * The padding around the dialog's scrolling body, as a CSS length (0.32,
  * docs/text-size-harmonization.md §10.11). Exported because a caller's sticky footer has
@@ -10,7 +8,7 @@ import { ComponentPropsWithoutRef, ReactNode } from 'react';
  * copy (`SCROLLER_GUTTER_PX = 12`) was 3–6 px off at 125/150 %. Use it in `calc()`:
  * `bottom: calc(${inset}px - ${DIALOG_GUTTER})`.
  */
-declare const DIALOG_GUTTER = "0.75rem";
+export declare const DIALOG_GUTTER = "0.75rem";
 /**
  * Named and exported, because `ComponentProps<typeof FullBleedDialog>` was the only way
  * to say "the props of this" and five call sites across keksdose and kastlan had already
@@ -21,7 +19,7 @@ declare const DIALOG_GUTTER = "0.75rem";
  * `aria-describedby` or a `data-tour` anchor belongs on. {@link className} keeps going
  * to the panel inside it, which is what it has always meant here.
  */
-interface FullBleedDialogProps extends Omit<ComponentPropsWithoutRef<"div">, "title"> {
+export interface FullBleedDialogProps extends Omit<ComponentPropsWithoutRef<"div">, "title"> {
     open: boolean;
     /** The X, the backdrop (where one shows) and — unless {@link backCloses} is off —
      *  the platform Back gesture all call this. */
@@ -72,6 +70,9 @@ interface FullBleedDialogProps extends Omit<ComponentPropsWithoutRef<"div">, "ti
      * 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>;
 }
 /**
  * The phone's full-screen dialog: a panel that covers the viewport edge to edge.
@@ -103,6 +104,4 @@ interface FullBleedDialogProps extends Omit<ComponentPropsWithoutRef<"div">, "ti
  * stays the free slot beside it. And `open`,
  * because who decides is the caller's business — see {@link backCloses}.
  */
-declare function FullBleedDialog({ open, onClose, title, headingAs: Heading, header, closeLabel, children, backCloses, className, footer, onMouseDown, onMouseUp, onKeyDown, ...rest }: FullBleedDialogProps): react.ReactPortal | null;
-
-export { DIALOG_GUTTER, FullBleedDialog, type FullBleedDialogProps };
+export declare function FullBleedDialog({ open, onClose, title, headingAs: Heading, header, closeLabel, children, backCloses, className, footer, onMouseDown, onMouseUp, onKeyDown, ref, ...rest }: FullBleedDialogProps): import("react").ReactPortal | null;

package/dist/components/full-bleed-dialog.js

@@ -1,14 +1,16 @@
 "use client";
 import { jsx, jsxs } from "react/jsx-runtime";
-import { useId, useRef } from "react";
+import { useId, useMemo, useRef } from "react";
 import { createPortal } from "react-dom";
 import { X } from "lucide-react";
 import { cn } from "../lib/cn.js";
+import { mergeRefs } from "./field-parts.js";
 import { useBackdropClose } from "./modal.js";
 import { useBodyScrollLock } from "../hooks/use-body-scroll-lock.js";
 import { useOverlayHistory } from "../hooks/use-overlay-history.js";
 import { useCloseTransition } from "../hooks/use-close-transition.js";
 import { useFocusTrap } from "../hooks/use-focus-trap.js";
+import { runOwnKeyDown, takeEscape, useDismissLayer } from "../hooks/use-dismiss.js";
 const DIALOG_GUTTER = "0.75rem";
 function FullBleedDialog({
   open,
@@ -24,6 +26,7 @@ function FullBleedDialog({
   onMouseDown,
   onMouseUp,
   onKeyDown,
+  ref,
   ...rest
 }) {
   const { closing, requestClose } = useCloseTransition(onClose);
@@ -31,17 +34,15 @@ function FullBleedDialog({
   useBodyScrollLock(open);
   useOverlayHistory(open && backCloses, requestClose);
   const dialogRef = useRef(null);
+  const setDialog = useMemo(() => mergeRefs(dialogRef, ref), [ref]);
   const titleId = useId();
   const hasTitle = title !== void 0 && title !== null && title !== false;
   const hasHeader = header !== void 0 && header !== null && header !== false;
   useFocusTrap(dialogRef, { active: open });
+  useDismissLayer(open, requestClose);
   const handleKeyDown = (e) => {
-    const preventedBefore = e.defaultPrevented;
-    onKeyDown?.(e);
-    const claimedByCaller = !preventedBefore && e.defaultPrevented;
-    if (claimedByCaller || e.key !== "Escape") return;
-    e.stopPropagation();
-    requestClose();
+    runOwnKeyDown(e, onKeyDown);
+    takeEscape(e);
   };
   if (!open || typeof document === "undefined") return null;
   return createPortal(
@@ -61,7 +62,7 @@ function FullBleedDialog({
         "aria-modal": "true",
         "aria-labelledby": rest["aria-labelledby"] ?? (hasTitle && !rest["aria-label"] ? titleId : void 0),
         tabIndex: -1,
-        ref: dialogRef,
+        ref: setDialog,
         onKeyDown: handleKeyDown,
         onMouseDown: (e) => {
           onMouseDown?.(e);
@@ -75,14 +76,14 @@ 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
             ),
             children: [
-              /* @__PURE__ */ jsxs("div", { className: "flex items-center justify-between gap-2 border-b border-[var(--border)] px-3 py-3", children: [
+              /* @__PURE__ */ jsxs("div", { className: "flex items-center justify-between gap-2 border-b border-subtle px-3 py-3", children: [
                 hasTitle ? /* @__PURE__ */ jsxs("div", { className: "flex min-w-0 flex-1 items-center gap-2", children: [
-                  /* @__PURE__ */ jsx(Heading, { id: titleId, className: "min-w-0 break-words text-base font-semibold leading-snug text-[var(--text-primary)]", children: title }),
+                  /* @__PURE__ */ jsx(Heading, { id: titleId, className: "min-w-0 break-words text-base font-semibold leading-snug text-primary", children: title }),
                   hasHeader && /* @__PURE__ */ jsx("div", { className: "min-w-0 flex-1 font-medium", children: header })
                 ] }) : /* @__PURE__ */ jsx("div", { className: "min-w-0 flex-1 font-medium", children: header }),
                 /* @__PURE__ */ jsx(
@@ -91,7 +92,7 @@ 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",
                     children: /* @__PURE__ */ jsx(X, { className: "size-5" })
                   }
                 )
@@ -101,7 +102,7 @@ function FullBleedDialog({
                 "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))" },
                   children: footer
                 }

package/dist/components/full-bleed-dialog.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/components/full-bleed-dialog.tsx"],"sourcesContent":["import { useId, useRef } from \"react\";\nimport { createPortal } from \"react-dom\";\nimport type { ComponentPropsWithoutRef, KeyboardEvent, ReactNode } from \"react\";\nimport { X } from \"lucide-react\";\n\nimport { cn } from \"../lib/cn\";\nimport { useBackdropClose } from \"./modal\";\nimport { useBodyScrollLock } from \"../hooks/use-body-scroll-lock\";\nimport { useOverlayHistory } from \"../hooks/use-overlay-history\";\nimport { useCloseTransition } from \"../hooks/use-close-transition\";\nimport { useFocusTrap } from \"../hooks/use-focus-trap\";\n\n/**\n * The padding around the dialog's scrolling body, as a CSS length (0.32,\n * docs/text-size-harmonization.md §10.11). Exported because a caller's sticky footer has\n * to reach across it: Chrome resolves a sticky offset against the scrollport's CONTENT\n * box, so a pinned row sits this far short of the panel's edge unless it cancels it\n * (keksdose's editor footer). In rem, so it grows with the text size — keksdose's px\n * copy (`SCROLLER_GUTTER_PX = 12`) was 3–6 px off at 125/150 %. Use it in `calc()`:\n * `bottom: calc(${inset}px - ${DIALOG_GUTTER})`.\n */\nexport const DIALOG_GUTTER = \"0.75rem\";\n\n/**\n * Named and exported, because `ComponentProps<typeof FullBleedDialog>` was the only way\n * to say \"the props of this\" and five call sites across keksdose and kastlan had already\n * written one (audit §api-design).\n *\n * It extends the `<div>` attributes so a caller can reach the OUTER element — the one\n * carrying `role=\"dialog\"`, and therefore the one an `aria-label`, an\n * `aria-describedby` or a `data-tour` anchor belongs on. {@link className} keeps going\n * to the panel inside it, which is what it has always meant here.\n */\nexport interface FullBleedDialogProps extends Omit<ComponentPropsWithoutRef<\"div\">, \"title\"> {\n  open: boolean;\n  /** The X, the backdrop (where one shows) and — unless {@link backCloses} is off —\n   *  the platform Back gesture all call this. */\n  onClose: () => void;\n  /**\n   * The dialog's HEADING: rendered as a real `h2` (see {@link headingAs}) at the start\n   * of the header strip, and wired to the dialog's `aria-labelledby`, so the dialog is\n   * announced by name rather than as just \"dialog\".\n   *\n   * Before this the strip was a styled `div`, and a caller that wanted its full-screen\n   * phone editor NAMED had to leave this component for `DialogFrame fullBleed` —\n   * keksdose's budget-table phone editor says so in a comment at the call site. A\n   * caller's own `aria-label` / `aria-labelledby` still wins.\n   */\n  title?: ReactNode;\n  /** The heading level of {@link title}. `h2` by default, as `DialogFrame`'s. */\n  headingAs?: \"h1\" | \"h2\" | \"h3\" | \"h4\";\n  /**\n   * Free content for the header strip, beside the close button — after the\n   * {@link title} when there is one, or on its own (the row editor shows the row's\n   * own first cell here). It does not name the dialog; `title` does.\n   */\n  header?: ReactNode;\n  closeLabel: string;\n  children: ReactNode;\n  /**\n   * Push a history entry so Back dismisses this dialog instead of navigating\n   * (Keksdose feedback #172). On by default, because a full-screen form that ignores\n   * the phone's universal \"go back\" gesture does not merely fail to close — the\n   * navigation lands somewhere else with the form still notionally open.\n   *\n   * **Off for a caller whose open state is already in the URL.** The transactions\n   * create card is `?action=new`, so Back already pops it through the router; a\n   * sentinel on top of that would cost two presses to close one dialog. One owner of\n   * the Back press, always.\n   */\n  backCloses?: boolean;\n  /** Extra classes for the PANEL (not the backdrop). */\n  className?: string;\n  /**\n   * A row pinned under the scrolling body — an Apply, a Save. Keksdose's `RangeSheet`\n   * (reports/report-range-field.tsx) is a hand-rolled copy of this dialog for want of\n   * exactly this slot: a date range picked on a phone is committed by a sticky Apply,\n   * and a button at the end of the body scrolls away with the calendar.\n   *\n   * Outside the scroller, so it stays put without `position: sticky` (which would\n   * need the body to be the scroll container of its own child and paint over the\n   * last field); padded for the home indicator, since it is the panel's bottom edge.\n   */\n  footer?: ReactNode;\n}\n\n/**\n * The phone's full-screen dialog: a panel that covers the viewport edge to edge.\n *\n * Not {@link Modal}, and that is a decision rather than an omission. Keksdose feedback\n * #32: the inset panel #204 shipped left a strip of page showing beside it on a phone,\n * and tapping that strip dismissed a form mid-edit. With no backdrop exposed there is\n * nothing to mis-tap, so the X is the way out — `backdropClose` stays wired for any\n * layout that does leave a backdrop visible, and costs nothing where none is.\n *\n * ## Why it is a component\n *\n * It was markup inside `data-table.tsx`, where it is the phone's row EDITOR. Keksdose\n * live #307's follow-up needed the same shell for the transactions CREATE card —\n * *\"Is the creation window of the tx still different than the edit window? Since the tx\n * list still appears below when scrolling down?\"* — and the two answers to that are\n * either one component or two copies that drift. Every previous convergence in that app\n * drifted the moment a second surface was written beside the first, which is what\n * `field-layer-parity` exists to catch one layer down.\n *\n * So the panel, the header strip, the scrolling body, the body-scroll lock and the Back\n * handling are all here, once.\n *\n * ## What the caller still owns\n *\n * The HEADER's content, because the two callers name themselves differently: the row\n * editor shows the row's own first column, the create card a plain title. A plain\n * title belongs in `title`, which is a real heading and the dialog's name; `header`\n * stays the free slot beside it. And `open`,\n * because who decides is the caller's business — see {@link backCloses}.\n */\nexport function FullBleedDialog({\n  open,\n  onClose,\n  title,\n  headingAs: Heading = \"h2\",\n  header,\n  closeLabel,\n  children,\n  backCloses = true,\n  className,\n  footer,\n  onMouseDown,\n  onMouseUp,\n  onKeyDown,\n  ...rest\n}: FullBleedDialogProps) {\n  // Every way OUT goes through `requestClose`, so the panel lowers itself before the\n  // caller unmounts it (live #320 rework). `onClose` is still what finally runs — this\n  // only delays it by the length of the animation.\n  const { closing, requestClose } = useCloseTransition(onClose);\n  const backdropClose = useBackdropClose(requestClose);\n  // The page behind must not scroll or jump under the overlay (feedback #204).\n  useBodyScrollLock(open);\n  useOverlayHistory(open && backCloses, requestClose);\n\n  const dialogRef = useRef<HTMLDivElement>(null);\n  const titleId = useId();\n  const hasTitle = title !== undefined && title !== null && title !== false;\n  const hasHeader = header !== undefined && header !== null && header !== false;\n  // The half of \"modal\" this dialog was only claiming. It has said\n  // `aria-modal=\"true\"` since it was extracted from `data-table.tsx`, which tells\n  // assistive technology to hide everything outside it — while the user's focus stayed\n  // on the row they tapped, in the part that is now hidden. Tab then walked them\n  // through a table the screen reader would not describe, and on a phone this dialog\n  // covers the whole screen, so there was nothing on screen to say where they were.\n  //\n  // `initialFocus` is left at the default — the dialog itself, not the first field.\n  // This is the phone's row EDITOR and its first child is usually an input; focusing it\n  // would pull the software keyboard up over half the form before the user has said\n  // which field they came for. `Modal` made the same call for the same reason.\n  //\n  // That default only decides when nothing inside asked for focus. A field the app\n  // autofocuses on purpose keeps it (0.33.1): keksdose's create card autofocuses its\n  // amount, and the trap used to take focus straight back to the dialog — and on a\n  // phone the numpad sheet, which shows only while the field is focused, went with it\n  // (live #402). Closing still hands focus back to whatever opened the dialog.\n  useFocusTrap(dialogRef, { active: open });\n\n  const handleKeyDown = (e: KeyboardEvent<HTMLDivElement>) => {\n    // The caller's handler first (keksdose's transaction-search keeps its list keys on\n    // the dialog); a `preventDefault()` IN THAT HANDLER claims the key, Escape included.\n    // Only there: a descendant's preventDefault does not count. A SearchField in the\n    // header prevents Escape to stop Chromium clearing a type=search input, and in\n    // 0.8.0 that silently stopped Escape from closing the dialog (keksdose).\n    const preventedBefore = e.defaultPrevented;\n    onKeyDown?.(e);\n    const claimedByCaller = !preventedBefore && e.defaultPrevented;\n    if (claimedByCaller || e.key !== \"Escape\") return;\n    // On the panel, the way `Modal` does it, and NOT through `useEscapeKey`: this\n    // dialog is the thing a `PickerSheet` opens on top of, and a document-level\n    // listener cannot tell which of the two the user meant. One press would dismiss\n    // the sheet AND throw away the edit behind it — Keksdose live #309 (*\"Mouse Back\n    // does not only close the select but also the whole edit or create dialog\"*) on a\n    // different key. The sheet's own handler stops the event here, so the innermost\n    // overlay is the one that closes, which is only true because focus is now in it.\n    e.stopPropagation();\n    requestClose();\n  };\n\n  if (!open || typeof document === \"undefined\") return null;\n\n  return createPortal(\n    /* eslint-disable-next-line jsx-a11y/no-noninteractive-element-interactions -- the dialog\n       container, per the APG dialog pattern: `onKeyDown` is Escape-to-close for whatever\n       inside it holds focus, and the mouse handlers are the backdrop press (Escape and the\n       close button are its keyboard path). */\n    <div\n      // `animate-overlay` on the backdrop and `animate-sheet` on the panel (live #320):\n      // the backdrop fades, the panel rises from the bottom edge it is anchored to.\n      // Both are no-ops under prefers-reduced-motion — see tokens.css.\n      //\n      // …and the same two backwards while `closing`, which is the #320 rework. The\n      // backdrop keeps taking pointer events on the way out: a tap during those 220ms\n      // is a tap on a dialog that is leaving, and letting it through to the row\n      // underneath would open a second one.\n      //\n      // `...rest` first, the dialog's own contract after it. A caller adding a\n      // `data-tour` anchor must not be able to take away the role, the modality or the\n      // `tabIndex` below by passing one of them too — this is the element the focus\n      // trap holds, and each of those failures is invisible on screen.\n      {...rest}\n      className={cn(\n        \"fixed inset-0 z-50 flex items-stretch justify-center bg-black/40 outline-none\",\n        closing ? \"animate-overlay-out\" : \"animate-overlay\",\n      )}\n      role=\"dialog\"\n      aria-modal=\"true\"\n      // The heading names the dialog unless the caller named it some other way — an\n      // `aria-labelledby` of its own, or an `aria-label` (which a `labelledby` would\n      // silently outrank).\n      aria-labelledby={rest[\"aria-labelledby\"] ?? (hasTitle && !rest[\"aria-label\"] ? titleId : undefined)}\n      // `tabIndex={-1}` is what makes the line above more than a claim: without it the\n      // container cannot take focus and `useFocusTrap` silently does nothing.\n      tabIndex={-1}\n      ref={dialogRef}\n      onKeyDown={handleKeyDown}\n      // COMPOSED with the backdrop's, not overridden by them. These two used to ride\n      // `...rest` and then lose to `{...backdropClose}` spread after it, silently —\n      // and the one caller about to pass one is keksdose's RangeSheet, whose\n      // `onMouseDown={(e) => e.stopPropagation()}` is its dev#477 fix: a press in a\n      // portalled sheet must not reach a document-level \"outside click\" listener,\n      // which would unmount the day cell before its `click`. The caller's runs first;\n      // the backdrop's still runs after it, since it is the same element.\n      onMouseDown={(e) => {\n        onMouseDown?.(e);\n        backdropClose.onMouseDown(e);\n      }}\n      onMouseUp={(e) => {\n        onMouseUp?.(e);\n        backdropClose.onMouseUp(e);\n      }}\n    >\n      <div\n        className={cn(\n          \"flex h-full w-full flex-col overflow-hidden bg-[var(--bg-surface)] shadow-xl\",\n          closing ? \"animate-sheet-out\" : \"animate-sheet\",\n          className,\n        )}\n      >\n        <div className=\"flex items-center justify-between gap-2 border-b border-[var(--border)] px-3 py-3\">\n          {hasTitle ? (\n            <div className=\"flex min-w-0 flex-1 items-center gap-2\">\n              <Heading id={titleId} className=\"min-w-0 break-words text-base font-semibold leading-snug text-[var(--text-primary)]\">\n                {title}\n              </Heading>\n              {hasHeader && <div className=\"min-w-0 flex-1 font-medium\">{header}</div>}\n            </div>\n          ) : (\n            <div className=\"min-w-0 flex-1 font-medium\">{header}</div>\n          )}\n          <button\n            type=\"button\"\n            onClick={requestClose}\n            aria-label={closeLabel}\n            className=\"-me-1 shrink-0 rounded p-1.5 text-[var(--text-muted)] hover:bg-[var(--bg-hover)] hover:text-[var(--text-secondary)]\"\n          >\n            <X className=\"size-5\" />\n          </button>\n        </div>\n        {/* DIALOG_GUTTER (0.75rem, the px-3 py-3 it was), not px-4: every pixel of\n            chrome here is width the form fields lose on a phone (feedback #32). The\n            body is the only thing that scrolls, so the header stays put and the page\n            underneath cannot move at all. */}\n        {/* `min-h-0` so it is the BODY that gives way to a footer, not the footer that\n            is pushed off the bottom edge. */}\n        <div className=\"min-h-0 flex-1 overflow-y-auto overscroll-contain\" style={{ padding: DIALOG_GUTTER }}>\n          {children}\n        </div>\n        {footer !== undefined && footer !== null && footer !== false && (\n          <div\n            data-full-bleed-footer=\"\"\n            className=\"flex shrink-0 flex-wrap items-center justify-end gap-2 border-t border-[var(--border)] px-3 pt-3\"\n            style={{ paddingBottom: \"max(0.75rem, env(safe-area-inset-bottom))\" }}\n          >\n            {footer}\n          </div>\n        )}\n      </div>\n    </div>,\n    document.body,\n  );\n}\n"],"mappings":"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","names":[]}
+{"version":3,"sources":["../../src/components/full-bleed-dialog.tsx"],"sourcesContent":["import { useId, useMemo, useRef } from \"react\";\nimport { createPortal } from \"react-dom\";\nimport type { ComponentPropsWithoutRef, KeyboardEvent, ReactNode, Ref } from \"react\";\nimport { X } from \"lucide-react\";\n\nimport { cn } from \"../lib/cn\";\nimport { mergeRefs } from \"./field-parts\";\nimport { useBackdropClose } from \"./modal\";\nimport { useBodyScrollLock } from \"../hooks/use-body-scroll-lock\";\nimport { useOverlayHistory } from \"../hooks/use-overlay-history\";\nimport { useCloseTransition } from \"../hooks/use-close-transition\";\nimport { useFocusTrap } from \"../hooks/use-focus-trap\";\nimport { runOwnKeyDown, takeEscape, useDismissLayer } from \"../hooks/use-dismiss\";\n\n/**\n * The padding around the dialog's scrolling body, as a CSS length (0.32,\n * docs/text-size-harmonization.md §10.11). Exported because a caller's sticky footer has\n * to reach across it: Chrome resolves a sticky offset against the scrollport's CONTENT\n * box, so a pinned row sits this far short of the panel's edge unless it cancels it\n * (keksdose's editor footer). In rem, so it grows with the text size — keksdose's px\n * copy (`SCROLLER_GUTTER_PX = 12`) was 3–6 px off at 125/150 %. Use it in `calc()`:\n * `bottom: calc(${inset}px - ${DIALOG_GUTTER})`.\n */\nexport const DIALOG_GUTTER = \"0.75rem\";\n\n/**\n * Named and exported, because `ComponentProps<typeof FullBleedDialog>` was the only way\n * to say \"the props of this\" and five call sites across keksdose and kastlan had already\n * written one (audit §api-design).\n *\n * It extends the `<div>` attributes so a caller can reach the OUTER element — the one\n * carrying `role=\"dialog\"`, and therefore the one an `aria-label`, an\n * `aria-describedby` or a `data-tour` anchor belongs on. {@link className} keeps going\n * to the panel inside it, which is what it has always meant here.\n */\nexport interface FullBleedDialogProps extends Omit<ComponentPropsWithoutRef<\"div\">, \"title\"> {\n  open: boolean;\n  /** The X, the backdrop (where one shows) and — unless {@link backCloses} is off —\n   *  the platform Back gesture all call this. */\n  onClose: () => void;\n  /**\n   * The dialog's HEADING: rendered as a real `h2` (see {@link headingAs}) at the start\n   * of the header strip, and wired to the dialog's `aria-labelledby`, so the dialog is\n   * announced by name rather than as just \"dialog\".\n   *\n   * Before this the strip was a styled `div`, and a caller that wanted its full-screen\n   * phone editor NAMED had to leave this component for `DialogFrame fullBleed` —\n   * keksdose's budget-table phone editor says so in a comment at the call site. A\n   * caller's own `aria-label` / `aria-labelledby` still wins.\n   */\n  title?: ReactNode;\n  /** The heading level of {@link title}. `h2` by default, as `DialogFrame`'s. */\n  headingAs?: \"h1\" | \"h2\" | \"h3\" | \"h4\";\n  /**\n   * Free content for the header strip, beside the close button — after the\n   * {@link title} when there is one, or on its own (the row editor shows the row's\n   * own first cell here). It does not name the dialog; `title` does.\n   */\n  header?: ReactNode;\n  closeLabel: string;\n  children: ReactNode;\n  /**\n   * Push a history entry so Back dismisses this dialog instead of navigating\n   * (Keksdose feedback #172). On by default, because a full-screen form that ignores\n   * the phone's universal \"go back\" gesture does not merely fail to close — the\n   * navigation lands somewhere else with the form still notionally open.\n   *\n   * **Off for a caller whose open state is already in the URL.** The transactions\n   * create card is `?action=new`, so Back already pops it through the router; a\n   * sentinel on top of that would cost two presses to close one dialog. One owner of\n   * the Back press, always.\n   */\n  backCloses?: boolean;\n  /** Extra classes for the PANEL (not the backdrop). */\n  className?: string;\n  /**\n   * A row pinned under the scrolling body — an Apply, a Save. Keksdose's `RangeSheet`\n   * (reports/report-range-field.tsx) is a hand-rolled copy of this dialog for want of\n   * exactly this slot: a date range picked on a phone is committed by a sticky Apply,\n   * and a button at the end of the body scrolls away with the calendar.\n   *\n   * Outside the scroller, so it stays put without `position: sticky` (which would\n   * need the body to be the scroll container of its own child and paint over the\n   * last field); padded for the home indicator, since it is the panel's bottom edge.\n   */\n  footer?: ReactNode;\n  /** The `role=\"dialog\"` element, where the rest of the props go (0.34, API-2, refactor\n   *  audit 2026-10) — merged with its own ref, which the focus trap holds. */\n  ref?: Ref<HTMLDivElement>;\n}\n\n/**\n * The phone's full-screen dialog: a panel that covers the viewport edge to edge.\n *\n * Not {@link Modal}, and that is a decision rather than an omission. Keksdose feedback\n * #32: the inset panel #204 shipped left a strip of page showing beside it on a phone,\n * and tapping that strip dismissed a form mid-edit. With no backdrop exposed there is\n * nothing to mis-tap, so the X is the way out — `backdropClose` stays wired for any\n * layout that does leave a backdrop visible, and costs nothing where none is.\n *\n * ## Why it is a component\n *\n * It was markup inside `data-table.tsx`, where it is the phone's row EDITOR. Keksdose\n * live #307's follow-up needed the same shell for the transactions CREATE card —\n * *\"Is the creation window of the tx still different than the edit window? Since the tx\n * list still appears below when scrolling down?\"* — and the two answers to that are\n * either one component or two copies that drift. Every previous convergence in that app\n * drifted the moment a second surface was written beside the first, which is what\n * `field-layer-parity` exists to catch one layer down.\n *\n * So the panel, the header strip, the scrolling body, the body-scroll lock and the Back\n * handling are all here, once.\n *\n * ## What the caller still owns\n *\n * The HEADER's content, because the two callers name themselves differently: the row\n * editor shows the row's own first column, the create card a plain title. A plain\n * title belongs in `title`, which is a real heading and the dialog's name; `header`\n * stays the free slot beside it. And `open`,\n * because who decides is the caller's business — see {@link backCloses}.\n */\nexport function FullBleedDialog({\n  open,\n  onClose,\n  title,\n  headingAs: Heading = \"h2\",\n  header,\n  closeLabel,\n  children,\n  backCloses = true,\n  className,\n  footer,\n  onMouseDown,\n  onMouseUp,\n  onKeyDown,\n  ref,\n  ...rest\n}: FullBleedDialogProps) {\n  // Every way OUT goes through `requestClose`, so the panel lowers itself before the\n  // caller unmounts it (live #320 rework). `onClose` is still what finally runs — this\n  // only delays it by the length of the animation.\n  const { closing, requestClose } = useCloseTransition(onClose);\n  const backdropClose = useBackdropClose(requestClose);\n  // The page behind must not scroll or jump under the overlay (feedback #204).\n  useBodyScrollLock(open);\n  useOverlayHistory(open && backCloses, requestClose);\n\n  const dialogRef = useRef<HTMLDivElement>(null);\n  const setDialog = useMemo(() => mergeRefs(dialogRef, ref), [ref]);\n  const titleId = useId();\n  const hasTitle = title !== undefined && title !== null && title !== false;\n  const hasHeader = header !== undefined && header !== null && header !== false;\n  // The half of \"modal\" this dialog was only claiming. It has said\n  // `aria-modal=\"true\"` since it was extracted from `data-table.tsx`, which tells\n  // assistive technology to hide everything outside it — while the user's focus stayed\n  // on the row they tapped, in the part that is now hidden. Tab then walked them\n  // through a table the screen reader would not describe, and on a phone this dialog\n  // covers the whole screen, so there was nothing on screen to say where they were.\n  //\n  // `initialFocus` is left at the default — the dialog itself, not the first field.\n  // This is the phone's row EDITOR and its first child is usually an input; focusing it\n  // would pull the software keyboard up over half the form before the user has said\n  // which field they came for. `Modal` made the same call for the same reason.\n  //\n  // That default only decides when nothing inside asked for focus. A field the app\n  // autofocuses on purpose keeps it (0.33.1): keksdose's create card autofocuses its\n  // amount, and the trap used to take focus straight back to the dialog — and on a\n  // phone the numpad sheet, which shows only while the field is focused, went with it\n  // (live #402). Closing still hands focus back to whatever opened the dialog.\n  useFocusTrap(dialogRef, { active: open });\n\n  // A layer on the Escape stack while open (Wave 2, DUP-1). This dialog is what a\n  // `PickerSheet`, a list or the numpad opens on top of, and the stack hands the key\n  // to whichever of them is topmost — one press dismissing the sheet AND the edit\n  // behind it was Keksdose live #309 (*\"Mouse Back does not only close the select but\n  // also the whole edit or create dialog\"*) on a different key.\n  useDismissLayer(open, requestClose);\n  const handleKeyDown = (e: KeyboardEvent<HTMLDivElement>) => {\n    // The caller's handler first (keksdose's transaction-search keeps its list keys on\n    // the dialog); a `preventDefault()` IN THAT HANDLER claims Escape. Only there: a\n    // descendant's does not count. A SearchField in the header prevents Escape to stop\n    // Chromium clearing a type=search input, and in 0.8.0 that silently stopped Escape\n    // from closing the dialog (keksdose). The one rule `Modal` now shares.\n    runOwnKeyDown(e, onKeyDown);\n    takeEscape(e);\n  };\n\n  if (!open || typeof document === \"undefined\") return null;\n\n  return createPortal(\n    /* eslint-disable-next-line jsx-a11y/no-noninteractive-element-interactions -- the dialog\n       container, per the APG dialog pattern: `onKeyDown` is Escape-to-close for whatever\n       inside it holds focus, and the mouse handlers are the backdrop press (Escape and the\n       close button are its keyboard path). */\n    <div\n      // `animate-overlay` on the backdrop and `animate-sheet` on the panel (live #320):\n      // the backdrop fades, the panel rises from the bottom edge it is anchored to.\n      // Both are no-ops under prefers-reduced-motion — see tokens.css.\n      //\n      // …and the same two backwards while `closing`, which is the #320 rework. The\n      // backdrop keeps taking pointer events on the way out: a tap during those 220ms\n      // is a tap on a dialog that is leaving, and letting it through to the row\n      // underneath would open a second one.\n      //\n      // `...rest` first, the dialog's own contract after it. A caller adding a\n      // `data-tour` anchor must not be able to take away the role, the modality or the\n      // `tabIndex` below by passing one of them too — this is the element the focus\n      // trap holds, and each of those failures is invisible on screen.\n      {...rest}\n      className={cn(\n        \"fixed inset-0 z-50 flex items-stretch justify-center bg-black/40 outline-none\",\n        closing ? \"animate-overlay-out\" : \"animate-overlay\",\n      )}\n      role=\"dialog\"\n      aria-modal=\"true\"\n      // The heading names the dialog unless the caller named it some other way — an\n      // `aria-labelledby` of its own, or an `aria-label` (which a `labelledby` would\n      // silently outrank).\n      aria-labelledby={rest[\"aria-labelledby\"] ?? (hasTitle && !rest[\"aria-label\"] ? titleId : undefined)}\n      // `tabIndex={-1}` is what makes the line above more than a claim: without it the\n      // container cannot take focus and `useFocusTrap` silently does nothing.\n      tabIndex={-1}\n      ref={setDialog}\n      onKeyDown={handleKeyDown}\n      // COMPOSED with the backdrop's, not overridden by them. These two used to ride\n      // `...rest` and then lose to `{...backdropClose}` spread after it, silently —\n      // and the one caller about to pass one is keksdose's RangeSheet, whose\n      // `onMouseDown={(e) => e.stopPropagation()}` is its dev#477 fix: a press in a\n      // portalled sheet must not reach a document-level \"outside click\" listener,\n      // which would unmount the day cell before its `click`. The caller's runs first;\n      // the backdrop's still runs after it, since it is the same element.\n      onMouseDown={(e) => {\n        onMouseDown?.(e);\n        backdropClose.onMouseDown(e);\n      }}\n      onMouseUp={(e) => {\n        onMouseUp?.(e);\n        backdropClose.onMouseUp(e);\n      }}\n    >\n      <div\n        className={cn(\n          \"flex h-full w-full flex-col overflow-hidden bg-surface shadow-xl\",\n          closing ? \"animate-sheet-out\" : \"animate-sheet\",\n          className,\n        )}\n      >\n        <div className=\"flex items-center justify-between gap-2 border-b border-subtle px-3 py-3\">\n          {hasTitle ? (\n            <div className=\"flex min-w-0 flex-1 items-center gap-2\">\n              <Heading id={titleId} className=\"min-w-0 break-words text-base font-semibold leading-snug text-primary\">\n                {title}\n              </Heading>\n              {hasHeader && <div className=\"min-w-0 flex-1 font-medium\">{header}</div>}\n            </div>\n          ) : (\n            <div className=\"min-w-0 flex-1 font-medium\">{header}</div>\n          )}\n          <button\n            type=\"button\"\n            onClick={requestClose}\n            aria-label={closeLabel}\n            className=\"-me-1 shrink-0 rounded p-1.5 text-muted hover:bg-hover hover:text-secondary\"\n          >\n            <X className=\"size-5\" />\n          </button>\n        </div>\n        {/* DIALOG_GUTTER (0.75rem, the px-3 py-3 it was), not px-4: every pixel of\n            chrome here is width the form fields lose on a phone (feedback #32). The\n            body is the only thing that scrolls, so the header stays put and the page\n            underneath cannot move at all. */}\n        {/* `min-h-0` so it is the BODY that gives way to a footer, not the footer that\n            is pushed off the bottom edge. */}\n        <div className=\"min-h-0 flex-1 overflow-y-auto overscroll-contain\" style={{ padding: DIALOG_GUTTER }}>\n          {children}\n        </div>\n        {footer !== undefined && footer !== null && footer !== false && (\n          <div\n            data-full-bleed-footer=\"\"\n            className=\"flex shrink-0 flex-wrap items-center justify-end gap-2 border-t border-subtle px-3 pt-3\"\n            style={{ paddingBottom: \"max(0.75rem, env(safe-area-inset-bottom))\" }}\n          >\n            {footer}\n          </div>\n        )}\n      </div>\n    </div>,\n    document.body,\n  );\n}\n"],"mappings":"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","names":[]}

package/dist/components/grouped-picker.d.ts

@@ -1,7 +1,5 @@
-import * as react from 'react';
-import { ComponentPropsWithoutRef, ReactNode } from 'react';
-
-interface PickerGroup {
+import type { ComponentPropsWithoutRef, ReactNode, Ref } from "react";
+export interface PickerGroup {
     key: string;
     label: string;
     /** `icon` is an optional leading glyph, drawn before the label — the same slot
@@ -20,9 +18,10 @@ interface PickerGroup {
  * different signatures under one name, and the kit's meaning is the one three apps
  * are written against.
  */
-interface GroupedPickerProps extends Omit<ComponentPropsWithoutRef<"div">, "onSelect"> {
+export interface GroupedPickerProps extends Omit<ComponentPropsWithoutRef<"div">, "onSelect"> {
     groups: PickerGroup[];
-    /** Face of the closed picker button. */
+    /** Face of the closed picker button. A string also names the trigger when no
+     *  `aria-label` does. */
     buttonLabel: ReactNode;
     /** Keys of the current selection, if any. */
     selected: {
@@ -30,19 +29,25 @@ interface GroupedPickerProps extends Omit<ComponentPropsWithoutRef<"div">, "onSe
         item: string;
     } | null;
     onSelect: (groupKey: string, itemKey: string) => void;
-    /**
-     * @deprecated Use `aria-label`, the DOM spelling every control in the kit now
-     * takes. Kept working — three apps pass it — and it applies only when
-     * `aria-label` is absent; it goes in a later minor.
-     */
-    ariaLabel?: string;
+    /** The filter box's prompt, and its accessible name. Default: `combobox.search` from
+     *  the {@link UiKitProvider}, else "Search". */
     filterPlaceholder?: string;
+    /** The TRIGGER — the focusable `<button>` — as on every picker of the kit (MultiSelect,
+     *  CountrySelect, CurrencySelect), not the wrapper the rest of the props go on (0.34,
+     *  API-2, refactor audit 2026-10). */
+    ref?: Ref<HTMLButtonElement>;
 }
 /** Panel picker for large grouped option sets: instead of one long flat
  * dropdown, the groups sit side by side as columns with their items listed
  * beneath (feedback #267/#276), narrowed by a filter box at the top (feedback
  * #267 rework). A query that matches a group's name keeps the whole group;
- * otherwise groups are reduced to their matching items. */
-declare function GroupedPicker({ groups, buttonLabel, selected, onSelect, ariaLabel, "aria-label": ariaLabelAttr, filterPlaceholder, className, ...rest }: GroupedPickerProps): react.JSX.Element;
-
-export { GroupedPicker, type GroupedPickerProps, type PickerGroup };
+ * otherwise groups are reduced to their matching items.
+ *
+ * On the picker family's foundation since round 0.34 (Wave 2, DUP-4 + BUG-12):
+ * `useComboboxCore` + `ComboboxPanel` in its `columns` layout. Its trigger promised a
+ * dialog that was no dialog, and the choice showed by colour alone; it is a combobox over
+ * a listbox now — one `role="group"` per column, named by its heading, the chosen item
+ * `aria-selected` and checked — with the arrow keys, Enter, a named filter box, the live
+ * result count, portal anchoring (dev#548) and, on a phone, the full-screen sheet
+ * (live #200) in one column. */
+export declare function GroupedPicker({ groups, buttonLabel, selected, onSelect, "aria-label": ariaLabel, filterPlaceholder, className, ref, ...rest }: GroupedPickerProps): import("react").JSX.Element;

package/dist/components/grouped-picker.js

@@ -1,39 +1,58 @@
 "use client";
 import { jsx, jsxs } from "react/jsx-runtime";
-import { useEffect, useMemo } from "react";
+import { useCallback, useId, useMemo } from "react";
 import { ChevronDown } from "lucide-react";
 import { cn } from "../lib/cn.js";
-import { DropdownSearchHeader, useDropdownSearch } from "./dropdown.js";
-import { useKitLocale } from "../i18n/kit-labels.js";
+import { foldForSearch } from "../lib/text-match.js";
+import { ComboboxPanel, useComboboxCore } from "./combobox-core.js";
+import { assignRef } from "./field-parts.js";
+import { DEFAULT_COMBOBOX_LABELS, useKitLabels, useKitLocale } from "../i18n/kit-labels.js";
+const itemValue = (group, item) => `${group}\0${item}`;
 function GroupedPicker({
   groups,
   buttonLabel,
   selected,
   onSelect,
-  ariaLabel,
-  "aria-label": ariaLabelAttr,
+  "aria-label": ariaLabel,
   filterPlaceholder,
   className,
+  ref,
   ...rest
 }) {
-  const { open, setOpen, wrapperRef, query, setQuery, inputRef } = useDropdownSearch();
-  useEffect(() => {
-    if (!open) return;
-    const onKey = (e) => {
-      if (e.key === "Escape") setOpen(false);
-    };
-    document.addEventListener("keydown", onKey);
-    return () => document.removeEventListener("keydown", onKey);
-  }, [open, setOpen]);
+  const core = useComboboxCore({ filter: false, backCloses: true });
+  const { open, setOpen, triggerRef, closeToTrigger, query } = core;
+  const setTrigger = useCallback(
+    (el) => {
+      triggerRef.current = el;
+      assignRef(ref, el);
+    },
+    [ref, triggerRef]
+  );
+  const comboText = useKitLabels("combobox", DEFAULT_COMBOBOX_LABELS);
   const locale = useKitLocale();
-  const filtered = useMemo(() => {
-    const fold = (s) => s.toLocaleLowerCase(locale);
-    const q = fold(query.trim());
-    if (!q) return groups;
-    return groups.map(
-      (g) => fold(g.label).includes(q) ? g : { ...g, items: g.items.filter((i) => fold(i.label).includes(q)) }
-    ).filter((g) => g.items.length > 0);
+  const results = useMemo(() => {
+    const q = foldForSearch(query.trim(), locale);
+    const has = (s) => foldForSearch(s, locale).includes(q);
+    const kept = q ? groups.map((g) => has(g.label) ? g : { ...g, items: g.items.filter((i) => has(i.label)) }).filter((g) => g.items.length > 0) : groups;
+    return kept.flatMap(
+      (g) => g.items.map(
+        (item) => ({
+          value: itemValue(g.key, item.key),
+          label: item.label,
+          icon: item.icon,
+          group: g.label
+        })
+      )
+    );
   }, [groups, query, locale]);
+  const keysOf = useMemo(() => {
+    const map = /* @__PURE__ */ new Map();
+    for (const g of groups) for (const item of g.items) map.set(itemValue(g.key, item.key), [g.key, item.key]);
+    return map;
+  }, [groups]);
+  const chosen = selected ? itemValue(selected.group, selected.item) : null;
+  const listboxId = `${useId()}-listbox`;
+  const name = ariaLabel ?? (typeof buttonLabel === "string" ? buttonLabel : void 0);
   return (
     // `rest` goes on the wrapper, but the accessible NAME does not: this div is a
     // positioning box with no role, so a label parked on it would be announced by
@@ -41,57 +60,52 @@ function GroupedPicker({
     // makes, and the reason `aria-label` is destructured out rather than left in
     // `rest`. Spread FIRST so the attributes below, each of them a fix with an
     // incident behind it, cannot be clobbered from outside.
-    /* @__PURE__ */ jsxs("div", { ...rest, ref: wrapperRef, className: cn("relative", className), children: [
+    /* @__PURE__ */ jsxs("div", { ...rest, className: cn("relative", className), children: [
       /* @__PURE__ */ jsxs(
         "button",
         {
+          ref: setTrigger,
           type: "button",
-          "aria-haspopup": "dialog",
+          role: "combobox",
+          "aria-haspopup": "listbox",
+          "aria-controls": listboxId,
           "aria-expanded": open,
-          "aria-label": ariaLabelAttr ?? ariaLabel,
+          "aria-label": name,
           onClick: () => setOpen((o) => !o),
-          className: "flex w-full items-center justify-between gap-2 rounded-md border border-[var(--border-strong)] bg-[var(--bg-surface)] px-2.5 py-1.5 text-sm text-[var(--text-primary)] hover:bg-[var(--bg-hover)]",
+          onKeyDown: (e) => {
+            if (e.key === "ArrowDown" || e.key === "ArrowUp") {
+              e.preventDefault();
+              setOpen(true);
+            }
+          },
+          className: "flex w-full items-center justify-between gap-2 rounded-md border border-strong bg-surface px-2.5 py-1.5 text-sm text-primary hover:bg-hover",
           children: [
-            /* @__PURE__ */ jsx("span", { className: "truncate", children: buttonLabel }),
-            /* @__PURE__ */ jsx(ChevronDown, { className: "size-4 shrink-0 text-[var(--text-placeholder)]" })
+            /* @__PURE__ */ jsx("span", { className: "truncate-until-large", children: buttonLabel }),
+            /* @__PURE__ */ jsx(ChevronDown, { className: "size-4 shrink-0 text-placeholder" })
           ]
         }
       ),
-      open && /* @__PURE__ */ jsxs("div", { className: "absolute start-0 z-30 mt-1 flex max-h-96 w-[min(56rem,85vw)] flex-col overflow-hidden rounded-md border border-[var(--border)] bg-[var(--bg-surface)] shadow-lg", children: [
-        /* @__PURE__ */ jsx(
-          DropdownSearchHeader,
-          {
-            query,
-            onQueryChange: setQuery,
-            inputRef,
-            placeholder: filterPlaceholder
-          }
-        ),
-        /* @__PURE__ */ jsx("div", { className: "overflow-y-auto p-3", children: filtered.length === 0 ? /* @__PURE__ */ jsx("p", { className: "text-sm text-[var(--text-muted)]", children: "\u2014" }) : /* @__PURE__ */ jsx("div", { className: "columns-2 gap-4 md:columns-3 xl:columns-4", children: filtered.map((g) => /* @__PURE__ */ jsxs("div", { className: "mb-3 break-inside-avoid", children: [
-          /* @__PURE__ */ jsx("div", { className: "mb-1 text-xs font-semibold uppercase tracking-wide text-[var(--text-muted)]", children: g.label }),
-          /* @__PURE__ */ jsx("ul", { className: "space-y-0.5", children: g.items.map((item) => {
-            const isSelected = selected !== null && g.key === selected.group && item.key === selected.item;
-            return /* @__PURE__ */ jsx("li", { children: /* @__PURE__ */ jsxs(
-              "button",
-              {
-                type: "button",
-                onClick: () => {
-                  onSelect(g.key, item.key);
-                  setOpen(false);
-                },
-                className: cn(
-                  "flex w-full items-center gap-1.5 rounded px-1.5 py-0.5 text-start text-sm",
-                  isSelected ? "bg-[var(--brand-bg)] font-medium text-[var(--brand-muted)]" : "text-[var(--text-secondary)] hover:bg-[var(--bg-hover)]"
-                ),
-                children: [
-                  item.icon && /* @__PURE__ */ jsx("span", { className: "shrink-0", children: item.icon }),
-                  /* @__PURE__ */ jsx("span", { className: "min-w-0 truncate", children: item.label })
-                ]
-              }
-            ) }, item.key);
-          }) })
-        ] }, g.key)) }) })
-      ] })
+      /* @__PURE__ */ jsx(
+        ComboboxPanel,
+        {
+          core: { ...core, results },
+          listboxId,
+          columns: true,
+          width: { minRem: 56 },
+          searchPlaceholder: filterPlaceholder ?? comboText.search,
+          sheetTitle: ariaLabel ?? buttonLabel,
+          isSelected: (v) => v === chosen,
+          onChoose: (o) => {
+            const keys = keysOf.get(o.value);
+            if (keys) onSelect(keys[0], keys[1]);
+            closeToTrigger();
+          },
+          showCreate: false,
+          onCreate: () => {
+          },
+          createContent: null
+        }
+      )
     ] })
   );
 }

package/dist/components/grouped-picker.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/components/grouped-picker.tsx"],"sourcesContent":["import { useEffect, useMemo } from \"react\";\nimport type { ComponentPropsWithoutRef, ReactNode } from \"react\";\nimport { ChevronDown } from \"lucide-react\";\nimport { cn } from \"../lib/cn\";\nimport { DropdownSearchHeader, useDropdownSearch } from \"./dropdown\";\nimport { useKitLocale } from \"../i18n/kit-labels\";\n\nexport interface PickerGroup {\n  key: string;\n  label: string;\n  /** `icon` is an optional leading glyph, drawn before the label — the same slot\n   *  `ComboOption` has always had, so the two pickers can present one option set\n   *  the same way. Omitted, a row is exactly what it was: label only, with no\n   *  reserved space, so a list where nothing has an icon does not indent. */\n  items: { key: string; label: string; icon?: ReactNode }[];\n}\n\n/**\n * `onSelect` is omitted from the div's own attributes because this component's\n * means \"an item was chosen\", not the DOM's \"text was selected inside me\" — two\n * different signatures under one name, and the kit's meaning is the one three apps\n * are written against.\n */\nexport interface GroupedPickerProps extends Omit<ComponentPropsWithoutRef<\"div\">, \"onSelect\"> {\n  groups: PickerGroup[];\n  /** Face of the closed picker button. */\n  buttonLabel: ReactNode;\n  /** Keys of the current selection, if any. */\n  selected: { group: string; item: string } | null;\n  onSelect: (groupKey: string, itemKey: string) => void;\n  /**\n   * @deprecated Use `aria-label`, the DOM spelling every control in the kit now\n   * takes. Kept working — three apps pass it — and it applies only when\n   * `aria-label` is absent; it goes in a later minor.\n   */\n  ariaLabel?: string;\n  filterPlaceholder?: string;\n}\n\n/** Panel picker for large grouped option sets: instead of one long flat\n * dropdown, the groups sit side by side as columns with their items listed\n * beneath (feedback #267/#276), narrowed by a filter box at the top (feedback\n * #267 rework). A query that matches a group's name keeps the whole group;\n * otherwise groups are reduced to their matching items. */\nexport function GroupedPicker({\n  groups,\n  buttonLabel,\n  selected,\n  onSelect,\n  ariaLabel,\n  \"aria-label\": ariaLabelAttr,\n  filterPlaceholder,\n  className,\n  ...rest\n}: GroupedPickerProps) {\n  const { open, setOpen, wrapperRef, query, setQuery, inputRef } = useDropdownSearch();\n\n  useEffect(() => {\n    if (!open) return;\n    const onKey = (e: KeyboardEvent) => {\n      if (e.key === \"Escape\") setOpen(false);\n    };\n    document.addEventListener(\"keydown\", onKey);\n    return () => document.removeEventListener(\"keydown\", onKey);\n  }, [open, setOpen]);\n\n  // Case folding in the provider's locale — see `rowMatches` for the Turkish \"İ\"\n  // that plain `toLowerCase` gets wrong.\n  const locale = useKitLocale();\n  const filtered = useMemo(() => {\n    const fold = (s: string) => s.toLocaleLowerCase(locale);\n    const q = fold(query.trim());\n    if (!q) return groups;\n    return groups\n      .map((g) =>\n        fold(g.label).includes(q)\n          ? g\n          : { ...g, items: g.items.filter((i) => fold(i.label).includes(q)) },\n      )\n      .filter((g) => g.items.length > 0);\n  }, [groups, query, locale]);\n\n  return (\n    // `rest` goes on the wrapper, but the accessible NAME does not: this div is a\n    // positioning box with no role, so a label parked on it would be announced by\n    // nothing. It belongs to the control — the same split every picker in this wave\n    // makes, and the reason `aria-label` is destructured out rather than left in\n    // `rest`. Spread FIRST so the attributes below, each of them a fix with an\n    // incident behind it, cannot be clobbered from outside.\n    <div {...rest} ref={wrapperRef} className={cn(\"relative\", className)}>\n      <button\n        type=\"button\"\n        aria-haspopup=\"dialog\"\n        aria-expanded={open}\n        aria-label={ariaLabelAttr ?? ariaLabel}\n        onClick={() => setOpen((o) => !o)}\n        className=\"flex w-full items-center justify-between gap-2 rounded-md border border-[var(--border-strong)] bg-[var(--bg-surface)] px-2.5 py-1.5 text-sm text-[var(--text-primary)] hover:bg-[var(--bg-hover)]\"\n      >\n        <span className=\"truncate\">{buttonLabel}</span>\n        <ChevronDown className=\"size-4 shrink-0 text-[var(--text-placeholder)]\" />\n      </button>\n      {open && (\n        <div className=\"absolute start-0 z-30 mt-1 flex max-h-96 w-[min(56rem,85vw)] flex-col overflow-hidden rounded-md border border-[var(--border)] bg-[var(--bg-surface)] shadow-lg\">\n          <DropdownSearchHeader\n            query={query}\n            onQueryChange={setQuery}\n            inputRef={inputRef}\n            placeholder={filterPlaceholder}\n          />\n          <div className=\"overflow-y-auto p-3\">\n            {filtered.length === 0 ? (\n              <p className=\"text-sm text-[var(--text-muted)]\">—</p>\n            ) : (\n              <div className=\"columns-2 gap-4 md:columns-3 xl:columns-4\">\n                {filtered.map((g) => (\n                  <div key={g.key} className=\"mb-3 break-inside-avoid\">\n                    <div className=\"mb-1 text-xs font-semibold uppercase tracking-wide text-[var(--text-muted)]\">\n                      {g.label}\n                    </div>\n                    <ul className=\"space-y-0.5\">\n                      {g.items.map((item) => {\n                        const isSelected =\n                          selected !== null &&\n                          g.key === selected.group &&\n                          item.key === selected.item;\n                        return (\n                          <li key={item.key}>\n                            <button\n                              type=\"button\"\n                              onClick={() => {\n                                onSelect(g.key, item.key);\n                                setOpen(false);\n                              }}\n                              className={cn(\n                                \"flex w-full items-center gap-1.5 rounded px-1.5 py-0.5 text-start text-sm\",\n                                isSelected\n                                  ? \"bg-[var(--brand-bg)] font-medium text-[var(--brand-muted)]\"\n                                  : \"text-[var(--text-secondary)] hover:bg-[var(--bg-hover)]\",\n                              )}\n                            >\n                              {item.icon && <span className=\"shrink-0\">{item.icon}</span>}\n                              <span className=\"min-w-0 truncate\">{item.label}</span>\n                            </button>\n                          </li>\n                        );\n                      })}\n                    </ul>\n                  </div>\n                ))}\n              </div>\n            )}\n          </div>\n        </div>\n      )}\n    </div>\n  );\n}\n"],"mappings":"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","names":[]}
+{"version":3,"sources":["../../src/components/grouped-picker.tsx"],"sourcesContent":["import { useCallback, useId, useMemo } from \"react\";\nimport type { ComponentPropsWithoutRef, ReactNode, Ref } from \"react\";\nimport { ChevronDown } from \"lucide-react\";\nimport { cn } from \"../lib/cn\";\nimport { foldForSearch } from \"../lib/text-match\";\nimport { ComboboxPanel, useComboboxCore, type ComboOption } from \"./combobox-core\";\nimport { assignRef } from \"./field-parts\";\nimport { DEFAULT_COMBOBOX_LABELS, useKitLabels, useKitLocale } from \"../i18n/kit-labels\";\n\nexport interface PickerGroup {\n  key: string;\n  label: string;\n  /** `icon` is an optional leading glyph, drawn before the label — the same slot\n   *  `ComboOption` has always had, so the two pickers can present one option set\n   *  the same way. Omitted, a row is exactly what it was: label only, with no\n   *  reserved space, so a list where nothing has an icon does not indent. */\n  items: { key: string; label: string; icon?: ReactNode }[];\n}\n\n/**\n * `onSelect` is omitted from the div's own attributes because this component's\n * means \"an item was chosen\", not the DOM's \"text was selected inside me\" — two\n * different signatures under one name, and the kit's meaning is the one three apps\n * are written against.\n */\nexport interface GroupedPickerProps extends Omit<ComponentPropsWithoutRef<\"div\">, \"onSelect\"> {\n  groups: PickerGroup[];\n  /** Face of the closed picker button. A string also names the trigger when no\n   *  `aria-label` does. */\n  buttonLabel: ReactNode;\n  /** Keys of the current selection, if any. */\n  selected: { group: string; item: string } | null;\n  onSelect: (groupKey: string, itemKey: string) => void;\n  /** The filter box's prompt, and its accessible name. Default: `combobox.search` from\n   *  the {@link UiKitProvider}, else \"Search\". */\n  filterPlaceholder?: string;\n  /** The TRIGGER — the focusable `<button>` — as on every picker of the kit (MultiSelect,\n   *  CountrySelect, CurrencySelect), not the wrapper the rest of the props go on (0.34,\n   *  API-2, refactor audit 2026-10). */\n  ref?: Ref<HTMLButtonElement>;\n}\n\n/** An item's value in the list: the group's key and the item's, which together are\n *  unique where an item key alone is not (two groups may each have an \"Other\"). */\nconst itemValue = (group: string, item: string) => `${group}\\u0000${item}`;\n\n/** Panel picker for large grouped option sets: instead of one long flat\n * dropdown, the groups sit side by side as columns with their items listed\n * beneath (feedback #267/#276), narrowed by a filter box at the top (feedback\n * #267 rework). A query that matches a group's name keeps the whole group;\n * otherwise groups are reduced to their matching items.\n *\n * On the picker family's foundation since round 0.34 (Wave 2, DUP-4 + BUG-12):\n * `useComboboxCore` + `ComboboxPanel` in its `columns` layout. Its trigger promised a\n * dialog that was no dialog, and the choice showed by colour alone; it is a combobox over\n * a listbox now — one `role=\"group\"` per column, named by its heading, the chosen item\n * `aria-selected` and checked — with the arrow keys, Enter, a named filter box, the live\n * result count, portal anchoring (dev#548) and, on a phone, the full-screen sheet\n * (live #200) in one column. */\nexport function GroupedPicker({\n  groups,\n  buttonLabel,\n  selected,\n  onSelect,\n  \"aria-label\": ariaLabel,\n  filterPlaceholder,\n  className,\n  ref,\n  ...rest\n}: GroupedPickerProps) {\n  // `filter: false`: the filter below keeps a whole group when its name matches, so the\n  // panel is handed the rows, as CountrySelect's are. Escape is the core's layer on the\n  // kit's stack — this kept an Escape handler of its own on its panel (round 0.34 BUG-1),\n  // and the stack is the one answer to it now (DUP-1). Back closes the list, as it did on\n  // `useDropdown`.\n  const core = useComboboxCore<string>({ filter: false, backCloses: true });\n  const { open, setOpen, triggerRef, closeToTrigger, query } = core;\n  // The core anchors the panel to the trigger and hands focus back to it; the caller's\n  // `ref` wants the same element. One callback feeds both, as on MultiSelect.\n  const setTrigger = useCallback(\n    (el: HTMLButtonElement | null) => {\n      triggerRef.current = el;\n      assignRef(ref, el);\n    },\n    [ref, triggerRef],\n  );\n  const comboText = useKitLabels(\"combobox\", DEFAULT_COMBOBOX_LABELS);\n\n  // Folded as every kit list folds (DUP-5): the locale's case (the Turkish \"İ\" that\n  // plain `toLowerCase` gets wrong), and now the accents too — \"zurich\" finds Zürich.\n  const locale = useKitLocale();\n  const results = useMemo(() => {\n    const q = foldForSearch(query.trim(), locale);\n    const has = (s: string) => foldForSearch(s, locale).includes(q);\n    const kept = q\n      ? groups\n          .map((g) => (has(g.label) ? g : { ...g, items: g.items.filter((i) => has(i.label)) }))\n          .filter((g) => g.items.length > 0)\n      : groups;\n    return kept.flatMap((g) =>\n      g.items.map(\n        (item): ComboOption<string> => ({\n          value: itemValue(g.key, item.key),\n          label: item.label,\n          icon: item.icon,\n          group: g.label,\n        }),\n      ),\n    );\n  }, [groups, query, locale]);\n  // Back to keys for `onSelect`, by the value the row carries.\n  const keysOf = useMemo(() => {\n    const map = new Map<string, [string, string]>();\n    for (const g of groups) for (const item of g.items) map.set(itemValue(g.key, item.key), [g.key, item.key]);\n    return map;\n  }, [groups]);\n  const chosen = selected ? itemValue(selected.group, selected.item) : null;\n\n  const listboxId = `${useId()}-listbox`;\n  // The trigger's NAME: a combobox takes none from its content. The caller's\n  // `aria-label`, as on every picker of the kit, else the face when it is text.\n  const name = ariaLabel ?? (typeof buttonLabel === \"string\" ? buttonLabel : undefined);\n\n  return (\n    // `rest` goes on the wrapper, but the accessible NAME does not: this div is a\n    // positioning box with no role, so a label parked on it would be announced by\n    // nothing. It belongs to the control — the same split every picker in this wave\n    // makes, and the reason `aria-label` is destructured out rather than left in\n    // `rest`. Spread FIRST so the attributes below, each of them a fix with an\n    // incident behind it, cannot be clobbered from outside.\n    <div {...rest} className={cn(\"relative\", className)}>\n      <button\n        ref={setTrigger}\n        type=\"button\"\n        // A closed choice that expands into the list below — the role every trigger\n        // picker in the kit wears. It said `aria-haspopup=\"dialog\"` over a panel that was\n        // no dialog (BUG-12).\n        role=\"combobox\"\n        aria-haspopup=\"listbox\"\n        aria-controls={listboxId}\n        aria-expanded={open}\n        aria-label={name}\n        onClick={() => setOpen((o) => !o)}\n        // Down/Up opens the list from the closed trigger, per the APG.\n        onKeyDown={(e) => {\n          if (e.key === \"ArrowDown\" || e.key === \"ArrowUp\") {\n            e.preventDefault();\n            setOpen(true);\n          }\n        }}\n        className=\"flex w-full items-center justify-between gap-2 rounded-md border border-strong bg-surface px-2.5 py-1.5 text-sm text-primary hover:bg-hover\"\n      >\n        {/* The trigger's label and each item wrap from Large up (text size §10.17,\n            round 0.34 T1: the sweep read \"Choose a cat…\" at 360 px / Extra large). */}\n        <span className=\"truncate-until-large\">{buttonLabel}</span>\n        <ChevronDown className=\"size-4 shrink-0 text-placeholder\" />\n      </button>\n      <ComboboxPanel\n        core={{ ...core, results }}\n        listboxId={listboxId}\n        columns\n        // As wide as four columns want (56rem), within the glass, from the trigger's\n        // start — the panel it always was.\n        width={{ minRem: 56 }}\n        searchPlaceholder={filterPlaceholder ?? comboText.search}\n        sheetTitle={ariaLabel ?? buttonLabel}\n        isSelected={(v) => v === chosen}\n        onChoose={(o) => {\n          const keys = keysOf.get(o.value);\n          if (keys) onSelect(keys[0], keys[1]);\n          closeToTrigger();\n        }}\n        showCreate={false}\n        onCreate={() => {}}\n        createContent={null}\n      />\n    </div>\n  );\n}\n"],"mappings":"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","names":[]}

package/dist/components/help-popover.d.ts

@@ -0,0 +1,60 @@
+import type { ReactNode } from "react";
+import type { RemLength } from "../hooks/use-breakpoint.js";
+/** {@link HelpPopover}'s props. */
+export interface HelpPopoverProps {
+    /**
+     * Names the "?" and the panel — a short question ("What do the statuses mean?") or
+     * "About <field>" ("About the settlement date"), in the reader's language. Required:
+     * a "?" named "?" tells a screen reader nothing about what it opens. Not the help
+     * itself, which is `children`.
+     */
+    label: string;
+    /** The help: a paragraph, or a few. Rendered in the panel at body size. */
+    children: ReactNode;
+    /** The panel's width — {@link Popover}'s `width`. Default `"20rem"`, a paragraph's
+     *  measure; it follows the text size and never exceeds the viewport. */
+    width?: number | RemLength;
+    /** Classes for the "?" button. */
+    className?: string;
+}
+/**
+ * A "?" whose HELP opens on a tap, a click or Enter — for a paragraph too long to print
+ * under a field (0.34, keksdose K3, live #400: *"Remove the long text and move it behind
+ * a clickable notice like a circle"*).
+ *
+ * **Help, not a fact** (docs/text-size-harmonization.md §10.23). {@link FieldHint} is
+ * the "?" for a FACT — a format, a limit, a consequence — and since 0.32 it turns into
+ * its own words under the field at Large and on a touch screen (`useInlineHint`, §4 "No
+ * fact only in a tooltip"), because a fact a reader cannot reach is a fact they do not
+ * have. That rule stays. This part is for HELP: why the field exists, how to choose,
+ * what the options mean — text the field is usable without. Printed inline it was the
+ * longest thing in keksdose's transaction form (four statuses, ~500 characters, on every
+ * new row on a phone). `useInlineHint` turns only a FieldHint into a caption, so this
+ * one stays on the label line at every size.
+ *
+ * **On a field.** Pass it as `hint`, as a FieldHint is passed: every kit field that
+ * puts a FieldHint on its label line puts this there too, as it does any `hint` that is
+ * not text (Input, Select, Textarea, NumberInput, AmountInput, the comboboxes and
+ * pickers, ToggleGroup, {@link FieldStrip}) — and an unlabelled one at its end edge,
+ * outside the box. The `@eifi1/ui-kit/rhf` bindings draw every `hint` under the field,
+ * this one included. It also stands on its own, beside a heading or a column title.
+ *
+ * **A popover, not a tooltip**: a tooltip bubble is for a line, and opens on hover a
+ * finger never makes. This is the kit {@link Popover}: it opens and closes on a tap or a
+ * click (and on Enter or Space, as any button does), closes on Escape and on a press
+ * outside, and takes the focus into its panel and gives it back to the "?" on close. The
+ * panel is a `dialog` named by `label` and described by the help, so a screen reader
+ * reads both on opening. The "?" says `aria-expanded` and `aria-haspopup="dialog"`.
+ *
+ * **"?" rather than "!"**: it answers a question ("what is the difference between
+ * accepted and cleared?", keksdose live #247); "!" is a warning.
+ *
+ * ```tsx
+ * <Select label="Status" hint={
+ *   <HelpPopover label="What do the statuses mean?">
+ *     Pending: … Accepted: … Cleared: … Reconciled: …
+ *   </HelpPopover>
+ * } … />
+ * ```
+ */
+export declare function HelpPopover({ label, children, width, className }: HelpPopoverProps): import("react").JSX.Element;

package/dist/components/help-popover.js

@@ -0,0 +1,48 @@
+"use client";
+import { jsx } from "react/jsx-runtime";
+import { useId } from "react";
+import { HelpCircle } from "lucide-react";
+import { cn } from "../lib/cn.js";
+import { FOCUS_RING } from "./focus-ring.js";
+import { Popover } from "./popover.js";
+const HELP_WIDTH = "20rem";
+function HelpPopover({ label, children, width = HELP_WIDTH, className }) {
+  const panelId = useId();
+  const bodyId = useId();
+  return /* @__PURE__ */ jsx(
+    Popover,
+    {
+      width,
+      panelId,
+      "aria-label": label,
+      "aria-describedby": bodyId,
+      trigger: ({ open, toggle, ref }) => /* @__PURE__ */ jsx(
+        "button",
+        {
+          ref,
+          type: "button",
+          "aria-label": label,
+          "aria-expanded": open,
+          "aria-haspopup": "dialog",
+          "aria-controls": open ? panelId : void 0,
+          onClick: (e) => {
+            e.preventDefault();
+            toggle();
+          },
+          className: cn(
+            "flex rounded-full text-placeholder transition-colors hover:text-secondary",
+            open && "text-secondary",
+            FOCUS_RING,
+            className
+          ),
+          children: /* @__PURE__ */ jsx(HelpCircle, { "aria-hidden": true, className: "size-3.5" })
+        }
+      ),
+      children: () => /* @__PURE__ */ jsx("div", { id: bodyId, className: "space-y-2 text-sm leading-snug text-primary", children })
+    }
+  );
+}
+export {
+  HelpPopover
+};
+//# sourceMappingURL=help-popover.js.map