@multiplatform.one/forms 6.0.4 → 6.3.0

package/src/fields/Combobox/index.tsx

@@ -9,6 +9,7 @@ import {
   useState,
   memo,
 } from "react";
+import { useTranslation } from "react-i18next";
 import {
   CaretDownIcon,
   CheckIcon,
@@ -27,10 +28,11 @@ import {
 import type { AnyFormApi } from "../../types";
 import { useResolvedKnobs } from "@multiplatform.one/theme";
 import type { LabelProps, SizeTokens } from "tamagui";
+import { Pressable as RNPressable } from "react-native";
 import { Input as TInput, Text, View, XStack, YStack, isWeb, styled, useTheme } from "tamagui";
 import { Chip, type ChipProps } from "../../Chip";
 import { Skeleton } from "../../Skeleton";
-import { Field, FieldLayout } from "../../fieldLayout";
+import { Field, FieldLayout, useFieldA11y, useFieldDescribedBy } from "../../fieldLayout";
 import { Input as InputParts } from "../../InputParts";
 import { Spinner } from "../../Spinner";
 import { formCommonColors, formInputColors } from "../../shared/colorRamps";
@@ -102,18 +104,39 @@ export interface ComboboxOption {
   keywords?: string;
   /** Optional group label for grouping options */
   group?: string;
+  /** Optional secondary line (muted) rendered under the label, e.g. a doc description */
+  description?: string;
 }
 
 export interface ComboboxProps {
   options: ComboboxOption[];
   value?: string | string[];
   defaultValue?: string | string[];
+  /**
+   * Canonical change handler, consistent with the rest of the field family.
+   * Prefer this over `onValueChange`.
+   */
+  onChange?: (value: string | string[]) => void;
+  /** @deprecated Use `onChange` instead. */
   onValueChange?: (value: string | string[]) => void;
   placeholder?: string;
   searchPlaceholder?: string;
   emptyMessage?: string;
   onSearch?: (query: string) => void | (() => void);
   loading?: boolean;
+  /**
+   * Honest async-search failure surface: when set, the dropdown list area
+   * shows this message (error-colored) instead of options / empty state.
+   */
+  searchError?: string;
+  /**
+   * Label to display for the current single-select value when it is not in
+   * `options` (async combobox: show the selected doc's title before any
+   * options have loaded). Purely additive — without it the placeholder shows.
+   */
+  valueLabel?: string;
+  /** Single-select: show a clear (×) affordance in the trigger when a value is set. */
+  clearable?: boolean;
   /** Called when the user scrolls near the bottom of the list. Use for cursor-based pagination. */
   onLoadMore?: () => void;
   /** Whether more pages are available. Shows a spinner at the bottom when loading more. */
@@ -306,17 +329,42 @@ const ComboboxItem = memo(function ComboboxItem({
                 : formInputColors.background.focus,
             },
           })}
+      {...(option.description
+        ? // Two-line rows need to grow past the size-variant height.
+          { height: "auto", paddingVertical: "$2" }
+        : undefined)}
       {...(ctx.knobProps.transition ? { animation: ctx.knobProps.transition } : undefined)}
     >
-      <Text
-        fontFamily={ctx.knobProps.body.fontFamily}
-        fontWeight={ctx.knobProps.body.fontWeight}
-        color={ctx.textColor}
-        numberOfLines={1}
-        flex={1}
-      >
-        {option.label}
-      </Text>
+      {option.description ? (
+        <YStack flex={1} minWidth={0}>
+          <Text
+            fontFamily={ctx.knobProps.body.fontFamily}
+            fontWeight={ctx.knobProps.body.fontWeight}
+            color={ctx.textColor}
+            numberOfLines={1}
+          >
+            {option.label}
+          </Text>
+          <Text
+            fontFamily={ctx.knobProps.body.fontFamily}
+            fontSize="$2"
+            color={formCommonColors.muted}
+            numberOfLines={1}
+          >
+            {option.description}
+          </Text>
+        </YStack>
+      ) : (
+        <Text
+          fontFamily={ctx.knobProps.body.fontFamily}
+          fontWeight={ctx.knobProps.body.fontWeight}
+          color={ctx.textColor}
+          numberOfLines={1}
+          flex={1}
+        >
+          {option.label}
+        </Text>
+      )}
       {isSelected && <CheckIcon size={14} />}
     </ComboboxRow>
   );
@@ -334,10 +382,15 @@ interface FloatingComboboxCoreProps {
   emptyMessage: string;
   onSearch?: (query: string) => void | (() => void);
   loading?: boolean;
+  searchError?: string;
+  valueLabel?: string;
+  clearable?: boolean;
   onLoadMore?: () => void;
   hasMore?: boolean;
   disabled?: boolean;
   id?: string;
+  "aria-label"?: string;
+  hasLabel?: boolean;
   tabIndexOverride?: number;
   popoverWidth?: number;
   trigger?: (selected: ComboboxOption | ComboboxOption[] | undefined, open: boolean) => ReactNode;
@@ -363,10 +416,15 @@ function FloatingComboboxCore({
   emptyMessage,
   onSearch,
   loading,
+  searchError,
+  valueLabel,
+  clearable,
   onLoadMore,
   hasMore,
   disabled,
   id,
+  "aria-label": ariaLabel,
+  hasLabel,
   tabIndexOverride,
   popoverWidth,
   trigger: triggerRender,
@@ -381,7 +439,9 @@ function FloatingComboboxCore({
   open: openProp,
   onOpenChange,
 }: FloatingComboboxCoreProps) {
+  const { t } = useTranslation();
   const inTableCell = useIsInTableCell();
+  const describedBy = useFieldDescribedBy();
   const [internalOpen, setInternalOpen] = useState(false);
   // Use external open state when provided (controlled), otherwise use internal state
   const open = openProp !== undefined ? openProp : internalOpen;
@@ -1028,6 +1088,12 @@ 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`;
+  // Standalone triggers (no label prop) still need a name (axe aria-input-field-name)
+  else if (placeholder) boxEventProps["aria-label"] = placeholder;
+  if (describedBy) boxEventProps["aria-describedby"] = describedBy;
 
   // Total navigable items includes the create option if shown
   const totalNavigableItems = sortedFiltered.length + (showCreateOption ? 1 : 0);
@@ -1109,6 +1175,9 @@ function FloatingComboboxCore({
           setOpen(false);
         }
       } else if (event.key === "Escape") {
+        // Consume the dismissal intent so an enclosing sheet (window-level
+        // Escape listener) does not also close on the same keypress (LC-21).
+        event.preventDefault();
         setOpen(false);
       }
     },
@@ -1162,19 +1231,30 @@ function FloatingComboboxCore({
   }, [activeIndex, multiple ? value : undefined]);
 
   const triggerContent = triggerRender ? (
-    <View {...boxEventProps} data-testid="combobox-trigger">
+    // Stretch so custom triggers (e.g. Awesomebar) can own their height
+    // instead of collapsing inside a shrink-wrapped View (SB-M-1703).
+    <View
+      {...boxEventProps}
+      data-testid="combobox-trigger"
+      width="100%"
+      alignSelf="stretch"
+      flexShrink={0}
+      style={{ display: "flex", alignItems: "stretch", width: "100%" }}
+    >
       {triggerRender(multiple ? selectedOptions : selectedOption, open)}
     </View>
   ) : (
     <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={disabled}
       size={knobProps.sizeToken}
       {...(inTableCell
-        ? {}
+        ? // Chromeless in cells, but keep a ≥44px pressable target (SP-FIXED).
+          { minHeight: 44 }
         : {
             borderRadius: knobProps.borderRadius.borderRadius,
             borderWidth: knobProps.borderRadius.borderWidth,
@@ -1185,7 +1265,6 @@ function FloatingComboboxCore({
         flex={1}
         paddingHorizontal="$3"
         paddingVertical="$2"
-        id={id}
         justifyContent={multiple && selectedValues.length > 0 ? "center" : "flex-start"}
         alignItems={multiple && selectedValues.length > 0 ? "center" : "flex-start"}
       >
@@ -1217,15 +1296,43 @@ function FloatingComboboxCore({
           <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"
           >
-            {selectedOption?.label ?? placeholder}
+            {selectedOption?.label ?? (!multiple && value && valueLabel ? valueLabel : placeholder)}
           </Text>
         )}
       </View>
-      <View paddingRight="$2" alignSelf="center">
+      {clearable && !multiple && !disabled && typeof value === "string" && value !== "" && (
+        <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={(e: any) => {
+            e.stopPropagation();
+            e.preventDefault();
+          }}
+          onPress={(e: any) => {
+            e.stopPropagation?.();
+            onValueChange?.("");
+          }}
+        >
+          <XIcon size={14} />
+        </View>
+      )}
+      <View paddingInlineEnd="$2" alignSelf="center">
         <CaretDownIcon size={16} />
       </View>
     </InputParts.Box>
@@ -1324,7 +1431,18 @@ function FloatingComboboxCore({
                 visible={panel.arrowUp}
                 arrowScrollDirRef={panel.arrowScrollDirRef}
               />
-              {sortedFiltered.length > 0 ? (
+              {searchError ? (
+                <View {...knobProps.panelPadding} alignItems="center">
+                  <Text
+                    color={formCommonColors.error}
+                    fontSize="$3"
+                    fontFamily={knobProps.body.fontFamily}
+                    fontWeight={knobProps.body.fontWeight}
+                  >
+                    {searchError}
+                  </Text>
+                </View>
+              ) : sortedFiltered.length > 0 ? (
                 <Fragment key={filter}>
                   {multiple
                     ? sortedFiltered.map((option, index) => (
@@ -1433,6 +1551,12 @@ function FloatingComboboxCore({
                     {createLabel.replace("{value}", filter.trim())}
                   </Text>
                 </View>
+              ) : loading ? (
+                // Async search in flight with nothing loaded yet: a bounded
+                // loading row — never a premature "no results".
+                <View {...knobProps.panelPadding} alignItems="center">
+                  <Spinner size="small" />
+                </View>
               ) : (
                 <View {...knobProps.panelPadding} alignItems="center">
                   <Text
@@ -1489,6 +1613,8 @@ const comboboxSearchHeader = (
       unstyled
       flex={1}
       placeholder={searchPlaceholder}
+      // iOS VoiceOver: name the search box (placeholder alone is value-only).
+      {...(!isWeb ? { accessibilityLabel: searchPlaceholder } : undefined)}
       value={filter}
       onChangeText={setFilter}
       onKeyDown={onKeyDown as any}
@@ -1518,10 +1644,15 @@ function NativeComboboxCore({
   emptyMessage,
   onSearch,
   loading,
+  searchError,
+  valueLabel,
+  clearable,
   onLoadMore,
   hasMore,
   disabled,
   id,
+  "aria-label": ariaLabel,
+  hasLabel,
   trigger: triggerRender,
   knobProps,
   multiple,
@@ -1534,7 +1665,9 @@ function NativeComboboxCore({
   open: openProp,
   onOpenChange,
 }: FloatingComboboxCoreProps) {
+  const { t } = useTranslation();
   const inTableCell = useIsInTableCell();
+  const describedBy = useFieldDescribedBy();
   const [internalOpen, setInternalOpen] = useState(false);
   // Use external open state when provided (controlled), otherwise use internal state
   const open = openProp !== undefined ? openProp : internalOpen;
@@ -1553,6 +1686,7 @@ function NativeComboboxCore({
   const filter = searchValue !== undefined ? searchValue : internalFilter;
   const [activeIndex, setActiveIndex] = useState<number | null>(0);
   const listRef = useRef<HTMLElement | null>(null);
+  const fieldA11y = useFieldA11y();
 
   const textColor = knobProps.textAccentColor;
   const theme = useTheme();
@@ -1629,7 +1763,12 @@ function NativeComboboxCore({
     setInternalFilter("");
   }, [onCreate, filter, multiple, value, onValueChange]);
 
-  const hasScrollableContent = filtered.length > 6;
+  // Async-search comboboxes (Awesomebar, Link fields) open with few or no
+  // options and stream results as the user types — open the sheet tall
+  // (FloatingPanel `scrollable` → percent snap points) so the keyboard and
+  // incoming results have room, instead of a fit-height sliver that shows
+  // only the search input.
+  const hasScrollableContent = Boolean(onSearch) || filtered.length > 6;
   const sheetTransition = knobProps.transition ?? "medium";
 
   // Selected item(s) at top when filter empty (single + multi); reset to normal order when searching
@@ -1811,55 +1950,89 @@ function NativeComboboxCore({
       );
 
   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.
     <View
       ref={listRef as any}
-      tabIndex={0}
-      onKeyDown={handleListKeyDown}
+      {...(isWeb ? { tabIndex: 0, onKeyDown: handleListKeyDown } : undefined)}
       outlineStyle="none"
-      flex={1}
+      // Native sheet: flex={1} inside FloatingPanel ScrollView collapses rows.
     >
-      {sortedFiltered.length > 0 ? (
+      {searchError ? (
+        <View {...knobProps.panelPadding} alignItems="center">
+          <Text
+            color={formCommonColors.error}
+            fontSize="$3"
+            fontFamily={knobProps.body.fontFamily}
+            fontWeight={knobProps.body.fontWeight}
+          >
+            {searchError}
+          </Text>
+        </View>
+      ) : sortedFiltered.length > 0 ? (
         <>
           {sortedFiltered.map((option, i) => {
             const selected = isSelectedFn(option.value);
             const active = i === activeIndex;
             const prevGroup = i > 0 ? sortedFiltered[i - 1].group : undefined;
             const showGroupHeader = option.group && option.group !== prevGroup;
-            return (
-              <View key={option.value}>
-                {showGroupHeader && <GroupHeader color={textColor}>{option.group}</GroupHeader>}
-                <View
-                  flexDirection="row"
-                  alignItems="center"
-                  gap="$2"
-                  paddingHorizontal="$3"
-                  height={knobProps.sizeToken}
-                  onPress={() => handleSelect(option)}
-                  onMouseEnter={() => setActiveIndex(i)}
-                  hoverStyle={
-                    activeIndex != null
-                      ? {
-                          backgroundColor: active
-                            ? formInputColors.background.focus
-                            : selected
-                              ? formInputColors.background.base
-                              : "transparent",
-                        }
-                      : {
-                          backgroundColor: selected
+            const optionRow = (
+              <View
+                flexDirection="row"
+                alignItems="center"
+                gap="$2"
+                paddingHorizontal="$3"
+                {...(option.description
+                  ? { minHeight: knobProps.sizeToken, paddingVertical: "$2" }
+                  : { height: knobProps.sizeToken })}
+                onPress={isWeb ? () => handleSelect(option) : undefined}
+                onMouseEnter={() => setActiveIndex(i)}
+                {...(!isWeb ? { pointerEvents: "none" as const } : {})}
+                hoverStyle={
+                  activeIndex != null
+                    ? {
+                        backgroundColor: active
+                          ? formInputColors.background.focus
+                          : selected
                             ? formInputColors.background.base
-                            : formInputColors.background.focus,
-                        }
-                  }
-                  backgroundColor={
-                    active
-                      ? formInputColors.background.focus
-                      : selected
-                        ? formInputColors.background.base
-                        : "transparent"
-                  }
-                  pressStyle={{ backgroundColor: formInputColors.background.focus }}
-                >
+                            : "transparent",
+                      }
+                    : {
+                        backgroundColor: selected
+                          ? formInputColors.background.base
+                          : formInputColors.background.focus,
+                      }
+                }
+                backgroundColor={
+                  active
+                    ? formInputColors.background.focus
+                    : selected
+                      ? formInputColors.background.base
+                      : "transparent"
+                }
+                pressStyle={{ backgroundColor: formInputColors.background.focus }}
+              >
+                {option.description ? (
+                  <YStack flex={1} minWidth={0}>
+                    <Text
+                      fontFamily={knobProps.body.fontFamily}
+                      fontWeight={knobProps.body.fontWeight}
+                      color={textColor}
+                      numberOfLines={1}
+                    >
+                      {option.label}
+                    </Text>
+                    <Text
+                      fontFamily={knobProps.body.fontFamily}
+                      fontSize="$2"
+                      color={formCommonColors.muted}
+                      numberOfLines={1}
+                    >
+                      {option.description}
+                    </Text>
+                  </YStack>
+                ) : (
                   <Text
                     fontFamily={knobProps.body.fontFamily}
                     fontWeight={knobProps.body.fontWeight}
@@ -1869,8 +2042,25 @@ function NativeComboboxCore({
                   >
                     {option.label}
                   </Text>
-                  {selected && <CheckIcon size={14} />}
-                </View>
+                )}
+                {selected && <CheckIcon size={14} />}
+              </View>
+            );
+            return (
+              <View key={option.value}>
+                {showGroupHeader && <GroupHeader color={textColor}>{option.group}</GroupHeader>}
+                {isWeb ? (
+                  optionRow
+                ) : (
+                  <RNPressable
+                    onPress={() => handleSelect(option)}
+                    accessibilityRole="button"
+                    accessibilityLabel={option.label}
+                    accessibilityState={{ selected }}
+                  >
+                    {optionRow}
+                  </RNPressable>
+                )}
               </View>
             );
           })}
@@ -1946,6 +2136,12 @@ function NativeComboboxCore({
             {createLabel.replace("{value}", filter.trim())}
           </Text>
         </View>
+      ) : loading ? (
+        // Async search in flight with nothing loaded yet: a bounded loading
+        // row — never a premature "no results".
+        <View {...knobProps.panelPadding} alignItems="center">
+          <Spinner size="small" />
+        </View>
       ) : (
         <View {...knobProps.panelPadding} alignItems="center">
           <Text
@@ -1967,23 +2163,51 @@ function NativeComboboxCore({
   );
 
   const triggerContent = triggerRender ? (
-    <View data-testid="combobox-trigger">
+    <View
+      data-testid="combobox-trigger"
+      width="100%"
+      alignSelf="stretch"
+      flexShrink={0}
+      style={{ display: "flex", alignItems: "stretch", width: "100%" }}
+    >
       {triggerRender(multiple ? selectedOptions : selectedOption, open)}
     </View>
   ) : (
     <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={disabled}
       size={knobProps.sizeToken}
       {...(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={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" as const,
+            "aria-haspopup": "listbox",
+            "aria-expanded": open,
+            // Standalone (no label): fall back to placeholder for the name
+            "aria-label": ariaLabel ?? (!hasLabel ? placeholder : undefined),
+            "aria-labelledby": !ariaLabel && hasLabel && id ? `${id}-label` : undefined,
+            "aria-describedby": describedBy,
+            tabIndex: disabled ? -1 : 0,
+          }
+        : { importantForAccessibility: "no" as const })}
+      // Web: trigger owns toggle. Native: FloatingPanel.native owns open
+      // (avoid double-toggle that batches open then immediately closed).
+      onPress={isWeb && !disabled ? () => handleOpenChange(!open) : undefined}
       onKeyDown={(e: React.KeyboardEvent) => {
         if (
           ["Enter", " ", "ArrowDown", "ArrowUp", "j", "k"].includes(e.key) ||
@@ -1998,7 +2222,6 @@ function NativeComboboxCore({
         flex={1}
         paddingHorizontal="$3"
         paddingVertical="$2"
-        id={id}
         justifyContent={multiple && selectedValues.length > 0 ? "center" : "flex-start"}
         alignItems={multiple && selectedValues.length > 0 ? "center" : "flex-start"}
       >
@@ -2030,25 +2253,61 @@ function NativeComboboxCore({
           <Text
             fontFamily={knobProps.body.fontFamily}
             fontWeight={knobProps.body.fontWeight}
-            color={selectedOption ? textColor : formCommonColors.muted}
+            color={
+              selectedOption || (!multiple && value && valueLabel)
+                ? textColor
+                : formCommonColors.muted
+            }
             numberOfLines={1}
           >
-            {selectedOption?.label ?? placeholder}
+            {selectedOption?.label ?? (!multiple && value && valueLabel ? valueLabel : placeholder)}
           </Text>
         )}
       </View>
-      <View paddingRight="$2" alignSelf="center">
+      {clearable && !multiple && !disabled && typeof value === "string" && value !== "" && (
+        <View
+          paddingInlineEnd="$1"
+          alignSelf="center"
+          cursor="pointer"
+          role="button"
+          tabIndex={-1}
+          aria-label={t("Clear")}
+          opacity={0.6}
+          hoverStyle={{ opacity: 1 }}
+          onPress={(e: any) => {
+            e.stopPropagation?.();
+            onValueChange?.("");
+          }}
+        >
+          <XIcon size={14} />
+        </View>
+      )}
+      <View paddingInlineEnd="$2" alignSelf="center">
         <CaretDownIcon size={16} />
       </View>
     </InputParts.Box>
   );
 
+  const triggerValueText = multiple
+    ? selectedValues.length > 0
+      ? selectedValues.map(getLabel).join(", ")
+      : placeholder
+    : (selectedOption?.label ?? placeholder);
+
   return (
     <FloatingPanel
       open={open}
       onOpenChange={handleOpenChange}
       sheet
+      // 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 ?? fieldA11y?.label,
+        value: triggerValueText,
+        hint: fieldA11y?.description,
+      }}
       header={searchHeader}
       scrollable={hasScrollableContent}
       disabled={disabled}
@@ -2076,12 +2335,16 @@ export 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,
@@ -2111,10 +2374,22 @@ export function Combobox({
   searchValue,
   open,
   onOpenChange,
+  "aria-label": ariaLabel,
   ...rest
 }: ComboboxProps) {
+  const { t } = 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, id } = useFormField({ form: formProp, id: idProp, compact });
   const resolvedValidators = useResolvedValidators(required, validators, label, name);
+  // Uncontrolled (no `value` prop, no form) still must reflect selections in
+  // the trigger — callbacks alone leave the display frozen on the placeholder.
+  const [uncontrolledValue, setUncontrolledValue] = useState<string | string[] | undefined>(
+    defaultValue,
+  );
+  const isControlled = valueProp !== undefined;
   const viewportGtSm = useViewportGtSm();
   // Sheet on native and sm (viewport ≤860px). Floating on desktop.
   const effectiveGtSm = typeof window !== "undefined" ? viewportGtSm : false;
@@ -2151,7 +2426,7 @@ export function Combobox({
     }
     const sv = typeof selectValue === "string" ? selectValue : undefined;
     const selected = options.find((option) => option.value === sv);
-    const displayText = selected?.label ?? (sv || "-");
+    const displayText = selected?.label ?? (sv ? (valueLabel ?? sv) : "-");
     return (
       <Text
         fontSize={knobProps.sizeToken}
@@ -2180,6 +2455,9 @@ export function Combobox({
         onValueChange={(value) => {
           if (disabled) return;
           handleValueChange?.(value);
+          // Canonical `onChange` and the alias `onValueChange` both fire from
+          // this single emit site (same reconciliation as Switch).
+          onChange?.(value);
           onValueChange?.(value);
         }}
         onBlur={handleBlur}
@@ -2188,10 +2466,15 @@ export function Combobox({
         emptyMessage={emptyMessage}
         onSearch={onSearch}
         loading={loading}
+        searchError={searchError}
+        valueLabel={valueLabel}
+        clearable={clearable}
         onLoadMore={onLoadMore}
         hasMore={hasMore}
         disabled={disabled}
         id={id}
+        aria-label={ariaLabel}
+        hasLabel={hasLabel}
         tabIndexOverride={tabIndexProp}
         popoverWidth={popoverWidth}
         trigger={trigger}
@@ -2210,7 +2493,13 @@ export function Combobox({
   };
 
   if (trigger) {
-    return renderComboboxContent(valueProp, onValueChange, onBlur);
+    // User callbacks fire once at the emit site above — passing them again as
+    // the internal handler double-fired `onValueChange` per change.
+    return renderComboboxContent(
+      valueProp ?? uncontrolledValue,
+      isControlled ? undefined : setUncontrolledValue,
+      onBlur,
+    );
   }
 
   if (!resolvedForm || !name) {
@@ -2224,10 +2513,17 @@ export function Combobox({
         required={required}
         size={sizeProp}
         knobProps={knobProps as any}
+        // LC-40: FieldLayout owns the dimWhole assembly dim (keepLabel pins
+        // the sibling label/helper readable) — it needs the disabled state.
+        disabled={disabled}
         {...rest}
       >
         <InputParts size={sizeProp || knobProps.sizeToken}>
-          {renderComboboxContent(valueProp ?? defaultValue, onValueChange, onBlur)}
+          {renderComboboxContent(
+            valueProp ?? uncontrolledValue,
+            isControlled ? undefined : setUncontrolledValue,
+            onBlur,
+          )}
         </InputParts>
       </FieldLayout>
     );
@@ -2252,6 +2548,8 @@ export function Combobox({
             required={required}
             size={sizeProp}
             knobProps={knobProps as any}
+            // LC-40: see standalone branch — FieldLayout carries dimWhole.
+            disabled={disabled}
             {...rest}
           >
             <InputParts size={sizeProp || knobProps.sizeToken}>