@base-ui/react 1.0.0 → 1.1.0

package/esm/popover/store/PopoverStore.js

@@ -21,7 +21,8 @@ function createInitialState() {
     stickIfOpen: true,
     nested: false,
     openOnHover: false,
-    closeDelay: 0
+    closeDelay: 0,
+    hasViewport: false
   };
 }
 const selectors = {
@@ -35,7 +36,8 @@ const selectors = {
   titleElementId: createSelector(state => state.titleElementId),
   descriptionElementId: createSelector(state => state.descriptionElementId),
   openOnHover: createSelector(state => state.openOnHover),
-  closeDelay: createSelector(state => state.closeDelay)
+  closeDelay: createSelector(state => state.closeDelay),
+  hasViewport: createSelector(state => state.hasViewport)
 };
 export class PopoverStore extends ReactStore {
   constructor(initialState) {
@@ -113,10 +115,11 @@ export class PopoverStore extends ReactStore {
     }
   };
   static useStore(externalStore, initialState) {
-    const store = useRefWithInit(() => {
-      return externalStore ?? new PopoverStore(initialState);
+    const internalStore = useRefWithInit(() => {
+      return new PopoverStore(initialState);
     }).current;
-    useOnMount(store.disposeEffect);
+    const store = externalStore ?? internalStore;
+    useOnMount(internalStore.disposeEffect);
     return store;
   }
   disposeEffect = () => {

package/esm/popover/title/PopoverTitle.d.ts

@@ -6,7 +6,7 @@ import type { BaseUIComponentProps } from "../../utils/types.js";
  *
  * Documentation: [Base UI Popover](https://base-ui.com/react/components/popover)
  */
-export declare const PopoverTitle: React.ForwardRefExoticComponent<PopoverTitleProps & React.RefAttributes<HTMLHeadingElement>>;
+export declare const PopoverTitle: React.ForwardRefExoticComponent<Omit<PopoverTitleProps, "ref"> & React.RefAttributes<HTMLHeadingElement>>;
 export interface PopoverTitleState {}
 export interface PopoverTitleProps extends BaseUIComponentProps<'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6', PopoverTitle.State> {}
 export declare namespace PopoverTitle {

package/esm/popover/trigger/PopoverTrigger.js

@@ -123,8 +123,8 @@ export const PopoverTrigger = /*#__PURE__*/React.forwardRef(function PopoverTrig
       ReactDOM.flushSync(() => {
         store.setOpen(false, createChangeEventDetails(REASONS.focusOut, event.nativeEvent, event.currentTarget));
       });
-      let nextTabbable = getTabbableAfterElement(triggerElementRef.current);
-      while (nextTabbable !== null && contains(positionerElement, nextTabbable) || nextTabbable?.hasAttribute('aria-hidden')) {
+      let nextTabbable = getTabbableAfterElement(store.context.triggerFocusTargetRef.current || triggerElementRef.current);
+      while (nextTabbable !== null && contains(positionerElement, nextTabbable)) {
         const prevTabbable = nextTabbable;
         nextTabbable = getNextTabbable(nextTabbable);
         if (nextTabbable === prevTabbable) {

package/esm/popover/viewport/PopoverViewport.d.ts

@@ -8,7 +8,7 @@ import { BaseUIComponentProps } from "../../utils/types.js";
  *
  * Documentation: [Base UI Popover](https://base-ui.com/react/components/popover)
  */
-export declare const PopoverViewport: React.ForwardRefExoticComponent<PopoverViewport.Props & React.RefAttributes<HTMLDivElement>>;
+export declare const PopoverViewport: React.ForwardRefExoticComponent<Omit<PopoverViewport.Props, "ref"> & React.RefAttributes<HTMLDivElement>>;
 export declare namespace PopoverViewport {
   interface Props extends BaseUIComponentProps<'div', State> {
     /**

package/esm/popover/viewport/PopoverViewport.js

@@ -7,9 +7,12 @@ import { usePreviousValue } from '@base-ui/utils/usePreviousValue';
 import { useIsoLayoutEffect } from '@base-ui/utils/useIsoLayoutEffect';
 import { useStableCallback } from '@base-ui/utils/useStableCallback';
 import { usePopoverRootContext } from "../root/PopoverRootContext.js";
+import { usePopoverPositionerContext } from "../positioner/PopoverPositionerContext.js";
 import { useAnimationsFinished } from "../../utils/useAnimationsFinished.js";
+import { usePopupAutoResize } from "../../utils/usePopupAutoResize.js";
 import { useRenderElement } from "../../utils/useRenderElement.js";
 import { PopoverViewportCssVars } from "./PopoverViewportCssVars.js";
+import { useDirection } from "../../direction-provider/DirectionContext.js";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 const stateAttributesMapping = {
   activationDirection: value => value ? {
@@ -35,9 +38,14 @@ export const PopoverViewport = /*#__PURE__*/React.forwardRef(function PopoverVie
   const {
     store
   } = usePopoverRootContext();
+  const positioner = usePopoverPositionerContext();
+  const direction = useDirection();
   const activeTrigger = store.useState('activeTriggerElement');
   const open = store.useState('open');
-  const floatingContext = store.useState('floatingRootContext');
+  const mounted = store.useState('mounted');
+  const payload = store.useState('payload');
+  const popupElement = store.useState('popupElement');
+  const positionerElement = store.useState('positionerElement');
   const previousActiveTrigger = usePreviousValue(open ? activeTrigger : null);
   const capturedNodeRef = React.useRef(null);
   const [previousContentNode, setPreviousContentNode] = React.useState(null);
@@ -48,6 +56,12 @@ export const PopoverViewport = /*#__PURE__*/React.forwardRef(function PopoverVie
   const cleanupFrame = useAnimationFrame();
   const [previousContentDimensions, setPreviousContentDimensions] = React.useState(null);
   const [showStartingStyleAttribute, setShowStartingStyleAttribute] = React.useState(false);
+  useIsoLayoutEffect(() => {
+    store.set('hasViewport', true);
+    return () => {
+      store.set('hasViewport', false);
+    };
+  }, [store]);
 
   // Capture a clone of the current content DOM subtree when not transitioning.
   // We can't store previous React nodes as they may be stateful; instead we capture DOM clones for visual continuity.
@@ -73,22 +87,14 @@ export const PopoverViewport = /*#__PURE__*/React.forwardRef(function PopoverVie
     currentContainerRef.current?.style.setProperty('transition', 'none');
     previousContainerRef.current?.style.setProperty('display', 'none');
   });
-  const handleMeasureLayoutComplete = useStableCallback(data => {
+  const handleMeasureLayoutComplete = useStableCallback(previousDimensions => {
     currentContainerRef.current?.style.removeProperty('animation');
     currentContainerRef.current?.style.removeProperty('transition');
     previousContainerRef.current?.style.removeProperty('display');
-    if (!previousContentDimensions) {
-      setPreviousContentDimensions(data.previousDimensions);
+    if (previousDimensions) {
+      setPreviousContentDimensions(previousDimensions);
     }
   });
-  React.useEffect(() => {
-    floatingContext.context.events.on('measure-layout', handleMeasureLayout);
-    floatingContext.context.events.on('measure-layout-complete', handleMeasureLayoutComplete);
-    return () => {
-      floatingContext.context.events.off('measure-layout', handleMeasureLayout);
-      floatingContext.context.events.off('measure-layout-complete', handleMeasureLayoutComplete);
-    };
-  }, [floatingContext, handleMeasureLayout, handleMeasureLayoutComplete]);
   const lastHandledTriggerRef = React.useRef(null);
   useIsoLayoutEffect(() => {
     // When a trigger changes, set the captured children HTML to state,
@@ -151,6 +157,16 @@ export const PopoverViewport = /*#__PURE__*/React.forwardRef(function PopoverVie
     }
     container.replaceChildren(...Array.from(previousContentNode.childNodes));
   }, [previousContentNode]);
+  usePopupAutoResize({
+    popupElement,
+    positionerElement,
+    mounted,
+    content: payload,
+    onMeasureLayout: handleMeasureLayout,
+    onMeasureLayoutComplete: handleMeasureLayoutComplete,
+    side: positioner.side,
+    direction
+  });
   const state = React.useMemo(() => {
     return {
       activationDirection: getActivationDirection(newTriggerOffset),

package/esm/preview-card/arrow/PreviewCardArrow.d.ts

@@ -7,7 +7,7 @@ import type { Align, Side } from "../../utils/useAnchorPositioning.js";
  *
  * Documentation: [Base UI Preview Card](https://base-ui.com/react/components/preview-card)
  */
-export declare const PreviewCardArrow: React.ForwardRefExoticComponent<PreviewCardArrowProps & React.RefAttributes<HTMLDivElement>>;
+export declare const PreviewCardArrow: React.ForwardRefExoticComponent<Omit<PreviewCardArrowProps, "ref"> & React.RefAttributes<HTMLDivElement>>;
 export interface PreviewCardArrowState {
   /**
    * Whether the preview card is currently open.

package/esm/preview-card/arrow/PreviewCardArrow.js

@@ -18,9 +18,7 @@ export const PreviewCardArrow = /*#__PURE__*/React.forwardRef(function PreviewCa
     className,
     ...elementProps
   } = componentProps;
-  const {
-    open
-  } = usePreviewCardRootContext();
+  const store = usePreviewCardRootContext();
   const {
     arrowRef,
     side,
@@ -28,6 +26,7 @@ export const PreviewCardArrow = /*#__PURE__*/React.forwardRef(function PreviewCa
     arrowUncentered,
     arrowStyles
   } = usePreviewCardPositionerContext();
+  const open = store.useState('open');
   const state = React.useMemo(() => ({
     open,
     side,

package/esm/preview-card/backdrop/PreviewCardBackdrop.d.ts

@@ -7,7 +7,7 @@ import type { TransitionStatus } from "../../utils/useTransitionStatus.js";
  *
  * Documentation: [Base UI Preview Card](https://base-ui.com/react/components/preview-card)
  */
-export declare const PreviewCardBackdrop: React.ForwardRefExoticComponent<PreviewCardBackdropProps & React.RefAttributes<HTMLDivElement>>;
+export declare const PreviewCardBackdrop: React.ForwardRefExoticComponent<Omit<PreviewCardBackdropProps, "ref"> & React.RefAttributes<HTMLDivElement>>;
 export interface PreviewCardBackdropState {
   /**
    * Whether the preview card is currently open.

package/esm/preview-card/backdrop/PreviewCardBackdrop.js

@@ -22,11 +22,10 @@ export const PreviewCardBackdrop = /*#__PURE__*/React.forwardRef(function Previe
     className,
     ...elementProps
   } = componentProps;
-  const {
-    open,
-    mounted,
-    transitionStatus
-  } = usePreviewCardRootContext();
+  const store = usePreviewCardRootContext();
+  const open = store.useState('open');
+  const mounted = store.useState('mounted');
+  const transitionStatus = store.useState('transitionStatus');
   const state = React.useMemo(() => ({
     open,
     transitionStatus

package/esm/preview-card/index.parts.d.ts

@@ -4,4 +4,6 @@ export { PreviewCardTrigger as Trigger } from "./trigger/PreviewCardTrigger.js";
 export { PreviewCardPositioner as Positioner } from "./positioner/PreviewCardPositioner.js";
 export { PreviewCardPopup as Popup } from "./popup/PreviewCardPopup.js";
 export { PreviewCardArrow as Arrow } from "./arrow/PreviewCardArrow.js";
-export { PreviewCardBackdrop as Backdrop } from "./backdrop/PreviewCardBackdrop.js";
+export { PreviewCardBackdrop as Backdrop } from "./backdrop/PreviewCardBackdrop.js";
+export { PreviewCardViewport as Viewport } from "./viewport/PreviewCardViewport.js";
+export { createPreviewCardHandle as createHandle, PreviewCardHandle as Handle } from "./store/PreviewCardHandle.js";

package/esm/preview-card/index.parts.js

@@ -4,4 +4,6 @@ export { PreviewCardTrigger as Trigger } from "./trigger/PreviewCardTrigger.js";
 export { PreviewCardPositioner as Positioner } from "./positioner/PreviewCardPositioner.js";
 export { PreviewCardPopup as Popup } from "./popup/PreviewCardPopup.js";
 export { PreviewCardArrow as Arrow } from "./arrow/PreviewCardArrow.js";
-export { PreviewCardBackdrop as Backdrop } from "./backdrop/PreviewCardBackdrop.js";
+export { PreviewCardBackdrop as Backdrop } from "./backdrop/PreviewCardBackdrop.js";
+export { PreviewCardViewport as Viewport } from "./viewport/PreviewCardViewport.js";
+export { createPreviewCardHandle as createHandle, PreviewCardHandle as Handle } from "./store/PreviewCardHandle.js";

package/esm/preview-card/popup/PreviewCardPopup.d.ts

@@ -8,7 +8,7 @@ import type { TransitionStatus } from "../../utils/useTransitionStatus.js";
  *
  * Documentation: [Base UI Preview Card](https://base-ui.com/react/components/preview-card)
  */
-export declare const PreviewCardPopup: React.ForwardRefExoticComponent<PreviewCardPopupProps & React.RefAttributes<HTMLDivElement>>;
+export declare const PreviewCardPopup: React.ForwardRefExoticComponent<Omit<PreviewCardPopupProps, "ref"> & React.RefAttributes<HTMLDivElement>>;
 export interface PreviewCardPopupState {
   /**
    * Whether the preview card is currently open.
@@ -16,6 +16,7 @@ export interface PreviewCardPopupState {
   open: boolean;
   side: Side;
   align: Align;
+  instant: 'dismiss' | 'focus' | undefined;
   transitionStatus: TransitionStatus;
 }
 export interface PreviewCardPopupProps extends BaseUIComponentProps<'div', PreviewCardPopup.State> {}

package/esm/preview-card/popup/PreviewCardPopup.js

@@ -1,6 +1,7 @@
 'use client';
 
 import * as React from 'react';
+import { useStableCallback } from '@base-ui/utils/useStableCallback';
 import { usePreviewCardRootContext } from "../root/PreviewCardContext.js";
 import { usePreviewCardPositionerContext } from "../positioner/PreviewCardPositionerContext.js";
 import { popupStateMapping as baseMapping } from "../../utils/popupStateMapping.js";
@@ -8,6 +9,7 @@ import { transitionStatusMapping } from "../../utils/stateAttributesMapping.js";
 import { useOpenChangeComplete } from "../../utils/useOpenChangeComplete.js";
 import { useRenderElement } from "../../utils/useRenderElement.js";
 import { getDisabledMountTransitionStyles } from "../../utils/getDisabledMountTransitionStyles.js";
+import { useHoverFloatingInteraction } from "../../floating-ui-react/index.js";
 const stateAttributesMapping = {
   ...baseMapping,
   ...transitionStatusMapping
@@ -25,35 +27,39 @@ export const PreviewCardPopup = /*#__PURE__*/React.forwardRef(function PreviewCa
     render,
     ...elementProps
   } = componentProps;
-  const {
-    open,
-    transitionStatus,
-    popupRef,
-    onOpenChangeComplete,
-    popupProps
-  } = usePreviewCardRootContext();
+  const store = usePreviewCardRootContext();
   const {
     side,
     align
   } = usePreviewCardPositionerContext();
+  const open = store.useState('open');
+  const instantType = store.useState('instantType');
+  const transitionStatus = store.useState('transitionStatus');
+  const popupProps = store.useState('popupProps');
+  const floatingContext = store.useState('floatingRootContext');
   useOpenChangeComplete({
     open,
-    ref: popupRef,
+    ref: store.context.popupRef,
     onComplete() {
       if (open) {
-        onOpenChangeComplete?.(true);
+        store.context.onOpenChangeComplete?.(true);
       }
     }
   });
+  const getCloseDelay = useStableCallback(() => store.context.closeDelayRef.current);
+  useHoverFloatingInteraction(floatingContext, {
+    closeDelay: getCloseDelay
+  });
   const state = React.useMemo(() => ({
     open,
     side,
     align,
+    instant: instantType,
     transitionStatus
-  }), [open, side, align, transitionStatus]);
+  }), [open, side, align, instantType, transitionStatus]);
   const element = useRenderElement('div', componentProps, {
-    ref: [popupRef, forwardedRef],
     state,
+    ref: [forwardedRef, store.context.popupRef, store.useStateSetter('popupElement')],
     props: [popupProps, getDisabledMountTransitionStyles(transitionStatus), elementProps],
     stateAttributesMapping
   });

package/esm/preview-card/portal/PreviewCardPortal.d.ts

@@ -7,7 +7,7 @@ import { FloatingPortalLite } from "../../utils/FloatingPortalLite.js";
  *
  * Documentation: [Base UI Preview Card](https://base-ui.com/react/components/preview-card)
  */
-export declare const PreviewCardPortal: React.ForwardRefExoticComponent<PreviewCardPortalProps & React.RefAttributes<HTMLDivElement>>;
+export declare const PreviewCardPortal: React.ForwardRefExoticComponent<Omit<PreviewCardPortalProps, "ref"> & React.RefAttributes<HTMLDivElement>>;
 export declare namespace PreviewCardPortal {
   interface State {}
 }

package/esm/preview-card/portal/PreviewCardPortal.js

@@ -18,9 +18,8 @@ export const PreviewCardPortal = /*#__PURE__*/React.forwardRef(function PreviewC
     keepMounted = false,
     ...portalProps
   } = props;
-  const {
-    mounted
-  } = usePreviewCardRootContext();
+  const store = usePreviewCardRootContext();
+  const mounted = store.useState('mounted');
   const shouldRender = mounted || keepMounted;
   if (!shouldRender) {
     return null;

package/esm/preview-card/positioner/PreviewCardPositioner.d.ts

@@ -7,7 +7,7 @@ import type { BaseUIComponentProps } from "../../utils/types.js";
  *
  * Documentation: [Base UI Preview Card](https://base-ui.com/react/components/preview-card)
  */
-export declare const PreviewCardPositioner: React.ForwardRefExoticComponent<PreviewCardPositionerProps & React.RefAttributes<HTMLDivElement>>;
+export declare const PreviewCardPositioner: React.ForwardRefExoticComponent<Omit<PreviewCardPositionerProps, "ref"> & React.RefAttributes<HTMLDivElement>>;
 export interface PreviewCardPositionerState {
   /**
    * Whether the preview card is currently open.
@@ -16,6 +16,7 @@ export interface PreviewCardPositionerState {
   side: Side;
   align: Align;
   anchorHidden: boolean;
+  instant: 'dismiss' | 'focus' | undefined;
 }
 export interface PreviewCardPositionerProps extends useAnchorPositioning.SharedParameters, BaseUIComponentProps<'div', PreviewCardPositioner.State> {}
 export declare namespace PreviewCardPositioner {

package/esm/preview-card/positioner/PreviewCardPositioner.js

@@ -8,6 +8,8 @@ import { popupStateMapping } from "../../utils/popupStateMapping.js";
 import { usePreviewCardPortalContext } from "../portal/PreviewCardPortalContext.js";
 import { POPUP_COLLISION_AVOIDANCE } from "../../utils/constants.js";
 import { useRenderElement } from "../../utils/useRenderElement.js";
+import { adaptiveOrigin } from "../../utils/adaptiveOriginMiddleware.js";
+import { getDisabledMountTransitionStyles } from "../../utils/getDisabledMountTransitionStyles.js";
 
 /**
  * Positions the popup against the trigger.
@@ -34,13 +36,14 @@ export const PreviewCardPositioner = /*#__PURE__*/React.forwardRef(function Prev
     collisionAvoidance = POPUP_COLLISION_AVOIDANCE,
     ...elementProps
   } = componentProps;
-  const {
-    open,
-    mounted,
-    floatingRootContext,
-    setPositionerElement
-  } = usePreviewCardRootContext();
+  const store = usePreviewCardRootContext();
   const keepMounted = 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 = useAnchorPositioning({
     anchor,
     floatingRootContext,
@@ -56,7 +59,8 @@ export const PreviewCardPositioner = /*#__PURE__*/React.forwardRef(function Prev
     sticky,
     disableAnchorTracking,
     keepMounted,
-    collisionAvoidance
+    collisionAvoidance,
+    adaptiveOrigin: hasViewport ? adaptiveOrigin : undefined
   });
   const defaultProps = React.useMemo(() => {
     const hiddenStyles = {};
@@ -76,8 +80,9 @@ export const PreviewCardPositioner = /*#__PURE__*/React.forwardRef(function Prev
     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,
@@ -87,8 +92,8 @@ export const PreviewCardPositioner = /*#__PURE__*/React.forwardRef(function Prev
   }), [positioning.side, positioning.align, positioning.arrowRef, positioning.arrowUncentered, positioning.arrowStyles]);
   const element = useRenderElement('div', componentProps, {
     state,
-    ref: [setPositionerElement, forwardedRef],
-    props: [defaultProps, elementProps],
+    props: [defaultProps, getDisabledMountTransitionStyles(transitionStatus), elementProps],
+    ref: [forwardedRef, store.useStateSetter('positionerElement')],
     stateAttributesMapping: popupStateMapping
   });
   return /*#__PURE__*/_jsx(PreviewCardPositionerContext.Provider, {

package/esm/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/esm/preview-card/root/PreviewCardContext.js

@@ -4,9 +4,9 @@ import _formatErrorMessage from "@base-ui/utils/formatErrorMessage";
 import * as React from 'react';
 export const PreviewCardRootContext = /*#__PURE__*/React.createContext(undefined);
 if (process.env.NODE_ENV !== "production") PreviewCardRootContext.displayName = "PreviewCardRootContext";
-export function usePreviewCardRootContext() {
+export 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>.' : _formatErrorMessage(50));
   }
   return context;

package/esm/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;