@onekeyfe/react-native-pager-view 3.0.178 → 3.0.179-alpha.20261015

package/lib/module/NativeScroller.web.js

@@ -7,6 +7,8 @@ export const NativeScroller = /*#__PURE__*/React.forwardRef(function NativeScrol
   const {
     dataSet,
     pagerScrollKey: _pagerScrollKey,
+    topOverlay: _topOverlay,
+    topScrollEdgeEffect: _topScrollEdgeEffect,
     ...props
   } = inputProps;
   const webDataProps = {

package/lib/module/NativeScrollerNativeComponent.ts

@@ -47,6 +47,8 @@ export interface NativeProps extends ViewProps {
   contentInsetRight?: WithDefault<Double, 0>;
   contentInsetBottom?: WithDefault<Double, 0>;
   contentInsetLeft?: WithDefault<Double, 0>;
+  topScrollEdgeHard?: WithDefault<boolean, false>;
+  topOverlayHeight?: WithDefault<Double, 0>;
   refreshEnabled?: WithDefault<boolean, false>;
   refreshing?: WithDefault<boolean, false>;
   refreshTintColor?: ColorValue;

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

@@ -55,7 +55,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" | "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" | "topScrollEdgeHard" | "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. */
@@ -64,6 +64,14 @@ export interface CollapsiblePagerViewProps extends Omit<NativeProps, "children"
     headerHeight: number;
     /** Measured sticky bar height. */
     stickyHeaderHeight: number;
+    /** Fixed content above the collapsible header on iOS 26 and newer. */
+    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";
+    /** Effective appearance of the fixed overlay or pinned sticky bar. */
+    topOverlayColorScheme?: "light" | "dark";
     /**
      * Lets the active native list own vertical gestures that begin on pager headers.
      * Defaults to false and has no effect on Web.
@@ -93,6 +101,7 @@ export interface CollapsiblePagerViewProps extends Omit<NativeProps, "children"
 type State = {
     selectedPage: number;
     transientRetainedPages: readonly number[];
+    topOverlayHeight: number;
 };
 /**
  * Pager variant whose vertical header coordination is performed by the native

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

@@ -39,6 +39,10 @@ export interface CollapsiblePagerViewProps extends Omit<WebCollapsiblePagerNativ
     stickyHeader: React.ReactNode;
     headerHeight: number;
     stickyHeaderHeight: number;
+    topOverlay?: React.ReactNode;
+    topScrollEdgeEffect?: "hard";
+    topOverlayColorScheme?: "light" | "dark";
+    externalTopOverlayTag?: number;
     pageRetentionDistance?: number;
     layoutDirection?: "ltr" | "rtl" | "locale";
     children?: React.ReactNode;

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

@@ -26,6 +26,9 @@ export type OnNativeTabPressEventData = Readonly<{
     position: Int32;
     key: string;
 }>;
+export type OnScrollEdgeCapabilityEventData = Readonly<{
+    available: boolean;
+}>;
 /**
  * Internal native props. Consumers should use CollapsiblePagerViewProps from
  * CollapsiblePagerView instead of mounting this host component directly.
@@ -39,6 +42,10 @@ export interface NativeProps extends ViewProps {
     nativeSmoothHeaderScrollEnabled?: WithDefault<boolean, false>;
     headerHeight?: Int32;
     stickyHeaderHeight?: Int32;
+    topScrollEdgeHard?: WithDefault<boolean, false>;
+    topOverlayColorScheme?: string;
+    topOverlayHeight?: WithDefault<Double, 0>;
+    externalTopOverlayTag?: WithDefault<Int32, 0>;
     pageKeys?: string;
     retainedPages?: string;
     nativeTabBarItems?: string;
@@ -61,6 +68,7 @@ export interface NativeProps extends ViewProps {
     onCollapsibleStateChanged?: DirectEventHandler<OnCollapsibleStateChangedEventData>;
     onNativeTabPress?: DirectEventHandler<OnNativeTabPressEventData>;
     onNativeSubHeaderPress?: DirectEventHandler<OnNativeTabPressEventData>;
+    onScrollEdgeCapability?: DirectEventHandler<OnScrollEdgeCapabilityEventData>;
 }
 type CollapsiblePagerViewNativeType = HostComponent<NativeProps>;
 export interface NativeCommands {

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

@@ -5,6 +5,10 @@ export declare const NATIVE_SCROLLER_NATIVE_ID_PREFIX = "rnc-collapsible-pager-n
 /** 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";
     /** 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,6 +47,8 @@ export interface NativeProps extends ViewProps {
     contentInsetRight?: WithDefault<Double, 0>;
     contentInsetBottom?: WithDefault<Double, 0>;
     contentInsetLeft?: WithDefault<Double, 0>;
+    topScrollEdgeHard?: WithDefault<boolean, false>;
+    topOverlayHeight?: WithDefault<Double, 0>;
     refreshEnabled?: WithDefault<boolean, false>;
     refreshing?: WithDefault<boolean, false>;
     refreshTintColor?: ColorValue;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onekeyfe/react-native-pager-view",
-  "version": "3.0.178",
+  "version": "3.0.179-alpha.20261015",
   "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.178",
+    "@onekeyfe/react-native-native-logger": "3.0.179-alpha.20261015",
     "react": "*",
     "react-native": "*"
   },

package/src/CollapsiblePagerView.tsx

@@ -86,6 +86,9 @@ export interface CollapsiblePagerViewProps
     | "children"
     | "headerHeight"
     | "stickyHeaderHeight"
+    | "topScrollEdgeHard"
+    | "topOverlayHeight"
+    | "externalTopOverlayTag"
     | "pageKeys"
     | "retainedPages"
     | "nativeTabBarItems"
@@ -114,6 +117,14 @@ export interface CollapsiblePagerViewProps
   headerHeight: number;
   /** Measured sticky bar height. */
   stickyHeaderHeight: number;
+  /** Fixed content above the collapsible header on iOS 26 and newer. */
+  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";
+  /** Effective appearance of the fixed overlay or pinned sticky bar. */
+  topOverlayColorScheme?: "light" | "dark";
   /**
    * Lets the active native list own vertical gestures that begin on pager headers.
    * Defaults to false and has no effect on Web.
@@ -146,6 +157,7 @@ export interface CollapsiblePagerViewProps
 type State = {
   selectedPage: number;
   transientRetainedPages: readonly number[];
+  topOverlayHeight: number;
 };
 
 const pageIndex = (value: number) => {
@@ -173,6 +185,7 @@ export class CollapsiblePagerView extends React.PureComponent<
   State
 > {
   state: State = {
+    topOverlayHeight: 0,
     selectedPage: clampedPageIndex(
       this.props.initialPage ?? 0,
       React.Children.toArray(this.props.children).length
@@ -458,6 +471,10 @@ export class CollapsiblePagerView extends React.PureComponent<
       stickyHeader,
       headerHeight,
       stickyHeaderHeight,
+      topOverlay,
+      externalTopOverlayTag,
+      topScrollEdgeEffect,
+      topOverlayColorScheme,
       nativeSmoothHeaderScrollEnabled,
       pageRetentionDistance: _pageRetentionDistance,
       onMountedPagesChanged: _onMountedPagesChanged,
@@ -474,6 +491,10 @@ export class CollapsiblePagerView extends React.PureComponent<
       ...nativeProps
     } = this.props;
     const pages = this.pages();
+    const supportsTopScrollEdge =
+      Platform.OS === "ios" && Number(Platform.Version) >= 26;
+    const hardScrollEdge = supportsTopScrollEdge && topScrollEdgeEffect === "hard";
+    const hasTopOverlay = hardScrollEdge && topOverlay != null;
     const pageKeys = pages.map(pageKey);
     const retained = new Set(this.mountedPages(pages.length));
     const deducedLayoutDirection =
@@ -514,6 +535,14 @@ 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}
+        externalTopOverlayTag={
+          supportsTopScrollEdge && !hasTopOverlay
+            ? externalTopOverlayTag ?? 0
+            : 0
+        }
         nativeSmoothHeaderScrollEnabled={nativeSmoothHeaderScrollEnabled}
         pageKeys={JSON.stringify(pageKeys)}
         retainedPages={JSON.stringify([...retained])}
@@ -603,6 +632,21 @@ export class CollapsiblePagerView extends React.PureComponent<
         >
           {stickyHeader}
         </View>
+        {hasTopOverlay ? (
+          <View
+            key="top-overlay"
+            collapsable={false}
+            style={[styles.slot, { bottom: undefined }]}
+            onLayout={(event) => {
+              const height = Math.ceil(event.nativeEvent.layout.height);
+              if (this.state.topOverlayHeight !== height) {
+                this.setState({ topOverlayHeight: height });
+              }
+            }}
+          >
+            {topOverlay}
+          </View>
+        ) : null}
         {pages.map((page, index) => (
           <View
             key={pageKeys[index]}

package/src/CollapsiblePagerView.web.tsx

@@ -66,6 +66,10 @@ export interface CollapsiblePagerViewProps
   stickyHeader: React.ReactNode;
   headerHeight: number;
   stickyHeaderHeight: number;
+  topOverlay?: React.ReactNode;
+  topScrollEdgeEffect?: "hard";
+  topOverlayColorScheme?: "light" | "dark";
+  externalTopOverlayTag?: number;
   pageRetentionDistance?: number;
   layoutDirection?: "ltr" | "rtl" | "locale";
   children?: React.ReactNode;
@@ -759,6 +763,10 @@ export class CollapsiblePagerView extends React.PureComponent<
       children: _children,
       header,
       stickyHeader,
+      topOverlay: _topOverlay,
+      topScrollEdgeEffect: _topScrollEdgeEffect,
+      topOverlayColorScheme: _topOverlayColorScheme,
+      externalTopOverlayTag: _externalTopOverlayTag,
       headerHeight: _headerHeight,
       stickyHeaderHeight: _stickyHeaderHeight,
       pageRetentionDistance: _pageRetentionDistance,

package/src/CollapsiblePagerViewNativeComponent.ts

@@ -43,6 +43,7 @@ export type OnNativeTabPressEventData = Readonly<{
   position: Int32;
   key: string;
 }>;
+export type OnScrollEdgeCapabilityEventData = Readonly<{ available: boolean }>;
 
 /**
  * Internal native props. Consumers should use CollapsiblePagerViewProps from
@@ -58,6 +59,10 @@ export interface NativeProps extends ViewProps {
   nativeSmoothHeaderScrollEnabled?: WithDefault<boolean, false>;
   headerHeight?: Int32;
   stickyHeaderHeight?: Int32;
+  topScrollEdgeHard?: WithDefault<boolean, false>;
+  topOverlayColorScheme?: string;
+  topOverlayHeight?: WithDefault<Double, 0>;
+  externalTopOverlayTag?: WithDefault<Int32, 0>;
   pageKeys?: string;
   retainedPages?: string;
   nativeTabBarItems?: string;
@@ -80,6 +85,7 @@ export interface NativeProps extends ViewProps {
   onCollapsibleStateChanged?: DirectEventHandler<OnCollapsibleStateChangedEventData>;
   onNativeTabPress?: DirectEventHandler<OnNativeTabPressEventData>;
   onNativeSubHeaderPress?: DirectEventHandler<OnNativeTabPressEventData>;
+  onScrollEdgeCapability?: DirectEventHandler<OnScrollEdgeCapabilityEventData>;
 }
 
 type CollapsiblePagerViewNativeType = HostComponent<NativeProps>;

package/src/NativeScroller.tsx

@@ -44,6 +44,10 @@ export interface NativeScrollerProps
       | "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";
   /** iOS only. Android retains AndroidX's native fling physics. */
   decelerationRate?: ScrollViewProps["decelerationRate"];
   /** Standard RefreshControl props are mapped to the independently owned native controller. */
@@ -81,6 +85,8 @@ export const NativeScroller = React.forwardRef<
 >(function NativeScroller(
   {
     children,
+    topOverlay,
+    topScrollEdgeEffect,
     nativeID,
     pagerScrollKey,
     style,
@@ -109,6 +115,10 @@ export const NativeScroller = React.forwardRef<
   const generatedId = React.useId();
   const [contentViewportHeight, setContentViewportHeight] = React.useState(0);
   const [contentSize, setContentSize] = React.useState({ width: 0, height: 0 });
+  const [topOverlayHeight, setTopOverlayHeight] = React.useState(0);
+  const hasTopOverlay =
+    Platform.OS === "ios" && Number(Platform.Version) >= 26 &&
+    topScrollEdgeEffect === "hard" && topOverlay != null;
   const [refreshEpoch, requestRefreshSync] = React.useReducer(
     (value: number) => value + 1,
     0
@@ -187,13 +197,14 @@ export const NativeScroller = React.forwardRef<
     );
 
   return (
+    <View collapsable={false} style={[styles.viewport, style]} onLayout={onLayout}>
     <NativeScrollerHost
       {...props}
       ref={hostRef}
       nativeID={`${NATIVE_SCROLLER_NATIVE_ID_PREFIX}:${
         pagerScrollKey ?? nativeID ?? generatedId
       }`}
-      style={[styles.viewport, style]}
+      style={StyleSheet.absoluteFill}
       nestedScrollEnabled={nestedScrollEnabled}
       contentWidth={contentSize.width}
       contentHeight={contentSize.height}
@@ -201,6 +212,8 @@ export const NativeScroller = React.forwardRef<
       contentInsetRight={contentInset?.right ?? 0}
       contentInsetBottom={contentInset?.bottom ?? 0}
       contentInsetLeft={contentInset?.left ?? 0}
+      topScrollEdgeHard={hasTopOverlay}
+      topOverlayHeight={hasTopOverlay ? topOverlayHeight : 0}
       decelerationRate={rate}
       keyboardShouldPersistTaps={persistTaps}
       refreshEnabled={Boolean(refresh) && refresh?.enabled !== false}
@@ -219,7 +232,6 @@ export const NativeScroller = React.forwardRef<
           requestRefreshSync();
         }
       }}
-      onLayout={onLayout}
       onContentViewportChange={(event) => {
         const height = event.nativeEvent.height;
         if (!Number.isFinite(height) || height < 0) return;
@@ -306,6 +318,19 @@ export const NativeScroller = React.forwardRef<
         {children}
       </View>
     </NativeScrollerHost>
+    {hasTopOverlay ? (
+      <View
+        collapsable={false}
+        style={{ position: "absolute", top: 0, left: 0, right: 0 }}
+        onLayout={(event) => {
+          const height = Math.ceil(event.nativeEvent.layout.height);
+          setTopOverlayHeight((previous) => previous === height ? previous : height);
+        }}
+      >
+        {topOverlay}
+      </View>
+    ) : null}
+    </View>
   );
 });
 

package/src/NativeScroller.web.tsx

@@ -14,6 +14,8 @@ export const NativeScroller = React.forwardRef<
   const {
     dataSet,
     pagerScrollKey: _pagerScrollKey,
+    topOverlay: _topOverlay,
+    topScrollEdgeEffect: _topScrollEdgeEffect,
     ...props
   } = inputProps as NativeScrollerWebProps;
   const webDataProps = {

package/src/NativeScrollerNativeComponent.ts

@@ -47,6 +47,8 @@ export interface NativeProps extends ViewProps {
   contentInsetRight?: WithDefault<Double, 0>;
   contentInsetBottom?: WithDefault<Double, 0>;
   contentInsetLeft?: WithDefault<Double, 0>;
+  topScrollEdgeHard?: WithDefault<boolean, false>;
+  topOverlayHeight?: WithDefault<Double, 0>;
   refreshEnabled?: WithDefault<boolean, false>;
   refreshing?: WithDefault<boolean, false>;
   refreshTintColor?: ColorValue;