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

package/src/recyclerview/RenderStackManager.ts

@@ -0,0 +1,265 @@
+import { ConsecutiveNumbers } from "./helpers/ConsecutiveNumbers";
+
+/**
+ * Manages the recycling of rendered items in a virtualized list.
+ * This class handles tracking, recycling, and reusing item keys to optimize
+ * rendering performance by minimizing creation/destruction of components.
+ */
+export class RenderStackManager {
+  public disableRecycling = false;
+
+  // Maximum number of items that can be in the recycle pool
+  private maxItemsInRecyclePool: number;
+
+  // Stores pools of recycled keys for each item type
+  private recycleKeyPools: Map<string, Set<string>>;
+
+  // Maps active keys to their metadata (item type and stable ID)
+  private keyMap: Map<
+    string,
+    { itemType: string; index: number; stableId: string }
+  >;
+
+  // Maps stable IDs to their corresponding keys for quick lookups
+  private stableIdMap: Map<string, string>;
+
+  // Counter for generating unique sequential keys
+  private keyCounter: number;
+
+  /**
+   * @param maxItemsInRecyclePool - Maximum number of items that can be in the recycle pool
+   */
+  constructor(maxItemsInRecyclePool: number = Number.MAX_SAFE_INTEGER) {
+    this.maxItemsInRecyclePool = maxItemsInRecyclePool;
+    this.recycleKeyPools = new Map();
+    this.keyMap = new Map();
+    this.stableIdMap = new Map();
+    this.keyCounter = 0;
+  }
+
+  /**
+   * Synchronizes the render stack with the current state of data.
+   * This method is the core orchestrator that:
+   * 1. Recycles keys for items that are no longer valid
+   * 2. Updates existing keys for items that remain visible
+   * 3. Assigns new keys for newly visible items
+   * 4. Cleans up excess items to maintain the recycling pool size
+   *
+   * @param getStableId - Function to get a stable identifier for an item at a specific index
+   * @param getItemType - Function to get the type of an item at a specific index
+   * @param engagedIndices - Collection of indices that are currently visible or engaged
+   * @param dataLength - Total length of the data set
+   */
+  public sync(
+    getStableId: (index: number) => string,
+    getItemType: (index: number) => string,
+    engagedIndices: ConsecutiveNumbers,
+    dataLength: number
+  ) {
+    if (this.disableRecycling) {
+      this.clearRecyclePool();
+    }
+    // Recycle keys for items that are no longer valid or visible
+    this.keyMap.forEach((keyInfo, key) => {
+      const { index, stableId, itemType } = keyInfo;
+      if (index >= dataLength) {
+        this.recycleKey(key);
+        return;
+      }
+      const newStableId = getStableId(index);
+      const newItemType = getItemType(index);
+      if (stableId !== newStableId || itemType !== newItemType) {
+        this.recycleKey(key);
+        return;
+      }
+      if (!engagedIndices.includes(index)) {
+        this.recycleKey(key);
+      }
+    });
+
+    // First pass: process items that already have optimized keys
+    for (const index of engagedIndices) {
+      if (this.hasOptimizedKey(getStableId(index))) {
+        this.syncItem(index, getItemType(index), getStableId(index));
+      }
+    }
+
+    // Second pass: process remaining items that need new keys
+    for (const index of engagedIndices) {
+      if (!this.hasOptimizedKey(getStableId(index))) {
+        this.syncItem(index, getItemType(index), getStableId(index));
+      }
+    }
+
+    // Clean up stale items and manage the recycle pool size
+    this.cleanup(getStableId, engagedIndices, dataLength);
+  }
+
+  /**
+   * Checks if a stable ID already has an assigned key
+   */
+  private hasOptimizedKey(stableId: string): boolean {
+    return this.stableIdMap.has(stableId);
+  }
+
+  /**
+   * Cleans up stale keys and manages the recycle pool size.
+   * This ensures we don't maintain references to items that are no longer in the dataset,
+   * and limits the number of recycled items to avoid excessive memory usage.
+   */
+  private cleanup(
+    getStableId: (index: number) => string,
+    engagedIndices: ConsecutiveNumbers,
+    dataLength: number
+  ) {
+    const itemsToDelete = new Array<string>();
+
+    // Remove items that are no longer in the dataset
+    for (const [key, keyInfo] of this.keyMap.entries()) {
+      const { index, itemType, stableId } = keyInfo;
+      if (index >= dataLength || getStableId(index) !== stableId) {
+        this.deleteKeyFromRecyclePool(itemType, key);
+        this.stableIdMap.delete(stableId);
+        itemsToDelete.push(key);
+      }
+    }
+
+    for (const key of itemsToDelete) {
+      this.keyMap.delete(key);
+    }
+
+    // Limit the size of the recycle pool
+    const itemsRenderedForRecycling = this.keyMap.size - engagedIndices.length;
+    if (itemsRenderedForRecycling > this.maxItemsInRecyclePool) {
+      const deleteCount =
+        itemsRenderedForRecycling - this.maxItemsInRecyclePool;
+      let deleted = 0;
+
+      // Use a for loop so we can break early once we've deleted enough items
+      const entries = Array.from(this.keyMap.entries()).reverse();
+      for (let i = 0; i < entries.length && deleted < deleteCount; i++) {
+        const [key, keyInfo] = entries[i];
+        const { index, itemType, stableId } = keyInfo;
+
+        if (!engagedIndices.includes(index)) {
+          this.deleteKeyFromRecyclePool(itemType, key);
+          this.stableIdMap.delete(stableId);
+          this.keyMap.delete(key);
+          deleted++;
+        }
+      }
+    }
+  }
+
+  /**
+   * Places a key back into its type-specific recycle pool for future reuse
+   */
+  private recycleKey(key: string): void {
+    if (this.disableRecycling) {
+      return;
+    }
+    const keyInfo = this.keyMap.get(key);
+
+    if (!keyInfo) {
+      return;
+    }
+
+    const { itemType } = keyInfo;
+
+    // Add key back to its type's pool
+    const pool = this.getRecyclePoolForType(itemType);
+
+    pool.add(key);
+  }
+
+  /**
+   * Returns the current render stack containing all active keys and their metadata
+   */
+  public getRenderStack() {
+    return this.keyMap;
+  }
+
+  /**
+   * Syncs an individual item by assigning it an appropriate key.
+   * Will use an existing key if available, or generate a new one.
+   *
+   * @returns The key assigned to the item
+   */
+  private syncItem(index: number, itemType: string, stableId: string): string {
+    // Try to reuse an existing key, or get one from the recycle pool, or generate a new one
+    const newKey =
+      this.stableIdMap.get(stableId) ||
+      this.getKeyFromRecyclePool(itemType) ||
+      this.generateKey();
+
+    const keyInfo = this.keyMap.get(newKey);
+    if (keyInfo) {
+      // Update an existing key's metadata
+      this.deleteKeyFromRecyclePool(itemType, newKey);
+      this.deleteKeyFromRecyclePool(keyInfo.itemType, newKey);
+      this.stableIdMap.delete(keyInfo.stableId);
+      keyInfo.index = index;
+      keyInfo.itemType = itemType;
+      keyInfo.stableId = stableId;
+    } else {
+      // Create a new entry in the key map
+      this.keyMap.set(newKey, {
+        itemType,
+        index,
+        stableId,
+      });
+    }
+    this.stableIdMap.set(stableId, newKey);
+
+    return newKey;
+  }
+
+  /**
+   * Clears all recycled keys from the pool, effectively resetting the recycling system.
+   * This operation does not affect currently active keys.
+   */
+  private clearRecyclePool() {
+    this.recycleKeyPools.clear();
+  }
+
+  /**
+   * Generates a unique sequential key using an internal counter.
+   * @returns A unique key as a string
+   */
+  private generateKey(): string {
+    return (this.keyCounter++).toString();
+  }
+
+  /**
+   * Removes a specific key from its type's recycle pool
+   */
+  private deleteKeyFromRecyclePool(itemType: string, key: string) {
+    this.recycleKeyPools.get(itemType)?.delete(key);
+  }
+
+  /**
+   * Gets or creates a recycle pool for a specific item type
+   */
+  private getRecyclePoolForType(itemType: string) {
+    let pool = this.recycleKeyPools.get(itemType);
+    if (!pool) {
+      pool = new Set();
+      this.recycleKeyPools.set(itemType, pool);
+    }
+    return pool;
+  }
+
+  /**
+   * Retrieves and removes a key from the type's recycle pool
+   * @returns A recycled key or undefined if none available
+   */
+  private getKeyFromRecyclePool(itemType: string) {
+    const pool = this.getRecyclePoolForType(itemType);
+    if (pool.size > 0) {
+      const key = pool.values().next().value;
+      pool.delete(key);
+      return key;
+    }
+    return undefined;
+  }
+}

package/src/recyclerview/ViewHolder.tsx

@@ -88,7 +88,7 @@ const ViewHolderInternal = <TItem,>(props: ViewHolderProps<TItem>) => {
   );
 
   const separator = useMemo(() => {
-    return ItemSeparatorComponent ? (
+    return ItemSeparatorComponent && trailingItem !== undefined ? (
       <ItemSeparatorComponent leadingItem={item} trailingItem={trailingItem} />
     ) : null;
   }, [ItemSeparatorComponent, item, trailingItem]);
@@ -97,7 +97,10 @@ const ViewHolderInternal = <TItem,>(props: ViewHolderProps<TItem>) => {
 
   const children = useMemo(() => {
     return renderItem?.({ item, index, extraData, target }) ?? null;
-  }, [item, index, extraData, target, renderItem]);
+    // TODO: Test more thoroughly
+    // We don't really  to re-render the children when the index changes
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [item, extraData, target, renderItem]);
 
   const style = {
     flexDirection: horizontal ? "row" : "column",
@@ -110,7 +113,6 @@ const ViewHolderInternal = <TItem,>(props: ViewHolderProps<TItem>) => {
     maxWidth: layout.maxWidth,
     left: layout.x,
     top: layout.y,
-    zIndex: 0,
   } as const;
 
   // TODO: Fix this type issue

package/src/recyclerview/ViewHolderCollection.tsx

@@ -21,7 +21,7 @@ export interface ViewHolderCollectionProps<TItem> {
   /** The data array to be rendered */
   data: FlashListProps<TItem>["data"];
   /** Map of indices to React keys for each rendered item */
-  renderStack: Map<number, string>;
+  renderStack: Map<string, { index: number }>;
   /** Function to get layout information for a specific index */
   getLayout: (index: number) => RVLayout;
   /** Ref to control layout updates from parent components */
@@ -99,27 +99,37 @@ export const ViewHolderCollection = <TItem,>(
       // );
       recyclerViewContext?.layout();
     }
+    // we need to run this callback on when fixedContainerSize changes
+    // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [fixedContainerSize]);
 
   useLayoutEffect(() => {
     if (renderId > 0) {
       onCommitLayoutEffect?.();
     }
+    // we need to run this callback on when renderId changes
+    // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [renderId]);
 
   useEffect(() => {
     if (renderId > 0) {
       onCommitEffect?.();
     }
+    // we need to run this callback on when renderId changes
+    // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [renderId]);
 
   // Expose forceUpdate through ref
-  useImperativeHandle(viewHolderCollectionRef, () => ({
-    commitLayout: () => {
-      // This will trigger a re-render of the component
-      setRenderId((prev) => prev + 1);
-    },
-  }));
+  useImperativeHandle(
+    viewHolderCollectionRef,
+    () => ({
+      commitLayout: () => {
+        // This will trigger a re-render of the component
+        setRenderId((prev) => prev + 1);
+      },
+    }),
+    [setRenderId]
+  );
 
   const hasData = data && data.length > 0;
 
@@ -128,6 +138,17 @@ export const ViewHolderCollection = <TItem,>(
     height: containerLayout?.height,
   };
 
+  // sort by index and log
+  // const sortedRenderStack = Array.from(renderStack.entries()).sort(
+  //   ([, a], [, b]) => a.index - b.index
+  // );
+  // console.log(
+  //   "sortedRenderStack",
+  //   sortedRenderStack.map(([reactKey, { index }]) => {
+  //     return `${index} => ${reactKey}`;
+  //   })
+  // );
+
   return (
     <CompatView
       // TODO: Take care of web scroll bar here
@@ -135,7 +156,7 @@ export const ViewHolderCollection = <TItem,>(
     >
       {containerLayout &&
         hasData &&
-        Array.from(renderStack, ([index, reactKey]) => {
+        Array.from(renderStack.entries(), ([reactKey, { index }]) => {
           const item = data[index];
           const trailingItem = ItemSeparatorComponent
             ? data[index + 1]

package/src/recyclerview/components/ScrollAnchor.tsx

@@ -35,11 +35,15 @@ export function ScrollAnchor({ scrollAnchorRef }: ScrollAnchorProps) {
   const [scrollOffset, setScrollOffset] = useState(1000000); // TODO: Fix this value
 
   // Expose scrollBy method through ref
-  useImperativeHandle(scrollAnchorRef, () => ({
-    scrollBy: (offset: number) => {
-      setScrollOffset((prev) => prev + offset);
-    },
-  }));
+  useImperativeHandle(
+    scrollAnchorRef,
+    () => ({
+      scrollBy: (offset: number) => {
+        setScrollOffset((prev) => prev + offset);
+      },
+    }),
+    []
+  );
 
   // Create an invisible anchor element that can be positioned
   const anchor = useMemo(() => {

package/src/recyclerview/components/StickyHeaders.tsx

@@ -58,25 +58,45 @@ export const StickyHeaders = <TItem,>({
   data,
   extraData,
 }: StickyHeaderProps<TItem>) => {
-  const [stickyIndices, setStickyIndices] = useState<{
+  const [stickyHeaderState, setStickyHeaderState] = useState<{
     currentStickyIndex: number;
     nextStickyIndex: number;
-  }>({ currentStickyIndex: -1, nextStickyIndex: -1 });
-
-  const { currentStickyIndex, nextStickyIndex } = stickyIndices;
+    currentStickyHeight: number;
+    nextStickyY: number;
+  }>({
+    currentStickyIndex: -1,
+    nextStickyIndex: -1,
+    currentStickyHeight: 0,
+    nextStickyY: 0,
+  });
+
+  const {
+    currentStickyIndex,
+    nextStickyIndex,
+    nextStickyY,
+    currentStickyHeight,
+  } = stickyHeaderState;
 
   // Memoize sorted indices based on their Y positions
   const sortedIndices = useMemo(() => {
     return stickyHeaderIndices.sort((first, second) => first - second);
   }, [stickyHeaderIndices]);
 
+  const legthInvalid =
+    sortedIndices.length === 0 ||
+    recyclerViewManager.getDataLength() <=
+      sortedIndices[sortedIndices.length - 1];
+
   const compute = useCallback(() => {
-    const adjustedValue = recyclerViewManager.getLastScrollOffset();
+    if (legthInvalid) {
+      return;
+    }
+    const adjustedScrollOffset = recyclerViewManager.getLastScrollOffset();
 
     // Binary search for current sticky index
     const currentIndexInArray = findCurrentStickyIndex(
       sortedIndices,
-      adjustedValue,
+      adjustedScrollOffset,
       (index) => recyclerViewManager.getLayout(index).y
     );
 
@@ -87,16 +107,34 @@ export const StickyHeaders = <TItem,>({
       newNextStickyIndex = -1;
     }
 
+    const newNextStickyY =
+      (recyclerViewManager.tryGetLayout(newNextStickyIndex)?.y ?? 0) +
+      recyclerViewManager.firstItemOffset;
+    const newCurrentStickyHeight =
+      recyclerViewManager.tryGetLayout(newStickyIndex)?.height ?? 0;
+
     if (
       newStickyIndex !== currentStickyIndex ||
-      newNextStickyIndex !== nextStickyIndex
+      newNextStickyIndex !== nextStickyIndex ||
+      newNextStickyY !== nextStickyY ||
+      newCurrentStickyHeight !== currentStickyHeight
     ) {
-      setStickyIndices({
+      setStickyHeaderState({
         currentStickyIndex: newStickyIndex,
         nextStickyIndex: newNextStickyIndex,
+        nextStickyY: newNextStickyY,
+        currentStickyHeight: newCurrentStickyHeight,
       });
     }
-  }, [currentStickyIndex, nextStickyIndex, recyclerViewManager, sortedIndices]);
+  }, [
+    currentStickyIndex,
+    nextStickyIndex,
+    recyclerViewManager,
+    sortedIndices,
+    legthInvalid,
+    nextStickyY,
+    currentStickyHeight,
+  ]);
 
   useEffect(() => {
     compute();
@@ -125,20 +163,20 @@ export const StickyHeaders = <TItem,>({
       });
     }
 
-    const currentLayout = recyclerViewManager.getLayout(currentStickyIndex);
-    const nextLayout = recyclerViewManager.getLayout(nextStickyIndex);
-
-    const pushStartsAt = nextLayout.y - currentLayout.height;
+    const pushStartsAt = nextStickyY - currentStickyHeight;
 
     return scrollY.interpolate({
-      inputRange: [
-        pushStartsAt + recyclerViewManager.firstItemOffset,
-        nextLayout.y + recyclerViewManager.firstItemOffset,
-      ],
-      outputRange: [0, -currentLayout.height],
+      inputRange: [pushStartsAt, nextStickyY],
+      outputRange: [0, -currentStickyHeight],
       extrapolate: "clamp",
     });
-  }, [currentStickyIndex, nextStickyIndex, recyclerViewManager, scrollY]);
+  }, [
+    currentStickyHeight,
+    currentStickyIndex,
+    nextStickyIndex,
+    nextStickyY,
+    scrollY,
+  ]);
 
   // Memoize header content
   const headerContent = useMemo(() => {

package/src/recyclerview/hooks/useBoundDetection.ts

@@ -1,9 +1,10 @@
 import { useCallback, useEffect, useMemo, useRef } from "react";
 
 import { RecyclerViewManager } from "../RecyclerViewManager";
-import { RecyclerViewProps } from "../RecyclerViewProps";
 import { CompatScroller } from "../components/CompatScroller";
 
+import { useUnmountAwareAnimationFrame } from "./useUnmountAwareCallbacks";
+
 /**
  * Hook to detect when the scroll position reaches near the start or end of the list
  * and trigger the appropriate callbacks. This hook is responsible for:
@@ -17,7 +18,6 @@ import { CompatScroller } from "../components/CompatScroller";
  */
 export function useBoundDetection<T>(
   recyclerViewManager: RecyclerViewManager<T>,
-  props: RecyclerViewProps<T>,
   scrollViewRef: React.RefObject<CompatScroller>
 ) {
   // Track whether we've already triggered the end reached callback to prevent duplicate calls
@@ -26,22 +26,27 @@ export function useBoundDetection<T>(
   const pendingStartReached = useRef(false);
   // Track whether we should auto-scroll to bottom when new content is added
   const pendingAutoscrollToBottom = useRef(false);
-  const { horizontal, data, maintainVisibleContentPosition } = props;
+  const { data } = recyclerViewManager.props;
+  const { requestAnimationFrame } = useUnmountAwareAnimationFrame();
 
   /**
    * Checks if the scroll position is near the start or end of the list
    * and triggers appropriate callbacks if configured.
    */
   const checkBounds = useCallback(() => {
+    const {
+      onEndReached,
+      onStartReached,
+      maintainVisibleContentPosition,
+      horizontal,
+      onEndReachedThreshold: onEndReachedThresholdProp,
+      onStartReachedThreshold: onStartReachedThresholdProp,
+    } = recyclerViewManager.props;
     // Skip all calculations if neither callback is provided and autoscroll is disabled
     const autoscrollToBottomThreshold =
       maintainVisibleContentPosition?.autoscrollToBottomThreshold ?? -1;
 
-    if (
-      !props.onEndReached &&
-      !props.onStartReached &&
-      autoscrollToBottomThreshold < 0
-    ) {
+    if (!onEndReached && !onStartReached && autoscrollToBottomThreshold < 0) {
       return;
     }
 
@@ -50,7 +55,7 @@ export function useBoundDetection<T>(
         recyclerViewManager.getAbsoluteLastScrollOffset();
       const contentSize = recyclerViewManager.getChildContainerDimensions();
       const windowSize = recyclerViewManager.getWindowSize();
-      const isHorizontal = props.horizontal === true;
+      const isHorizontal = horizontal === true;
 
       // Calculate dimensions based on scroll direction
       const visibleLength = isHorizontal ? windowSize.width : windowSize.height;
@@ -59,8 +64,8 @@ export function useBoundDetection<T>(
         recyclerViewManager.firstItemOffset;
 
       // Check if we're near the end of the list
-      if (props.onEndReached) {
-        const onEndReachedThreshold = props.onEndReachedThreshold ?? 0.5;
+      if (onEndReached) {
+        const onEndReachedThreshold = onEndReachedThresholdProp ?? 0.5;
         const endThresholdDistance = onEndReachedThreshold * visibleLength;
 
         const isNearEnd =
@@ -69,27 +74,27 @@ export function useBoundDetection<T>(
 
         if (isNearEnd && !pendingEndReached.current) {
           pendingEndReached.current = true;
-          props.onEndReached();
+          onEndReached();
         }
         pendingEndReached.current = isNearEnd;
       }
 
       // Check if we're near the start of the list
-      if (props.onStartReached) {
-        const onStartReachedThreshold = props.onStartReachedThreshold ?? 0.2;
+      if (onStartReached) {
+        const onStartReachedThreshold = onStartReachedThresholdProp ?? 0.2;
         const startThresholdDistance = onStartReachedThreshold * visibleLength;
 
         const isNearStart = lastScrollOffset <= startThresholdDistance;
 
         if (isNearStart && !pendingStartReached.current) {
           pendingStartReached.current = true;
-          props.onStartReached();
+          onStartReached();
         }
         pendingStartReached.current = isNearStart;
       }
 
       // Handle auto-scrolling to bottom for vertical lists
-      if (!horizontal) {
+      if (!isHorizontal) {
         const autoscrollToBottomThresholdDistance =
           autoscrollToBottomThreshold * visibleLength;
 
@@ -104,11 +109,13 @@ export function useBoundDetection<T>(
         }
       }
     }
-  }, [recyclerViewManager, props]);
+  }, [recyclerViewManager]);
 
   // Reset end reached state when data changes
   useMemo(() => {
     pendingEndReached.current = false;
+    // needs to run only when data changes
+    // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [data]);
 
   // Auto-scroll to bottom when new content is added and we're near the bottom
@@ -119,7 +126,7 @@ export function useBoundDetection<T>(
         pendingAutoscrollToBottom.current = false;
       });
     }
-  }, [data]);
+  }, [data, requestAnimationFrame, scrollViewRef]);
 
   return {
     checkBounds,

package/src/recyclerview/hooks/useOnLoad.ts

@@ -2,7 +2,7 @@ import { useEffect, useMemo, useRef, useState } from "react";
 
 import { RecyclerViewManager } from "../RecyclerViewManager";
 
-import { useUnmountFlag } from "./useUnmountFlag";
+import { useUnmountAwareAnimationFrame } from "./useUnmountAwareCallbacks";
 // import { ToastAndroid } from "react-native";
 
 /**
@@ -22,7 +22,7 @@ export const useOnListLoad = <T>(
   const [isLoaded, setIsLoaded] = useState<boolean>(false);
   const dataLength = recyclerViewManager.getDataLength();
   // const dataCollector = useRef<number[]>([]);
-  const isUnmounted = useUnmountFlag();
+  const { requestAnimationFrame } = useUnmountAwareAnimationFrame();
   // Track render cycles by collecting elapsed time on each render
   // useEffect(() => {
   //   const elapsedTimeInMs = Date.now() - loadStartTimeRef.current;
@@ -48,10 +48,8 @@ export const useOnListLoad = <T>(
     // console.log("----------> dataCollector", dataCollectorString);
     // console.log("----------> FlashList v2 load in", `${elapsedTimeInMs} ms`);
     requestAnimationFrame(() => {
-      if (!isUnmounted.current) {
-        onLoad?.({ elapsedTimeInMs });
-        setIsLoaded(true);
-      }
+      onLoad?.({ elapsedTimeInMs });
+      setIsLoaded(true);
     });
   });