@multiplatform.one/forms 6.1.0 → 6.4.0

package/dist/cjs/fields/Combobox/index.cjs

@@ -26,8 +26,10 @@ __export(Combobox_exports, {
 });
 module.exports = __toCommonJS(Combobox_exports);
 var import_react = require("react");
+var import_react_i18next = require("react-i18next");
 var import_react2 = require("@phosphor-icons/react");
 var import_react3 = require("@floating-ui/react");
+var import_react_native = require("react-native-web");
 var import_tamagui = require("tamagui");
 var import_Chip = require("../../Chip/index.cjs");
 var import_Skeleton = require("../../Skeleton/index.cjs");
@@ -187,10 +189,32 @@ const ComboboxItem = (0, import_react.memo)(function ComboboxItem2({
         backgroundColor: isSelected ? import_colorRamps.formInputColors.background.base : import_colorRamps.formInputColors.background.focus
       }
     }),
+    ...(option.description ?
+    // Two-line rows need to grow past the size-variant height.
+    {
+      height: "auto",
+      paddingVertical: "$2"
+    } : void 0),
     ...(ctx.knobProps.transition ? {
       animation: ctx.knobProps.transition
     } : void 0),
-    children: [/* @__PURE__ */(0, import_jsx_runtime.jsx)(import_tamagui.Text, {
+    children: [option.description ? /* @__PURE__ */(0, import_jsx_runtime.jsxs)(import_tamagui.YStack, {
+      flex: 1,
+      minWidth: 0,
+      children: [/* @__PURE__ */(0, import_jsx_runtime.jsx)(import_tamagui.Text, {
+        fontFamily: ctx.knobProps.body.fontFamily,
+        fontWeight: ctx.knobProps.body.fontWeight,
+        color: ctx.textColor,
+        numberOfLines: 1,
+        children: option.label
+      }), /* @__PURE__ */(0, import_jsx_runtime.jsx)(import_tamagui.Text, {
+        fontFamily: ctx.knobProps.body.fontFamily,
+        fontSize: "$2",
+        color: import_colorRamps.formCommonColors.muted,
+        numberOfLines: 1,
+        children: option.description
+      })]
+    }) : /* @__PURE__ */(0, import_jsx_runtime.jsx)(import_tamagui.Text, {
       fontFamily: ctx.knobProps.body.fontFamily,
       fontWeight: ctx.knobProps.body.fontWeight,
       color: ctx.textColor,
@@ -212,10 +236,15 @@ function FloatingComboboxCore({
   emptyMessage,
   onSearch,
   loading,
+  searchError,
+  valueLabel,
+  clearable,
   onLoadMore,
   hasMore,
   disabled,
   id,
+  "aria-label": ariaLabel,
+  hasLabel,
   tabIndexOverride,
   popoverWidth,
   trigger: triggerRender,
@@ -230,7 +259,11 @@ function FloatingComboboxCore({
   open: openProp,
   onOpenChange
 }) {
+  const {
+    t
+  } = (0, import_react_i18next.useTranslation)();
   const inTableCell = (0, import_tableCellContext.useIsInTableCell)();
+  const describedBy = (0, import_fieldLayout.useFieldDescribedBy)();
   const [internalOpen, setInternalOpen] = (0, import_react.useState)(false);
   const open = openProp !== void 0 ? openProp : internalOpen;
   const setOpen = (0, import_react.useCallback)(nextOpen => {
@@ -772,6 +805,9 @@ function FloatingComboboxCore({
   boxEventProps.role = "combobox";
   boxEventProps["aria-haspopup"] = "listbox";
   boxEventProps["aria-expanded"] = open;
+  if (id) boxEventProps.id = id;
+  if (ariaLabel) boxEventProps["aria-label"] = ariaLabel;else if (hasLabel && id) boxEventProps["aria-labelledby"] = `${id}-label`;else if (placeholder) boxEventProps["aria-label"] = placeholder;
+  if (describedBy) boxEventProps["aria-describedby"] = describedBy;
   const totalNavigableItems = sortedFiltered.length + (showCreateOption ? 1 : 0);
   const createOptionIndex = showCreateOption ? sortedFiltered.length : -1;
   const handleItemKeyDown = (0, import_react.useCallback)((e, _index) => {
@@ -838,6 +874,7 @@ function FloatingComboboxCore({
         setOpen(false);
       }
     } else if (event.key === "Escape") {
+      event.preventDefault();
       setOpen(false);
     }
   }, [sortedFiltered, activeIndex, handleSelect, handleCreate, totalNavigableItems, createOptionIndex, showCreateOption, multiple]);
@@ -874,18 +911,33 @@ function FloatingComboboxCore({
     });
     return () => cancelAnimationFrame(rafId);
   }, [activeIndex, multiple ? value : void 0]);
-  const triggerContent = triggerRender ? /* @__PURE__ */(0, import_jsx_runtime.jsx)(import_tamagui.View, {
+  const triggerContent = triggerRender ?
+  // Stretch so custom triggers (e.g. Awesomebar) can own their height
+  // instead of collapsing inside a shrink-wrapped View (SB-M-1703).
+  /* @__PURE__ */
+  (0, import_jsx_runtime.jsx)(import_tamagui.View, {
     ...boxEventProps,
     "data-testid": "combobox-trigger",
+    width: "100%",
+    alignSelf: "stretch",
+    flexShrink: 0,
+    style: {
+      display: "flex",
+      alignItems: "stretch",
+      width: "100%"
+    },
     children: triggerRender(multiple ? selectedOptions : selectedOption, open)
   }) : /* @__PURE__ */(0, import_jsx_runtime.jsxs)(import_InputParts.Input.Box, {
     ...boxEventProps,
     "data-testid": "combobox-trigger",
     cursor: disabled ? "not-allowed" : "pointer",
-    opacity: disabled ? 0.5 : 1,
     disabled,
     size: knobProps.sizeToken,
-    ...(inTableCell ? {} : {
+    ...(inTableCell ?
+    // Chromeless in cells, but keep a ≥44px pressable target (SP-FIXED).
+    {
+      minHeight: 44
+    } : {
       borderRadius: knobProps.borderRadius.borderRadius,
       borderWidth: knobProps.borderRadius.borderWidth
     }),
@@ -895,7 +947,6 @@ function FloatingComboboxCore({
       flex: 1,
       paddingHorizontal: "$3",
       paddingVertical: "$2",
-      id,
       justifyContent: multiple && selectedValues.length > 0 ? "center" : "flex-start",
       alignItems: multiple && selectedValues.length > 0 ? "center" : "flex-start",
       children: multiple && selectedValues.length > 0 ? /* @__PURE__ */(0, import_jsx_runtime.jsx)(import_tamagui.View, {
@@ -919,13 +970,35 @@ function FloatingComboboxCore({
       }) : /* @__PURE__ */(0, import_jsx_runtime.jsx)(import_tamagui.Text, {
         fontFamily: knobProps.body.fontFamily,
         fontWeight: knobProps.body.fontWeight,
-        color: selectedOption ? textColor : import_colorRamps.formCommonColors.muted,
+        color: selectedOption || !multiple && value && valueLabel ? textColor : import_colorRamps.formCommonColors.muted,
         numberOfLines: 1,
         userSelect: "none",
-        children: selectedOption?.label ?? placeholder
+        children: selectedOption?.label ?? (!multiple && value && valueLabel ? valueLabel : placeholder)
+      })
+    }), clearable && !multiple && !disabled && typeof value === "string" && value !== "" && /* @__PURE__ */(0, import_jsx_runtime.jsx)(import_tamagui.View, {
+      paddingInlineEnd: "$1",
+      alignSelf: "center",
+      cursor: "pointer",
+      role: "button",
+      tabIndex: -1,
+      "aria-label": t("Clear"),
+      opacity: 0.6,
+      hoverStyle: {
+        opacity: 1
+      },
+      onMouseDown: e => {
+        e.stopPropagation();
+        e.preventDefault();
+      },
+      onPress: e => {
+        e.stopPropagation?.();
+        onValueChange?.("");
+      },
+      children: /* @__PURE__ */(0, import_jsx_runtime.jsx)(import_react2.XIcon, {
+        size: 14
       })
     }), /* @__PURE__ */(0, import_jsx_runtime.jsx)(import_tamagui.View, {
-      paddingRight: "$2",
+      paddingInlineEnd: "$2",
       alignSelf: "center",
       children: /* @__PURE__ */(0, import_jsx_runtime.jsx)(import_react2.CaretDownIcon, {
         size: 16
@@ -1014,7 +1087,17 @@ function FloatingComboboxCore({
             scrollRef: listScrollRef,
             visible: panel.arrowUp,
             arrowScrollDirRef: panel.arrowScrollDirRef
-          }), sortedFiltered.length > 0 ? /* @__PURE__ */(0, import_jsx_runtime.jsxs)(import_react.Fragment, {
+          }), searchError ? /* @__PURE__ */(0, import_jsx_runtime.jsx)(import_tamagui.View, {
+            ...knobProps.panelPadding,
+            alignItems: "center",
+            children: /* @__PURE__ */(0, import_jsx_runtime.jsx)(import_tamagui.Text, {
+              color: import_colorRamps.formCommonColors.error,
+              fontSize: "$3",
+              fontFamily: knobProps.body.fontFamily,
+              fontWeight: knobProps.body.fontWeight,
+              children: searchError
+            })
+          }) : sortedFiltered.length > 0 ? /* @__PURE__ */(0, import_jsx_runtime.jsxs)(import_react.Fragment, {
             children: [multiple ? sortedFiltered.map((option, index) => /* @__PURE__ */(0, import_jsx_runtime.jsx)(ComboboxItem, {
               option,
               index,
@@ -1091,6 +1174,16 @@ function FloatingComboboxCore({
               flex: 1,
               children: createLabel.replace("{value}", filter.trim())
             })]
+          }) : loading ?
+          // Async search in flight with nothing loaded yet: a bounded
+          // loading row — never a premature "no results".
+          /* @__PURE__ */
+          (0, import_jsx_runtime.jsx)(import_tamagui.View, {
+            ...knobProps.panelPadding,
+            alignItems: "center",
+            children: /* @__PURE__ */(0, import_jsx_runtime.jsx)(import_Spinner.Spinner, {
+              size: "small"
+            })
           }) : /* @__PURE__ */(0, import_jsx_runtime.jsx)(import_tamagui.View, {
             ...knobProps.panelPadding,
             alignItems: "center",
@@ -1132,6 +1225,9 @@ const comboboxSearchHeader = (knobProps, filter, setFilter, searchPlaceholder, t
     unstyled: true,
     flex: 1,
     placeholder: searchPlaceholder,
+    ...(!import_tamagui.isWeb ? {
+      accessibilityLabel: searchPlaceholder
+    } : void 0),
     value: filter,
     onChangeText: setFilter,
     onKeyDown,
@@ -1160,10 +1256,15 @@ function NativeComboboxCore({
   emptyMessage,
   onSearch,
   loading,
+  searchError,
+  valueLabel,
+  clearable,
   onLoadMore,
   hasMore,
   disabled,
   id,
+  "aria-label": ariaLabel,
+  hasLabel,
   trigger: triggerRender,
   knobProps,
   multiple,
@@ -1176,7 +1277,11 @@ function NativeComboboxCore({
   open: openProp,
   onOpenChange
 }) {
+  const {
+    t
+  } = (0, import_react_i18next.useTranslation)();
   const inTableCell = (0, import_tableCellContext.useIsInTableCell)();
+  const describedBy = (0, import_fieldLayout.useFieldDescribedBy)();
   const [internalOpen, setInternalOpen] = (0, import_react.useState)(false);
   const open = openProp !== void 0 ? openProp : internalOpen;
   const setOpen = (0, import_react.useCallback)(nextOpen => {
@@ -1190,6 +1295,7 @@ function NativeComboboxCore({
   const filter = searchValue !== void 0 ? searchValue : internalFilter;
   const [activeIndex, setActiveIndex] = (0, import_react.useState)(0);
   const listRef = (0, import_react.useRef)(null);
+  const fieldA11y = (0, import_fieldLayout.useFieldA11y)();
   const textColor = knobProps.textAccentColor;
   const theme = (0, import_tamagui.useTheme)();
   const mutedColor = theme.color7?.val ?? "$color7";
@@ -1234,7 +1340,7 @@ function NativeComboboxCore({
     }
     setInternalFilter("");
   }, [onCreate, filter, multiple, value, onValueChange]);
-  const hasScrollableContent = filtered.length > 6;
+  const hasScrollableContent = Boolean(onSearch) || filtered.length > 6;
   const sheetTransition = knobProps.transition ?? "medium";
   const sortedFiltered = (0, import_react.useMemo)(() => {
     if (filter.trim()) return filtered;
@@ -1356,49 +1462,98 @@ function NativeComboboxCore({
     if (!val) onBlur?.();
   }, [onBlur]);
   const searchHeader = hideSearch ? void 0 : comboboxSearchHeader(knobProps, filter, setInternalFilter, searchPlaceholder, textColor, mutedColor, loading ?? false, handleSearchKeyDown);
-  const listContent = /* @__PURE__ */(0, import_jsx_runtime.jsxs)(import_tamagui.View, {
+  const listContent =
+  // tabIndex/onKeyDown are web-only: on iOS tabIndex makes the container an
+  // accessibility element, which merges every option into one unactionable
+  // VoiceOver blob.
+  /* @__PURE__ */
+  (0, import_jsx_runtime.jsxs)(import_tamagui.View, {
     ref: listRef,
-    tabIndex: 0,
-    onKeyDown: handleListKeyDown,
+    ...(import_tamagui.isWeb ? {
+      tabIndex: 0,
+      onKeyDown: handleListKeyDown
+    } : void 0),
     outlineStyle: "none",
-    flex: 1,
-    children: [sortedFiltered.length > 0 ? /* @__PURE__ */(0, import_jsx_runtime.jsxs)(import_jsx_runtime.Fragment, {
+    children: [searchError ? /* @__PURE__ */(0, import_jsx_runtime.jsx)(import_tamagui.View, {
+      ...knobProps.panelPadding,
+      alignItems: "center",
+      children: /* @__PURE__ */(0, import_jsx_runtime.jsx)(import_tamagui.Text, {
+        color: import_colorRamps.formCommonColors.error,
+        fontSize: "$3",
+        fontFamily: knobProps.body.fontFamily,
+        fontWeight: knobProps.body.fontWeight,
+        children: searchError
+      })
+    }) : sortedFiltered.length > 0 ? /* @__PURE__ */(0, import_jsx_runtime.jsxs)(import_jsx_runtime.Fragment, {
       children: [sortedFiltered.map((option, i) => {
         const selected = isSelectedFn(option.value);
         const active = i === activeIndex;
         const prevGroup = i > 0 ? sortedFiltered[i - 1].group : void 0;
         const showGroupHeader = option.group && option.group !== prevGroup;
-        return /* @__PURE__ */(0, import_jsx_runtime.jsxs)(import_tamagui.View, {
-          children: [showGroupHeader && /* @__PURE__ */(0, import_jsx_runtime.jsx)(GroupHeader, {
-            color: textColor,
-            children: option.group
-          }), /* @__PURE__ */(0, import_jsx_runtime.jsxs)(import_tamagui.View, {
-            flexDirection: "row",
-            alignItems: "center",
-            gap: "$2",
-            paddingHorizontal: "$3",
-            height: knobProps.sizeToken,
-            onPress: () => handleSelect(option),
-            onMouseEnter: () => setActiveIndex(i),
-            hoverStyle: activeIndex != null ? {
-              backgroundColor: active ? import_colorRamps.formInputColors.background.focus : selected ? import_colorRamps.formInputColors.background.base : "transparent"
-            } : {
-              backgroundColor: selected ? import_colorRamps.formInputColors.background.base : import_colorRamps.formInputColors.background.focus
-            },
-            backgroundColor: active ? import_colorRamps.formInputColors.background.focus : selected ? import_colorRamps.formInputColors.background.base : "transparent",
-            pressStyle: {
-              backgroundColor: import_colorRamps.formInputColors.background.focus
-            },
+        const optionRow = /* @__PURE__ */(0, import_jsx_runtime.jsxs)(import_tamagui.View, {
+          flexDirection: "row",
+          alignItems: "center",
+          gap: "$2",
+          paddingHorizontal: "$3",
+          ...(option.description ? {
+            minHeight: knobProps.sizeToken,
+            paddingVertical: "$2"
+          } : {
+            height: knobProps.sizeToken
+          }),
+          onPress: import_tamagui.isWeb ? () => handleSelect(option) : void 0,
+          onMouseEnter: () => setActiveIndex(i),
+          ...(!import_tamagui.isWeb ? {
+            pointerEvents: "none"
+          } : {}),
+          hoverStyle: activeIndex != null ? {
+            backgroundColor: active ? import_colorRamps.formInputColors.background.focus : selected ? import_colorRamps.formInputColors.background.base : "transparent"
+          } : {
+            backgroundColor: selected ? import_colorRamps.formInputColors.background.base : import_colorRamps.formInputColors.background.focus
+          },
+          backgroundColor: active ? import_colorRamps.formInputColors.background.focus : selected ? import_colorRamps.formInputColors.background.base : "transparent",
+          pressStyle: {
+            backgroundColor: import_colorRamps.formInputColors.background.focus
+          },
+          children: [option.description ? /* @__PURE__ */(0, import_jsx_runtime.jsxs)(import_tamagui.YStack, {
+            flex: 1,
+            minWidth: 0,
             children: [/* @__PURE__ */(0, import_jsx_runtime.jsx)(import_tamagui.Text, {
               fontFamily: knobProps.body.fontFamily,
               fontWeight: knobProps.body.fontWeight,
               color: textColor,
               numberOfLines: 1,
-              flex: 1,
               children: option.label
-            }), selected && /* @__PURE__ */(0, import_jsx_runtime.jsx)(import_react2.CheckIcon, {
-              size: 14
+            }), /* @__PURE__ */(0, import_jsx_runtime.jsx)(import_tamagui.Text, {
+              fontFamily: knobProps.body.fontFamily,
+              fontSize: "$2",
+              color: import_colorRamps.formCommonColors.muted,
+              numberOfLines: 1,
+              children: option.description
             })]
+          }) : /* @__PURE__ */(0, import_jsx_runtime.jsx)(import_tamagui.Text, {
+            fontFamily: knobProps.body.fontFamily,
+            fontWeight: knobProps.body.fontWeight,
+            color: textColor,
+            numberOfLines: 1,
+            flex: 1,
+            children: option.label
+          }), selected && /* @__PURE__ */(0, import_jsx_runtime.jsx)(import_react2.CheckIcon, {
+            size: 14
+          })]
+        });
+        return /* @__PURE__ */(0, import_jsx_runtime.jsxs)(import_tamagui.View, {
+          children: [showGroupHeader && /* @__PURE__ */(0, import_jsx_runtime.jsx)(GroupHeader, {
+            color: textColor,
+            children: option.group
+          }), import_tamagui.isWeb ? optionRow : /* @__PURE__ */(0, import_jsx_runtime.jsx)(import_react_native.Pressable, {
+            onPress: () => handleSelect(option),
+            accessibilityRole: "button",
+            accessibilityLabel: option.label,
+            accessibilityState: {
+              selected
+            },
+            children: optionRow
           })]
         }, option.value);
       }), showCreateOption && /* @__PURE__ */(0, import_jsx_runtime.jsxs)(import_tamagui.View, {
@@ -1458,6 +1613,16 @@ function NativeComboboxCore({
         flex: 1,
         children: createLabel.replace("{value}", filter.trim())
       })]
+    }) : loading ?
+    // Async search in flight with nothing loaded yet: a bounded loading
+    // row — never a premature "no results".
+    /* @__PURE__ */
+    (0, import_jsx_runtime.jsx)(import_tamagui.View, {
+      ...knobProps.panelPadding,
+      alignItems: "center",
+      children: /* @__PURE__ */(0, import_jsx_runtime.jsx)(import_Spinner.Spinner, {
+        size: "small"
+      })
     }) : /* @__PURE__ */(0, import_jsx_runtime.jsx)(import_tamagui.View, {
       ...knobProps.panelPadding,
       alignItems: "center",
@@ -1478,18 +1643,42 @@ function NativeComboboxCore({
   });
   const triggerContent = triggerRender ? /* @__PURE__ */(0, import_jsx_runtime.jsx)(import_tamagui.View, {
     "data-testid": "combobox-trigger",
+    width: "100%",
+    alignSelf: "stretch",
+    flexShrink: 0,
+    style: {
+      display: "flex",
+      alignItems: "stretch",
+      width: "100%"
+    },
     children: triggerRender(multiple ? selectedOptions : selectedOption, open)
   }) : /* @__PURE__ */(0, import_jsx_runtime.jsxs)(import_InputParts.Input.Box, {
     "data-testid": "combobox-trigger",
     cursor: disabled ? "not-allowed" : "pointer",
-    opacity: disabled ? 0.5 : 1,
     disabled,
     size: knobProps.sizeToken,
-    ...(inTableCell ? {} : {
+    ...(inTableCell ?
+    // Chromeless in cells, but keep a ≥44px pressable target (SP-FIXED).
+    {
+      minHeight: 44
+    } : {
       borderRadius: knobProps.borderRadius.borderRadius,
       borderWidth: knobProps.borderRadius.borderWidth
     }),
-    tabIndex: disabled ? -1 : 0,
+    id,
+    ...(import_tamagui.isWeb ? {
+      role: "combobox",
+      "aria-haspopup": "listbox",
+      "aria-expanded": open,
+      // Standalone (no label): fall back to placeholder for the name
+      "aria-label": ariaLabel ?? (!hasLabel ? placeholder : void 0),
+      "aria-labelledby": !ariaLabel && hasLabel && id ? `${id}-label` : void 0,
+      "aria-describedby": describedBy,
+      tabIndex: disabled ? -1 : 0
+    } : {
+      importantForAccessibility: "no"
+    }),
+    onPress: import_tamagui.isWeb && !disabled ? () => handleOpenChange(!open) : void 0,
     onKeyDown: e => {
       if (["Enter", " ", "ArrowDown", "ArrowUp", "j", "k"].includes(e.key) || e.code === "Space") {
         e.preventDefault();
@@ -1500,7 +1689,6 @@ function NativeComboboxCore({
       flex: 1,
       paddingHorizontal: "$3",
       paddingVertical: "$2",
-      id,
       justifyContent: multiple && selectedValues.length > 0 ? "center" : "flex-start",
       alignItems: multiple && selectedValues.length > 0 ? "center" : "flex-start",
       children: multiple && selectedValues.length > 0 ? /* @__PURE__ */(0, import_jsx_runtime.jsx)(import_tamagui.View, {
@@ -1524,23 +1712,48 @@ function NativeComboboxCore({
       }) : /* @__PURE__ */(0, import_jsx_runtime.jsx)(import_tamagui.Text, {
         fontFamily: knobProps.body.fontFamily,
         fontWeight: knobProps.body.fontWeight,
-        color: selectedOption ? textColor : import_colorRamps.formCommonColors.muted,
+        color: selectedOption || !multiple && value && valueLabel ? textColor : import_colorRamps.formCommonColors.muted,
         numberOfLines: 1,
-        children: selectedOption?.label ?? placeholder
+        children: selectedOption?.label ?? (!multiple && value && valueLabel ? valueLabel : placeholder)
+      })
+    }), clearable && !multiple && !disabled && typeof value === "string" && value !== "" && /* @__PURE__ */(0, import_jsx_runtime.jsx)(import_tamagui.View, {
+      paddingInlineEnd: "$1",
+      alignSelf: "center",
+      cursor: "pointer",
+      role: "button",
+      tabIndex: -1,
+      "aria-label": t("Clear"),
+      opacity: 0.6,
+      hoverStyle: {
+        opacity: 1
+      },
+      onPress: e => {
+        e.stopPropagation?.();
+        onValueChange?.("");
+      },
+      children: /* @__PURE__ */(0, import_jsx_runtime.jsx)(import_react2.XIcon, {
+        size: 14
       })
     }), /* @__PURE__ */(0, import_jsx_runtime.jsx)(import_tamagui.View, {
-      paddingRight: "$2",
+      paddingInlineEnd: "$2",
       alignSelf: "center",
       children: /* @__PURE__ */(0, import_jsx_runtime.jsx)(import_react2.CaretDownIcon, {
         size: 16
       })
     })]
   });
+  const triggerValueText = multiple ? selectedValues.length > 0 ? selectedValues.map(getLabel).join(", ") : placeholder : selectedOption?.label ?? placeholder;
   return /* @__PURE__ */(0, import_jsx_runtime.jsx)(import_FloatingPanel.FloatingPanel, {
     open,
     onOpenChange: handleOpenChange,
     sheet: true,
+    sheetFill: Boolean(onSearch),
     trigger: triggerContent,
+    triggerA11y: {
+      label: ariaLabel ?? fieldA11y?.label,
+      value: triggerValueText,
+      hint: fieldA11y?.description
+    },
     header: searchHeader,
     scrollable: hasScrollableContent,
     disabled,
@@ -1567,12 +1780,16 @@ function Combobox({
   options,
   value: valueProp,
   defaultValue,
+  onChange,
   onValueChange,
-  placeholder = "Select...",
-  searchPlaceholder = "Search...",
-  emptyMessage = "No results found.",
+  placeholder: placeholderProp,
+  searchPlaceholder: searchPlaceholderProp,
+  emptyMessage: emptyMessageProp,
   onSearch,
   loading,
+  searchError,
+  valueLabel,
+  clearable,
   onLoadMore,
   hasMore,
   trigger,
@@ -1602,8 +1819,16 @@ function Combobox({
   searchValue,
   open,
   onOpenChange,
+  "aria-label": ariaLabel,
   ...rest
 }) {
+  const {
+    t
+  } = (0, import_react_i18next.useTranslation)();
+  const placeholder = placeholderProp ?? t("Select...");
+  const hasLabel = Boolean(label);
+  const searchPlaceholder = searchPlaceholderProp ?? t("Search...");
+  const emptyMessage = emptyMessageProp ?? t("No results found.");
   const {
     resolvedForm,
     knobProps,
@@ -1614,6 +1839,8 @@ function Combobox({
     compact
   });
   const resolvedValidators = (0, import_utils.useResolvedValidators)(required, validators, label, name);
+  const [uncontrolledValue, setUncontrolledValue] = (0, import_react.useState)(defaultValue);
+  const isControlled = valueProp !== void 0;
   const viewportGtSm = (0, import_FloatingPanel.useViewportGtSm)();
   const effectiveGtSm = typeof window !== "undefined" ? viewportGtSm : false;
   const shouldUseSheet = !import_tamagui.isWeb || !effectiveGtSm;
@@ -1647,7 +1874,7 @@ function Combobox({
     }
     const sv = typeof selectValue === "string" ? selectValue : void 0;
     const selected = options.find(option => option.value === sv);
-    const displayText = selected?.label ?? (sv || "-");
+    const displayText = selected?.label ?? (sv ? valueLabel ?? sv : "-");
     return /* @__PURE__ */(0, import_jsx_runtime.jsx)(import_tamagui.Text, {
       fontSize: knobProps.sizeToken,
       color: textColor,
@@ -1667,6 +1894,7 @@ function Combobox({
       onValueChange: value => {
         if (disabled) return;
         handleValueChange?.(value);
+        onChange?.(value);
         onValueChange?.(value);
       },
       onBlur: handleBlur,
@@ -1675,10 +1903,15 @@ function Combobox({
       emptyMessage,
       onSearch,
       loading,
+      searchError,
+      valueLabel,
+      clearable,
       onLoadMore,
       hasMore,
       disabled,
       id,
+      "aria-label": ariaLabel,
+      hasLabel,
       tabIndexOverride: tabIndexProp,
       popoverWidth,
       trigger,
@@ -1695,7 +1928,7 @@ function Combobox({
     });
   };
   if (trigger) {
-    return renderComboboxContent(valueProp, onValueChange, onBlur);
+    return renderComboboxContent(valueProp ?? uncontrolledValue, isControlled ? void 0 : setUncontrolledValue, onBlur);
   }
   if (!resolvedForm || !name) {
     return /* @__PURE__ */(0, import_jsx_runtime.jsx)(import_fieldLayout.FieldLayout, {
@@ -1707,10 +1940,11 @@ function Combobox({
       required,
       size: sizeProp,
       knobProps,
+      disabled,
       ...rest,
       children: /* @__PURE__ */(0, import_jsx_runtime.jsx)(import_InputParts.Input, {
         size: sizeProp || knobProps.sizeToken,
-        children: renderComboboxContent(valueProp ?? defaultValue, onValueChange, onBlur)
+        children: renderComboboxContent(valueProp ?? uncontrolledValue, isControlled ? void 0 : setUncontrolledValue, onBlur)
       })
     });
   }
@@ -1730,6 +1964,7 @@ function Combobox({
         required,
         size: sizeProp,
         knobProps,
+        disabled,
         ...rest,
         children: /* @__PURE__ */(0, import_jsx_runtime.jsx)(import_InputParts.Input, {
           size: sizeProp || knobProps.sizeToken,