@shopify/flash-list 2.0.0-alpha.9 → 2.0.0-rc.10

package/src/benchmark/useBenchmark.ts

@@ -199,42 +199,5 @@ function computeSuggestions(
         `Data count is low. Try to increase it to a large number (e.g 200) using the 'useDataMultiplier' hook.`
       );
     }
-    const distanceFromWindow = roundToDecimalPlaces(
-      flashListRef.current.firstItemOffset,
-      0
-    );
-    if (
-      (flashListRef.current.props.estimatedFirstItemOffset || 0) !==
-      distanceFromWindow
-    ) {
-      suggestions.push(
-        `estimatedFirstItemOffset can be set to ${distanceFromWindow}`
-      );
-    }
-    const rlv = flashListRef.current.recyclerlistview_unsafe;
-    const horizontal = flashListRef.current.props.horizontal;
-    if (rlv) {
-      const sizeArray = rlv.props.dataProvider
-        .getAllData()
-        .map((_, index) =>
-          horizontal
-            ? rlv.getLayout?.(index)?.width || 0
-            : rlv.getLayout?.(index)?.height || 0
-        );
-      const averageSize = Math.round(
-        sizeArray.reduce((prev, current) => prev + current, 0) /
-          sizeArray.length
-      );
-      if (
-        Math.abs(
-          averageSize -
-            (flashListRef.current.props.estimatedItemSize ??
-              flashListRef.current.state.layoutProvider
-                .defaultEstimatedItemSize)
-        ) > 5
-      ) {
-        suggestions.push(`estimatedItemSize can be set to ${averageSize}`);
-      }
-    }
   }
 }

package/src/benchmark/useFlatListBenchmark.ts

@@ -25,7 +25,7 @@ export function useFlatListBenchmark(
 ) {
   useEffect(() => {
     const cancellable = new Cancellable();
-    if (flatListRef.current) {
+    if (flatListRef.current && flatListRef.current.props) {
       if (!(Number(flatListRef.current.props.data?.length) > 0)) {
         throw new Error("Data is empty, cannot run benchmark");
       }
@@ -71,7 +71,7 @@ async function runScrollBenchmark(
   scrollSpeedMultiplier: number
 ): Promise<void> {
   if (flatListRef.current) {
-    const horizontal = flatListRef.current.props.horizontal;
+    const horizontal = Boolean(flatListRef.current.props?.horizontal);
 
     const fromX = 0;
     const fromY = 0;

package/src/index.ts

@@ -5,6 +5,7 @@ import { RecyclerView } from "./recyclerview/RecyclerView";
 
 // Keep this unmodified for TS type checking
 export { default as FlashList } from "./FlashList";
+export { FlashListRef } from "./FlashListRef";
 export {
   FlashListProps,
   ContentStyle,
@@ -52,7 +53,7 @@ export { default as ViewToken } from "./viewability/ViewToken";
 export { default as CellContainer } from "./native/cell-container/CellContainer";
 export { RecyclerView } from "./recyclerview/RecyclerView";
 export { RecyclerViewProps } from "./recyclerview/RecyclerViewProps";
-export { useRecyclerViewContext } from "./recyclerview/RecyclerViewContextProvider";
+export { useFlashListContext } from "./recyclerview/RecyclerViewContextProvider";
 
 // @ts-ignore - This is ignored by TypeScript but will be present in the compiled JS
 // In the compiled JS, this will override the previous FlashList export with a conditional one

package/src/native/config/PlatformHelper.android.ts

@@ -3,6 +3,7 @@ import { BaseItemAnimator } from "recyclerlistview";
 const PlatformConfig = {
   defaultDrawDistance: 250,
   supportsOffsetCorrection: true,
+  trackAverageRenderTimeForOffsetProjection: true,
   // Using rotate instead of scaleY on Android to avoid performance issues. Issue: https://github.com/Shopify/flash-list/issues/751
   invertedTransformStyle: { transform: [{ rotate: "180deg" }] },
   invertedTransformStyleHorizontal: { transform: [{ rotate: "180deg" }] },

package/src/native/config/PlatformHelper.ios.ts

@@ -3,6 +3,7 @@ import { BaseItemAnimator } from "recyclerlistview";
 const PlatformConfig = {
   defaultDrawDistance: 250,
   supportsOffsetCorrection: true,
+  trackAverageRenderTimeForOffsetProjection: false,
   invertedTransformStyle: { transform: [{ scaleY: -1 }] },
   invertedTransformStyleHorizontal: { transform: [{ scaleX: -1 }] },
 };

package/src/native/config/PlatformHelper.ts

@@ -4,6 +4,7 @@ import { DefaultJSItemAnimator } from "recyclerlistview/dist/reactnative/platfor
 const PlatformConfig = {
   defaultDrawDistance: 250,
   supportsOffsetCorrection: false,
+  trackAverageRenderTimeForOffsetProjection: false,
   invertedTransformStyle: { transform: [{ scaleY: -1 }] },
   invertedTransformStyleHorizontal: { transform: [{ scaleX: -1 }] },
 };

package/src/native/config/PlatformHelper.web.ts

@@ -6,6 +6,7 @@ import { DefaultJSItemAnimator } from "recyclerlistview/dist/reactnative/platfor
 const PlatformConfig = {
   defaultDrawDistance: 500,
   supportsOffsetCorrection: false,
+  trackAverageRenderTimeForOffsetProjection: false,
   invertedTransformStyle: { transform: [{ scaleY: -1 }] },
   invertedTransformStyleHorizontal: { transform: [{ scaleX: -1 }] },
 };

package/src/recyclerview/RecyclerView.tsx

@@ -19,6 +19,8 @@ import {
   NativeSyntheticEvent,
 } from "react-native";
 
+import { FlashListRef } from "../FlashListRef";
+
 import { RVDimension } from "./layout-managers/LayoutManager";
 import {
   areDimensionsNotEqual,
@@ -47,6 +49,7 @@ import { useSecondaryProps } from "./hooks/useSecondaryProps";
 import { StickyHeaders, StickyHeaderRef } from "./components/StickyHeaders";
 import { ScrollAnchor, ScrollAnchorRef } from "./components/ScrollAnchor";
 import { useRecyclerViewController } from "./hooks/useRecyclerViewController";
+import { RenderTimeTracker } from "./helpers/RenderTimeTracker";
 
 /**
  * Main RecyclerView component that handles list rendering, scrolling, and item recycling.
@@ -54,7 +57,7 @@ import { useRecyclerViewController } from "./hooks/useRecyclerViewController";
  */
 const RecyclerViewComponent = <T,>(
   props: RecyclerViewProps<T>,
-  ref: React.Ref<any>
+  ref: React.Ref<FlashListRef<T>>
 ) => {
   // Destructure props and initialize refs
   const {
@@ -75,8 +78,6 @@ const RecyclerViewComponent = <T,>(
     ListFooterComponentStyle,
     ItemSeparatorComponent,
     renderScrollComponent,
-    onScroll,
-    disableRecycling,
     style,
     stickyHeaderIndices,
     maintainVisibleContentPosition,
@@ -84,6 +85,10 @@ const RecyclerViewComponent = <T,>(
     ...rest
   } = props;
 
+  const [renderTimeTracker] = useState(() => new RenderTimeTracker());
+
+  renderTimeTracker.startTracking();
+
   // Core refs for managing scroll view, internal view, and child container
   const scrollViewRef = useRef<CompatScroller>(null);
   const internalViewRef = useRef<CompatView>(null);
@@ -109,15 +114,19 @@ const RecyclerViewComponent = <T,>(
   );
 
   // Initialize core RecyclerView manager and content offset management
-  const { recyclerViewManager } = useRecyclerViewManager(props);
-  const { applyContentOffset, applyInitialScrollIndex } =
-    useRecyclerViewController(
-      recyclerViewManager,
-      ref,
-      scrollViewRef,
-      scrollAnchorRef,
-      props
-    );
+  const { recyclerViewManager, velocityTracker } =
+    useRecyclerViewManager(props);
+  const {
+    applyOffsetCorrection,
+    computeFirstVisibleIndexForOffsetCorrection,
+    applyInitialScrollIndex,
+    handlerMethods,
+  } = useRecyclerViewController(
+    recyclerViewManager,
+    ref,
+    scrollViewRef,
+    scrollAnchorRef
+  );
 
   // Initialize view holder collection ref
   const viewHolderCollectionRef = useRef<ViewHolderCollectionRef>(null);
@@ -126,11 +135,7 @@ const RecyclerViewComponent = <T,>(
   useOnListLoad(recyclerViewManager, onLoad);
 
   // Hook to detect when scrolling reaches list bounds
-  const { checkBounds } = useBoundDetection(
-    recyclerViewManager,
-    props,
-    scrollViewRef
-  );
+  const { checkBounds } = useBoundDetection(recyclerViewManager, scrollViewRef);
 
   const isHorizontalRTL = I18nManager.isRTL && horizontal;
 
@@ -176,6 +181,7 @@ const RecyclerViewComponent = <T,>(
    * Effect to handle layout updates for list items
    * This ensures proper positioning and recycling of items
    */
+  // eslint-disable-next-line react-hooks/exhaustive-deps
   useLayoutEffect(() => {
     if (pendingChildIds.size > 0) {
       return;
@@ -183,7 +189,7 @@ const RecyclerViewComponent = <T,>(
     const layoutInfo = Array.from(refHolder, ([index, viewHolderRef]) => {
       const layout = measureItemLayout(
         viewHolderRef.current!,
-        recyclerViewManager.getLayout(index)
+        recyclerViewManager.tryGetLayout(index)
       );
 
       // comapre height with stored layout
@@ -209,7 +215,7 @@ const RecyclerViewComponent = <T,>(
       setRenderId((prev) => prev + 1);
     } else {
       viewHolderCollectionRef.current?.commitLayout();
-      applyContentOffset();
+      applyOffsetCorrection();
     }
   });
 
@@ -221,23 +227,11 @@ const RecyclerViewComponent = <T,>(
       if (recyclerViewManager.ignoreScrollEvents) {
         return;
       }
-      let velocity = event.nativeEvent.velocity;
 
       let scrollOffset = horizontal
         ? event.nativeEvent.contentOffset.x
         : event.nativeEvent.contentOffset.y;
 
-      if (!velocity) {
-        const velocityValue =
-          recyclerViewManager.getAbsoluteLastScrollOffset() < scrollOffset
-            ? 1
-            : -1;
-        velocity = {
-          x: horizontal ? velocityValue : 0,
-          y: horizontal ? 0 : velocityValue,
-        };
-      }
-
       // Handle RTL (Right-to-Left) layout adjustments
       if (isHorizontalRTL) {
         scrollOffset = adjustOffsetForRTL(
@@ -245,18 +239,31 @@ const RecyclerViewComponent = <T,>(
           event.nativeEvent.contentSize.width,
           event.nativeEvent.layoutMeasurement.width
         );
-        if (velocity) {
-          velocity = {
-            x: -velocity.x,
-            y: velocity.y,
-          };
-        }
-      }
-      // Update scroll position and trigger re-render if needed
-      if (recyclerViewManager.updateScrollOffset(scrollOffset, velocity)) {
-        setRenderId((prev) => prev + 1);
       }
 
+      velocityTracker.computeVelocity(
+        scrollOffset,
+        recyclerViewManager.getAbsoluteLastScrollOffset(),
+        Boolean(horizontal),
+        (velocity, isMomentumEnd) => {
+          if (recyclerViewManager.ignoreScrollEvents) {
+            return;
+          }
+
+          if (isMomentumEnd) {
+            computeFirstVisibleIndexForOffsetCorrection();
+            if (!recyclerViewManager.isOffsetProjectionEnabled) {
+              return;
+            }
+            recyclerViewManager.resetVelocityCompute();
+          }
+          // Update scroll position and trigger re-render if needed
+          if (recyclerViewManager.updateScrollOffset(scrollOffset, velocity)) {
+            setRenderId((prev) => prev + 1);
+          }
+        }
+      );
+
       // Update sticky headers and check bounds
       stickyHeaderRef.current?.reportScrollEvent(event.nativeEvent);
       checkBounds();
@@ -266,22 +273,41 @@ const RecyclerViewComponent = <T,>(
       recyclerViewManager.computeItemViewability();
 
       // Call user-provided onScroll handler
-      onScroll?.(event);
+      recyclerViewManager.props.onScroll?.(event);
     },
-    [horizontal, isHorizontalRTL, recyclerViewManager]
+    [
+      checkBounds,
+      computeFirstVisibleIndexForOffsetCorrection,
+      horizontal,
+      isHorizontalRTL,
+      recyclerViewManager,
+      velocityTracker,
+    ]
   );
 
+  const parentRecyclerViewContext = useRecyclerViewContext();
+  const recyclerViewId = useId();
+
   // Create context for child components
-  const recyclerViewContext: RecyclerViewContext = useMemo(() => {
+  const recyclerViewContext: RecyclerViewContext<T> = useMemo(() => {
     return {
       layout: () => {
         setLayoutTreeId((prev) => prev + 1);
       },
       getRef: () => {
-        return ref;
+        if (recyclerViewManager.isDisposed) {
+          return null;
+        }
+        return handlerMethods;
+      },
+      getParentRef: () => {
+        return parentRecyclerViewContext?.getRef() ?? null;
+      },
+      getParentScrollViewRef: () => {
+        return parentRecyclerViewContext?.getScrollViewRef() ?? null;
       },
       getScrollViewRef: () => {
-        return scrollViewRef;
+        return scrollViewRef.current;
       },
       markChildLayoutAsPending: (id: string) => {
         pendingChildIds.add(id);
@@ -293,10 +319,13 @@ const RecyclerViewComponent = <T,>(
         }
       },
     };
-  }, [setLayoutTreeId]);
-
-  const parentRecyclerViewContext = useRecyclerViewContext();
-  const recyclerViewId = useId();
+  }, [
+    handlerMethods,
+    parentRecyclerViewContext,
+    pendingChildIds,
+    recyclerViewManager.isDisposed,
+    setLayoutTreeId,
+  ]);
 
   /**
    * Validates that item dimensions match the expected layout
@@ -328,7 +357,7 @@ const RecyclerViewComponent = <T,>(
         recyclerViewContext.layout();
       }
     },
-    [recyclerViewManager]
+    [recyclerViewContext, recyclerViewManager]
   );
 
   // Get secondary props and components
@@ -368,7 +397,14 @@ const RecyclerViewComponent = <T,>(
       );
     }
     return null;
-  }, [data, stickyHeaderIndices, renderItem, extraData]);
+  }, [
+    data,
+    stickyHeaderIndices,
+    renderItem,
+    scrollY,
+    recyclerViewManager,
+    extraData,
+  ]);
 
   // Set up scroll event handling with animation support for sticky headers
   const animatedEvent = useMemo(() => {
@@ -379,31 +415,24 @@ const RecyclerViewComponent = <T,>(
       );
     }
     return onScrollHandler;
-  }, [onScrollHandler, stickyHeaders]);
+  }, [onScrollHandler, scrollY, stickyHeaders]);
+
+  const shouldMaintainVisibleContentPosition =
+    recyclerViewManager.shouldMaintainVisibleContentPosition();
 
   const maintainVisibleContentPositionInternal = useMemo(() => {
-    if (maintainVisibleContentPosition?.disabled || horizontal) {
-      return undefined;
-    } else {
+    if (shouldMaintainVisibleContentPosition) {
       return {
         ...maintainVisibleContentPosition,
         minIndexForVisible: 0,
       };
     }
-  }, [maintainVisibleContentPosition]);
+    return undefined;
+  }, [maintainVisibleContentPosition, shouldMaintainVisibleContentPosition]);
 
   const shouldRenderFromBottom =
-    maintainVisibleContentPositionInternal?.startRenderingFromBottom ?? false;
-
-  // Calculate minimum height adjustment for bottom rendering
-  const adjustmentMinHeight = recyclerViewManager.hasLayout()
-    ? Math.max(
-        0,
-        recyclerViewManager.getWindowSize().height -
-          recyclerViewManager.getChildContainerDimensions().height -
-          recyclerViewManager.firstItemOffset
-      )
-    : 0;
+    recyclerViewManager.getDataLength() > 0 &&
+    (maintainVisibleContentPosition?.startRenderingFromBottom ?? false);
 
   // Create view for measuring bounded size
   const viewToMeasureBoundedSize = useMemo(() => {
@@ -412,12 +441,23 @@ const RecyclerViewComponent = <T,>(
         style={{
           height: horizontal ? undefined : 0,
           width: horizontal ? 0 : undefined,
-          minHeight: shouldRenderFromBottom ? adjustmentMinHeight : undefined,
         }}
         ref={firstChildViewRef}
       />
     );
-  }, [horizontal, shouldRenderFromBottom, adjustmentMinHeight]);
+  }, [horizontal]);
+
+  const scrollAnchor = useMemo(() => {
+    if (shouldMaintainVisibleContentPosition) {
+      return (
+        <ScrollAnchor
+          horizontal={Boolean(horizontal)}
+          scrollAnchorRef={scrollAnchorRef}
+        />
+      );
+    }
+    return null;
+  }, [horizontal, shouldMaintainVisibleContentPosition]);
 
   // console.log("render", recyclerViewManager.getRenderStack());
 
@@ -465,9 +505,7 @@ const RecyclerViewComponent = <T,>(
           {...overrideProps}
         >
           {/* Scroll anchor for maintaining content position */}
-          {maintainVisibleContentPositionInternal && (
-            <ScrollAnchor scrollAnchorRef={scrollAnchorRef} />
-          )}
+          {scrollAnchor}
           {isHorizontalRTL && viewToMeasureBoundedSize}
           {renderHeader}
           {!isHorizontalRTL && viewToMeasureBoundedSize}
@@ -478,6 +516,25 @@ const RecyclerViewComponent = <T,>(
             horizontal={horizontal}
             renderStack={recyclerViewManager.getRenderStack()}
             getLayout={(index) => recyclerViewManager.getLayout(index)}
+            getAdjustmentMargin={() => {
+              if (!shouldRenderFromBottom || !recyclerViewManager.hasLayout()) {
+                return 0;
+              }
+
+              const windowSize = horizontal
+                ? recyclerViewManager.getWindowSize().width
+                : recyclerViewManager.getWindowSize().height;
+              const childContainerSize = horizontal
+                ? recyclerViewManager.getChildContainerDimensions().width
+                : recyclerViewManager.getChildContainerDimensions().height;
+
+              return Math.max(
+                0,
+                windowSize -
+                  childContainerSize -
+                  recyclerViewManager.firstItemOffset
+              );
+            }}
             refHolder={refHolder}
             onSizeChanged={validateItemSize}
             renderItem={renderItem}
@@ -490,10 +547,14 @@ const RecyclerViewComponent = <T,>(
               onCommitLayoutEffect?.();
             }}
             onCommitEffect={() => {
+              renderTimeTracker.markRenderComplete();
+              recyclerViewManager.updateAverageRenderTime(
+                renderTimeTracker.getAverageRenderTime()
+              );
               applyInitialScrollIndex();
               checkBounds();
               recyclerViewManager.computeItemViewability();
-              recyclerViewManager.disableRecycling = Boolean(disableRecycling);
+              recyclerViewManager.animationOptimizationsEnabled = false;
             }}
             CellRendererComponent={CellRendererComponent}
             ItemSeparatorComponent={ItemSeparatorComponent}
@@ -512,9 +573,12 @@ const RecyclerViewComponent = <T,>(
   );
 };
 
+// Set displayName for the inner component
+RecyclerViewComponent.displayName = "FlashList";
+
 // Type definition for the RecyclerView component
 type RecyclerViewType = <T>(
-  props: RecyclerViewProps<T> & { ref?: React.Ref<any> }
+  props: RecyclerViewProps<T> & { ref?: React.Ref<FlashListRef<T>> }
 ) => React.JSX.Element;
 
 // Create and export the memoized, forwarded ref component

package/src/recyclerview/RecyclerViewContextProvider.ts

@@ -1,20 +1,65 @@
 import { createContext, useContext } from "react";
 
+import { FlashListRef } from "../FlashListRef";
+
 import { CompatScroller } from "./components/CompatScroller";
 
-export interface RecyclerViewContext {
-  layout: () => void;
-  getRef: () => React.Ref<any>;
-  getScrollViewRef: () => React.RefObject<CompatScroller | null>;
+export interface RecyclerViewContext<T> extends FlashListContext<T> {
+  /**
+   * Mark the children FlashLists as pending for layout
+   * This will force parent FlashList to wait for children to be laid out before
+   * rendering the next batch of items.
+   * @param id - The id of the child FlashList
+   * @returns void
+   */
   markChildLayoutAsPending: (id: string) => void;
+  /**
+   * Unmark the child FlashList as pending for layout
+   * This will allow parent FlashList to render the next batch of items.
+   * @param id - The id of the child FlashList
+   * @returns void
+   */
   unmarkChildLayoutAsPending: (id: string) => void;
 }
 
+export interface FlashListContext<T> {
+  /**
+   * Layout the current FlashList
+   * @returns void
+   */
+  layout: () => void;
+  /**
+   * Get the ref for the current FlashList
+   */
+  getRef: () => FlashListRef<T> | null;
+  /**
+   * Get the ref for the parent FlashList if present
+   */
+  getParentRef: () => FlashListRef<unknown> | null;
+  /**
+   * Get the scrollView ref for the current FlashList if present
+   */
+  getScrollViewRef: () => CompatScroller | null;
+  /**
+   * Get the scrollView ref for the parent FlashList if present
+   */
+  getParentScrollViewRef: () => CompatScroller | null;
+}
+
 const RecyclerViewContextInstance = createContext<
-  RecyclerViewContext | undefined
+  RecyclerViewContext<unknown> | undefined
 >(undefined);
 
 export const RecyclerViewContextProvider = RecyclerViewContextInstance.Provider;
-export function useRecyclerViewContext() {
-  return useContext(RecyclerViewContextInstance);
+export function useRecyclerViewContext<T>():
+  | RecyclerViewContext<T>
+  | undefined {
+  return useContext(RecyclerViewContextInstance) as
+    | RecyclerViewContext<T>
+    | undefined;
+}
+export function useFlashListContext<T>(): FlashListContext<T> | undefined {
+  return useContext(RecyclerViewContextInstance) as
+    | FlashListContext<T>
+    | undefined;
 }