@base-ui/react 1.6.0 → 1.7.0

package/popover/root/PopoverRoot.d.mts

@@ -44,6 +44,8 @@ export interface PopoverRootProps<Payload = unknown> {
    * - `false`: user interaction with the rest of the document is allowed.
    * - `'trap-focus'`: focus is trapped inside the popover, but document page scroll is not locked and pointer interactions outside of it remain enabled.
    *
+   * On touch devices, a `true` modal blocks outside taps but leaves the page scrollable unless the popup spans nearly the full viewport width, matching native iOS behavior.
+   *
    * When `modal` is `true`, focus trapping is enabled only if `<Popover.Close>` is rendered
    * inside `<Popover.Popup>`. It can be visually hidden with your own CSS if needed, such as
    * Tailwind's `sr-only` utility.

package/popover/root/PopoverRoot.d.ts

@@ -44,6 +44,8 @@ export interface PopoverRootProps<Payload = unknown> {
    * - `false`: user interaction with the rest of the document is allowed.
    * - `'trap-focus'`: focus is trapped inside the popover, but document page scroll is not locked and pointer interactions outside of it remain enabled.
    *
+   * On touch devices, a `true` modal blocks outside taps but leaves the page scrollable unless the popup spans nearly the full viewport width, matching native iOS behavior.
+   *
    * When `modal` is `true`, focus trapping is enabled only if `<Popover.Close>` is rendered
    * inside `<Popover.Popup>`. It can be visually hidden with your own CSS if needed, such as
    * Tailwind's `sr-only` utility.

package/popover/root/PopoverRoot.js

@@ -7,14 +7,12 @@ Object.defineProperty(exports, "__esModule", {
 });
 exports.PopoverRoot = PopoverRoot;
 var React = _interopRequireWildcard(require("react"));
-var _empty = require("@base-ui/utils/empty");
 var _floatingUiReact = require("../../floating-ui-react");
 var _PopoverRootContext = require("./PopoverRootContext");
 var _PopoverStore = require("../store/PopoverStore");
 var _createBaseUIEventDetails = require("../../internals/createBaseUIEventDetails");
 var _reasons = require("../../internals/reasons");
 var _popups = require("../../utils/popups");
-var _mergeProps = require("../../merge-props");
 var _jsxRuntime = require("react/jsx-runtime");
 function PopoverRootComponent({
   props
@@ -30,20 +28,18 @@ function PopoverRootComponent({
     triggerId: triggerIdProp,
     defaultTriggerId: defaultTriggerIdProp = null
   } = props;
-  const store = _PopoverStore.PopoverStore.useStore(handle?.store, {
+  const store = usePopoverRootStore(handle, {
     modal,
     open: defaultOpen,
     openProp,
     activeTriggerId: defaultTriggerIdProp,
     triggerIdProp
   });
-  (0, _popups.useInitialOpenSync)(store, openProp, defaultOpen, defaultTriggerIdProp);
   store.useControlledProp('openProp', openProp);
   store.useControlledProp('triggerIdProp', triggerIdProp);
   const open = store.useState('open');
   const mounted = store.useState('mounted');
   const payload = store.useState('payload');
-  const nested = (0, _floatingUiReact.useFloatingParentNodeId)() != null;
   store.useContextCallback('onOpenChange', onOpenChange);
   store.useContextCallback('onOpenChangeComplete', onOpenChangeComplete);
   (0, _popups.usePopupRootSync)(store, open);
@@ -57,28 +53,24 @@ function PopoverRootComponent({
     });
   });
   store.useSyncedValues({
-    modal,
-    nested
+    modal
   });
   React.useEffect(() => {
     if (!open) {
       store.context.stickIfOpenTimeout.clear();
     }
   }, [store, open]);
-  const handleImperativeClose = React.useCallback(() => {
-    store.setOpen(false, (0, _createBaseUIEventDetails.createChangeEventDetails)(_reasons.REASONS.imperativeAction));
-  }, [store]);
   React.useImperativeHandle(props.actionsRef, () => ({
     unmount: forceUnmount,
-    close: handleImperativeClose
-  }), [forceUnmount, handleImperativeClose]);
+    close: () => store.setOpen(false, (0, _createBaseUIEventDetails.createChangeEventDetails)(_reasons.REASONS.imperativeAction))
+  }), [forceUnmount, store]);
   const shouldRenderInteractions = open || mounted;
-  const popoverContext = React.useMemo(() => ({
-    store
-  }), [store]);
   return /*#__PURE__*/(0, _jsxRuntime.jsxs)(_PopoverRootContext.PopoverRootContext.Provider, {
-    value: popoverContext,
-    children: [shouldRenderInteractions && /*#__PURE__*/(0, _jsxRuntime.jsx)(PopoverInteractions, {
+    value: store,
+    children: [handle && /*#__PURE__*/(0, _jsxRuntime.jsx)(_popups.PopupHandleAttachment, {
+      handle: handle,
+      store: store
+    }), shouldRenderInteractions && /*#__PURE__*/(0, _jsxRuntime.jsx)(PopoverInteractions, {
       store: store,
       modal: modal
     }), typeof children === 'function' ? children({
@@ -105,6 +97,16 @@ function PopoverRoot(props) {
     })
   });
 }
+function usePopoverRootStore(handle, 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.
+  const store = (0, _popups.usePopupRootStore)((floatingId, nested) => new _PopoverStore.PopoverStore(initialState, floatingId, nested));
+
+  // Popover-specific: dispose the patient-click timeout held in the store's context on unmount.
+  React.useEffect(() => store.context.stickIfOpenTimeout.disposeEffect(), [store]);
+  return store;
+}
 function PopoverInteractions({
   store,
   modal
@@ -118,12 +120,17 @@ function PopoverInteractions({
       touch: 'sloppy'
     }
   });
-  const activeTriggerProps = dismiss.reference ?? _empty.EMPTY_OBJECT;
-  const inactiveTriggerProps = dismiss.trigger ?? _empty.EMPTY_OBJECT;
-  const popupProps = React.useMemo(() => (0, _mergeProps.mergeProps)(_popups.FOCUSABLE_POPUP_PROPS, dismiss.floating), [dismiss.floating]);
+
+  // `useDismiss` is not given an `enabled` option, so it always returns both prop bags. Restore
+  // the `EMPTY_OBJECT` fallbacks if that ever changes: the store fields are non-optional.
+  // `dismiss.trigger` is always the same object as `dismiss.reference`.
+  const triggerProps = dismiss.reference;
+  // PopoverPopup already spreads `FOCUSABLE_POPUP_PROPS` directly, so the popup
+  // props only need to carry the dismiss handlers.
+  const popupProps = dismiss.floating;
   (0, _popups.usePopupInteractionProps)(store, {
-    activeTriggerProps,
-    inactiveTriggerProps,
+    activeTriggerProps: triggerProps,
+    inactiveTriggerProps: triggerProps,
     popupProps
   });
   return null;

package/popover/root/PopoverRoot.mjs

@@ -1,14 +1,12 @@
 'use client';
 
 import * as React from 'react';
-import { EMPTY_OBJECT } from '@base-ui/utils/empty';
-import { useDismiss, FloatingTree, useFloatingParentNodeId } from "../../floating-ui-react/index.mjs";
+import { useDismiss, FloatingTree } from "../../floating-ui-react/index.mjs";
 import { PopoverRootContext, usePopoverRootContext } from "./PopoverRootContext.mjs";
 import { PopoverStore } from "../store/PopoverStore.mjs";
 import { createChangeEventDetails } from "../../internals/createBaseUIEventDetails.mjs";
 import { REASONS } from "../../internals/reasons.mjs";
-import { FOCUSABLE_POPUP_PROPS, useImplicitActiveTrigger, useInitialOpenSync, useOpenStateTransitions, usePopupInteractionProps, usePopupRootSync } from "../../utils/popups/index.mjs";
-import { mergeProps } from "../../merge-props/index.mjs";
+import { PopupHandleAttachment, useImplicitActiveTrigger, usePopupRootStore, useOpenStateTransitions, usePopupInteractionProps, usePopupRootSync } from "../../utils/popups/index.mjs";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 function PopoverRootComponent({
   props
@@ -24,20 +22,18 @@ function PopoverRootComponent({
     triggerId: triggerIdProp,
     defaultTriggerId: defaultTriggerIdProp = null
   } = props;
-  const store = PopoverStore.useStore(handle?.store, {
+  const store = usePopoverRootStore(handle, {
     modal,
     open: defaultOpen,
     openProp,
     activeTriggerId: defaultTriggerIdProp,
     triggerIdProp
   });
-  useInitialOpenSync(store, openProp, defaultOpen, defaultTriggerIdProp);
   store.useControlledProp('openProp', openProp);
   store.useControlledProp('triggerIdProp', triggerIdProp);
   const open = store.useState('open');
   const mounted = store.useState('mounted');
   const payload = store.useState('payload');
-  const nested = useFloatingParentNodeId() != null;
   store.useContextCallback('onOpenChange', onOpenChange);
   store.useContextCallback('onOpenChangeComplete', onOpenChangeComplete);
   usePopupRootSync(store, open);
@@ -51,28 +47,24 @@ function PopoverRootComponent({
     });
   });
   store.useSyncedValues({
-    modal,
-    nested
+    modal
   });
   React.useEffect(() => {
     if (!open) {
       store.context.stickIfOpenTimeout.clear();
     }
   }, [store, open]);
-  const handleImperativeClose = React.useCallback(() => {
-    store.setOpen(false, createChangeEventDetails(REASONS.imperativeAction));
-  }, [store]);
   React.useImperativeHandle(props.actionsRef, () => ({
     unmount: forceUnmount,
-    close: handleImperativeClose
-  }), [forceUnmount, handleImperativeClose]);
+    close: () => store.setOpen(false, createChangeEventDetails(REASONS.imperativeAction))
+  }), [forceUnmount, store]);
   const shouldRenderInteractions = open || mounted;
-  const popoverContext = React.useMemo(() => ({
-    store
-  }), [store]);
   return /*#__PURE__*/_jsxs(PopoverRootContext.Provider, {
-    value: popoverContext,
-    children: [shouldRenderInteractions && /*#__PURE__*/_jsx(PopoverInteractions, {
+    value: store,
+    children: [handle && /*#__PURE__*/_jsx(PopupHandleAttachment, {
+      handle: handle,
+      store: store
+    }), shouldRenderInteractions && /*#__PURE__*/_jsx(PopoverInteractions, {
       store: store,
       modal: modal
     }), typeof children === 'function' ? children({
@@ -99,6 +91,16 @@ export function PopoverRoot(props) {
     })
   });
 }
+function usePopoverRootStore(handle, 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.
+  const store = usePopupRootStore((floatingId, nested) => new PopoverStore(initialState, floatingId, nested));
+
+  // Popover-specific: dispose the patient-click timeout held in the store's context on unmount.
+  React.useEffect(() => store.context.stickIfOpenTimeout.disposeEffect(), [store]);
+  return store;
+}
 function PopoverInteractions({
   store,
   modal
@@ -112,12 +114,17 @@ function PopoverInteractions({
       touch: 'sloppy'
     }
   });
-  const activeTriggerProps = dismiss.reference ?? EMPTY_OBJECT;
-  const inactiveTriggerProps = dismiss.trigger ?? EMPTY_OBJECT;
-  const popupProps = React.useMemo(() => mergeProps(FOCUSABLE_POPUP_PROPS, dismiss.floating), [dismiss.floating]);
+
+  // `useDismiss` is not given an `enabled` option, so it always returns both prop bags. Restore
+  // the `EMPTY_OBJECT` fallbacks if that ever changes: the store fields are non-optional.
+  // `dismiss.trigger` is always the same object as `dismiss.reference`.
+  const triggerProps = dismiss.reference;
+  // PopoverPopup already spreads `FOCUSABLE_POPUP_PROPS` directly, so the popup
+  // props only need to carry the dismiss handlers.
+  const popupProps = dismiss.floating;
   usePopupInteractionProps(store, {
-    activeTriggerProps,
-    inactiveTriggerProps,
+    activeTriggerProps: triggerProps,
+    inactiveTriggerProps: triggerProps,
     popupProps
   });
   return null;

package/popover/root/PopoverRootContext.d.mts

@@ -1,8 +1,6 @@
 import * as React from 'react';
 import type { PopoverStore } from "../store/PopoverStore.mjs";
-export interface PopoverRootContext<Payload = unknown> {
-  store: PopoverStore<Payload>;
-}
+export type PopoverRootContext<Payload = unknown> = PopoverStore<Payload>;
 export declare const PopoverRootContext: React.Context<PopoverRootContext<unknown> | undefined>;
 export declare function usePopoverRootContext(optional?: false): PopoverRootContext;
 export declare function usePopoverRootContext(optional: true): PopoverRootContext | undefined;

package/popover/root/PopoverRootContext.d.ts

@@ -1,8 +1,6 @@
 import * as React from 'react';
 import type { PopoverStore } from "../store/PopoverStore.js";
-export interface PopoverRootContext<Payload = unknown> {
-  store: PopoverStore<Payload>;
-}
+export type PopoverRootContext<Payload = unknown> = PopoverStore<Payload>;
 export declare const PopoverRootContext: React.Context<PopoverRootContext<unknown> | undefined>;
 export declare function usePopoverRootContext(optional?: false): PopoverRootContext;
 export declare function usePopoverRootContext(optional: true): PopoverRootContext | undefined;

package/popover/store/PopoverHandle.d.mts

@@ -1,24 +1,32 @@
-import { PopoverStore } from "./PopoverStore.mjs";
-export declare class PopoverHandle<Payload> {
-  /**
-   * Internal store holding the popover's state.
-   * @internal
-   */
-  readonly store: PopoverStore<Payload>;
+import { PopoverStore, type PopoverHandleStore } from "./PopoverStore.mjs";
+import { BasePopupHandle } from "../../utils/popups/popupHandle.mjs";
+/**
+ * Controls a Popover imperatively and associates detached `Popover.Trigger` components with a
+ * `Popover.Root`. Create one with `Popover.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 PopoverHandle<Payload> extends BasePopupHandle<PopoverHandleStore<Payload>, PopoverStore<Payload>> {
   constructor();
   /**
    * Opens the popover and associates it with the trigger with the given id.
-   * The trigger must be a Popover.Trigger component with this handle passed as a prop.
    *
-   * @param triggerId ID of the trigger to associate with the popover.
+   * 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 popover. The trigger must be a matching
+   * `Popover.Trigger` with this handle passed as a prop.
    */
   open(triggerId: string): void;
   /**
    * Closes the popover.
+   *
+   * This method should only be called in an event handler or an effect (not during rendering).
    */
   close(): void;
   /**
-   * Indicates whether the popover is currently open.
+   * Whether the popover is currently open. Returns `false` while no root is attached to the handle.
    */
   get isOpen(): boolean;
 }

package/popover/store/PopoverHandle.d.ts

@@ -1,24 +1,32 @@
-import { PopoverStore } from "./PopoverStore.js";
-export declare class PopoverHandle<Payload> {
-  /**
-   * Internal store holding the popover's state.
-   * @internal
-   */
-  readonly store: PopoverStore<Payload>;
+import { PopoverStore, type PopoverHandleStore } from "./PopoverStore.js";
+import { BasePopupHandle } from "../../utils/popups/popupHandle.js";
+/**
+ * Controls a Popover imperatively and associates detached `Popover.Trigger` components with a
+ * `Popover.Root`. Create one with `Popover.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 PopoverHandle<Payload> extends BasePopupHandle<PopoverHandleStore<Payload>, PopoverStore<Payload>> {
   constructor();
   /**
    * Opens the popover and associates it with the trigger with the given id.
-   * The trigger must be a Popover.Trigger component with this handle passed as a prop.
    *
-   * @param triggerId ID of the trigger to associate with the popover.
+   * 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 popover. The trigger must be a matching
+   * `Popover.Trigger` with this handle passed as a prop.
    */
   open(triggerId: string): void;
   /**
    * Closes the popover.
+   *
+   * This method should only be called in an event handler or an effect (not during rendering).
    */
   close(): void;
   /**
-   * Indicates whether the popover is currently open.
+   * Whether the popover is currently open. Returns `false` while no root is attached to the handle.
    */
   get isOpen(): boolean;
 }

package/popover/store/PopoverHandle.js

@@ -1,51 +1,51 @@
 "use strict";
 
-var _interopRequireDefault = require("@babel/runtime/helpers/interopRequireDefault").default;
 Object.defineProperty(exports, "__esModule", {
   value: true
 });
 exports.PopoverHandle = void 0;
 exports.createPopoverHandle = createPopoverHandle;
-var _formatErrorMessage2 = _interopRequireDefault(require("@base-ui/utils/formatErrorMessage"));
-var _createBaseUIEventDetails = require("../../internals/createBaseUIEventDetails");
-var _reasons = require("../../internals/reasons");
 var _PopoverStore = require("./PopoverStore");
-class PopoverHandle {
-  /**
-   * Internal store holding the popover's state.
-   * @internal
-   */
-
+var _popupHandle = require("../../utils/popups/popupHandle");
+/**
+ * Controls a Popover imperatively and associates detached `Popover.Trigger` components with a
+ * `Popover.Root`. Create one with `Popover.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 PopoverHandle extends _popupHandle.BasePopupHandle {
   constructor() {
-    this.store = new _PopoverStore.PopoverStore();
+    super((0, _PopoverStore.createNullPopoverStore)(), 'Popover');
   }
 
   /**
    * Opens the popover and associates it with the trigger with the given id.
-   * The trigger must be a Popover.Trigger component with this handle passed as a prop.
    *
-   * @param triggerId ID of the trigger to associate with the popover.
+   * 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 popover. The trigger must be a matching
+   * `Popover.Trigger` with this handle passed as a prop.
    */
   open(triggerId) {
-    const triggerElement = triggerId ? this.store.context.triggerElements.getById(triggerId) ?? undefined : undefined;
-    if (triggerId && !triggerElement) {
-      throw new Error(process.env.NODE_ENV !== "production" ? `Base UI: PopoverHandle.open: No trigger found with id "${triggerId}".` : (0, _formatErrorMessage2.default)(80, triggerId));
-    }
-    this.store.setOpen(true, (0, _createBaseUIEventDetails.createChangeEventDetails)(_reasons.REASONS.imperativeAction, undefined, triggerElement));
+    this.openByTrigger(triggerId);
   }
 
   /**
    * Closes the popover.
+   *
+   * This method should only be called in an event handler or an effect (not during rendering).
    */
   close() {
-    this.store.setOpen(false, (0, _createBaseUIEventDetails.createChangeEventDetails)(_reasons.REASONS.imperativeAction, undefined, undefined));
+    this.closePopup();
   }
 
   /**
-   * Indicates whether the popover is currently open.
+   * Whether the popover 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/popover/store/PopoverHandle.mjs

@@ -1,43 +1,45 @@
-import _formatErrorMessage from "@base-ui/utils/formatErrorMessage";
-import { createChangeEventDetails } from "../../internals/createBaseUIEventDetails.mjs";
-import { REASONS } from "../../internals/reasons.mjs";
-import { PopoverStore } from "./PopoverStore.mjs";
-export class PopoverHandle {
-  /**
-   * Internal store holding the popover's state.
-   * @internal
-   */
+import { createNullPopoverStore } from "./PopoverStore.mjs";
+import { BasePopupHandle } from "../../utils/popups/popupHandle.mjs";
 
+/**
+ * Controls a Popover imperatively and associates detached `Popover.Trigger` components with a
+ * `Popover.Root`. Create one with `Popover.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 PopoverHandle extends BasePopupHandle {
   constructor() {
-    this.store = new PopoverStore();
+    super(createNullPopoverStore(), 'Popover');
   }
 
   /**
    * Opens the popover and associates it with the trigger with the given id.
-   * The trigger must be a Popover.Trigger component with this handle passed as a prop.
    *
-   * @param triggerId ID of the trigger to associate with the popover.
+   * 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 popover. The trigger must be a matching
+   * `Popover.Trigger` with this handle passed as a prop.
    */
   open(triggerId) {
-    const triggerElement = triggerId ? this.store.context.triggerElements.getById(triggerId) ?? undefined : undefined;
-    if (triggerId && !triggerElement) {
-      throw new Error(process.env.NODE_ENV !== "production" ? `Base UI: PopoverHandle.open: No trigger found with id "${triggerId}".` : _formatErrorMessage(80, triggerId));
-    }
-    this.store.setOpen(true, createChangeEventDetails(REASONS.imperativeAction, undefined, triggerElement));
+    this.openByTrigger(triggerId);
   }
 
   /**
    * Closes the popover.
+   *
+   * This method should only be called in an event handler or an effect (not during rendering).
    */
   close() {
-    this.store.setOpen(false, createChangeEventDetails(REASONS.imperativeAction, undefined, undefined));
+    this.closePopup();
   }
 
   /**
-   * Indicates whether the popover is currently open.
+   * Whether the popover 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/popover/store/PopoverStore.d.mts

@@ -3,7 +3,8 @@ import { ReactStore } from '@base-ui/utils/store';
 import { Timeout } from '@base-ui/utils/useTimeout';
 import { type InteractionType } from '@base-ui/utils/useEnhancedClickHandler';
 import { type PopoverRoot } from "../root/PopoverRoot.mjs";
-import { PopupStoreContext, PopupStoreState } from "../../utils/popups/index.mjs";
+import { PopupStoreContext, PopupStoreState, type PopupTriggerStoreKeys } from "../../utils/popups/index.mjs";
+import type { AdaptiveOriginMiddleware } from "../../utils/adaptiveOriginConstants.mjs";
 export type State<Payload> = PopupStoreState<Payload> & {
   disabled: boolean;
   instantType: 'dismiss' | 'click' | 'focus' | 'trigger-change' | undefined;
@@ -12,17 +13,14 @@ export type State<Payload> = PopupStoreState<Payload> & {
   openMethod: InteractionType | null;
   openChangeReason: PopoverRoot.ChangeEventReason | null;
   stickIfOpen: boolean;
-  nested: boolean;
   titleElementId: string | undefined;
   descriptionElementId: string | undefined;
   openOnHover: boolean;
   closeDelay: number;
-  hasViewport: boolean;
+  adaptiveOrigin: AdaptiveOriginMiddleware | undefined;
 };
 type Context = PopupStoreContext<PopoverRoot.ChangeEventDetails> & {
   readonly popupRef: React.RefObject<HTMLElement | null>;
-  readonly backdropRef: React.RefObject<HTMLDivElement | null>;
-  readonly internalBackdropRef: React.RefObject<HTMLDivElement | null>;
   readonly triggerFocusTargetRef: React.RefObject<HTMLElement | null>;
   readonly beforeContentFocusGuardRef: React.RefObject<HTMLElement | null>;
   readonly stickIfOpenTimeout: Timeout;
@@ -381,13 +379,27 @@ declare const selectors: {
   descriptionElementId: (state: State<unknown>) => string | undefined;
   openOnHover: (state: State<unknown>) => boolean;
   closeDelay: (state: State<unknown>) => number;
-  hasViewport: (state: State<unknown>) => boolean;
+  adaptiveOrigin: (state: State<unknown>) => AdaptiveOriginMiddleware | undefined;
 };
+type Selectors = typeof selectors;
+/**
+ * The store view that detached handle-backed triggers read from. Both the real `PopoverStore` 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 PopoverHandleStore<Payload> = Pick<PopoverStore<Payload>, PopupTriggerStoreKeys | 'setOpen'>;
 export declare class PopoverStore<Payload> extends ReactStore<Readonly<State<Payload>>, Context, Selectors> {
-  constructor(initialState?: Partial<State<Payload>>, floatingId?: string | undefined, nested?: boolean);
+  constructor(initialState: Partial<State<Payload>>, floatingId: string | undefined, nested: boolean);
   setOpen: (nextOpen: boolean, eventDetails: Omit<PopoverRoot.ChangeEventDetails, 'preventUnmountOnClose'>) => void;
-  static useStore<Payload>(externalStore: PopoverStore<Payload> | undefined, initialState: Partial<State<Payload>>): PopoverStore<Payload>;
-  private disposeEffect;
 }
-type Selectors = typeof selectors;
+/**
+ * Creates the inert fallback store used by detached handle-backed triggers while no
+ * `Popover.Root` is attached. It preserves a popover-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 createNullPopoverStore<Payload>(): PopoverHandleStore<Payload>;
 export {};

package/popover/store/PopoverStore.d.ts

@@ -3,7 +3,8 @@ import { ReactStore } from '@base-ui/utils/store';
 import { Timeout } from '@base-ui/utils/useTimeout';
 import { type InteractionType } from '@base-ui/utils/useEnhancedClickHandler';
 import { type PopoverRoot } from "../root/PopoverRoot.js";
-import { PopupStoreContext, PopupStoreState } from "../../utils/popups/index.js";
+import { PopupStoreContext, PopupStoreState, type PopupTriggerStoreKeys } from "../../utils/popups/index.js";
+import type { AdaptiveOriginMiddleware } from "../../utils/adaptiveOriginConstants.js";
 export type State<Payload> = PopupStoreState<Payload> & {
   disabled: boolean;
   instantType: 'dismiss' | 'click' | 'focus' | 'trigger-change' | undefined;
@@ -12,17 +13,14 @@ export type State<Payload> = PopupStoreState<Payload> & {
   openMethod: InteractionType | null;
   openChangeReason: PopoverRoot.ChangeEventReason | null;
   stickIfOpen: boolean;
-  nested: boolean;
   titleElementId: string | undefined;
   descriptionElementId: string | undefined;
   openOnHover: boolean;
   closeDelay: number;
-  hasViewport: boolean;
+  adaptiveOrigin: AdaptiveOriginMiddleware | undefined;
 };
 type Context = PopupStoreContext<PopoverRoot.ChangeEventDetails> & {
   readonly popupRef: React.RefObject<HTMLElement | null>;
-  readonly backdropRef: React.RefObject<HTMLDivElement | null>;
-  readonly internalBackdropRef: React.RefObject<HTMLDivElement | null>;
   readonly triggerFocusTargetRef: React.RefObject<HTMLElement | null>;
   readonly beforeContentFocusGuardRef: React.RefObject<HTMLElement | null>;
   readonly stickIfOpenTimeout: Timeout;
@@ -381,13 +379,27 @@ declare const selectors: {
   descriptionElementId: (state: State<unknown>) => string | undefined;
   openOnHover: (state: State<unknown>) => boolean;
   closeDelay: (state: State<unknown>) => number;
-  hasViewport: (state: State<unknown>) => boolean;
+  adaptiveOrigin: (state: State<unknown>) => AdaptiveOriginMiddleware | undefined;
 };
+type Selectors = typeof selectors;
+/**
+ * The store view that detached handle-backed triggers read from. Both the real `PopoverStore` 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 PopoverHandleStore<Payload> = Pick<PopoverStore<Payload>, PopupTriggerStoreKeys | 'setOpen'>;
 export declare class PopoverStore<Payload> extends ReactStore<Readonly<State<Payload>>, Context, Selectors> {
-  constructor(initialState?: Partial<State<Payload>>, floatingId?: string | undefined, nested?: boolean);
+  constructor(initialState: Partial<State<Payload>>, floatingId: string | undefined, nested: boolean);
   setOpen: (nextOpen: boolean, eventDetails: Omit<PopoverRoot.ChangeEventDetails, 'preventUnmountOnClose'>) => void;
-  static useStore<Payload>(externalStore: PopoverStore<Payload> | undefined, initialState: Partial<State<Payload>>): PopoverStore<Payload>;
-  private disposeEffect;
 }
-type Selectors = typeof selectors;
+/**
+ * Creates the inert fallback store used by detached handle-backed triggers while no
+ * `Popover.Root` is attached. It preserves a popover-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 createNullPopoverStore<Payload>(): PopoverHandleStore<Payload>;
 export {};