@base-ui/react 1.6.0 → 1.7.0

package/preview-card/root/PreviewCardRoot.mjs

@@ -2,15 +2,13 @@
 
 import * as React from 'react';
 import { fastComponent } from '@base-ui/utils/fastHooks';
-import { EMPTY_OBJECT } from '@base-ui/utils/empty';
 import { useIsoLayoutEffect } from '@base-ui/utils/useIsoLayoutEffect';
 import { useDismiss, FloatingTree } from "../../floating-ui-react/index.mjs";
 import { PreviewCardRootContext, usePreviewCardRootContext } from "./PreviewCardContext.mjs";
 import { createChangeEventDetails } from "../../internals/createBaseUIEventDetails.mjs";
 import { REASONS } from "../../internals/reasons.mjs";
 import { PreviewCardStore } from "../store/PreviewCardStore.mjs";
-import { FOCUSABLE_POPUP_PROPS, useImplicitActiveTrigger, useInitialOpenSync, useOpenStateTransitions, usePopupInteractionProps } from "../../utils/popups/index.mjs";
-import { mergeProps } from "../../merge-props/index.mjs";
+import { PopupHandleAttachment, useImplicitActiveTrigger, usePopupRootStore, useOpenStateTransitions, usePopupInteractionProps } from "../../utils/popups/index.mjs";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 function PreviewCardRootComponent(props) {
   const {
@@ -24,13 +22,12 @@ function PreviewCardRootComponent(props) {
     defaultTriggerId: defaultTriggerIdProp = null,
     children
   } = props;
-  const store = PreviewCardStore.useStore(handle?.store, {
+  const store = usePopupRootStore((floatingId, nested) => new PreviewCardStore({
     open: defaultOpen,
     openProp,
     activeTriggerId: defaultTriggerIdProp,
     triggerIdProp
-  });
-  useInitialOpenSync(store, openProp, defaultOpen, defaultTriggerIdProp);
+  }, floatingId, nested));
   store.useControlledProp('openProp', openProp);
   store.useControlledProp('triggerIdProp', triggerIdProp);
   store.useContextCallback('onOpenChange', onOpenChange);
@@ -54,17 +51,17 @@ function PreviewCardRootComponent(props) {
       }
     }
   }, [store, activeTriggerId, open]);
-  const handleImperativeClose = React.useCallback(() => {
-    store.setOpen(false, createChangeEventDetails(REASONS.imperativeAction));
-  }, [store]);
   React.useImperativeHandle(actionsRef, () => ({
     unmount: forceUnmount,
-    close: handleImperativeClose
-  }), [forceUnmount, handleImperativeClose]);
+    close: () => store.setOpen(false, createChangeEventDetails(REASONS.imperativeAction))
+  }), [forceUnmount, store]);
   const shouldRenderInteractions = open || mounted;
   return /*#__PURE__*/_jsxs(PreviewCardRootContext.Provider, {
     value: store,
-    children: [shouldRenderInteractions && /*#__PURE__*/_jsx(PreviewCardInteractions, {
+    children: [handle && /*#__PURE__*/_jsx(PopupHandleAttachment, {
+      handle: handle,
+      store: store
+    }), shouldRenderInteractions && /*#__PURE__*/_jsx(PreviewCardInteractions, {
       store: store
     }), typeof children === 'function' ? children({
       payload
@@ -76,13 +73,13 @@ function PreviewCardInteractions({
 }) {
   const floatingRootContext = store.useState('floatingRootContext');
   const dismiss = useDismiss(floatingRootContext);
-  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 all three prop bags are always defined.
+  // `dismiss.trigger` is the same object as `dismiss.reference`.
   usePopupInteractionProps(store, {
-    activeTriggerProps,
-    inactiveTriggerProps,
-    popupProps
+    activeTriggerProps: dismiss.reference,
+    inactiveTriggerProps: dismiss.trigger,
+    popupProps: dismiss.floating
   });
   return null;
 }

package/preview-card/store/PreviewCardHandle.d.mts

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

package/preview-card/store/PreviewCardHandle.d.ts

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

package/preview-card/store/PreviewCardHandle.js

@@ -1,56 +1,51 @@
 "use strict";
 
-var _interopRequireDefault = require("@babel/runtime/helpers/interopRequireDefault").default;
 Object.defineProperty(exports, "__esModule", {
   value: true
 });
 exports.PreviewCardHandle = void 0;
 exports.createPreviewCardHandle = createPreviewCardHandle;
-var _formatErrorMessage2 = _interopRequireDefault(require("@base-ui/utils/formatErrorMessage"));
 var _PreviewCardStore = require("./PreviewCardStore");
-var _createBaseUIEventDetails = require("../../internals/createBaseUIEventDetails");
-var _reasons = require("../../internals/reasons");
+var _popupHandle = require("../../utils/popups/popupHandle");
 /**
- * A handle to control a preview card imperatively and to associate detached triggers with it.
+ * Controls a PreviewCard imperatively and associates detached `PreviewCard.Trigger` components with
+ * a `PreviewCard.Root`. Create one with `PreviewCard.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 PreviewCardHandle {
-  /**
-   * Internal store holding the preview card state.
-   * @internal
-   */
-
+class PreviewCardHandle extends _popupHandle.BasePopupHandle {
   constructor() {
-    this.store = new _PreviewCardStore.PreviewCardStore();
+    super((0, _PreviewCardStore.createNullPreviewCardStore)(), 'PreviewCard');
   }
 
   /**
-   * Opens the preview card and associates it with the trigger with the given ID.
-   * The trigger must be a PreviewCard.Trigger component with this handle passed as a prop.
+   * Opens the preview card and associates it with the trigger with the given id.
    *
    * 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 preview card.
+   * @param triggerId ID of the trigger to associate with the preview card. The trigger must be a
+   * matching `PreviewCard.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: PreviewCardHandle.open: No trigger found with id "${triggerId}".` : (0, _formatErrorMessage2.default)(88, triggerId));
-    }
-    this.store.setOpen(true, (0, _createBaseUIEventDetails.createChangeEventDetails)(_reasons.REASONS.imperativeAction, undefined, triggerElement));
+    this.openByTrigger(triggerId);
   }
 
   /**
    * Closes the preview card.
+   *
+   * 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 preview card is currently open.
+   * Whether the preview card 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/preview-card/store/PreviewCardHandle.mjs

@@ -1,49 +1,45 @@
-import _formatErrorMessage from "@base-ui/utils/formatErrorMessage";
-import { PreviewCardStore } from "./PreviewCardStore.mjs";
-import { createChangeEventDetails } from "../../internals/createBaseUIEventDetails.mjs";
-import { REASONS } from "../../internals/reasons.mjs";
+import { createNullPreviewCardStore } from "./PreviewCardStore.mjs";
+import { BasePopupHandle } from "../../utils/popups/popupHandle.mjs";
 
 /**
- * A handle to control a preview card imperatively and to associate detached triggers with it.
+ * Controls a PreviewCard imperatively and associates detached `PreviewCard.Trigger` components with
+ * a `PreviewCard.Root`. Create one with `PreviewCard.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 PreviewCardHandle {
-  /**
-   * Internal store holding the preview card state.
-   * @internal
-   */
-
+export class PreviewCardHandle extends BasePopupHandle {
   constructor() {
-    this.store = new PreviewCardStore();
+    super(createNullPreviewCardStore(), 'PreviewCard');
   }
 
   /**
-   * Opens the preview card and associates it with the trigger with the given ID.
-   * The trigger must be a PreviewCard.Trigger component with this handle passed as a prop.
+   * Opens the preview card and associates it with the trigger with the given id.
    *
    * 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 preview card.
+   * @param triggerId ID of the trigger to associate with the preview card. The trigger must be a
+   * matching `PreviewCard.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: PreviewCardHandle.open: No trigger found with id "${triggerId}".` : _formatErrorMessage(88, triggerId));
-    }
-    this.store.setOpen(true, createChangeEventDetails(REASONS.imperativeAction, undefined, triggerElement));
+    this.openByTrigger(triggerId);
   }
 
   /**
    * Closes the preview card.
+   *
+   * 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 preview card is currently open.
+   * Whether the preview card 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/preview-card/store/PreviewCardStore.d.mts

@@ -1,13 +1,14 @@
 import * as React from 'react';
 import { ReactStore } from '@base-ui/utils/store';
-import { InlineRectCoords, PopupStoreContext, PopupStoreState } from "../../utils/popups/index.mjs";
+import { InlineRectCoords, PopupStoreContext, PopupStoreState, type PopupTriggerStoreKeys } from "../../utils/popups/index.mjs";
 import { type PreviewCardRoot } from "../root/PreviewCardRoot.mjs";
+import type { AdaptiveOriginMiddleware } from "../../utils/adaptiveOriginConstants.mjs";
 export type State<Payload> = PopupStoreState<Payload> & {
   instantType: 'dismiss' | 'focus' | undefined;
-  hasViewport: boolean;
+  adaptiveOrigin: AdaptiveOriginMiddleware | undefined;
+  closeDelay: number;
 };
 export type Context = PopupStoreContext<PreviewCardRoot.ChangeEventDetails> & {
-  closeDelayRef: React.RefObject<number>;
   inlineRectCoordsRef: React.MutableRefObject<InlineRectCoords | undefined>;
 };
 declare const selectors: {
@@ -354,11 +355,25 @@ declare const selectors: {
     popupProps: import("../../index.mjs").HTMLProps;
   }) => HTMLElement | null;
   instantType: (state: State<unknown>) => "dismiss" | "focus" | undefined;
-  hasViewport: (state: State<unknown>) => boolean;
+  adaptiveOrigin: (state: State<unknown>) => AdaptiveOriginMiddleware | undefined;
+  closeDelay: (state: State<unknown>) => number;
 };
-export declare class PreviewCardStore<Payload> extends ReactStore<Readonly<State<Payload>>, Context, typeof selectors> {
-  constructor(initialState?: Partial<State<Payload>>, floatingId?: string | undefined, nested?: boolean);
+type Selectors = typeof selectors;
+/**
+ * The store view that detached handle-backed triggers read from. Both the real `PreviewCardStore`
+ * and the inert fallback store satisfy it, so a trigger can read from whichever store the handle
+ * currently exposes. Narrowed to the trigger-data members a trigger uses; it exposes no popup-open
+ * mutator, so the inert fallback can be a plain `NullStore`.
+ */
+export type PreviewCardHandleStore<Payload> = Pick<PreviewCardStore<Payload>, PopupTriggerStoreKeys>;
+export declare class PreviewCardStore<Payload> extends ReactStore<Readonly<State<Payload>>, Context, Selectors> {
+  constructor(initialState: Partial<State<Payload>>, floatingId: string | undefined, nested: boolean);
   setOpen: (nextOpen: boolean, eventDetails: Omit<PreviewCardRoot.ChangeEventDetails, 'preventUnmountOnClose'>) => void;
-  static useStore<Payload>(externalStore: PreviewCardStore<Payload> | undefined, initialState?: Partial<State<Payload>>): PreviewCardStore<Payload>;
 }
+/**
+ * Creates the inert fallback store used by detached handle-backed triggers while no
+ * `PreviewCard.Root` is attached. It preserves a preview-card-specific trigger registry in context
+ * so detached triggers can register before migrating to the live root store.
+ */
+export declare function createNullPreviewCardStore<Payload>(): PreviewCardHandleStore<Payload>;
 export {};

package/preview-card/store/PreviewCardStore.d.ts

@@ -1,13 +1,14 @@
 import * as React from 'react';
 import { ReactStore } from '@base-ui/utils/store';
-import { InlineRectCoords, PopupStoreContext, PopupStoreState } from "../../utils/popups/index.js";
+import { InlineRectCoords, PopupStoreContext, PopupStoreState, type PopupTriggerStoreKeys } from "../../utils/popups/index.js";
 import { type PreviewCardRoot } from "../root/PreviewCardRoot.js";
+import type { AdaptiveOriginMiddleware } from "../../utils/adaptiveOriginConstants.js";
 export type State<Payload> = PopupStoreState<Payload> & {
   instantType: 'dismiss' | 'focus' | undefined;
-  hasViewport: boolean;
+  adaptiveOrigin: AdaptiveOriginMiddleware | undefined;
+  closeDelay: number;
 };
 export type Context = PopupStoreContext<PreviewCardRoot.ChangeEventDetails> & {
-  closeDelayRef: React.RefObject<number>;
   inlineRectCoordsRef: React.MutableRefObject<InlineRectCoords | undefined>;
 };
 declare const selectors: {
@@ -354,11 +355,25 @@ declare const selectors: {
     popupProps: import("../../index.js").HTMLProps;
   }) => HTMLElement | null;
   instantType: (state: State<unknown>) => "dismiss" | "focus" | undefined;
-  hasViewport: (state: State<unknown>) => boolean;
+  adaptiveOrigin: (state: State<unknown>) => AdaptiveOriginMiddleware | undefined;
+  closeDelay: (state: State<unknown>) => number;
 };
-export declare class PreviewCardStore<Payload> extends ReactStore<Readonly<State<Payload>>, Context, typeof selectors> {
-  constructor(initialState?: Partial<State<Payload>>, floatingId?: string | undefined, nested?: boolean);
+type Selectors = typeof selectors;
+/**
+ * The store view that detached handle-backed triggers read from. Both the real `PreviewCardStore`
+ * and the inert fallback store satisfy it, so a trigger can read from whichever store the handle
+ * currently exposes. Narrowed to the trigger-data members a trigger uses; it exposes no popup-open
+ * mutator, so the inert fallback can be a plain `NullStore`.
+ */
+export type PreviewCardHandleStore<Payload> = Pick<PreviewCardStore<Payload>, PopupTriggerStoreKeys>;
+export declare class PreviewCardStore<Payload> extends ReactStore<Readonly<State<Payload>>, Context, Selectors> {
+  constructor(initialState: Partial<State<Payload>>, floatingId: string | undefined, nested: boolean);
   setOpen: (nextOpen: boolean, eventDetails: Omit<PreviewCardRoot.ChangeEventDetails, 'preventUnmountOnClose'>) => void;
-  static useStore<Payload>(externalStore: PreviewCardStore<Payload> | undefined, initialState?: Partial<State<Payload>>): PreviewCardStore<Payload>;
 }
+/**
+ * Creates the inert fallback store used by detached handle-backed triggers while no
+ * `PreviewCard.Root` is attached. It preserves a preview-card-specific trigger registry in context
+ * so detached triggers can register before migrating to the live root store.
+ */
+export declare function createNullPreviewCardStore<Payload>(): PreviewCardHandleStore<Payload>;
 export {};

package/preview-card/store/PreviewCardStore.js

@@ -5,36 +5,31 @@ Object.defineProperty(exports, "__esModule", {
   value: true
 });
 exports.PreviewCardStore = void 0;
+exports.createNullPreviewCardStore = createNullPreviewCardStore;
 var React = _interopRequireWildcard(require("react"));
 var _store = require("@base-ui/utils/store");
 var _popups = require("../../utils/popups");
 var _reasons = require("../../internals/reasons");
+var _NullStore = require("../../utils/NullStore");
 var _constants = require("../utils/constants");
 const selectors = {
   ..._popups.popupStoreSelectors,
-  instantType: (0, _store.createSelector)(state => state.instantType),
-  hasViewport: (0, _store.createSelector)(state => state.hasViewport)
+  instantType: state => state.instantType,
+  adaptiveOrigin: state => state.adaptiveOrigin,
+  closeDelay: state => state.closeDelay
 };
+
+/**
+ * The store view that detached handle-backed triggers read from. Both the real `PreviewCardStore`
+ * and the inert fallback store satisfy it, so a trigger can read from whichever store the handle
+ * currently exposes. Narrowed to the trigger-data members a trigger uses; it exposes no popup-open
+ * mutator, so the inert fallback can be a plain `NullStore`.
+ */
+
 class PreviewCardStore extends _store.ReactStore {
-  constructor(initialState, floatingId, nested = false) {
+  constructor(initialState, floatingId, nested) {
     const triggerElements = new _popups.PopupTriggerMap();
-    const state = {
-      ...createInitialState(),
-      ...initialState
-    };
-    state.floatingRootContext = (0, _popups.createPopupFloatingRootContext)(triggerElements, floatingId, nested);
-    super(state, {
-      popupRef: /*#__PURE__*/React.createRef(),
-      onOpenChange: undefined,
-      onOpenChangeComplete: undefined,
-      triggerElements,
-      closeDelayRef: {
-        current: _constants.CLOSE_DELAY
-      },
-      inlineRectCoordsRef: {
-        current: undefined
-      }
-    }, selectors);
+    super(createInitialState(initialState, triggerElements, floatingId, nested), createInitialContext(triggerElements), selectors);
   }
   setOpen = (nextOpen, eventDetails) => {
     const {
@@ -51,19 +46,37 @@ class PreviewCardStore extends _store.ReactStore {
       }
     });
   };
-  static useStore(externalStore, initialState) {
-    /* eslint-disable react-hooks/rules-of-hooks */
-    const store = (0, _popups.usePopupStore)(externalStore, (floatingId, nested) => new PreviewCardStore(initialState, floatingId, nested)).store;
-    /* eslint-enable react-hooks/rules-of-hooks */
-
-    return store;
-  }
 }
+
+/**
+ * Creates the inert fallback store used by detached handle-backed triggers while no
+ * `PreviewCard.Root` is attached. It preserves a preview-card-specific trigger registry in context
+ * so detached triggers can register before migrating to the live root store.
+ */
 exports.PreviewCardStore = PreviewCardStore;
-function createInitialState() {
-  return {
+function createNullPreviewCardStore() {
+  const triggerElements = new _popups.PopupTriggerMap();
+  return new _NullStore.NullStore(Object.freeze(createInitialState(undefined, triggerElements)), Object.freeze(createInitialContext(triggerElements)), selectors);
+}
+function createInitialState(initialState, triggerElements, floatingId, nested = false) {
+  const state = {
     ...(0, _popups.createInitialPopupStoreState)(),
     instantType: undefined,
-    hasViewport: false
+    adaptiveOrigin: undefined,
+    closeDelay: _constants.CLOSE_DELAY,
+    ...initialState
+  };
+  state.floatingRootContext = (0, _popups.createPopupFloatingRootContext)(triggerElements, floatingId, nested);
+  return state;
+}
+function createInitialContext(triggerElements) {
+  return {
+    popupRef: /*#__PURE__*/React.createRef(),
+    onOpenChange: undefined,
+    onOpenChangeComplete: undefined,
+    triggerElements,
+    inlineRectCoordsRef: {
+      current: undefined
+    }
   };
 }

package/preview-card/store/PreviewCardStore.mjs

@@ -1,33 +1,27 @@
 import * as React from 'react';
-import { createSelector, ReactStore } from '@base-ui/utils/store';
-import { applyPopupOpenChange, createPopupFloatingRootContext, createInitialPopupStoreState, popupStoreSelectors, PopupTriggerMap, updateInlineRectCoords, usePopupStore } from "../../utils/popups/index.mjs";
+import { ReactStore } from '@base-ui/utils/store';
+import { applyPopupOpenChange, createPopupFloatingRootContext, createInitialPopupStoreState, popupStoreSelectors, PopupTriggerMap, updateInlineRectCoords } from "../../utils/popups/index.mjs";
 import { REASONS } from "../../internals/reasons.mjs";
+import { NullStore } from "../../utils/NullStore.mjs";
 import { CLOSE_DELAY } from "../utils/constants.mjs";
 const selectors = {
   ...popupStoreSelectors,
-  instantType: createSelector(state => state.instantType),
-  hasViewport: createSelector(state => state.hasViewport)
+  instantType: state => state.instantType,
+  adaptiveOrigin: state => state.adaptiveOrigin,
+  closeDelay: state => state.closeDelay
 };
+
+/**
+ * The store view that detached handle-backed triggers read from. Both the real `PreviewCardStore`
+ * and the inert fallback store satisfy it, so a trigger can read from whichever store the handle
+ * currently exposes. Narrowed to the trigger-data members a trigger uses; it exposes no popup-open
+ * mutator, so the inert fallback can be a plain `NullStore`.
+ */
+
 export class PreviewCardStore extends ReactStore {
-  constructor(initialState, floatingId, nested = false) {
+  constructor(initialState, floatingId, nested) {
     const triggerElements = new PopupTriggerMap();
-    const state = {
-      ...createInitialState(),
-      ...initialState
-    };
-    state.floatingRootContext = createPopupFloatingRootContext(triggerElements, floatingId, nested);
-    super(state, {
-      popupRef: /*#__PURE__*/React.createRef(),
-      onOpenChange: undefined,
-      onOpenChangeComplete: undefined,
-      triggerElements,
-      closeDelayRef: {
-        current: CLOSE_DELAY
-      },
-      inlineRectCoordsRef: {
-        current: undefined
-      }
-    }, selectors);
+    super(createInitialState(initialState, triggerElements, floatingId, nested), createInitialContext(triggerElements), selectors);
   }
   setOpen = (nextOpen, eventDetails) => {
     const {
@@ -44,18 +38,36 @@ export class PreviewCardStore extends ReactStore {
       }
     });
   };
-  static useStore(externalStore, initialState) {
-    /* eslint-disable react-hooks/rules-of-hooks */
-    const store = usePopupStore(externalStore, (floatingId, nested) => new PreviewCardStore(initialState, floatingId, nested)).store;
-    /* eslint-enable react-hooks/rules-of-hooks */
+}
 
-    return store;
-  }
+/**
+ * Creates the inert fallback store used by detached handle-backed triggers while no
+ * `PreviewCard.Root` is attached. It preserves a preview-card-specific trigger registry in context
+ * so detached triggers can register before migrating to the live root store.
+ */
+export function createNullPreviewCardStore() {
+  const triggerElements = new PopupTriggerMap();
+  return new NullStore(Object.freeze(createInitialState(undefined, triggerElements)), Object.freeze(createInitialContext(triggerElements)), selectors);
 }
-function createInitialState() {
-  return {
+function createInitialState(initialState, triggerElements, floatingId, nested = false) {
+  const state = {
     ...createInitialPopupStoreState(),
     instantType: undefined,
-    hasViewport: false
+    adaptiveOrigin: undefined,
+    closeDelay: CLOSE_DELAY,
+    ...initialState
+  };
+  state.floatingRootContext = createPopupFloatingRootContext(triggerElements, floatingId, nested);
+  return state;
+}
+function createInitialContext(triggerElements) {
+  return {
+    popupRef: /*#__PURE__*/React.createRef(),
+    onOpenChange: undefined,
+    onOpenChangeComplete: undefined,
+    triggerElements,
+    inlineRectCoordsRef: {
+      current: undefined
+    }
   };
 }

package/preview-card/trigger/PreviewCardTrigger.d.mts

@@ -17,7 +17,7 @@ export interface PreviewCardTriggerState {
    */
   open: boolean;
 }
-export interface PreviewCardTriggerProps<Payload = unknown> extends BaseUIComponentProps<'a', PreviewCardTriggerState> {
+export interface PreviewCardTriggerProps<Payload = unknown> extends BaseUIComponentProps<'a', PreviewCardTriggerState, React.ComponentPropsWithRef<'a'>> {
   /**
    * A handle to associate the trigger with a preview card.
    */

package/preview-card/trigger/PreviewCardTrigger.d.ts

@@ -17,7 +17,7 @@ export interface PreviewCardTriggerState {
    */
   open: boolean;
 }
-export interface PreviewCardTriggerProps<Payload = unknown> extends BaseUIComponentProps<'a', PreviewCardTriggerState> {
+export interface PreviewCardTriggerProps<Payload = unknown> extends BaseUIComponentProps<'a', PreviewCardTriggerState, React.ComponentPropsWithRef<'a'>> {
   /**
    * A handle to associate the trigger with a preview card.
    */