@lodev09/react-native-true-sheet 4.0.0-beta.3 → 4.0.0-beta.30

package/src/TrueSheet.web.tsx

@@ -6,9 +6,11 @@ import {
   useCallback,
   useEffect,
   useImperativeHandle,
+  useLayoutEffect,
   useMemo,
   useRef,
   useState,
+  type RefObject,
 } from 'react';
 import type { DimensionValue, LayoutChangeEvent } from 'react-native';
 import { StyleSheet, useColorScheme, useWindowDimensions, View } from 'react-native';
@@ -31,15 +33,25 @@ import type {
   TrueSheetStaticMethods,
   WillBlurEvent,
   WillDismissEvent,
+  DismissAttemptEvent,
   WillFocusEvent,
   WillPresentEvent,
 } from './TrueSheet.types';
-import { measurePeekContentHeight, TrueSheetPeekContext } from './TrueSheetPeek.web';
-import { usePortalContainer, useRegisterSheet, useSheetStack } from './TrueSheetProvider.web';
+import {
+  measurePeekContentHeight,
+  TrueSheetPeekContext,
+  type TrueSheetPeekContextValue,
+} from './TrueSheetPeek.web';
+import {
+  usePortalContainer,
+  useRegisterSheet,
+  useSheetStack,
+  type SheetHandle,
+} from './TrueSheetProvider.web';
 import {
   COLOR_SURFACE_CONTAINER_LOW_DARK,
   COLOR_SURFACE_CONTAINER_LOW_LIGHT,
-  DEFAULT_ANCHOR_OFFSET,
+  DEFAULT_PLACEMENT_OFFSET,
   DEFAULT_CORNER_RADIUS,
   DEFAULT_DETACHED_OFFSET,
   DEFAULT_FORM_SHEET_HEIGHT_RATIO,
@@ -52,18 +64,19 @@ import {
   DEFAULT_MAX_WIDTH,
 } from './web/constants';
 import { getDOMElement } from './web/dom';
+import { TrueSheetBackground } from './TrueSheetBackground';
+import { getDetentBackgroundIndex, normalizeDetentBackground } from './detentBackgrounds';
+import { revealFocusedElement, useKeyboardViewport } from './web/keyboard';
+import { observeSheetLayout } from './web/layout';
+import { resolveScrollable } from './scrollable';
 import { Drawer } from './web/vaul';
-import { DEFAULT_PEEK_HEIGHT, TRANSITIONS } from './web/vaul/constants';
-
-// 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).
-const findVerticalScroller = (root: HTMLElement): HTMLElement | null => {
-  for (const el of root.querySelectorAll<HTMLElement>('*')) {
-    const { overflowY } = window.getComputedStyle(el);
-    if (overflowY === 'auto' || overflowY === 'scroll') return el;
-  }
-  return null;
+import { DEFAULT_PEEK_HEIGHT, DRAG_CLASS, TRANSITIONS } from './web/vaul/constants';
+
+// Resolves the user's `scrollableRef` to its scrollable DOM element. The
+// node's first child is the content container.
+const getScrollableElement = (scrollable: unknown): HTMLElement | null => {
+  const node = resolveScrollable(scrollable);
+  return node instanceof HTMLElement ? node : null;
 };
 
 const TrueSheetComponent = forwardRef<TrueSheetMethods, TrueSheetProps>((props, ref) => {
@@ -72,18 +85,26 @@ const TrueSheetComponent = forwardRef<TrueSheetMethods, TrueSheetProps>((props,
     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,
     detents = [0.5, 1],
     dimmed = true,
+    dimColor,
+    dimOpacity,
     dimmedDetentIndex = 0,
     initialDetentIndex = -1,
     header,
@@ -103,6 +124,7 @@ const TrueSheetComponent = forwardRef<TrueSheetMethods, TrueSheetProps>((props,
     onDidPresent,
     onWillDismiss,
     onDidDismiss,
+    onDismissAttempt,
     onDetentChange,
     onDragBegin,
     onDragChange,
@@ -143,12 +165,33 @@ const TrueSheetComponent = forwardRef<TrueSheetMethods, TrueSheetProps>((props,
   const effectiveDetached = isFormSheet || detached;
 
   const colorScheme = useColorScheme();
+  const shouldAutoPresent = initialDetentIndex >= 0 && initialDetentIndex < validDetents.length;
+  const didInitiallyPresentRef = useRef(shouldAutoPresent);
+  const [isOpen, setIsOpen] = useState(shouldAutoPresent);
+  const isOpenRef = useRef(isOpen);
+  isOpenRef.current = isOpen;
+  const keyboardViewport = useKeyboardViewport(isOpen);
+  const isPresentingRef = useRef(shouldAutoPresent);
+  // Native's lifecycle state — updated synchronously so calls in the same tick see each other
+  const phaseRef = useRef<SheetPhase>(shouldAutoPresent ? 'presenting' : 'dismissed');
+  const resolvePresentRef = useRef<(() => void) | null>(null);
+  const resolveDismissRef = useRef<(() => void) | null>(null);
+  // Whether willPresent fired for the current open cycle — a present undone
+  // before it fires has nothing to pair a dismiss with.
+  const didEmitWillPresentRef = useRef(false);
+  // Whether the current open cycle came from initialDetentIndex. Native mounts those
+  // eagerly, so a dismiss before willPresent lands after the present instead of cancelling it.
+  const isAutoPresentRef = useRef(shouldAutoPresent);
+  const shouldDismissOnPresentRef = useRef(false);
+  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 shouldAutoPresent = initialDetentIndex >= 0 && initialDetentIndex < validDetents.length;
-  const [isOpen, setIsOpen] = useState(shouldAutoPresent);
   const [activeSnapPoint, setActiveSnapPoint] = useState<SheetDetent | null>(
     () => validDetents[shouldAutoPresent ? initialDetentIndex : 0] ?? null
   );
@@ -164,8 +207,6 @@ const TrueSheetComponent = forwardRef<TrueSheetMethods, TrueSheetProps>((props,
   const validDetentsRef = useRef(validDetents);
   validDetentsRef.current = validDetents;
 
-  const hasAutoDetent = validDetents.includes('auto');
-
   const handleSetActiveSnapPoint = useCallback((snapPoint: number | string | null) => {
     setActiveSnapPoint(
       snapPoint == null
@@ -176,13 +217,31 @@ const TrueSheetComponent = forwardRef<TrueSheetMethods, TrueSheetProps>((props,
     );
   }, []);
 
+  // Returns null when there's nothing to dismiss. Resolves on didDismiss.
+  const dismissSheet = useCallback((): Promise<void> | null => {
+    if (phaseRef.current === 'dismissed' || phaseRef.current === 'dismissing') return null;
+    settle(resolvePresentRef);
+    if (didEmitWillPresentRef.current) {
+      setIsOpen(false);
+    } else if (isAutoPresentRef.current) {
+      shouldDismissOnPresentRef.current = true;
+    } else {
+      // Mirror native's lazy-mount cancel: nothing shown yet, nothing to animate out
+      setIsOpen(false);
+      phaseRef.current = 'dismissed';
+      return Promise.resolve();
+    }
+    phaseRef.current = 'dismissing';
+    return new Promise((resolve) => {
+      resolveDismissRef.current = resolve;
+    });
+  }, []);
+
   const handleOpenChange = useCallback(
     (open: boolean) => {
-      if (!open && isOpen) {
-        setIsOpen(false);
-      }
+      if (!open) dismissSheet();
     },
-    [isOpen]
+    [dismissSheet]
   );
 
   const portalContainer = usePortalContainer();
@@ -196,34 +255,67 @@ const TrueSheetComponent = forwardRef<TrueSheetMethods, TrueSheetProps>((props,
       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<(animated?: boolean) => Promise<void>>(async () => {});
+  const dismissDescendantsRef = useRef<() => void>(() => {});
+
+  const presentSheet = useCallback(async (index: number, auto: boolean) => {
+    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 (phaseRef.current !== 'dismissed') {
+      console.warn(ALREADY_PRESENTED_WARNING);
+      return;
+    }
+    phaseRef.current = 'presenting';
+    isAutoPresentRef.current = auto;
+    isPresentingRef.current = true;
+    setDisplayedBackgroundIndex(index);
+    setActiveSnapPoint(detent);
+    setIsOpen(true);
+    await new Promise<void>((resolve) => {
+      resolvePresentRef.current = resolve;
+    });
+  }, []);
 
   const methods = useMemo<TrueSheetMethods>(
     () => ({
-      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)`
-          );
-        }
-        setActiveSnapPoint(detent);
-        setIsOpen(true);
-      },
+      present: (index = 0) => presentSheet(index, false),
       dismiss: async () => {
-        setIsOpen(false);
+        const dismissal = dismissSheet();
+        if (!dismissal) {
+          console.warn(ALREADY_DISMISSED_WARNING);
+          return;
+        }
+        await dismissal;
       },
       resize: async (index) => {
         const detent = validDetentsRef.current[index];
@@ -235,18 +327,49 @@ const TrueSheetComponent = forwardRef<TrueSheetMethods, TrueSheetProps>((props,
         setActiveSnapPoint(detent);
       },
       dismissStack: async (animated) => {
+        if (phaseRef.current === 'dismissed' || phaseRef.current === 'dismissing') {
+          console.warn(ALREADY_DISMISSED_WARNING);
+          return;
+        }
         await dismissAboveRef.current(animated);
       },
     }),
-    []
+    [presentSheet, dismissSheet]
   );
 
   useImperativeHandle(ref, () => methods, [methods]);
 
-  const methodsRef = useRef<TrueSheetMethods | null>(methods);
-  useRegisterSheet(name, methodsRef);
+  useEffect(() => {
+    if (!shouldAutoPresent || didInitiallyPresentRef.current) return;
+    didInitiallyPresentRef.current = true;
+    if (phaseRef.current === 'dismissed') {
+      presentSheet(initialDetentIndex, true);
+    }
+  }, [initialDetentIndex, shouldAutoPresent, presentSheet]);
+
+  // Unmounted mid-transition: don't leave callers awaiting forever
+  useEffect(
+    () => () => {
+      settle(resolvePresentRef);
+      settle(resolveDismissRef);
+    },
+    []
+  );
+
+  const handleRef = useRef<SheetHandle>({
+    methods,
+    dismissQuietly: async () => {
+      await dismissSheet();
+    },
+  });
+  useRegisterSheet(name, handleRef);
 
   const drawerContentRef = useRef<HTMLDivElement | null>(null);
+  const [drawerContent, setDrawerContent] = useState<HTMLDivElement | null>(null);
+  const handleDrawerRef = useCallback((node: HTMLDivElement | null) => {
+    drawerContentRef.current = node;
+    setDrawerContent(node);
+  }, []);
 
   // Measured header/footer heights drive the 'peek' snap point — mirrors
   // native, where the controller tracks headerHeight/footerHeight.
@@ -272,15 +395,45 @@ const TrueSheetComponent = forwardRef<TrueSheetMethods, TrueSheetProps>((props,
   // within the content — measured by the peek against `contentRef`.
   const [peekContentHeight, setPeekContentHeight] = useState(0);
   const contentRef = useRef<View>(null);
-  const peekElRef = useRef<View>(null);
-  const peekContext = useMemo(() => ({ contentRef, peekRef: peekElRef, setPeekContentHeight }), []);
+  const peekElRef = useRef<View | null>(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<TrueSheetPeekContextValue>(
+    () => ({
+      contentRef,
+      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
@@ -316,120 +469,67 @@ const TrueSheetComponent = forwardRef<TrueSheetMethods, TrueSheetProps>((props,
       (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<HTMLElement | null>(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;
+
+  useLayoutEffect(() => {
+    const layoutEl = sizedLayoutRef.current;
+    if (!isOpen || !drawerContent || !layoutEl?.isConnected) return undefined;
+
+    setHeaderHeight(getDOMElement(headerElRef.current)?.offsetHeight ?? 0);
+    setFooterHeight(getDOMElement(footerElRef.current)?.offsetHeight ?? 0);
+    measurePeek();
+
+    const observer = observeSheetLayout({
+      drawer: drawerContent,
+      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);
+      },
+    });
 
-  useEffect(() => {
-    if (!isOpen || !hasAutoDetent) return undefined;
+    return () => observer.disconnect();
+  }, [
+    isOpen,
+    drawerContent,
+    measurePeek,
+    absoluteHeader,
+    absoluteFooter,
+    footerInsetAdjustment,
+    measureContent,
+    scrollableRef,
+  ]);
 
+  // Re-reveal the focused field once the sheet settles above the keyboard
+  useEffect(() => {
+    const drawer = drawerContentRef.current;
+    if (!keyboardViewport || !drawer) return undefined;
     let canceled = false;
-    let rafId = 0;
-    let mutationObserver: MutationObserver | null = null;
-    let resizeObserver: ResizeObserver | null = null;
-
-    const attach = () => {
-      if (canceled) return;
-      const drawerEl = drawerContentRef.current;
-      if (!drawerEl || !drawerEl.isConnected) {
-        // Radix Presence defers the portal mount; poll until the drawer is live.
-        rafId = window.requestAnimationFrame(attach);
-        return;
-      }
-
-      const measure = () => setScrollableAutoHeight(measureNaturalHeight());
-
-      let observed: {
-        contentEl: HTMLElement | null;
-        headerEl: HTMLElement | null;
-        scroller: HTMLElement;
-        scrollContent: Element | null;
-      } | null = 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;
-        }
-
-        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);
-
+    // Flush styles so this commit's snap transition shows up in getAnimations()
+    // eslint-disable-next-line no-void
+    void drawer.offsetHeight;
+    Promise.allSettled(drawer.getAnimations().map((a) => a.finished)).then(() => {
+      if (!canceled) revealFocusedElement(drawer);
+    });
     return () => {
       canceled = true;
-      window.cancelAnimationFrame(rafId);
-      mutationObserver?.disconnect();
-      resizeObserver?.disconnect();
     };
-  }, [isOpen, hasAutoDetent, measureNaturalHeight]);
+  }, [keyboardViewport]);
 
   // Below the last detent a vertical touch pan moves the sheet, not the
   // content — `[data-vaul-scroll-locked]` disables vertical touch panning on
@@ -437,13 +537,6 @@ const TrueSheetComponent = forwardRef<TrueSheetMethods, TrueSheetProps>((props,
   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<number | undefined>(() => {
     if (maxContentHeight !== undefined) return maxContentHeight;
     if (!isFormSheet) return undefined;
@@ -510,7 +603,7 @@ const TrueSheetComponent = forwardRef<TrueSheetMethods, TrueSheetProps>((props,
     effectiveMaxContentHeight,
     peekHeight,
     peekContentHeight,
-    measuredContentHeight,
+    keyboardViewport,
   });
   geometryInputsRef.current = {
     effectiveDetached,
@@ -518,26 +611,26 @@ const TrueSheetComponent = forwardRef<TrueSheetMethods, TrueSheetProps>((props,
     effectiveMaxContentHeight,
     peekHeight,
     peekContentHeight,
-    measuredContentHeight,
+    keyboardViewport,
   };
 
   const computeDetentGeometry = useCallback(() => {
     const inputs = geometryInputsRef.current;
-    const windowH = window.innerHeight;
-    const effectiveH = inputs.effectiveDetached
-      ? windowH - inputs.effectiveDetachedOffset
-      : windowH;
+    const windowH = inputs.keyboardViewport?.height ?? window.innerHeight;
+    const bottomGap = inputs.effectiveDetached ? inputs.effectiveDetachedOffset : 0;
+    const effectiveH = windowH - bottomGap;
+    // Above a keyboard, fractions keep their full-height size (see vaul).
+    const fractionH = inputs.keyboardViewport
+      ? inputs.keyboardViewport.layoutHeight - bottomGap
+      : effectiveH;
     // 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
@@ -565,7 +658,7 @@ const TrueSheetComponent = forwardRef<TrueSheetMethods, TrueSheetProps>((props,
     for (const d of validDetentsRef.current) {
       const h =
         typeof d === 'number'
-          ? Math.min(d * effectiveH, ceiling)
+          ? Math.min(d * fractionH, ceiling)
           : d === 'peek'
             ? Math.min(livePeekHeight, ceiling)
             : autoHeight;
@@ -573,7 +666,7 @@ const TrueSheetComponent = forwardRef<TrueSheetMethods, TrueSheetProps>((props,
       values.push(effectiveH > 0 ? h / effectiveH : 0);
     }
     return { windowH, effectiveH, ceiling, 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
@@ -652,54 +745,27 @@ const TrueSheetComponent = forwardRef<TrueSheetMethods, TrueSheetProps>((props,
     [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<HTMLDivElement>(null);
   const isDraggingRef = useRef(false);
-  const isSettlingAfterDragRef = useRef(false);
-  const updateSizedLayoutHeight = useCallback(
-    (position: number) => {
-      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: number) => {
-      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, position, detent, realtime: true },
       } as PositionChangeEvent);
     },
-    [interpolateFromPosition, updateSizedLayoutHeight]
+    [interpolateFromPosition, computeDetentGeometry]
   );
 
   // Fire onMount once after first render. React-mount is the earliest point
@@ -726,6 +792,12 @@ const TrueSheetComponent = forwardRef<TrueSheetMethods, TrueSheetProps>((props,
 
     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();
+      // Mirror native's lazy-mount cancel: dismissed before willPresent, no events
+      if (!didEmitWillPresentRef.current) return undefined;
+      didEmitWillPresentRef.current = false;
       // 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).
@@ -735,11 +807,21 @@ const TrueSheetComponent = forwardRef<TrueSheetMethods, TrueSheetProps>((props,
 
     const fireDone = () => {
       if (present) {
+        isPresentingRef.current = false;
+        // A dismiss may already be underway (it lands on the next commit)
+        if (phaseRef.current === 'presenting') phaseRef.current = 'presented';
         onDidPresentRef.current?.({ nativeEvent: computeDetentInfo() } as DidPresentEvent);
         onDidFocusRef.current?.({ nativeEvent: null } as DidFocusEvent);
+        settle(resolvePresentRef);
+        if (shouldDismissOnPresentRef.current) {
+          shouldDismissOnPresentRef.current = false;
+          setIsOpen(false);
+        }
       } else {
+        phaseRef.current = 'dismissed';
         onDidBlurRef.current?.({ nativeEvent: null } as DidBlurEvent);
         onDidDismissRef.current?.({ nativeEvent: null } as DidDismissEvent);
+        settle(resolveDismissRef);
       }
     };
 
@@ -765,6 +847,7 @@ const TrueSheetComponent = forwardRef<TrueSheetMethods, TrueSheetProps>((props,
         // willPresent mirrors native iOS where viewWillAppear dispatches
         // both; the descendant-stack focus effect handles subsequent
         // transitions.
+        didEmitWillPresentRef.current = true;
         onWillPresentRef.current?.({ nativeEvent: computeDetentInfo() } as WillPresentEvent);
         onWillFocusRef.current?.({ nativeEvent: null } as WillFocusEvent);
       }
@@ -824,29 +907,31 @@ const TrueSheetComponent = forwardRef<TrueSheetMethods, TrueSheetProps>((props,
     }
     onDragChangeRef.current?.({ nativeEvent: computeDetentInfo(true) } as DragChangeEvent);
   }, [computeDetentInfo]);
-  const handleRelease = useCallback(
-    (_event: unknown, open: boolean) => {
-      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) } as DragEndEvent);
-    },
-    [computeDetentInfo]
-  );
+  const handleRelease = useCallback(() => {
+    if (!isDraggingRef.current) return;
+    isDraggingRef.current = false;
+    onDragEndRef.current?.({ nativeEvent: computeDetentInfo(true) } as DragEndEvent);
+  }, [computeDetentInfo]);
 
   const { isNested, dismissAbove, descendants } = useSheetStack(
-    methodsRef,
+    handleRef,
     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?.dismissQuietly();
+    }
+  };
 
   // 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;
@@ -858,7 +943,7 @@ const TrueSheetComponent = forwardRef<TrueSheetMethods, TrueSheetProps>((props,
     if (!isOpen) return;
     const parentWrapper = parent.closest<HTMLElement>('[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)';
 
@@ -882,23 +967,32 @@ const TrueSheetComponent = forwardRef<TrueSheetMethods, TrueSheetProps>((props,
     };
 
     if (descendants.length === 0) {
+      if (!wasCascadedRef.current) return;
+      wasCascadedRef.current = false;
       parent.style.transition = transition;
       parent.style.transform = '';
       setClip(CLIP_NONE);
       return;
     }
-
-    // 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.
+    wasCascadedRef.current = true;
+
+    // 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: HTMLElement) => {
+      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
@@ -934,18 +1028,24 @@ const TrueSheetComponent = forwardRef<TrueSheetMethods, TrueSheetProps>((props,
 
     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)`;
@@ -957,12 +1057,15 @@ const TrueSheetComponent = forwardRef<TrueSheetMethods, TrueSheetProps>((props,
     // inline style changes.
     const observer = new MutationObserver(apply);
     observer.observe(parent, { 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
@@ -973,12 +1076,17 @@ const TrueSheetComponent = forwardRef<TrueSheetMethods, TrueSheetProps>((props,
   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 } as DismissAttemptEvent);
+  }, []);
 
   const prevDescendantCountRef = useRef(0);
   useEffect(() => {
@@ -1026,11 +1134,6 @@ const TrueSheetComponent = forwardRef<TrueSheetMethods, TrueSheetProps>((props,
     };
   }, [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
@@ -1048,6 +1151,24 @@ const TrueSheetComponent = forwardRef<TrueSheetMethods, TrueSheetProps>((props,
       ? `drop-shadow(0 ${-elevation}px ${elevation * 3}px rgba(0, 0, 0, 0.15))`
       : undefined;
 
+  const backgroundLayerStyle: React.CSSProperties = {
+    position: 'absolute',
+    inset: 0,
+    pointerEvents: 'none',
+    backgroundColor: backgroundColor as string,
+    transition: isPresentingRef.current ? 'none' : 'background-color 200ms',
+  };
+
+  // Vaul fades the overlay through its opacity, so the dim opacity goes into the color
+  const resolvedOverlayStyle = useMemo<React.CSSProperties>(() => {
+    if (dimColor == null && dimOpacity == null) return overlayStyle;
+    const percentage = Math.min(1, Math.max(0, dimOpacity ?? DEFAULT_DIM_OPACITY)) * 100;
+    return {
+      ...overlayStyle,
+      backgroundColor: `color-mix(in srgb, ${String(dimColor ?? 'black')} ${percentage}%, transparent)`,
+    };
+  }, [dimColor, dimOpacity]);
+
   const mergedContentStyle = useMemo<React.CSSProperties>(
     () => ({
       position: 'fixed',
@@ -1059,7 +1180,6 @@ const TrueSheetComponent = forwardRef<TrueSheetMethods, TrueSheetProps>((props,
       flexDirection: 'column',
       borderTopLeftRadius: effectiveCornerRadius,
       borderTopRightRadius: effectiveCornerRadius,
-      backgroundColor: backgroundColor as string,
       // 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.
@@ -1069,12 +1189,24 @@ const TrueSheetComponent = forwardRef<TrueSheetMethods, TrueSheetProps>((props,
       // 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.
+      // 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)
+        insetAdjustment === 'automatic' &&
+        !(footerOwnsInset && !absoluteFooter) &&
+        (!scrollableRef || insetBehavior === 'automatic' || insetBehavior === 'safe-area')
           ? 'env(safe-area-inset-bottom, 0px)'
           : 0,
     }),
-    [backgroundColor, effectiveCornerRadius, insetAdjustment, footerOwnsInset, absoluteFooter]
+    [
+      effectiveCornerRadius,
+      insetAdjustment,
+      footerOwnsInset,
+      absoluteFooter,
+      scrollableRef,
+      insetBehavior,
+    ]
   );
 
   const defaultGrabberColor =
@@ -1112,7 +1244,7 @@ const TrueSheetComponent = forwardRef<TrueSheetMethods, TrueSheetProps>((props,
   //   `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<React.CSSProperties | undefined>(() => {
     // Mobile portrait ignores width sizing entirely (matches iOS/Android:
@@ -1131,30 +1263,30 @@ const TrueSheetComponent = forwardRef<TrueSheetMethods, TrueSheetProps>((props,
     if (dropShadow) next.filter = dropShadow;
     if (!needsMargins) return next;
 
-    let marginLeft: number | string;
-    let marginRight: number | string;
+    let marginInlineStart: number | string;
+    let marginInlineEnd: number | string;
     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,
+    placement,
+    placementOffset,
     effectiveDetached,
     dropShadow,
   ]);
@@ -1191,6 +1323,8 @@ const TrueSheetComponent = forwardRef<TrueSheetMethods, TrueSheetProps>((props,
         onDrag={handleDrag}
         onRelease={handleRelease}
         dismissible={dismissible}
+        dismissThreshold={dismissThreshold}
+        onDismissAttempt={handleDismissAttempt}
         draggable={draggable}
         repositionInputs={false}
         modal={dimmed}
@@ -1200,24 +1334,18 @@ const TrueSheetComponent = forwardRef<TrueSheetMethods, TrueSheetProps>((props,
         detachedRadius={effectiveCornerRadius}
         maxContentHeight={effectiveMaxContentHeight}
         peekHeight={peekHeight}
-        initialAnimated={initialDetentAnimated}
+        initialAnimated={shouldAutoPresent ? initialDetentAnimated : true}
         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}
+        keyboardViewport={keyboardViewport}
         activeSnapPoint={activeSnapPoint}
         setActiveSnapPoint={handleSetActiveSnapPoint}
         {...snapPointsProps}
       >
         <Drawer.Portal container={portalContainer ?? undefined}>
-          <Drawer.Overlay style={overlayStyle} />
+          <Drawer.Overlay style={resolvedOverlayStyle} />
           <Drawer.Content
-            ref={drawerContentRef}
+            ref={handleDrawerRef}
             style={mergedContentStyle}
             onPointerDownOutside={handlePointerDownOutside}
             detachedSiblings={
@@ -1230,66 +1358,35 @@ const TrueSheetComponent = forwardRef<TrueSheetMethods, TrueSheetProps>((props,
               ) : undefined
             }
           >
+            <div aria-hidden style={backgroundLayerStyle} />
             <Drawer.Title style={visuallyHiddenStyle}>
               {accessibilityOptions?.paneTitle ?? 'Sheet'}
             </Drawer.Title>
             {grabber && <Drawer.Handle style={handleStyle} />}
-            {useSizedLayout ? (
-              // 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.
-              <div
-                ref={sizedLayoutRef}
-                style={sizedLayoutStyle}
-                data-vaul-scroll-locked={isScrollLocked ? '' : undefined}
-              >
-                {header && (
-                  <View ref={headerElRef} style={resolvedHeaderStyle} onLayout={handleHeaderLayout}>
-                    {isValidElement(header) ? header : createElement(header)}
-                  </View>
-                )}
-                {/* Content lays out naturally like native — fill only for auto
-                    detents with a plugged scrollable, where natural layout is
-                    circular (sheet height derives from the scroll content size).
-                    Mirrors the native shadow node's scrollableBounded behavior. */}
+            <div
+              ref={sizedLayoutRef}
+              style={sizedLayoutStyle}
+              data-vaul-scroll-locked={isScrollLocked ? '' : undefined}
+            >
+              <TrueSheetBackground background={background} backgroundStyle={backgroundStyle} />
+              {header && (
+                <View ref={headerElRef} style={resolvedHeaderStyle} onLayout={handleHeaderLayout}>
+                  {isValidElement(header) ? header : createElement(header)}
+                </View>
+              )}
+              <View ref={contentRef} style={[contentStyle, style]} onLayout={handleContentLayout}>
+                {children}
+              </View>
+              {footer && !absoluteFooter && (
                 <View
-                  ref={contentRef}
-                  style={hasAutoDetent && hasBoundedScrollable ? [contentFillStyle, style] : style}
+                  ref={footerElRef}
+                  style={[relativeFooterStyle, resolvedFooterStyle]}
+                  onLayout={handleFooterLayout}
                 >
-                  {children}
+                  {isValidElement(footer) ? footer : createElement(footer)}
                 </View>
-                {footer && !absoluteFooter && (
-                  <View
-                    ref={footerElRef}
-                    style={[relativeFooterStyle, resolvedFooterStyle]}
-                    onLayout={handleFooterLayout}
-                  >
-                    {isValidElement(footer) ? footer : createElement(footer)}
-                  </View>
-                )}
-              </div>
-            ) : (
-              // Natural flow so vaul can measure content height — required for
-              // 'auto' detents and form-sheet content-fit sizing.
-              <>
-                {header && (
-                  <View ref={headerElRef} style={resolvedHeaderStyle} onLayout={handleHeaderLayout}>
-                    {isValidElement(header) ? header : createElement(header)}
-                  </View>
-                )}
-                <View ref={contentRef} style={style}>
-                  {children}
-                </View>
-                {footer && !absoluteFooter && (
-                  <View ref={footerElRef} style={resolvedFooterStyle} onLayout={handleFooterLayout}>
-                    {isValidElement(footer) ? footer : createElement(footer)}
-                  </View>
-                )}
-              </>
-            )}
+              )}
+            </div>
           </Drawer.Content>
         </Drawer.Portal>
       </Drawer.Root>
@@ -1297,6 +1394,8 @@ const TrueSheetComponent = forwardRef<TrueSheetMethods, TrueSheetProps>((props,
   );
 });
 
+const DEFAULT_DIM_OPACITY = 0.5;
+
 const overlayStyle: React.CSSProperties = {
   position: 'fixed',
   inset: 0,
@@ -1327,12 +1426,11 @@ const sizedLayoutStyle: React.CSSProperties = {
   height: SIZED_LAYOUT_HEIGHT,
   display: 'flex',
   flexDirection: 'column',
+  boxSizing: 'border-box',
+  paddingBottom: 'inherit',
 };
 
-const contentFillStyle = {
-  flex: 1,
-  minHeight: 0,
-} as const;
+const contentStyle = { flexShrink: 1, minHeight: 0 } as const;
 
 const visuallyHiddenStyle: React.CSSProperties = {
   position: 'absolute',
@@ -1346,6 +1444,20 @@ const visuallyHiddenStyle: React.CSSProperties = {
   border: 0,
 };
 
+type SheetPhase = 'dismissed' | 'presenting' | 'presented' | 'dismissing';
+
+const settle = (resolveRef: RefObject<(() => void) | null>) => {
+  const resolve = resolveRef.current;
+  resolveRef.current = null;
+  resolve?.();
+};
+
+// Same as native
+const ALREADY_PRESENTED_WARNING =
+  'TrueSheet: sheet is already presented. Use resize() to change detent.';
+const ALREADY_DISMISSED_WARNING =
+  'TrueSheet: sheet is already dismissed. No need to dismiss it again.';
+
 const STATIC_METHOD_ERROR =
   'Static methods are not supported on web. Use the useTrueSheet() hook instead.';