@base-ui/react 1.0.0 → 1.1.0

package/preview-card/positioner/PreviewCardPositioner.js

@@ -14,6 +14,8 @@ var _popupStateMapping = require("../../utils/popupStateMapping");
 var _PreviewCardPortalContext = require("../portal/PreviewCardPortalContext");
 var _constants = require("../../utils/constants");
 var _useRenderElement = require("../../utils/useRenderElement");
+var _adaptiveOriginMiddleware = require("../../utils/adaptiveOriginMiddleware");
+var _getDisabledMountTransitionStyles = require("../../utils/getDisabledMountTransitionStyles");
 var _jsxRuntime = require("react/jsx-runtime");
 /**
  * Positions the popup against the trigger.
@@ -39,13 +41,14 @@ const PreviewCardPositioner = exports.PreviewCardPositioner = /*#__PURE__*/React
     collisionAvoidance = _constants.POPUP_COLLISION_AVOIDANCE,
     ...elementProps
   } = componentProps;
-  const {
-    open,
-    mounted,
-    floatingRootContext,
-    setPositionerElement
-  } = (0, _PreviewCardContext.usePreviewCardRootContext)();
+  const store = (0, _PreviewCardContext.usePreviewCardRootContext)();
   const keepMounted = (0, _PreviewCardPortalContext.usePreviewCardPortalContext)();
+  const open = store.useState('open');
+  const mounted = store.useState('mounted');
+  const floatingRootContext = store.useState('floatingRootContext');
+  const instantType = store.useState('instantType');
+  const transitionStatus = store.useState('transitionStatus');
+  const hasViewport = store.useState('hasViewport');
   const positioning = (0, _useAnchorPositioning.useAnchorPositioning)({
     anchor,
     floatingRootContext,
@@ -61,7 +64,8 @@ const PreviewCardPositioner = exports.PreviewCardPositioner = /*#__PURE__*/React
     sticky,
     disableAnchorTracking,
     keepMounted,
-    collisionAvoidance
+    collisionAvoidance,
+    adaptiveOrigin: hasViewport ? _adaptiveOriginMiddleware.adaptiveOrigin : undefined
   });
   const defaultProps = React.useMemo(() => {
     const hiddenStyles = {};
@@ -81,8 +85,9 @@ const PreviewCardPositioner = exports.PreviewCardPositioner = /*#__PURE__*/React
     open,
     side: positioning.side,
     align: positioning.align,
-    anchorHidden: positioning.anchorHidden
-  }), [open, positioning.side, positioning.align, positioning.anchorHidden]);
+    anchorHidden: positioning.anchorHidden,
+    instant: instantType
+  }), [open, positioning.side, positioning.align, positioning.anchorHidden, instantType]);
   const contextValue = React.useMemo(() => ({
     side: positioning.side,
     align: positioning.align,
@@ -92,8 +97,8 @@ const PreviewCardPositioner = exports.PreviewCardPositioner = /*#__PURE__*/React
   }), [positioning.side, positioning.align, positioning.arrowRef, positioning.arrowUncentered, positioning.arrowStyles]);
   const element = (0, _useRenderElement.useRenderElement)('div', componentProps, {
     state,
-    ref: [setPositionerElement, forwardedRef],
-    props: [defaultProps, elementProps],
+    props: [defaultProps, (0, _getDisabledMountTransitionStyles.getDisabledMountTransitionStyles)(transitionStatus), elementProps],
+    ref: [forwardedRef, store.useStateSetter('positionerElement')],
     stateAttributesMapping: _popupStateMapping.popupStateMapping
   });
   return /*#__PURE__*/(0, _jsxRuntime.jsx)(_PreviewCardPositionerContext.PreviewCardPositionerContext.Provider, {

package/preview-card/root/PreviewCardContext.d.ts

@@ -1,27 +1,6 @@
 import * as React from 'react';
-import type { FloatingRootContext } from "../../floating-ui-react/index.js";
-import type { TransitionStatus } from "../../utils/useTransitionStatus.js";
-import type { HTMLProps } from "../../utils/types.js";
-import type { PreviewCardRoot } from "./PreviewCardRoot.js";
-export interface PreviewCardTriggerDelayConfig {
-  delay?: number;
-  closeDelay?: number;
-}
-export interface PreviewCardRootContext {
-  open: boolean;
-  setOpen: (open: boolean, eventDetails: PreviewCardRoot.ChangeEventDetails) => void;
-  setTriggerElement: (el: Element | null) => void;
-  positionerElement: HTMLElement | null;
-  setPositionerElement: (el: HTMLElement | null) => void;
-  mounted: boolean;
-  setMounted: React.Dispatch<React.SetStateAction<boolean>>;
-  triggerProps: HTMLProps;
-  popupProps: HTMLProps;
-  floatingRootContext: FloatingRootContext;
-  transitionStatus: TransitionStatus;
-  popupRef: React.RefObject<HTMLElement | null>;
-  onOpenChangeComplete: ((open: boolean) => void) | undefined;
-  writeDelayRefs: (config: PreviewCardTriggerDelayConfig) => void;
-}
-export declare const PreviewCardRootContext: React.Context<PreviewCardRootContext | undefined>;
-export declare function usePreviewCardRootContext(): PreviewCardRootContext;
+import { PreviewCardStore } from "../store/PreviewCardStore.js";
+export type PreviewCardRootContext<Payload = unknown> = PreviewCardStore<Payload>;
+export declare const PreviewCardRootContext: React.Context<PreviewCardRootContext<unknown> | undefined>;
+export declare function usePreviewCardRootContext(optional?: false): PreviewCardRootContext;
+export declare function usePreviewCardRootContext(optional: true): PreviewCardRootContext | undefined;

package/preview-card/root/PreviewCardContext.js

@@ -12,9 +12,9 @@ var _formatErrorMessage2 = _interopRequireDefault(require("@base-ui/utils/format
 var React = _interopRequireWildcard(require("react"));
 const PreviewCardRootContext = exports.PreviewCardRootContext = /*#__PURE__*/React.createContext(undefined);
 if (process.env.NODE_ENV !== "production") PreviewCardRootContext.displayName = "PreviewCardRootContext";
-function usePreviewCardRootContext() {
+function usePreviewCardRootContext(optional) {
   const context = React.useContext(PreviewCardRootContext);
-  if (context === undefined) {
+  if (context === undefined && !optional) {
     throw new Error(process.env.NODE_ENV !== "production" ? 'Base UI: PreviewCardRootContext is missing. PreviewCard parts must be placed within <PreviewCard.Root>.' : (0, _formatErrorMessage2.default)(50));
   }
   return context;

package/preview-card/root/PreviewCardRoot.d.ts

@@ -1,16 +1,17 @@
 import * as React from 'react';
 import { type BaseUIChangeEventDetails } from "../../utils/createBaseUIEventDetails.js";
 import { REASONS } from "../../utils/reasons.js";
+import { PayloadChildRenderFunction } from "../../utils/popups/index.js";
+import { PreviewCardHandle } from "../store/PreviewCardHandle.js";
 /**
  * Groups all parts of the preview card.
  * Doesn’t render its own HTML element.
  *
  * Documentation: [Base UI Preview Card](https://base-ui.com/react/components/preview-card)
  */
-export declare function PreviewCardRoot(props: PreviewCardRoot.Props): import("react/jsx-runtime").JSX.Element;
+export declare function PreviewCardRoot<Payload>(props: PreviewCardRoot.Props<Payload>): import("react/jsx-runtime").JSX.Element;
 export interface PreviewCardRootState {}
-export interface PreviewCardRootProps {
-  children?: React.ReactNode;
+export interface PreviewCardRootProps<Payload = unknown> {
   /**
    * Whether the preview card is initially open.
    *
@@ -32,20 +33,44 @@ export interface PreviewCardRootProps {
   onOpenChangeComplete?: (open: boolean) => void;
   /**
    * A ref to imperative actions.
-   * - `unmount`: When specified, the preview card will not be unmounted when closed.
-   * Instead, the `unmount` function must be called to unmount the preview card manually.
-   * Useful when the preview card's animation is controlled by an external library.
+   * - `unmount`: Unmounts the preview card popup.
+   * - `close`: Closes the preview card imperatively when called.
    */
-  actionsRef?: React.RefObject<PreviewCardRoot.Actions>;
+  actionsRef?: React.RefObject<PreviewCardRoot.Actions | null>;
+  /**
+   * A handle to associate the preview card with a trigger.
+   * If specified, allows external triggers to control the card's open state.
+   * Can be created with the PreviewCard.createHandle() method.
+   */
+  handle?: PreviewCardHandle<Payload>;
+  /**
+   * The content of the preview card.
+   * This can be a regular React node or a render function that receives the `payload` of the active trigger.
+   */
+  children?: React.ReactNode | PayloadChildRenderFunction<Payload>;
+  /**
+   * ID of the trigger that the preview card is associated with.
+   * This is useful in conjuntion with the `open` prop to create a controlled preview card.
+   * There's no need to specify this prop when the preview card is uncontrolled (i.e. when the `open` prop is not set).
+   */
+  triggerId?: string | null;
+  /**
+   * ID of the trigger that the preview card is associated with.
+   * This is useful in conjunction with the `defaultOpen` prop to create an initially open preview card.
+   */
+  defaultTriggerId?: string | null;
 }
 export interface PreviewCardRootActions {
   unmount: () => void;
+  close: () => void;
 }
-export type PreviewCardRootChangeEventReason = typeof REASONS.triggerHover | typeof REASONS.triggerFocus | typeof REASONS.triggerPress | typeof REASONS.outsidePress | typeof REASONS.escapeKey | typeof REASONS.none;
-export type PreviewCardRootChangeEventDetails = BaseUIChangeEventDetails<PreviewCardRoot.ChangeEventReason>;
+export type PreviewCardRootChangeEventReason = typeof REASONS.triggerHover | typeof REASONS.triggerFocus | typeof REASONS.triggerPress | typeof REASONS.outsidePress | typeof REASONS.escapeKey | typeof REASONS.imperativeAction | typeof REASONS.none;
+export type PreviewCardRootChangeEventDetails = BaseUIChangeEventDetails<PreviewCardRoot.ChangeEventReason> & {
+  preventUnmountOnClose(): void;
+};
 export declare namespace PreviewCardRoot {
   type State = PreviewCardRootState;
-  type Props = PreviewCardRootProps;
+  type Props<Payload = unknown> = PreviewCardRootProps<Payload>;
   type Actions = PreviewCardRootActions;
   type ChangeEventReason = PreviewCardRootChangeEventReason;
   type ChangeEventDetails = PreviewCardRootChangeEventDetails;

package/preview-card/root/PreviewCardRoot.js

@@ -7,16 +7,13 @@ Object.defineProperty(exports, "__esModule", {
 });
 exports.PreviewCardRoot = PreviewCardRoot;
 var React = _interopRequireWildcard(require("react"));
-var ReactDOM = _interopRequireWildcard(require("react-dom"));
-var _useControlled = require("@base-ui/utils/useControlled");
-var _useStableCallback = require("@base-ui/utils/useStableCallback");
+var _useIsoLayoutEffect = require("@base-ui/utils/useIsoLayoutEffect");
 var _floatingUiReact = require("../../floating-ui-react");
 var _PreviewCardContext = require("./PreviewCardContext");
-var _constants = require("../utils/constants");
+var _createBaseUIEventDetails = require("../../utils/createBaseUIEventDetails");
 var _reasons = require("../../utils/reasons");
-var _useFocusWithDelay = require("../../utils/interactions/useFocusWithDelay");
-var _useOpenChangeComplete = require("../../utils/useOpenChangeComplete");
-var _useTransitionStatus = require("../../utils/useTransitionStatus");
+var _PreviewCardStore = require("../store/PreviewCardStore");
+var _popups = require("../../utils/popups");
 var _jsxRuntime = require("react/jsx-runtime");
 /**
  * Groups all parts of the preview card.
@@ -26,122 +23,71 @@ var _jsxRuntime = require("react/jsx-runtime");
  */
 function PreviewCardRoot(props) {
   const {
-    open: externalOpen,
-    defaultOpen,
-    onOpenChange: onOpenChangeProp,
+    open: openProp,
+    defaultOpen = false,
+    onOpenChange,
     onOpenChangeComplete,
-    actionsRef
+    actionsRef,
+    handle,
+    triggerId: triggerIdProp,
+    defaultTriggerId: defaultTriggerIdProp = null,
+    children
   } = props;
-  const delayRef = React.useRef(_constants.OPEN_DELAY);
-  const closeDelayRef = React.useRef(_constants.CLOSE_DELAY);
-  const writeDelayRefs = (0, _useStableCallback.useStableCallback)(config => {
-    delayRef.current = config.delay ?? _constants.OPEN_DELAY;
-    closeDelayRef.current = config.closeDelay ?? _constants.CLOSE_DELAY;
+  const store = _PreviewCardStore.PreviewCardStore.useStore(handle?.store, {
+    open: openProp ?? defaultOpen,
+    activeTriggerId: triggerIdProp !== undefined ? triggerIdProp : defaultTriggerIdProp
   });
-  const [triggerElement, setTriggerElement] = React.useState(null);
-  const [positionerElement, setPositionerElement] = React.useState(null);
-  const [instantTypeState, setInstantTypeState] = React.useState();
-  const popupRef = React.useRef(null);
-  const [open, setOpenUnwrapped] = (0, _useControlled.useControlled)({
-    controlled: externalOpen,
-    default: defaultOpen,
-    name: 'PreviewCard',
-    state: 'open'
-  });
-  const onOpenChange = (0, _useStableCallback.useStableCallback)(onOpenChangeProp);
+  store.useControlledProp('open', openProp, defaultOpen);
+  store.useControlledProp('activeTriggerId', triggerIdProp, defaultTriggerIdProp);
+  store.useContextCallback('onOpenChange', onOpenChange);
+  store.useContextCallback('onOpenChangeComplete', onOpenChangeComplete);
+  const open = store.useState('open');
+  const activeTriggerId = store.useState('activeTriggerId');
+  const payload = store.useState('payload');
+  (0, _popups.useImplicitActiveTrigger)(store);
   const {
-    mounted,
-    setMounted,
-    transitionStatus
-  } = (0, _useTransitionStatus.useTransitionStatus)(open);
-  const handleUnmount = (0, _useStableCallback.useStableCallback)(() => {
-    setMounted(false);
-    onOpenChangeComplete?.(false);
-  });
-  (0, _useOpenChangeComplete.useOpenChangeComplete)({
-    enabled: !actionsRef,
-    open,
-    ref: popupRef,
-    onComplete() {
-      if (!open) {
-        handleUnmount();
+    forceUnmount
+  } = (0, _popups.useOpenStateTransitions)(open, store);
+  (0, _useIsoLayoutEffect.useIsoLayoutEffect)(() => {
+    if (open) {
+      if (activeTriggerId == null) {
+        store.set('payload', undefined);
       }
     }
-  });
+  }, [store, activeTriggerId, open]);
+  const handleImperativeClose = React.useCallback(() => {
+    store.setOpen(false, createPreviewCardEventDetails(store, _reasons.REASONS.imperativeAction));
+  }, [store]);
   React.useImperativeHandle(actionsRef, () => ({
-    unmount: handleUnmount
-  }), [handleUnmount]);
-  const setOpen = (0, _useStableCallback.useStableCallback)((nextOpen, eventDetails) => {
-    const isHover = eventDetails.reason === _reasons.REASONS.triggerHover;
-    const isFocusOpen = nextOpen && eventDetails.reason === _reasons.REASONS.triggerFocus;
-    const isDismissClose = !nextOpen && (eventDetails.reason === _reasons.REASONS.triggerPress || eventDetails.reason === _reasons.REASONS.escapeKey);
-    onOpenChange(nextOpen, eventDetails);
-    if (eventDetails.isCanceled) {
-      return;
-    }
-    function changeState() {
-      setOpenUnwrapped(nextOpen);
-    }
-    if (isHover) {
-      // If a hover reason is provided, we need to flush the state synchronously. This ensures
-      // `node.getAnimations()` knows about the new state.
-      ReactDOM.flushSync(changeState);
-    } else {
-      changeState();
-    }
-    if (isFocusOpen || isDismissClose) {
-      setInstantTypeState(isFocusOpen ? 'focus' : 'dismiss');
-    } else if (eventDetails.reason === _reasons.REASONS.triggerHover) {
-      setInstantTypeState(undefined);
-    }
-  });
-  const context = (0, _floatingUiReact.useFloatingRootContext)({
-    elements: {
-      reference: triggerElement,
-      floating: positionerElement
-    },
-    open,
-    onOpenChange: setOpen
-  });
-  const instantType = instantTypeState;
-  const getDelayValue = () => delayRef.current;
-  const getCloseDelayValue = () => closeDelayRef.current;
-  const hover = (0, _floatingUiReact.useHover)(context, {
-    mouseOnly: true,
-    move: false,
-    handleClose: (0, _floatingUiReact.safePolygon)(),
-    restMs: getDelayValue,
-    delay: () => ({
-      close: getCloseDelayValue()
-    })
-  });
-  const focus = (0, _useFocusWithDelay.useFocusWithDelay)(context, {
-    delay: getDelayValue
-  });
-  const dismiss = (0, _floatingUiReact.useDismiss)(context);
+    unmount: forceUnmount,
+    close: handleImperativeClose
+  }), [forceUnmount, handleImperativeClose]);
+  const floatingRootContext = store.useState('floatingRootContext');
+  const dismiss = (0, _floatingUiReact.useDismiss)(floatingRootContext);
   const {
     getReferenceProps,
+    getTriggerProps,
     getFloatingProps
-  } = (0, _floatingUiReact.useInteractions)([hover, focus, dismiss]);
-  const contextValue = React.useMemo(() => ({
-    open,
-    setOpen,
-    mounted,
-    setMounted,
-    setTriggerElement,
-    positionerElement,
-    setPositionerElement,
-    popupRef,
-    triggerProps: getReferenceProps(),
-    popupProps: getFloatingProps(),
-    floatingRootContext: context,
-    instantType,
-    transitionStatus,
-    onOpenChangeComplete,
-    writeDelayRefs
-  }), [open, setOpen, mounted, setMounted, positionerElement, getReferenceProps, getFloatingProps, context, instantType, transitionStatus, onOpenChangeComplete, writeDelayRefs]);
+  } = (0, _floatingUiReact.useInteractions)([dismiss]);
+  const activeTriggerProps = React.useMemo(() => getReferenceProps(), [getReferenceProps]);
+  const inactiveTriggerProps = React.useMemo(() => getTriggerProps(), [getTriggerProps]);
+  const popupProps = React.useMemo(() => getFloatingProps(), [getFloatingProps]);
+  store.useSyncedValues({
+    activeTriggerProps,
+    inactiveTriggerProps,
+    popupProps
+  });
   return /*#__PURE__*/(0, _jsxRuntime.jsx)(_PreviewCardContext.PreviewCardRootContext.Provider, {
-    value: contextValue,
-    children: props.children
+    value: store,
+    children: typeof children === 'function' ? children({
+      payload
+    }) : children
   });
+}
+function createPreviewCardEventDetails(store, reason) {
+  const details = (0, _createBaseUIEventDetails.createChangeEventDetails)(reason);
+  details.preventUnmountOnClose = () => {
+    store.set('preventUnmountingOnClose', true);
+  };
+  return details;
 }

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

@@ -0,0 +1,33 @@
+import { PreviewCardStore } from "./PreviewCardStore.js";
+/**
+ * A handle to control a preview card imperatively and to associate detached triggers with it.
+ */
+export declare class PreviewCardHandle<Payload> {
+  /**
+   * Internal store holding the preview card state.
+   * @internal
+   */
+  readonly store: 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.
+   *
+   * 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.
+   */
+  open(triggerId: string): void;
+  /**
+   * Closes the preview card.
+   */
+  close(): void;
+  /**
+   * Indicates whether the preview card is currently open.
+   */
+  get isOpen(): boolean;
+}
+/**
+ * Creates a new handle to connect a PreviewCard.Root with detached PreviewCard.Trigger components.
+ */
+export declare function createPreviewCardHandle<Payload>(): PreviewCardHandle<Payload>;

package/preview-card/store/PreviewCardHandle.js

@@ -0,0 +1,63 @@
+"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("../../utils/createBaseUIEventDetails");
+var _reasons = require("../../utils/reasons");
+/**
+ * A handle to control a preview card imperatively and to associate detached triggers with it.
+ */
+class PreviewCardHandle {
+  /**
+   * Internal store holding the preview card state.
+   * @internal
+   */
+
+  constructor() {
+    this.store = new _PreviewCardStore.PreviewCardStore();
+  }
+
+  /**
+   * 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.
+   *
+   * 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.
+   */
+  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));
+  }
+
+  /**
+   * Closes the preview card.
+   */
+  close() {
+    this.store.setOpen(false, (0, _createBaseUIEventDetails.createChangeEventDetails)(_reasons.REASONS.imperativeAction, undefined, undefined));
+  }
+
+  /**
+   * Indicates whether the preview card is currently open.
+   */
+  get isOpen() {
+    return this.store.state.open;
+  }
+}
+
+/**
+ * Creates a new handle to connect a PreviewCard.Root with detached PreviewCard.Trigger components.
+ */
+exports.PreviewCardHandle = PreviewCardHandle;
+function createPreviewCardHandle() {
+  return new PreviewCardHandle();
+}

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

@@ -0,0 +1,36 @@
+import * as React from 'react';
+import { ReactStore } from '@base-ui/utils/store';
+import { PopupStoreContext, PopupStoreState } from "../../utils/popups/index.js";
+import { type PreviewCardRoot } from "../root/PreviewCardRoot.js";
+export type State<Payload> = PopupStoreState<Payload> & {
+  instantType: 'dismiss' | 'focus' | undefined;
+  hasViewport: boolean;
+};
+export type Context = PopupStoreContext<PreviewCardRoot.ChangeEventDetails> & {
+  closeDelayRef: React.RefObject<number>;
+};
+declare const selectors: {
+  instantType: (state: State<unknown>) => "focus" | "dismiss" | undefined;
+  hasViewport: (state: State<unknown>) => boolean;
+  open: (state: PopupStoreState<unknown>) => boolean;
+  mounted: (state: PopupStoreState<unknown>) => boolean;
+  transitionStatus: (state: PopupStoreState<unknown>) => import("../../utils/useTransitionStatus.js").TransitionStatus;
+  floatingRootContext: (state: PopupStoreState<unknown>) => import("../../floating-ui-react/components/FloatingRootStore.js").FloatingRootStore;
+  preventUnmountingOnClose: (state: PopupStoreState<unknown>) => boolean;
+  payload: (state: PopupStoreState<unknown>) => unknown;
+  activeTriggerId: (state: PopupStoreState<unknown>) => string | null;
+  activeTriggerElement: (state: PopupStoreState<unknown>) => Element | null;
+  isTriggerActive: (state: PopupStoreState<unknown>, triggerId: string | undefined) => boolean;
+  isOpenedByTrigger: (state: PopupStoreState<unknown>, triggerId: string | undefined) => boolean;
+  isMountedByTrigger: (state: PopupStoreState<unknown>, triggerId: string | undefined) => boolean;
+  triggerProps: (state: PopupStoreState<unknown>, isActive: boolean) => import("../../index.js").HTMLProps;
+  popupProps: (state: PopupStoreState<unknown>) => import("../../index.js").HTMLProps;
+  popupElement: (state: PopupStoreState<unknown>) => HTMLElement | null;
+  positionerElement: (state: PopupStoreState<unknown>) => HTMLElement | null;
+};
+export declare class PreviewCardStore<Payload> extends ReactStore<Readonly<State<Payload>>, Context, typeof selectors> {
+  constructor(initialState?: Partial<State<Payload>>);
+  setOpen: (nextOpen: boolean, eventDetails: Omit<PreviewCardRoot.ChangeEventDetails, "preventUnmountOnClose">) => void;
+  static useStore<Payload>(externalStore: PreviewCardStore<Payload> | undefined, initialState?: Partial<State<Payload>>): PreviewCardStore<Payload>;
+}
+export {};

package/preview-card/store/PreviewCardStore.js

@@ -0,0 +1,105 @@
+"use strict";
+
+var _interopRequireWildcard = require("@babel/runtime/helpers/interopRequireWildcard").default;
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.PreviewCardStore = void 0;
+var React = _interopRequireWildcard(require("react"));
+var ReactDOM = _interopRequireWildcard(require("react-dom"));
+var _store = require("@base-ui/utils/store");
+var _useRefWithInit = require("@base-ui/utils/useRefWithInit");
+var _popups = require("../../utils/popups");
+var _floatingUiReact = require("../../floating-ui-react");
+var _reasons = require("../../utils/reasons");
+var _constants = require("../utils/constants");
+const selectors = {
+  ..._popups.popupStoreSelectors,
+  instantType: (0, _store.createSelector)(state => state.instantType),
+  hasViewport: (0, _store.createSelector)(state => state.hasViewport)
+};
+class PreviewCardStore extends _store.ReactStore {
+  constructor(initialState) {
+    super({
+      ...createInitialState(),
+      ...initialState
+    }, {
+      popupRef: /*#__PURE__*/React.createRef(),
+      onOpenChange: undefined,
+      onOpenChangeComplete: undefined,
+      triggerElements: new _popups.PopupTriggerMap(),
+      closeDelayRef: {
+        current: _constants.CLOSE_DELAY
+      }
+    }, selectors);
+  }
+  setOpen = (nextOpen, eventDetails) => {
+    const reason = eventDetails.reason;
+    const isHover = reason === _reasons.REASONS.triggerHover;
+    const isFocusOpen = nextOpen && reason === _reasons.REASONS.triggerFocus;
+    const isDismissClose = !nextOpen && (reason === _reasons.REASONS.triggerPress || reason === _reasons.REASONS.escapeKey);
+    eventDetails.preventUnmountOnClose = () => {
+      this.set('preventUnmountingOnClose', true);
+    };
+    this.context.onOpenChange?.(nextOpen, eventDetails);
+    if (eventDetails.isCanceled) {
+      return;
+    }
+    const changeState = () => {
+      const updatedState = {
+        open: nextOpen
+      };
+      if (isFocusOpen) {
+        updatedState.instantType = 'focus';
+      } else if (isDismissClose) {
+        updatedState.instantType = 'dismiss';
+      } else if (reason === _reasons.REASONS.triggerHover) {
+        updatedState.instantType = undefined;
+      }
+
+      // If a popup is closing, the `trigger` may be null.
+      // We want to keep the previous value so that exit animations are played and focus is returned correctly.
+      const newTriggerId = eventDetails.trigger?.id ?? null;
+      if (newTriggerId || nextOpen) {
+        updatedState.activeTriggerId = newTriggerId;
+        updatedState.activeTriggerElement = eventDetails.trigger ?? null;
+      }
+      this.update(updatedState);
+    };
+    if (isHover) {
+      // If a hover reason is provided, we need to flush the state synchronously. This ensures
+      // `node.getAnimations()` knows about the new state.
+      ReactDOM.flushSync(changeState);
+    } else {
+      changeState();
+    }
+  };
+  static useStore(externalStore, initialState) {
+    // eslint-disable-next-line react-hooks/rules-of-hooks
+    const internalStore = (0, _useRefWithInit.useRefWithInit)(() => {
+      return new PreviewCardStore(initialState);
+    }).current;
+    const store = externalStore ?? internalStore;
+
+    // eslint-disable-next-line react-hooks/rules-of-hooks
+    const floatingRootContext = (0, _floatingUiReact.useSyncedFloatingRootContext)({
+      popupStore: store,
+      onOpenChange: store.setOpen
+    });
+
+    // It's safe to set this here because when this code runs for the first time,
+    // nothing has had a chance to subscribe to the `store` yet.
+    // For subsequent renders, the `floatingRootContext` reference remains the same,
+    // so it's basically a no-op.
+    store.state.floatingRootContext = floatingRootContext;
+    return store;
+  }
+}
+exports.PreviewCardStore = PreviewCardStore;
+function createInitialState() {
+  return {
+    ...(0, _popups.createInitialPopupStoreState)(),
+    instantType: undefined,
+    hasViewport: false
+  };
+}

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

@@ -1,19 +1,31 @@
 import * as React from 'react';
 import type { BaseUIComponentProps } from "../../utils/types.js";
+import { PreviewCardHandle } from "../store/PreviewCardHandle.js";
 /**
  * A link that opens the preview card.
  * Renders an `<a>` element.
  *
  * Documentation: [Base UI Preview Card](https://base-ui.com/react/components/preview-card)
  */
-export declare const PreviewCardTrigger: React.ForwardRefExoticComponent<PreviewCardTriggerProps & React.RefAttributes<HTMLAnchorElement>>;
+export declare const PreviewCardTrigger: PreviewCardTrigger;
+export interface PreviewCardTrigger {
+  <Payload>(componentProps: PreviewCardTrigger.Props<Payload> & React.RefAttributes<HTMLElement>): React.JSX.Element;
+}
 export interface PreviewCardTriggerState {
   /**
    * Whether the preview card is currently open.
    */
   open: boolean;
 }
-export interface PreviewCardTriggerProps extends BaseUIComponentProps<'a', PreviewCardTrigger.State> {
+export interface PreviewCardTriggerProps<Payload = unknown> extends BaseUIComponentProps<'a', PreviewCardTrigger.State> {
+  /**
+   * A handle to associate the trigger with a preview card.
+   */
+  handle?: PreviewCardHandle<Payload>;
+  /**
+   * A payload to pass to the preview card when it is opened.
+   */
+  payload?: Payload;
   /**
    * How long to wait before the preview card opens. Specified in milliseconds.
    * @default 600
@@ -27,5 +39,5 @@ export interface PreviewCardTriggerProps extends BaseUIComponentProps<'a', Previ
 }
 export declare namespace PreviewCardTrigger {
   type State = PreviewCardTriggerState;
-  type Props = PreviewCardTriggerProps;
+  type Props<Payload = unknown> = PreviewCardTriggerProps<Payload>;
 }