@onekeyfe/react-native-pager-view 6.7.0-1 → 6.7.0-3

package/README.md

@@ -67,6 +67,15 @@ Web scroll child can opt in by exposing a DOM element with
 `data-collapsible-pager-scroll`. CSS scroll timelines drive header/sticky
 movement, so React is not updated on each vertical scroll frame.
 
+On Web, `WebCollapsiblePagerView` is an explicit root export of the existing Web
+pager. It measures Header and sticky content when their heights are omitted.
+`isActive` describes route visibility; the pager preserves a pending scroll
+target across a short or temporarily hidden page and retries when real content
+geometry becomes ready. `useWebCollapsiblePagerPage()` exposes the selected
+page's scroll owner, visible metrics, content registration and pending target
+to descendants. These Web-only APIs require a DOM when mounted. Native callers
+continue to use `CollapsiblePagerView`.
+
 On iOS and Android, `nativeTabBar` renders the tab bar natively and
 `onNativeTabPress` reports presses. By default, adjacent tab presses animate and
 non-adjacent presses jump directly to the target without passing intermediate

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

@@ -207,8 +207,8 @@ class CollapsiblePagerViewManager : ViewGroupManager<CollapsiblePagerHost>(),
   }
 
   // The scroll-edge effect and external overlay are UIKit-only.
-  @ReactProp(name = "topScrollEdgeHard", defaultBoolean = false)
-  override fun setTopScrollEdgeHard(view: CollapsiblePagerHost?, value: Boolean) = Unit
+  @ReactProp(name = "topScrollEdgeEffect")
+  override fun setTopScrollEdgeEffect(view: CollapsiblePagerHost?, value: String?) = Unit
   @ReactProp(name = "topOverlayColorScheme")
   override fun setTopOverlayColorScheme(view: CollapsiblePagerHost?, value: String?) = Unit
   @ReactProp(name = "topOverlayHeight", defaultDouble = 0.0)

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

@@ -49,8 +49,8 @@ class NativeScrollerViewManager : ViewGroupManager<NativeScrollerView>(),
   override fun setContentWidth(view: NativeScrollerView, value: Double) = view.setContentSize(width = view.dip(value))
   @ReactProp(name = "contentHeight")
   override fun setContentHeight(view: NativeScrollerView, value: Double) = view.setContentSize(height = view.dip(value))
-  @ReactProp(name = "topScrollEdgeHard", defaultBoolean = false)
-  override fun setTopScrollEdgeHard(view: NativeScrollerView, value: Boolean) = Unit
+  @ReactProp(name = "topScrollEdgeEffect")
+  override fun setTopScrollEdgeEffect(view: NativeScrollerView, value: String?) = Unit
   @ReactProp(name = "topOverlayHeight", defaultDouble = 0.0)
   override fun setTopOverlayHeight(view: NativeScrollerView, value: Double) = Unit
   @ReactProp(name = "scrollEnabled", defaultBoolean = true)

package/docs/SPEC.md

@@ -7,13 +7,17 @@ scroll-edge props.
 ## iOS 26 top scroll edge overlay
 
 `CollapsiblePagerView` and standalone `NativeScroller` accept the optional
-`topScrollEdgeEffect="hard"` with a fixed `topOverlay` React child. Both are
+`topScrollEdgeEffect={ScrollEdgeEffect.Hard}` or `ScrollEdgeEffect.Soft` with a
+fixed `topOverlay` React child. `ScrollEdgeEffect` is an exported string enum
+(`Hard = "hard"`, `Soft = "soft"`); the corresponding string literals remain
+valid prop values. Both the style and overlay are
 disabled by default. On iOS 26 or newer, a local overlay remains fixed at the
 top of the viewport while the owned vertical `UIScrollView` can draw behind it.
 The component measures the overlay's Fabric layout height and owns the
 corresponding top content inset. It binds UIKit's
 `UIScrollEdgeElementContainerInteraction` to that exact scroll view and selects
-the hard top edge style. A pager owns the effect and inset for its current page;
+the requested top edge style. Hard has UIKit's dividing line; Soft has its
+gradual blurred transition. A pager owns the effect and inset for its current page;
 its nested NativeList or NativeScroller must not opt into another top overlay.
 Invisible, noninteractive native labels let UIKit recognize the React-drawn
 overlay and sticky header as scroll-edge elements. The pager does not add an
@@ -28,7 +32,7 @@ The pager weakly observes its geometry in the same window, retaining its own
 noninteractive native proxy for UIKit recognition without reparenting or
 modifying the React header. The measured external header bottom supplies the
 top inset and sticky anchor. A local `topOverlay` takes precedence. The tag
-alone never enables the effect: `topScrollEdgeEffect="hard"` controls the
+alone never enables the effect: either `topScrollEdgeEffect` enum value controls the
 interaction, while valid external geometry can reserve the top inset before
 the effect is enabled. Before the tag and height are ready, the caller keeps
 its existing layout; an unresolved native tag has zero external height. An
@@ -47,7 +51,7 @@ When a smooth shared header reaches the overlay boundary, the existing sticky
 React and native tab views move together into a view pinned to the active
 scroll view. Their identities, scroll-view gesture ancestry and hit targets
 remain intact; the collapsible header stays in the scrolling header host.
-Without a local or external overlay, `topScrollEdgeEffect="hard"` may protect
+Without a local or external overlay, either scroll-edge style may protect
 only the genuinely pinned sticky header; it must not consume a page as a
 synthetic overlay slot or change the collapsible banner distance.
 Changing pages, replacing the active list or recycling returns those views to
@@ -69,6 +73,29 @@ Acceptance requires real iOS 26 scrolling, partial collapse, short/empty page,
 refresh, page transition/cancellation, dynamic tabs and light/dark checks;
 source and build checks alone do not establish visual correctness.
 
+Experimental trial: `CollapsiblePagerView` paints a cover at each owned
+fixed-overlay or pinned-sticky boundary with one physical pixel of the nearest
+opaque ancestor background color (system background if none is available).
+These native layers do not receive touches, change insets, or clip glass shadows.
+They are removed for Soft, disabled/detached effects, and recycling. This is a
+visual workaround using public layer APIs, not a UIKit separator setting; rendered
+light/dark, scrolling, and transition acceptance is pending. Standalone
+NativeScroller and NativeList retain UIKit's unmodified Hard appearance.
+On the iOS 26.5 simulator, a runtime probe confirmed Hard and the cover layers,
+including pinned-header ownership. The original hairline was not reliably
+reproduced with the covers hidden, so separator suppression is not yet verified.
+
+Style selection crosses Fabric as the enum `none | hard | soft`, defaulting to
+`none`, rather than a hard-effect boolean. Switching Hard ↔ Soft on an attached
+owner updates UIKit without replacing the overlay or changing its inset,
+logical scroll offset, or saved original style. Clearing the prop, detaching,
+or recycling releases the interaction and restores that original style.
+This bridge contract requires a matching native rebuild. Soft selection is
+implemented in the public wrappers and native hosts. Focused JS tests cover
+style forwarding, overlay retention and disabling; UIKit tests cover native
+style switching and restoring the previous style. Rendered iOS acceptance must
+be reported separately from type, codegen and build checks.
+
 ## Smooth shared-header and per-page body memory
 
 With nativeSmoothHeaderScrollEnabled, the header collapse C is shared across all
@@ -814,3 +841,49 @@ The native Home Spotlight adapter consumes this snapshot in the main UI runtime
 Removing a page or clearing the page collection MUST cancel the active horizontal transition and its temporary display snapshots before notifying the adapter. Cancellation MUST NOT rewrite the shared Header collapse or surviving pages' saved body reading memory. The previous observed owner MUST be detached without committing an offset under a shifted page key.
 
 An empty adapter MUST reject transition starts and transition completion without coercing an index into an empty range. The selected index uses zero as an empty-state sentinel; nonempty mutations clamp it to the remaining valid range. Readding pages MUST allow a fresh selection and MUST NOT resume a removed transition source. Conformance requires actual Android active-transition → zero-pages → readd/selection regression and remaining-page mutation checks; structural checks and compilation alone do not establish runtime behavior.
+
+
+## Web parent-scroll owner identity
+
+Web Header and sticky overlays use the named scroll timeline only when the
+browser supports every CSS property needed for that linkage. Otherwise, the
+active scroll owner's offset drives the same clamped Header collapse in JS:
+`C = min(max(scrollTop, 0), max(headerHeight, 0))`. The fallback keeps the
+existing page owner, insets, body offset memory, and sticky anchor. It updates
+when scrolling, selecting or restoring a page, replacing an owner, or changing
+Header height, and releases its listener when that owner detaches. An inactive
+page cannot move the visible Header. This is a Web-only compatibility path; no
+native behavior or public prop changes.
+When an overlay forwards a vertical wheel or touch scroll to the active owner,
+the owner receives the same internal user-input notification used by route
+restoration to cancel an obsolete pending offset.
+
+On Web, an explicitly marked NativeScroller is selected before an implicit NativeList viewport. There is one vertical owner per page; callers using parent-owned NativeList pass that same scroll element as webScrollHost.
+
+The existing NativeScroller pagerScrollKey identifies a Web page scroll owner. Changing the key invalidates that page body offset without remounting its React business content. The active owner also resets the shared header collapse and cancels queued old restore/top commands. Inactive owners invalidate their saved body offset without imperative scrolling; selection checks the current identity before restoring. A→B→A identity changes never revive a prior owner offset. Stable keys preserve ordinary page C+B restoration. Current-page top commands continue to affect only the selected page.
+
+Identity notifications and DOM owner listeners are internal implementation details, removed when the pager root or owner is replaced/unmounted. No native behavior or public configuration is added.
+
+### Web overlay input and keyed-page updates
+
+- Header and sticky slots remain overlays: overflow outside the sticky slot may remain visible without adding its portal height to page insets twice.
+- Vertical wheel or touch input over those overlays transfers only to the active page scroll owner when no nested scrollable consumes it. Horizontal controls, editable inputs, and ordinary button/tap behavior retain their own events. Input originating inside the page owner follows native scrolling once.
+- Reordering or removing keyed pages must save the previously configured key and owner, rather than resolving the old selected index against new children. Caller index synchronization preserves keyed body offsets and shared header collapse.
+- For an explicit NativeScroller, Pager chrome insets apply to the existing ScrollView content element, not its viewport. Insets taller than the available window cannot enlarge the scroll viewport. Existing owner/content padding is preserved and restored separately from Pager insets; direct NativeList/page-host fallback retains its prior layout path.
+- The Pager root clips without becoming a programmatically scrollable overflow box. Browser focus and descendant scrollIntoView cannot add a second horizontal page offset outside the selected-page transform.
+
+## Web page geometry and route restoration
+
+Status: Implemented in Web source and focused tests; browser and native runtime acceptance remain separate.
+
+`WebCollapsiblePagerView` is the existing Web `CollapsiblePagerView` class under an explicit root export. Its `isActive` prop defaults to true and represents route visibility, independently of the selected page. The Web-only `useWebCollapsiblePagerPage()` hook returns null outside a Web pager and otherwise exposes `isFocused`, `isRouteActive`, `owner`, `content`, optional `contentHeight`, `width`, `height`, content-relative `scrollTop`, `registerContent`, and read-only `pendingRouteScrollTop`. Native `CollapsiblePagerView`, its bridge, and its props are unchanged. The Web component rejects mounting without a DOM; importing the root or Web module alone must not access DOM globals.
+
+Web callers may supply finite nonnegative `headerHeight` and `stickyHeaderHeight`. When omitted or invalid (negative, NaN, or infinite), the SDK measures the natural inner Header and sticky content with `ResizeObserver`; explicit valid values take precedence, including zero. An initial unmeasured zero is not ready for route restoration; a measured empty chrome element may legitimately have zero height. Measurement must not use the constrained slot height as its own input. Height changes update the owned insets before route restoration. Existing explicit-height callers retain their layout path.
+
+Each page has one SDK-discovered vertical owner: explicit `NativeScroller`, then implicit NativeList viewport, then page host. Registration accepts a connected content element and optional finite nonnegative explicit height; invalid height metadata is ignored. It does not change DOM layout or make a pending target reachable. A later registration of the same element supersedes an earlier one, and stale cleanup cannot remove it. An explicit-height change schedules geometry measurement even if the element border box is unchanged. Metrics use owner client width; `pinnedBottom = ownerRect.top + max(0, headerHeight - owner.scrollTop) + stickyHeaderHeight`; `visibleTop = max(ownerRect.top, pinnedBottom, contentRect.top if present)`; visible height is `max(0, ownerRect.bottom - visibleTop)` and content-relative scroll top is `max(0, pinnedBottom - contentRect.top)`. Unregistered content falls back to the first owner child. Detached content and callbacks from old owners are ignored. One animation-frame measurement per page coalesces scroll, resize, registration, owner configuration, and active-page changes. Disposal releases observers, listeners, frames, and subscriptions.
+
+On active-to-inactive transition, the Web pager freezes the selected logical React page key, `pagerScrollKey` identity, actual owner generation, and last valid raw DOM top. Inactive scroll/geometry changes cannot replace the snapshot. A second blur of the same pending identity preserves the original target. On focus, owner, content, chrome, or inset changes, the pager retries without a timer only when the route is active, that exact key/identity/owner remains selected and connected, the viewport has positive height, the pager has configured the expected insets, and real `scrollHeight - clientHeight` reaches the target. Short content keeps the target pending. Restoration clears pending before one instant scroll and synchronizes the existing shared Header C and per-page body B memory. An idempotent Web `restoreScrollPosition()` returns false while inactive or not ready and true when no target remains or it applies; normal callers need no polling.
+
+Valid vertical wheel, scroll keys, scrollbar drag, overlay-forwarded input, accepted NativeList commands, and explicit page-top/sticky-top commands cancel pending route intent through the existing SDK takeover path. As in the prior Web app adapter, any owner `pointerdown` or `touchstart`, including a child target, cancels only route pending; this does not newly commit or clear SDK C+B memory. Geometry-only scroll/resize/scrollend cannot cancel intent. Valid same-offset commands cancel it; invalid or stale commands do not. A matching route target takes priority over automatic tab C+B restoration. Selection of a different key, owner identity reset (including A→B→A), genuine DOM owner replacement, or removal cancels pending; a same-key index reorder preserves it. A same-commit blur and Activity/Offscreen effect disconnect captures the current route target before releasing the owner; repeated disconnects preserve an existing pending target. A temporary React ref null or Activity/Offscreen effect disconnect followed by the identical connected owner preserves the logical route target and owner generation while releasing all observers, listeners, frames, and DOM configuration during disconnect. Restoration is unavailable while disconnected; reconnect remeasures automatic chrome before applying pending. A truly removed pager instance cannot transfer its pending target to a new instance. Older queued tab/top callbacks must validate generation before writing after route restoration or cancellation. The app owns navigation focus and business tab names; the SDK never infers them from escaped React child keys.
+
+Platform matrix: Web owns this DOM geometry, registration, route pending, and explicit Web export. iOS and Android keep native scrolling, restoration, and page coordination documented above, with no new prop, native bridge call, JS heap sharing, or process resource. The UI main runtime owns Web state; background runtimes do not deserialize it. Source/type tests establish only Web contract implementation, not browser rendering or native device behavior. Acceptance requires real Web/Desktop route blur, short content then growth, user takeover, dynamic chrome, key reset, and Home/Market scroll regressions.

package/ios/RNCCollapsiblePagerViewComponentView.mm

@@ -1467,6 +1467,7 @@ static void RNCLogNativeTabScrollBoundary(NSString *owner,
 - (void)cancelTopInsetReboundCheck;
 - (void)scheduleTopInsetReboundCheck;
 - (void)syncScrollEdgeAppearance;
+- (void)updateHardEdgeSeparatorCovers;
 - (void)updateScrollEdgeContentMasks;
 - (void)restoreScrollEdgeContentMasks;
 - (void)sharedHeaderPressCancellationGestureChanged:(UIPanGestureRecognizer *)recognizer;
@@ -1503,6 +1504,8 @@ static void RNCLogNativeTabScrollBoundary(NSString *owner,
   UIScrollEdgeElementContainerInteraction *_stickyEdgeInteraction;
   UILabel *_topEdgeMarker;
   UILabel *_stickyEdgeMarker;
+  CALayer *_topEdgeSeparatorCover;
+  CALayer *_stickyEdgeSeparatorCover;
   __weak UIView *_topEdgeInteractionHost;
   __weak UIView *_stickyEdgeInteractionHost;
   __weak UIScrollView *_topEdgeScrollView;
@@ -1521,7 +1524,8 @@ static void RNCLogNativeTabScrollBoundary(NSString *owner,
   __weak RNCPagerViewComponentView *_externalOuterPager;
   BOOL _externalOuterPageActive;
   BOOL _externalOuterTransitioning;
-  BOOL _topScrollEdgeHard;
+  BOOL _topScrollEdgeEnabled;
+  RNCCollapsiblePagerViewTopScrollEdgeEffect _topScrollEdgeEffect;
   NSString *_topOverlayColorScheme;
   BOOL _pendingTopOverlayAppearanceCommit;
   BOOL _applyingTopOverlayInsetChange;
@@ -1914,7 +1918,7 @@ static void RNCLogNativeTabScrollBoundary(NSString *owner,
 
 - (void)syncScrollEdgeAppearance
 {
-  BOOL active = _topScrollEdgeHard &&
+  BOOL active = _topScrollEdgeEnabled &&
     (self.hasFixedTopOverlay || _stickyHeaderView != nil) && self.window != nil &&
     !_isBeingRecycled;
   UIUserInterfaceStyle style = UIUserInterfaceStyleUnspecified;
@@ -1952,7 +1956,8 @@ static void RNCLogNativeTabScrollBoundary(NSString *owner,
 
 - (void)updateScrollEdgeContentMasks
 {
-  BOOL enabled = _topScrollEdgeHard &&
+  [self updateHardEdgeSeparatorCovers];
+  BOOL enabled = _topScrollEdgeEnabled &&
     (self.hasFixedTopOverlay || _stickyHeaderView != nil) &&
     self.window != nil && !_isBeingRecycled;
   if (!enabled) {
@@ -2052,9 +2057,9 @@ static void RNCLogNativeTabScrollBoundary(NSString *owner,
     BOOL externalOwnerReady = _externalTopOverlayTag <= 0 ||
       _externalOuterPager == nil ||
       (_externalOuterPageActive && !_externalOuterTransitioning);
-    BOOL hasOverlay = _topScrollEdgeHard && self.hasFixedTopOverlay &&
+    BOOL hasOverlay = _topScrollEdgeEnabled && self.hasFixedTopOverlay &&
       externalOwnerReady && self.window != nil;
-    BOOL hasSticky = _topScrollEdgeHard && _stickyHeaderView != nil &&
+    BOOL hasSticky = _topScrollEdgeEnabled && _stickyHeaderView != nil &&
       externalOwnerReady && self.window != nil;
     BOOL enabled = (hasOverlay || hasSticky) && scrollView != nil;
     BOOL topHostChanged = (_topEdgeInteraction != nil) != hasOverlay ||
@@ -2080,7 +2085,12 @@ static void RNCLogNativeTabScrollBoundary(NSString *owner,
     if (enabled && _topEdgeScrollView == nil) {
       _originalTopEdgeStyle = scrollView.topEdgeEffect.style;
       _topEdgeScrollView = scrollView;
-      scrollView.topEdgeEffect.style = UIScrollEdgeEffectStyle.hardStyle;
+    }
+    if (enabled) {
+      UIScrollEdgeEffectStyle *style =
+        _topScrollEdgeEffect == RNCCollapsiblePagerViewTopScrollEdgeEffect::Soft
+          ? UIScrollEdgeEffectStyle.softStyle : UIScrollEdgeEffectStyle.hardStyle;
+      if (scrollView.topEdgeEffect.style != style) scrollView.topEdgeEffect.style = style;
     }
     if (hasOverlay && enabled && _topEdgeInteraction == nil) {
       // UIKit needs a native element to shape the edge effect around React-drawn content.
@@ -2135,6 +2145,54 @@ static void RNCLogNativeTabScrollBoundary(NSString *owner,
   }
 }
 
+- (void)updateHardEdgeSeparatorCovers
+{
+  BOOL enabled = _topScrollEdgeEnabled &&
+    _topScrollEdgeEffect == RNCCollapsiblePagerViewTopScrollEdgeEffect::Hard &&
+    _topEdgeScrollView != nil && self.window != nil && !_isBeingRecycled;
+  if (!enabled && _topEdgeSeparatorCover == nil && _stickyEdgeSeparatorCover == nil) return;
+  UIColor *color = nil;
+  for (UIView *view = self; view != nil; view = view.superview) {
+    UIColor *candidate = [view.backgroundColor resolvedColorWithTraitCollection:
+      _topOverlayHostView.traitCollection];
+    if (candidate != nil && CGColorGetAlpha(candidate.CGColor) >= 1) {
+      color = candidate;
+      break;
+    }
+  }
+  color = color ?: [UIColor.systemBackgroundColor resolvedColorWithTraitCollection:
+    _topOverlayHostView.traitCollection];
+  CGFloat scale = self.window.screen.scale ?: self.traitCollection.displayScale;
+  CGFloat pixel = 1.0 / MAX(1, scale);
+  UIView *hosts[] = {_topEdgeInteractionHost, _stickyEdgeInteractionHost};
+  CALayer *covers[] = {_topEdgeSeparatorCover, _stickyEdgeSeparatorCover};
+  for (NSInteger index = 0; index < 2; index++) {
+    UIView *host = hosts[index];
+    CALayer *cover = covers[index];
+    if (!enabled || host == nil || host.hidden || CGRectIsEmpty(host.bounds)) {
+      [cover removeFromSuperlayer];
+      cover = nil;
+    } else {
+      if (cover == nil) {
+        cover = [CALayer layer];
+        cover.name = @"onekey-hard-edge-separator-cover";
+        cover.zPosition = 1;
+        cover.actions = @{@"position": NSNull.null, @"bounds": NSNull.null,
+          @"backgroundColor": NSNull.null};
+        [_containerView.layer addSublayer:cover];
+      }
+      // Cover only the hairline; keep the native Hard material and glass shadows.
+      CGFloat boundary = CGRectGetMaxY([host convertRect:host.bounds toView:_containerView]);
+      cover.frame = CGRectMake(0, round(boundary * scale) / scale - pixel,
+        CGRectGetWidth(_containerView.bounds), pixel);
+      cover.contentsScale = scale;
+      cover.backgroundColor = color.CGColor;
+    }
+    if (index == 0) _topEdgeSeparatorCover = cover;
+    else _stickyEdgeSeparatorCover = cover;
+  }
+}
+
 - (void)dealloc
 {
   [self updateTopScrollEdgeForScrollView:nil];
@@ -2321,7 +2379,7 @@ static void RNCLogNativeTabScrollBoundary(NSString *owner,
   if (_sharedHeaderScrollView == scrollView &&
       _sharedHeaderHostView.superview == scrollView) {
     _sharedHeaderHostView.layer.zPosition =
-      _topScrollEdgeHard && (self.hasFixedTopOverlay || _stickyHeaderView != nil) ? 0 : 1000;
+      _topScrollEdgeEnabled && (self.hasFixedTopOverlay || _stickyHeaderView != nil) ? 0 : 1000;
     [self layoutSharedHeaders];
     return;
   }
@@ -2329,7 +2387,7 @@ static void RNCLogNativeTabScrollBoundary(NSString *owner,
   _sharedHeaderScrollView = scrollView;
   _sharedHeadersLiftedForPagerTransition = NO;
   _sharedHeaderHostView.layer.zPosition =
-    _topScrollEdgeHard && (self.hasFixedTopOverlay || _stickyHeaderView != nil) ? 0 : 1000;
+    _topScrollEdgeEnabled && (self.hasFixedTopOverlay || _stickyHeaderView != nil) ? 0 : 1000;
   if (_sharedHeaderHostView.superview != scrollView) {
     [scrollView addSubview:_sharedHeaderHostView];
   }
@@ -2424,7 +2482,7 @@ static void RNCLogNativeTabScrollBoundary(NSString *owner,
   CGFloat pinnedTranslation = MAX(0, _currentLogicalOffset - _headerHeight - refreshInset);
   CGFloat stickyTop = [_sharedHeaderHostView convertPoint:
     CGPointMake(0, _headerHeight + pinnedTranslation) toView:self].y;
-  BOOL shouldPin = _topScrollEdgeHard &&
+  BOOL shouldPin = _topScrollEdgeEnabled &&
     _stickyHeaderView != nil && attachedToList && !_transitioning &&
     !_externalOuterTransitioning &&
     !_isPagerDragging && _headerOffset >= _headerHeight - 0.5 &&
@@ -2646,7 +2704,7 @@ static void RNCLogNativeTabScrollBoundary(NSString *owner,
       _topOverlayView.window == self.window;
     BOOL externalOverlayReady = _externalTopOverlayTag > 0 &&
       _externalTopOverlayView.window == self.window;
-    if (!_isBeingRecycled && _topScrollEdgeHard && self.window != nil &&
+    if (!_isBeingRecycled && _topScrollEdgeEnabled && self.window != nil &&
         (localOverlayReady || externalOverlayReady)) {
       [self updateTopScrollEdgeForScrollView:_observedScrollView];
     }
@@ -2729,7 +2787,7 @@ static void RNCLogNativeTabScrollBoundary(NSString *owner,
   if (_isBeingRecycled) return;
   NSInteger safeIndex = MIN(MAX(index, 0), _logicalChildren.count);
   [_logicalChildren insertObject:childComponentView atIndex:safeIndex];
-  if (_topScrollEdgeHard || _topOverlayView != nil) {
+  if (_topScrollEdgeEnabled || _topOverlayView != nil) {
     _needsSlotRebuild = YES;
   } else {
     [self rebuildSlots];
@@ -2744,7 +2802,7 @@ static void RNCLogNativeTabScrollBoundary(NSString *owner,
   if (existingIndex == NSNotFound) return;
   [childComponentView removeFromSuperview];
   [_logicalChildren removeObjectAtIndex:existingIndex];
-  if (_topScrollEdgeHard || _topOverlayView != nil) {
+  if (_topScrollEdgeEnabled || _topOverlayView != nil) {
     _needsSlotRebuild = YES;
   } else {
     [self rebuildSlots];
@@ -2761,7 +2819,7 @@ static void RNCLogNativeTabScrollBoundary(NSString *owner,
     _needsSlotRebuild = YES;
     return;
   }
-  if (_topScrollEdgeHard &&
+  if (_topScrollEdgeEnabled &&
       _logicalChildren.count != _pageKeys.count + 2 &&
       _logicalChildren.count != _pageKeys.count + 3) {
     _needsSlotRebuild = YES;
@@ -2800,7 +2858,7 @@ static void RNCLogNativeTabScrollBoundary(NSString *owner,
     _stickyHeaderView = _logicalChildren[1];
     [_sharedHeaderHostView addSubview:_stickyHeaderView];
   }
-  BOOL hasOverlaySlot = _topScrollEdgeHard &&
+  BOOL hasOverlaySlot = _topScrollEdgeEnabled &&
     _logicalChildren.count == _pageKeys.count + 3;
   NSInteger pageSlotStart = hasOverlaySlot ? 3 : 2;
   if (hasOverlaySlot) {
@@ -3050,7 +3108,8 @@ static void RNCLogNativeTabScrollBoundary(NSString *owner,
   _externalTopOverlayHeight = 0;
   _externalOuterPageActive = NO;
   _externalOuterTransitioning = NO;
-  _topScrollEdgeHard = NO;
+  _topScrollEdgeEnabled = NO;
+  _topScrollEdgeEffect = RNCCollapsiblePagerViewTopScrollEdgeEffect::None;
   _nativeTabBarHeight = 44;
   _nativeSubHeaderHeight = 74;
   _headerOffset = 0;
@@ -3092,7 +3151,8 @@ static void RNCLogNativeTabScrollBoundary(NSString *owner,
   const auto &oldViewProps = *std::static_pointer_cast<const RNCCollapsiblePagerViewProps>(_props);
   const auto &newViewProps = *std::static_pointer_cast<const RNCCollapsiblePagerViewProps>(props);
   _applyingTopOverlayInsetChange =
-    oldViewProps.topScrollEdgeHard != newViewProps.topScrollEdgeHard ||
+    (oldViewProps.topScrollEdgeEffect == RNCCollapsiblePagerViewTopScrollEdgeEffect::None) !=
+      (newViewProps.topScrollEdgeEffect == RNCCollapsiblePagerViewTopScrollEdgeEffect::None) ||
     oldViewProps.topOverlayHeight != newViewProps.topOverlayHeight;
 
   if (_needsPropsReapply || oldViewProps.initialPage != newViewProps.initialPage) {
@@ -3143,9 +3203,12 @@ static void RNCLogNativeTabScrollBoundary(NSString *owner,
     _stickyHeaderHeight = MAX(0, newViewProps.stickyHeaderHeight);
     insetsChanged = YES;
   }
-  if (_needsPropsReapply || oldViewProps.topScrollEdgeHard != newViewProps.topScrollEdgeHard) {
-    _topScrollEdgeHard = newViewProps.topScrollEdgeHard;
-    if (oldViewProps.topScrollEdgeHard || newViewProps.topScrollEdgeHard) {
+  if (_needsPropsReapply || oldViewProps.topScrollEdgeEffect != newViewProps.topScrollEdgeEffect) {
+    BOOL enabled = newViewProps.topScrollEdgeEffect != RNCCollapsiblePagerViewTopScrollEdgeEffect::None;
+    BOOL enabledChanged = _topScrollEdgeEnabled != enabled;
+    _topScrollEdgeEnabled = enabled;
+    _topScrollEdgeEffect = newViewProps.topScrollEdgeEffect;
+    if (enabledChanged) {
       _deferTopEdgeSlotRebuild = YES;
       [self rebuildSlots];
       NSUInteger generation = _generation;
@@ -3156,12 +3219,12 @@ static void RNCLogNativeTabScrollBoundary(NSString *owner,
         [self rebuildSlots];
       });
     }
-    insetsChanged = YES;
+    insetsChanged |= enabledChanged;
   }
   if (_needsPropsReapply ||
       oldViewProps.topOverlayColorScheme != newViewProps.topOverlayColorScheme) {
     NSString *nextScheme = RCTNSStringFromString(newViewProps.topOverlayColorScheme);
-    if (self.hasFixedTopOverlay && _topScrollEdgeHard &&
+    if (self.hasFixedTopOverlay && _topScrollEdgeEnabled &&
         _topOverlayColorScheme != nil &&
         ![_topOverlayColorScheme isEqualToString:nextScheme]) {
       _pendingTopOverlayAppearanceCommit = YES;

package/ios/RNCNativeScrollerComponentView.mm

@@ -196,7 +196,7 @@ static Event RNCScrollerMetrics(UIScrollView *scroll, CGPoint velocity, CGPoint
   BOOL refreshEnded = previous.refreshing && !next.refreshing;
   [super updateProps:props oldProps:oldProps];
   [self updateTopScrollEdge];
-  if (next.topScrollEdgeHard && _topOverlay == nil) {
+  if ((next.topScrollEdgeEffect != RNCNativeScrollerTopScrollEdgeEffect::None) && _topOverlay == nil) {
     __weak __typeof__(self) weakSelf = self;
     dispatch_async(dispatch_get_main_queue(), ^{ [weakSelf updateTopScrollEdge]; });
   }
@@ -210,7 +210,7 @@ static Event RNCScrollerMetrics(UIScrollView *scroll, CGPoint velocity, CGPoint
   if (@available(iOS 26.0, *)) {
     const auto &props = *std::static_pointer_cast<const RNCNativeScrollerProps>(_props);
     UIView *overlay = nil;
-    if (props.topScrollEdgeHard && !_recycled) {
+    if ((props.topScrollEdgeEffect != RNCNativeScrollerTopScrollEdgeEffect::None) && !_recycled) {
       NSUInteger fabricSiblings = 0;
       for (UIView *candidate in self.superview.subviews) {
         if (![candidate conformsToProtocol:@protocol(RCTComponentViewProtocol)]) continue;
@@ -220,7 +220,7 @@ static Event RNCScrollerMetrics(UIScrollView *scroll, CGPoint velocity, CGPoint
       if (fabricSiblings != 2) overlay = nil;
     }
     _topOverlay = overlay;
-    CGFloat requestedOverlayInset = props.topScrollEdgeHard && !_recycled && overlay != nil &&
+    CGFloat requestedOverlayInset = (props.topScrollEdgeEffect != RNCNativeScrollerTopScrollEdgeEffect::None) && !_recycled && overlay != nil &&
       isfinite(props.topOverlayHeight) ? MAX(0, props.topOverlayHeight) : 0;
     if (_appliedOverlayInset != requestedOverlayInset) {
       // Keep UIKit's refresh rebound animation in control while it is overscrolled.
@@ -236,7 +236,7 @@ static Event RNCScrollerMetrics(UIScrollView *scroll, CGPoint velocity, CGPoint
       }
       [self emitContentViewportChangeIfNeeded];
     }
-    BOOL enabled = props.topScrollEdgeHard && !_recycled && overlay != nil && self.window != nil;
+    BOOL enabled = (props.topScrollEdgeEffect != RNCNativeScrollerTopScrollEdgeEffect::None) && !_recycled && overlay != nil && self.window != nil;
     if (!enabled || _topEdgeInteractionHost != overlay) {
       if (_topEdgeInteraction != nil) {
         [_topEdgeInteractionHost removeInteraction:_topEdgeInteraction];
@@ -271,7 +271,8 @@ static Event RNCScrollerMetrics(UIScrollView *scroll, CGPoint velocity, CGPoint
       [overlay addInteraction:_topEdgeInteraction];
       _topEdgeInteractionHost = overlay;
     }
-    _scrollView.topEdgeEffect.style = UIScrollEdgeEffectStyle.hardStyle;
+    _scrollView.topEdgeEffect.style = props.topScrollEdgeEffect == RNCNativeScrollerTopScrollEdgeEffect::Soft
+      ? UIScrollEdgeEffectStyle.softStyle : UIScrollEdgeEffectStyle.hardStyle;
   }
 }
 

package/ios/tests/RNCCollapsiblePagerHitTestTests.mm

@@ -90,9 +90,17 @@ using namespace facebook::react;
     UIScrollView *scrollView = [[UIScrollView alloc] initWithFrame:self.pager.bounds];
     [self.pager addSubview:scrollView];
     UIScrollEdgeEffectStyle *originalStyle = scrollView.topEdgeEffect.style;
-    [self.pager setValue:@YES forKey:@"topScrollEdgeHard"];
+    [self.pager setValue:@YES forKey:@"topScrollEdgeEnabled"];
+    [self.pager setValue:@(static_cast<NSInteger>(RNCCollapsiblePagerViewTopScrollEdgeEffect::Hard))
+                 forKey:@"topScrollEdgeEffect"];
     [self.pager setValue:@123 forKey:@"externalTopOverlayTag"];
     [self.pager setValue:@64 forKey:@"externalTopOverlayHeight"];
+    UIView *container = [self.pager valueForKey:@"containerView"];
+    container.frame = self.pager.bounds;
+    UIView *overlayHost = [self.pager valueForKey:@"topOverlayHostView"];
+    overlayHost.frame = CGRectMake(0, 0, 320, 64);
+    overlayHost.hidden = NO;
+    self.pager.backgroundColor = UIColor.redColor;
     [self.pager updateTopScrollEdgeForScrollView:scrollView];
     XCTAssertEqual([self.pager valueForKey:@"topEdgeScrollView"], scrollView);
     UIScrollEdgeElementContainerInteraction *interaction =
@@ -100,6 +108,23 @@ using namespace facebook::react;
     XCTAssertEqual(interaction.scrollView, scrollView);
     UIView *host = [self.pager valueForKey:@"topEdgeInteractionHost"];
     XCTAssertTrue([host.interactions containsObject:interaction]);
+    XCTAssertEqual(scrollView.topEdgeEffect.style, UIScrollEdgeEffectStyle.hardStyle);
+    CALayer *cover = [self.pager valueForKey:@"topEdgeSeparatorCover"];
+    XCTAssertEqual(cover.superlayer, container.layer);
+    XCTAssertEqualWithAccuracy(CGRectGetMaxY(cover.frame), 64, 0.001);
+    XCTAssertEqualWithAccuracy(CGRectGetHeight(cover.frame), 1.0 / window.screen.scale, 0.001);
+    XCTAssertTrue(CGColorEqualToColor(cover.backgroundColor, UIColor.redColor.CGColor));
+    UIEdgeInsets inset = scrollView.contentInset;
+    CGPoint offset = scrollView.contentOffset;
+    [self.pager setValue:@(static_cast<NSInteger>(RNCCollapsiblePagerViewTopScrollEdgeEffect::Soft))
+                 forKey:@"topScrollEdgeEffect"];
+    [self.pager updateTopScrollEdgeForScrollView:scrollView];
+    XCTAssertEqual(scrollView.topEdgeEffect.style, UIScrollEdgeEffectStyle.softStyle);
+    XCTAssertNil([self.pager valueForKey:@"topEdgeSeparatorCover"]);
+    XCTAssertNil(cover.superlayer);
+    XCTAssertEqual([self.pager valueForKey:@"topEdgeInteraction"], interaction);
+    XCTAssertTrue(UIEdgeInsetsEqualToEdgeInsets(scrollView.contentInset, inset));
+    XCTAssertTrue(CGPointEqualToPoint(scrollView.contentOffset, offset));
 
     RNCPagerViewComponentView *outer = [RNCPagerViewComponentView new];
     [self.pager setValue:outer forKey:@"externalOuterPager"];

package/ios/tests/RNCNativeScrollerTests.mm

@@ -69,6 +69,45 @@ using namespace facebook::react;
   XCTAssertFalse([self.scroller.scrollView isKindOfClass:NSClassFromString(@"RCTEnhancedScrollView")]);
 }
 
+- (void)testScrollEdgeStyleSwitchPreservesOverlayInsetAndRestoresOriginalStyle
+{
+  if (@available(iOS 26.0, *)) {
+    UIWindow *window = [[UIWindow alloc] initWithFrame:CGRectMake(0, 0, 320, 600)];
+    UIView *root = [[UIView alloc] initWithFrame:window.bounds];
+    [window addSubview:root];
+    [root addSubview:self.scroller];
+    RCTViewComponentView *overlay = [RCTViewComponentView new];
+    overlay.frame = CGRectMake(0, 0, 320, 64);
+    [root addSubview:overlay];
+    UIScrollEdgeEffectStyle *original = self.scroller.scrollView.topEdgeEffect.style;
+    auto props = std::make_shared<RNCNativeScrollerProps>();
+    props->contentHeight = 1500;
+    props->topOverlayHeight = 64;
+    props->topScrollEdgeEffect = RNCNativeScrollerTopScrollEdgeEffect::Hard;
+    [self.scroller updateProps:props oldProps:nullptr];
+    XCTAssertEqual(self.scroller.scrollView.topEdgeEffect.style, UIScrollEdgeEffectStyle.hardStyle);
+    XCTAssertEqualWithAccuracy(self.scroller.scrollView.contentInset.top, 64, 0.01);
+    CGPoint offset = self.scroller.scrollView.contentOffset;
+    auto soft = std::make_shared<RNCNativeScrollerProps>();
+    soft->contentHeight = 1500;
+    soft->topOverlayHeight = 64;
+    soft->topScrollEdgeEffect = RNCNativeScrollerTopScrollEdgeEffect::Soft;
+    [self.scroller updateProps:soft oldProps:props];
+    XCTAssertEqual(self.scroller.scrollView.topEdgeEffect.style, UIScrollEdgeEffectStyle.softStyle);
+    XCTAssertEqualWithAccuracy(self.scroller.scrollView.contentInset.top, 64, 0.01);
+    XCTAssertTrue(CGPointEqualToPoint(self.scroller.scrollView.contentOffset, offset));
+    auto disabled = std::make_shared<RNCNativeScrollerProps>();
+    disabled->contentHeight = 1500;
+    disabled->topScrollEdgeEffect = RNCNativeScrollerTopScrollEdgeEffect::None;
+    [self.scroller updateProps:disabled oldProps:soft];
+    XCTAssertEqual(self.scroller.scrollView.topEdgeEffect.style, original);
+    XCTAssertEqualWithAccuracy(self.scroller.scrollView.contentInset.top, 0, 0.01);
+    [self.scroller removeFromSuperview];
+  } else {
+    XCTSkip(@"Scroll-edge styles require iOS 26 or newer");
+  }
+}
+
 - (void)testShrinkClampsOnlyUnreachableUpperOffset
 {
   auto props = std::make_shared<RNCNativeScrollerProps>();

package/lib/module/CollapsiblePagerView.js

@@ -217,8 +217,8 @@ export class CollapsiblePagerView extends React.PureComponent {
     } = this.props;
     const pages = this.pages();
     const supportsTopScrollEdge = Platform.OS === "ios" && parseInt(String(Platform.Version), 10) >= 26;
-    const hardScrollEdge = supportsTopScrollEdge && topScrollEdgeEffect === "hard";
-    const hasTopOverlay = hardScrollEdge && topOverlay != null;
+    const scrollEdgeEnabled = supportsTopScrollEdge && (topScrollEdgeEffect === "hard" || topScrollEdgeEffect === "soft");
+    const hasTopOverlay = scrollEdgeEnabled && topOverlay != null;
     const pageKeys = pages.map(pageKey);
     const retained = new Set(this.mountedPages(pages.length));
     const deducedLayoutDirection = !layoutDirection || layoutDirection === "locale" ? I18nManager.isRTL ? "rtl" : "ltr" : layoutDirection;
@@ -243,8 +243,8 @@ export class CollapsiblePagerView extends React.PureComponent {
       offscreenPageLimit: Math.max(1, offscreenPageLimit ?? 1),
       headerHeight: Math.max(0, Math.round(headerHeight)),
       stickyHeaderHeight: Math.max(0, Math.round(stickyHeaderHeight)),
-      topScrollEdgeHard: hardScrollEdge,
-      topOverlayColorScheme: hardScrollEdge ? topOverlayColorScheme : undefined,
+      topScrollEdgeEffect: scrollEdgeEnabled ? topScrollEdgeEffect : "none",
+      topOverlayColorScheme: scrollEdgeEnabled ? topOverlayColorScheme : undefined,
       topOverlayHeight: hasTopOverlay ? this.state.topOverlayHeight : 0,
       externalTopOverlayTag: supportsTopScrollEdge && !hasTopOverlay ? externalTopOverlayTag ?? 0 : 0,
       nativeSmoothHeaderScrollEnabled: nativeSmoothHeaderScrollEnabled,