feat: add scrollingExpandsSheet to scrollableOptions (#585)

* feat: add scrollingExpandsSheet to scrollableOptions

* feat(android): implement scrollingExpandsSheet via custom behavior

* feat(android): auto-enable nestedScrollingEnabled for scrollable sheets

* refactor(android): support NestedScrollView for future RN compatibility

* docs: update scrollable guides and add scrollableOptions reference

* fix(android): add scroll expansion padding for scrollable sheets

Adds bottom padding to ScrollView to compensate for the container being
sized to the largest detent. Without this, the scroll range is reduced
at smaller detents since the viewport extends beyond the visible area.

* refactor: type scrollableOptions and grabberOptions on both platforms

Replace NSDictionary/ReadableMap with typed ScrollableOptions and
GrabberOptions classes. ViewManager (Android) and TrueSheetView (iOS)
normalize raw props into typed objects.

* chore: add changelog entries for scrollingExpandsSheet

Author: lodev09

CHANGELOG.md

@@ -2,11 +2,19 @@
 
 ## Unreleased
 
+### 🎉 New features
+
+- Add `scrollingExpandsSheet` option to `scrollableOptions`. ([#585](https://github.com/lodev09/react-native-true-sheet/pull/585) by [@lodev09](https://github.com/lodev09))
+
 ### 🐛 Bug fixes
 
 - **iOS**: Fixed position change not emitting when detent or index changed. ([#584](https://github.com/lodev09/react-native-true-sheet/pull/584) by [@lodev09](https://github.com/lodev09))
 - **Android**: Use RN `BackHandler` for back press detection for reliability across Android versions. ([#580](https://github.com/lodev09/react-native-true-sheet/pull/580) by [@lodev09](https://github.com/lodev09))
 
+### ⚠️ Breaking
+
+- **Android**: `nestedScrollingEnabled` is now automatically managed when `scrollable` is enabled. ([#585](https://github.com/lodev09/react-native-true-sheet/pull/585))
+
 ## 3.9.9
 
 ### 🐛 Bug fixes

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

@@ -2,7 +2,6 @@ package com.lodev09.truesheet
 
 import android.annotation.SuppressLint
 import android.view.View
-import com.facebook.react.bridge.ReadableMap
 import com.facebook.react.uimanager.ThemedReactContext
 import com.facebook.react.uimanager.events.EventDispatcher
 import com.facebook.react.views.view.ReactViewGroup
@@ -40,7 +39,7 @@ class TrueSheetContainerView(reactContext: ThemedReactContext) :
   var insetAdjustment: TrueSheetInsetAdjustment = TrueSheetInsetAdjustment.AUTOMATIC
   var scrollViewBottomInset: Int = 0
   var scrollableEnabled: Boolean = false
-  var scrollableOptions: ReadableMap? = null
+  var scrollableOptions: ScrollableOptions? = null
     set(value) {
       field = value
       contentView?.scrollableOptions = value

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

@@ -4,13 +4,21 @@ import android.annotation.SuppressLint
 import android.view.View
 import android.view.ViewGroup
 import android.widget.ScrollView
-import com.facebook.react.bridge.ReadableMap
+import androidx.core.widget.NestedScrollView
+import androidx.swiperefreshlayout.widget.SwipeRefreshLayout
 import com.facebook.react.uimanager.PixelUtil.dpToPx
 import com.facebook.react.uimanager.ThemedReactContext
 import com.facebook.react.views.view.ReactViewGroup
 import com.lodev09.truesheet.core.TrueSheetKeyboardObserver
 import com.lodev09.truesheet.core.TrueSheetKeyboardObserverDelegate
 import com.lodev09.truesheet.utils.isDescendantOf
+import com.lodev09.truesheet.utils.smoothScrollBy
+import com.lodev09.truesheet.utils.smoothScrollTo
+
+data class ScrollableOptions(
+  val keyboardScrollOffset: Float = 0f,
+  val scrollingExpandsSheet: Boolean = true
+)
 
 /**
  * Delegate interface for content view size changes
@@ -32,17 +40,18 @@ class TrueSheetContentView(private val reactContext: ThemedReactContext) : React
   private var lastWidth = 0
   private var lastHeight = 0
 
-  private var pinnedScrollView: ScrollView? = null
+  private var pinnedScrollView: ViewGroup? = null
   private var originalScrollViewPaddingBottom: Int = 0
   private var bottomInset: Int = 0
+  private var scrollExpansionPadding: Int = 0
 
   private var keyboardScrollOffset: Float = 0f
   private var keyboardObserver: TrueSheetKeyboardObserver? = null
 
-  var scrollableOptions: ReadableMap? = null
+  var scrollableOptions: ScrollableOptions? = null
     set(value) {
       field = value
-      keyboardScrollOffset = value?.getDouble("keyboardScrollOffset")?.toFloat()?.dpToPx() ?: 0f
+      keyboardScrollOffset = value?.keyboardScrollOffset?.dpToPx() ?: 0f
     }
 
   override fun addView(child: View?, index: Int) {
@@ -94,6 +103,9 @@ class TrueSheetContentView(private val reactContext: ThemedReactContext) : React
       originalScrollViewPaddingBottom = scrollView.paddingBottom
       pinnedScrollView = scrollView
 
+      scrollView.isNestedScrollingEnabled = true
+      (scrollView.parent as? SwipeRefreshLayout)?.isNestedScrollingEnabled = false
+
       scrollView.setOnScrollChangeListener { _, _, scrollY, _, oldScrollY ->
         if (scrollY != oldScrollY) {
           delegate?.contentViewDidScroll()
@@ -112,33 +124,49 @@ class TrueSheetContentView(private val reactContext: ThemedReactContext) : React
     }
   }
 
+  // TODO: Replace this workaround with synchronous state layout updates on every sheet resize.
+  // The container is currently sized to the largest detent, so at smaller detents the ScrollView
+  // viewport extends beyond the visible area, reducing the effective scroll range. This padding
+  // compensates for that difference until we can resize the container per-detent synchronously.
+  fun updateScrollExpansionPadding(padding: Int) {
+    if (scrollExpansionPadding == padding) return
+    scrollExpansionPadding = padding
+    val keyboardHeight = keyboardObserver?.currentHeight ?: 0
+    val basePadding = if (keyboardHeight > 0) keyboardHeight else bottomInset
+    setScrollViewPaddingBottom(originalScrollViewPaddingBottom + basePadding)
+    nudgeScrollView()
+  }
+
   private fun setScrollViewPaddingBottom(paddingBottom: Int) {
     val scrollView = pinnedScrollView ?: return
     scrollView.clipToPadding = false
     scrollView.setPadding(
       scrollView.paddingLeft,
       scrollView.paddingTop,
       scrollView.paddingRight,
-      paddingBottom
+      paddingBottom + scrollExpansionPadding
     )
   }
 
   fun clearScrollable() {
     pinnedScrollView?.setOnScrollChangeListener(null as View.OnScrollChangeListener?)
+    pinnedScrollView?.isNestedScrollingEnabled = false
+    (pinnedScrollView?.parent as? SwipeRefreshLayout)?.isNestedScrollingEnabled = true
+    scrollExpansionPadding = 0
     setScrollViewPaddingBottom(originalScrollViewPaddingBottom)
     pinnedScrollView = null
     originalScrollViewPaddingBottom = 0
     bottomInset = 0
   }
 
-  fun findScrollView(): ScrollView? {
+  fun findScrollView(): ViewGroup? {
     if (pinnedScrollView != null) return pinnedScrollView
     return findScrollView(this as View)
   }
 
-  private fun findScrollView(view: View): ScrollView? {
-    if (view is ScrollView) {
-      return view
+  private fun findScrollView(view: View): ViewGroup? {
+    if (view is ScrollView || view is NestedScrollView) {
+      return view as ViewGroup
     }
 
     if (view is ViewGroup) {
@@ -191,11 +219,13 @@ class TrueSheetContentView(private val reactContext: ThemedReactContext) : React
     val totalBottomInset = if (keyboardHeight > 0) keyboardHeight else bottomInset
     setScrollViewPaddingBottom(originalScrollViewPaddingBottom + totalBottomInset)
 
-    // Trigger a scroll to force update
-    scrollView.post {
-      scrollView.smoothScrollBy(0, 1)
-      scrollView.smoothScrollBy(0, -1)
-    }
+    scrollView.post { nudgeScrollView() }
+  }
+
+  private fun nudgeScrollView() {
+    val scrollView = pinnedScrollView ?: return
+    scrollView.smoothScrollBy(0, 1)
+    scrollView.smoothScrollBy(0, -1)
   }
 
   private fun scrollToFocusedInput() {

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

@@ -6,7 +6,6 @@ import android.view.ViewGroup
 import android.view.accessibility.AccessibilityEvent
 import androidx.annotation.UiThread
 import com.facebook.react.bridge.LifecycleEventListener
-import com.facebook.react.bridge.ReadableMap
 import com.facebook.react.bridge.WritableNativeMap
 import com.facebook.react.uimanager.PixelUtil.pxToDp
 import com.facebook.react.uimanager.StateWrapper
@@ -282,7 +281,7 @@ class TrueSheetView(private val reactContext: ThemedReactContext) :
     setupScrollable()
   }
 
-  fun setScrollableOptions(options: ReadableMap?) {
+  fun setScrollableOptions(options: ScrollableOptions?) {
     viewController.scrollableOptions = options
     setupScrollable()
   }

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

@@ -8,12 +8,10 @@ import android.view.View
 import android.view.ViewGroup
 import android.view.accessibility.AccessibilityNodeInfo
 import android.widget.ImageView
-import android.widget.ScrollView
 import androidx.coordinatorlayout.widget.CoordinatorLayout
 import androidx.core.graphics.createBitmap
 import androidx.core.view.isNotEmpty
 import com.facebook.react.R
-import com.facebook.react.bridge.ReadableMap
 import com.facebook.react.uimanager.JSPointerDispatcher
 import com.facebook.react.uimanager.JSTouchDispatcher
 import com.facebook.react.uimanager.PixelUtil.dpToPx
@@ -24,6 +22,7 @@ import com.facebook.react.uimanager.events.EventDispatcher
 import com.facebook.react.util.RNLog
 import com.facebook.react.views.view.ReactViewGroup
 import com.google.android.material.bottomsheet.BottomSheetBehavior
+import com.lodev09.truesheet.core.TrueSheetBottomSheetBehavior
 import com.lodev09.truesheet.core.GrabberOptions
 import com.lodev09.truesheet.core.TrueSheetBottomSheetView
 import com.lodev09.truesheet.core.TrueSheetBottomSheetViewDelegate
@@ -208,7 +207,12 @@ class TrueSheetViewController(private val reactContext: ThemedReactContext) :
 
   var scrollable: Boolean = false
 
-  var scrollableOptions: ReadableMap? = null
+  var scrollableOptions: ScrollableOptions? = null
+    set(value) {
+      field = value
+      behavior?.scrollingExpandsSheet = value?.scrollingExpandsSheet ?: true
+      if (isPresented) sheetView?.let { updateScrollExpansionPadding(it.top) }
+    }
 
   override var sheetCornerRadius: Float = DEFAULT_CORNER_RADIUS.dpToPx()
     set(value) {
@@ -240,7 +244,7 @@ class TrueSheetViewController(private val reactContext: ThemedReactContext) :
   // =============================================================================
 
   // Behavior
-  private val behavior: BottomSheetBehavior<TrueSheetBottomSheetView>?
+  private val behavior: TrueSheetBottomSheetBehavior<TrueSheetBottomSheetView>?
     get() = sheetView?.behavior
 
   internal val containerView: TrueSheetContainerView?
@@ -425,7 +429,7 @@ class TrueSheetViewController(private val reactContext: ThemedReactContext) :
     sheetView?.let { emitChangePositionDelegate(it.top, realtime = false) }
   }
 
-  override fun findScrollView(): ScrollView? = containerView?.contentView?.findScrollView()
+  override fun findScrollView(): ViewGroup? = containerView?.contentView?.findScrollView()
   override fun findSheetView(): TrueSheetBottomSheetView? = sheetView
 
   // =============================================================================
@@ -524,6 +528,7 @@ class TrueSheetViewController(private val reactContext: ThemedReactContext) :
       else -> { }
     }
 
+    updateScrollExpansionPadding(sheetView.top)
     emitChangePositionDelegate(sheetView.top)
 
     // On older APIs, use onSlide for footer positioning during keyboard transitions
@@ -537,6 +542,15 @@ class TrueSheetViewController(private val reactContext: ThemedReactContext) :
     }
   }
 
+  private fun updateScrollExpansionPadding(sheetTop: Int) {
+    if (!scrollable) {
+      containerView?.contentView?.updateScrollExpansionPadding(0)
+      return
+    }
+    val expandedOffset = behavior?.expandedOffset ?: return
+    containerView?.contentView?.updateScrollExpansionPadding(maxOf(0, sheetTop - expandedOffset))
+  }
+
   private fun handleStateSettled(sheetView: View, newState: Int) {
     if (interactionState is InteractionState.Reconfiguring) return
 
@@ -696,11 +710,12 @@ class TrueSheetViewController(private val reactContext: ThemedReactContext) :
     val params = sheet.createLayoutParams()
 
     @Suppress("UNCHECKED_CAST")
-    val behavior = params.behavior as BottomSheetBehavior<TrueSheetBottomSheetView>
+    val behavior = params.behavior as TrueSheetBottomSheetBehavior<TrueSheetBottomSheetView>
 
     // Configure behavior
     behavior.isHideable = true
     behavior.isDraggable = draggable
+    behavior.scrollingExpandsSheet = scrollableOptions?.scrollingExpandsSheet ?: true
     behavior.state = BottomSheetBehavior.STATE_HIDDEN
     behavior.addBottomSheetCallback(sheetCallback)
 

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

@@ -218,7 +218,16 @@ class TrueSheetViewManager :
 
   @ReactProp(name = "scrollableOptions")
   override fun setScrollableOptions(view: TrueSheetView, options: ReadableMap?) {
-    view.setScrollableOptions(options)
+    if (options == null) {
+      view.setScrollableOptions(null)
+      return
+    }
+
+    val scrollableOptions = ScrollableOptions(
+      keyboardScrollOffset = if (options.hasKey("keyboardScrollOffset")) options.getDouble("keyboardScrollOffset").toFloat() else 0f,
+      scrollingExpandsSheet = if (options.hasKey("scrollingExpandsSheet")) options.getBoolean("scrollingExpandsSheet") else true
+    )
+    view.setScrollableOptions(scrollableOptions)
   }
 
   companion object {

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

@@ -0,0 +1,36 @@
+package com.lodev09.truesheet.core
+
+import android.view.View
+import androidx.coordinatorlayout.widget.CoordinatorLayout
+import com.google.android.material.bottomsheet.BottomSheetBehavior
+
+class TrueSheetBottomSheetBehavior<V : View> : BottomSheetBehavior<V>() {
+  var scrollingExpandsSheet: Boolean = true
+
+  override fun onNestedPreScroll(
+    coordinatorLayout: CoordinatorLayout,
+    child: V,
+    target: View,
+    dx: Int,
+    dy: Int,
+    consumed: IntArray,
+    type: Int
+  ) {
+    // dy > 0 = user swiping up = sheet expanding
+    // Block expansion from scroll, but allow if sheet is already being dragged
+    if (!scrollingExpandsSheet && dy > 0 && state != STATE_DRAGGING) return
+    super.onNestedPreScroll(coordinatorLayout, child, target, dx, dy, consumed, type)
+  }
+
+  override fun onNestedPreFling(
+    coordinatorLayout: CoordinatorLayout,
+    child: V,
+    target: View,
+    velocityX: Float,
+    velocityY: Float
+  ): Boolean {
+    // Don't consume flings — let the ScrollView decelerate naturally
+    if (!scrollingExpandsSheet) return false
+    return super.onNestedPreFling(coordinatorLayout, child, target, velocityX, velocityY)
+  }
+}

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

@@ -63,9 +63,9 @@ class TrueSheetBottomSheetView(private val reactContext: ThemedReactContext) : F
 
   // Behavior reference (set after adding to CoordinatorLayout)
   @Suppress("UNCHECKED_CAST")
-  val behavior: BottomSheetBehavior<TrueSheetBottomSheetView>?
+  val behavior: TrueSheetBottomSheetBehavior<TrueSheetBottomSheetView>?
     get() = (layoutParams as? CoordinatorLayout.LayoutParams)
-      ?.behavior as? BottomSheetBehavior<TrueSheetBottomSheetView>
+      ?.behavior as? TrueSheetBottomSheetBehavior<TrueSheetBottomSheetView>
 
   // =============================================================================
   // MARK: - Initialization
@@ -106,7 +106,7 @@ class TrueSheetBottomSheetView(private val reactContext: ThemedReactContext) : F
   fun createLayoutParams(): CoordinatorLayout.LayoutParams {
     val applyMaxWidth = delegate?.maxContentWidth != null && !ScreenUtils.isPortraitPhone(reactContext)
     val effectiveMaxWidth = if (applyMaxWidth) delegate!!.maxContentWidth!! else DEFAULT_MAX_WIDTH.dpToPx().toInt()
-    val behavior = BottomSheetBehavior<TrueSheetBottomSheetView>().apply {
+    val behavior = TrueSheetBottomSheetBehavior<TrueSheetBottomSheetView>().apply {
       isHideable = true
       maxWidth = effectiveMaxWidth
     }

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

@@ -5,7 +5,7 @@ import android.content.Context
 import android.content.res.Configuration
 import android.view.MotionEvent
 import android.view.ViewConfiguration
-import android.widget.ScrollView
+import android.view.ViewGroup
 import androidx.coordinatorlayout.widget.CoordinatorLayout
 import androidx.swiperefreshlayout.widget.SwipeRefreshLayout
 import com.facebook.react.uimanager.PointerEvents
@@ -15,7 +15,7 @@ import com.lodev09.truesheet.utils.isDescendantOf
 interface TrueSheetCoordinatorLayoutDelegate {
   fun coordinatorLayoutDidLayout(changed: Boolean)
   fun coordinatorLayoutDidChangeConfiguration()
-  fun findScrollView(): ScrollView?
+  fun findScrollView(): ViewGroup?
   fun findSheetView(): TrueSheetBottomSheetView?
 }
 
@@ -75,7 +75,7 @@ class TrueSheetCoordinatorLayout(context: Context) :
     val sheet = delegate?.findSheetView() ?: return
     val behavior = sheet.behavior ?: return
     try {
-      val field = behavior.javaClass.getDeclaredField("nestedScrollingChildRef")
+      val field = behavior.javaClass.superclass.getDeclaredField("nestedScrollingChildRef")
       field.isAccessible = true
       @Suppress("UNCHECKED_CAST")
       val ref = field.get(behavior) as? java.lang.ref.WeakReference<android.view.View> ?: return
@@ -105,6 +105,7 @@ class TrueSheetCoordinatorLayout(context: Context) :
       scrollView.scrollY == 0 &&
       !scrollView.canScrollVertically(1)
 
+
     if (cannotScroll) {
       when (ev.action and MotionEvent.ACTION_MASK) {
         MotionEvent.ACTION_DOWN -> {