@base-ui/react 1.6.0 → 1.8.0

package/{utils → internals}/useAnchorPositioning.mjs

@@ -6,11 +6,15 @@ import { ownerDocument, ownerWindow } from '@base-ui/utils/owner';
 import { useIsoLayoutEffect } from '@base-ui/utils/useIsoLayoutEffect';
 import { useValueAsRef } from '@base-ui/utils/useValueAsRef';
 import { useStableCallback } from '@base-ui/utils/useStableCallback';
-import { autoUpdate, flip, limitShift, offset, shift, useFloating, size } from "../floating-ui-react/index.mjs";
-import { useDirection } from "../internals/direction-context/DirectionContext.mjs";
+import { autoUpdate, flip, limitShift, offset, shift as floatingShift, size } from "../floating-ui-react/index.mjs";
+import { useBaseUIFloating } from "../floating-ui-react/hooks/useFloating.mjs";
+import { useDirection } from "./direction-context/DirectionContext.mjs";
 import { arrow } from "../floating-ui-react/middleware/arrow.mjs";
-import { hide } from "./hideMiddleware.mjs";
-import { DEFAULT_SIDES } from "./adaptiveOriginMiddleware.mjs";
+import { hide } from "../utils/hideMiddleware.mjs";
+import { DEFAULT_SIDES } from "../utils/adaptiveOriginConstants.mjs";
+import * as CommonPositionerCssVars from "../utils/CommonPositionerCssVars.mjs";
+const AVAILABLE_WIDTH_VAR = CommonPositionerCssVars.availableWidth;
+const AVAILABLE_HEIGHT_VAR = CommonPositionerCssVars.availableHeight;
 function getLogicalSide(sideParam, renderedSide, isRtl) {
   const isLogicalSideParam = sideParam === 'inline-start' || sideParam === 'inline-end';
   const logicalRight = isRtl ? 'inline-start' : 'inline-end';
@@ -46,6 +50,9 @@ function getOffsetData(state, sideParam, isRtl) {
  * `useFloating` hook.
  */
 export function useAnchorPositioning(params) {
+  return useAnchorPositioningWithHook(params, useBaseUIFloating);
+}
+export function useAnchorPositioningWithHook(params, useFloatingHook) {
   const {
     // Public parameters
     anchor,
@@ -65,7 +72,7 @@ export function useAnchorPositioning(params) {
     floatingRootContext,
     mounted,
     collisionAvoidance,
-    shiftCrossAxis = false,
+    shift,
     nodeId,
     adaptiveOrigin,
     lazyFlip = false,
@@ -78,6 +85,8 @@ export function useAnchorPositioning(params) {
   const collisionAvoidanceSide = collisionAvoidance.side || 'flip';
   const collisionAvoidanceAlign = collisionAvoidance.align || 'flip';
   const collisionAvoidanceFallbackAxisSide = collisionAvoidance.fallbackAxisSide || 'end';
+  const shiftCrossAxis = shift?.crossAxis ?? false;
+  const shiftRootBoundary = shift?.rootBoundary;
   const anchorFn = typeof anchor === 'function' ? anchor : undefined;
   const anchorFnCallback = useStableCallback(anchorFn);
   const anchorDep = anchorFn ? anchorFnCallback : anchor;
@@ -95,30 +104,32 @@ export function useAnchorPositioning(params) {
   }[sideParam];
   const placement = align === 'center' ? side : `${side}-${align}`;
   let collisionPadding = collisionPaddingParam;
+  if (typeof collisionPadding === 'number') {
+    collisionPadding = {
+      top: collisionPadding,
+      right: collisionPadding,
+      bottom: collisionPadding,
+      left: collisionPadding
+    };
+  } else if (collisionPadding) {
+    collisionPadding = {
+      top: collisionPadding.top || 0,
+      right: collisionPadding.right || 0,
+      bottom: collisionPadding.bottom || 0,
+      left: collisionPadding.left || 0
+    };
+  }
 
   // Create a bias to the preferred side.
   // On iOS, when the mobile software keyboard opens, the input is exactly centered
   // in the viewport, but this can cause it to flip to the top undesirably.
+  // The bias is only applied to `flip()` so it doesn't shift the resting position
+  // computed by `shift()` and `size()` away from the requested `collisionPadding`.
   const bias = 1;
   const biasTop = sideParam === 'bottom' ? bias : 0;
   const biasBottom = sideParam === 'top' ? bias : 0;
   const biasLeft = sideParam === 'right' ? bias : 0;
   const biasRight = sideParam === 'left' ? bias : 0;
-  if (typeof collisionPadding === 'number') {
-    collisionPadding = {
-      top: collisionPadding + biasTop,
-      right: collisionPadding + biasRight,
-      bottom: collisionPadding + biasBottom,
-      left: collisionPadding + biasLeft
-    };
-  } else if (collisionPadding) {
-    collisionPadding = {
-      top: (collisionPadding.top || 0) + biasTop,
-      right: (collisionPadding.right || 0) + biasRight,
-      bottom: (collisionPadding.bottom || 0) + biasBottom,
-      left: (collisionPadding.left || 0) + biasLeft
-    };
-  }
   const commonCollisionProps = {
     boundary: collisionBoundary === 'clipping-ancestors' ? 'clippingAncestors' : collisionBoundary,
     padding: collisionPadding
@@ -155,46 +166,37 @@ export function useAnchorPositioning(params) {
     // Ensure the popup flips if it's been limited by its --available-height and it resizes.
     // Since the size() padding is smaller than the flip() padding, flip() will take precedence.
     padding: {
-      top: collisionPadding.top + bias,
-      right: collisionPadding.right + bias,
-      bottom: collisionPadding.bottom + bias,
-      left: collisionPadding.left + bias
+      top: collisionPadding.top + bias + biasTop,
+      right: collisionPadding.right + bias + biasRight,
+      bottom: collisionPadding.bottom + bias + biasBottom,
+      left: collisionPadding.left + bias + biasLeft
     },
     mainAxis: !shiftCrossAxis && collisionAvoidanceSide === 'flip',
     crossAxis: collisionAvoidanceAlign === 'flip' ? 'alignment' : false,
     fallbackAxisSideDirection: collisionAvoidanceFallbackAxisSide
   });
-  const shiftMiddleware = shiftDisabled ? null : shift(data => {
-    const html = ownerDocument(data.elements.floating).documentElement;
-    return {
-      ...commonCollisionProps,
-      // Use the Layout Viewport to avoid shifting around when pinch-zooming
-      // for context menus.
-      rootBoundary: shiftCrossAxis ? {
-        x: 0,
-        y: 0,
-        width: html.clientWidth,
-        height: html.clientHeight
-      } : undefined,
-      mainAxis: collisionAvoidanceAlign !== 'none',
-      crossAxis: crossAxisShiftEnabled,
-      limiter: sticky || shiftCrossAxis ? undefined : limitShift(limitData => {
-        if (!arrowRef.current) {
-          return {};
-        }
-        const {
-          width,
-          height
-        } = arrowRef.current.getBoundingClientRect();
-        const sideAxis = getSideAxis(getSide(limitData.placement));
-        const arrowSize = sideAxis === 'y' ? width : height;
-        const offsetAmount = sideAxis === 'y' ? collisionPadding.left + collisionPadding.right : collisionPadding.top + collisionPadding.bottom;
-        return {
-          offset: arrowSize / 2 + offsetAmount / 2
-        };
-      })
-    };
-  }, [commonCollisionProps, sticky, shiftCrossAxis, collisionPadding, collisionAvoidanceAlign]);
+  const shiftMiddleware = shiftDisabled ? null : floatingShift({
+    ...commonCollisionProps,
+    // Use the Layout Viewport to avoid shifting around when pinch-zooming.
+    rootBoundary: shiftRootBoundary,
+    mainAxis: collisionAvoidanceAlign !== 'none',
+    crossAxis: crossAxisShiftEnabled,
+    limiter: sticky || shiftCrossAxis ? undefined : limitShift(limitData => {
+      if (!arrowRef.current) {
+        return {};
+      }
+      const {
+        width,
+        height
+      } = arrowRef.current.getBoundingClientRect();
+      const sideAxis = getSideAxis(getSide(limitData.placement));
+      const arrowSize = sideAxis === 'y' ? width : height;
+      const offsetAmount = sideAxis === 'y' ? collisionPadding.left + collisionPadding.right : collisionPadding.top + collisionPadding.bottom;
+      return {
+        offset: arrowSize / 2 + offsetAmount / 2
+      };
+    })
+  }, [commonCollisionProps, sticky, shiftCrossAxis, shiftRootBoundary, collisionPadding, collisionAvoidanceAlign]);
 
   // https://floating-ui.com/docs/flip#combining-with-shift
   if (collisionAvoidanceSide === 'shift' || collisionAvoidanceAlign === 'shift' || align === 'center') {
@@ -216,8 +218,8 @@ export function useAnchorPositioning(params) {
         return;
       }
       const floatingStyle = floating.style;
-      floatingStyle.setProperty('--available-width', `${availableWidth}px`);
-      floatingStyle.setProperty('--available-height', `${availableHeight}px`);
+      floatingStyle.setProperty(AVAILABLE_WIDTH_VAR, `${availableWidth}px`);
+      floatingStyle.setProperty(AVAILABLE_HEIGHT_VAR, `${availableHeight}px`);
 
       // Snap anchor dimensions to device pixels to ensure the popup's visual width matches the anchor's one.
       const dpr = ownerWindow(floating).devicePixelRatio || 1;
@@ -229,46 +231,53 @@ export function useAnchorPositioning(params) {
       } = rects.reference;
       const anchorWidth = (Math.round((x + width) * dpr) - Math.round(x * dpr)) / dpr;
       const anchorHeight = (Math.round((y + height) * dpr) - Math.round(y * dpr)) / dpr;
-      floatingStyle.setProperty('--anchor-width', `${anchorWidth}px`);
-      floatingStyle.setProperty('--anchor-height', `${anchorHeight}px`);
+      floatingStyle.setProperty(CommonPositionerCssVars.anchorWidth, `${anchorWidth}px`);
+      floatingStyle.setProperty(CommonPositionerCssVars.anchorHeight, `${anchorHeight}px`);
     }
   }), arrow(state => ({
     // `transform-origin` calculations rely on an element existing. If the arrow hasn't been set,
     // we'll create a fake element.
     element: arrowRef.current || ownerDocument(state.elements.floating).createElement('div'),
-    padding: arrowPadding,
+    // No padding for the fake arrow: it would displace aligned popups on narrow anchors.
+    padding: arrowRef.current ? arrowPadding : 0,
     offsetParent: 'floating'
   }), [arrowPadding]), {
     name: 'transformOrigin',
     fn(state) {
       const {
-        elements,
+        elements: {
+          floating
+        },
         middlewareData,
         placement: renderedPlacement,
+        platform,
         rects,
         y
       } = state;
-      const currentRenderedSide = getSide(renderedPlacement);
-      const currentRenderedAxis = getSideAxis(currentRenderedSide);
+      const renderedSide = getSide(renderedPlacement);
+      const renderedAlign = getAlignment(renderedPlacement);
+      const isVertical = getSideAxis(renderedSide) === 'y';
       const arrowEl = arrowRef.current;
-      const arrowX = middlewareData.arrow?.x || 0;
-      const arrowY = middlewareData.arrow?.y || 0;
-      const arrowWidth = arrowEl?.clientWidth || 0;
-      const arrowHeight = arrowEl?.clientHeight || 0;
-      const transformX = arrowX + arrowWidth / 2;
-      const transformY = arrowY + arrowHeight / 2;
-      const shiftY = Math.abs(middlewareData.shift?.y || 0);
-      const halfAnchorHeight = rects.reference.height / 2;
       const sideOffsetValue = typeof sideOffset === 'function' ? sideOffset(getOffsetData(state, sideParam, isRtl)) : sideOffset;
-      const isOverlappingAnchor = shiftY > sideOffsetValue;
-      const adjacentTransformOrigin = {
-        top: `${transformX}px calc(100% + ${sideOffsetValue}px)`,
-        bottom: `${transformX}px ${-sideOffsetValue}px`,
-        left: `calc(100% + ${sideOffsetValue}px) ${transformY}px`,
-        right: `${-sideOffsetValue}px ${transformY}px`
-      }[currentRenderedSide];
-      const overlapTransformOrigin = `${transformX}px ${rects.reference.y + halfAnchorHeight - y}px`;
-      elements.floating.style.setProperty('--transform-origin', crossAxisShiftEnabled && currentRenderedAxis === 'y' && isOverlappingAnchor ? overlapTransformOrigin : adjacentTransformOrigin);
+
+      // An aligned arrowless popup grows from its aligned edge, until a shift (beyond subpixel)
+      // breaks its alignment with the anchor. Everything else grows from the arrow, real or fake.
+      let crossOrigin;
+      if (!arrowEl && renderedAlign && Math.abs(isVertical ? middlewareData.shift?.x || 0 : middlewareData.shift?.y || 0) <= 1) {
+        // The platform direction, not `isRtl`: it must match what Floating UI placed with.
+        crossOrigin = renderedAlign === 'start' === (isVertical && platform.isRTL?.(floating) === true) ? '100%' : '0%';
+      } else {
+        const arrowOffset = isVertical ? middlewareData.arrow?.x || 0 : middlewareData.arrow?.y || 0;
+        const arrowSize = isVertical ? arrowEl?.clientWidth || 0 : arrowEl?.clientHeight || 0;
+        crossOrigin = `${arrowOffset + arrowSize / 2}px`;
+      }
+
+      // Side axis: the anchor-facing edge, or the anchor's center when the popup overlaps it.
+      let sideOrigin = renderedSide === 'top' || renderedSide === 'left' ? `calc(100% + ${sideOffsetValue}px)` : `${-sideOffsetValue}px`;
+      if (crossAxisShiftEnabled && isVertical && Math.abs(middlewareData.shift?.y || 0) > sideOffsetValue) {
+        sideOrigin = `${rects.reference.y + rects.reference.height / 2 - y}px`;
+      }
+      floating.style.setProperty(CommonPositionerCssVars.transformOrigin, isVertical ? `${crossOrigin} ${sideOrigin}` : `${sideOrigin} ${crossOrigin}`);
       return {};
     }
   }, hide, adaptiveOrigin);
@@ -285,6 +294,7 @@ export function useAnchorPositioning(params) {
     }
   }, [mounted, floatingRootContext]);
   const autoUpdateOptions = React.useMemo(() => ({
+    ancestorScroll: !disableAnchorTracking,
     elementResize: !disableAnchorTracking && typeof ResizeObserver !== 'undefined',
     layoutShift: !disableAnchorTracking && typeof IntersectionObserver !== 'undefined'
   }), [disableAnchorTracking]);
@@ -299,7 +309,7 @@ export function useAnchorPositioning(params) {
     context,
     isPositioned,
     floatingStyles: originalFloatingStyles
-  } = useFloating({
+  } = useFloatingHook({
     rootContext: floatingRootContext,
     open: keepMounted ? mounted : undefined,
     placement,
@@ -318,14 +328,41 @@ export function useAnchorPositioning(params) {
   // This ensures the popup is inside the viewport initially before it gets positioned.
   const resolvedPosition = isPositioned ? positionMethod : 'fixed';
   const floatingStyles = React.useMemo(() => {
-    const base = adaptiveOrigin ? {
-      position: resolvedPosition,
-      [sideX]: x,
-      [sideY]: y
-    } : {
-      position: resolvedPosition,
-      ...originalFloatingStyles
-    };
+    let base;
+    if (!isPositioned) {
+      // Until a position for the current open is computed, ignore any coordinates retained from a
+      // previous open (or from a pass that measured the hidden popup as 0x0). Rendering the
+      // full-size popup at such stale coordinates can overflow the layout viewport, which makes
+      // mobile Chrome zoom the page out and reflow everything the popup is anchored to.
+      base = {
+        position: resolvedPosition,
+        top: 0,
+        left: 0
+      };
+    } else if (adaptiveOrigin) {
+      base = {
+        position: resolvedPosition,
+        [sideX]: x,
+        [sideY]: y
+      };
+    } else {
+      base = {
+        ...originalFloatingStyles,
+        position: resolvedPosition
+      };
+    }
+
+    // Seed the available size vars so consumer `max-height: min(x, var(--available-height))` rules
+    // resolve to a valid length on the first positioning pass, before `size()` writes the real
+    // values. Without a fallback the unresolved `var()` invalidates the whole declaration, so the
+    // popup is measured unconstrained while `flip()` picks its side, against the full content
+    // height rather than the capped one. Seeded unconditionally (not only while `!isPositioned`):
+    // the keys must stay present with a constant value so React's per-property style diff never
+    // rewrites them after mount, preserving the px values `size()` sets imperatively. Moving them
+    // into the `!isPositioned` branch makes React remove them once positioned, wiping `size()`'s
+    // values and leaving the popup unconstrained.
+    base[AVAILABLE_WIDTH_VAR] = '100vw';
+    base[AVAILABLE_HEIGHT_VAR] = '100vh';
     if (!isPositioned) {
       base.opacity = 0;
     }
@@ -376,10 +413,10 @@ export function useAnchorPositioning(params) {
   // and flips back lazily, not eagerly. Ideal for filtered lists that change
   // the size of the popup dynamically to avoid unwanted flipping when typing.
   useIsoLayoutEffect(() => {
-    if (lazyFlip && mounted && isPositioned) {
+    if (lazyFlip && mounted && isPositioned && renderedSide !== side) {
       setMountSide(renderedSide);
     }
-  }, [lazyFlip, mounted, isPositioned, renderedSide]);
+  }, [lazyFlip, mounted, isPositioned, renderedSide, side]);
   const arrowStyles = React.useMemo(() => ({
     position: 'absolute',
     top: middlewareData.arrow?.y,

package/internals/useAnimationsFinished.d.mts

@@ -1,10 +1,12 @@
 import * as React from 'react';
 /**
  * Executes a function once all animations have finished on the provided element.
+ * If an animation is canceled, waits for any replacement animations before executing.
  * @param elementOrRef - The element to watch for animations.
  * @param waitForStartingStyleRemoved - Whether to wait for [data-starting-style] to be removed before checking for animations.
- * @param treatAbortedAsFinished - Whether to treat aborted animations as finished. If `false`, and there are aborted animations,
- *   the function will check again if any new animations have started and wait for them to finish.
+ * @param batch - Whether completions ready in the same microtask may be coalesced into a single
+ * commit. A batched callback runs before earlier callbacks' React updates have committed, so only
+ * opt in when the callback doesn't read state that another completion can change.
  * @returns A function that takes a callback to execute once all animations have finished, and an optional AbortSignal to abort the callback
  */
-export declare function useAnimationsFinished(elementOrRef: React.RefObject<HTMLElement | null> | HTMLElement | null, waitForStartingStyleRemoved?: boolean, treatAbortedAsFinished?: boolean): (fnToExecute: () => void, signal?: AbortSignal | null) => void;
+export declare function useAnimationsFinished(elementOrRef: React.RefObject<HTMLElement | null> | HTMLElement | null, waitForStartingStyleRemoved?: boolean, batch?: boolean): (fnToExecute: () => void, signal?: AbortSignal | null) => void;

package/internals/useAnimationsFinished.d.ts

@@ -1,10 +1,12 @@
 import * as React from 'react';
 /**
  * Executes a function once all animations have finished on the provided element.
+ * If an animation is canceled, waits for any replacement animations before executing.
  * @param elementOrRef - The element to watch for animations.
  * @param waitForStartingStyleRemoved - Whether to wait for [data-starting-style] to be removed before checking for animations.
- * @param treatAbortedAsFinished - Whether to treat aborted animations as finished. If `false`, and there are aborted animations,
- *   the function will check again if any new animations have started and wait for them to finish.
+ * @param batch - Whether completions ready in the same microtask may be coalesced into a single
+ * commit. A batched callback runs before earlier callbacks' React updates have committed, so only
+ * opt in when the callback doesn't read state that another completion can change.
  * @returns A function that takes a callback to execute once all animations have finished, and an optional AbortSignal to abort the callback
  */
-export declare function useAnimationsFinished(elementOrRef: React.RefObject<HTMLElement | null> | HTMLElement | null, waitForStartingStyleRemoved?: boolean, treatAbortedAsFinished?: boolean): (fnToExecute: () => void, signal?: AbortSignal | null) => void;
+export declare function useAnimationsFinished(elementOrRef: React.RefObject<HTMLElement | null> | HTMLElement | null, waitForStartingStyleRemoved?: boolean, batch?: boolean): (fnToExecute: () => void, signal?: AbortSignal | null) => void;

package/internals/useAnimationsFinished.js

@@ -10,16 +10,43 @@ var ReactDOM = _interopRequireWildcard(require("react-dom"));
 var _useAnimationFrame = require("@base-ui/utils/useAnimationFrame");
 var _useStableCallback = require("@base-ui/utils/useStableCallback");
 var _resolveRef = require("../utils/resolveRef");
-var _stateAttributesMapping = require("./stateAttributesMapping");
+var TransitionStatusDataAttributes = _interopRequireWildcard(require("./TransitionStatusDataAttributes"));
+let pendingCallbacks = null;
+
+/**
+ * Runs the callback in a synchronous flush before the browser paints, so that the
+ * browser doesn't paint an intermediate frame: https://github.com/mui/base-ui/issues/979
+ * Callbacks that become ready within the same microtask checkpoint (e.g. multiple elements
+ * whose animations finish together) are batched into a single commit:
+ * https://github.com/mui/base-ui/issues/5481
+ */
+function flushBeforePaint(fn) {
+  if (!pendingCallbacks) {
+    const callbacks = [];
+    pendingCallbacks = callbacks;
+    queueMicrotask(() => {
+      pendingCallbacks = null;
+      ReactDOM.flushSync(() => {
+        for (const callback of callbacks) {
+          callback();
+        }
+      });
+    });
+  }
+  pendingCallbacks.push(fn);
+}
+
 /**
  * Executes a function once all animations have finished on the provided element.
+ * If an animation is canceled, waits for any replacement animations before executing.
  * @param elementOrRef - The element to watch for animations.
  * @param waitForStartingStyleRemoved - Whether to wait for [data-starting-style] to be removed before checking for animations.
- * @param treatAbortedAsFinished - Whether to treat aborted animations as finished. If `false`, and there are aborted animations,
- *   the function will check again if any new animations have started and wait for them to finish.
+ * @param batch - Whether completions ready in the same microtask may be coalesced into a single
+ * commit. A batched callback runs before earlier callbacks' React updates have committed, so only
+ * opt in when the callback doesn't read state that another completion can change.
  * @returns A function that takes a callback to execute once all animations have finished, and an optional AbortSignal to abort the callback
  */
-function useAnimationsFinished(elementOrRef, waitForStartingStyleRemoved = false, treatAbortedAsFinished = true) {
+function useAnimationsFinished(elementOrRef, waitForStartingStyleRemoved = false, batch = false) {
   const frame = (0, _useAnimationFrame.useAnimationFrame)();
   return (0, _useStableCallback.useStableCallback)((fnToExecute,
   /**
@@ -35,9 +62,20 @@ function useAnimationsFinished(elementOrRef, waitForStartingStyleRemoved = false
     }
     const resolvedElement = element;
     const done = () => {
-      // Synchronously flush the unmounting of the component so that the browser doesn't
-      // paint: https://github.com/mui/base-ui/issues/979
-      ReactDOM.flushSync(fnToExecute);
+      if (!batch) {
+        // Synchronously flush the unmounting of the component so that the browser doesn't
+        // paint: https://github.com/mui/base-ui/issues/979
+        // Each callback gets its own commit so that later completions observe the React
+        // updates caused by earlier ones.
+        ReactDOM.flushSync(fnToExecute);
+        return;
+      }
+      flushBeforePaint(() => {
+        // Re-check at flush time: the signal may abort between queueing and the flush.
+        if (!signal?.aborted) {
+          fnToExecute();
+        }
+      });
     };
     if (typeof resolvedElement.getAnimations !== 'function' || globalThis.BASE_UI_ANIMATIONS_DISABLED) {
       fnToExecute();
@@ -48,23 +86,22 @@ function useAnimationsFinished(elementOrRef, waitForStartingStyleRemoved = false
         if (!signal?.aborted) {
           done();
         }
-      }).catch(() => {
-        if (treatAbortedAsFinished) {
-          if (!signal?.aborted) {
-            done();
-          }
+      }, () => {
+        if (signal?.aborted) {
           return;
         }
         const currentAnimations = resolvedElement.getAnimations();
-        if (!signal?.aborted && currentAnimations.length > 0 && currentAnimations.some(animation => animation.pending || animation.playState !== 'finished')) {
+        if (currentAnimations.some(animation => animation.pending || animation.playState !== 'finished')) {
           // Sometimes animations can be aborted because a property they depend on changes while the animation plays.
           // In such cases, we need to re-check if any new animations have started.
           exec();
+          return;
         }
+        done();
       });
     }
     if (waitForStartingStyleRemoved) {
-      const startingStyleAttribute = _stateAttributesMapping.TransitionStatusDataAttributes.startingStyle;
+      const startingStyleAttribute = TransitionStatusDataAttributes.startingStyle;
 
       // If `[data-starting-style]` isn't present, fall back to waiting one more frame
       // to give "open" animations a chance to be registered.

package/internals/useAnimationsFinished.mjs

@@ -4,17 +4,43 @@ import * as ReactDOM from 'react-dom';
 import { useAnimationFrame } from '@base-ui/utils/useAnimationFrame';
 import { useStableCallback } from '@base-ui/utils/useStableCallback';
 import { resolveRef } from "../utils/resolveRef.mjs";
-import { TransitionStatusDataAttributes } from "./stateAttributesMapping.mjs";
+import * as TransitionStatusDataAttributes from "./TransitionStatusDataAttributes.mjs";
+let pendingCallbacks = null;
+
+/**
+ * Runs the callback in a synchronous flush before the browser paints, so that the
+ * browser doesn't paint an intermediate frame: https://github.com/mui/base-ui/issues/979
+ * Callbacks that become ready within the same microtask checkpoint (e.g. multiple elements
+ * whose animations finish together) are batched into a single commit:
+ * https://github.com/mui/base-ui/issues/5481
+ */
+function flushBeforePaint(fn) {
+  if (!pendingCallbacks) {
+    const callbacks = [];
+    pendingCallbacks = callbacks;
+    queueMicrotask(() => {
+      pendingCallbacks = null;
+      ReactDOM.flushSync(() => {
+        for (const callback of callbacks) {
+          callback();
+        }
+      });
+    });
+  }
+  pendingCallbacks.push(fn);
+}
 
 /**
  * Executes a function once all animations have finished on the provided element.
+ * If an animation is canceled, waits for any replacement animations before executing.
  * @param elementOrRef - The element to watch for animations.
  * @param waitForStartingStyleRemoved - Whether to wait for [data-starting-style] to be removed before checking for animations.
- * @param treatAbortedAsFinished - Whether to treat aborted animations as finished. If `false`, and there are aborted animations,
- *   the function will check again if any new animations have started and wait for them to finish.
+ * @param batch - Whether completions ready in the same microtask may be coalesced into a single
+ * commit. A batched callback runs before earlier callbacks' React updates have committed, so only
+ * opt in when the callback doesn't read state that another completion can change.
  * @returns A function that takes a callback to execute once all animations have finished, and an optional AbortSignal to abort the callback
  */
-export function useAnimationsFinished(elementOrRef, waitForStartingStyleRemoved = false, treatAbortedAsFinished = true) {
+export function useAnimationsFinished(elementOrRef, waitForStartingStyleRemoved = false, batch = false) {
   const frame = useAnimationFrame();
   return useStableCallback((fnToExecute,
   /**
@@ -30,9 +56,20 @@ export function useAnimationsFinished(elementOrRef, waitForStartingStyleRemoved
     }
     const resolvedElement = element;
     const done = () => {
-      // Synchronously flush the unmounting of the component so that the browser doesn't
-      // paint: https://github.com/mui/base-ui/issues/979
-      ReactDOM.flushSync(fnToExecute);
+      if (!batch) {
+        // Synchronously flush the unmounting of the component so that the browser doesn't
+        // paint: https://github.com/mui/base-ui/issues/979
+        // Each callback gets its own commit so that later completions observe the React
+        // updates caused by earlier ones.
+        ReactDOM.flushSync(fnToExecute);
+        return;
+      }
+      flushBeforePaint(() => {
+        // Re-check at flush time: the signal may abort between queueing and the flush.
+        if (!signal?.aborted) {
+          fnToExecute();
+        }
+      });
     };
     if (typeof resolvedElement.getAnimations !== 'function' || globalThis.BASE_UI_ANIMATIONS_DISABLED) {
       fnToExecute();
@@ -43,19 +80,18 @@ export function useAnimationsFinished(elementOrRef, waitForStartingStyleRemoved
         if (!signal?.aborted) {
           done();
         }
-      }).catch(() => {
-        if (treatAbortedAsFinished) {
-          if (!signal?.aborted) {
-            done();
-          }
+      }, () => {
+        if (signal?.aborted) {
           return;
         }
         const currentAnimations = resolvedElement.getAnimations();
-        if (!signal?.aborted && currentAnimations.length > 0 && currentAnimations.some(animation => animation.pending || animation.playState !== 'finished')) {
+        if (currentAnimations.some(animation => animation.pending || animation.playState !== 'finished')) {
           // Sometimes animations can be aborted because a property they depend on changes while the animation plays.
           // In such cases, we need to re-check if any new animations have started.
           exec();
+          return;
         }
+        done();
       });
     }
     if (waitForStartingStyleRemoved) {

package/internals/useOpenChangeComplete.d.mts

@@ -17,6 +17,12 @@ export interface UseOpenChangeCompleteParameters {
    * Ref to the element being closed.
    */
   ref: React.RefObject<HTMLElement | null>;
+  /**
+   * Whether completions ready in the same microtask may be coalesced into a single commit.
+   * Only safe when `onComplete` doesn't read state that another completion can change.
+   * @default false
+   */
+  batch?: boolean | undefined;
   /**
    * Function to call when the animation completes (or there is no animation).
    */

package/internals/useOpenChangeComplete.d.ts

@@ -17,6 +17,12 @@ export interface UseOpenChangeCompleteParameters {
    * Ref to the element being closed.
    */
   ref: React.RefObject<HTMLElement | null>;
+  /**
+   * Whether completions ready in the same microtask may be coalesced into a single commit.
+   * Only safe when `onComplete` doesn't read state that another completion can change.
+   * @default false
+   */
+  batch?: boolean | undefined;
   /**
    * Function to call when the animation completes (or there is no animation).
    */

package/internals/useOpenChangeComplete.js

@@ -17,10 +17,11 @@ function useOpenChangeComplete(parameters) {
     enabled = true,
     open,
     ref,
+    batch = false,
     onComplete: onCompleteParam
   } = parameters;
   const onComplete = (0, _useStableCallback.useStableCallback)(onCompleteParam);
-  const runOnceAnimationsFinish = (0, _useAnimationsFinished.useAnimationsFinished)(ref, open, false);
+  const runOnceAnimationsFinish = (0, _useAnimationsFinished.useAnimationsFinished)(ref, open, batch);
   React.useEffect(() => {
     if (!enabled) {
       return undefined;

package/internals/useOpenChangeComplete.mjs

@@ -12,10 +12,11 @@ export function useOpenChangeComplete(parameters) {
     enabled = true,
     open,
     ref,
+    batch = false,
     onComplete: onCompleteParam
   } = parameters;
   const onComplete = useStableCallback(onCompleteParam);
-  const runOnceAnimationsFinish = useAnimationsFinished(ref, open, false);
+  const runOnceAnimationsFinish = useAnimationsFinished(ref, open, batch);
   React.useEffect(() => {
     if (!enabled) {
       return undefined;

package/internals/usePressAndHold.d.mts

@@ -2,7 +2,6 @@ import * as React from 'react';
 export declare function isTouchLikePointerType(pointerType: string): pointerType is "pen" | "touch";
 export interface UsePressAndHoldParameters {
   disabled: boolean;
-  readOnly?: boolean | undefined;
   /**
    * Called on each tick during a hold. Return `false` to stop the auto-change sequence.
    */

package/internals/usePressAndHold.d.ts

@@ -2,7 +2,6 @@ import * as React from 'react';
 export declare function isTouchLikePointerType(pointerType: string): pointerType is "pen" | "touch";
 export interface UsePressAndHoldParameters {
   disabled: boolean;
-  readOnly?: boolean | undefined;
   /**
    * Called on each tick during a hold. Return `false` to stop the auto-change sequence.
    */