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

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,
@@ -55,7 +57,7 @@ import { RenderTimeTracker } from "./helpers/RenderTimeTracker";
  */
 const RecyclerViewComponent = <T,>(
   props: RecyclerViewProps<T>,
-  ref: React.Ref<any>
+  ref: React.Ref<FlashListRef<T>>
 ) => {
   // Destructure props and initialize refs
   const {
@@ -76,8 +78,6 @@ const RecyclerViewComponent = <T,>(
     ListFooterComponentStyle,
     ItemSeparatorComponent,
     renderScrollComponent,
-    onScroll,
-    disableRecycling,
     style,
     stickyHeaderIndices,
     maintainVisibleContentPosition,
@@ -116,13 +116,12 @@ const RecyclerViewComponent = <T,>(
   // Initialize core RecyclerView manager and content offset management
   const { recyclerViewManager, velocityTracker } =
     useRecyclerViewManager(props);
-  const { applyContentOffset, applyInitialScrollIndex } =
+  const { applyContentOffset, applyInitialScrollIndex, handlerMethods } =
     useRecyclerViewController(
       recyclerViewManager,
       ref,
       scrollViewRef,
-      scrollAnchorRef,
-      props
+      scrollAnchorRef
     );
 
   // Initialize view holder collection ref
@@ -132,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;
 
@@ -182,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;
@@ -189,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
@@ -272,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);
@@ -299,7 +304,7 @@ const RecyclerViewComponent = <T,>(
         }
       },
     };
-  }, [setLayoutTreeId]);
+  }, [handlerMethods, pendingChildIds, recyclerViewManager, setLayoutTreeId]);
 
   const parentRecyclerViewContext = useRecyclerViewContext();
   const recyclerViewId = useId();
@@ -334,7 +339,7 @@ const RecyclerViewComponent = <T,>(
         recyclerViewContext.layout();
       }
     },
-    [recyclerViewManager]
+    [recyclerViewContext, recyclerViewManager]
   );
 
   // Get secondary props and components
@@ -374,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(() => {
@@ -385,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()
@@ -472,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}
@@ -503,7 +520,7 @@ const RecyclerViewComponent = <T,>(
               applyInitialScrollIndex();
               checkBounds();
               recyclerViewManager.computeItemViewability();
-              recyclerViewManager.disableRecycling = Boolean(disableRecycling);
+              recyclerViewManager.disableRecycling(false);
             }}
             CellRendererComponent={CellRendererComponent}
             ItemSeparatorComponent={ItemSeparatorComponent}
@@ -522,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;
 }

package/src/recyclerview/RecyclerViewManager.ts

@@ -9,30 +9,27 @@ import {
 } from "./layout-managers/LayoutManager";
 import { RVLinearLayoutManagerImpl } from "./layout-managers/LinearLayoutManager";
 import { RVMasonryLayoutManagerImpl } from "./layout-managers/MasonryLayoutManager";
-import { RecycleKeyManagerImpl, RecycleKeyManager } from "./RecycleKeyManager";
 import { RecyclerViewProps } from "./RecyclerViewProps";
 import {
   RVEngagedIndicesTracker,
   RVEngagedIndicesTrackerImpl,
   Velocity,
 } from "./helpers/EngagedIndicesTracker";
-
-// Abstracts layout manager, key manager and viewability manager and generates render stack (progressively on load)
+import { RenderStackManager } from "./RenderStackManager";
+// Abstracts layout manager, render stack manager and viewability manager and generates render stack (progressively on load)
 export class RecyclerViewManager<T> {
   private initialDrawBatchSize = 1;
   private engagedIndicesTracker: RVEngagedIndicesTracker;
-  private recycleKeyManager: RecycleKeyManager;
+  private renderStackManager: RenderStackManager;
   private layoutManager?: RVLayoutManager;
   // Map of index to key
-  private renderStack: Map<number, string> = new Map();
   private isFirstLayoutComplete = false;
   private hasRenderedProgressively = false;
-  private props: RecyclerViewProps<T>;
+  private propsRef: RecyclerViewProps<T>;
   private itemViewabilityManager: ViewabilityManager<T>;
-  private allocatedKeyTracker: Set<string> = new Set();
   private _isDisposed = false;
+  private _isLayoutManagerDirty = false;
 
-  public disableRecycling = false;
   public firstItemOffset = 0;
   public ignoreScrollEvents = false;
 
@@ -45,74 +42,46 @@ export class RecyclerViewManager<T> {
   }
 
   constructor(props: RecyclerViewProps<T>) {
-    this.props = props;
+    this.getStableId = this.getStableId.bind(this);
+    this.getItemType = this.getItemType.bind(this);
+    this.propsRef = props;
     this.engagedIndicesTracker = new RVEngagedIndicesTrackerImpl();
-    this.recycleKeyManager = new RecycleKeyManagerImpl();
+    this.renderStackManager = new RenderStackManager(
+      props.maxItemsInRecyclePool
+    );
     this.itemViewabilityManager = new ViewabilityManager<T>(this as any);
   }
 
   // updates render stack based on the engaged indices which are sorted. Recycles unused keys.
-  // TODO: Write comprehensive tests for this function
   private updateRenderStack = (engagedIndices: ConsecutiveNumbers): void => {
-    // console.log("updateRenderStack", engagedIndices);
-
-    this.allocatedKeyTracker.clear();
-    const newRenderStack = new Map<number, string>();
-    for (const [index, key] of this.renderStack) {
-      if (!engagedIndices.includes(index)) {
-        this.recycleKeyManager.recycleKey(key);
-      }
-    }
-    if (this.disableRecycling) {
-      this.recycleKeyManager.clearPool();
-    }
-    for (const index of engagedIndices) {
-      const currentKey = this.renderStack.get(index);
-
-      if (
-        currentKey &&
-        !this.disableRecycling &&
-        !this.allocatedKeyTracker.has(currentKey)
-      ) {
-        this.recycleKeyManager.recycleKey(currentKey);
-      }
-
-      const newKey = this.recycleKeyManager.getKey(
-        this.getItemType(index),
-        this.getStableId(index),
-        currentKey
-      );
-      this.allocatedKeyTracker.add(newKey);
-      newRenderStack.set(index, newKey);
-    }
-    //  DANGER
-    for (const [index, key] of this.renderStack) {
-      if (
-        this.recycleKeyManager.hasKeyInPool(key) &&
-        !newRenderStack.has(index) &&
-        index < (this.props.data?.length ?? 0)
-      ) {
-        this.allocatedKeyTracker.add(key);
-        newRenderStack.set(index, key);
-      }
-    }
-
-    this.renderStack = newRenderStack;
+    this.renderStackManager.sync(
+      this.getStableId,
+      this.getItemType,
+      engagedIndices,
+      this.getDataLength()
+    );
   };
 
+  get props() {
+    return this.propsRef;
+  }
+
   setOffsetProjectionEnabled(value: boolean) {
     this.engagedIndicesTracker.enableOffsetProjection = value;
   }
 
   updateProps(props: RecyclerViewProps<T>) {
-    this.props = props;
+    this.propsRef = props;
     this.engagedIndicesTracker.drawDistance =
       props.drawDistance ?? this.engagedIndicesTracker.drawDistance;
-    if (this.props.drawDistance === 0) {
+    if (this.propsRef.drawDistance === 0) {
       this.initialDrawBatchSize = 1;
     } else {
       this.initialDrawBatchSize = (props.numColumns ?? 1) * 2;
     }
+    this.initialDrawBatchSize =
+      this.propsRef.overrideProps?.initialDrawBatchSize ??
+      this.initialDrawBatchSize;
   }
 
   /**
@@ -124,7 +93,7 @@ export class RecyclerViewManager<T> {
     offset: number,
     velocity?: Velocity
   ): ConsecutiveNumbers | undefined {
-    if (this.layoutManager && !this.isDisposed) {
+    if (this.layoutManager && !this._isDisposed) {
       const engagedIndices = this.engagedIndicesTracker.updateScrollOffset(
         offset - this.firstItemOffset,
         velocity,
@@ -147,6 +116,10 @@ export class RecyclerViewManager<T> {
     return this.isFirstLayoutComplete;
   }
 
+  disableRecycling(disable: boolean) {
+    this.renderStackManager.disableRecycling = disable;
+  }
+
   getLayout(index: number) {
     if (!this.layoutManager) {
       throw new Error(
@@ -156,6 +129,17 @@ export class RecyclerViewManager<T> {
     return this.layoutManager.getLayout(index);
   }
 
+  tryGetLayout(index: number) {
+    if (
+      this.layoutManager &&
+      index >= 0 &&
+      index < this.layoutManager.getLayoutCount()
+    ) {
+      return this.layoutManager.getLayout(index);
+    }
+    return undefined;
+  }
+
   // Doesn't include header / foot etc
   getChildContainerDimensions() {
     if (!this.layoutManager) {
@@ -167,7 +151,7 @@ export class RecyclerViewManager<T> {
   }
 
   getRenderStack() {
-    return this.renderStack;
+    return this.renderStackManager.getRenderStack();
   }
 
   getWindowSize() {
@@ -187,10 +171,10 @@ export class RecyclerViewManager<T> {
   getMaxScrollOffset() {
     return Math.max(
       0,
-      (this.props.horizontal
+      (this.propsRef.horizontal
         ? this.getChildContainerDimensions().width
         : this.getChildContainerDimensions().height) -
-        (this.props.horizontal
+        (this.propsRef.horizontal
           ? this.getWindowSize().width
           : this.getWindowSize().height) +
         this.firstItemOffset
@@ -216,28 +200,33 @@ export class RecyclerViewManager<T> {
     if (
       this.layoutManager &&
       Boolean(this.layoutManager?.isHorizontal()) !==
-        Boolean(this.props.horizontal)
+        Boolean(this.propsRef.horizontal)
     ) {
       throw new Error(
         "Horizontal prop cannot be toggled, you can use a key on FlashList to recreate it."
       );
     }
+    if (this._isLayoutManagerDirty) {
+      this.layoutManager = undefined;
+      this._isLayoutManagerDirty = false;
+    }
     if (!(this.layoutManager instanceof LayoutManagerClass)) {
       // console.log("-----> new LayoutManagerClass");
 
       this.layoutManager = new LayoutManagerClass(
         {
           windowSize,
-          maxColumns: this.props.numColumns ?? 1,
-          horizontal: Boolean(this.props.horizontal),
-          optimizeItemArrangement: this.props.optimizeItemArrangement ?? true,
+          maxColumns: this.propsRef.numColumns ?? 1,
+          horizontal: Boolean(this.propsRef.horizontal),
+          optimizeItemArrangement:
+            this.propsRef.optimizeItemArrangement ?? true,
           overrideItemLayout: (index, layout) => {
-            this.props?.overrideItemLayout?.(
+            this.propsRef?.overrideItemLayout?.(
               layout,
-              this.props.data![index],
+              this.propsRef.data![index],
               index,
-              this.props.numColumns ?? 1,
-              this.props.extraData
+              this.propsRef.numColumns ?? 1,
+              this.propsRef.extraData
             );
           },
         },
@@ -246,9 +235,9 @@ export class RecyclerViewManager<T> {
     } else {
       this.layoutManager.updateLayoutParams({
         windowSize,
-        maxColumns: this.props.numColumns ?? 1,
-        horizontal: Boolean(this.props.horizontal),
-        optimizeItemArrangement: this.props.optimizeItemArrangement ?? true,
+        maxColumns: this.propsRef.numColumns ?? 1,
+        horizontal: Boolean(this.propsRef.horizontal),
+        optimizeItemArrangement: this.propsRef.optimizeItemArrangement ?? true,
       });
     }
   }
@@ -257,7 +246,7 @@ export class RecyclerViewManager<T> {
     return this.layoutManager !== undefined;
   }
 
-  getVisibleIndices() {
+  computeVisibleIndices() {
     if (!this.layoutManager) {
       throw new Error(
         "LayoutManager is not initialized, visible indices are not unavailable"
@@ -295,9 +284,9 @@ export class RecyclerViewManager<T> {
     // Using higher buffer for masonry to avoid missing items
     this.itemViewabilityManager.shouldListenToVisibleIndices &&
       this.itemViewabilityManager.updateViewableItems(
-        this.props.masonry
+        this.propsRef.masonry
           ? this.engagedIndicesTracker.getEngagedIndices().toArray()
-          : this.getVisibleIndices().toArray()
+          : this.computeVisibleIndices().toArray()
       );
   }
 
@@ -311,7 +300,7 @@ export class RecyclerViewManager<T> {
 
   processDataUpdate() {
     if (this.hasLayout()) {
-      this.modifyChildrenLayout([], this.props.data?.length ?? 0);
+      this.modifyChildrenLayout([], this.propsRef.data?.length ?? 0);
       if (!this.recomputeEngagedIndices()) {
         // recomputeEngagedIndices will update the render stack if there are any changes in the engaged indices.
         // It's important to update render stack so that elements are assgined right keys incase items were deleted.
@@ -329,30 +318,42 @@ export class RecyclerViewManager<T> {
     this.itemViewabilityManager.dispose();
   }
 
+  markLayoutManagerDirty() {
+    this._isLayoutManagerDirty = true;
+  }
+
   getInitialScrollIndex() {
     return (
-      this.props.initialScrollIndex ??
-      (this.props.maintainVisibleContentPosition?.startRenderingFromBottom
+      this.propsRef.initialScrollIndex ??
+      (this.propsRef.maintainVisibleContentPosition?.startRenderingFromBottom
         ? this.getDataLength() - 1
         : undefined)
     );
   }
 
+  shouldMaintainVisibleContentPosition() {
+    // Return true if maintainVisibleContentPosition is enabled and not horizontal
+    return (
+      !this.propsRef.maintainVisibleContentPosition?.disabled &&
+      !this.propsRef.horizontal
+    );
+  }
+
   getDataLength() {
-    return this.props.data?.length ?? 0;
+    return this.propsRef.data?.length ?? 0;
   }
 
   private getLayoutManagerClass() {
     // throw errors for incompatible props
-    if (this.props.masonry && this.props.horizontal) {
+    if (this.propsRef.masonry && this.propsRef.horizontal) {
       throw new Error("Masonry and horizontal props are incompatible");
     }
-    if ((this.props.numColumns ?? 1) > 1 && this.props.horizontal) {
+    if ((this.propsRef.numColumns ?? 1) > 1 && this.propsRef.horizontal) {
       throw new Error("numColumns and horizontal props are incompatible");
     }
-    return this.props.masonry
+    return this.propsRef.masonry
       ? RVMasonryLayoutManagerImpl
-      : (this.props.numColumns ?? 1) > 1 && !this.props.horizontal
+      : (this.propsRef.numColumns ?? 1) > 1 && !this.propsRef.horizontal
       ? RVGridLayoutManagerImpl
       : RVLinearLayoutManagerImpl;
   }
@@ -366,7 +367,7 @@ export class RecyclerViewManager<T> {
     const initialItemLayout = this.layoutManager?.getLayout(
       initialScrollIndex ?? 0
     );
-    const initialItemOffset = this.props.horizontal
+    const initialItemOffset = this.propsRef.horizontal
       ? initialItemLayout?.x
       : initialItemLayout?.y;
 
@@ -391,7 +392,7 @@ export class RecyclerViewManager<T> {
     const layoutManager = this.layoutManager;
     if (layoutManager) {
       this.applyInitialScrollAdjustment();
-      const visibleIndices = this.getVisibleIndices();
+      const visibleIndices = this.computeVisibleIndices();
       // console.log("---------> visibleIndices", visibleIndices);
       this.hasRenderedProgressively = visibleIndices.every(
         (index) =>
@@ -412,7 +413,7 @@ export class RecyclerViewManager<T> {
             0,
             Math.min(
               visibleIndices.length,
-              this.renderStack.size + this.initialDrawBatchSize
+              this.getRenderStack().size + this.initialDrawBatchSize
             )
           )
         );
@@ -421,13 +422,14 @@ export class RecyclerViewManager<T> {
 
   private getItemType(index: number): string {
     return (
-      this.props.getItemType?.(this.props.data![index], index) ?? "default"
+      this.propsRef.getItemType?.(this.propsRef.data![index], index) ??
+      "default"
     ).toString();
   }
 
   private getStableId(index: number): string {
     return (
-      this.props.keyExtractor?.(this.props.data![index], index) ??
+      this.propsRef.keyExtractor?.(this.propsRef.data![index], index) ??
       index.toString()
     );
   }