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

package/src/TrueSheet.tsx

@@ -59,16 +59,26 @@ if (!TrueSheetModule) {
 
 type NativeRef = ComponentRef<typeof TrueSheetViewNativeComponent>;
 
-// Claim touches that no descendant claimed so the responder negotiation
-// doesn't bubble up to touchables outside the sheet
-const absorbUnclaimedTouches = () => true;
-
 // Stop raw touch events from bubbling past the sheet to outside ancestors
 const stopTouchPropagation = (event: GestureResponderEvent) => event.stopPropagation();
 
+// Stop the responder negotiation at the sheet boundary without claiming the
+// responder. Views inside the sheet are asked before this one, so in-sheet
+// touchables work normally; views outside are asked after, so stopping here
+// keeps unclaimed touches from leaking to touchables behind the sheet.
+// Claiming instead (returning true) would steal the responder from a pressed
+// touchable whenever the negotiation re-runs mid-gesture — e.g. a second
+// finger, or the duplicate touch stream from a nested react-native-screens
+// screen that attaches its own touch handler inside the sheet.
+const stopResponderNegotiation = (event: GestureResponderEvent) => {
+  event.stopPropagation();
+  return false;
+};
+
 interface TrueSheetState {
   shouldRenderNativeView: boolean;
   initialPresentReady: boolean;
+  scrollableHandle: number | null;
 }
 
 // Gates auto-present (initialDetentIndex) by one commit. Rendered last in the
@@ -120,13 +130,15 @@ export class TrueSheet
 
     this.validateDetents();
 
-    // Lazy load by default, except when initialDetentIndex is set (for auto-presentation)
+    // Lazy load by default, except when auto-presenting or when lazy is disabled
     const shouldRenderImmediately =
-      props.initialDetentIndex !== undefined && props.initialDetentIndex >= 0;
+      (props.initialDetentIndex !== undefined && props.initialDetentIndex >= 0) ||
+      props.lazy === false;
 
     this.state = {
       shouldRenderNativeView: shouldRenderImmediately,
       initialPresentReady: false,
+      scrollableHandle: null,
     };
 
     this.onMount = this.onMount.bind(this);
@@ -152,6 +164,17 @@ export class TrueSheet
     this.setState({ initialPresentReady: true });
   }
 
+  // Resolves after commit (didMount/didUpdate) — the scrollable mounts with the
+  // sheet content, so its ref is only populated once the native tree renders.
+  private updateScrollableHandle(): void {
+    const { scrollableRef } = this.props;
+    const scrollableHandle = scrollableRef?.current ? findNodeHandle(scrollableRef.current) : null;
+
+    if (scrollableHandle !== this.state.scrollableHandle) {
+      this.setState({ scrollableHandle });
+    }
+  }
+
   private validateDetents(): void {
     const { detents, initialDetentIndex } = this.props;
 
@@ -328,9 +351,8 @@ export class TrueSheet
     this.backHandlerSubscription?.remove();
     this.backHandlerSubscription = null;
 
-    // Clean up native view after dismiss for lazy loading.
-    // Skip unmount if a present is in progress to avoid race condition.
-    if (!this.isPresenting) {
+    // Non-lazy content stays mounted; otherwise clean it up unless another presentation is active.
+    if (!this.isPresenting && this.props.lazy !== false) {
       this.setState({ shouldRenderNativeView: false });
     }
 
@@ -455,10 +477,20 @@ export class TrueSheet
 
   componentDidMount(): void {
     this.registerInstance();
+    this.updateScrollableHandle();
   }
 
   componentDidUpdate(prevProps: TrueSheetProps): void {
     this.registerInstance();
+    this.updateScrollableHandle();
+
+    if (
+      prevProps.lazy !== false &&
+      this.props.lazy === false &&
+      !this.state.shouldRenderNativeView
+    ) {
+      this.setState({ shouldRenderNativeView: true });
+    }
 
     // Validate when detents prop changes
     if (prevProps.detents !== this.props.detents) {
@@ -519,6 +551,7 @@ export class TrueSheet
       insetAdjustment = 'automatic',
       ...rest
     } = this.props;
+    delete rest.lazy;
 
     // Trim to max 3 detents and clamp fractions
     const resolvedDetents: number[] = detents.slice(0, 3).map((detent) => {
@@ -570,6 +603,7 @@ export class TrueSheet
         maxContentWidth={maxContentWidth}
         anchor={anchor}
         anchorOffset={anchorOffset}
+        scrollableHandle={this.state.scrollableHandle ?? -1}
         scrollableOptions={scrollableOptions}
         headerOptions={headerOptions}
         footerOptions={{
@@ -595,10 +629,11 @@ export class TrueSheet
         onVisibilityChange={this.onVisibilityChange}
         // These must stay on this host view, not on the container. The container is
         // reparented into the native sheet, so this view is never a native ancestor of
-        // the sheet content. Claiming the responder here stops the negotiation at the
-        // sheet boundary without making an ancestor of the content the JS responder,
-        // which would block scrolling inside the sheet.
-        onStartShouldSetResponder={absorbUnclaimedTouches}
+        // the sheet content — this is the React-tree boundary between the sheet and
+        // the presenting screen, where both the responder negotiation and raw touch
+        // bubbling must stop.
+        onStartShouldSetResponder={stopResponderNegotiation}
+        onMoveShouldSetResponder={stopResponderNegotiation}
         onTouchStart={stopTouchPropagation}
         onTouchMove={stopTouchPropagation}
         onTouchEnd={stopTouchPropagation}

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,
@@ -165,6 +165,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 +194,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 +431,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`.
@@ -568,8 +617,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;
 

package/src/TrueSheet.web.tsx

@@ -55,15 +55,15 @@ 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;
+// 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) => {
@@ -79,6 +79,8 @@ const TrueSheetComponent = forwardRef<TrueSheetMethods, TrueSheetProps>((props,
     maxContentWidth,
     anchor = 'center',
     anchorOffset = DEFAULT_ANCHOR_OFFSET,
+    scrollableRef,
+    scrollableOptions,
     grabber = true,
     grabberOptions,
     accessibilityOptions,
@@ -323,9 +325,9 @@ 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(() => {
@@ -335,7 +337,7 @@ const TrueSheetComponent = forwardRef<TrueSheetMethods, TrueSheetProps>((props,
     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;
@@ -369,7 +371,7 @@ 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
@@ -379,10 +381,8 @@ const TrueSheetComponent = forwardRef<TrueSheetMethods, TrueSheetProps>((props,
         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 &&
@@ -394,9 +394,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 }
@@ -429,7 +430,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
@@ -1069,12 +1070,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 =
@@ -1254,7 +1268,8 @@ 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}

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/TrueSheetViewNativeComponent.ts

@@ -35,7 +35,9 @@ type BlurOptionsType = Readonly<{
 type ScrollEdgeEffect = 'automatic' | 'hard' | 'soft' | 'hidden';
 
 type ScrollableOptionsType = Readonly<{
+  contentInsetAdjustmentBehavior?: WithDefault<boolean, true>;
   keyboardScrollOffset?: WithDefault<Double, 0>;
+  keyboardOffset?: WithDefault<Double, 0>;
   scrollingExpandsSheet?: WithDefault<boolean, true>;
   topScrollEdgeEffect?: WithDefault<ScrollEdgeEffect, 'hidden'>;
   bottomScrollEdgeEffect?: WithDefault<ScrollEdgeEffect, 'hidden'>;
@@ -122,6 +124,8 @@ export interface NativeProps extends ViewProps {
   draggable?: WithDefault<boolean, true>;
   dimmed?: WithDefault<boolean, true>;
   initialDetentAnimated?: WithDefault<boolean, true>;
+  // React tag of the scrollable component within the content (see scrollableRef)
+  scrollableHandle?: WithDefault<Int32, -1>;
   scrollableOptions?: ScrollableOptionsType;
   headerOptions?: HeaderOptionsType;
   footerOptions?: FooterOptionsType;

package/src/navigation/types.ts

@@ -176,6 +176,7 @@ export type TrueSheetNavigationSheetProps = Pick<
   | 'footer'
   | 'footerStyle'
   | 'footerOptions'
+  | 'scrollableRef'
   | 'scrollableOptions'
   | 'insetAdjustment'
   | 'anchor'