@onekeyfe/react-native-pager-view 3.0.173 → 3.0.175

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

@@ -43,6 +43,7 @@ class CollapsiblePagerViewManager : ViewGroupManager<CollapsiblePagerHost>(),
     )
     host.pager.registerOnPageChangeCallback(object : ViewPager2.OnPageChangeCallback() {
       override fun onPageScrolled(position: Int, offset: Float, offsetPixels: Int) {
+        host.onPagerScrolled(position, offset)
         dispatch(reactContext, host, PageScrollEvent(host.id, position, offset))
       }
 
@@ -55,6 +56,7 @@ class CollapsiblePagerViewManager : ViewGroupManager<CollapsiblePagerHost>(),
       }
 
       override fun onPageScrollStateChanged(state: Int) {
+        host.onPagerScrollStateChanged(state)
         val value = when (state) {
           ViewPager2.SCROLL_STATE_IDLE -> "idle"
           ViewPager2.SCROLL_STATE_DRAGGING -> "dragging"
@@ -92,6 +94,9 @@ class CollapsiblePagerViewManager : ViewGroupManager<CollapsiblePagerHost>(),
         ),
       )
     }
+    host.onHeaderSettledStateChanged = {
+      dispatchDiagnostics(reactContext, host, "header-settled-state")
+    }
     host.onHeaderOffsetChanged = {
       if (!host.pager.isFakeDragging && host.pager.scrollState == ViewPager2.SCROLL_STATE_IDLE) {
         dispatchDiagnostics(reactContext, host, "vertical-idle")
@@ -125,6 +130,8 @@ class CollapsiblePagerViewManager : ViewGroupManager<CollapsiblePagerHost>(),
         host.observedScrollableCount(),
         host.retainedPages,
         reason,
+        host.headerStatePageKey(),
+        host.headerSettledAtTop,
       ),
     )
   }
@@ -322,15 +329,25 @@ class CollapsiblePagerViewManager : ViewGroupManager<CollapsiblePagerHost>(),
     delegate.receiveCommand(root, commandId, args)
   }
 
+  override fun scrollToTop(view: CollapsiblePagerHost?, target: Int, animated: Boolean) {
+    view?.scrollToTop(target, animated)
+  }
+
   override fun setPage(view: CollapsiblePagerHost?, selectedPage: Int) {
     if (view != null && selectedPage in 0 until view.adapter.itemCount) {
+      view.beginPageTransition(selectedPage)
       view.pager.setCurrentItem(selectedPage, true)
+      if (view.pager.scrollState == ViewPager2.SCROLL_STATE_IDLE) {
+        view.onPagerScrollStateChanged(ViewPager2.SCROLL_STATE_IDLE)
+      }
     }
   }
 
   override fun setPageWithoutAnimation(view: CollapsiblePagerHost?, selectedPage: Int) {
     if (view != null && selectedPage in 0 until view.adapter.itemCount) {
+      view.beginPageTransition(selectedPage)
       view.pager.setCurrentItem(selectedPage, false)
+      view.onPagerScrollStateChanged(ViewPager2.SCROLL_STATE_IDLE)
     }
   }
 

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

@@ -255,6 +255,8 @@ class NativeScrollerView(context: Context) : FrameLayout(context) {
 
   internal fun cancelPendingScrollRestore() = pendingRestore.cancel()
 
+  internal fun hasPendingScrollRestore(): Boolean = pendingRestore.target != null
+
   internal fun setRefreshOffset(value: Int) {
     refreshOffset = value
     applyRefreshOffset()
@@ -293,11 +295,22 @@ class NativeScrollerView(context: Context) : FrameLayout(context) {
   }
 
   internal fun scrollToPosition(x: Int, y: Int, animated: Boolean) {
+    notifyScrollCommand(0, y <= 0)
     viewport.stopMotion()
     pendingRestore.cancel()
+    notifyScrollCommand(1, y <= 0)
     if (animated) viewport.scrollToAnimated(y)
     else viewport.scrollTo(0, y.coerceAtLeast(0))
     emitScroll(force = true)
+    if (!viewport.isReadingMotionActive()) notifyScrollCommand(2, y <= 0)
+  }
+
+  internal fun notifyScrollCommand(phase: Int, explicitTop: Boolean = false) {
+    var owner = parent
+    while (owner is View) {
+      if (owner is CollapsiblePagerHost) owner.acceptObservedScrollCommand(viewport, explicitTop, phase)
+      owner = owner.parent
+    }
   }
 
   internal fun scrollToEnd(animated: Boolean) = scrollToPosition(
@@ -587,6 +600,8 @@ internal class NativeScrollerViewport(context: Context, internal val host: Nativ
     super.fling(velocityY)
   }
 
+  internal fun isReadingMotionActive() = dragging || momentum
+
   internal fun scrollToAnimated(y: Int) {
     val child = getChildAt(0) ?: return
     val margins = child.layoutParams as FrameLayout.LayoutParams
@@ -637,6 +652,7 @@ internal class NativeScrollerViewport(context: Context, internal val host: Nativ
   private fun finishMomentum() {
     if (!momentum) return
     momentum = false
+    host.notifyScrollCommand(2)
     host.emitScroll(force = true)
     host.emitLifecycle("topMomentumScrollEnd")
   }

package/android/src/main/java/com/reactnativepagerview/event/CollapsibleStateChangedEvent.kt

@@ -14,6 +14,8 @@ class CollapsibleStateChangedEvent(
   private val observedScrollableCount: Int,
   private val retainedPages: String,
   private val reason: String,
+  private val pageKey: String,
+  private val headerSettledAtTop: Boolean,
 ) : Event<CollapsibleStateChangedEvent>(viewTag) {
   override fun getEventName() = EVENT_NAME
 
@@ -31,6 +33,8 @@ class CollapsibleStateChangedEvent(
     putInt("observedScrollableCount", observedScrollableCount)
     putString("retainedPages", retainedPages)
     putString("reason", reason)
+    putString("pageKey", pageKey)
+    putBoolean("headerSettledAtTop", headerSettledAtTop)
   }
 
   companion object {

package/android/src/main/res/values/native_scroll_coordinator_ids.xml

@@ -2,4 +2,6 @@
     <item name="onekey_native_scroll_coordinator_consumed_offsets" type="id" />
     <item name="onekey_native_scroll_coordinator_offset_listener" type="id" />
     <item name="onekey_native_scroll_coordinator_refresh_inset" type="id" />
+    <item name="onekey_native_scroll_coordinator_command_listener" type="id" />
+    <item name="onekey_native_scroll_coordinator_command_cancel_listener" type="id" />
 </resources>

package/android/src/test/java/com/reactnativepagerview/NativeScrollerPendingRestoreTest.kt

@@ -27,5 +27,16 @@ fun main() {
   restore.cancel()
   check(restore.target == null)
   check(restore.anchor(120) == 120)
+  // Cancellation clears the old target without requiring the reached offset to change.
+  restore.request(target = 640, reached = 120)
+  check(restore.anchor(120) == 640)
+  restore.cancel()
+  check(restore.target == null)
+  check(restore.anchor(120) == 120)
+  // A fresh request owns its target after cancellation.
+  restore.request(target = 320, reached = 120)
+  check(restore.target == 320)
+  restore.settle(reached = 320)
+  check(restore.target == null)
   println("Native scroller pending restore: clamp retry, partial growth, settle and cancel passed")
 }

package/docs/SPEC.md

@@ -3,6 +3,60 @@
 Existing PagerView and CollapsiblePagerView APIs are documented in README.md.
 The sections below define native coordination boundaries without new React props.
 
+## Smooth shared-header and per-page body memory
+
+With nativeSmoothHeaderScrollEnabled, the header collapse C is shared across all
+pages and the available collapse distance is D. Each page separately remembers
+its sticky-body reading distance B (unvisited pages default to zero). Outside
+pull overscroll, the rendered whole-page distance is Q = C + effectiveB.
+B denotes the saved reading position. For an owned vertical LinearLayoutManager
+RecyclerView, restoration uses the first visible adapter position and its
+decorated top relative to padding; scrollbar offset estimates MUST NOT decide
+completion of that anchor restoration.
+When C = D, selection restores the destination's saved B. When C < D, effectiveB
+is zero while the previous saved B remains suspended. Horizontal selection by
+tap, swipe or an existing programmatic command MUST preserve C throughout.
+
+Alignment, prefetch, replacement, inset changes and pending restoration MUST NOT
+commit new B. Actual consumed vertical scrolling takes over the visible body
+position; reaching full collapse during that gesture MUST NOT resurrect the old
+suspended B. Selecting a page anew at full collapse may restore its saved B.
+Valid explicit native scroll commands, including same-offset commands, cancel
+only their current owned restoration and take over body memory. Invalid commands
+and stale owners do not affect another page. Existing command coordinate systems
+are unchanged; in particular NativeScroller iOS uses physical offsets whereas
+NativeList offset commands exclude the content-start inset.
+
+Transitions use immutable destination memory and the source's actual displayed
+position. Cancellation restores that source presentation, even when a cached B
+was temporarily unreachable. Loading or zero geometry preserves pending intent;
+a genuinely short page clamps its display without silently replacing saved B.
+Cancelling a horizontal gesture invalidates queued callbacks, but preserves
+unreachable reading intent until real vertical consumption or a valid command
+takes over; later usable geometry may resume it.
+Late callbacks cannot revive cancelled restoration or erase a newer request.
+Observers and commands must match page key, view identity and generation.
+Removed or recycled owners cannot apply callbacks to another page; recycling
+resets owned memory.
+Legacy mode and pagers without a collapsible header retain their existing
+behavior. Vertical scrolling, refresh, snapping and repeated-current-tab behavior
+are unchanged. This state belongs to native UI instances, with no new React prop
+or per-frame JavaScript synchronization.
+
+## Current-page top commands
+
+`scrollToPageTop(options?: Readonly<{ animated?: boolean }>)` restores the current
+page to C = 0 and B = 0. `scrollToStickyTop(options?: Readonly<{ animated?: boolean }>)`
+restores it to C = D and B = 0, including from a partially expanded header.
+Animation defaults to true. Neither command clears another page's memory.
+Both commands require a stable, attached current owner; horizontal transitions
+or missing owners reject them rather than queueing a command for another page.
+Acceptance cancels older owned list commands and pending restoration before the
+new target is established. Same-target commands also take over old reading
+intent. Real vertical consumption, a newer valid command, or owner detachment
+releases the target. Existing NativeList and NativeScroller public coordinates
+are unchanged. The same page-top/sticky-top destinations are available without smooth-header mode.
+
 ## Independent NativeScroller migration
 
 Status: implemented in source. Both native builds pass. Android focused emulator
@@ -454,7 +508,8 @@ When restoring a retained page's cached vertical offset, the pager limits only
 the upper bound to the current content height, viewport and applied insets. A
 cache captured before rows were removed MUST NOT restore an offset below the new
 content bottom, including when removal occurs during a page transition. Valid
-deep offsets and the existing lower-bound/header alignment rules are unchanged.
+deep offsets and pull-overscroll behavior are preserved; smooth-header selection
+follows the shared-header and per-page body-memory contract above.
 This check runs only on explicit restoration, not on scroll frames; UIKit pull
 overscroll and refresh settlement retain their existing ownership. An unmeasured
 zero-height viewport defers this upper-bound limit to a later restoration.
@@ -662,3 +717,12 @@ cases additionally verified recorded refresh, header, restoration and gesture
 paths; they do not establish every possible sequence or runtime acceptance of a
 newly installed module release. Physical-device feel and semantic accessibility
 activation remain unverified.
+
+
+### Native Header stability snapshot
+
+`onCollapsibleStateChanged` retains its existing diagnostic fields and reasons and adds native-only `pageKey: string` and `headerSettledAtTop: boolean`. The key is the actual mounted React child key, not an application tab identifier. Unattached, unknown, replaced or transitioning owners MUST report false. A mounted current owner emits an initial identity snapshot without requiring a first user scroll.
+
+The Header is settled only when C is at its expanded top, the current attached view/key/index/generation still matches, and there is no actual drag, deceleration, scrolling command or horizontal transition. Offset/inset/content/header geometry MUST remain stable for 150ms before true is emitted. Motion or geometry changes revoke true promptly. Deferred reading memory alone MUST NOT be treated as active motion. Pull-to-refresh may settle at a normalized negative offset after drag, bounce and inset geometry stop; network refreshing alone is not a motion gate. Checks stop for collapsed, detached and recycled owners; delayed callbacks revalidate their captured identity. State changes are deduplicated; identity changes still publish an unknown/false snapshot.
+
+The native Home Spotlight adapter consumes this snapshot in the main UI runtime and keeps unknown states paused. It MUST use the mounted page-key mapping and reject old page/source callbacks. Native snapshots already include the 150ms stabilization delay: consumers MUST NOT add another such delay. Legacy Tabs keep their existing normalized-offset and debounce behavior. Anchor measurement, guide qualification and the existing display delay remain independent gates.