refactor: remove auto bottom inset on scrollables (#784)

* refactor: remove auto bottom inset on scrollables

Scrollables no longer get the bottom safe-area inset applied natively.
Only keyboard handling stays automatic — apply the inset in JS instead.

Also drops manual scroll indicator insets on iOS; UIKit derives them
from the content inset.

* refactor: rename pinned scroll view to detected

v3 literally pinned the scroll view's frame to the container. v4 lets
Yoga own every frame — we only detect it and wire keyboard handling.

* docs: add changelog entry for #784

* fix(web): don't lift detected scrollables above the bottom safe area

Mirrors native — scroll content runs edge-to-edge behind the home
indicator and user-applied content padding owns the inset. Avoids
double padding when following the v4 migration advice.

* fix(ios): drop keyboard content inset — the sheet already avoids the keyboard

UIKit keeps the sheet above the keyboard and v4 rebounds the container
to the sheet's visible size, so the viewport is never behind it. The
v3-era keyboardHeight inset double-compensated, leaving a huge gap at
the bottom of scroll content while typing. Caret auto-scroll now
extends its target past an absolute footer instead.

* fix(ios): apply keyboard inset only when content overflows the viewport

Restores the keyboard-height content inset — content that already fits
above the keyboard has nothing to reveal, so the inset only opened
blank scroll range below it (huge gap at the bottom). Re-synced while
typing since a growing multiline input can cross the threshold.

* fix: keyboard inset stops at the keyboard edge for absolute footers

The inset also lifted content above a floating footer, doubling the
clearance the user's content padding already provides. Footer clearance
now belongs to the padding alone; the caret reveal extends its target
past the footer instead.

* chore(example): fix PromptSheet FOOTER_HEIGHT

Author: lodev09

CHANGELOG.md

@@ -19,6 +19,7 @@
 - The footer now lays out relative by default — it takes up space below the content, is included in the `auto` detent height (excluded from `peek`), and stays behind the keyboard. Set `footerOptions.position` to `'absolute'` to restore the previous floating behavior (`keyboardOffset` only applies there). ([#748](https://github.com/lodev09/react-native-true-sheet/pull/748), [#754](https://github.com/lodev09/react-native-true-sheet/pull/754) by [@lodev09](https://github.com/lodev09))
 - Content now wraps its children's height by default instead of filling the sheet — like a regular view. Pass `flex: 1` via `style` to fill. ([#746](https://github.com/lodev09/react-native-true-sheet/pull/746) by [@lodev09](https://github.com/lodev09))
 - The container is now sized to the sheet's visible height per detent and tracks it in realtime while dragging, on all platforms. The `scrollable` prop is removed — scrollables are auto-detected. Requires React Native 0.82+. ([#735](https://github.com/lodev09/react-native-true-sheet/pull/735) by [@lodev09](https://github.com/lodev09))
+- Scrollables no longer get the bottom safe-area inset applied natively — only keyboard handling stays automatic. Pad the scroll content yourself via `contentContainerStyle` (or `contentInsetAdjustmentBehavior` on iOS). ([#784](https://github.com/lodev09/react-native-true-sheet/pull/784) by [@lodev09](https://github.com/lodev09))
 - The sheet navigator is now built on `standard-navigation` with first-class Expo Router support — import the ready-made `Sheet` layout from the new `/navigation/expo-router` entry point instead of wrapping with `withLayoutContext`. Requires the new `standard-navigation` peer dependency; React Navigation apps also need `@react-navigation/native` 7.3+ (same API otherwise, plus a new `createTrueSheetScreen` for the static API). ([#772](https://github.com/lodev09/react-native-true-sheet/pull/772) by [@lodev09](https://github.com/lodev09))
 
 ### 💡 Others

android/src/main/java/com/lodev09/truesheet/TrueSheetContainerView.kt

@@ -61,8 +61,6 @@ class TrueSheetContainerView(reactContext: ThemedReactContext) :
       return bottom
     }
 
-  var insetAdjustment: TrueSheetInsetAdjustment = TrueSheetInsetAdjustment.AUTOMATIC
-  var scrollViewBottomInset: Int = 0
   var absoluteFooter: Boolean = false
 
   /**
@@ -96,8 +94,7 @@ class TrueSheetContainerView(reactContext: ThemedReactContext) :
   }
 
   fun setupScrollable() {
-    val bottomInset = if (insetAdjustment == TrueSheetInsetAdjustment.AUTOMATIC) scrollViewBottomInset else 0
-    contentView?.setupScrollable(bottomInset)
+    contentView?.setupScrollable()
   }
 
   fun setupKeyboardHandler() {

android/src/main/java/com/lodev09/truesheet/TrueSheetContentView.kt

@@ -32,8 +32,9 @@ interface TrueSheetContentViewDelegate {
 
   /**
    * Keyboard occlusion adjustment below the content — positive for an absolute
-   * footer risen above the keyboard covering the content's bottom edge,
-   * negative for a relative footer sitting behind the keyboard shielding it.
+   * footer floating over the viewport's bottom edge (extends the caret reveal),
+   * negative for a relative footer sitting behind the keyboard shielding that
+   * much of its overlap (reduces the keyboard padding).
    */
   val footerKeyboardOcclusion: Int
 }
@@ -47,9 +48,8 @@ class TrueSheetContentView(private val reactContext: ThemedReactContext) : React
   var delegate: TrueSheetContentViewDelegate? = null
   var stateWrapper: StateWrapper? = null
 
-  private var pinnedScrollView: ViewGroup? = null
+  private var detectedScrollView: ViewGroup? = null
   private var originalScrollViewPaddingBottom: Int = 0
-  private var bottomInset: Int = 0
   private var scrollableBounded = false
 
   /**
@@ -84,14 +84,14 @@ class TrueSheetContentView(private val reactContext: ThemedReactContext) : React
 
   /**
    * Whether the sheet has an `auto` detent. Deriving the sheet height from the
-   * scroll content is circular with natural layout, so the pinned ScrollView's
+   * scroll content is circular with natural layout, so the detected ScrollView's
    * viewport is force-bounded to the container only in this case.
    */
   var hasAutoDetent = false
     set(value) {
       if (field == value) return
       field = value
-      if (pinnedScrollView != null) {
+      if (detectedScrollView != null) {
         setScrollableBounded(value)
       }
     }
@@ -107,14 +107,14 @@ class TrueSheetContentView(private val reactContext: ThemedReactContext) : React
   }
 
   private fun checkScrollViewChanged() {
-    if (pinnedScrollView == null || pinnedScrollView?.isDescendantOf(this) == false) {
+    if (detectedScrollView == null || detectedScrollView?.isDescendantOf(this) == false) {
       delegate?.contentViewScrollViewDidChange()
     }
   }
 
   /**
    * Tells the shadow node to fill the container (flexGrow/flexShrink) so the
-   * pinned ScrollView's viewport is bounded to the visible space. Only applied
+   * detected ScrollView's viewport is bounded to the visible space. Only applied
    * for auto detents — otherwise content lays out naturally like a regular view.
    */
   private fun setScrollableBounded(bounded: Boolean) {
@@ -128,39 +128,31 @@ class TrueSheetContentView(private val reactContext: ThemedReactContext) : React
     }
   }
 
-  fun setupScrollable(bottomInset: Int) {
-    // Check if pinned scroll view is still valid (still in view hierarchy)
-    if (pinnedScrollView != null && pinnedScrollView?.isDescendantOf(this) == false) {
+  fun setupScrollable() {
+    // Check if the detected scroll view is still valid (still in view hierarchy)
+    if (detectedScrollView != null && detectedScrollView?.isDescendantOf(this) == false) {
       clearScrollable()
     }
 
-    // Already set up with same inset and valid scroll view
-    if (pinnedScrollView != null && this.bottomInset == bottomInset) {
+    if (detectedScrollView != null) {
       return
     }
 
     val scrollView = findScrollView(this) ?: return
 
-    // Only capture originals on first pin
-    if (pinnedScrollView == null) {
-      originalScrollViewPaddingBottom = scrollView.paddingBottom
-      pinnedScrollView = scrollView
+    originalScrollViewPaddingBottom = scrollView.paddingBottom
+    detectedScrollView = scrollView
 
-      scrollView.isNestedScrollingEnabled = true
-      (scrollView.parent as? SwipeRefreshLayout)?.isNestedScrollingEnabled = false
+    scrollView.isNestedScrollingEnabled = true
+    (scrollView.parent as? SwipeRefreshLayout)?.isNestedScrollingEnabled = false
 
-      scrollView.setOnScrollChangeListener { _, _, scrollY, _, oldScrollY ->
-        if (scrollY != oldScrollY) {
-          delegate?.contentViewDidScroll()
-        }
+    scrollView.setOnScrollChangeListener { _, _, scrollY, _, oldScrollY ->
+      if (scrollY != oldScrollY) {
+        delegate?.contentViewDidScroll()
       }
-
-      setScrollableBounded(hasAutoDetent)
     }
 
-    this.bottomInset = bottomInset
-
-    setScrollViewPaddingBottom(originalScrollViewPaddingBottom + bottomInset)
+    setScrollableBounded(hasAutoDetent)
 
     // If keyboard is currently showing, re-apply the keyboard inset to the new ScrollView
     val keyboardHeight = keyboardObserver?.currentHeight ?: 0
@@ -170,7 +162,7 @@ class TrueSheetContentView(private val reactContext: ThemedReactContext) : React
   }
 
   private fun setScrollViewPaddingBottom(paddingBottom: Int) {
-    val scrollView = pinnedScrollView ?: return
+    val scrollView = detectedScrollView ?: return
     scrollView.clipToPadding = false
     scrollView.setPadding(
       scrollView.paddingLeft,
@@ -181,18 +173,17 @@ class TrueSheetContentView(private val reactContext: ThemedReactContext) : React
   }
 
   fun clearScrollable() {
-    pinnedScrollView?.setOnScrollChangeListener(null as View.OnScrollChangeListener?)
-    pinnedScrollView?.isNestedScrollingEnabled = false
-    (pinnedScrollView?.parent as? SwipeRefreshLayout)?.isNestedScrollingEnabled = true
+    detectedScrollView?.setOnScrollChangeListener(null as View.OnScrollChangeListener?)
+    detectedScrollView?.isNestedScrollingEnabled = false
+    (detectedScrollView?.parent as? SwipeRefreshLayout)?.isNestedScrollingEnabled = true
     setScrollViewPaddingBottom(originalScrollViewPaddingBottom)
     setScrollableBounded(false)
-    pinnedScrollView = null
+    detectedScrollView = null
     originalScrollViewPaddingBottom = 0
-    bottomInset = 0
   }
 
   fun findScrollView(): ViewGroup? {
-    if (pinnedScrollView != null) return pinnedScrollView
+    if (detectedScrollView != null) return detectedScrollView
     return findScrollView(this as View)
   }
 
@@ -276,30 +267,30 @@ class TrueSheetContentView(private val reactContext: ThemedReactContext) : React
   }
 
   private fun updateScrollViewInsetForKeyboard(keyboardHeight: Int) {
-    val scrollView = pinnedScrollView ?: return
+    val scrollView = detectedScrollView ?: return
 
-    // An absolute footer rises above the keyboard and covers the content's
-    // bottom edge — include it so the caret clears the footer, not just the
-    // keyboard. A relative footer stays behind the keyboard below the content,
-    // so its height shields that much of the keyboard's overlap.
+    // A relative footer stays behind the keyboard below the content, so its
+    // height shields that much of the keyboard's overlap. An absolute footer
+    // floats within the viewport — its clearance is the content padding's job
+    // (the caret reveal accounts for it, see scrollToFocusedInput).
     val totalBottomInset = if (keyboardHeight > 0) {
-      maxOf(0, keyboardHeight + (delegate?.footerKeyboardOcclusion ?: 0))
+      maxOf(0, keyboardHeight + minOf(0, delegate?.footerKeyboardOcclusion ?: 0))
     } else {
-      bottomInset
+      0
     }
     setScrollViewPaddingBottom(originalScrollViewPaddingBottom + totalBottomInset)
 
     scrollView.post { nudgeScrollView() }
   }
 
   private fun nudgeScrollView() {
-    val scrollView = pinnedScrollView ?: return
+    val scrollView = detectedScrollView ?: return
     scrollView.smoothScrollBy(0, 1)
     scrollView.smoothScrollBy(0, -1)
   }
 
   private fun scrollToFocusedInput() {
-    val scrollView = pinnedScrollView ?: findScrollView() ?: return
+    val scrollView = detectedScrollView ?: findScrollView() ?: return
     val focusedView = findFocus() ?: return
 
     val focusedLocation = IntArray(2)
@@ -326,14 +317,18 @@ class TrueSheetContentView(private val reactContext: ThemedReactContext) : React
       caretBottom = viewTop + focusedView.height
     }
 
+    // An absolute footer floats over the viewport's bottom edge — extend the
+    // caret target so it clears the footer, not just the keyboard.
+    val footerOcclusion = maxOf(0, delegate?.footerKeyboardOcclusion ?: 0)
+
     val offset = keyboardScrollOffset.toInt()
     val visibleHeight = scrollView.height - scrollView.paddingBottom
     val visibleTop = scrollView.scrollY
     val visibleBottom = scrollView.scrollY + visibleHeight
 
     when {
-      caretBottom + offset > visibleBottom ->
-        scrollView.smoothScrollTo(0, caretBottom + offset - visibleHeight)
+      caretBottom + offset + footerOcclusion > visibleBottom ->
+        scrollView.smoothScrollTo(0, caretBottom + offset + footerOcclusion - visibleHeight)
 
       caretTop - offset < visibleTop ->
         scrollView.smoothScrollTo(0, (caretTop - offset).coerceAtLeast(0))

android/src/main/java/com/lodev09/truesheet/TrueSheetView.kt

@@ -319,8 +319,6 @@ class TrueSheetView(private val reactContext: ThemedReactContext) :
 
   private fun setupScrollable() {
     viewController.containerView?.let {
-      it.insetAdjustment = viewController.insetAdjustment
-      it.scrollViewBottomInset = viewController.contentBottomInset
       it.scrollableOptions = viewController.scrollableOptions
       it.hasAutoDetent = viewController.detents.contains(-1.0)
       it.footerBottomInset = viewController.contentBottomInset
@@ -643,7 +641,7 @@ class TrueSheetView(private val reactContext: ThemedReactContext) :
     viewController.commitKeyboardDetent()
   }
 
-  // When the ScrollView changes (e.g. conditional remount), re-pin the new ScrollView
+  // When the ScrollView changes (e.g. conditional remount), re-detect the new ScrollView
   // and request layout so BottomSheetBehavior re-discovers the nested scrolling child.
   override fun containerViewScrollViewDidChange() {
     setupScrollable()

android/src/main/java/com/lodev09/truesheet/core/TrueSheetCoordinatorLayout.kt

@@ -57,7 +57,7 @@ class TrueSheetCoordinatorLayout(context: Context) :
   private var streamGestureClaimed = false
 
   // Whether the sheet owns vertical drags for this stream: the touch target is inside
-  // the sheet but outside the pinned scrollable (e.g. a header overlaying it), with
+  // the sheet but outside the detected scrollable (e.g. a header overlaying it), with
   // nothing vertically scrollable along its chain. Such targets consume the stream
   // natively (no nested scroll), and BottomSheetBehavior won't intercept because the
   // scrollable's bounds still contain the point (touchingScrollingChild) — intercept
@@ -127,7 +127,7 @@ class TrueSheetCoordinatorLayout(context: Context) :
 
   /**
    * Resolves the stream's touch target (respecting zIndex and pointerEvents) and
-   * decides whether the sheet may drag from it — inside the sheet, outside the pinned
+   * decides whether the sheet may drag from it — inside the sheet, outside the detected
    * scrollable, and nothing along the target's chain scrolls vertically.
    */
   private fun updateStreamTargetFlags(ev: MotionEvent) {
@@ -139,7 +139,7 @@ class TrueSheetCoordinatorLayout(context: Context) :
       .firstNotNullOfOrNull { it.getView() } ?: return
     if (target !== sheet && !target.isDescendantOf(sheet)) return
 
-    // A pinned scrollable that can scroll (or hosts pull-to-refresh) owns its
+    // A detected scrollable that can scroll (or hosts pull-to-refresh) owns its
     // touches — nested scrolling drags the sheet. When it can't scroll (e.g.
     // the sheet is fully expanded and the content fits) it eats the gesture
     // instead, so fall through and let the sheet drag from it — an EditText

common/cpp/react/renderer/components/TrueSheetSpec/TrueSheetContentViewShadowNode.cpp

@@ -25,7 +25,7 @@ void TrueSheetContentViewShadowNode::adjustLayoutWithState() {
 
   auto &props = getConcreteProps();
 
-  // When a ScrollView is pinned under an auto detent, fill the container so
+  // When a ScrollView is detected under an auto detent, fill the container so
   // descendant flex layouts (flex:1 wrappers, the ScrollView itself) resolve
   // against a definite height and the viewport is bounded — natural layout is
   // circular there since the sheet height derives from the content's natural

common/cpp/react/renderer/components/TrueSheetSpec/TrueSheetContentViewState.h

@@ -12,7 +12,7 @@ namespace facebook::react {
 
 /*
  * State for <TrueSheetContentView> component.
- * `scrollableBounded` is set from native when a ScrollView is pinned so the
+ * `scrollableBounded` is set from native when a ScrollView is detected so the
  * shadow node bounds the content to the container via flexShrink.
  * `naturalHeight` is measured by the shadow node during layout — the height
  * the content wants when unbounded (see TrueSheetContentViewShadowNode).

docs/docs/guides/scrolling.mdx

@@ -12,7 +12,7 @@ Scrolling content within the sheet works like a regular view — bound the scrol
 
 ## How?
 
-Scroll views (including `ScrollView` and `FlatList`) are **automatically detected**. Insets, keyboard handling, and nested scrolling are all wired for you — no props needed.
+Scroll views (including `ScrollView` and `FlatList`) are **automatically detected**. Keyboard handling and nested scrolling are wired for you — no props needed.
 
 Like any scroll view in React Native, it needs a bounded height to scroll. Pass `flex: 1` via the sheet's [`style`](../reference/configuration#style) prop so the content fills the sheet's visible height per detent — resizing in realtime while dragging:
 

docs/docs/migration.mdx

@@ -124,7 +124,33 @@ const MyFooter = () => {
 See the [Footer guide](guides/footer#safe-area-handling) for more details.
 :::
 
-### 6. Sheet Navigator Requires `@react-navigation/native` 7.3+
+### 6. Scrollables No Longer Auto-Inset
+
+A plugged scrollable no longer gets the bottom safe-area inset applied natively. Only keyboard handling stays automatic. Pad the scroll content yourself:
+
+```tsx
+// ❌ v3 — the inset was applied natively
+<ScrollView>{/* ... */}</ScrollView>
+
+// ✅ v4 — pad the content yourself
+const insets = useSafeAreaInsets();
+
+<ScrollView contentContainerStyle={{ paddingBottom: insets.bottom }}>
+  {/* ... */}
+</ScrollView>
+```
+
+On iOS, you can let UIKit apply it instead with React Native's [`contentInsetAdjustmentBehavior`](https://reactnative.dev/docs/scrollview#contentinsetadjustmentbehavior-ios) (iOS only, defaults to `"never"`):
+
+```tsx
+<ScrollView contentInsetAdjustmentBehavior="automatic">{/* ... */}</ScrollView>
+```
+
+:::info
+If your sheet has a footer, it already absorbs the bottom inset (see above) — pad for the footer's height instead of the safe area.
+:::
+
+### 7. Sheet Navigator Requires `@react-navigation/native` 7.3+
 
 The navigator is now built on [`standard-navigation`](https://github.com/react-navigation/standard-navigation), so one implementation works with both React Navigation and Expo Router. For React Navigation apps, the `/navigation` entry point now requires `@react-navigation/native` version `7.3.0` or higher (previously `@react-navigation/core`), plus the new `standard-navigation` peer dependency:
 
@@ -134,7 +160,7 @@ yarn add @react-navigation/native@^7.3.0 standard-navigation
 
 Your navigator code is unchanged — `createTrueSheetNavigator`, `useTrueSheetNavigation`, screen options, `navigation.resize()`, and listeners all keep the same API.
 
-### 7. Expo Router Uses the New `/navigation/expo-router` Entry Point
+### 8. Expo Router Uses the New `/navigation/expo-router` Entry Point
 
 The `withLayoutContext` recipe is replaced by a ready-to-use `Sheet` layout. Requires Expo SDK 57+ and the new `standard-navigation` peer dependency — no `@react-navigation/*` install needed.
 
@@ -251,6 +277,7 @@ const Sheet = createTrueSheetNavigator({
    - Add `style={{ flex: 1 }}` where content should fill the sheet (bounded scroll views, spacer layouts)
    - Add `footerOptions={{ position: 'absolute' }}` to keep a floating footer
    - Remove manual safe-area padding from footers
+   - Add bottom safe-area padding to scrollables — it's no longer applied natively
    - If using the Sheet Navigator, install `standard-navigation` and update `@react-navigation/native` to 7.3+
    - If using Expo Router, install `standard-navigation`, replace the `withLayoutContext` wrapper with the `Sheet` layout from `/navigation/expo-router`, and update `useTrueSheetNavigation` imports
 6. **Test your app:**

example/shared/src/components/sheets/FlatListSheet.tsx

@@ -1,6 +1,7 @@
 import { forwardRef, useRef, useState } from 'react';
-import { StyleSheet, FlatList, View, Platform } from 'react-native';
+import { StyleSheet, FlatList, Platform } from 'react-native';
 import { TrueSheet, type TrueSheetProps } from '@lodev09/react-native-true-sheet';
+import { useSafeAreaInsets } from 'react-native-safe-area-context';
 
 import { DARK, DARK_GRAY, FOOTER_HEIGHT, HEADER_HEIGHT, SPACING, times } from '../../utils';
 import { DemoContent } from '../DemoContent';
@@ -16,6 +17,7 @@ export const FlatListSheet = forwardRef<TrueSheet, FlatListSheetProps>((props, r
   const testRef = useRef<TrueSheet>(null);
   const scrollRef = useRef<FlatList>(null);
   const [itemCount, setItemCount] = useState(3);
+  const insets = useSafeAreaInsets();
 
   return (
     <TrueSheet
@@ -39,7 +41,10 @@ export const FlatListSheet = forwardRef<TrueSheet, FlatListSheetProps>((props, r
       <FlatList
         ref={scrollRef}
         data={times(itemCount, (i) => i)}
-        contentContainerStyle={styles.content}
+        contentContainerStyle={[
+          styles.content,
+          { paddingBottom: FOOTER_HEIGHT + SPACING + insets.bottom },
+        ]}
         indicatorStyle="black"
         ItemSeparatorComponent={Spacer}
         renderItem={({ item }) => <DemoContent color={DARK_GRAY} text={`Item #${item}`} />}
@@ -75,6 +80,5 @@ const styles = StyleSheet.create({
   content: {
     padding: SPACING,
     paddingTop: HEADER_HEIGHT + SPACING,
-    paddingBottom: FOOTER_HEIGHT + SPACING,
   },
 });