@base-ui/react 1.2.0 → 1.3.0

package/labelable-provider/useAriaLabelledBy.js

@@ -0,0 +1,61 @@
+"use strict";
+'use client';
+
+var _interopRequireWildcard = require("@babel/runtime/helpers/interopRequireWildcard").default;
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.useAriaLabelledBy = useAriaLabelledBy;
+var React = _interopRequireWildcard(require("react"));
+var _useIsoLayoutEffect = require("@base-ui/utils/useIsoLayoutEffect");
+var _useBaseUiId = require("../utils/useBaseUiId");
+/**
+ * @internal
+ */
+function useAriaLabelledBy(explicitAriaLabelledBy, labelId, labelSourceRef, enableFallback = true, labelSourceId) {
+  const [fallbackAriaLabelledBy, setFallbackAriaLabelledBy] = React.useState();
+  const generatedLabelId = (0, _useBaseUiId.useBaseUiId)(labelSourceId ? `${labelSourceId}-label` : undefined);
+  const ariaLabelledBy = explicitAriaLabelledBy ?? labelId ?? fallbackAriaLabelledBy;
+
+  // Fallback for <span> controls labelled by wrapping/sibling native <label>.
+  // Run after every commit so DOM association changes (e.g. label mount/unmount)
+  // are reflected even when props/state deps are unchanged.
+  // eslint-disable-next-line react-hooks/exhaustive-deps
+  (0, _useIsoLayoutEffect.useIsoLayoutEffect)(() => {
+    const nextAriaLabelledBy = explicitAriaLabelledBy || labelId || !enableFallback ? undefined : getAriaLabelledBy(labelSourceRef.current, generatedLabelId);
+    if (fallbackAriaLabelledBy !== nextAriaLabelledBy) {
+      setFallbackAriaLabelledBy(nextAriaLabelledBy);
+    }
+  });
+  return ariaLabelledBy;
+}
+function getAriaLabelledBy(labelSource, generatedLabelId) {
+  const label = findAssociatedLabel(labelSource);
+  if (!label) {
+    return undefined;
+  }
+  if (!label.id && generatedLabelId) {
+    label.id = generatedLabelId;
+  }
+  return label.id || undefined;
+}
+function findAssociatedLabel(labelSource) {
+  if (!labelSource) {
+    return undefined;
+  }
+
+  // Fast path before the expensive `.labels` read.
+  const parent = labelSource.parentElement;
+  if (parent && parent.tagName === 'LABEL') {
+    return parent;
+  }
+  const controlId = labelSource.id;
+  if (controlId) {
+    const nextSibling = labelSource.nextElementSibling;
+    if (nextSibling && nextSibling.htmlFor === controlId) {
+      return nextSibling;
+    }
+  }
+  const labels = labelSource.labels;
+  return labels && labels[0];
+}

package/labelable-provider/useLabel.d.ts

@@ -0,0 +1,25 @@
+import * as React from 'react';
+export declare function useLabel(params?: UseLabelParameters): UseLabelReturnValue;
+export interface UseLabelParameters {
+  id?: string | undefined;
+  /**
+   * Control id used when no labelable context control id exists.
+   */
+  fallbackControlId?: string | null | undefined;
+  /**
+   * Whether the rendered element is a native `<label>`.
+   * @default false
+   */
+  native?: boolean | undefined;
+  /**
+   * Additional callback to sync the current label id with local component state/store.
+   */
+  setLabelId?: ((nextLabelId: string | undefined) => void) | undefined;
+  /**
+   * Custom focus handler for non-native labels.
+   * If omitted, focus behavior targets the resolved control id.
+   */
+  focusControl?: ((event: React.MouseEvent, controlId: string | null | undefined) => void) | undefined;
+}
+export type UseLabelReturnValue = React.HTMLAttributes<any> & React.LabelHTMLAttributes<any>;
+export declare function focusElementWithVisible(element: HTMLElement): void;

package/labelable-provider/useLabel.js

@@ -0,0 +1,80 @@
+"use strict";
+'use client';
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.focusElementWithVisible = focusElementWithVisible;
+exports.useLabel = useLabel;
+var _dom = require("@floating-ui/utils/dom");
+var _owner = require("@base-ui/utils/owner");
+var _useStableCallback = require("@base-ui/utils/useStableCallback");
+var _utils = require("../floating-ui-react/utils");
+var _useRegisteredLabelId = require("../utils/useRegisteredLabelId");
+var _LabelableContext = require("./LabelableContext");
+function useLabel(params = {}) {
+  const {
+    id: idProp,
+    fallbackControlId,
+    native = false,
+    setLabelId: setLabelIdProp,
+    focusControl: focusControlProp
+  } = params;
+  const {
+    controlId: contextControlId,
+    setLabelId: setContextLabelId
+  } = (0, _LabelableContext.useLabelableContext)();
+  const syncLabelId = (0, _useStableCallback.useStableCallback)(nextLabelId => {
+    setContextLabelId(nextLabelId);
+    setLabelIdProp?.(nextLabelId);
+  });
+  const id = (0, _useRegisteredLabelId.useRegisteredLabelId)(idProp, syncLabelId);
+  const resolvedControlId = contextControlId ?? fallbackControlId;
+  function focusControl(event) {
+    if (focusControlProp) {
+      focusControlProp(event, resolvedControlId);
+      return;
+    }
+    if (!resolvedControlId) {
+      return;
+    }
+    const controlElement = (0, _owner.ownerDocument)(event.currentTarget).getElementById(resolvedControlId);
+    if ((0, _dom.isHTMLElement)(controlElement)) {
+      focusElementWithVisible(controlElement);
+    }
+  }
+  function handleInteraction(event) {
+    const target = (0, _utils.getTarget)(event.nativeEvent);
+    if (target?.closest('button,input,select,textarea')) {
+      return;
+    }
+
+    // Prevent text selection when double clicking label.
+    if (!event.defaultPrevented && event.detail > 1) {
+      event.preventDefault();
+    }
+    if (native) {
+      return;
+    }
+    focusControl(event);
+  }
+  return native ? {
+    id,
+    htmlFor: resolvedControlId ?? undefined,
+    onMouseDown: handleInteraction
+  } : {
+    id,
+    onClick: handleInteraction,
+    onPointerDown(event) {
+      event.preventDefault();
+    }
+  };
+}
+function focusElementWithVisible(element) {
+  element.focus({
+    // Available from Chrome 144+ (January 2026).
+    // Safari and Firefox already support it.
+    // @ts-expect-error not available in types yet
+    focusVisible: true
+  });
+}

package/labelable-provider/useLabelableId.d.ts

@@ -1,5 +1,5 @@
 import * as React from 'react';
-export declare function useLabelableId(params?: useLabelableId.Parameters): string | undefined;
+export declare function useLabelableId(params?: UseLabelableIdParameters): string | undefined;
 export interface UseLabelableIdParameters {
   id?: string | undefined;
   /**
@@ -13,7 +13,4 @@ export interface UseLabelableIdParameters {
   controlRef?: React.RefObject<HTMLElement | null> | undefined;
 }
 export type UseLabelableIdReturnValue = string;
-export declare namespace useLabelableId {
-  type Parameters = UseLabelableIdParameters;
-  type ReturnValue = UseLabelableIdReturnValue;
-}
+export interface UseLabelableIdState {}

package/menu/arrow/MenuArrow.d.ts

@@ -13,11 +13,20 @@ export interface MenuArrowState {
    * Whether the menu is currently 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 arrow cannot be centered on the anchor.
+   */
   uncentered: boolean;
 }
-export interface MenuArrowProps extends BaseUIComponentProps<'div', MenuArrow.State> {}
+export interface MenuArrowProps extends BaseUIComponentProps<'div', MenuArrowState> {}
 export declare namespace MenuArrow {
   type State = MenuArrowState;
   type Props = MenuArrowProps;

package/menu/backdrop/MenuBackdrop.d.ts

@@ -13,9 +13,12 @@ export interface MenuBackdropState {
    * Whether the menu is currently open.
    */
   open: boolean;
+  /**
+   * The transition status of the component.
+   */
   transitionStatus: TransitionStatus;
 }
-export interface MenuBackdropProps extends BaseUIComponentProps<'div', MenuBackdrop.State> {}
+export interface MenuBackdropProps extends BaseUIComponentProps<'div', MenuBackdropState> {}
 export declare namespace MenuBackdrop {
   type State = MenuBackdropState;
   type Props = MenuBackdropProps;

package/menu/checkbox-item/MenuCheckboxItem.d.ts

@@ -8,7 +8,7 @@ import type { MenuRoot } from "../root/MenuRoot.js";
  * Documentation: [Base UI Menu](https://base-ui.com/react/components/menu)
  */
 export declare const MenuCheckboxItem: React.ForwardRefExoticComponent<Omit<MenuCheckboxItemProps, "ref"> & React.RefAttributes<HTMLElement>>;
-export type MenuCheckboxItemState = {
+export interface MenuCheckboxItemState {
   /**
    * Whether the checkbox item should ignore user interaction.
    */
@@ -21,8 +21,8 @@ export type MenuCheckboxItemState = {
    * Whether the checkbox item is currently ticked.
    */
   checked: boolean;
-};
-export interface MenuCheckboxItemProps extends NonNativeButtonProps, BaseUIComponentProps<'div', MenuCheckboxItem.State> {
+}
+export interface MenuCheckboxItemProps extends NonNativeButtonProps, BaseUIComponentProps<'div', MenuCheckboxItemState> {
   /**
    * Whether the checkbox item is currently ticked.
    *

package/menu/checkbox-item-indicator/MenuCheckboxItemIndicator.d.ts

@@ -8,7 +8,7 @@ import { TransitionStatus } from "../../utils/useTransitionStatus.js";
  * Documentation: [Base UI Menu](https://base-ui.com/react/components/menu)
  */
 export declare const MenuCheckboxItemIndicator: React.ForwardRefExoticComponent<Omit<MenuCheckboxItemIndicatorProps, "ref"> & React.RefAttributes<HTMLSpanElement>>;
-export interface MenuCheckboxItemIndicatorProps extends BaseUIComponentProps<'span', MenuCheckboxItemIndicator.State> {
+export interface MenuCheckboxItemIndicatorProps extends BaseUIComponentProps<'span', MenuCheckboxItemIndicatorState> {
   /**
    * Whether to keep the HTML element in the DOM when the checkbox item is not checked.
    * @default false
@@ -24,7 +24,13 @@ export interface MenuCheckboxItemIndicatorState {
    * Whether the component should ignore user interaction.
    */
   disabled: boolean;
+  /**
+   * Whether the item is highlighted.
+   */
   highlighted: boolean;
+  /**
+   * The transition status of the component.
+   */
   transitionStatus: TransitionStatus;
 }
 export declare namespace MenuCheckboxItemIndicator {

package/menu/group/MenuGroup.d.ts

@@ -7,7 +7,7 @@ import { BaseUIComponentProps } from "../../utils/types.js";
  * Documentation: [Base UI Menu](https://base-ui.com/react/components/menu)
  */
 export declare const MenuGroup: React.ForwardRefExoticComponent<Omit<MenuGroupProps, "ref"> & React.RefAttributes<HTMLDivElement>>;
-export interface MenuGroupProps extends BaseUIComponentProps<'div', MenuGroup.State> {
+export interface MenuGroupProps extends BaseUIComponentProps<'div', MenuGroupState> {
   /**
    * The content of the component.
    */

package/menu/group-label/MenuGroupLabel.d.ts

@@ -7,7 +7,7 @@ import type { BaseUIComponentProps } from "../../utils/types.js";
  * Documentation: [Base UI Menu](https://base-ui.com/react/components/menu)
  */
 export declare const MenuGroupLabel: React.ForwardRefExoticComponent<Omit<MenuGroupLabelProps, "ref"> & React.RefAttributes<HTMLDivElement>>;
-export interface MenuGroupLabelProps extends BaseUIComponentProps<'div', MenuGroupLabel.State> {}
+export interface MenuGroupLabelProps extends BaseUIComponentProps<'div', MenuGroupLabelState> {}
 export interface MenuGroupLabelState {}
 export declare namespace MenuGroupLabel {
   type Props = MenuGroupLabelProps;

package/menu/index.d.ts

@@ -16,4 +16,5 @@ export type * from "./radio-item/MenuRadioItem.js";
 export type * from "./radio-item-indicator/MenuRadioItemIndicator.js";
 export type * from "./submenu-root/MenuSubmenuRoot.js";
 export type * from "./trigger/MenuTrigger.js";
-export type * from "./submenu-trigger/MenuSubmenuTrigger.js";
+export type * from "./submenu-trigger/MenuSubmenuTrigger.js";
+export type * from "./viewport/MenuViewport.js";

package/menu/index.parts.d.ts

@@ -15,6 +15,7 @@ export { MenuRadioItemIndicator as RadioItemIndicator } from "./radio-item-indic
 export { MenuRoot as Root } from "./root/MenuRoot.js";
 export { MenuSubmenuRoot as SubmenuRoot } from "./submenu-root/MenuSubmenuRoot.js";
 export { MenuTrigger as Trigger } from "./trigger/MenuTrigger.js";
+export { MenuViewport as Viewport } from "./viewport/MenuViewport.js";
 export { Separator } from "../separator/Separator.js";
 export { MenuSubmenuTrigger as SubmenuTrigger } from "./submenu-trigger/MenuSubmenuTrigger.js";
 export { MenuHandle as Handle, createMenuHandle as createHandle } from "./store/MenuHandle.js";

package/menu/index.parts.js

@@ -123,6 +123,12 @@ Object.defineProperty(exports, "Trigger", {
     return _MenuTrigger.MenuTrigger;
   }
 });
+Object.defineProperty(exports, "Viewport", {
+  enumerable: true,
+  get: function () {
+    return _MenuViewport.MenuViewport;
+  }
+});
 Object.defineProperty(exports, "createHandle", {
   enumerable: true,
   get: function () {
@@ -146,6 +152,7 @@ var _MenuRadioItemIndicator = require("./radio-item-indicator/MenuRadioItemIndic
 var _MenuRoot = require("./root/MenuRoot");
 var _MenuSubmenuRoot = require("./submenu-root/MenuSubmenuRoot");
 var _MenuTrigger = require("./trigger/MenuTrigger");
+var _MenuViewport = require("./viewport/MenuViewport");
 var _Separator = require("../separator/Separator");
 var _MenuSubmenuTrigger = require("./submenu-trigger/MenuSubmenuTrigger");
 var _MenuHandle = require("./store/MenuHandle");

package/menu/item/MenuItem.d.ts

@@ -17,7 +17,7 @@ export interface MenuItemState {
    */
   highlighted: boolean;
 }
-export interface MenuItemProps extends NonNativeButtonProps, BaseUIComponentProps<'div', MenuItem.State> {
+export interface MenuItemProps extends NonNativeButtonProps, BaseUIComponentProps<'div', MenuItemState> {
   /**
    * The click handler for the menu item.
    */

package/menu/item/useMenuItem.d.ts

@@ -4,7 +4,7 @@ import { MenuStore } from "../store/MenuStore.js";
 export declare const REGULAR_ITEM: {
   type: "regular-item";
 };
-export declare function useMenuItem(params: useMenuItem.Parameters): useMenuItem.ReturnValue;
+export declare function useMenuItem(params: UseMenuItemParameters): UseMenuItemReturnValue;
 export interface UseMenuItemParameters {
   /**
    * Whether to close the menu when the item is clicked.
@@ -32,7 +32,7 @@ export interface UseMenuItemParameters {
   /**
    * Additional data specific to the item type.
    */
-  itemMetadata: useMenuItem.Metadata;
+  itemMetadata: UseMenuItemMetadata;
   /**
    * The node id of the menu positioner.
    */
@@ -41,6 +41,11 @@ export interface UseMenuItemParameters {
    * The menu store.
    */
   store: MenuStore<any>;
+  /**
+   * Whether a typeahead session is in progress.
+   * @default store.context.typingRef
+   */
+  typingRef?: React.RefObject<boolean> | undefined;
 }
 export type UseMenuItemMetadata = typeof REGULAR_ITEM | {
   type: 'submenu-trigger';
@@ -58,8 +63,4 @@ export interface UseMenuItemReturnValue {
    */
   itemRef: React.RefCallback<HTMLElement> | null;
 }
-export declare namespace useMenuItem {
-  type Parameters = UseMenuItemParameters;
-  type Metadata = UseMenuItemMetadata;
-  type ReturnValue = UseMenuItemReturnValue;
-}
+export interface UseMenuItemState {}

package/menu/item/useMenuItem.js

@@ -22,6 +22,7 @@ function useMenuItem(params) {
     highlighted,
     id,
     store,
+    typingRef = store.context.typingRef,
     nativeButton,
     itemMetadata,
     nodeId
@@ -33,7 +34,8 @@ function useMenuItem(params) {
   } = (0, _useButton.useButton)({
     disabled,
     focusableWhenDisabled: true,
-    native: nativeButton
+    native: nativeButton,
+    composite: true
   });
   const commonProps = (0, _useMenuItemCommonProps.useMenuItemCommonProps)({
     closeOnClick,
@@ -41,6 +43,7 @@ function useMenuItem(params) {
     id,
     nodeId,
     store,
+    typingRef,
     itemRef,
     itemMetadata
   });
@@ -51,14 +54,9 @@ function useMenuItem(params) {
           return;
         }
         itemMetadata.setActive();
-      },
-      onKeyUp(event) {
-        if (event.key === ' ' && store.context.typingRef.current) {
-          event.preventBaseUIHandler();
-        }
       }
     }, externalProps, getButtonProps);
-  }, [commonProps, getButtonProps, store, itemMetadata]);
+  }, [commonProps, getButtonProps, itemMetadata]);
   const mergedRef = (0, _useMergedRefs.useMergedRefs)(itemRef, buttonRef);
   return React.useMemo(() => ({
     getItemProps,

package/menu/item/useMenuItemCommonProps.d.ts

@@ -23,6 +23,10 @@ export interface UseMenuItemCommonPropsParameters {
    * The menu store.
    */
   store: MenuStore<any>;
+  /**
+   * Whether a typeahead session is in progress.
+   */
+  typingRef?: React.RefObject<boolean> | undefined;
   /**
    * Ref to the item element.
    */
@@ -35,9 +39,8 @@ export interface UseMenuItemCommonPropsParameters {
 }
 /**
  * Returns common props shared by all menu item types.
- * This hook extracts the shared logic for id, role, tabIndex, onMouseMove, onClick, and onMouseUp handlers.
+ * This hook extracts the shared logic for id, role, tabIndex, onKeyDown,
+ * onMouseMove, onClick, and onMouseUp handlers.
  */
 export declare function useMenuItemCommonProps(params: UseMenuItemCommonPropsParameters): HTMLProps;
-export declare namespace useMenuItemCommonProps {
-  type Parameters = UseMenuItemCommonPropsParameters;
-}
+export interface UseMenuItemCommonPropsState {}

package/menu/item/useMenuItemCommonProps.js

@@ -7,11 +7,13 @@ Object.defineProperty(exports, "__esModule", {
 });
 exports.useMenuItemCommonProps = useMenuItemCommonProps;
 var React = _interopRequireWildcard(require("react"));
+var _detectBrowser = require("@base-ui/utils/detectBrowser");
 var _reasons = require("../../utils/reasons");
 var _ContextMenuRootContext = require("../../context-menu/root/ContextMenuRootContext");
 /**
  * Returns common props shared by all menu item types.
- * This hook extracts the shared logic for id, role, tabIndex, onMouseMove, onClick, and onMouseUp handlers.
+ * This hook extracts the shared logic for id, role, tabIndex, onKeyDown,
+ * onMouseMove, onClick, and onMouseUp handlers.
  */
 function useMenuItemCommonProps(params) {
   const {
@@ -20,6 +22,7 @@ function useMenuItemCommonProps(params) {
     id,
     nodeId,
     store,
+    typingRef,
     itemRef,
     itemMetadata
   } = params;
@@ -32,6 +35,11 @@ function useMenuItemCommonProps(params) {
     id,
     role: 'menuitem',
     tabIndex: highlighted ? 0 : -1,
+    onKeyDown(event) {
+      if (event.key === ' ' && typingRef?.current) {
+        event.preventDefault();
+      }
+    },
     onMouseMove(event) {
       if (!nodeId) {
         return;
@@ -59,6 +67,12 @@ function useMenuItemCommonProps(params) {
         if (isContextMenu && initialCursorPoint && Math.abs(event.clientX - initialCursorPoint.x) <= 1 && Math.abs(event.clientY - initialCursorPoint.y) <= 1) {
           return;
         }
+
+        // On non-macOS platforms, this mouseup belongs to the right-click gesture
+        // that opened the context menu, so it must not activate an item.
+        if (isContextMenu && !_detectBrowser.isMac && event.button === 2) {
+          return;
+        }
       }
       if (itemRef.current && store.context.allowMouseUpTriggerRef.current && (!isContextMenu || event.button === 2)) {
         // This fires whenever the user clicks on the trigger, moves the cursor, and releases it over the item.
@@ -68,5 +82,5 @@ function useMenuItemCommonProps(params) {
         }
       }
     }
-  }), [closeOnClick, highlighted, id, menuEvents, nodeId, store, itemRef, contextMenuContext, isContextMenu, itemMetadata]);
+  }), [closeOnClick, highlighted, id, menuEvents, nodeId, store, typingRef, itemRef, contextMenuContext, isContextMenu, itemMetadata]);
 }

package/menu/link-item/MenuLinkItem.d.ts

@@ -13,7 +13,7 @@ export interface MenuLinkItemState {
    */
   highlighted: boolean;
 }
-export interface MenuLinkItemProps extends BaseUIComponentProps<'a', MenuLinkItem.State> {
+export interface MenuLinkItemProps extends BaseUIComponentProps<'a', MenuLinkItemState> {
   /**
    * Overrides the text label to use when the item is matched during keyboard text navigation.
    */

package/menu/link-item/MenuLinkItem.js

@@ -13,6 +13,8 @@ var _useBaseUiId = require("../../utils/useBaseUiId");
 var _useCompositeListItem = require("../../composite/list/useCompositeListItem");
 var _MenuPositionerContext = require("../positioner/MenuPositionerContext");
 var _useMenuItemCommonProps = require("../item/useMenuItemCommonProps");
+var _useButton = require("../../use-button");
+var _mergeProps = require("../../merge-props");
 /**
  * A link in the menu that can be used to navigate to a different page or section.
  * Renders an `<a>` element.
@@ -40,21 +42,33 @@ const MenuLinkItem = exports.MenuLinkItem = /*#__PURE__*/React.forwardRef(functi
   } = (0, _MenuRootContext.useMenuRootContext)();
   const highlighted = store.useState('isActive', listItem.index);
   const itemProps = store.useState('itemProps');
+  const typingRef = store.context.typingRef;
+  const {
+    getButtonProps,
+    buttonRef
+  } = (0, _useButton.useButton)({
+    native: false,
+    composite: true
+  });
   const commonProps = (0, _useMenuItemCommonProps.useMenuItemCommonProps)({
     closeOnClick,
     highlighted,
     id,
     nodeId,
     store,
+    typingRef,
     itemRef: linkRef
   });
+  function getItemProps(externalProps) {
+    return (0, _mergeProps.mergeProps)(commonProps, externalProps, getButtonProps);
+  }
   const state = React.useMemo(() => ({
     highlighted
   }), [highlighted]);
   return (0, _useRenderElement.useRenderElement)('a', componentProps, {
     state,
-    props: [itemProps, elementProps, commonProps],
-    ref: [linkRef, forwardedRef, listItem.ref]
+    props: [itemProps, elementProps, getItemProps],
+    ref: [linkRef, buttonRef, forwardedRef, listItem.ref]
   });
 });
 if (process.env.NODE_ENV !== "production") MenuLinkItem.displayName = "MenuLinkItem";

package/menu/popup/MenuPopup.d.ts

@@ -10,7 +10,7 @@ import type { TransitionStatus } from "../../utils/useTransitionStatus.js";
  * Documentation: [Base UI Menu](https://base-ui.com/react/components/menu)
  */
 export declare const MenuPopup: React.ForwardRefExoticComponent<Omit<MenuPopupProps, "ref"> & React.RefAttributes<HTMLDivElement>>;
-export interface MenuPopupProps extends BaseUIComponentProps<'div', MenuPopup.State> {
+export interface MenuPopupProps extends BaseUIComponentProps<'div', MenuPopupState> {
   children?: React.ReactNode;
   /**
    * @ignore
@@ -25,19 +25,34 @@ export interface MenuPopupProps extends BaseUIComponentProps<'div', MenuPopup.St
    * - `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) => boolean | HTMLElement | null | void)) | undefined;
+  finalFocus?: boolean | React.RefObject<HTMLElement | null> | ((closeType: InteractionType) => boolean | HTMLElement | null | void) | undefined;
 }
-export type MenuPopupState = {
+export interface MenuPopupState {
+  /**
+   * The transition status of the component.
+   */
   transitionStatus: TransitionStatus;
+  /**
+   * 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 menu is currently open.
    */
   open: boolean;
+  /**
+   * Whether the component is nested.
+   */
   nested: boolean;
-  instant: 'dismiss' | 'click' | 'group' | undefined;
-};
+  /**
+   * Whether transitions should be skipped.
+   */
+  instant: 'dismiss' | 'click' | 'group' | 'trigger-change' | undefined;
+}
 export declare namespace MenuPopup {
   type Props = MenuPopupProps;
   type State = MenuPopupState;

package/menu/popup/MenuPopup.js

@@ -92,9 +92,12 @@ const MenuPopup = exports.MenuPopup = /*#__PURE__*/React.forwardRef(function Men
     nested: parent.type === 'menu',
     instant: instantType
   };
+  const setPopupElement = React.useCallback(element => {
+    store.set('popupElement', element);
+  }, [store]);
   const element = (0, _useRenderElement.useRenderElement)('div', componentProps, {
     state,
-    ref: [forwardedRef, store.context.popupRef],
+    ref: [forwardedRef, store.context.popupRef, setPopupElement],
     stateAttributesMapping,
     props: [popupProps, {
       onKeyDown(event) {

package/menu/popup/MenuPopupDataAttributes.d.ts

@@ -27,7 +27,7 @@ export declare enum MenuPopupDataAttributes {
   align = "data-align",
   /**
    * Present if animations should be instant.
-   * @type {'click' | 'dismiss' | 'group'}
+   * @type {'click' | 'dismiss' | 'group' | 'trigger-change'}
    */
   instant = "data-instant",
 }

package/menu/popup/MenuPopupDataAttributes.js

@@ -34,7 +34,7 @@ let MenuPopupDataAttributes = exports.MenuPopupDataAttributes = function (MenuPo
   MenuPopupDataAttributes[MenuPopupDataAttributes["align"] = _popupStateMapping.CommonPopupDataAttributes.align] = "align";
   /**
    * Present if animations should be instant.
-   * @type {'click' | 'dismiss' | 'group'}
+   * @type {'click' | 'dismiss' | 'group' | 'trigger-change'}
    */
   MenuPopupDataAttributes["instant"] = "data-instant";
   return MenuPopupDataAttributes;

package/menu/portal/MenuPortal.d.ts

@@ -8,10 +8,8 @@ import { FloatingPortal } from "../../floating-ui-react/index.js";
  * Documentation: [Base UI Menu](https://base-ui.com/react/components/menu)
  */
 export declare const MenuPortal: React.ForwardRefExoticComponent<Omit<MenuPortalProps, "ref"> & React.RefAttributes<HTMLDivElement>>;
-export declare namespace MenuPortal {
-  interface State {}
-}
-export interface MenuPortalProps extends FloatingPortal.Props<MenuPortal.State> {
+export interface MenuPortalState {}
+export interface MenuPortalProps extends FloatingPortal.Props<MenuPortalState> {
   /**
    * Whether to keep the portal mounted in the DOM while the popup is hidden.
    * @default false
@@ -19,5 +17,6 @@ export interface MenuPortalProps extends FloatingPortal.Props<MenuPortal.State>
   keepMounted?: boolean | undefined;
 }
 export declare namespace MenuPortal {
+  type State = MenuPortalState;
   type Props = MenuPortalProps;
 }