@shopify/flash-list 2.0.0-alpha.10 → 2.0.0-alpha.11

package/src/recyclerview/hooks/useRecyclerViewController.tsx

@@ -8,7 +8,13 @@ import {
 } from "react";
 import { I18nManager } from "react-native";
 
-import { RecyclerViewProps } from "../RecyclerViewProps";
+import {
+  ScrollToOffsetParams,
+  ScrollToIndexParams,
+  ScrollToItemParams,
+  ScrollToEdgeParams,
+  FlashListRef,
+} from "../../FlashListRef";
 import { CompatScroller } from "../components/CompatScroller";
 import { RecyclerViewManager } from "../RecyclerViewManager";
 import { adjustOffsetForRTL } from "../utils/adjustOffsetForRTL";
@@ -17,58 +23,7 @@ import { ScrollAnchorRef } from "../components/ScrollAnchor";
 import { PlatformConfig } from "../../native/config/PlatformHelper";
 
 import { useUnmountFlag } from "./useUnmountFlag";
-import { useUnmountAwareCallbacks } from "./useUnmountAwareCallbacks";
-
-/**
- * Parameters for scrolling to a specific position in the list.
- * Extends ScrollToEdgeParams to include view positioning options.
- */
-export interface ScrollToParams extends ScrollToEdgeParams {
-  /** Position of the target item relative to the viewport (0 = top, 0.5 = center, 1 = bottom) */
-  viewPosition?: number;
-  /** Additional offset to apply after viewPosition calculation */
-  viewOffset?: number;
-}
-
-/**
- * Parameters for scrolling to a specific offset in the list.
- * Used when you want to scroll to an exact pixel position.
- */
-export interface ScrollToOffsetParams extends ScrollToParams {
-  /** The pixel offset to scroll to */
-  offset: number;
-  /**
-   * If true, the first item offset will not be added to the offset calculation.
-   * First offset represents header size or top padding.
-   */
-  skipFirstItemOffset?: boolean;
-}
-
-/**
- * Parameters for scrolling to a specific index in the list.
- * Used when you want to scroll to a specific item by its position in the data array.
- */
-export interface ScrollToIndexParams extends ScrollToParams {
-  /** The index of the item to scroll to */
-  index: number;
-}
-
-/**
- * Parameters for scrolling to a specific item in the list.
- * Used when you want to scroll to a specific item by its data value.
- */
-export interface ScrollToItemParams<T> extends ScrollToParams {
-  /** The item to scroll to */
-  item: T;
-}
-
-/**
- * Base parameters for scrolling to the edges of the list.
- */
-export interface ScrollToEdgeParams {
-  /** Whether the scroll should be animated */
-  animated?: boolean;
-}
+import { useUnmountAwareTimeout } from "./useUnmountAwareCallbacks";
 
 /**
  * Comprehensive hook that manages RecyclerView scrolling behavior and provides
@@ -88,61 +43,22 @@ export interface ScrollToEdgeParams {
  */
 export function useRecyclerViewController<T>(
   recyclerViewManager: RecyclerViewManager<T>,
-  ref: React.Ref<any>,
+  ref: React.Ref<FlashListRef<T>>,
   scrollViewRef: RefObject<CompatScroller>,
-  scrollAnchorRef: React.RefObject<ScrollAnchorRef>,
-  props: RecyclerViewProps<T>
+  scrollAnchorRef: React.RefObject<ScrollAnchorRef>
 ) {
-  const { horizontal, data } = props;
   const isUnmounted = useUnmountFlag();
   const [_, setRenderId] = useState(0);
   const pauseOffsetCorrection = useRef(false);
   const initialScrollCompletedRef = useRef(false);
-  const lastDataLengthRef = useRef(data?.length ?? 0);
-  const { setTimeout } = useUnmountAwareCallbacks();
+  const lastDataLengthRef = useRef(recyclerViewManager.props.data?.length ?? 0);
+  const { setTimeout } = useUnmountAwareTimeout();
 
   // Track the first visible item for maintaining scroll position
   const firstVisibleItemKey = useRef<string | undefined>(undefined);
   const firstVisibleItemLayout = useRef<RVLayout | undefined>(undefined);
   const pendingScrollResolves = useRef<(() => void)[]>([]);
 
-  const applyInitialScrollIndex = useCallback(() => {
-    const initialScrollIndex =
-      recyclerViewManager.getInitialScrollIndex() ?? -1;
-    const dataLength = props.data?.length ?? 0;
-    if (
-      initialScrollIndex >= 0 &&
-      initialScrollIndex < dataLength &&
-      !initialScrollCompletedRef.current &&
-      recyclerViewManager.getIsFirstLayoutComplete()
-    ) {
-      // Use setTimeout to ensure that we keep trying to scroll on first few renders
-      setTimeout(() => {
-        initialScrollCompletedRef.current = true;
-        pauseOffsetCorrection.current = false;
-      }, 100);
-
-      pauseOffsetCorrection.current = true;
-
-      const offset = horizontal
-        ? recyclerViewManager.getLayout(initialScrollIndex).x
-        : recyclerViewManager.getLayout(initialScrollIndex).y;
-      handlerMethods.scrollToOffset({
-        offset,
-        animated: false,
-        skipFirstItemOffset: false,
-      });
-
-      setTimeout(() => {
-        handlerMethods.scrollToOffset({
-          offset,
-          animated: false,
-          skipFirstItemOffset: false,
-        });
-      }, 0);
-    }
-  }, [recyclerViewManager, props.data]);
-
   // Handle initial scroll position when the list first loads
   //   useOnLoad(recyclerViewManager, () => {
 
@@ -173,19 +89,21 @@ export function useRecyclerViewController<T>(
    * the user's current view position when new messages are added.
    */
   const applyContentOffset = useCallback(async () => {
+    const { horizontal, data, keyExtractor, maintainVisibleContentPosition } =
+      recyclerViewManager.props;
     // Resolve all pending scroll updates from previous calls
     const resolves = pendingScrollResolves.current;
     pendingScrollResolves.current = [];
     resolves.forEach((resolve) => resolve());
 
-    const currentDataLength = props.data?.length ?? 0;
+    const currentDataLength = data?.length ?? 0;
 
     if (
-      !props.horizontal &&
+      !horizontal &&
       recyclerViewManager.getIsFirstLayoutComplete() &&
-      props.keyExtractor &&
+      keyExtractor &&
       currentDataLength > 0 &&
-      props.maintainVisibleContentPosition?.disabled !== true
+      maintainVisibleContentPosition?.disabled !== true
     ) {
       const hasDataChanged = currentDataLength !== lastDataLengthRef.current;
       // If we have a tracked first visible item, maintain its position
@@ -195,14 +113,13 @@ export function useRecyclerViewController<T>(
             .getEngagedIndices()
             .findValue(
               (index) =>
-                props.keyExtractor?.(props.data![index], index) ===
+                keyExtractor?.(data![index], index) ===
                 firstVisibleItemKey.current
             ) ??
           (hasDataChanged
-            ? props.data?.findIndex(
+            ? data?.findIndex(
                 (item, index) =>
-                  props.keyExtractor?.(item, index) ===
-                  firstVisibleItemKey.current
+                  keyExtractor?.(item, index) === firstVisibleItemKey.current
               )
             : undefined);
 
@@ -240,11 +157,11 @@ export function useRecyclerViewController<T>(
       // Update the tracked first visible item
       const firstVisibleIndex = Math.max(
         0,
-        recyclerViewManager.getVisibleIndices().startIndex
+        recyclerViewManager.computeVisibleIndices().startIndex
       );
       if (firstVisibleIndex !== undefined && firstVisibleIndex >= 0) {
-        firstVisibleItemKey.current = props.keyExtractor(
-          props.data![firstVisibleIndex],
+        firstVisibleItemKey.current = keyExtractor(
+          data![firstVisibleIndex],
           firstVisibleIndex
         );
         firstVisibleItemLayout.current = {
@@ -252,12 +169,20 @@ export function useRecyclerViewController<T>(
         };
       }
     }
-    lastDataLengthRef.current = props.data?.length ?? 0;
-  }, [props.data, props.keyExtractor, recyclerViewManager, setTimeout]);
-
-  const handlerMethods = useMemo(() => {
+    lastDataLengthRef.current = data?.length ?? 0;
+  }, [
+    recyclerViewManager,
+    scrollAnchorRef,
+    scrollViewRef,
+    setTimeout,
+    updateScrollOffsetAsync,
+  ]);
+
+  const handlerMethods: FlashListRef<T> = useMemo(() => {
     return {
-      props,
+      get props() {
+        return recyclerViewManager.props;
+      },
       /**
        * Scrolls the list to a specific offset position.
        * Handles RTL layouts and first item offset adjustments.
@@ -267,6 +192,7 @@ export function useRecyclerViewController<T>(
         animated,
         skipFirstItemOffset = true,
       }: ScrollToOffsetParams) => {
+        const { horizontal } = recyclerViewManager.props;
         if (scrollViewRef.current) {
           // Adjust offset for RTL layouts in horizontal mode
           if (I18nManager.isRTL && horizontal) {
@@ -314,6 +240,7 @@ export function useRecyclerViewController<T>(
        * Scrolls to the end of the list.
        */
       scrollToEnd: async ({ animated }: ScrollToEdgeParams = {}) => {
+        const { data } = recyclerViewManager.props;
         if (data && data.length > 0) {
           await handlerMethods.scrollToIndex({
             index: data.length - 1,
@@ -345,11 +272,11 @@ export function useRecyclerViewController<T>(
         viewPosition,
         viewOffset,
       }: ScrollToIndexParams) => {
+        const { horizontal } = recyclerViewManager.props;
         if (
           scrollViewRef.current &&
-          data &&
           index >= 0 &&
-          index < data.length
+          index < recyclerViewManager.getDataLength()
         ) {
           // Pause the scroll offset adjustments
           pauseOffsetCorrection.current = true;
@@ -424,6 +351,14 @@ export function useRecyclerViewController<T>(
               : startScrollOffset +
                 (finalOffset - startScrollOffset) * (i / (steps - 1));
             await updateScrollOffsetAsync(nextOffset);
+
+            // In case some change happens in the middle of this operation
+            // and the index is out of bounds, scroll to the end
+            if (index >= recyclerViewManager.getDataLength()) {
+              handlerMethods.scrollToEnd({ animated });
+              return;
+            }
+
             const newFinalOffset = getFinalOffset();
             if (
               (newFinalOffset < initialTargetOffset &&
@@ -480,11 +415,10 @@ export function useRecyclerViewController<T>(
         viewPosition,
         viewOffset,
       }: ScrollToItemParams<T>) => {
+        const { data } = recyclerViewManager.props;
         if (scrollViewRef.current && data) {
           // Find the index of the item in the data array
-          const index = Array.from(data).findIndex(
-            (dataItem) => dataItem === item
-          );
+          const index = data.findIndex((dataItem) => dataItem === item);
           if (index >= 0) {
             handlerMethods.scrollToIndex({
               index,
@@ -504,7 +438,7 @@ export function useRecyclerViewController<T>(
         return recyclerViewManager.getWindowSize();
       },
       getLayout: (index: number) => {
-        return recyclerViewManager.getLayout(index);
+        return recyclerViewManager.tryGetLayout(index);
       },
       getAbsoluteLastScrollOffset: () => {
         return recyclerViewManager.getAbsoluteLastScrollOffset();
@@ -515,11 +449,11 @@ export function useRecyclerViewController<T>(
       recordInteraction: () => {
         recyclerViewManager.recordInteraction();
       },
-      getVisibleIndices: () => {
-        return recyclerViewManager.getVisibleIndices();
+      computeVisibleIndices: () => {
+        return recyclerViewManager.computeVisibleIndices();
       },
       getFirstVisibleIndex: () => {
-        return recyclerViewManager.getVisibleIndices().startIndex;
+        return recyclerViewManager.computeVisibleIndices().startIndex;
       },
       recomputeViewableItems: () => {
         recyclerViewManager.recomputeViewableItems();
@@ -528,10 +462,55 @@ export function useRecyclerViewController<T>(
        * Disables item recycling in preparation for layout animations.
        */
       prepareForLayoutAnimationRender: () => {
-        recyclerViewManager.disableRecycling = true;
+        recyclerViewManager.disableRecycling(true);
       },
     };
-  }, [horizontal, data, recyclerViewManager]);
+  }, [
+    recyclerViewManager,
+    scrollViewRef,
+    setTimeout,
+    isUnmounted,
+    updateScrollOffsetAsync,
+  ]);
+
+  const applyInitialScrollIndex = useCallback(() => {
+    const { horizontal, data } = recyclerViewManager.props;
+
+    const initialScrollIndex =
+      recyclerViewManager.getInitialScrollIndex() ?? -1;
+    const dataLength = data?.length ?? 0;
+    if (
+      initialScrollIndex >= 0 &&
+      initialScrollIndex < dataLength &&
+      !initialScrollCompletedRef.current &&
+      recyclerViewManager.getIsFirstLayoutComplete()
+    ) {
+      // Use setTimeout to ensure that we keep trying to scroll on first few renders
+      setTimeout(() => {
+        initialScrollCompletedRef.current = true;
+        pauseOffsetCorrection.current = false;
+      }, 100);
+
+      pauseOffsetCorrection.current = true;
+
+      const offset = horizontal
+        ? recyclerViewManager.getLayout(initialScrollIndex).x
+        : recyclerViewManager.getLayout(initialScrollIndex).y;
+      handlerMethods.scrollToOffset({
+        offset,
+        animated: false,
+        skipFirstItemOffset: false,
+      });
+
+      setTimeout(() => {
+        handlerMethods.scrollToOffset({
+          offset,
+          animated: false,
+          skipFirstItemOffset: false,
+        });
+      }, 0);
+    }
+  }, [handlerMethods, recyclerViewManager, setTimeout]);
 
   // Expose imperative methods through the ref
   useImperativeHandle(
@@ -539,8 +518,8 @@ export function useRecyclerViewController<T>(
     () => {
       return { ...scrollViewRef.current, ...handlerMethods };
     },
-    [handlerMethods]
+    [handlerMethods, scrollViewRef]
   );
 
-  return { applyContentOffset, applyInitialScrollIndex };
+  return { applyContentOffset, applyInitialScrollIndex, handlerMethods };
 }

package/src/recyclerview/hooks/useRecyclerViewManager.ts

@@ -14,6 +14,8 @@ export const useRecyclerViewManager = <T>(props: RecyclerViewProps<T>) => {
 
   useMemo(() => {
     recyclerViewManager.updateProps(props);
+    // used to update props so rule can be disabled
+    // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [props]);
 
   /**
@@ -21,6 +23,8 @@ export const useRecyclerViewManager = <T>(props: RecyclerViewProps<T>) => {
    */
   useMemo(() => {
     recyclerViewManager.processDataUpdate();
+    // used to process data update so rule can be disabled
+    // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [data]);
 
   useEffect(() => {
@@ -28,6 +32,8 @@ export const useRecyclerViewManager = <T>(props: RecyclerViewProps<T>) => {
       recyclerViewManager.dispose();
       velocityTracker.cleanUp();
     };
+    // needs to run only on unmount
+    // eslint-disable-next-line react-hooks/exhaustive-deps
   }, []);
 
   return { recyclerViewManager, velocityTracker };

package/src/recyclerview/hooks/useSecondaryProps.tsx

@@ -105,7 +105,7 @@ export function useSecondaryProps<T>(props: RecyclerViewProps<T>) {
       const ForwardedScrollComponent = React.forwardRef((_props, ref) =>
         (renderScrollComponent as any)({ ..._props, ref } as any)
       );
-      ForwardedScrollComponent.displayName = "CompatScrollView";
+      ForwardedScrollComponent.displayName = "CustomScrollView";
       scrollComponent = ForwardedScrollComponent as any;
     } else if (renderScrollComponent) {
       scrollComponent = renderScrollComponent;

package/src/recyclerview/hooks/useUnmountAwareCallbacks.ts

@@ -1,10 +1,10 @@
 import { useCallback, useEffect, useState } from "react";
 
 /**
- * Hook that provides callbacks which are aware of component unmount state.
- * Any timeouts created with these callbacks will be automatically cleared when the component unmounts.
+ * Hook that provides a setTimeout which is aware of component unmount state.
+ * Any timeouts created with this hook will be automatically cleared when the component unmounts.
  */
-export function useUnmountAwareCallbacks() {
+export function useUnmountAwareTimeout() {
   // Store active timeout IDs in a Set for more efficient add/remove operations
   const [timeoutIds] = useState<Set<NodeJS.Timeout>>(() => new Set());
 
@@ -35,3 +35,39 @@ export function useUnmountAwareCallbacks() {
     setTimeout,
   };
 }
+
+/**
+ * Hook that provides a requestAnimationFrame which is aware of component unmount state.
+ * Any animation frames requested with this hook will be automatically canceled when the component unmounts.
+ */
+export function useUnmountAwareAnimationFrame() {
+  // Store active animation frame request IDs in a Set for more efficient add/remove operations
+  const [requestIds] = useState<Set<number>>(() => new Set());
+
+  // Cancel all animation frame requests on unmount
+  useEffect(() => {
+    return () => {
+      requestIds.forEach((id) => cancelAnimationFrame(id));
+      requestIds.clear();
+    };
+  }, [requestIds]);
+
+  // Create a safe requestAnimationFrame that will be canceled on unmount
+  const requestAnimationFrame = useCallback(
+    (callback: FrameRequestCallback): void => {
+      const id = global.requestAnimationFrame((timestamp) => {
+        // Remove this request ID from the tracking set
+        requestIds.delete(id);
+        callback(timestamp);
+      });
+
+      // Track this request ID
+      requestIds.add(id);
+    },
+    [requestIds]
+  );
+
+  return {
+    requestAnimationFrame,
+  };
+}

package/src/recyclerview/layout-managers/GridLayoutManager.ts

@@ -78,12 +78,10 @@ export class RVGridLayoutManagerImpl extends RVLayoutManager {
    */
   getLayoutSize(): RVDimension {
     if (this.layouts.length === 0) return { width: 0, height: 0 };
-    const lastRowTallestItem = this.processAndReturnTallestItemInRow(
-      this.layouts.length - 1
-    );
+    const totalHeight = this.computeTotalHeight(this.layouts.length - 1);
     return {
       width: this.boundedSize,
-      height: lastRowTallestItem.y + lastRowTallestItem.height,
+      height: totalHeight,
     };
   }
 
@@ -93,7 +91,9 @@ export class RVGridLayoutManagerImpl extends RVLayoutManager {
    * @param endIndex Ending index of items to recompute
    */
   recomputeLayouts(startIndex: number, endIndex: number): void {
-    const newStartIndex = this.locateFirstNeighbourIndex(startIndex);
+    const newStartIndex = this.locateFirstNeighbourIndex(
+      Math.max(0, startIndex - 1)
+    );
     const startVal = this.getLayout(newStartIndex);
 
     let startX = startVal.x;
@@ -102,7 +102,7 @@ export class RVGridLayoutManagerImpl extends RVLayoutManager {
     for (let i = newStartIndex; i <= endIndex; i++) {
       const layout = this.getLayout(i);
       if (!this.checkBounds(startX, layout.width)) {
-        const tallestItem = this.processAndReturnTallestItemInRow(i);
+        const tallestItem = this.processAndReturnTallestItemInRow(i - 1);
         startY = tallestItem.y + tallestItem.height;
         startX = 0;
       }
@@ -111,6 +111,9 @@ export class RVGridLayoutManagerImpl extends RVLayoutManager {
       layout.y = startY;
       startX += layout.width;
     }
+    if (endIndex === this.layouts.length - 1) {
+      this.processAndReturnTallestItemInRow(endIndex);
+    }
   }
 
   /**
@@ -182,6 +185,26 @@ export class RVGridLayoutManagerImpl extends RVLayoutManager {
     return tallestItem;
   }
 
+  /**
+   * Computes the total height of the layout.
+   * @param index Index of the last item in the layout
+   * @returns Total height of the layout
+   */
+  private computeTotalHeight(index: number): number {
+    const startIndex = this.locateFirstNeighbourIndex(index);
+    const y = this.layouts[startIndex].y;
+    let maxHeight = 0;
+    let i = startIndex;
+    while (Math.ceil(this.layouts[i].y) === Math.ceil(y)) {
+      maxHeight = Math.max(maxHeight, this.layouts[i].height);
+      i++;
+      if (i >= this.layouts.length) {
+        break;
+      }
+    }
+    return y + maxHeight;
+  }
+
   /**
    * Checks if an item can fit within the bounded width.
    * @param itemX Starting X position of the item
@@ -201,7 +224,7 @@ export class RVGridLayoutManagerImpl extends RVLayoutManager {
     if (startIndex === 0) {
       return 0;
     }
-    let i = startIndex - 1;
+    let i = startIndex;
     for (; i >= 0; i--) {
       if (this.layouts[i].x === 0) {
         break;

package/src/recyclerview/layout-managers/LayoutManager.ts

@@ -114,8 +114,8 @@ export abstract class RVLayoutManager {
   /**
    * Gets indices of items currently visible in the viewport.
    * Uses binary search for efficient lookup.
-   * @param unboundDimensionStart Start position of viewport
-   * @param unboundDimensionEnd End position of viewport
+   * @param unboundDimensionStart Start position of viewport (start X or start Y)
+   * @param unboundDimensionEnd End position of viewport (end X or end Y)
    * @returns ConsecutiveNumbers containing visible indices
    */
   getVisibleLayouts(

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

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

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

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