@base-ui/react 1.2.0 → 1.4.0

package/esm/combobox/input-group/ComboboxInputGroup.d.ts

@@ -0,0 +1,42 @@
+import * as React from 'react';
+import type { BaseUIComponentProps } from "../../utils/types.js";
+import type { FieldRoot } from "../../field/root/FieldRoot.js";
+import type { Side } from "../../utils/useAnchorPositioning.js";
+/**
+ * A wrapper for the input and its associated controls.
+ * Renders a `<div>` element.
+ *
+ * Documentation: [Base UI Combobox](https://base-ui.com/react/components/combobox)
+ */
+export declare const ComboboxInputGroup: React.ForwardRefExoticComponent<Omit<ComboboxInputGroupProps, "ref"> & React.RefAttributes<HTMLDivElement>>;
+export interface ComboboxInputGroupState extends FieldRoot.State {
+  /**
+   * Whether the corresponding popup is open.
+   */
+  open: boolean;
+  /**
+   * 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.
+   */
+  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 ComboboxInputGroupProps extends BaseUIComponentProps<'div', ComboboxInputGroup.State> {}
+export declare namespace ComboboxInputGroup {
+  type State = ComboboxInputGroupState;
+  type Props = ComboboxInputGroupProps;
+}

package/esm/combobox/input-group/ComboboxInputGroup.js

@@ -0,0 +1,72 @@
+'use client';
+
+import * as React from 'react';
+import { useStableCallback } from '@base-ui/utils/useStableCallback';
+import { useStore } from '@base-ui/utils/store';
+import { useRenderElement } from "../../utils/useRenderElement.js";
+import { useFieldRootContext } from "../../field/root/FieldRootContext.js";
+import { useComboboxDerivedItemsContext, useComboboxRootContext } from "../root/ComboboxRootContext.js";
+import { selectors } from "../store.js";
+import { triggerStateAttributesMapping } from "../utils/stateAttributesMapping.js";
+import { handleInputPress } from "../utils/handleInputPress.js";
+import { contains } from "../../floating-ui-react/utils/element.js";
+
+/**
+ * A wrapper for the input and its associated controls.
+ * Renders a `<div>` element.
+ *
+ * Documentation: [Base UI Combobox](https://base-ui.com/react/components/combobox)
+ */
+export const ComboboxInputGroup = /*#__PURE__*/React.forwardRef(function ComboboxInputGroup(componentProps, forwardedRef) {
+  const {
+    render,
+    className,
+    style,
+    ...elementProps
+  } = componentProps;
+  const {
+    state: fieldState
+  } = useFieldRootContext();
+  const store = useComboboxRootContext();
+  const {
+    filteredItems
+  } = useComboboxDerivedItemsContext();
+  const open = useStore(store, selectors.open);
+  const mounted = useStore(store, selectors.mounted);
+  const popupSideValue = useStore(store, selectors.popupSide);
+  const positionerElement = useStore(store, selectors.positionerElement);
+  const comboboxDisabled = useStore(store, selectors.disabled);
+  const readOnly = useStore(store, selectors.readOnly);
+  const hasSelectedValue = useStore(store, selectors.hasSelectedValue);
+  const selectionMode = useStore(store, selectors.selectionMode);
+  const popupSide = mounted && positionerElement ? popupSideValue : null;
+  const disabled = comboboxDisabled;
+  const listEmpty = filteredItems.length === 0;
+  const placeholder = selectionMode === 'none' ? false : !hasSelectedValue;
+  const state = {
+    ...fieldState,
+    open,
+    disabled,
+    readOnly,
+    popupSide,
+    listEmpty,
+    placeholder
+  };
+  const setInputGroupElement = useStableCallback(element => {
+    store.set('inputGroupElement', element);
+  });
+  return useRenderElement('div', componentProps, {
+    ref: [forwardedRef, setInputGroupElement],
+    props: [{
+      role: 'group',
+      onMouseDown(event) {
+        handleInputPress(event, store, disabled, readOnly, target => {
+          return contains(store.state.chipsContainerRef.current, target);
+        });
+      }
+    }, elementProps],
+    state,
+    stateAttributesMapping: triggerStateAttributesMapping
+  });
+});
+if (process.env.NODE_ENV !== "production") ComboboxInputGroup.displayName = "ComboboxInputGroup";

package/esm/combobox/input-group/ComboboxInputGroupDataAttributes.d.ts

@@ -0,0 +1,55 @@
+export declare enum ComboboxInputGroupDataAttributes {
+  /**
+   * Present when the corresponding popup is open.
+   */
+  popupOpen = "data-popup-open",
+  /**
+   * Present when the input group is pressed.
+   */
+  pressed = "data-pressed",
+  /**
+   * Present when the component is disabled.
+   */
+  disabled = "data-disabled",
+  /**
+   * 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 in valid state (when wrapped in Field.Root).
+   */
+  valid = "data-valid",
+  /**
+   * Present when the component is in invalid state (when wrapped in Field.Root).
+   */
+  invalid = "data-invalid",
+  /**
+   * Present when the component has been touched (when wrapped in Field.Root).
+   */
+  touched = "data-touched",
+  /**
+   * Present when the component's value has changed (when wrapped in Field.Root).
+   */
+  dirty = "data-dirty",
+  /**
+   * Present when the component has a value (when wrapped in Field.Root).
+   */
+  filled = "data-filled",
+  /**
+   * Present when the component 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/esm/combobox/input-group/ComboboxInputGroupDataAttributes.js

@@ -0,0 +1,56 @@
+export let ComboboxInputGroupDataAttributes = /*#__PURE__*/function (ComboboxInputGroupDataAttributes) {
+  /**
+   * Present when the corresponding popup is open.
+   */
+  ComboboxInputGroupDataAttributes["popupOpen"] = "data-popup-open";
+  /**
+   * Present when the input group is pressed.
+   */
+  ComboboxInputGroupDataAttributes["pressed"] = "data-pressed";
+  /**
+   * Present when the component is disabled.
+   */
+  ComboboxInputGroupDataAttributes["disabled"] = "data-disabled";
+  /**
+   * Present when the component is readonly.
+   */
+  ComboboxInputGroupDataAttributes["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}
+   */
+  ComboboxInputGroupDataAttributes["popupSide"] = "data-popup-side";
+  /**
+   * Present when the component is in valid state (when wrapped in Field.Root).
+   */
+  ComboboxInputGroupDataAttributes["valid"] = "data-valid";
+  /**
+   * Present when the component is in invalid state (when wrapped in Field.Root).
+   */
+  ComboboxInputGroupDataAttributes["invalid"] = "data-invalid";
+  /**
+   * Present when the component has been touched (when wrapped in Field.Root).
+   */
+  ComboboxInputGroupDataAttributes["touched"] = "data-touched";
+  /**
+   * Present when the component's value has changed (when wrapped in Field.Root).
+   */
+  ComboboxInputGroupDataAttributes["dirty"] = "data-dirty";
+  /**
+   * Present when the component has a value (when wrapped in Field.Root).
+   */
+  ComboboxInputGroupDataAttributes["filled"] = "data-filled";
+  /**
+   * Present when the component is focused (when wrapped in Field.Root).
+   */
+  ComboboxInputGroupDataAttributes["focused"] = "data-focused";
+  /**
+   * Present when the corresponding items list is empty.
+   */
+  ComboboxInputGroupDataAttributes["listEmpty"] = "data-list-empty";
+  /**
+   * Present when the combobox doesn't have a value.
+   */
+  ComboboxInputGroupDataAttributes["placeholder"] = "data-placeholder";
+  return ComboboxInputGroupDataAttributes;
+}({});

package/esm/combobox/item/ComboboxItem.d.ts

@@ -3,6 +3,8 @@ import type { BaseUIComponentProps, NonNativeButtonProps } from "../../utils/typ
 /**
  * An individual item in the list.
  * Renders a `<div>` element.
+ *
+ * Documentation: [Base UI Combobox](https://base-ui.com/react/components/combobox)
  */
 export declare const ComboboxItem: React.NamedExoticComponent<Omit<ComboboxItemProps, "ref"> & React.RefAttributes<HTMLDivElement>>;
 export interface ComboboxItemState {
@@ -19,7 +21,7 @@ export interface ComboboxItemState {
    */
   highlighted: boolean;
 }
-export interface ComboboxItemProps extends NonNativeButtonProps, Omit<BaseUIComponentProps<'div', ComboboxItem.State>, 'id'> {
+export interface ComboboxItemProps extends NonNativeButtonProps, Omit<BaseUIComponentProps<'div', ComboboxItemState>, 'id'> {
   children?: React.ReactNode;
   /**
    * An optional click handler for the item when selected.

package/esm/combobox/item/ComboboxItem.js

@@ -16,6 +16,8 @@ import { compareItemEquality, findItemIndex } from "../../utils/itemEquality.js"
 /**
  * An individual item in the list.
  * 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 ComboboxItem = /*#__PURE__*/React.memo(/*#__PURE__*/React.forwardRef(function ComboboxItem(componentProps, forwardedRef) {
@@ -26,6 +28,7 @@ export const ComboboxItem = /*#__PURE__*/React.memo(/*#__PURE__*/React.forwardRe
     index: indexProp,
     disabled = false,
     nativeButton = false,
+    style,
     ...elementProps
   } = componentProps;
   const didPointerDownRef = React.useRef(false);
@@ -115,7 +118,8 @@ export const ComboboxItem = /*#__PURE__*/React.memo(/*#__PURE__*/React.forwardRe
   } = useButton({
     disabled,
     focusableWhenDisabled: true,
-    native: nativeButton
+    native: nativeButton,
+    composite: true
   });
   function commitSelection(nativeEvent) {
     function selectItem() {
@@ -140,6 +144,11 @@ export const ComboboxItem = /*#__PURE__*/React.memo(/*#__PURE__*/React.forwardRe
       didPointerDownRef.current = true;
       event.preventDefault();
     },
+    onMouseDown(event) {
+      // iOS Safari can emit a synthetic mousedown for touch taps without a preceding
+      // pointerdown. Prevent default here too so tapping an item does not blur the input.
+      event.preventDefault();
+    },
     onClick(event) {
       if (disabled || readOnly) {
         return;

package/esm/combobox/item-indicator/ComboboxItemIndicator.d.ts

@@ -4,9 +4,11 @@ import { type TransitionStatus } from "../../utils/useTransitionStatus.js";
 /**
  * Indicates whether the item is selected.
  * Renders a `<span>` element.
+ *
+ * Documentation: [Base UI Combobox](https://base-ui.com/react/components/combobox)
  */
 export declare const ComboboxItemIndicator: React.ForwardRefExoticComponent<Omit<ComboboxItemIndicatorProps, "ref"> & React.RefAttributes<HTMLSpanElement>>;
-export interface ComboboxItemIndicatorProps extends BaseUIComponentProps<'span', ComboboxItemIndicator.State> {
+export interface ComboboxItemIndicatorProps extends BaseUIComponentProps<'span', ComboboxItemIndicatorState> {
   children?: React.ReactNode;
   /**
    * Whether to keep the HTML element in the DOM when the item is not selected.
@@ -15,7 +17,13 @@ export interface ComboboxItemIndicatorProps extends BaseUIComponentProps<'span',
   keepMounted?: boolean | undefined;
 }
 export interface ComboboxItemIndicatorState {
+  /**
+   * Whether the item is selected.
+   */
   selected: boolean;
+  /**
+   * The transition status of the component.
+   */
   transitionStatus: TransitionStatus;
 }
 export declare namespace ComboboxItemIndicator {

package/esm/combobox/item-indicator/ComboboxItemIndicator.js

@@ -10,6 +10,8 @@ import { transitionStatusMapping } from "../../utils/stateAttributesMapping.js";
 /**
  * Indicates whether the item is selected.
  * Renders a `<span>` element.
+ *
+ * Documentation: [Base UI Combobox](https://base-ui.com/react/components/combobox)
  */
 import { jsx as _jsx } from "react/jsx-runtime";
 export const ComboboxItemIndicator = /*#__PURE__*/React.forwardRef(function ComboboxItemIndicator(componentProps, forwardedRef) {
@@ -36,6 +38,7 @@ const Inner = /*#__PURE__*/React.memo(/*#__PURE__*/React.forwardRef((componentPr
   const {
     render,
     className,
+    style,
     keepMounted,
     ...elementProps
   } = componentProps;

package/esm/combobox/item-indicator/ComboboxItemIndicatorDataAttributes.d.ts

@@ -0,0 +1,10 @@
+export declare enum ComboboxItemIndicatorDataAttributes {
+  /**
+   * Present when the indicator is animating in.
+   */
+  startingStyle = "data-starting-style",
+  /**
+   * Present when the indicator is animating out.
+   */
+  endingStyle = "data-ending-style",
+}

package/esm/combobox/item-indicator/ComboboxItemIndicatorDataAttributes.js

@@ -0,0 +1,12 @@
+import { TransitionStatusDataAttributes } from "../../utils/stateAttributesMapping.js";
+export let ComboboxItemIndicatorDataAttributes = function (ComboboxItemIndicatorDataAttributes) {
+  /**
+   * Present when the indicator is animating in.
+   */
+  ComboboxItemIndicatorDataAttributes[ComboboxItemIndicatorDataAttributes["startingStyle"] = TransitionStatusDataAttributes.startingStyle] = "startingStyle";
+  /**
+   * Present when the indicator is animating out.
+   */
+  ComboboxItemIndicatorDataAttributes[ComboboxItemIndicatorDataAttributes["endingStyle"] = TransitionStatusDataAttributes.endingStyle] = "endingStyle";
+  return ComboboxItemIndicatorDataAttributes;
+}({});

package/esm/combobox/label/ComboboxLabel.d.ts

@@ -0,0 +1,16 @@
+import * as React from 'react';
+import type { BaseUIComponentProps } from "../../utils/types.js";
+import type { FieldRoot } from "../../field/root/FieldRoot.js";
+/**
+ * An accessible label that is automatically associated with the combobox trigger.
+ * Renders a `<div>` element.
+ *
+ * Documentation: [Base UI Combobox](https://base-ui.com/react/components/combobox)
+ */
+export declare const ComboboxLabel: React.ForwardRefExoticComponent<Omit<ComboboxLabelProps, "ref"> & React.RefAttributes<HTMLDivElement>>;
+export type ComboboxLabelState = FieldRoot.State;
+export interface ComboboxLabelProps extends Omit<BaseUIComponentProps<'div', ComboboxLabel.State>, 'id'> {}
+export declare namespace ComboboxLabel {
+  type State = ComboboxLabelState;
+  type Props = ComboboxLabelProps;
+}

package/esm/combobox/label/ComboboxLabel.js

@@ -0,0 +1,64 @@
+'use client';
+
+import * as React from 'react';
+import { error } from '@base-ui/utils/error';
+import { SafeReact } from '@base-ui/utils/safeReact';
+import { useStore } from '@base-ui/utils/store';
+import { useRenderElement } from "../../utils/useRenderElement.js";
+import { useFieldRootContext } from "../../field/root/FieldRootContext.js";
+import { fieldValidityMapping } from "../../field/utils/constants.js";
+import { useLabel } from "../../labelable-provider/useLabel.js";
+import { getDefaultLabelId } from "../../utils/resolveAriaLabelledBy.js";
+import { useComboboxRootContext } from "../root/ComboboxRootContext.js";
+import { selectors } from "../store.js";
+
+/**
+ * An accessible label that is automatically associated with the combobox trigger.
+ * Renders a `<div>` element.
+ *
+ * Documentation: [Base UI Combobox](https://base-ui.com/react/components/combobox)
+ */
+export const ComboboxLabel = /*#__PURE__*/React.forwardRef(function ComboboxLabel(componentProps, forwardedRef) {
+  const {
+    render,
+    className,
+    style,
+    ...elementProps
+  } = componentProps;
+  // Keep label id derived from the root and ignore runtime `id` overrides from untyped consumers.
+  const elementPropsWithoutId = elementProps;
+  delete elementPropsWithoutId.id;
+  const fieldRootContext = useFieldRootContext();
+  const store = useComboboxRootContext();
+  const inputInsidePopup = useStore(store, selectors.inputInsidePopup);
+  const triggerElement = useStore(store, selectors.triggerElement);
+  const inputElement = useStore(store, selectors.inputElement);
+  const rootId = useStore(store, selectors.id);
+  const defaultLabelId = getDefaultLabelId(rootId);
+  const localControlId = triggerElement?.id ?? (inputInsidePopup ? rootId : undefined);
+  if (process.env.NODE_ENV !== 'production') {
+    // eslint-disable-next-line react-hooks/rules-of-hooks
+    React.useEffect(() => {
+      if (!inputElement || inputInsidePopup) {
+        return;
+      }
+      const ownerStackMessage = SafeReact.captureOwnerStack?.() || '';
+      const message = '<Combobox.Label> labels <Combobox.Trigger> only. ' + 'When <Combobox.Input> is the form control, use a native <label> or <Field.Label> instead.';
+      error(`${message}${ownerStackMessage}`);
+    }, [inputElement, inputInsidePopup]);
+  }
+  const labelProps = useLabel({
+    id: defaultLabelId,
+    fallbackControlId: localControlId,
+    setLabelId(nextLabelId) {
+      store.set('labelId', nextLabelId);
+    }
+  });
+  return useRenderElement('div', componentProps, {
+    ref: forwardedRef,
+    state: fieldRootContext.state,
+    props: [labelProps, elementProps],
+    stateAttributesMapping: fieldValidityMapping
+  });
+});
+if (process.env.NODE_ENV !== "production") ComboboxLabel.displayName = "ComboboxLabel";

package/esm/combobox/list/ComboboxList.d.ts

@@ -3,6 +3,8 @@ import type { BaseUIComponentProps } from "../../utils/types.js";
 /**
  * A list container for the items.
  * Renders a `<div>` element.
+ *
+ * Documentation: [Base UI Combobox](https://base-ui.com/react/components/combobox)
  */
 export declare const ComboboxList: React.ForwardRefExoticComponent<Omit<ComboboxListProps, "ref"> & React.RefAttributes<HTMLDivElement>>;
 export interface ComboboxListState {
@@ -11,7 +13,7 @@ export interface ComboboxListState {
    */
   empty: boolean;
 }
-export interface ComboboxListProps extends Omit<BaseUIComponentProps<'div', ComboboxList.State>, 'children'> {
+export interface ComboboxListProps extends Omit<BaseUIComponentProps<'div', ComboboxListState>, 'children'> {
   children?: React.ReactNode | ((item: any, index: number) => React.ReactNode);
 }
 export declare namespace ComboboxList {

package/esm/combobox/list/ComboboxList.js

@@ -14,6 +14,8 @@ import { stopEvent } from "../../floating-ui-react/utils.js";
 /**
  * A list container for the items.
  * 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 ComboboxList = /*#__PURE__*/React.forwardRef(function ComboboxList(componentProps, forwardedRef) {
@@ -21,6 +23,7 @@ export const ComboboxList = /*#__PURE__*/React.forwardRef(function ComboboxList(
   const {
     render,
     className,
+    style,
     children,
     ...elementProps
   } = componentProps;
@@ -28,16 +31,12 @@ export const ComboboxList = /*#__PURE__*/React.forwardRef(function ComboboxList(
   const floatingRootContext = useComboboxFloatingContext();
   const hasPositionerContext = Boolean(useComboboxPositionerContext(true));
   const {
-    filteredItems
+    filteredItems,
+    hasItems
   } = useComboboxDerivedItemsContext();
-  const items = useStore(store, selectors.items);
-  const labelsRef = useStore(store, selectors.labelsRef);
-  const listRef = useStore(store, selectors.listRef);
   const selectionMode = useStore(store, selectors.selectionMode);
   const grid = useStore(store, selectors.grid);
   const popupProps = useStore(store, selectors.popupProps);
-  const disabled = useStore(store, selectors.disabled);
-  const readOnly = useStore(store, selectors.readOnly);
   const virtualized = useStore(store, selectors.virtualized);
   const multiple = selectionMode === 'multiple';
   const empty = filteredItems.length === 0;
@@ -74,7 +73,7 @@ export const ComboboxList = /*#__PURE__*/React.forwardRef(function ComboboxList(
       role: grid ? 'grid' : 'listbox',
       'aria-multiselectable': multiple ? 'true' : undefined,
       onKeyDown(event) {
-        if (disabled || readOnly) {
+        if (store.state.disabled || store.state.readOnly) {
           return;
         }
         if (event.key === 'Enter') {
@@ -105,8 +104,8 @@ export const ComboboxList = /*#__PURE__*/React.forwardRef(function ComboboxList(
     return element;
   }
   return /*#__PURE__*/_jsx(CompositeList, {
-    elementsRef: listRef,
-    labelsRef: items ? undefined : labelsRef,
+    elementsRef: store.state.listRef,
+    labelsRef: hasItems ? undefined : store.state.labelsRef,
     children: element
   });
 });

package/esm/combobox/popup/ComboboxPopup.d.ts

@@ -6,17 +6,37 @@ import type { TransitionStatus } from "../../utils/useTransitionStatus.js";
 /**
  * A container for the list.
  * Renders a `<div>` element.
+ *
+ * Documentation: [Base UI Combobox](https://base-ui.com/react/components/combobox)
  */
 export declare const ComboboxPopup: React.ForwardRefExoticComponent<Omit<ComboboxPopupProps, "ref"> & React.RefAttributes<HTMLDivElement>>;
 export interface ComboboxPopupState {
+  /**
+   * Whether the component is open.
+   */
   open: boolean;
+  /**
+   * The side of the anchor the component is placed on.
+   */
   side: Side;
+  /**
+   * The alignment of the component relative to the anchor.
+   */
   align: Align;
+  /**
+   * Whether the anchor element is hidden.
+   */
   anchorHidden: boolean;
+  /**
+   * The transition status of the component.
+   */
   transitionStatus: TransitionStatus;
+  /**
+   * Whether there are no items to display.
+   */
   empty: boolean;
 }
-export interface ComboboxPopupProps extends BaseUIComponentProps<'div', ComboboxPopup.State> {
+export interface ComboboxPopupProps extends BaseUIComponentProps<'div', ComboboxPopupState> {
   /**
    * Determines the element to focus when the popup is opened.
    *
@@ -26,7 +46,7 @@ export interface ComboboxPopupProps extends BaseUIComponentProps<'div', Combobox
    * - `function`: Called with the interaction type (`mouse`, `touch`, `pen`, or `keyboard`).
    *   Return an element to focus, `true` to use the default behavior, or `false`/`undefined` to do nothing.
    */
-  initialFocus?: (boolean | React.RefObject<HTMLElement | null> | ((openType: InteractionType) => void | boolean | HTMLElement | null)) | undefined;
+  initialFocus?: boolean | React.RefObject<HTMLElement | null> | ((openType: InteractionType) => void | boolean | HTMLElement | null) | undefined;
   /**
    * Determines the element to focus when the popup is closed.
    *
@@ -36,7 +56,7 @@ export interface ComboboxPopupProps extends BaseUIComponentProps<'div', Combobox
    * - `function`: Called with the interaction type (`mouse`, `touch`, `pen`, or `keyboard`).
    *   Return an element to focus, `true` to use the default behavior, or `false`/`undefined` to do nothing.
    */
-  finalFocus?: (boolean | React.RefObject<HTMLElement | null> | ((closeType: InteractionType) => void | boolean | HTMLElement | null)) | undefined;
+  finalFocus?: boolean | React.RefObject<HTMLElement | null> | ((closeType: InteractionType) => void | boolean | HTMLElement | null) | undefined;
 }
 export declare namespace ComboboxPopup {
   type State = ComboboxPopupState;

package/esm/combobox/popup/ComboboxPopup.js

@@ -12,7 +12,8 @@ import { useOpenChangeComplete } from "../../utils/useOpenChangeComplete.js";
 import { transitionStatusMapping } from "../../utils/stateAttributesMapping.js";
 import { contains, getTarget } from "../../floating-ui-react/utils.js";
 import { getDisabledMountTransitionStyles } from "../../utils/getDisabledMountTransitionStyles.js";
-import { jsx as _jsx } from "react/jsx-runtime";
+import { ComboboxInternalDismissButton } from "../utils/ComboboxInternalDismissButton.js";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 const stateAttributesMapping = {
   ...popupStateMapping,
   ...transitionStatusMapping
@@ -21,11 +22,14 @@ const stateAttributesMapping = {
 /**
  * A container for the list.
  * Renders a `<div>` element.
+ *
+ * Documentation: [Base UI Combobox](https://base-ui.com/react/components/combobox)
  */
 export const ComboboxPopup = /*#__PURE__*/React.forwardRef(function ComboboxPopup(componentProps, forwardedRef) {
   const {
     render,
     className,
+    style,
     initialFocus,
     finalFocus,
     ...elementProps
@@ -42,6 +46,7 @@ export const ComboboxPopup = /*#__PURE__*/React.forwardRef(function ComboboxPopu
   const transitionStatus = useStore(store, selectors.transitionStatus);
   const inputInsidePopup = useStore(store, selectors.inputInsidePopup);
   const inputElement = useStore(store, selectors.inputElement);
+  const modal = useStore(store, selectors.modal);
   const empty = filteredItems.length === 0;
   useOpenChangeComplete({
     open,
@@ -87,14 +92,20 @@ export const ComboboxPopup = /*#__PURE__*/React.forwardRef(function ComboboxPopu
   } else {
     resolvedFinalFocus = inputInsidePopup ? undefined : false;
   }
+  const focusManagerModal = !inputInsidePopup || modal;
   return /*#__PURE__*/_jsx(FloatingFocusManager, {
     context: floatingRootContext,
     disabled: !mounted,
-    modal: !inputInsidePopup,
+    modal: focusManagerModal,
     openInteractionType: openMethod,
     initialFocus: resolvedInitialFocus,
     returnFocus: resolvedFinalFocus,
-    children: element
+    getInsideElements: () => [store.state.startDismissRef.current, store.state.endDismissRef.current],
+    children: /*#__PURE__*/_jsxs(React.Fragment, {
+      children: [element, focusManagerModal && /*#__PURE__*/_jsx(ComboboxInternalDismissButton, {
+        ref: store.state.endDismissRef
+      })]
+    })
   });
 });
 if (process.env.NODE_ENV !== "production") ComboboxPopup.displayName = "ComboboxPopup";

package/esm/combobox/portal/ComboboxPortal.d.ts

@@ -4,12 +4,12 @@ import { FloatingPortal } from "../../floating-ui-react/index.js";
  * A portal element that moves the popup to a different part of the DOM.
  * By default, the portal element is appended to `<body>`.
  * Renders a `<div>` element.
+ *
+ * Documentation: [Base UI Combobox](https://base-ui.com/react/components/combobox)
  */
 export declare const ComboboxPortal: React.ForwardRefExoticComponent<Omit<ComboboxPortalProps, "ref"> & React.RefAttributes<HTMLDivElement>>;
-export declare namespace ComboboxPortal {
-  interface State {}
-}
-export interface ComboboxPortalProps extends FloatingPortal.Props<ComboboxPortal.State> {
+export interface ComboboxPortalState {}
+export interface ComboboxPortalProps extends FloatingPortal.Props<ComboboxPortalState> {
   /**
    * Whether to keep the portal mounted in the DOM while the popup is hidden.
    * @default false
@@ -17,5 +17,6 @@ export interface ComboboxPortalProps extends FloatingPortal.Props<ComboboxPortal
   keepMounted?: boolean | undefined;
 }
 export declare namespace ComboboxPortal {
+  type State = ComboboxPortalState;
   type Props = ComboboxPortalProps;
 }

package/esm/combobox/portal/ComboboxPortal.js

@@ -11,6 +11,8 @@ import { selectors } from "../store.js";
  * A portal element that moves the popup to a different part of the DOM.
  * By default, the portal element is appended to `<body>`.
  * 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 ComboboxPortal = /*#__PURE__*/React.forwardRef(function ComboboxPortal(props, forwardedRef) {