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

package/src/combobox/createComboBoxState.ts

@@ -1,3 +1,17 @@
+/*
+ * Copyright 2020 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+// Ported to SolidJS for Proyecto Viviana; based on packages/react-stately/src/combobox/useComboBoxState.ts
+
 /**
  * State management for ComboBox components.
  * Based on @react-stately/combobox useComboBoxState.
@@ -6,12 +20,19 @@
  * either type to filter options or select from a list.
  */
 
-import { createSignal, createMemo, createEffect, untrack, type Accessor } from "solid-js";
-import { access, type MaybeAccessor } from "../utils";
-import { createListState } from "../collections/createListState";
+import { createMemo, createEffect, untrack } from "solid-js";
+import type { Accessor } from "solid-js";
+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";
 
@@ -19,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. */
@@ -32,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). */
@@ -74,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>>;
   /**
@@ -93,17 +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>>;
-  /** 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;
@@ -132,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. */
@@ -154,59 +259,65 @@ 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] = createSignal<FocusStrategy | null>(null);
+  const [focusStrategy, setFocusStrategy] = createInternalSignal<FocusStrategy | null>(null);
 
   // Track whether we're showing all items (vs filtered)
-  const [showAllItems, setShowAllItems] = createSignal(false);
+  const [showAllItems, setShowAllItems] = createInternalSignal(false);
 
   // Track the menu open trigger
   let menuOpenTrigger: MenuTriggerAction = "focus";
 
-  // ---- Multi-select State ----
-  const isMultiSelectionControlled = () => getProps().selectedKeys !== undefined;
-  const [internalSelectedKeys, setInternalSelectedKeys] = createSignal<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] = createSignal<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
   const isInputControlled = () => getProps().inputValue !== undefined;
 
   // We'll set the proper initial value after collection is created
-  const [internalInputValue, setInternalInputValue] = createSignal(
+  const [internalInputValue, setInternalInputValue] = createInternalSignal(
     getProps().defaultInputValue ?? "",
   );
   // Track if we've initialized input from selection
@@ -217,6 +328,9 @@ export function createComboBoxState<T = unknown>(
   };
 
   const setInputValue = (value: string) => {
+    // Solid 2 batches writes onto a microtask, so onInputChange and the
+    // auto-open effect settle in one flush (CB-OC-03: onInputChange then
+    // onOpenChange(true, "input")).
     if (!isInputControlled()) {
       setInternalInputValue(value);
     }
@@ -224,20 +338,130 @@ export function createComboBoxState<T = unknown>(
   };
 
   // Track last committed input value
-  const [lastValue, setLastValue] = createSignal(inputValue());
+  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) => {
-    if (!isSelectionControlled()) {
-      setInternalSelectedKey(key);
+  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 the value then inputValue settles in
+    // one flush instead of closing then auto-opening.
+    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;
     }
-    getProps().onSelectionChange?.(key);
+
+    // 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().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.
+  let listState!: ListState<T>;
   const overlayState = createOverlayTriggerState({
     get isOpen() {
       return getProps().isOpen;
@@ -247,11 +471,16 @@ export function createComboBoxState<T = unknown>(
     },
     onOpenChange(isOpen: boolean) {
       getProps().onOpenChange?.(isOpen, isOpen ? menuOpenTrigger : undefined);
+      // RAC useComboBoxState.ts:314-317
+      listState?.setFocused(isOpen);
+      if (!isOpen) {
+        listState?.setFocusedKey(null);
+      }
     },
   });
 
   // ---- List State (unfiltered collection) ----
-  const listState = createListState<T>({
+  listState = createListState<T>({
     get items() {
       // Use items or defaultItems
       return getProps().items ?? getProps().defaultItems ?? [];
@@ -271,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);
     },
   });
 
@@ -307,16 +539,12 @@ export function createComboBoxState<T = unknown>(
 
   const filteredCollection = createMemo<Collection<T>>(() => {
     const collection = originalCollection();
-    const input = inputValue();
     const filter = getProps().defaultFilter;
-
-    // If no filter function provided, return original collection
-    if (!filter) {
+    // RAC useComboBoxState.ts:297-302 — no default filter if items are controlled.
+    if (getProps().items != null || !filter) {
       return collection;
     }
-
-    // Filter the collection based on input value
-    return filterCollection(collection, input, filter);
+    return filterCollection(collection, inputValue(), filter);
   });
 
   // The displayed collection depends on showAllItems flag
@@ -346,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;
@@ -360,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);
   };
@@ -374,13 +605,12 @@ export function createComboBoxState<T = unknown>(
 
   // ---- Open/Toggle Logic ----
   // Auto-focus the menu on open the way upstream's listbox does via its
-  // `autoFocus: state.focusStrategy || true` prop (useComboBox.ts:490 → useSelectableCollection):
-  // the first selectable selected key, else the first/last key for an explicit
-  // strategy, else nothing. The port drives this from the state (createListBox
-  // reimplements nav inline and does not honor a listbox `autoFocus` prop), so
-  // BOTH open() and toggle() must apply it — a button/mouse open routes through
-  // toggle(), and omitting it there left the menu opened with no active option
-  // (no aria-activedescendant / no highlighted row) unlike upstream.
+  // `autoFocus: state.focusStrategy || true` prop (useComboBox.ts:535 →
+  // useSelectableCollection). createListBox does not honor a listbox
+  // `autoFocus` prop, so BOTH open() and toggle() apply it here. RAC applies
+  // this in a later effect; doing it synchronously keeps the first option
+  // paint (slot `aria-labelledby`) stable. createComboBox still announces
+  // option count on open.
   const applyOpenFocus = (strategy: FocusStrategy | null) => {
     const key = selectedKey();
     const nextFocusedKey =
@@ -398,15 +628,20 @@ export function createComboBoxState<T = unknown>(
   const open = (strategy: FocusStrategy | null = null, trigger?: MenuTriggerAction) => {
     const displayAll = trigger === "manual" || (trigger === "focus" && menuTrigger() === "focus");
 
-    // Check if we should open
+    // RAC useComboBoxState.ts:331-340 — controlled `items` may open empty;
+    // showAllItems only when items are undefined (collection filtering).
     const filtered = filteredCollection();
     const original = originalCollection();
+    const items = getProps().items;
     const canOpen =
-      allowsEmptyCollection() || filtered.size > 0 || (displayAll && original.size > 0);
+      allowsEmptyCollection() ||
+      filtered.size > 0 ||
+      (displayAll && original.size > 0) ||
+      items != null;
 
     if (!canOpen) return;
 
-    if (displayAll && !overlayState.isOpen()) {
+    if (displayAll && !overlayState.isOpen() && items === undefined) {
       setShowAllItems(true);
     }
 
@@ -421,17 +656,20 @@ export function createComboBoxState<T = unknown>(
   const toggle = (strategy: FocusStrategy | null = null, trigger?: MenuTriggerAction) => {
     const displayAll = trigger === "manual" || (trigger === "focus" && menuTrigger() === "focus");
 
-    // Check if we can open (if closed)
     const filtered = filteredCollection();
     const original = originalCollection();
+    const items = getProps().items;
     const canOpen =
-      allowsEmptyCollection() || filtered.size > 0 || (displayAll && original.size > 0);
+      allowsEmptyCollection() ||
+      filtered.size > 0 ||
+      (displayAll && original.size > 0) ||
+      items != null;
 
     if (!canOpen && !overlayState.isOpen()) return;
 
     const willOpen = !overlayState.isOpen();
 
-    if (displayAll && willOpen) {
+    if (displayAll && willOpen && items === undefined) {
       setShowAllItems(true);
     }
 
@@ -448,19 +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();
-      setLastValue(item?.textValue ?? "");
+  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(itemText);
       closeMenu();
     } else {
-      // Reset input to selected item's text
       resetInputValue();
       closeMenu();
     }
@@ -483,22 +737,18 @@ 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) {
-      // If focused key is already selected, just commit
-      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 {
-        // Select the focused item
-        setSelectedKey(focusedKey);
-        closeMenu();
+        listState.selectionManager.select(focusedKey);
       }
     } else {
       commitValue();
@@ -514,12 +764,31 @@ export function createComboBoxState<T = unknown>(
   };
 
   // ---- Focus Handling ----
-  const [isFocused, setIsFocused] = createSignal(false);
-  let valueOnFocus = "";
+  const [isFocused, setIsFocused] = createInternalSignal(false);
+
+  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();
+      valueOnFocus = [inputValue(), displayValue() as Key | readonly Key[] | null];
       if (menuTrigger() === "focus" && !getProps().isReadOnly) {
         open(null, "focus");
       }
@@ -527,47 +796,93 @@ 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);
   };
 
   // ---- Effects for Auto Open/Close ----
-  createEffect(() => {
-    const input = inputValue();
-    const filtered = filteredCollection();
-    const isOpen = overlayState.isOpen();
-    const last = lastValue();
-    const focused = isFocused();
-
-    // Auto-open when typing
-    if (
-      focused &&
-      (filtered.size > 0 || allowsEmptyCollection()) &&
-      !isOpen &&
-      input !== last &&
-      menuTrigger() !== "manual"
-    ) {
-      open(null, "input");
-    }
+  // RAC useComboBoxState.ts:408-496 is one effect: auto-open, auto-close,
+  // close-on-selection, then lastValue. Close-on-selection must not run as a
+  // later effect — after a fully-controlled commit the parent updates
+  // inputValue, a trailing close leaves !isOpen && input !== last, and
+  // auto-open reopens (D13 Enter re-announces "N options available.").
+  // lastDisplayValue starts as the current key so an initial selectedKey is
+  // not treated as a selection change (RAC lastValueRef = useRef(displayValue)).
+  let lastDisplayValue: Key | null | undefined = untrack(selectedKey);
+
+  createEffect(
+    () => ({
+      input: inputValue(),
+      filtered: filteredCollection(),
+      isOpen: overlayState.isOpen(),
+      last: lastValue(),
+      focused: isFocused(),
+      key: isMultiple() ? null : selectedKey(),
+      allowsEmpty: allowsEmptyCollection(),
+      trigger: menuTrigger(),
+      showingAll: showAllItems(),
+      inputControlled: isInputControlled(),
+      selectionControlled: isValueControlled(),
+      multiple: isMultiple(),
+    }),
+    ({
+      input,
+      filtered,
+      isOpen,
+      last,
+      focused,
+      key,
+      allowsEmpty,
+      trigger,
+      showingAll,
+      inputControlled,
+      selectionControlled,
+      multiple,
+    }) => {
+      // Auto-open when typing
+      if (
+        focused &&
+        (filtered.size > 0 || allowsEmpty) &&
+        !isOpen &&
+        input !== last &&
+        trigger !== "manual"
+      ) {
+        open(null, "input");
+      }
 
-    // Auto-close when empty (unless showing all)
-    if (!showAllItems() && !allowsEmptyCollection() && isOpen && filtered.size === 0) {
-      closeMenu();
-    }
+      // Auto-close when empty (unless showing all)
+      if (!showingAll && !allowsEmpty && isOpen && filtered.size === 0) {
+        closeMenu();
+      }
 
-    // Clear focused key when input changes
-    if (input !== last) {
-      listState.setFocusedKey(null);
-      setShowAllItems(false);
+      // Close when an item is selected (RAC displayValue !== lastValueRef).
+      if (key != null && key !== lastDisplayValue) {
+        closeMenu();
+      }
+
+      // Clear focused key when input changes
+      if (input !== last) {
+        listState.setFocusedKey(null);
+        setShowAllItems(false);
+
+        // Clear selection when the input is cleared. Fully controlled single
+        // values, and every multiple value, stay put.
+        if (!multiple && input === "" && (!inputControlled || !selectionControlled)) {
+          setValue(null);
+        }
 
-      // Clear selection when input is cleared (if not fully controlled)
-      if (input === "" && (!isInputControlled() || !isSelectionControlled())) {
-        setSelectedKey(null);
+        setLastValue(input);
       }
 
-      setLastValue(input);
-    }
-  });
+      lastDisplayValue = key;
+    },
+  );
 
   // Keep the input text in sync with the selected item (single mode only).
   //
@@ -585,79 +900,82 @@ export function createComboBoxState<T = unknown>(
   // dependency. `originalCollection()` stays tracked (the unfiltered collection
   // only changes when `items` change, never on filtering) so a preset selection
   // still gets its text once async items arrive.
-  createEffect(() => {
-    if (isMultiple()) return;
-    const key = selectedKey();
-    const item = key != null ? originalCollection().getItem(key) : null;
-    const textValue = item?.textValue ?? "";
-
-    // Only update if selection changed and not fully controlled
-    if (!isInputControlled() || !isSelectionControlled()) {
-      if (key != null && textValue !== untrack(inputValue)) {
-        setInputValue(textValue);
-        setLastValue(textValue);
+  createEffect(
+    () => {
+      if (isMultiple()) return null;
+      const key = selectedKey();
+      const item = key != null ? originalCollection().getItem(key) : null;
+      return {
+        key,
+        textValue: item?.textValue ?? "",
+        inputControlled: isInputControlled(),
+        selectionControlled: isValueControlled(),
+      };
+    },
+    (data) => {
+      if (!data) return;
+      const { key, textValue, inputControlled, selectionControlled } = data;
+      // Only update if selection changed and not fully controlled
+      if (!inputControlled || !selectionControlled) {
+        if (key != null && textValue !== untrack(inputValue)) {
+          setInputValue(textValue);
+          setLastValue(textValue);
+        }
       }
-    }
-  });
-
-  // Close when selection changes (only in single mode)
-  createEffect((prevKey: Key | null | undefined) => {
-    if (isMultiple()) return undefined;
-    const key = selectedKey();
-    if (key != null && key !== prevKey) {
-      closeMenu();
-    }
-    return key;
-  }, undefined);
+    },
+  );
 
   // ---- Selection Methods for ListState compatibility ----
   // 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,
     removeSelectedKey,
     inputValue,
@@ -688,8 +1006,21 @@ 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`,
+ * which reassigns `index` (ListCollection.ts:51-53). Keeping the original
+ * `index` makes virtualized `aria-posinset` report the unfiltered position.
  */
 function filterCollection<T>(
   collection: Collection<T>,
@@ -701,19 +1032,18 @@ function filterCollection<T>(
   }
 
   const filteredItems: CollectionNode<T>[] = [];
+  let index = 0;
 
   for (const item of collection) {
     if (item.type === "section") {
-      // Filter section children
       const filteredChildren: CollectionNode<T>[] = [];
       if (item.childNodes) {
         for (const child of item.childNodes) {
           if (child.type === "item" && filter(child.textValue, inputValue)) {
-            filteredChildren.push(child);
+            filteredChildren.push({ ...child, index: index++ });
           }
         }
       }
-      // Only include section if it has matching children
       if (filteredChildren.length > 0) {
         filteredItems.push({
           ...item,
@@ -722,109 +1052,12 @@ function filterCollection<T>(
       }
     } else if (item.type === "item") {
       if (filter(item.textValue, inputValue)) {
-        filteredItems.push(item);
-      }
-    }
-  }
-
-  // Create a new collection from filtered items
-  return createFilteredCollection(filteredItems, collection);
-}
-
-/**
- * Create a filtered collection wrapper.
- */
-function createFilteredCollection<T>(
-  items: CollectionNode<T>[],
-  original: Collection<T>,
-): Collection<T> {
-  const itemMap = new Map<Key, CollectionNode<T>>();
-
-  for (const item of items) {
-    itemMap.set(item.key, item);
-    if (item.childNodes) {
-      for (const child of item.childNodes) {
-        itemMap.set(child.key, child);
+        filteredItems.push({ ...item, index: index++ });
       }
+    } else {
+      filteredItems.push({ ...item });
     }
   }
 
-  return {
-    get size() {
-      let count = 0;
-      for (const item of items) {
-        if (item.type === "item") {
-          count++;
-        } else if (item.childNodes) {
-          count += Array.from(item.childNodes).filter((c) => c.type === "item").length;
-        }
-      }
-      return count;
-    },
-    getItem(key: Key) {
-      return itemMap.get(key) ?? null;
-    },
-    getKeys() {
-      return itemMap.keys();
-    },
-    getFirstKey() {
-      for (const item of items) {
-        if (item.type === "item") return item.key;
-        if (item.childNodes) {
-          for (const child of item.childNodes) {
-            if (child.type === "item") return child.key;
-          }
-        }
-      }
-      return null;
-    },
-    getLastKey() {
-      for (let i = items.length - 1; i >= 0; i--) {
-        const item = items[i];
-        if (item.type === "item") return item.key;
-        if (item.childNodes) {
-          const children = Array.from(item.childNodes);
-          for (let j = children.length - 1; j >= 0; j--) {
-            if (children[j].type === "item") return children[j].key;
-          }
-        }
-      }
-      return null;
-    },
-    getKeyBefore(key: Key) {
-      return original.getKeyBefore(key);
-    },
-    getKeyAfter(key: Key) {
-      return original.getKeyAfter(key);
-    },
-    at(index: number) {
-      // Flatten items for indexing
-      let currentIndex = 0;
-      for (const item of items) {
-        if (item.type === "item") {
-          if (currentIndex === index) return item;
-          currentIndex++;
-        } else if (item.childNodes) {
-          for (const child of item.childNodes) {
-            if (child.type === "item") {
-              if (currentIndex === index) return child;
-              currentIndex++;
-            }
-          }
-        }
-      }
-      return null;
-    },
-    getChildren(key: Key) {
-      const item = itemMap.get(key);
-      return item?.childNodes ?? [];
-    },
-    getTextValue(key: Key) {
-      const item = itemMap.get(key);
-      return item?.textValue ?? "";
-    },
-    [Symbol.iterator]() {
-      return items[Symbol.iterator]();
-    },
-  };
+  return new ListCollection(filteredItems);
 }