@base-ui/react 1.7.0 → 1.8.0

package/combobox/root/AriaCombobox.mjs

@@ -1,5 +1,6 @@
 'use client';
 
+import _formatErrorMessage from "@base-ui/utils/formatErrorMessage";
 import * as React from 'react';
 import { useControlled } from '@base-ui/utils/useControlled';
 import { useIsoLayoutEffect } from '@base-ui/utils/useIsoLayoutEffect';
@@ -9,7 +10,7 @@ import { useMergedRefs } from '@base-ui/utils/useMergedRefs';
 import { useValueAsRef } from '@base-ui/utils/useValueAsRef';
 import { visuallyHidden, visuallyHiddenInput } from '@base-ui/utils/visuallyHidden';
 import { useRefWithInit } from '@base-ui/utils/useRefWithInit';
-import { Store, useStore } from '@base-ui/utils/store';
+import { ReactStore } from '@base-ui/utils/store';
 import { EMPTY_ARRAY, EMPTY_OBJECT } from '@base-ui/utils/empty';
 import { isHTMLElement } from '@floating-ui/utils/dom';
 import { getOverflowAncestors, useDismiss, useFloatingRootContext, useListNavigation, useClick } from "../../floating-ui-react/index.mjs";
@@ -33,11 +34,11 @@ import { useValueChanged } from "../../internals/useValueChanged.mjs";
 import { NOOP } from "../../internals/noop.mjs";
 import { FOCUSABLE_POPUP_PROPS } from "../../utils/popups/index.mjs";
 import { mergeProps } from "../../merge-props/index.mjs";
-import { stringifyAsLabel, stringifyAsValue, isGroupedItems } from "../../internals/resolveValueLabel.mjs";
-import { compareItemEquality, defaultItemEquality, findSelectionIndex, removeItem, selectedValueIncludes } from "../../internals/itemEquality.mjs";
-import { areArraysEqual } from "../../internals/areArraysEqual.mjs";
+import { stringifyAsLabel, stringifyAsValue, flattenLeafItems, isGroupedItems } from "../../internals/resolveValueLabel.mjs";
+import { compareItemEquality, defaultItemEquality, findItemIndex, findSelectionIndex, isSelectedValueDirty, removeItem, selectedValueIncludes } from "../../internals/itemEquality.mjs";
 import { INITIAL_LAST_HIGHLIGHT, NO_ACTIVE_VALUE } from "./utils/constants.mjs";
 import { useDirection } from "../../internals/direction-context/DirectionContext.mjs";
+import { findCollectionItem } from "../items/itemCollection.mjs";
 
 /**
  * @internal
@@ -50,7 +51,7 @@ export function AriaCombobox(props) {
     defaultSelectedValue = null,
     selectedValue: selectedValueProp,
     onSelectedValueChange,
-    defaultInputValue: defaultInputValueProp,
+    defaultInputValue,
     inputValue: inputValueProp,
     open: openProp,
     defaultOpen = false,
@@ -63,15 +64,16 @@ export function AriaCombobox(props) {
     required = false,
     inputRef: inputRefProp,
     grid = false,
-    items,
+    items: itemsProp,
     filteredItems: filteredItemsProp,
     filter: filterProp,
+    filterQuery: filterQueryProp,
     openOnInputClick = true,
     autoHighlight = false,
     keepHighlight = false,
     highlightItemOnHover = true,
     loopFocus = true,
-    itemToStringLabel,
+    itemToStringLabel: itemToStringLabelProp,
     itemToStringValue,
     isItemEqualToValue = defaultItemEquality,
     virtualized = false,
@@ -105,8 +107,76 @@ export function AriaCombobox(props) {
   const collatorFilter = useCoreFilter({
     locale
   });
+
+  // Plain items are arrays; normalized `createItems()` collections are objects.
+  const collection = Array.isArray(itemsProp) ? null : itemsProp;
+  if (collection && typeof collection.label !== 'function') {
+    throw new Error(process.env.NODE_ENV !== "production" ? 'Base UI: the `items` prop received an object that is not a collection, ' + 'so its items cannot be read. Pass an array of items, an array of groups with items, ' + 'or the result of `createItems()`. ' + 'See https://base-ui.com/react/components/combobox#createitems' : _formatErrorMessage(100));
+  }
+  const items = collection ? collection.data : itemsProp;
+  const itemToValue = collection?.value;
+
+  // A projected collection's items live in the source domain, not the selection-value domain the
+  // store matches against, so they are withheld from the store.
+  const storeItems = itemToValue ? undefined : items;
+
+  // The externally filtered items projected to their selection values, with a lookup back to the
+  // source items. Declared before `itemToStringLabel`, which resolves labels from it on the
+  // first render (initial input value).
+  const externalWindow = React.useMemo(() => {
+    if (!filteredItemsProp || !itemToValue) {
+      return undefined;
+    }
+    const flat = flattenLeafItems(filteredItemsProp);
+    const values = flat.map(itemToValue);
+    let valueToItem;
+    return {
+      values,
+      findItem(itemValue, isEqual) {
+        if (!valueToItem) {
+          valueToItem = new Map();
+          for (let i = 0; i < values.length; i += 1) {
+            if (!valueToItem.has(values[i])) {
+              valueToItem.set(values[i], flat[i]);
+            }
+          }
+        }
+        return findCollectionItem(valueToItem, itemValue, isEqual);
+      }
+    };
+  }, [filteredItemsProp, itemToValue]);
+
+  // Labels selection values from current props only: collection data first, then the current
+  // external window, then the prop. Nothing from a past window is remembered — keeping a value
+  // resolvable over time means keeping its item in the collection's data.
+  const itemToStringLabel = React.useMemo(() => {
+    if (!collection) {
+      return itemToStringLabelProp;
+    }
+    return itemValue => {
+      return collection.label(itemValue, isItemEqualToValue, unresolvedValue => {
+        const externalItem = externalWindow?.findItem(unresolvedValue, isItemEqualToValue);
+        if (externalItem != null) {
+          return collection.itemLabel(externalItem);
+        }
+        return stringifyAsLabel(unresolvedValue, itemToStringLabelProp);
+      });
+    };
+  }, [collection, itemToStringLabelProp, externalWindow, isItemEqualToValue]);
+  const filterItemToString = React.useMemo(() => {
+    if (!collection) {
+      return itemToStringLabelProp;
+    }
+    return Object.assign(item => collection.itemLabel(item), {
+      selected: value => stringifyAsLabel(value, itemToStringLabel)
+    });
+  }, [collection, itemToStringLabel, itemToStringLabelProp]);
+  function stringifyValueLabel(item) {
+    return stringifyAsLabel(item, itemToStringLabel);
+  }
   const [queryChangedAfterOpen, setQueryChangedAfterOpen] = React.useState(false);
   const [closeQuery, setCloseQuery] = React.useState(null);
+  const previousCloseQueryRef = React.useRef(closeQuery);
   const listRef = React.useRef([]);
   const labelsRef = React.useRef([]);
   const popupRef = React.useRef(null);
@@ -135,7 +205,7 @@ export function AriaCombobox(props) {
   const name = fieldName ?? nameProp;
   const multiple = selectionMode === 'multiple';
   const single = selectionMode === 'single';
-  const hasInputValue = inputValueProp !== undefined || defaultInputValueProp !== undefined;
+  const hasInputValue = inputValueProp !== undefined || defaultInputValue !== undefined;
   const hasItems = items !== undefined;
   const hasFilteredItemsProp = filteredItemsProp !== undefined;
   let autoHighlightMode;
@@ -159,17 +229,17 @@ export function AriaCombobox(props) {
     }
     // `shouldBypassFiltering` already empties the query whenever a single selection's label
     // matches it exactly, so the filter never needs a selection-aware variant here.
-    return createCollatorItemFilter(collatorFilter, itemToStringLabel);
-  }, [filterProp, collatorFilter, itemToStringLabel]);
+    return createCollatorItemFilter(collatorFilter, filterItemToString);
+  }, [filterProp, collatorFilter, filterItemToString]);
 
   // If neither inputValue nor defaultInputValue are provided, derive it from the
   // selected value for single mode so the input reflects the selection on mount.
   const initialDefaultInputValue = useRefWithInit(() => {
     if (hasInputValue) {
-      return defaultInputValueProp ?? '';
+      return defaultInputValue ?? '';
     }
     if (single) {
-      return stringifyAsLabel(selectedValue, itemToStringLabel);
+      return stringifyValueLabel(selectedValue);
     }
     return '';
   }).current;
@@ -186,20 +256,12 @@ export function AriaCombobox(props) {
     state: 'open'
   });
   const isGrouped = isGroupedItems(items);
-  const query = closeQuery ?? String(inputValue).trim();
-  const selectedLabelString = single ? stringifyAsLabel(selectedValue, itemToStringLabel) : '';
+  const query = !open && closeQuery !== null ? closeQuery : String(inputValue).trim();
+  const selectedLabelString = single ? stringifyValueLabel(selectedValue) : '';
   const shouldBypassFiltering = single && !queryChangedAfterOpen && query !== '' && selectedLabelString.length === query.length && collatorFilter.contains(selectedLabelString, query);
-  const filterQuery = shouldBypassFiltering ? '' : query;
-  const shouldIgnoreExternalFiltering = hasItems && hasFilteredItemsProp && shouldBypassFiltering;
-  const flatItems = React.useMemo(() => {
-    if (!items) {
-      return EMPTY_ARRAY;
-    }
-    if (isGrouped) {
-      return items.flatMap(group => group.items);
-    }
-    return items;
-  }, [items, isGrouped]);
+  const filterQuery = shouldBypassFiltering ? '' : filterQueryProp ?? query;
+  const shouldIgnoreExternalFiltering = hasItems && hasFilteredItemsProp && shouldBypassFiltering && (!collection || collection.hasValue(selectedValue, isItemEqualToValue));
+  const flatItems = React.useMemo(() => items ? flattenLeafItems(items) : EMPTY_ARRAY, [items]);
   const filteredItems = React.useMemo(() => {
     if (filteredItemsProp && !shouldIgnoreExternalFiltering) {
       return filteredItemsProp;
@@ -222,7 +284,7 @@ export function AriaCombobox(props) {
             if (itemsToTake.length >= remainingLimit) {
               break;
             }
-            if (filter(item, filterQuery, itemToStringLabel)) {
+            if (filter(item, filterQuery, filterItemToString)) {
               itemsToTake.push(item);
             }
           }
@@ -241,7 +303,7 @@ export function AriaCombobox(props) {
     if (filterQuery === '') {
       return limit > -1 ? flatItems.slice(0, limit) :
       // The cast here is done as `flatItems` is readonly.
-      // valuesRef.current, a mutable ref, can be set to `flatFilteredItems`, which may
+      // valuesRef.current, a mutable ref, can be set to `flatFilteredValues`, which may
       // reference this exact readonly value, creating a mutation risk.
       // However, <Combobox.Item> can never mutate this value as the mutating effect
       // bails early when `items` is provided, and this is only ever returned
@@ -253,19 +315,25 @@ export function AriaCombobox(props) {
       if (limit > -1 && limitedItems.length >= limit) {
         break;
       }
-      if (filter(item, filterQuery, itemToStringLabel)) {
+      if (filter(item, filterQuery, filterItemToString)) {
         limitedItems.push(item);
       }
     }
     return limitedItems;
-  }, [filteredItemsProp, shouldIgnoreExternalFiltering, items, isGrouped, filterQuery, limit, filter, itemToStringLabel, flatItems]);
-  const flatFilteredItems = React.useMemo(() => {
-    if (isGrouped) {
-      const groups = filteredItems;
-      return groups.flatMap(g => g.items);
+  }, [filteredItemsProp, shouldIgnoreExternalFiltering, items, isGrouped, filterQuery, limit, filter, filterItemToString, flatItems]);
+
+  /**
+   * The filtered items flattened across groups and projected to their selection values.
+   */
+  const flatFilteredValues = React.useMemo(() => {
+    if (externalWindow && filteredItems === filteredItemsProp) {
+      return externalWindow.values;
     }
-    return filteredItems;
-  }, [filteredItems, isGrouped]);
+    // Explicit type argument: inferring it from a union of both shapes resolves `Item` to
+    // `Group<Item>`, which tsc rejects and tsgo does not.
+    const flat = flattenLeafItems(filteredItems);
+    return itemToValue ? flat.map(item => itemToValue(item)) : flat;
+  }, [filteredItems, filteredItemsProp, externalWindow, itemToValue]);
   const store = useRefWithInit(() => {
     // An inline list open on the first render never gets a closed pass of the closed-state
     // sync effect below, and `items`-prop lists don't self-register their index the way
@@ -275,28 +343,15 @@ export function AriaCombobox(props) {
     // doesn't move an existing highlight or scroll the list away.
     let initialSelectedIndex = null;
     if (inlineProp && open && hasItems && selectionMode !== 'none') {
-      initialSelectedIndex = findSelectionIndex(flatFilteredItems, selectedValue, isItemEqualToValue, multiple);
+      initialSelectedIndex = findSelectionIndex(flatFilteredValues, selectedValue, isItemEqualToValue, multiple);
     }
-    return new Store({
+    return new ReactStore({
       id,
       labelId: undefined,
       selectedValue,
       open,
-      items,
+      items: storeItems,
       selectionMode,
-      listRef,
-      labelsRef,
-      popupRef,
-      emptyRef,
-      inputRef,
-      startDismissRef,
-      endDismissRef,
-      keyboardActiveRef,
-      chipsContainerRef,
-      clearRef,
-      valuesRef,
-      pointerDownItemRef,
-      selectionEventRef,
       name,
       form,
       disabled,
@@ -333,7 +388,8 @@ export function AriaCombobox(props) {
       inputInsidePopup: true,
       // Avoid duplicate names in the server HTML. Popup inputs aren't rendered
       // until after hydration, so the hidden input takes over then if needed.
-      inputOwnsFormValue: selectionMode === 'none',
+      inputOwnsFormValue: selectionMode === 'none'
+    }, {
       // Placeholder callbacks replaced on first render
       onOpenChangeComplete: NOOP,
       setOpen: NOOP,
@@ -342,8 +398,21 @@ export function AriaCombobox(props) {
       setIndices: NOOP,
       handleSelection: NOOP,
       forceMount: NOOP,
-      requestSubmit: NOOP
-    });
+      requestSubmit: NOOP,
+      listRef,
+      labelsRef,
+      popupRef,
+      emptyRef,
+      inputRef,
+      startDismissRef,
+      endDismissRef,
+      keyboardActiveRef,
+      chipsContainerRef,
+      clearRef,
+      valuesRef,
+      pointerDownItemRef,
+      selectionEventRef
+    }, selectors);
   }).current;
   const fieldRawValue = selectionMode === 'none' ? inputValue : selectedValue;
   const fieldStringValue = React.useMemo(() => {
@@ -357,16 +426,17 @@ export function AriaCombobox(props) {
   }, [fieldRawValue, itemToStringValue, selectionMode, selectedValue]);
   const onItemHighlighted = useStableCallback(onItemHighlightedProp);
   const onOpenChangeComplete = useStableCallback(onOpenChangeCompleteProp);
-  const activeIndex = useStore(store, selectors.activeIndex);
-  const selectedIndex = useStore(store, selectors.selectedIndex);
-  const positionerElement = useStore(store, selectors.positionerElement);
-  const listElement = useStore(store, selectors.listElement);
-  const triggerElement = useStore(store, selectors.triggerElement);
-  const inputElement = useStore(store, selectors.inputElement);
-  const inputGroupElement = useStore(store, selectors.inputGroupElement);
-  const inline = useStore(store, selectors.inline);
-  const inputInsidePopup = useStore(store, selectors.inputInsidePopup);
-  const inputOwnsFormValue = useStore(store, selectors.inputOwnsFormValue);
+  const activeIndex = store.useState('activeIndex');
+  const selectedIndex = store.useState('selectedIndex');
+  const positionerElement = store.useState('positionerElement');
+  const listElement = store.useState('listElement');
+  const triggerElement = store.useState('triggerElement');
+  const inputElement = store.useState('inputElement');
+  const inputGroupElement = store.useState('inputGroupElement');
+  const inline = store.useState('inline');
+  const inputInsidePopup = store.useState('inputInsidePopup');
+  const inputOwnsFormValue = store.useState('inputOwnsFormValue');
+  const inputMatchesSelectedValue = single && !inputInsidePopup && inputValue === selectedLabelString;
   const triggerRef = useValueAsRef(triggerElement);
   const {
     mounted,
@@ -382,7 +452,7 @@ export function AriaCombobox(props) {
   const forceMount = useStableCallback(() => {
     if (items) {
       // Ensure typeahead works on a closed list.
-      labelsRef.current = flatFilteredItems.map(item => stringifyAsLabel(item, itemToStringLabel));
+      labelsRef.current = flatFilteredValues.map(stringifyValueLabel);
     } else {
       store.set('forceMounted', true);
     }
@@ -409,7 +479,14 @@ export function AriaCombobox(props) {
     }));
   });
   const setIndices = useStableCallback(options => {
-    store.update(options);
+    const update = {};
+    if (options.activeIndex !== undefined) {
+      update.activeIndex = options.activeIndex;
+    }
+    if (options.selectedIndex !== undefined) {
+      update.selectedIndex = options.selectedIndex;
+    }
+    store.update(update);
     const activeIndexOption = options.activeIndex;
     if (activeIndexOption === undefined) {
       return;
@@ -422,12 +499,14 @@ export function AriaCombobox(props) {
     }
   });
   const setInputValue = useStableCallback((next, eventDetails) => {
-    hadInputClearRef.current = eventDetails.reason === REASONS.inputClear;
     props.onInputValueChange?.(next, eventDetails);
     if (eventDetails.isCanceled) {
       return;
     }
 
+    // A canceled selection clear must not suppress close-completion cleanup.
+    hadInputClearRef.current = eventDetails.reason === REASONS.inputClear;
+
     // If user is typing, ensure we don't auto-highlight on open due to a race
     // with the post-open effect that sets this flag.
     if (eventDetails.reason === REASONS.inputChange) {
@@ -482,6 +561,20 @@ export function AriaCombobox(props) {
     }
     setInputValueUnwrapped(next);
   });
+  const handleInterruptedReopen = useStableCallback(isInputChange => {
+    // Preserve values supplied with the reopen rather than owned by the interrupted close.
+    const clearsPendingInput = !isInputChange && inputInsidePopup && !inline && inputValue !== '' && (String(inputValue).trim() === closeQuery || inputValue === selectedLabelString);
+
+    // Keep the flag while a visible filter survives so the `items` sync cannot overwrite it.
+    if (!isInputChange && (clearsPendingInput || inputValue === '' || inputMatchesSelectedValue)) {
+      setQueryChangedAfterOpen(false);
+    }
+    setCloseQuery(null);
+    if (clearsPendingInput) {
+      // Cleanup clears omit the selection flag and reopening gesture.
+      setInputValue('', createChangeEventDetails(REASONS.inputClear));
+    }
+  });
   const setOpen = useStableCallback((nextOpen, eventDetails) => {
     if (open === nextOpen) {
       return;
@@ -490,22 +583,17 @@ export function AriaCombobox(props) {
     // If the `Empty` component is not used, the positioner or popup should be hidden
     // with CSS. In this case, allow the Escape key to bubble to close a parent popup
     // if there are no items to show.
-    if (eventDetails.reason === REASONS.escapeKey && hasItems && flatFilteredItems.length === 0 && !emptyRef.current) {
+    if (eventDetails.reason === REASONS.escapeKey && hasItems && flatFilteredValues.length === 0 && !emptyRef.current) {
       eventDetails.allowPropagation();
     }
     props.onOpenChange?.(nextOpen, eventDetails);
     if (eventDetails.isCanceled) {
       return;
     }
-
-    // If reopening interrupts the close animation, handleUnmount won't run to clear the
-    // frozen closeQuery and pending popup input.
-    if (nextOpen && inputInsidePopup && !inline && closeQuery !== null) {
-      setQueryChangedAfterOpen(false);
-      setCloseQuery(null);
-      if (inputValue !== '' && eventDetails.reason !== REASONS.inputChange) {
-        setInputValue('', createChangeEventDetails(REASONS.inputClear, eventDetails.event));
-      }
+    if (nextOpen && closeQuery !== null) {
+      // `ComboboxInput` calls `setInputValue` before `setOpen`, so on an input-change reopen
+      // `inputValue` is still the pre-keystroke value and the typed filter always survives.
+      handleInterruptedReopen(eventDetails.reason === REASONS.inputChange);
     }
     if (!nextOpen && queryChangedAfterOpen) {
       if (single) {
@@ -531,7 +619,9 @@ export function AriaCombobox(props) {
         // if the input is outside the popup. When the input is inside the popup, defer the clear until
         // unmount so the filtered list doesn't flash to unfiltered during the exit animation.
         if (!inputInsidePopup || inline) {
-          setInputValue('', createChangeEventDetails(REASONS.inputClear, eventDetails.event));
+          setInputValue('', createChangeEventDetails(REASONS.inputClear, eventDetails.event, undefined, {
+            isItemPress: eventDetails.reason === REASONS.itemPress
+          }));
         }
       }
     }
@@ -555,7 +645,7 @@ export function AriaCombobox(props) {
     setSelectedValueUnwrapped(nextValue);
     const shouldFillInput = selectionMode === 'none' && popupRef.current && fillInputOnItemPress || single && !store.state.inputInsidePopup;
     if (shouldFillInput) {
-      setInputValue(stringifyAsLabel(nextValue, itemToStringLabel), createChangeEventDetails(eventDetails.reason, eventDetails.event));
+      setInputValue(stringifyValueLabel(nextValue), createChangeEventDetails(eventDetails.reason, eventDetails.event));
     }
   });
   const handleSelection = useStableCallback((event, itemValue) => {
@@ -585,7 +675,15 @@ export function AriaCombobox(props) {
         return;
       }
       if (store.state.inputInsidePopup) {
-        setInputValue('', createChangeEventDetails(REASONS.inputClear, eventDetails.event));
+        setInputValue('', createChangeEventDetails(REASONS.inputClear, eventDetails.event, undefined, {
+          isItemPress: true
+        }));
+        // A newly selected item stays highlighted through the clear; a deselection
+        // falls back to the standard selection anchor.
+        const pendingHighlight = pendingQueryHighlightRef.current;
+        if (pendingHighlight && !isCurrentlySelected) {
+          pendingHighlight.toggledValue = itemValue;
+        }
       } else {
         setOpen(false, eventDetails);
       }
@@ -635,7 +733,7 @@ export function AriaCombobox(props) {
           setInputValue('', createChangeEventDetails(REASONS.inputClear));
         }
       } else {
-        const stringVal = stringifyAsLabel(selectedValue, itemToStringLabel);
+        const stringVal = stringifyValueLabel(selectedValue);
         if (inputRef.current && inputRef.current.value !== stringVal) {
           // If no selection was made, treat this as clearing the typed filter.
           const reason = stringVal === '' ? REASONS.inputClear : REASONS.none;
@@ -670,14 +768,21 @@ export function AriaCombobox(props) {
   React.useImperativeHandle(props.actionsRef, () => ({
     unmount: handleUnmount
   }), [handleUnmount]);
-  useIsoLayoutEffect(function syncClosedState() {
-    if (open) {
+  useIsoLayoutEffect(function syncSelectedIndex() {
+    const closeQueryReleased = previousCloseQueryRef.current !== null && closeQuery === null;
+    previousCloseQueryRef.current = closeQuery;
+
+    // Closing indexes against the frozen filtered list. Reopening releases that query, so its
+    // rendered coordinates must be synchronized again even though the popup is already open.
+    if (open && (!closeQueryReleased || !hasItems)) {
       return;
     }
 
     // State-driven (not tied to the internal event path) so controlled closes
     // also clear a pointerdown that never received a matching item mouseup.
-    pointerDownItemRef.current = null;
+    if (!open) {
+      pointerDownItemRef.current = null;
+    }
     if (selectionMode === 'none') {
       return;
     }
@@ -688,17 +793,18 @@ export function AriaCombobox(props) {
     // items re-assert the index themselves when their registration moves; when
     // nothing is mounted the lookup resolves to `null` and each item re-registers
     // the index on the next open.
-    const registry = hasItems ? flatItems : valuesRef.current;
+    // Keep the selected index in the coordinates of the list that is actually rendered.
+    const registry = hasItems ? flatFilteredValues : valuesRef.current;
     setIndices({
       selectedIndex: findSelectionIndex(registry, selectedValue, isItemEqualToValue, multiple)
     });
-  }, [open, selectedValue, selectionMode, multiple, hasItems, flatItems, isItemEqualToValue, setIndices]);
+  }, [open, closeQuery, selectedValue, selectionMode, multiple, hasItems, flatFilteredValues, isItemEqualToValue, setIndices]);
   useIsoLayoutEffect(() => {
     if (items) {
-      valuesRef.current = flatFilteredItems;
-      listRef.current.length = flatFilteredItems.length;
+      valuesRef.current = flatFilteredValues;
+      listRef.current.length = flatFilteredValues.length;
     }
-  }, [items, flatFilteredItems]);
+  }, [items, flatFilteredValues]);
   useIsoLayoutEffect(() => {
     const pendingHighlight = pendingQueryHighlightRef.current;
     if (pendingHighlight) {
@@ -735,13 +841,18 @@ export function AriaCombobox(props) {
             // re-running this effect on every render.
             const currentSelectedValue = store.state.selectedValue;
             const isMultiple = store.state.selectionMode === 'multiple';
-            const lastSelectedValue = isMultiple && Array.isArray(currentSelectedValue) ? currentSelectedValue[currentSelectedValue.length - 1] : currentSelectedValue;
-            const hasSelection = store.state.selectionMode !== 'none' && lastSelectedValue != null;
-            if (hasSelection || clearedBySelection) {
-              const registry = hasItems || hasFilteredItemsProp ? flatFilteredItems : valuesRef.current;
-              // A selection that is no longer in the list drops the highlight rather than
-              // leaving it on whichever item now occupies that index.
-              store.set('activeIndex', hasSelection ? findSelectionIndex(registry, currentSelectedValue, store.state.isItemEqualToValue, isMultiple) : null);
+            const hasSelection = isMultiple && Array.isArray(currentSelectedValue) ? currentSelectedValue.length > 0 : store.state.selectionMode !== 'none' && currentSelectedValue != null;
+            if (hasSelection) {
+              const registry = hasItems || hasFilteredItemsProp ? flatFilteredValues : valuesRef.current;
+              // A selection-driven clear keeps the just-selected item highlighted;
+              // otherwise return to the open anchor. A selection that is no longer in
+              // the list drops the highlight rather than leaving it on whichever item
+              // now occupies that index.
+              // `findItemIndex` resolves to -1 when no value was toggled.
+              const toggledIndex = findItemIndex(registry, pendingHighlight.toggledValue, store.state.isItemEqualToValue);
+              store.set('activeIndex', toggledIndex !== -1 ? toggledIndex : findSelectionIndex(registry, currentSelectedValue, store.state.isItemEqualToValue, isMultiple));
+            } else if (clearedBySelection) {
+              store.set('activeIndex', null);
             } else if (autoHighlightMode === 'always') {
               store.set('activeIndex', 0);
             }
@@ -752,8 +863,8 @@ export function AriaCombobox(props) {
     if (!open && !inline) {
       return;
     }
-    const shouldUseFlatFilteredItems = hasItems || hasFilteredItemsProp;
-    const candidateItems = shouldUseFlatFilteredItems ? flatFilteredItems : valuesRef.current;
+    const shouldUseFlatFilteredValues = hasItems || hasFilteredItemsProp;
+    const candidateItems = shouldUseFlatFilteredValues ? flatFilteredValues : valuesRef.current;
     const storeActiveIndex = store.state.activeIndex;
     if (storeActiveIndex == null) {
       if (autoHighlightMode === 'always' && candidateItems.length > 0) {
@@ -774,7 +885,7 @@ export function AriaCombobox(props) {
     if (lastHighlightRef.current.index !== storeActiveIndex || !isSameItem) {
       emitHighlight(itemValue, storeActiveIndex, REASONS.none);
     }
-  }, [activeIndex, autoHighlightMode, emitHighlight, hasFilteredItemsProp, hasItems, flatFilteredItems, inline, open, store,
+  }, [activeIndex, autoHighlightMode, emitHighlight, hasFilteredItemsProp, hasItems, flatFilteredValues, inline, open, store,
   // Reruns the effect when the query changes without affecting the deps above, such as
   // clearing the input when no items are filtered out (individually rendered items).
   inputValue]);
@@ -789,56 +900,67 @@ export function AriaCombobox(props) {
   // Ensures that the active index is not set to 0 when the list is empty.
   // This avoids needing to press ArrowDown twice under certain conditions.
   React.useEffect(() => {
-    if (hasItems && autoHighlightMode && flatFilteredItems.length === 0) {
+    if (hasItems && autoHighlightMode && flatFilteredValues.length === 0) {
       setIndices({
         activeIndex: null
       });
     }
-  }, [hasItems, autoHighlightMode, flatFilteredItems.length, setIndices]);
-  function isSelectedValueDirty(value) {
-    const initialValue = validityData.initialValue;
-    if (Array.isArray(value) && Array.isArray(initialValue)) {
-      return !areArraysEqual(value, initialValue, (itemValue, initialItemValue) => compareItemEquality(itemValue, initialItemValue, isItemEqualToValue));
+  }, [hasItems, autoHighlightMode, flatFilteredValues.length, setIndices]);
+  function handleQueryChanged() {
+    if (open && query !== '' && query !== String(initialDefaultInputValue) && !inputMatchesSelectedValue) {
+      setQueryChangedAfterOpen(true);
     }
-    return value !== initialValue;
   }
-  useValueChanged(query, () => {
-    if (!open || query === '' || query === String(initialDefaultInputValue)) {
-      return;
+  function handleOpenChanged() {
+    // A controlled `open` prop can interrupt the close without calling `setOpen`.
+    if (open && closeQuery !== null) {
+      handleInterruptedReopen(false);
     }
-    setQueryChangedAfterOpen(true);
-  });
+  }
+
+  // These sync triggers can run in the same commit while still seeing the pre-commit `inputValue`.
+  // This render-scoped flag prevents duplicate callbacks and resets so canceled writes can retry.
+  let syncedSelectedLabel = false;
   function syncInputToSelectedLabel() {
-    const nextInputValue = stringifyAsLabel(selectedValue, itemToStringLabel);
-    if (inputValue !== nextInputValue) {
-      setInputValue(nextInputValue, createChangeEventDetails(REASONS.none));
+    if (!syncedSelectedLabel && inputValue !== selectedLabelString) {
+      syncedSelectedLabel = true;
+      setInputValue(selectedLabelString, createChangeEventDetails(REASONS.none));
     }
   }
-  useValueChanged(selectedValue, () => {
+  function handleSelectedValueChanged() {
     if (selectionMode === 'none') {
       return;
     }
     clearErrors(name);
-    setDirty(isSelectedValueDirty(selectedValue));
+    setDirty(isSelectedValueDirty(selectedValue, validityData.initialValue, isItemEqualToValue));
     validation.change(selectedValue);
     if (single && !hasInputValue && !inputInsidePopup) {
       syncInputToSelectedLabel();
     }
-  });
-  useValueChanged(inputValue, () => {
+  }
+
+  // The label catches accessor changes while the items identity restores the selected label after
+  // a one-step input clear followed by a data reload. The shared sync prevents duplicate writes
+  // when both change in the same commit.
+  function syncInputAfterItemsOrLabelChange() {
+    if (single && !hasInputValue && !inputInsidePopup && !queryChangedAfterOpen) {
+      syncInputToSelectedLabel();
+    }
+  }
+  function handleInputValueChanged() {
     if (selectionMode !== 'none') {
       return;
     }
     clearErrors(name);
     setDirty(inputValue !== validityData.initialValue);
     validation.change(inputValue);
-  });
-  useValueChanged(items, () => {
-    if (!single || hasInputValue || inputInsidePopup || queryChangedAfterOpen) {
-      return;
-    }
-    syncInputToSelectedLabel();
-  });
+  }
+  useValueChanged(query, handleQueryChanged);
+  useValueChanged(open, handleOpenChanged);
+  useValueChanged(selectedValue, handleSelectedValueChanged);
+  useValueChanged(selectedLabelString, syncInputAfterItemsOrLabelChange);
+  useValueChanged(items, syncInputAfterItemsOrLabelChange);
+  useValueChanged(inputValue, handleInputValueChanged);
   const floatingRootContext = useFloatingRootContext({
     open: inline ? true : open,
     onOpenChange: setOpen,
@@ -871,7 +993,8 @@ export function AriaCombobox(props) {
       reference['aria-expanded'] = ariaExpanded;
       reference['aria-haspopup'] = ariaHasPopup;
       reference['aria-controls'] = expanded ? listElement?.id : undefined;
-      reference['aria-autocomplete'] = autoComplete;
+      // `readOnly` accepts no input, so no completion of any kind is offered.
+      reference['aria-autocomplete'] = readOnly ? 'none' : autoComplete;
     }
     return {
       reference,
@@ -879,9 +1002,13 @@ export function AriaCombobox(props) {
         role: 'presentation'
       }
     };
-  }, [inputElement, expanded, ariaExpanded, ariaHasPopup, listElement?.id, autoComplete]);
+  }, [inputElement, expanded, ariaExpanded, ariaHasPopup, listElement?.id, autoComplete, readOnly]);
+
+  // `readOnly` locks the value, not the interaction: the popup opens and can be browsed.
+  // Value changes stay blocked in `ComboboxItem`, `ComboboxInput`'s keydown, `ComboboxTrigger`'s
+  // typeahead, the clear/remove parts, and the hidden input's autofill handler.
   const click = useClick(floatingRootContext, {
-    enabled: !readOnly && !disabled && openOnInputClick,
+    enabled: !disabled && openOnInputClick,
     event: 'mousedown-only',
     toggle: false,
     // Apply a small delay for touch to let mobile viewport/keyboard positioning settle.
@@ -890,7 +1017,7 @@ export function AriaCombobox(props) {
     reason: REASONS.inputPress
   });
   const dismiss = useDismiss(floatingRootContext, {
-    enabled: !readOnly && !disabled && !inline,
+    enabled: !disabled && !inline,
     outsidePressEvent: {
       mouse: 'sloppy',
       // The visual viewport (affected by the mobile software keyboard) can be
@@ -906,7 +1033,7 @@ export function AriaCombobox(props) {
     }
   });
   const listNavigation = useListNavigation(floatingRootContext, {
-    enabled: !readOnly && !disabled,
+    enabled: !disabled,
     id,
     listRef,
     activeIndex,
@@ -963,6 +1090,17 @@ export function AriaCombobox(props) {
       onFocus: undefined
     };
   }, [listNavigation.item]);
+  store.useContextCallback('setOpen', setOpen);
+  store.useContextCallback('setInputValue', setInputValue);
+  store.useContextCallback('setSelectedValue', setSelectedValue);
+  store.useContextCallback('setIndices', setIndices);
+  store.useContextCallback('handleSelection', handleSelection);
+  store.useContextCallback('forceMount', forceMount);
+  store.useContextCallback('requestSubmit', requestSubmit);
+  store.useContextCallback('onOpenChangeComplete', onOpenChangeCompleteProp);
+
+  // The prop bags must be in the store before the parts render: they read them with `useStore`
+  // during render, and a layout effect commits only after all children have rendered.
   useOnFirstRender(() => {
     store.update({
       inline: inlineProp,
@@ -970,57 +1108,58 @@ export function AriaCombobox(props) {
       listProps,
       inputProps,
       triggerProps,
-      itemProps,
-      setOpen,
-      setInputValue,
-      setSelectedValue,
-      setIndices,
-      handleSelection,
-      forceMount,
-      requestSubmit,
-      onOpenChangeComplete
+      itemProps
     });
   });
+  const syncedValues = {
+    id,
+    selectedValue,
+    open,
+    mounted,
+    transitionStatus,
+    items: storeItems,
+    inline: inlineProp,
+    popupProps,
+    listProps,
+    inputProps,
+    triggerProps,
+    itemProps,
+    openMethod,
+    selectionMode,
+    name,
+    form,
+    disabled,
+    readOnly,
+    required,
+    grid,
+    virtualized,
+    openOnInputClick,
+    itemToStringLabel,
+    modal,
+    autoHighlight: autoHighlightMode,
+    isItemEqualToValue,
+    submitOnItemClick,
+    hasInputValue
+  };
   useIsoLayoutEffect(() => {
+    // `inputOwnsFormValue` is derived here rather than during render because `ComboboxInput`
+    // writes it from a ref callback earlier in the same commit, and it has to land in this same
+    // `update` so subscribers never observe an intermediate snapshot. That is also why
+    // `store.useSyncedValues` can't be used yet: it would need a second write. The dependencies
+    // are derived from `syncedValues` so a newly synchronized field can't be forgotten here.
     store.update({
-      id,
-      selectedValue,
-      open,
-      mounted,
-      transitionStatus,
-      items,
-      inline: inlineProp,
-      popupProps,
-      listProps,
-      inputProps,
-      triggerProps,
-      openMethod,
-      itemProps,
-      selectionMode,
-      name,
-      form,
-      disabled,
-      readOnly,
-      required,
-      grid,
-      virtualized,
-      openOnInputClick,
-      itemToStringLabel,
-      modal,
-      autoHighlight: autoHighlightMode,
-      isItemEqualToValue,
-      submitOnItemClick,
-      hasInputValue,
+      ...syncedValues,
       inputOwnsFormValue: selectionMode === 'none' && (inlineProp || !store.state.inputInsidePopup)
     });
-  }, [store, id, selectedValue, open, mounted, transitionStatus, items, popupProps, listProps, inputProps, itemProps, openMethod, triggerProps, selectionMode, name, disabled, readOnly, required, grid, virtualized, openOnInputClick, itemToStringLabel, modal, isItemEqualToValue, submitOnItemClick, hasInputValue, inlineProp, autoHighlightMode, form]);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [store, ...Object.values(syncedValues)]);
   const hiddenInputRef = useMergedRefs(inputRefProp, validation.inputRef);
   const itemsContextValue = React.useMemo(() => ({
     query,
     hasItems,
     filteredItems,
-    flatFilteredItems
-  }), [query, hasItems, filteredItems, flatFilteredItems]);
+    flatFilteredValues
+  }), [query, hasItems, filteredItems, flatFilteredValues]);
   const serializedValue = React.useMemo(() => {
     if (Array.isArray(fieldRawValue)) {
       return '';
@@ -1064,7 +1203,7 @@ export function AriaCombobox(props) {
           const nextValue = event.currentTarget.value;
           const nextValueLower = nextValue.toLowerCase();
           const details = createChangeEventDetails(REASONS.none, event.nativeEvent);
-          const findSerializedMatchIndex = () => valuesRef.current.findIndex(candidate => stringifyAsValue(candidate, itemToStringValue).toLowerCase() === nextValueLower || stringifyAsLabel(candidate, itemToStringLabel).toLowerCase() === nextValueLower);
+          const findSerializedMatchIndex = () => valuesRef.current.findIndex(candidate => stringifyAsValue(candidate, itemToStringValue).toLowerCase() === nextValueLower || stringifyValueLabel(candidate).toLowerCase() === nextValueLower);
           function handleChange() {
             // Browser autofill only writes a single scalar value.
             if (multiple) {