@onekeyfe/react-native-pager-view 3.0.157-alpha.256 → 3.0.157-alpha.258

package/README.md

@@ -68,12 +68,59 @@ Web scroll child can opt in by exposing a DOM element with
 movement, so React is not updated on each vertical scroll frame.
 
 On iOS and Android, `nativeTabBar` renders the tab bar natively and
-`onNativeTabPress` reports presses. A press animates to the pressed page by
-default. Set `nativeTabPressAnimationEnabled={false}` to jump straight there,
-so pressing a distant tab does not scroll through every page in between,
-including unmounted pages that would show blank.
+`onNativeTabPress` reports presses. By default, adjacent tab presses animate and
+non-adjacent presses jump directly to the target without passing intermediate
+pages. Set `nativeTabPressAnimationEnabled={true}` to always animate, or `false`
+to always jump. Swipe gestures and imperative page commands are unchanged.
 
 Thank you again to Callstack and everyone who contributes to
 `react-native-pager-view` 💙
 
 The native ancestor-scroll contribution protocol is specified in [docs/SPEC.md](docs/SPEC.md).
+
+## NativeScroller compatibility
+
+The independent iOS/Android `NativeScroller` has passing native builds and
+focused simulator checks. The complete acceptance matrix remains open; see
+[docs/SPEC.md](docs/SPEC.md) for the verified cases and limits. It is a
+non-virtualized vertical scroller with one internal React content View. Fabric/Yoga lays out React children and content padding; size
+changes are sent to native through layout props, not a JavaScript scroll loop.
+Shared Fabric native state tracks local scroll displacement and ancestor header
+travel separately, without per-frame JavaScript coordination. Descendant hit
+testing and `measureInWindow` use that state; device acceptance must compare the
+reported coordinates with visible React content after scrolling and page return.
+The automatic flexGrow minimum uses a native-reported usable content height,
+with static pager reservations accounted for once. This internal size event is
+not public API and does not run on scroll frames. Before it arrives the automatic
+minimum is zero; a larger explicit numeric minHeight remains authoritative.
+Refresh insets and content-dependent bottom fill do not change this minimum.
+Web continues using its existing ScrollView implementation.
+
+The supported ScrollView subset is `contentContainerStyle` (including padding,
+height, numeric minHeight and flexGrow), `onContentSizeChange`, `scrollEnabled`,
+`nestedScrollEnabled`, indicators, `bounces`, `alwaysBounceVertical`,
+`contentInset`, keyboard dismissal/persist-tap modes, `scrollEventThrottle`, and
+the scroll/drag/momentum callbacks. Standard View props remain available.
+`decelerationRate` applies on iOS; Android uses AndroidX's native fling physics.
+`bounces`/`alwaysBounceVertical` and refresh tint/title are iOS controls; Android
+uses refresh colors/background/size and does not expose a bounce policy here.
+Tap-to-dismiss uses RN 0.86's JavaScript TextInput registry to preserve taps on
+another input and child-handled presses; keyboard behavior requires device checks.
+Horizontal scrolling, sticky rows, snapping, zoom, automatic keyboard insets and
+the full ScrollView responder API are not provided.
+
+Pass a standard `<RefreshControl refreshing={value} onRefresh={callback} />` as
+`refreshControl`. Its enabled, tint/colors, background, offset, title/title color
+and size props map to the component's native refresh controller; the RN refresh
+element is not mounted. Refreshing remains controlled even if the callback does
+not change the value. Arbitrary custom refresh components are not supported.
+
+`NativeScrollerRef` exposes `scrollTo`, `scrollToEnd`, `flashScrollIndicators`,
+host measurement/focus methods, `getNativeScrollRef` and `getScrollableNode`.
+`pagerScrollKey` remains the stable primary-scroller identity. Native command
+events use the ScrollView event shape; UIKit/AndroidX continue owning gestures
+and momentum. Animated commands whose clamped target differs from the current
+position emit a momentum begin/end pair; a no-op emits no new pair. A new command,
+new touch, content-root replacement or detach ends the previous active sequence.
+The focused JS tests verify wrapper routing, not native scrolling,
+Yoga rendering, keyboard interaction or refresh placement on a device.

package/android/src/main/java/com/reactnativepagerview/CollapsiblePagerHost.kt

@@ -1,6 +1,8 @@
 package com.reactnativepagerview
 
 import android.content.Context
+import android.graphics.Canvas
+import android.graphics.Matrix
 import android.graphics.Rect
 import android.os.SystemClock
 import android.view.MotionEvent
@@ -9,6 +11,7 @@ import android.view.ViewConfiguration
 import android.view.ViewGroup
 import android.view.ViewTreeObserver
 import android.widget.HorizontalScrollView
+import android.widget.ImageView
 import android.widget.ScrollView
 // OneKey patch: FrameLayout is inherited through NestedScrollableHost.
 // import android.widget.FrameLayout
@@ -17,11 +20,14 @@ import androidx.core.view.NestedScrollingParentHelper
 import androidx.core.view.ViewCompat
 import androidx.recyclerview.widget.LinearLayoutManager
 import androidx.recyclerview.widget.RecyclerView
+import androidx.swiperefreshlayout.widget.CircularProgressDrawable
+import androidx.swiperefreshlayout.widget.SwipeRefreshLayout
 import androidx.viewpager2.widget.ViewPager2
 import com.facebook.react.R as ReactR
 import com.facebook.react.uimanager.events.NativeGestureUtil
 import com.facebook.react.views.scroll.ReactScrollView
 import com.margelo.nitro.nativelogger.OneKeyLog
+import java.lang.ref.WeakReference
 import java.util.WeakHashMap
 import kotlin.math.max
 import kotlin.math.min
@@ -116,9 +122,19 @@ class CollapsiblePagerHost(context: Context) : NestedScrollableHost(context), Ne
   private val restoredRecyclerKeys = WeakHashMap<RecyclerView, String>()
   private val originalScrollerPadding = WeakHashMap<ScrollView, ScrollerPadding>()
   private val restoredScrollerKeys = WeakHashMap<ScrollView, String>()
+  private val ownedScrollerKeys = WeakHashMap<NativeScrollerViewport, String>()
+  private var foregroundRefreshIndicator: WeakReference<ImageView>? = null
+  private var refreshForegroundWasVisible = false
+  private val refreshForegroundMatrix = Matrix()
+  private val refreshForegroundOrigin = FloatArray(2)
+  private val refreshForegroundAncestors = ArrayList<View>()
+  private var refreshForegroundAncestorAlpha = 1f
   private val pageOffsets = HashMap<String, Int>()
   private var observedRecyclerView: RecyclerView? = null
   private var observedScrollListener: RecyclerView.OnScrollListener? = null
+  private var observedOwnedScroller: NativeScrollerViewport? = null
+  private var observedOwnedScrollerKey: String? = null
+  private var observedOwnedScrollerListener: ViewTreeObserver.OnScrollChangedListener? = null
   private var observedNativeScroller: ScrollView? = null
   private var observedNativeScrollerListener: ViewTreeObserver.OnScrollChangedListener? = null
   private var attachmentGeneration = 0
@@ -134,6 +150,7 @@ class CollapsiblePagerHost(context: Context) : NestedScrollableHost(context), Ne
   private var headerDownEvent: MotionEvent? = null
   private var headerHasHorizontalChild = false
   private var forwardedScrollable: View? = null
+  private var pendingRefreshPull: WeakReference<SwipeRefreshLayout>? = null
   private var nativeGestureStarted = false
   private var pressCancelled = false
   private val pageContentLayoutListener = ViewTreeObserver.OnPreDrawListener {
@@ -309,6 +326,7 @@ class CollapsiblePagerHost(context: Context) : NestedScrollableHost(context), Ne
   }
 
   fun removeReactChild(child: View) {
+    releaseRefreshForeground()
     val index = logicalChildren.indexOf(child)
     if (index < 0) return
     logicalChildren.removeAt(index)
@@ -326,6 +344,7 @@ class CollapsiblePagerHost(context: Context) : NestedScrollableHost(context), Ne
           findExplicitNativeScrollerInView(child) ?: findVerticalScrollableView(child)) {
           is RecyclerView -> restoreRecyclerInsets(scrollable)
           is ScrollView -> restoreNativeScrollerInsets(scrollable)
+          is NativeScrollerViewport -> restoreOwnedScrollerInsets(scrollable)
         }
         adapter.removePage(child)
         log("page-detach slot=${index - PAGE_SLOT_OFFSET} nativePages=${adapter.itemCount}")
@@ -334,6 +353,7 @@ class CollapsiblePagerHost(context: Context) : NestedScrollableHost(context), Ne
   }
 
   fun removeAllReactChildren() {
+    releaseRefreshForeground()
     detachPrimaryScrollObserver()
     for (recycler in originalRecyclerPadding.keys.toList()) {
       restoreRecyclerInsets(recycler)
@@ -341,6 +361,7 @@ class CollapsiblePagerHost(context: Context) : NestedScrollableHost(context), Ne
     for (scroller in originalScrollerPadding.keys.toList()) {
       restoreNativeScrollerInsets(scroller)
     }
+    for (scroller in ownedScrollerKeys.keys.toList()) restoreOwnedScrollerInsets(scroller)
     headerView?.let { view -> super.removeView(view) }
     stickyHeaderView?.let { view -> super.removeView(view) }
     headerView = null
@@ -356,8 +377,10 @@ class CollapsiblePagerHost(context: Context) : NestedScrollableHost(context), Ne
   fun reactChildAt(index: Int) = logicalChildren[index]
 
   fun selectPage(position: Int) {
+    pendingRefreshPull = null
     if (adapter.itemCount == 0) return
     detachPrimaryScrollObserver()
+    releaseRefreshForeground()
     selectedPage = position.coerceIn(0, adapter.itemCount - 1)
     val savedOffset = pageOffsets[currentPageKey()]
       ?: primaryScrollableForPage(selectedPage)?.let(::verticalScrollOffset)
@@ -391,7 +414,7 @@ class CollapsiblePagerHost(context: Context) : NestedScrollableHost(context), Ne
   fun attachedPageCount(): Int = (pager.getChildAt(0) as? RecyclerView)?.childCount ?: 0
 
   fun observedScrollableCount(): Int =
-    originalRecyclerPadding.size + originalScrollerPadding.size
+    originalRecyclerPadding.size + originalScrollerPadding.size + ownedScrollerKeys.size
 
   private fun layoutPagerIfRequested() {
     val recycler = pager.getChildAt(0) as? RecyclerView ?: return
@@ -488,6 +511,7 @@ class CollapsiblePagerHost(context: Context) : NestedScrollableHost(context), Ne
 
   private fun maximumHeaderOffset(): Int {
     val scrollable = observedRecyclerView
+      ?: observedOwnedScroller
       ?: observedNativeScroller
       ?: primaryScrollableForPage(selectedPage)
       ?: return headerHeightPx
@@ -509,7 +533,7 @@ class CollapsiblePagerHost(context: Context) : NestedScrollableHost(context), Ne
     applyHeaderOffset()
   }
 
-  private fun publishConsumedOffset(recycler: RecyclerView, remove: Boolean = false) {
+  private fun publishConsumedOffset(recycler: View, remove: Boolean = false) {
     val key = R.id.onekey_native_scroll_coordinator_consumed_offsets
     val existing = recycler.getTag(key) as? NativeScrollCoordinatorContributions
     val contributions = existing ?: if (remove) return else NativeScrollCoordinatorContributions().also {
@@ -530,6 +554,7 @@ class CollapsiblePagerHost(context: Context) : NestedScrollableHost(context), Ne
     nativeTabBarView.translationY = -offset
     nativeSubHeaderView.translationY = -offset
     observedRecyclerView?.let { publishConsumedOffset(it) }
+    observedOwnedScroller?.let { publishConsumedOffset(it) }
   }
 
   private fun pageKey(index: Int): String = pageKeys.getOrNull(index) ?: "page-$index"
@@ -556,6 +581,7 @@ class CollapsiblePagerHost(context: Context) : NestedScrollableHost(context), Ne
   }
 
   private fun findExplicitNativeScrollerInView(view: View): View? {
+    if (view is NativeScrollerView) return view.viewport
     if (view !== this && view is CollapsiblePagerHost) {
       return view.currentPrimaryScrollableForParent()
     }
@@ -572,6 +598,7 @@ class CollapsiblePagerHost(context: Context) : NestedScrollableHost(context), Ne
   }
 
   private fun findVerticalScrollableView(view: View): View? {
+    if (view is NativeScrollerView) return view.viewport
     if (view !== this && view is CollapsiblePagerHost) {
       return view.currentPrimaryScrollableForParent()
     }
@@ -600,6 +627,7 @@ class CollapsiblePagerHost(context: Context) : NestedScrollableHost(context), Ne
   private fun verticalScrollOffset(view: View): Int = when (view) {
     is RecyclerView -> view.computeVerticalScrollOffset()
     is ScrollView -> view.scrollY
+    is NativeScrollerViewport -> view.scrollY
     else -> 0
   }
 
@@ -610,13 +638,15 @@ class CollapsiblePagerHost(context: Context) : NestedScrollableHost(context), Ne
       when (val scrollable = primaryScrollableForPage(index)) {
         is RecyclerView -> applyRecyclerInsets(scrollable, index)
         is ScrollView -> applyNativeScrollerInsets(scrollable, index)
+        is NativeScrollerViewport -> applyOwnedScrollerInsets(scrollable, index)
       }
     }
+    updateRefreshForeground()
   }
 
   private fun attachPrimaryScrollObserver() {
     if (selectedPage !in 0 until adapter.itemCount) return
-    val previous = observedRecyclerView ?: observedNativeScroller
+    val previous = observedRecyclerView ?: observedOwnedScroller ?: observedNativeScroller
     if (previous != null && !isDescendant(previous, adapter.pageAt(selectedPage))) {
       detachPrimaryScrollObserver()
       // A replacement scroller starts at the beginning while retaining header collapse.
@@ -625,6 +655,7 @@ class CollapsiblePagerHost(context: Context) : NestedScrollableHost(context), Ne
     when (val scrollable = primaryScrollableForPage(selectedPage)) {
       is RecyclerView -> attachRecyclerObserver(scrollable)
       is ScrollView -> attachNativeScrollerObserver(scrollable)
+      is NativeScrollerViewport -> attachOwnedScrollerObserver(scrollable)
     }
   }
 
@@ -718,10 +749,63 @@ class CollapsiblePagerHost(context: Context) : NestedScrollableHost(context), Ne
   }
 
   private fun detachPrimaryScrollObserver() {
+    detachOwnedScrollerObserver()
     detachRecyclerObserver()
     detachNativeScrollerObserver()
   }
 
+  private fun applyOwnedScrollerInsets(scroller: NativeScrollerViewport, pageIndex: Int) {
+    scroller.host.setPagerInset(this, headerHeightPx + stickyHeaderHeightPx)
+    publishConsumedOffset(scroller)
+    val key = pageKey(pageIndex)
+    if (ownedScrollerKeys[scroller] == key) return
+    ownedScrollerKeys[scroller] = key
+    postForCurrentAttachment {
+      if (ownedScrollerKeys[scroller] == key && scroller.isAttachedToWindow) {
+        scroller.scrollTo(0, pageOffsets[key] ?: 0)
+      }
+    }
+  }
+
+  private fun restoreOwnedScrollerInsets(scroller: NativeScrollerViewport) {
+    scroller.stopMotion()
+    ownedScrollerKeys.remove(scroller)
+    publishConsumedOffset(scroller, remove = true)
+    scroller.host.setPagerInset(this, null)
+  }
+
+  private fun attachOwnedScrollerObserver(scroller: NativeScrollerViewport) {
+    if (observedOwnedScroller === scroller && observedOwnedScrollerKey == currentPageKey()) {
+      applyOwnedScrollerInsets(scroller, selectedPage)
+      return
+    }
+    detachPrimaryScrollObserver()
+    observedOwnedScroller = scroller
+    observedOwnedScrollerKey = currentPageKey()
+    val key = currentPageKey()
+    applyOwnedScrollerInsets(scroller, selectedPage)
+    val listener = ViewTreeObserver.OnScrollChangedListener {
+      val contentOffset = scroller.scrollY
+      pageOffsets[key] = contentOffset
+      if (contentOffset > 0 && headerOffsetPx < headerHeightPx) setHeaderOffset(headerHeightPx)
+    }
+    observedOwnedScrollerListener = listener
+    scroller.viewTreeObserver.addOnScrollChangedListener(listener)
+  }
+
+  private fun detachOwnedScrollerObserver() {
+    val scroller = observedOwnedScroller ?: return
+    scroller.stopMotion()
+    publishConsumedOffset(scroller, remove = true)
+    observedOwnedScrollerKey?.let { pageOffsets[it] = scroller.scrollY }
+    observedOwnedScrollerListener?.let {
+      if (scroller.viewTreeObserver.isAlive) scroller.viewTreeObserver.removeOnScrollChangedListener(it)
+    }
+    observedOwnedScroller = null
+    observedOwnedScrollerKey = null
+    observedOwnedScrollerListener = null
+  }
+
   private fun applyRecyclerInsets(recycler: RecyclerView, pageIndex: Int) {
     val original = originalRecyclerPadding.getOrPut(recycler) {
       RecyclerPadding(
@@ -910,6 +994,136 @@ class CollapsiblePagerHost(context: Context) : NestedScrollableHost(context), Ne
     scroller.setPadding(original.left, original.top, original.right, original.bottom)
   }
 
+  private fun refreshLayoutFor(scrollable: View): SwipeRefreshLayout? {
+    if (scrollable !is ScrollView && scrollable !is RecyclerView && scrollable !is NativeScrollerViewport) return null
+    var ancestor = scrollable.parent
+    while (ancestor != null && ancestor !is SwipeRefreshLayout) ancestor = ancestor.parent
+    return ancestor as? SwipeRefreshLayout
+  }
+
+  private fun refreshIndicatorFor(refresh: SwipeRefreshLayout): ImageView? {
+    for (index in 0 until refresh.childCount) {
+      val child = refresh.getChildAt(index)
+      if (child is ImageView && child.drawable is CircularProgressDrawable) return child
+    }
+    return null
+  }
+
+  private fun refreshForegroundOwner(scrollable: View): CollapsiblePagerHost? {
+    var owner: CollapsiblePagerHost? = null
+    var ancestor = scrollable.parent
+    while (ancestor != null) {
+      if (ancestor is CollapsiblePagerHost && ancestor.nativeSmoothHeaderScrollEnabled &&
+        ancestor.isAttachedToWindow && ancestor.isShown &&
+        ancestor.primaryScrollableForPage(ancestor.selectedPage) === scrollable) {
+        owner = ancestor
+      }
+      ancestor = ancestor.parent
+    }
+    return owner
+  }
+
+  private fun updateRefreshForeground() {
+    val scrollable = primaryScrollableForPage(selectedPage)
+    val refresh = scrollable?.takeIf { refreshForegroundOwner(it) === this }?.let(::refreshLayoutFor)
+    val indicator = refresh?.let(::refreshIndicatorFor)
+    if (foregroundRefreshIndicator?.get() !== indicator) releaseRefreshForeground()
+    if (indicator != null) {
+      if (foregroundRefreshIndicator?.get() !== indicator) {
+        foregroundRefreshIndicator = WeakReference(indicator)
+      }
+      val state = refreshIndicatorAlphas.getOrPut(indicator) {
+        NativeRefreshForegroundAlpha(indicator.alpha)
+      }
+      val alpha = state.update(indicator.alpha, this, acquire = true)
+      if (indicator.alpha != alpha) indicator.alpha = alpha
+    }
+    val visible = indicator?.isShown == true &&
+      (refreshIndicatorAlphas[indicator]?.drawingAlpha ?: 0f) > 0f
+    // The foreground lies outside the original child's invalidation rectangle.
+    // Repaint once on disappearance as well as throughout the native animation.
+    if (visible || refreshForegroundWasVisible) postInvalidateOnAnimation()
+    refreshForegroundWasVisible = visible
+  }
+
+  private fun releaseRefreshForeground() {
+    val indicator = foregroundRefreshIndicator?.get()
+    foregroundRefreshIndicator = null
+    if (indicator != null) {
+      refreshIndicatorAlphas[indicator]?.let { state ->
+        indicator.alpha = state.update(indicator.alpha, this, acquire = false)
+        if (state.isEmpty) refreshIndicatorAlphas.remove(indicator)
+      }
+    }
+    if (indicator != null || refreshForegroundWasVisible) invalidate()
+    refreshForegroundWasVisible = false
+  }
+
+  private fun refreshMatrixInHost(refresh: View): Boolean {
+    refreshForegroundMatrix.reset()
+    refreshForegroundAncestorAlpha = 1f
+    refreshForegroundAncestors.clear()
+    try {
+      var current: View? = refresh
+      while (current != null && current !== this) {
+        refreshForegroundAncestors.add(current)
+        current = current.parent as? View
+      }
+      if (current !== this) return false
+      for (index in refreshForegroundAncestors.lastIndex downTo 0) {
+        val child = refreshForegroundAncestors[index]
+        val parent = child.parent as? View ?: return false
+        refreshForegroundMatrix.preTranslate(
+          (child.left - parent.scrollX).toFloat(), (child.top - parent.scrollY).toFloat(),
+        )
+        refreshForegroundMatrix.preConcat(child.matrix)
+        refreshForegroundAncestorAlpha *= child.alpha
+      }
+      return true
+    } finally {
+      refreshForegroundAncestors.clear()
+    }
+  }
+
+  override fun dispatchDraw(canvas: Canvas) {
+    // The original parent advances native refresh animations and their listeners.
+    super.dispatchDraw(canvas)
+    val indicator = foregroundRefreshIndicator?.get() ?: return
+    val scrollable = primaryScrollableForPage(selectedPage) ?: return
+    if (refreshForegroundOwner(scrollable) !== this) return
+    val refresh = refreshLayoutFor(scrollable) ?: return
+    if (refreshIndicatorFor(refresh) !== indicator || !indicator.isShown ||
+      indicator.width <= 0 || indicator.height <= 0 || !refreshMatrixInHost(refresh)) return
+    val alpha = (refreshIndicatorAlphas[indicator]?.drawingAlpha ?: return) *
+      refreshForegroundAncestorAlpha
+    if (alpha <= 0f) return
+    refreshForegroundOrigin[0] = 0f
+    refreshForegroundOrigin[1] = 0f
+    refreshForegroundMatrix.mapPoints(refreshForegroundOrigin)
+    val appliedInset = (refresh.getTag(R.id.onekey_native_scroll_coordinator_refresh_inset) as? Number)
+      ?.toFloat() ?: 0f
+    val save = canvas.save()
+    try {
+      // Pin the refresh container's origin to this Host top while retaining its
+      // horizontal page position, native scale/pivot, and caller translation.
+      canvas.translate(0f, -refreshForegroundOrigin[1])
+      canvas.concat(refreshForegroundMatrix)
+      canvas.translate(indicator.left.toFloat(), nativeRefreshForegroundTop(indicator.top, appliedInset))
+      canvas.concat(indicator.matrix)
+      if (alpha < 1f) {
+        canvas.saveLayerAlpha(
+          0f, 0f, indicator.width.toFloat(), indicator.height.toFloat(),
+          (alpha * 255f).roundToInt().coerceIn(0, 255),
+        )
+      }
+      // Direct draw deliberately bypasses the alpha used to hide the original
+      // RenderNode. Do not advance Animation.getTransformation a second time.
+      indicator.draw(canvas)
+    } finally {
+      canvas.restoreToCount(save)
+    }
+  }
+
   private fun headerRegionAt(y: Float): String? {
     val headerBottom = headerHeightPx - headerOffsetPx
     val stickyBottom = headerHeightPx + stickyHeaderHeightPx - headerOffsetPx
@@ -1134,10 +1348,12 @@ class CollapsiblePagerHost(context: Context) : NestedScrollableHost(context), Ne
     axes and ViewCompat.SCROLL_AXIS_VERTICAL != 0 && isCurrentPageTarget(target)
 
   override fun onNestedScrollAccepted(child: View, target: View, axes: Int, type: Int) {
+    if (type == ViewCompat.TYPE_TOUCH) pendingRefreshPull = null
     nestedScrollingParentHelper.onNestedScrollAccepted(child, target, axes, type)
   }
 
   override fun onStopNestedScroll(target: View, type: Int) {
+    if (pendingRefreshPull?.get() === target) pendingRefreshPull = null
     nestedScrollingParentHelper.onStopNestedScroll(target, type)
     onHeaderOffsetChanged?.invoke()
   }
@@ -1152,10 +1368,18 @@ class CollapsiblePagerHost(context: Context) : NestedScrollableHost(context), Ne
       val used = min(dy, maximumOffset - headerOffsetPx)
       setHeaderOffset(headerOffsetPx + used)
       consumed[1] += used
-    } else if (dy < 0 && headerOffsetPx > 0 && !target.canScrollVertically(-1)) {
-      val used = max(dy, -headerOffsetPx)
-      setHeaderOffset(headerOffsetPx + used)
-      consumed[1] += used
+    } else if (dy < 0 && headerOffsetPx > 0) {
+      // Refresh wrappers forward nested scrolls but do not scroll themselves.
+      val canScrollUp = if (target is SwipeRefreshLayout) {
+        target.canChildScrollUp()
+      } else {
+        target.canScrollVertically(-1)
+      }
+      if (!canScrollUp) {
+        val used = max(dy, -headerOffsetPx)
+        setHeaderOffset(headerOffsetPx + used)
+        consumed[1] += used
+      }
     }
   }
 
@@ -1168,10 +1392,14 @@ class CollapsiblePagerHost(context: Context) : NestedScrollableHost(context), Ne
     type: Int,
     consumed: IntArray,
   ) {
-    if (!isCurrentPageTarget(target) || dyUnconsumed >= 0 || headerOffsetPx <= 0) return
+    if (!isCurrentPageTarget(target) || dyUnconsumed >= 0) return
     val used = max(dyUnconsumed, -headerOffsetPx)
     setHeaderOffset(headerOffsetPx + used)
     consumed[1] += used
+    if (type == ViewCompat.TYPE_TOUCH && dyUnconsumed < used &&
+      target is SwipeRefreshLayout && target.isEnabled) {
+      pendingRefreshPull = WeakReference(target)
+    }
   }
 
   override fun onNestedScroll(
@@ -1193,6 +1421,20 @@ class CollapsiblePagerHost(context: Context) : NestedScrollableHost(context), Ne
     )
   }
 
+  override fun onNestedPreFling(target: View, velocityX: Float, velocityY: Float): Boolean {
+    val refresh = pendingRefreshPull?.get()
+    val scrollable = primaryScrollableForPage(selectedPage)
+    if (nativeSmoothHeaderScrollEnabled && refresh != null && refresh === target && isCurrentPageTarget(target) &&
+      headerOffsetPx == 0 && scrollable != null && !scrollable.canScrollVertically(-1) &&
+      refresh.isEnabled && !refresh.isRefreshing &&
+      refreshIndicatorFor(refresh)?.visibility == View.VISIBLE) {
+      // A small release reversal must settle the current refresh pull, not fling
+      // content upward and make its first positive offset collapse the header.
+      return true
+    }
+    return super.onNestedPreFling(target, velocityX, velocityY)
+  }
+
   override fun getNestedScrollAxes() = nestedScrollingParentHelper.nestedScrollAxes
 
   override fun onAttachedToWindow() {
@@ -1208,6 +1450,8 @@ class CollapsiblePagerHost(context: Context) : NestedScrollableHost(context), Ne
   }
 
   override fun onDetachedFromWindow() {
+    pendingRefreshPull = null
+    releaseRefreshForeground()
     attachmentGeneration += 1
     headerDownEvent?.recycle()
     headerDownEvent = null
@@ -1224,6 +1468,7 @@ class CollapsiblePagerHost(context: Context) : NestedScrollableHost(context), Ne
     for (scroller in originalScrollerPadding.keys.toList()) {
       restoreNativeScrollerInsets(scroller)
     }
+    for (scroller in ownedScrollerKeys.keys.toList()) restoreOwnedScrollerInsets(scroller)
     log(
       "host-detach generation=$attachmentGeneration inner=$selectedPage " +
         "outer=${outerPagerIndex()} nativePages=${adapter.itemCount}",
@@ -1232,6 +1477,7 @@ class CollapsiblePagerHost(context: Context) : NestedScrollableHost(context), Ne
   }
 
   companion object {
+    private val refreshIndicatorAlphas = WeakHashMap<ImageView, NativeRefreshForegroundAlpha>()
     const val NATIVE_SCROLLER_ID_PREFIX = "rnc-collapsible-pager-native-scroller:"
     const val PAGE_SLOT_OFFSET = 2
   }

package/android/src/main/java/com/reactnativepagerview/NativeScrollerScrollAwayInsets.kt

@@ -1,5 +1,7 @@
 package com.reactnativepagerview
 
+import java.util.WeakHashMap
+
 // Replace only this pager's contribution; another native owner may share the scroller.
 internal fun nativeScrollerScrollAwayTop(currentTop: Int, previousInset: Int, nextInset: Int): Int =
   (currentTop - previousInset).coerceAtLeast(0) + nextInset
@@ -15,3 +17,25 @@ internal fun nativeScrollerPaddingWasResetByScrollAway(
   scrollAwayBottom: Int,
 ): Boolean = appliedInset > 0 && left == 0 && top == 0 && right == 0 &&
   bottom == scrollAwayTop + scrollAwayBottom
+
+// The refresh controller publishes its actual combined ancestor compensation.
+internal fun nativeRefreshForegroundTop(indicatorTop: Int, appliedInset: Float): Float =
+  indicatorTop - appliedInset
+
+internal class NativeRefreshForegroundAlpha(initialAlpha: Float) {
+  private val owners = WeakHashMap<Any, Unit>()
+  private var baseline = initialAlpha
+  private var lastApplied = initialAlpha
+
+  val isEmpty: Boolean
+    get() = owners.isEmpty()
+  val drawingAlpha: Float
+    get() = baseline
+
+  fun update(currentAlpha: Float, owner: Any, acquire: Boolean): Float {
+    if (currentAlpha != lastApplied) baseline = currentAlpha
+    if (acquire) owners[owner] = Unit else owners.remove(owner)
+    lastApplied = if (owners.isEmpty()) baseline else 0f
+    return lastApplied
+  }
+}