@eifi1/ui-kit 0.21.0 → 0.23.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 { 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,6 +24,17 @@ import {
   type ComboOption,
 } from "./combobox-core";
 import { DEFAULT_COMBOBOX_LABELS, useKitLabels } from "../i18n/kit-labels";
+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
@@ -123,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
@@ -149,10 +183,31 @@ export interface ComboboxProps
    *  field, on the `<input>`'s `aria-describedby`, and implies `invalid` (lenkbank's
    *  scope fields, which moved here off `<Input list>` + `<datalist>`). */
   error?: ReactNode;
+  /**
+   * Standing advice for the field — {@link Input}'s `hint`, so the combobox family
+   * reads like every other field (keksdose K4: the family had `error` and no `hint`, so
+   * the app's pickers carried their captions outside the component, attached to
+   * nothing). Plain TEXT is a caption under the field on the input's
+   * `aria-describedby`, before any error; a {@link FieldHint} "?" rides the label line,
+   * or with no label sits at the field's end edge, outside the box.
+   */
+  hint?: ReactNode;
   /** As `<input disabled>`: no focus, no list, the field's settled look. The chevron
    *  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
@@ -217,39 +272,44 @@ 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,
-  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,
+    createLabel,
+    invalid,
+    error,
+    hint,
+    disabled,
+    disabledReason,
+    commit,
+    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
+  } = props;
+  const hintParts = useFieldHint(hint, ariaDescribedBy);
   const field = useComboboxFieldError(
     error,
     invalid || ariaInvalid === true || ariaInvalid === "true",
-    ariaDescribedBy,
+    hintParts.describedBy,
   );
   const generated = useId();
   const fieldId = id ?? generated;
@@ -264,6 +324,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
@@ -349,7 +415,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);
@@ -369,6 +436,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())
@@ -383,138 +461,160 @@ export function Combobox({
     <div {...rest} ref={wrapperRef} className={cn("relative", className)}>
       {/* A real <label for> since lenkbank's tests met a field `getByLabelText` could
           not find: it used to be a <span>, with the text copied onto `aria-label`. The
-          name a reader hears is the same words either way. */}
-      {label !== undefined && (
-        <ComboboxFieldLabel htmlFor={fieldId} className={disabled ? "opacity-50" : undefined}>
+          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={inert ? "opacity-50" : undefined}>
           {label}
         </ComboboxFieldLabel>
       )}
-      {/* 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();
-              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) {
+      <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
+              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);
+                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();
+                  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);
+                  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();
-                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();
-                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);
-              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>
+                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, inert && "opacity-50")}>
+            {label}
+          </ComboboxFieldLabel>
+        </StaticLabelRow>
+      )}
+      <FieldCaption parts={hintParts} />
       {field.errorEl}
       {isPhone && (
         <PickerSheet
-          open={open && !disabled}
+          open={open && !inert}
           onClose={() => setOpen(false)}
           title={label}
           // The sheet's input IS the field: this is a free-text control, so what is
@@ -539,7 +639,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}
@@ -563,7 +663,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",
@@ -579,7 +679,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">
@@ -592,7 +692,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)]")}
               >
@@ -632,7 +732,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(
@@ -667,6 +767,8 @@ export interface InlineEntityComboboxProps<V extends string | number, C extends
   invalid?: boolean;
   /** What is wrong with the value — see {@link Combobox}'s `error`. */
   error?: ReactNode;
+  /** Standing advice — see {@link Combobox}'s `hint` (keksdose K4). */
+  hint?: ReactNode;
   /** A picked/typed option emits its id; emptying the field, or the "×", emits
    *  `clearValue`. */
   onChange: (v: V | C) => void;
@@ -702,6 +804,72 @@ 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;
 }
 
 /**
@@ -722,40 +890,51 @@ 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,
-  "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,
+    clearable,
+    clearLabel,
+    disabledReason,
+    commit,
+    onCreate,
+    createLabel,
+    createEmptyLabel,
+    createCommit,
+    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
+  } = 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);
+  const hintParts = useFieldHint(hint, ariaDescribedBy);
   const field = useComboboxFieldError(
     error,
     invalid || ariaInvalid === true || ariaInvalid === "true",
-    ariaDescribedBy,
+    hintParts.describedBy,
   );
   const generated = useId();
   const fieldId = id ?? generated;
@@ -783,7 +962,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)),
@@ -792,7 +985,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
@@ -826,11 +1019,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 = () => {
@@ -838,9 +1055,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();
@@ -855,8 +1073,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);
@@ -869,164 +1094,209 @@ 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,
     // which is the combobox a reader meets. Spread FIRST, so the field's ARIA and the
     // handlers carrying live #309 and dev#549 cannot be replaced from outside.
     <div {...rest} ref={wrapperRef} className={cn("relative", className)}>
-      {/* A real <label for> — see {@link Combobox}. */}
-      {label !== undefined && (
-        <ComboboxFieldLabel htmlFor={fieldId} className={disabled ? "opacity-50" : undefined}>
+      {/* A real <label for> — see {@link Combobox}; with a "?", in a row after the field. */}
+      {label !== undefined && hintParts.labelHint === undefined && (
+        <ComboboxFieldLabel htmlFor={fieldId} className={inert ? "opacity-50" : undefined}>
           {label}
         </ComboboxFieldLabel>
       )}
-      {/* 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();
-              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])) {
-                e.preventDefault();
-                commit(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();
-            }
-            // 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);
-            }}
-            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",
+      <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
+              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);
+                // 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();
+                  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();
+                }
+                // 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();
+                  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>,
         )}
-      </div>
+      </EndHintRow>
+      {label !== undefined && hintParts.labelHint !== undefined && (
+        <StaticLabelRow hint={hintParts.labelHint}>
+          <ComboboxFieldLabel htmlFor={fieldId} className={cn(LABEL_IN_ROW, inert && "opacity-50")}>
+            {label}
+          </ComboboxFieldLabel>
+        </StaticLabelRow>
+      )}
+      <FieldCaption parts={hintParts} />
       {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}
@@ -1060,7 +1330,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",
@@ -1072,13 +1342,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
@@ -1112,7 +1403,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);
@@ -1136,6 +1427,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>