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

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,

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,14 +114,14 @@ const RecyclerViewComponent = <T,>(
   );
 
   // Initialize core RecyclerView manager and content offset management
-  const { recyclerViewManager } = useRecyclerViewManager(props);
-  const { applyContentOffset, applyInitialScrollIndex } =
+  const { recyclerViewManager, velocityTracker } =
+    useRecyclerViewManager(props);
+  const { applyContentOffset, applyInitialScrollIndex, handlerMethods } =
     useRecyclerViewController(
       recyclerViewManager,
       ref,
       scrollViewRef,
-      scrollAnchorRef,
-      props
+      scrollAnchorRef
     );
 
   // Initialize view holder collection ref
@@ -126,11 +131,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 +177,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 +185,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
@@ -221,23 +223,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 +235,30 @@ 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) {
+            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 +268,31 @@ const RecyclerViewComponent = <T,>(
       recyclerViewManager.computeItemViewability();
 
       // Call user-provided onScroll handler
-      onScroll?.(event);
+      recyclerViewManager.props.onScroll?.(event);
     },
-    [horizontal, isHorizontalRTL, recyclerViewManager]
+    [
+      checkBounds,
+      horizontal,
+      isHorizontalRTL,
+      recyclerViewManager,
+      velocityTracker,
+    ]
   );
 
   // 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;
       },
       getScrollViewRef: () => {
-        return scrollViewRef;
+        return scrollViewRef.current;
       },
       markChildLayoutAsPending: (id: string) => {
         pendingChildIds.add(id);
@@ -293,7 +304,7 @@ const RecyclerViewComponent = <T,>(
         }
       },
     };
-  }, [setLayoutTreeId]);
+  }, [handlerMethods, pendingChildIds, recyclerViewManager, setLayoutTreeId]);
 
   const parentRecyclerViewContext = useRecyclerViewContext();
   const recyclerViewId = useId();
@@ -328,7 +339,7 @@ const RecyclerViewComponent = <T,>(
         recyclerViewContext.layout();
       }
     },
-    [recyclerViewManager]
+    [recyclerViewContext, recyclerViewManager]
   );
 
   // Get secondary props and components
@@ -368,7 +379,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,21 +397,23 @@ 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;
+    maintainVisibleContentPosition?.startRenderingFromBottom ?? false;
 
   // Calculate minimum height adjustment for bottom rendering
   const adjustmentMinHeight = recyclerViewManager.hasLayout()
@@ -466,7 +486,10 @@ const RecyclerViewComponent = <T,>(
         >
           {/* Scroll anchor for maintaining content position */}
           {maintainVisibleContentPositionInternal && (
-            <ScrollAnchor scrollAnchorRef={scrollAnchorRef} />
+            <ScrollAnchor
+              horizontal={Boolean(horizontal)}
+              scrollAnchorRef={scrollAnchorRef}
+            />
           )}
           {isHorizontalRTL && viewToMeasureBoundedSize}
           {renderHeader}
@@ -490,10 +513,14 @@ const RecyclerViewComponent = <T,>(
               onCommitLayoutEffect?.();
             }}
             onCommitEffect={() => {
+              renderTimeTracker.markRenderComplete();
+              recyclerViewManager.updateAverageRenderTime(
+                renderTimeTracker.getAverageRenderTime()
+              );
               applyInitialScrollIndex();
               checkBounds();
               recyclerViewManager.computeItemViewability();
-              recyclerViewManager.disableRecycling = Boolean(disableRecycling);
+              recyclerViewManager.disableRecycling(false);
             }}
             CellRendererComponent={CellRendererComponent}
             ItemSeparatorComponent={ItemSeparatorComponent}
@@ -512,9 +539,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,26 @@
 import { createContext, useContext } from "react";
 
+import { FlashListRef } from "../FlashListRef";
+
 import { CompatScroller } from "./components/CompatScroller";
 
-export interface RecyclerViewContext {
+export interface RecyclerViewContext<T> {
   layout: () => void;
-  getRef: () => React.Ref<any>;
-  getScrollViewRef: () => React.RefObject<CompatScroller | null>;
+  getRef: () => FlashListRef<T> | null;
+  getScrollViewRef: () => CompatScroller | null;
   markChildLayoutAsPending: (id: string) => void;
   unmarkChildLayoutAsPending: (id: string) => void;
 }
 
 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;
 }