@onekeyfe/react-native-pager-view 3.0.180 → 6.7.0-2

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

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,

package/lib/module/CollapsiblePagerViewNativeComponent.ts

@@ -59,7 +59,7 @@ export interface NativeProps extends ViewProps {
   nativeSmoothHeaderScrollEnabled?: WithDefault<boolean, false>;
   headerHeight?: Int32;
   stickyHeaderHeight?: Int32;
-  topScrollEdgeHard?: WithDefault<boolean, false>;
+  topScrollEdgeEffect?: WithDefault<"none" | "hard" | "soft", "none">;
   topOverlayColorScheme?: string;
   topOverlayHeight?: WithDefault<Double, 0>;
   externalTopOverlayTag?: WithDefault<Int32, 0>;

package/lib/module/NativeScroller.js

@@ -59,7 +59,7 @@ export const NativeScroller = /*#__PURE__*/React.forwardRef(function NativeScrol
     height: 0
   });
   const [topOverlayHeight, setTopOverlayHeight] = React.useState(0);
-  const hasTopOverlay = Platform.OS === "ios" && parseInt(String(Platform.Version), 10) >= 26 && topScrollEdgeEffect === "hard" && topOverlay != null;
+  const hasTopOverlay = Platform.OS === "ios" && parseInt(String(Platform.Version), 10) >= 26 && (topScrollEdgeEffect === "hard" || topScrollEdgeEffect === "soft") && topOverlay != null;
   const [refreshEpoch, requestRefreshSync] = React.useReducer(value => value + 1, 0);
   const contentSizeRef = React.useRef(contentSize);
   const scrolledSinceGrant = React.useRef(false);
@@ -114,7 +114,7 @@ export const NativeScroller = /*#__PURE__*/React.forwardRef(function NativeScrol
       contentInsetRight: contentInset?.right ?? 0,
       contentInsetBottom: contentInset?.bottom ?? 0,
       contentInsetLeft: contentInset?.left ?? 0,
-      topScrollEdgeHard: hasTopOverlay,
+      topScrollEdgeEffect: hasTopOverlay ? topScrollEdgeEffect : "none",
       topOverlayHeight: hasTopOverlay ? topOverlayHeight : 0,
       decelerationRate: rate,
       keyboardShouldPersistTaps: persistTaps,

package/lib/module/NativeScrollerNativeComponent.ts

@@ -47,7 +47,7 @@ export interface NativeProps extends ViewProps {
   contentInsetRight?: WithDefault<Double, 0>;
   contentInsetBottom?: WithDefault<Double, 0>;
   contentInsetLeft?: WithDefault<Double, 0>;
-  topScrollEdgeHard?: WithDefault<boolean, false>;
+  topScrollEdgeEffect?: WithDefault<"none" | "hard" | "soft", "none">;
   topOverlayHeight?: WithDefault<Double, 0>;
   refreshEnabled?: WithDefault<boolean, false>;
   refreshing?: WithDefault<boolean, false>;

package/lib/module/ScrollEdgeEffect.js

@@ -0,0 +1,8 @@
+"use strict";
+
+export let ScrollEdgeEffect = /*#__PURE__*/function (ScrollEdgeEffect) {
+  ScrollEdgeEffect["Hard"] = "hard";
+  ScrollEdgeEffect["Soft"] = "soft";
+  return ScrollEdgeEffect;
+}({});
+//# sourceMappingURL=ScrollEdgeEffect.js.map

package/lib/module/index.js

@@ -5,4 +5,5 @@ export default PagerView;
 export * from "./usePagerView.js";
 export * from './CollapsiblePagerView';
 export * from './NativeScroller';
+export { ScrollEdgeEffect } from "./ScrollEdgeEffect.js";
 //# sourceMappingURL=index.js.map

package/lib/module/index.web.js

@@ -4,4 +4,5 @@ export { PagerView as default, PagerView } from "./PagerView.web.js";
 export * from "./usePagerView.js";
 export * from "./CollapsiblePagerView.web.js";
 export * from "./NativeScroller.web.js";
+export { ScrollEdgeEffect } from "./ScrollEdgeEffect.js";
 //# sourceMappingURL=index.web.js.map

package/lib/typescript/src/CollapsiblePagerView.d.ts

@@ -1,3 +1,4 @@
+import type { ScrollEdgeEffect } from "./ScrollEdgeEffect";
 import React from "react";
 import type * as ReactNative from "react-native";
 import { type NativeProps, type OnCollapsibleStateChangedEventData, type OnNativeTabPressEventData } from "./CollapsiblePagerViewNativeComponent";
@@ -55,7 +56,7 @@ export type CollapsiblePagerNativeSubHeaderConfig = Readonly<{
 }>;
 export type CollapsiblePagerViewOnNativeTabPressEvent = ReactNative.NativeSyntheticEvent<OnNativeTabPressEventData>;
 export type CollapsiblePagerViewOnNativeSubHeaderPressEvent = ReactNative.NativeSyntheticEvent<OnNativeTabPressEventData>;
-export interface CollapsiblePagerViewProps extends Omit<NativeProps, "children" | "headerHeight" | "stickyHeaderHeight" | "topScrollEdgeHard" | "topOverlayHeight" | "externalTopOverlayTag" | "pageKeys" | "retainedPages" | "nativeTabBarItems" | "nativeTabBarHeight" | "nativeTabBarContentPaddingHorizontal" | "nativeTabBarItemSpacing" | "nativeTabBarFontSize" | "nativeTabBarFontFamily" | "nativeTabBarBackgroundColor" | "nativeTabBarActiveTextColor" | "nativeTabBarInactiveTextColor" | "nativeTabBarIndicatorColor" | "nativeTabBarIndicatorHeight" | "nativeTabBarIndicatorBottom" | "nativeSubHeaderConfig" | "nativeSubHeaderSelectedBackgroundColor" | "onNativeTabPress" | "onNativeSubHeaderPress" | "layoutDirection"> {
+export interface CollapsiblePagerViewProps extends Omit<NativeProps, "children" | "headerHeight" | "stickyHeaderHeight" | "topScrollEdgeEffect" | "topOverlayHeight" | "externalTopOverlayTag" | "pageKeys" | "retainedPages" | "nativeTabBarItems" | "nativeTabBarHeight" | "nativeTabBarContentPaddingHorizontal" | "nativeTabBarItemSpacing" | "nativeTabBarFontSize" | "nativeTabBarFontFamily" | "nativeTabBarBackgroundColor" | "nativeTabBarActiveTextColor" | "nativeTabBarInactiveTextColor" | "nativeTabBarIndicatorColor" | "nativeTabBarIndicatorHeight" | "nativeTabBarIndicatorBottom" | "nativeSubHeaderConfig" | "nativeSubHeaderSelectedBackgroundColor" | "onNativeTabPress" | "onNativeSubHeaderPress" | "layoutDirection"> {
     /** Collapsible content rendered above the sticky bar. */
     header: React.ReactNode;
     /** Bar which remains pinned after the header has collapsed. */
@@ -68,8 +69,8 @@ export interface CollapsiblePagerViewProps extends Omit<NativeProps, "children"
     topOverlay?: React.ReactNode;
     /** Existing fixed header shared with a parent pager on iOS 26 and newer. */
     externalTopOverlayTag?: number;
-    /** Enables UIKit's hard top scroll-edge effect on iOS 26 and newer. */
-    topScrollEdgeEffect?: "hard";
+    /** Selects UIKit's top scroll-edge effect on iOS 26 and newer. */
+    topScrollEdgeEffect?: `${ScrollEdgeEffect}`;
     /** Effective appearance of the fixed overlay or pinned sticky bar. */
     topOverlayColorScheme?: "light" | "dark";
     /**

package/lib/typescript/src/CollapsiblePagerView.web.d.ts

@@ -1,3 +1,4 @@
+import type { ScrollEdgeEffect } from "./ScrollEdgeEffect";
 import React from "react";
 import type * as ReactNative from "react-native";
 export type OnPageScrollEventData = Readonly<{
@@ -40,7 +41,7 @@ export interface CollapsiblePagerViewProps extends Omit<WebCollapsiblePagerNativ
     headerHeight: number;
     stickyHeaderHeight: number;
     topOverlay?: React.ReactNode;
-    topScrollEdgeEffect?: "hard";
+    topScrollEdgeEffect?: `${ScrollEdgeEffect}`;
     topOverlayColorScheme?: "light" | "dark";
     externalTopOverlayTag?: number;
     pageRetentionDistance?: number;

package/lib/typescript/src/CollapsiblePagerViewNativeComponent.d.ts

@@ -42,7 +42,7 @@ export interface NativeProps extends ViewProps {
     nativeSmoothHeaderScrollEnabled?: WithDefault<boolean, false>;
     headerHeight?: Int32;
     stickyHeaderHeight?: Int32;
-    topScrollEdgeHard?: WithDefault<boolean, false>;
+    topScrollEdgeEffect?: WithDefault<"none" | "hard" | "soft", "none">;
     topOverlayColorScheme?: string;
     topOverlayHeight?: WithDefault<Double, 0>;
     externalTopOverlayTag?: WithDefault<Int32, 0>;

package/lib/typescript/src/NativeScroller.d.ts

@@ -1,14 +1,15 @@
 import * as React from "react";
 import { type NativeMethods, type RefreshControlProps, type ScrollView, type ScrollViewProps, type ViewProps } from "react-native";
 import NativeScrollerHost from "./NativeScrollerNativeComponent";
+import type { ScrollEdgeEffect } from "./ScrollEdgeEffect";
 export declare const NATIVE_SCROLLER_NATIVE_ID_PREFIX = "rnc-collapsible-pager-native-scroller";
 /** Supported vertical subset; horizontal, snapping, zoom and sticky rows are not supported. */
 export interface NativeScrollerProps extends ViewProps, Pick<ScrollViewProps, "contentContainerStyle" | "onContentSizeChange" | "scrollEnabled" | "nestedScrollEnabled" | "showsVerticalScrollIndicator" | "showsHorizontalScrollIndicator" | "bounces" | "alwaysBounceVertical" | "contentInset" | "keyboardDismissMode" | "keyboardShouldPersistTaps" | "scrollEventThrottle" | "decelerationRate" | "onScroll" | "onScrollBeginDrag" | "onScrollEndDrag" | "onMomentumScrollBegin" | "onMomentumScrollEnd"> {
     pagerScrollKey?: string;
     /** Fixed overlay above scrolling content on iOS 26 and newer. */
     topOverlay?: React.ReactNode;
-    /** Enables UIKit's hard top scroll-edge effect on iOS 26 and newer. */
-    topScrollEdgeEffect?: "hard";
+    /** Selects UIKit's top scroll-edge effect on iOS 26 and newer. */
+    topScrollEdgeEffect?: `${ScrollEdgeEffect}`;
     /** iOS only. Android retains AndroidX's native fling physics. */
     decelerationRate?: ScrollViewProps["decelerationRate"];
     /** Standard RefreshControl props are mapped to the independently owned native controller. */

package/lib/typescript/src/NativeScrollerNativeComponent.d.ts

@@ -47,7 +47,7 @@ export interface NativeProps extends ViewProps {
     contentInsetRight?: WithDefault<Double, 0>;
     contentInsetBottom?: WithDefault<Double, 0>;
     contentInsetLeft?: WithDefault<Double, 0>;
-    topScrollEdgeHard?: WithDefault<boolean, false>;
+    topScrollEdgeEffect?: WithDefault<"none" | "hard" | "soft", "none">;
     topOverlayHeight?: WithDefault<Double, 0>;
     refreshEnabled?: WithDefault<boolean, false>;
     refreshing?: WithDefault<boolean, false>;

package/lib/typescript/src/ScrollEdgeEffect.d.ts

@@ -0,0 +1,5 @@
+export declare enum ScrollEdgeEffect {
+    Hard = "hard",
+    Soft = "soft"
+}
+//# sourceMappingURL=ScrollEdgeEffect.d.ts.map

package/lib/typescript/src/index.d.ts

@@ -9,4 +9,5 @@ export type { PagerViewOnPageScrollEventData, PagerViewOnPageSelectedEventData,
 export type PagerViewOnPageScrollEvent = ReactNative.NativeSyntheticEvent<PagerViewOnPageScrollEventData>;
 export type PagerViewOnPageSelectedEvent = ReactNative.NativeSyntheticEvent<PagerViewOnPageSelectedEventData>;
 export type PageScrollStateChangedNativeEvent = ReactNative.NativeSyntheticEvent<PageScrollStateChangedNativeEventData>;
+export { ScrollEdgeEffect } from './ScrollEdgeEffect';
 //# sourceMappingURL=index.d.ts.map

package/lib/typescript/src/index.web.d.ts

@@ -3,4 +3,5 @@ export type { PagerViewProps, PagerViewOnPageScrollEvent, PagerViewOnPageScrollE
 export * from "./usePagerView";
 export * from "./CollapsiblePagerView.web";
 export * from "./NativeScroller.web";
+export { ScrollEdgeEffect } from "./ScrollEdgeEffect";
 //# sourceMappingURL=index.web.d.ts.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onekeyfe/react-native-pager-view",
-  "version": "3.0.180",
+  "version": "6.7.0-2",
   "description": "React Native wrapper for Android and iOS ViewPager",
   "source": "./src/index.tsx",
   "main": "./lib/module/index.js",
@@ -72,7 +72,7 @@
     "typescript": "^5.9.2"
   },
   "peerDependencies": {
-    "@onekeyfe/react-native-native-logger": "3.0.180",
+    "@onekeyfe/react-native-native-logger": "6.7.0-2",
     "react": "*",
     "react-native": "*"
   },

package/src/CollapsiblePagerView.tsx

@@ -1,3 +1,4 @@
+import type { ScrollEdgeEffect } from "./ScrollEdgeEffect";
 import React from "react";
 import { I18nManager, Platform, StyleSheet, View } from "react-native";
 import type * as ReactNative from "react-native";
@@ -86,7 +87,7 @@ export interface CollapsiblePagerViewProps
     | "children"
     | "headerHeight"
     | "stickyHeaderHeight"
-    | "topScrollEdgeHard"
+    | "topScrollEdgeEffect"
     | "topOverlayHeight"
     | "externalTopOverlayTag"
     | "pageKeys"
@@ -121,8 +122,8 @@ export interface CollapsiblePagerViewProps
   topOverlay?: React.ReactNode;
   /** Existing fixed header shared with a parent pager on iOS 26 and newer. */
   externalTopOverlayTag?: number;
-  /** Enables UIKit's hard top scroll-edge effect on iOS 26 and newer. */
-  topScrollEdgeEffect?: "hard";
+  /** Selects UIKit's top scroll-edge effect on iOS 26 and newer. */
+  topScrollEdgeEffect?: `${ScrollEdgeEffect}`;
   /** Effective appearance of the fixed overlay or pinned sticky bar. */
   topOverlayColorScheme?: "light" | "dark";
   /**
@@ -493,8 +494,10 @@ export class CollapsiblePagerView extends React.PureComponent<
     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 =
@@ -535,8 +538,10 @@ 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

package/src/CollapsiblePagerView.web.tsx

@@ -1,3 +1,4 @@
+import type { ScrollEdgeEffect } from "./ScrollEdgeEffect";
 import React from "react";
 import { I18nManager, StyleSheet, View } from "react-native";
 import type * as ReactNative from "react-native";
@@ -67,7 +68,7 @@ export interface CollapsiblePagerViewProps
   headerHeight: number;
   stickyHeaderHeight: number;
   topOverlay?: React.ReactNode;
-  topScrollEdgeEffect?: "hard";
+  topScrollEdgeEffect?: `${ScrollEdgeEffect}`;
   topOverlayColorScheme?: "light" | "dark";
   externalTopOverlayTag?: number;
   pageRetentionDistance?: number;

package/src/CollapsiblePagerViewNativeComponent.ts

@@ -59,7 +59,7 @@ export interface NativeProps extends ViewProps {
   nativeSmoothHeaderScrollEnabled?: WithDefault<boolean, false>;
   headerHeight?: Int32;
   stickyHeaderHeight?: Int32;
-  topScrollEdgeHard?: WithDefault<boolean, false>;
+  topScrollEdgeEffect?: WithDefault<"none" | "hard" | "soft", "none">;
   topOverlayColorScheme?: string;
   topOverlayHeight?: WithDefault<Double, 0>;
   externalTopOverlayTag?: WithDefault<Int32, 0>;

package/src/NativeScroller.tsx

@@ -15,6 +15,7 @@ import {
 } from "react-native";
 
 import NativeScrollerHost, { Commands } from "./NativeScrollerNativeComponent";
+import type { ScrollEdgeEffect } from "./ScrollEdgeEffect";
 
 export const NATIVE_SCROLLER_NATIVE_ID_PREFIX =
   "rnc-collapsible-pager-native-scroller";
@@ -46,8 +47,8 @@ export interface NativeScrollerProps
   pagerScrollKey?: string;
   /** Fixed overlay above scrolling content on iOS 26 and newer. */
   topOverlay?: React.ReactNode;
-  /** Enables UIKit's hard top scroll-edge effect on iOS 26 and newer. */
-  topScrollEdgeEffect?: "hard";
+  /** Selects UIKit's top scroll-edge effect on iOS 26 and newer. */
+  topScrollEdgeEffect?: `${ScrollEdgeEffect}`;
   /** iOS only. Android retains AndroidX's native fling physics. */
   decelerationRate?: ScrollViewProps["decelerationRate"];
   /** Standard RefreshControl props are mapped to the independently owned native controller. */
@@ -118,7 +119,8 @@ export const NativeScroller = React.forwardRef<
   const [topOverlayHeight, setTopOverlayHeight] = React.useState(0);
   const hasTopOverlay =
     Platform.OS === "ios" && parseInt(String(Platform.Version), 10) >= 26 &&
-    topScrollEdgeEffect === "hard" && topOverlay != null;
+    (topScrollEdgeEffect === "hard" || topScrollEdgeEffect === "soft") &&
+    topOverlay != null;
   const [refreshEpoch, requestRefreshSync] = React.useReducer(
     (value: number) => value + 1,
     0
@@ -212,7 +214,7 @@ export const NativeScroller = React.forwardRef<
       contentInsetRight={contentInset?.right ?? 0}
       contentInsetBottom={contentInset?.bottom ?? 0}
       contentInsetLeft={contentInset?.left ?? 0}
-      topScrollEdgeHard={hasTopOverlay}
+      topScrollEdgeEffect={hasTopOverlay ? topScrollEdgeEffect : "none"}
       topOverlayHeight={hasTopOverlay ? topOverlayHeight : 0}
       decelerationRate={rate}
       keyboardShouldPersistTaps={persistTaps}

package/src/NativeScrollerNativeComponent.ts

@@ -47,7 +47,7 @@ export interface NativeProps extends ViewProps {
   contentInsetRight?: WithDefault<Double, 0>;
   contentInsetBottom?: WithDefault<Double, 0>;
   contentInsetLeft?: WithDefault<Double, 0>;
-  topScrollEdgeHard?: WithDefault<boolean, false>;
+  topScrollEdgeEffect?: WithDefault<"none" | "hard" | "soft", "none">;
   topOverlayHeight?: WithDefault<Double, 0>;
   refreshEnabled?: WithDefault<boolean, false>;
   refreshing?: WithDefault<boolean, false>;

package/src/ScrollEdgeEffect.ts

@@ -0,0 +1,4 @@
+export enum ScrollEdgeEffect {
+  Hard = "hard",
+  Soft = "soft",
+}

package/src/index.tsx

@@ -27,3 +27,5 @@ export type PagerViewOnPageSelectedEvent =
 
 export type PageScrollStateChangedNativeEvent =
   ReactNative.NativeSyntheticEvent<PageScrollStateChangedNativeEventData>;
+
+export { ScrollEdgeEffect } from './ScrollEdgeEffect';

package/src/index.web.tsx

@@ -11,3 +11,5 @@ export type {
 export * from "./usePagerView";
 export * from "./CollapsiblePagerView.web";
 export * from "./NativeScroller.web";
+
+export { ScrollEdgeEffect } from "./ScrollEdgeEffect";