@base-ui/react 1.3.0 → 1.4.1

package/esm/combobox/positioner/ComboboxPositioner.js

@@ -5,21 +5,21 @@ import { useStore } from '@base-ui/utils/store';
 import { useIsoLayoutEffect } from '@base-ui/utils/useIsoLayoutEffect';
 import { useStableCallback } from '@base-ui/utils/useStableCallback';
 import { inertValue } from '@base-ui/utils/inertValue';
-import { useScrollLock } from '@base-ui/utils/useScrollLock';
 import { useComboboxFloatingContext, useComboboxRootContext, useComboboxDerivedItemsContext } from "../root/ComboboxRootContext.js";
 import { ComboboxPositionerContext } from "./ComboboxPositionerContext.js";
 import { useAnchorPositioning } from "../../utils/useAnchorPositioning.js";
-import { popupStateMapping } from "../../utils/popupStateMapping.js";
 import { useComboboxPortalContext } from "../portal/ComboboxPortalContext.js";
-import { DROPDOWN_COLLISION_AVOIDANCE } from "../../utils/constants.js";
-import { getDisabledMountTransitionStyles } from "../../utils/getDisabledMountTransitionStyles.js";
-import { useRenderElement } from "../../utils/useRenderElement.js";
+import { DROPDOWN_COLLISION_AVOIDANCE } from "../../internals/constants.js";
 import { selectors } from "../store.js";
 import { InternalBackdrop } from "../../utils/InternalBackdrop.js";
+import { usePositioner } from "../../utils/usePositioner.js";
+import { useAnchoredPopupScrollLock } from "../../utils/useAnchoredPopupScrollLock.js";
 
 /**
  * Positions the popup against the trigger.
  * Renders a `<div>` element.
+ *
+ * Documentation: [Base UI Combobox](https://base-ui.com/react/components/combobox)
  */
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 export const ComboboxPositioner = /*#__PURE__*/React.forwardRef(function ComboboxPositioner(componentProps, forwardedRef) {
@@ -38,6 +38,7 @@ export const ComboboxPositioner = /*#__PURE__*/React.forwardRef(function Combobo
     sticky = false,
     disableAnchorTracking = false,
     collisionAvoidance = DROPDOWN_COLLISION_AVOIDANCE,
+    style: styleProp,
     ...elementProps
   } = componentProps;
   const store = useComboboxRootContext();
@@ -50,6 +51,7 @@ export const ComboboxPositioner = /*#__PURE__*/React.forwardRef(function Combobo
   const open = useStore(store, selectors.open);
   const mounted = useStore(store, selectors.mounted);
   const openMethod = useStore(store, selectors.openMethod);
+  const positionerElement = useStore(store, selectors.positionerElement);
   const triggerElement = useStore(store, selectors.triggerElement);
   const inputElement = useStore(store, selectors.inputElement);
   const inputGroupElement = useStore(store, selectors.inputGroupElement);
@@ -75,20 +77,7 @@ export const ComboboxPositioner = /*#__PURE__*/React.forwardRef(function Combobo
     collisionAvoidance,
     lazyFlip: true
   });
-  useScrollLock(open && modal && openMethod !== 'touch', triggerElement);
-  const defaultProps = React.useMemo(() => {
-    const style = {
-      ...positioning.positionerStyles
-    };
-    if (!open) {
-      style.pointerEvents = 'none';
-    }
-    return {
-      role: 'presentation',
-      hidden: !mounted,
-      style
-    };
-  }, [open, mounted, positioning.positionerStyles]);
+  useAnchoredPopupScrollLock(open && modal, openMethod === 'touch', positionerElement, triggerElement);
   const state = {
     open,
     side: positioning.side,
@@ -99,26 +88,19 @@ export const ComboboxPositioner = /*#__PURE__*/React.forwardRef(function Combobo
   useIsoLayoutEffect(() => {
     store.set('popupSide', positioning.side);
   }, [store, positioning.side]);
-  const contextValue = React.useMemo(() => ({
-    side: positioning.side,
-    align: positioning.align,
-    arrowRef: positioning.arrowRef,
-    arrowUncentered: positioning.arrowUncentered,
-    arrowStyles: positioning.arrowStyles,
-    anchorHidden: positioning.anchorHidden,
-    isPositioned: positioning.isPositioned
-  }), [positioning.side, positioning.align, positioning.arrowRef, positioning.arrowUncentered, positioning.arrowStyles, positioning.anchorHidden, positioning.isPositioned]);
   const setPositionerElement = useStableCallback(element => {
     store.set('positionerElement', element);
   });
-  const element = useRenderElement('div', componentProps, {
-    state,
-    ref: [forwardedRef, setPositionerElement],
-    props: [defaultProps, getDisabledMountTransitionStyles(transitionStatus), elementProps],
-    stateAttributesMapping: popupStateMapping
+  const element = usePositioner(componentProps, state, {
+    styles: positioning.positionerStyles,
+    transitionStatus,
+    props: elementProps,
+    refs: [forwardedRef, setPositionerElement],
+    hidden: !mounted,
+    inert: !open
   });
   return /*#__PURE__*/_jsxs(ComboboxPositionerContext.Provider, {
-    value: contextValue,
+    value: positioning,
     children: [mounted && modal && /*#__PURE__*/_jsx(InternalBackdrop, {
       inert: inertValue(!open),
       cutout: inputGroupElement ?? inputElement ?? triggerElement

package/esm/combobox/positioner/ComboboxPositionerContext.d.ts

@@ -1,14 +1,6 @@
 import * as React from 'react';
-import type { Side, Align } from "../../utils/useAnchorPositioning.js";
-export interface ComboboxPositionerContext {
-  side: Side;
-  align: Align;
-  arrowRef: React.RefObject<Element | null>;
-  arrowUncentered: boolean;
-  arrowStyles: React.CSSProperties;
-  anchorHidden: boolean;
-  isPositioned: boolean;
-}
+import type { UseAnchorPositioningReturnValue } from "../../utils/useAnchorPositioning.js";
+export type ComboboxPositionerContext = Pick<UseAnchorPositioningReturnValue, 'side' | 'align' | 'arrowRef' | 'arrowUncentered' | 'arrowStyles' | 'anchorHidden' | 'isPositioned'>;
 export declare const ComboboxPositionerContext: React.Context<ComboboxPositionerContext | undefined>;
 export declare function useComboboxPositionerContext(optional?: false): ComboboxPositionerContext;
 export declare function useComboboxPositionerContext(optional: true): ComboboxPositionerContext | undefined;

package/esm/combobox/root/AriaCombobox.d.ts

@@ -1,7 +1,7 @@
 import * as React from 'react';
-import { type BaseUIChangeEventDetails, type BaseUIGenericEventDetails } from "../../utils/createBaseUIEventDetails.js";
-import { REASONS } from "../../utils/reasons.js";
-import { Group } from "../../utils/resolveValueLabel.js";
+import { type BaseUIChangeEventDetails, type BaseUIGenericEventDetails } from "../../internals/createBaseUIEventDetails.js";
+import { REASONS } from "../../internals/reasons.js";
+import { Group } from "../../internals/resolveValueLabel.js";
 /**
  * @internal
  */
@@ -19,6 +19,11 @@ interface ComboboxRootProps<ItemValue> {
    * Identifies the field when a form is submitted.
    */
   name?: string | undefined;
+  /**
+   * Identifies the form that owns the internal input.
+   * Useful when the combobox is rendered outside the form.
+   */
+  form?: string | undefined;
   /**
    * The id of the component.
    */

package/esm/combobox/root/AriaCombobox.js

@@ -6,30 +6,30 @@ import { useIsoLayoutEffect } from '@base-ui/utils/useIsoLayoutEffect';
 import { useOnFirstRender } from '@base-ui/utils/useOnFirstRender';
 import { useStableCallback } from '@base-ui/utils/useStableCallback';
 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 { useValueAsRef } from '@base-ui/utils/useValueAsRef';
+import { EMPTY_ARRAY, EMPTY_OBJECT } from '@base-ui/utils/empty';
 import { useDismiss, useFloatingRootContext, useInteractions, useListNavigation, useClick } from "../../floating-ui-react/index.js";
 import { contains, getTarget } from "../../floating-ui-react/utils.js";
-import { createChangeEventDetails, createGenericEventDetails } from "../../utils/createBaseUIEventDetails.js";
-import { REASONS } from "../../utils/reasons.js";
+import { createChangeEventDetails, createGenericEventDetails } from "../../internals/createBaseUIEventDetails.js";
+import { REASONS } from "../../internals/reasons.js";
 import { ComboboxFloatingContext, ComboboxDerivedItemsContext, ComboboxRootContext, ComboboxInputValueContext } from "./ComboboxRootContext.js";
 import { selectors } from "../store.js";
-import { useOpenChangeComplete } from "../../utils/useOpenChangeComplete.js";
-import { useFieldRootContext } from "../../field/root/FieldRootContext.js";
-import { useField } from "../../field/useField.js";
-import { useFormContext } from "../../form/FormContext.js";
-import { useLabelableId } from "../../labelable-provider/useLabelableId.js";
+import { useOpenChangeComplete } from "../../internals/useOpenChangeComplete.js";
+import { useFieldRootContext } from "../../internals/field-root-context/FieldRootContext.js";
+import { useRegisterFieldControl } from "../../internals/field-register-control/useRegisterFieldControl.js";
+import { useFormContext } from "../../internals/form-context/FormContext.js";
+import { useLabelableId } from "../../internals/labelable-provider/useLabelableId.js";
 import { createCollatorItemFilter, createSingleSelectionCollatorFilter } from "./utils/index.js";
 import { useCoreFilter } from "./utils/useFilter.js";
-import { useTransitionStatus } from "../../utils/useTransitionStatus.js";
-import { EMPTY_ARRAY, EMPTY_OBJECT } from "../../utils/constants.js";
+import { useTransitionStatus } from "../../internals/useTransitionStatus.js";
 import { useOpenInteractionType } from "../../utils/useOpenInteractionType.js";
-import { useValueChanged } from "../../utils/useValueChanged.js";
-import { NOOP } from "../../utils/noop.js";
-import { stringifyAsLabel, stringifyAsValue, isGroupedItems } from "../../utils/resolveValueLabel.js";
-import { compareItemEquality, defaultItemEquality, findItemIndex, removeItem, selectedValueIncludes } from "../../utils/itemEquality.js";
+import { useValueChanged } from "../../internals/useValueChanged.js";
+import { NOOP } from "../../internals/noop.js";
+import { stringifyAsLabel, stringifyAsValue, isGroupedItems } from "../../internals/resolveValueLabel.js";
+import { compareItemEquality, defaultItemEquality, findItemIndex, removeItem, selectedValueIncludes } from "../../internals/itemEquality.js";
 import { INITIAL_LAST_HIGHLIGHT, NO_ACTIVE_VALUE } from "./utils/constants.js";
 
 /**
@@ -45,9 +45,12 @@ export function AriaCombobox(props) {
     onSelectedValueChange,
     defaultInputValue: defaultInputValueProp,
     inputValue: inputValueProp,
+    open: openProp,
+    defaultOpen = false,
     selectionMode = 'none',
     onItemHighlighted: onItemHighlightedProp,
     name: nameProp,
+    form,
     disabled: disabledProp = false,
     readOnly = false,
     required = false,
@@ -173,8 +176,8 @@ export function AriaCombobox(props) {
     state: 'inputValue'
   });
   const [open, setOpenUnwrapped] = useControlled({
-    controlled: props.open,
-    default: props.defaultOpen,
+    controlled: openProp,
+    default: defaultOpen,
     name: 'Combobox',
     state: 'open'
   });
@@ -276,6 +279,7 @@ export function AriaCombobox(props) {
     allValuesRef,
     selectionEventRef,
     name,
+    form,
     disabled,
     readOnly,
     required,
@@ -349,13 +353,11 @@ export function AriaCombobox(props) {
     openMethod,
     triggerProps
   } = useOpenInteractionType(open);
-  useField({
+  const getFieldValue = useStableCallback(() => fieldStringValue);
+  useRegisterFieldControl(inputInsidePopup ? triggerRef : inputRef, {
     id,
-    name,
-    commit: validation.commit,
     value: fieldRawValue,
-    controlRef: inputInsidePopup ? triggerRef : inputRef,
-    getValue: () => fieldStringValue
+    getValue: getFieldValue
   });
   const forceMount = useStableCallback(() => {
     if (items) {
@@ -536,9 +538,9 @@ export function AriaCombobox(props) {
     if (!store.state.submitOnItemClick) {
       return;
     }
-    const form = store.state.inputElement?.form;
-    if (form && typeof form.requestSubmit === 'function') {
-      form.requestSubmit();
+    const formElement = validation.inputRef.current?.form ?? store.state.inputElement?.form;
+    if (formElement && typeof formElement.requestSubmit === 'function') {
+      formElement.requestSubmit();
     }
   });
   const handleUnmount = useStableCallback(() => {
@@ -793,9 +795,9 @@ export function AriaCombobox(props) {
     enabled: !readOnly && !disabled && openOnInputClick,
     event: 'mousedown-only',
     toggle: false,
-    // Apply a small delay for touch to let iOS viewport centering settle.
+    // Apply a small delay for touch to let mobile viewport/keyboard positioning settle.
     // This avoids top-bottom flip flickers if the preferred position is "top" when first tapping.
-    touchOpenDelay: inputInsidePopup ? 0 : 50,
+    touchOpenDelay: inputInsidePopup ? 0 : 100,
     reason: REASONS.inputPress
   });
   const dismiss = useDismiss(floatingRootContext, {
@@ -888,6 +890,7 @@ export function AriaCombobox(props) {
       getItemProps,
       selectionMode,
       name,
+      form,
       disabled,
       readOnly,
       required,
@@ -904,7 +907,7 @@ export function AriaCombobox(props) {
       hasInputValue,
       requestSubmit
     });
-  }, [store, id, selectedValue, open, mounted, transitionStatus, items, getFloatingProps, getReferenceProps, getItemProps, openMethod, triggerProps, selectionMode, name, disabled, readOnly, required, validation, grid, isGrouped, virtualized, onOpenChangeComplete, openOnInputClick, itemToStringLabel, modal, isItemEqualToValue, submitOnItemClick, hasInputValue, inlineProp, requestSubmit, autoHighlightMode]);
+  }, [store, id, selectedValue, open, mounted, transitionStatus, items, getFloatingProps, getReferenceProps, getItemProps, openMethod, triggerProps, selectionMode, name, disabled, readOnly, required, validation, grid, isGrouped, virtualized, onOpenChangeComplete, openOnInputClick, itemToStringLabel, modal, isItemEqualToValue, submitOnItemClick, hasInputValue, inlineProp, requestSubmit, autoHighlightMode, form]);
   const hiddenInputRef = useMergedRefs(inputRefProp, validation.inputRef);
   const itemsContextValue = React.useMemo(() => ({
     query,
@@ -928,11 +931,12 @@ export function AriaCombobox(props) {
       const currentSerializedValue = stringifyAsValue(value, itemToStringValue);
       return /*#__PURE__*/_jsx("input", {
         type: "hidden",
+        form: form,
         name: name,
         value: currentSerializedValue
       }, currentSerializedValue);
     });
-  }, [multiple, selectedValue, name, itemToStringValue]);
+  }, [multiple, selectedValue, form, name, itemToStringValue]);
   const children = /*#__PURE__*/_jsxs(React.Fragment, {
     children: [props.children, /*#__PURE__*/_jsx("input", {
       ...validation.getInputValidationProps({
@@ -950,7 +954,7 @@ export function AriaCombobox(props) {
           if (event.nativeEvent.defaultPrevented) {
             return;
           }
-          const nextValue = event.target.value;
+          const nextValue = event.currentTarget.value;
           const details = createChangeEventDetails(REASONS.none, event.nativeEvent);
           function handleChange() {
             // Browser autofill only writes a single scalar value.
@@ -966,8 +970,15 @@ export function AriaCombobox(props) {
               return;
             }
             const matchingValue = valuesRef.current.find(v => {
-              const candidate = stringifyAsValue(v, itemToStringValue);
-              if (candidate.toLowerCase() === nextValue.toLowerCase()) {
+              // Try matching by value first (e.g., "US" for country code)
+              const candidateValue = stringifyAsValue(v, itemToStringValue);
+              if (candidateValue.toLowerCase() === nextValue.toLowerCase()) {
+                return true;
+              }
+              // Also try matching by label for browser autofill compatibility
+              // (browsers autofill with displayed text like "United States", not the underlying value)
+              const candidateLabel = stringifyAsLabel(v, itemToStringLabel);
+              if (candidateLabel.toLowerCase() === nextValue.toLowerCase()) {
                 return true;
               }
               return false;
@@ -989,6 +1000,7 @@ export function AriaCombobox(props) {
         }
       }),
       id: id && hiddenInputName == null ? `${id}-hidden-input` : undefined,
+      form: form,
       name: hiddenInputName,
       autoComplete: formAutoComplete,
       disabled: disabled,
@@ -998,7 +1010,8 @@ export function AriaCombobox(props) {
       ref: hiddenInputRef,
       style: hiddenInputName ? visuallyHiddenInput : visuallyHidden,
       tabIndex: -1,
-      "aria-hidden": true
+      "aria-hidden": true,
+      suppressHydrationWarning: true
     }), hiddenInputs]
   });
   return /*#__PURE__*/_jsx(ComboboxRootContext.Provider, {

package/esm/combobox/root/utils/index.js

@@ -1,4 +1,4 @@
-import { stringifyAsLabel } from "../../../utils/resolveValueLabel.js";
+import { stringifyAsLabel } from "../../../internals/resolveValueLabel.js";
 /**
  * Enhanced filter using Intl.Collator for more robust string matching.
  * Uses the provided `itemToStringLabel` function if available, otherwise falls back to:

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

@@ -1,16 +1,5 @@
-export interface UseFilterOptions extends Intl.CollatorOptions {
-  /**
-   * The locale to use for string comparison.
-   * Defaults to the user's runtime locale.
-   */
-  locale?: Intl.LocalesArgument | undefined;
-}
-export interface Filter {
-  contains: <Item>(item: Item, query: string, itemToString?: (item: Item) => string) => boolean;
-  startsWith: <Item>(item: Item, query: string, itemToString?: (item: Item) => string) => boolean;
-  endsWith: <Item>(item: Item, query: string, itemToString?: (item: Item) => string) => boolean;
-}
-declare function getFilter(options?: UseFilterOptions): Filter;
+import { type Filter, type GetFilterParameters as UseFilterOptions, getFilter } from "../../../internals/filter.js";
+export type { Filter, UseFilterOptions };
 /**
  * Matches items against a query using `Intl.Collator` for robust string matching.
  */
@@ -29,5 +18,4 @@ export interface UseComboboxFilterOptions extends UseFilterOptions {
 /**
  * Matches items against a query using `Intl.Collator` for robust string matching.
  */
-export declare function useComboboxFilter(options?: UseComboboxFilterOptions): Filter;
-export {};
+export declare function useComboboxFilter(options?: UseComboboxFilterOptions): Filter;

package/esm/combobox/root/utils/useFilter.js

@@ -2,63 +2,7 @@
 
 import * as React from 'react';
 import { createCollatorItemFilter, createSingleSelectionCollatorFilter } from "./index.js";
-import { stringifyAsLabel } from "../../../utils/resolveValueLabel.js";
-const filterCache = new Map();
-function stringifyLocale(locale) {
-  if (Array.isArray(locale)) {
-    return locale.map(value => stringifyLocale(value)).join(',');
-  }
-  if (locale == null) {
-    return '';
-  }
-  return String(locale);
-}
-function getFilter(options = {}) {
-  const mergedOptions = {
-    usage: 'search',
-    sensitivity: 'base',
-    ignorePunctuation: true,
-    ...options
-  };
-  const cacheKey = `${stringifyLocale(options.locale)}|${JSON.stringify(mergedOptions)}`;
-  const cachedFilter = filterCache.get(cacheKey);
-  if (cachedFilter) {
-    return cachedFilter;
-  }
-  const collator = new Intl.Collator(options.locale, mergedOptions);
-  const filter = {
-    contains(item, query, itemToString) {
-      if (!query) {
-        return true;
-      }
-      const itemString = stringifyAsLabel(item, itemToString);
-      for (let i = 0; i <= itemString.length - query.length; i += 1) {
-        if (collator.compare(itemString.slice(i, i + query.length), query) === 0) {
-          return true;
-        }
-      }
-      return false;
-    },
-    startsWith(item, query, itemToString) {
-      if (!query) {
-        return true;
-      }
-      const itemString = stringifyAsLabel(item, itemToString);
-      return collator.compare(itemString.slice(0, query.length), query) === 0;
-    },
-    endsWith(item, query, itemToString) {
-      if (!query) {
-        return true;
-      }
-      const itemString = stringifyAsLabel(item, itemToString);
-      const queryLength = query.length;
-      return itemString.length >= queryLength && collator.compare(itemString.slice(itemString.length - queryLength), query) === 0;
-    }
-  };
-  filterCache.set(cacheKey, filter);
-  return filter;
-}
-
+import { getFilter } from "../../../internals/filter.js";
 /**
  * Matches items against a query using `Intl.Collator` for robust string matching.
  */

package/esm/combobox/row/ComboboxRow.d.ts

@@ -1,9 +1,11 @@
 import * as React from 'react';
-import { BaseUIComponentProps } from "../../utils/types.js";
+import { BaseUIComponentProps } from "../../internals/types.js";
 /**
  * Displays a single row of items in a grid list.
  * Enable `grid` on the root component to turn the listbox into a grid.
  * Renders a `<div>` element.
+ *
+ * Documentation: [Base UI Combobox](https://base-ui.com/react/components/combobox)
  */
 export declare const ComboboxRow: React.ForwardRefExoticComponent<Omit<ComboboxRowProps, "ref"> & React.RefAttributes<HTMLDivElement>>;
 export interface ComboboxRowState {}

package/esm/combobox/row/ComboboxRow.js

@@ -1,19 +1,22 @@
 'use client';
 
 import * as React from 'react';
-import { useRenderElement } from "../../utils/useRenderElement.js";
+import { useRenderElement } from "../../internals/useRenderElement.js";
 import { ComboboxRowContext } from "./ComboboxRowContext.js";
 
 /**
  * Displays a single row of items in a grid list.
  * Enable `grid` on the root component to turn the listbox into a grid.
  * Renders a `<div>` element.
+ *
+ * Documentation: [Base UI Combobox](https://base-ui.com/react/components/combobox)
  */
 import { jsx as _jsx } from "react/jsx-runtime";
 export const ComboboxRow = /*#__PURE__*/React.forwardRef(function ComboboxRow(componentProps, forwardedRef) {
   const {
     render,
     className,
+    style,
     ...elementProps
   } = componentProps;
   const element = useRenderElement('div', componentProps, {

package/esm/combobox/status/ComboboxStatus.d.ts

@@ -1,9 +1,15 @@
 import * as React from 'react';
-import { BaseUIComponentProps } from "../../utils/types.js";
+import { BaseUIComponentProps } from "../../internals/types.js";
 /**
  * Displays a status message whose content changes are announced politely to screen readers.
  * Useful for conveying the status of an asynchronously loaded list.
+ * This component's root element must remain mounted in the DOM to announce
+ * changes consistently across screen readers. Avoid hiding or removing the
+ * component itself with `display: none`, `hidden`, `aria-hidden`, or conditional
+ * rendering. Prefer updating or conditionally rendering its children instead.
  * Renders a `<div>` element.
+ *
+ * Documentation: [Base UI Combobox](https://base-ui.com/react/components/combobox)
  */
 export declare const ComboboxStatus: React.ForwardRefExoticComponent<Omit<ComboboxStatusProps, "ref"> & React.RefAttributes<HTMLDivElement>>;
 export interface ComboboxStatusState {}

package/esm/combobox/status/ComboboxStatus.js

@@ -1,22 +1,33 @@
 'use client';
 
 import * as React from 'react';
-import { useRenderElement } from "../../utils/useRenderElement.js";
+import { useRenderElement } from "../../internals/useRenderElement.js";
+import { useInitialLiveRegionTextMutation } from "../utils/useInitialLiveRegionTextMutation.js";
 
 /**
  * Displays a status message whose content changes are announced politely to screen readers.
  * Useful for conveying the status of an asynchronously loaded list.
+ * This component's root element must remain mounted in the DOM to announce
+ * changes consistently across screen readers. Avoid hiding or removing the
+ * component itself with `display: none`, `hidden`, `aria-hidden`, or conditional
+ * rendering. Prefer updating or conditionally rendering its children instead.
  * Renders a `<div>` element.
+ *
+ * Documentation: [Base UI Combobox](https://base-ui.com/react/components/combobox)
  */
 export const ComboboxStatus = /*#__PURE__*/React.forwardRef(function ComboboxStatus(componentProps, forwardedRef) {
   const {
     render,
     className,
+    style,
+    children: childrenProp,
     ...elementProps
   } = componentProps;
+  const statusRef = useInitialLiveRegionTextMutation();
   return useRenderElement('div', componentProps, {
-    ref: forwardedRef,
+    ref: [forwardedRef, statusRef],
     props: [{
+      children: childrenProp,
       role: 'status',
       'aria-live': 'polite',
       'aria-atomic': true

package/esm/combobox/store.d.ts

@@ -1,7 +1,7 @@
 import { Store } from '@base-ui/utils/store';
 import type { InteractionType } from '@base-ui/utils/useEnhancedClickHandler';
-import type { TransitionStatus } from "../utils/useTransitionStatus.js";
-import type { HTMLProps } from "../utils/types.js";
+import type { TransitionStatus } from "../internals/useTransitionStatus.js";
+import type { HTMLProps } from "../internals/types.js";
 import type { Side } from "../utils/useAnchorPositioning.js";
 import type { AriaCombobox } from "./root/AriaCombobox.js";
 export type State = {
@@ -60,6 +60,7 @@ export type State = {
   }) => Record<string, unknown>;
   requestSubmit: () => void;
   name: string | undefined;
+  form: string | undefined;
   disabled: boolean;
   readOnly: boolean;
   required: boolean;
@@ -79,7 +80,6 @@ export type ComboboxStore = Store<State>;
 export declare const selectors: {
   id: (state: State) => string | undefined;
   labelId: (state: State) => string | undefined;
-  query: (state: State) => string;
   items: (state: State) => readonly any[] | undefined;
   selectedValue: (state: State) => any;
   hasSelectionChips: (state: State) => boolean;
@@ -110,25 +110,13 @@ export declare const selectors: {
   openMethod: (state: State) => InteractionType | null;
   inputInsidePopup: (state: State) => boolean;
   selectionMode: (state: State) => "none" | "multiple" | "single";
-  listRef: (state: State) => import("react").RefObject<(HTMLElement | null)[]>;
-  labelsRef: (state: State) => import("react").RefObject<(string | null)[]>;
-  popupRef: (state: State) => import("react").RefObject<HTMLDivElement | null>;
-  emptyRef: (state: State) => import("react").RefObject<HTMLDivElement | null>;
-  inputRef: (state: State) => import("react").RefObject<HTMLInputElement | null>;
-  keyboardActiveRef: (state: State) => import("react").RefObject<boolean>;
-  chipsContainerRef: (state: State) => import("react").RefObject<HTMLDivElement | null>;
-  clearRef: (state: State) => import("react").RefObject<HTMLButtonElement | null>;
-  valuesRef: (state: State) => import("react").RefObject<any[]>;
-  allValuesRef: (state: State) => import("react").RefObject<any[]>;
   name: (state: State) => string | undefined;
+  form: (state: State) => string | undefined;
   disabled: (state: State) => boolean;
   readOnly: (state: State) => boolean;
   required: (state: State) => boolean;
   grid: (state: State) => boolean;
-  isGrouped: (state: State) => boolean;
   virtualized: (state: State) => boolean;
-  onOpenChangeComplete: (state: State) => (open: boolean) => void;
-  openOnInputClick: (state: State) => boolean;
   itemToStringLabel: (state: State) => ((item: any) => string) | undefined;
   isItemEqualToValue: (state: State) => (itemValue: any, selectedValue: any) => boolean;
   modal: (state: State) => boolean;

package/esm/combobox/store.js

@@ -1,10 +1,9 @@
 import { createSelector } from '@base-ui/utils/store';
-import { compareItemEquality } from "../utils/itemEquality.js";
-import { hasNullItemLabel } from "../utils/resolveValueLabel.js";
+import { compareItemEquality } from "../internals/itemEquality.js";
+import { hasNullItemLabel } from "../internals/resolveValueLabel.js";
 export const selectors = {
   id: createSelector(state => state.id),
   labelId: createSelector(state => state.labelId),
-  query: createSelector(state => state.query),
   items: createSelector(state => state.items),
   selectedValue: createSelector(state => state.selectedValue),
   hasSelectionChips: createSelector(state => {
@@ -56,25 +55,13 @@ export const selectors = {
   openMethod: createSelector(state => state.openMethod),
   inputInsidePopup: createSelector(state => state.inputInsidePopup),
   selectionMode: createSelector(state => state.selectionMode),
-  listRef: createSelector(state => state.listRef),
-  labelsRef: createSelector(state => state.labelsRef),
-  popupRef: createSelector(state => state.popupRef),
-  emptyRef: createSelector(state => state.emptyRef),
-  inputRef: createSelector(state => state.inputRef),
-  keyboardActiveRef: createSelector(state => state.keyboardActiveRef),
-  chipsContainerRef: createSelector(state => state.chipsContainerRef),
-  clearRef: createSelector(state => state.clearRef),
-  valuesRef: createSelector(state => state.valuesRef),
-  allValuesRef: createSelector(state => state.allValuesRef),
   name: createSelector(state => state.name),
+  form: createSelector(state => state.form),
   disabled: createSelector(state => state.disabled),
   readOnly: createSelector(state => state.readOnly),
   required: createSelector(state => state.required),
   grid: createSelector(state => state.grid),
-  isGrouped: createSelector(state => state.isGrouped),
   virtualized: createSelector(state => state.virtualized),
-  onOpenChangeComplete: createSelector(state => state.onOpenChangeComplete),
-  openOnInputClick: createSelector(state => state.openOnInputClick),
   itemToStringLabel: createSelector(state => state.itemToStringLabel),
   isItemEqualToValue: createSelector(state => state.isItemEqualToValue),
   modal: createSelector(state => state.modal),

package/esm/combobox/trigger/ComboboxTrigger.d.ts

@@ -1,10 +1,12 @@
 import * as React from 'react';
-import { BaseUIComponentProps, NativeButtonProps } from "../../utils/types.js";
+import { BaseUIComponentProps, NativeButtonProps } from "../../internals/types.js";
 import type { FieldRootState } from "../../field/root/FieldRoot.js";
 import type { Side } from "../../utils/useAnchorPositioning.js";
 /**
  * A button that opens the popup.
  * Renders a `<button>` element.
+ *
+ * Documentation: [Base UI Combobox](https://base-ui.com/react/components/combobox)
  */
 export declare const ComboboxTrigger: React.ForwardRefExoticComponent<Omit<ComboboxTriggerProps, "ref"> & React.RefAttributes<HTMLButtonElement>>;
 export interface ComboboxTriggerState extends FieldRootState {