@multiplatform.one/forms 6.0.4 → 6.3.0

package/dist/esm/fields/Combobox/index.native.js

@@ -1,11 +1,13 @@
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
 import { Fragment, useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState, memo } from "react";
+import { useTranslation } from "react-i18next";
 import { CaretDownIcon, CheckIcon, MagnifyingGlassIcon, PlusIcon, XIcon } from "@phosphor-icons/react";
 import { useClick, useDismiss, useInteractions, useListNavigation, useRole, FloatingFocusManager } from "@floating-ui/react";
+import { Pressable as RNPressable } from "react-native";
 import { Input as TInput, Text, View, XStack, YStack, isWeb, styled, useTheme } from "tamagui";
 import { Chip } from "../../Chip/index.native.js";
 import { Skeleton } from "../../Skeleton/index.native.js";
-import { Field, FieldLayout } from "../../fieldLayout.native.js";
+import { Field, FieldLayout, useFieldA11y, useFieldDescribedBy } from "../../fieldLayout.native.js";
 import { Input as InputParts } from "../../InputParts/index.native.js";
 import { Spinner } from "../../Spinner/index.native.js";
 import { formCommonColors, formInputColors } from "../../shared/colorRamps.native.js";
@@ -248,10 +250,32 @@ var ComboboxItem = /* @__PURE__ */memo(function ComboboxItem2(param) {
         backgroundColor: isSelected ? formInputColors.background.base : 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__ */_jsx(Text, {
+    children: [option.description ? /* @__PURE__ */_jsxs(YStack, {
+      flex: 1,
+      minWidth: 0,
+      children: [/* @__PURE__ */_jsx(Text, {
+        fontFamily: ctx.knobProps.body.fontFamily,
+        fontWeight: ctx.knobProps.body.fontWeight,
+        color: ctx.textColor,
+        numberOfLines: 1,
+        children: option.label
+      }), /* @__PURE__ */_jsx(Text, {
+        fontFamily: ctx.knobProps.body.fontFamily,
+        fontSize: "$2",
+        color: formCommonColors.muted,
+        numberOfLines: 1,
+        children: option.description
+      })]
+    }) : /* @__PURE__ */_jsx(Text, {
       fontFamily: ctx.knobProps.body.fontFamily,
       fontWeight: ctx.knobProps.body.fontWeight,
       color: ctx.textColor,
@@ -274,10 +298,15 @@ function FloatingComboboxCore(param) {
     emptyMessage,
     onSearch,
     loading,
+    searchError,
+    valueLabel,
+    clearable,
     onLoadMore,
     hasMore,
     disabled,
     id,
+    "aria-label": ariaLabel,
+    hasLabel,
     tabIndexOverride,
     popoverWidth,
     trigger: triggerRender,
@@ -293,7 +322,11 @@ function FloatingComboboxCore(param) {
     onOpenChange
   } = param;
   var _ref;
+  var {
+    t
+  } = useTranslation();
   var inTableCell = useIsInTableCell();
+  var describedBy = useFieldDescribedBy();
   var [internalOpen, setInternalOpen] = useState(false);
   var open = openProp !== void 0 ? openProp : internalOpen;
   var setOpen = useCallback(function (nextOpen) {
@@ -927,6 +960,9 @@ function FloatingComboboxCore(param) {
   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;
   var totalNavigableItems = sortedFiltered.length + (showCreateOption ? 1 : 0);
   var createOptionIndex = showCreateOption ? sortedFiltered.length : -1;
   var handleItemKeyDown = useCallback(function (e, _index) {
@@ -993,6 +1029,7 @@ function FloatingComboboxCore(param) {
         setOpen(false);
       }
     } else if (event.key === "Escape") {
+      event.preventDefault();
       setOpen(false);
     }
   }, [sortedFiltered, activeIndex, handleSelect, handleCreate, totalNavigableItems, createOptionIndex, showCreateOption, multiple]);
@@ -1031,18 +1068,35 @@ function FloatingComboboxCore(param) {
       return cancelAnimationFrame(rafId);
     };
   }, [activeIndex, multiple ? value : void 0]);
-  var triggerContent = triggerRender ? /* @__PURE__ */_jsx(View, {
+  var 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__ */
+  _jsx(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__ */_jsxs(InputParts.Box, {
     ...boxEventProps,
     "data-testid": "combobox-trigger",
+    // LC-40: Box washes its own chrome when disabled — no opacity dim here
+    // (it stacked with the wash and pushed the value text below AA).
     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
     }),
@@ -1052,7 +1106,6 @@ function FloatingComboboxCore(param) {
       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__ */_jsx(View, {
@@ -1081,13 +1134,38 @@ function FloatingComboboxCore(param) {
       }) : /* @__PURE__ */_jsx(Text, {
         fontFamily: knobProps.body.fontFamily,
         fontWeight: knobProps.body.fontWeight,
-        color: selectedOption ? textColor : formCommonColors.muted,
+        color: selectedOption || !multiple && value && valueLabel ? textColor : formCommonColors.muted,
         numberOfLines: 1,
         userSelect: "none",
-        children: (_ref = selectedOption === null || selectedOption === void 0 ? void 0 : selectedOption.label) !== null && _ref !== void 0 ? _ref : placeholder
+        children: (_ref = selectedOption === null || selectedOption === void 0 ? void 0 : selectedOption.label) !== null && _ref !== void 0 ? _ref : !multiple && value && valueLabel ? valueLabel : placeholder
+      })
+    }), clearable && !multiple && !disabled && typeof value === "string" && value !== "" && /* @__PURE__ */_jsx(View, {
+      paddingInlineEnd: "$1",
+      alignSelf: "center",
+      cursor: "pointer",
+      role: "button",
+      tabIndex: -1,
+      "aria-label": t("Clear"),
+      opacity: 0.6,
+      hoverStyle: {
+        opacity: 1
+      },
+      // useClick opens on mousedown at the trigger — swallow it so
+      // clearing never toggles the dropdown.
+      onMouseDown: function onMouseDown(e) {
+        e.stopPropagation();
+        e.preventDefault();
+      },
+      onPress: function onPress(e) {
+        var _e_stopPropagation;
+        (_e_stopPropagation = e.stopPropagation) === null || _e_stopPropagation === void 0 ? void 0 : _e_stopPropagation.call(e);
+        onValueChange === null || onValueChange === void 0 ? void 0 : onValueChange("");
+      },
+      children: /* @__PURE__ */_jsx(XIcon, {
+        size: 14
       })
     }), /* @__PURE__ */_jsx(View, {
-      paddingRight: "$2",
+      paddingInlineEnd: "$2",
       alignSelf: "center",
       children: /* @__PURE__ */_jsx(CaretDownIcon, {
         size: 16
@@ -1180,7 +1258,17 @@ function FloatingComboboxCore(param) {
             scrollRef: listScrollRef,
             visible: panel.arrowUp,
             arrowScrollDirRef: panel.arrowScrollDirRef
-          }), sortedFiltered.length > 0 ? /* @__PURE__ */_jsxs(Fragment, {
+          }), searchError ? /* @__PURE__ */_jsx(View, {
+            ...knobProps.panelPadding,
+            alignItems: "center",
+            children: /* @__PURE__ */_jsx(Text, {
+              color: formCommonColors.error,
+              fontSize: "$3",
+              fontFamily: knobProps.body.fontFamily,
+              fontWeight: knobProps.body.fontWeight,
+              children: searchError
+            })
+          }) : sortedFiltered.length > 0 ? /* @__PURE__ */_jsxs(Fragment, {
             children: [multiple ? sortedFiltered.map(function (option, index) {
               return /* @__PURE__ */_jsx(ComboboxItem, {
                 option,
@@ -1261,6 +1349,16 @@ function FloatingComboboxCore(param) {
               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__ */
+          _jsx(View, {
+            ...knobProps.panelPadding,
+            alignItems: "center",
+            children: /* @__PURE__ */_jsx(Spinner, {
+              size: "small"
+            })
           }) : /* @__PURE__ */_jsx(View, {
             ...knobProps.panelPadding,
             alignItems: "center",
@@ -1303,6 +1401,10 @@ var comboboxSearchHeader = function comboboxSearchHeader2(knobProps, filter, set
       unstyled: true,
       flex: 1,
       placeholder: searchPlaceholder,
+      // iOS VoiceOver: name the search box (placeholder alone is value-only).
+      ...(!isWeb ? {
+        accessibilityLabel: searchPlaceholder
+      } : void 0),
       value: filter,
       onChangeText: setFilter,
       onKeyDown,
@@ -1335,10 +1437,15 @@ function NativeComboboxCore(param) {
     emptyMessage,
     onSearch,
     loading,
+    searchError,
+    valueLabel,
+    clearable,
     onLoadMore,
     hasMore,
     disabled,
     id,
+    "aria-label": ariaLabel,
+    hasLabel,
     trigger: triggerRender,
     knobProps,
     multiple,
@@ -1351,9 +1458,13 @@ function NativeComboboxCore(param) {
     open: openProp,
     onOpenChange
   } = param;
-  var _ref, _knobProps_transition, _ref1;
+  var _ref, _knobProps_transition, _ref1, _ref2;
   var _theme_color7;
+  var {
+    t
+  } = useTranslation();
   var inTableCell = useIsInTableCell();
+  var describedBy = useFieldDescribedBy();
   var [internalOpen, setInternalOpen] = useState(false);
   var open = openProp !== void 0 ? openProp : internalOpen;
   var setOpen = useCallback(function (nextOpen) {
@@ -1367,6 +1478,7 @@ function NativeComboboxCore(param) {
   var filter = searchValue !== void 0 ? searchValue : internalFilter;
   var [activeIndex, setActiveIndex] = useState(0);
   var listRef = useRef(null);
+  var fieldA11y = useFieldA11y();
   var textColor = knobProps.textAccentColor;
   var theme = useTheme();
   var mutedColor = (_ref = (_theme_color7 = theme.color7) === null || _theme_color7 === void 0 ? void 0 : _theme_color7.val) !== null && _ref !== void 0 ? _ref : "$color7";
@@ -1453,7 +1565,7 @@ function NativeComboboxCore(param) {
     }
     setInternalFilter("");
   }, [onCreate, filter, multiple, value, onValueChange]);
-  var hasScrollableContent = filtered.length > 6;
+  var hasScrollableContent = Boolean(onSearch) || filtered.length > 6;
   var sheetTransition = (_knobProps_transition = knobProps.transition) !== null && _knobProps_transition !== void 0 ? _knobProps_transition : "medium";
   var sortedFiltered = useMemo(function () {
     if (filter.trim()) return filtered;
@@ -1592,53 +1704,106 @@ function NativeComboboxCore(param) {
     if (!val) onBlur === null || onBlur === void 0 ? void 0 : onBlur();
   }, [onBlur]);
   var searchHeader = hideSearch ? void 0 : comboboxSearchHeader(knobProps, filter, setInternalFilter, searchPlaceholder, textColor, mutedColor, loading !== null && loading !== void 0 ? loading : false, handleSearchKeyDown);
-  var listContent = /* @__PURE__ */_jsxs(View, {
+  var 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__ */
+  _jsxs(View, {
     ref: listRef,
-    tabIndex: 0,
-    onKeyDown: handleListKeyDown,
+    ...(isWeb ? {
+      tabIndex: 0,
+      onKeyDown: handleListKeyDown
+    } : void 0),
     outlineStyle: "none",
-    flex: 1,
-    children: [sortedFiltered.length > 0 ? /* @__PURE__ */_jsxs(_Fragment, {
+    children: [
+    // Native sheet: flex={1} inside FloatingPanel ScrollView collapses rows.
+    searchError ? /* @__PURE__ */_jsx(View, {
+      ...knobProps.panelPadding,
+      alignItems: "center",
+      children: /* @__PURE__ */_jsx(Text, {
+        color: formCommonColors.error,
+        fontSize: "$3",
+        fontFamily: knobProps.body.fontFamily,
+        fontWeight: knobProps.body.fontWeight,
+        children: searchError
+      })
+    }) : sortedFiltered.length > 0 ? /* @__PURE__ */_jsxs(_Fragment, {
       children: [sortedFiltered.map(function (option, i) {
         var selected = isSelectedFn(option.value);
         var active = i === activeIndex;
         var prevGroup = i > 0 ? sortedFiltered[i - 1].group : void 0;
         var showGroupHeader = option.group && option.group !== prevGroup;
+        var optionRow = /* @__PURE__ */_jsxs(View, {
+          flexDirection: "row",
+          alignItems: "center",
+          gap: "$2",
+          paddingHorizontal: "$3",
+          ...(option.description ? {
+            minHeight: knobProps.sizeToken,
+            paddingVertical: "$2"
+          } : {
+            height: knobProps.sizeToken
+          }),
+          onPress: isWeb ? function () {
+            return handleSelect(option);
+          } : void 0,
+          onMouseEnter: function onMouseEnter() {
+            return setActiveIndex(i);
+          },
+          ...(!isWeb ? {
+            pointerEvents: "none"
+          } : {}),
+          hoverStyle: activeIndex != null ? {
+            backgroundColor: active ? formInputColors.background.focus : selected ? formInputColors.background.base : "transparent"
+          } : {
+            backgroundColor: selected ? formInputColors.background.base : formInputColors.background.focus
+          },
+          backgroundColor: active ? formInputColors.background.focus : selected ? formInputColors.background.base : "transparent",
+          pressStyle: {
+            backgroundColor: formInputColors.background.focus
+          },
+          children: [option.description ? /* @__PURE__ */_jsxs(YStack, {
+            flex: 1,
+            minWidth: 0,
+            children: [/* @__PURE__ */_jsx(Text, {
+              fontFamily: knobProps.body.fontFamily,
+              fontWeight: knobProps.body.fontWeight,
+              color: textColor,
+              numberOfLines: 1,
+              children: option.label
+            }), /* @__PURE__ */_jsx(Text, {
+              fontFamily: knobProps.body.fontFamily,
+              fontSize: "$2",
+              color: formCommonColors.muted,
+              numberOfLines: 1,
+              children: option.description
+            })]
+          }) : /* @__PURE__ */_jsx(Text, {
+            fontFamily: knobProps.body.fontFamily,
+            fontWeight: knobProps.body.fontWeight,
+            color: textColor,
+            numberOfLines: 1,
+            flex: 1,
+            children: option.label
+          }), selected && /* @__PURE__ */_jsx(CheckIcon, {
+            size: 14
+          })]
+        });
         return /* @__PURE__ */_jsxs(View, {
           children: [showGroupHeader && /* @__PURE__ */_jsx(GroupHeader, {
             color: textColor,
             children: option.group
-          }), /* @__PURE__ */_jsxs(View, {
-            flexDirection: "row",
-            alignItems: "center",
-            gap: "$2",
-            paddingHorizontal: "$3",
-            height: knobProps.sizeToken,
+          }), isWeb ? optionRow : /* @__PURE__ */_jsx(RNPressable, {
             onPress: function onPress() {
               return handleSelect(option);
             },
-            onMouseEnter: function onMouseEnter() {
-              return setActiveIndex(i);
-            },
-            hoverStyle: activeIndex != null ? {
-              backgroundColor: active ? formInputColors.background.focus : selected ? formInputColors.background.base : "transparent"
-            } : {
-              backgroundColor: selected ? formInputColors.background.base : formInputColors.background.focus
-            },
-            backgroundColor: active ? formInputColors.background.focus : selected ? formInputColors.background.base : "transparent",
-            pressStyle: {
-              backgroundColor: formInputColors.background.focus
+            accessibilityRole: "button",
+            accessibilityLabel: option.label,
+            accessibilityState: {
+              selected
             },
-            children: [/* @__PURE__ */_jsx(Text, {
-              fontFamily: knobProps.body.fontFamily,
-              fontWeight: knobProps.body.fontWeight,
-              color: textColor,
-              numberOfLines: 1,
-              flex: 1,
-              children: option.label
-            }), selected && /* @__PURE__ */_jsx(CheckIcon, {
-              size: 14
-            })]
+            children: optionRow
           })]
         }, option.value);
       }), showCreateOption && /* @__PURE__ */_jsxs(View, {
@@ -1702,6 +1867,16 @@ function NativeComboboxCore(param) {
         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__ */
+    _jsx(View, {
+      ...knobProps.panelPadding,
+      alignItems: "center",
+      children: /* @__PURE__ */_jsx(Spinner, {
+        size: "small"
+      })
     }) : /* @__PURE__ */_jsx(View, {
       ...knobProps.panelPadding,
       alignItems: "center",
@@ -1722,18 +1897,53 @@ function NativeComboboxCore(param) {
   });
   var triggerContent = triggerRender ? /* @__PURE__ */_jsx(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__ */_jsxs(InputParts.Box, {
     "data-testid": "combobox-trigger",
+    // LC-40: Box washes its own chrome when disabled — no opacity dim here
+    // (it stacked with the wash and pushed the value text below AA).
     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,
+    // Web: the box is the combobox control (ARIA + keyboard). Native:
+    // FloatingPanel's trigger Pressable (triggerA11y) is the single
+    // accessible node — role/aria props here surface the box as a
+    // duplicate TalkBack stop on Android, so exclude it from the tree
+    // (descendants stay reachable; "no", not "no-hide-descendants").
+    ...(isWeb ? {
+      role: "combobox",
+      "aria-haspopup": "listbox",
+      "aria-expanded": open,
+      // Standalone (no label): fall back to placeholder for the name
+      "aria-label": ariaLabel !== null && ariaLabel !== void 0 ? ariaLabel : !hasLabel ? placeholder : void 0,
+      "aria-labelledby": !ariaLabel && hasLabel && id ? `${id}-label` : void 0,
+      "aria-describedby": describedBy,
+      tabIndex: disabled ? -1 : 0
+    } : {
+      importantForAccessibility: "no"
+    }),
+    // Web: trigger owns toggle. Native: FloatingPanel.native owns open
+    // (avoid double-toggle that batches open then immediately closed).
+    onPress: isWeb && !disabled ? function () {
+      return handleOpenChange(!open);
+    } : void 0,
     onKeyDown: function onKeyDown(e) {
       if (["Enter", " ", "ArrowDown", "ArrowUp", "j", "k"].includes(e.key) || e.code === "Space") {
         e.preventDefault();
@@ -1744,7 +1954,6 @@ function NativeComboboxCore(param) {
       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__ */_jsx(View, {
@@ -1773,23 +1982,51 @@ function NativeComboboxCore(param) {
       }) : /* @__PURE__ */_jsx(Text, {
         fontFamily: knobProps.body.fontFamily,
         fontWeight: knobProps.body.fontWeight,
-        color: selectedOption ? textColor : formCommonColors.muted,
+        color: selectedOption || !multiple && value && valueLabel ? textColor : formCommonColors.muted,
         numberOfLines: 1,
-        children: (_ref1 = selectedOption === null || selectedOption === void 0 ? void 0 : selectedOption.label) !== null && _ref1 !== void 0 ? _ref1 : placeholder
+        children: (_ref1 = selectedOption === null || selectedOption === void 0 ? void 0 : selectedOption.label) !== null && _ref1 !== void 0 ? _ref1 : !multiple && value && valueLabel ? valueLabel : placeholder
+      })
+    }), clearable && !multiple && !disabled && typeof value === "string" && value !== "" && /* @__PURE__ */_jsx(View, {
+      paddingInlineEnd: "$1",
+      alignSelf: "center",
+      cursor: "pointer",
+      role: "button",
+      tabIndex: -1,
+      "aria-label": t("Clear"),
+      opacity: 0.6,
+      hoverStyle: {
+        opacity: 1
+      },
+      onPress: function onPress(e) {
+        var _e_stopPropagation;
+        (_e_stopPropagation = e.stopPropagation) === null || _e_stopPropagation === void 0 ? void 0 : _e_stopPropagation.call(e);
+        onValueChange === null || onValueChange === void 0 ? void 0 : onValueChange("");
+      },
+      children: /* @__PURE__ */_jsx(XIcon, {
+        size: 14
       })
     }), /* @__PURE__ */_jsx(View, {
-      paddingRight: "$2",
+      paddingInlineEnd: "$2",
       alignSelf: "center",
       children: /* @__PURE__ */_jsx(CaretDownIcon, {
         size: 16
       })
     })]
   });
+  var triggerValueText = multiple ? selectedValues.length > 0 ? selectedValues.map(getLabel).join(", ") : placeholder : (_ref2 = selectedOption === null || selectedOption === void 0 ? void 0 : selectedOption.label) !== null && _ref2 !== void 0 ? _ref2 : placeholder;
   return /* @__PURE__ */_jsx(FloatingPanel, {
     open,
     onOpenChange: handleOpenChange,
     sheet: true,
+    // Search-driven comboboxes open the sheet tall: results stream in as
+    // the user types, so a content-fit sheet would open as a sliver.
+    sheetFill: Boolean(onSearch),
     trigger: triggerContent,
+    triggerA11y: {
+      label: ariaLabel !== null && ariaLabel !== void 0 ? ariaLabel : fieldA11y === null || fieldA11y === void 0 ? void 0 : fieldA11y.label,
+      value: triggerValueText,
+      hint: fieldA11y === null || fieldA11y === void 0 ? void 0 : fieldA11y.description
+    },
     header: searchHeader,
     scrollable: hasScrollableContent,
     disabled,
@@ -1817,12 +2054,16 @@ function Combobox(param) {
     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,
@@ -1852,8 +2093,16 @@ function Combobox(param) {
     searchValue,
     open,
     onOpenChange,
+    "aria-label": ariaLabel,
     ...rest
   } = param;
+  var {
+    t
+  } = useTranslation();
+  var placeholder = placeholderProp !== null && placeholderProp !== void 0 ? placeholderProp : t("Select...");
+  var hasLabel = Boolean(label);
+  var searchPlaceholder = searchPlaceholderProp !== null && searchPlaceholderProp !== void 0 ? searchPlaceholderProp : t("Search...");
+  var emptyMessage = emptyMessageProp !== null && emptyMessageProp !== void 0 ? emptyMessageProp : t("No results found.");
   var {
     resolvedForm,
     knobProps,
@@ -1864,6 +2113,8 @@ function Combobox(param) {
     compact
   });
   var resolvedValidators = useResolvedValidators(required, validators, label, name);
+  var [uncontrolledValue, setUncontrolledValue] = useState(defaultValue);
+  var isControlled = valueProp !== void 0;
   var viewportGtSm = useViewportGtSm();
   var effectiveGtSm = typeof window !== "undefined" ? viewportGtSm : false;
   var shouldUseSheet = !isWeb || !effectiveGtSm;
@@ -1906,7 +2157,7 @@ function Combobox(param) {
     var selected = options.find(function (option) {
       return option.value === sv;
     });
-    var displayText = (_ref = selected === null || selected === void 0 ? void 0 : selected.label) !== null && _ref !== void 0 ? _ref : sv || "-";
+    var displayText = (_ref = selected === null || selected === void 0 ? void 0 : selected.label) !== null && _ref !== void 0 ? _ref : sv ? valueLabel !== null && valueLabel !== void 0 ? valueLabel : sv : "-";
     return /* @__PURE__ */_jsx(Text, {
       fontSize: knobProps.sizeToken,
       color: textColor,
@@ -1926,6 +2177,7 @@ function Combobox(param) {
       onValueChange: function onValueChange1(value) {
         if (disabled) return;
         handleValueChange === null || handleValueChange === void 0 ? void 0 : handleValueChange(value);
+        onChange === null || onChange === void 0 ? void 0 : onChange(value);
         onValueChange === null || onValueChange === void 0 ? void 0 : onValueChange(value);
       },
       onBlur: handleBlur,
@@ -1934,10 +2186,15 @@ function Combobox(param) {
       emptyMessage,
       onSearch,
       loading,
+      searchError,
+      valueLabel,
+      clearable,
       onLoadMore,
       hasMore,
       disabled,
       id,
+      "aria-label": ariaLabel,
+      hasLabel,
       tabIndexOverride: tabIndexProp,
       popoverWidth,
       trigger,
@@ -1954,7 +2211,7 @@ function Combobox(param) {
     });
   };
   if (trigger) {
-    return renderComboboxContent(valueProp, onValueChange, onBlur);
+    return renderComboboxContent(valueProp !== null && valueProp !== void 0 ? valueProp : uncontrolledValue, isControlled ? void 0 : setUncontrolledValue, onBlur);
   }
   if (!resolvedForm || !name) {
     return /* @__PURE__ */_jsx(FieldLayout, {
@@ -1966,10 +2223,13 @@ function Combobox(param) {
       required,
       size: sizeProp,
       knobProps,
+      // LC-40: FieldLayout owns the dimWhole assembly dim (keepLabel pins
+      // the sibling label/helper readable) — it needs the disabled state.
+      disabled,
       ...rest,
       children: /* @__PURE__ */_jsx(InputParts, {
         size: sizeProp || knobProps.sizeToken,
-        children: renderComboboxContent(valueProp !== null && valueProp !== void 0 ? valueProp : defaultValue, onValueChange, onBlur)
+        children: renderComboboxContent(valueProp !== null && valueProp !== void 0 ? valueProp : uncontrolledValue, isControlled ? void 0 : setUncontrolledValue, onBlur)
       })
     });
   }
@@ -1989,6 +2249,8 @@ function Combobox(param) {
         required,
         size: sizeProp,
         knobProps,
+        // LC-40: see standalone branch — FieldLayout carries dimWhole.
+        disabled,
         ...rest,
         children: /* @__PURE__ */_jsx(InputParts, {
           size: sizeProp || knobProps.sizeToken,