@eifi1/ui-kit 0.54.0 → 0.55.0

package/dist/components/dropdown.js

@@ -7,6 +7,7 @@ import { anchoredInline, useAnchoredPanel } from "../hooks/use-anchored-panel.js
 import { pressInside, runOwnKeyDown, takeEscape, useDismissLayer, useOutsideClick } from "../hooks/use-dismiss.js";
 import { useOverlayHistory } from "../hooks/use-overlay-history.js";
 import { cn } from "../lib/cn.js";
+import { returnFocus } from "../lib/focus-left.js";
 import { FIELD_TOUCH_TEXT } from "./field-base.js";
 import { mergeRefs } from "./field-parts.js";
 import { FOCUS_RING } from "./focus-ring.js";
@@ -23,15 +24,18 @@ function useDropdown({
   const panelRef = useRef(null);
   const openerRef = useRef(null);
   useEffect(() => {
-    if (!open) return;
+    if (!open) {
+      openerRef.current = null;
+      return;
+    }
     const el = document.activeElement;
     openerRef.current = el instanceof HTMLElement && el !== document.body ? el : null;
   }, [open]);
   const close = useCallback(() => setOpen(false), []);
   const closeToTrigger = useCallback(() => {
+    const closing = panelRef.current ?? wrapperRef.current;
+    returnFocus({ opener: triggerRef.current, fallback: [openerRef.current], closing });
     setOpen(false);
-    const back = triggerRef.current ?? openerRef.current;
-    if (back?.isConnected) back.focus();
   }, []);
   useOutsideClick([wrapperRef, panelRef], close, open && !panelIsSheet);
   const layer = useDismissLayer(open && escapeLayer, closeToTrigger);

package/dist/components/dropdown.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/components/dropdown.tsx"],"sourcesContent":["import { useCallback, useEffect, useMemo, useRef, useState } from \"react\";\nimport type {\n  ComponentPropsWithoutRef,\n  ComponentPropsWithRef,\n  KeyboardEvent as ReactKeyboardEvent,\n  PointerEvent as ReactPointerEvent,\n  ReactNode,\n  Ref,\n  RefObject,\n} from \"react\";\nimport { createPortal } from \"react-dom\";\nimport { Search } from \"lucide-react\";\nimport { anchoredInline, useAnchoredPanel } from \"../hooks/use-anchored-panel\";\nimport { pressInside, runOwnKeyDown, takeEscape, useDismissLayer, useOutsideClick } from \"../hooks/use-dismiss\";\nimport type { DismissLayer } from \"../hooks/use-dismiss\";\nimport { useOverlayHistory } from \"../hooks/use-overlay-history\";\nimport { cn } from \"../lib/cn\";\nimport { FIELD_TOUCH_TEXT } from \"./field-base\";\nimport { mergeRefs } from \"./field-parts\";\nimport { FOCUS_RING } from \"./focus-ring\";\nimport { useAnchorDir } from \"./use-anchor-dir\";\n\n/** Each list's Escape layer, filed under the refs {@link useDropdown} and\n *  {@link useDropdownSearch} hand out (`panelRef`, `inputRef`), for the panel and the\n *  search box those refs are passed to — see \"The caller's own handler\" on\n *  {@link useDropdown} (round 0.35 R2). Weak: a list's refs go with its component. */\nconst listLayers = new WeakMap<object, DismissLayer>();\n\n/**\n * Open state + close-on-outside-click for a custom dropdown — the two input-shaped\n * comboboxes, and an app's own panel. (MultiSelect, CurrencySelect, GroupedPicker and\n * AmountInput's currency picker moved onto `useComboboxCore` + `ComboboxPanel` in round\n * 0.34, Wave 2 DUP-4, for the phone sheet and the portal.) Attach `wrapperRef`\n * to the relatively-positioned container; the popover lives inside it so a click\n * anywhere else closes it.\n *\n * ## Back closes the list, not the page behind it\n *\n * Keksdose live #309 rework: *\"It shall only close it if it is prior open, and not\n * when I am seeing the dialog.\"* Round one wired {@link PickerSheet} — the shape\n * these lists take on a PHONE — into {@link useOverlayHistory}, and left the pointer\n * shape out. So on a desktop one Back press over an open list still went past it to\n * the dialog underneath: measured on his own budget, the transfer form's account list\n * was showing and Back took the entire add card, amount and all. That is the same\n * loss round one called *\"discarding an edit in progress in order to dismiss a\n * list\"*, in the other shell.\n *\n * Every dropdown built on this hook is dismissible and is the topmost thing on screen\n * while it is up, so the rule is the hook's rather than each caller's. `backCloses`\n * is for the ONE case where a second entry would be wrong: a caller whose panel is\n * itself a `PickerSheet`, which already registers one — both comboboxes swap shape at\n * the phone layout (`usePhoneLayout()`), and two entries would cost two Back presses to close one sheet.\n *\n * ## One outside-click rule for the whole package\n *\n * This hand-rolled a second document listener, on `mousedown`, months after\n * {@link useOutsideClick} — the hook the entity pickers dismiss through — was moved to\n * `pointerdown` for a reason that applies here word for word: on a touch platform\n * `mousedown` is SYNTHESISED, the browser emits it for most taps but is not obliged\n * to, and MultiSelect, CurrencySelect, GroupedPicker, AmountInput's currency picker\n * and both comboboxes all dismiss through this. Two copies of one rule is one copy\n * too many; this now delegates, so the package has a single answer to \"what is an\n * outside press\".\n *\n * `panelIsSheet` is what that delegation needs. A {@link PickerSheet} is modal and\n * fills the screen, so it has no outside — and being portalled to `<body>`, it is\n * inside neither `wrapperRef` nor `panelRef`, so a listener left running would read\n * every tap in it as a press outside and close it at finger-down. The sheet's own\n * `onMouseDown` stopPropagation guard used to hide that from this hook; it cannot\n * stop a `pointerdown`. It defaults to `!backCloses` because the two ask the same\n * question — \"is this caller's panel a sheet?\" — and the one caller that answers yes\n * already says so; they are separate props so a future caller can answer them apart.\n *\n * ## Escape, and where focus lands after it\n *\n * This hook had no Escape at all (the audit's §a11y): Back closed these lists, an\n * outside press closed them, and the one key every other dismissible surface in the\n * package answers to did nothing — so a keyboard user who opened a list had no way\n * out of it that did not also choose something. An open list is a layer on the kit's\n * one Escape stack ({@link useDismissLayer}), as `Modal`, `Popover` and\n * `useComboboxCore` are, so the package keeps one answer to \"what does Escape do\".\n *\n * Escape RESTORES FOCUS; an outside press does not. A press has already put focus\n * where the user pointed, and dragging it back from there would be the bug. Attach\n * `triggerRef` to the control that opens the panel and the keyboard paths — Escape,\n * Tab, a commit — hand focus back to it; leave it unattached and they hand it back to\n * whatever held focus when the list opened, which is the control that was pressed.\n *\n * ## Escape inside a dialog (round 0.34 BUG-1, Wave 2 DUP-1)\n *\n * One press in an open list inside a `Modal` or a `FullBleedDialog` used to close the\n * DIALOG, form and all, and leave the list open: the dialog took Escape in its own\n * `onKeyDown` before a document listener could. On the stack the list is above the\n * dialog, so the list closes and the dialog stays. {@link DropdownPanel} and\n * {@link DropdownSearchHeader} take the key on their own elements, where focus is,\n * and stop it there — so a caller passes nothing new, AmountInput's currency chip\n * included.\n *\n * ## The caller's own handler (round 0.35 R2)\n *\n * A caller's `onKeyDown` on {@link DropdownPanel} or {@link DropdownSearchHeader} hears\n * Escape only while this list is the layer on top — the rule the dialogs got first. A\n * tooltip over a row takes that press first, and the next one is the handler's, whose\n * `preventDefault()` still keeps the list. The two find the list's layer through the\n * refs this hook hands out — the panel through `panelRef`, the search box through\n * {@link useDropdownSearch}'s `inputRef` — so a caller passes nothing new. One handed\n * neither (an un-anchored panel may leave `panelRef` off) hears every key, as before.\n *\n * `escapeLayer: false` is for a caller that registers its own layer: the editable\n * comboboxes, whose list can be \"open\" with nothing in it to show — an Escape there\n * belongs to the dialog.\n */\nexport function useDropdown<T extends HTMLElement = HTMLDivElement>({\n  backCloses = true,\n  panelIsSheet = !backCloses,\n  escapeLayer = true,\n}: { backCloses?: boolean; panelIsSheet?: boolean; escapeLayer?: boolean } = {}) {\n  const [open, setOpen] = useState(false);\n  const wrapperRef = useRef<T>(null);\n  // The control that opens the panel — see the note above on why only the keyboard\n  // paths read it, and why attaching it is the caller's choice.\n  const triggerRef = useRef<HTMLButtonElement>(null);\n  // The panel, once it is PORTALLED (see {@link DropdownPanel}'s `anchorRef`): it is\n  // then a child of <body> rather than of the wrapper, so \"did the click land inside\n  // the wrapper\" answers no for every click on the list itself and the first option a\n  // user picked closed the dropdown without picking anything.\n  const panelRef = useRef<HTMLDivElement>(null);\n  // Where focus was as the list opened — the trigger focus goes back to when the\n  // caller attached none. Read in an effect, before `useDropdownSearch`'s frame moves\n  // focus into the search box.\n  const openerRef = useRef<HTMLElement | null>(null);\n  useEffect(() => {\n    if (!open) return;\n    const el = document.activeElement;\n    openerRef.current = el instanceof HTMLElement && el !== document.body ? el : null;\n  }, [open]);\n  const close = useCallback(() => setOpen(false), []);\n  // Closing unmounts whatever held focus — the search box, the row the keyboard was\n  // on — and the browser then drops focus on <body>: the caret vanishes and the next\n  // Tab restarts at the top of the document, and inside a dialog the next Escape goes\n  // nowhere. Whoever closed the list with a key gets focus handed back to the trigger\n  // they opened it from.\n  const closeToTrigger = useCallback(() => {\n    setOpen(false);\n    const back = triggerRef.current ?? openerRef.current;\n    if (back?.isConnected) back.focus();\n  }, []);\n  useOutsideClick([wrapperRef, panelRef], close, open && !panelIsSheet);\n  // See \"Escape inside a dialog\" above.\n  const layer = useDismissLayer(open && escapeLayer, closeToTrigger);\n  // Filed under `panelRef` for the panel's own handler — \"The caller's own handler\" above.\n  useEffect(() => {\n    listLayers.set(panelRef, layer);\n  }, [panelRef, layer]);\n  // Same close path Escape and an outside click take, so a list dismissed by Back\n  // cannot end up in a different state from one dismissed any other way.\n  useOverlayHistory(open && backCloses, close);\n  return { open, setOpen, wrapperRef, panelRef, triggerRef, closeToTrigger };\n}\n\n/**\n * {@link useDropdown} plus a search box: clears the query and focuses the search\n * input each time the panel opens, so typing filters immediately.\n */\nexport function useDropdownSearch<T extends HTMLElement = HTMLDivElement>() {\n  const { open, setOpen, wrapperRef, panelRef, triggerRef, closeToTrigger } = useDropdown<T>();\n  const [query, setQuery] = useState(\"\");\n  const inputRef = useRef<HTMLInputElement>(null);\n  // The list's layer again, under `inputRef` for the search box's handler (round 0.35\n  // R2). `useDropdown`'s effect, which runs first, has filed it under `panelRef`.\n  useEffect(() => {\n    const layer = listLayers.get(panelRef);\n    if (layer) listLayers.set(inputRef, layer);\n  }, [panelRef]);\n  useEffect(() => {\n    if (open) {\n      // eslint-disable-next-line react-hooks/set-state-in-effect -- reset the query on open\n      setQuery(\"\");\n      requestAnimationFrame(() => inputRef.current?.focus());\n    }\n  }, [open]);\n  return {\n    open,\n    setOpen,\n    wrapperRef,\n    panelRef,\n    triggerRef,\n    closeToTrigger,\n    query,\n    setQuery,\n    inputRef,\n  };\n}\n\n/** `onKeyDown` is the INPUT's, not the wrapper's — the list's keyboard is handled\n *  where the focus is (see the note above), so the div's own handler signature is\n *  omitted in favour of it. */\nexport interface DropdownSearchHeaderProps extends Omit<ComponentPropsWithRef<\"div\">, \"onKeyDown\"> {\n  query: string;\n  onQueryChange: (v: string) => void;\n  inputRef: RefObject<HTMLInputElement | null>;\n  placeholder?: string;\n  /** The `<ul role=\"listbox\">` this box filters. */\n  listboxId?: string;\n  /** The id of the option the arrow keys are currently on, if any. */\n  activeId?: string;\n  /** Arrow/Home/End/Enter/Tab — the list's keyboard, handled where the focus is.\n   *  Escape closes the list (the topmost layer on the kit's Escape stack); call\n   *  `preventDefault()` on it here to keep it. */\n  onKeyDown?: (e: ReactKeyboardEvent<HTMLInputElement>) => void;\n}\n\n/** The search row (magnifier + text input) shared by the searchable dropdowns.\n *\n *  The input had `outline-none` and nothing in its place (the audit's §a11y, the same\n *  finding as the numpad's keys). That mattered more here than the bare class suggests:\n *  {@link useDropdownSearch} focuses this box the moment a panel opens, so the caret is\n *  the ONLY evidence of where the next keystroke goes — and a caret in an empty field\n *  showing a placeholder is a single blinking pixel column. The ring is what says \"this\n *  list is being typed into\"; it appears whenever the field holds focus, which for a\n *  text input is exactly when it is true.\n *\n *  ## Why this box is a plain textbox and the TRIGGER is the combobox\n *\n *  The panels this header sits in are opened by a field-shaped trigger, and that\n *  trigger is what carries `role=\"combobox\"` (see {@link MultiSelect},\n *  {@link EntityCombobox}). Two comboboxes for one list would be one too many — a\n *  reader tabbing back to the field would meet a second one describing the same\n *  choice. So this stays a textbox, which ARIA lets own `aria-activedescendant` and\n *  `aria-controls` exactly as a combobox does: focus is HERE while the list is up, so\n *  this is what has to say which option the arrow keys are on.\n *\n *  Pass `listboxId` and the wiring appears; omit it and the box is what it always\n *  was, for the callers that have no listbox to point at. */\nexport function DropdownSearchHeader({\n  query,\n  onQueryChange,\n  inputRef,\n  placeholder,\n  listboxId,\n  activeId,\n  onKeyDown,\n  \"aria-label\": ariaLabel,\n  className,\n  ...rest\n}: DropdownSearchHeaderProps) {\n  return (\n    // `rest` dresses the header row; the NAME goes on the box below it. A search\n    // input whose only name is its placeholder has none the moment a character is\n    // typed into it — the placeholder disappears — which is why this is worth a prop\n    // at all rather than something a caller could add from outside.\n    <div {...rest} className={cn(\"flex items-center gap-2 border-b border-subtle px-2 py-1.5\", className)}>\n      <Search className=\"size-4 text-placeholder\" />\n      <input\n        ref={inputRef}\n        type=\"text\"\n        value={query}\n        onChange={(e) => onQueryChange(e.target.value)}\n        onKeyDown={(e) => {\n          // The caller's handler hears Escape only while the list is on top (round 0.35\n          // R2) — the layer filed under `inputRef`, when {@link useDropdownSearch} made it.\n          runOwnKeyDown(e, onKeyDown, listLayers.get(inputRef));\n          // Focus is in this box while the list is up, so this is where Escape lands\n          // first — see \"Escape inside a dialog\" on {@link useDropdown}.\n          takeEscape(e);\n        }}\n        placeholder={placeholder}\n        aria-label={ariaLabel}\n        aria-controls={listboxId}\n        aria-activedescendant={activeId}\n        aria-autocomplete={listboxId ? \"list\" : undefined}\n        // FIELD_TOUCH_TEXT: a search box is a field — at least 16 px on touch, or iOS zooms\n        // the page the moment a picker opens and focuses it (§10.1).\n        className={cn(\n          \"w-full rounded-sm bg-transparent text-sm outline-none placeholder:text-placeholder text-primary\",\n          FOCUS_RING,\n          FIELD_TOUCH_TEXT,\n        )}\n      />\n    </div>\n  );\n}\n\nexport interface DropdownPanelProps extends ComponentPropsWithoutRef<\"div\"> {\n  header?: ReactNode;\n  empty?: boolean;\n  /** Attributes for the `<ul>` itself — how a caller whose children are options\n   *  gives the list its `role=\"listbox\"`, its id and `aria-multiselectable`. The\n   *  panel owns the scrolling and the padding, so `className` here is merged rather\n   *  than replaced. */\n  listProps?: ComponentPropsWithoutRef<\"ul\">;\n  /** The trigger to hang off. Given, the panel portals and goes `fixed`. */\n  anchorRef?: RefObject<HTMLElement | null>;\n  /** {@link useDropdown}'s `panelRef`, so an outside-click sees this as inside. Escape\n   *  anywhere in the panel, on a row as in the search box, closes the list rather than\n   *  a dialog around it. It is also how the panel finds the list's Escape layer, for\n   *  its `onKeyDown` (round 0.35 R2: see \"The caller's own handler\" there). */\n  panelRef?: RefObject<HTMLDivElement | null>;\n  /** Panel width in px, for the anchored form (the CSS `w-*` cannot be measured). */\n  width?: number;\n  /** Which of the panel's edges lines up with the trigger's, room permitting, by the\n   *  trigger's reading direction — `end` is the right edge in a left-to-right form and\n   *  the left one in a right-to-left form. Default `end`. The physical `left` / `right`\n   *  went in 0.35 (round 0.35 R1, refactor audit 2026-10, API-6e): `right` is `end` in a\n   *  left-to-right page, `left` is `start`. */\n  align?: \"start\" | \"end\";\n  children: ReactNode;\n  /** The panel, where the rest of the props go (0.34, API-2, refactor audit 2026-10) —\n   *  merged with `panelRef`, so the outside-click still sees it. */\n  ref?: Ref<HTMLDivElement>;\n}\n\n/**\n * The floating popover surface for the searchable dropdowns: bordered/shadowed\n * panel, an optional `header` slot (search box, plus any actions), and a\n * scrollable `<ul>` of `children` with an \"empty\" row when nothing matches.\n *\n * ## Anchored, or merely absolute\n *\n * Without `anchorRef` the panel is `position: absolute` inside whatever relative box\n * the caller put it in, and the caller places it with `className` (`w-64`,\n * `end-0 top-full`). That is fine in a page that does not scroll around it, and\n * wrong the moment an ancestor has `overflow` — the panel is then CLIPPED by that\n * ancestor's box, with no error and no scrollbar, just a list with its side sliced\n * off. Keksdose dev#548 is what that looks like in practice: the app's own content\n * scroller starts 280px from the left, the amount field's currency picker opens\n * right-aligned and 256px wide, and in the transaction row editor its left third —\n * the search box's first letter, and every row's currency symbol — was cut away.\n *\n * With `anchorRef` the panel is PORTALLED to `<body>` and positioned `fixed` against\n * that trigger's rect, so no ancestor can clip it: the same treatment {@link Popover}\n * already gives the calculator, and the same reason. It re-aligns on scroll and\n * resize, flips above the trigger when the room is there instead (a phone keyboard\n * eats the bottom of the screen), and is clamped to the viewport's edges so a trigger\n * near either side cannot push it off-screen.\n *\n * Pass `panelRef` from {@link useDropdown} along with it: once portalled the panel is\n * no longer inside the wrapper, so the outside-click handler has to be told about it\n * or the first click on an option closes the list instead of choosing from it.\n */\nexport function DropdownPanel({\n  header,\n  empty,\n  className,\n  listProps,\n  anchorRef,\n  panelRef,\n  width = 256,\n  align = \"end\",\n  children,\n  style,\n  onKeyDown,\n  ref,\n  ...rest\n}: DropdownPanelProps) {\n  const setPanel = useMemo(() => mergeRefs(panelRef, ref), [panelRef, ref]);\n  const anchored = useAnchoredPanel(anchorRef ?? EMPTY_REF, Boolean(anchorRef));\n  const dir = useAnchorDir(anchorRef ?? EMPTY_REF, Boolean(anchorRef));\n  // A row the keyboard reached by Tab holds focus too, and its Escape has to close the\n  // list as the search box's does (BUG-1). The caller's handler first, as everywhere.\n  const handleKeyDown = (e: ReactKeyboardEvent<HTMLDivElement>) => {\n    // It hears Escape only while the list is on top, a tooltip over a row taking the\n    // press first (round 0.35 R2) — the layer filed under `panelRef`, when handed one.\n    runOwnKeyDown(e, onKeyDown, panelRef && listLayers.get(panelRef));\n    takeEscape(e);\n  };\n  // A press in a panel opened from a row (a popover, its lists) is inside the list for\n  // `useDropdown`'s outside press, though portalled elsewhere (dev#623).\n  const markInside = pressInside(panelRef);\n  const handlePointerDownCapture = (e: ReactPointerEvent<HTMLDivElement>) => {\n    rest.onPointerDownCapture?.(e);\n    markInside?.(e);\n  };\n  const body = (\n    <>\n      {header}\n      {/* The anchored form caps its own height against the VISIBLE viewport and lets\n          this list have the rest; the absolute form keeps the fixed `max-h-64` it has\n          always had, applied by the wrapper below. */}\n      <ul {...listProps} className={cn(\"overflow-y-auto py-1\", listProps?.className)}>\n        {children}\n        {/* `presentation`, so that a caller who made this list a `listbox` does not\n            end up with one child that is not an option. The em dash still reads — it\n            is the row's semantics that are dropped, not its text. */}\n        {empty && (\n          <li role=\"presentation\" className=\"px-3 py-2 text-sm text-muted\">\n            —\n          </li>\n        )}\n      </ul>\n    </>\n  );\n\n  if (!anchorRef) {\n    return (\n      // eslint-disable-next-line jsx-a11y/no-static-element-interactions -- never focused itself: it catches Escape bubbling from the search box or a row inside it.\n      <div\n        {...rest}\n        style={style}\n        ref={setPanel}\n        onKeyDown={handleKeyDown}\n        onPointerDownCapture={handlePointerDownCapture}\n        className={cn(\n          \"absolute z-30 mt-1 rounded-md border border-subtle bg-surface shadow-lg\",\n          \"[&>ul]:max-h-64\",\n          className,\n        )}\n      >\n        {body}\n      </div>\n    );\n  }\n\n  const rect = anchored.rect;\n  if (!rect) return null;\n  // Clamped to the glass as `Popover` is (Wave 2, DUP-7): the panel may leave the\n  // trigger's edge to stay on screen, because a list half off the viewport is the bug\n  // this exists for. The portal leaves the subtree the trigger's `dir` came from, so it\n  // is read off the trigger — for the alignment here, and for the panel's own `dir`\n  // below, without which a right-to-left form got a left-to-right list.\n  const { left } = anchoredInline(rect, width, { dir, align });\n  return createPortal(\n    // eslint-disable-next-line jsx-a11y/no-static-element-interactions -- never focused itself: it catches Escape bubbling from the search box or a row inside it.\n    <div\n      {...rest}\n      ref={setPanel}\n      // A kit layer, for the tour's layer order (0.50, docs/tours-harmonization.md §11.6).\n      data-kit-layer=\"\"\n      dir={dir}\n      onKeyDown={handleKeyDown}\n      onPointerDownCapture={handlePointerDownCapture}\n      // The caller's `style` is kept underneath, but the placement is measured rather\n      // than chosen (dev#548: an `overflow` ancestor clipped a third of this panel\n      // away), so these values are the panel's own. Flipped above, it hangs from its\n      // bottom edge, so a list shorter than its cap still meets the trigger (keksdose\n      // K1); the edge not in use is cleared, a caller's included.\n      style={{\n        ...style,\n        position: \"fixed\",\n        top: anchored.above ? undefined : anchored.top,\n        bottom: anchored.above ? anchored.bottom : undefined,\n        left,\n        width,\n        maxHeight: anchored.maxHeight,\n      }}\n      className={cn(\n        \"z-50 flex flex-col overflow-hidden rounded-md border border-subtle bg-surface shadow-lg\",\n        // The list, not the panel, is what scrolls: the search header has to stay put\n        // while the options move under it.\n        \"[&>ul]:min-h-0 [&>ul]:flex-1\",\n        className,\n      )}\n    >\n      {body}\n    </div>,\n    document.body,\n  );\n}\n\n/** A ref that is always null, for the un-anchored form — hooks may not be conditional. */\nconst EMPTY_REF: RefObject<HTMLElement | null> = { current: null };\n"],"mappings":"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","names":[]}
+{"version":3,"sources":["../../src/components/dropdown.tsx"],"sourcesContent":["import { useCallback, useEffect, useMemo, useRef, useState } from \"react\";\nimport type {\n  ComponentPropsWithoutRef,\n  ComponentPropsWithRef,\n  KeyboardEvent as ReactKeyboardEvent,\n  PointerEvent as ReactPointerEvent,\n  ReactNode,\n  Ref,\n  RefObject,\n} from \"react\";\nimport { createPortal } from \"react-dom\";\nimport { Search } from \"lucide-react\";\nimport { anchoredInline, useAnchoredPanel } from \"../hooks/use-anchored-panel\";\nimport { pressInside, runOwnKeyDown, takeEscape, useDismissLayer, useOutsideClick } from \"../hooks/use-dismiss\";\nimport type { DismissLayer } from \"../hooks/use-dismiss\";\nimport { useOverlayHistory } from \"../hooks/use-overlay-history\";\nimport { cn } from \"../lib/cn\";\nimport { returnFocus } from \"../lib/focus-left\";\nimport { FIELD_TOUCH_TEXT } from \"./field-base\";\nimport { mergeRefs } from \"./field-parts\";\nimport { FOCUS_RING } from \"./focus-ring\";\nimport { useAnchorDir } from \"./use-anchor-dir\";\n\n/** Each list's Escape layer, filed under the refs {@link useDropdown} and\n *  {@link useDropdownSearch} hand out (`panelRef`, `inputRef`), for the panel and the\n *  search box those refs are passed to — see \"The caller's own handler\" on\n *  {@link useDropdown} (round 0.35 R2). Weak: a list's refs go with its component. */\nconst listLayers = new WeakMap<object, DismissLayer>();\n\n/**\n * Open state + close-on-outside-click for a custom dropdown — the two input-shaped\n * comboboxes, and an app's own panel. (MultiSelect, CurrencySelect, GroupedPicker and\n * AmountInput's currency picker moved onto `useComboboxCore` + `ComboboxPanel` in round\n * 0.34, Wave 2 DUP-4, for the phone sheet and the portal.) Attach `wrapperRef`\n * to the relatively-positioned container; the popover lives inside it so a click\n * anywhere else closes it.\n *\n * ## Back closes the list, not the page behind it\n *\n * Keksdose live #309 rework: *\"It shall only close it if it is prior open, and not\n * when I am seeing the dialog.\"* Round one wired {@link PickerSheet} — the shape\n * these lists take on a PHONE — into {@link useOverlayHistory}, and left the pointer\n * shape out. So on a desktop one Back press over an open list still went past it to\n * the dialog underneath: measured on his own budget, the transfer form's account list\n * was showing and Back took the entire add card, amount and all. That is the same\n * loss round one called *\"discarding an edit in progress in order to dismiss a\n * list\"*, in the other shell.\n *\n * Every dropdown built on this hook is dismissible and is the topmost thing on screen\n * while it is up, so the rule is the hook's rather than each caller's. `backCloses`\n * is for the ONE case where a second entry would be wrong: a caller whose panel is\n * itself a `PickerSheet`, which already registers one — both comboboxes swap shape at\n * the phone layout (`usePhoneLayout()`), and two entries would cost two Back presses to close one sheet.\n *\n * ## One outside-click rule for the whole package\n *\n * This hand-rolled a second document listener, on `mousedown`, months after\n * {@link useOutsideClick} — the hook the entity pickers dismiss through — was moved to\n * `pointerdown` for a reason that applies here word for word: on a touch platform\n * `mousedown` is SYNTHESISED, the browser emits it for most taps but is not obliged\n * to, and MultiSelect, CurrencySelect, GroupedPicker, AmountInput's currency picker\n * and both comboboxes all dismiss through this. Two copies of one rule is one copy\n * too many; this now delegates, so the package has a single answer to \"what is an\n * outside press\".\n *\n * `panelIsSheet` is what that delegation needs. A {@link PickerSheet} is modal and\n * fills the screen, so it has no outside — and being portalled to `<body>`, it is\n * inside neither `wrapperRef` nor `panelRef`, so a listener left running would read\n * every tap in it as a press outside and close it at finger-down. The sheet's own\n * `onMouseDown` stopPropagation guard used to hide that from this hook; it cannot\n * stop a `pointerdown`. It defaults to `!backCloses` because the two ask the same\n * question — \"is this caller's panel a sheet?\" — and the one caller that answers yes\n * already says so; they are separate props so a future caller can answer them apart.\n *\n * ## Escape, and where focus lands after it\n *\n * This hook had no Escape at all (the audit's §a11y): Back closed these lists, an\n * outside press closed them, and the one key every other dismissible surface in the\n * package answers to did nothing — so a keyboard user who opened a list had no way\n * out of it that did not also choose something. An open list is a layer on the kit's\n * one Escape stack ({@link useDismissLayer}), as `Modal`, `Popover` and\n * `useComboboxCore` are, so the package keeps one answer to \"what does Escape do\".\n *\n * Escape RESTORES FOCUS; an outside press does not. A press has already put focus\n * where the user pointed, and dragging it back from there would be the bug. Attach\n * `triggerRef` to the control that opens the panel and the keyboard paths — Escape,\n * Tab, a commit — hand focus back to it; leave it unattached and they hand it back to\n * whatever held focus when the list opened, which is the control that was pressed.\n *\n * ## Escape inside a dialog (round 0.34 BUG-1, Wave 2 DUP-1)\n *\n * One press in an open list inside a `Modal` or a `FullBleedDialog` used to close the\n * DIALOG, form and all, and leave the list open: the dialog took Escape in its own\n * `onKeyDown` before a document listener could. On the stack the list is above the\n * dialog, so the list closes and the dialog stays. {@link DropdownPanel} and\n * {@link DropdownSearchHeader} take the key on their own elements, where focus is,\n * and stop it there — so a caller passes nothing new, AmountInput's currency chip\n * included.\n *\n * ## The caller's own handler (round 0.35 R2)\n *\n * A caller's `onKeyDown` on {@link DropdownPanel} or {@link DropdownSearchHeader} hears\n * Escape only while this list is the layer on top — the rule the dialogs got first. A\n * tooltip over a row takes that press first, and the next one is the handler's, whose\n * `preventDefault()` still keeps the list. The two find the list's layer through the\n * refs this hook hands out — the panel through `panelRef`, the search box through\n * {@link useDropdownSearch}'s `inputRef` — so a caller passes nothing new. One handed\n * neither (an un-anchored panel may leave `panelRef` off) hears every key, as before.\n *\n * `escapeLayer: false` is for a caller that registers its own layer: the editable\n * comboboxes, whose list can be \"open\" with nothing in it to show — an Escape there\n * belongs to the dialog.\n */\nexport function useDropdown<T extends HTMLElement = HTMLDivElement>({\n  backCloses = true,\n  panelIsSheet = !backCloses,\n  escapeLayer = true,\n}: { backCloses?: boolean; panelIsSheet?: boolean; escapeLayer?: boolean } = {}) {\n  const [open, setOpen] = useState(false);\n  const wrapperRef = useRef<T>(null);\n  // The control that opens the panel — see the note above on why only the keyboard\n  // paths read it, and why attaching it is the caller's choice.\n  const triggerRef = useRef<HTMLButtonElement>(null);\n  // The panel, once it is PORTALLED (see {@link DropdownPanel}'s `anchorRef`): it is\n  // then a child of <body> rather than of the wrapper, so \"did the click land inside\n  // the wrapper\" answers no for every click on the list itself and the first option a\n  // user picked closed the dropdown without picking anything.\n  const panelRef = useRef<HTMLDivElement>(null);\n  // Where focus was as the list opened — the trigger focus goes back to when the\n  // caller attached none. Read in an effect, before `useDropdownSearch`'s frame moves\n  // focus into the search box.\n  // Dropped on close: a note of where to go must not outlive the list it was for (0.52\n  // code review 2026-10-31, held to 0.55).\n  const openerRef = useRef<HTMLElement | null>(null);\n  useEffect(() => {\n    if (!open) {\n      openerRef.current = null;\n      return;\n    }\n    const el = document.activeElement;\n    openerRef.current = el instanceof HTMLElement && el !== document.body ? el : null;\n  }, [open]);\n  const close = useCallback(() => setOpen(false), []);\n  // Closing unmounts whatever held focus — the search box, the row the keyboard was\n  // on — and the browser then drops focus on <body>: the caret vanishes and the next\n  // Tab restarts at the top of the document, and inside a dialog the next Escape goes\n  // nowhere. Whoever closed the list with a key gets focus handed back to the trigger\n  // they opened it from — by the kit's one rule (lib/focus-left `returnFocus`, 0.55):\n  // only from inside the list or from nowhere, so an Escape pressed with the focus in the\n  // page leaves it there, and to where the focus was as the list opened when the\n  // trigger cannot take it.\n  const closeToTrigger = useCallback(() => {\n    // The panel, or — not portalled, with no `panelRef` — the wrapper it sits in.\n    const closing = panelRef.current ?? wrapperRef.current;\n    returnFocus({ opener: triggerRef.current, fallback: [openerRef.current], closing });\n    setOpen(false);\n  }, []);\n  useOutsideClick([wrapperRef, panelRef], close, open && !panelIsSheet);\n  // See \"Escape inside a dialog\" above.\n  const layer = useDismissLayer(open && escapeLayer, closeToTrigger);\n  // Filed under `panelRef` for the panel's own handler — \"The caller's own handler\" above.\n  useEffect(() => {\n    listLayers.set(panelRef, layer);\n  }, [panelRef, layer]);\n  // Same close path Escape and an outside click take, so a list dismissed by Back\n  // cannot end up in a different state from one dismissed any other way.\n  useOverlayHistory(open && backCloses, close);\n  return { open, setOpen, wrapperRef, panelRef, triggerRef, closeToTrigger };\n}\n\n/**\n * {@link useDropdown} plus a search box: clears the query and focuses the search\n * input each time the panel opens, so typing filters immediately.\n */\nexport function useDropdownSearch<T extends HTMLElement = HTMLDivElement>() {\n  const { open, setOpen, wrapperRef, panelRef, triggerRef, closeToTrigger } = useDropdown<T>();\n  const [query, setQuery] = useState(\"\");\n  const inputRef = useRef<HTMLInputElement>(null);\n  // The list's layer again, under `inputRef` for the search box's handler (round 0.35\n  // R2). `useDropdown`'s effect, which runs first, has filed it under `panelRef`.\n  useEffect(() => {\n    const layer = listLayers.get(panelRef);\n    if (layer) listLayers.set(inputRef, layer);\n  }, [panelRef]);\n  useEffect(() => {\n    if (open) {\n      // eslint-disable-next-line react-hooks/set-state-in-effect -- reset the query on open\n      setQuery(\"\");\n      requestAnimationFrame(() => inputRef.current?.focus());\n    }\n  }, [open]);\n  return {\n    open,\n    setOpen,\n    wrapperRef,\n    panelRef,\n    triggerRef,\n    closeToTrigger,\n    query,\n    setQuery,\n    inputRef,\n  };\n}\n\n/** `onKeyDown` is the INPUT's, not the wrapper's — the list's keyboard is handled\n *  where the focus is (see the note above), so the div's own handler signature is\n *  omitted in favour of it. */\nexport interface DropdownSearchHeaderProps extends Omit<ComponentPropsWithRef<\"div\">, \"onKeyDown\"> {\n  query: string;\n  onQueryChange: (v: string) => void;\n  inputRef: RefObject<HTMLInputElement | null>;\n  placeholder?: string;\n  /** The `<ul role=\"listbox\">` this box filters. */\n  listboxId?: string;\n  /** The id of the option the arrow keys are currently on, if any. */\n  activeId?: string;\n  /** Arrow/Home/End/Enter/Tab — the list's keyboard, handled where the focus is.\n   *  Escape closes the list (the topmost layer on the kit's Escape stack); call\n   *  `preventDefault()` on it here to keep it. */\n  onKeyDown?: (e: ReactKeyboardEvent<HTMLInputElement>) => void;\n}\n\n/** The search row (magnifier + text input) shared by the searchable dropdowns.\n *\n *  The input had `outline-none` and nothing in its place (the audit's §a11y, the same\n *  finding as the numpad's keys). That mattered more here than the bare class suggests:\n *  {@link useDropdownSearch} focuses this box the moment a panel opens, so the caret is\n *  the ONLY evidence of where the next keystroke goes — and a caret in an empty field\n *  showing a placeholder is a single blinking pixel column. The ring is what says \"this\n *  list is being typed into\"; it appears whenever the field holds focus, which for a\n *  text input is exactly when it is true.\n *\n *  ## Why this box is a plain textbox and the TRIGGER is the combobox\n *\n *  The panels this header sits in are opened by a field-shaped trigger, and that\n *  trigger is what carries `role=\"combobox\"` (see {@link MultiSelect},\n *  {@link EntityCombobox}). Two comboboxes for one list would be one too many — a\n *  reader tabbing back to the field would meet a second one describing the same\n *  choice. So this stays a textbox, which ARIA lets own `aria-activedescendant` and\n *  `aria-controls` exactly as a combobox does: focus is HERE while the list is up, so\n *  this is what has to say which option the arrow keys are on.\n *\n *  Pass `listboxId` and the wiring appears; omit it and the box is what it always\n *  was, for the callers that have no listbox to point at. */\nexport function DropdownSearchHeader({\n  query,\n  onQueryChange,\n  inputRef,\n  placeholder,\n  listboxId,\n  activeId,\n  onKeyDown,\n  \"aria-label\": ariaLabel,\n  className,\n  ...rest\n}: DropdownSearchHeaderProps) {\n  return (\n    // `rest` dresses the header row; the NAME goes on the box below it. A search\n    // input whose only name is its placeholder has none the moment a character is\n    // typed into it — the placeholder disappears — which is why this is worth a prop\n    // at all rather than something a caller could add from outside.\n    <div {...rest} className={cn(\"flex items-center gap-2 border-b border-subtle px-2 py-1.5\", className)}>\n      <Search className=\"size-4 text-placeholder\" />\n      <input\n        ref={inputRef}\n        type=\"text\"\n        value={query}\n        onChange={(e) => onQueryChange(e.target.value)}\n        onKeyDown={(e) => {\n          // The caller's handler hears Escape only while the list is on top (round 0.35\n          // R2) — the layer filed under `inputRef`, when {@link useDropdownSearch} made it.\n          runOwnKeyDown(e, onKeyDown, listLayers.get(inputRef));\n          // Focus is in this box while the list is up, so this is where Escape lands\n          // first — see \"Escape inside a dialog\" on {@link useDropdown}.\n          takeEscape(e);\n        }}\n        placeholder={placeholder}\n        aria-label={ariaLabel}\n        aria-controls={listboxId}\n        aria-activedescendant={activeId}\n        aria-autocomplete={listboxId ? \"list\" : undefined}\n        // FIELD_TOUCH_TEXT: a search box is a field — at least 16 px on touch, or iOS zooms\n        // the page the moment a picker opens and focuses it (§10.1).\n        className={cn(\n          \"w-full rounded-sm bg-transparent text-sm outline-none placeholder:text-placeholder text-primary\",\n          FOCUS_RING,\n          FIELD_TOUCH_TEXT,\n        )}\n      />\n    </div>\n  );\n}\n\nexport interface DropdownPanelProps extends ComponentPropsWithoutRef<\"div\"> {\n  header?: ReactNode;\n  empty?: boolean;\n  /** Attributes for the `<ul>` itself — how a caller whose children are options\n   *  gives the list its `role=\"listbox\"`, its id and `aria-multiselectable`. The\n   *  panel owns the scrolling and the padding, so `className` here is merged rather\n   *  than replaced. */\n  listProps?: ComponentPropsWithoutRef<\"ul\">;\n  /** The trigger to hang off. Given, the panel portals and goes `fixed`. */\n  anchorRef?: RefObject<HTMLElement | null>;\n  /** {@link useDropdown}'s `panelRef`, so an outside-click sees this as inside. Escape\n   *  anywhere in the panel, on a row as in the search box, closes the list rather than\n   *  a dialog around it. It is also how the panel finds the list's Escape layer, for\n   *  its `onKeyDown` (round 0.35 R2: see \"The caller's own handler\" there). */\n  panelRef?: RefObject<HTMLDivElement | null>;\n  /** Panel width in px, for the anchored form (the CSS `w-*` cannot be measured). */\n  width?: number;\n  /** Which of the panel's edges lines up with the trigger's, room permitting, by the\n   *  trigger's reading direction — `end` is the right edge in a left-to-right form and\n   *  the left one in a right-to-left form. Default `end`. The physical `left` / `right`\n   *  went in 0.35 (round 0.35 R1, refactor audit 2026-10, API-6e): `right` is `end` in a\n   *  left-to-right page, `left` is `start`. */\n  align?: \"start\" | \"end\";\n  children: ReactNode;\n  /** The panel, where the rest of the props go (0.34, API-2, refactor audit 2026-10) —\n   *  merged with `panelRef`, so the outside-click still sees it. */\n  ref?: Ref<HTMLDivElement>;\n}\n\n/**\n * The floating popover surface for the searchable dropdowns: bordered/shadowed\n * panel, an optional `header` slot (search box, plus any actions), and a\n * scrollable `<ul>` of `children` with an \"empty\" row when nothing matches.\n *\n * ## Anchored, or merely absolute\n *\n * Without `anchorRef` the panel is `position: absolute` inside whatever relative box\n * the caller put it in, and the caller places it with `className` (`w-64`,\n * `end-0 top-full`). That is fine in a page that does not scroll around it, and\n * wrong the moment an ancestor has `overflow` — the panel is then CLIPPED by that\n * ancestor's box, with no error and no scrollbar, just a list with its side sliced\n * off. Keksdose dev#548 is what that looks like in practice: the app's own content\n * scroller starts 280px from the left, the amount field's currency picker opens\n * right-aligned and 256px wide, and in the transaction row editor its left third —\n * the search box's first letter, and every row's currency symbol — was cut away.\n *\n * With `anchorRef` the panel is PORTALLED to `<body>` and positioned `fixed` against\n * that trigger's rect, so no ancestor can clip it: the same treatment {@link Popover}\n * already gives the calculator, and the same reason. It re-aligns on scroll and\n * resize, flips above the trigger when the room is there instead (a phone keyboard\n * eats the bottom of the screen), and is clamped to the viewport's edges so a trigger\n * near either side cannot push it off-screen.\n *\n * Pass `panelRef` from {@link useDropdown} along with it: once portalled the panel is\n * no longer inside the wrapper, so the outside-click handler has to be told about it\n * or the first click on an option closes the list instead of choosing from it.\n */\nexport function DropdownPanel({\n  header,\n  empty,\n  className,\n  listProps,\n  anchorRef,\n  panelRef,\n  width = 256,\n  align = \"end\",\n  children,\n  style,\n  onKeyDown,\n  ref,\n  ...rest\n}: DropdownPanelProps) {\n  const setPanel = useMemo(() => mergeRefs(panelRef, ref), [panelRef, ref]);\n  const anchored = useAnchoredPanel(anchorRef ?? EMPTY_REF, Boolean(anchorRef));\n  const dir = useAnchorDir(anchorRef ?? EMPTY_REF, Boolean(anchorRef));\n  // A row the keyboard reached by Tab holds focus too, and its Escape has to close the\n  // list as the search box's does (BUG-1). The caller's handler first, as everywhere.\n  const handleKeyDown = (e: ReactKeyboardEvent<HTMLDivElement>) => {\n    // It hears Escape only while the list is on top, a tooltip over a row taking the\n    // press first (round 0.35 R2) — the layer filed under `panelRef`, when handed one.\n    runOwnKeyDown(e, onKeyDown, panelRef && listLayers.get(panelRef));\n    takeEscape(e);\n  };\n  // A press in a panel opened from a row (a popover, its lists) is inside the list for\n  // `useDropdown`'s outside press, though portalled elsewhere (dev#623).\n  const markInside = pressInside(panelRef);\n  const handlePointerDownCapture = (e: ReactPointerEvent<HTMLDivElement>) => {\n    rest.onPointerDownCapture?.(e);\n    markInside?.(e);\n  };\n  const body = (\n    <>\n      {header}\n      {/* The anchored form caps its own height against the VISIBLE viewport and lets\n          this list have the rest; the absolute form keeps the fixed `max-h-64` it has\n          always had, applied by the wrapper below. */}\n      <ul {...listProps} className={cn(\"overflow-y-auto py-1\", listProps?.className)}>\n        {children}\n        {/* `presentation`, so that a caller who made this list a `listbox` does not\n            end up with one child that is not an option. The em dash still reads — it\n            is the row's semantics that are dropped, not its text. */}\n        {empty && (\n          <li role=\"presentation\" className=\"px-3 py-2 text-sm text-muted\">\n            —\n          </li>\n        )}\n      </ul>\n    </>\n  );\n\n  if (!anchorRef) {\n    return (\n      // eslint-disable-next-line jsx-a11y/no-static-element-interactions -- never focused itself: it catches Escape bubbling from the search box or a row inside it.\n      <div\n        {...rest}\n        style={style}\n        ref={setPanel}\n        onKeyDown={handleKeyDown}\n        onPointerDownCapture={handlePointerDownCapture}\n        className={cn(\n          \"absolute z-30 mt-1 rounded-md border border-subtle bg-surface shadow-lg\",\n          \"[&>ul]:max-h-64\",\n          className,\n        )}\n      >\n        {body}\n      </div>\n    );\n  }\n\n  const rect = anchored.rect;\n  if (!rect) return null;\n  // Clamped to the glass as `Popover` is (Wave 2, DUP-7): the panel may leave the\n  // trigger's edge to stay on screen, because a list half off the viewport is the bug\n  // this exists for. The portal leaves the subtree the trigger's `dir` came from, so it\n  // is read off the trigger — for the alignment here, and for the panel's own `dir`\n  // below, without which a right-to-left form got a left-to-right list.\n  const { left } = anchoredInline(rect, width, { dir, align });\n  return createPortal(\n    // eslint-disable-next-line jsx-a11y/no-static-element-interactions -- never focused itself: it catches Escape bubbling from the search box or a row inside it.\n    <div\n      {...rest}\n      ref={setPanel}\n      // A kit layer, for the tour's layer order (0.50, docs/tours-harmonization.md §11.6).\n      data-kit-layer=\"\"\n      dir={dir}\n      onKeyDown={handleKeyDown}\n      onPointerDownCapture={handlePointerDownCapture}\n      // The caller's `style` is kept underneath, but the placement is measured rather\n      // than chosen (dev#548: an `overflow` ancestor clipped a third of this panel\n      // away), so these values are the panel's own. Flipped above, it hangs from its\n      // bottom edge, so a list shorter than its cap still meets the trigger (keksdose\n      // K1); the edge not in use is cleared, a caller's included.\n      style={{\n        ...style,\n        position: \"fixed\",\n        top: anchored.above ? undefined : anchored.top,\n        bottom: anchored.above ? anchored.bottom : undefined,\n        left,\n        width,\n        maxHeight: anchored.maxHeight,\n      }}\n      className={cn(\n        \"z-50 flex flex-col overflow-hidden rounded-md border border-subtle bg-surface shadow-lg\",\n        // The list, not the panel, is what scrolls: the search header has to stay put\n        // while the options move under it.\n        \"[&>ul]:min-h-0 [&>ul]:flex-1\",\n        className,\n      )}\n    >\n      {body}\n    </div>,\n    document.body,\n  );\n}\n\n/** A ref that is always null, for the un-anchored form — hooks may not be conditional. */\nconst EMPTY_REF: RefObject<HTMLElement | null> = { current: null };\n"],"mappings":"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","names":[]}

package/dist/components/entity-combobox.js

@@ -17,7 +17,7 @@ import {
   EndHintRow,
   FieldCaption,
   LABEL_IN_ROW,
-  LockedReason,
+  LockFrame,
   mergeDescribedBy,
   StaticLabelRow,
   useFieldError,
@@ -113,7 +113,7 @@ function EntityCombobox(props) {
   );
   const showClear = Boolean(clearable && chosen != null && !inert);
   const triggerText = selectedOption?.label ?? placeholder ?? "";
-  const withLock = (trigger) => lock.locked ? /* @__PURE__ */ jsx(LockedReason, { lock, display: disabledReasonDisplay, className: "block", children: trigger }) : trigger;
+  const withLock = (trigger) => /* @__PURE__ */ jsx(LockFrame, { lock, display: disabledReasonDisplay, children: trigger });
   const choose = (o) => {
     if (lock.locked) return;
     rememberOption(o);

package/dist/components/entity-combobox.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/components/entity-combobox.tsx"],"sourcesContent":["import { useCallback, useId } from \"react\";\nimport type { ComponentPropsWithoutRef, ReactNode, Ref } from \"react\";\nimport { X } from \"lucide-react\";\nimport { cn } from \"../lib/cn\";\nimport { FieldChevron, FIELD_TRIGGER, FIELD_FLOATING_PAD, FIELD_INVALID } from \"./field-base\";\nimport { FieldLabel } from \"./field-parts\";\nimport {\n  ComboboxPanel,\n  endHintRowProps,\n  offersCreate,\n  useComboboxCore,\n  type ComboClearValue,\n  type ComboOption,\n} from \"./combobox-core\";\nimport { DEFAULT_COMBOBOX_LABELS, DEFAULT_COMMON_LABELS, useKitLabels, useKitLocale } from \"../i18n/kit-labels\";\nimport {\n  assignRef,\n  EndHintRow,\n  FieldCaption,\n  LABEL_IN_ROW,\n  LockedReason,\n  mergeDescribedBy,\n  StaticLabelRow,\n  useFieldError,\n  useFieldHint,\n  useLockReason,\n  type DisabledReasonDisplay,\n  type FieldHelpProps,\n} from \"./field-parts\";\nimport { useCommitReason, type CommitScope } from \"./write-lock\";\n\nexport type { ComboClearValue, ComboOption } from \"./combobox-core\";\n\n/** `onChange` is the kit's — \"a selection was made\", carrying values — rather\n *  than the div's form event, so the DOM's spelling of it is omitted. */\nexport interface EntityComboboxProps<V extends string | number, C extends ComboClearValue = null>\n  extends Omit<ComponentPropsWithoutRef<\"div\">, \"onChange\">, FieldHelpProps {\n  /** Selected id; `null`, `undefined` or `clearValue` when nothing is selected. */\n  value: V | C | null | undefined;\n  /** Selecting an option emits its value; the clear button emits `clearValue`. */\n  onChange: (value: V | C) => void;\n  /**\n   * What the clear button emits. Default `null`. Pass `\"\"` for a form whose schema\n   * wants an empty string for \"no choice\" (a zod `z.string()` field), rather than\n   * mapping `null` in every `onChange` — the type of `onChange` follows it, so the\n   * mapping cannot be forgotten on one field and not another. The picker also reads\n   * the value back as empty, so `value=\"\"` shows the placeholder and no \"×\".\n   * See {@link ComboClearValue} for why the choice is closed.\n   */\n  clearValue?: C;\n  /** Already-loaded options (client-side filtered). Also used to resolve the\n   *  trigger label for the current `value`. */\n  options?: ComboOption<V>[];\n  /** Async option source, debounced and called on open + as the query changes\n   *  (at `minChars` and up). Stale responses are ignored; a rejection empties the\n   *  list and says `loadErrorLabel` instead of leaving the last query's rows up. When set, `options` is used only for label\n   *  resolution, not as the result list. */\n  loadOptions?: (query: string) => Promise<ComboOption<V>[]>;\n  /** External loading flag (OR-ed with the internal async state). */\n  loading?: boolean;\n  label?: ReactNode;\n  placeholder?: string;\n  searchPlaceholder?: string;\n  emptyLabel?: string;\n  /** Offer a clear \"×\" in place of the chevron while something is chosen; it emits\n   *  `clearValue`. A pointer shortcut inside the trigger, out of the tab order — the\n   *  keyboard's way is Delete or Backspace on the CLOSED trigger (0.23, as\n   *  {@link CountrySelect}). Not offered while `disabled` or locked. */\n  clearable?: boolean;\n  clearLabel?: string;\n  /** The phone sheet's close button. Its own prop rather than a reuse of\n   *  `clearLabel`: \"clear the selection\" and \"close this screen\" are different\n   *  actions, and on a full-screen sheet the close button is the only way out —\n   *  so it is the one control here that MUST be in the reader's language. */\n  closeLabel?: string;\n  /** The phone sheet's heading (and, as a string, its accessible name) for a picker\n   *  whose label is drawn by someone else — a bound field's label; `RhfCombobox`\n   *  hands its label over here (0.24). Default: `label`, then `placeholder`. */\n  sheetTitle?: ReactNode;\n  disabled?: boolean;\n  /**\n   * Why the choice cannot be changed — {@link Button}'s `disabledReason`, for a picker\n   * that SAVES on change (keksdose G2: the statement's account, where picking IS the\n   * write). The trigger stays focusable and `aria-disabled`, the list does not open,\n   * the clear \"×\" is gone and `onChange` never fires; the reason is in the kit\n   * {@link Tooltip} and on the trigger's `aria-describedby`. Wins over `disabled`.\n   * {@link CountrySelect}'s lock, which is built on the same core.\n   */\n  disabledReason?: ReactNode;\n  /**\n   * This picker COMMITS — choosing saves. Under a locked {@link WriteLockProvider} it is\n   * locked the `disabledReason` way with the lock's reason (which wins over its own).\n   * A picker inside a form with its own Save stays editable under the lock: leave this\n   * off there and put `commit` on the Save. No provider, or an unlocked one: no effect.\n   */\n  commit?: CommitScope;\n  /** Where the reason shows — {@link Button}'s `disabledReasonDisplay`: a line under the\n   *  field at Large and on a touch screen by default, the tooltip otherwise (DUP-3). */\n  disabledReasonDisplay?: DisabledReasonDisplay;\n  /** When set, a \"create\" row appears for a non-empty query with no exact match. */\n  onCreate?: (query: string) => void;\n  createLabel?: (query: string) => string;\n  /**\n   * Offer the create row with NOTHING typed too, worded as this — keksdose G9's\n   * \"Create cash account\", which mints a record under a default name and so needs no\n   * query. `onCreate` then receives `\"\"`. Left out, the row needs a query, as before.\n   * See {@link InlineEntityCombobox}'s `createEmptyLabel`.\n   */\n  createEmptyLabel?: string;\n  /**\n   * The create row WRITES (it mints the record on the server) while picking does not.\n   * Under a locked {@link WriteLockProvider} the row stays in the list but cannot be\n   * taken, with the lock's reason as its second line — the picker itself stays live.\n   * keksdose dev#496: on the read-only demo choosing is draft state, minting is not.\n   */\n  createCommit?: CommitScope;\n  /** Required and unanswered — {@link FIELD_INVALID}. See {@link Input}'s `invalid`. */\n  invalid?: boolean;\n  /** What is wrong with the value, as {@link Input}'s `error`: rendered under the\n   *  field, on the trigger's `aria-describedby`, and implies `invalid`. */\n  error?: ReactNode;\n  /**\n   * Standing advice — {@link Combobox}'s `hint`, so the pickers read like every other\n   * field (keksdose K4): plain TEXT is a caption under the field on the trigger's\n   * `aria-describedby`, before any error; a {@link FieldHint} \"?\" rides the label line,\n   * or with no label sits at the trigger's end edge, outside the box.\n   */\n  hint?: ReactNode;\n  /** Narrow `options` client-side by the query. Default `true`; `false` shows them\n   *  as given (a server-ranked list). */\n  filter?: boolean;\n  /** Offer nothing, and call no `loadOptions`, below this many characters. Default\n   *  `0`, i.e. the list loads as the panel opens. */\n  minChars?: number;\n  /** `loadOptions` debounce. Default 150 ms. */\n  debounceMs?: number;\n  /** Shown when `loadOptions` rejects. Default: `combobox.loadError`. */\n  loadErrorLabel?: string;\n  /**\n   * The TRIGGER — the focusable `<button>` a reader meets — as a React 19 ref prop, as\n   * on {@link CountrySelect}, which is built on the same core (0.24, kastlan: react-hook-\n   * form's focus-on-error calls `focus()` on whatever `field.ref` is handed, and a\n   * picker with no ref gave it nothing to focus). Not the wrapper: focus belongs on the\n   * trigger, which is also where the panel hands it back after a pick.\n   */\n  ref?: Ref<HTMLButtonElement>;\n}\n\n/**\n * An id-keyed, searchable entity picker: a field-styled trigger showing the\n * selected item's label, and a portalled dropdown of `{label, sublabel, icon}`\n * options — loaded up front via `options` or lazily via `loadOptions`. Built on\n * the shared field/anchor/dismiss/search primitives (no cmdk/Radix). For picking\n * several entities use {@link MultiEntityCombobox}.\n */\nexport function EntityCombobox<V extends string | number, C extends ComboClearValue = null>(\n  props: EntityComboboxProps<V, C>,\n) {\n  const {\n    value,\n    onChange,\n    clearValue = null as C,\n    options,\n    loadOptions,\n    loading,\n    label,\n    placeholder,\n    searchPlaceholder,\n    emptyLabel,\n    clearable,\n    clearLabel,\n    closeLabel,\n    sheetTitle,\n    disabled,\n    disabledReason,\n    disabledReasonDisplay,\n    commit,\n    onCreate,\n    createLabel,\n    createEmptyLabel,\n    createCommit,\n    className,\n    invalid,\n    error,\n    hint,\n    help,\n    filter,\n    minChars,\n    debounceMs,\n    loadErrorLabel,\n    ref,\n    \"aria-label\": ariaLabel,\n    // The control's own wiring, taken off `rest` so it lands on the TRIGGER rather than\n    // the wrapper — see MultiEntityCombobox: `Field`'s render-prop spreads `{ id,\n    // aria-describedby, aria-invalid, aria-required }`, and on the role-less wrapper\n    // div the label's `htmlFor` named nothing and the hint described nothing.\n    id,\n    \"aria-describedby\": ariaDescribedBy,\n    \"aria-invalid\": ariaInvalid,\n    \"aria-required\": ariaRequired,\n    ...rest\n  } = props;\n  const core = useComboboxCore<V>({\n    options,\n    loadOptions,\n    loading,\n    filter,\n    minChars,\n    debounceMs,\n  });\n  const hintParts = useFieldHint(hint, ariaDescribedBy, { help, name: label ?? ariaLabel });\n  const field = useFieldError(error, invalid, hintParts.describedBy, ariaInvalid);\n  // The props are the per-instance overrides, the provider the app-wide ones; a\n  // prop left `undefined` falls through to the provider rather than masking it.\n  const labels = useKitLabels(\"combobox\", DEFAULT_COMBOBOX_LABELS, {\n    search: searchPlaceholder,\n    noResults: emptyLabel,\n    clear: clearLabel,\n    create: createLabel,\n  });\n  const common = useKitLabels(\"common\", DEFAULT_COMMON_LABELS);\n  const { open, results, resolve, setOpen, rememberOption, query, triggerRef } = 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 — CountrySelect's.\n  const setTrigger = useCallback(\n    (el: HTMLButtonElement | null) => {\n      triggerRef.current = el;\n      assignRef(ref, el);\n    },\n    [ref, triggerRef],\n  );\n  // The lock: this picker's own reason, or the provider's under `commit`.\n  const lock = useLockReason(commit, disabledReason);\n  const inert = lock.locked || Boolean(disabled);\n  // A lock arriving while the list is up closes it — adjusted while\n  // rendering, as the core adjusts its own query, so no frame offers a pick that would\n  // be thrown away.\n  if (lock.locked && open) setOpen(false);\n  // The create row's own lock, for a picker whose choosing is draft and whose create\n  // is the write (`createCommit`).\n  const createReason = useCommitReason(createCommit, undefined);\n  // One id per instance, generated here rather than in the core: `aria-controls` on\n  // the trigger has to name the list while the list is still closed, so the id\n  // belongs to whoever renders both ends of it.\n  const listboxId = useId();\n\n  // The clear value is \"nothing selected\" too, whichever one the caller picked.\n  const chosen: V | null = value == null || value === clearValue ? null : (value as V);\n  const selectedOption = chosen == null ? null : resolve(chosen);\n  const q = query.trim();\n  // The create row's \"is this name already listed\" folds as the list's match does (DUP-5).\n  const locale = useKitLocale();\n  const showCreate = offersCreate(\n    onCreate,\n    q,\n    results.map((o) => o.label),\n    createEmptyLabel,\n    locale,\n  );\n  const showClear = Boolean(clearable && chosen != null && !inert);\n  /** What the closed control is showing — the second half of its accessible name. */\n  const triggerText = selectedOption?.label ?? placeholder ?? \"\";\n  // While locked the trigger sits in the reason's Tooltip — in a fragment with a hidden\n  // copy of the reason, Button's anatomy — `block` so a full-width field stays full width.\n  const withLock = (trigger: ReactNode) =>\n    lock.locked ? (\n      <LockedReason lock={lock} display={disabledReasonDisplay} className=\"block\">\n        {trigger}\n      </LockedReason>\n    ) : (\n      trigger\n    );\n\n  const choose = (o: ComboOption<V>) => {\n    if (lock.locked) return;\n    rememberOption(o);\n    onChange(o.value);\n    // Back to the trigger, not to <body>: the panel that held focus is about to\n    // unmount, and a keyboard user who just answered this field should be standing\n    // on it, ready to Tab to the next one.\n    core.closeToTrigger();\n  };\n\n  return (\n    // `rest` dresses the wrapper, which has no role; the accessible NAME — and the\n    // id, description, invalid and required state above — go on the trigger, which\n    // has one. Spread FIRST so the trigger's ARIA and the\n    // handlers that open the panel cannot be clobbered from outside.\n    <div {...rest} className={cn(\"relative\", className)}>\n      {label !== undefined && hintParts.labelHint === undefined && <FieldLabel>{label}</FieldLabel>}\n      <EndHintRow {...endHintRowProps(\"hint\" in props, label !== undefined, hintParts.labelHint)}>\n        {withLock(\n          <button\n            ref={setTrigger}\n            id={id}\n            type=\"button\"\n            // A combobox, not a button. The distinction is not pedantry: this control\n            // carried `aria-invalid`, which `button` does not support, so a required\n            // field left empty painted a rose border and told a reader nothing at all —\n            // and ESLint flagged it as exactly that (`role-supports-aria-props`). The\n            // fix the audit asked for is the role that describes what this IS: a closed\n            // choice that expands into the list named below. `combobox` supports\n            // `aria-invalid`, so the border and the announcement finally agree.\n            role=\"combobox\"\n            aria-expanded={open}\n            aria-controls={listboxId}\n            aria-haspopup=\"listbox\"\n            // The label is a floating <span>, not a <label for>, so without this the\n            // trigger's accessible name is whatever value happens to be selected —\n            // \"Checking\" with nothing saying it is the account. The label AND the\n            // value, because `aria-label` replaces the content rather than adding to\n            // it, and a control that announces only its name has lost the answer.\n            // A caller's own name wins over the composition: two fields labelled\n            // \"Account\" on a transfer form are the from and the to, and only the\n            // caller knows which is which.\n            aria-label={ariaLabel ?? (typeof label === \"string\" ? common.fieldValue(label, triggerText) : undefined)}\n            // The focusable kind of disabled while locked (Button's rule): a native\n            // `disabled` would take the field out of the tab order, and the reason with it.\n            disabled={lock.locked ? undefined : disabled}\n            aria-disabled={lock.locked || undefined}\n            aria-invalid={field.isInvalid || undefined}\n            aria-describedby={mergeDescribedBy(field.describedBy, lock.locked && lock.reasonId)}\n            aria-required={ariaRequired}\n            onClick={() => !inert && setOpen((o) => !o)}\n            // Down/Up opens the list from the closed trigger, per the APG. Enter and\n            // Space already do it through the button's own click.\n            onKeyDown={(e) => {\n              if (inert) return;\n              if (e.key === \"ArrowDown\" || e.key === \"ArrowUp\") {\n                e.preventDefault();\n                setOpen(true);\n              } else if (showClear && !open && (e.key === \"Delete\" || e.key === \"Backspace\")) {\n                // The keyboard's clear: the \"×\" is a pointer shortcut out of the tab\n                // order, so without this a cleared-by-mouse field was set-only from the\n                // keyboard. The closed trigger only — CountrySelect's rule (0.23).\n                e.preventDefault();\n                onChange(clearValue);\n              }\n            }}\n            className={cn(\n              FIELD_TRIGGER,\n              \"pe-9\",\n              label !== undefined && FIELD_FLOATING_PAD,\n              inert && \"cursor-not-allowed opacity-50\",\n              field.isInvalid && FIELD_INVALID,\n            )}\n          >\n            <span className=\"flex min-w-0 items-center gap-2\">\n              {selectedOption?.icon && <span className=\"shrink-0\">{selectedOption.icon}</span>}\n              <span\n                className={cn(\n                  // One line at Normal; from Large up the value wraps and the trigger\n                  // grows, as DatePicker's does (text size §10.17, round 0.34 T1).\n                  \"truncate-until-large\",\n                  // A chosen value is the field's VALUE, so it is set in the same ink an\n                  // <input>'s value is — FIELD_BASE's own text colour, inherited rather\n                  // than restated (Keksdose dev#477). It used to be one notch lighter\n                  // than the typeahead fields beside it, which is visible when a picker\n                  // and a text field share a form row. Nothing selected keeps the\n                  // placeholder tone (`--text-placeholder`), which every field here\n                  // agrees on.\n                  !selectedOption && \"text-placeholder\",\n                )}\n              >\n                {selectedOption?.label ?? placeholder ?? \"\"}\n              </span>\n            </span>\n            {showClear ? (\n              /* eslint-disable-next-line jsx-a11y/click-events-have-key-events -- tabIndex -1 inside\n                  the trigger <button>, so it never holds focus and a key handler here could\n                  never fire; the keys go to the trigger, where Delete and Backspace clear. */\n              <span\n                role=\"button\"\n                tabIndex={-1}\n                aria-label={labels.clear}\n                onClick={(e) => {\n                  e.stopPropagation();\n                  onChange(clearValue);\n                }}\n                className=\"absolute end-2 top-1/2 -translate-y-1/2 rounded p-0.5 text-placeholder hover:text-secondary\"\n              >\n                <X className=\"size-4\" />\n              </span>\n            ) : (\n              <FieldChevron />\n            )}\n          </button>,\n        )}\n      </EndHintRow>\n      {/* With a \"?\" the label shares the top strip with it — after the trigger, so the\n          \"?\" follows the control in the tab order, as on Input and Select. */}\n      {label !== undefined && hintParts.labelHint !== undefined && (\n        <StaticLabelRow hint={hintParts.labelHint}>\n          <FieldLabel className={LABEL_IN_ROW}>{label}</FieldLabel>\n        </StaticLabelRow>\n      )}\n      <ComboboxPanel\n        core={core}\n        listboxId={listboxId}\n        // On a phone the panel becomes a full-screen sheet, which needs the field's\n        // own label to say what it is asking for (live #200).\n        sheetTitle={sheetTitle ?? label ?? placeholder}\n        searchPlaceholder={labels.search}\n        emptyLabel={labels.noResults}\n        closeLabel={closeLabel}\n        loadErrorLabel={loadErrorLabel}\n        isSelected={(v) => v === value}\n        onChoose={choose}\n        showCreate={showCreate}\n        onCreate={() => {\n          if (lock.locked) return;\n          onCreate?.(q);\n          core.closeToTrigger();\n        }}\n        createContent={q ? labels.create(q) : createEmptyLabel}\n        createDisabledReason={createReason}\n      />\n      <FieldCaption parts={hintParts} />\n      {field.errorEl}\n    </div>\n  );\n}\n"],"mappings":"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","names":[]}
+{"version":3,"sources":["../../src/components/entity-combobox.tsx"],"sourcesContent":["import { useCallback, useId } from \"react\";\nimport type { ComponentPropsWithoutRef, ReactNode, Ref } from \"react\";\nimport { X } from \"lucide-react\";\nimport { cn } from \"../lib/cn\";\nimport { FieldChevron, FIELD_TRIGGER, FIELD_FLOATING_PAD, FIELD_INVALID } from \"./field-base\";\nimport { FieldLabel } from \"./field-parts\";\nimport {\n  ComboboxPanel,\n  endHintRowProps,\n  offersCreate,\n  useComboboxCore,\n  type ComboClearValue,\n  type ComboOption,\n} from \"./combobox-core\";\nimport { DEFAULT_COMBOBOX_LABELS, DEFAULT_COMMON_LABELS, useKitLabels, useKitLocale } from \"../i18n/kit-labels\";\nimport {\n  assignRef,\n  EndHintRow,\n  FieldCaption,\n  LABEL_IN_ROW,\n  LockFrame,\n  mergeDescribedBy,\n  StaticLabelRow,\n  useFieldError,\n  useFieldHint,\n  useLockReason,\n  type DisabledReasonDisplay,\n  type FieldHelpProps,\n} from \"./field-parts\";\nimport { useCommitReason, type CommitScope } from \"./write-lock\";\n\nexport type { ComboClearValue, ComboOption } from \"./combobox-core\";\n\n/** `onChange` is the kit's — \"a selection was made\", carrying values — rather\n *  than the div's form event, so the DOM's spelling of it is omitted. */\nexport interface EntityComboboxProps<V extends string | number, C extends ComboClearValue = null>\n  extends Omit<ComponentPropsWithoutRef<\"div\">, \"onChange\">, FieldHelpProps {\n  /** Selected id; `null`, `undefined` or `clearValue` when nothing is selected. */\n  value: V | C | null | undefined;\n  /** Selecting an option emits its value; the clear button emits `clearValue`. */\n  onChange: (value: V | C) => void;\n  /**\n   * What the clear button emits. Default `null`. Pass `\"\"` for a form whose schema\n   * wants an empty string for \"no choice\" (a zod `z.string()` field), rather than\n   * mapping `null` in every `onChange` — the type of `onChange` follows it, so the\n   * mapping cannot be forgotten on one field and not another. The picker also reads\n   * the value back as empty, so `value=\"\"` shows the placeholder and no \"×\".\n   * See {@link ComboClearValue} for why the choice is closed.\n   */\n  clearValue?: C;\n  /** Already-loaded options (client-side filtered). Also used to resolve the\n   *  trigger label for the current `value`. */\n  options?: ComboOption<V>[];\n  /** Async option source, debounced and called on open + as the query changes\n   *  (at `minChars` and up). Stale responses are ignored; a rejection empties the\n   *  list and says `loadErrorLabel` instead of leaving the last query's rows up. When set, `options` is used only for label\n   *  resolution, not as the result list. */\n  loadOptions?: (query: string) => Promise<ComboOption<V>[]>;\n  /** External loading flag (OR-ed with the internal async state). */\n  loading?: boolean;\n  label?: ReactNode;\n  placeholder?: string;\n  searchPlaceholder?: string;\n  emptyLabel?: string;\n  /** Offer a clear \"×\" in place of the chevron while something is chosen; it emits\n   *  `clearValue`. A pointer shortcut inside the trigger, out of the tab order — the\n   *  keyboard's way is Delete or Backspace on the CLOSED trigger (0.23, as\n   *  {@link CountrySelect}). Not offered while `disabled` or locked. */\n  clearable?: boolean;\n  clearLabel?: string;\n  /** The phone sheet's close button. Its own prop rather than a reuse of\n   *  `clearLabel`: \"clear the selection\" and \"close this screen\" are different\n   *  actions, and on a full-screen sheet the close button is the only way out —\n   *  so it is the one control here that MUST be in the reader's language. */\n  closeLabel?: string;\n  /** The phone sheet's heading (and, as a string, its accessible name) for a picker\n   *  whose label is drawn by someone else — a bound field's label; `RhfCombobox`\n   *  hands its label over here (0.24). Default: `label`, then `placeholder`. */\n  sheetTitle?: ReactNode;\n  disabled?: boolean;\n  /**\n   * Why the choice cannot be changed — {@link Button}'s `disabledReason`, for a picker\n   * that SAVES on change (keksdose G2: the statement's account, where picking IS the\n   * write). The trigger stays focusable and `aria-disabled`, the list does not open,\n   * the clear \"×\" is gone and `onChange` never fires; the reason is in the kit\n   * {@link Tooltip} and on the trigger's `aria-describedby`. Wins over `disabled`.\n   * {@link CountrySelect}'s lock, which is built on the same core.\n   */\n  disabledReason?: ReactNode;\n  /**\n   * This picker COMMITS — choosing saves. Under a locked {@link WriteLockProvider} it is\n   * locked the `disabledReason` way with the lock's reason (which wins over its own).\n   * A picker inside a form with its own Save stays editable under the lock: leave this\n   * off there and put `commit` on the Save. No provider, or an unlocked one: no effect.\n   */\n  commit?: CommitScope;\n  /** Where the reason shows — {@link Button}'s `disabledReasonDisplay`: a line under the\n   *  field at Large and on a touch screen by default, the tooltip otherwise (DUP-3). */\n  disabledReasonDisplay?: DisabledReasonDisplay;\n  /** When set, a \"create\" row appears for a non-empty query with no exact match. */\n  onCreate?: (query: string) => void;\n  createLabel?: (query: string) => string;\n  /**\n   * Offer the create row with NOTHING typed too, worded as this — keksdose G9's\n   * \"Create cash account\", which mints a record under a default name and so needs no\n   * query. `onCreate` then receives `\"\"`. Left out, the row needs a query, as before.\n   * See {@link InlineEntityCombobox}'s `createEmptyLabel`.\n   */\n  createEmptyLabel?: string;\n  /**\n   * The create row WRITES (it mints the record on the server) while picking does not.\n   * Under a locked {@link WriteLockProvider} the row stays in the list but cannot be\n   * taken, with the lock's reason as its second line — the picker itself stays live.\n   * keksdose dev#496: on the read-only demo choosing is draft state, minting is not.\n   */\n  createCommit?: CommitScope;\n  /** Required and unanswered — {@link FIELD_INVALID}. See {@link Input}'s `invalid`. */\n  invalid?: boolean;\n  /** What is wrong with the value, as {@link Input}'s `error`: rendered under the\n   *  field, on the trigger's `aria-describedby`, and implies `invalid`. */\n  error?: ReactNode;\n  /**\n   * Standing advice — {@link Combobox}'s `hint`, so the pickers read like every other\n   * field (keksdose K4): plain TEXT is a caption under the field on the trigger's\n   * `aria-describedby`, before any error; a {@link FieldHint} \"?\" rides the label line,\n   * or with no label sits at the trigger's end edge, outside the box.\n   */\n  hint?: ReactNode;\n  /** Narrow `options` client-side by the query. Default `true`; `false` shows them\n   *  as given (a server-ranked list). */\n  filter?: boolean;\n  /** Offer nothing, and call no `loadOptions`, below this many characters. Default\n   *  `0`, i.e. the list loads as the panel opens. */\n  minChars?: number;\n  /** `loadOptions` debounce. Default 150 ms. */\n  debounceMs?: number;\n  /** Shown when `loadOptions` rejects. Default: `combobox.loadError`. */\n  loadErrorLabel?: string;\n  /**\n   * The TRIGGER — the focusable `<button>` a reader meets — as a React 19 ref prop, as\n   * on {@link CountrySelect}, which is built on the same core (0.24, kastlan: react-hook-\n   * form's focus-on-error calls `focus()` on whatever `field.ref` is handed, and a\n   * picker with no ref gave it nothing to focus). Not the wrapper: focus belongs on the\n   * trigger, which is also where the panel hands it back after a pick.\n   */\n  ref?: Ref<HTMLButtonElement>;\n}\n\n/**\n * An id-keyed, searchable entity picker: a field-styled trigger showing the\n * selected item's label, and a portalled dropdown of `{label, sublabel, icon}`\n * options — loaded up front via `options` or lazily via `loadOptions`. Built on\n * the shared field/anchor/dismiss/search primitives (no cmdk/Radix). For picking\n * several entities use {@link MultiEntityCombobox}.\n */\nexport function EntityCombobox<V extends string | number, C extends ComboClearValue = null>(\n  props: EntityComboboxProps<V, C>,\n) {\n  const {\n    value,\n    onChange,\n    clearValue = null as C,\n    options,\n    loadOptions,\n    loading,\n    label,\n    placeholder,\n    searchPlaceholder,\n    emptyLabel,\n    clearable,\n    clearLabel,\n    closeLabel,\n    sheetTitle,\n    disabled,\n    disabledReason,\n    disabledReasonDisplay,\n    commit,\n    onCreate,\n    createLabel,\n    createEmptyLabel,\n    createCommit,\n    className,\n    invalid,\n    error,\n    hint,\n    help,\n    filter,\n    minChars,\n    debounceMs,\n    loadErrorLabel,\n    ref,\n    \"aria-label\": ariaLabel,\n    // The control's own wiring, taken off `rest` so it lands on the TRIGGER rather than\n    // the wrapper — see MultiEntityCombobox: `Field`'s render-prop spreads `{ id,\n    // aria-describedby, aria-invalid, aria-required }`, and on the role-less wrapper\n    // div the label's `htmlFor` named nothing and the hint described nothing.\n    id,\n    \"aria-describedby\": ariaDescribedBy,\n    \"aria-invalid\": ariaInvalid,\n    \"aria-required\": ariaRequired,\n    ...rest\n  } = props;\n  const core = useComboboxCore<V>({\n    options,\n    loadOptions,\n    loading,\n    filter,\n    minChars,\n    debounceMs,\n  });\n  const hintParts = useFieldHint(hint, ariaDescribedBy, { help, name: label ?? ariaLabel });\n  const field = useFieldError(error, invalid, hintParts.describedBy, ariaInvalid);\n  // The props are the per-instance overrides, the provider the app-wide ones; a\n  // prop left `undefined` falls through to the provider rather than masking it.\n  const labels = useKitLabels(\"combobox\", DEFAULT_COMBOBOX_LABELS, {\n    search: searchPlaceholder,\n    noResults: emptyLabel,\n    clear: clearLabel,\n    create: createLabel,\n  });\n  const common = useKitLabels(\"common\", DEFAULT_COMMON_LABELS);\n  const { open, results, resolve, setOpen, rememberOption, query, triggerRef } = 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 — CountrySelect's.\n  const setTrigger = useCallback(\n    (el: HTMLButtonElement | null) => {\n      triggerRef.current = el;\n      assignRef(ref, el);\n    },\n    [ref, triggerRef],\n  );\n  // The lock: this picker's own reason, or the provider's under `commit`.\n  const lock = useLockReason(commit, disabledReason);\n  const inert = lock.locked || Boolean(disabled);\n  // A lock arriving while the list is up closes it — adjusted while\n  // rendering, as the core adjusts its own query, so no frame offers a pick that would\n  // be thrown away.\n  if (lock.locked && open) setOpen(false);\n  // The create row's own lock, for a picker whose choosing is draft and whose create\n  // is the write (`createCommit`).\n  const createReason = useCommitReason(createCommit, undefined);\n  // One id per instance, generated here rather than in the core: `aria-controls` on\n  // the trigger has to name the list while the list is still closed, so the id\n  // belongs to whoever renders both ends of it.\n  const listboxId = useId();\n\n  // The clear value is \"nothing selected\" too, whichever one the caller picked.\n  const chosen: V | null = value == null || value === clearValue ? null : (value as V);\n  const selectedOption = chosen == null ? null : resolve(chosen);\n  const q = query.trim();\n  // The create row's \"is this name already listed\" folds as the list's match does (DUP-5).\n  const locale = useKitLocale();\n  const showCreate = offersCreate(\n    onCreate,\n    q,\n    results.map((o) => o.label),\n    createEmptyLabel,\n    locale,\n  );\n  const showClear = Boolean(clearable && chosen != null && !inert);\n  /** What the closed control is showing — the second half of its accessible name. */\n  const triggerText = selectedOption?.label ?? placeholder ?? \"\";\n  // While locked the trigger sits in the reason's Tooltip — in a fragment with a hidden\n  // copy of the reason, Button's anatomy — `block` so a full-width field stays full width.\n  const withLock = (trigger: ReactNode) => (\n    <LockFrame lock={lock} display={disabledReasonDisplay}>\n      {trigger}\n    </LockFrame>\n  );\n\n  const choose = (o: ComboOption<V>) => {\n    if (lock.locked) return;\n    rememberOption(o);\n    onChange(o.value);\n    // Back to the trigger, not to <body>: the panel that held focus is about to\n    // unmount, and a keyboard user who just answered this field should be standing\n    // on it, ready to Tab to the next one.\n    core.closeToTrigger();\n  };\n\n  return (\n    // `rest` dresses the wrapper, which has no role; the accessible NAME — and the\n    // id, description, invalid and required state above — go on the trigger, which\n    // has one. Spread FIRST so the trigger's ARIA and the\n    // handlers that open the panel cannot be clobbered from outside.\n    <div {...rest} className={cn(\"relative\", className)}>\n      {label !== undefined && hintParts.labelHint === undefined && <FieldLabel>{label}</FieldLabel>}\n      <EndHintRow {...endHintRowProps(\"hint\" in props, label !== undefined, hintParts.labelHint)}>\n        {withLock(\n          <button\n            ref={setTrigger}\n            id={id}\n            type=\"button\"\n            // A combobox, not a button. The distinction is not pedantry: this control\n            // carried `aria-invalid`, which `button` does not support, so a required\n            // field left empty painted a rose border and told a reader nothing at all —\n            // and ESLint flagged it as exactly that (`role-supports-aria-props`). The\n            // fix the audit asked for is the role that describes what this IS: a closed\n            // choice that expands into the list named below. `combobox` supports\n            // `aria-invalid`, so the border and the announcement finally agree.\n            role=\"combobox\"\n            aria-expanded={open}\n            aria-controls={listboxId}\n            aria-haspopup=\"listbox\"\n            // The label is a floating <span>, not a <label for>, so without this the\n            // trigger's accessible name is whatever value happens to be selected —\n            // \"Checking\" with nothing saying it is the account. The label AND the\n            // value, because `aria-label` replaces the content rather than adding to\n            // it, and a control that announces only its name has lost the answer.\n            // A caller's own name wins over the composition: two fields labelled\n            // \"Account\" on a transfer form are the from and the to, and only the\n            // caller knows which is which.\n            aria-label={ariaLabel ?? (typeof label === \"string\" ? common.fieldValue(label, triggerText) : undefined)}\n            // The focusable kind of disabled while locked (Button's rule): a native\n            // `disabled` would take the field out of the tab order, and the reason with it.\n            disabled={lock.locked ? undefined : disabled}\n            aria-disabled={lock.locked || undefined}\n            aria-invalid={field.isInvalid || undefined}\n            aria-describedby={mergeDescribedBy(field.describedBy, lock.locked && lock.reasonId)}\n            aria-required={ariaRequired}\n            onClick={() => !inert && setOpen((o) => !o)}\n            // Down/Up opens the list from the closed trigger, per the APG. Enter and\n            // Space already do it through the button's own click.\n            onKeyDown={(e) => {\n              if (inert) return;\n              if (e.key === \"ArrowDown\" || e.key === \"ArrowUp\") {\n                e.preventDefault();\n                setOpen(true);\n              } else if (showClear && !open && (e.key === \"Delete\" || e.key === \"Backspace\")) {\n                // The keyboard's clear: the \"×\" is a pointer shortcut out of the tab\n                // order, so without this a cleared-by-mouse field was set-only from the\n                // keyboard. The closed trigger only — CountrySelect's rule (0.23).\n                e.preventDefault();\n                onChange(clearValue);\n              }\n            }}\n            className={cn(\n              FIELD_TRIGGER,\n              \"pe-9\",\n              label !== undefined && FIELD_FLOATING_PAD,\n              inert && \"cursor-not-allowed opacity-50\",\n              field.isInvalid && FIELD_INVALID,\n            )}\n          >\n            <span className=\"flex min-w-0 items-center gap-2\">\n              {selectedOption?.icon && <span className=\"shrink-0\">{selectedOption.icon}</span>}\n              <span\n                className={cn(\n                  // One line at Normal; from Large up the value wraps and the trigger\n                  // grows, as DatePicker's does (text size §10.17, round 0.34 T1).\n                  \"truncate-until-large\",\n                  // A chosen value is the field's VALUE, so it is set in the same ink an\n                  // <input>'s value is — FIELD_BASE's own text colour, inherited rather\n                  // than restated (Keksdose dev#477). It used to be one notch lighter\n                  // than the typeahead fields beside it, which is visible when a picker\n                  // and a text field share a form row. Nothing selected keeps the\n                  // placeholder tone (`--text-placeholder`), which every field here\n                  // agrees on.\n                  !selectedOption && \"text-placeholder\",\n                )}\n              >\n                {selectedOption?.label ?? placeholder ?? \"\"}\n              </span>\n            </span>\n            {showClear ? (\n              /* eslint-disable-next-line jsx-a11y/click-events-have-key-events -- tabIndex -1 inside\n                  the trigger <button>, so it never holds focus and a key handler here could\n                  never fire; the keys go to the trigger, where Delete and Backspace clear. */\n              <span\n                role=\"button\"\n                tabIndex={-1}\n                aria-label={labels.clear}\n                onClick={(e) => {\n                  e.stopPropagation();\n                  onChange(clearValue);\n                }}\n                className=\"absolute end-2 top-1/2 -translate-y-1/2 rounded p-0.5 text-placeholder hover:text-secondary\"\n              >\n                <X className=\"size-4\" />\n              </span>\n            ) : (\n              <FieldChevron />\n            )}\n          </button>,\n        )}\n      </EndHintRow>\n      {/* With a \"?\" the label shares the top strip with it — after the trigger, so the\n          \"?\" follows the control in the tab order, as on Input and Select. */}\n      {label !== undefined && hintParts.labelHint !== undefined && (\n        <StaticLabelRow hint={hintParts.labelHint}>\n          <FieldLabel className={LABEL_IN_ROW}>{label}</FieldLabel>\n        </StaticLabelRow>\n      )}\n      <ComboboxPanel\n        core={core}\n        listboxId={listboxId}\n        // On a phone the panel becomes a full-screen sheet, which needs the field's\n        // own label to say what it is asking for (live #200).\n        sheetTitle={sheetTitle ?? label ?? placeholder}\n        searchPlaceholder={labels.search}\n        emptyLabel={labels.noResults}\n        closeLabel={closeLabel}\n        loadErrorLabel={loadErrorLabel}\n        isSelected={(v) => v === value}\n        onChoose={choose}\n        showCreate={showCreate}\n        onCreate={() => {\n          if (lock.locked) return;\n          onCreate?.(q);\n          core.closeToTrigger();\n        }}\n        createContent={q ? labels.create(q) : createEmptyLabel}\n        createDisabledReason={createReason}\n      />\n      <FieldCaption parts={hintParts} />\n      {field.errorEl}\n    </div>\n  );\n}\n"],"mappings":"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","names":[]}

package/dist/components/field-parts.d.ts

@@ -1,13 +1,15 @@
 import type { ComponentPropsWithoutRef, ComponentPropsWithRef, ReactNode } from "react";
+import { type LabelOverride } from "../i18n/kit-labels.js";
 import { type TooltipSide } from "./tooltip.js";
 import { type CommitScope } from "./write-lock.js";
+import { DEFAULT_FIELD_SUGGESTION_LABELS } from "./field-suggestion-labels.js";
 /**
  * The pieces of a field's anatomy the kit's fields share — the static label, the hint
  * (caption or "?"), the caption and the error under a field, the label strip over a
  * bare group, the write lock on a control that saves itself, and the wiring under them
  * (`aria-describedby`, refs). Private to the package — not re-exported from the barrel,
- * except `FieldLabel` and `FLOATING_LABEL_STATIC`, which the barrel names (ui.tsx did until
- * 0.34 split it).
+ * except `FieldLabel`, `FLOATING_LABEL_STATIC`, `FieldHint` and (0.55) `FieldSuggestion`,
+ * which the barrel names (ui.tsx did until 0.34 split it).
  *
  * One file since 0.23: until then the pickers' half (`field-anatomy.tsx`: the date and
  * month pickers, whose trigger is a button in a wrapper of their own, and the groups
@@ -115,7 +117,67 @@ export declare function FieldHint({ label, side, className, "aria-label": ariaLa
  * ({@link fieldHelpMark}) — so a FieldHint is its words at EVERY size, not only at Large
  * and on touch.
  */
-export declare function useInlineHint(hint: ReactNode, withHelp?: boolean): ReactNode;
+export declare function useInlineHint(hint: ReactNode, withHelp?: boolean, name?: ReactNode): ReactNode;
+export interface FieldSuggestionLabels {
+    /** The caption when the field names no source: the value was filled in for the user. */
+    suggested: string;
+    /** The button after the caption that takes the suggested value back out. */
+    clear: string;
+    /** That button's accessible name — with the field's name when it has one ("Clear the
+     *  suggestion for “Category”"), else alone. It holds `clear`'s word, the one a voice
+     *  user says to press it (WCAG 2.5.3), first where the language allows. */
+    clearName: (field?: string) => string;
+}
+export { DEFAULT_FIELD_SUGGESTION_LABELS };
+export interface FieldSuggestionProps {
+    /**
+     * Where the value came from, in the app's words: "From the memo", "Last used",
+     * "From the receipt". Default the kit's "Suggested" (`fieldSuggestion.suggested`).
+     */
+    from?: ReactNode;
+    /**
+     * Take the suggestion back: the app empties the field (or restores what was there), and
+     * stops passing the caption. With it, a "Clear" button follows the words; without it,
+     * the caption is words alone and the field's own editing is the way to change it.
+     */
+    onClear?: () => void;
+    /** The field's name in the button's accessible name. The kit's fields fill it in from
+     *  their label (else `aria-label`); set it for a caption drawn outside a field. */
+    field?: string;
+    /** Prop > `<UiKitProvider labels={{ fieldSuggestion }}>` > English. */
+    labels?: LabelOverride<FieldSuggestionLabels>;
+}
+/**
+ * A field's "suggested from" caption (0.55, keksdose dev #638): the line under a field
+ * the app filled in for the user, saying where the value came from — "From the memo",
+ * "Last used" — and, with `onClear`, a button that takes it back out.
+ *
+ * keksdose drew it by hand twice: the memo's category under the category field (a `<p>`
+ * of the caption's type, wired to the field's `aria-describedby` by its own id) and the
+ * create card's "Last used account" as a plain `hint`. The kit's fields take it as their
+ * `hint`, so the wiring is theirs:
+ *
+ * ```tsx
+ * <CategoryCombobox
+ *   hint={fromMemo ? <FieldSuggestion from={t("from_memo")} onClear={clearCategory} /> : undefined}
+ * />
+ * ```
+ *
+ * It is a CAPTION at every size, as a text hint is — under the field, on its
+ * `aria-describedby`, never a "?" on the label line — in every field that takes a `hint`
+ * (Input, Select, Textarea, the comboboxes, the pickers, the number fields, `Field`,
+ * `RhfField` and the bound fields, the groups). The hint slot is one: while the value is
+ * the suggestion, the caption takes the place of the field's own hint, and the app passes
+ * its hint back once the user has chosen. A fact that must stay beside it goes in `help`.
+ *
+ * The button is part of the caption, so the field's description is the words and then the
+ * button ("From the memo … Clear"; the "·" between them is not read): a screen reader
+ * learns there is a way back, and the button is the next tab stop after the field.
+ */
+export declare function FieldSuggestion({ from, onClear, field, labels: labelsProp }: FieldSuggestionProps): import("react").JSX.Element;
+/** Whether a `hint` is a {@link FieldSuggestion} — a caption under the field at every
+ *  size, as text is (0.55). */
+export declare function isSuggestionHint(hint: ReactNode): boolean;
 /**
  * The doc every field's `help` prop points at.
  *
@@ -187,8 +249,8 @@ export interface FieldHintParts {
 }
 /**
  * Whether a resolved `hint` goes under the field as its caption: text always (see
- * {@link isTextHint}); with a `help` beside it, whatever it is — the label line's "?"
- * is the help's (round 0.36, §4).
+ * {@link isTextHint}), and a {@link FieldSuggestion} (0.55); with a `help` beside it,
+ * whatever it is — the label line's "?" is the help's (round 0.36, §4).
  */
 export declare function isHintCaption(hint: ReactNode, withHelp: boolean): boolean;
 /**
@@ -291,9 +353,23 @@ export interface LockReason {
  * The lock's reason wins over the control's own (`useCommitReason`).
  */
 export declare function useLockReason(commit: CommitScope | undefined, disabledReason: ReactNode): LockReason;
+/** {@link useRefusal}'s answer: the lock's, and whether the button refuses at all. */
+export interface Refusal extends LockReason {
+    /** The button refuses: it has a reason (`locked`), or `refused` was given as `true`. */
+    refused: boolean;
+}
+/**
+ * Button's and IconButton's `refused`, `disabledReason` and `commit`, read as one (0.52
+ * code review 2026-10-31, held to 0.55). `refused` as words is the reason, the path
+ * `disabledReason` has always taken, and its words win over `disabledReason`'s;
+ * `refused={true}` refuses with no words of its own; a lock's reason wins over both, as
+ * {@link useLockReason} has it.
+ */
+export declare function useRefusal(refused: ReactNode, disabledReason: ReactNode, commit: CommitScope | undefined): Refusal;
 /**
  * A locked control and its reason — the kit's ONE frame for it, used by Button,
- * IconButton, Chip, Checkbox, Switch and every field that locks (DUP-3, refactor audit
+ * IconButton, Chip, Checkbox, Switch and every field that locks (the fields through
+ * {@link LockFrame} since 0.55) (DUP-3, refactor audit
  * 2026-10: Button's `ReasonFrame` and Chip's `ChipReasonFrame` were copies of it, and
  * only those two drew the line, so a field locked through `commit` kept its reason in a
  * tooltip on a phone while the Save beside it said it in words). Where it shows is
@@ -329,6 +405,32 @@ export declare function LockedReason({ lock, display, line: lineProp, side, port
     lineClassName?: string;
     children: ReactNode;
 }): import("react").JSX.Element;
+/**
+ * A field in its lock's frame: in {@link LockedReason} while `lock` holds (a write lock's
+ * reason through `commit`, or the field's own `disabledReason`), else the field as it is —
+ * no element and no hook added.
+ *
+ * The fields' ONE helper for it, held back from 0.53 (0.52 code review,
+ * date-picker.tsx:300). Fifteen fields wrote the same ternary around the same frame:
+ * `withReason` in DatePicker, MonthPicker, Input and Select, `withLock` in Combobox,
+ * InlineEntityCombobox, EntityCombobox, MultiEntityCombobox and Autocomplete, one inline in
+ * DateRangePicker, NumberInput, MultiSelect, CountrySelect and CurrencySelect, and
+ * AmountInput's `LockedOrNot` — so a change to the frame's box had to be made in each.
+ *
+ * The frame is `block`, so a full-width field stays full width in it, then `className`. A
+ * field whose root it is while locked moves the caller's layout classes (a width, a grid
+ * cell) here, so a lock does not reflow the form; a display class there replaces `block`
+ * (CountrySelect's `flex w-full items-stretch`, so its trigger keeps the full width).
+ */
+export declare function LockFrame({ lock, display, className, children, }: {
+    /** The field's lock (`useLockReason`): framed only while `locked`. */
+    lock: Pick<LockReason, "locked" | "reason" | "reasonId">;
+    /** Where the reason shows — the field's `disabledReasonDisplay`. Default `"auto"`. */
+    display?: DisabledReasonDisplay;
+    /** The frame's classes, after `block`. */
+    className?: string;
+    children: ReactNode;
+}): import("react").JSX.Element;
 /**
  * Where a control's `disabledReason` is shown (§4 "No fact only in a tooltip"):
  *

package/dist/components/field-parts.js

@@ -1,6 +1,6 @@
 "use client";
 import { Fragment, jsx, jsxs } from "react/jsx-runtime";
-import { createContext, isValidElement, useContext, useId } from "react";
+import { cloneElement, createContext, isValidElement, useContext, useId } from "react";
 import { HelpCircle } from "lucide-react";
 import { cn } from "../lib/cn.js";
 import { hasContent } from "../lib/presence.js";
@@ -11,6 +11,7 @@ import { FOCUS_RING } from "./focus-ring.js";
 import { HelpPopover } from "./help-popover.js";
 import { Tooltip } from "./tooltip.js";
 import { useCommitReason } from "./write-lock.js";
+import { DEFAULT_FIELD_SUGGESTION_LABELS } from "./field-suggestion-labels.js";
 function mergeDescribedBy(...ids) {
   const list = ids.filter(Boolean);
   return list.length ? list.join(" ") : void 0;
@@ -55,13 +56,47 @@ function FieldHint({ label, side = "start", className, "aria-label": ariaLabel,
     ) })
   );
 }
-function useInlineHint(hint, withHelp = false) {
+function useInlineHint(hint, withHelp = false, name) {
   const inline = useInlineFacts();
   if ((inline || withHelp) && isValidElement(hint) && hint.type === FieldHint) {
     const words = hint.props.label;
     if (words) return words;
   }
-  return hint;
+  return namedSuggestion(hint, name);
+}
+function FieldSuggestion({ from, onClear, field, labels: labelsProp }) {
+  const labels = useKitLabels("fieldSuggestion", DEFAULT_FIELD_SUGGESTION_LABELS, labelsProp);
+  return (
+    // Inline: the field's caption (`<p>`) holds it, and a `<p>` holds no block.
+    /* @__PURE__ */ jsxs("span", { "data-slot": "field-suggestion", children: [
+      hasContent(from) ? from : labels.suggested,
+      onClear && /* @__PURE__ */ jsxs(Fragment, { children: [
+        /* @__PURE__ */ jsx("span", { "aria-hidden": "true", children: " \xB7 " }),
+        /* @__PURE__ */ jsx(
+          "button",
+          {
+            type: "button",
+            onClick: onClear,
+            "aria-label": labels.clearName(field),
+            className: cn(
+              "rounded-sm font-medium text-secondary underline underline-offset-2 transition-colors hover:text-primary",
+              "focus-visible:outline-focus focus-visible:outline-offset-2 focus-visible:outline-brand"
+            ),
+            children: labels.clear
+          }
+        )
+      ] })
+    ] })
+  );
+}
+function isSuggestionHint(hint) {
+  return isValidElement(hint) && hint.type === FieldSuggestion;
+}
+function namedSuggestion(hint, name) {
+  if (!isValidElement(hint) || hint.type !== FieldSuggestion) return hint;
+  if (hint.props.field !== void 0) return hint;
+  const field = plainText(name);
+  return field === void 0 ? hint : cloneElement(hint, { field });
 }
 function FieldHelp({ name, children }) {
   const common = useKitLabels("common", DEFAULT_COMMON_LABELS);
@@ -78,12 +113,12 @@ function isTextHint(hint) {
 }
 const FIELD_CAPTION_CLASS = "mt-1 text-caption leading-tight text-muted";
 function isHintCaption(hint, withHelp) {
-  return isTextHint(hint) || withHelp && hasContent(hint);
+  return isTextHint(hint) || isSuggestionHint(hint) || withHelp && hasContent(hint);
 }
 function useFieldHint(hintProp, describedBy, { help, name } = {}) {
   const helpMark = fieldHelpMark(help, name);
   const withHelp = helpMark !== void 0;
-  const hint = useInlineHint(hintProp, withHelp);
+  const hint = useInlineHint(hintProp, withHelp, name);
   const captionId = useId();
   const caption = isHintCaption(hint, withHelp);
   return {
@@ -141,6 +176,10 @@ function useLockReason(commit, disabledReason) {
   const reasonId = useId();
   return { reason, locked: hasContent(reason), reasonId };
 }
+function useRefusal(refused, disabledReason, commit) {
+  const lock = useLockReason(commit, refused !== true && hasContent(refused) ? refused : disabledReason);
+  return { ...lock, refused: lock.locked || refused === true };
+}
 function LockedReason({
   lock,
   display,
@@ -160,6 +199,15 @@ function LockedReason({
     /* @__PURE__ */ jsx("span", { id: lock.reasonId, hidden: true, children: lock.reason })
   ] }) });
 }
+function LockFrame({
+  lock,
+  display,
+  className,
+  children
+}) {
+  if (!lock.locked) return /* @__PURE__ */ jsx(Fragment, { children });
+  return /* @__PURE__ */ jsx(LockedReason, { lock, display, className: cn("block", className), children });
+}
 const CompactControlsContext = createContext(false);
 function CompactControls({ children, compact = true }) {
   return /* @__PURE__ */ jsx(CompactControlsContext.Provider, { value: compact, children });
@@ -267,6 +315,7 @@ function LabelStrip({
 export {
   CompactControls,
   CompactControlsContext,
+  DEFAULT_FIELD_SUGGESTION_LABELS,
   DISABLED_REASON_LINE_CLASS,
   DisabledReasonLine,
   EndHintRow,
@@ -278,11 +327,13 @@ export {
   FieldHint,
   FieldLabel,
   FieldLabelLine,
+  FieldSuggestion,
   LABEL_ABOVE_AT_LARGE,
   LABEL_ABOVE_BOX,
   LABEL_IN_ROW,
   LABEL_STRIP_PAD,
   LabelStrip,
+  LockFrame,
   LockedReason,
   RequiredStarOnLegend,
   STATIC_LABEL_TYPE,
@@ -290,6 +341,7 @@ export {
   assignRef,
   fieldHelpMark,
   isHintCaption,
+  isSuggestionHint,
   isTextHint,
   mergeDescribedBy,
   mergeRefs,
@@ -298,6 +350,7 @@ export {
   useFieldHint,
   useFieldMessages,
   useInlineHint,
-  useLockReason
+  useLockReason,
+  useRefusal
 };
 //# sourceMappingURL=field-parts.js.map