@eifi1/ui-kit 0.21.0 → 0.23.0

package/dist/components/combobox.js

@@ -1,8 +1,8 @@
 "use client";
-import { jsx, jsxs } from "react/jsx-runtime";
-import { Fragment, useId, useMemo, useRef, useState } from "react";
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+import { Fragment as Fragment2, useId, useMemo, useRef, useState } 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.js";
 import { cn } from "../lib/cn.js";
 import { useDropdown } from "./dropdown.js";
@@ -13,7 +13,9 @@ import { PickerSheet, SHEET_ROW_CLASS } from "./picker-sheet.js";
 import {
   ComboboxFieldLabel,
   DISABLED_ROW_CLASS,
+  endHintRowProps,
   isOptionEnabled,
+  offersCreate,
   stepEnabled,
   SUGGESTION_LIST_CLASS,
   suggestionRowClass,
@@ -21,6 +23,17 @@ import {
   useComboboxFieldError
 } from "./combobox-core.js";
 import { DEFAULT_COMBOBOX_LABELS, useKitLabels } from "../i18n/kit-labels.js";
+import {
+  EndHintRow,
+  FieldCaption,
+  LABEL_IN_ROW,
+  LockedReason,
+  StaticLabelRow,
+  useFieldHint,
+  useLockReason
+} from "./field-parts.js";
+import { hasMessage, mergeDescribedBy } from "./choice-parts.js";
+import { useCommitReason } from "./write-lock.js";
 const LIST_CLASS = SUGGESTION_LIST_CLASS;
 function usePrimaryPressOnly() {
   const auxPress = useRef(false);
@@ -60,39 +73,48 @@ function SuggestionList({
   );
 }
 const rowClass = suggestionRowClass;
-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
-}) {
+function lockedKeyDown(e) {
+  if (e.key === "Enter") e.preventDefault();
+}
+const CREATE_ROW_CLASS = "flex items-center gap-2 font-medium text-[var(--brand)]";
+function Combobox(props) {
+  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;
@@ -102,6 +124,10 @@ function Combobox({
   const { open, setOpen, wrapperRef, panelRef } = useDropdown({ backCloses: !isPhone });
   const primaryOnly = usePrimaryPressOnly();
   const [active, setActive] = useState(-1);
+  const lock = useLockReason(commit, disabledReason);
+  const locked = lock.locked;
+  const inert = locked || Boolean(disabled);
+  if (locked && open) setOpen(false);
   const sheetInputRef = useRef(null);
   const fieldRef = useRef(null);
   const [typing, setTyping] = useState(false);
@@ -140,7 +166,8 @@ function Combobox({
     });
     return heads;
   }, [matches, groupBy]);
-  const commit = (v) => {
+  const take = (v) => {
+    if (locked) return;
     onChange(v);
     setOpen(false);
     setActive(-1);
@@ -148,6 +175,7 @@ function Combobox({
   };
   const activeId = !isPhone && active >= 0 && active < matches.length ? optionId(active) : void 0;
   useActiveOptionScroll(activeId);
+  const withLock = (box) => locked ? /* @__PURE__ */ jsx(LockedReason, { lock, className: "block", children: box }) : box;
   const typed = value.trim();
   const createRow = createLabel && typed.length > 0 && !options.some((o) => o.toLowerCase() === typed.toLowerCase()) ? createLabel(typed) : null;
   return (
@@ -156,99 +184,117 @@ function Combobox({
     // 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.
     /* @__PURE__ */ jsxs("div", { ...rest, ref: wrapperRef, className: cn("relative", className), children: [
-      label !== void 0 && /* @__PURE__ */ jsx(ComboboxFieldLabel, { htmlFor: fieldId, className: disabled ? "opacity-50" : void 0, children: label }),
-      /* @__PURE__ */ jsxs("div", { ref: fieldRef, className: cn("relative", disabled && "cursor-not-allowed opacity-50"), children: [
-        /* @__PURE__ */ jsx(
-          "input",
-          {
-            id: fieldId,
-            value,
-            placeholder,
-            "aria-label": ariaLabel,
-            role: "combobox",
-            "aria-expanded": open,
-            "aria-controls": listboxId,
-            "aria-activedescendant": activeId,
-            "aria-autocomplete": "list",
-            "aria-invalid": field.isInvalid || void 0,
-            "aria-describedby": field.describedBy,
-            "aria-required": ariaRequired,
-            autoComplete: "off",
-            disabled,
-            autoFocus,
-            onBlur,
-            onMouseDown: primaryOnly.onMouseDown,
-            onFocus: () => {
-              if (primaryOnly.fromAuxButton()) return;
-              setOpen(true);
-              setTyping(false);
-              if (isPhone) sheetInputRef.current?.focus();
-            },
-            onClick: () => {
-              setOpen(true);
-              setTyping(false);
-            },
-            inputMode: isPhone ? "none" : void 0,
-            onChange: (e) => {
-              onChange(e.target.value);
-              setOpen(true);
-              setActive(-1);
-              setTyping(true);
-            },
-            onKeyDown: (e) => {
-              if (e.key === "ArrowDown") {
-                e.preventDefault();
+      label !== void 0 && hintParts.labelHint === void 0 && /* @__PURE__ */ jsx(ComboboxFieldLabel, { htmlFor: fieldId, className: inert ? "opacity-50" : void 0, children: label }),
+      /* @__PURE__ */ jsx(EndHintRow, { ...endHintRowProps("hint" in props, label !== void 0, hintParts.labelHint), children: 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). */
+        /* @__PURE__ */ jsxs("div", { ref: fieldRef, className: cn("relative", inert && "cursor-not-allowed opacity-50"), children: [
+          /* @__PURE__ */ jsx(
+            "input",
+            {
+              id: fieldId,
+              value,
+              placeholder,
+              "aria-label": ariaLabel,
+              role: "combobox",
+              "aria-expanded": open,
+              "aria-controls": listboxId,
+              "aria-activedescendant": activeId,
+              "aria-autocomplete": "list",
+              "aria-invalid": field.isInvalid || void 0,
+              "aria-describedby": mergeDescribedBy(field.describedBy, locked && lock.reasonId),
+              "aria-required": ariaRequired,
+              autoComplete: "off",
+              disabled: locked ? void 0 : disabled,
+              readOnly: locked || void 0,
+              "aria-disabled": locked || void 0,
+              autoFocus,
+              onBlur,
+              onMouseDown: primaryOnly.onMouseDown,
+              onFocus: () => {
+                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);
+                if (isPhone) sheetInputRef.current?.focus();
+              },
+              onClick: () => {
+                if (locked) return;
+                setOpen(true);
+                setTyping(false);
+              },
+              inputMode: isPhone ? "none" : void 0,
+              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 {
-                  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 {
+                    if (onSubmit) e.preventDefault();
+                    setOpen(false);
+                    onSubmit?.();
+                  }
+                } else if (e.key === "Escape") {
+                  setOpen(false);
+                  setActive(-1);
+                } else if (e.key === "Tab") {
                   setOpen(false);
-                  onSubmit?.();
+                  setActive(-1);
                 }
-              } else if (e.key === "Escape") {
-                setOpen(false);
-                setActive(-1);
-              } else if (e.key === "Tab") {
-                setOpen(false);
-                setActive(-1);
-              }
-            },
-            className: cn(
-              FIELD_BASE,
-              label !== void 0 && FIELD_FLOATING_PAD,
-              "pe-9",
-              field.isInvalid && FIELD_INVALID
-            )
-          }
-        ),
-        /* @__PURE__ */ jsx(
-          ChevronDown,
-          {
-            "aria-hidden": true,
-            onMouseDown: (e) => {
-              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"
-            )
-          }
-        )
-      ] }),
+              },
+              className: cn(
+                FIELD_BASE,
+                label !== void 0 && FIELD_FLOATING_PAD,
+                "pe-9",
+                field.isInvalid && FIELD_INVALID
+              )
+            }
+          ),
+          /* @__PURE__ */ jsx(
+            ChevronDown,
+            {
+              "aria-hidden": true,
+              onMouseDown: (e) => {
+                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"
+              )
+            }
+          )
+        ] })
+      ) }),
+      label !== void 0 && hintParts.labelHint !== void 0 && /* @__PURE__ */ jsx(StaticLabelRow, { hint: hintParts.labelHint, children: /* @__PURE__ */ jsx(ComboboxFieldLabel, { htmlFor: fieldId, className: cn(LABEL_IN_ROW, inert && "opacity-50"), children: label }) }),
+      /* @__PURE__ */ jsx(FieldCaption, { parts: hintParts }),
       field.errorEl,
       isPhone && /* @__PURE__ */ jsx(
         PickerSheet,
         {
-          open: open && !disabled,
+          open: open && !inert,
           onClose: () => setOpen(false),
           title: label,
           query: value,
@@ -269,14 +315,14 @@ 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)]"),
                 children: createRow
               }
             ) }),
             matches.map((o, i) => {
               const group = groupHeadings?.get(i);
-              return /* @__PURE__ */ jsxs(Fragment, { children: [
+              return /* @__PURE__ */ jsxs(Fragment2, { children: [
                 group !== void 0 && /* @__PURE__ */ jsx(
                   "li",
                   {
@@ -291,7 +337,7 @@ 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"
@@ -307,7 +353,7 @@ function Combobox({
           ] })
         }
       ),
-      !isPhone && open && !disabled && (matches.length > 0 || createRow) && /* @__PURE__ */ jsxs(SuggestionList, { id: listboxId, anchorRef: fieldRef, panelRef, children: [
+      !isPhone && open && !inert && (matches.length > 0 || createRow) && /* @__PURE__ */ jsxs(SuggestionList, { id: listboxId, anchorRef: fieldRef, panelRef, children: [
         createRow && /* @__PURE__ */ jsx("li", { role: "presentation", children: /* @__PURE__ */ jsx(
           "button",
           {
@@ -317,7 +363,7 @@ function Combobox({
             tabIndex: -1,
             onMouseDown: (e) => {
               e.preventDefault();
-              commit(typed);
+              take(typed);
             },
             className: cn(rowClass(false), "font-medium text-[var(--brand)]"),
             children: createRow
@@ -325,7 +371,7 @@ function Combobox({
         ) }),
         matches.map((o, i) => {
           const group = groupHeadings?.get(i);
-          return /* @__PURE__ */ jsxs(Fragment, { children: [
+          return /* @__PURE__ */ jsxs(Fragment2, { children: [
             group !== void 0 && /* @__PURE__ */ jsx(
               "li",
               {
@@ -344,7 +390,7 @@ function Combobox({
                 tabIndex: -1,
                 onMouseDown: (e) => {
                   e.preventDefault();
-                  commit(o);
+                  take(o);
                 },
                 onMouseEnter: () => setActive(i),
                 className: cn(
@@ -367,38 +413,47 @@ function Combobox({
     ] })
   );
 }
-function InlineEntityCombobox({
-  value: rawValue,
-  onChange,
-  clearValue = null,
-  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
-}) {
+function InlineEntityCombobox(props) {
+  const {
+    value: rawValue,
+    onChange,
+    clearValue = null,
+    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;
   const value = rawValue == null || rawValue === clearValue ? null : rawValue;
+  const hintParts = useFieldHint(hint, ariaDescribedBy);
   const field = useComboboxFieldError(
     error,
     invalid || ariaInvalid === true || ariaInvalid === "true",
-    ariaDescribedBy
+    hintParts.describedBy
   );
   const generated = useId();
   const fieldId = id ?? generated;
@@ -415,14 +470,24 @@ function InlineEntityCombobox({
   const labels = useKitLabels("combobox", DEFAULT_COMBOBOX_LABELS, {
     search: searchPlaceholder,
     noResults: emptyLabel,
-    clear: clearLabel
+    clear: clearLabel,
+    create: createLabel
   });
+  const lock = useLockReason(commit, disabledReason);
+  const locked = lock.locked;
+  const inert = locked || Boolean(disabled);
+  if (locked && (open || text !== null)) {
+    setOpen(false);
+    setText(null);
+  }
+  const createReason = useCommitReason(createCommit, void 0);
+  const createLocked = hasMessage(createReason);
   const selected = useMemo(
     () => value == null ? null : options.find((o) => o.value === value) ?? null,
     [options, value]
   );
   const shown = text ?? selected?.label ?? "";
-  const showClear = Boolean(clearable && value != null && !disabled);
+  const showClear = Boolean(clearable && value != null && !inert);
   const typedQuery = text !== null && text !== (selected?.label ?? "") ? text.trim().toLowerCase() : "";
   const query = isPhone ? sheetQuery.trim().toLowerCase() : typedQuery;
   const matches = useMemo(() => {
@@ -444,21 +509,37 @@ function InlineEntityCombobox({
     }
     return [...blocks.values()].flat();
   }, [options, query]);
-  const activeId = !isPhone && isOptionEnabled(matches[active]) ? optionId(active) : void 0;
+  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;
+  const rows = showCreate ? [...matches, { disabled: createLocked }] : matches;
+  const createIndex = matches.length;
+  const activeId = !isPhone && isOptionEnabled(rows[active]) ? optionId(active) : void 0;
   useActiveOptionScroll(activeId);
   const close = () => {
     setOpen(false);
     setActive(-1);
     setSheetQuery("");
   };
-  const commit = (o) => {
-    if (o.disabled) return;
+  const take = (o) => {
+    if (o.disabled || locked) return;
     if (o.value !== value) onChange(o.value);
     setText(null);
     close();
   };
+  const create = () => {
+    if (!onCreate || locked || createLocked) return;
+    onCreate(createQuery);
+    setText(null);
+    close();
+  };
   const reconcile = () => {
-    if (text !== null) {
+    if (text !== null && !locked) {
       const q = text.trim();
       if (!q) {
         if (value != null) onChange(clearValue);
@@ -469,122 +550,145 @@ function InlineEntityCombobox({
         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();
   };
+  const createRowContent = /* @__PURE__ */ jsxs(Fragment, { children: [
+    /* @__PURE__ */ jsx(Plus, { "aria-hidden": true, className: "size-4 shrink-0" }),
+    /* @__PURE__ */ jsxs("span", { className: "min-w-0 flex-1", children: [
+      /* @__PURE__ */ jsx("span", { className: "block truncate", children: createText }),
+      createLocked && /* @__PURE__ */ jsx("span", { className: "block truncate text-xs font-normal text-[var(--text-placeholder)]", children: createReason })
+    ] })
+  ] });
+  const withLock = (box) => locked ? /* @__PURE__ */ jsx(LockedReason, { lock, className: "block", children: box }) : 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.
     /* @__PURE__ */ jsxs("div", { ...rest, ref: wrapperRef, className: cn("relative", className), children: [
-      label !== void 0 && /* @__PURE__ */ jsx(ComboboxFieldLabel, { htmlFor: fieldId, className: disabled ? "opacity-50" : void 0, children: label }),
-      /* @__PURE__ */ jsxs("div", { ref: fieldRef, className: cn("relative", disabled && "cursor-not-allowed opacity-50"), children: [
-        /* @__PURE__ */ jsx(
-          "input",
-          {
-            id: fieldId,
-            value: shown,
-            placeholder,
-            "aria-label": ariaLabel,
-            role: "combobox",
-            "aria-expanded": open,
-            "aria-controls": listboxId,
-            "aria-activedescendant": activeId,
-            "aria-autocomplete": "list",
-            "aria-invalid": field.isInvalid || void 0,
-            "aria-describedby": field.describedBy,
-            "aria-required": ariaRequired,
-            autoComplete: "off",
-            disabled,
-            autoFocus,
-            inputMode: isPhone ? "none" : void 0,
-            onMouseDown: primaryOnly.onMouseDown,
-            onFocus: (e) => {
-              if (primaryOnly.fromAuxButton()) return;
-              setText(shown);
-              e.currentTarget.select();
-              setOpen(true);
-              if (isPhone) sheetInputRef.current?.focus();
-            },
-            onBlur: () => {
-              if (!isPhone) reconcile();
-            },
-            onChange: (e) => {
-              setText(e.target.value);
-              setOpen(true);
-              setActive(-1);
-            },
-            onKeyDown: (e) => {
-              if (e.key === "ArrowDown") {
-                e.preventDefault();
+      label !== void 0 && hintParts.labelHint === void 0 && /* @__PURE__ */ jsx(ComboboxFieldLabel, { htmlFor: fieldId, className: inert ? "opacity-50" : void 0, children: label }),
+      /* @__PURE__ */ jsx(EndHintRow, { ...endHintRowProps("hint" in props, label !== void 0, hintParts.labelHint), children: 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). */
+        /* @__PURE__ */ jsxs("div", { ref: fieldRef, className: cn("relative", inert && "cursor-not-allowed opacity-50"), children: [
+          /* @__PURE__ */ jsx(
+            "input",
+            {
+              id: fieldId,
+              value: shown,
+              placeholder,
+              "aria-label": ariaLabel,
+              role: "combobox",
+              "aria-expanded": open,
+              "aria-controls": listboxId,
+              "aria-activedescendant": activeId,
+              "aria-autocomplete": "list",
+              "aria-invalid": field.isInvalid || void 0,
+              "aria-describedby": mergeDescribedBy(field.describedBy, locked && lock.reasonId),
+              "aria-required": ariaRequired,
+              autoComplete: "off",
+              disabled: locked ? void 0 : disabled,
+              readOnly: locked || void 0,
+              "aria-disabled": locked || void 0,
+              autoFocus,
+              inputMode: isPhone ? "none" : void 0,
+              onMouseDown: primaryOnly.onMouseDown,
+              onFocus: (e) => {
+                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])) {
+                if (isPhone) sheetInputRef.current?.focus();
+              },
+              onBlur: () => {
+                if (!isPhone) reconcile();
+              },
+              onChange: (e) => {
+                if (locked) return;
+                setText(e.target.value);
+                setOpen(true);
+                setActive(-1);
+              },
+              onKeyDown: (e) => {
+                if (locked) return lockedKeyDown(e);
+                if (e.key === "ArrowDown") {
+                  e.preventDefault();
+                  setOpen(true);
+                  setActive((i) => stepEnabled(rows, i, 1));
+                } else if (e.key === "ArrowUp") {
                   e.preventDefault();
-                  commit(matches[active]);
-                } else {
+                  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") {
                   reconcile();
                 }
-              } else if (e.key === "Escape") {
+              },
+              className: cn(
+                FIELD_BASE,
+                label !== void 0 && FIELD_FLOATING_PAD,
+                "pe-9",
+                field.isInvalid && FIELD_INVALID
+              )
+            }
+          ),
+          showClear ? /* @__PURE__ */ jsx(
+            "button",
+            {
+              type: "button",
+              tabIndex: -1,
+              "aria-label": labels.clear,
+              onMouseDown: (e) => e.preventDefault(),
+              onClick: () => {
                 setText(null);
                 close();
-              } else if (e.key === "Tab") {
-                reconcile();
-              }
-            },
-            className: cn(
-              FIELD_BASE,
-              label !== void 0 && FIELD_FLOATING_PAD,
-              "pe-9",
-              field.isInvalid && FIELD_INVALID
-            )
-          }
-        ),
-        showClear ? /* @__PURE__ */ jsx(
-          "button",
-          {
-            type: "button",
-            tabIndex: -1,
-            "aria-label": labels.clear,
-            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)]"
-            ),
-            children: /* @__PURE__ */ jsx(X, { "aria-hidden": true, className: "size-4" })
-          }
-        ) : /* @__PURE__ */ jsx(
-          ChevronDown,
-          {
-            "aria-hidden": true,
-            onMouseDown: (e) => {
-              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"
-            )
-          }
-        )
-      ] }),
+                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)]"
+              ),
+              children: /* @__PURE__ */ jsx(X, { "aria-hidden": true, className: "size-4" })
+            }
+          ) : /* @__PURE__ */ jsx(
+            ChevronDown,
+            {
+              "aria-hidden": true,
+              onMouseDown: (e) => {
+                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"
+              )
+            }
+          )
+        ] })
+      ) }),
+      label !== void 0 && hintParts.labelHint !== void 0 && /* @__PURE__ */ jsx(StaticLabelRow, { hint: hintParts.labelHint, children: /* @__PURE__ */ jsx(ComboboxFieldLabel, { htmlFor: fieldId, className: cn(LABEL_IN_ROW, inert && "opacity-50"), children: label }) }),
+      /* @__PURE__ */ jsx(FieldCaption, { parts: hintParts }),
       field.errorEl,
       isPhone && /* @__PURE__ */ jsx(
         PickerSheet,
         {
-          open: open && !disabled,
+          open: open && !inert,
           onClose: reconcile,
           title: label,
           query: sheetQuery,
@@ -600,7 +704,7 @@ function InlineEntityCombobox({
               // Keyed by group AND value, like combobox-core.tsx: an option may
               // deliberately appear twice (see `reconcile`), and a bare value key
               // would collide.
-              /* @__PURE__ */ jsxs(Fragment, { children: [
+              /* @__PURE__ */ jsxs(Fragment2, { children: [
                 o.group && o.group !== matches[i - 1]?.group && /* @__PURE__ */ jsx(
                   "li",
                   {
@@ -616,7 +720,7 @@ function InlineEntityCombobox({
                     role: "option",
                     "aria-selected": o.value === value,
                     "aria-disabled": o.disabled || void 0,
-                    onClick: () => commit(o),
+                    onClick: () => take(o),
                     className: cn(
                       SHEET_ROW_CLASS,
                       o.value === value && "font-medium",
@@ -627,58 +731,100 @@ function InlineEntityCombobox({
                 ) })
               ] }, `${o.group ?? ""}|${String(o.value)}`)
             )),
-            matches.length === 0 && /* @__PURE__ */ jsx("li", { className: "px-4 py-3 text-sm text-[var(--text-muted)]", children: labels.noResults })
+            showCreate && /* @__PURE__ */ jsx("li", { role: "presentation", children: /* @__PURE__ */ jsx(
+              "button",
+              {
+                type: "button",
+                role: "option",
+                "aria-selected": false,
+                "aria-disabled": createLocked || void 0,
+                onClick: create,
+                className: cn(
+                  SHEET_ROW_CLASS,
+                  CREATE_ROW_CLASS,
+                  createLocked && DISABLED_ROW_CLASS
+                ),
+                children: createRowContent
+              }
+            ) }),
+            matches.length === 0 && !showCreate && /* @__PURE__ */ jsx("li", { className: "px-4 py-3 text-sm text-[var(--text-muted)]", children: labels.noResults })
           ] })
         }
       ),
-      !isPhone && open && !disabled && matches.length > 0 && /* @__PURE__ */ jsx(SuggestionList, { id: listboxId, anchorRef: fieldRef, panelRef, children: matches.map((o, i) => (
-        // A group heading is emitted at each group boundary rather than repeating
-        // the group on every row (feedback #136). `matches` is group-contiguous,
-        // so comparing with the previous row is enough. Fragment key sits here;
-        // the heading and the option carry their own list semantics — keyed by
-        // group AND value, because an option may deliberately appear twice (see
-        // `reconcile`).
-        /* @__PURE__ */ jsxs(Fragment, { children: [
-          o.group && o.group !== matches[i - 1]?.group && /* @__PURE__ */ jsx(
-            "li",
-            {
-              role: "presentation",
-              className: "px-3 pb-0.5 pt-2 text-[11px] font-semibold uppercase tracking-wide text-[var(--text-muted)] first:pt-1",
-              children: o.group
-            }
-          ),
-          /* @__PURE__ */ jsx("li", { role: "presentation", children: /* @__PURE__ */ jsxs(
-            "button",
-            {
-              type: "button",
-              id: optionId(i),
-              role: "option",
-              "aria-selected": o.value === value,
-              "aria-disabled": o.disabled || void 0,
-              tabIndex: -1,
-              onMouseDown: (e) => {
-                e.preventDefault();
-                commit(o);
-              },
-              onMouseEnter: () => {
-                if (!o.disabled) setActive(i);
-              },
-              className: cn(
-                rowClass(i === active && !o.disabled),
-                o.disabled && DISABLED_ROW_CLASS,
-                // Indented under its heading, so the hierarchy is readable at a
-                // glance instead of inferred from grey trailing text.
-                o.group && "ps-6",
-                o.value === value && "font-medium"
-              ),
-              children: [
-                o.label,
-                o.sublabel && /* @__PURE__ */ jsx("span", { className: "ms-2 text-xs text-[var(--text-placeholder)]", children: o.sublabel })
-              ]
-            }
-          ) })
-        ] }, `${o.group ?? ""}|${String(o.value)}`)
-      )) })
+      !isPhone && open && !inert && (matches.length > 0 || showCreate) && /* @__PURE__ */ jsxs(SuggestionList, { id: listboxId, anchorRef: fieldRef, panelRef, children: [
+        matches.map((o, i) => (
+          // A group heading is emitted at each group boundary rather than repeating
+          // the group on every row (feedback #136). `matches` is group-contiguous,
+          // so comparing with the previous row is enough. Fragment key sits here;
+          // the heading and the option carry their own list semantics — keyed by
+          // group AND value, because an option may deliberately appear twice (see
+          // `reconcile`).
+          /* @__PURE__ */ jsxs(Fragment2, { children: [
+            o.group && o.group !== matches[i - 1]?.group && /* @__PURE__ */ jsx(
+              "li",
+              {
+                role: "presentation",
+                className: "px-3 pb-0.5 pt-2 text-[11px] font-semibold uppercase tracking-wide text-[var(--text-muted)] first:pt-1",
+                children: o.group
+              }
+            ),
+            /* @__PURE__ */ jsx("li", { role: "presentation", children: /* @__PURE__ */ jsxs(
+              "button",
+              {
+                type: "button",
+                id: optionId(i),
+                role: "option",
+                "aria-selected": o.value === value,
+                "aria-disabled": o.disabled || void 0,
+                tabIndex: -1,
+                onMouseDown: (e) => {
+                  e.preventDefault();
+                  take(o);
+                },
+                onMouseEnter: () => {
+                  if (!o.disabled) setActive(i);
+                },
+                className: cn(
+                  rowClass(i === active && !o.disabled),
+                  o.disabled && DISABLED_ROW_CLASS,
+                  // Indented under its heading, so the hierarchy is readable at a
+                  // glance instead of inferred from grey trailing text.
+                  o.group && "ps-6",
+                  o.value === value && "font-medium"
+                ),
+                children: [
+                  o.label,
+                  o.sublabel && /* @__PURE__ */ jsx("span", { className: "ms-2 text-xs text-[var(--text-placeholder)]", children: o.sublabel })
+                ]
+              }
+            ) })
+          ] }, `${o.group ?? ""}|${String(o.value)}`)
+        )),
+        showCreate && /* @__PURE__ */ jsx("li", { role: "presentation", children: /* @__PURE__ */ jsx(
+          "button",
+          {
+            type: "button",
+            id: optionId(createIndex),
+            role: "option",
+            "aria-selected": false,
+            "aria-disabled": createLocked || void 0,
+            tabIndex: -1,
+            onMouseDown: (e) => {
+              e.preventDefault();
+              create();
+            },
+            onMouseEnter: () => {
+              if (!createLocked) setActive(createIndex);
+            },
+            className: cn(
+              rowClass(active === createIndex && !createLocked),
+              CREATE_ROW_CLASS,
+              createLocked && DISABLED_ROW_CLASS
+            ),
+            children: createRowContent
+          }
+        ) })
+      ] })
     ] })
   );
 }