@base-ui/react 1.2.0 → 1.4.0

package/esm/utils/useFocusableWhenDisabled.d.ts

@@ -1,5 +1,5 @@
 import * as React from 'react';
-export declare function useFocusableWhenDisabled(parameters: useFocusableWhenDisabled.Parameters): useFocusableWhenDisabled.ReturnValue;
+export declare function useFocusableWhenDisabled(parameters: UseFocusableWhenDisabledParameters): UseFocusableWhenDisabledReturnValue;
 interface FocusableWhenDisabledProps {
   'aria-disabled'?: boolean | undefined;
   disabled?: boolean | undefined;
@@ -33,8 +33,5 @@ export interface UseFocusableWhenDisabledParameters {
 export interface UseFocusableWhenDisabledReturnValue {
   props: FocusableWhenDisabledProps;
 }
-export declare namespace useFocusableWhenDisabled {
-  type Parameters = UseFocusableWhenDisabledParameters;
-  type ReturnValue = UseFocusableWhenDisabledReturnValue;
-}
+export interface UseFocusableWhenDisabledState {}
 export {};

package/esm/utils/useIsHydrating.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Returns `true` while React is hydrating server-rendered markup and `false`
+ * for fresh client-only mounts.
+ */
+export declare function useIsHydrating(): boolean;

package/esm/utils/useIsHydrating.js

@@ -0,0 +1,19 @@
+import { useSyncExternalStore } from 'use-sync-external-store/shim';
+import { NOOP } from "./noop.js";
+function subscribe() {
+  return NOOP;
+}
+function getSnapshot() {
+  return false;
+}
+function getServerSnapshot() {
+  return true;
+}
+
+/**
+ * Returns `true` while React is hydrating server-rendered markup and `false`
+ * for fresh client-only mounts.
+ */
+export function useIsHydrating() {
+  return useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot);
+}

package/esm/utils/useMixedToggleClickHandler.d.ts

@@ -3,7 +3,7 @@
  * For example, a button that opens a popup on mousedown and closes it on click.
  * This hook prevents the popup from closing immediately after the mouse button is released.
  */
-export declare function useMixedToggleClickHandler(params: useMixedToggleClickHandler.Parameters): Readonly<{}>;
+export declare function useMixedToggleClickHandler(params: UseMixedToggleClickHandlerParameters): Readonly<{}>;
 export interface UseMixedToggleClickHandlerParameters {
   /**
    * Whether the mixed toggle click handler is enabled.
@@ -19,6 +19,4 @@ export interface UseMixedToggleClickHandlerParameters {
    */
   open: boolean;
 }
-export declare namespace useMixedToggleClickHandler {
-  type Parameters = UseMixedToggleClickHandlerParameters;
-}
+export interface UseMixedToggleClickHandlerState {}

package/esm/utils/useOpenChangeComplete.d.ts

@@ -2,7 +2,7 @@ import * as React from 'react';
 /**
  * Calls the provided function when the CSS open/close animation or transition completes.
  */
-export declare function useOpenChangeComplete(parameters: useOpenChangeComplete.Parameters): void;
+export declare function useOpenChangeComplete(parameters: UseOpenChangeCompleteParameters): void;
 export interface UseOpenChangeCompleteParameters {
   /**
    * Whether the hook is enabled.
@@ -22,6 +22,4 @@ export interface UseOpenChangeCompleteParameters {
    */
   onComplete: () => void;
 }
-export declare namespace useOpenChangeComplete {
-  type Parameters = UseOpenChangeCompleteParameters;
-}
+export interface UseOpenChangeCompleteState {}

package/esm/utils/useOpenInteractionType.d.ts

@@ -7,7 +7,6 @@ import { InteractionType } from '@base-ui/utils/useEnhancedClickHandler';
  */
 export declare function useOpenInteractionType(open: boolean): {
   openMethod: InteractionType | null;
-  reset: () => void;
   triggerProps: {
     onClick: (event: React.MouseEvent | React.PointerEvent) => void;
     onPointerDown: (event: React.PointerEvent) => void;

package/esm/utils/useOpenInteractionType.js

@@ -4,6 +4,7 @@ import * as React from 'react';
 import { useStableCallback } from '@base-ui/utils/useStableCallback';
 import { useEnhancedClickHandler } from '@base-ui/utils/useEnhancedClickHandler';
 import { isIOS } from '@base-ui/utils/detectBrowser';
+import { useValueChanged } from "./useValueChanged.js";
 
 /**
  * Determines the interaction type (keyboard, mouse, touch, etc.) that opened the component.
@@ -21,19 +22,20 @@ export function useOpenInteractionType(open) {
       isIOS ? 'touch' : ''));
     }
   });
-  const reset = React.useCallback(() => {
-    setOpenMethod(null);
-  }, []);
+  useValueChanged(open, previousOpen => {
+    if (previousOpen && !open) {
+      setOpenMethod(null);
+    }
+  });
   const {
     onClick,
     onPointerDown
   } = useEnhancedClickHandler(handleTriggerClick);
   return React.useMemo(() => ({
     openMethod,
-    reset,
     triggerProps: {
       onClick,
       onPointerDown
     }
-  }), [openMethod, reset, onClick, onPointerDown]);
+  }), [openMethod, onClick, onPointerDown]);
 }

package/esm/utils/usePopupAutoResize.js

@@ -8,7 +8,6 @@ import { NOOP } from '@base-ui/utils/empty';
 import { useAnimationsFinished } from "./useAnimationsFinished.js";
 import { getCssDimensions } from "./getCssDimensions.js";
 import { EMPTY_OBJECT } from "./constants.js";
-const supportsResizeObserver = typeof ResizeObserver !== 'undefined';
 const DEFAULT_ENABLED = () => true;
 
 /**
@@ -53,7 +52,7 @@ export function usePopupAutoResize(parameters) {
   }, [side, direction]);
   useIsoLayoutEffect(() => {
     // Reset the state when the popup is closed.
-    if (!mounted || !enabled() || !supportsResizeObserver) {
+    if (!mounted || !enabled() || typeof ResizeObserver !== 'function') {
       restoreAnchoringStylesRef.current = NOOP;
       isInitialRenderRef.current = true;
       committedDimensionsRef.current = null;

package/esm/utils/usePopupViewport.js

@@ -1,11 +1,13 @@
 '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 { ownerDocument } from '@base-ui/utils/owner';
 import { useAnimationsFinished } from "./useAnimationsFinished.js";
 import { usePopupAutoResize } from "./usePopupAutoResize.js";
 import { useDirection } from "../direction-provider/index.js";
@@ -74,13 +76,13 @@ export function usePopupViewport(parameters) {
       const offset = calculateRelativePosition(previousActiveTrigger, activeTrigger);
       setNewTriggerOffset(offset);
       cleanupFrame.request(() => {
-        cleanupFrame.request(() => {
+        ReactDOM.flushSync(() => {
           setShowStartingStyleAttribute(false);
-          onAnimationsFinished(() => {
-            setPreviousContentNode(null);
-            setPreviousContentDimensions(null);
-            capturedNodeRef.current = null;
-          });
+        });
+        onAnimationsFinished(() => {
+          setPreviousContentNode(null);
+          setPreviousContentDimensions(null);
+          capturedNodeRef.current = null;
         });
       });
       lastHandledTriggerRef.current = activeTrigger;
@@ -100,7 +102,7 @@ export function usePopupViewport(parameters) {
     if (!source) {
       return;
     }
-    const wrapper = document.createElement('div');
+    const wrapper = ownerDocument(source).createElement('div');
     for (const child of Array.from(source.childNodes)) {
       wrapper.appendChild(child.cloneNode(true));
     }
@@ -121,8 +123,10 @@ export function usePopupViewport(parameters) {
         inert: inertValue(true),
         ref: previousContainerRef,
         style: {
-          [cssVars.popupWidth]: `${previousContentDimensions?.width}px`,
-          [cssVars.popupHeight]: `${previousContentDimensions?.height}px`,
+          ...(previousContentDimensions ? {
+            [cssVars.popupWidth]: `${previousContentDimensions.width}px`,
+            [cssVars.popupHeight]: `${previousContentDimensions.height}px`
+          } : null),
           position: 'absolute'
         },
         "data-ending-style": showStartingStyleAttribute ? undefined : ''

package/esm/utils/usePositioner.d.ts

@@ -0,0 +1,23 @@
+import { type UseRenderElementComponentProps } from "./useRenderElement.js";
+import type { TransitionStatus } from "./useTransitionStatus.js";
+interface UsePositionerOptions {
+  styles: React.CSSProperties;
+  transitionStatus: TransitionStatus;
+  props?: React.ComponentProps<'div'> | undefined;
+  refs?: React.Ref<HTMLDivElement> | (React.Ref<HTMLDivElement> | undefined)[] | undefined;
+  hidden?: boolean | undefined;
+  inert?: boolean | undefined;
+}
+/**
+ * Renders the shared outer Positioner element used by popup components.
+ * Applies the common role, hidden state, transition styles, state attributes, and optional inert styling.
+ */
+export declare function usePositioner<State extends Record<string, any>>(componentProps: UseRenderElementComponentProps<State>, state: State, {
+  styles,
+  transitionStatus,
+  props,
+  refs,
+  hidden,
+  inert
+}: UsePositionerOptions): import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>>;
+export {};

package/esm/utils/usePositioner.js

@@ -0,0 +1,34 @@
+'use client';
+
+import { popupStateMapping } from "./popupStateMapping.js";
+import { useRenderElement } from "./useRenderElement.js";
+import { getDisabledMountTransitionStyles } from "./getDisabledMountTransitionStyles.js";
+/**
+ * Renders the shared outer Positioner element used by popup components.
+ * Applies the common role, hidden state, transition styles, state attributes, and optional inert styling.
+ */
+export function usePositioner(componentProps, state, {
+  styles,
+  transitionStatus,
+  props,
+  refs,
+  hidden,
+  inert = false
+}) {
+  const style = {
+    ...styles
+  };
+  if (inert) {
+    style.pointerEvents = 'none';
+  }
+  return useRenderElement('div', componentProps, {
+    state,
+    ref: refs,
+    props: [{
+      role: 'presentation',
+      hidden,
+      style
+    }, getDisabledMountTransitionStyles(transitionStatus), props],
+    stateAttributesMapping: popupStateMapping
+  });
+}

package/esm/utils/usePressAndHold.d.ts

@@ -0,0 +1,58 @@
+import * as React from 'react';
+export interface UsePressAndHoldParameters {
+  disabled: boolean;
+  readOnly?: boolean | undefined;
+  /**
+   * Called on each tick during a hold. Return `false` to stop the auto-change sequence.
+   */
+  tick: (triggerEvent?: Event) => boolean;
+  /**
+   * Called when the hold ends via the global `pointerup` event.
+   */
+  onStop?: ((nativeEvent: PointerEvent) => void) | undefined;
+  /**
+   * Interval between ticks once the hold is active.
+   * @default 60
+   */
+  tickDelay?: number | undefined;
+  /**
+   * Delay before the repeating ticks start after the initial hold.
+   * @default 400
+   */
+  startDelay?: number | undefined;
+  /**
+   * Pointer movement distance (px) that cancels the hold and is treated as scrolling.
+   * @default 8
+   */
+  scrollDistance?: number | undefined;
+  /**
+   * Ref to the anchor element used to resolve `ownerWindow`.
+   */
+  elementRef: React.RefObject<HTMLElement | null>;
+}
+export interface UsePressAndHoldReturnValue {
+  pointerHandlers: {
+    onTouchStart: React.TouchEventHandler<HTMLElement>;
+    onTouchEnd: React.TouchEventHandler<HTMLElement>;
+    onPointerDown: React.PointerEventHandler<HTMLElement>;
+    onPointerUp: React.PointerEventHandler<HTMLElement>;
+    onPointerMove: React.PointerEventHandler<HTMLElement>;
+    onMouseEnter: React.MouseEventHandler<HTMLElement>;
+    onMouseLeave: React.MouseEventHandler<HTMLElement>;
+    onMouseUp: React.MouseEventHandler<HTMLElement>;
+  };
+  /**
+   * Returns `true` if the `onClick` handler should be skipped.
+   * Use this in the element's `onClick` to prevent double-firing on mouse clicks
+   * (already handled by `onPointerDown`) and to suppress the synthesized click
+   * that browsers fire after a touch hold.
+   */
+  shouldSkipClick: (event: React.MouseEvent) => boolean;
+}
+/**
+ * Adds press-and-hold behavior to a button element.
+ * On pointer down, performs one action immediately, then after a delay starts
+ * continuous repeated actions at a fixed interval. Handles mouse, touch, and pen
+ * inputs correctly, including Android-specific quirks.
+ */
+export declare function usePressAndHold(params: UsePressAndHoldParameters): UsePressAndHoldReturnValue;

package/esm/utils/usePressAndHold.js

@@ -0,0 +1,192 @@
+'use client';
+
+import * as React from 'react';
+import { addEventListener } from '@base-ui/utils/addEventListener';
+import { useTimeout } from '@base-ui/utils/useTimeout';
+import { useInterval } from '@base-ui/utils/useInterval';
+import { useStableCallback } from '@base-ui/utils/useStableCallback';
+import { ownerWindow } from '@base-ui/utils/owner';
+const DEFAULT_TICK_DELAY = 60;
+const DEFAULT_START_DELAY = 400;
+const DEFAULT_SCROLL_DISTANCE = 8;
+const TOUCH_TIMEOUT = 50;
+const MAX_POINTER_MOVES_AFTER_TOUCH = 3;
+
+// Treat pen as touch-like to avoid forcing the software keyboard on stylus taps.
+// Linux Chrome may emit "pen" historically for mouse usage due to a bug, but the touch path
+// still works with minor behavioral differences.
+function isTouchLikePointerType(pointerType) {
+  return pointerType === 'touch' || pointerType === 'pen';
+}
+/**
+ * Adds press-and-hold behavior to a button element.
+ * On pointer down, performs one action immediately, then after a delay starts
+ * continuous repeated actions at a fixed interval. Handles mouse, touch, and pen
+ * inputs correctly, including Android-specific quirks.
+ */
+export function usePressAndHold(params) {
+  const {
+    disabled,
+    readOnly = false,
+    tick,
+    onStop,
+    tickDelay = DEFAULT_TICK_DELAY,
+    startDelay = DEFAULT_START_DELAY,
+    scrollDistance = DEFAULT_SCROLL_DISTANCE,
+    elementRef
+  } = params;
+  const startTickTimeout = useTimeout();
+  const tickInterval = useInterval();
+  const intentionalTouchCheckTimeout = useTimeout();
+  const isPressedRef = React.useRef(false);
+  const movesAfterTouchRef = React.useRef(0);
+  const downCoordsRef = React.useRef({
+    x: 0,
+    y: 0
+  });
+  const isTouchingButtonRef = React.useRef(false);
+  const ignoreClickRef = React.useRef(false);
+  const pointerTypeRef = React.useRef('');
+  const unsubscribeFromGlobalContextMenuRef = React.useRef(() => {});
+  const stopAutoChange = useStableCallback(() => {
+    intentionalTouchCheckTimeout.clear();
+    startTickTimeout.clear();
+    tickInterval.clear();
+    unsubscribeFromGlobalContextMenuRef.current();
+    movesAfterTouchRef.current = 0;
+  });
+  const startAutoChange = useStableCallback(triggerNativeEvent => {
+    stopAutoChange();
+    const element = elementRef.current;
+    if (!element) {
+      return;
+    }
+    const win = ownerWindow(element);
+    function handleContextMenu(event) {
+      event.preventDefault();
+    }
+
+    // A global context menu listener is necessary to prevent the context menu from
+    // appearing when the touch is slightly outside of the element's hit area.
+    unsubscribeFromGlobalContextMenuRef.current = addEventListener(win, 'contextmenu', handleContextMenu);
+    addEventListener(win, 'pointerup', event => {
+      isPressedRef.current = false;
+      stopAutoChange();
+      onStop?.(event);
+    }, {
+      once: true
+    });
+    if (!tick(triggerNativeEvent)) {
+      stopAutoChange();
+      return;
+    }
+    startTickTimeout.start(startDelay, () => {
+      tickInterval.start(tickDelay, () => {
+        if (!tick(triggerNativeEvent)) {
+          stopAutoChange();
+        }
+      });
+    });
+  });
+  React.useEffect(() => () => stopAutoChange(), [stopAutoChange]);
+  const pointerHandlers = {
+    onTouchStart() {
+      isTouchingButtonRef.current = true;
+    },
+    onTouchEnd() {
+      isTouchingButtonRef.current = false;
+    },
+    onPointerDown(event) {
+      const isMainButton = !event.button || event.button === 0;
+      if (event.defaultPrevented || !isMainButton || disabled || readOnly) {
+        return;
+      }
+      pointerTypeRef.current = event.pointerType;
+      ignoreClickRef.current = false;
+      isPressedRef.current = true;
+      downCoordsRef.current = {
+        x: event.clientX,
+        y: event.clientY
+      };
+      const isTouchPointer = isTouchLikePointerType(event.pointerType);
+      if (!isTouchPointer) {
+        event.preventDefault();
+        startAutoChange(event.nativeEvent);
+      } else {
+        // Check if the pointerdown was intentional and not the result of a scroll or
+        // pinch-zoom. In that case, we don't want to start the auto-change sequence.
+        intentionalTouchCheckTimeout.start(TOUCH_TIMEOUT, () => {
+          const moves = movesAfterTouchRef.current;
+          movesAfterTouchRef.current = 0;
+          // Only start auto-change if the touch is still pressed (prevents races
+          // with pointerup occurring before the timeout fires on quick taps).
+          const stillPressed = isPressedRef.current;
+          if (stillPressed && moves < MAX_POINTER_MOVES_AFTER_TOUCH) {
+            startAutoChange(event.nativeEvent);
+            ignoreClickRef.current = true; // synthesized click after hold should be ignored
+          } else {
+            // No auto-change (simple tap or scroll gesture), allow the click handler
+            // to perform a single action.
+            ignoreClickRef.current = false;
+            stopAutoChange();
+          }
+        });
+      }
+    },
+    onPointerUp(event) {
+      // Ensure we mark the press as released for touch flows even if auto-change never
+      // started, so the delayed auto-change check won't start after a quick tap.
+      if (isTouchLikePointerType(event.pointerType)) {
+        isPressedRef.current = false;
+      }
+    },
+    onPointerMove(event) {
+      if (disabled || readOnly || !isTouchLikePointerType(event.pointerType) || !isPressedRef.current) {
+        return;
+      }
+      if (movesAfterTouchRef.current != null) {
+        movesAfterTouchRef.current += 1;
+      }
+      const {
+        x,
+        y
+      } = downCoordsRef.current;
+      const dx = x - event.clientX;
+      const dy = y - event.clientY;
+      if (dx ** 2 + dy ** 2 > scrollDistance ** 2) {
+        stopAutoChange();
+      }
+    },
+    onMouseEnter(event) {
+      if (event.defaultPrevented || disabled || readOnly || !isPressedRef.current || isTouchingButtonRef.current || isTouchLikePointerType(pointerTypeRef.current)) {
+        return;
+      }
+      startAutoChange(event.nativeEvent);
+    },
+    onMouseLeave() {
+      if (isTouchingButtonRef.current) {
+        return;
+      }
+      stopAutoChange();
+    },
+    onMouseUp() {
+      if (isTouchingButtonRef.current) {
+        return;
+      }
+      stopAutoChange();
+    }
+  };
+  const shouldSkipClick = useStableCallback(event => {
+    if (event.defaultPrevented) {
+      return true;
+    }
+    if (isTouchLikePointerType(pointerTypeRef.current)) {
+      return ignoreClickRef.current;
+    }
+    return event.detail !== 0;
+  });
+  return {
+    pointerHandlers,
+    shouldSkipClick
+  };
+}

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> = {
   /**
@@ -25,7 +25,7 @@ export type UseRenderElementParameters<State, RenderedElementType extends Elemen
   /**
    * The ref to apply to the rendered element.
    */
-  ref?: (React.Ref<RenderedElementType> | (React.Ref<RenderedElementType> | undefined)[]) | undefined;
+  ref?: React.Ref<RenderedElementType> | (React.Ref<RenderedElementType> | undefined)[] | undefined;
   /**
    * The state of the component.
    */
@@ -33,7 +33,7 @@ export type UseRenderElementParameters<State, RenderedElementType extends Elemen
   /**
    * Intrinsic props to be spread on the rendered element.
    */
-  props?: (RenderFunctionProps<TagName> | Array<RenderFunctionProps<TagName> | undefined | ((props: RenderFunctionProps<TagName>) => RenderFunctionProps<TagName>)>) | undefined;
+  props?: RenderFunctionProps<TagName> | Array<RenderFunctionProps<TagName> | undefined | ((props: RenderFunctionProps<TagName>) => RenderFunctionProps<TagName>)> | undefined;
   /**
    * A mapping of state to `data-*` attributes.
    */
@@ -44,7 +44,7 @@ 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)) | undefined;
+  className?: string | ((state: State) => string | undefined) | undefined;
   /**
    * The render prop or React element to override the default element.
    */
@@ -53,10 +53,7 @@ export interface UseRenderElementComponentProps<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)) | 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";
@@ -45,7 +46,12 @@ function useRenderElementProps(componentProps, params = {}) {
   const className = enabled ? resolveClassName(classNameProp, state) : undefined;
   const style = enabled ? resolveStyle(styleProp, state) : undefined;
   const stateProps = enabled ? getStateAttributesProps(state, stateAttributesMapping) : EMPTY_OBJECT;
-  const outProps = enabled ? mergeObjects(stateProps, Array.isArray(props) ? mergePropsN(props) : props) ?? EMPTY_OBJECT : EMPTY_OBJECT;
+  const resolvedProps = enabled && props ? resolveRenderFunctionProps(props) : undefined;
+
+  // Ensure outProps is always a new mutable object when enabled, never EMPTY_OBJECT.
+  // This prevents potential TypeError when setting ref, className, or style properties,
+  // since EMPTY_OBJECT is frozen and mutations would fail in strict mode.
+  const outProps = enabled ? mergeObjects(stateProps, resolvedProps) ?? {} : EMPTY_OBJECT;
 
   // SAFETY: The `useMergedRefs` functions use a single hook to store the same value,
   // switching between them at runtime is safe. If this assertion fails, React will
@@ -73,15 +79,26 @@ function useRenderElementProps(componentProps, params = {}) {
   }
   return outProps;
 }
+function resolveRenderFunctionProps(props) {
+  if (Array.isArray(props)) {
+    return mergePropsN(props);
+  }
+  return mergeProps(undefined, props);
+}
 
 // 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');
+const COMPONENT_IDENTIFIER_PATTERN = /^[A-Z][A-Za-z0-9$]*$/;
+const LOWERCASE_CHARACTER_PATTERN = /[a-z]/;
 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);
@@ -118,6 +135,19 @@ 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;
+  }
+  if (!COMPONENT_IDENTIFIER_PATTERN.test(functionName)) {
+    return;
+  }
+  if (!LOWERCASE_CHARACTER_PATTERN.test(functionName)) {
+    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", {