@base-ui/react 1.6.0 → 1.7.0

package/menu/root/MenuRoot.js

@@ -11,6 +11,7 @@ var _useTimeout = require("@base-ui/utils/useTimeout");
 var _useStableCallback = require("@base-ui/utils/useStableCallback");
 var _useId = require("@base-ui/utils/useId");
 var _useIsoLayoutEffect = require("@base-ui/utils/useIsoLayoutEffect");
+var _useRefWithInit = require("@base-ui/utils/useRefWithInit");
 var _empty = require("@base-ui/utils/empty");
 var _fastHooks = require("@base-ui/utils/fastHooks");
 var _floatingUiReact = require("../../floating-ui-react");
@@ -82,14 +83,13 @@ const MenuRoot = exports.MenuRoot = (0, _fastHooks.fastComponent)(function MenuR
       type: undefined
     };
   }, [contextMenuContext, parentMenuRootContext, menubarContext, isSubmenu]);
-  const store = _MenuStore.MenuStore.useStore(handle?.store, {
+  const store = useMenuRootStore({
     open: defaultOpen,
     openProp,
     activeTriggerId: defaultTriggerIdProp,
     triggerIdProp,
     parent: parentFromContext
   });
-  (0, _popups.useInitialOpenSync)(store, openProp, defaultOpen, defaultTriggerIdProp);
   store.useControlledProp('openProp', openProp);
   store.useControlledProp('triggerIdProp', triggerIdProp);
   store.useContextCallback('onOpenChangeComplete', onOpenChangeComplete);
@@ -134,10 +134,7 @@ const MenuRoot = exports.MenuRoot = (0, _fastHooks.fastComponent)(function MenuR
   const {
     forceUnmount
   } = (0, _popups.useOpenStateTransitions)(open, store, () => {
-    store.update({
-      allowMouseEnter: false,
-      stickIfOpen: true
-    });
+    store.set('allowMouseEnter', false);
   });
   (0, _useIsoLayoutEffect.useIsoLayoutEffect)(() => {
     if (contextMenuContext && !parentMenuRootContext) {
@@ -185,6 +182,12 @@ const MenuRoot = exports.MenuRoot = (0, _fastHooks.fastComponent)(function MenuR
   }, [open, hoverEnabled, store]);
   const setOpen = (0, _useStableCallback.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;
     }
@@ -217,13 +220,17 @@ const MenuRoot = exports.MenuRoot = (0, _fastHooks.fastComponent)(function MenuR
       allowTouchToCloseRef.current = true;
       allowTouchToCloseTimeout.clear();
     }
-    const isKeyboardClick = (reason === _reasons.REASONS.triggerPress || reason === _reasons.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.REASONS.triggerPress || reason === _reasons.REASONS.itemPress) && nativeEvent.detail === 0;
     const isDismissClose = !nextOpen && (reason === _reasons.REASONS.escapeKey || reason == null);
     const updatedState = {
       open: nextOpen,
       openChangeReason: reason
     };
-    openEventRef.current = eventDetails.event ?? null;
+    openEventRef.current = eventDetails.event;
     (0, _popups.setPopupOpenState)(updatedState, nextOpen, eventDetails.trigger, shouldPreventUnmountOnClose());
     store.update(updatedState);
     if (parent.type === 'menubar' && (reason === _reasons.REASONS.triggerFocus || reason === _reasons.REASONS.focusOut || reason === _reasons.REASONS.triggerHover || reason === _reasons.REASONS.listNavigation || reason === _reasons.REASONS.siblingOpen)) {
@@ -241,7 +248,11 @@ const MenuRoot = exports.MenuRoot = (0, _fastHooks.fastComponent)(function MenuR
     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.
+  (0, _useIsoLayoutEffect.useIsoLayoutEffect)(() => {
     const handleSetOpenEvent = ({
       open: nextOpen,
       eventDetails
@@ -370,11 +381,14 @@ const MenuRoot = exports.MenuRoot = (0, _fastHooks.fastComponent)(function MenuR
     store,
     parent: parentFromContext
   }), [store, parentFromContext]);
-  const content = /*#__PURE__*/(0, _jsxRuntime.jsx)(_MenuRootContext.MenuRootContext.Provider, {
+  const content = /*#__PURE__*/(0, _jsxRuntime.jsxs)(_MenuRootContext.MenuRootContext.Provider, {
     value: context,
-    children: typeof children === 'function' ? children({
+    children: [handle && /*#__PURE__*/(0, _jsxRuntime.jsx)(_popups.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
@@ -385,4 +399,13 @@ const MenuRoot = exports.MenuRoot = (0, _fastHooks.fastComponent)(function MenuR
   }
   return content;
 });
-if (process.env.NODE_ENV !== "production") MenuRoot.displayName = "MenuRoot";
+if (process.env.NODE_ENV !== "production") MenuRoot.displayName = "MenuRoot";
+function useMenuRootStore(initialState) {
+  // 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 = (0, _useRefWithInit.useRefWithInit)(() => new _MenuStore.MenuStore(initialState)).current;
+  return store;
+}

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";
@@ -18,7 +19,7 @@ import { REASONS } from "../../internals/reasons.mjs";
 import { useContextMenuRootContext } from "../../context-menu/root/ContextMenuRootContext.mjs";
 import { mergeProps } from "../../merge-props/index.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, setPopupOpenState, PopupHandleAttachment, useImplicitActiveTrigger, useOpenStateTransitions, usePopupInteractionProps } from "../../utils/popups/index.mjs";
 import { useMenuSubmenuRootContext } from "../submenu-root/MenuSubmenuRootContext.mjs";
 
 /**
@@ -27,7 +28,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,14 +78,13 @@ export const MenuRoot = fastComponent(function MenuRoot(props) {
       type: undefined
     };
   }, [contextMenuContext, parentMenuRootContext, menubarContext, isSubmenu]);
-  const store = MenuStore.useStore(handle?.store, {
+  const store = useMenuRootStore({
     open: defaultOpen,
     openProp,
     activeTriggerId: defaultTriggerIdProp,
     triggerIdProp,
     parent: parentFromContext
   });
-  useInitialOpenSync(store, openProp, defaultOpen, defaultTriggerIdProp);
   store.useControlledProp('openProp', openProp);
   store.useControlledProp('triggerIdProp', triggerIdProp);
   store.useContextCallback('onOpenChangeComplete', onOpenChangeComplete);
@@ -129,10 +129,7 @@ export const MenuRoot = fastComponent(function MenuRoot(props) {
   const {
     forceUnmount
   } = useOpenStateTransitions(open, store, () => {
-    store.update({
-      allowMouseEnter: false,
-      stickIfOpen: true
-    });
+    store.set('allowMouseEnter', false);
   });
   useIsoLayoutEffect(() => {
     if (contextMenuContext && !parentMenuRootContext) {
@@ -180,6 +177,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,13 +215,17 @@ 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;
+    openEventRef.current = eventDetails.event;
     setPopupOpenState(updatedState, nextOpen, eventDetails.trigger, shouldPreventUnmountOnClose());
     store.update(updatedState);
     if (parent.type === 'menubar' && (reason === REASONS.triggerFocus || reason === REASONS.focusOut || reason === REASONS.triggerHover || reason === REASONS.listNavigation || reason === REASONS.siblingOpen)) {
@@ -236,7 +243,11 @@ export const MenuRoot = fastComponent(function MenuRoot(props) {
     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
@@ -365,11 +376,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 +394,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) {
+  // 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)).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,7 +4,8 @@ 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;
@@ -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> {
+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>>);
   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,7 +4,8 @@ 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;
@@ -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> {
+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>>);
   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 {};