@base-ui/react 1.0.0 → 1.2.0

package/combobox/root/ComboboxRoot.d.ts

@@ -9,59 +9,64 @@ import { AriaCombobox } from "./AriaCombobox.js";
 export declare function ComboboxRoot<Value, Multiple extends boolean | undefined = false>(props: ComboboxRoot.Props<Value, Multiple>): 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' | 'submitOnItemClick' | 'autoHighlight' | 'keepHighlight' | 'highlightItemOnHover' | 'itemToStringLabel' | 'itemToStringValue' | 'isItemEqualToValue' | 'selectionMode' | 'defaultSelectedValue' | 'selectedValue' | 'onSelectedValueChange' | 'actionsRef' | 'onOpenChange' | 'onInputValueChange' | 'onItemHighlighted'> & {
+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'> & {
   /**
    * Whether multiple items can be selected.
    * @default false
    */
-  multiple?: Multiple;
+  multiple?: Multiple | undefined;
+  /**
+   * Provides a hint to the browser for autofill.
+   * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Attributes/autocomplete
+   */
+  autoComplete?: string | undefined;
   /**
    * Whether the first matching item is highlighted automatically while filtering.
    * @default false
    */
-  autoHighlight?: boolean;
+  autoHighlight?: boolean | undefined;
   /**
    * Whether moving the pointer over items should highlight them.
    * Disabling this prop allows CSS `:hover` to be differentiated from the `:focus` (`data-highlighted`) state.
    * @default true
    */
-  highlightItemOnHover?: boolean;
+  highlightItemOnHover?: boolean | undefined;
   /**
    * 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.
    */
-  itemToStringLabel?: (itemValue: Value) => string;
+  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.
    */
-  itemToStringValue?: (itemValue: Value) => string;
+  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.
    * Defaults to `Object.is` comparison.
    */
-  isItemEqualToValue?: (itemValue: Value, selectedValue: Value) => boolean;
+  isItemEqualToValue?: ((itemValue: Value, value: Value) => boolean) | undefined;
   /**
    * The uncontrolled selected value of the combobox when it's initially rendered.
    *
    * To render a controlled combobox, use the `value` prop instead.
    */
-  defaultValue?: ComboboxValueType<Value, Multiple> | null;
+  defaultValue?: (ComboboxValueType<Value, Multiple> | null) | undefined;
   /**
    * A ref to imperative actions.
    * - `unmount`: When specified, the combobox will not be unmounted when closed.
    * Instead, the `unmount` function must be called to unmount the combobox manually.
    * Useful when the combobox's animation is controlled by an external library.
    */
-  actionsRef?: React.RefObject<ComboboxRoot.Actions>;
+  actionsRef?: React.RefObject<ComboboxRoot.Actions | null> | undefined;
   /**
    * Event handler called when the popup is opened or closed.
    */
-  onOpenChange?: (open: boolean, eventDetails: ComboboxRoot.ChangeEventDetails) => void;
+  onOpenChange?: ((open: boolean, eventDetails: ComboboxRoot.ChangeEventDetails) => void) | undefined;
   /**
    * Event handler called when the input value changes.
    */
-  onInputValueChange?: (inputValue: string, eventDetails: ComboboxRoot.ChangeEventDetails) => void;
+  onInputValueChange?: ((inputValue: string, eventDetails: ComboboxRoot.ChangeEventDetails) => void) | undefined;
   /**
    * Callback fired when an item is highlighted or unhighlighted.
    * Receives the highlighted item value (or `undefined` if no item is highlighted) and event details with a `reason` property describing why the highlight changed.
@@ -70,15 +75,15 @@ export type ComboboxRootProps<Value, Multiple extends boolean | undefined = fals
    * - `'pointer'`: the highlight changed due to pointer hovering.
    * - `'none'`: the highlight changed programmatically.
    */
-  onItemHighlighted?: (highlightedValue: Value | undefined, eventDetails: ComboboxRoot.HighlightEventDetails) => void;
+  onItemHighlighted?: ((highlightedValue: Value | undefined, eventDetails: ComboboxRoot.HighlightEventDetails) => void) | undefined;
   /**
    * The selected value of the combobox. Use when controlled.
    */
-  value?: ComboboxValueType<Value, Multiple> | null;
+  value?: (ComboboxValueType<Value, Multiple> | null) | undefined;
   /**
    * Event handler called when the selected value of the combobox changes.
    */
-  onValueChange?: (value: ComboboxValueType<Value, Multiple> | (Multiple extends true ? never : null), eventDetails: ComboboxRoot.ChangeEventDetails) => void;
+  onValueChange?: ((value: ComboboxValueType<Value, Multiple> | (Multiple extends true ? never : null), eventDetails: ComboboxRoot.ChangeEventDetails) => void) | undefined;
 };
 export type ComboboxRootState = AriaCombobox.State;
 export type ComboboxRootActions = AriaCombobox.Actions;

package/combobox/root/ComboboxRoot.js

@@ -21,6 +21,7 @@ function ComboboxRoot(props) {
     defaultValue,
     value,
     onValueChange,
+    autoComplete,
     ...other
   } = props;
   return /*#__PURE__*/(0, _jsxRuntime.jsx)(_AriaCombobox.AriaCombobox, {
@@ -28,6 +29,7 @@ function ComboboxRoot(props) {
     selectionMode: multiple ? 'multiple' : 'single',
     selectedValue: value,
     defaultSelectedValue: defaultValue,
-    onSelectedValueChange: onValueChange
+    onSelectedValueChange: onValueChange,
+    formAutoComplete: autoComplete
   });
 }

package/combobox/root/ComboboxRootContext.d.ts

@@ -2,6 +2,7 @@ import * as React from 'react';
 import { ComboboxStore } from "../store.js";
 export interface ComboboxDerivedItemsContext {
   query: string;
+  hasItems: boolean;
   filteredItems: any[];
   flatFilteredItems: any[];
 }

package/combobox/root/ComboboxRootContext.js

@@ -1,4 +1,5 @@
 "use strict";
+'use client';
 
 var _interopRequireWildcard = require("@babel/runtime/helpers/interopRequireWildcard").default;
 var _interopRequireDefault = require("@babel/runtime/helpers/interopRequireDefault").default;

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

@@ -3,7 +3,7 @@ export interface UseFilterOptions extends Intl.CollatorOptions {
    * The locale to use for string comparison.
    * Defaults to the user's runtime locale.
    */
-  locale?: Intl.LocalesArgument;
+  locale?: Intl.LocalesArgument | undefined;
 }
 export interface Filter {
   contains: <Item>(item: Item, query: string, itemToString?: (item: Item) => string) => boolean;
@@ -20,7 +20,7 @@ export interface UseComboboxFilterOptions extends UseFilterOptions {
    * Whether the combobox is in multiple selection mode.
    * @default false
    */
-  multiple?: boolean;
+  multiple?: boolean | undefined;
   /**
    * The current value of the combobox.
    */

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

@@ -0,0 +1,4 @@
+/**
+ * Returns the internally filtered items.
+ */
+export declare function useFilteredItems<T>(): T[];

package/combobox/root/utils/useFilteredItems.js

@@ -0,0 +1,14 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.useFilteredItems = useFilteredItems;
+var _ComboboxRootContext = require("../ComboboxRootContext");
+/**
+ * Returns the internally filtered items.
+ */
+function useFilteredItems() {
+  const items = (0, _ComboboxRootContext.useComboboxDerivedItemsContext)();
+  return items.filteredItems;
+}

package/combobox/row/ComboboxRow.d.ts

@@ -5,7 +5,7 @@ import { BaseUIComponentProps } from "../../utils/types.js";
  * Enable `grid` on the root component to turn the listbox into a grid.
  * Renders a `<div>` element.
  */
-export declare const ComboboxRow: React.ForwardRefExoticComponent<ComboboxRowProps & React.RefAttributes<HTMLDivElement>>;
+export declare const ComboboxRow: React.ForwardRefExoticComponent<Omit<ComboboxRowProps, "ref"> & React.RefAttributes<HTMLDivElement>>;
 export interface ComboboxRowState {}
 export interface ComboboxRowProps extends BaseUIComponentProps<'div', ComboboxRow.State> {}
 export declare namespace ComboboxRow {

package/combobox/row/ComboboxRowContext.js

@@ -1,4 +1,5 @@
 "use strict";
+'use client';
 
 var _interopRequireWildcard = require("@babel/runtime/helpers/interopRequireWildcard").default;
 Object.defineProperty(exports, "__esModule", {

package/combobox/status/ComboboxStatus.d.ts

@@ -5,7 +5,7 @@ import { BaseUIComponentProps } from "../../utils/types.js";
  * Useful for conveying the status of an asynchronously loaded list.
  * Renders a `<div>` element.
  */
-export declare const ComboboxStatus: React.ForwardRefExoticComponent<ComboboxStatusProps & React.RefAttributes<HTMLDivElement>>;
+export declare const ComboboxStatus: React.ForwardRefExoticComponent<Omit<ComboboxStatusProps, "ref"> & React.RefAttributes<HTMLDivElement>>;
 export interface ComboboxStatusState {}
 export interface ComboboxStatusProps extends BaseUIComponentProps<'div', ComboboxStatus.State> {}
 export declare namespace ComboboxStatus {

package/combobox/store.d.ts

@@ -43,16 +43,16 @@ export type State = {
   setInputValue: (value: string, eventDetails: AriaCombobox.ChangeEventDetails) => void;
   setSelectedValue: (value: any, eventDetails: AriaCombobox.ChangeEventDetails) => void;
   setIndices: (indices: {
-    activeIndex?: number | null;
-    selectedIndex?: number | null;
-    type?: 'keyboard' | 'pointer' | 'none';
+    activeIndex?: (number | null) | undefined;
+    selectedIndex?: (number | null) | undefined;
+    type?: ('keyboard' | 'pointer' | 'none') | undefined;
   }) => void;
   onItemHighlighted: (item: any, eventDetails: AriaCombobox.HighlightEventDetails) => void;
   forceMount: () => void;
   handleSelection: (event: MouseEvent | PointerEvent | KeyboardEvent, passedValue?: any) => void;
   getItemProps: (props?: HTMLProps & {
-    active?: boolean;
-    selected?: boolean;
+    active?: boolean | undefined;
+    selected?: boolean | undefined;
   }) => Record<string, unknown>;
   requestSubmit: () => void;
   name: string | undefined;
@@ -64,8 +64,8 @@ export type State = {
   virtualized: boolean;
   onOpenChangeComplete: (open: boolean) => void;
   openOnInputClick: boolean;
-  itemToStringLabel?: (item: any) => string;
-  isItemEqualToValue: (item: any, value: any) => boolean;
+  itemToStringLabel?: ((item: any) => string) | undefined;
+  isItemEqualToValue: (itemValue: any, selectedValue: any) => boolean;
   modal: boolean;
   autoHighlight: false | 'always' | 'input-change';
   submitOnItemClick: boolean;
@@ -77,6 +77,9 @@ export declare const selectors: {
   query: (state: State) => string;
   items: (state: State) => readonly any[] | undefined;
   selectedValue: (state: State) => any;
+  hasSelectionChips: (state: State) => boolean;
+  hasSelectedValue: (state: State) => boolean;
+  hasNullItemLabel: (state: State, enabled: boolean) => boolean;
   open: (state: State) => boolean;
   mounted: (state: State) => boolean;
   forceMounted: (state: State) => boolean;
@@ -84,14 +87,14 @@ export declare const selectors: {
   activeIndex: (state: State) => number | null;
   selectedIndex: (state: State) => number | null;
   isActive: (state: State, index: number) => boolean;
-  isSelected: (state: State, candidate: any) => boolean;
+  isSelected: (state: State, itemValue: any) => boolean;
   transitionStatus: (state: State) => TransitionStatus;
   popupProps: (state: State) => HTMLProps;
   inputProps: (state: State) => HTMLProps;
   triggerProps: (state: State) => HTMLProps;
   getItemProps: (state: State) => (props?: HTMLProps & {
-    active?: boolean;
-    selected?: boolean;
+    active?: boolean | undefined;
+    selected?: boolean | undefined;
   }) => Record<string, unknown>;
   positionerElement: (state: State) => HTMLElement | null;
   listElement: (state: State) => HTMLElement | null;
@@ -121,7 +124,7 @@ export declare const selectors: {
   onOpenChangeComplete: (state: State) => (open: boolean) => void;
   openOnInputClick: (state: State) => boolean;
   itemToStringLabel: (state: State) => ((item: any) => string) | undefined;
-  isItemEqualToValue: (state: State) => (item: any, value: any) => boolean;
+  isItemEqualToValue: (state: State) => (itemValue: any, selectedValue: any) => boolean;
   modal: (state: State) => boolean;
   autoHighlight: (state: State) => false | "always" | "input-change";
   submitOnItemClick: (state: State) => boolean;

package/combobox/store.js

@@ -6,11 +6,32 @@ Object.defineProperty(exports, "__esModule", {
 exports.selectors = void 0;
 var _store = require("@base-ui/utils/store");
 var _itemEquality = require("../utils/itemEquality");
+var _resolveValueLabel = require("../utils/resolveValueLabel");
 const selectors = exports.selectors = {
   id: (0, _store.createSelector)(state => state.id),
   query: (0, _store.createSelector)(state => state.query),
   items: (0, _store.createSelector)(state => state.items),
   selectedValue: (0, _store.createSelector)(state => state.selectedValue),
+  hasSelectionChips: (0, _store.createSelector)(state => {
+    const selectedValue = state.selectedValue;
+    return Array.isArray(selectedValue) && selectedValue.length > 0;
+  }),
+  hasSelectedValue: (0, _store.createSelector)(state => {
+    const {
+      selectedValue,
+      selectionMode
+    } = state;
+    if (selectedValue == null) {
+      return false;
+    }
+    if (selectionMode === 'multiple' && Array.isArray(selectedValue)) {
+      return selectedValue.length > 0;
+    }
+    return true;
+  }),
+  hasNullItemLabel: (0, _store.createSelector)((state, enabled) => {
+    return enabled ? (0, _resolveValueLabel.hasNullItemLabel)(state.items) : false;
+  }),
   open: (0, _store.createSelector)(state => state.open),
   mounted: (0, _store.createSelector)(state => state.mounted),
   forceMounted: (0, _store.createSelector)(state => state.forceMounted),
@@ -18,13 +39,13 @@ const selectors = exports.selectors = {
   activeIndex: (0, _store.createSelector)(state => state.activeIndex),
   selectedIndex: (0, _store.createSelector)(state => state.selectedIndex),
   isActive: (0, _store.createSelector)((state, index) => state.activeIndex === index),
-  isSelected: (0, _store.createSelector)((state, candidate) => {
+  isSelected: (0, _store.createSelector)((state, itemValue) => {
     const comparer = state.isItemEqualToValue;
     const selectedValue = state.selectedValue;
     if (Array.isArray(selectedValue)) {
-      return selectedValue.some(value => (0, _itemEquality.compareItemEquality)(value, candidate, comparer));
+      return selectedValue.some(selectedItem => (0, _itemEquality.compareItemEquality)(itemValue, selectedItem, comparer));
     }
-    return (0, _itemEquality.compareItemEquality)(selectedValue, candidate, comparer);
+    return (0, _itemEquality.compareItemEquality)(itemValue, selectedValue, comparer);
   }),
   transitionStatus: (0, _store.createSelector)(state => state.transitionStatus),
   popupProps: (0, _store.createSelector)(state => state.popupProps),

package/combobox/trigger/ComboboxTrigger.d.ts

@@ -1,11 +1,12 @@
 import * as React from 'react';
 import { BaseUIComponentProps, NativeButtonProps } from "../../utils/types.js";
 import type { FieldRoot } from "../../field/root/FieldRoot.js";
+import type { Side } from "../../utils/useAnchorPositioning.js";
 /**
  * A button that opens the popup.
  * Renders a `<button>` element.
  */
-export declare const ComboboxTrigger: React.ForwardRefExoticComponent<ComboboxTriggerProps & React.RefAttributes<HTMLButtonElement>>;
+export declare const ComboboxTrigger: React.ForwardRefExoticComponent<Omit<ComboboxTriggerProps, "ref"> & React.RefAttributes<HTMLButtonElement>>;
 export interface ComboboxTriggerState extends FieldRoot.State {
   /**
    * Whether the popup is open.
@@ -15,13 +16,25 @@ export interface ComboboxTriggerState extends FieldRoot.State {
    * Whether the component should ignore user interaction.
    */
   disabled: boolean;
+  /**
+   * Indicates which side the corresponding popup is positioned relative to its anchor.
+   */
+  popupSide: Side | null;
+  /**
+   * Present when the corresponding items list is empty.
+   */
+  listEmpty: boolean;
+  /**
+   * Whether the combobox doesn't have a value.
+   */
+  placeholder: boolean;
 }
 export interface ComboboxTriggerProps extends NativeButtonProps, BaseUIComponentProps<'button', ComboboxTrigger.State> {
   /**
    * Whether the component should ignore user interaction.
    * @default false
    */
-  disabled?: boolean;
+  disabled?: boolean | undefined;
 }
 export declare namespace ComboboxTrigger {
   type State = ComboboxTriggerState;

package/combobox/trigger/ComboboxTrigger.js

@@ -14,21 +14,17 @@ var _owner = require("@base-ui/utils/owner");
 var _useRenderElement = require("../../utils/useRenderElement");
 var _useButton = require("../../use-button");
 var _ComboboxRootContext = require("../root/ComboboxRootContext");
+var _stateAttributesMapping = require("../utils/stateAttributesMapping");
 var _store2 = require("../store");
 var _FieldRootContext = require("../../field/root/FieldRootContext");
 var _LabelableContext = require("../../labelable-provider/LabelableContext");
-var _popupStateMapping = require("../../utils/popupStateMapping");
 var _utils = require("../../floating-ui-react/utils");
 var _getPseudoElementBounds = require("../../utils/getPseudoElementBounds");
 var _createBaseUIEventDetails = require("../../utils/createBaseUIEventDetails");
 var _reasons = require("../../utils/reasons");
-var _constants = require("../../field/utils/constants");
 var _floatingUiReact = require("../../floating-ui-react");
+var _useLabelableId = require("../../labelable-provider/useLabelableId");
 const BOUNDARY_OFFSET = 2;
-const stateAttributesMapping = {
-  ..._popupStateMapping.pressableTriggerOpenStateMapping,
-  ..._constants.fieldValidityMapping
-};
 
 /**
  * A button that opens the popup.
@@ -40,6 +36,7 @@ const ComboboxTrigger = exports.ComboboxTrigger = /*#__PURE__*/React.forwardRef(
     className,
     nativeButton = true,
     disabled: disabledProp = false,
+    id: idProp,
     ...elementProps
   } = componentProps;
   const {
@@ -54,26 +51,41 @@ const ComboboxTrigger = exports.ComboboxTrigger = /*#__PURE__*/React.forwardRef(
     labelId
   } = (0, _LabelableContext.useLabelableContext)();
   const store = (0, _ComboboxRootContext.useComboboxRootContext)();
+  const {
+    filteredItems
+  } = (0, _ComboboxRootContext.useComboboxDerivedItemsContext)();
   const selectionMode = (0, _store.useStore)(store, _store2.selectors.selectionMode);
   const comboboxDisabled = (0, _store.useStore)(store, _store2.selectors.disabled);
   const readOnly = (0, _store.useStore)(store, _store2.selectors.readOnly);
+  const required = (0, _store.useStore)(store, _store2.selectors.required);
+  const mounted = (0, _store.useStore)(store, _store2.selectors.mounted);
+  const popupSideValue = (0, _store.useStore)(store, _store2.selectors.popupSide);
+  const positionerElement = (0, _store.useStore)(store, _store2.selectors.positionerElement);
   const listElement = (0, _store.useStore)(store, _store2.selectors.listElement);
   const triggerProps = (0, _store.useStore)(store, _store2.selectors.triggerProps);
   const triggerElement = (0, _store.useStore)(store, _store2.selectors.triggerElement);
   const inputInsidePopup = (0, _store.useStore)(store, _store2.selectors.inputInsidePopup);
+  const rootId = (0, _store.useStore)(store, _store2.selectors.id);
   const open = (0, _store.useStore)(store, _store2.selectors.open);
   const selectedValue = (0, _store.useStore)(store, _store2.selectors.selectedValue);
   const activeIndex = (0, _store.useStore)(store, _store2.selectors.activeIndex);
   const selectedIndex = (0, _store.useStore)(store, _store2.selectors.selectedIndex);
+  const hasSelectedValue = (0, _store.useStore)(store, _store2.selectors.hasSelectedValue);
   const floatingRootContext = (0, _ComboboxRootContext.useComboboxFloatingContext)();
   const inputValue = (0, _ComboboxRootContext.useComboboxInputValueContext)();
   const focusTimeout = (0, _useTimeout.useTimeout)();
   const disabled = fieldDisabled || comboboxDisabled || disabledProp;
+  const listEmpty = filteredItems.length === 0;
+  const popupSide = mounted && positionerElement ? popupSideValue : null;
+  (0, _useLabelableId.useLabelableId)({
+    id: inputInsidePopup ? idProp : undefined
+  });
+  const id = inputInsidePopup ? idProp ?? rootId : idProp;
   const currentPointerTypeRef = React.useRef('');
   function trackPointerType(event) {
     currentPointerTypeRef.current = event.pointerType;
   }
-  const domReference = floatingRootContext.select('domReferenceElement');
+  const domReference = floatingRootContext.useState('domReferenceElement');
 
   // Update the floating root context to use the trigger element when it differs from the current reference.
   // This ensures useClick and useTypeahead attach handlers to the correct element.
@@ -112,11 +124,14 @@ const ComboboxTrigger = exports.ComboboxTrigger = /*#__PURE__*/React.forwardRef(
     native: nativeButton,
     disabled
   });
-  const state = React.useMemo(() => ({
+  const state = {
     ...fieldState,
     open,
-    disabled
-  }), [fieldState, open, disabled]);
+    disabled,
+    popupSide,
+    listEmpty,
+    placeholder: !hasSelectedValue
+  };
   const setTriggerElement = (0, _useStableCallback.useStableCallback)(element => {
     store.set('triggerElement', element);
   });
@@ -124,13 +139,13 @@ const ComboboxTrigger = exports.ComboboxTrigger = /*#__PURE__*/React.forwardRef(
     ref: [forwardedRef, buttonRef, setTriggerElement],
     state,
     props: [triggerProps, triggerClickProps, triggerTypeaheadProps, {
+      id,
       tabIndex: inputInsidePopup ? 0 : -1,
-      disabled,
       role: inputInsidePopup ? 'combobox' : undefined,
       'aria-expanded': open ? 'true' : 'false',
       'aria-haspopup': inputInsidePopup ? 'dialog' : 'listbox',
       'aria-controls': open ? listElement?.id : undefined,
-      'aria-readonly': readOnly || undefined,
+      'aria-required': inputInsidePopup ? required || undefined : undefined,
       'aria-labelledby': labelId,
       onPointerDown: trackPointerType,
       onPointerEnter: trackPointerType,
@@ -141,7 +156,11 @@ const ComboboxTrigger = exports.ComboboxTrigger = /*#__PURE__*/React.forwardRef(
         }
         focusTimeout.start(0, store.state.forceMount);
       },
-      onBlur() {
+      onBlur(event) {
+        // If focus is moving into the popup, don't count it as a blur.
+        if ((0, _utils.contains)(positionerElement, event.relatedTarget)) {
+          return;
+        }
         setTouched(true);
         setFocused(false);
         if (validationMode === 'onBlur') {
@@ -204,7 +223,7 @@ const ComboboxTrigger = exports.ComboboxTrigger = /*#__PURE__*/React.forwardRef(
         }
       }
     }, validation ? validation.getValidationProps(elementProps) : elementProps, getButtonProps],
-    stateAttributesMapping
+    stateAttributesMapping: _stateAttributesMapping.triggerStateAttributesMapping
   });
   return element;
 });

package/combobox/trigger/ComboboxTriggerDataAttributes.d.ts

@@ -15,6 +15,11 @@ export declare enum ComboboxTriggerDataAttributes {
    * Present when the component is readonly.
    */
   readonly = "data-readonly",
+  /**
+   * Indicates which side the corresponding popup is positioned relative to its anchor.
+   * @type {'top' | 'bottom' | 'left' | 'right' | 'inline-end' | 'inline-start' | null}
+   */
+  popupSide = "data-popup-side",
   /**
    * Present when the component is required.
    */
@@ -43,4 +48,12 @@ export declare enum ComboboxTriggerDataAttributes {
    * Present when the trigger is focused (when wrapped in Field.Root).
    */
   focused = "data-focused",
+  /**
+   * Present when the corresponding items list is empty.
+   */
+  listEmpty = "data-list-empty",
+  /**
+   * Present when the combobox doesn't have a value.
+   */
+  placeholder = "data-placeholder",
 }

package/combobox/trigger/ComboboxTriggerDataAttributes.js

@@ -22,6 +22,11 @@ let ComboboxTriggerDataAttributes = exports.ComboboxTriggerDataAttributes = func
    * Present when the component is readonly.
    */
   ComboboxTriggerDataAttributes["readonly"] = "data-readonly";
+  /**
+   * Indicates which side the corresponding popup is positioned relative to its anchor.
+   * @type {'top' | 'bottom' | 'left' | 'right' | 'inline-end' | 'inline-start' | null}
+   */
+  ComboboxTriggerDataAttributes["popupSide"] = "data-popup-side";
   /**
    * Present when the component is required.
    */
@@ -50,5 +55,13 @@ let ComboboxTriggerDataAttributes = exports.ComboboxTriggerDataAttributes = func
    * Present when the trigger is focused (when wrapped in Field.Root).
    */
   ComboboxTriggerDataAttributes["focused"] = "data-focused";
+  /**
+   * Present when the corresponding items list is empty.
+   */
+  ComboboxTriggerDataAttributes["listEmpty"] = "data-list-empty";
+  /**
+   * Present when the combobox doesn't have a value.
+   */
+  ComboboxTriggerDataAttributes["placeholder"] = "data-placeholder";
   return ComboboxTriggerDataAttributes;
 }({});

package/combobox/utils/stateAttributesMapping.d.ts

@@ -0,0 +1,14 @@
+import type { Side } from "../../utils/useAnchorPositioning.js";
+export declare const triggerStateAttributesMapping: {
+  popupSide: (side: Side | null) => {
+    'data-popup-side': Side;
+  } | null;
+  listEmpty: (empty: boolean) => {
+    'data-list-empty': string;
+  } | null;
+  valid(value: boolean | null): Record<string, string> | null;
+  open(value: boolean): {
+    "data-popup-open": string;
+    "data-pressed": string;
+  } | null;
+};

package/combobox/utils/stateAttributesMapping.js

@@ -0,0 +1,18 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.triggerStateAttributesMapping = void 0;
+var _popupStateMapping = require("../../utils/popupStateMapping");
+var _constants = require("../../field/utils/constants");
+const triggerStateAttributesMapping = exports.triggerStateAttributesMapping = {
+  ..._popupStateMapping.pressableTriggerOpenStateMapping,
+  ..._constants.fieldValidityMapping,
+  popupSide: side => side ? {
+    'data-popup-side': side
+  } : null,
+  listEmpty: empty => empty ? {
+    'data-list-empty': ''
+  } : null
+};

package/combobox/value/ComboboxValue.d.ts

@@ -9,6 +9,11 @@ export declare function ComboboxValue(props: ComboboxValue.Props): React.ReactEl
 export interface ComboboxValueState {}
 export interface ComboboxValueProps {
   children?: React.ReactNode | ((selectedValue: any) => React.ReactNode);
+  /**
+   * The placeholder value to display when no value is selected.
+   * This is overridden by `children` if specified, or by a null item's label in `items`.
+   */
+  placeholder?: React.ReactNode;
 }
 export declare namespace ComboboxValue {
   type State = ComboboxValueState;

package/combobox/value/ComboboxValue.js

@@ -20,21 +20,30 @@ var _jsxRuntime = require("react/jsx-runtime");
  */
 function ComboboxValue(props) {
   const {
-    children: childrenProp
+    children: childrenProp,
+    placeholder
   } = props;
   const store = (0, _ComboboxRootContext.useComboboxRootContext)();
   const itemToStringLabel = (0, _store.useStore)(store, _store2.selectors.itemToStringLabel);
   const selectedValue = (0, _store.useStore)(store, _store2.selectors.selectedValue);
   const items = (0, _store.useStore)(store, _store2.selectors.items);
-  let returnValue = null;
+  const multiple = (0, _store.useStore)(store, _store2.selectors.selectionMode) === 'multiple';
+  const hasSelectedValue = (0, _store.useStore)(store, _store2.selectors.hasSelectedValue);
+  const shouldCheckNullItemLabel = !hasSelectedValue && placeholder != null && childrenProp == null;
+  const hasNullLabel = (0, _store.useStore)(store, _store2.selectors.hasNullItemLabel, shouldCheckNullItemLabel);
+  let children = null;
   if (typeof childrenProp === 'function') {
-    returnValue = childrenProp(selectedValue);
+    children = childrenProp(selectedValue);
   } else if (childrenProp != null) {
-    returnValue = childrenProp;
+    children = childrenProp;
+  } else if (!hasSelectedValue && placeholder != null && !hasNullLabel) {
+    children = placeholder;
+  } else if (multiple && Array.isArray(selectedValue)) {
+    children = (0, _resolveValueLabel.resolveMultipleLabels)(selectedValue, items, itemToStringLabel);
   } else {
-    returnValue = (0, _resolveValueLabel.resolveSelectedLabel)(selectedValue, items, itemToStringLabel);
+    children = (0, _resolveValueLabel.resolveSelectedLabel)(selectedValue, items, itemToStringLabel);
   }
   return /*#__PURE__*/(0, _jsxRuntime.jsx)(React.Fragment, {
-    children: returnValue
+    children: children
   });
 }

package/composite/item/CompositeItem.d.ts

@@ -7,12 +7,12 @@ import { StateAttributesMapping } from "../../utils/getStateAttributesProps.js";
 export declare function CompositeItem<Metadata, State extends Record<string, any>>(componentProps: CompositeItem.Props<Metadata, State>): React.ReactElement<unknown, string | React.JSXElementConstructor<any>>;
 export interface CompositeItemProps<Metadata, State extends Record<string, any>> extends Pick<BaseUIComponentProps<any, State>, 'render' | 'className'> {
   children?: React.ReactNode;
-  metadata?: Metadata;
-  refs?: React.Ref<HTMLElement | null>[];
-  props?: Array<Record<string, any> | (() => Record<string, any>)>;
-  state?: State;
-  stateAttributesMapping?: StateAttributesMapping<State>;
-  tag?: keyof React.JSX.IntrinsicElements;
+  metadata?: Metadata | undefined;
+  refs?: React.Ref<HTMLElement | null>[] | undefined;
+  props?: Array<Record<string, any> | (() => Record<string, any>)> | undefined;
+  state?: State | undefined;
+  stateAttributesMapping?: StateAttributesMapping<State> | undefined;
+  tag?: keyof React.JSX.IntrinsicElements | undefined;
 }
 export declare namespace CompositeItem {
   type Props<Metadata, State extends Record<string, any>> = CompositeItemProps<Metadata, State>;