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

package/src/recyclerview/RecyclerViewManager.ts

@@ -0,0 +1,434 @@
+import ViewabilityManager from "../viewability/ViewabilityManager";
+
+import { ConsecutiveNumbers } from "./helpers/ConsecutiveNumbers";
+import { RVGridLayoutManagerImpl } from "./layout-managers/GridLayoutManager";
+import {
+  RVDimension,
+  RVLayoutInfo,
+  RVLayoutManager,
+} 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)
+export class RecyclerViewManager<T> {
+  private initialDrawBatchSize = 1;
+  private engagedIndicesTracker: RVEngagedIndicesTracker;
+  private recycleKeyManager: RecycleKeyManager;
+  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 itemViewabilityManager: ViewabilityManager<T>;
+  private allocatedKeyTracker: Set<string> = new Set();
+  private _isDisposed = false;
+
+  public disableRecycling = false;
+  public firstItemOffset = 0;
+  public ignoreScrollEvents = false;
+
+  public get isOffsetProjectionEnabled() {
+    return this.engagedIndicesTracker.enableOffsetProjection;
+  }
+
+  public get isDisposed() {
+    return this._isDisposed;
+  }
+
+  constructor(props: RecyclerViewProps<T>) {
+    this.props = props;
+    this.engagedIndicesTracker = new RVEngagedIndicesTrackerImpl();
+    this.recycleKeyManager = new RecycleKeyManagerImpl();
+    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;
+  };
+
+  setOffsetProjectionEnabled(value: boolean) {
+    this.engagedIndicesTracker.enableOffsetProjection = value;
+  }
+
+  updateProps(props: RecyclerViewProps<T>) {
+    this.props = props;
+    this.engagedIndicesTracker.drawDistance =
+      props.drawDistance ?? this.engagedIndicesTracker.drawDistance;
+    if (this.props.drawDistance === 0) {
+      this.initialDrawBatchSize = 1;
+    } else {
+      this.initialDrawBatchSize = (props.numColumns ?? 1) * 2;
+    }
+  }
+
+  /**
+   * Updates the scroll offset and returns the engaged indices if any
+   * @param offset
+   * @param velocity
+   */
+  updateScrollOffset(
+    offset: number,
+    velocity?: Velocity
+  ): ConsecutiveNumbers | undefined {
+    if (this.layoutManager && !this.isDisposed) {
+      const engagedIndices = this.engagedIndicesTracker.updateScrollOffset(
+        offset - this.firstItemOffset,
+        velocity,
+        this.layoutManager
+      );
+
+      if (engagedIndices) {
+        this.updateRenderStack(engagedIndices);
+        return engagedIndices;
+      }
+    }
+    return undefined;
+  }
+
+  updateAverageRenderTime(time: number) {
+    this.engagedIndicesTracker.averageRenderTime = time;
+  }
+
+  getIsFirstLayoutComplete() {
+    return this.isFirstLayoutComplete;
+  }
+
+  getLayout(index: number) {
+    if (!this.layoutManager) {
+      throw new Error(
+        "LayoutManager is not initialized, layout info is unavailable"
+      );
+    }
+    return this.layoutManager.getLayout(index);
+  }
+
+  // Doesn't include header / foot etc
+  getChildContainerDimensions() {
+    if (!this.layoutManager) {
+      throw new Error(
+        "LayoutManager is not initialized, child container layout is unavailable"
+      );
+    }
+    return this.layoutManager.getLayoutSize();
+  }
+
+  getRenderStack() {
+    return this.renderStack;
+  }
+
+  getWindowSize() {
+    if (!this.layoutManager) {
+      throw new Error(
+        "LayoutManager is not initialized, window size is unavailable"
+      );
+    }
+    return this.layoutManager.getWindowsSize();
+  }
+
+  // Includes first item offset correction
+  getLastScrollOffset() {
+    return this.engagedIndicesTracker.scrollOffset;
+  }
+
+  getMaxScrollOffset() {
+    return Math.max(
+      0,
+      (this.props.horizontal
+        ? this.getChildContainerDimensions().width
+        : this.getChildContainerDimensions().height) -
+        (this.props.horizontal
+          ? this.getWindowSize().width
+          : this.getWindowSize().height) +
+        this.firstItemOffset
+    );
+  }
+
+  // Doesn't include first item offset correction
+  getAbsoluteLastScrollOffset() {
+    return this.engagedIndicesTracker.scrollOffset + this.firstItemOffset;
+  }
+
+  setScrollDirection(scrollDirection: "forward" | "backward") {
+    this.engagedIndicesTracker.setScrollDirection(scrollDirection);
+  }
+
+  resetVelocityCompute() {
+    this.engagedIndicesTracker.resetVelocityHistory();
+  }
+
+  updateLayoutParams(windowSize: RVDimension, firstItemOffset: number) {
+    this.firstItemOffset = firstItemOffset;
+    const LayoutManagerClass = this.getLayoutManagerClass();
+    if (
+      this.layoutManager &&
+      Boolean(this.layoutManager?.isHorizontal()) !==
+        Boolean(this.props.horizontal)
+    ) {
+      throw new Error(
+        "Horizontal prop cannot be toggled, you can use a key on FlashList to recreate it."
+      );
+    }
+    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,
+          overrideItemLayout: (index, layout) => {
+            this.props?.overrideItemLayout?.(
+              layout,
+              this.props.data![index],
+              index,
+              this.props.numColumns ?? 1,
+              this.props.extraData
+            );
+          },
+        },
+        this.layoutManager
+      );
+    } else {
+      this.layoutManager.updateLayoutParams({
+        windowSize,
+        maxColumns: this.props.numColumns ?? 1,
+        horizontal: Boolean(this.props.horizontal),
+        optimizeItemArrangement: this.props.optimizeItemArrangement ?? true,
+      });
+    }
+  }
+
+  hasLayout() {
+    return this.layoutManager !== undefined;
+  }
+
+  getVisibleIndices() {
+    if (!this.layoutManager) {
+      throw new Error(
+        "LayoutManager is not initialized, visible indices are not unavailable"
+      );
+    }
+    return this.engagedIndicesTracker.computeVisibleIndices(this.layoutManager);
+  }
+
+  getEngagedIndices() {
+    return this.engagedIndicesTracker.getEngagedIndices();
+  }
+
+  modifyChildrenLayout(
+    layoutInfo: RVLayoutInfo[],
+    dataLength: number
+  ): boolean {
+    this.layoutManager?.modifyLayout(layoutInfo, dataLength);
+    if (dataLength === 0) {
+      return false;
+    }
+    if (this.layoutManager?.requiresRepaint) {
+      // console.log("requiresRepaint triggered");
+      this.layoutManager.requiresRepaint = false;
+      return true;
+    }
+    if (this.hasRenderedProgressively) {
+      return this.recomputeEngagedIndices() !== undefined;
+    } else {
+      this.renderProgressively();
+    }
+    return !this.hasRenderedProgressively;
+  }
+
+  computeItemViewability() {
+    // Using higher buffer for masonry to avoid missing items
+    this.itemViewabilityManager.shouldListenToVisibleIndices &&
+      this.itemViewabilityManager.updateViewableItems(
+        this.props.masonry
+          ? this.engagedIndicesTracker.getEngagedIndices().toArray()
+          : this.getVisibleIndices().toArray()
+      );
+  }
+
+  recordInteraction() {
+    this.itemViewabilityManager.recordInteraction();
+  }
+
+  recomputeViewableItems() {
+    this.itemViewabilityManager.recomputeViewableItems();
+  }
+
+  processDataUpdate() {
+    if (this.hasLayout()) {
+      this.modifyChildrenLayout([], this.props.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.
+        this.updateRenderStack(this.engagedIndicesTracker.getEngagedIndices());
+      }
+    }
+  }
+
+  recomputeEngagedIndices(): ConsecutiveNumbers | undefined {
+    return this.updateScrollOffset(this.getAbsoluteLastScrollOffset());
+  }
+
+  dispose() {
+    this._isDisposed = true;
+    this.itemViewabilityManager.dispose();
+  }
+
+  getInitialScrollIndex() {
+    return (
+      this.props.initialScrollIndex ??
+      (this.props.maintainVisibleContentPosition?.startRenderingFromBottom
+        ? this.getDataLength() - 1
+        : undefined)
+    );
+  }
+
+  getDataLength() {
+    return this.props.data?.length ?? 0;
+  }
+
+  private getLayoutManagerClass() {
+    // throw errors for incompatible props
+    if (this.props.masonry && this.props.horizontal) {
+      throw new Error("Masonry and horizontal props are incompatible");
+    }
+    if ((this.props.numColumns ?? 1) > 1 && this.props.horizontal) {
+      throw new Error("numColumns and horizontal props are incompatible");
+    }
+    return this.props.masonry
+      ? RVMasonryLayoutManagerImpl
+      : (this.props.numColumns ?? 1) > 1 && !this.props.horizontal
+      ? RVGridLayoutManagerImpl
+      : RVLinearLayoutManagerImpl;
+  }
+
+  private applyInitialScrollAdjustment() {
+    if (!this.layoutManager || this.getDataLength() === 0) {
+      return;
+    }
+
+    const initialScrollIndex = this.getInitialScrollIndex();
+    const initialItemLayout = this.layoutManager?.getLayout(
+      initialScrollIndex ?? 0
+    );
+    const initialItemOffset = this.props.horizontal
+      ? initialItemLayout?.x
+      : initialItemLayout?.y;
+
+    if (initialScrollIndex !== undefined) {
+      // console.log(
+      //   "initialItemOffset",
+      //   initialScrollIndex,
+      //   initialItemOffset,
+      //   this.firstItemOffset
+      // );
+      this.layoutManager.recomputeLayouts(0, initialScrollIndex);
+      this.engagedIndicesTracker.scrollOffset =
+        initialItemOffset ?? 0 + this.firstItemOffset;
+    } else {
+      // console.log("initialItemOffset", initialItemOffset, this.firstItemOffset);
+      this.engagedIndicesTracker.scrollOffset =
+        (initialItemOffset ?? 0) - this.firstItemOffset;
+    }
+  }
+
+  private renderProgressively() {
+    const layoutManager = this.layoutManager;
+    if (layoutManager) {
+      this.applyInitialScrollAdjustment();
+      const visibleIndices = this.getVisibleIndices();
+      // console.log("---------> visibleIndices", visibleIndices);
+      this.hasRenderedProgressively = visibleIndices.every(
+        (index) =>
+          layoutManager.getLayout(index).isHeightMeasured &&
+          layoutManager.getLayout(index).isWidthMeasured
+      );
+
+      if (this.hasRenderedProgressively) {
+        this.isFirstLayoutComplete = true;
+      }
+
+      // If everything is measured then render stack will be in sync. The buffer items will get rendered in the next update
+      // triggered by the useOnLoad hook.
+      !this.hasRenderedProgressively &&
+        this.updateRenderStack(
+          // pick first n indices from visible ones and n is size of renderStack
+          visibleIndices.slice(
+            0,
+            Math.min(
+              visibleIndices.length,
+              this.renderStack.size + this.initialDrawBatchSize
+            )
+          )
+        );
+    }
+  }
+
+  private getItemType(index: number): string {
+    return (
+      this.props.getItemType?.(this.props.data![index], index) ?? "default"
+    ).toString();
+  }
+
+  private getStableId(index: number): string {
+    return (
+      this.props.keyExtractor?.(this.props.data![index], index) ??
+      index.toString()
+    );
+  }
+}

package/src/recyclerview/RecyclerViewProps.ts

@@ -0,0 +1,11 @@
+import { ScrollViewProps } from "react-native";
+
+import { FlashListProps } from "../FlashListProps";
+
+export interface RecyclerViewProps<TItem>
+  extends Omit<FlashListProps<TItem>, "contentContainerStyle"> {
+  /**
+   * Style for the RecyclerView's parent container.
+   */
+  contentContainerStyle?: ScrollViewProps["contentContainerStyle"];
+}

package/src/recyclerview/ViewHolder.tsx

@@ -0,0 +1,178 @@
+/**
+ * ViewHolder is a core component in FlashList that manages individual item rendering and layout.
+ * It handles the rendering of list items, separators, and manages layout updates for each item.
+ * The component is memoized to prevent unnecessary re-renders and includes layout comparison logic.
+ */
+
+import { LayoutChangeEvent } from "react-native";
+import React, {
+  RefObject,
+  useCallback,
+  useLayoutEffect,
+  useMemo,
+  useRef,
+} from "react";
+
+import { FlashListProps, RenderTarget } from "../FlashListProps";
+
+import { RVDimension, RVLayout } from "./layout-managers/LayoutManager";
+import { CompatView } from "./components/CompatView";
+
+/**
+ * Props interface for the ViewHolder component
+ * @template TItem - The type of item being rendered in the list
+ */
+export interface ViewHolderProps<TItem> {
+  /** Index of the item in the data array */
+  index: number;
+  /** Layout information for positioning and sizing the item */
+  layout: RVLayout;
+  /** Map to store refs for each ViewHolder instance, keyed by index */
+  refHolder: Map<number, RefObject<CompatView | null>>;
+  /** Additional data passed to renderItem that can trigger re-renders */
+  extraData: any;
+  /** Specifies the rendering target (e.g., "Cell", "StickyHeader") */
+  target: RenderTarget;
+  /** The actual item data to be rendered */
+  item: TItem;
+  /** The next item in the list, used for rendering separators */
+  trailingItem: TItem | undefined;
+  /** Function to render the item content */
+  renderItem: FlashListProps<TItem>["renderItem"];
+  /** 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"];
+  /** Callback when the item's size changes */
+  onSizeChanged?: (index: number, size: RVDimension) => void;
+}
+
+/**
+ * Internal ViewHolder component that handles the actual rendering of list items
+ * @template TItem - The type of item being rendered in the list
+ */
+const ViewHolderInternal = <TItem,>(props: ViewHolderProps<TItem>) => {
+  // create ref for View
+  const viewRef = useRef<CompatView>(null);
+  const {
+    index,
+    refHolder,
+    layout,
+    onSizeChanged,
+    renderItem,
+    extraData,
+    item,
+    target,
+    CellRendererComponent,
+    ItemSeparatorComponent,
+    trailingItem,
+    horizontal,
+  } = props;
+
+  useLayoutEffect(() => {
+    refHolder.set(index, viewRef);
+    return () => {
+      if (refHolder.get(index) === viewRef) {
+        refHolder.delete(index);
+      }
+    };
+  }, [index, refHolder]);
+
+  const onLayout = useCallback(
+    (event: LayoutChangeEvent) => {
+      onSizeChanged?.(index, event.nativeEvent.layout);
+    },
+    [index, onSizeChanged]
+  );
+
+  const separator = useMemo(() => {
+    return ItemSeparatorComponent ? (
+      <ItemSeparatorComponent leadingItem={item} trailingItem={trailingItem} />
+    ) : null;
+  }, [ItemSeparatorComponent, item, trailingItem]);
+
+  // console.log("ViewHolder re-render", index);
+
+  const children = useMemo(() => {
+    return renderItem?.({ item, index, extraData, target }) ?? null;
+  }, [item, index, extraData, target, renderItem]);
+
+  const style = {
+    flexDirection: horizontal ? "row" : "column",
+    position: target === "StickyHeader" ? "relative" : "absolute",
+    width: layout.enforcedWidth ? layout.width : undefined,
+    height: layout.enforcedHeight ? layout.height : undefined,
+    minHeight: layout.minHeight,
+    minWidth: layout.minWidth,
+    maxHeight: layout.maxHeight,
+    maxWidth: layout.maxWidth,
+    left: layout.x,
+    top: layout.y,
+    zIndex: 0,
+  } as const;
+
+  // TODO: Fix this type issue
+  const CompatContainer = (CellRendererComponent ??
+    CompatView) as unknown as any;
+
+  return (
+    <CompatContainer
+      ref={viewRef}
+      onLayout={onLayout}
+      style={style}
+      index={index}
+    >
+      {children}
+      {separator}
+    </CompatContainer>
+  );
+};
+
+/**
+ * Memoized ViewHolder component that prevents unnecessary re-renders by comparing props
+ * @template TItem - The type of item being rendered in the list
+ */
+export const ViewHolder = React.memo(
+  ViewHolderInternal,
+  (prevProps, nextProps) => {
+    // compare all props and spread layout
+    return (
+      prevProps.index === nextProps.index &&
+      areLayoutsEqual(prevProps.layout, nextProps.layout) &&
+      prevProps.refHolder === nextProps.refHolder &&
+      prevProps.onSizeChanged === nextProps.onSizeChanged &&
+      prevProps.extraData === nextProps.extraData &&
+      prevProps.target === nextProps.target &&
+      prevProps.item === nextProps.item &&
+      prevProps.renderItem === nextProps.renderItem &&
+      prevProps.CellRendererComponent === nextProps.CellRendererComponent &&
+      prevProps.ItemSeparatorComponent === nextProps.ItemSeparatorComponent &&
+      prevProps.trailingItem === nextProps.trailingItem &&
+      prevProps.horizontal === nextProps.horizontal
+    );
+  }
+);
+
+/**
+ * Compares two RVLayout objects to determine if they are equal
+ * Used in the memo comparison function to prevent unnecessary re-renders
+ * @param prevLayout - Previous layout object
+ * @param nextLayout - Next layout object
+ * @returns boolean indicating if layouts are equal
+ */
+function areLayoutsEqual(prevLayout: RVLayout, nextLayout: RVLayout): boolean {
+  return (
+    prevLayout.x === nextLayout.x &&
+    prevLayout.y === nextLayout.y &&
+    prevLayout.width === nextLayout.width &&
+    prevLayout.height === nextLayout.height &&
+    prevLayout.enforcedWidth === nextLayout.enforcedWidth &&
+    prevLayout.enforcedHeight === nextLayout.enforcedHeight &&
+    prevLayout.minWidth === nextLayout.minWidth &&
+    prevLayout.minHeight === nextLayout.minHeight &&
+    prevLayout.maxWidth === nextLayout.maxWidth &&
+    prevLayout.maxHeight === nextLayout.maxHeight
+  );
+}