@base-ui/react 1.0.0 → 1.1.0

package/esm/preview-card/root/PreviewCardRoot.js

@@ -1,142 +1,87 @@
 '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 { 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 [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'
+  const store = PreviewCardStore.useStore(handle?.store, {
+    open: openProp ?? defaultOpen,
+    activeTriggerId: triggerIdProp !== undefined ? triggerIdProp : defaultTriggerIdProp
   });
-  const onOpenChange = 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');
+  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();
+}

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

@@ -0,0 +1,97 @@
+import * as React from 'react';
+import * as ReactDOM from 'react-dom';
+import { createSelector, ReactStore } from '@base-ui/utils/store';
+import { useRefWithInit } from '@base-ui/utils/useRefWithInit';
+import { createInitialPopupStoreState, popupStoreSelectors, PopupTriggerMap } from "../../utils/popups/index.js";
+import { useSyncedFloatingRootContext } from "../../floating-ui-react/index.js";
+import { REASONS } from "../../utils/reasons.js";
+import { CLOSE_DELAY } from "../utils/constants.js";
+const selectors = {
+  ...popupStoreSelectors,
+  instantType: createSelector(state => state.instantType),
+  hasViewport: createSelector(state => state.hasViewport)
+};
+export class PreviewCardStore extends ReactStore {
+  constructor(initialState) {
+    super({
+      ...createInitialState(),
+      ...initialState
+    }, {
+      popupRef: /*#__PURE__*/React.createRef(),
+      onOpenChange: undefined,
+      onOpenChangeComplete: undefined,
+      triggerElements: new PopupTriggerMap(),
+      closeDelayRef: {
+        current: CLOSE_DELAY
+      }
+    }, selectors);
+  }
+  setOpen = (nextOpen, eventDetails) => {
+    const reason = eventDetails.reason;
+    const isHover = reason === REASONS.triggerHover;
+    const isFocusOpen = nextOpen && reason === REASONS.triggerFocus;
+    const isDismissClose = !nextOpen && (reason === REASONS.triggerPress || reason === 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.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 = useRefWithInit(() => {
+      return new PreviewCardStore(initialState);
+    }).current;
+    const store = externalStore ?? internalStore;
+
+    // eslint-disable-next-line react-hooks/rules-of-hooks
+    const floatingRootContext = 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;
+  }
+}
+function createInitialState() {
+  return {
+    ...createInitialPopupStoreState(),
+    instantType: undefined,
+    hasViewport: false
+  };
+}

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

package/esm/preview-card/trigger/PreviewCardTrigger.js

@@ -1,10 +1,15 @@
 'use client';
 
+import _formatErrorMessage from "@base-ui/utils/formatErrorMessage";
 import * as React from 'react';
 import { useIsoLayoutEffect } from '@base-ui/utils/useIsoLayoutEffect';
 import { usePreviewCardRootContext } from "../root/PreviewCardContext.js";
 import { triggerOpenStateMapping } from "../../utils/popupStateMapping.js";
 import { useRenderElement } from "../../utils/useRenderElement.js";
+import { useBaseUiId } from "../../utils/useBaseUiId.js";
+import { useTriggerDataForwarding } from "../../utils/popups/index.js";
+import { CLOSE_DELAY, OPEN_DELAY } from "../utils/constants.js";
+import { safePolygon, useFocus, useHoverReferenceInteraction } from "../../floating-ui-react/index.js";
 
 /**
  * A link that opens the preview card.
@@ -18,27 +23,58 @@ export const PreviewCardTrigger = /*#__PURE__*/React.forwardRef(function Preview
     className,
     delay,
     closeDelay,
+    id: idProp,
+    payload,
+    handle,
     ...elementProps
   } = componentProps;
+  const rootContext = usePreviewCardRootContext(true);
+  const store = handle?.store ?? rootContext;
+  if (!store) {
+    throw new Error(process.env.NODE_ENV !== "production" ? 'Base UI: <PreviewCard.Trigger> must be either used within a <PreviewCard.Root> component or provided with a handle.' : _formatErrorMessage(89));
+  }
+  const thisTriggerId = useBaseUiId(idProp);
+  const isTriggerActive = store.useState('isTriggerActive', thisTriggerId);
+  const isOpenedByThisTrigger = store.useState('isOpenedByTrigger', thisTriggerId);
+  const floatingRootContext = store.useState('floatingRootContext');
+  const triggerElementRef = React.useRef(null);
+  const delayWithDefault = delay ?? OPEN_DELAY;
+  const closeDelayWithDefault = closeDelay ?? CLOSE_DELAY;
   const {
-    open,
-    triggerProps,
-    setTriggerElement,
-    writeDelayRefs
-  } = usePreviewCardRootContext();
+    registerTrigger,
+    isMountedByThisTrigger
+  } = useTriggerDataForwarding(thisTriggerId, triggerElementRef, store, {
+    payload
+  });
   useIsoLayoutEffect(() => {
-    writeDelayRefs({
-      delay,
-      closeDelay
-    });
+    if (isMountedByThisTrigger) {
+      store.context.closeDelayRef.current = closeDelayWithDefault;
+    }
+  }, [store, isMountedByThisTrigger, closeDelayWithDefault]);
+  const hoverProps = useHoverReferenceInteraction(floatingRootContext, {
+    mouseOnly: true,
+    move: false,
+    handleClose: safePolygon(),
+    delay: () => ({
+      open: delayWithDefault,
+      close: closeDelayWithDefault
+    }),
+    triggerElementRef,
+    isActiveTrigger: isTriggerActive
+  });
+  const focusProps = useFocus(floatingRootContext, {
+    delay: delayWithDefault
   });
   const state = React.useMemo(() => ({
-    open
-  }), [open]);
+    open: isOpenedByThisTrigger
+  }), [isOpenedByThisTrigger]);
+  const rootTriggerProps = store.useState('triggerProps', isMountedByThisTrigger);
   const element = useRenderElement('a', componentProps, {
-    ref: [setTriggerElement, forwardedRef],
     state,
-    props: [triggerProps, elementProps],
+    ref: [forwardedRef, registerTrigger, triggerElementRef],
+    props: [hoverProps, focusProps.reference, rootTriggerProps, {
+      id: thisTriggerId
+    }, elementProps],
     stateAttributesMapping: triggerOpenStateMapping
   });
   return element;

package/esm/preview-card/viewport/PreviewCardViewport.d.ts

@@ -0,0 +1,22 @@
+import * as React from 'react';
+import { BaseUIComponentProps } from "../../utils/types.js";
+/**
+ * A viewport for displaying content transitions.
+ * This component is only required if one popup can be opened by multiple triggers, its content change based on the trigger
+ * and switching between them is animated.
+ * Renders a `<div>` element.
+ *
+ * Documentation: [Base UI Preview Card](https://base-ui.com/react/components/preview-card)
+ */
+export declare const PreviewCardViewport: React.ForwardRefExoticComponent<Omit<PreviewCardViewport.Props, "ref"> & React.RefAttributes<HTMLDivElement>>;
+export declare namespace PreviewCardViewport {
+  interface Props extends BaseUIComponentProps<'div', State> {
+    /**
+     * The content to render inside the transition container.
+     */
+    children?: React.ReactNode;
+  }
+  interface State {
+    activationDirection?: string;
+  }
+}