@base-ui/react 1.0.0 → 1.2.0

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 = {};
@@ -72,12 +76,13 @@ export const PreviewCardPositioner = /*#__PURE__*/React.forwardRef(function Prev
       }
     };
   }, [open, mounted, positioning.positionerStyles]);
-  const state = React.useMemo(() => ({
+  const state = {
     open,
     side: positioning.side,
     align: positioning.align,
-    anchorHidden: positioning.anchorHidden
-  }), [open, positioning.side, positioning.align, positioning.anchorHidden]);
+    anchorHidden: positioning.anchorHidden,
+    instant: 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/positioner/PreviewCardPositionerContext.d.ts

@@ -3,7 +3,7 @@ import type { Side, Align } from "../../utils/useAnchorPositioning.js";
 export interface PreviewCardPositionerContext {
   side: Side;
   align: Align;
-  arrowRef: React.MutableRefObject<Element | null>;
+  arrowRef: React.RefObject<Element | null>;
   arrowUncentered: boolean;
   arrowStyles: React.CSSProperties;
 }

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

@@ -16,11 +16,11 @@ export let PreviewCardPositionerDataAttributes = function (PreviewCardPositioner
    * Indicates which side the popup is positioned relative to the trigger.
    * @type {'top' | 'bottom' | 'left' | 'right' | 'inline-end' | 'inline-start'}
    */
-  PreviewCardPositionerDataAttributes["side"] = "data-side";
+  PreviewCardPositionerDataAttributes[PreviewCardPositionerDataAttributes["side"] = CommonPopupDataAttributes.side] = "side";
   /**
    * Indicates how the popup is aligned relative to specified side.
    * @type {'start' | 'center' | 'end'}
    */
-  PreviewCardPositionerDataAttributes["align"] = "data-align";
+  PreviewCardPositionerDataAttributes[PreviewCardPositionerDataAttributes["align"] = CommonPopupDataAttributes.align] = "align";
   return PreviewCardPositionerDataAttributes;
 }({});

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,51 +1,76 @@
 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.
    *
    * To render a controlled preview card, use the `open` prop instead.
    * @default false
    */
-  defaultOpen?: boolean;
+  defaultOpen?: boolean | undefined;
   /**
    * Whether the preview card is currently open.
    */
-  open?: boolean;
+  open?: boolean | undefined;
   /**
    * Event handler called when the preview card is opened or closed.
    */
-  onOpenChange?: (open: boolean, eventDetails: PreviewCardRoot.ChangeEventDetails) => void;
+  onOpenChange?: ((open: boolean, eventDetails: PreviewCardRoot.ChangeEventDetails) => void) | undefined;
   /**
    * Event handler called after any animations complete when the preview card is opened or closed.
    */
-  onOpenChangeComplete?: (open: boolean) => void;
+  onOpenChangeComplete?: ((open: boolean) => void) | undefined;
   /**
    * 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> | undefined;
+  /**
+   * 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> | undefined;
+  /**
+   * 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) | undefined;
+  /**
+   * 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) | undefined;
 }
 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/esm/preview-card/root/PreviewCardRoot.js

@@ -1,142 +1,100 @@
 'use client';
 
 import * as React from 'react';
-import * as ReactDOM from 'react-dom';
-import { useControlled } from '@base-ui/utils/useControlled';
-import { useStableCallback } from '@base-ui/utils/useStableCallback';
-import { safePolygon, useDismiss, useHover, useInteractions, useFloatingRootContext } from "../../floating-ui-react/index.js";
+import { useIsoLayoutEffect } from '@base-ui/utils/useIsoLayoutEffect';
+import { useOnFirstRender } from '@base-ui/utils/useOnFirstRender';
+import { useDismiss, useInteractions } from "../../floating-ui-react/index.js";
 import { PreviewCardRootContext } from "./PreviewCardContext.js";
-import { CLOSE_DELAY, OPEN_DELAY } from "../utils/constants.js";
+import { createChangeEventDetails } from "../../utils/createBaseUIEventDetails.js";
 import { REASONS } from "../../utils/reasons.js";
-import { useFocusWithDelay } from "../../utils/interactions/useFocusWithDelay.js";
-import { useOpenChangeComplete } from "../../utils/useOpenChangeComplete.js";
-import { useTransitionStatus } from "../../utils/useTransitionStatus.js";
-
+import { PreviewCardStore } from "../store/PreviewCardStore.js";
+import { useImplicitActiveTrigger, useOpenStateTransitions } from "../../utils/popups/index.js";
+import { jsx as _jsx } from "react/jsx-runtime";
 /**
  * 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)
  */
-import { jsx as _jsx } from "react/jsx-runtime";
 export 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(OPEN_DELAY);
-  const closeDelayRef = React.useRef(CLOSE_DELAY);
-  const writeDelayRefs = useStableCallback(config => {
-    delayRef.current = config.delay ?? OPEN_DELAY;
-    closeDelayRef.current = config.closeDelay ?? CLOSE_DELAY;
+  const store = PreviewCardStore.useStore(handle?.store, {
+    open: defaultOpen,
+    openProp,
+    activeTriggerId: defaultTriggerIdProp,
+    triggerIdProp
   });
-  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] = useControlled({
-    controlled: externalOpen,
-    default: defaultOpen,
-    name: 'PreviewCard',
-    state: 'open'
+
+  // Support initially open state when uncontrolled
+  useOnFirstRender(() => {
+    if (openProp === undefined && store.state.open === false && defaultOpen === true) {
+      store.update({
+        open: true,
+        activeTriggerId: defaultTriggerIdProp
+      });
+    }
   });
-  const onOpenChange = useStableCallback(onOpenChangeProp);
+  store.useControlledProp('openProp', openProp);
+  store.useControlledProp('triggerIdProp', triggerIdProp);
+  store.useContextCallback('onOpenChange', onOpenChange);
+  store.useContextCallback('onOpenChangeComplete', onOpenChangeComplete);
+  const open = store.useState('open');
+  const activeTriggerId = store.useState('activeTriggerId');
+  const payload = store.useState('payload');
+  useImplicitActiveTrigger(store);
   const {
-    mounted,
-    setMounted,
-    transitionStatus
-  } = useTransitionStatus(open);
-  const handleUnmount = useStableCallback(() => {
-    setMounted(false);
-    onOpenChangeComplete?.(false);
-  });
-  useOpenChangeComplete({
-    enabled: !actionsRef,
-    open,
-    ref: popupRef,
-    onComplete() {
-      if (!open) {
-        handleUnmount();
+    forceUnmount
+  } = useOpenStateTransitions(open, store);
+  useIsoLayoutEffect(() => {
+    if (open) {
+      if (activeTriggerId == null) {
+        store.set('payload', undefined);
       }
     }
-  });
+  }, [store, activeTriggerId, open]);
+  const handleImperativeClose = React.useCallback(() => {
+    store.setOpen(false, createPreviewCardEventDetails(store, REASONS.imperativeAction));
+  }, [store]);
   React.useImperativeHandle(actionsRef, () => ({
-    unmount: handleUnmount
-  }), [handleUnmount]);
-  const setOpen = useStableCallback((nextOpen, eventDetails) => {
-    const isHover = eventDetails.reason === REASONS.triggerHover;
-    const isFocusOpen = nextOpen && eventDetails.reason === REASONS.triggerFocus;
-    const isDismissClose = !nextOpen && (eventDetails.reason === REASONS.triggerPress || eventDetails.reason === 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.triggerHover) {
-      setInstantTypeState(undefined);
-    }
-  });
-  const context = useFloatingRootContext({
-    elements: {
-      reference: triggerElement,
-      floating: positionerElement
-    },
-    open,
-    onOpenChange: setOpen
-  });
-  const instantType = instantTypeState;
-  const getDelayValue = () => delayRef.current;
-  const getCloseDelayValue = () => closeDelayRef.current;
-  const hover = useHover(context, {
-    mouseOnly: true,
-    move: false,
-    handleClose: safePolygon(),
-    restMs: getDelayValue,
-    delay: () => ({
-      close: getCloseDelayValue()
-    })
-  });
-  const focus = useFocusWithDelay(context, {
-    delay: getDelayValue
-  });
-  const dismiss = useDismiss(context);
+    unmount: forceUnmount,
+    close: handleImperativeClose
+  }), [forceUnmount, handleImperativeClose]);
+  const floatingRootContext = store.useState('floatingRootContext');
+  const dismiss = useDismiss(floatingRootContext);
   const {
     getReferenceProps,
+    getTriggerProps,
     getFloatingProps
-  } = 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]);
+  } = 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__*/_jsx(PreviewCardRootContext.Provider, {
-    value: contextValue,
-    children: props.children
+    value: store,
+    children: typeof children === 'function' ? children({
+      payload
+    }) : children
   });
+}
+function createPreviewCardEventDetails(store, reason) {
+  const details = createChangeEventDetails(reason);
+  details.preventUnmountOnClose = () => {
+    store.set('preventUnmountingOnClose', true);
+  };
+  return details;
 }

package/esm/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/esm/preview-card/store/PreviewCardHandle.js

@@ -0,0 +1,55 @@
+import _formatErrorMessage from "@base-ui/utils/formatErrorMessage";
+import { PreviewCardStore } from "./PreviewCardStore.js";
+import { createChangeEventDetails } from "../../utils/createBaseUIEventDetails.js";
+import { REASONS } from "../../utils/reasons.js";
+
+/**
+ * A handle to control a preview card imperatively and to associate detached triggers with it.
+ */
+export class PreviewCardHandle {
+  /**
+   * Internal store holding the preview card state.
+   * @internal
+   */
+
+  constructor() {
+    this.store = new 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}".` : _formatErrorMessage(88, triggerId));
+    }
+    this.store.setOpen(true, createChangeEventDetails(REASONS.imperativeAction, undefined, triggerElement));
+  }
+
+  /**
+   * Closes the preview card.
+   */
+  close() {
+    this.store.setOpen(false, createChangeEventDetails(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.
+ */
+export function createPreviewCardHandle() {
+  return new PreviewCardHandle();
+}