@base-ui/react 1.1.0 → 1.2.0

package/esm/utils/usePopupAutoResize.js

@@ -1,3 +1,5 @@
+'use client';
+
 import * as React from 'react';
 import { useAnimationFrame } from '@base-ui/utils/useAnimationFrame';
 import { useIsoLayoutEffect } from '@base-ui/utils/useIsoLayoutEffect';
@@ -130,7 +132,7 @@ export function usePopupAutoResize(parameters) {
       };
     }
     setPopupCssSize(popupElement, previousDimensions);
-    restoreMeasurementOverrides();
+    restoreMeasurementOverridesIncludingScale();
     onMeasureLayoutComplete?.(previousDimensions, newDimensions);
     setPositionerCssSize(positionerElement, newDimensions);
     const abortController = new AbortController();

package/esm/utils/usePopupViewport.d.ts

@@ -0,0 +1,58 @@
+import * as React from 'react';
+import type { ReactStore } from '@base-ui/utils/store';
+import { Side } from "./useAnchorPositioning.js";
+export type PopupViewportCssVars = {
+  /**
+   * CSS variable name storing the popup width for the previous content snapshot.
+   */
+  popupWidth: string;
+  /**
+   * CSS variable name storing the popup height for the previous content snapshot.
+   */
+  popupHeight: string;
+};
+export interface PopupViewportState {
+  /**
+   * Direction from which the popup was activated, used for directional animations.
+   */
+  activationDirection: string | undefined;
+  /**
+   * Whether the viewport is currently transitioning between contents.
+   */
+  transitioning: boolean;
+}
+type PopupViewportStore = Pick<ReactStore<any, any, any>, 'useState' | 'set'>;
+export interface UsePopupViewportParameters {
+  /**
+   * Popup store instance for accessing shared popup state.
+   */
+  store: PopupViewportStore;
+  /**
+   * Side of the positioner relative to the trigger.
+   */
+  side: Side;
+  /**
+   * CSS variable names used for sizing the previous content snapshot.
+   */
+  cssVars: PopupViewportCssVars;
+  /**
+   * Viewport children to render in the current container.
+   */
+  children?: React.ReactNode;
+}
+export interface UsePopupViewportResult {
+  /**
+   * The viewport children wrapped in current/previous containers as needed.
+   */
+  children: React.ReactNode;
+  /**
+   * Viewport state used for data attributes and render prop styling.
+   */
+  state: PopupViewportState;
+}
+/**
+ * Builds morphing viewport containers for popups that animate between trigger-based content.
+ * Handles previous-content snapshots, auto-resize, and state attributes for transitions.
+ */
+export declare function usePopupViewport(parameters: UsePopupViewportParameters): UsePopupViewportResult;
+export {};

package/esm/utils/usePopupViewport.js

@@ -0,0 +1,247 @@
+'use client';
+
+import * as React from 'react';
+import { inertValue } from '@base-ui/utils/inertValue';
+import { useAnimationFrame } from '@base-ui/utils/useAnimationFrame';
+import { usePreviousValue } from '@base-ui/utils/usePreviousValue';
+import { useIsoLayoutEffect } from '@base-ui/utils/useIsoLayoutEffect';
+import { useStableCallback } from '@base-ui/utils/useStableCallback';
+import { useAnimationsFinished } from "./useAnimationsFinished.js";
+import { usePopupAutoResize } from "./usePopupAutoResize.js";
+import { useDirection } from "../direction-provider/index.js";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * Builds morphing viewport containers for popups that animate between trigger-based content.
+ * Handles previous-content snapshots, auto-resize, and state attributes for transitions.
+ */
+export function usePopupViewport(parameters) {
+  const {
+    store,
+    side,
+    cssVars,
+    children
+  } = parameters;
+  const direction = useDirection();
+  const activeTrigger = store.useState('activeTriggerElement');
+  const activeTriggerId = store.useState('activeTriggerId');
+  const open = store.useState('open');
+  const payload = store.useState('payload');
+  const mounted = store.useState('mounted');
+  const popupElement = store.useState('popupElement');
+  const positionerElement = store.useState('positionerElement');
+  const previousActiveTrigger = usePreviousValue(open ? activeTrigger : null);
+  // Remount current content on trigger changes (and once more when payload lags) to avoid DOM reuse flashes.
+  // The key bumps immediately on trigger switches, then again if the payload arrives on a later render.
+  const currentContentKey = usePopupContentKey(activeTriggerId, payload);
+  const capturedNodeRef = React.useRef(null);
+  const [previousContentNode, setPreviousContentNode] = React.useState(null);
+  const [newTriggerOffset, setNewTriggerOffset] = React.useState(null);
+  const currentContainerRef = React.useRef(null);
+  const previousContainerRef = React.useRef(null);
+  const onAnimationsFinished = useAnimationsFinished(currentContainerRef, true, false);
+  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]);
+  const handleMeasureLayout = useStableCallback(() => {
+    currentContainerRef.current?.style.setProperty('animation', 'none');
+    currentContainerRef.current?.style.setProperty('transition', 'none');
+    previousContainerRef.current?.style.setProperty('display', 'none');
+  });
+  const handleMeasureLayoutComplete = useStableCallback(previousDimensions => {
+    currentContainerRef.current?.style.removeProperty('animation');
+    currentContainerRef.current?.style.removeProperty('transition');
+    previousContainerRef.current?.style.removeProperty('display');
+    if (previousDimensions) {
+      setPreviousContentDimensions(previousDimensions);
+    }
+  });
+  const lastHandledTriggerRef = React.useRef(null);
+  useIsoLayoutEffect(() => {
+    // When a trigger changes, set the captured children HTML to state,
+    // so we can render both new and old content.
+    if (activeTrigger && previousActiveTrigger && activeTrigger !== previousActiveTrigger && lastHandledTriggerRef.current !== activeTrigger && capturedNodeRef.current) {
+      setPreviousContentNode(capturedNodeRef.current);
+      setShowStartingStyleAttribute(true);
+
+      // Calculate the relative position between the previous and new trigger,
+      // so we can pass it to the style hook for animation purposes.
+      const offset = calculateRelativePosition(previousActiveTrigger, activeTrigger);
+      setNewTriggerOffset(offset);
+      cleanupFrame.request(() => {
+        cleanupFrame.request(() => {
+          setShowStartingStyleAttribute(false);
+          onAnimationsFinished(() => {
+            setPreviousContentNode(null);
+            setPreviousContentDimensions(null);
+            capturedNodeRef.current = null;
+          });
+        });
+      });
+      lastHandledTriggerRef.current = activeTrigger;
+    }
+  }, [activeTrigger, previousActiveTrigger, previousContentNode, onAnimationsFinished, cleanupFrame]);
+
+  // 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.
+  useIsoLayoutEffect(() => {
+    // When a transition is in progress, we store the next content in capturedNodeRef.
+    // This handles the case where the trigger changes multiple times before the transition finishes.
+    // We want to always capture the latest content for the previous snapshot.
+    // So clicking quickly on T1, T2, T3 will result in the following sequence:
+    // 1. T1 -> T2: previousContent = T1, currentContent = T2
+    // 2. T2 -> T3: previousContent = T2, currentContent = T3
+    const source = currentContainerRef.current;
+    if (!source) {
+      return;
+    }
+    const wrapper = document.createElement('div');
+    for (const child of Array.from(source.childNodes)) {
+      wrapper.appendChild(child.cloneNode(true));
+    }
+    capturedNodeRef.current = wrapper;
+  });
+  const isTransitioning = previousContentNode != null;
+  let childrenToRender;
+  if (!isTransitioning) {
+    childrenToRender = /*#__PURE__*/_jsx("div", {
+      "data-current": true,
+      ref: currentContainerRef,
+      children: children
+    }, currentContentKey);
+  } else {
+    childrenToRender = /*#__PURE__*/_jsxs(React.Fragment, {
+      children: [/*#__PURE__*/_jsx("div", {
+        "data-previous": true,
+        inert: inertValue(true),
+        ref: previousContainerRef,
+        style: {
+          [cssVars.popupWidth]: `${previousContentDimensions?.width}px`,
+          [cssVars.popupHeight]: `${previousContentDimensions?.height}px`,
+          position: 'absolute'
+        },
+        "data-ending-style": showStartingStyleAttribute ? undefined : ''
+      }, "previous"), /*#__PURE__*/_jsx("div", {
+        "data-current": true,
+        ref: currentContainerRef,
+        "data-starting-style": showStartingStyleAttribute ? '' : undefined,
+        children: children
+      }, currentContentKey)]
+    });
+  }
+
+  // When previousContentNode is present, imperatively populate the previous container with the cloned children.
+  useIsoLayoutEffect(() => {
+    const container = previousContainerRef.current;
+    if (!container || !previousContentNode) {
+      return;
+    }
+    container.replaceChildren(...Array.from(previousContentNode.childNodes));
+  }, [previousContentNode]);
+  usePopupAutoResize({
+    popupElement,
+    positionerElement,
+    mounted,
+    content: payload,
+    onMeasureLayout: handleMeasureLayout,
+    onMeasureLayoutComplete: handleMeasureLayoutComplete,
+    side,
+    direction
+  });
+  const state = {
+    activationDirection: getActivationDirection(newTriggerOffset),
+    transitioning: isTransitioning
+  };
+  return {
+    children: childrenToRender,
+    state
+  };
+}
+/**
+ * Returns a string describing the provided offset.
+ * It describes both the horizontal and vertical offset, separated by a space.
+ *
+ * @param offset
+ */
+function getActivationDirection(offset) {
+  if (!offset) {
+    return undefined;
+  }
+  return `${getValueWithTolerance(offset.horizontal, 5, 'right', 'left')} ${getValueWithTolerance(offset.vertical, 5, 'down', 'up')}`;
+}
+
+/**
+ * Returns a label describing the value (positive/negative) treating values
+ * within tolerance as zero.
+ *
+ * @param value Value to check
+ * @param tolerance Tolerance to treat the value as zero.
+ * @param positiveLabel
+ * @param negativeLabel
+ * @returns If 0 < abs(value) < tolerance, returns an empty string. Otherwise returns positiveLabel or negativeLabel.
+ */
+function getValueWithTolerance(value, tolerance, positiveLabel, negativeLabel) {
+  if (value > tolerance) {
+    return positiveLabel;
+  }
+  if (value < -tolerance) {
+    return negativeLabel;
+  }
+  return '';
+}
+
+/**
+ * Calculates the relative position between centers of two elements.
+ */
+function calculateRelativePosition(from, to) {
+  const fromRect = from.getBoundingClientRect();
+  const toRect = to.getBoundingClientRect();
+  const fromCenter = {
+    x: fromRect.left + fromRect.width / 2,
+    y: fromRect.top + fromRect.height / 2
+  };
+  const toCenter = {
+    x: toRect.left + toRect.width / 2,
+    y: toRect.top + toRect.height / 2
+  };
+  return {
+    horizontal: toCenter.x - fromCenter.x,
+    vertical: toCenter.y - fromCenter.y
+  };
+}
+
+/**
+ * Returns a key that forces remounting content when triggers change or a payload is updated.
+ */
+function usePopupContentKey(activeTriggerId, payload) {
+  const [contentKey, setContentKey] = React.useState(0);
+  const previousActiveTriggerIdRef = React.useRef(activeTriggerId);
+  const previousPayloadRef = React.useRef(payload);
+  const pendingPayloadUpdateRef = React.useRef(false);
+  useIsoLayoutEffect(() => {
+    // Compare against the last committed values to decide whether we need a new DOM subtree.
+    const previousActiveTriggerId = previousActiveTriggerIdRef.current;
+    const previousPayload = previousPayloadRef.current;
+    const triggerIdChanged = activeTriggerId !== previousActiveTriggerId;
+    const payloadChanged = payload !== previousPayload;
+    if (triggerIdChanged) {
+      // Remount immediately on trigger change; remember if payload hasn't caught up yet.
+      setContentKey(value => value + 1);
+      pendingPayloadUpdateRef.current = !payloadChanged;
+    } else if (pendingPayloadUpdateRef.current && payloadChanged) {
+      // Payload arrived a render later, so remount once more to avoid reusing the old <img>.
+      setContentKey(value => value + 1);
+      pendingPayloadUpdateRef.current = false;
+    }
+
+    // Persist current values for the next render's comparison.
+    previousActiveTriggerIdRef.current = activeTriggerId;
+    previousPayloadRef.current = payload;
+  }, [activeTriggerId, payload]);
+  return `${activeTriggerId ?? 'current'}-${contentKey}`;
+}

package/esm/utils/useRenderElement.d.ts

@@ -17,43 +17,43 @@ export type UseRenderElementParameters<State, RenderedElementType extends Elemen
    * This is useful for rendering a component conditionally.
    * @default true
    */
-  enabled?: Enabled;
+  enabled?: Enabled | undefined;
   /**
    * @deprecated
    */
-  propGetter?: (externalProps: HTMLProps) => HTMLProps;
+  propGetter?: ((externalProps: HTMLProps) => HTMLProps) | undefined;
   /**
    * The ref to apply to the rendered element.
    */
-  ref?: React.Ref<RenderedElementType> | (React.Ref<RenderedElementType> | undefined)[];
+  ref?: (React.Ref<RenderedElementType> | (React.Ref<RenderedElementType> | undefined)[]) | undefined;
   /**
    * The state of the component.
    */
-  state?: State;
+  state?: State | undefined;
   /**
    * Intrinsic props to be spread on the rendered element.
    */
-  props?: RenderFunctionProps<TagName> | Array<RenderFunctionProps<TagName> | undefined | ((props: RenderFunctionProps<TagName>) => RenderFunctionProps<TagName>)>;
+  props?: (RenderFunctionProps<TagName> | Array<RenderFunctionProps<TagName> | undefined | ((props: RenderFunctionProps<TagName>) => RenderFunctionProps<TagName>)>) | undefined;
   /**
    * A mapping of state to `data-*` attributes.
    */
-  stateAttributesMapping?: StateAttributesMapping<State>;
+  stateAttributesMapping?: StateAttributesMapping<State> | undefined;
 };
 export interface UseRenderElementComponentProps<State> {
   /**
    * The class name to apply to the rendered element.
    * Can be a string or a function that accepts the state and returns a string.
    */
-  className?: string | ((state: State) => string | undefined);
+  className?: (string | ((state: State) => string | undefined)) | undefined;
   /**
    * The render prop or React element to override the default element.
    */
-  render?: undefined | ComponentRenderFn<React.HTMLAttributes<any>, State> | React.ReactElement;
+  render?: undefined | React.ReactElement | ComponentRenderFn<React.HTMLAttributes<any>, State>;
   /**
    * The style to apply to the rendered element.
    * Can be a style object or a function that accepts the state and returns a style object.
    */
-  style?: React.CSSProperties | ((state: State) => React.CSSProperties | undefined);
+  style?: (React.CSSProperties | ((state: State) => React.CSSProperties | undefined)) | undefined;
 }
 export declare namespace useRenderElement {
   type Parameters<State, RenderedElementType extends Element, TagName, Enabled extends boolean | undefined> = UseRenderElementParameters<State, RenderedElementType, TagName, Enabled>;

package/esm/utils/useRenderElement.js

@@ -73,6 +73,12 @@ function useRenderElementProps(componentProps, params = {}) {
   }
   return outProps;
 }
+
+// The symbol React uses internally for lazy components
+// https://github.com/facebook/react/blob/a0566250b210499b4c5677f5ac2eedbd71d51a1b/packages/shared/ReactSymbols.js#L31
+//
+// TODO delete once https://github.com/facebook/react/issues/32392 is fixed
+const REACT_LAZY_TYPE = Symbol.for('react.lazy');
 function evaluateRenderProp(element, render, props, state) {
   if (render) {
     if (typeof render === 'function') {
@@ -80,7 +86,28 @@ function evaluateRenderProp(element, render, props, state) {
     }
     const mergedProps = mergeProps(props, render.props);
     mergedProps.ref = props.ref;
-    return /*#__PURE__*/React.cloneElement(render, mergedProps);
+    let newElement = render;
+
+    // Workaround for https://github.com/facebook/react/issues/32392
+    // This works because the toArray() logic unwrap lazy element type in
+    // https://github.com/facebook/react/blob/a0566250b210499b4c5677f5ac2eedbd71d51a1b/packages/react/src/ReactChildren.js#L186
+    if (newElement?.$$typeof === REACT_LAZY_TYPE) {
+      const children = React.Children.toArray(render);
+      newElement = children[0];
+    }
+
+    // There is a high number of indirections, the error message thrown by React.cloneElement() is
+    // hard to use for developers, this logic provides a better context.
+    //
+    // Our general guideline is to never change the control flow depending on the environment.
+    // However, React.cloneElement() throws if React.isValidElement() is false,
+    // so we can throw before with custom message.
+    if (process.env.NODE_ENV !== 'production') {
+      if (! /*#__PURE__*/React.isValidElement(newElement)) {
+        throw new Error(['Base UI: The `render` prop was provided an invalid React element as `React.isValidElement(render)` is `false`.', 'A valid React element must be provided to the `render` prop because it is cloned with props to replace the default element.', 'https://base-ui.com/r/invalid-render-prop'].join('\n'));
+      }
+    }
+    return /*#__PURE__*/React.cloneElement(newElement, mergedProps);
   }
   if (element) {
     if (typeof element === 'string') {

package/esm/utils/useSwipeDismiss.d.ts

@@ -0,0 +1,108 @@
+import * as React from 'react';
+export type SwipeDirection = 'up' | 'down' | 'left' | 'right';
+type SwipeProgressDetailsInternal = {
+  deltaX: number;
+  deltaY: number;
+  direction: SwipeDirection | undefined;
+};
+export declare function getDisplacement(direction: SwipeDirection, deltaX: number, deltaY: number): number;
+export declare function getElementTransform(element: HTMLElement): {
+  x: number;
+  y: number;
+  scale: number;
+};
+export declare function useSwipeDismiss(options: useSwipeDismiss.Options): useSwipeDismiss.ReturnValue;
+export declare namespace useSwipeDismiss {
+  interface SwipeDismissDetails {
+    nativeEvent: PointerEvent | TouchEvent;
+    direction: SwipeDirection | undefined;
+  }
+  type SwipeProgressDetails = SwipeProgressDetailsInternal;
+  interface Options {
+    enabled: boolean;
+    directions: SwipeDirection[];
+    elementRef: React.RefObject<HTMLElement | null>;
+    movementCssVars: {
+      x: string;
+      y: string;
+    };
+    /**
+     * The minimum distance (in pixels) the pointer must travel from the initial swipe point
+     * before the gesture is considered a dismiss.
+     * @default 40
+     */
+    swipeThreshold?: number | ((details: {
+      element: HTMLElement;
+      direction: SwipeDirection;
+    }) => number) | undefined;
+    /**
+     * If provided, swiping will only begin once this returns true.
+     * The predicate is evaluated on start and on subsequent move events while the pointer is down.
+     */
+    canStart?: ((position: {
+      x: number;
+      y: number;
+    }, details: SwipeDismissDetails) => boolean) | undefined;
+    /**
+     * If true, swiping won't start when the gesture begins within a scrollable element.
+     * This helps avoid conflicts between scrolling content and swipe-to-dismiss.
+     * @default false
+     */
+    ignoreScrollableAncestors?: boolean | undefined;
+    /**
+     * If false, touch interactions can start swiping on interactive elements
+     * that are ignored during pointer swipes.
+     * @default true
+     */
+    ignoreSelectorWhenTouch?: boolean | undefined;
+    /**
+     * Whether to update drag offsets in React state on every move.
+     * Disable for event-only usage to avoid re-renders.
+     * @default true
+     */
+    trackDrag?: boolean | undefined;
+    onSwipeStart?: ((event: PointerEvent | TouchEvent) => void) | undefined;
+    onProgress?: ((progress: number, details?: SwipeProgressDetailsInternal) => void) | undefined;
+    /**
+     * Called when the swipe interaction starts or ends.
+     */
+    onSwipingChange?: ((swiping: boolean) => void) | undefined;
+    /**
+     * Called when the swipe interaction ends. Returning `true` or `false`
+     * overrides the default dismissal behavior.
+     */
+    onRelease?: ((details: {
+      event: PointerEvent | TouchEvent;
+      direction: SwipeDirection | undefined;
+      deltaX: number;
+      deltaY: number;
+      velocityX: number;
+      velocityY: number;
+      releaseVelocityX: number;
+      releaseVelocityY: number;
+    }) => boolean | void) | undefined;
+    onDismiss?: ((event: PointerEvent | TouchEvent, details: {
+      direction: SwipeDirection;
+    }) => void) | undefined;
+  }
+  interface ReturnValue {
+    swiping: boolean;
+    swipeDirection: SwipeDirection | undefined;
+    dragDismissed: boolean;
+    getPointerProps: () => {
+      onPointerDown?: ((event: React.PointerEvent) => void) | undefined;
+      onPointerMove?: ((event: React.PointerEvent) => void) | undefined;
+      onPointerUp?: ((event: React.PointerEvent) => void) | undefined;
+      onPointerCancel?: ((event: React.PointerEvent) => void) | undefined;
+    };
+    getTouchProps: () => {
+      onTouchStart?: ((event: React.TouchEvent) => void) | undefined;
+      onTouchMove?: ((event: React.TouchEvent) => void) | undefined;
+      onTouchEnd?: ((event: React.TouchEvent) => void) | undefined;
+      onTouchCancel?: ((event: React.TouchEvent) => void) | undefined;
+    };
+    getDragStyles: () => React.CSSProperties;
+    reset: () => void;
+  }
+}
+export {};