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

package/ios/RNCNativeScrollerComponentView.mm

@@ -8,6 +8,25 @@
 
 using namespace facebook::react;
 
+static void RNCNativeScrollerHomeVisualLog(NSString *phase, UIScrollView *scrollView)
+{
+#if DEBUG
+  Class logClass = NSClassFromString(@"ReactNativeNativeLogger.OneKeyLog");
+  if (logClass == nil) logClass = NSClassFromString(@"OneKeyLog");
+  SEL selector = NSSelectorFromString(@"debug::");
+  if (logClass == nil || ![logClass respondsToSelector:selector]) return;
+  UIRefreshControl *control = scrollView.refreshControl;
+  NSString *message = [NSString stringWithFormat:
+    @"[IOS-HOME-VISUAL] epochMs=%.0f monoMs=%.0f phase=scroller-%@ scrollTag=%ld refresh=%d refreshing=%d scrollY=%.1f insetTop=%.1f",
+    [NSDate.date timeIntervalSince1970] * 1000, CACurrentMediaTime() * 1000,
+    phase, (long)scrollView.tag, control != nil, control.isRefreshing,
+    scrollView.contentOffset.y, scrollView.contentInset.top];
+  typedef void (*LogFunction)(id, SEL, NSString *, NSString *);
+  LogFunction logFunction = (LogFunction)[logClass methodForSelector:selector];
+  logFunction(logClass, selector, @"NativeScroller", message);
+#endif
+}
+
 @interface RNCNativeVerticalScrollView : UIScrollView
 @end
 @implementation RNCNativeVerticalScrollView
@@ -156,6 +175,7 @@ static Event RNCScrollerMetrics(UIScrollView *scroll, CGPoint velocity, CGPoint
     [_refreshControl addTarget:self action:@selector(refreshTriggered:)
              forControlEvents:UIControlEventValueChanged];
     _scrollView.refreshControl = _refreshControl;
+    RNCNativeScrollerHomeVisualLog(@"refresh-created", _scrollView);
   } else if (!next.refreshEnabled && _refreshControl != nil) {
     [_refreshControl endRefreshing];
     _scrollView.refreshControl = nil;
@@ -174,8 +194,10 @@ static Event RNCScrollerMetrics(UIScrollView *scroll, CGPoint velocity, CGPoint
     }
     if (next.refreshing && !_refreshControl.refreshing) {
       [_refreshControl beginRefreshing];
+      RNCNativeScrollerHomeVisualLog(@"refresh-begin-prop", _scrollView);
     } else if (!next.refreshing && (previous.refreshing || createdRefreshControl)) {
       [_refreshControl endRefreshing];
+      if (previous.refreshing) RNCNativeScrollerHomeVisualLog(@"refresh-end-prop", _scrollView);
     }
   }
 
@@ -196,7 +218,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 +232,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 +242,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 +258,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 +293,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;
   }
 }
 
@@ -378,6 +401,7 @@ static Event RNCScrollerMetrics(UIScrollView *scroll, CGPoint velocity, CGPoint
   const auto &props = *std::static_pointer_cast<const RNCNativeScrollerProps>(_props);
   if (!props.refreshEnabled || props.refreshing) return;
   _refreshEventSentForDrag = YES;
+  RNCNativeScrollerHomeVisualLog(@"refresh-native-trigger", _scrollView);
   if (_eventEmitter) {
     std::static_pointer_cast<const RNCNativeScrollerEventEmitter>(_eventEmitter)->onRefresh({});
   }
@@ -522,6 +546,7 @@ static Event RNCScrollerMetrics(UIScrollView *scroll, CGPoint velocity, CGPoint
 - (void)setRefreshing:(BOOL)refreshing
 {
   if (_recycled || _refreshControl == nil) return;
+  RNCNativeScrollerHomeVisualLog(refreshing ? @"refresh-command-start" : @"refresh-command-stop", _scrollView);
   if (refreshing) {
     if (!_refreshControl.refreshing) [_refreshControl beginRefreshing];
   } else {

package/ios/tests/RNCCollapsiblePagerFirstFrameTests.mm

@@ -1,6 +1,7 @@
 #import <XCTest/XCTest.h>
 #import "RNCCollapsiblePagerViewComponentView.h"
 #import "RNCNativeScrollerComponentView.h"
+#import <react/renderer/components/pagerview/Props.h>
 #import <react/renderer/mounting/MountingTransaction.h>
 
 using namespace facebook::react;
@@ -22,6 +23,10 @@ using namespace facebook::react;
 - (void)updateHeaderSettledStateForceBusy:(BOOL)forceBusy;
 - (void)preparePageForHorizontalTransitionAtIndex:(NSInteger)index;
 - (void)applyInsetsToScrollView:(UIScrollView *)scrollView pageIndex:(NSInteger)index restore:(BOOL)restore;
+- (void)updateProps:(const Props::Shared &)props oldProps:(const Props::Shared &)oldProps;
+- (void)mountChildComponentView:(UIView<RCTComponentViewProtocol> *)childComponentView index:(NSInteger)index;
+- (CGFloat)effectiveTopOverlayHeight;
+- (void)updateRefreshControlForScrollView:(UIScrollView *)scrollView;
 @end
 
 @interface RNCNativeScrollerComponentView (ScrollCommandTesting)
@@ -34,6 +39,125 @@ using namespace facebook::react;
 
 @implementation RNCCollapsiblePagerFirstFrameTests
 
+- (void)testPendingLocalOverlayReservesManagedScrollerInsetBeforeSlotRebuild
+{
+  RNCCollapsiblePagerViewComponentView *pager =
+    [[RNCCollapsiblePagerViewComponentView alloc] initWithFrame:CGRectMake(0, 0, 320, 844)];
+  UIWindow *window = [[UIWindow alloc] initWithFrame:pager.frame];
+  UIViewController *root = [UIViewController new];
+  window.rootViewController = root;
+  [root.view addSubview:pager];
+  window.hidden = NO;
+  [self addTeardownBlock:^{
+    [pager prepareForRecycle];
+    window.hidden = YES;
+  }];
+
+  auto baseline = std::make_shared<RNCCollapsiblePagerViewProps>();
+  baseline->nativeSmoothHeaderScrollEnabled = true;
+  baseline->headerHeight = 120;
+  baseline->stickyHeaderHeight = 44;
+  baseline->pageKeys = "[\"page-0\"]";
+  [pager updateProps:baseline oldProps:nullptr];
+
+  UIView *header = [[UIView alloc] initWithFrame:CGRectMake(0, 0, 320, 120)];
+  UIView *sticky = [[UIView alloc] initWithFrame:CGRectMake(0, 0, 320, 44)];
+  UIView *page = [[UIView alloc] initWithFrame:CGRectMake(0, 0, 320, 844)];
+  RNCNativeScrollerComponentView *scroller = [RNCNativeScrollerComponentView new];
+  scroller.frame = page.bounds;
+  scroller.scrollView.frame = scroller.bounds;
+  scroller.scrollView.contentSize = CGSizeMake(320, 1500);
+  [page addSubview:scroller];
+  [pager mountChildComponentView:(id)header index:0];
+  [pager mountChildComponentView:(id)sticky index:1];
+  [pager mountChildComponentView:(id)page index:2];
+  [root.view layoutIfNeeded];
+  [pager layoutIfNeeded];
+  XCTestExpectation *settled = [self expectationWithDescription:@"Baseline slots and observer settled"];
+  dispatch_async(dispatch_get_main_queue(), ^{ [settled fulfill]; });
+  [self waitForExpectations:@[settled] timeout:1];
+  [pager attachScrollObserverForCurrentPage];
+  UIScrollView *ownedScroll = scroller.scrollView;
+  XCTAssertEqual([pager valueForKey:@"observedScrollView"], ownedScroll);
+  XCTAssertEqualWithAccuracy(ownedScroll.contentInset.top, 164, 0.01);
+  [scroller scrollTo:0 y:40 - ownedScroll.contentInset.top animated:NO];
+  [pager setValue:@40 forKey:@"headerOffset"];
+  CGFloat initialLogicalOffset = ownedScroll.contentOffset.y + ownedScroll.contentInset.top;
+  XCTAssertEqualWithAccuracy(initialLogicalOffset, 40, 0.01);
+
+  auto hard = std::make_shared<RNCCollapsiblePagerViewProps>();
+  hard->nativeSmoothHeaderScrollEnabled = true;
+  hard->headerHeight = 120;
+  hard->stickyHeaderHeight = 44;
+  hard->pageKeys = "[\"page-0\"]";
+  hard->topScrollEdgeEffect = RNCCollapsiblePagerViewTopScrollEdgeEffect::Hard;
+  hard->topOverlayHeight = 162;
+  [pager updateProps:hard oldProps:baseline];
+  XCTAssertNil([pager valueForKey:@"topOverlayView"]);
+  XCTAssertEqual([pager valueForKey:@"observedScrollView"], ownedScroll);
+  XCTAssertEqualWithAccuracy([pager effectiveTopOverlayHeight], 162, 0.01);
+  XCTAssertEqualWithAccuracy(ownedScroll.contentInset.top, 326, 0.01);
+  XCTAssertEqualWithAccuracy(ownedScroll.contentOffset.y + ownedScroll.contentInset.top,
+                             initialLogicalOffset, 0.01);
+  [self finishMount:pager];
+  XCTAssertNil([pager valueForKey:@"topOverlayView"]);
+  XCTAssertTrue([[pager valueForKey:@"deferTopEdgeSlotRebuild"] boolValue]);
+
+  UIView *overlay = [[UIView alloc] initWithFrame:CGRectMake(0, 0, 320, 162)];
+  [pager mountChildComponentView:(id)overlay index:2];
+  XCTAssertNil([pager valueForKey:@"topOverlayView"]);
+  [self finishMount:pager];
+  UIView *overlayHost = [pager valueForKey:@"topOverlayHostView"];
+  XCTAssertEqual([pager valueForKey:@"topOverlayView"], overlay);
+  XCTAssertEqual(overlay.superview, overlayHost);
+  XCTAssertEqual(overlay.window, window);
+  XCTAssertEqualWithAccuracy(ownedScroll.contentInset.top, 326, 0.01);
+  XCTAssertEqualWithAccuracy(ownedScroll.contentOffset.y + ownedScroll.contentInset.top,
+                             initialLogicalOffset, 0.01);
+  XCTestExpectation *rebuilt = [self expectationWithDescription:@"Post-mount observer restored"];
+  dispatch_async(dispatch_get_main_queue(), ^{ [rebuilt fulfill]; });
+  [self waitForExpectations:@[rebuilt] timeout:1];
+  [pager attachScrollObserverForCurrentPage];
+  XCTAssertEqual([pager valueForKey:@"topOverlayView"], overlay);
+  XCTAssertEqual([pager valueForKey:@"observedScrollView"], ownedScroll);
+  XCTAssertEqualWithAccuracy(ownedScroll.contentInset.top, 326, 0.01);
+  XCTAssertEqualWithAccuracy(ownedScroll.contentOffset.y + ownedScroll.contentInset.top,
+                             initialLogicalOffset, 0.01);
+
+  UIRefreshControl *control = [UIRefreshControl new];
+  ownedScroll.refreshControl = control;
+  [pager updateRefreshControlForScrollView:ownedScroll];
+  UIEdgeInsets refreshingInset = ownedScroll.contentInset;
+  refreshingInset.top += 60;
+  ownedScroll.contentInset = refreshingInset;
+  auto disabled = std::make_shared<RNCCollapsiblePagerViewProps>();
+  disabled->nativeSmoothHeaderScrollEnabled = true;
+  disabled->headerHeight = 120;
+  disabled->stickyHeaderHeight = 44;
+  disabled->pageKeys = "[\"page-0\"]";
+  disabled->topScrollEdgeEffect = RNCCollapsiblePagerViewTopScrollEdgeEffect::None;
+  disabled->topOverlayHeight = 0;
+  [pager updateProps:disabled oldProps:hard];
+  XCTAssertEqual(ownedScroll.refreshControl, control);
+  XCTAssertEqualWithAccuracy([pager effectiveTopOverlayHeight], 0, 0.01);
+  XCTAssertEqualWithAccuracy(ownedScroll.contentInset.top, 224, 0.01);
+}
+
+- (void)testPendingLocalOverlayHeightDoesNotOverrideExternalGeometry
+{
+  RNCCollapsiblePagerViewComponentView *pager = [RNCCollapsiblePagerViewComponentView new];
+  auto props = std::make_shared<RNCCollapsiblePagerViewProps>();
+  props->topScrollEdgeEffect = RNCCollapsiblePagerViewTopScrollEdgeEffect::Hard;
+  props->topOverlayHeight = 162;
+  props->externalTopOverlayTag = 999;
+  [pager updateProps:props oldProps:nullptr];
+  XCTAssertNil([pager valueForKey:@"topOverlayView"]);
+  XCTAssertEqualWithAccuracy([pager effectiveTopOverlayHeight], 0, 0.01);
+  [pager setValue:@64 forKey:@"externalTopOverlayHeight"];
+  XCTAssertEqualWithAccuracy([pager effectiveTopOverlayHeight], 64, 0.01);
+  [pager prepareForRecycle];
+}
+
 - (void)testHeaderSettledAtTopRequiresCurrentQuietOwnerAndCancelsDetachedTimer
 {
   RNCCollapsiblePagerViewComponentView *pager = [self pagerWithPageCount:1];

package/ios/tests/RNCCollapsiblePagerHitTestTests.mm

@@ -8,6 +8,7 @@ using namespace facebook::react;
 
 @interface RNCCollapsiblePagerViewComponentView (ScrollEdgeTesting)
 - (void)updateTopScrollEdgeForScrollView:(UIScrollView *)scrollView;
+- (void)updateScrollEdgeContentMasks;
 @end
 
 @interface RNCCollapsiblePagerHitTestTests : XCTestCase
@@ -90,9 +91,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 +109,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"];
@@ -126,4 +152,163 @@ using namespace facebook::react;
   }
 }
 
+- (void)testPinnedHardEdgeHidesOnlyTopSeparatorCoverUntilUnpinned
+{
+  if (@available(iOS 26.0, *)) {
+    UIWindow *window = [[UIWindow alloc] initWithFrame:self.root.bounds];
+    [window addSubview:self.root];
+    [self addTeardownBlock:^{ window.hidden = YES; }];
+    window.hidden = NO;
+    UIScrollView *scrollView = [[UIScrollView alloc] initWithFrame:self.pager.bounds];
+    [self.pager addSubview:scrollView];
+    [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"];
+    [self.pager setValue:self.sticky forKey:@"stickyHeaderView"];
+    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;
+    UIView *pinnedHost = [self.pager valueForKey:@"pinnedStickyHostView"];
+    pinnedHost.frame = CGRectMake(0, 64, 320, 44);
+    pinnedHost.hidden = NO;
+    [scrollView addSubview:pinnedHost];
+
+    [self.pager updateTopScrollEdgeForScrollView:scrollView];
+    UIScrollEdgeElementContainerInteraction *topInteraction =
+      [self.pager valueForKey:@"topEdgeInteraction"];
+    CALayer *topCover = [self.pager valueForKey:@"topEdgeSeparatorCover"];
+    XCTAssertNotNil(topInteraction);
+    XCTAssertNotNil(topCover);
+    XCTAssertFalse(topCover.hidden);
+    XCTAssertEqual(scrollView.topEdgeEffect.style, UIScrollEdgeEffectStyle.hardStyle);
+
+    [self.pager setValue:@YES forKey:@"stickyHeaderIsPinned"];
+    [self.pager updateTopScrollEdgeForScrollView:scrollView];
+    UIScrollEdgeElementContainerInteraction *stickyInteraction =
+      [self.pager valueForKey:@"stickyEdgeInteraction"];
+    CALayer *stickyCover = [self.pager valueForKey:@"stickyEdgeSeparatorCover"];
+    XCTAssertEqual([self.pager valueForKey:@"topEdgeInteraction"], topInteraction);
+    XCTAssertEqual(topInteraction.scrollView, scrollView);
+    XCTAssertEqual(stickyInteraction.scrollView, scrollView);
+    XCTAssertEqual([self.pager valueForKey:@"topEdgeSeparatorCover"], topCover);
+    XCTAssertTrue(topCover.hidden);
+    XCTAssertNotNil(stickyCover);
+    XCTAssertFalse(stickyCover.hidden);
+    XCTAssertEqual(scrollView.topEdgeEffect.style, UIScrollEdgeEffectStyle.hardStyle);
+
+    [self.pager setValue:@NO forKey:@"stickyHeaderIsPinned"];
+    [self.pager updateTopScrollEdgeForScrollView:scrollView];
+    XCTAssertEqual([self.pager valueForKey:@"topEdgeInteraction"], topInteraction);
+    XCTAssertEqual([self.pager valueForKey:@"topEdgeSeparatorCover"], topCover);
+    XCTAssertFalse(topCover.hidden);
+    XCTAssertEqual(scrollView.topEdgeEffect.style, UIScrollEdgeEffectStyle.hardStyle);
+    [self.root removeFromSuperview];
+  } else {
+    XCTSkip(@"Scroll-edge interactions require iOS 26 or newer");
+  }
+}
+
+- (void)testIOS27LocalHardThemeBackgroundTracksMaskedHeaderGeometry
+{
+  if (@available(iOS 27.0, *)) {
+    UIWindowScene *scene = nil;
+    for (UIScene *connectedScene in UIApplication.sharedApplication.connectedScenes) {
+      if ([connectedScene isKindOfClass:UIWindowScene.class]) {
+        scene = (UIWindowScene *)connectedScene;
+        break;
+      }
+    }
+    XCTAssertNotNil(scene);
+    UIWindow *window = [[UIWindow alloc] initWithWindowScene:scene];
+    window.frame = self.root.bounds;
+    [window addSubview:self.root];
+    window.hidden = NO;
+    [self addTeardownBlock:^{ window.hidden = YES; }];
+    [self.pager layoutIfNeeded];
+    self.pager.backgroundColor = [UIColor colorWithWhite:0.2 alpha:1];
+    UIView *container = [self.pager valueForKey:@"containerView"];
+    container.frame = self.pager.bounds;
+    UIScrollView *scroll = [[UIScrollView alloc] initWithFrame:container.bounds];
+    scroll.contentInsetAdjustmentBehavior = UIScrollViewContentInsetAdjustmentNever;
+    scroll.alwaysBounceVertical = YES;
+    scroll.contentSize = CGSizeMake(320, 1200);
+    scroll.contentInset = UIEdgeInsetsMake(50 + 100 + 20, 0, 0, 0);
+    [container insertSubview:scroll atIndex:0];
+    UIView *sharedHost = [self.pager valueForKey:@"sharedHeaderHostView"];
+    for (UIView *child in sharedHost.subviews.copy) [child removeFromSuperview];
+    [scroll addSubview:sharedHost];
+    sharedHost.frame = CGRectMake(0, -120, 320, 120);
+    UIView *header = [[UIView alloc] initWithFrame:CGRectMake(0, 0, 320, 100)];
+    [sharedHost addSubview:header];
+    [self.pager setValue:header forKey:@"headerView"];
+    UIView *overlayHost = [self.pager valueForKey:@"topOverlayHostView"];
+    overlayHost.frame = CGRectMake(0, 0, 320, 50);
+    overlayHost.hidden = NO;
+    UIView *overlay = [[UIView alloc] initWithFrame:overlayHost.bounds];
+    [overlayHost addSubview:overlay];
+    [self.pager setValue:overlay forKey:@"topOverlayView"];
+    [self.pager setValue:@50 forKey:@"topOverlayHeight"];
+    [self.pager setValue:@100 forKey:@"headerHeight"];
+    [self.pager setValue:@20 forKey:@"stickyHeaderHeight"];
+    [self.pager setValue:@YES forKey:@"nativeSmoothHeaderScrollEnabled"];
+    [self.pager setValue:@YES forKey:@"topScrollEdgeEnabled"];
+    [self.pager setValue:@(static_cast<NSInteger>(RNCCollapsiblePagerViewTopScrollEdgeEffect::Hard))
+                 forKey:@"topScrollEdgeEffect"];
+    [self.pager setValue:scroll forKey:@"observedScrollView"];
+    [self.pager setValue:scroll forKey:@"sharedHeaderScrollView"];
+    scroll.contentOffset = CGPointMake(0, -170);
+    [self.pager updateTopScrollEdgeForScrollView:scroll];
+    CALayer *layer = [self.pager valueForKey:@"topOverlayThemeBackgroundLayer"];
+    XCTAssertNotNil(layer);
+    XCTAssertEqual(layer.superlayer, overlayHost.layer);
+    XCTAssertEqualWithAccuracy(layer.opacity, 1, 0.01);
+    XCTAssertEqual(scroll.topEdgeEffect.style, UIScrollEdgeEffectStyle.hardStyle);
+    XCTAssertEqual([self.pager valueForKey:@"topEdgeScrollView"], scroll);
+
+    scroll.contentOffset = CGPointMake(0, -120);
+    [self.pager updateScrollEdgeContentMasks];
+    XCTAssertEqualWithAccuracy(layer.opacity, 0.5, 0.01);
+    scroll.contentOffset = CGPointMake(0, -70);
+    [self.pager updateScrollEdgeContentMasks];
+    XCTAssertEqualWithAccuracy(layer.opacity, 0, 0.01);
+    scroll.contentOffset = CGPointMake(0, -210);
+    [self.pager updateScrollEdgeContentMasks];
+    XCTAssertEqualWithAccuracy(layer.opacity, 1, 0.01);
+
+    scroll.contentInset = UIEdgeInsetsMake(230, 0, 0, 0);
+    scroll.contentOffset = CGPointMake(0, -230);
+    [self.pager updateScrollEdgeContentMasks];
+    XCTAssertEqualWithAccuracy(layer.opacity, 1, 0.01);
+    self.pager.backgroundColor = UIColor.whiteColor;
+    [self.pager updateScrollEdgeContentMasks];
+    XCTAssertTrue(CGColorEqualToColor(layer.backgroundColor, UIColor.whiteColor.CGColor));
+
+    [self.pager updateTopScrollEdgeForScrollView:nil];
+    XCTAssertEqual([self.pager valueForKey:@"topOverlayThemeBackgroundLayer"], layer);
+    XCTAssertEqualWithAccuracy(layer.opacity, 1, 0.01);
+    [self.pager setValue:@YES forKey:@"topScrollEdgeEnabled"];
+    [self.pager updateTopScrollEdgeForScrollView:scroll];
+    [self.pager setValue:@123 forKey:@"externalTopOverlayTag"];
+    [self.pager updateScrollEdgeContentMasks];
+    XCTAssertNil([self.pager valueForKey:@"topOverlayThemeBackgroundLayer"]);
+    [self.pager setValue:@0 forKey:@"externalTopOverlayTag"];
+    [self.pager updateTopScrollEdgeForScrollView:scroll];
+    XCTAssertEqual(scroll.topEdgeEffect.style, UIScrollEdgeEffectStyle.hardStyle);
+    [self.pager setValue:@NO forKey:@"topScrollEdgeEnabled"];
+    [self.pager updateTopScrollEdgeForScrollView:scroll];
+    XCTAssertNil([self.pager valueForKey:@"topOverlayThemeBackgroundLayer"]);
+    [self.pager setValue:@YES forKey:@"topScrollEdgeEnabled"];
+    [self.pager updateTopScrollEdgeForScrollView:scroll];
+    XCTAssertNotNil([self.pager valueForKey:@"topOverlayThemeBackgroundLayer"]);
+    [self.pager prepareForRecycle];
+    XCTAssertNil([self.pager valueForKey:@"topOverlayThemeBackgroundLayer"]);
+  } else {
+    XCTSkip(@"The theme background applies only on iOS 27 or newer");
+  }
+}
+
 @end

package/ios/tests/RNCCollapsiblePagerRefreshControlTests.mm

@@ -60,6 +60,56 @@
   XCTAssertEqualWithAccuracy(control.bounds.origin.x, 3, 0.001);
 }
 
+- (void)testRefreshLayerWindowGeometryStartsBelowFixedOverlay
+{
+  for (NSNumber *overlayHeight in @[@0, @162]) {
+    CGFloat fixedHeight = overlayHeight.doubleValue;
+    CGFloat baseInset = fixedHeight + 180 + 44;
+    UIWindow *window = [[UIWindow alloc] initWithFrame:CGRectMake(0, 0, 390, 844)];
+    UIViewController *root = [UIViewController new];
+    window.rootViewController = root;
+    UIScrollView *scroll = [[UIScrollView alloc] initWithFrame:window.bounds];
+    scroll.contentInsetAdjustmentBehavior = UIScrollViewContentInsetAdjustmentNever;
+    scroll.contentSize = CGSizeMake(390, 1500);
+    scroll.contentInset = UIEdgeInsetsMake(baseInset + 60, 0, 0, 0);
+    scroll.contentOffset = CGPointMake(0, -baseInset - 102);
+    [root.view addSubview:scroll];
+    UIView *overlay = [[UIView alloc] initWithFrame:CGRectMake(0, 0, 390, fixedHeight)];
+    [root.view addSubview:overlay];
+    UIRefreshControl *control = [UIRefreshControl new];
+    scroll.refreshControl = control;
+    window.hidden = NO;
+    [root.view layoutIfNeeded];
+    [control layoutIfNeeded];
+    // Match the control's window position recorded during a real refresh drag.
+    control.frame = [scroll convertRect:CGRectMake(0, baseInset, 390, 60)
+                                fromView:window];
+
+    RNCCollapsiblePagerViewComponentView *pager = [self pagerWithHeader:180];
+    [pager setValue:@(fixedHeight) forKey:@"topOverlayHeight"];
+    if (fixedHeight > 0) [pager setValue:overlay forKey:@"topOverlayView"];
+    [pager updateRefreshControlForScrollView:scroll];
+    [CATransaction flush];
+    CALayer *firstChild = control.layer.sublayers.firstObject;
+    XCTAssertNotNil(firstChild);
+    XCTAssertEqual(control.window, window);
+    CGRect overlayWindow = [overlay convertRect:overlay.bounds toView:window];
+    CGRect controlWindow = [control convertRect:control.bounds toView:window];
+    CGRect childWindow = [firstChild convertRect:firstChild.bounds toLayer:window.layer];
+    XCTAssertEqualWithAccuracy(CGRectGetMinY(controlWindow), baseInset, 0.01);
+    XCTAssertEqualWithAccuracy(CGRectGetMinY(childWindow),
+      CGRectGetMaxY(overlayWindow), 0.01);
+    XCTAssertEqualWithAccuracy(scroll.contentInset.top, baseInset + 60, 0.01);
+    [pager updateRefreshControlForScrollView:scroll];
+    XCTAssertEqualWithAccuracy(CGRectGetMinY(
+      [firstChild convertRect:firstChild.bounds toLayer:window.layer]),
+      CGRectGetMaxY(overlayWindow), 0.01);
+    [pager releaseRefreshControlForScrollView:scroll];
+    XCTAssertTrue(CATransform3DIsIdentity(control.layer.sublayerTransform));
+    window.hidden = YES;
+  }
+}
+
 - (void)testUIKitSizeChangesAndRefreshCycleDoNotAccumulateOffset
 {
   RNCCollapsiblePagerViewComponentView *pager = [self pagerWithHeader:64];

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

@@ -23,7 +23,7 @@ const pageKey = (child, index) => {
  */
 export class CollapsiblePagerView extends React.PureComponent {
   state = {
-    topOverlayHeight: 0,
+    topOverlayHeight: null,
     selectedPage: clampedPageIndex(this.props.initialPage ?? 0, React.Children.toArray(this.props.children).length),
     transientRetainedPages: []
   };
@@ -41,7 +41,14 @@ export class CollapsiblePagerView extends React.PureComponent {
   componentDidMount() {
     this.notifyMountedPagesChanged();
   }
-  componentDidUpdate() {
+  componentDidUpdate(previousProps) {
+    const previousOverlayEnabled = previousProps.topOverlay != null && (previousProps.topScrollEdgeEffect === "hard" || previousProps.topScrollEdgeEffect === "soft");
+    const overlayEnabled = this.props.topOverlay != null && (this.props.topScrollEdgeEffect === "hard" || this.props.topScrollEdgeEffect === "soft");
+    if (previousOverlayEnabled && !overlayEnabled && this.state.topOverlayHeight !== null) {
+      this.setState({
+        topOverlayHeight: null
+      });
+    }
     const pageCount = this.pages().length;
     const selectedPage = clampedPageIndex(this.state.selectedPage, pageCount);
     if (selectedPage !== this.state.selectedPage) {
@@ -197,6 +204,7 @@ export class CollapsiblePagerView extends React.PureComponent {
       headerHeight,
       stickyHeaderHeight,
       topOverlay,
+      topOverlayHeightHint,
       externalTopOverlayTag,
       topScrollEdgeEffect,
       topOverlayColorScheme,
@@ -217,8 +225,9 @@ 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 initialTopOverlayHeight = typeof topOverlayHeightHint === "number" && Number.isFinite(topOverlayHeightHint) ? Math.max(0, Math.ceil(topOverlayHeightHint)) : 0;
     const pageKeys = pages.map(pageKey);
     const retained = new Set(this.mountedPages(pages.length));
     const deducedLayoutDirection = !layoutDirection || layoutDirection === "locale" ? I18nManager.isRTL ? "rtl" : "ltr" : layoutDirection;
@@ -243,9 +252,9 @@ 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,
-      topOverlayHeight: hasTopOverlay ? this.state.topOverlayHeight : 0,
+      topScrollEdgeEffect: scrollEdgeEnabled ? topScrollEdgeEffect : "none",
+      topOverlayColorScheme: scrollEdgeEnabled ? topOverlayColorScheme : undefined,
+      topOverlayHeight: hasTopOverlay ? this.state.topOverlayHeight ?? initialTopOverlayHeight : 0,
       externalTopOverlayTag: supportsTopScrollEdge && !hasTopOverlay ? externalTopOverlayTag ?? 0 : 0,
       nativeSmoothHeaderScrollEnabled: nativeSmoothHeaderScrollEnabled,
       pageKeys: JSON.stringify(pageKeys),