@shopify/flash-list 2.0.0-alpha.8 → 2.0.0-rc.1

package/src/AnimatedFlashList.ts

@@ -1,11 +1,12 @@
 import { Animated } from "react-native";
 
-import FlashList from "./FlashList";
 import { FlashListProps } from "./FlashListProps";
+import { RecyclerView } from "./recyclerview/RecyclerView";
 
+// Typecast as required
 const AnimatedFlashList =
   Animated.createAnimatedComponent<React.ComponentType<FlashListProps<any>>>(
-    FlashList
+    RecyclerView
   );
 
 export default AnimatedFlashList;

package/src/FlashList.tsx

@@ -42,6 +42,7 @@ import {
   hasUnsupportedKeysInContentContainerStyle,
   updateContentStyle,
 } from "./utils/ContentContainerUtils";
+import { ScrollToEdgeParams } from "./FlashListRef";
 
 interface StickyProps extends StickyContainerProps {
   children: any;
@@ -924,6 +925,29 @@ class FlashList<T> extends React.PureComponent<
   public getFirstVisibleIndex() {
     return this.rlvRef?.findApproxFirstVisibleIndex() ?? -1;
   }
+
+  flashScrollIndicators() {
+    this.getNativeScrollRef()?.flashScrollIndicators();
+  }
+
+  getNativeScrollRef() {
+    return (this.rlvRef as any)?._scrollComponent?._scrollViewRef;
+  }
+
+  getScrollResponder() {
+    return this.getNativeScrollRef()?.getScrollResponder();
+  }
+
+  scrollToTop(params?: ScrollToEdgeParams) {
+    this.rlvRef?.scrollToTop(params?.animated);
+  }
+
+  computeVisibleIndices() {
+    console.warn(
+      "computeVisibleIndices is not implemented in old architecture"
+    );
+    return { startIndex: -1, endIndex: -2 };
+  }
 }
 
 export default FlashList;

package/src/FlashListProps.ts

@@ -23,6 +23,12 @@ export interface ListRenderItemInfo<TItem> {
   extraData?: any;
 }
 
+export interface OverrideProps {
+  initialDrawBatchSize?: number;
+  // rest can be string to any
+  [key: string]: any;
+}
+
 export type RenderTarget = "Cell" | "StickyHeader" | "Measurement";
 
 export const RenderTargetOptions: Record<string, RenderTarget> = {
@@ -248,7 +254,10 @@ export interface FlashListProps<TItem>
    * they might be deferred until JS thread is less busy.
    */
   onViewableItemsChanged?:
-    | ((info: { viewableItems: ViewToken[]; changed: ViewToken[] }) => void)
+    | ((info: {
+        viewableItems: ViewToken<TItem>[];
+        changed: ViewToken<TItem>[];
+      }) => void)
     | null
     | undefined;
 
@@ -293,7 +302,7 @@ export interface FlashListProps<TItem>
   /**
    * For debugging and exception use cases, internal props will be overriden with these values if used
    */
-  overrideProps?: object;
+  overrideProps?: OverrideProps;
 
   /**
    * Set this when offset is needed for the loading indicator to show correctly.
@@ -334,6 +343,15 @@ export interface FlashListProps<TItem>
    */
   disableAutoLayout?: boolean;
 
+  /**
+   * New arch only
+   * Maximum number of items in the recycle pool. These are the items that are cached in the recycle pool when they are scrolled off the screen.
+   * Unless you have a huge number of item types, you shouldn't need to set this.
+   * Setting this to 0, will disable the recycle pool and items will unmount once they are scrolled off the screen.
+   * There's no limit by default.
+   */
+  maxItemsInRecyclePool?: number;
+
   /**
    * New arch only
    * Enable masonry layout.
@@ -360,12 +378,6 @@ export interface FlashListProps<TItem>
    */
   onStartReachedThreshold?: FlashListProps<TItem>["onEndReachedThreshold"];
 
-  /**
-   * New arch only
-   * If true, the RecyclerView will not recycle items.
-   */
-  disableRecycling?: boolean;
-
   /**
    * New arch only
    * Style for the RecyclerView's parent container.

package/src/FlashListRef.ts

@@ -0,0 +1,320 @@
+import type { RVLayout } from "./recyclerview/layout-managers/LayoutManager";
+import { RecyclerViewProps } from "./recyclerview/RecyclerViewProps";
+import { CompatScroller } from "./recyclerview/components/CompatScroller";
+
+/**
+ * Base parameters for scrolling to the edges of the list.
+ */
+export interface ScrollToEdgeParams {
+  /** Whether the scroll should be animated */
+  animated?: boolean;
+}
+
+/**
+ * Parameters for scrolling to a specific position in the list.
+ * Extends ScrollToEdgeParams to include view positioning options.
+ */
+export interface ScrollToParams extends ScrollToEdgeParams {
+  /** Position of the target item relative to the viewport (0 = top, 0.5 = center, 1 = bottom) */
+  viewPosition?: number;
+  /** Additional offset to apply after viewPosition calculation */
+  viewOffset?: number;
+}
+
+/**
+ * Parameters for scrolling to a specific offset in the list.
+ * Used when you want to scroll to an exact pixel position.
+ */
+export interface ScrollToOffsetParams extends ScrollToParams {
+  /** The pixel offset to scroll to */
+  offset: number;
+  /**
+   * If true, the first item offset will not be added to the offset calculation.
+   * First offset represents header size or top padding.
+   */
+  skipFirstItemOffset?: boolean;
+}
+
+/**
+ * Parameters for scrolling to a specific index in the list.
+ * Used when you want to scroll to a specific item by its position in the data array.
+ */
+export interface ScrollToIndexParams extends ScrollToParams {
+  /** The index of the item to scroll to */
+  index: number;
+}
+
+/**
+ * Parameters for scrolling to a specific item in the list.
+ * Used when you want to scroll to a specific item by its data value.
+ */
+export interface ScrollToItemParams<T> extends ScrollToParams {
+  /** The item to scroll to */
+  item: T;
+}
+
+/**
+ * Interface for FlashList's ref object that provides imperative methods
+ * for controlling list behavior.
+ *
+ * Usage example:
+ * ```tsx
+ * const listRef = useRef<FlashListRef<ItemType>>(null);
+ *
+ * // Later in your component
+ * <FlashList
+ *   ref={listRef}
+ *   data={data}
+ *   renderItem={renderItem}
+ * />
+ *
+ * // Somewhere else in your component
+ * listRef.current?.scrollToIndex({ index: 5, animated: true });
+ * ```
+ */
+export interface FlashListRef<T> {
+  /**
+   * Get access to current props
+   */
+  props: RecyclerViewProps<T>;
+  /**
+   * Scrolls the list to a specific offset position.
+   *
+   * Use this method when you want precise control over the scroll position in pixels
+   * rather than by item index.
+   *
+   * @param params - Parameters for scrolling to offset
+   * @param params.offset - The pixel offset to scroll to
+   * @param params.animated - Whether the scroll should be animated (default: false)
+   * @param params.skipFirstItemOffset - If true, the first item offset (headers/padding)
+   *                                    will not be included in calculation (default: true)
+   *
+   * @example
+   * // Scroll to 200px from the top/left
+   * listRef.current?.scrollToOffset({ offset: 200, animated: true });
+   */
+  scrollToOffset: (params: ScrollToOffsetParams) => void;
+
+  /**
+   * Makes the scroll indicators flash momentarily.
+   *
+   * Useful to indicate to users that there is more content to scroll.
+   *
+   * @example
+   * listRef.current?.flashScrollIndicators();
+   */
+  flashScrollIndicators: () => void;
+
+  /**
+   * Returns the underlying native scroll view reference.
+   *
+   * Use this when you need direct access to the native scroll component.
+   * This is generally not recommended for regular use.
+   *
+   * @returns The native scroll view reference
+   */
+  getNativeScrollRef: () => CompatScroller | null;
+
+  /**
+   * Returns a reference to the scroll responder.
+   *
+   * Useful for more advanced scroll handling and integrations.
+   *
+   * @returns The scroll responder
+   */
+  getScrollResponder: CompatScroller["getScrollResponder"];
+
+  /**
+   * Returns the underlying scrollable node.
+   *
+   * Primarily used for platform-specific integrations.
+   *
+   * @returns The scrollable node
+   */
+  getScrollableNode: () => any;
+
+  /**
+   * Scrolls to the end of the list.
+   *
+   * @param params - Optional parameters for scrolling
+   * @param params.animated - Whether the scroll should be animated (default: false)
+   *
+   * @example
+   * // Animate scroll to the end of the list
+   * listRef.current?.scrollToEnd({ animated: true });
+   */
+  scrollToEnd: (params?: ScrollToEdgeParams) => void;
+
+  /**
+   * Scrolls to the top (or start) of the list.
+   *
+   * @param params - Optional parameters for scrolling
+   * @param params.animated - Whether the scroll should be animated (default: false)
+   *
+   * @example
+   * // Smoothly scroll to the top
+   * listRef.current?.scrollToTop({ animated: true });
+   */
+  scrollToTop: (params?: ScrollToEdgeParams) => void;
+
+  /**
+   * Scrolls to a specific index in the list.
+   *
+   * This is the most common method to scroll to a particular item.
+   *
+   * @param params - Parameters for scrolling to index
+   * @param params.index - The index of the item to scroll to
+   * @param params.animated - Whether the scroll should be animated (default: false)
+   * @param params.viewPosition - Position of the item within the visible area:
+   *                              0 = top/left, 0.5 = center, 1 = bottom/right (default: 0)
+   * @param params.viewOffset - Additional offset to apply after viewPosition calculation
+   *
+   * @returns A Promise that resolves when the scroll operation is complete
+   *
+   * @example
+   * // Scroll to the 5th item (index 4) and center it
+   * listRef.current?.scrollToIndex({
+   *   index: 4,
+   *   animated: true,
+   *   viewPosition: 0.5
+   * });
+   */
+  scrollToIndex: (params: ScrollToIndexParams) => Promise<void>;
+
+  /**
+   * Scrolls to a specific item in the list.
+   *
+   * Similar to scrollToIndex, but works with the item reference instead of its index.
+   * Useful when you have a reference to an item but don't know its index.
+   *
+   * @param params - Parameters for scrolling to item
+   * @param params.item - The item object to scroll to
+   * @param params.animated - Whether the scroll should be animated (default: false)
+   * @param params.viewPosition - Position of the item within the visible area:
+   *                              0 = top/left, 0.5 = center, 1 = bottom/right (default: 0)
+   * @param params.viewOffset - Additional offset to apply after viewPosition calculation
+   *
+   * @example
+   * // Scroll to a specific item
+   * const targetItem = data[10];
+   * listRef.current?.scrollToItem({
+   *   item: targetItem,
+   *   animated: true
+   * });
+   */
+  scrollToItem: (params: ScrollToItemParams<T>) => void;
+
+  /**
+   * Returns the offset of the first item (accounts for header/padding).
+   *
+   * Useful when implementing custom scroll behavior or calculating positions.
+   *
+   * @returns The pixel offset of the first item
+   */
+  getFirstItemOffset: () => number;
+
+  /**
+   * Returns the current viewport dimensions.
+   *
+   * @returns An object with width and height properties representing viewport size
+   */
+  getWindowSize: () => { width: number; height: number };
+
+  /**
+   * Returns the layout information for a specific item.
+   *
+   * Use this to get position and size information for an item at a given index.
+   *
+   * @param index - The index of the item to get layout information for
+   * @returns Layout information including x, y, width, and height
+   *
+   * @example
+   * const itemLayout = listRef.current?.getLayout(5);
+   * console.log(`Item 5 position: (${itemLayout.x}, ${itemLayout.y})`);
+   */
+  getLayout: (index: number) => RVLayout | undefined;
+
+  /**
+   * Returns the absolute last scroll offset.
+   *
+   * Useful for implementing custom scroll tracking functionality.
+   *
+   * @returns The last scroll offset in pixels
+   */
+  getAbsoluteLastScrollOffset: () => number;
+
+  /**
+   * Returns the dimensions of the child container.
+   *
+   * @returns An object with width and height properties
+   */
+  getChildContainerDimensions: () => { width: number; height: number };
+
+  /**
+   * Marks the list as having been interacted with.
+   *
+   * Call this method when you want to manually trigger the onViewableItemsChanged
+   * callback without an actual scroll event.
+   */
+  recordInteraction: () => void;
+
+  /**
+   * Returns the currently visible item indices.
+   *
+   * Use this to determine which items are currently visible to the user.
+   *
+   * @returns An object with startIndex and endIndex properties
+   *
+   * @example
+   * const { startIndex, endIndex } = listRef.current?.getVisibleIndices();
+   * console.log(`Visible items: ${startIndex} to ${endIndex}`);
+   */
+  computeVisibleIndices: () => { startIndex: number; endIndex: number };
+
+  /**
+   * Returns the index of the first visible item.
+   *
+   * Convenience method when you only need the first visible item.
+   *
+   * @returns The index of the first visible item
+   *
+   * @example
+   * const firstVisibleIndex = listRef.current?.getFirstVisibleIndex();
+   */
+  getFirstVisibleIndex: () => number;
+
+  /**
+   * Forces recalculation of viewable items (vieability callbacks).
+   *
+   * Call this after any operation that might affect item visibility but
+   * doesn't trigger a scroll event.
+   *
+   * @example
+   * // After manually changing item sizes
+   * listRef.current?.recomputeViewableItems();
+   */
+  recomputeViewableItems: () => void;
+
+  /**
+   * Disables item recycling in preparation for layout animations.
+   *
+   * Call this before performing layout animations to prevent visual glitches.
+   * Remember to reset disableRecycling after animations complete.
+   *
+   * @example
+   * // Before starting layout animations
+   * listRef.current?.prepareForLayoutAnimationRender();
+   */
+  prepareForLayoutAnimationRender: () => void;
+
+  /**
+   * Clears the layout cache on update.
+   * Call this when you want to clear the layout cache on update.
+   * Can be useful for carousals when orientation changes.
+   * This should be called before the render and not in an effect.
+   *
+   * @example
+   * listRef.current?.clearLayoutCacheOnUpdate();
+   */
+  clearLayoutCacheOnUpdate: () => void;
+}

package/src/MasonryFlashList.tsx

@@ -258,7 +258,7 @@ const MasonryFlashListComponent = React.forwardRef(
                   ? (info) => {
                       updateViewTokens(info.viewableItems);
                       updateViewTokens(info.changed);
-                      onViewableItemsChanged?.(info);
+                      onViewableItemsChanged?.(info as any);
                     }
                   : undefined
               }
@@ -437,7 +437,7 @@ const getFlashListScrollView = (
   FlashListScrollView.displayName = "FlashListScrollView";
   return FlashListScrollView;
 };
-const updateViewTokens = (tokens: ViewToken[]) => {
+const updateViewTokens = (tokens: ViewToken<any>[]) => {
   const length = tokens.length;
   for (let i = 0; i < length; i++) {
     const token = tokens[i];

package/src/__tests__/RecyclerView.test.tsx

@@ -15,14 +15,14 @@ jest.mock("../recyclerview/utils/measureLayout", () => {
     measureParentSize: jest.fn().mockImplementation(() => ({
       x: 0,
       y: 0,
-      width: 400,
-      height: 900,
+      width: 399,
+      height: 899,
     })),
-    measureChildContainerLayout: jest.fn().mockImplementation(() => ({
+    measureFirstChildLayout: jest.fn().mockImplementation(() => ({
       x: 0,
       y: 0,
-      width: 400,
-      height: 900,
+      width: 399,
+      height: 899,
     })),
     measureItemLayout: jest.fn().mockImplementation(() => ({
       x: 0,
@@ -33,37 +33,91 @@ jest.mock("../recyclerview/utils/measureLayout", () => {
   };
 });
 
+const renderRecyclerView = (args: {
+  numColumns?: number;
+  masonry?: boolean;
+  horizontal?: boolean;
+}) => {
+  const { numColumns = 1, masonry = false, horizontal = false } = args;
+  return render(
+    <RecyclerView
+      data={[
+        0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19,
+      ]}
+      masonry={masonry}
+      overrideProps={{ initialDrawBatchSize: 1 }}
+      drawDistance={0}
+      numColumns={numColumns}
+      horizontal={horizontal}
+      renderItem={({ item }) => <Text>{item}</Text>}
+    />
+  );
+};
+
 describe("RecyclerView", () => {
   beforeEach(() => {
     jest.clearAllMocks();
     jest.useFakeTimers();
   });
+  describe("Linear Layout", () => {
+    it("renders items ", () => {
+      const result = renderRecyclerView({});
+
+      expect(result).toContainReactComponent(Text, { children: 0 });
+      expect(result).not.toContainReactComponent(Text, { children: 11 });
+    });
+  });
+
+  describe("Masonry Layout", () => {
+    it("renders items with masonry", () => {
+      const result = renderRecyclerView({ masonry: true });
+
+      expect(result).toContainReactComponent(Text, { children: 0 });
+    });
+    it("should not render item 18, 19 with numColumns 2", () => {
+      const result = renderRecyclerView({ numColumns: 2, masonry: true });
+
+      expect(result).toContainReactComponent(Text, {
+        children: 17,
+      });
+      expect(result).not.toContainReactComponent(Text, {
+        children: 18,
+      });
+
+      expect(result).not.toContainReactComponent(Text, {
+        children: 19,
+      });
+    });
+  });
+
+  describe("Grid Layout", () => {
+    it("renders items with numColumns 2", () => {
+      const result = renderRecyclerView({ numColumns: 2 });
+
+      expect(result).toContainReactComponent(Text, { children: 0 });
+    });
+    it("should not render item 18, 19 with numColumns 2", () => {
+      const result = renderRecyclerView({ numColumns: 2 });
+
+      expect(result).toContainReactComponent(Text, {
+        children: 17,
+      });
+      expect(result).not.toContainReactComponent(Text, {
+        children: 18,
+      });
+
+      expect(result).not.toContainReactComponent(Text, {
+        children: 19,
+      });
+    });
+  });
 
-  it("renders items ", () => {
-    const result = render(
-      <RecyclerView
-        data={[
-          "One",
-          "Two",
-          "Three",
-          "Four",
-          "Five",
-          "Six",
-          "Seven",
-          "Eight",
-          "Nine",
-          "Ten",
-          "Eleven",
-          "Twelve",
-          "Thirteen",
-          "Fourteen",
-          "Fifteen",
-        ]}
-        renderItem={({ item }) => <Text>{item}</Text>}
-      />
-    );
+  describe("Horizontal Layout", () => {
+    it("renders items with horizontal", () => {
+      const result = renderRecyclerView({ horizontal: true });
 
-    expect(result).toContainReactComponent(Text, { children: "One" });
-    expect(result).not.toContainReactComponent(Text, { children: "Eleven" });
+      expect(result).toContainReactComponent(Text, { children: 0 });
+      expect(result).not.toContainReactComponent(Text, { children: 4 });
+    });
   });
 });