@lodev09/react-native-true-sheet 4.0.0-beta.2 → 4.0.0-beta.21

package/lib/module/TrueSheet.web.js

@@ -5,23 +5,24 @@ import { createElement, forwardRef, isValidElement, useCallback, useEffect, useI
 import { StyleSheet, useColorScheme, useWindowDimensions, View } from 'react-native';
 import { measurePeekContentHeight, TrueSheetPeekContext } from "./TrueSheetPeek.web.js";
 import { usePortalContainer, useRegisterSheet, useSheetStack } from "./TrueSheetProvider.web.js";
-import { COLOR_SURFACE_CONTAINER_LOW_DARK, COLOR_SURFACE_CONTAINER_LOW_LIGHT, DEFAULT_ANCHOR_OFFSET, DEFAULT_CORNER_RADIUS, DEFAULT_DETACHED_OFFSET, DEFAULT_FORM_SHEET_HEIGHT_RATIO, DEFAULT_FORM_SHEET_WIDTH, DEFAULT_GRABBER_COLOR_DARK, DEFAULT_GRABBER_COLOR_LIGHT, DEFAULT_GRABBER_HEIGHT, DEFAULT_GRABBER_TOP_MARGIN, DEFAULT_GRABBER_WIDTH, DEFAULT_MAX_WIDTH } from "./web/constants.js";
+import { COLOR_SURFACE_CONTAINER_LOW_DARK, COLOR_SURFACE_CONTAINER_LOW_LIGHT, DEFAULT_PLACEMENT_OFFSET, DEFAULT_CORNER_RADIUS, DEFAULT_DETACHED_OFFSET, DEFAULT_FORM_SHEET_HEIGHT_RATIO, DEFAULT_FORM_SHEET_WIDTH, DEFAULT_GRABBER_COLOR_DARK, DEFAULT_GRABBER_COLOR_LIGHT, DEFAULT_GRABBER_HEIGHT, DEFAULT_GRABBER_TOP_MARGIN, DEFAULT_GRABBER_WIDTH, DEFAULT_MAX_WIDTH } from "./web/constants.js";
 import { getDOMElement } from "./web/dom.js";
+import { TrueSheetBackground } from "./TrueSheetBackground.js";
+import { getDetentBackgroundIndex, normalizeDetentBackground } from "./detentBackgrounds.js";
+import { observeSheetLayout } from "./web/layout.js";
 import { Drawer } from "./web/vaul/index.js";
-import { DEFAULT_PEEK_HEIGHT, TRANSITIONS } from "./web/vaul/constants.js";
+import { DEFAULT_PEEK_HEIGHT, DRAG_CLASS, TRANSITIONS } from "./web/vaul/constants.js";
 
-// First vertically scrollable descendant — web mirror of native's
-// findScrollView (RN-web ScrollView/FlatList render a node with
-// `overflow-y: auto`; its first child is the content container).
-import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
-const findVerticalScroller = root => {
-  for (const el of root.querySelectorAll('*')) {
-    const {
-      overflowY
-    } = window.getComputedStyle(el);
-    if (overflowY === 'auto' || overflowY === 'scroll') return el;
-  }
-  return null;
+// Resolves the user's `scrollableRef` to its scrollable DOM element — RN-web
+// ScrollView refs expose the scroll node directly (with helpers attached);
+// list refs (e.g. FlatList) expose it via getScrollableNode(). The node's
+// first child is the content container.
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+const getScrollableElement = scrollable => {
+  if (!scrollable) return null;
+  if (scrollable instanceof HTMLElement) return scrollable;
+  const node = scrollable.getScrollableNode?.();
+  return node instanceof HTMLElement ? node : null;
 };
 const TrueSheetComponent = /*#__PURE__*/forwardRef((props, ref) => {
   const {
@@ -29,13 +30,19 @@ const TrueSheetComponent = /*#__PURE__*/forwardRef((props, ref) => {
     name,
     dismissible = true,
     draggable = true,
+    dismissThreshold = 'half',
     cornerRadius,
     style,
     backgroundColor: backgroundColorProp,
+    detentBackgrounds,
+    background,
+    backgroundStyle,
     maxContentHeight,
     maxContentWidth,
-    anchor = 'center',
-    anchorOffset = DEFAULT_ANCHOR_OFFSET,
+    placement = 'automatic',
+    placementOffset = DEFAULT_PLACEMENT_OFFSET,
+    scrollableRef,
+    scrollableOptions,
     grabber = true,
     grabberOptions,
     accessibilityOptions,
@@ -60,6 +67,7 @@ const TrueSheetComponent = /*#__PURE__*/forwardRef((props, ref) => {
     onDidPresent,
     onWillDismiss,
     onDidDismiss,
+    onDismissAttempt,
     onDetentChange,
     onDragBegin,
     onDragChange,
@@ -91,9 +99,13 @@ const TrueSheetComponent = /*#__PURE__*/forwardRef((props, ref) => {
   // is explicitly set.
   const effectiveDetached = isFormSheet || detached;
   const colorScheme = useColorScheme();
-  const backgroundColor = backgroundColorProp ?? (colorScheme === 'dark' ? COLOR_SURFACE_CONTAINER_LOW_DARK : COLOR_SURFACE_CONTAINER_LOW_LIGHT);
   const shouldAutoPresent = initialDetentIndex >= 0 && initialDetentIndex < validDetents.length;
   const [isOpen, setIsOpen] = useState(shouldAutoPresent);
+  const isOpenRef = useRef(isOpen);
+  isOpenRef.current = isOpen;
+  const isPresentingRef = useRef(shouldAutoPresent);
+  const [displayedBackgroundIndex, setDisplayedBackgroundIndex] = useState(shouldAutoPresent ? initialDetentIndex : 0);
+  const backgroundColor = normalizeDetentBackground(detentBackgrounds?.[Math.min(displayedBackgroundIndex, validDetents.length - 1)])?.color ?? backgroundColorProp ?? (colorScheme === 'dark' ? COLOR_SURFACE_CONTAINER_LOW_DARK : COLOR_SURFACE_CONTAINER_LOW_LIGHT);
   const [activeSnapPoint, setActiveSnapPoint] = useState(() => validDetents[shouldAutoPresent ? initialDetentIndex : 0] ?? null);
 
   // Keep activeSnapPoint valid if detents change (e.g., prop updates).
@@ -103,7 +115,6 @@ const TrueSheetComponent = /*#__PURE__*/forwardRef((props, ref) => {
   }, [validDetents]);
   const validDetentsRef = useRef(validDetents);
   validDetentsRef.current = validDetents;
-  const hasAutoDetent = validDetents.includes('auto');
   const handleSetActiveSnapPoint = useCallback(snapPoint => {
     setActiveSnapPoint(snapPoint == null ? null : typeof snapPoint === 'number' || snapPoint === 'auto' || snapPoint === 'peek' ? snapPoint : null);
   }, []);
@@ -122,24 +133,43 @@ const TrueSheetComponent = /*#__PURE__*/forwardRef((props, ref) => {
       e.preventDefault();
       return;
     }
+    if (!(target instanceof Element)) return;
+    const wrapper = drawerContentRef.current?.closest('[data-vaul-detached-wrapper]');
+    if (!wrapper) return;
     // The footer is rendered via vaul's `detachedSiblings` as a sibling of
     // Drawer.Content inside [data-vaul-detached-wrapper], so Radix treats
     // clicks on it as "outside" the content. Don't dismiss for clicks that
     // landed inside the wrapper.
-    if (target instanceof Element) {
-      const wrapper = drawerContentRef.current?.closest('[data-vaul-detached-wrapper]');
-      if (wrapper && wrapper.contains(target)) {
-        e.preventDefault();
-      }
+    if (wrapper.contains(target)) {
+      e.preventDefault();
+      return;
     }
+    // Every sheet runs Radix non-modal and portals its overlay + wrapper as
+    // siblings into the shared container, so a press on a sheet stacked above
+    // this one (its content or its dim overlay) is also delivered here as
+    // "outside". Sheets present in document order, so anything after our
+    // wrapper belongs to a descendant. Radix may dispatch on the deferred
+    // click (touch), after a dismissing descendant has left the DOM — treat
+    // disconnected as above too.
+    /* eslint-disable no-bitwise */
+    const above = Node.DOCUMENT_POSITION_FOLLOWING | Node.DOCUMENT_POSITION_DISCONNECTED;
+    if (wrapper.compareDocumentPosition(target) & above) {
+      e.preventDefault();
+    }
+    /* eslint-enable no-bitwise */
   };
   const dismissAboveRef = useRef(async () => {});
+  const dismissDescendantsRef = useRef(() => {});
   const methods = useMemo(() => ({
     present: async (index = 0) => {
       const detent = validDetentsRef.current[index];
       if (detent === undefined) {
         throw new Error(`TrueSheet: present index (${index}) is out of bounds. detents array has ${validDetentsRef.current.length} item(s)`);
       }
+      if (!isOpenRef.current) {
+        isPresentingRef.current = true;
+        setDisplayedBackgroundIndex(index);
+      }
       setActiveSnapPoint(detent);
       setIsOpen(true);
     },
@@ -185,17 +215,40 @@ const TrueSheetComponent = /*#__PURE__*/forwardRef((props, ref) => {
   const [peekContentHeight, setPeekContentHeight] = useState(0);
   const contentRef = useRef(null);
   const peekElRef = useRef(null);
+  const measurePeek = useCallback(() => {
+    const peekEl = getDOMElement(peekElRef.current);
+    const contentEl = getDOMElement(contentRef.current);
+    if (peekEl && contentEl) {
+      setPeekContentHeight(measurePeekContentHeight(peekEl, contentEl));
+    }
+  }, []);
+
+  // Last-attached wins — during a screen swap the incoming peek mounts before
+  // the outgoing one unmounts, so the outgoing detach must not clear it.
   const peekContext = useMemo(() => ({
     contentRef,
-    peekRef: peekElRef,
-    setPeekContentHeight
-  }), []);
+    attachPeek: view => {
+      peekElRef.current = view;
+      measurePeek();
+    },
+    detachPeek: view => {
+      if (peekElRef.current !== view) return;
+      peekElRef.current = null;
+      setPeekContentHeight(0);
+    },
+    measurePeek: view => {
+      if (peekElRef.current === view) measurePeek();
+    }
+  }), [measurePeek]);
+
+  // The peek's own onLayout only fires when *it* resizes. Content added above
+  // it moves it without resizing it, so re-measure its offset whenever the
+  // content view's layout changes.
+  const handleContentLayout = measurePeek;
 
   // An absolute (floating) header overlaps the content, so it contributes no
   // height to the 'auto' detent measurement.
   const absoluteHeader = headerOptions?.position === 'absolute';
-  const absoluteHeaderRef = useRef(absoluteHeader);
-  absoluteHeaderRef.current = absoluteHeader;
   const resolvedHeaderStyle = absoluteHeader ? [absoluteHeaderStyle, headerStyle] : headerStyle;
 
   // Same for an absolute (floating) footer — rendered via vaul's
@@ -222,115 +275,54 @@ const TrueSheetComponent = /*#__PURE__*/forwardRef((props, ref) => {
   // A relative footer is laid out below the content, so it's pushed off-screen
   // at the peek detent and contributes no height.
   const peekHeight = (header ? headerHeight : 0) + (footer && absoluteFooter ? footerHeight : 0) + peekContentHeight || DEFAULT_PEEK_HEIGHT;
-
-  // Web mirror of native's scrollable handling for 'auto' detents: a plugged
-  // scrollable keeps the sized (bounded) layout so its viewport is capped to
-  // the visible sheet and can scroll, while the 'auto' height is measured with
-  // the viewport replaced by the scrollable's content size — mirrors native
-  // `naturalHeight`.
-  const [hasBoundedScrollable, setHasBoundedScrollable] = useState(false);
-  const [scrollableAutoHeight, setScrollableAutoHeight] = useState(0);
-  const pinnedScrollerRef = useRef(null);
-
-  // Natural content height (header + content + footer, with a pinned
-  // scrollable's viewport replaced by its content size) — the height the
-  // content wants regardless of the sheet's bounds.
-  const measureNaturalHeight = useCallback(() => {
-    const contentEl = getDOMElement(contentRef.current);
-    if (!contentEl || !contentEl.isConnected) return 0;
-    const headerEl = absoluteHeaderRef.current ? null : getDOMElement(headerElRef.current);
-    const footerEl = absoluteFooterRef.current ? null : getDOMElement(footerElRef.current);
-    let height = (headerEl?.offsetHeight ?? 0) + (footerEl?.offsetHeight ?? 0) + contentEl.offsetHeight;
-    const scroller = pinnedScrollerRef.current;
-    const scrollContent = scroller?.firstElementChild;
-    if (scroller?.isConnected && scrollContent instanceof HTMLElement) {
-      height += scrollContent.offsetHeight - scroller.clientHeight;
-    }
-    return Math.max(0, height);
-  }, []);
+  const [measuredContentHeight, setMeasuredContentHeight] = useState(0);
+  const naturalHeightRef = useRef(0);
+  const insetBehavior = scrollableOptions?.contentInsetAdjustment ?? 'automatic';
+  const footerInsetAdjustment = Boolean(footer) && absoluteFooter && (insetBehavior === 'automatic' || insetBehavior === 'footer');
+  const measureContent = validDetents.includes('auto') || isFormSheet;
   useEffect(() => {
-    if (!isOpen || !hasAutoDetent) return undefined;
+    if (!isOpen) return undefined;
     let canceled = false;
     let rafId = 0;
-    let mutationObserver = null;
-    let resizeObserver = null;
+    let observer;
     const attach = () => {
       if (canceled) return;
-      const drawerEl = drawerContentRef.current;
-      if (!drawerEl || !drawerEl.isConnected) {
+      const layoutEl = sizedLayoutRef.current;
+      const drawer = drawerContentRef.current;
+      if (!drawer || !layoutEl?.isConnected) {
         // Radix Presence defers the portal mount; poll until the drawer is live.
         rafId = window.requestAnimationFrame(attach);
         return;
       }
-      const measure = () => setScrollableAutoHeight(measureNaturalHeight());
-      let observed = null;
-
-      // (Re)pin the first vertical scrollable and observe the nodes whose size
-      // feeds the natural height — content growth inside a bounded scroller is
-      // invisible to the sheet's own layout (mirrors native's contentSize
-      // observation). Resolves the content node live: the layout-branch swap
-      // (natural flow ↔ sized) remounts it.
-      const observe = () => {
-        const contentEl = getDOMElement(contentRef.current);
-        const headerEl = getDOMElement(headerElRef.current);
-
-        // Skip mutations that don't change the observed topology — e.g. a
-        // virtualized list mounting rows inside the pinned scroller, which
-        // would otherwise trigger a full-subtree rescan (findVerticalScroller
-        // resolves computed styles) on every scroll frame. Size changes are
-        // already covered by the ResizeObserver.
-        if (observed && observed.contentEl === contentEl && contentEl?.isConnected && observed.headerEl === headerEl && observed.scroller.isConnected && observed.scrollContent === observed.scroller.firstElementChild) {
-          return;
+      observer = observeSheetLayout({
+        drawer,
+        layout: layoutEl,
+        getContent: () => getDOMElement(contentRef.current),
+        getHeader: () => getDOMElement(headerElRef.current),
+        getFooter: () => getDOMElement(footerElRef.current),
+        getScrollable: () => getScrollableElement(scrollableRef?.current),
+        absoluteHeader,
+        absoluteFooter,
+        footerInsetAdjustment,
+        measureContent,
+        onHeightChange: height => {
+          naturalHeightRef.current = height;
+          setMeasuredContentHeight(height);
         }
-        const scroller = contentEl && contentEl.isConnected ? findVerticalScroller(contentEl) : null;
-        pinnedScrollerRef.current = scroller;
-        setHasBoundedScrollable(scroller != null);
-        observed = scroller ? {
-          contentEl,
-          headerEl,
-          scroller,
-          scrollContent: scroller.firstElementChild
-        } : null;
-        resizeObserver?.disconnect();
-        resizeObserver = new ResizeObserver(measure);
-        if (contentEl?.isConnected) resizeObserver.observe(contentEl);
-        if (headerEl) resizeObserver.observe(headerEl);
-        if (scroller) {
-          resizeObserver.observe(scroller);
-          if (scroller.firstElementChild) resizeObserver.observe(scroller.firstElementChild);
-        }
-        measure();
-      };
-      observe();
-      // Watch the whole drawer subtree — catches the scrollable mounting/
-      // unmounting AND the layout-branch swap, which remounts the content node
-      // (a content-scoped observer would go stale after the swap).
-      mutationObserver = new MutationObserver(observe);
-      mutationObserver.observe(drawerEl, {
-        childList: true,
-        subtree: true
       });
     };
     rafId = window.requestAnimationFrame(attach);
     return () => {
       canceled = true;
       window.cancelAnimationFrame(rafId);
-      mutationObserver?.disconnect();
-      resizeObserver?.disconnect();
+      observer?.disconnect();
     };
-  }, [isOpen, hasAutoDetent, measureNaturalHeight]);
+  }, [isOpen, absoluteHeader, absoluteFooter, footerInsetAdjustment, measureContent, scrollableRef]);
 
   // Below the last detent a vertical touch pan moves the sheet, not the
   // content — `[data-vaul-scroll-locked]` disables vertical touch panning on
   // the scroll container and everything inside it (see vaul/style.css).
   const isScrollLocked = validDetents.length > 0 && activeSnapPoint !== validDetents[validDetents.length - 1];
-
-  // Vaul measures the auto-size wrapper's offsetHeight (always, post fork).
-  // Track it here so the form sheet can size its card to fit content,
-  // clamped between a minimum ratio of the viewport and a maximum derived
-  // from `detachedOffset` (the breathing room left at top + bottom of the
-  // floating card).
-  const [measuredContentHeight, setMeasuredContentHeight] = useState(0);
   const effectiveMaxContentHeight = useMemo(() => {
     if (maxContentHeight !== undefined) return maxContentHeight;
     if (!isFormSheet) return undefined;
@@ -393,16 +385,14 @@ const TrueSheetComponent = /*#__PURE__*/forwardRef((props, ref) => {
     effectiveDetachedOffset,
     effectiveMaxContentHeight,
     peekHeight,
-    peekContentHeight,
-    measuredContentHeight
+    peekContentHeight
   });
   geometryInputsRef.current = {
     effectiveDetached,
     effectiveDetachedOffset,
     effectiveMaxContentHeight,
     peekHeight,
-    peekContentHeight,
-    measuredContentHeight
+    peekContentHeight
   };
   const computeDetentGeometry = useCallback(() => {
     const inputs = geometryInputsRef.current;
@@ -410,12 +400,9 @@ const TrueSheetComponent = /*#__PURE__*/forwardRef((props, ref) => {
     const effectiveH = inputs.effectiveDetached ? windowH - inputs.effectiveDetachedOffset : windowH;
     // Matches vaul's height ceiling: min(effectiveH, maxContentHeight).
     const ceiling = inputs.effectiveMaxContentHeight !== undefined ? Math.min(effectiveH, inputs.effectiveMaxContentHeight) : effectiveH;
-    // 'auto' resolves to the content's natural height. Read it live — the
-    // `measuredContentHeight` state lags mount by a frame (vaul's initial
-    // ref-callback measure runs while the portal subtree is still detached,
-    // so it reads 0 until the ResizeObserver fires). Falls back to the state
-    // value, then to vaul's pre-measure fallback (effectiveHeight / 2).
-    const measuredHeight = measureNaturalHeight() || inputs.measuredContentHeight;
+    // Reuse the intrinsic measurement during position events so animation
+    // frames don't clone the content tree again.
+    const measuredHeight = naturalHeightRef.current;
     const autoHeight = Math.min(measuredHeight > 0 ? measuredHeight : effectiveH / 2, ceiling);
 
     // 'peek' is measured live from the DOM (offsetHeight is layout-based, so
@@ -446,7 +433,7 @@ const TrueSheetComponent = /*#__PURE__*/forwardRef((props, ref) => {
       positions,
       values
     };
-  }, [measureNaturalHeight]);
+  }, []);
 
   // Detent info for lifecycle events. Position/detent come from the active
   // detent's target geometry — not the live DOM rect — so willPresent (drawer
@@ -533,50 +520,20 @@ const TrueSheetComponent = /*#__PURE__*/forwardRef((props, ref) => {
       detent: values[count - 1]
     };
   }, [computeDetentGeometry]);
-
-  // Mirror native synchronous layout: while dragging (and through the post-
-  // release settle) the sized layout tracks the sheet's visible height in
-  // realtime, clamped to the smallest detent — dragging below it slides the
-  // sheet out without resizing. Once settled, the inline height is cleared so
-  // the CSS calc() owns sizing again (adapts to viewport resizes at rest).
   const sizedLayoutRef = useRef(null);
   const isDraggingRef = useRef(false);
-  const isSettlingAfterDragRef = useRef(false);
-  const updateSizedLayoutHeight = useCallback(position => {
-    const node = sizedLayoutRef.current;
-    if (!node) return;
-    const {
-      effectiveH,
-      ceiling,
-      positions
-    } = computeDetentGeometry();
-    if (positions.length === 0) return;
-    if (isSettlingAfterDragRef.current) {
-      const snap = activeSnapPointRef.current;
-      const index = snap != null ? validDetentsRef.current.indexOf(snap) : -1;
-      const target = index >= 0 ? positions[index] : null;
-      if (target != null && Math.abs(position - target) < 1) {
-        isSettlingAfterDragRef.current = false;
-        // Restore the calc — height is an inline style, so clearing it would
-        // leave the div unsized (React won't re-apply it without a render)
-        node.style.height = SIZED_LAYOUT_HEIGHT;
-        return;
-      }
-    }
-
-    // positions[0] is the smallest detent's top-Y — its height is the clamp floor.
-    const minHeight = effectiveH - positions[0];
-    const height = Math.min(Math.max(effectiveH - position, minHeight), ceiling);
-    node.style.height = `${height}px`;
-  }, [computeDetentGeometry]);
   const handlePositionChange = useCallback(position => {
-    if (isDraggingRef.current || isSettlingAfterDragRef.current) {
-      updateSizedLayoutHeight(position);
-    }
     const {
       index,
       detent
     } = interpolateFromPosition(position);
+    if (isOpenRef.current && !isPresentingRef.current) {
+      const {
+        effectiveH,
+        positions
+      } = computeDetentGeometry();
+      setDisplayedBackgroundIndex(current => getDetentBackgroundIndex(effectiveH - position, positions.map(top => effectiveH - top), current));
+    }
     onPositionChangeRef.current?.({
       nativeEvent: {
         index,
@@ -585,7 +542,7 @@ const TrueSheetComponent = /*#__PURE__*/forwardRef((props, ref) => {
         realtime: true
       }
     });
-  }, [interpolateFromPosition, updateSizedLayoutHeight]);
+  }, [interpolateFromPosition, computeDetentGeometry]);
 
   // Fire onMount once after first render. React-mount is the earliest point
   // the component is ready for imperative calls, matching the native
@@ -611,6 +568,9 @@ const TrueSheetComponent = /*#__PURE__*/forwardRef((props, ref) => {
     if (isOpen === wasOpen) return undefined;
     const present = isOpen;
     if (!present) {
+      // Mirror native: dismissing a sheet takes every sheet stacked above it
+      // (iOS dismisses from the presenter; Android runs dismissStack first).
+      dismissDescendantsRef.current();
       // Pair willBlur with willDismiss on dismiss — mirrors native iOS
       // emitWillDismissEvents (blur fires before dismiss). willPresent is
       // deferred to `start()` below (needs the mounted drawer's geometry).
@@ -623,6 +583,7 @@ const TrueSheetComponent = /*#__PURE__*/forwardRef((props, ref) => {
     }
     const fireDone = () => {
       if (present) {
+        isPresentingRef.current = false;
         onDidPresentRef.current?.({
           nativeEvent: computeDetentInfo()
         });
@@ -728,12 +689,9 @@ const TrueSheetComponent = /*#__PURE__*/forwardRef((props, ref) => {
       nativeEvent: computeDetentInfo(true)
     });
   }, [computeDetentInfo]);
-  const handleRelease = useCallback((_event, open) => {
+  const handleRelease = useCallback(() => {
     if (!isDraggingRef.current) return;
     isDraggingRef.current = false;
-    // Track the sized layout through the settle animation only when the sheet
-    // stays open — a dismissal slides out at the min-clamped height.
-    isSettlingAfterDragRef.current = open;
     onDragEndRef.current?.({
       nativeEvent: computeDetentInfo(true)
     });
@@ -744,10 +702,18 @@ const TrueSheetComponent = /*#__PURE__*/forwardRef((props, ref) => {
     descendants
   } = useSheetStack(methodsRef, drawerContentRef, isOpen, isFormSheet);
   dismissAboveRef.current = dismissAbove;
+  // Captured per render: by the time the dismiss effect runs, this sheet has
+  // already been popped from the stack, so `dismissAbove` can't find it.
+  dismissDescendantsRef.current = () => {
+    for (let i = descendants.length - 1; i >= 0; i--) {
+      descendants[i].ref.current?.dismiss();
+    }
+  };
 
   // Mirror Android: translate this sheet down to match the deepest descendant's
   // top so the whole stack visually aligns. Cascades because every ancestor
   // re-runs whenever the stack (and thus its descendants) changes.
+  const wasCascadedRef = useRef(false);
   useEffect(() => {
     const parent = drawerContentRef.current;
     if (!parent) return;
@@ -758,7 +724,7 @@ const TrueSheetComponent = /*#__PURE__*/forwardRef((props, ref) => {
     // out — nothing to align with anymore.
     if (!isOpen) return;
     const parentWrapper = parent.closest('[data-vaul-detached-wrapper]');
-    const transition = `transform ${TRANSITIONS.DURATION}s cubic-bezier(${TRANSITIONS.EASE.join(',')})`;
+    const transition = `transform ${TRANSITIONS.DURATION}s cubic-bezier(${TRANSITIONS.EASE.join(',')}), --snap-point-height ${TRANSITIONS.DURATION}s cubic-bezier(${TRANSITIONS.EASE.join(',')})`;
     const wrapperTransition = `clip-path ${TRANSITIONS.DURATION}s cubic-bezier(${TRANSITIONS.EASE.join(',')})`;
     const CLIP_NONE = 'inset(0px round 0px)';
 
@@ -781,22 +747,29 @@ const TrueSheetComponent = /*#__PURE__*/forwardRef((props, ref) => {
       parentWrapper.style.clipPath = next;
     };
     if (descendants.length === 0) {
+      if (!wasCascadedRef.current) return;
+      wasCascadedRef.current = false;
       parent.style.transition = transition;
       parent.style.transform = '';
       setClip(CLIP_NONE);
       return;
     }
+    wasCascadedRef.current = true;
 
-    // Track only the immediate child's snap point. Walking deeper descendants
-    // would push this sheet further when a grandchild opens, even when our
-    // own child didn't move (e.g., child skipped its cascade for a page
-    // grandchild) — leaving a visible gap between this sheet and its child.
+    // Track the immediate child's *actual* top: its cascade transform when it
+    // was itself pushed behind a grandchild, else its own snap point. Mirrors
+    // Android's addTranslation propagating extra translation up the stack —
+    // a grandchild opening pushes this sheet only as far as our child moved.
+    const readTranslateY = el => {
+      const match = el.style.transform.match(/translate3d\([^,]*,\s*(-?\d*\.?\d+)px/);
+      return match ? Number.parseFloat(match[1]) : null;
+    };
     const computeTargetY = () => {
       const parentSnap = Number.parseFloat(parent.style.getPropertyValue('--snap-point-height')) || 0;
       const node = descendants[0]?.nodeRef.current;
       if (!node) return parentSnap;
-      const childSnap = Number.parseFloat(node.style.getPropertyValue('--snap-point-height')) || 0;
-      return Math.max(parentSnap, childSnap);
+      const childTop = readTranslateY(node) ?? (Number.parseFloat(node.style.getPropertyValue('--snap-point-height')) || 0);
+      return Math.max(parentSnap, childTop);
     };
 
     // When a form-sheet parent has a form-sheet descendant, clip the parent to
@@ -830,18 +803,26 @@ const TrueSheetComponent = /*#__PURE__*/forwardRef((props, ref) => {
     };
     const apply = () => {
       applyFormClip();
-      // Mirror iOS: a page-sheet child fully covers a form-sheet parent, so the
-      // cascade push-down has no visible effect — and would briefly peek above
-      // the page during the present animation. Leave the parent put.
-      const child = descendants[0];
-      if (isFormSheet && child && !child.isFormSheetRef.current) {
+      // Mirror iPad/Android (`isExpanded`): a parent at full height (detent 1)
+      // stays put and the child simply overlays it. Full height is the sheet's
+      // own ceiling — the viewport for a page sheet, the capped content-fit
+      // height for a form sheet — so compare against where detent 1 lands.
+      const parentSnap = Number.parseFloat(parent.style.getPropertyValue('--snap-point-height')) || 0;
+      const {
+        effectiveH,
+        ceiling
+      } = computeDetentGeometry();
+      if (parentSnap <= effectiveH - ceiling + 0.5) {
         parent.style.transition = transition;
         parent.style.transform = '';
         return;
       }
+      // Mirror Android: stay put while the child is being dragged (its live
+      // transform would drag us along during drag-to-dismiss). The release
+      // snap rewrites the child's style and re-applies.
+      if (descendants[0]?.nodeRef.current?.classList.contains(DRAG_CLASS)) return;
       const targetY = computeTargetY();
-      const match = parent.style.transform.match(/translate3d\([^,]*,\s*(-?\d*\.?\d+)px/);
-      const currentY = match ? Number.parseFloat(match[1]) : 0;
+      const currentY = readTranslateY(parent) ?? 0;
       if (Math.abs(currentY - targetY) < 0.5) return;
       parent.style.transition = transition;
       parent.style.transform = `translate3d(0, ${targetY}px, 0)`;
@@ -855,11 +836,17 @@ const TrueSheetComponent = /*#__PURE__*/forwardRef((props, ref) => {
       attributes: true,
       attributeFilter: ['style']
     });
+    // The child's own cascade lands in a later frame — follow it when it moves.
+    const childNode = descendants[0]?.nodeRef.current;
+    if (childNode) observer.observe(childNode, {
+      attributes: true,
+      attributeFilter: ['style']
+    });
     return () => {
       cancelAnimationFrame(raf);
       observer.disconnect();
     };
-  }, [descendants, activeSnapPoint, cornerRadius, isFormSheet, isOpen]);
+  }, [descendants, activeSnapPoint, cornerRadius, isFormSheet, isOpen, computeDetentGeometry]);
 
   // Focus/blur events fire when a descendant sheet appears on top of this one
   // (blur) or when all descendants are dismissed (focus). will-events fire
@@ -870,12 +857,19 @@ const TrueSheetComponent = /*#__PURE__*/forwardRef((props, ref) => {
   const onDidBlurRef = useRef(onDidBlur);
   const onWillFocusRef = useRef(onWillFocus);
   const onDidFocusRef = useRef(onDidFocus);
+  const onDismissAttemptRef = useRef(onDismissAttempt);
   useEffect(() => {
     onWillBlurRef.current = onWillBlur;
     onDidBlurRef.current = onDidBlur;
     onWillFocusRef.current = onWillFocus;
     onDidFocusRef.current = onDidFocus;
+    onDismissAttemptRef.current = onDismissAttempt;
   });
+  const handleDismissAttempt = useCallback(() => {
+    onDismissAttemptRef.current?.({
+      nativeEvent: null
+    });
+  }, []);
   const prevDescendantCountRef = useRef(0);
   useEffect(() => {
     const prevCount = prevDescendantCountRef.current;
@@ -924,11 +918,6 @@ const TrueSheetComponent = /*#__PURE__*/forwardRef((props, ref) => {
       window.cancelAnimationFrame(rafId);
     };
   }, [isOpen, descendants.length]);
-
-  // Definite-height flex layout (per-detent sizing) unless content must be
-  // measured in natural flow: 'auto' detents (without a plugged scrollable —
-  // those measure via `measureNaturalHeight`) and form-sheet content-fit sizing.
-  const useSizedLayout = (!hasAutoDetent || hasBoundedScrollable) && !isFormSheet;
   const effectiveCornerRadius = cornerRadius ?? DEFAULT_CORNER_RADIUS;
 
   // Shadow cast upward from the sheet's top edge toward the background. Matches
@@ -942,6 +931,13 @@ const TrueSheetComponent = /*#__PURE__*/forwardRef((props, ref) => {
   // wrapper edges). drop-shadow on the wrapper follows the post-clip silhouette
   // and isn't clipped by the wrapper itself.
   const dropShadow = elevation > 0 ? `drop-shadow(0 ${-elevation}px ${elevation * 3}px rgba(0, 0, 0, 0.15))` : undefined;
+  const backgroundLayerStyle = {
+    position: 'absolute',
+    inset: 0,
+    pointerEvents: 'none',
+    backgroundColor: backgroundColor,
+    transition: isPresentingRef.current ? 'none' : 'background-color 200ms'
+  };
   const mergedContentStyle = useMemo(() => ({
     position: 'fixed',
     top: 0,
@@ -952,7 +948,6 @@ const TrueSheetComponent = /*#__PURE__*/forwardRef((props, ref) => {
     flexDirection: 'column',
     borderTopLeftRadius: effectiveCornerRadius,
     borderTopRightRadius: effectiveCornerRadius,
-    backgroundColor: backgroundColor,
     // Clip children to the rounded top so headers/content with their own
     // background don't bleed past the corners. `clip` (not `hidden`): a
     // hidden box is still a scroll container, so browser focus-reveal (e.g.
@@ -962,8 +957,11 @@ const TrueSheetComponent = /*#__PURE__*/forwardRef((props, ref) => {
     // Lift content above iOS home indicator / bottom safe area when enabled.
     // A relative footer owns the inset instead (see resolvedFooterStyle); an
     // absolute footer floats over the content, so the content keeps its lift.
-    paddingBottom: insetAdjustment === 'automatic' && !(footerOwnsInset && !absoluteFooter) ? 'env(safe-area-inset-bottom, 0px)' : 0
-  }), [backgroundColor, effectiveCornerRadius, insetAdjustment, footerOwnsInset, absoluteFooter]);
+    // A plugged scrollable keeps the lift too (contentInsetAdjustment
+    // 'automatic' | 'safe-area') — 'footer' | 'never' scroll edge-to-edge
+    // behind the indicator with user-applied content padding.
+    paddingBottom: insetAdjustment === 'automatic' && !(footerOwnsInset && !absoluteFooter) && (!scrollableRef || insetBehavior === 'automatic' || insetBehavior === 'safe-area') ? 'env(safe-area-inset-bottom, 0px)' : 0
+  }), [effectiveCornerRadius, insetAdjustment, footerOwnsInset, absoluteFooter, scrollableRef, insetBehavior]);
   const defaultGrabberColor = colorScheme === 'dark' ? DEFAULT_GRABBER_COLOR_DARK : DEFAULT_GRABBER_COLOR_LIGHT;
   const grabberHeight = grabberOptions?.height ?? DEFAULT_GRABBER_HEIGHT;
 
@@ -994,7 +992,7 @@ const TrueSheetComponent = /*#__PURE__*/forwardRef((props, ref) => {
   //   `maxContentWidth` is ignored ('form' is absolute).
   // - presentation='page' → `maxContentWidth` (any viewport) or
   //   DEFAULT_MAX_WIDTH (tablet/landscape readability cap).
-  // Detached without a width constraint applies anchorOffset on both edges so
+  // Detached without a width constraint applies placementOffset on both edges so
   // the floating card breathes from the viewport sides.
   const wrapperStyle = useMemo(() => {
     // Mobile portrait ignores width sizing entirely (matches iOS/Android:
@@ -1006,23 +1004,23 @@ const TrueSheetComponent = /*#__PURE__*/forwardRef((props, ref) => {
     const next = {};
     if (dropShadow) next.filter = dropShadow;
     if (!needsMargins) return next;
-    let marginLeft;
-    let marginRight;
+    let marginInlineStart;
+    let marginInlineEnd;
     if (isFormSheet) {
-      marginLeft = 'auto';
-      marginRight = 'auto';
+      marginInlineStart = 'auto';
+      marginInlineEnd = 'auto';
     } else if (maxWidth == null) {
-      marginLeft = anchorOffset;
-      marginRight = anchorOffset;
+      marginInlineStart = placementOffset;
+      marginInlineEnd = placementOffset;
     } else {
-      marginLeft = anchor === 'left' ? anchorOffset : 'auto';
-      marginRight = anchor === 'right' ? anchorOffset : 'auto';
+      marginInlineStart = placement === 'leading' ? placementOffset : 'auto';
+      marginInlineEnd = placement === 'trailing' ? placementOffset : 'auto';
     }
     if (maxWidth != null) next.maxWidth = maxWidth;
-    next.marginLeft = marginLeft;
-    next.marginRight = marginRight;
+    next.marginInlineStart = marginInlineStart;
+    next.marginInlineEnd = marginInlineEnd;
     return next;
-  }, [isLandscapeOrTablet, isFormSheet, maxContentWidth, presentation, anchor, anchorOffset, effectiveDetached, dropShadow]);
+  }, [isLandscapeOrTablet, isFormSheet, maxContentWidth, presentation, placement, placementOffset, effectiveDetached, dropShadow]);
 
   // Absolute-position the grabber so it overlays the content top-edge
   // instead of consuming flow height — mirrors native iOS/Android, where
@@ -1052,6 +1050,8 @@ const TrueSheetComponent = /*#__PURE__*/forwardRef((props, ref) => {
       onDrag: handleDrag,
       onRelease: handleRelease,
       dismissible: dismissible,
+      dismissThreshold: dismissThreshold,
+      onDismissAttempt: handleDismissAttempt,
       draggable: draggable,
       repositionInputs: false,
       modal: dimmed,
@@ -1063,11 +1063,7 @@ const TrueSheetComponent = /*#__PURE__*/forwardRef((props, ref) => {
       peekHeight: peekHeight,
       initialAnimated: initialDetentAnimated,
       detachedWrapperStyle: wrapperStyle,
-      onContentHeightChange: setMeasuredContentHeight,
-      contentHeight:
-      // Bounded scrollable → the auto-size wrapper measures 0 (sized
-      // layout is absolute), so feed vaul the natural height instead.
-      hasAutoDetent && hasBoundedScrollable && scrollableAutoHeight > 0 ? scrollableAutoHeight : undefined,
+      contentHeight: measuredContentHeight,
       activeSnapPoint: activeSnapPoint,
       setActiveSnapPoint: handleSetActiveSnapPoint,
       ...snapPointsProps,
@@ -1088,31 +1084,30 @@ const TrueSheetComponent = /*#__PURE__*/forwardRef((props, ref) => {
               children: /*#__PURE__*/isValidElement(footer) ? footer : /*#__PURE__*/createElement(footer)
             })
           }) : undefined,
-          children: [/*#__PURE__*/_jsx(Drawer.Title, {
+          children: [/*#__PURE__*/_jsx("div", {
+            "aria-hidden": true,
+            style: backgroundLayerStyle
+          }), /*#__PURE__*/_jsx(Drawer.Title, {
             style: visuallyHiddenStyle,
             children: accessibilityOptions?.paneTitle ?? 'Sheet'
           }), grabber && /*#__PURE__*/_jsx(Drawer.Handle, {
             style: handleStyle
-          }), useSizedLayout ?
-          /*#__PURE__*/
-          // vaul wraps children in `[data-vaul-auto-size-wrapper]` (display:
-          // flow-root) which doesn't honor descendant flex layout. Use an
-          // absolute fill sized to the visible portion (via vaul's
-          // `--snap-point-height` var) so the inner flex column has a
-          // definite height for flex layouts to fill — mirrors native, where
-          // the container is sized to the sheet's visible height per detent.
-          _jsxs("div", {
+          }), /*#__PURE__*/_jsxs("div", {
             ref: sizedLayoutRef,
             style: sizedLayoutStyle,
             "data-vaul-scroll-locked": isScrollLocked ? '' : undefined,
-            children: [header && /*#__PURE__*/_jsx(View, {
+            children: [/*#__PURE__*/_jsx(TrueSheetBackground, {
+              background: background,
+              backgroundStyle: backgroundStyle
+            }), header && /*#__PURE__*/_jsx(View, {
               ref: headerElRef,
               style: resolvedHeaderStyle,
               onLayout: handleHeaderLayout,
               children: /*#__PURE__*/isValidElement(header) ? header : /*#__PURE__*/createElement(header)
             }), /*#__PURE__*/_jsx(View, {
               ref: contentRef,
-              style: hasAutoDetent && hasBoundedScrollable ? [contentFillStyle, style] : style,
+              style: [contentStyle, style],
+              onLayout: handleContentLayout,
               children: children
             }), footer && !absoluteFooter && /*#__PURE__*/_jsx(View, {
               ref: footerElRef,
@@ -1120,26 +1115,6 @@ const TrueSheetComponent = /*#__PURE__*/forwardRef((props, ref) => {
               onLayout: handleFooterLayout,
               children: /*#__PURE__*/isValidElement(footer) ? footer : /*#__PURE__*/createElement(footer)
             })]
-          }) :
-          /*#__PURE__*/
-          // Natural flow so vaul can measure content height — required for
-          // 'auto' detents and form-sheet content-fit sizing.
-          _jsxs(_Fragment, {
-            children: [header && /*#__PURE__*/_jsx(View, {
-              ref: headerElRef,
-              style: resolvedHeaderStyle,
-              onLayout: handleHeaderLayout,
-              children: /*#__PURE__*/isValidElement(header) ? header : /*#__PURE__*/createElement(header)
-            }), /*#__PURE__*/_jsx(View, {
-              ref: contentRef,
-              style: style,
-              children: children
-            }), footer && !absoluteFooter && /*#__PURE__*/_jsx(View, {
-              ref: footerElRef,
-              style: resolvedFooterStyle,
-              onLayout: handleFooterLayout,
-              children: /*#__PURE__*/isValidElement(footer) ? footer : /*#__PURE__*/createElement(footer)
-            })]
           })]
         })]
       })
@@ -1173,10 +1148,12 @@ const sizedLayoutStyle = {
   right: 0,
   height: SIZED_LAYOUT_HEIGHT,
   display: 'flex',
-  flexDirection: 'column'
+  flexDirection: 'column',
+  boxSizing: 'border-box',
+  paddingBottom: 'inherit'
 };
-const contentFillStyle = {
-  flex: 1,
+const contentStyle = {
+  flexShrink: 1,
   minHeight: 0
 };
 const visuallyHiddenStyle = {