@onekeyfe/react-native-pager-view 6.7.0-alpha.327 → 6.7.0-alpha.335

package/lib/module/NativeScroller.web.js

@@ -6,20 +6,33 @@ import { jsx as _jsx } from "react/jsx-runtime";
 export const NativeScroller = /*#__PURE__*/React.forwardRef(function NativeScroller(inputProps, ref) {
   const {
     dataSet,
-    pagerScrollKey: _pagerScrollKey,
+    pagerScrollKey,
     topOverlay: _topOverlay,
     topScrollEdgeEffect: _topScrollEdgeEffect,
     ...props
   } = inputProps;
+  const scrollRef = React.useRef(null);
+  const setRef = React.useCallback(node => {
+    scrollRef.current = node;
+    if (typeof ref === "function") ref(node);else if (ref) ref.current = node;
+  }, [ref]);
+  React.useLayoutEffect(() => {
+    const element = scrollRef.current?.getScrollableNode();
+    const EventConstructor = element?.ownerDocument?.defaultView?.Event;
+    if (EventConstructor) element.dispatchEvent(new EventConstructor("ok-collapsible-pager-scroll-key-changed", {
+      bubbles: true
+    }));
+  }, [pagerScrollKey]);
   const webDataProps = {
     dataSet: {
       ...dataSet,
-      collapsiblePagerScroll: "true"
+      collapsiblePagerScroll: "true",
+      collapsiblePagerScrollKey: pagerScrollKey ?? ""
     }
   };
   return /*#__PURE__*/_jsx(ScrollView, {
     ...props,
-    ref: ref,
+    ref: setRef,
     ...webDataProps
   });
 });

package/lib/module/WebCollapsiblePagerPage.js

@@ -0,0 +1,182 @@
+"use strict";
+
+import React from "react";
+import { jsx as _jsx } from "react/jsx-runtime";
+const PageContext = /*#__PURE__*/React.createContext(null);
+export function useWebCollapsiblePagerPage() {
+  return React.useContext(PageContext);
+}
+export function WebCollapsiblePagerPage({
+  children,
+  pageKey,
+  isFocused,
+  isRouteActive,
+  headerHeight,
+  stickyHeaderHeight,
+  onBridge,
+  onGeometryChange,
+  onScroll,
+  onUserInput
+}) {
+  const [owner, setOwner] = React.useState(null);
+  const ownerRef = React.useRef(null);
+  const [registered, setRegistered] = React.useState(null);
+  const registeredRef = React.useRef(registered);
+  const observerRef = React.useRef(null);
+  const observedContentRef = React.useRef(null);
+  const frameRef = React.useRef(null);
+  const disposedRef = React.useRef(false);
+  const [pendingRouteScrollTop, setPendingRouteScrollTop] = React.useState(null);
+  const [metrics, setMetrics] = React.useState({
+    width: 0,
+    height: 0,
+    scrollTop: 0
+  });
+  const inputsRef = React.useRef({
+    pageKey,
+    headerHeight,
+    stickyHeaderHeight,
+    onGeometryChange,
+    onScroll,
+    onUserInput
+  });
+  inputsRef.current = {
+    pageKey,
+    headerHeight,
+    stickyHeaderHeight,
+    onGeometryChange,
+    onScroll,
+    onUserInput
+  };
+  const measure = React.useCallback(() => {
+    frameRef.current = null;
+    if (disposedRef.current) return;
+    const current = ownerRef.current;
+    if (!current?.isConnected) return;
+    const ownerRect = current.getBoundingClientRect();
+    const candidate = registeredRef.current?.element;
+    const content = candidate?.isConnected && current.contains(candidate) ? candidate : null;
+    const contentRect = (content ?? current.firstElementChild)?.getBoundingClientRect();
+    const inputs = inputsRef.current;
+    const pinnedBottom = ownerRect.top + Math.max(0, inputs.headerHeight - current.scrollTop) + inputs.stickyHeaderHeight;
+    const visibleTop = Math.max(ownerRect.top, pinnedBottom, contentRect?.top ?? 0);
+    const next = {
+      width: current.clientWidth,
+      height: Math.max(0, ownerRect.bottom - visibleTop),
+      scrollTop: Math.max(0, pinnedBottom - (contentRect?.top ?? pinnedBottom))
+    };
+    setMetrics(previous => previous.width === next.width && previous.height === next.height && previous.scrollTop === next.scrollTop ? previous : next);
+    inputs.onGeometryChange(inputs.pageKey);
+  }, []);
+  const requestMeasure = React.useCallback(() => {
+    if (!disposedRef.current && frameRef.current === null) frameRef.current = requestAnimationFrame(measure);
+  }, [measure]);
+  const syncContentObservation = React.useCallback(() => {
+    const observer = observerRef.current;
+    const current = ownerRef.current;
+    if (!observer || !current) return;
+    const candidate = registeredRef.current?.element;
+    const content = candidate?.isConnected && current.contains(candidate) ? candidate : current.firstElementChild;
+    const next = typeof HTMLElement !== "undefined" && content instanceof HTMLElement ? content : null;
+    if (observedContentRef.current === next) return;
+    if (observedContentRef.current) observer.unobserve(observedContentRef.current);
+    observedContentRef.current = next;
+    if (next) observer.observe(next);
+  }, []);
+  const registerContent = React.useCallback((element, height) => {
+    const entry = {
+      element,
+      height: height !== undefined && Number.isFinite(height) && height >= 0 ? height : undefined
+    };
+    registeredRef.current = entry;
+    setRegistered(entry);
+    syncContentObservation();
+    requestMeasure();
+    return () => {
+      if (registeredRef.current !== entry) return;
+      registeredRef.current = null;
+      setRegistered(null);
+      syncContentObservation();
+      requestMeasure();
+    };
+  }, [requestMeasure, syncContentObservation]);
+  const bridge = React.useMemo(() => ({
+    setOwner: next => {
+      if (ownerRef.current === next) return;
+      ownerRef.current = next;
+      setOwner(next);
+      requestMeasure();
+    },
+    requestMeasure,
+    setPendingRouteScrollTop
+  }), [requestMeasure]);
+  React.useLayoutEffect(() => {
+    disposedRef.current = false;
+    return () => {
+      disposedRef.current = true;
+      if (frameRef.current !== null) cancelAnimationFrame(frameRef.current);
+      frameRef.current = null;
+    };
+  }, []);
+  React.useLayoutEffect(() => {
+    onBridge(pageKey, bridge);
+    return () => onBridge(pageKey, null);
+  }, [bridge, onBridge, pageKey]);
+  React.useLayoutEffect(() => {
+    if (!owner) return undefined;
+    const observer = new ResizeObserver(requestMeasure);
+    observerRef.current = observer;
+    observer.observe(owner);
+    syncContentObservation();
+    const handleScroll = () => {
+      if (ownerRef.current !== owner) return;
+      const inputs = inputsRef.current;
+      inputs.onScroll(inputs.pageKey, owner.scrollTop);
+      requestMeasure();
+    };
+    const handleKey = event => {
+      if (["ArrowUp", "ArrowDown", "PageUp", "PageDown", "Home", "End", " "].includes(event.key)) inputsRef.current.onUserInput(inputsRef.current.pageKey);
+    };
+    const handleUserInput = () => inputsRef.current.onUserInput(inputsRef.current.pageKey);
+    owner.addEventListener("scroll", handleScroll, {
+      passive: true
+    });
+    owner.addEventListener("touchstart", handleUserInput, {
+      passive: true
+    });
+    owner.addEventListener("pointerdown", handleUserInput);
+    owner.addEventListener("keydown", handleKey);
+    owner.addEventListener("ok-collapsible-pager-user-scroll", handleUserInput);
+    owner.addEventListener("ok-collapsible-pager-insets-changed", requestMeasure);
+    requestMeasure();
+    return () => {
+      observer.disconnect();
+      observerRef.current = null;
+      observedContentRef.current = null;
+      owner.removeEventListener("scroll", handleScroll);
+      owner.removeEventListener("touchstart", handleUserInput);
+      owner.removeEventListener("pointerdown", handleUserInput);
+      owner.removeEventListener("keydown", handleKey);
+      owner.removeEventListener("ok-collapsible-pager-user-scroll", handleUserInput);
+      owner.removeEventListener("ok-collapsible-pager-insets-changed", requestMeasure);
+      if (frameRef.current !== null) cancelAnimationFrame(frameRef.current);
+      frameRef.current = null;
+    };
+  }, [owner, requestMeasure, syncContentObservation]);
+  React.useLayoutEffect(requestMeasure, [isFocused, isRouteActive, headerHeight, stickyHeaderHeight, requestMeasure]);
+  const value = React.useMemo(() => ({
+    isFocused,
+    isRouteActive,
+    owner,
+    content: registered?.element.isConnected && owner?.contains(registered.element) ? registered.element : null,
+    contentHeight: registered?.height,
+    ...metrics,
+    pendingRouteScrollTop,
+    registerContent
+  }), [isFocused, isRouteActive, owner, registered, metrics, pendingRouteScrollTop, registerContent]);
+  return /*#__PURE__*/_jsx(PageContext.Provider, {
+    value: value,
+    children: children
+  });
+}
+//# sourceMappingURL=WebCollapsiblePagerPage.js.map

package/lib/module/index.js

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

package/lib/module/index.native.js

@@ -0,0 +1,9 @@
+"use strict";
+
+import { PagerView } from "./PagerView";
+export default PagerView;
+export * from "./usePagerView.js";
+export * from "./CollapsiblePagerView";
+export * from "./NativeScroller";
+export { ScrollEdgeEffect } from "./ScrollEdgeEffect.js";
+//# sourceMappingURL=index.native.js.map

package/lib/module/index.web.js

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

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

@@ -67,6 +67,8 @@ export interface CollapsiblePagerViewProps extends Omit<NativeProps, "children"
     stickyHeaderHeight: number;
     /** Fixed content above the collapsible header on iOS 26 and newer. */
     topOverlay?: React.ReactNode;
+    /** Known overlay height to reserve until its first layout measurement. */
+    topOverlayHeightHint?: number;
     /** Existing fixed header shared with a parent pager on iOS 26 and newer. */
     externalTopOverlayTag?: number;
     /** Selects UIKit's top scroll-edge effect on iOS 26 and newer. */
@@ -102,7 +104,7 @@ export interface CollapsiblePagerViewProps extends Omit<NativeProps, "children"
 type State = {
     selectedPage: number;
     transientRetainedPages: readonly number[];
-    topOverlayHeight: number;
+    topOverlayHeight: number | null;
 };
 /**
  * Pager variant whose vertical header coordination is performed by the native
@@ -120,7 +122,7 @@ export declare class CollapsiblePagerView extends React.PureComponent<Collapsibl
     private nativePagerScrollState;
     private nativeTabCommandQueuedDuringScroll;
     componentDidMount(): void;
-    componentDidUpdate(): void;
+    componentDidUpdate(previousProps: CollapsiblePagerViewProps): void;
     setPage: (selectedPage: number) => void;
     setPageWithoutAnimation: (selectedPage: number) => void;
     scrollToPageTop: (options?: Readonly<{

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

@@ -38,8 +38,9 @@ export type CollapsiblePagerMountState = Readonly<{
 export interface CollapsiblePagerViewProps extends Omit<WebCollapsiblePagerNativeProps, "children" | "headerHeight" | "stickyHeaderHeight" | "pageKeys" | "retainedPages" | "layoutDirection"> {
     header: React.ReactNode;
     stickyHeader: React.ReactNode;
-    headerHeight: number;
-    stickyHeaderHeight: number;
+    headerHeight?: number;
+    stickyHeaderHeight?: number;
+    isActive?: boolean;
     topOverlay?: React.ReactNode;
     topScrollEdgeEffect?: `${ScrollEdgeEffect}`;
     topOverlayColorScheme?: "light" | "dark";
@@ -53,16 +54,42 @@ type State = {
     selectedPage: number;
     animateTransition: boolean;
 };
+type WebRouteTarget = Readonly<{
+    key: string;
+    identity: string;
+    owner: HTMLElement;
+    generation: number;
+    top: number;
+}>;
 /** Web counterpart of the native collapsible pager contract. */
 export declare class CollapsiblePagerView extends React.PureComponent<CollapsiblePagerViewProps, State> {
     state: State;
     private root;
     private track;
+    private headerSlot;
+    private stickySlot;
+    private cssTimelineSupported;
+    private overlayTouch;
     private touchStartX;
     private touchStartY;
     private horizontalTouch;
     private pageOffsets;
     private pageHosts;
+    private pageScrollIdentities;
+    private pageBridges;
+    private ownerRecords;
+    private ownerGeneration;
+    private lastRawTops;
+    private routeTarget;
+    private measuredHeaderHeight;
+    private measuredStickyHeight;
+    private headerMeasured;
+    private stickyMeasured;
+    private headerContent;
+    private stickyContent;
+    private chromeObserver;
+    private chromeMeasureFrame;
+    private disposed;
     private sharedHeaderOffset;
     private selectionRestoreToken;
     private bodyAlignment;
@@ -74,9 +101,32 @@ export declare class CollapsiblePagerView extends React.PureComponent<Collapsibl
     private pageScrollState;
     private configuredScrollElement;
     private readonly timelineName;
+    private get headerHeight();
+    private get hasExplicitHeaderHeight();
+    private get stickyHeaderHeight();
+    private get hasExplicitStickyHeaderHeight();
+    getSnapshotBeforeUpdate(previousProps: CollapsiblePagerViewProps): Readonly<{
+        key: string;
+        identity: string;
+        owner: HTMLElement;
+        generation: number;
+        top: number;
+    }> | null;
     componentDidMount(): void;
-    componentDidUpdate(previousProps: CollapsiblePagerViewProps): void;
+    componentDidUpdate(previousProps: CollapsiblePagerViewProps, _previousState: State, routeSnapshot: WebRouteTarget | null): void;
     componentWillUnmount(): void;
+    private setHeaderContent;
+    private setStickyContent;
+    private observeChrome;
+    private scheduleChromeMeasurement;
+    private onPageBridge;
+    private setRouteTarget;
+    private syncPageOwner;
+    private captureRouteTarget;
+    restoreScrollPosition: () => boolean;
+    private onPageScroll;
+    private onPageGeometryChange;
+    private onPageUserInput;
     setPage: (selectedPage: number) => void;
     setPageWithoutAnimation: (selectedPage: number) => void;
     scrollToPageTop: (options?: Readonly<{
@@ -101,9 +151,20 @@ export declare class CollapsiblePagerView extends React.PureComponent<Collapsibl
     private onTrackTransitionEnd;
     private setTrack;
     private pageScrollElement;
+    private setRoot;
+    private overlayTarget;
+    private nestedScrollConsumes;
+    private scrollOverlayOwner;
+    private onOverlayWheel;
+    private onOverlayTouchStart;
+    private onOverlayTouchMove;
+    private onOverlayTouchEnd;
+    private synchronizeScrollOwnerIdentity;
+    private onScrollOwnerIdentityChanged;
     private notifyInsetsChanged;
     private restoreConfiguredScrollElement;
     private configureActiveScrollElement;
+    private syncFallbackHeader;
     private scheduleScrollConfiguration;
     private takeOverVerticalScroll;
     private onListScrollCommandAccepted;

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

@@ -0,0 +1,42 @@
+import React from "react";
+export type WebCollapsiblePagerPageState = Readonly<{
+    isFocused: boolean;
+    isRouteActive: boolean;
+    owner: HTMLElement | null;
+    content: HTMLElement | null;
+    contentHeight?: number;
+    width: number;
+    height: number;
+    scrollTop: number;
+    pendingRouteScrollTop: number | null;
+    registerContent: (element: HTMLElement, explicitHeight?: number) => () => void;
+}>;
+export type WebCollapsiblePagerPageBridge = Readonly<{
+    setOwner: (owner: HTMLElement | null) => void;
+    requestMeasure: () => void;
+    setPendingRouteScrollTop: (top: number | null) => void;
+}>;
+export declare function useWebCollapsiblePagerPage(): Readonly<{
+    isFocused: boolean;
+    isRouteActive: boolean;
+    owner: HTMLElement | null;
+    content: HTMLElement | null;
+    contentHeight?: number;
+    width: number;
+    height: number;
+    scrollTop: number;
+    pendingRouteScrollTop: number | null;
+    registerContent: (element: HTMLElement, explicitHeight?: number) => () => void;
+}> | null;
+export declare function WebCollapsiblePagerPage({ children, pageKey, isFocused, isRouteActive, headerHeight, stickyHeaderHeight, onBridge, onGeometryChange, onScroll, onUserInput, }: React.PropsWithChildren<{
+    pageKey: string;
+    isFocused: boolean;
+    isRouteActive: boolean;
+    headerHeight: number;
+    stickyHeaderHeight: number;
+    onBridge: (key: string, bridge: WebCollapsiblePagerPageBridge | null) => void;
+    onGeometryChange: (key: string) => void;
+    onScroll: (key: string, top: number) => void;
+    onUserInput: (key: string) => void;
+}>): import("react/jsx-runtime").JSX.Element;
+//# sourceMappingURL=WebCollapsiblePagerPage.d.ts.map

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

@@ -4,6 +4,10 @@ export default PagerView;
 export * from './usePagerView';
 export * from './CollapsiblePagerView';
 export * from './NativeScroller';
+export { CollapsiblePagerView as WebCollapsiblePagerView } from './CollapsiblePagerView.web';
+export type { CollapsiblePagerViewProps as WebCollapsiblePagerViewProps } from './CollapsiblePagerView.web';
+export { useWebCollapsiblePagerPage } from './WebCollapsiblePagerPage';
+export type { WebCollapsiblePagerPageState } from './WebCollapsiblePagerPage';
 import type { OnPageScrollEventData as PagerViewOnPageScrollEventData, OnPageSelectedEventData as PagerViewOnPageSelectedEventData, OnPageScrollStateChangedEventData as PageScrollStateChangedNativeEventData, NativeProps } from './PagerViewNativeComponent';
 export type { PagerViewOnPageScrollEventData, PagerViewOnPageSelectedEventData, PageScrollStateChangedNativeEventData, NativeProps as PagerViewProps, };
 export type PagerViewOnPageScrollEvent = ReactNative.NativeSyntheticEvent<PagerViewOnPageScrollEventData>;

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

@@ -0,0 +1,13 @@
+import type * as ReactNative from "react-native";
+import { PagerView } from "./PagerView";
+export default PagerView;
+export * from "./usePagerView";
+export * from "./CollapsiblePagerView";
+export * from "./NativeScroller";
+import type { OnPageScrollEventData as PagerViewOnPageScrollEventData, OnPageSelectedEventData as PagerViewOnPageSelectedEventData, OnPageScrollStateChangedEventData as PageScrollStateChangedNativeEventData, NativeProps } from "./PagerViewNativeComponent";
+export type { PagerViewOnPageScrollEventData, PagerViewOnPageSelectedEventData, PageScrollStateChangedNativeEventData, NativeProps as PagerViewProps, };
+export type PagerViewOnPageScrollEvent = ReactNative.NativeSyntheticEvent<PagerViewOnPageScrollEventData>;
+export type PagerViewOnPageSelectedEvent = ReactNative.NativeSyntheticEvent<PagerViewOnPageSelectedEventData>;
+export type PageScrollStateChangedNativeEvent = ReactNative.NativeSyntheticEvent<PageScrollStateChangedNativeEventData>;
+export { ScrollEdgeEffect } from "./ScrollEdgeEffect";
+//# sourceMappingURL=index.native.d.ts.map

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

@@ -3,5 +3,9 @@ export type { PagerViewProps, PagerViewOnPageScrollEvent, PagerViewOnPageScrollE
 export * from "./usePagerView";
 export * from "./CollapsiblePagerView.web";
 export * from "./NativeScroller.web";
+export { CollapsiblePagerView as WebCollapsiblePagerView } from "./CollapsiblePagerView.web";
+export type { CollapsiblePagerViewProps as WebCollapsiblePagerViewProps } from "./CollapsiblePagerView.web";
+export { useWebCollapsiblePagerPage } from "./WebCollapsiblePagerPage";
+export type { WebCollapsiblePagerPageState } from "./WebCollapsiblePagerPage";
 export { ScrollEdgeEffect } from "./ScrollEdgeEffect";
 //# sourceMappingURL=index.web.d.ts.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onekeyfe/react-native-pager-view",
-  "version": "6.7.0-alpha.327",
+  "version": "6.7.0-alpha.335",
   "description": "React Native wrapper for Android and iOS ViewPager",
   "source": "./src/index.tsx",
   "main": "./lib/module/index.js",
@@ -9,8 +9,9 @@
   "sideEffects": false,
   "exports": {
     ".": {
-      "source": "./src/index.tsx",
       "types": "./lib/typescript/src/index.d.ts",
+      "react-native": "./lib/module/index.native.js",
+      "source": "./src/index.tsx",
       "browser": "./lib/module/index.web.js",
       "default": "./lib/module/index.js"
     },
@@ -72,7 +73,7 @@
     "typescript": "^5.9.2"
   },
   "peerDependencies": {
-    "@onekeyfe/react-native-native-logger": "6.7.0-alpha.327",
+    "@onekeyfe/react-native-native-logger": "6.7.0-alpha.335",
     "react": "*",
     "react-native": "*"
   },
@@ -108,5 +109,6 @@
         "RNCNativeScroller": "RNCNativeScrollerComponentView"
       }
     }
-  }
+  },
+  "react-native": "./lib/module/index.native.js"
 }

package/src/CollapsiblePagerView.tsx

@@ -120,6 +120,8 @@ export interface CollapsiblePagerViewProps
   stickyHeaderHeight: number;
   /** Fixed content above the collapsible header on iOS 26 and newer. */
   topOverlay?: React.ReactNode;
+  /** Known overlay height to reserve until its first layout measurement. */
+  topOverlayHeightHint?: number;
   /** Existing fixed header shared with a parent pager on iOS 26 and newer. */
   externalTopOverlayTag?: number;
   /** Selects UIKit's top scroll-edge effect on iOS 26 and newer. */
@@ -158,7 +160,7 @@ export interface CollapsiblePagerViewProps
 type State = {
   selectedPage: number;
   transientRetainedPages: readonly number[];
-  topOverlayHeight: number;
+  topOverlayHeight: number | null;
 };
 
 const pageIndex = (value: number) => {
@@ -186,7 +188,7 @@ export class CollapsiblePagerView extends React.PureComponent<
   State
 > {
   state: State = {
-    topOverlayHeight: 0,
+    topOverlayHeight: null,
     selectedPage: clampedPageIndex(
       this.props.initialPage ?? 0,
       React.Children.toArray(this.props.children).length
@@ -219,7 +221,22 @@ export class CollapsiblePagerView extends React.PureComponent<
     this.notifyMountedPagesChanged();
   }
 
-  componentDidUpdate() {
+  componentDidUpdate(previousProps: CollapsiblePagerViewProps) {
+    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) {
@@ -473,6 +490,7 @@ export class CollapsiblePagerView extends React.PureComponent<
       headerHeight,
       stickyHeaderHeight,
       topOverlay,
+      topOverlayHeightHint,
       externalTopOverlayTag,
       topScrollEdgeEffect,
       topOverlayColorScheme,
@@ -498,6 +516,11 @@ export class CollapsiblePagerView extends React.PureComponent<
       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 =
@@ -542,7 +565,11 @@ export class CollapsiblePagerView extends React.PureComponent<
         topOverlayColorScheme={
           scrollEdgeEnabled ? topOverlayColorScheme : undefined
         }
-        topOverlayHeight={hasTopOverlay ? this.state.topOverlayHeight : 0}
+        topOverlayHeight={
+          hasTopOverlay
+            ? this.state.topOverlayHeight ?? initialTopOverlayHeight
+            : 0
+        }
         externalTopOverlayTag={
           supportsTopScrollEdge && !hasTopOverlay
             ? externalTopOverlayTag ?? 0