@base-ui/react 1.1.0 → 1.3.0

package/esm/utils/usePopupViewport.js

@@ -0,0 +1,250 @@
+'use client';
+
+import * as React from 'react';
+import * as ReactDOM from 'react-dom';
+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(() => {
+        ReactDOM.flushSync(() => {
+          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: {
+          ...(previousContentDimensions ? {
+            [cssVars.popupWidth]: `${previousContentDimensions.width}px`,
+            [cssVars.popupHeight]: `${previousContentDimensions.height}px`
+          } : null),
+          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/useRegisteredLabelId.d.ts

@@ -0,0 +1 @@
+export declare function useRegisteredLabelId(idProp: string | undefined, setLabelId: (id: string | undefined) => void): string | undefined;

package/esm/utils/useRegisteredLabelId.js

@@ -0,0 +1,14 @@
+'use client';
+
+import { useIsoLayoutEffect } from '@base-ui/utils/useIsoLayoutEffect';
+import { useBaseUiId } from "./useBaseUiId.js";
+export function useRegisteredLabelId(idProp, setLabelId) {
+  const id = useBaseUiId(idProp);
+  useIsoLayoutEffect(() => {
+    setLabelId(id);
+    return () => {
+      setLabelId(undefined);
+    };
+  }, [id, setLabelId]);
+  return id;
+}

package/esm/utils/useRenderElement.d.ts

@@ -9,7 +9,7 @@ type IntrinsicTagName = keyof React.JSX.IntrinsicElements;
  * @param componentProps An object containing the `render` and `className` props to be used for element customization. Other props are ignored.
  * @param params Additional parameters for rendering the element.
  */
-export declare function useRenderElement<State extends Record<string, any>, RenderedElementType extends Element, TagName extends IntrinsicTagName | undefined, Enabled extends boolean | undefined = undefined>(element: TagName, componentProps: useRenderElement.ComponentProps<State>, params?: useRenderElement.Parameters<State, RenderedElementType, TagName, Enabled>): Enabled extends false ? null : React.ReactElement;
+export declare function useRenderElement<State extends Record<string, any>, RenderedElementType extends Element, TagName extends IntrinsicTagName | undefined, Enabled extends boolean | undefined = undefined>(element: TagName, componentProps: UseRenderElementComponentProps<State>, params?: UseRenderElementParameters<State, RenderedElementType, TagName, Enabled>): Enabled extends false ? null : React.ReactElement;
 type RenderFunctionProps<TagName> = TagName extends keyof React.JSX.IntrinsicElements ? React.JSX.IntrinsicElements[TagName] : React.HTMLAttributes<any>;
 export type UseRenderElementParameters<State, RenderedElementType extends Element, TagName, Enabled extends boolean | undefined> = {
   /**
@@ -17,46 +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);
-}
-export declare namespace useRenderElement {
-  type Parameters<State, RenderedElementType extends Element, TagName, Enabled extends boolean | undefined> = UseRenderElementParameters<State, RenderedElementType, TagName, Enabled>;
-  type ComponentProps<State> = UseRenderElementComponentProps<State>;
+  style?: React.CSSProperties | ((state: State) => React.CSSProperties | undefined) | undefined;
 }
+export interface UseRenderElementState {}
 export {};

package/esm/utils/useRenderElement.js

@@ -3,6 +3,7 @@ import * as React from 'react';
 import { useMergedRefs, useMergedRefsN } from '@base-ui/utils/useMergedRefs';
 import { getReactElementRef } from '@base-ui/utils/getReactElementRef';
 import { mergeObjects } from '@base-ui/utils/mergeObjects';
+import { warn } from '@base-ui/utils/warn';
 import { getStateAttributesProps } from "./getStateAttributesProps.js";
 import { resolveClassName } from "./resolveClassName.js";
 import { resolveStyle } from "./resolveStyle.js";
@@ -73,14 +74,44 @@ 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') {
+      if (process.env.NODE_ENV !== 'production') {
+        warnIfRenderPropLooksLikeComponent(render);
+      }
       return 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') {
@@ -91,6 +122,17 @@ function evaluateRenderProp(element, render, props, state) {
   // to annotate it correctly.
   throw new Error(process.env.NODE_ENV !== "production" ? 'Base UI: Render element or function are not defined.' : _formatErrorMessage(8));
 }
+function warnIfRenderPropLooksLikeComponent(renderFn) {
+  const functionName = renderFn.name;
+  if (functionName.length === 0) {
+    return;
+  }
+  const firstCharacterCode = functionName.charCodeAt(0);
+  if (firstCharacterCode < 65 || firstCharacterCode > 90) {
+    return;
+  }
+  warn(`The \`render\` prop received a function named \`${functionName}\` that starts with an uppercase letter.`, 'This usually means a React component was passed directly as `render={Component}`.', 'Base UI calls `render` as a plain function, which can break the Rules of Hooks during reconciliation.', 'If this is an intentional render callback, rename it to start with a lowercase letter.', 'Use `render={<Component />}` or `render={(props) => <Component {...props} />}` instead.', 'https://base-ui.com/r/invalid-render-prop');
+}
 function renderTag(Tag, props) {
   if (Tag === 'button') {
     return /*#__PURE__*/_createElement("button", {

package/esm/utils/useSwipeDismiss.d.ts

@@ -0,0 +1,107 @@
+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: UseSwipeDismissOptions): UseSwipeDismissReturnValue;
+export interface UseSwipeDismissState {}
+export interface UseSwipeDismissDetails {
+  nativeEvent: PointerEvent | TouchEvent;
+  direction: SwipeDirection | undefined;
+}
+export type UseSwipeDismissProgressDetails = SwipeProgressDetailsInternal;
+export interface UseSwipeDismissOptions {
+  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: UseSwipeDismissDetails) => 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?: UseSwipeDismissProgressDetails) => 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;
+}
+export interface UseSwipeDismissReturnValue {
+  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 {};