@proyecto-viviana/solid-stately 0.6.0-rc.0 → 0.6.0-rc.1

package/src/combobox/createComboBoxState.ts

@@ -22,12 +22,17 @@
 
 import { createMemo, createEffect, untrack } from "solid-js";
 import type { Accessor } from "solid-js";
-import { createInternalSignal, access, type MaybeAccessor } from "../utils";
+import { createInternalSignal, propsAccessor, type MaybeAccessor } from "../utils";
 import { createListState, type ListState } from "../collections/createListState";
 import { createOverlayTriggerState } from "../overlays";
 import { ListCollection } from "../collections/ListCollection";
 import type { Key, CollectionNode, Collection, FocusStrategy } from "../collections/types";
 import type { SelectionManager } from "../selection/SelectionManager";
+import {
+  createFormValidationState,
+  type FormValidationState,
+  type ValidationFunction,
+} from "../form";
 
 export type MenuTriggerAction = "focus" | "input" | "manual";
 
@@ -35,7 +40,37 @@ export type { FocusStrategy } from "../collections/types";
 
 export type FilterFn = (textValue: string, inputValue: string) => boolean;
 
-export interface ComboBoxStateProps<T = unknown> {
+export type ComboBoxSelectionMode = "single" | "multiple";
+
+/** Single mode is `Key | null`. Multiple mode is `readonly Key[]`. */
+export type ComboBoxValueType<M extends ComboBoxSelectionMode> = M extends "single"
+  ? Key | null
+  : readonly Key[];
+
+/** `onChange` receives a mutable `Key[]` in multiple mode. */
+export type ComboBoxChangeValueType<M extends ComboBoxSelectionMode> = M extends "single"
+  ? Key | null
+  : Key[];
+
+type ComboBoxValidationType<M extends ComboBoxSelectionMode> = M extends "single"
+  ? Key | null
+  : Key[];
+
+const EMPTY_COMBOBOX_KEYS: readonly Key[] = [];
+
+export interface ComboBoxValidationValue<M extends ComboBoxSelectionMode = "single"> {
+  /**
+   * The selected key in the ComboBox.
+   * @deprecated Use `value`.
+   */
+  selectedKey: Key | null;
+  /** The keys of the currently selected items. */
+  value: ComboBoxValidationType<M>;
+  /** The value of the ComboBox input. */
+  inputValue: string;
+}
+
+export interface ComboBoxStateProps<T = unknown, M extends ComboBoxSelectionMode = "single"> {
   /** The items to display in the combobox dropdown. */
   items?: T[];
   /** Default items when uncontrolled. */
@@ -48,20 +83,35 @@ export interface ComboBoxStateProps<T = unknown> {
   getDisabled?: (item: T) => boolean;
   /** Keys of disabled items. */
   disabledKeys?: Iterable<Key>;
-  /** The selection mode for the combobox. */
-  selectionMode?: "single" | "multiple";
-  /** The currently selected key (controlled, single mode). */
+  /**
+   * Whether single or multiple selection is enabled.
+   * @default 'single'
+   */
+  selectionMode?: M;
+  /**
+   * The current value (controlled).
+   * Single mode is `Key | null`. Multiple mode is `readonly Key[]`.
+   */
+  value?: ComboBoxValueType<M>;
+  /** The default value (uncontrolled). */
+  defaultValue?: ComboBoxValueType<M>;
+  /** Handler called when the value changes. */
+  onChange?: (value: ComboBoxChangeValueType<M>) => void;
+  /**
+   * The currently selected key in the collection (controlled).
+   * @deprecated Use `value`.
+   */
   selectedKey?: Key | null;
-  /** The default selected key (uncontrolled, single mode). */
+  /**
+   * The initial selected key in the collection (uncontrolled).
+   * @deprecated Use `defaultValue`.
+   */
   defaultSelectedKey?: Key | null;
-  /** The currently selected keys (controlled, multiple mode). */
-  selectedKeys?: Iterable<Key>;
-  /** The default selected keys (uncontrolled, multiple mode). */
-  defaultSelectedKeys?: Iterable<Key>;
-  /** Handler called when the selection changes (single mode). */
+  /**
+   * Handler that is called when the selection changes.
+   * @deprecated Use `onChange`.
+   */
   onSelectionChange?: (key: Key | null) => void;
-  /** Handler called when the selection changes (multiple mode). */
-  onSelectionChangeMultiple?: (keys: Set<Key>) => void;
   /** The current input value (controlled). */
   inputValue?: string;
   /** The default input value (uncontrolled). */
@@ -90,9 +140,25 @@ export interface ComboBoxStateProps<T = unknown> {
   menuTrigger?: MenuTriggerAction;
   /** Whether to close the menu on blur. */
   shouldCloseOnBlur?: boolean;
+  /** Whether the combobox is invalid (controlled). */
+  isInvalid?: boolean;
+  /** @deprecated Use isInvalid instead. */
+  validationState?: "valid" | "invalid";
+  /** Custom validation function. */
+  validate?: ValidationFunction<ComboBoxValidationValue<M> | null>;
+  /**
+   * Whether to use native HTML form validation or ARIA validation semantics.
+   * @default "native"
+   */
+  validationBehavior?: "aria" | "native";
+  /** Field name(s) for server error lookup. */
+  name?: string | string[];
 }
 
-export interface ComboBoxState<T = unknown> {
+export interface ComboBoxState<
+  T = unknown,
+  M extends ComboBoxSelectionMode = "single",
+> extends FormValidationState {
   /** The collection of items (may be filtered). */
   readonly collection: Accessor<Collection<T>>;
   /**
@@ -109,19 +175,40 @@ export interface ComboBoxState<T = unknown> {
   close(): void;
   /** Toggle the combobox dropdown. */
   toggle(focusStrategy?: FocusStrategy | null, trigger?: MenuTriggerAction): void;
-  /** The currently selected key (single mode). */
+  /**
+   * The key for the first selected item. Null in multiple mode.
+   * @deprecated Use `value`.
+   */
   readonly selectedKey: Accessor<Key | null>;
-  /** The default selected key. */
+  /**
+   * The default selected key.
+   * @deprecated Use `defaultValue`.
+   */
   readonly defaultSelectedKey: Key | null;
-  /** The currently selected item (single mode). */
+  /**
+   * The value of the first selected item.
+   * @deprecated Use `selectedItems`.
+   */
   readonly selectedItem: Accessor<CollectionNode<T> | null>;
-  /** Set the selected key. */
+  /**
+   * Sets the selected key.
+   * @deprecated Use `setValue`.
+   */
   setSelectedKey(key: Key | null): void;
-  /** The currently selected keys (multiple mode). */
+  /** The current combobox value. */
+  readonly value: Accessor<ComboBoxValueType<M>>;
+  /** The default combobox value. */
+  readonly defaultValue: ComboBoxValueType<M>;
+  /** Sets the combobox value. */
+  setValue(value: Key | readonly Key[] | null): void;
+  /**
+   * Selected keys derived from `value`.
+   * Kept for the headless Backspace path and the tag/list adapters.
+   */
   readonly selectedKeys: Accessor<Set<Key>>;
-  /** Replace the selected keys (multiple mode). */
-  setSelectedKeys(keys: Set<Key>): void;
-  /** The currently selected items (multiple mode). */
+  /** Replace the selected keys. */
+  setSelectedKeys(keys: Iterable<Key>): void;
+  /** The currently selected items. */
   readonly selectedItems: Accessor<CollectionNode<T>[]>;
   /** Remove a selected key (multiple mode). */
   removeSelectedKey(key: Key): void;
@@ -150,7 +237,7 @@ export interface ComboBoxState<T = unknown> {
   /** Select a key and close the menu (for ListState compatibility). */
   select(key: Key): void;
   /** The selection mode. */
-  readonly selectionMode: Accessor<"single" | "multiple">;
+  readonly selectionMode: Accessor<M>;
   /** Check if a key is selected. */
   isSelected(key: Key): boolean;
   /** Whether the combobox is disabled. */
@@ -172,17 +259,17 @@ export const defaultContainsFilter: FilterFn = (textValue, inputValue) => {
  * Creates state for a combobox component.
  * Combines list state with input value management and filtering.
  */
-export function createComboBoxState<T = unknown>(
-  props: MaybeAccessor<ComboBoxStateProps<T>>,
-): ComboBoxState<T> {
-  const getProps = () => access(props);
+export function createComboBoxState<T = unknown, M extends ComboBoxSelectionMode = "single">(
+  props: MaybeAccessor<ComboBoxStateProps<T, M>>,
+): ComboBoxState<T, M> {
+  const getProps = propsAccessor(props);
 
   // Extract options with defaults
   const menuTrigger = () => getProps().menuTrigger ?? "input";
   const allowsEmptyCollection = () => getProps().allowsEmptyCollection ?? false;
   const allowsCustomValue = () => getProps().allowsCustomValue ?? false;
   const shouldCloseOnBlur = () => getProps().shouldCloseOnBlur ?? true;
-  const isMultiple = () => getProps().selectionMode === "multiple";
+  const isMultiple = () => (getProps().selectionMode ?? "single") === "multiple";
 
   // Track focus strategy for list navigation
   const [focusStrategy, setFocusStrategy] = createInternalSignal<FocusStrategy | null>(null);
@@ -193,31 +280,37 @@ export function createComboBoxState<T = unknown>(
   // Track the menu open trigger
   let menuOpenTrigger: MenuTriggerAction = "focus";
 
-  // ---- Multi-select State ----
-  const isMultiSelectionControlled = () => getProps().selectedKeys !== undefined;
-  const [internalSelectedKeys, setInternalSelectedKeys] = createInternalSignal<Set<Key>>(
-    new Set(getProps().defaultSelectedKeys ?? []),
-  );
+  // ---- Value ----
+  // One signal matches upstream ValueType<M>. `selectedKey` stays as a
+  // deprecated single-mode view. Multiple mode reads and writes `value`.
+  type StoredComboBoxValue = Key | readonly Key[] | null;
 
-  const selectedKeys: Accessor<Set<Key>> = () => {
-    return isMultiSelectionControlled()
-      ? new Set(getProps().selectedKeys ?? [])
-      : internalSelectedKeys();
+  const controlledPropValue = (): StoredComboBoxValue | undefined => {
+    const propsNow = getProps();
+    if (propsNow.value !== undefined) {
+      return propsNow.value as StoredComboBoxValue;
+    }
+    if (!isMultiple() && propsNow.selectedKey !== undefined) {
+      return propsNow.selectedKey;
+    }
+    return undefined;
   };
 
-  const setSelectedKeys = (keys: Set<Key>) => {
-    if (!isMultiSelectionControlled()) {
-      setInternalSelectedKeys(new Set(keys));
+  const isValueControlled = () => controlledPropValue() !== undefined;
+
+  const initialStoredValue = (): StoredComboBoxValue => {
+    const propsNow = getProps();
+    if (propsNow.defaultValue !== undefined) {
+      return propsNow.defaultValue as StoredComboBoxValue;
     }
-    getProps().onSelectionChangeMultiple?.(keys);
+    if ((propsNow.selectionMode ?? "single") === "multiple") {
+      return [];
+    }
+    return propsNow.defaultSelectedKey ?? null;
   };
 
-  // ---- Selection State (single mode) ----
-  // Note: Selection state is initialized first because input value may depend on it
-  const isSelectionControlled = () => getProps().selectedKey !== undefined;
-  const [internalSelectedKey, setInternalSelectedKey] = createInternalSignal<Key | null>(
-    getProps().defaultSelectedKey ?? null,
-  );
+  const [internalValue, setInternalValue] =
+    createInternalSignal<StoredComboBoxValue>(initialStoredValue());
 
   // ---- Input Value State ----
   // Initialized after selection so we can derive from selected item if needed
@@ -247,20 +340,124 @@ export function createComboBoxState<T = unknown>(
   // Track last committed input value
   const [lastValue, setLastValue] = createInternalSignal(inputValue());
 
+  const storedValue = (): StoredComboBoxValue => {
+    const controlled = controlledPropValue();
+    return controlled !== undefined ? controlled : internalValue();
+  };
+
+  // `Array.isArray` narrows `readonly Key[]` to `any[]` and then fails to
+  // exclude that array from the scalar branch. A string/number check keeps
+  // the caller's readonly list intact.
+  const displayValue = (): Key | readonly Key[] | null => {
+    const current = storedValue();
+    if (!isMultiple()) {
+      return isKeyList(current) ? (current[0] ?? null) : current;
+    }
+    if (isKeyList(current)) return current;
+    if (current == null) return EMPTY_COMBOBOX_KEYS;
+    return [current];
+  };
+
   const selectedKey: Accessor<Key | null> = () => {
-    return isSelectionControlled() ? (getProps().selectedKey ?? null) : internalSelectedKey();
+    if (isMultiple()) return null;
+    const current = displayValue();
+    return isKeyList(current) ? (current[0] ?? null) : current;
   };
 
-  const setSelectedKey = (key: Key | null) => {
+  const selectedKeys: Accessor<Set<Key>> = () => {
+    const current = displayValue();
+    if (isKeyList(current)) return new Set(current);
+    return current == null ? new Set() : new Set([current]);
+  };
+
+  const setValue = (next: Key | readonly Key[] | null) => {
     // Solid 2 batches writes onto a microtask, so a fully controlled
-    // onSelectionChange that updates selectedKey then inputValue settles in
+    // onSelectionChange that updates the value then inputValue settles in
     // one flush instead of closing then auto-opening.
-    if (!isSelectionControlled()) {
-      setInternalSelectedKey(key);
+    if (!isMultiple()) {
+      const key: Key | null =
+        typeof next === "string" || typeof next === "number"
+          ? next
+          : next === null
+            ? null
+            : (next[0] ?? null);
+      const previous = untrack(selectedKey);
+      if (!isValueControlled()) {
+        setInternalValue(key);
+      }
+      getProps().onChange?.(key as ComboBoxChangeValueType<M>);
+      if (key !== previous) {
+        getProps().onSelectionChange?.(key);
+      }
+      return;
+    }
+
+    // Copy into state so the caller's list is never stored or mutated.
+    // `onChange` gets a second array, so a callback can mutate its argument
+    // without changing state or the input.
+    const keys: Key[] =
+      typeof next === "string" || typeof next === "number"
+        ? [next]
+        : next === null
+          ? []
+          : [...next];
+    if (!isValueControlled()) {
+      setInternalValue(keys);
     }
-    getProps().onSelectionChange?.(key);
+    getProps().onChange?.([...keys] as ComboBoxChangeValueType<M>);
   };
 
+  const setSelectedKey = (key: Key | null) => {
+    setValue(key);
+  };
+
+  const defaultValue: ComboBoxValueType<M> = (() => {
+    const propsNow = getProps();
+    const resolved =
+      propsNow.defaultValue !== undefined
+        ? propsNow.defaultValue
+        : isMultiple()
+          ? (EMPTY_COMBOBOX_KEYS as unknown as ComboBoxValueType<M>)
+          : ((propsNow.defaultSelectedKey ?? null) as ComboBoxValueType<M>);
+    return (resolved ?? untrack(displayValue)) as ComboBoxValueType<M>;
+  })();
+
+  const defaultSelectedKey =
+    getProps().defaultSelectedKey ?? (isMultiple() ? null : (untrack(displayValue) as Key | null));
+
+  const validationValue = createMemo<ComboBoxValidationValue<M> | null>(() => {
+    const dVal = displayValue();
+    if (isKeyList(dVal) && dVal.length === 0) {
+      return null;
+    }
+    return {
+      inputValue: inputValue(),
+      value: (isKeyList(dVal) ? [...dVal] : dVal) as ComboBoxValidationType<M>,
+      selectedKey: selectedKey(),
+    };
+  });
+
+  const validation = createFormValidationState({
+    get value() {
+      return validationValue();
+    },
+    get isInvalid() {
+      return getProps().isInvalid;
+    },
+    get validationState() {
+      return getProps().validationState;
+    },
+    get validate() {
+      return getProps().validate;
+    },
+    get name() {
+      return getProps().name;
+    },
+    get validationBehavior() {
+      return getProps().validationBehavior ?? "native";
+    },
+  });
+
   // ---- Overlay State ----
   // Assigned after createListState; onOpenChange only fires after both exist
   // except a defaultOpen init, which we skip via the optional call.
@@ -303,34 +500,37 @@ export function createComboBoxState<T = unknown>(
     get selectionMode() {
       return isMultiple() ? ("multiple" as const) : ("single" as const);
     },
-    disallowEmptySelection: false,
+    // RAC useComboBoxState.ts:254-255. Single selection cannot be toggled
+    // empty. Duplicate events re-emit the same key so a click on the selected
+    // option reaches the reset-and-close branch below. Multiple selection
+    // still allows clearing the last key.
+    get disallowEmptySelection() {
+      return !isMultiple();
+    },
+    allowDuplicateSelectionEvents: true,
     get selectedKeys() {
-      if (isMultiple()) {
-        return Array.from(selectedKeys());
-      }
-      const key = selectedKey();
-      return key != null ? [key] : [];
+      return convertValue(displayValue());
     },
     onSelectionChange(keys) {
       if (keys === "all") return;
 
       if (isMultiple()) {
-        // In multiple mode, toggle selections
-        const newKeys = new Set(keys);
-        setSelectedKeys(newKeys);
+        setValue([...keys]);
         return;
       }
 
       const key = keys.size > 0 ? Array.from(keys)[0] : null;
 
-      // If same key selected, just reset input and close
+      // RAC useComboBoxState.ts:265-270 — same key still notifies, then
+      // resets the input and closes (click on the already selected option).
       if (key === selectedKey()) {
+        getProps().onSelectionChange?.(key);
         resetInputValue();
         closeMenu();
         return;
       }
 
-      setSelectedKey(key);
+      setValue(key);
     },
   });
 
@@ -374,13 +574,16 @@ export function createComboBoxState<T = unknown>(
   // Initialize input value from selected item if not already set
   // This runs once on creation
   if (!inputInitialized && !isInputControlled()) {
-    const defaultKey = getProps().defaultSelectedKey;
-    if (defaultKey != null && !getProps().defaultInputValue) {
-      // Get the text value from the collection for the default selected key
-      const item = originalCollection().getItem(defaultKey);
-      if (item) {
-        setInternalInputValue(item.textValue);
-        setLastValue(item.textValue);
+    // RAC getDefaultInputValue: an explicit empty defaultInputValue wins.
+    // Multiple mode does not seed the input from the first selected item.
+    if (getProps().defaultInputValue == null && !isMultiple()) {
+      const key = selectedKey();
+      if (key != null) {
+        const item = originalCollection().getItem(key);
+        if (item) {
+          setInternalInputValue(item.textValue);
+          setLastValue(item.textValue);
+        }
       }
     }
     inputInitialized = true;
@@ -388,8 +591,8 @@ export function createComboBoxState<T = unknown>(
 
   // ---- Helper Functions ----
   const resetInputValue = () => {
-    const item = selectedItem();
-    const textValue = item?.textValue ?? "";
+    const key = selectedKey();
+    const textValue = key != null ? (originalCollection().getItem(key)?.textValue ?? "") : "";
     setLastValue(textValue);
     setInputValue(textValue);
   };
@@ -483,21 +686,35 @@ export function createComboBoxState<T = unknown>(
 
   // ---- Commit/Revert Logic ----
   const commitCustomValue = () => {
-    setSelectedKey(null);
+    if (isMultiple()) {
+      // Custom text is independent of the selected items.
+      setLastValue(inputValue());
+      closeMenu();
+      return;
+    }
+    setValue(null);
     closeMenu();
   };
 
-  const commitSelection = () => {
-    // If both are controlled, just call onSelectionChange
-    if (isSelectionControlled() && isInputControlled()) {
-      getProps().onSelectionChange?.(selectedKey());
-      const item = selectedItem();
+  const commitSelection = (shouldForceSelectionChange = false) => {
+    // Both the value and the input are controlled: notify, then close.
+    // Otherwise reset the input for the caller.
+    if (isValueControlled() && isInputControlled()) {
+      const key = selectedKey();
+      const itemText = key != null ? (originalCollection().getItem(key)?.textValue ?? "") : "";
+      if (shouldForceSelectionChange || isMultiple() || inputValue() !== itemText) {
+        getProps().onSelectionChange?.(key);
+        const current = displayValue();
+        const changeValue = (
+          isKeyList(current) ? [...current] : current
+        ) as ComboBoxChangeValueType<M>;
+        getProps().onChange?.(changeValue);
+      }
       // RAC useComboBoxState.ts:543-545 — stop the auto-open-on-input effect
       // from reopening after this close.
-      setLastValue(item?.textValue ?? "");
+      setLastValue(itemText);
       closeMenu();
     } else {
-      // Reset input to selected item's text
       resetInputValue();
       closeMenu();
     }
@@ -520,21 +737,16 @@ export function createComboBoxState<T = unknown>(
   const commit = () => {
     const focusedKey = listState.focusedKey();
 
-    if (isMultiple()) {
-      // In multiple mode, toggle the focused item without closing
-      if (overlayState.isOpen() && focusedKey != null) {
-        select(focusedKey);
-      }
-      return;
-    }
-
     if (overlayState.isOpen() && focusedKey != null) {
-      // RAC useComboBoxState.ts:564-572 — already-selected key goes through
-      // commitSelection. A new key is `selectionManager.select()` without
-      // close; the open/close effect then closes while the menu is still
-      // open, so auto-open (input !== last && !isOpen) is skipped.
-      if (selectedKey() === focusedKey) {
-        commitSelection();
+      // RAC useComboBoxState.ts:564-572 — an already-selected single key goes
+      // through commitSelection. A new single key is `selectionManager.select()`
+      // without close; the open/close effect then closes while the menu is
+      // still open, so auto-open (input !== last && !isOpen) is skipped.
+      // Multiple toggles through setValue and leaves the menu open.
+      if (!isMultiple() && selectedKey() === focusedKey) {
+        commitSelection(true);
+      } else if (isMultiple()) {
+        select(focusedKey);
       } else {
         listState.selectionManager.select(focusedKey);
       }
@@ -554,12 +766,29 @@ export function createComboBoxState<T = unknown>(
   // ---- Focus Handling ----
   const [isFocused, setIsFocused] = createInternalSignal(false);
 
-  // RAC useComboBoxState.ts:578-593 also keeps `valueOnFocus` and, on blur,
-  // calls `validation.commitValidation()` when the input value or the display
-  // value moved while focused. This hook has no validation state at all, so
-  // the binding was written and never read; #560 owes the whole wiring.
+  let valueOnFocus: [string, Key | readonly Key[] | null] = [
+    untrack(inputValue),
+    untrack(displayValue) as Key | readonly Key[] | null,
+  ];
+
+  const hasMoved = (a: Key | readonly Key[] | null, b: Key | readonly Key[] | null): boolean => {
+    if (a === b) return false;
+    if (Array.isArray(a) && Array.isArray(b)) {
+      if (a.length !== b.length) return true;
+      for (let i = 0; i < a.length; i++) {
+        if (a[i] !== b[i]) return true;
+      }
+      return false;
+    }
+    return true;
+  };
+
+  // RAC useComboBoxState.ts:578-593 keeps `valueOnFocus = useRef([inputValue, displayValue])`
+  // and, on blur, calls `validation.commitValidation()` when the input value or the display
+  // value moved while focused.
   const setFocused = (focused: boolean) => {
     if (focused) {
+      valueOnFocus = [inputValue(), displayValue() as Key | readonly Key[] | null];
       if (menuTrigger() === "focus" && !getProps().isReadOnly) {
         open(null, "focus");
       }
@@ -567,6 +796,12 @@ export function createComboBoxState<T = unknown>(
       if (shouldCloseOnBlur()) {
         commitValue();
       }
+      if (
+        inputValue() !== valueOnFocus[0] ||
+        hasMoved(displayValue() as Key | readonly Key[] | null, valueOnFocus[1])
+      ) {
+        validation.commitValidation();
+      }
     }
     setIsFocused(focused);
   };
@@ -593,7 +828,8 @@ export function createComboBoxState<T = unknown>(
       trigger: menuTrigger(),
       showingAll: showAllItems(),
       inputControlled: isInputControlled(),
-      selectionControlled: isSelectionControlled(),
+      selectionControlled: isValueControlled(),
+      multiple: isMultiple(),
     }),
     ({
       input,
@@ -607,6 +843,7 @@ export function createComboBoxState<T = unknown>(
       showingAll,
       inputControlled,
       selectionControlled,
+      multiple,
     }) => {
       // Auto-open when typing
       if (
@@ -634,9 +871,10 @@ export function createComboBoxState<T = unknown>(
         listState.setFocusedKey(null);
         setShowAllItems(false);
 
-        // Clear selection when input is cleared (if not fully controlled)
-        if (input === "" && (!inputControlled || !selectionControlled)) {
-          setSelectedKey(null);
+        // Clear selection when the input is cleared. Fully controlled single
+        // values, and every multiple value, stay put.
+        if (!multiple && input === "" && (!inputControlled || !selectionControlled)) {
+          setValue(null);
         }
 
         setLastValue(input);
@@ -671,7 +909,7 @@ export function createComboBoxState<T = unknown>(
         key,
         textValue: item?.textValue ?? "",
         inputControlled: isInputControlled(),
-        selectionControlled: isSelectionControlled(),
+        selectionControlled: isValueControlled(),
       };
     },
     (data) => {
@@ -691,49 +929,51 @@ export function createComboBoxState<T = unknown>(
   // These methods allow createOption to work with ComboBoxState
   const select = (key: Key) => {
     if (isMultiple()) {
-      // Toggle selection in multiple mode
       const current = new Set(selectedKeys());
       if (current.has(key)) {
         current.delete(key);
       } else {
         current.add(key);
       }
-      setSelectedKeys(current);
-      // Don't close menu and don't reset input in multi-select mode
+      setValue([...current]);
     } else {
-      setSelectedKey(key);
+      setValue(key);
       closeMenu();
     }
   };
 
+  const setSelectedKeys = (keys: Iterable<Key>) => {
+    setValue([...keys]);
+  };
+
   const removeSelectedKey = (key: Key) => {
-    if (isMultiple()) {
-      const current = new Set(selectedKeys());
-      current.delete(key);
-      setSelectedKeys(current);
-    }
+    if (!isMultiple()) return;
+    setValue([...selectedKeys()].filter((selected) => selected !== key));
   };
 
-  const selectionMode: Accessor<"single" | "multiple"> = () => getProps().selectionMode ?? "single";
+  const selectionMode: Accessor<M> = () => (getProps().selectionMode ?? "single") as M;
 
-  const isSelected = (key: Key) => {
-    if (isMultiple()) {
-      return selectedKeys().has(key);
-    }
-    return selectedKey() === key;
-  };
+  const isSelected = (key: Key) => selectedKeys().has(key);
 
   // ---- Return State ----
   return {
+    realtimeValidation: validation.realtimeValidation,
+    displayValidation: validation.displayValidation,
+    updateValidation: validation.updateValidation,
+    resetValidation: validation.resetValidation,
+    commitValidation: validation.commitValidation,
     collection: displayedCollection,
     isOpen: overlayState.isOpen,
     open,
     close: commitValue,
     toggle,
     selectedKey,
-    defaultSelectedKey: getProps().defaultSelectedKey ?? null,
+    defaultSelectedKey,
     selectedItem,
     setSelectedKey,
+    value: () => displayValue() as ComboBoxValueType<M>,
+    defaultValue,
+    setValue,
     selectedKeys,
     setSelectedKeys,
     selectedItems,
@@ -766,6 +1006,16 @@ export function createComboBoxState<T = unknown>(
   };
 }
 
+function isKeyList(value: Key | readonly Key[] | null): value is readonly Key[] {
+  return value !== null && typeof value !== "string" && typeof value !== "number";
+}
+
+function convertValue(value: Key | readonly Key[] | null | undefined): readonly Key[] {
+  if (value == null) return [];
+  if (typeof value === "string" || typeof value === "number") return [value];
+  return value;
+}
+
 /**
  * Filter a collection based on input value.
  * RAC `useComboBoxState.ts:644-672` copies nodes into a new `ListCollection`,