@react-native-ohos/flash-list 1.8.3 → 2.1.1-rc.1

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

@@ -0,0 +1,180 @@
+/**
+ * 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 && trailingItem !== undefined ? (
+      <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;
+    // 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",
+    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,
+  } 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
+  );
+}

package/src/recyclerview/ViewHolderCollection.tsx

@@ -0,0 +1,193 @@
+/**
+ * ViewHolderCollection is a container component that manages multiple ViewHolder instances.
+ * It handles the rendering of a collection of list items, manages layout updates,
+ * and coordinates with the RecyclerView context for layout changes.
+ */
+
+import React, { useEffect, useImperativeHandle, useLayoutEffect } from "react";
+
+import { FlashListProps } from "../FlashListProps";
+
+import { ViewHolder, ViewHolderProps } from "./ViewHolder";
+import { RVDimension, RVLayout } from "./layout-managers/LayoutManager";
+import { CompatView } from "./components/CompatView";
+import { useRecyclerViewContext } from "./RecyclerViewContextProvider";
+
+/**
+ * Props interface for the ViewHolderCollection component
+ * @template TItem - The type of items in the data array
+ */
+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<string, { index: number }>;
+  /** Function to get layout information for a specific index */
+  getLayout: (index: number) => RVLayout;
+  /** Ref to control layout updates from parent components */
+  viewHolderCollectionRef: React.Ref<ViewHolderCollectionRef>;
+  /** Map to store refs for each ViewHolder instance */
+  refHolder: ViewHolderProps<TItem>["refHolder"];
+  /** Callback when any item's size changes */
+  onSizeChanged: ViewHolderProps<TItem>["onSizeChanged"];
+  /** Function to render each item */
+  renderItem: FlashListProps<TItem>["renderItem"];
+  /** Additional data passed to renderItem that can trigger re-renders */
+  extraData: any;
+  /** Function to get the container's layout dimensions */
+  getChildContainerLayout: () => RVDimension | undefined;
+  /** Callback after layout effects are committed */
+  onCommitLayoutEffect: () => void;
+  /** Callback after effects are committed */
+  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;
+}
+
+/**
+ * Ref interface for ViewHolderCollection that exposes methods to control layout updates
+ */
+export interface ViewHolderCollectionRef {
+  /** Forces a layout update by triggering a re-render */
+  commitLayout: () => void;
+}
+
+/**
+ * ViewHolderCollection component that manages the rendering of multiple ViewHolder instances
+ * and handles layout updates for the entire collection
+ * @template TItem - The type of items in the data array
+ */
+export const ViewHolderCollection = <TItem,>(
+  props: ViewHolderCollectionProps<TItem>
+) => {
+  const {
+    data,
+    renderStack,
+    getLayout,
+    refHolder,
+    onSizeChanged,
+    renderItem,
+    extraData,
+    viewHolderCollectionRef,
+    getChildContainerLayout,
+    onCommitLayoutEffect,
+    CellRendererComponent,
+    ItemSeparatorComponent,
+    onCommitEffect,
+    horizontal,
+    getAdjustmentMargin,
+  } = props;
+
+  const [renderId, setRenderId] = React.useState(0);
+
+  const containerLayout = getChildContainerLayout();
+
+  const fixedContainerSize = horizontal
+    ? containerLayout?.height
+    : containerLayout?.width;
+
+  const recyclerViewContext = useRecyclerViewContext();
+
+  useLayoutEffect(() => {
+    if (renderId > 0) {
+      // console.log(
+      //   "parent layout trigger due to child container size change",
+      //   fixedContainerSize
+      // );
+      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);
+      },
+    }),
+    [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 style={hasData && containerStyle}>
+      {containerLayout &&
+        hasData &&
+        Array.from(renderStack.entries(), ([reactKey, { index }]) => {
+          const item = data[index];
+          const trailingItem = ItemSeparatorComponent
+            ? data[index + 1]
+            : undefined;
+          return (
+            <ViewHolder
+              key={reactKey}
+              index={index}
+              item={item}
+              trailingItem={trailingItem}
+              layout={{
+                ...getLayout(index),
+              }}
+              refHolder={refHolder}
+              onSizeChanged={onSizeChanged}
+              target="Cell"
+              renderItem={renderItem}
+              extraData={extraData}
+              CellRendererComponent={CellRendererComponent}
+              ItemSeparatorComponent={ItemSeparatorComponent}
+              horizontal={horizontal}
+            />
+          );
+        })}
+    </CompatView>
+  );
+};

package/src/recyclerview/components/CompatScroller.ts

@@ -0,0 +1,9 @@
+import { ScrollView, Animated } from "react-native";
+
+const AnimatedScrollView = Animated.ScrollView;
+
+/** Regular scroll view component */
+export { ScrollView as CompatScroller };
+
+/** Animated scroll view component for smooth scrolling animations */
+export { AnimatedScrollView as CompatAnimatedScroller };