@eifi1/ui-kit 0.22.0 → 0.24.0

package/src/components/combobox.tsx

@@ -1,7 +1,7 @@
 import { Fragment, useId, useMemo, useRef, useState } from "react";
-import type { ComponentPropsWithoutRef, ReactNode, RefObject } from "react";
+import type { ComponentPropsWithoutRef, ReactNode, Ref, RefObject } from "react";
 import { createPortal } from "react-dom";
-import { ChevronDown, X } from "lucide-react";
+import { ChevronDown, Plus, X } from "lucide-react";
 import { FIELD_BASE, FIELD_FLOATING_PAD, FIELD_INVALID, PHONE_QUERY } from "./ui";
 import { cn } from "../lib/cn";
 import { useDropdown } from "./dropdown";
@@ -12,7 +12,9 @@ import { PickerSheet, SHEET_ROW_CLASS } from "./picker-sheet";
 import {
   ComboboxFieldLabel,
   DISABLED_ROW_CLASS,
+  endHintRowProps,
   isOptionEnabled,
+  offersCreate,
   stepEnabled,
   SUGGESTION_LIST_CLASS,
   suggestionRowClass,
@@ -22,7 +24,17 @@ import {
   type ComboOption,
 } from "./combobox-core";
 import { DEFAULT_COMBOBOX_LABELS, useKitLabels } from "../i18n/kit-labels";
-import { EndHintRow, FieldCaption, LABEL_IN_ROW, StaticLabelRow, useFieldHint } from "./field-parts";
+import {
+  EndHintRow,
+  FieldCaption,
+  LABEL_IN_ROW,
+  LockedReason,
+  StaticLabelRow,
+  useFieldHint,
+  useLockReason,
+} from "./field-parts";
+import { hasMessage, mergeDescribedBy } from "./choice-parts";
+import { useCommitReason } from "./write-lock";
 
 // One look for both combobox flavors below — the suggestion list and its rows
 // must stay pixel-identical between the free-text and the id-keyed variant (and
@@ -124,6 +136,27 @@ function SuggestionList({
 
 const rowClass = suggestionRowClass;
 
+/**
+ * The write lock on the two TYPED fields below — {@link Button}'s `disabledReason`
+ * path, for an input (keksdose G2).
+ *
+ * `readOnly` rather than `disabled`, as everywhere the kit locks a field: still focusable,
+ * so the reason in the Tooltip reaches a keyboard; refusing keys, so nothing typed can
+ * become a value; and FIELD_BASE paints a `[readonly]` field in the settled grey a
+ * disabled one wears. No list opens, by focus, click, chevron or arrow — and Enter is
+ * swallowed, so a locked field does not submit the form around it either (Select's
+ * lock, `LOCKED_SELECT_KEYS`). Every other key is left alone: the arrows and Home/End
+ * still move the caret through a long value someone is trying to read.
+ */
+function lockedKeyDown(e: { key: string; preventDefault: () => void }) {
+  if (e.key === "Enter") e.preventDefault();
+}
+
+/** {@link InlineEntityCombobox}'s create row over the shared row look: in the brand
+ *  colour {@link Combobox}'s own create row wears, with a leading "+" as the panel
+ *  pickers' has — an action at the foot of the list, not one more record. */
+const CREATE_ROW_CLASS = "flex items-center gap-2 font-medium text-[var(--brand)]";
+
 /**
  * Four of the div's own attributes are omitted because this component already owns
  * the name, with a different meaning: `id` is the INPUT's (a caller labels or
@@ -163,6 +196,18 @@ export interface ComboboxProps
    *  stops toggling with it — it is a mouse target the input's own `disabled` does
    *  not reach. */
   disabled?: boolean;
+  /**
+   * Why the value cannot be changed — {@link Button}'s `disabledReason`, for a field
+   * that SAVES itself (an inline editor whose blur writes). The input stays focusable
+   * and `aria-disabled`, is `readOnly`, opens no list and calls neither `onChange` nor
+   * `onSubmit`; the reason is in the kit {@link Tooltip} and on its `aria-describedby`.
+   * Wins over `disabled`. The family's lock (keksdose G2) — see {@link InlineEntityCombobox}.
+   */
+  disabledReason?: ReactNode;
+  /** This field COMMITS. Under a locked {@link WriteLockProvider} it is locked the
+   *  `disabledReason` way with the lock's reason; inside a form with its own Save, leave
+   *  it off and put `commit` on the Save. No provider, or an unlocked one: no effect. */
+  commit?: boolean;
   /** Heading an option belongs under. Supplying it makes this list read exactly
    *  like {@link InlineEntityCombobox}'s — one heading per group with its rows
    *  indented beneath — instead of a flat list (feedback #136 rework: the payee
@@ -199,6 +244,14 @@ export interface ComboboxProps
   maxSuggestions?: number;
   searchPlaceholder?: string;
   closeLabel?: string;
+  /**
+   * The phone sheet's heading — and, as a string, the dialog's accessible name — for a
+   * field whose label is drawn by someone else: a form's `FormLabel` above it,
+   * which `RhfTextCombobox` hands over here (0.24). Default: `label`. Without either, the
+   * full-screen sheet opened untitled and unnamed, the one screen on a phone that has to
+   * say what it is asking for (live #200).
+   */
+  sheetTitle?: ReactNode;
   /**
    * Label for the row that COMMITS a value the list does not contain — e.g.
    * `(v) => \`Add "${v}" as payee\``. Supplying it turns the free text into
@@ -215,6 +268,15 @@ export interface ComboboxProps
    * values are all supposed to already exist.
    */
   createLabel?: (value: string) => string;
+  /**
+   * The `<input>` — the control a reader types in and the one focus belongs on — as a
+   * React 19 ref prop, the way {@link CountrySelect} takes its trigger's (0.24, kastlan:
+   * react-hook-form's focus-on-error calls `focus()` on whatever `field.ref` is handed,
+   * and a combobox with no ref inside a hand-wired `RhfField` gave it nothing, so a
+   * failed submit could not take the user to it). Not the wrapper: a ref is for focus,
+   * measurement and selection, and all three are the input's. `RhfTextCombobox` passes it.
+   */
+  ref?: Ref<HTMLInputElement>;
 }
 
 /**
@@ -227,36 +289,41 @@ export interface ComboboxProps
  * visually and behaviourally consistent with the other dropdowns (feedback
  * #230 — the payee field looked/behaved differently from every other select).
  */
-export function Combobox({
-  value,
-  onChange,
-  options,
-  label,
-  id,
-  placeholder,
-  className,
-  groupBy,
-  maxSuggestions,
-  searchPlaceholder,
-  closeLabel,
-  createLabel,
-  invalid,
-  error,
-  hint,
-  disabled,
-  optionAdornment,
-  autoFocus,
-  onBlur,
-  onSubmit,
-  "aria-label": ariaLabel,
-  // Off `rest` and onto the <input>, which is the combobox a reader meets: `Field`'s
-  // render-prop spreads `{ id, aria-describedby, aria-invalid, aria-required }`, and
-  // on the wrapper div the hint and required state described nothing.
-  "aria-describedby": ariaDescribedBy,
-  "aria-invalid": ariaInvalid,
-  "aria-required": ariaRequired,
-  ...rest
-}: ComboboxProps) {
+export function Combobox(props: ComboboxProps) {
+  const {
+    value,
+    onChange,
+    options,
+    label,
+    id,
+    placeholder,
+    className,
+    groupBy,
+    maxSuggestions,
+    searchPlaceholder,
+    closeLabel,
+    sheetTitle,
+    createLabel,
+    invalid,
+    error,
+    hint,
+    disabled,
+    disabledReason,
+    commit,
+    optionAdornment,
+    autoFocus,
+    onBlur,
+    onSubmit,
+    ref,
+    "aria-label": ariaLabel,
+    // Off `rest` and onto the <input>, which is the combobox a reader meets: `Field`'s
+    // render-prop spreads `{ id, aria-describedby, aria-invalid, aria-required }`, and
+    // on the wrapper div the hint and required state described nothing.
+    "aria-describedby": ariaDescribedBy,
+    "aria-invalid": ariaInvalid,
+    "aria-required": ariaRequired,
+    ...rest
+  } = props;
   const hintParts = useFieldHint(hint, ariaDescribedBy);
   const field = useComboboxFieldError(
     error,
@@ -276,6 +343,12 @@ export function Combobox({
   const { open, setOpen, wrapperRef, panelRef } = useDropdown({ backCloses: !isPhone });
   const primaryOnly = usePrimaryPressOnly();
   const [active, setActive] = useState(-1);
+  // The lock (see `lockedKeyDown`): a lock arriving while the list is up closes it,
+  // adjusted while rendering so no frame offers a row that can no longer be taken.
+  const lock = useLockReason(commit, disabledReason);
+  const locked = lock.locked;
+  const inert = locked || Boolean(disabled);
+  if (locked && open) setOpen(false);
   // A phone opens the list as a full-screen sheet with its own input, the way a
   // native <select> does — live #200: "Paid as full screen dialog with input.
   // Similar to the account select that already appears as full screen." The
@@ -361,7 +434,8 @@ export function Combobox({
     return heads;
   }, [matches, groupBy]);
 
-  const commit = (v: string) => {
+  const take = (v: string) => {
+    if (locked) return;
     onChange(v);
     setOpen(false);
     setActive(-1);
@@ -381,6 +455,17 @@ export function Combobox({
   const activeId = !isPhone && active >= 0 && active < matches.length ? optionId(active) : undefined;
   useActiveOptionScroll(activeId);
 
+  // While locked the field sits in the reason's Tooltip — in a fragment with a hidden
+  // copy of the reason, Button's anatomy; `block` so a full-width field stays full width.
+  const withLock = (box: ReactNode) =>
+    locked ? (
+      <LockedReason lock={lock} className="block">
+        {box}
+      </LockedReason>
+    ) : (
+      box
+    );
+
   const typed = value.trim();
   const createRow =
     createLabel && typed.length > 0 && !options.some((o) => o.toLowerCase() === typed.toLowerCase())
@@ -398,139 +483,149 @@ export function Combobox({
           name a reader hears is the same words either way. With a "?" it moves into a
           row after the field, below. */}
       {label !== undefined && hintParts.labelHint === undefined && (
-        <ComboboxFieldLabel htmlFor={fieldId} className={disabled ? "opacity-50" : undefined}>
+        <ComboboxFieldLabel htmlFor={fieldId} className={inert ? "opacity-50" : undefined}>
           {label}
         </ComboboxFieldLabel>
       )}
-      <EndHintRow hint={label === undefined ? hintParts.labelHint : undefined}>
-        {/* The chevron centers against this inner wrapper, which hugs the input.
-            The outer div can be taller than the input (as a grid item it
-            stretches to the row height, e.g. next to the editor's category cell
-            with its split button), which used to drag a top-1/2 chevron down to
-            the input's bottom edge (feedback #248). */}
-        {/* Dimmed as a whole when disabled, the way EntityCombobox dims its trigger.
-            FIELD_BASE's grey alone left a disabled picker looking like a filled-in
-            one beside the pickers that do dim (the label is not the input's `peer`,
-            so it is dimmed by hand above). */}
-        <div ref={fieldRef} className={cn("relative", disabled && "cursor-not-allowed opacity-50")}>
-          <input
-            id={fieldId}
-            value={value}
-            placeholder={placeholder}
-            // The caller's name, over the <label for> above — which is what names the
-            // field otherwise (dev#477: a field with neither announces only its text).
-            aria-label={ariaLabel}
-            role="combobox"
-            aria-expanded={open}
-            // The list this field is the mouth of. Required by the role, and the half
-            // that was missing: the field said it was expanded and never said what it
-            // had expanded, so a reader had no way from the box to the options
-            // (ESLint's `role-has-required-aria-props`, the audit's §a11y).
-            aria-controls={listboxId}
-            aria-activedescendant={activeId}
-            aria-autocomplete="list"
-            aria-invalid={field.isInvalid || undefined}
-            aria-describedby={field.describedBy}
-            aria-required={ariaRequired}
-            autoComplete="off"
-            disabled={disabled}
-            // eslint-disable-next-line jsx-a11y/no-autofocus -- a documented prop the caller opts into (off by default); the field never takes focus on its own.
-            autoFocus={autoFocus}
-            onBlur={onBlur}
-            onMouseDown={primaryOnly.onMouseDown}
-            onFocus={() => {
-              // A back/forward mouse button focuses this field on its way to
-              // navigating; it is not a request to open anything (live #309 rework).
-              if (primaryOnly.fromAuxButton()) return;
-              setOpen(true);
-              setTyping(false);
-              // The sheet carries its own input, so the field behind it must not also
-              // pull up the keyboard and scroll the page under the dialog.
-              if (isPhone) sheetInputRef.current?.focus();
-            }}
-            // A CLICK as well as focus — the other half of dev#549. Picking a suggestion
-            // closes the list without moving focus (the rows suppress `mousedown` on
-            // purpose, so the input never blurred), which means clicking the field again
-            // fires no `focus` event at all and the list stayed shut. "Does not open
-            // anything" was literally true.
-            onClick={() => {
-              setOpen(true);
-              setTyping(false);
-            }}
-            // `inputMode="none"` rather than readOnly: the field must not look
-            // uneditable (FIELD_BASE greys a read-only field since dev#468) and must
-            // still take focus — it just has no keyboard of its own, the same trick
-            // the amount field uses for the numpad.
-            inputMode={isPhone ? "none" : undefined}
-            onChange={(e) => {
-              onChange(e.target.value);
-              setOpen(true);
-              setActive(-1);
-              setTyping(true);
-            }}
-            onKeyDown={(e) => {
-              if (e.key === "ArrowDown") {
-                e.preventDefault();
+      <EndHintRow {...endHintRowProps("hint" in props, label !== undefined, hintParts.labelHint)}>
+        {withLock(
+          /* The chevron centers against this inner wrapper, which hugs the input.
+              The outer div can be taller than the input (as a grid item it
+              stretches to the row height, e.g. next to the editor's category cell
+              with its split button), which used to drag a top-1/2 chevron down to
+              the input's bottom edge (feedback #248).
+              Dimmed as a whole when disabled (or locked), the way EntityCombobox dims its
+              trigger. FIELD_BASE's grey alone left a disabled picker looking like a
+              filled-in one beside the pickers that do dim (the label is not the input's
+              `peer`, so it is dimmed by hand above). */
+          <div ref={fieldRef} className={cn("relative", inert && "cursor-not-allowed opacity-50")}>
+            <input
+              ref={ref}
+              id={fieldId}
+              value={value}
+              placeholder={placeholder}
+              // The caller's name, over the <label for> above — which is what names the
+              // field otherwise (dev#477: a field with neither announces only its text).
+              aria-label={ariaLabel}
+              role="combobox"
+              aria-expanded={open}
+              // The list this field is the mouth of. Required by the role, and the half
+              // that was missing: the field said it was expanded and never said what it
+              // had expanded, so a reader had no way from the box to the options
+              // (ESLint's `role-has-required-aria-props`, the audit's §a11y).
+              aria-controls={listboxId}
+              aria-activedescendant={activeId}
+              aria-autocomplete="list"
+              aria-invalid={field.isInvalid || undefined}
+              aria-describedby={mergeDescribedBy(field.describedBy, locked && lock.reasonId)}
+              aria-required={ariaRequired}
+              autoComplete="off"
+              // Locked: focusable, `readOnly`, `aria-disabled` — see `lockedKeyDown`.
+              disabled={locked ? undefined : disabled}
+              readOnly={locked || undefined}
+              aria-disabled={locked || undefined}
+              // eslint-disable-next-line jsx-a11y/no-autofocus -- a documented prop the caller opts into (off by default); the field never takes focus on its own.
+              autoFocus={autoFocus}
+              onBlur={onBlur}
+              onMouseDown={primaryOnly.onMouseDown}
+              onFocus={() => {
+                // A back/forward mouse button focuses this field on its way to
+                // navigating; it is not a request to open anything (live #309 rework).
+                // A locked field takes focus to say why, and opens nothing.
+                if (primaryOnly.fromAuxButton() || locked) return;
                 setOpen(true);
-                setActive((i) => Math.min(i + 1, matches.length - 1));
-              } else if (e.key === "ArrowUp") {
-                e.preventDefault();
-                setActive((i) => Math.max(i - 1, 0));
-              } else if (e.key === "Enter") {
-                if (open && active >= 0 && active < matches.length) {
+                setTyping(false);
+                // The sheet carries its own input, so the field behind it must not also
+                // pull up the keyboard and scroll the page under the dialog.
+                if (isPhone) sheetInputRef.current?.focus();
+              }}
+              // A CLICK as well as focus — the other half of dev#549. Picking a suggestion
+              // closes the list without moving focus (the rows suppress `mousedown` on
+              // purpose, so the input never blurred), which means clicking the field again
+              // fires no `focus` event at all and the list stayed shut. "Does not open
+              // anything" was literally true.
+              onClick={() => {
+                if (locked) return;
+                setOpen(true);
+                setTyping(false);
+              }}
+              // `inputMode="none"` rather than readOnly: the field must not look
+              // uneditable (FIELD_BASE greys a read-only field since dev#468) and must
+              // still take focus — it just has no keyboard of its own, the same trick
+              // the amount field uses for the numpad.
+              inputMode={isPhone ? "none" : undefined}
+              onChange={(e) => {
+                if (locked) return;
+                onChange(e.target.value);
+                setOpen(true);
+                setActive(-1);
+                setTyping(true);
+              }}
+              onKeyDown={(e) => {
+                if (locked) return lockedKeyDown(e);
+                if (e.key === "ArrowDown") {
+                  e.preventDefault();
+                  setOpen(true);
+                  setActive((i) => Math.min(i + 1, matches.length - 1));
+                } else if (e.key === "ArrowUp") {
                   e.preventDefault();
-                  commit(matches[active]);
-                } else {
-                  // No row highlighted: the typed text is the answer. `preventDefault`
-                  // only when a caller is taking Enter, so a plain form submit is
-                  // otherwise left alone.
-                  if (onSubmit) e.preventDefault();
+                  setActive((i) => Math.max(i - 1, 0));
+                } else if (e.key === "Enter") {
+                  if (open && active >= 0 && active < matches.length) {
+                    e.preventDefault();
+                    take(matches[active]);
+                  } else {
+                    // No row highlighted: the typed text is the answer. `preventDefault`
+                    // only when a caller is taking Enter, so a plain form submit is
+                    // otherwise left alone.
+                    if (onSubmit) e.preventDefault();
+                    setOpen(false);
+                    onSubmit?.();
+                  }
+                } else if (e.key === "Escape") {
+                  setOpen(false);
+                  setActive(-1);
+                } else if (e.key === "Tab") {
+                  // Closes, and lets the browser take the Tab: focus is in THIS input,
+                  // which is staying, so there is nothing to catch — unlike the pickers
+                  // whose focus sits inside a portalled panel.
                   setOpen(false);
-                  onSubmit?.();
+                  setActive(-1);
                 }
-              } else if (e.key === "Escape") {
-                setOpen(false);
-                setActive(-1);
-              } else if (e.key === "Tab") {
-                // Closes, and lets the browser take the Tab: focus is in THIS input,
-                // which is staying, so there is nothing to catch — unlike the pickers
-                // whose focus sits inside a portalled panel.
-                setOpen(false);
-                setActive(-1);
-              }
-              // Home/End are deliberately absent. The APG gives them to the list only
-              // where the combobox is not editable; here the text IS the value, a
-              // payee name is long enough to want the caret moved to its start, and
-              // the desktop list is capped at 8 rows — so jumping it would be worth
-              // almost nothing and would cost the one gesture that field is used with.
-            }}
-            className={cn(
-              FIELD_BASE,
-              label !== undefined && FIELD_FLOATING_PAD,
-              "pe-9",
-              field.isInvalid && FIELD_INVALID,
-            )}
-          />
-          <ChevronDown
-            aria-hidden
-            onMouseDown={(e) => {
-              // Toggle on the chevron without stealing focus from the input.
-              e.preventDefault();
-              if (!disabled) setOpen((o) => !o);
-            }}
-            className={cn(
-              "absolute end-2.5 top-1/2 size-4 -translate-y-1/2 text-[var(--text-placeholder)]",
-              // The box above does the dimming; dimming here too would halve it again.
-              !disabled && "cursor-pointer",
-            )}
-          />
-        </div>
+                // Home/End are deliberately absent. The APG gives them to the list only
+                // where the combobox is not editable; here the text IS the value, a
+                // payee name is long enough to want the caret moved to its start, and
+                // the desktop list is capped at 8 rows — so jumping it would be worth
+                // almost nothing and would cost the one gesture that field is used with.
+              }}
+              className={cn(
+                FIELD_BASE,
+                label !== undefined && FIELD_FLOATING_PAD,
+                "pe-9",
+                field.isInvalid && FIELD_INVALID,
+              )}
+            />
+            <ChevronDown
+              aria-hidden
+              onMouseDown={(e) => {
+                // Toggle on the chevron without stealing focus from the input.
+                e.preventDefault();
+                if (!inert) setOpen((o) => !o);
+              }}
+              className={cn(
+                "absolute end-2.5 top-1/2 size-4 -translate-y-1/2 text-[var(--text-placeholder)]",
+                // The box above does the dimming; dimming here too would halve it again.
+                !inert && "cursor-pointer",
+              )}
+            />
+          </div>,
+        )}
       </EndHintRow>
       {/* The label and its "?" share the top strip — after the field in the DOM, so the
           "?" follows the control in the tab order, as it does on Input and Select. */}
       {label !== undefined && hintParts.labelHint !== undefined && (
         <StaticLabelRow hint={hintParts.labelHint}>
-          <ComboboxFieldLabel htmlFor={fieldId} className={cn(LABEL_IN_ROW, disabled && "opacity-50")}>
+          <ComboboxFieldLabel htmlFor={fieldId} className={cn(LABEL_IN_ROW, inert && "opacity-50")}>
             {label}
           </ComboboxFieldLabel>
         </StaticLabelRow>
@@ -539,9 +634,9 @@ export function Combobox({
       {field.errorEl}
       {isPhone && (
         <PickerSheet
-          open={open && !disabled}
+          open={open && !inert}
           onClose={() => setOpen(false)}
-          title={label}
+          title={sheetTitle ?? label}
           // The sheet's input IS the field: this is a free-text control, so what is
           // typed here is the value (a brand-new payee is just a name nothing
           // matches), and the list below narrows as it changes.
@@ -564,7 +659,7 @@ export function Combobox({
                   type="button"
                   role="option"
                   aria-selected={false}
-                  onClick={() => commit(typed)}
+                  onClick={() => take(typed)}
                   className={cn(SHEET_ROW_CLASS, "font-medium text-[var(--brand)]")}
                 >
                   {createRow}
@@ -588,7 +683,7 @@ export function Combobox({
                       type="button"
                       role="option"
                       aria-selected={o === value}
-                      onClick={() => commit(o)}
+                      onClick={() => take(o)}
                       className={cn(
                         SHEET_ROW_CLASS,
                         optionAdornment && "flex items-center justify-between gap-2",
@@ -604,7 +699,7 @@ export function Combobox({
           </ul>
         </PickerSheet>
       )}
-      {!isPhone && open && !disabled && (matches.length > 0 || createRow) && (
+      {!isPhone && open && !inert && (matches.length > 0 || createRow) && (
         <SuggestionList id={listboxId} anchorRef={fieldRef} panelRef={panelRef}>
           {createRow && (
             <li role="presentation">
@@ -617,7 +712,7 @@ export function Combobox({
                   // mousedown, like the rows below: the input's blur would otherwise
                   // close the list before the click landed.
                   e.preventDefault();
-                  commit(typed);
+                  take(typed);
                 }}
                 className={cn(rowClass(false), "font-medium text-[var(--brand)]")}
               >
@@ -657,7 +752,7 @@ export function Combobox({
                       // mousedown (not click) so the blur from the input firing first
                       // doesn't close the list before the selection registers.
                       e.preventDefault();
-                      commit(o);
+                      take(o);
                     }}
                     onMouseEnter={() => setActive(i)}
                     className={cn(
@@ -719,6 +814,11 @@ export interface InlineEntityComboboxProps<V extends string | number, C extends
    *  list simply does not open. Default: `combobox.noResults` from the provider. */
   emptyLabel?: string;
   closeLabel?: string;
+  /** The phone sheet's heading (and, as a string, its accessible name) for a field
+   *  whose label is drawn by someone else — a form's `FormLabel`;
+   *  `RhfInlineEntityCombobox` hands its label over here (0.24). Default: `label`.
+   *  See {@link Combobox}'s `sheetTitle`. */
+  sheetTitle?: ReactNode;
   /** Offer a clear "×" in place of the chevron whenever something is selected.
    *
    *  Emptying the text already clears (see {@link reconcile}), and on a desktop that
@@ -729,6 +829,82 @@ export interface InlineEntityComboboxProps<V extends string | number, C extends
    *  affordance both shells share, and it clears without opening anything. */
   clearable?: boolean;
   clearLabel?: string;
+  /**
+   * Why the choice cannot be changed — {@link Button}'s `disabledReason`, for a picker
+   * that SAVES on change. keksdose G2: the statement review's account picker IS the
+   * write (picking re-runs the duplicate check on the server), and on the read-only demo
+   * the app wrapped it in a hand-made Tooltip over a native `disabled` — out of the tab
+   * order, so the reason never reached a keyboard.
+   *
+   * With a reason the input stays focusable and `aria-disabled`, is `readOnly` (the
+   * settled grey), opens no list or sheet, offers no clear "×", and no pick, typed
+   * label or clear reaches `onChange`; the reason is in the kit {@link Tooltip} and on
+   * the input's `aria-describedby`. Wins over `disabled`. Use it CONTROLLED, as the
+   * component always is: the shown label is `value`'s.
+   */
+  disabledReason?: ReactNode;
+  /**
+   * This picker COMMITS — choosing saves. Under a locked {@link WriteLockProvider} it is
+   * locked the `disabledReason` way with the lock's reason (which wins over its own).
+   * A picker inside a form with its own Save stays editable under the lock — leave this
+   * off there and put `commit` on the Save. No provider, or an unlocked one: no effect.
+   */
+  commit?: boolean;
+  /**
+   * A last row that makes a new record from what was typed — keksdose G9, whose "Create
+   * cash account" had to become a separate button because this picker had no such row.
+   *
+   * Shown while the typed query is non-empty and names no option exactly
+   * (case-insensitive — an exact hit is a record the list already shows), worded
+   * `createLabel(query)`, default `combobox.create`: "Create “{query}”". The arrow keys
+   * reach it like an option; Enter or a click calls `onCreate(query)` and closes the
+   * list. Making the record, and then passing its id as `value`, is the caller's: the
+   * field shows the old selection until it does.
+   *
+   * The same rule as {@link EntityCombobox}'s `onCreate`, so the family agrees. It is a
+   * row of the LIST, not an option: it is never `aria-selected`, never matched by a
+   * typed label on blur, and never sorted among the records the way a sentinel option
+   * would be (the reason keksdose gave for the separate button).
+   */
+  onCreate?: (query: string) => void;
+  /** The create row's words for a query. Default: `combobox.create` from the
+   *  {@link UiKitProvider}, else English `Create “{query}”`. */
+  createLabel?: (query: string) => string;
+  /**
+   * Offer the create row with NOTHING typed too, worded as this — keksdose's "Create cash
+   * account", which mints an account under a default name and so needs no query.
+   * `onCreate` then receives `""`, and the caller supplies the name. Left out, the row
+   * needs a query.
+   *
+   * One string rather than a switch: a row with no query has nothing to quote, so the
+   * kit cannot word it — "Create “”" says nothing — and naming it is what turns it on.
+   * With both, one handler serves both rows:
+   *
+   * ```tsx
+   * onCreate={(name) => createCash(name || t("cash_account_default_name"))}
+   * createEmptyLabel={t("create_cash_account")}
+   * ```
+   */
+  createEmptyLabel?: string;
+  /**
+   * The create row WRITES while picking does not — keksdose dev#496: on the read-only
+   * demo choosing the cash account is draft state and stays live, minting one is a
+   * write. Under a locked {@link WriteLockProvider} the row stays in the list, dimmed and
+   * passed over by the arrows, with the lock's reason as its second line (a hover is the
+   * one explanation a phone cannot show), and `onCreate` is not called. Not needed with
+   * `commit`: a locked field opens no list at all.
+   */
+  createCommit?: boolean;
+  /**
+   * The `<input>` — the focusable control, the one a reader types in — as a React 19
+   * ref prop (0.24, kastlan). Its account picker is this component inside an
+   * `RhfField` render, and react-hook-form's focus-on-error calls `focus()` on whatever
+   * `field.ref` is handed: with no ref there was nothing to hand it, so a line-item form
+   * whose account was missing failed its submit and left the caret where it was. Pass
+   * `field.ref` here, or use `RhfInlineEntityCombobox`, which does. The wrapper is not
+   * reachable this way — focus and selection are the input's. See {@link Combobox}'s `ref`.
+   */
+  ref?: Ref<HTMLInputElement>;
 }
 
 /**
@@ -749,34 +925,45 @@ export interface InlineEntityComboboxProps<V extends string | number, C extends
  * sheet that emptied it to show the full list would read as "the user cleared the
  * field" the moment it closed.
  */
-export function InlineEntityCombobox<V extends string | number, C extends ComboClearValue = null>({
-  value: rawValue,
-  onChange,
-  clearValue = null as C,
-  options,
-  label,
-  id,
-  placeholder,
-  className,
-  disabled,
-  autoFocus,
-  searchPlaceholder,
-  emptyLabel,
-  closeLabel,
-  clearable,
-  clearLabel,
-  invalid,
-  error,
-  hint,
-  "aria-label": ariaLabel,
-  // Off `rest` and onto the <input>, which is the combobox a reader meets: `Field`'s
-  // render-prop spreads `{ id, aria-describedby, aria-invalid, aria-required }`, and
-  // on the wrapper div the hint and required state described nothing.
-  "aria-describedby": ariaDescribedBy,
-  "aria-invalid": ariaInvalid,
-  "aria-required": ariaRequired,
-  ...rest
-}: InlineEntityComboboxProps<V, C>) {
+export function InlineEntityCombobox<V extends string | number, C extends ComboClearValue = null>(
+  props: InlineEntityComboboxProps<V, C>,
+) {
+  const {
+    value: rawValue,
+    onChange,
+    clearValue = null as C,
+    options,
+    label,
+    id,
+    placeholder,
+    className,
+    disabled,
+    autoFocus,
+    searchPlaceholder,
+    emptyLabel,
+    closeLabel,
+    sheetTitle,
+    clearable,
+    clearLabel,
+    disabledReason,
+    commit,
+    onCreate,
+    createLabel,
+    createEmptyLabel,
+    createCommit,
+    invalid,
+    error,
+    hint,
+    ref,
+    "aria-label": ariaLabel,
+    // Off `rest` and onto the <input>, which is the combobox a reader meets: `Field`'s
+    // render-prop spreads `{ id, aria-describedby, aria-invalid, aria-required }`, and
+    // on the wrapper div the hint and required state described nothing.
+    "aria-describedby": ariaDescribedBy,
+    "aria-invalid": ariaInvalid,
+    "aria-required": ariaRequired,
+    ...rest
+  } = props;
   // The clear value reads as "nothing selected", whichever one the caller picked —
   // so from here down `value` is the id or `null`, as it always was.
   const value: V | null = rawValue == null || rawValue === clearValue ? null : (rawValue as V);
@@ -812,7 +999,21 @@ export function InlineEntityCombobox<V extends string | number, C extends ComboC
     search: searchPlaceholder,
     noResults: emptyLabel,
     clear: clearLabel,
+    create: createLabel,
   });
+  // The lock (see `lockedKeyDown` above). A lock arriving mid-edit closes the list and
+  // drops the loose text, adjusted while rendering: nothing typed before it may be
+  // judged by `reconcile` after it.
+  const lock = useLockReason(commit, disabledReason);
+  const locked = lock.locked;
+  const inert = locked || Boolean(disabled);
+  if (locked && (open || text !== null)) {
+    setOpen(false);
+    setText(null);
+  }
+  // The create row's own lock (`createCommit`): the list stays live, the row does not.
+  const createReason = useCommitReason(createCommit, undefined);
+  const createLocked = hasMessage(createReason);
 
   const selected = useMemo(
     () => (value == null ? null : (options.find((o) => o.value === value) ?? null)),
@@ -821,7 +1022,7 @@ export function InlineEntityCombobox<V extends string | number, C extends ComboC
   const shown = text ?? selected?.label ?? "";
   // Nothing selected has nothing to clear, and the chevron comes back — the field
   // keeps exactly one trailing control, so the "×" never crowds the value it sits on.
-  const showClear = Boolean(clearable && value != null && !disabled);
+  const showClear = Boolean(clearable && value != null && !inert);
 
   // Focusing select-alls the current label; filtering only kicks in once the
   // text actually differs from it, so an already-filled field still opens on
@@ -855,11 +1056,35 @@ export function InlineEntityCombobox<V extends string | number, C extends ComboC
     return [...blocks.values()].flat();
   }, [options, query]);
 
+  // The create row (`onCreate`), on the query as typed — not lowercased: it becomes a
+  // name. Compared against EVERY option, not `matches`: an exact hit anywhere is a
+  // record that exists, disabled or not. Restated from `text` rather than derived from
+  // `typedQuery`: this value is handed to the caller's `onCreate`, and the React
+  // Compiler cannot then keep `matches` memoised on anything it was derived from.
+  const createQuery = isPhone
+    ? sheetQuery.trim()
+    : text !== null && text !== (selected?.label ?? "")
+      ? text.trim()
+      : "";
+  const showCreate = offersCreate(
+    onCreate,
+    createQuery,
+    options.map((o) => o.label),
+    createEmptyLabel,
+  );
+  const createText = createQuery ? labels.create(createQuery) : createEmptyLabel;
+  // Every row the keyboard can land on: the options, then the create row — passed over
+  // like a disabled option while a write lock holds it.
+  const rows: readonly { disabled?: boolean }[] = showCreate
+    ? [...matches, { disabled: createLocked }]
+    : matches;
+  const createIndex = matches.length;
+
   // Pointer-device only: the phone's rows live in a {@link PickerSheet} whose own
   // search box holds focus, so the field behind it must not claim to be pointing at
   // one of them.
   // A disabled row is never the keyboard's, even if the list changed under it.
-  const activeId = !isPhone && isOptionEnabled(matches[active]) ? optionId(active) : undefined;
+  const activeId = !isPhone && isOptionEnabled(rows[active]) ? optionId(active) : undefined;
   useActiveOptionScroll(activeId);
 
   const close = () => {
@@ -867,9 +1092,10 @@ export function InlineEntityCombobox<V extends string | number, C extends ComboC
     setActive(-1);
     setSheetQuery("");
   };
-  const commit = (o: ComboOption<V>) => {
-    // A `disabled` option is listed, never taken — by any path.
-    if (o.disabled) return;
+  const take = (o: ComboOption<V>) => {
+    // A `disabled` option is listed, never taken — by any path; nor is anything while
+    // the field is locked.
+    if (o.disabled || locked) return;
     if (o.value !== value) onChange(o.value);
     setText(null);
     close();
@@ -884,8 +1110,15 @@ export function InlineEntityCombobox<V extends string | number, C extends ComboC
    *  used, then tabbing away, silently discarded it, and the more categories you used
    *  the more of them stopped working. Two rows naming the same id are not an ambiguity;
    *  two ids sharing a label are. */
+  const create = () => {
+    if (!onCreate || locked || createLocked) return;
+    onCreate(createQuery);
+    setText(null);
+    close();
+  };
   const reconcile = () => {
-    if (text !== null) {
+    // Locked, loose text is dropped rather than judged: nothing reaches `onChange`.
+    if (text !== null && !locked) {
       const q = text.trim();
       if (!q) {
         if (value != null) onChange(clearValue);
@@ -898,11 +1131,36 @@ export function InlineEntityCombobox<V extends string | number, C extends ComboC
         const ids = new Set(hits.map((h) => h.value));
         if (ids.size === 1 && hits[0].value !== value) onChange(hits[0].value);
       }
-      setText(null);
     }
+    setText(null);
     close();
   };
 
+  // The create row's inside, one for both shells: a "+" (it is an action, not a record),
+  // the words, and — while a write lock holds it — the lock's reason as a second line.
+  const createRowContent = (
+    <>
+      <Plus aria-hidden className="size-4 shrink-0" />
+      <span className="min-w-0 flex-1">
+        <span className="block truncate">{createText}</span>
+        {createLocked && (
+          <span className="block truncate text-xs font-normal text-[var(--text-placeholder)]">
+            {createReason}
+          </span>
+        )}
+      </span>
+    </>
+  );
+  // While locked the field sits in the reason's Tooltip — see Combobox.
+  const withLock = (box: ReactNode) =>
+    locked ? (
+      <LockedReason lock={lock} className="block">
+        {box}
+      </LockedReason>
+    ) : (
+      box
+    );
+
   return (
     // `rest` dresses the outer box — a `data-tour` anchor, a test id. Not the NAME,
     // description, invalid or required state: those belong on the <input> below,
@@ -911,152 +1169,163 @@ export function InlineEntityCombobox<V extends string | number, C extends ComboC
     <div {...rest} ref={wrapperRef} className={cn("relative", className)}>
       {/* A real <label for> — see {@link Combobox}; with a "?", in a row after the field. */}
       {label !== undefined && hintParts.labelHint === undefined && (
-        <ComboboxFieldLabel htmlFor={fieldId} className={disabled ? "opacity-50" : undefined}>
+        <ComboboxFieldLabel htmlFor={fieldId} className={inert ? "opacity-50" : undefined}>
           {label}
         </ComboboxFieldLabel>
       )}
-      <EndHintRow hint={label === undefined ? hintParts.labelHint : undefined}>
-        {/* Inner wrapper for chevron centering — same reasoning as Combobox above.
-            It is also what the portalled list anchors to. */}
-        {/* Dimmed as a whole when disabled, the way EntityCombobox dims its trigger.
-            FIELD_BASE's grey alone left a disabled picker looking like a filled-in
-            one beside the pickers that do dim (the label is not the input's `peer`,
-            so it is dimmed by hand above). */}
-        <div ref={fieldRef} className={cn("relative", disabled && "cursor-not-allowed opacity-50")}>
-          <input
-            id={fieldId}
-            value={shown}
-            placeholder={placeholder}
-            // The caller's name, over the <label for> above. Just the label, never
-            // "label: value" the way a trigger button has to compose it: an input
-            // already exposes its value separately.
-            aria-label={ariaLabel}
-            role="combobox"
-            aria-expanded={open}
-            // Required by the role, and the half that was missing: the field said it
-            // was expanded and never said what it had expanded (ESLint's
-            // `role-has-required-aria-props`, the audit's §a11y).
-            aria-controls={listboxId}
-            aria-activedescendant={activeId}
-            aria-autocomplete="list"
-            aria-invalid={field.isInvalid || undefined}
-            aria-describedby={field.describedBy}
-            aria-required={ariaRequired}
-            autoComplete="off"
-            disabled={disabled}
-            // eslint-disable-next-line jsx-a11y/no-autofocus -- a documented prop the caller opts into (off by default); the field never takes focus on its own.
-            autoFocus={autoFocus}
-            // `inputMode="none"` rather than readOnly, for the same reason Combobox
-            // above gives: the sheet carries the keyboard, and a readOnly field would
-            // take FIELD_BASE's settled look on a field that is perfectly editable.
-            inputMode={isPhone ? "none" : undefined}
-            onMouseDown={primaryOnly.onMouseDown}
-            onFocus={(e) => {
-              // See {@link usePrimaryPressOnly}: a back/forward button lands here on
-              // its way to navigating, and neither the list nor the select-all is
-              // anything it asked for (live #309 rework).
-              if (primaryOnly.fromAuxButton()) return;
-              setText(shown);
-              e.currentTarget.select();
-              setOpen(true);
-              // The sheet has its own input; the field behind it must not also pull up
-              // the keyboard and scroll the page under the dialog.
-              if (isPhone) sheetInputRef.current?.focus();
-            }}
-            onBlur={() => {
-              // On a phone the blur is the SHEET taking focus, not the user leaving the
-              // field — reconciling there would close the sheet the instant it opened.
-              if (!isPhone) reconcile();
-            }}
-            onChange={(e) => {
-              setText(e.target.value);
-              setOpen(true);
-              setActive(-1);
-            }}
-            onKeyDown={(e) => {
-              // Disabled rows are passed over; Up from "nothing highlighted" lands on
-              // the first takeable row, as it always landed on row 0.
-              if (e.key === "ArrowDown") {
-                e.preventDefault();
+      <EndHintRow {...endHintRowProps("hint" in props, label !== undefined, hintParts.labelHint)}>
+        {withLock(
+          /* Inner wrapper for chevron centering — same reasoning as Combobox above.
+              It is also what the portalled list anchors to.
+              Dimmed as a whole when disabled (or locked), the way EntityCombobox dims its
+              trigger. FIELD_BASE's grey alone left a disabled picker looking like a
+              filled-in one beside the pickers that do dim (the label is not the input's
+              `peer`, so it is dimmed by hand above). */
+          <div ref={fieldRef} className={cn("relative", inert && "cursor-not-allowed opacity-50")}>
+            <input
+              ref={ref}
+              id={fieldId}
+              value={shown}
+              placeholder={placeholder}
+              // The caller's name, over the <label for> above. Just the label, never
+              // "label: value" the way a trigger button has to compose it: an input
+              // already exposes its value separately.
+              aria-label={ariaLabel}
+              role="combobox"
+              aria-expanded={open}
+              // Required by the role, and the half that was missing: the field said it
+              // was expanded and never said what it had expanded (ESLint's
+              // `role-has-required-aria-props`, the audit's §a11y).
+              aria-controls={listboxId}
+              aria-activedescendant={activeId}
+              aria-autocomplete="list"
+              aria-invalid={field.isInvalid || undefined}
+              aria-describedby={mergeDescribedBy(field.describedBy, locked && lock.reasonId)}
+              aria-required={ariaRequired}
+              autoComplete="off"
+              // Locked: focusable, `readOnly`, `aria-disabled` — see `lockedKeyDown`.
+              disabled={locked ? undefined : disabled}
+              readOnly={locked || undefined}
+              aria-disabled={locked || undefined}
+              // eslint-disable-next-line jsx-a11y/no-autofocus -- a documented prop the caller opts into (off by default); the field never takes focus on its own.
+              autoFocus={autoFocus}
+              // `inputMode="none"` rather than readOnly, for the same reason Combobox
+              // above gives: the sheet carries the keyboard, and a readOnly field would
+              // take FIELD_BASE's settled look on a field that is perfectly editable.
+              inputMode={isPhone ? "none" : undefined}
+              onMouseDown={primaryOnly.onMouseDown}
+              onFocus={(e) => {
+                // See {@link usePrimaryPressOnly}: a back/forward button lands here on
+                // its way to navigating, and neither the list nor the select-all is
+                // anything it asked for (live #309 rework). A locked field takes focus to
+                // say why, and opens nothing.
+                if (primaryOnly.fromAuxButton() || locked) return;
+                setText(shown);
+                e.currentTarget.select();
                 setOpen(true);
-                setActive((i) => stepEnabled(matches, i, 1));
-              } else if (e.key === "ArrowUp") {
-                e.preventDefault();
-                setActive((i) => (i < 0 ? stepEnabled(matches, -1, 1) : stepEnabled(matches, i, -1)));
-              } else if (e.key === "Enter") {
-                if (open && isOptionEnabled(matches[active])) {
+                // The sheet has its own input; the field behind it must not also pull up
+                // the keyboard and scroll the page under the dialog.
+                if (isPhone) sheetInputRef.current?.focus();
+              }}
+              onBlur={() => {
+                // On a phone the blur is the SHEET taking focus, not the user leaving the
+                // field — reconciling there would close the sheet the instant it opened.
+                if (!isPhone) reconcile();
+              }}
+              onChange={(e) => {
+                if (locked) return;
+                setText(e.target.value);
+                setOpen(true);
+                setActive(-1);
+              }}
+              onKeyDown={(e) => {
+                if (locked) return lockedKeyDown(e);
+                // Disabled rows are passed over; Up from "nothing highlighted" lands on
+                // the first takeable row, as it always landed on row 0. The create row is
+                // the last row the arrows reach.
+                if (e.key === "ArrowDown") {
                   e.preventDefault();
-                  commit(matches[active]);
-                } else {
+                  setOpen(true);
+                  setActive((i) => stepEnabled(rows, i, 1));
+                } else if (e.key === "ArrowUp") {
+                  e.preventDefault();
+                  setActive((i) => (i < 0 ? stepEnabled(rows, -1, 1) : stepEnabled(rows, i, -1)));
+                } else if (e.key === "Enter") {
+                  if (open && isOptionEnabled(rows[active])) {
+                    e.preventDefault();
+                    if (active === createIndex && showCreate) create();
+                    else take(matches[active]);
+                  } else {
+                    reconcile();
+                  }
+                } else if (e.key === "Escape") {
+                  setText(null);
+                  close();
+                } else if (e.key === "Tab") {
+                  // Focus is in THIS input and stays there, so the browser's own Tab is
+                  // left alone; all that is needed is that the list stop covering what
+                  // the user is tabbing to. `reconcile` rather than `close`, because
+                  // leaving the field is exactly when loose text has to be judged.
                   reconcile();
                 }
-              } else if (e.key === "Escape") {
-                setText(null);
-                close();
-              } else if (e.key === "Tab") {
-                // Focus is in THIS input and stays there, so the browser's own Tab is
-                // left alone; all that is needed is that the list stop covering what
-                // the user is tabbing to. `reconcile` rather than `close`, because
-                // leaving the field is exactly when loose text has to be judged.
-                reconcile();
-              }
-              // Home/End stay with the caret — see the note in {@link Combobox}: this
-              // field is editable, and its text is what `reconcile` judges.
-            }}
-            className={cn(
-              FIELD_BASE,
-              label !== undefined && FIELD_FLOATING_PAD,
-              "pe-9",
-              field.isInvalid && FIELD_INVALID,
-            )}
-          />
-          {showClear ? (
-            <button
-              type="button"
-              // Out of the tab order, like the clear on `EntityCombobox`: the keyboard
-              // already clears this field by selecting its text and deleting, and a
-              // second stop between every picker and the next field is a worse trade
-              // than the one gesture it saves.
-              tabIndex={-1}
-              aria-label={labels.clear}
-              // preventDefault, exactly as the chevron does: without it the press
-              // focuses the input, which on a phone opens the sheet over the field the
-              // press was clearing.
-              onMouseDown={(e) => e.preventDefault()}
-              onClick={() => {
-                setText(null);
-                close();
-                onChange(clearValue);
+                // Home/End stay with the caret — see the note in {@link Combobox}: this
+                // field is editable, and its text is what `reconcile` judges.
               }}
               className={cn(
-                "absolute end-2 top-1/2 -translate-y-1/2 rounded p-0.5 text-[var(--text-placeholder)]",
-                "hover:text-[var(--text-secondary)]",
-              )}
-            >
-              <X aria-hidden className="size-4" />
-            </button>
-          ) : (
-            <ChevronDown
-              aria-hidden
-              onMouseDown={(e) => {
-                // Toggle on the chevron without stealing focus from the input — and
-                // not at all on a disabled field, which the input's own `disabled`
-                // does not stop from here.
-                e.preventDefault();
-                if (!disabled) setOpen((o) => !o);
-              }}
-              className={cn(
-                "absolute end-2.5 top-1/2 size-4 -translate-y-1/2 text-[var(--text-placeholder)]",
-                // The box above does the dimming; dimming here too would halve it again.
-                !disabled && "cursor-pointer",
+                FIELD_BASE,
+                label !== undefined && FIELD_FLOATING_PAD,
+                "pe-9",
+                field.isInvalid && FIELD_INVALID,
               )}
             />
-          )}
-        </div>
+            {showClear ? (
+              <button
+                type="button"
+                // Out of the tab order, like the clear on `EntityCombobox`: the keyboard
+                // already clears this field by selecting its text and deleting, and a
+                // second stop between every picker and the next field is a worse trade
+                // than the one gesture it saves.
+                tabIndex={-1}
+                aria-label={labels.clear}
+                // preventDefault, exactly as the chevron does: without it the press
+                // focuses the input, which on a phone opens the sheet over the field the
+                // press was clearing.
+                onMouseDown={(e) => e.preventDefault()}
+                onClick={() => {
+                  setText(null);
+                  close();
+                  if (!locked) onChange(clearValue);
+                }}
+                className={cn(
+                  "absolute end-2 top-1/2 -translate-y-1/2 rounded p-0.5 text-[var(--text-placeholder)]",
+                  "hover:text-[var(--text-secondary)]",
+                )}
+              >
+                <X aria-hidden className="size-4" />
+              </button>
+            ) : (
+              <ChevronDown
+                aria-hidden
+                onMouseDown={(e) => {
+                  // Toggle on the chevron without stealing focus from the input — and
+                  // not at all on a disabled or locked field, which the input's own
+                  // `disabled`/`readOnly` does not stop from here.
+                  e.preventDefault();
+                  if (!inert) setOpen((o) => !o);
+                }}
+                className={cn(
+                  "absolute end-2.5 top-1/2 size-4 -translate-y-1/2 text-[var(--text-placeholder)]",
+                  // The box above does the dimming; dimming here too would halve it again.
+                  !inert && "cursor-pointer",
+                )}
+              />
+            )}
+          </div>,
+        )}
       </EndHintRow>
       {label !== undefined && hintParts.labelHint !== undefined && (
         <StaticLabelRow hint={hintParts.labelHint}>
-          <ComboboxFieldLabel htmlFor={fieldId} className={cn(LABEL_IN_ROW, disabled && "opacity-50")}>
+          <ComboboxFieldLabel htmlFor={fieldId} className={cn(LABEL_IN_ROW, inert && "opacity-50")}>
             {label}
           </ComboboxFieldLabel>
         </StaticLabelRow>
@@ -1065,11 +1334,11 @@ export function InlineEntityCombobox<V extends string | number, C extends ComboC
       {field.errorEl}
       {isPhone && (
         <PickerSheet
-          open={open && !disabled}
+          open={open && !inert}
           // Closing without choosing keeps the value: `text` was never emptied, so
           // reconcile has nothing to undo — it just puts the label back.
           onClose={reconcile}
-          title={label}
+          title={sheetTitle ?? label}
           query={sheetQuery}
           onQueryChange={(v) => {
             setSheetQuery(v);
@@ -1099,7 +1368,7 @@ export function InlineEntityCombobox<V extends string | number, C extends ComboC
                     role="option"
                     aria-selected={o.value === value}
                     aria-disabled={o.disabled || undefined}
-                    onClick={() => commit(o)}
+                    onClick={() => take(o)}
                     className={cn(
                       SHEET_ROW_CLASS,
                       o.value === value && "font-medium",
@@ -1111,13 +1380,34 @@ export function InlineEntityCombobox<V extends string | number, C extends ComboC
                 </li>
               </Fragment>
             ))}
-            {matches.length === 0 && (
+            {showCreate && (
+              <li role="presentation">
+                <button
+                  type="button"
+                  role="option"
+                  // An action, never chosen — see `onCreate`.
+                  aria-selected={false}
+                  aria-disabled={createLocked || undefined}
+                  onClick={create}
+                  className={cn(
+                    SHEET_ROW_CLASS,
+                    CREATE_ROW_CLASS,
+                    createLocked && DISABLED_ROW_CLASS,
+                  )}
+                >
+                  {createRowContent}
+                </button>
+              </li>
+            )}
+            {/* "Nothing matched" only when there is nothing to do either: with a create
+                row the list is not empty, it is offering to fill itself. */}
+            {matches.length === 0 && !showCreate && (
               <li className="px-4 py-3 text-sm text-[var(--text-muted)]">{labels.noResults}</li>
             )}
           </ul>
         </PickerSheet>
       )}
-      {!isPhone && open && !disabled && matches.length > 0 && (
+      {!isPhone && open && !inert && (matches.length > 0 || showCreate) && (
         <SuggestionList id={listboxId} anchorRef={fieldRef} panelRef={panelRef}>
           {matches.map((o, i) => (
             // A group heading is emitted at each group boundary rather than repeating
@@ -1151,7 +1441,7 @@ export function InlineEntityCombobox<V extends string | number, C extends ComboC
                     // list before the selection registers. Prevented on a disabled
                     // row too, so pressing one leaves the field focused and open.
                     e.preventDefault();
-                    commit(o);
+                    take(o);
                   }}
                   onMouseEnter={() => {
                     if (!o.disabled) setActive(i);
@@ -1175,6 +1465,36 @@ export function InlineEntityCombobox<V extends string | number, C extends ComboC
               </li>
             </Fragment>
           ))}
+          {showCreate && (
+            <li role="presentation">
+              <button
+                type="button"
+                id={optionId(createIndex)}
+                role="option"
+                // An action, never chosen; whether the keyboard is ON it is the field's
+                // `aria-activedescendant`'s to say.
+                aria-selected={false}
+                aria-disabled={createLocked || undefined}
+                tabIndex={-1}
+                onMouseDown={(e) => {
+                  // mousedown, like the rows above: the input's blur would otherwise
+                  // reconcile and close the list before the click landed.
+                  e.preventDefault();
+                  create();
+                }}
+                onMouseEnter={() => {
+                  if (!createLocked) setActive(createIndex);
+                }}
+                className={cn(
+                  rowClass(active === createIndex && !createLocked),
+                  CREATE_ROW_CLASS,
+                  createLocked && DISABLED_ROW_CLASS,
+                )}
+              >
+                {createRowContent}
+              </button>
+            </li>
+          )}
         </SuggestionList>
       )}
     </div>