@shopify/flash-list 2.0.4-alpha.1 → 2.2.0

package/src/benchmark/useBenchmark.ts

@@ -1,4 +1,4 @@
-import React, { useEffect } from "react";
+import React, { useEffect, useState, useCallback, useRef } from "react";
 
 import { FlashListRef } from "../FlashListRef";
 import { ErrorMessages } from "../errors/ErrorMessages";
@@ -24,6 +24,12 @@ export interface BenchmarkParams {
    * Blank area is negative when list is able to draw faster than the scroll speed.
    */
   sumNegativeBlankAreaValues?: boolean;
+
+  /**
+   * When set to true, the benchmark will not start automatically.
+   * Use the returned startBenchmark function to trigger it manually.
+   */
+  startManually?: boolean;
 }
 
 export interface BenchmarkResult {
@@ -44,15 +50,27 @@ export function useBenchmark(
   callback: (benchmarkResult: BenchmarkResult) => void,
   params: BenchmarkParams = {}
 ) {
-  useEffect(() => {
+  const [isBenchmarkRunning, setIsBenchmarkRunning] = useState(false);
+  const cancellableRef = useRef<Cancellable | null>(null);
+
+  const startBenchmark = useCallback(() => {
+    if (isBenchmarkRunning) {
+      return;
+    }
+
     const cancellable = new Cancellable();
+    cancellableRef.current = cancellable;
     const suggestions: string[] = [];
+
     if (flashListRef.current) {
       if (!(Number(flashListRef.current.props.data?.length) > 0)) {
         throw new Error(ErrorMessages.dataEmptyCannotRunBenchmark);
       }
     }
-    const cancelTimeout = setTimeout(async () => {
+
+    setIsBenchmarkRunning(true);
+
+    const runBenchmark = async () => {
       const jsFPSMonitor = new JSFPSMonitor();
       jsFPSMonitor.startTracking();
       for (let i = 0; i < (params.repeatCount || 1); i++) {
@@ -78,13 +96,37 @@ export function useBenchmark(
         result.formattedString = getFormattedString(result);
       }
       callback(result);
+      setIsBenchmarkRunning(false);
+    };
+
+    runBenchmark();
+  }, [
+    callback,
+    flashListRef,
+    isBenchmarkRunning,
+    params.repeatCount,
+    params.speedMultiplier,
+  ]);
+
+  useEffect(() => {
+    if (params.startManually) {
+      return;
+    }
+
+    const cancelTimeout = setTimeout(() => {
+      startBenchmark();
     }, params.startDelayInMs || 3000);
+
     return () => {
       clearTimeout(cancelTimeout);
-      cancellable.cancel();
+      if (cancellableRef.current) {
+        cancellableRef.current.cancel();
+      }
     };
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, []);
+
+  return { startBenchmark, isBenchmarkRunning } as const;
 }
 
 export function getFormattedString(res: BenchmarkResult) {
@@ -161,6 +203,7 @@ async function runScrollBenchmark(
     }
   }
 }
+
 function computeSuggestions(
   flashListRef: React.RefObject<FlashListRef<any> | null | undefined>,
   suggestions: string[]

package/src/benchmark/useFlatListBenchmark.ts

@@ -1,4 +1,4 @@
-import { useEffect } from "react";
+import { useCallback, useEffect, useRef, useState } from "react";
 import { FlatList } from "react-native";
 
 import { ErrorMessages } from "../errors/ErrorMessages";
@@ -25,14 +25,24 @@ export function useFlatListBenchmark(
   callback: (benchmarkResult: BenchmarkResult) => void,
   params: FlatListBenchmarkParams
 ) {
-  useEffect(() => {
+  const [isBenchmarkRunning, setIsBenchmarkRunning] = useState(false);
+  const cancellableRef = useRef<Cancellable | null>(null);
+
+  const startBenchmark = useCallback(() => {
+    if (isBenchmarkRunning) {
+      return;
+    }
     const cancellable = new Cancellable();
+    cancellableRef.current = cancellable;
     if (flatListRef.current && flatListRef.current.props) {
       if (!(Number(flatListRef.current.props.data?.length) > 0)) {
         throw new Error(ErrorMessages.dataEmptyCannotRunBenchmark);
       }
     }
-    const cancelTimeout = setTimeout(async () => {
+
+    setIsBenchmarkRunning(true);
+
+    const runBenchmark = async () => {
       const jsFPSMonitor = new JSFPSMonitor();
       jsFPSMonitor.startTracking();
       for (let i = 0; i < (params.repeatCount || 1); i++) {
@@ -53,14 +63,37 @@ export function useFlatListBenchmark(
         result.formattedString = getFormattedString(result);
       }
       callback(result);
+      setIsBenchmarkRunning(false);
+    };
+
+    runBenchmark();
+  }, [
+    callback,
+    flatListRef,
+    isBenchmarkRunning,
+    params.repeatCount,
+    params.speedMultiplier,
+    params.targetOffset,
+  ]);
+
+  useEffect(() => {
+    if (params.startManually) {
+      return;
+    }
+
+    const cancelTimeout = setTimeout(() => {
+      startBenchmark();
     }, params.startDelayInMs || 3000);
+
     return () => {
       clearTimeout(cancelTimeout);
-      cancellable.cancel();
+      if (cancellableRef.current) {
+        cancellableRef.current.cancel();
+      }
     };
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, []);
-  return [];
+  return { startBenchmark, isBenchmarkRunning };
 }
 
 /**

package/src/recyclerview/RecyclerView.tsx

@@ -84,6 +84,8 @@ const RecyclerViewComponent = <T,>(
     stickyHeaderIndices,
     maintainVisibleContentPosition,
     onCommitLayoutEffect,
+    onChangeStickyIndex,
+    stickyHeaderConfig,
     ...rest
   } = props;
 
@@ -91,6 +93,13 @@ const RecyclerViewComponent = <T,>(
 
   renderTimeTracker.startTracking();
 
+  // Sticky header config
+  const stickyHeaderOffset = stickyHeaderConfig?.offset ?? 0;
+  const stickyHeaderUseNativeDriver =
+    stickyHeaderConfig?.useNativeDriver ?? true;
+  const stickyHeaderHideRelatedCell =
+    stickyHeaderConfig?.hideRelatedCell ?? false;
+
   // Core refs for managing scroll view, internal view, and child container
   const scrollViewRef = useRef<CompatScroller>(null);
   const internalViewRef = useRef<CompatView>(null);
@@ -108,6 +117,7 @@ const RecyclerViewComponent = <T,>(
   // State for managing layout and render updates
   const [_, setLayoutTreeId] = useLayoutState(0);
   const [__, setRenderId] = useState(0);
+  const [currentStickyIndex, setCurrentStickyIndex] = useState(-1);
 
   // Map to store refs for each item in the list
   const refHolder = useMemo(
@@ -388,6 +398,7 @@ const RecyclerViewComponent = <T,>(
     renderFooter,
     renderEmpty,
     CompatScrollView,
+    renderStickyHeaderBackdrop,
   } = useSecondaryProps(props);
 
   if (
@@ -408,15 +419,23 @@ const RecyclerViewComponent = <T,>(
       if (horizontal) {
         throw new Error(ErrorMessages.stickyHeadersNotSupportedForHorizontal);
       }
+
       return (
         <StickyHeaders
           stickyHeaderIndices={stickyHeaderIndices}
+          stickyHeaderOffset={stickyHeaderOffset}
           data={data}
           renderItem={renderItem}
           scrollY={scrollY}
           stickyHeaderRef={stickyHeaderRef}
           recyclerViewManager={recyclerViewManager}
           extraData={extraData}
+          onChangeStickyIndex={(newStickyHeaderIndex) => {
+            if (stickyHeaderHideRelatedCell) {
+              setCurrentStickyIndex(newStickyHeaderIndex);
+            }
+            onChangeStickyIndex?.(newStickyHeaderIndex, currentStickyIndex);
+          }}
         />
       );
     }
@@ -424,11 +443,15 @@ const RecyclerViewComponent = <T,>(
   }, [
     data,
     stickyHeaderIndices,
+    stickyHeaderOffset,
     renderItem,
     scrollY,
     horizontal,
     recyclerViewManager,
     extraData,
+    currentStickyIndex,
+    onChangeStickyIndex,
+    stickyHeaderHideRelatedCell,
   ]);
 
   // Set up scroll event handling with animation support for sticky headers
@@ -436,11 +459,14 @@ const RecyclerViewComponent = <T,>(
     if (stickyHeaders) {
       return Animated.event(
         [{ nativeEvent: { contentOffset: { y: scrollY } } }],
-        { useNativeDriver: true, listener: onScrollHandler }
+        {
+          useNativeDriver: stickyHeaderUseNativeDriver,
+          listener: onScrollHandler,
+        }
       );
     }
     return onScrollHandler;
-  }, [onScrollHandler, scrollY, stickyHeaders]);
+  }, [onScrollHandler, scrollY, stickyHeaders, stickyHeaderUseNativeDriver]);
 
   const shouldMaintainVisibleContentPosition =
     recyclerViewManager.shouldMaintainVisibleContentPosition();
@@ -464,13 +490,14 @@ const RecyclerViewComponent = <T,>(
     return (
       <CompatView
         style={{
+          marginTop: horizontal ? undefined : stickyHeaderOffset,
           height: horizontal ? undefined : 0,
           width: horizontal ? 0 : undefined,
         }}
         ref={firstChildViewRef}
       />
     );
-  }, [horizontal]);
+  }, [horizontal, stickyHeaderOffset]);
 
   const scrollAnchor = useMemo(() => {
     if (shouldMaintainVisibleContentPosition) {
@@ -490,11 +517,13 @@ const RecyclerViewComponent = <T,>(
   return (
     <RecyclerViewContextProvider value={recyclerViewContext}>
       <CompatView
-        style={{
-          flex: horizontal ? undefined : 1,
-          overflow: "hidden",
-          ...style,
-        }}
+        style={[
+          {
+            flex: horizontal ? undefined : 1,
+            overflow: "hidden",
+          },
+          style,
+        ]}
         ref={internalViewRef}
         collapsable={false}
         onLayout={(event) => {
@@ -588,10 +617,15 @@ const RecyclerViewComponent = <T,>(
                 ? recyclerViewManager.getChildContainerDimensions()
                 : undefined
             }
+            currentStickyIndex={currentStickyIndex}
+            hideStickyHeaderRelatedCell={stickyHeaderHideRelatedCell}
           />
           {renderEmpty}
           {renderFooter}
         </CompatScrollView>
+        {stickyHeaderIndices && stickyHeaderIndices.length > 0
+          ? renderStickyHeaderBackdrop
+          : null}
         {stickyHeaders}
       </CompatView>
     </RecyclerViewContextProvider>

package/src/recyclerview/ViewHolder.tsx

@@ -47,6 +47,8 @@ export interface ViewHolderProps<TItem> {
   horizontal?: FlashListProps<TItem>["horizontal"];
   /** Callback when the item's size changes */
   onSizeChanged?: (index: number, size: RVDimension) => void;
+  /** Whether this item should be hidden (likely because it is associated with the active sticky header) */
+  hidden: boolean;
 }
 
 /**
@@ -69,6 +71,7 @@ const ViewHolderInternal = <TItem,>(props: ViewHolderProps<TItem>) => {
     ItemSeparatorComponent,
     trailingItem,
     horizontal,
+    hidden,
   } = props;
 
   useLayoutEffect(() => {
@@ -113,6 +116,7 @@ const ViewHolderInternal = <TItem,>(props: ViewHolderProps<TItem>) => {
     maxWidth: layout.maxWidth,
     left: layout.x,
     top: layout.y,
+    opacity: hidden ? 0 : 1,
   } as const;
 
   // TODO: Fix this type issue
@@ -152,7 +156,8 @@ export const ViewHolder = React.memo(
       prevProps.CellRendererComponent === nextProps.CellRendererComponent &&
       prevProps.ItemSeparatorComponent === nextProps.ItemSeparatorComponent &&
       prevProps.trailingItem === nextProps.trailingItem &&
-      prevProps.horizontal === nextProps.horizontal
+      prevProps.horizontal === nextProps.horizontal &&
+      prevProps.hidden === nextProps.hidden
     );
   }
 );

package/src/recyclerview/ViewHolderCollection.tsx

@@ -50,6 +50,10 @@ export interface ViewHolderCollectionProps<TItem> {
    * For startRenderingFromBottom, we need to adjust the height of the container
    */
   getAdjustmentMargin: () => number;
+  /** Current sticky index */
+  currentStickyIndex: number;
+  /** Whether the cell associated with an active sticky header is hidden */
+  hideStickyHeaderRelatedCell: boolean;
 }
 
 /**
@@ -84,6 +88,8 @@ export const ViewHolderCollection = <TItem,>(
     onCommitEffect,
     horizontal,
     getAdjustmentMargin,
+    currentStickyIndex,
+    hideStickyHeaderRelatedCell,
   } = props;
 
   const [renderId, setRenderId] = React.useState(0);
@@ -168,6 +174,7 @@ export const ViewHolderCollection = <TItem,>(
           const trailingItem = ItemSeparatorComponent
             ? data[index + 1]
             : undefined;
+
           return (
             <ViewHolder
               key={reactKey}
@@ -185,6 +192,9 @@ export const ViewHolderCollection = <TItem,>(
               CellRendererComponent={CellRendererComponent}
               ItemSeparatorComponent={ItemSeparatorComponent}
               horizontal={horizontal}
+              hidden={
+                hideStickyHeaderRelatedCell && currentStickyIndex === index
+              }
             />
           );
         })}

package/src/recyclerview/components/StickyHeaders.tsx

@@ -27,6 +27,10 @@ import { CompatAnimatedView } from "./CompatView";
 export interface StickyHeaderProps<TItem> {
   /** Array of indices that should have sticky headers */
   stickyHeaderIndices: number[];
+  /** Offset from the top where sticky headers should stick (in pixels) */
+  stickyHeaderOffset: number;
+  /** Sticky header change handler */
+  onChangeStickyIndex: (index: number) => void;
   /** The data array being rendered */
   data: ReadonlyArray<TItem>;
   /** Animated value tracking scroll position */
@@ -56,12 +60,14 @@ interface StickyHeaderState {
 
 export const StickyHeaders = <TItem,>({
   stickyHeaderIndices,
+  stickyHeaderOffset,
   renderItem,
   stickyHeaderRef,
   recyclerViewManager,
   scrollY,
   data,
   extraData,
+  onChangeStickyIndex,
 }: StickyHeaderProps<TItem>) => {
   const [stickyHeaderState, setStickyHeaderState] = useState<StickyHeaderState>(
     {
@@ -91,7 +97,7 @@ export const StickyHeaders = <TItem,>({
     // Binary search for current sticky index
     const currentIndexInArray = findCurrentStickyIndex(
       sortedIndices,
-      adjustedScrollOffset,
+      adjustedScrollOffset + stickyHeaderOffset,
       (index) => recyclerViewManager.getLayout(index).y
     );
 
@@ -102,7 +108,8 @@ export const StickyHeaders = <TItem,>({
       newNextStickyIndex = -1;
     }
 
-    // To make sure header offset is 0 in the interpolate compute
+    // Calculate when the next sticky header should start pushing the current one
+    // The next header starts pushing when it reaches the bottom of the current sticky header
     const newNextStickyY =
       newNextStickyIndex === -1
         ? Number.MAX_SAFE_INTEGER
@@ -111,6 +118,7 @@ export const StickyHeaders = <TItem,>({
     const newCurrentStickyHeight =
       recyclerViewManager.tryGetLayout(newStickyIndex)?.height ?? 0;
 
+    // Push should start when the next header reaches the bottom of the current sticky header
     const newPushStartsAt = newNextStickyY - newCurrentStickyHeight;
 
     if (
@@ -119,15 +127,21 @@ export const StickyHeaders = <TItem,>({
     ) {
       setStickyHeaderState({
         currentStickyIndex: newStickyIndex,
-        pushStartsAt: newPushStartsAt,
+        pushStartsAt: newPushStartsAt - stickyHeaderOffset,
       });
     }
+
+    if (newStickyIndex !== currentStickyIndex) {
+      onChangeStickyIndex?.(newStickyIndex);
+    }
   }, [
     legthInvalid,
     recyclerViewManager,
     sortedIndices,
     currentStickyIndex,
     pushStartsAt,
+    onChangeStickyIndex,
+    stickyHeaderOffset,
   ]);
 
   useEffect(() => {
@@ -147,16 +161,32 @@ export const StickyHeaders = <TItem,>({
 
   const refHolder = useRef(new Map()).current;
 
-  const translateY = useMemo(() => {
+  const { translateY, opacity } = useMemo(() => {
     const currentStickyHeight =
       recyclerViewManager.tryGetLayout(currentStickyIndex)?.height ?? 0;
 
-    return scrollY.interpolate({
-      inputRange: [pushStartsAt, pushStartsAt + currentStickyHeight],
-      outputRange: [0, -currentStickyHeight],
-      extrapolate: "clamp",
-    });
-  }, [recyclerViewManager, currentStickyIndex, scrollY, pushStartsAt]);
+    return {
+      translateY: scrollY.interpolate({
+        inputRange: [pushStartsAt, pushStartsAt + currentStickyHeight],
+        outputRange: [0, -currentStickyHeight],
+        extrapolate: "clamp",
+      }),
+      opacity:
+        stickyHeaderOffset > 0
+          ? scrollY.interpolate({
+              inputRange: [pushStartsAt, pushStartsAt + currentStickyHeight],
+              outputRange: [1, 0],
+              extrapolate: "clamp",
+            })
+          : undefined,
+    };
+  }, [
+    recyclerViewManager,
+    currentStickyIndex,
+    scrollY,
+    pushStartsAt,
+    stickyHeaderOffset,
+  ]);
 
   // Memoize header content
   const headerContent = useMemo(() => {
@@ -164,11 +194,12 @@ export const StickyHeaders = <TItem,>({
       <CompatAnimatedView
         style={{
           position: "absolute",
-          top: 0,
+          top: stickyHeaderOffset,
           left: 0,
           right: 0,
-          zIndex: 1,
+          zIndex: 2,
           transform: [{ translateY }],
+          opacity,
         }}
       >
         {currentStickyIndex !== -1 && currentStickyIndex < data.length ? (
@@ -181,11 +212,21 @@ export const StickyHeaders = <TItem,>({
             extraData={extraData}
             trailingItem={null}
             target="StickyHeader"
+            hidden={false}
           />
         ) : null}
       </CompatAnimatedView>
     );
-  }, [translateY, currentStickyIndex, data, renderItem, refHolder, extraData]);
+  }, [
+    translateY,
+    opacity,
+    currentStickyIndex,
+    data,
+    renderItem,
+    refHolder,
+    extraData,
+    stickyHeaderOffset,
+  ]);
 
   return headerContent;
 };

package/src/recyclerview/hooks/useRecyclerViewController.tsx

@@ -289,7 +289,7 @@ export function useRecyclerViewController<T>(
           }
         }
         setTimeout(() => {
-          scrollViewRef.current!.scrollToEnd({ animated });
+          scrollViewRef.current?.scrollToEnd({ animated });
         }, 0);
       },
 
@@ -564,7 +564,8 @@ export function useRecyclerViewController<T>(
   ]);
 
   const applyInitialScrollIndex = useCallback(() => {
-    const { horizontal, data } = recyclerViewManager.props;
+    const { horizontal, data, initialScrollIndexParams } =
+      recyclerViewManager.props;
 
     const initialScrollIndex =
       recyclerViewManager.getInitialScrollIndex() ?? -1;
@@ -583,9 +584,11 @@ export function useRecyclerViewController<T>(
 
       pauseOffsetCorrection.current = true;
 
+      const additionalOffset = initialScrollIndexParams?.viewOffset ?? 0;
       const offset = horizontal
-        ? recyclerViewManager.getLayout(initialScrollIndex).x
-        : recyclerViewManager.getLayout(initialScrollIndex).y;
+        ? recyclerViewManager.getLayout(initialScrollIndex).x + additionalOffset
+        : recyclerViewManager.getLayout(initialScrollIndex).y +
+          additionalOffset;
       handlerMethods.scrollToOffset({
         offset,
         animated: false,

package/src/recyclerview/hooks/useSecondaryProps.tsx

@@ -20,6 +20,7 @@ import { CompatAnimatedScroller } from "../components/CompatScroller";
  *   - renderHeader: The header component renderer
  *   - renderFooter: The footer component renderer
  *   - renderEmpty: The empty state component renderer
+ *   - renderStickyHeaderBackdrop: The sticky header backdrop component renderer
  *   - CompatScrollView: The animated scroll component
  */
 export function useSecondaryProps<T>(props: RecyclerViewProps<T>) {
@@ -35,6 +36,7 @@ export function useSecondaryProps<T>(props: RecyclerViewProps<T>) {
     onRefresh,
     data,
     refreshControl: customRefreshControl,
+    stickyHeaderConfig,
   } = props;
 
   /**
@@ -94,6 +96,26 @@ export function useSecondaryProps<T>(props: RecyclerViewProps<T>) {
     return getValidComponent(ListEmptyComponent);
   }, [ListEmptyComponent, data]);
 
+  /**
+   * Creates the sticky header backdrop component.
+   */
+  const renderStickyHeaderBackdrop = useMemo(() => {
+    if (!stickyHeaderConfig?.backdropComponent) {
+      return null;
+    }
+    return (
+      <CompatView
+        style={{
+          position: "absolute",
+          inset: 0,
+          pointerEvents: "none",
+        }}
+      >
+        {getValidComponent(stickyHeaderConfig?.backdropComponent)}
+      </CompatView>
+    );
+  }, [stickyHeaderConfig?.backdropComponent]);
+
   /**
    * Creates an animated scroll component based on the provided renderScrollComponent.
    * If no custom component is provided, uses the default CompatAnimatedScroller.
@@ -120,5 +142,6 @@ export function useSecondaryProps<T>(props: RecyclerViewProps<T>) {
     renderFooter,
     renderEmpty,
     CompatScrollView,
+    renderStickyHeaderBackdrop,
   };
 }

package/dist/__tests__/AverageWindow.test.d.ts

@@ -1,2 +0,0 @@
-export {};
-//# sourceMappingURL=AverageWindow.test.d.ts.map

package/dist/__tests__/AverageWindow.test.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"AverageWindow.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/AverageWindow.test.ts"],"names":[],"mappings":""}