@base-ui/react 1.6.0 → 1.8.0

package/menu/root/MenuRoot.mjs

@@ -5,6 +5,7 @@ import { useTimeout } from '@base-ui/utils/useTimeout';
 import { useStableCallback } from '@base-ui/utils/useStableCallback';
 import { useId } from '@base-ui/utils/useId';
 import { useIsoLayoutEffect } from '@base-ui/utils/useIsoLayoutEffect';
+import { useRefWithInit } from '@base-ui/utils/useRefWithInit';
 import { EMPTY_ARRAY, EMPTY_OBJECT } from '@base-ui/utils/empty';
 import { fastComponent } from '@base-ui/utils/fastHooks';
 import { FloatingTree, useDismiss, useFloatingNodeId, useFloatingParentNodeId, useListNavigation, useTypeahead, useSyncedFloatingRootContext } from "../../floating-ui-react/index.mjs";
@@ -17,8 +18,9 @@ import { createChangeEventDetails } from "../../internals/createBaseUIEventDetai
 import { REASONS } from "../../internals/reasons.mjs";
 import { useContextMenuRootContext } from "../../context-menu/root/ContextMenuRootContext.mjs";
 import { mergeProps } from "../../merge-props/index.mjs";
+import { useAnimationsFinished } from "../../internals/useAnimationsFinished.mjs";
 import { MenuStore } from "../store/MenuStore.mjs";
-import { attachPreventUnmountOnClose, FOCUSABLE_POPUP_PROPS, setPopupOpenState, useImplicitActiveTrigger, useInitialOpenSync, useOpenStateTransitions, usePopupInteractionProps } from "../../utils/popups/index.mjs";
+import { attachPreventUnmountOnClose, FOCUSABLE_POPUP_PROPS, createPopupOpenState, PopupHandleAttachment, useImplicitActiveTrigger, useOpenStateTransitions, usePopupInteractionProps } from "../../utils/popups/index.mjs";
 import { useMenuSubmenuRootContext } from "../submenu-root/MenuSubmenuRootContext.mjs";
 
 /**
@@ -27,7 +29,7 @@ import { useMenuSubmenuRootContext } from "../submenu-root/MenuSubmenuRootContex
  *
  * Documentation: [Base UI Menu](https://base-ui.com/react/components/menu)
  */
-import { jsx as _jsx } from "react/jsx-runtime";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 export const MenuRoot = fastComponent(function MenuRoot(props) {
   const {
     children,
@@ -77,22 +79,41 @@ export const MenuRoot = fastComponent(function MenuRoot(props) {
       type: undefined
     };
   }, [contextMenuContext, parentMenuRootContext, menubarContext, isSubmenu]);
-  const store = MenuStore.useStore(handle?.store, {
+  const rootId = useId();
+  const floatingId = useId();
+  const floatingParentNodeIdFromContext = useFloatingParentNodeId();
+  const parentMenuStore = parentFromContext.type === 'menu' ? parentFromContext.store : undefined;
+  // An initially open submenu should animate in only when the user watches it appear, i.e. when
+  // its subtree mounts because the parent popup is playing its own enter transition. A parent
+  // that was `defaultOpen` at page load never passes through `'starting'`, and under a
+  // `keepMounted` parent these initializers run at page load while the parent's status is still
+  // `undefined` — in both cases the submenu is page-load content that must not animate. Gated on
+  // being open at mount so a closed submenu doesn't seed `instantType` it would never clear. Read
+  // during the first render only — consumed exclusively by first-render initializers below
+  // (`useState` and the store's initial state).
+  const animateInitialOpen = (openProp ?? defaultOpen) && parentMenuStore?.state.transitionStatus === 'starting';
+
+  // Mirror an instantly-opened parent (e.g. keyboard click) so `[data-instant]` styling
+  // suppresses the enter transition on both popups or neither. Captured once —
+  // `animateInitialOpen` is only meaningful during the first render.
+  const seededInstantType = useRefWithInit(() => animateInitialOpen ? parentMenuStore?.state.instantType : undefined).current;
+  const store = useMenuRootStore({
     open: defaultOpen,
     openProp,
     activeTriggerId: defaultTriggerIdProp,
     triggerIdProp,
-    parent: parentFromContext
-  });
-  useInitialOpenSync(store, openProp, defaultOpen, defaultTriggerIdProp);
+    parent: parentFromContext,
+    disabled: disabledProp,
+    highlightItemOnHover,
+    modal: parentFromContext.type === undefined ? modalProp : undefined,
+    rootId,
+    instantType: seededInstantType
+  }, floatingId, floatingParentNodeIdFromContext != null);
   store.useControlledProp('openProp', openProp);
   store.useControlledProp('triggerIdProp', triggerIdProp);
   store.useContextCallback('onOpenChangeComplete', onOpenChangeComplete);
-  const rootId = useId();
-  const floatingId = useId();
   const floatingTreeRoot = store.useState('floatingTreeRoot');
   const floatingNodeIdFromContext = useFloatingNodeId(floatingTreeRoot);
-  const floatingParentNodeIdFromContext = useFloatingParentNodeId();
   const open = store.useState('open');
   const activeTriggerElement = store.useState('activeTriggerElement');
   const positionerElement = store.useState('positionerElement');
@@ -127,13 +148,54 @@ export const MenuRoot = fastComponent(function MenuRoot(props) {
   });
   useImplicitActiveTrigger(store);
   const {
-    forceUnmount
+    forceUnmount,
+    transitionStatus
   } = useOpenStateTransitions(open, store, () => {
-    store.update({
-      allowMouseEnter: false,
-      stickIfOpen: true
-    });
-  });
+    store.set('allowMouseEnter', false);
+  }, animateInitialOpen);
+  const runOnceAnimationsFinish = useAnimationsFinished(store.context.popupRef);
+
+  // An inherited `instantType` is only for the initial reveal. A later controlled `open` flip
+  // bypasses `setOpen`, so nothing would reset it and `[data-instant]` would wrongly suppress
+  // every subsequent transition. Clear it once the enter phase settles, unless an interactive
+  // open change already replaced it.
+  React.useEffect(() => {
+    if (seededInstantType === undefined) {
+      return undefined;
+    }
+    const clearSeededInstantType = () => {
+      if (store.state.instantType === seededInstantType) {
+        store.set('instantType', undefined);
+      }
+    };
+
+    // A controlled close can interrupt the initial enter before the animations-finished cleanup
+    // below fires (its abort cancels the pending callback, and a closed popup schedules no new
+    // one). Nothing is left to protect once closing starts — the exit's suppression was already
+    // decided at its trigger commit — so clear now or the next reopen renders a stale
+    // `[data-instant]`.
+    if (!open) {
+      clearSeededInstantType();
+      return undefined;
+    }
+    if (transitionStatus !== undefined) {
+      return undefined;
+    }
+
+    // With no popup element (e.g. its subtree is suspended or waiting on data), there is no
+    // enter transition to protect, and `useAnimationsFinished` would return without invoking the
+    // callback — a ref assignment alone would never rerun this effect, leaving the seed stuck.
+    // Clear immediately: a popup that appears after the reveal settles is page-load-like content.
+    if (store.context.popupRef.current == null) {
+      clearSeededInstantType();
+      return undefined;
+    }
+    const abortController = new AbortController();
+    runOnceAnimationsFinish(clearSeededInstantType, abortController.signal);
+    return () => {
+      abortController.abort();
+    };
+  }, [seededInstantType, open, transitionStatus, runOnceAnimationsFinish, store]);
   useIsoLayoutEffect(() => {
     if (contextMenuContext && !parentMenuRootContext) {
       // This is a context menu root.
@@ -180,6 +242,12 @@ export const MenuRoot = fastComponent(function MenuRoot(props) {
   }, [open, hoverEnabled, store]);
   const setOpen = useStableCallback((nextOpen, eventDetails) => {
     const reason = eventDetails.reason;
+
+    // Read the store directly, as relayed tree events and stale hover timers can request
+    // a close after the state changed but before this component re-rendered.
+    if (!nextOpen && !store.select('open')) {
+      return;
+    }
     if (open === nextOpen && eventDetails.trigger === activeTriggerElement && lastOpenChangeReason === reason) {
       return;
     }
@@ -212,31 +280,42 @@ export const MenuRoot = fastComponent(function MenuRoot(props) {
       allowTouchToCloseRef.current = true;
       allowTouchToCloseTimeout.clear();
     }
-    const isKeyboardClick = (reason === REASONS.triggerPress || reason === REASONS.itemPress) && nativeEvent.detail === 0 && nativeEvent?.isTrusted;
+
+    // Keyboard and assistive-technology activations produce `detail === 0` clicks;
+    // mouse-gesture clicks (including the synthesized drag-release click from
+    // `useMenuItemCommonProps`) carry `detail >= 1`.
+    const isKeyboardClick = (reason === REASONS.triggerPress || reason === REASONS.itemPress) && nativeEvent.detail === 0;
     const isDismissClose = !nextOpen && (reason === REASONS.escapeKey || reason == null);
-    const updatedState = {
-      open: nextOpen,
-      openChangeReason: reason
-    };
-    openEventRef.current = eventDetails.event ?? null;
-    setPopupOpenState(updatedState, nextOpen, eventDetails.trigger, shouldPreventUnmountOnClose());
-    store.update(updatedState);
+    openEventRef.current = eventDetails.event;
+    const popupOpenState = createPopupOpenState(store.state, nextOpen, eventDetails.trigger, shouldPreventUnmountOnClose());
+    popupOpenState.openChangeReason = reason;
     if (parent.type === 'menubar' && (reason === REASONS.triggerFocus || reason === REASONS.focusOut || reason === REASONS.triggerHover || reason === REASONS.listNavigation || reason === REASONS.siblingOpen)) {
-      store.set('instantType', 'group');
+      popupOpenState.instantType = 'group';
     } else if (isKeyboardClick || isDismissClose) {
-      store.set('instantType', isKeyboardClick ? 'click' : 'dismiss');
+      popupOpenState.instantType = isKeyboardClick ? 'click' : 'dismiss';
     } else {
-      store.set('instantType', undefined);
+      popupOpenState.instantType = undefined;
     }
+
+    // `instantType` must land in the same update that mounts the popup subtree: in React 17
+    // legacy mode this `update` can flush synchronously, and a separate `instantType` write
+    // after it would come too late for an initially open submenu seeding its own store from
+    // this one during that flush.
+    store.update(popupOpenState);
   });
   const floatingRootContext = useSyncedFloatingRootContext({
     popupStore: store,
+    floatingRootContext: store.state.floatingRootContext,
     floatingId,
     nested: floatingParentNodeIdFromContext != null,
     onOpenChange: setOpen
   });
   const floatingEvents = floatingRootContext.context.events;
-  React.useEffect(() => {
+
+  // Registered in a layout effect (not a passive one) so `setOpen` emits from imperative
+  // `MenuHandle.open()` calls made in the same commit this root mounts — e.g. from another layout
+  // effect during a route-transition handoff — are received instead of being silently dropped.
+  useIsoLayoutEffect(() => {
     const handleSetOpenEvent = ({
       open: nextOpen,
       eventDetails
@@ -328,9 +407,20 @@ export const MenuRoot = fastComponent(function MenuRoot(props) {
     mergedProps['aria-expanded'] = false;
     return mergedProps;
   }, [listNavigation.trigger, dismiss.trigger, interactionTypeProps]);
+
+  // The initial render has no store subscribers yet. Seed these props before triggers render so
+  // the synchronization effect below doesn't make every trigger render twice in the first commit.
+  useRefWithInit(() => {
+    store.update({
+      inactiveTriggerProps
+    });
+    return null;
+  });
   const popupProps = React.useMemo(() => mergeProps(FOCUSABLE_POPUP_PROPS, {
     id: floatingId,
     role: 'menu',
+    // `menu` is implicitly vertical, so only the non-default value needs to be rendered.
+    'aria-orientation': orientation === 'horizontal' ? 'horizontal' : undefined,
     'aria-labelledby': activeTriggerElement?.id,
     onMouseMove() {
       store.set('allowMouseEnter', true);
@@ -352,7 +442,7 @@ export const MenuRoot = fastComponent(function MenuRoot(props) {
         relay(event);
       }
     }
-  }, typeahead.floating, listNavigation.floating, dismiss.floating), [activeTriggerElement, floatingId, parent.type, store, typeahead.floating, listNavigation.floating, dismiss.floating]);
+  }, typeahead.floating, listNavigation.floating, dismiss.floating), [activeTriggerElement, floatingId, orientation, parent.type, store, typeahead.floating, listNavigation.floating, dismiss.floating]);
   const itemProps = listNavigation.item ?? EMPTY_OBJECT;
   usePopupInteractionProps(store, {
     floatingRootContext,
@@ -365,11 +455,14 @@ export const MenuRoot = fastComponent(function MenuRoot(props) {
     store,
     parent: parentFromContext
   }), [store, parentFromContext]);
-  const content = /*#__PURE__*/_jsx(MenuRootContext.Provider, {
+  const content = /*#__PURE__*/_jsxs(MenuRootContext.Provider, {
     value: context,
-    children: typeof children === 'function' ? children({
+    children: [handle && /*#__PURE__*/_jsx(PopupHandleAttachment, {
+      handle: handle,
+      store: store
+    }), typeof children === 'function' ? children({
       payload
-    }) : children
+    }) : children]
   });
   if (parent.type === undefined || parent.type === 'context-menu') {
     // set up a FloatingTree to provide the context to nested menus
@@ -380,4 +473,13 @@ export const MenuRoot = fastComponent(function MenuRoot(props) {
   }
   return content;
 });
-if (process.env.NODE_ENV !== "production") MenuRoot.displayName = "MenuRoot";
+if (process.env.NODE_ENV !== "production") MenuRoot.displayName = "MenuRoot";
+function useMenuRootStore(initialState, floatingId, nested) {
+  // The store is owned by this Root instance and created exactly once. It is not tied to the handle:
+  // the handle attaches to it, so swapping the handle re-attaches rather than recreating state.
+  // Default values are only initial values; controlled values and root state are synced after creation.
+  // Unlike other popups, Menu wires its floating root context separately (it relays open changes
+  // through an event).
+  const store = useRefWithInit(() => new MenuStore(initialState, floatingId, nested)).current;
+  return store;
+}

package/menu/store/MenuHandle.d.mts

@@ -1,24 +1,32 @@
-import { MenuStore } from "./MenuStore.mjs";
-export declare class MenuHandle<Payload> {
-  /**
-   * Internal store holding the menu's state.
-   * @internal
-   */
-  readonly store: MenuStore<Payload>;
+import { MenuStore, type MenuHandleStore } from "./MenuStore.mjs";
+import { BasePopupHandle } from "../../utils/popups/popupHandle.mjs";
+/**
+ * Controls a Menu imperatively and associates detached `Menu.Trigger` components with a `Menu.Root`.
+ * Create one with `Menu.createHandle()` and pass it to the `handle` prop of the root and of any
+ * triggers rendered outside of it.
+ *
+ * The imperative methods take effect only while a root using this handle is mounted; calls made
+ * before a root attaches (or after it unmounts) are ignored.
+ */
+export declare class MenuHandle<Payload> extends BasePopupHandle<MenuHandleStore<Payload>, MenuStore<Payload>> {
   constructor();
   /**
    * Opens the menu and associates it with the trigger with the given id.
-   * The trigger must be a Menu.Trigger component with this handle passed as a prop.
    *
-   * @param triggerId ID of the trigger to associate with the menu.
+   * This method should only be called in an event handler or an effect (not during rendering).
+   *
+   * @param triggerId ID of the trigger to associate with the menu. The trigger must be a matching
+   * `Menu.Trigger` with this handle passed as a prop.
    */
   open(triggerId: string): void;
   /**
    * Closes the menu.
+   *
+   * This method should only be called in an event handler or an effect (not during rendering).
    */
   close(): void;
   /**
-   * Indicates whether the menu is currently open.
+   * Whether the menu is currently open. Returns `false` while no root is attached to the handle.
    */
   get isOpen(): boolean;
 }

package/menu/store/MenuHandle.d.ts

@@ -1,24 +1,32 @@
-import { MenuStore } from "./MenuStore.js";
-export declare class MenuHandle<Payload> {
-  /**
-   * Internal store holding the menu's state.
-   * @internal
-   */
-  readonly store: MenuStore<Payload>;
+import { MenuStore, type MenuHandleStore } from "./MenuStore.js";
+import { BasePopupHandle } from "../../utils/popups/popupHandle.js";
+/**
+ * Controls a Menu imperatively and associates detached `Menu.Trigger` components with a `Menu.Root`.
+ * Create one with `Menu.createHandle()` and pass it to the `handle` prop of the root and of any
+ * triggers rendered outside of it.
+ *
+ * The imperative methods take effect only while a root using this handle is mounted; calls made
+ * before a root attaches (or after it unmounts) are ignored.
+ */
+export declare class MenuHandle<Payload> extends BasePopupHandle<MenuHandleStore<Payload>, MenuStore<Payload>> {
   constructor();
   /**
    * Opens the menu and associates it with the trigger with the given id.
-   * The trigger must be a Menu.Trigger component with this handle passed as a prop.
    *
-   * @param triggerId ID of the trigger to associate with the menu.
+   * This method should only be called in an event handler or an effect (not during rendering).
+   *
+   * @param triggerId ID of the trigger to associate with the menu. The trigger must be a matching
+   * `Menu.Trigger` with this handle passed as a prop.
    */
   open(triggerId: string): void;
   /**
    * Closes the menu.
+   *
+   * This method should only be called in an event handler or an effect (not during rendering).
    */
   close(): void;
   /**
-   * Indicates whether the menu is currently open.
+   * Whether the menu is currently open. Returns `false` while no root is attached to the handle.
    */
   get isOpen(): boolean;
 }

package/menu/store/MenuHandle.js

@@ -1,50 +1,51 @@
 "use strict";
 
-var _interopRequireDefault = require("@babel/runtime/helpers/interopRequireDefault").default;
 Object.defineProperty(exports, "__esModule", {
   value: true
 });
 exports.MenuHandle = void 0;
 exports.createMenuHandle = createMenuHandle;
-var _formatErrorMessage2 = _interopRequireDefault(require("@base-ui/utils/formatErrorMessage"));
-var _createBaseUIEventDetails = require("../../internals/createBaseUIEventDetails");
 var _MenuStore = require("./MenuStore");
-class MenuHandle {
-  /**
-   * Internal store holding the menu's state.
-   * @internal
-   */
-
+var _popupHandle = require("../../utils/popups/popupHandle");
+/**
+ * Controls a Menu imperatively and associates detached `Menu.Trigger` components with a `Menu.Root`.
+ * Create one with `Menu.createHandle()` and pass it to the `handle` prop of the root and of any
+ * triggers rendered outside of it.
+ *
+ * The imperative methods take effect only while a root using this handle is mounted; calls made
+ * before a root attaches (or after it unmounts) are ignored.
+ */
+class MenuHandle extends _popupHandle.BasePopupHandle {
   constructor() {
-    this.store = new _MenuStore.MenuStore();
+    super((0, _MenuStore.createNullMenuStore)(), 'Menu');
   }
 
   /**
    * Opens the menu and associates it with the trigger with the given id.
-   * The trigger must be a Menu.Trigger component with this handle passed as a prop.
    *
-   * @param triggerId ID of the trigger to associate with the menu.
+   * This method should only be called in an event handler or an effect (not during rendering).
+   *
+   * @param triggerId ID of the trigger to associate with the menu. The trigger must be a matching
+   * `Menu.Trigger` with this handle passed as a prop.
    */
   open(triggerId) {
-    const triggerElement = triggerId ? this.store.context.triggerElements.getById(triggerId) : undefined;
-    if (triggerId && !triggerElement) {
-      throw new Error(process.env.NODE_ENV !== "production" ? `Base UI: MenuHandle.open: No trigger found with id "${triggerId}".` : (0, _formatErrorMessage2.default)(83, triggerId));
-    }
-    this.store.setOpen(true, (0, _createBaseUIEventDetails.createChangeEventDetails)('imperative-action', undefined, triggerElement));
+    this.openByTrigger(triggerId);
   }
 
   /**
    * Closes the menu.
+   *
+   * This method should only be called in an event handler or an effect (not during rendering).
    */
   close() {
-    this.store.setOpen(false, (0, _createBaseUIEventDetails.createChangeEventDetails)('imperative-action', undefined, undefined));
+    this.closePopup();
   }
 
   /**
-   * Indicates whether the menu is currently open.
+   * Whether the menu is currently open. Returns `false` while no root is attached to the handle.
    */
   get isOpen() {
-    return this.store.select('open');
+    return this.attachedStore?.select('open') ?? false;
   }
 }
 

package/menu/store/MenuHandle.mjs

@@ -1,42 +1,45 @@
-import _formatErrorMessage from "@base-ui/utils/formatErrorMessage";
-import { createChangeEventDetails } from "../../internals/createBaseUIEventDetails.mjs";
-import { MenuStore } from "./MenuStore.mjs";
-export class MenuHandle {
-  /**
-   * Internal store holding the menu's state.
-   * @internal
-   */
+import { createNullMenuStore } from "./MenuStore.mjs";
+import { BasePopupHandle } from "../../utils/popups/popupHandle.mjs";
 
+/**
+ * Controls a Menu imperatively and associates detached `Menu.Trigger` components with a `Menu.Root`.
+ * Create one with `Menu.createHandle()` and pass it to the `handle` prop of the root and of any
+ * triggers rendered outside of it.
+ *
+ * The imperative methods take effect only while a root using this handle is mounted; calls made
+ * before a root attaches (or after it unmounts) are ignored.
+ */
+export class MenuHandle extends BasePopupHandle {
   constructor() {
-    this.store = new MenuStore();
+    super(createNullMenuStore(), 'Menu');
   }
 
   /**
    * Opens the menu and associates it with the trigger with the given id.
-   * The trigger must be a Menu.Trigger component with this handle passed as a prop.
    *
-   * @param triggerId ID of the trigger to associate with the menu.
+   * This method should only be called in an event handler or an effect (not during rendering).
+   *
+   * @param triggerId ID of the trigger to associate with the menu. The trigger must be a matching
+   * `Menu.Trigger` with this handle passed as a prop.
    */
   open(triggerId) {
-    const triggerElement = triggerId ? this.store.context.triggerElements.getById(triggerId) : undefined;
-    if (triggerId && !triggerElement) {
-      throw new Error(process.env.NODE_ENV !== "production" ? `Base UI: MenuHandle.open: No trigger found with id "${triggerId}".` : _formatErrorMessage(83, triggerId));
-    }
-    this.store.setOpen(true, createChangeEventDetails('imperative-action', undefined, triggerElement));
+    this.openByTrigger(triggerId);
   }
 
   /**
    * Closes the menu.
+   *
+   * This method should only be called in an event handler or an effect (not during rendering).
    */
   close() {
-    this.store.setOpen(false, createChangeEventDetails('imperative-action', undefined, undefined));
+    this.closePopup();
   }
 
   /**
-   * Indicates whether the menu is currently open.
+   * Whether the menu is currently open. Returns `false` while no root is attached to the handle.
    */
   get isOpen() {
-    return this.store.select('open');
+    return this.attachedStore?.select('open') ?? false;
   }
 }
 

package/menu/store/MenuStore.d.mts

@@ -4,10 +4,11 @@ import type { InteractionType } from '@base-ui/utils/useEnhancedClickHandler';
 import { MenuParent, MenuRoot } from "../root/MenuRoot.mjs";
 import { FloatingTreeStore } from "../../floating-ui-react/components/FloatingTreeStore.mjs";
 import { HTMLProps } from "../../internals/types.mjs";
-import { PopupStoreContext, PopupStoreState } from "../../utils/popups/index.mjs";
+import type { AdaptiveOriginMiddleware } from "../../utils/adaptiveOriginConstants.mjs";
+import { PopupStoreContext, PopupStoreState, type PopupTriggerStoreKeys } from "../../utils/popups/index.mjs";
 export type State<Payload> = PopupStoreState<Payload> & {
   disabled: boolean;
-  modal: boolean;
+  modal: boolean | undefined;
   openMethod: InteractionType | null;
   allowMouseEnter: boolean;
   highlightItemOnHover: boolean;
@@ -15,7 +16,6 @@ export type State<Payload> = PopupStoreState<Payload> & {
   rootId: string | undefined;
   activeIndex: number | null;
   hoverEnabled: boolean;
-  stickIfOpen: boolean;
   instantType: 'dismiss' | 'click' | 'group' | 'trigger-change' | undefined;
   openChangeReason: MenuRoot.ChangeEventReason | null;
   floatingTreeRoot: FloatingTreeStore;
@@ -24,7 +24,7 @@ export type State<Payload> = PopupStoreState<Payload> & {
   itemProps: HTMLProps;
   closeDelay: number;
   keyboardEventRelay: ((event: React.KeyboardEvent<any>) => void) | undefined;
-  hasViewport: boolean;
+  adaptiveOrigin: AdaptiveOriginMiddleware | undefined;
 };
 type Context = PopupStoreContext<MenuRoot.ChangeEventDetails> & {
   readonly positionerRef: React.RefObject<HTMLElement | null>;
@@ -384,7 +384,6 @@ declare const selectors: {
   openMethod: (state: State<unknown>) => InteractionType | null;
   allowMouseEnter: (state: State<unknown>) => boolean;
   highlightItemOnHover: (state: State<unknown>) => boolean;
-  stickIfOpen: (state: State<unknown>) => boolean;
   parent: (state: State<unknown>) => MenuParent;
   rootId: (state: State<unknown>) => string | undefined;
   activeIndex: (state: State<unknown>) => number | null;
@@ -397,13 +396,29 @@ declare const selectors: {
   floatingParentNodeId: (state: State<unknown>) => string | null;
   itemProps: (state: State<unknown>) => HTMLProps;
   closeDelay: (state: State<unknown>) => number;
-  hasViewport: (state: State<unknown>) => boolean;
+  adaptiveOrigin: (state: State<unknown>) => AdaptiveOriginMiddleware | undefined;
   keyboardEventRelay: (state: State<unknown>) => React.KeyboardEventHandler<any> | undefined;
 };
-export declare class MenuStore<Payload> extends ReactStore<Readonly<State<Payload>>, Context, typeof selectors> {
-  constructor(initialState?: Partial<State<Payload>>);
+type Selectors = typeof selectors;
+/**
+ * The store view that detached handle-backed triggers read from. Both the real `MenuStore` and the
+ * inert fallback store satisfy it, so a trigger can read from whichever store the handle currently
+ * exposes. Narrowed to the members a trigger actually uses — the trigger-data members plus `setOpen`
+ * (called by the focus guards) — so the exposed surface can't bypass the open-change pipeline; on
+ * the detached fallback store every one of these mutations is a no-op.
+ */
+export type MenuHandleStore<Payload> = Pick<MenuStore<Payload>, PopupTriggerStoreKeys | 'setOpen'>;
+export declare class MenuStore<Payload> extends ReactStore<Readonly<State<Payload>>, Context, Selectors> {
+  constructor(initialState?: Partial<State<Payload>>, floatingId?: string | undefined, nested?: boolean);
   setOpen(open: boolean, eventDetails: Omit<MenuRoot.ChangeEventDetails, 'preventUnmountOnClose'>): void;
-  static useStore<Payload>(externalStore: MenuStore<Payload> | undefined, initialState: Partial<State<Payload>>): MenuStore<Payload>;
   private unsubscribeParentListener;
 }
+/**
+ * Creates the inert fallback store used by detached handle-backed triggers while no `Menu.Root` is
+ * attached. It preserves a menu-specific trigger registry in context so detached triggers can
+ * register before migrating to the live root store. `setOpen` is a no-op (matching the inert
+ * reads/writes of `NullStore`), so a trigger can hand the store to focus-guard helpers that expect
+ * `setOpen` without it ever taking effect while detached.
+ */
+export declare function createNullMenuStore<Payload>(): MenuHandleStore<Payload>;
 export {};

package/menu/store/MenuStore.d.ts

@@ -4,10 +4,11 @@ import type { InteractionType } from '@base-ui/utils/useEnhancedClickHandler';
 import { MenuParent, MenuRoot } from "../root/MenuRoot.js";
 import { FloatingTreeStore } from "../../floating-ui-react/components/FloatingTreeStore.js";
 import { HTMLProps } from "../../internals/types.js";
-import { PopupStoreContext, PopupStoreState } from "../../utils/popups/index.js";
+import type { AdaptiveOriginMiddleware } from "../../utils/adaptiveOriginConstants.js";
+import { PopupStoreContext, PopupStoreState, type PopupTriggerStoreKeys } from "../../utils/popups/index.js";
 export type State<Payload> = PopupStoreState<Payload> & {
   disabled: boolean;
-  modal: boolean;
+  modal: boolean | undefined;
   openMethod: InteractionType | null;
   allowMouseEnter: boolean;
   highlightItemOnHover: boolean;
@@ -15,7 +16,6 @@ export type State<Payload> = PopupStoreState<Payload> & {
   rootId: string | undefined;
   activeIndex: number | null;
   hoverEnabled: boolean;
-  stickIfOpen: boolean;
   instantType: 'dismiss' | 'click' | 'group' | 'trigger-change' | undefined;
   openChangeReason: MenuRoot.ChangeEventReason | null;
   floatingTreeRoot: FloatingTreeStore;
@@ -24,7 +24,7 @@ export type State<Payload> = PopupStoreState<Payload> & {
   itemProps: HTMLProps;
   closeDelay: number;
   keyboardEventRelay: ((event: React.KeyboardEvent<any>) => void) | undefined;
-  hasViewport: boolean;
+  adaptiveOrigin: AdaptiveOriginMiddleware | undefined;
 };
 type Context = PopupStoreContext<MenuRoot.ChangeEventDetails> & {
   readonly positionerRef: React.RefObject<HTMLElement | null>;
@@ -384,7 +384,6 @@ declare const selectors: {
   openMethod: (state: State<unknown>) => InteractionType | null;
   allowMouseEnter: (state: State<unknown>) => boolean;
   highlightItemOnHover: (state: State<unknown>) => boolean;
-  stickIfOpen: (state: State<unknown>) => boolean;
   parent: (state: State<unknown>) => MenuParent;
   rootId: (state: State<unknown>) => string | undefined;
   activeIndex: (state: State<unknown>) => number | null;
@@ -397,13 +396,29 @@ declare const selectors: {
   floatingParentNodeId: (state: State<unknown>) => string | null;
   itemProps: (state: State<unknown>) => HTMLProps;
   closeDelay: (state: State<unknown>) => number;
-  hasViewport: (state: State<unknown>) => boolean;
+  adaptiveOrigin: (state: State<unknown>) => AdaptiveOriginMiddleware | undefined;
   keyboardEventRelay: (state: State<unknown>) => React.KeyboardEventHandler<any> | undefined;
 };
-export declare class MenuStore<Payload> extends ReactStore<Readonly<State<Payload>>, Context, typeof selectors> {
-  constructor(initialState?: Partial<State<Payload>>);
+type Selectors = typeof selectors;
+/**
+ * The store view that detached handle-backed triggers read from. Both the real `MenuStore` and the
+ * inert fallback store satisfy it, so a trigger can read from whichever store the handle currently
+ * exposes. Narrowed to the members a trigger actually uses — the trigger-data members plus `setOpen`
+ * (called by the focus guards) — so the exposed surface can't bypass the open-change pipeline; on
+ * the detached fallback store every one of these mutations is a no-op.
+ */
+export type MenuHandleStore<Payload> = Pick<MenuStore<Payload>, PopupTriggerStoreKeys | 'setOpen'>;
+export declare class MenuStore<Payload> extends ReactStore<Readonly<State<Payload>>, Context, Selectors> {
+  constructor(initialState?: Partial<State<Payload>>, floatingId?: string | undefined, nested?: boolean);
   setOpen(open: boolean, eventDetails: Omit<MenuRoot.ChangeEventDetails, 'preventUnmountOnClose'>): void;
-  static useStore<Payload>(externalStore: MenuStore<Payload> | undefined, initialState: Partial<State<Payload>>): MenuStore<Payload>;
   private unsubscribeParentListener;
 }
+/**
+ * Creates the inert fallback store used by detached handle-backed triggers while no `Menu.Root` is
+ * attached. It preserves a menu-specific trigger registry in context so detached triggers can
+ * register before migrating to the live root store. `setOpen` is a no-op (matching the inert
+ * reads/writes of `NullStore`), so a trigger can hand the store to focus-guard helpers that expect
+ * `setOpen` without it ever taking effect while detached.
+ */
+export declare function createNullMenuStore<Payload>(): MenuHandleStore<Payload>;
 export {};