@lodev09/react-native-true-sheet 4.0.0-beta.1 → 4.0.0-beta.11

package/src/TrueSheet.types.ts

@@ -1,4 +1,4 @@
-import type { ComponentType, ReactElement } from 'react';
+import type { Component, ComponentType, ReactElement, RefObject } from 'react';
 import type {
   ColorValue,
   NativeSyntheticEvent,
@@ -36,6 +36,7 @@ export type WillPresentEvent = NativeSyntheticEvent<DetentInfoEventPayload>;
 export type DidPresentEvent = NativeSyntheticEvent<DetentInfoEventPayload>;
 export type WillDismissEvent = NativeSyntheticEvent<null>;
 export type DidDismissEvent = NativeSyntheticEvent<null>;
+export type DismissAttemptEvent = NativeSyntheticEvent<null>;
 export type DragBeginEvent = NativeSyntheticEvent<DetentInfoEventPayload>;
 export type DragChangeEvent = NativeSyntheticEvent<DetentInfoEventPayload>;
 export type DragEndEvent = NativeSyntheticEvent<DetentInfoEventPayload>;
@@ -165,6 +166,28 @@ export type ScrollEdgeEffect = 'automatic' | 'hard' | 'soft' | 'hidden';
  * Options for scrollable behavior.
  */
 export interface ScrollableOptions {
+  /**
+   * Applies the bottom safe-area inset to the scroll content automatically
+   * while the content can scroll, so the last item clears the home indicator
+   * (iOS) and navigation bar (Android).
+   *
+   * - **iOS**: Sets the scroll view's native
+   * [`contentInsetAdjustmentBehavior`](https://developer.apple.com/documentation/uikit/uiscrollview/contentinsetadjustmentbehavior)
+   * to `automatic` while it's plugged into the sheet — no need to set React
+   * Native's iOS-only prop yourself.
+   * - **Android**: Pads the scroll content with the bottom window inset,
+   * mirroring iOS's `automatic` behavior — parity React Native's iOS-only
+   * prop can't provide.
+   * - **Web**: Lifts the content above the safe area
+   * (`env(safe-area-inset-bottom)`).
+   *
+   * Only applies while the sheet's `insetAdjustment` is `'automatic'`. When
+   * the sheet has a relative footer, the footer absorbs the inset instead.
+   *
+   * @default true
+   */
+  contentInsetAdjustmentBehavior?: boolean;
+
   /**
    * Extra offset when scrolling to the focused input when keyboard appears.
    *
@@ -172,6 +195,18 @@ export interface ScrollableOptions {
    */
   keyboardScrollOffset?: number;
 
+  /**
+   * Adjusts the bottom inset applied to the scrollable when the keyboard is shown.
+   * Positive values increase the inset; negative values reduce it.
+   * Pass `-insets.bottom` to cancel out safe-area padding already included in
+   * the content's `paddingBottom`.
+   * Does not affect the auto scroll of the focused input — it always targets
+   * the keyboard edge.
+   *
+   * @default 0
+   */
+  keyboardOffset?: number;
+
   /**
    * Whether scrolling the content expands the sheet to the next detent.
    * When `false`, only the grabber can expand the sheet.
@@ -397,6 +432,21 @@ export interface TrueSheetProps extends ViewProps {
    */
   initialDetentAnimated?: boolean;
 
+  /**
+   * Specify whether the sheet content should mount lazily, on first presentation.
+   * Set to `false` to mount the content before presentation without presenting the sheet.
+   * Use this when content is not ready on the first render, then call `present()`
+   * after your readiness signal so auto detents measure the settled content.
+   *
+   * Content that requires window attachment to measure, such as SwiftUI-hosted views,
+   * still only measures during presentation.
+   *
+   * @platform android
+   * @platform ios
+   * @default true
+   */
+  lazy?: boolean;
+
   /**
    * The detent index that the sheet should start to dim the background.
    * This is ignored if `dimmed` is set to `false`.
@@ -407,6 +457,7 @@ export interface TrueSheetProps extends ViewProps {
 
   /**
    * Prevents interactive dismissal of the Sheet.
+   * Blocked attempts fire `onDismissAttempt`, so you can confirm before dismissing programmatically.
    *
    * @default true
    */
@@ -568,8 +619,26 @@ export interface TrueSheetProps extends ViewProps {
    */
   footerStyle?: StyleProp<ViewStyle>;
 
+  /**
+   * A ref to the scrollable component (e.g. `ScrollView`, `FlatList`)
+   * rendered within the sheet content.
+   * Required for scrollable handling — nested scrolling, keyboard insets,
+   * and `auto` detent sizing are wired to this scrollable.
+   *
+   * Example:
+   * ```tsx
+   * const scrollableRef = useRef<ScrollView>(null)
+   *
+   * <TrueSheet scrollableRef={scrollableRef}>
+   *   <ScrollView ref={scrollableRef} />
+   * </TrueSheet>
+   * ```
+   */
+  scrollableRef?: RefObject<Component<unknown> | null>;
+
   /**
    * Options for scrollable behavior.
+   * Applies to the scrollable provided via `scrollableRef`.
    */
   scrollableOptions?: ScrollableOptions;
 
@@ -621,6 +690,13 @@ export interface TrueSheetProps extends ViewProps {
    */
   onDidDismiss?: (event: DidDismissEvent) => void;
 
+  /**
+   * Called when the user tries to dismiss the sheet while `dismissible` is `false`,
+   * e.g. by dragging down or pressing back/escape. Tapping the dim does not count.
+   * The sheet stays presented. Confirm with the user, then call `dismiss()` to proceed.
+   */
+  onDismissAttempt?: (event: DismissAttemptEvent) => void;
+
   /**
    * Called when the detent of the sheet has changed.
    * Either by dragging or programatically.

package/src/TrueSheet.web.tsx

@@ -10,7 +10,7 @@ import {
   useRef,
   useState,
 } from 'react';
-import type { LayoutChangeEvent, ViewStyle } from 'react-native';
+import type { DimensionValue, LayoutChangeEvent } from 'react-native';
 import { StyleSheet, useColorScheme, useWindowDimensions, View } from 'react-native';
 
 import type {
@@ -31,6 +31,7 @@ import type {
   TrueSheetStaticMethods,
   WillBlurEvent,
   WillDismissEvent,
+  DismissAttemptEvent,
   WillFocusEvent,
   WillPresentEvent,
 } from './TrueSheet.types';
@@ -51,18 +52,19 @@ import {
   DEFAULT_GRABBER_WIDTH,
   DEFAULT_MAX_WIDTH,
 } from './web/constants';
+import { getDOMElement } from './web/dom';
 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 — 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.
+const getScrollableElement = (scrollable: unknown): HTMLElement | null => {
+  if (!scrollable) return null;
+  if (scrollable instanceof HTMLElement) return scrollable;
+  const node = (scrollable as { getScrollableNode?: () => unknown }).getScrollableNode?.();
+  return node instanceof HTMLElement ? node : null;
 };
 
 const TrueSheetComponent = forwardRef<TrueSheetMethods, TrueSheetProps>((props, ref) => {
@@ -78,6 +80,8 @@ const TrueSheetComponent = forwardRef<TrueSheetMethods, TrueSheetProps>((props,
     maxContentWidth,
     anchor = 'center',
     anchorOffset = DEFAULT_ANCHOR_OFFSET,
+    scrollableRef,
+    scrollableOptions,
     grabber = true,
     grabberOptions,
     accessibilityOptions,
@@ -102,6 +106,7 @@ const TrueSheetComponent = forwardRef<TrueSheetMethods, TrueSheetProps>((props,
     onDidPresent,
     onWillDismiss,
     onDidDismiss,
+    onDismissAttempt,
     onDetentChange,
     onDragBegin,
     onDragChange,
@@ -195,19 +200,34 @@ 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 methods = useMemo<TrueSheetMethods>(
     () => ({
@@ -274,6 +294,17 @@ const TrueSheetComponent = forwardRef<TrueSheetMethods, TrueSheetProps>((props,
   const peekElRef = useRef<View>(null);
   const peekContext = useMemo(() => ({ contentRef, peekRef: peekElRef, setPeekContentHeight }), []);
 
+  // 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 = useCallback(() => {
+    const peekEl = getDOMElement(peekElRef.current);
+    const contentEl = getDOMElement(contentRef.current);
+    if (peekEl && contentEl) {
+      setPeekContentHeight(measurePeekContentHeight(peekEl, contentEl));
+    }
+  }, []);
+
   // An absolute (floating) header overlaps the content, so it contributes no
   // height to the 'auto' detent measurement.
   const absoluteHeader = headerOptions?.position === 'absolute';
@@ -302,8 +333,9 @@ const TrueSheetComponent = forwardRef<TrueSheetMethods, TrueSheetProps>((props,
     return [
       footerStyle,
       {
-        paddingBottom: `calc(${baseCss} + env(safe-area-inset-bottom, 0px))`,
-      } as unknown as ViewStyle,
+        // RN types don't model CSS calc(), but RN-web passes it through
+        paddingBottom: `calc(${baseCss} + env(safe-area-inset-bottom, 0px))` as DimensionValue,
+      },
     ];
   }, [footerOwnsInset, footerStyle]);
 
@@ -321,23 +353,19 @@ const TrueSheetComponent = forwardRef<TrueSheetMethods, TrueSheetProps>((props,
   // `naturalHeight`.
   const [hasBoundedScrollable, setHasBoundedScrollable] = useState(false);
   const [scrollableAutoHeight, setScrollableAutoHeight] = useState(0);
-  const pinnedScrollerRef = useRef<HTMLElement | null>(null);
+  const detectedScrollerRef = useRef<HTMLElement | null>(null);
 
-  // Natural content height (header + content + footer, with a pinned
+  // Natural content height (header + content + footer, with a detected
   // scrollable's viewport replaced by its content size) — the height the
   // content wants regardless of the sheet's bounds.
   const measureNaturalHeight = useCallback(() => {
-    const contentEl = contentRef.current as unknown as HTMLElement | null;
+    const contentEl = getDOMElement(contentRef.current);
     if (!contentEl || !contentEl.isConnected) return 0;
-    const headerEl = absoluteHeaderRef.current
-      ? null
-      : (headerElRef.current as unknown as HTMLElement | null);
-    const footerEl = absoluteFooterRef.current
-      ? null
-      : (footerElRef.current as unknown as HTMLElement | null);
+    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 scroller = detectedScrollerRef.current;
     const scrollContent = scroller?.firstElementChild;
     if (scroller?.isConnected && scrollContent instanceof HTMLElement) {
       height += scrollContent.offsetHeight - scroller.clientHeight;
@@ -371,20 +399,18 @@ const TrueSheetComponent = forwardRef<TrueSheetMethods, TrueSheetProps>((props,
         scrollContent: Element | null;
       } | null = null;
 
-      // (Re)pin the first vertical scrollable and observe the nodes whose size
+      // (Re)resolve the plugged 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 = contentRef.current as unknown as HTMLElement | null;
-        const headerEl = headerElRef.current as unknown as HTMLElement | null;
+        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.
+        // virtualized list mounting rows inside the plugged scroller. Size
+        // changes are already covered by the ResizeObserver.
         if (
           observed &&
           observed.contentEl === contentEl &&
@@ -396,9 +422,10 @@ const TrueSheetComponent = forwardRef<TrueSheetMethods, TrueSheetProps>((props,
           return;
         }
 
-        const scroller =
-          contentEl && contentEl.isConnected ? findVerticalScroller(contentEl) : null;
-        pinnedScrollerRef.current = scroller;
+        const resolved =
+          contentEl && contentEl.isConnected ? getScrollableElement(scrollableRef?.current) : null;
+        const scroller = resolved?.isConnected ? resolved : null;
+        detectedScrollerRef.current = scroller;
         setHasBoundedScrollable(scroller != null);
         observed = scroller
           ? { contentEl, headerEl, scroller, scrollContent: scroller.firstElementChild }
@@ -431,7 +458,7 @@ const TrueSheetComponent = forwardRef<TrueSheetMethods, TrueSheetProps>((props,
       mutationObserver?.disconnect();
       resizeObserver?.disconnect();
     };
-  }, [isOpen, hasAutoDetent, measureNaturalHeight]);
+  }, [isOpen, hasAutoDetent, measureNaturalHeight, scrollableRef]);
 
   // Below the last detent a vertical touch pan moves the sheet, not the
   // content — `[data-vaul-scroll-locked]` disables vertical touch panning on
@@ -549,13 +576,11 @@ const TrueSheetComponent = forwardRef<TrueSheetMethods, TrueSheetProps>((props,
     // measure either: they fire while the portal subtree is still detached.
     // Geometry only runs while the drawer is mounted, so the elements are
     // measurable here; fall back to the state value when they're absent.
-    const headerEl = headerElRef.current as unknown as HTMLElement | null;
+    const headerEl = getDOMElement(headerElRef.current);
     // A relative footer is pushed off-screen at the peek detent — excluded
-    const footerEl = absoluteFooterRef.current
-      ? (footerElRef.current as unknown as HTMLElement | null)
-      : null;
-    const peekEl = peekElRef.current as unknown as HTMLElement | null;
-    const contentEl = contentRef.current as unknown as HTMLElement | null;
+    const footerEl = absoluteFooterRef.current ? getDOMElement(footerElRef.current) : null;
+    const peekEl = getDOMElement(peekElRef.current);
+    const contentEl = getDOMElement(contentRef.current);
     const livePeekContentHeight =
       peekEl && contentEl ? measurePeekContentHeight(peekEl, contentEl) : inputs.peekContentHeight;
     const livePeekHeight =
@@ -730,6 +755,9 @@ 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();
       // 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).
@@ -847,6 +875,13 @@ const TrueSheetComponent = forwardRef<TrueSheetMethods, TrueSheetProps>((props,
     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
@@ -892,17 +927,23 @@ const TrueSheetComponent = forwardRef<TrueSheetMethods, TrueSheetProps>((props,
       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.
+    // 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
@@ -938,18 +979,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)`;
@@ -961,12 +1008,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
@@ -977,12 +1027,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(() => {
@@ -1073,12 +1128,25 @@ 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 (contentInsetAdjustmentBehavior,
+      // default on) — disable it to scroll edge-to-edge behind the indicator
+      // with user-applied content padding.
       paddingBottom:
-        insetAdjustment === 'automatic' && !(footerOwnsInset && !absoluteFooter)
+        insetAdjustment === 'automatic' &&
+        !(footerOwnsInset && !absoluteFooter) &&
+        (!scrollableRef || (scrollableOptions?.contentInsetAdjustmentBehavior ?? true))
           ? 'env(safe-area-inset-bottom, 0px)'
           : 0,
     }),
-    [backgroundColor, effectiveCornerRadius, insetAdjustment, footerOwnsInset, absoluteFooter]
+    [
+      backgroundColor,
+      effectiveCornerRadius,
+      insetAdjustment,
+      footerOwnsInset,
+      absoluteFooter,
+      scrollableRef,
+      scrollableOptions,
+    ]
   );
 
   const defaultGrabberColor =
@@ -1195,6 +1263,7 @@ const TrueSheetComponent = forwardRef<TrueSheetMethods, TrueSheetProps>((props,
         onDrag={handleDrag}
         onRelease={handleRelease}
         dismissible={dismissible}
+        onDismissAttempt={handleDismissAttempt}
         draggable={draggable}
         repositionInputs={false}
         modal={dimmed}
@@ -1258,10 +1327,12 @@ const TrueSheetComponent = forwardRef<TrueSheetMethods, TrueSheetProps>((props,
                 {/* 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. */}
+                    Unlike native, CSS won't cap the content to the container
+                    (no fit-content flex basis), so the fill is still needed here. */}
                 <View
                   ref={contentRef}
                   style={hasAutoDetent && hasBoundedScrollable ? [contentFillStyle, style] : style}
+                  onLayout={handleContentLayout}
                 >
                   {children}
                 </View>
@@ -1284,7 +1355,7 @@ const TrueSheetComponent = forwardRef<TrueSheetMethods, TrueSheetProps>((props,
                     {isValidElement(header) ? header : createElement(header)}
                   </View>
                 )}
-                <View ref={contentRef} style={style}>
+                <View ref={contentRef} style={style} onLayout={handleContentLayout}>
                   {children}
                 </View>
                 {footer && !absoluteFooter && (

package/src/TrueSheetOverlay.tsx

@@ -0,0 +1,24 @@
+import { StyleSheet, type ViewProps } from 'react-native';
+
+import TrueSheetOverlayViewNativeComponent from './fabric/TrueSheetOverlayViewNativeComponent';
+
+/**
+ * Renders its children in a native layer above every presented sheet — for
+ * toasts, dialogs, and other content a sheet must not cover.
+ * Fills the window; touches that miss its children pass through to the views beneath.
+ */
+export const TrueSheetOverlay = ({ style, ...rest }: ViewProps) => (
+  <TrueSheetOverlayViewNativeComponent {...rest} style={[styles.overlay, style]} />
+);
+
+const styles = StyleSheet.create({
+  // Sized to the window from native — absolute so it takes no layout space.
+  // Children render in a native container, so the host itself must never
+  // catch touches (Android forces it visible on layout).
+  overlay: {
+    position: 'absolute',
+    top: 0,
+    left: 0,
+    pointerEvents: 'none',
+  },
+});

package/src/TrueSheetOverlay.web.tsx

@@ -0,0 +1,33 @@
+/// <reference lib="dom" />
+import { useLayoutEffect, useState } from 'react';
+import { createPortal } from 'react-dom';
+import { StyleSheet, View, type ViewProps } from 'react-native';
+
+/**
+ * Renders its children in a layer above every presented sheet — for
+ * toasts, dialogs, and other content a sheet must not cover.
+ * Fills the window; touches that miss its children pass through to the views beneath.
+ */
+export const TrueSheetOverlay = ({ style, ...rest }: ViewProps) => {
+  // Portal target appended to the body so it stacks above the sheets' portal
+  const [container] = useState(() =>
+    typeof document !== 'undefined' ? document.createElement('div') : null
+  );
+
+  useLayoutEffect(() => {
+    if (!container) return;
+
+    container.style.cssText = 'position:fixed;inset:0;pointer-events:none';
+    document.body.appendChild(container);
+    return () => {
+      container.remove();
+    };
+  }, [container]);
+
+  if (!container) return null;
+
+  return createPortal(
+    <View pointerEvents="box-none" {...rest} style={[StyleSheet.absoluteFill, style]} />,
+    container
+  );
+};

package/src/TrueSheetPeek.web.tsx

@@ -1,6 +1,8 @@
 import { createContext, type RefObject, useContext, useEffect, useRef } from 'react';
 import { type LayoutChangeEvent, View, type ViewProps } from 'react-native';
 
+import { getDOMElement } from './web/dom';
+
 /**
  * Reports the measured peek content height to the owning TrueSheet.
  * @internal
@@ -44,9 +46,8 @@ export const TrueSheetPeek = ({ onLayout, ...rest }: ViewProps) => {
 
   const handleLayout = (event: LayoutChangeEvent) => {
     if (context) {
-      // On web, View refs resolve to the underlying DOM elements.
-      const peekElement = viewRef.current as unknown as HTMLElement | null;
-      const contentElement = context.contentRef.current as unknown as HTMLElement | null;
+      const peekElement = getDOMElement(viewRef.current);
+      const contentElement = getDOMElement(context.contentRef.current);
 
       const bottom =
         peekElement && contentElement

package/src/fabric/TrueSheetContentViewNativeComponent.ts

@@ -6,7 +6,7 @@ export interface NativeProps extends ViewProps {
 }
 
 // interfaceOnly: shadow node/state/descriptor are custom (common/cpp) so the
-// content can be bounded to the container when a ScrollView is pinned
+// content can be bounded to the container when a ScrollView is detected
 export default codegenNativeComponent<NativeProps>('TrueSheetContentView', {
   interfaceOnly: true,
 });

package/src/fabric/TrueSheetOverlayViewNativeComponent.ts

@@ -0,0 +1,12 @@
+import type { ViewProps } from 'react-native';
+import { codegenNativeComponent } from 'react-native';
+
+export interface NativeProps extends ViewProps {
+  // No props needed - sized to the window from native
+}
+
+// interfaceOnly: shadow node/state/descriptor are custom (common/cpp) so the
+// overlay is sized to the window
+export default codegenNativeComponent<NativeProps>('TrueSheetOverlayView', {
+  interfaceOnly: true,
+});