@base-ui/react 1.0.0 → 1.2.0

package/utils/usePopupAutoResize.js

@@ -1,4 +1,5 @@
 "use strict";
+'use client';
 
 var _interopRequireWildcard = require("@babel/runtime/helpers/interopRequireWildcard").default;
 Object.defineProperty(exports, "__esModule", {
@@ -9,6 +10,7 @@ var React = _interopRequireWildcard(require("react"));
 var _useAnimationFrame = require("@base-ui/utils/useAnimationFrame");
 var _useIsoLayoutEffect = require("@base-ui/utils/useIsoLayoutEffect");
 var _useStableCallback = require("@base-ui/utils/useStableCallback");
+var _empty = require("@base-ui/utils/empty");
 var _useAnimationsFinished = require("./useAnimationsFinished");
 var _getCssDimensions = require("./getCssDimensions");
 var _constants = require("./constants");
@@ -30,10 +32,12 @@ function usePopupAutoResize(parameters) {
     side,
     direction
   } = parameters;
-  const isInitialRender = React.useRef(true);
   const runOnceAnimationsFinish = (0, _useAnimationsFinished.useAnimationsFinished)(popupElement, true, false);
   const animationFrame = (0, _useAnimationFrame.useAnimationFrame)();
-  const previousDimensionsRef = React.useRef(null);
+  const committedDimensionsRef = React.useRef(null);
+  const liveDimensionsRef = React.useRef(null);
+  const isInitialRenderRef = React.useRef(true);
+  const restoreAnchoringStylesRef = React.useRef(_empty.NOOP);
   const onMeasureLayout = (0, _useStableCallback.useStableCallback)(onMeasureLayoutParam);
   const onMeasureLayoutComplete = (0, _useStableCallback.useStableCallback)(onMeasureLayoutCompleteParam);
   const anchoringStyles = React.useMemo(() => {
@@ -56,80 +60,90 @@ function usePopupAutoResize(parameters) {
   (0, _useIsoLayoutEffect.useIsoLayoutEffect)(() => {
     // Reset the state when the popup is closed.
     if (!mounted || !enabled() || !supportsResizeObserver) {
-      isInitialRender.current = true;
-      previousDimensionsRef.current = null;
+      restoreAnchoringStylesRef.current = _empty.NOOP;
+      isInitialRenderRef.current = true;
+      committedDimensionsRef.current = null;
+      liveDimensionsRef.current = null;
       return undefined;
     }
     if (!popupElement || !positionerElement) {
       return undefined;
     }
-    Object.entries(anchoringStyles).forEach(([key, value]) => {
-      popupElement.style.setProperty(key, value);
-    });
+    restoreAnchoringStylesRef.current = applyElementStyles(popupElement, anchoringStyles);
     const observer = new ResizeObserver(entries => {
       const entry = entries[0];
       if (entry) {
-        if (previousDimensionsRef.current === null) {
-          previousDimensionsRef.current = {
-            width: Math.ceil(entry.borderBoxSize[0].inlineSize),
-            height: Math.ceil(entry.borderBoxSize[0].blockSize)
-          };
-        } else {
-          previousDimensionsRef.current.width = Math.ceil(entry.borderBoxSize[0].inlineSize);
-          previousDimensionsRef.current.height = Math.ceil(entry.borderBoxSize[0].blockSize);
-        }
+        liveDimensionsRef.current = {
+          width: Math.ceil(entry.borderBoxSize[0].inlineSize),
+          height: Math.ceil(entry.borderBoxSize[0].blockSize)
+        };
       }
     });
     observer.observe(popupElement);
 
     // Measure the rendered size to enable transitions:
-    popupElement.style.setProperty('--popup-width', 'auto');
-    popupElement.style.setProperty('--popup-height', 'auto');
+    setPopupCssSize(popupElement, 'auto');
     const restorePopupPosition = overrideElementStyle(popupElement, 'position', 'static');
     const restorePopupTransform = overrideElementStyle(popupElement, 'transform', 'none');
     const restorePopupScale = overrideElementStyle(popupElement, 'scale', '1');
-    const restoreAvailableWidth = overrideElementStyle(positionerElement, '--available-width', 'max-content');
-    const restoreAvailableHeight = overrideElementStyle(positionerElement, '--available-height', 'max-content');
+    const restorePositionerAvailableSize = applyElementStyles(positionerElement, {
+      '--available-width': 'max-content',
+      '--available-height': 'max-content'
+    });
+    function restoreMeasurementOverrides() {
+      restorePopupPosition();
+      restorePopupTransform();
+      restorePositionerAvailableSize();
+    }
+    function restoreMeasurementOverridesIncludingScale() {
+      restoreMeasurementOverrides();
+      restorePopupScale();
+    }
     onMeasureLayout?.();
 
     // Initial render (for each time the popup opens).
-    if (isInitialRender.current || previousDimensionsRef.current === null) {
-      positionerElement.style.setProperty('--positioner-width', 'max-content');
-      positionerElement.style.setProperty('--positioner-height', 'max-content');
+    if (isInitialRenderRef.current || committedDimensionsRef.current === null) {
+      setPositionerCssSize(positionerElement, 'max-content');
       const dimensions = (0, _getCssDimensions.getCssDimensions)(popupElement);
-      positionerElement.style.setProperty('--positioner-width', `${dimensions.width}px`);
-      positionerElement.style.setProperty('--positioner-height', `${dimensions.height}px`);
-      restorePopupPosition();
-      restorePopupTransform();
-      restorePopupScale();
-      restoreAvailableWidth();
-      restoreAvailableHeight();
+      committedDimensionsRef.current = dimensions;
+      setPositionerCssSize(positionerElement, dimensions);
+      restoreMeasurementOverridesIncludingScale();
       onMeasureLayoutComplete?.(null, dimensions);
-      isInitialRender.current = false;
+      isInitialRenderRef.current = false;
       return () => {
         observer.disconnect();
+        restoreAnchoringStylesRef.current();
+        restoreAnchoringStylesRef.current = _empty.NOOP;
       };
     }
 
     // Subsequent renders while open (when `content` changes).
-    popupElement.style.setProperty('--popup-width', 'auto');
-    popupElement.style.setProperty('--popup-height', 'auto');
-    positionerElement.style.setProperty('--positioner-width', 'max-content');
-    positionerElement.style.setProperty('--positioner-height', 'max-content');
+    setPopupCssSize(popupElement, 'auto');
+    setPositionerCssSize(positionerElement, 'max-content');
+    const previousDimensions = committedDimensionsRef.current ?? liveDimensionsRef.current;
     const newDimensions = (0, _getCssDimensions.getCssDimensions)(popupElement);
-    popupElement.style.setProperty('--popup-width', `${previousDimensionsRef.current.width}px`);
-    popupElement.style.setProperty('--popup-height', `${previousDimensionsRef.current.height}px`);
-    restorePopupPosition();
-    restorePopupTransform();
-    restoreAvailableWidth();
-    restoreAvailableHeight();
-    onMeasureLayoutComplete?.(previousDimensionsRef.current, newDimensions);
-    positionerElement.style.setProperty('--positioner-width', `${newDimensions.width}px`);
-    positionerElement.style.setProperty('--positioner-height', `${newDimensions.height}px`);
+
+    // Commit immediately so future content changes have a stable previous size, even if
+    // ResizeObserver runs after this point.
+    committedDimensionsRef.current = newDimensions;
+    if (!previousDimensions) {
+      setPositionerCssSize(positionerElement, newDimensions);
+      restoreMeasurementOverridesIncludingScale();
+      onMeasureLayoutComplete?.(null, newDimensions);
+      return () => {
+        observer.disconnect();
+        animationFrame.cancel();
+        restoreAnchoringStylesRef.current();
+        restoreAnchoringStylesRef.current = _empty.NOOP;
+      };
+    }
+    setPopupCssSize(popupElement, previousDimensions);
+    restoreMeasurementOverridesIncludingScale();
+    onMeasureLayoutComplete?.(previousDimensions, newDimensions);
+    setPositionerCssSize(positionerElement, newDimensions);
     const abortController = new AbortController();
     animationFrame.request(() => {
-      popupElement.style.setProperty('--popup-width', `${newDimensions.width}px`);
-      popupElement.style.setProperty('--popup-height', `${newDimensions.height}px`);
+      setPopupCssSize(popupElement, newDimensions);
       runOnceAnimationsFinish(() => {
         popupElement.style.setProperty('--popup-width', 'auto');
         popupElement.style.setProperty('--popup-height', 'auto');
@@ -139,6 +153,8 @@ function usePopupAutoResize(parameters) {
       observer.disconnect();
       abortController.abort();
       animationFrame.cancel();
+      restoreAnchoringStylesRef.current();
+      restoreAnchoringStylesRef.current = _empty.NOOP;
     };
   }, [content, popupElement, positionerElement, runOnceAnimationsFinish, animationFrame, enabled, mounted, onMeasureLayout, onMeasureLayoutComplete, anchoringStyles]);
 }
@@ -148,4 +164,25 @@ function overrideElementStyle(element, property, value) {
   return () => {
     element.style.setProperty(property, originalValue);
   };
+}
+function applyElementStyles(element, styles) {
+  const restorers = [];
+  for (const [key, value] of Object.entries(styles)) {
+    restorers.push(overrideElementStyle(element, key, value));
+  }
+  return restorers.length ? () => {
+    restorers.forEach(restore => restore());
+  } : _empty.NOOP;
+}
+function setPopupCssSize(popupElement, size) {
+  const width = size === 'auto' ? 'auto' : `${size.width}px`;
+  const height = size === 'auto' ? 'auto' : `${size.height}px`;
+  popupElement.style.setProperty('--popup-width', width);
+  popupElement.style.setProperty('--popup-height', height);
+}
+function setPositionerCssSize(positionerElement, size) {
+  const width = size === 'max-content' ? 'max-content' : `${size.width}px`;
+  const height = size === 'max-content' ? 'max-content' : `${size.height}px`;
+  positionerElement.style.setProperty('--positioner-width', width);
+  positionerElement.style.setProperty('--positioner-height', height);
 }

package/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/utils/usePopupViewport.js

@@ -0,0 +1,253 @@
+"use strict";
+'use client';
+
+var _interopRequireWildcard = require("@babel/runtime/helpers/interopRequireWildcard").default;
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.usePopupViewport = usePopupViewport;
+var React = _interopRequireWildcard(require("react"));
+var _inertValue = require("@base-ui/utils/inertValue");
+var _useAnimationFrame = require("@base-ui/utils/useAnimationFrame");
+var _usePreviousValue = require("@base-ui/utils/usePreviousValue");
+var _useIsoLayoutEffect = require("@base-ui/utils/useIsoLayoutEffect");
+var _useStableCallback = require("@base-ui/utils/useStableCallback");
+var _useAnimationsFinished = require("./useAnimationsFinished");
+var _usePopupAutoResize = require("./usePopupAutoResize");
+var _directionProvider = require("../direction-provider");
+var _jsxRuntime = require("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.
+ */
+function usePopupViewport(parameters) {
+  const {
+    store,
+    side,
+    cssVars,
+    children
+  } = parameters;
+  const direction = (0, _directionProvider.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 = (0, _usePreviousValue.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 = (0, _useAnimationsFinished.useAnimationsFinished)(currentContainerRef, true, false);
+  const cleanupFrame = (0, _useAnimationFrame.useAnimationFrame)();
+  const [previousContentDimensions, setPreviousContentDimensions] = React.useState(null);
+  const [showStartingStyleAttribute, setShowStartingStyleAttribute] = React.useState(false);
+  (0, _useIsoLayoutEffect.useIsoLayoutEffect)(() => {
+    store.set('hasViewport', true);
+    return () => {
+      store.set('hasViewport', false);
+    };
+  }, [store]);
+  const handleMeasureLayout = (0, _useStableCallback.useStableCallback)(() => {
+    currentContainerRef.current?.style.setProperty('animation', 'none');
+    currentContainerRef.current?.style.setProperty('transition', 'none');
+    previousContainerRef.current?.style.setProperty('display', 'none');
+  });
+  const handleMeasureLayoutComplete = (0, _useStableCallback.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);
+  (0, _useIsoLayoutEffect.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.
+  (0, _useIsoLayoutEffect.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__*/(0, _jsxRuntime.jsx)("div", {
+      "data-current": true,
+      ref: currentContainerRef,
+      children: children
+    }, currentContentKey);
+  } else {
+    childrenToRender = /*#__PURE__*/(0, _jsxRuntime.jsxs)(React.Fragment, {
+      children: [/*#__PURE__*/(0, _jsxRuntime.jsx)("div", {
+        "data-previous": true,
+        inert: (0, _inertValue.inertValue)(true),
+        ref: previousContainerRef,
+        style: {
+          [cssVars.popupWidth]: `${previousContentDimensions?.width}px`,
+          [cssVars.popupHeight]: `${previousContentDimensions?.height}px`,
+          position: 'absolute'
+        },
+        "data-ending-style": showStartingStyleAttribute ? undefined : ''
+      }, "previous"), /*#__PURE__*/(0, _jsxRuntime.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.
+  (0, _useIsoLayoutEffect.useIsoLayoutEffect)(() => {
+    const container = previousContainerRef.current;
+    if (!container || !previousContentNode) {
+      return;
+    }
+    container.replaceChildren(...Array.from(previousContentNode.childNodes));
+  }, [previousContentNode]);
+  (0, _usePopupAutoResize.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);
+  (0, _useIsoLayoutEffect.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/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/utils/useRenderElement.js

@@ -81,6 +81,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') {
@@ -88,7 +94,28 @@ function evaluateRenderProp(element, render, props, state) {
     }
     const mergedProps = (0, _mergeProps.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') {