fix: non-scrollable ScrollView when blankSpace is big should make it scrollable (#1487)

## 📜 Description

This fixes an Android-only `KeyboardChatScrollView` edge case where
short content can become scrollable only because of `blankSpace`, but a
scroll gesture that starts on the content is not intercepted by the
`ScrollView`.

## 💡 Motivation and Context

The root cause is not Fabric and not React Native “overriding touch
events” in the usual sense. The issue comes from Android `ScrollView`
having two different scrollability calculations when padding is used as
synthetic scrollable space.

[AOSP
ScrollView.java](https://android.googlesource.com/platform/frameworks/base/+/refs/heads/main/core/java/android/widget/ScrollView.java#581)
`ScrollView.onInterceptTouchEvent` exits early when it thinks the view
cannot scroll down:

```java
if (getScrollY() == 0 && !canScrollVertically(1)) {
  return false;
}
```

`canScrollVertically()` is implemented on
[View](https://android.googlesource.com/platform/frameworks/base/+/refs/heads/main/core/java/android/view/View.java#22167)
and uses:

```java
computeVerticalScrollRange() - computeVerticalScrollExtent()
```

For
[ScrollView](https://android.googlesource.com/platform/frameworks/base/+/refs/heads/main/core/java/android/widget/ScrollView.java#1338),
`computeVerticalScrollRange()` is based on the content child bounds:

```java
int scrollRange = getChildAt(0).getBottom();
```

That does not include `paddingBottom`.

But the actual scroll/drag range uses
[`getScrollRange()`](https://android.googlesource.com/platform/frameworks/base/+/refs/heads/main/core/java/android/widget/ScrollView.java#1036):

```java
child.getHeight() - (getHeight() - mPaddingBottom - mPaddingTop)
```

That does include padding, because padding reduces the viewport height.

So with short content plus padding-backed `blankSpace`, Android can get
into this contradictory state:

```text
canScrollVertically(1) -> false
actual getScrollRange() -> positive
```

React Native is not the primary source of the bug. `ReactScrollView`
adds RN event/state handling, but still delegates interception and touch
handling to AOSP `ScrollView`. The package triggers the Android edge
case because `KeyboardChatScrollView` uses native padding to model an
iOS-like `contentInset`/`blankSpace`.

There are a few possible ways to fix this:

1. Patch Android or React Native `ScrollView` so `canScrollVertically()`
and the actual scroll range agree when padding is used as scrollable
inset. This would be the most fundamental fix, but it is outside this
package.

2. Own a custom Android `ReactScrollView` subclass and override the
relevant scrollability/range methods. This is more correct in isolation,
but it is a large maintenance burden because we would need to preserve
React Native ScrollView props, events, commands, refs, Paper/Fabric
behavior, and Reanimated compatibility.

3. Represent `blankSpace` as real content layout, for example with a
spacer/footer or `contentContainerStyle.paddingBottom`. This makes
Android’s range calculations agree naturally, but it changes content
layout semantics and can interfere with virtualized lists (it changes
layout, JS update may overwrite it etc., not really "safe" way of doing
this)

4. Keep the current `ClippingScrollView` approach and avoid pathological
blank ranges.

This PR chooses option 4. The native workaround fixes the short-content
gesture issue without forking React Native’s ScrollView or changing user
content layout. On top of that, we clamp `blankSpace` in JS so it cannot
exceed one ScrollView viewport. Otherwise we have this bug:


https://github.com/user-attachments/assets/5311381b-76ad-4f0e-95b5-f235741ab754

The JS clamp is needed because values larger than the viewport create a
scroll range made mostly or entirely of empty space. That oversized
empty range is not useful for the chat use case and can expose Android
momentum/range desynchronization during fast gestures. One viewport of
`blankSpace` is enough to make short content scrollable and position it
correctly; larger values only allow scrolling to a fully blank screen:
#1497

Closes
#1497
#1453
#1455

## 📢 Changelog

<!-- High level overview of important changes -->
<!-- For example: fixed status bar manipulation; added new types
declarations; -->
<!-- If your changes don't affect one of platform/language below - then
remove this platform/language -->

## 📢 Changelog

### JS

- clamp `KeyboardChatScrollView` `blankSpace` to the ScrollView viewport
height;
- prevent oversized blank scroll ranges that can cause Android momentum
flicker;

### Android

- adjust `ClippingScrollViewDecoratorView` touch handling to allow short
content with padding-backed `blankSpace` to start scrolling from the
content area;
- keep the temporary content range expansion scoped to the touch
dispatch path and restore it immediately after dispatch;

## 🤔 How Has This Been Tested?

Tested manually on Pixel 7 Pro (API 36).

## 📸 Screenshots (if appropriate):

|Before|After|
|-------|-----|
|<video
src="https://github.com/user-attachments/assets/2c9aabdd-7252-4d23-95a2-9de944ecdafa">|<video
src="https://github.com/user-attachments/assets/8e64eefd-55a8-49ce-8f53-ac32d6b36598">|

## 📝 Checklist

- [x] CI successfully passed
- [x] I added new mocks and corresponding unit-tests if library API was
changed

Author: kirillzyusko

android/src/main/java/com/reactnativekeyboardcontroller/views/ClippingScrollViewDecoratorView.kt

@@ -1,12 +1,14 @@
 package com.reactnativekeyboardcontroller.views
 
 import android.annotation.SuppressLint
+import android.view.MotionEvent
 import android.view.View
 import android.view.ViewGroup
 import android.widget.ScrollView
 import com.facebook.react.uimanager.ThemedReactContext
 import com.facebook.react.views.view.ReactViewGroup
 import com.reactnativekeyboardcontroller.extensions.px
+import kotlin.math.max
 
 @SuppressLint("ViewConstructor")
 class ClippingScrollViewDecoratorView(
@@ -15,13 +17,42 @@ class ClippingScrollViewDecoratorView(
   private var insetBottom = 0.0
   private var insetTop = 0.0
   private var appliedTopInsetPx = 0
+  private var paddingScrollWorkaroundActive = false
 
   override fun onAttachedToWindow() {
     super.onAttachedToWindow()
 
     decorateScrollView()
   }
 
+  override fun dispatchTouchEvent(event: MotionEvent): Boolean {
+    val scrollView = findScrollView(this)
+
+    if (scrollView == null) {
+      return super.dispatchTouchEvent(event)
+    }
+
+    if (event.actionMasked == MotionEvent.ACTION_DOWN) {
+      paddingScrollWorkaroundActive = shouldUsePaddingScrollWorkaround(scrollView, event)
+    }
+
+    val handled =
+      if (paddingScrollWorkaroundActive) {
+        dispatchWithExpandedContentRange(scrollView, event)
+      } else {
+        super.dispatchTouchEvent(event)
+      }
+
+    if (
+      event.actionMasked == MotionEvent.ACTION_UP ||
+      event.actionMasked == MotionEvent.ACTION_CANCEL
+    ) {
+      paddingScrollWorkaroundActive = false
+    }
+
+    return handled
+  }
+
   fun setContentInsetBottom(value: Double) {
     insetBottom = value
     decorateScrollView()
@@ -68,6 +99,65 @@ class ClippingScrollViewDecoratorView(
     appliedTopInsetPx = newTopInsetPx
   }
 
+  private fun shouldUsePaddingScrollWorkaround(
+    scrollView: ScrollView,
+    event: MotionEvent,
+  ): Boolean {
+    val contentView = scrollView.getChildAt(0) ?: return false
+    val viewportHeight =
+      scrollView.height - scrollView.paddingTop - scrollView.paddingBottom
+    val paddingCreatesScrollRange = contentView.height > viewportHeight
+
+    return scrollView.scrollY == 0 &&
+      paddingCreatesScrollRange &&
+      !scrollView.canScrollVertically(1) &&
+      isTouchInScrollContent(scrollView, event)
+  }
+
+  private fun dispatchWithExpandedContentRange(
+    scrollView: ScrollView,
+    event: MotionEvent,
+  ): Boolean {
+    val contentView = scrollView.getChildAt(0)
+    val originalBottom = contentView?.bottom ?: 0
+    val expandedBottom =
+      max(originalBottom, scrollView.height + scrollView.scrollY + MIN_SCROLL_RANGE_PX)
+
+    if (contentView == null || expandedBottom == originalBottom) {
+      return super.dispatchTouchEvent(event)
+    }
+
+    return try {
+      contentView.bottom = expandedBottom
+      super.dispatchTouchEvent(event)
+    } finally {
+      contentView.bottom = originalBottom
+    }
+  }
+
+  private fun isTouchInScrollContent(
+    scrollView: ScrollView,
+    event: MotionEvent,
+  ): Boolean {
+    val contentView = scrollView.getChildAt(0) ?: return false
+    val thisLocation = IntArray(COORDINATES_SIZE)
+    val scrollViewLocation = IntArray(COORDINATES_SIZE)
+
+    getLocationOnScreen(thisLocation)
+    scrollView.getLocationOnScreen(scrollViewLocation)
+
+    val x = event.x + thisLocation[0] - scrollViewLocation[0]
+    val y = event.y + thisLocation[1] - scrollViewLocation[1]
+    val scrollY = scrollView.scrollY
+
+    return !(
+      y < contentView.top - scrollY ||
+        y >= contentView.bottom - scrollY ||
+        x < contentView.left ||
+        x >= contentView.right
+    )
+  }
+
   private fun findScrollView(view: View?): ScrollView? {
     var result: ScrollView? = null
 
@@ -83,4 +173,9 @@ class ClippingScrollViewDecoratorView(
 
     return result
   }
+
+  companion object {
+    private const val COORDINATES_SIZE = 2
+    private const val MIN_SCROLL_RANGE_PX = 2
+  }
 }

src/components/KeyboardChatScrollView/index.tsx

@@ -88,8 +88,18 @@ const KeyboardChatScrollView = forwardRef<
       onEndVisible,
     });
 
+    // intentionally clamp `blankSpace` at one ScrollView viewport. The Android
+    // `ClippingScrollView` workaround temporarily substitutes padding/range
+    // during touch handling, and oversized blank ranges can de-sync during fast
+    // momentum gestures. One viewport is enough for the short-content case;
+    // larger values only allow scrolling to a fully blank screen which is not
+    // the use case for this library. If you found this comment and it causes
+    // a bug for you, please open an issue.
     const totalPadding = useDerivedValue(() =>
-      Math.max(blankSpace.value, padding.value + extraContentPadding.value),
+      Math.min(
+        layout.value.height,
+        Math.max(blankSpace.value, padding.value + extraContentPadding.value),
+      ),
     );
 
     // Scroll indicator inset = keyboard + extraContentPadding (excludes blankSpace).