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

package/src/recyclerview/RenderStackManager.ts

@@ -0,0 +1,317 @@
+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;
+
+  private unProcessedIndices: Set<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;
+    this.unProcessedIndices = new Set();
+  }
+
+  /**
+   * 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
+  ) {
+    this.clearRecyclePool();
+    this.unProcessedIndices.clear();
+
+    // 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;
+      }
+      if (!this.disableRecycling) {
+        this.unProcessedIndices.add(index);
+      }
+      if (!engagedIndices.includes(index)) {
+        this.recycleKey(key);
+        return;
+      }
+      const newStableId = getStableId(index);
+      const newItemType = getItemType(index);
+      if (stableId !== newStableId || itemType !== newItemType) {
+        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));
+      }
+    }
+
+    // create indices that are not in the engagedIndices and less than dataLength
+    // select only indices that are not in the engagedIndices
+    const validIndicesInPool: number[] = [];
+    for (const keyInfo of this.keyMap.values()) {
+      const index = keyInfo.index;
+      if (index < dataLength && !engagedIndices.includes(index)) {
+        validIndicesInPool.push(index);
+      }
+    }
+
+    // First pass: process items that already have optimized keys
+    for (const index of validIndicesInPool) {
+      if (this.hasOptimizedKey(getStableId(index))) {
+        this.syncItem(index, getItemType(index), getStableId(index));
+      }
+    }
+
+    for (const index of validIndicesInPool) {
+      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, getItemType, 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,
+    getItemType: (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;
+      const indexOutOfBounds = index >= dataLength;
+      const hasStableIdChanged =
+        !indexOutOfBounds && getStableId(index) !== stableId;
+
+      if (indexOutOfBounds || hasStableIdChanged) {
+        const nextIndex = this.unProcessedIndices.values().next().value;
+        let shouldDeleteKey = true;
+
+        if (nextIndex !== undefined) {
+          const nextItemType = getItemType(nextIndex);
+          const nextStableId = getStableId(nextIndex);
+          if (itemType === nextItemType) {
+            this.syncItem(nextIndex, nextItemType, nextStableId);
+            shouldDeleteKey = false;
+          }
+        }
+        if (shouldDeleteKey) {
+          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();
+
+    this.unProcessedIndices.delete(index);
+
+    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() {
+    // iterate over all pools and clear them
+    for (const pool of this.recycleKeyPools.values()) {
+      pool.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 */
@@ -37,15 +37,19 @@ export interface ViewHolderCollectionProps<TItem> {
   /** Function to get the container's layout dimensions */
   getChildContainerLayout: () => RVDimension | undefined;
   /** Callback after layout effects are committed */
-  onCommitLayoutEffect?: () => void;
+  onCommitLayoutEffect: () => void;
   /** Callback after effects are committed */
-  onCommitEffect?: () => void;
+  onCommitEffect: () => void;
   /** Optional custom component to wrap each item */
   CellRendererComponent?: FlashListProps<TItem>["CellRendererComponent"];
   /** Optional component to render between items */
   ItemSeparatorComponent?: FlashListProps<TItem>["ItemSeparatorComponent"];
   /** Whether the list is horizontal or vertical */
   horizontal: FlashListProps<TItem>["horizontal"];
+  /** Function to get the adjustment margin for the container.
+   * For startRenderingFromBottom, we need to adjust the height of the container
+   */
+  getAdjustmentMargin: () => number;
 }
 
 /**
@@ -79,6 +83,7 @@ export const ViewHolderCollection = <TItem,>(
     ItemSeparatorComponent,
     onCommitEffect,
     horizontal,
+    getAdjustmentMargin,
   } = props;
 
   const [renderId, setRenderId] = React.useState(0);
@@ -99,43 +104,66 @@ 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;
 
   const containerStyle = {
     width: horizontal ? containerLayout?.width : undefined,
     height: containerLayout?.height,
+    marginTop: horizontal ? undefined : getAdjustmentMargin(),
+    marginLeft: horizontal ? getAdjustmentMargin() : undefined,
+    // TODO: Temp workaround, useLayoutEffect doesn't block paint in some cases
+    // We need to investigate why this is happening
+    opacity: renderId > 0 ? 1 : 0,
   };
 
+  // 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
-      style={hasData && containerStyle}
-    >
+    <CompatView style={hasData && containerStyle}>
       {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

@@ -15,6 +15,7 @@ import { CompatView } from "./CompatView";
 export interface ScrollAnchorProps {
   /** Ref to access scroll anchor methods */
   scrollAnchorRef: React.Ref<ScrollAnchorRef>;
+  horizontal: boolean;
 }
 
 /**
@@ -27,28 +28,39 @@ export interface ScrollAnchorRef {
 
 /**
  * ScrollAnchor component that provides programmatic scrolling capabilities using maintainVisibleContentPosition property
- * TODO: Implement this for web
  * @param props - Component props
  * @returns An invisible anchor element used for scrolling
  */
-export function ScrollAnchor({ scrollAnchorRef }: ScrollAnchorProps) {
+export function ScrollAnchor({
+  scrollAnchorRef,
+  horizontal,
+}: 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(() => {
     return (
       <CompatView
-        style={{ position: "absolute", height: 0, top: scrollOffset }}
+        style={{
+          position: "absolute",
+          height: 0,
+          top: horizontal ? 0 : scrollOffset,
+          left: horizontal ? scrollOffset : 0,
+        }}
       />
     );
-  }, [scrollOffset]);
+  }, [scrollOffset, horizontal]);
 
   return anchor;
 }

package/src/recyclerview/components/StickyHeaders.tsx

@@ -49,6 +49,11 @@ export interface StickyHeaderRef {
   reportScrollEvent: (event: NativeScrollEvent) => void;
 }
 
+interface StickyHeaderState {
+  currentStickyIndex: number;
+  pushStartsAt: number;
+}
+
 export const StickyHeaders = <TItem,>({
   stickyHeaderIndices,
   renderItem,
@@ -58,25 +63,35 @@ export const StickyHeaders = <TItem,>({
   data,
   extraData,
 }: StickyHeaderProps<TItem>) => {
-  const [stickyIndices, setStickyIndices] = useState<{
-    currentStickyIndex: number;
-    nextStickyIndex: number;
-  }>({ currentStickyIndex: -1, nextStickyIndex: -1 });
+  const [stickyHeaderState, setStickyHeaderState] = useState<StickyHeaderState>(
+    {
+      currentStickyIndex: -1,
+      pushStartsAt: Number.MAX_SAFE_INTEGER,
+    }
+  );
 
-  const { currentStickyIndex, nextStickyIndex } = stickyIndices;
+  const { currentStickyIndex, pushStartsAt } = stickyHeaderState;
 
-  // Memoize sorted indices based on their Y positions
+  // sort indices and memoize compute
   const sortedIndices = useMemo(() => {
-    return stickyHeaderIndices.sort((first, second) => first - second);
+    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 +102,33 @@ export const StickyHeaders = <TItem,>({
       newNextStickyIndex = -1;
     }
 
+    // To make sure header offset is 0 in the interpolate compute
+    const newNextStickyY =
+      newNextStickyIndex === -1
+        ? Number.MAX_SAFE_INTEGER
+        : (recyclerViewManager.tryGetLayout(newNextStickyIndex)?.y ?? 0) +
+          recyclerViewManager.firstItemOffset;
+    const newCurrentStickyHeight =
+      recyclerViewManager.tryGetLayout(newStickyIndex)?.height ?? 0;
+
+    const newPushStartsAt = newNextStickyY - newCurrentStickyHeight;
+
     if (
       newStickyIndex !== currentStickyIndex ||
-      newNextStickyIndex !== nextStickyIndex
+      newPushStartsAt !== pushStartsAt
     ) {
-      setStickyIndices({
+      setStickyHeaderState({
         currentStickyIndex: newStickyIndex,
-        nextStickyIndex: newNextStickyIndex,
+        pushStartsAt: newPushStartsAt,
       });
     }
-  }, [currentStickyIndex, nextStickyIndex, recyclerViewManager, sortedIndices]);
+  }, [
+    legthInvalid,
+    recyclerViewManager,
+    sortedIndices,
+    currentStickyIndex,
+    pushStartsAt,
+  ]);
 
   useEffect(() => {
     compute();
@@ -115,35 +147,19 @@ export const StickyHeaders = <TItem,>({
 
   const refHolder = useRef(new Map()).current;
 
-  // Memoize translateY calculation
   const translateY = useMemo(() => {
-    if (currentStickyIndex === -1 || nextStickyIndex === -1) {
-      return scrollY.interpolate({
-        inputRange: [0, Infinity],
-        outputRange: [0, 0],
-        extrapolate: "clamp",
-      });
-    }
-
-    const currentLayout = recyclerViewManager.getLayout(currentStickyIndex);
-    const nextLayout = recyclerViewManager.getLayout(nextStickyIndex);
-
-    const pushStartsAt = nextLayout.y - currentLayout.height;
+    const currentStickyHeight =
+      recyclerViewManager.tryGetLayout(currentStickyIndex)?.height ?? 0;
 
     return scrollY.interpolate({
-      inputRange: [
-        pushStartsAt + recyclerViewManager.firstItemOffset,
-        nextLayout.y + recyclerViewManager.firstItemOffset,
-      ],
-      outputRange: [0, -currentLayout.height],
+      inputRange: [pushStartsAt, pushStartsAt + currentStickyHeight],
+      outputRange: [0, -currentStickyHeight],
       extrapolate: "clamp",
     });
-  }, [currentStickyIndex, nextStickyIndex, recyclerViewManager, scrollY]);
+  }, [recyclerViewManager, currentStickyIndex, scrollY, pushStartsAt]);
 
   // Memoize header content
   const headerContent = useMemo(() => {
-    if (currentStickyIndex === -1) return null;
-
     return (
       <CompatAnimatedView
         style={{
@@ -155,19 +171,21 @@ export const StickyHeaders = <TItem,>({
           transform: [{ translateY }],
         }}
       >
-        <ViewHolder
-          index={currentStickyIndex}
-          item={data[currentStickyIndex]}
-          renderItem={renderItem}
-          layout={{ x: 0, y: 0, width: 0, height: 0 }}
-          refHolder={refHolder}
-          extraData={extraData}
-          trailingItem={null}
-          target="StickyHeader"
-        />
+        {currentStickyIndex !== -1 && currentStickyIndex < data.length ? (
+          <ViewHolder
+            index={currentStickyIndex}
+            item={data[currentStickyIndex]}
+            renderItem={renderItem}
+            layout={{ x: 0, y: 0, width: 0, height: 0 }}
+            refHolder={refHolder}
+            extraData={extraData}
+            trailingItem={null}
+            target="StickyHeader"
+          />
+        ) : null}
       </CompatAnimatedView>
     );
-  }, [currentStickyIndex, data, renderItem, extraData, refHolder, translateY]);
+  }, [translateY, currentStickyIndex, data, renderItem, refHolder, extraData]);
 
   return headerContent;
 };