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

package/src/index.ts

@@ -1,4 +1,12 @@
-export { default as FlashList } from "./FlashList";
+import { RecyclerView } from "./recyclerview/RecyclerView";
+import LegacyFlashList from "./FlashList";
+import { isNewCoreEnabled } from "./enableNewCore";
+
+const FlashList = (isNewCoreEnabled()
+  ? RecyclerView
+  : LegacyFlashList) as unknown as typeof LegacyFlashList;
+
+export { FlashList };
 export {
   FlashListProps,
   ContentStyle,
@@ -37,7 +45,12 @@ export {
   MasonryListRenderItem,
   MasonryListRenderItemInfo,
 } from "./MasonryFlashList";
+export { useLayoutState } from "./recyclerview/hooks/useLayoutState";
+export { useRecyclingState } from "./recyclerview/hooks/useRecyclingState";
 export { JSFPSMonitor, JSFPSResult } from "./benchmark/JSFPSMonitor";
 export { autoScroll, Cancellable } from "./benchmark/AutoScrollHelper";
 export { default as ViewToken } from "./viewability/ViewToken";
 export { default as CellContainer } from "./native/cell-container/CellContainer";
+export { RecyclerView } from "./recyclerview/RecyclerView";
+export { RecyclerViewProps } from "./recyclerview/RecyclerViewProps";
+export { useRecyclerViewContext } from "./recyclerview/RecyclerViewContextProvider";

package/src/recyclerview/RecycleKeyManager.ts

@@ -0,0 +1,185 @@
+export interface RecycleKeyManager {
+  /**
+   * Retrieves a unique key for an item type, maintaining a separate pool for each type.
+   * If a stableId is provided and exists, returns the associated key.
+   * Otherwise, generates a new key or reuses one from the pool.
+   * @param itemType - The type/category of the item (e.g., 'header', 'product', 'footer')
+   * @param stableId - Optional unique identifier for stable item tracking
+   * @param currentKey - Optional current key to maintain if it exists in the pool
+   * @returns A unique key for the item
+   */
+  getKey: (itemType: string, stableId: string, currentKey?: string) => string;
+
+  /**
+   * Recycles a key back into its item type's pool when the associated view is no longer visible.
+   * This allows the key to be reused for new items of the same type.
+   * @param key - The key to be recycled back into the pool
+   */
+  recycleKey: (key: string) => void;
+
+  /**
+   * Checks if a key is currently available in the recycling pool (not in use).
+   * @param key - The key to check
+   * @returns True if the key is available in the pool, false otherwise
+   */
+  hasKeyInPool: (key: string) => boolean;
+
+  /**
+   * Clears all recycled keys from the pool, resetting the recycling system.
+   * This is useful when the list needs to be completely reset.
+   */
+  clearPool: () => void;
+}
+
+export class RecycleKeyManagerImpl implements RecycleKeyManager {
+  // Maximum number of unique keys that can be active at any time
+  private maxItems: number;
+
+  // Stores pools of recycled keys for each item type
+  private keyPools: Map<string, Set<string>>;
+
+  // Maps active keys to their metadata (item type and stable ID)
+  private keyMap: Map<string, { itemType: string; 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;
+
+  /**
+   * Creates a new RecycleKeyManager with a specified maximum number of items.
+   * @param maxItems - Maximum number of unique keys that can be active simultaneously.
+   *                   Defaults to Number.MAX_SAFE_INTEGER if not specified.
+   */
+  constructor(maxItems: number = Number.MAX_SAFE_INTEGER) {
+    this.maxItems = maxItems;
+    this.keyPools = new Map();
+    this.keyMap = new Map();
+    this.stableIdMap = new Map();
+    this.keyCounter = 0;
+  }
+
+  /**
+   * Gets a key for the specified item type, prioritizing stable ID associations.
+   * If a stable ID exists, returns its associated key. Otherwise, either reuses
+   * a key from the pool or generates a new one.
+   * @param itemType - The type/category of the item
+   * @param stableId - Optional unique identifier for stable item tracking
+   * @param currentKey - Optional current key to maintain if it exists in the pool
+   * @returns A unique key for the item
+   */
+  public getKey(
+    itemType: string,
+    stableId: string,
+    currentKey?: string
+  ): string {
+    // Return existing key if stableId is already mapped
+    if (stableId && this.stableIdMap.has(stableId)) {
+      return this.stableIdMap.get(stableId)!;
+    }
+
+    // Get or create the pool for this item type
+    let pool = this.keyPools.get(itemType);
+    if (!pool) {
+      pool = new Set();
+      this.keyPools.set(itemType, pool);
+    }
+
+    let key: string;
+    // Reuse existing key from pool if available
+    if (pool.size > 0) {
+      key =
+        currentKey && pool.has(currentKey)
+          ? currentKey
+          : pool.values().next().value;
+      pool.delete(key);
+    } else {
+      // Generate new key if pool is empty
+      key = this.generateKey();
+    }
+
+    // Update mappings with new key information
+    this.keyMap.set(key, { itemType, stableId });
+    if (stableId) {
+      this.stableIdMap.set(stableId, key);
+    }
+
+    // Ensure we don't exceed the maximum number of active keys
+    this.ensurePoolSize();
+
+    return key;
+  }
+
+  /**
+   * Recycles a key by adding it back to its item type's pool and cleaning up
+   * associated mappings. This should be called when a view is no longer visible.
+   * @param key - The key to be recycled
+   */
+  public recycleKey(key: string): void {
+    const keyInfo = this.keyMap.get(key);
+
+    if (!keyInfo) {
+      return;
+    }
+
+    const { itemType, stableId } = keyInfo;
+    // Clean up stable ID mapping if it exists
+    if (stableId) {
+      this.stableIdMap.delete(stableId);
+    }
+
+    // Add key back to its type's pool
+    let pool = this.keyPools.get(itemType);
+    if (!pool) {
+      pool = new Set();
+      this.keyPools.set(itemType, pool);
+    }
+
+    pool.add(key);
+    this.keyMap.delete(key);
+  }
+
+  /**
+   * Checks if a key is currently available in the recycling pool.
+   * @param key - The key to check
+   * @returns True if the key is available in the pool, false otherwise
+   */
+  public hasKeyInPool(key: string): boolean {
+    return !this.keyMap.has(key);
+  }
+
+  /**
+   * Clears all recycled keys from the pool, effectively resetting the recycling system.
+   * This operation does not affect currently active keys.
+   */
+  public clearPool() {
+    this.keyPools.clear();
+  }
+
+  /**
+   * Generates a unique sequential key using an internal counter.
+   * @returns A unique key as a string
+   */
+  private generateKey(): string {
+    return (this.keyCounter++).toString();
+  }
+
+  /**
+   * Ensures the total number of active keys doesn't exceed the maximum limit.
+   * If the limit is exceeded, recycles the oldest keys until within bounds.
+   * Note: This operation may impact performance when dealing with large lists.
+   * TODO: Check performance impact of this
+   */
+  private ensurePoolSize(): void {
+    if (this.keyMap.size <= this.maxItems) return;
+
+    const keysToRecycle = Array.from(this.keyMap.keys()).slice(
+      0,
+      this.keyMap.size - this.maxItems
+    );
+    for (const key of keysToRecycle) {
+      this.recycleKey(key);
+    }
+  }
+}

package/src/recyclerview/RecyclerView.tsx

@@ -0,0 +1,500 @@
+/**
+ * RecyclerView is a high-performance list component that efficiently renders and recycles list items.
+ * It's designed to handle large lists with optimal memory usage and smooth scrolling.
+ */
+import React, {
+  RefObject,
+  useCallback,
+  useLayoutEffect,
+  useMemo,
+  useRef,
+  forwardRef,
+  useState,
+  useId,
+} from "react";
+import {
+  Animated,
+  I18nManager,
+  NativeScrollEvent,
+  NativeSyntheticEvent,
+} from "react-native";
+
+import { RVDimension } from "./layout-managers/LayoutManager";
+import {
+  areDimensionsNotEqual,
+  measureLayout,
+  measureLayoutRelative,
+} from "./utils/measureLayout";
+import {
+  RecyclerViewContext,
+  RecyclerViewContextProvider,
+  useRecyclerViewContext,
+} from "./RecyclerViewContextProvider";
+import { useLayoutState } from "./hooks/useLayoutState";
+import { useRecyclerViewManager } from "./hooks/useRecyclerViewManager";
+import { RecyclerViewProps } from "./RecyclerViewProps";
+import { useOnListLoad } from "./hooks/useOnLoad";
+import {
+  ViewHolderCollection,
+  ViewHolderCollectionRef,
+} from "./ViewHolderCollection";
+import { CompatView } from "./components/CompatView";
+import { CompatScroller } from "./components/CompatScroller";
+import { useBoundDetection } from "./hooks/useBoundDetection";
+import { adjustOffsetForRTL } from "./utils/adjustOffsetForRTL";
+import { useSecondaryProps } from "./hooks/useSecondaryProps";
+import { StickyHeaders, StickyHeaderRef } from "./components/StickyHeaders";
+import { ScrollAnchor, ScrollAnchorRef } from "./components/ScrollAnchor";
+import { useRecyclerViewController } from "./hooks/useRecyclerViewController";
+
+/**
+ * Main RecyclerView component that handles list rendering, scrolling, and item recycling.
+ * @template T - The type of items in the list
+ */
+const RecyclerViewComponent = <T,>(
+  props: RecyclerViewProps<T>,
+  ref: React.Ref<any>
+) => {
+  // Destructure props and initialize refs
+  const {
+    horizontal,
+    renderItem,
+    data,
+    extraData,
+    onLoad,
+    CellRendererComponent,
+    overrideProps,
+    refreshing,
+    onRefresh,
+    progressViewOffset,
+    ListEmptyComponent,
+    ListHeaderComponent,
+    ListHeaderComponentStyle,
+    ListFooterComponent,
+    ListFooterComponentStyle,
+    ItemSeparatorComponent,
+    renderScrollComponent,
+    onScroll,
+    disableRecycling,
+    style,
+    stickyHeaderIndices,
+    maintainVisibleContentPosition,
+    onCommitLayoutEffect,
+    ...rest
+  } = props;
+
+  // Core refs for managing scroll view, internal view, and child container
+  const scrollViewRef = useRef<CompatScroller>(null);
+  const internalViewRef = useRef<CompatView>(null);
+  const childContainerViewRef = useRef<CompatView>(null);
+  const containerViewSizeRef = useRef<RVDimension | undefined>(undefined);
+  const pendingChildIds = useRef<Set<string>>(new Set()).current;
+
+  // Track scroll position
+  const scrollY = useRef(new Animated.Value(0)).current;
+
+  // Refs for sticky headers and scroll anchoring
+  const stickyHeaderRef = useRef<StickyHeaderRef>(null);
+  const scrollAnchorRef = useRef<ScrollAnchorRef>(null);
+
+  // State for managing layout and render updates
+  const [_, setLayoutTreeId] = useLayoutState(0);
+  const [__, setRenderId] = useState(0);
+
+  // Map to store refs for each item in the list
+  const refHolder = useMemo(
+    () => new Map<number, RefObject<CompatView | null>>(),
+    []
+  );
+
+  // Initialize core RecyclerView manager and content offset management
+  const { recyclerViewManager } = useRecyclerViewManager(props);
+  const { applyContentOffset, applyInitialScrollIndex } =
+    useRecyclerViewController(
+      recyclerViewManager,
+      ref,
+      scrollViewRef,
+      scrollAnchorRef,
+      props
+    );
+
+  // Initialize view holder collection ref
+  const viewHolderCollectionRef = useRef<ViewHolderCollectionRef>(null);
+
+  // Hook to handle list loading
+  useOnListLoad(recyclerViewManager, onLoad);
+
+  // Hook to detect when scrolling reaches list bounds
+  const { checkBounds } = useBoundDetection(
+    recyclerViewManager,
+    props,
+    scrollViewRef
+  );
+
+  /**
+   * Initialize the RecyclerView by measuring and setting up the window size
+   * This effect runs when the component mounts or when layout changes
+   */
+  useLayoutEffect(() => {
+    if (internalViewRef.current && childContainerViewRef.current) {
+      // Measure the outer and inner container layouts
+      const outerViewLayout = measureLayout(internalViewRef.current, undefined);
+      const childViewLayout = measureLayoutRelative(
+        childContainerViewRef.current,
+        internalViewRef.current,
+        undefined
+      );
+
+      containerViewSizeRef.current = outerViewLayout;
+
+      // Calculate offset of first item
+      const firstItemOffset = horizontal
+        ? childViewLayout.x - outerViewLayout.x
+        : childViewLayout.y - outerViewLayout.y;
+
+      // Update the RecyclerView manager with window dimensions
+      recyclerViewManager.updateLayoutParams(
+        {
+          width: horizontal ? outerViewLayout.width : childViewLayout.width,
+          height: horizontal ? childViewLayout.height : outerViewLayout.height,
+        },
+        firstItemOffset
+      );
+    }
+  });
+
+  /**
+   * Effect to handle layout updates for list items
+   * This ensures proper positioning and recycling of items
+   */
+  useLayoutEffect(() => {
+    if (pendingChildIds.size > 0) {
+      return;
+    }
+    const layoutInfo = Array.from(refHolder, ([index, viewHolderRef]) => {
+      const layout = measureLayout(
+        viewHolderRef.current!,
+        recyclerViewManager.getLayout(index)
+      );
+
+      //comapre height with stored layout
+      //const storedLayout = recyclerViewManager.getLayout(index);
+      // if (
+      //   storedLayout.height !== layout.height &&
+      //   storedLayout.isHeightMeasured
+      // ) {
+      //   console.log(
+      //     "height changed",
+      //     index,
+      //     layout.height,
+      //     storedLayout.height
+      //   );
+      // }
+      return { index, dimensions: layout };
+    });
+
+    if (
+      recyclerViewManager.modifyChildrenLayout(layoutInfo, data?.length ?? 0)
+    ) {
+      // Trigger re-render if layout modifications were made
+      setRenderId((prev) => prev + 1);
+    } else {
+      //console.log("commitLayout");
+      // TODO: reduce perf impact of commitLayout
+      viewHolderCollectionRef.current?.commitLayout();
+      applyContentOffset();
+    }
+  });
+
+  /**
+   * Scroll event handler that manages scroll position, velocity, and RTL support
+   */
+  const onScrollHandler = useCallback(
+    (event: NativeSyntheticEvent<NativeScrollEvent>) => {
+      let velocity = event.nativeEvent.velocity;
+      let scrollOffset = horizontal
+        ? event.nativeEvent.contentOffset.x
+        : event.nativeEvent.contentOffset.y;
+
+      // Handle RTL (Right-to-Left) layout adjustments
+      if (I18nManager.isRTL && horizontal) {
+        scrollOffset = adjustOffsetForRTL(
+          scrollOffset,
+          event.nativeEvent.contentSize.width,
+          event.nativeEvent.layoutMeasurement.width
+        );
+        if (velocity) {
+          velocity = {
+            x: -velocity.x,
+            y: velocity.y,
+          };
+        }
+      }
+
+      // Update scroll position and trigger re-render if needed
+      if (recyclerViewManager.updateScrollOffset(scrollOffset, velocity)) {
+        setRenderId((prev) => prev + 1);
+      }
+
+      // Update sticky headers and check bounds
+      stickyHeaderRef.current?.reportScrollEvent(event.nativeEvent);
+      checkBounds();
+
+      // Record interaction and compute item visibility
+      recyclerViewManager.recordInteraction();
+      recyclerViewManager.computeItemViewability();
+
+      // Call user-provided onScroll handler
+      onScroll?.(event);
+    },
+    [horizontal, recyclerViewManager]
+  );
+
+  // Create context for child components
+  const recyclerViewContext: RecyclerViewContext = useMemo(() => {
+    return {
+      layout: () => {
+        setLayoutTreeId((prev) => prev + 1);
+      },
+      getRef: () => {
+        return ref;
+      },
+      getScrollViewRef: () => {
+        return scrollViewRef;
+      },
+      markChildLayoutAsPending: (id: string) => {
+        pendingChildIds.add(id);
+      },
+      unmarkChildLayoutAsPending: (id: string) => {
+        if (pendingChildIds.has(id)) {
+          pendingChildIds.delete(id);
+          recyclerViewContext.layout();
+        }
+      },
+    };
+  }, [setLayoutTreeId]);
+
+  const parentRecyclerViewContext = useRecyclerViewContext();
+  const recyclerViewId = useId();
+
+  /**
+   * Validates that item dimensions match the expected layout
+   */
+  const validateItemSize = useCallback(
+    (index: number, size: RVDimension) => {
+      const layout = recyclerViewManager.getLayout(index);
+      const width = Math.max(
+        Math.min(layout.width, layout.maxWidth ?? Infinity),
+        layout.minWidth ?? 0
+      );
+      const height = Math.max(
+        Math.min(layout.height, layout.maxHeight ?? Infinity),
+        layout.minHeight ?? 0
+      );
+      if (
+        areDimensionsNotEqual(width, size.width) ||
+        areDimensionsNotEqual(height, size.height)
+      ) {
+        // console.log(
+        //   "invalid size",
+        //   index,
+        //   width,
+        //   size.width,
+        //   height,
+        //   size.height
+        // );
+        // TODO: Add a warning for missing useLayoutState
+        recyclerViewContext.layout();
+      }
+    },
+    [recyclerViewManager]
+  );
+
+  // Get secondary props and components
+  const {
+    refreshControl,
+    renderHeader,
+    renderFooter,
+    renderEmpty,
+    CompatScrollView,
+  } = useSecondaryProps(props);
+
+  if (
+    !recyclerViewManager.getIsFirstLayoutComplete() &&
+    recyclerViewManager.getDataLength() > 0
+  ) {
+    parentRecyclerViewContext?.markChildLayoutAsPending(recyclerViewId);
+  }
+
+  // Render sticky headers if configured
+  const stickyHeaders = useMemo(() => {
+    if (
+      data &&
+      data.length > 0 &&
+      stickyHeaderIndices &&
+      stickyHeaderIndices.length > 0
+    ) {
+      return (
+        <StickyHeaders
+          stickyHeaderIndices={stickyHeaderIndices}
+          data={data}
+          renderItem={renderItem}
+          scrollY={scrollY}
+          stickyHeaderRef={stickyHeaderRef}
+          recyclerViewManager={recyclerViewManager}
+          extraData={extraData}
+        />
+      );
+    }
+    return null;
+  }, [data, stickyHeaderIndices, renderItem, extraData]);
+
+  // Set up scroll event handling with animation support for sticky headers
+  const animatedEvent = useMemo(() => {
+    if (stickyHeaders) {
+      return Animated.event(
+        [{ nativeEvent: { contentOffset: { y: scrollY } } }],
+        { useNativeDriver: true, listener: onScrollHandler }
+      );
+    }
+    return onScrollHandler;
+  }, [onScrollHandler, stickyHeaders]);
+
+  const maintainVisibleContentPositionInternal = useMemo(() => {
+    if (maintainVisibleContentPosition?.disabled || horizontal) {
+      return undefined;
+    } else {
+      return {
+        ...maintainVisibleContentPosition,
+        minIndexForVisible: 0,
+      };
+    }
+  }, [maintainVisibleContentPosition]);
+
+  const shouldRenderFromBottom =
+    maintainVisibleContentPositionInternal?.startRenderingFromBottom ?? false;
+
+  // Calculate minimum height adjustment for bottom rendering
+  const adjustmentMinHeight = recyclerViewManager.hasLayout()
+    ? Math.max(
+        0,
+        recyclerViewManager.getWindowSize().height -
+          recyclerViewManager.getChildContainerDimensions().height -
+          recyclerViewManager.firstItemOffset
+      )
+    : 0;
+
+  // Create view for measuring bounded size
+  const viewToMeasureBoundedSize = useMemo(() => {
+    return (
+      <CompatView
+        style={{
+          height: horizontal ? undefined : 0,
+          width: horizontal ? 0 : undefined,
+          minHeight: shouldRenderFromBottom ? adjustmentMinHeight : undefined,
+        }}
+        ref={childContainerViewRef}
+      />
+    );
+  }, [horizontal, shouldRenderFromBottom, adjustmentMinHeight]);
+
+  //console.log("render");
+
+  // Render the main RecyclerView structure
+  return (
+    <RecyclerViewContextProvider value={recyclerViewContext}>
+      <CompatView
+        style={{ flex: horizontal ? undefined : 1, ...style }}
+        ref={internalViewRef}
+        collapsable={false}
+        onLayout={(event) => {
+          if (
+            areDimensionsNotEqual(
+              event.nativeEvent.layout.width,
+              containerViewSizeRef.current?.width ?? 0
+            ) ||
+            areDimensionsNotEqual(
+              event.nativeEvent.layout.height,
+              containerViewSizeRef.current?.height ?? 0
+            )
+          ) {
+            // console.log(
+            //   "onLayout",
+
+            //   recyclerViewManager.getWindowSize(),
+            //   event.nativeEvent.layout
+            // );
+            recyclerViewContext.layout();
+          }
+        }}
+      >
+        <CompatScrollView
+          {...rest}
+          horizontal={horizontal}
+          ref={scrollViewRef}
+          onScroll={animatedEvent}
+          // TODO: evaluate perf
+          maintainVisibleContentPosition={
+            maintainVisibleContentPositionInternal
+          }
+          refreshControl={refreshControl}
+          {...overrideProps}
+        >
+          {/* Scroll anchor for maintaining content position */}
+          {maintainVisibleContentPositionInternal && (
+            <ScrollAnchor scrollAnchorRef={scrollAnchorRef} />
+          )}
+          {renderHeader}
+          {viewToMeasureBoundedSize}
+          {/* Main list content */}
+          <ViewHolderCollection
+            viewHolderCollectionRef={viewHolderCollectionRef}
+            data={data}
+            horizontal={horizontal}
+            renderStack={recyclerViewManager.getRenderStack()}
+            getLayout={(index) => recyclerViewManager.getLayout(index)}
+            refHolder={refHolder}
+            onSizeChanged={validateItemSize}
+            renderItem={renderItem}
+            extraData={extraData}
+            onCommitLayoutEffect={() => {
+              applyInitialScrollIndex();
+              parentRecyclerViewContext?.unmarkChildLayoutAsPending(
+                recyclerViewId
+              );
+              onCommitLayoutEffect?.();
+            }}
+            onCommitEffect={() => {
+              applyInitialScrollIndex();
+              checkBounds();
+              recyclerViewManager.computeItemViewability();
+              recyclerViewManager.disableRecycling = Boolean(disableRecycling);
+            }}
+            CellRendererComponent={CellRendererComponent}
+            ItemSeparatorComponent={ItemSeparatorComponent}
+            getChildContainerLayout={() =>
+              recyclerViewManager.hasLayout()
+                ? recyclerViewManager.getChildContainerDimensions()
+                : undefined
+            }
+          />
+          {renderEmpty}
+          {renderFooter}
+        </CompatScrollView>
+        {stickyHeaders}
+      </CompatView>
+    </RecyclerViewContextProvider>
+  );
+};
+
+// Type definition for the RecyclerView component
+type RecyclerViewType = <T>(
+  props: RecyclerViewProps<T> & { ref?: React.Ref<any> }
+) => React.JSX.Element;
+
+// Create and export the memoized, forwarded ref component
+const RecyclerView = React.memo(
+  forwardRef(RecyclerViewComponent)
+) as RecyclerViewType;
+
+export { RecyclerView };