@base-ui/react 1.7.0 → 1.8.0

package/combobox/root/ComboboxRoot.d.mts

@@ -6,10 +6,10 @@ import { AriaCombobox, type AriaComboboxState } from "./AriaCombobox.mjs";
  *
  * Documentation: [Base UI Combobox](https://base-ui.com/react/components/combobox)
  */
-export declare function ComboboxRoot<Value, Multiple extends boolean | undefined = false>(props: ComboboxRoot.Props<Value, Multiple>): React.JSX.Element;
+export declare function ComboboxRoot<Value, Multiple extends boolean | undefined = false, Item = Value>(props: ComboboxRoot.Props<Value, Multiple, Item>): React.JSX.Element;
 type ModeFromMultiple<Multiple extends boolean | undefined> = Multiple extends true ? 'multiple' : 'single';
 type ComboboxValueType<Value, Multiple extends boolean | undefined> = Multiple extends true ? Value[] : Value;
-export type ComboboxRootProps<Value, Multiple extends boolean | undefined = false> = Omit<AriaCombobox.Props<Value, ModeFromMultiple<Multiple>>, 'fillInputOnItemPress' | 'autoComplete' | 'formAutoComplete' | 'submitOnItemClick' | 'autoHighlight' | 'keepHighlight' | 'highlightItemOnHover' | 'itemToStringLabel' | 'itemToStringValue' | 'isItemEqualToValue' | 'selectionMode' | 'defaultSelectedValue' | 'selectedValue' | 'onSelectedValueChange' | 'actionsRef' | 'onOpenChange' | 'onInputValueChange' | 'onItemHighlighted'> & {
+export type ComboboxRootProps<Value, Multiple extends boolean | undefined = false, Item = Value> = Omit<AriaCombobox.Props<Value, ModeFromMultiple<Multiple>, Item>, 'fillInputOnItemPress' | 'autoComplete' | 'formAutoComplete' | 'submitOnItemClick' | 'autoHighlight' | 'keepHighlight' | 'highlightItemOnHover' | 'itemToStringLabel' | 'itemToStringValue' | 'isItemEqualToValue' | 'selectionMode' | 'defaultSelectedValue' | 'selectedValue' | 'onSelectedValueChange' | 'actionsRef' | 'onOpenChange' | 'onInputValueChange' | 'onItemHighlighted'> & {
   /**
    * Whether multiple items can be selected.
    * @default false
@@ -34,15 +34,19 @@ export type ComboboxRootProps<Value, Multiple extends boolean | undefined = fals
   /**
    * When the item values are objects (`<Combobox.Item value={object}>`), this function converts the object value to a string representation for display in the input.
    * If the shape of the object is `{ value, label }`, the label will be used automatically without needing to specify this prop.
+   * With a `createItems()` collection, this receives the derived value, and the collection's
+   * `getLabel` takes precedence for values it can resolve.
    */
   itemToStringLabel?: ((itemValue: Value) => string) | undefined;
   /**
    * When the item values are objects (`<Combobox.Item value={object}>`), this function converts the object value to a string representation for form submission.
    * If the shape of the object is `{ value, label }`, the value will be used automatically without needing to specify this prop.
+   * With a `createItems()` collection, this receives the derived value.
    */
   itemToStringValue?: ((itemValue: Value) => string) | undefined;
   /**
    * Custom comparison logic used to determine if a combobox item value matches the current selected value. Useful when item values are objects without matching referentially.
+   * With a `createItems()` collection, both arguments are derived values.
    * Defaults to `Object.is` comparison.
    */
   isItemEqualToValue?: ((itemValue: Value, value: Value) => boolean) | undefined;
@@ -91,7 +95,7 @@ export type ComboboxRootChangeEventDetails = AriaCombobox.ChangeEventDetails;
 export type ComboboxRootHighlightEventReason = AriaCombobox.HighlightEventReason;
 export type ComboboxRootHighlightEventDetails = AriaCombobox.HighlightEventDetails;
 export declare namespace ComboboxRoot {
-  type Props<Value, Multiple extends boolean | undefined = false> = ComboboxRootProps<Value, Multiple>;
+  type Props<Value, Multiple extends boolean | undefined = false, Item = Value> = ComboboxRootProps<Value, Multiple, Item>;
   type State = ComboboxRootState;
   type Actions = ComboboxRootActions;
   type ChangeEventReason = ComboboxRootChangeEventReason;

package/combobox/root/ComboboxRoot.d.ts

@@ -6,10 +6,10 @@ import { AriaCombobox, type AriaComboboxState } from "./AriaCombobox.js";
  *
  * Documentation: [Base UI Combobox](https://base-ui.com/react/components/combobox)
  */
-export declare function ComboboxRoot<Value, Multiple extends boolean | undefined = false>(props: ComboboxRoot.Props<Value, Multiple>): React.JSX.Element;
+export declare function ComboboxRoot<Value, Multiple extends boolean | undefined = false, Item = Value>(props: ComboboxRoot.Props<Value, Multiple, Item>): React.JSX.Element;
 type ModeFromMultiple<Multiple extends boolean | undefined> = Multiple extends true ? 'multiple' : 'single';
 type ComboboxValueType<Value, Multiple extends boolean | undefined> = Multiple extends true ? Value[] : Value;
-export type ComboboxRootProps<Value, Multiple extends boolean | undefined = false> = Omit<AriaCombobox.Props<Value, ModeFromMultiple<Multiple>>, 'fillInputOnItemPress' | 'autoComplete' | 'formAutoComplete' | 'submitOnItemClick' | 'autoHighlight' | 'keepHighlight' | 'highlightItemOnHover' | 'itemToStringLabel' | 'itemToStringValue' | 'isItemEqualToValue' | 'selectionMode' | 'defaultSelectedValue' | 'selectedValue' | 'onSelectedValueChange' | 'actionsRef' | 'onOpenChange' | 'onInputValueChange' | 'onItemHighlighted'> & {
+export type ComboboxRootProps<Value, Multiple extends boolean | undefined = false, Item = Value> = Omit<AriaCombobox.Props<Value, ModeFromMultiple<Multiple>, Item>, 'fillInputOnItemPress' | 'autoComplete' | 'formAutoComplete' | 'submitOnItemClick' | 'autoHighlight' | 'keepHighlight' | 'highlightItemOnHover' | 'itemToStringLabel' | 'itemToStringValue' | 'isItemEqualToValue' | 'selectionMode' | 'defaultSelectedValue' | 'selectedValue' | 'onSelectedValueChange' | 'actionsRef' | 'onOpenChange' | 'onInputValueChange' | 'onItemHighlighted'> & {
   /**
    * Whether multiple items can be selected.
    * @default false
@@ -34,15 +34,19 @@ export type ComboboxRootProps<Value, Multiple extends boolean | undefined = fals
   /**
    * When the item values are objects (`<Combobox.Item value={object}>`), this function converts the object value to a string representation for display in the input.
    * If the shape of the object is `{ value, label }`, the label will be used automatically without needing to specify this prop.
+   * With a `createItems()` collection, this receives the derived value, and the collection's
+   * `getLabel` takes precedence for values it can resolve.
    */
   itemToStringLabel?: ((itemValue: Value) => string) | undefined;
   /**
    * When the item values are objects (`<Combobox.Item value={object}>`), this function converts the object value to a string representation for form submission.
    * If the shape of the object is `{ value, label }`, the value will be used automatically without needing to specify this prop.
+   * With a `createItems()` collection, this receives the derived value.
    */
   itemToStringValue?: ((itemValue: Value) => string) | undefined;
   /**
    * Custom comparison logic used to determine if a combobox item value matches the current selected value. Useful when item values are objects without matching referentially.
+   * With a `createItems()` collection, both arguments are derived values.
    * Defaults to `Object.is` comparison.
    */
   isItemEqualToValue?: ((itemValue: Value, value: Value) => boolean) | undefined;
@@ -91,7 +95,7 @@ export type ComboboxRootChangeEventDetails = AriaCombobox.ChangeEventDetails;
 export type ComboboxRootHighlightEventReason = AriaCombobox.HighlightEventReason;
 export type ComboboxRootHighlightEventDetails = AriaCombobox.HighlightEventDetails;
 export declare namespace ComboboxRoot {
-  type Props<Value, Multiple extends boolean | undefined = false> = ComboboxRootProps<Value, Multiple>;
+  type Props<Value, Multiple extends boolean | undefined = false, Item = Value> = ComboboxRootProps<Value, Multiple, Item>;
   type State = ComboboxRootState;
   type Actions = ComboboxRootActions;
   type ChangeEventReason = ComboboxRootChangeEventReason;

package/combobox/root/ComboboxRootContext.d.mts

@@ -4,7 +4,11 @@ export interface ComboboxDerivedItemsContext {
   query: string;
   hasItems: boolean;
   filteredItems: any[];
-  flatFilteredItems: any[];
+  /**
+   * `filteredItems` flattened across groups and projected to selection values. Identical to the
+   * items themselves unless `items` is a `createItems()` collection.
+   */
+  flatFilteredValues: any[];
 }
 export declare const ComboboxRootContext: React.Context<ComboboxStore | undefined>;
 export declare const ComboboxFloatingContext: React.Context<import("../../floating-ui-react/components/FloatingRootStore.mjs").FloatingRootStore | undefined>;

package/combobox/root/ComboboxRootContext.d.ts

@@ -4,7 +4,11 @@ export interface ComboboxDerivedItemsContext {
   query: string;
   hasItems: boolean;
   filteredItems: any[];
-  flatFilteredItems: any[];
+  /**
+   * `filteredItems` flattened across groups and projected to selection values. Identical to the
+   * items themselves unless `items` is a `createItems()` collection.
+   */
+  flatFilteredValues: any[];
 }
 export declare const ComboboxRootContext: React.Context<ComboboxStore | undefined>;
 export declare const ComboboxFloatingContext: React.Context<import("../../floating-ui-react/components/FloatingRootStore.js").FloatingRootStore | undefined>;

package/combobox/root/utils/index.d.mts

@@ -1,4 +1,7 @@
 import type { Filter } from "./useFilter.mjs";
+export type FilterItemToString = ((item: any) => string) & {
+  selected?: ((value: any) => string) | undefined;
+};
 /**
  * Derives the default id assigned to `Combobox.Popup` when the input is rendered inside it.
  * Shared by the popup (which applies it) and the trigger (which references it via `aria-controls`)
@@ -11,9 +14,9 @@ export declare function getComboboxPopupId(rootId: string | null | undefined): s
  * • When `item` is an object with a `value` property, that property is used.
  * • When `item` is a primitive (e.g. `string`), it is used directly.
  */
-export declare function createCollatorItemFilter(collatorFilter: Filter, itemToStringLabel?: (item: any) => string): (item: any, query: string) => boolean;
+export declare function createCollatorItemFilter(collatorFilter: Filter, itemToStringLabel?: FilterItemToString): (item: any, query: string) => boolean;
 /**
  * Enhanced filter for single selection mode using Intl.Collator that shows all items
  * when query is empty or matches the current selection, making it easier to browse options.
  */
-export declare function createSingleSelectionCollatorFilter(collatorFilter: Filter, itemToStringLabel?: (item: any) => string, selectedValue?: any): (item: any, query: string) => boolean;
+export declare function createSingleSelectionCollatorFilter(collatorFilter: Filter, itemToStringLabel?: FilterItemToString, selectedValue?: any): (item: any, query: string) => boolean;

package/combobox/root/utils/index.d.ts

@@ -1,4 +1,7 @@
 import type { Filter } from "./useFilter.js";
+export type FilterItemToString = ((item: any) => string) & {
+  selected?: ((value: any) => string) | undefined;
+};
 /**
  * Derives the default id assigned to `Combobox.Popup` when the input is rendered inside it.
  * Shared by the popup (which applies it) and the trigger (which references it via `aria-controls`)
@@ -11,9 +14,9 @@ export declare function getComboboxPopupId(rootId: string | null | undefined): s
  * • When `item` is an object with a `value` property, that property is used.
  * • When `item` is a primitive (e.g. `string`), it is used directly.
  */
-export declare function createCollatorItemFilter(collatorFilter: Filter, itemToStringLabel?: (item: any) => string): (item: any, query: string) => boolean;
+export declare function createCollatorItemFilter(collatorFilter: Filter, itemToStringLabel?: FilterItemToString): (item: any, query: string) => boolean;
 /**
  * Enhanced filter for single selection mode using Intl.Collator that shows all items
  * when query is empty or matches the current selection, making it easier to browse options.
  */
-export declare function createSingleSelectionCollatorFilter(collatorFilter: Filter, itemToStringLabel?: (item: any) => string, selectedValue?: any): (item: any, query: string) => boolean;
+export declare function createSingleSelectionCollatorFilter(collatorFilter: Filter, itemToStringLabel?: FilterItemToString, selectedValue?: any): (item: any, query: string) => boolean;

package/combobox/root/utils/index.js

@@ -43,7 +43,8 @@ function createSingleSelectionCollatorFilter(collatorFilter, itemToStringLabel,
     if (!query) {
       return true;
     }
-    const selectedString = selectedValue != null ? (0, _resolveValueLabel.stringifyAsLabel)(selectedValue, itemToStringLabel) : '';
+    const selectedValueToString = itemToStringLabel?.selected ?? itemToStringLabel;
+    const selectedString = selectedValue != null ? (0, _resolveValueLabel.stringifyAsLabel)(selectedValue, selectedValueToString) : '';
 
     // Handle case-insensitive matching consistently
     if (selectedString && collatorFilter.contains(selectedString, query) && selectedString.length === query.length) {

package/combobox/root/utils/index.mjs

@@ -35,7 +35,8 @@ export function createSingleSelectionCollatorFilter(collatorFilter, itemToString
     if (!query) {
       return true;
     }
-    const selectedString = selectedValue != null ? stringifyAsLabel(selectedValue, itemToStringLabel) : '';
+    const selectedValueToString = itemToStringLabel?.selected ?? itemToStringLabel;
+    const selectedString = selectedValue != null ? stringifyAsLabel(selectedValue, selectedValueToString) : '';
 
     // Handle case-insensitive matching consistently
     if (selectedString && collatorFilter.contains(selectedString, query) && selectedString.length === query.length) {

package/combobox/root/utils/useFilter.d.mts

@@ -11,7 +11,8 @@ export interface UseComboboxFilterOptions extends UseFilterOptions {
    */
   multiple?: boolean | undefined;
   /**
-   * The current value of the combobox.
+   * The current value of the combobox, used to keep every item visible while the query still
+   * matches the selection.
    */
   value?: any;
 }

package/combobox/root/utils/useFilter.d.ts

@@ -11,7 +11,8 @@ export interface UseComboboxFilterOptions extends UseFilterOptions {
    */
   multiple?: boolean | undefined;
   /**
-   * The current value of the combobox.
+   * The current value of the combobox, used to keep every item visible while the query still
+   * matches the selection.
    */
   value?: any;
 }

package/combobox/root/utils/useFilteredItems.d.mts

@@ -1,4 +1,5 @@
 /**
  * Returns the internally filtered items.
+ * Treat the result as read-only: it is internal state and may be a shared frozen array.
  */
 export declare function useFilteredItems<T>(): T[];

package/combobox/root/utils/useFilteredItems.d.ts

@@ -1,4 +1,5 @@
 /**
  * Returns the internally filtered items.
+ * Treat the result as read-only: it is internal state and may be a shared frozen array.
  */
 export declare function useFilteredItems<T>(): T[];

package/combobox/root/utils/useFilteredItems.js

@@ -7,6 +7,7 @@ exports.useFilteredItems = useFilteredItems;
 var _ComboboxRootContext = require("../ComboboxRootContext");
 /**
  * Returns the internally filtered items.
+ * Treat the result as read-only: it is internal state and may be a shared frozen array.
  */
 function useFilteredItems() {
   const items = (0, _ComboboxRootContext.useComboboxDerivedItemsContext)();

package/combobox/root/utils/useFilteredItems.mjs

@@ -2,6 +2,7 @@ import { useComboboxDerivedItemsContext } from "../ComboboxRootContext.mjs";
 
 /**
  * Returns the internally filtered items.
+ * Treat the result as read-only: it is internal state and may be a shared frozen array.
  */
 export function useFilteredItems() {
   const items = useComboboxDerivedItemsContext();

package/combobox/store.d.mts

@@ -1,4 +1,4 @@
-import { Store } from '@base-ui/utils/store';
+import { ReactStore } from '@base-ui/utils/store';
 import type { InteractionType } from '@base-ui/utils/useEnhancedClickHandler';
 import type { TransitionStatus } from "../internals/useTransitionStatus.mjs";
 import type { HTMLProps } from "../internals/types.mjs";
@@ -32,30 +32,6 @@ export type State = {
   inputInsidePopup: boolean;
   inputOwnsFormValue: boolean;
   selectionMode: 'single' | 'multiple' | 'none';
-  listRef: React.RefObject<Array<HTMLElement | null>>;
-  labelsRef: React.RefObject<Array<string | null>>;
-  popupRef: React.RefObject<HTMLDivElement | null>;
-  emptyRef: React.RefObject<HTMLDivElement | null>;
-  inputRef: React.RefObject<HTMLInputElement | null>;
-  startDismissRef: React.RefObject<HTMLSpanElement | null>;
-  endDismissRef: React.RefObject<HTMLSpanElement | null>;
-  keyboardActiveRef: React.RefObject<boolean>;
-  chipsContainerRef: React.RefObject<HTMLDivElement | null>;
-  clearRef: React.RefObject<HTMLButtonElement | null>;
-  valuesRef: React.RefObject<Array<any>>;
-  pointerDownItemRef: React.RefObject<Element | null>;
-  selectionEventRef: React.RefObject<MouseEvent | PointerEvent | KeyboardEvent | null>;
-  setOpen: (open: boolean, eventDetails: AriaCombobox.ChangeEventDetails) => void;
-  setInputValue: (value: string, eventDetails: AriaCombobox.ChangeEventDetails) => void;
-  setSelectedValue: (value: any, eventDetails: AriaCombobox.ChangeEventDetails) => void;
-  setIndices: (indices: {
-    activeIndex?: number | null | undefined;
-    selectedIndex?: number | null | undefined;
-    type?: AriaCombobox.HighlightEventReason | undefined;
-  }) => void;
-  forceMount: () => void;
-  handleSelection: (event: MouseEvent | PointerEvent | KeyboardEvent, itemValue: any) => void;
-  requestSubmit: () => void;
   name: string | undefined;
   form: string | undefined;
   disabled: boolean;
@@ -63,7 +39,6 @@ export type State = {
   required: boolean;
   grid: boolean;
   virtualized: boolean;
-  onOpenChangeComplete: (open: boolean) => void;
   openOnInputClick: boolean;
   itemToStringLabel?: ((item: any) => string) | undefined;
   isItemEqualToValue: (itemValue: any, selectedValue: any) => boolean;
@@ -72,7 +47,58 @@ export type State = {
   submitOnItemClick: boolean;
   hasInputValue: boolean;
 };
-export type ComboboxStore = Store<State>;
+/**
+ * Non-reactive values shared with the combobox parts. Nothing here is observable through
+ * `selectors`, so writing to a ref never notifies subscribers.
+ */
+export type ComboboxStoreContext = {
+  /** Item elements in list order, owned by `Combobox.List`. */
+  readonly listRef: React.RefObject<Array<HTMLElement | null>>;
+  /** Item text labels in list order, used for typeahead. */
+  readonly labelsRef: React.RefObject<Array<string | null>>;
+  /** The popup element. */
+  readonly popupRef: React.RefObject<HTMLDivElement | null>;
+  /** The empty-state element. */
+  readonly emptyRef: React.RefObject<HTMLDivElement | null>;
+  /** The input element that owns the combobox role. */
+  readonly inputRef: React.RefObject<HTMLInputElement | null>;
+  /** Internal dismiss button rendered before the popup content. */
+  readonly startDismissRef: React.RefObject<HTMLSpanElement | null>;
+  /** Internal dismiss button rendered after the popup content. */
+  readonly endDismissRef: React.RefObject<HTMLSpanElement | null>;
+  /** Whether the last interaction came from the keyboard. */
+  readonly keyboardActiveRef: React.RefObject<boolean>;
+  /** Container holding the selection chips. */
+  readonly chipsContainerRef: React.RefObject<HTMLDivElement | null>;
+  /** The clear button. */
+  readonly clearRef: React.RefObject<HTMLButtonElement | null>;
+  /** Item values in list order. */
+  readonly valuesRef: React.RefObject<Array<any>>;
+  /** Item element that received the last pointerdown, to pair it with a mouseup. */
+  readonly pointerDownItemRef: React.RefObject<Element | null>;
+  /** Native event that triggered the in-flight selection. */
+  readonly selectionEventRef: React.RefObject<MouseEvent | PointerEvent | KeyboardEvent | null>;
+  /** Opens or closes the popup. */
+  setOpen: (open: boolean, eventDetails: AriaCombobox.ChangeEventDetails) => void;
+  /** Sets the input value. */
+  setInputValue: (value: string, eventDetails: AriaCombobox.ChangeEventDetails) => void;
+  /** Sets the selected value. */
+  setSelectedValue: (value: any, eventDetails: AriaCombobox.ChangeEventDetails) => void;
+  /** Sets the active and/or selected index. */
+  setIndices: (indices: {
+    activeIndex?: number | null | undefined;
+    selectedIndex?: number | null | undefined;
+    type?: AriaCombobox.HighlightEventReason | undefined;
+  }) => void;
+  /** Mounts the popup subtree without opening it, to resolve derived item labels. */
+  forceMount: () => void;
+  /** Applies a selection originating from an item. */
+  handleSelection: (event: MouseEvent | PointerEvent | KeyboardEvent, itemValue: any) => void;
+  /** Requests submission of the owning form. */
+  requestSubmit: () => void;
+  /** Called when the open state change animation completes. */
+  onOpenChangeComplete: (open: boolean) => void;
+};
 export declare const selectors: {
   id: (state: State) => string | undefined;
   labelId: (state: State) => string | undefined;
@@ -117,4 +143,5 @@ export declare const selectors: {
   isItemEqualToValue: (state: State) => (itemValue: any, selectedValue: any) => boolean;
   modal: (state: State) => boolean;
   autoHighlight: (state: State) => "always" | "input-change" | false;
-};
+};
+export type ComboboxStore = ReactStore<State, ComboboxStoreContext, typeof selectors>;

package/combobox/store.d.ts

@@ -1,4 +1,4 @@
-import { Store } from '@base-ui/utils/store';
+import { ReactStore } from '@base-ui/utils/store';
 import type { InteractionType } from '@base-ui/utils/useEnhancedClickHandler';
 import type { TransitionStatus } from "../internals/useTransitionStatus.js";
 import type { HTMLProps } from "../internals/types.js";
@@ -32,30 +32,6 @@ export type State = {
   inputInsidePopup: boolean;
   inputOwnsFormValue: boolean;
   selectionMode: 'single' | 'multiple' | 'none';
-  listRef: React.RefObject<Array<HTMLElement | null>>;
-  labelsRef: React.RefObject<Array<string | null>>;
-  popupRef: React.RefObject<HTMLDivElement | null>;
-  emptyRef: React.RefObject<HTMLDivElement | null>;
-  inputRef: React.RefObject<HTMLInputElement | null>;
-  startDismissRef: React.RefObject<HTMLSpanElement | null>;
-  endDismissRef: React.RefObject<HTMLSpanElement | null>;
-  keyboardActiveRef: React.RefObject<boolean>;
-  chipsContainerRef: React.RefObject<HTMLDivElement | null>;
-  clearRef: React.RefObject<HTMLButtonElement | null>;
-  valuesRef: React.RefObject<Array<any>>;
-  pointerDownItemRef: React.RefObject<Element | null>;
-  selectionEventRef: React.RefObject<MouseEvent | PointerEvent | KeyboardEvent | null>;
-  setOpen: (open: boolean, eventDetails: AriaCombobox.ChangeEventDetails) => void;
-  setInputValue: (value: string, eventDetails: AriaCombobox.ChangeEventDetails) => void;
-  setSelectedValue: (value: any, eventDetails: AriaCombobox.ChangeEventDetails) => void;
-  setIndices: (indices: {
-    activeIndex?: number | null | undefined;
-    selectedIndex?: number | null | undefined;
-    type?: AriaCombobox.HighlightEventReason | undefined;
-  }) => void;
-  forceMount: () => void;
-  handleSelection: (event: MouseEvent | PointerEvent | KeyboardEvent, itemValue: any) => void;
-  requestSubmit: () => void;
   name: string | undefined;
   form: string | undefined;
   disabled: boolean;
@@ -63,7 +39,6 @@ export type State = {
   required: boolean;
   grid: boolean;
   virtualized: boolean;
-  onOpenChangeComplete: (open: boolean) => void;
   openOnInputClick: boolean;
   itemToStringLabel?: ((item: any) => string) | undefined;
   isItemEqualToValue: (itemValue: any, selectedValue: any) => boolean;
@@ -72,7 +47,58 @@ export type State = {
   submitOnItemClick: boolean;
   hasInputValue: boolean;
 };
-export type ComboboxStore = Store<State>;
+/**
+ * Non-reactive values shared with the combobox parts. Nothing here is observable through
+ * `selectors`, so writing to a ref never notifies subscribers.
+ */
+export type ComboboxStoreContext = {
+  /** Item elements in list order, owned by `Combobox.List`. */
+  readonly listRef: React.RefObject<Array<HTMLElement | null>>;
+  /** Item text labels in list order, used for typeahead. */
+  readonly labelsRef: React.RefObject<Array<string | null>>;
+  /** The popup element. */
+  readonly popupRef: React.RefObject<HTMLDivElement | null>;
+  /** The empty-state element. */
+  readonly emptyRef: React.RefObject<HTMLDivElement | null>;
+  /** The input element that owns the combobox role. */
+  readonly inputRef: React.RefObject<HTMLInputElement | null>;
+  /** Internal dismiss button rendered before the popup content. */
+  readonly startDismissRef: React.RefObject<HTMLSpanElement | null>;
+  /** Internal dismiss button rendered after the popup content. */
+  readonly endDismissRef: React.RefObject<HTMLSpanElement | null>;
+  /** Whether the last interaction came from the keyboard. */
+  readonly keyboardActiveRef: React.RefObject<boolean>;
+  /** Container holding the selection chips. */
+  readonly chipsContainerRef: React.RefObject<HTMLDivElement | null>;
+  /** The clear button. */
+  readonly clearRef: React.RefObject<HTMLButtonElement | null>;
+  /** Item values in list order. */
+  readonly valuesRef: React.RefObject<Array<any>>;
+  /** Item element that received the last pointerdown, to pair it with a mouseup. */
+  readonly pointerDownItemRef: React.RefObject<Element | null>;
+  /** Native event that triggered the in-flight selection. */
+  readonly selectionEventRef: React.RefObject<MouseEvent | PointerEvent | KeyboardEvent | null>;
+  /** Opens or closes the popup. */
+  setOpen: (open: boolean, eventDetails: AriaCombobox.ChangeEventDetails) => void;
+  /** Sets the input value. */
+  setInputValue: (value: string, eventDetails: AriaCombobox.ChangeEventDetails) => void;
+  /** Sets the selected value. */
+  setSelectedValue: (value: any, eventDetails: AriaCombobox.ChangeEventDetails) => void;
+  /** Sets the active and/or selected index. */
+  setIndices: (indices: {
+    activeIndex?: number | null | undefined;
+    selectedIndex?: number | null | undefined;
+    type?: AriaCombobox.HighlightEventReason | undefined;
+  }) => void;
+  /** Mounts the popup subtree without opening it, to resolve derived item labels. */
+  forceMount: () => void;
+  /** Applies a selection originating from an item. */
+  handleSelection: (event: MouseEvent | PointerEvent | KeyboardEvent, itemValue: any) => void;
+  /** Requests submission of the owning form. */
+  requestSubmit: () => void;
+  /** Called when the open state change animation completes. */
+  onOpenChangeComplete: (open: boolean) => void;
+};
 export declare const selectors: {
   id: (state: State) => string | undefined;
   labelId: (state: State) => string | undefined;
@@ -117,4 +143,5 @@ export declare const selectors: {
   isItemEqualToValue: (state: State) => (itemValue: any, selectedValue: any) => boolean;
   modal: (state: State) => boolean;
   autoHighlight: (state: State) => "always" | "input-change" | false;
-};
+};
+export type ComboboxStore = ReactStore<State, ComboboxStoreContext, typeof selectors>;

package/combobox/store.js

@@ -6,6 +6,11 @@ Object.defineProperty(exports, "__esModule", {
 exports.selectors = void 0;
 var _itemEquality = require("../internals/itemEquality");
 var _resolveValueLabel = require("../internals/resolveValueLabel");
+/**
+ * Non-reactive values shared with the combobox parts. Nothing here is observable through
+ * `selectors`, so writing to a ref never notifies subscribers.
+ */
+
 const selectors = exports.selectors = {
   id: state => state.id,
   labelId: state => state.labelId,

package/combobox/store.mjs

@@ -1,5 +1,11 @@
 import { compareItemEquality } from "../internals/itemEquality.mjs";
 import { hasNullItemLabel } from "../internals/resolveValueLabel.mjs";
+
+/**
+ * Non-reactive values shared with the combobox parts. Nothing here is observable through
+ * `selectors`, so writing to a ref never notifies subscribers.
+ */
+
 export const selectors = {
   id: state => state.id,
   labelId: state => state.labelId,

package/combobox/trigger/ComboboxTrigger.d.mts

@@ -18,6 +18,10 @@ export interface ComboboxTriggerState extends FieldRootState {
    * Whether the component should ignore user interaction.
    */
   disabled: boolean;
+  /**
+   * Whether the component should ignore user edits.
+   */
+  readOnly: boolean;
   /**
    * Indicates which side the corresponding popup is positioned relative to its anchor.
    */

package/combobox/trigger/ComboboxTrigger.d.ts

@@ -18,6 +18,10 @@ export interface ComboboxTriggerState extends FieldRootState {
    * Whether the component should ignore user interaction.
    */
   disabled: boolean;
+  /**
+   * Whether the component should ignore user edits.
+   */
+  readOnly: boolean;
   /**
    * Indicates which side the corresponding popup is positioned relative to its anchor.
    */