@shopify/flash-list 2.0.0-alpha.2 → 2.0.0-alpha.21

package/dist/viewability/ViewabilityManager.js.map

@@ -1 +1 @@
-{"version":3,"file":"ViewabilityManager.js","sourceRoot":"","sources":["../../src/viewability/ViewabilityManager.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"ViewabilityManager.js","sourceRoot":"","sources":["../../src/viewability/ViewabilityManager.ts"],"names":[],"mappings":"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"}

package/jestSetup.js

@@ -1,16 +1,35 @@
 jest.mock("@shopify/flash-list", () => {
-  const ActualFlashList = jest.requireActual("@shopify/flash-list").FlashList;
-  class MockFlashList extends ActualFlashList {
-    componentDidMount() {
-      super.componentDidMount();
-      this.rlvRef?._scrollComponent?._scrollViewRef?.props.onLayout({
-        nativeEvent: { layout: { height: 900, width: 400 } },
-      });
-    }
-  }
+  const RecyclerView = jest.requireActual("@shopify/flash-list").RecyclerView;
+
   return {
     ...jest.requireActual("@shopify/flash-list"),
-    FlashList: MockFlashList,
-    AnimatedFlashList: MockFlashList,
+    FlashList: RecyclerView,
+  };
+});
+
+jest.mock("@shopify/flash-list/dist/recyclerview/utils/measureLayout", () => {
+  const originalModule = jest.requireActual(
+    "@shopify/flash-list/dist/recyclerview/utils/measureLayout"
+  );
+  return {
+    ...originalModule,
+    measureParentSize: jest.fn().mockImplementation(() => ({
+      x: 0,
+      y: 0,
+      width: 400,
+      height: 900,
+    })),
+    measureFirstChildLayout: jest.fn().mockImplementation(() => ({
+      x: 0,
+      y: 0,
+      width: 400,
+      height: 900,
+    })),
+    measureItemLayout: jest.fn().mockImplementation(() => ({
+      x: 0,
+      y: 0,
+      width: 100,
+      height: 100,
+    })),
   };
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shopify/flash-list",
-  "version": "2.0.0-alpha.2",
+  "version": "2.0.0-alpha.21",
   "keywords": [
     "react-native",
     "recyclerview",
@@ -35,6 +35,7 @@
     "lint:fix": "yarn eslint . --ext .ts,.tsx --fix",
     "type-check": "yarn tsc --pretty --noEmit",
     "build": "tsc -b",
+    "watch-web": "sh fixture/web/scripts/copy-dist.sh",
     "prepublishOnly": "yarn run build",
     "fixture:rn:up": "cd fixture/react-native && yarn && cd ios && bundle exec pod install && cd ../../../",
     "fixture:expo:up": "cd fixture/expo && yarn && cd ../../",
@@ -46,7 +47,7 @@
     "rw": "yarn fixture:expo:start",
     "e2e:up": "cd fixture/react-native/ios && brew tap wix/brew && brew install applesimutils && cd ../../../",
     "e2e:ios": "cd fixture/react-native && yarn e2e:build:ios && yarn e2e:test:ios",
-    "rei": "yarn run-e2e-ios",
+    "rei": "yarn run e2e:ios",
     "e2e:android": "cd fixture/react-native && yarn e2e:build:android && yarn e2e:test:android",
     "rea": "yarn run-e2e-android",
     "predeploy:website": "sh ./build_website.sh",
@@ -75,7 +76,7 @@
     "react": "18.3.1",
     "react-native": "0.76.5",
     "react-test-renderer": "18.2.0",
-    "typescript": "^4.7.4"
+    "typescript": "5.8.3"
   },
   "files": [
     "android",

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;
@@ -624,7 +625,7 @@ class FlashList<T> extends React.PureComponent<
   private getValidComponent(
     component: React.ComponentType | React.ReactElement | null | undefined
   ) {
-    const PassedComponent = component;
+    const PassedComponent = component as any;
     return (
       (React.isValidElement(PassedComponent) && PassedComponent) ||
       (PassedComponent && <PassedComponent />) ||
@@ -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

@@ -3,7 +3,6 @@ import {
   StyleProp,
   ScrollViewProps,
   ViewabilityConfig,
-  ViewabilityConfigCallbackPairs,
   ViewStyle,
 } from "react-native";
 
@@ -23,6 +22,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> = {
@@ -47,6 +52,19 @@ export type ContentStyle = Pick<
   | "paddingHorizontal"
 >;
 
+export interface ViewabilityConfigCallbackPair<TItem> {
+  viewabilityConfig: ViewabilityConfig;
+  onViewableItemsChanged:
+    | ((info: {
+        viewableItems: ViewToken<TItem>[];
+        changed: ViewToken<TItem>[];
+      }) => void)
+    | null;
+}
+
+export type ViewabilityConfigCallbackPairs<TItem> =
+  ViewabilityConfigCallbackPair<TItem>[];
+
 export interface FlashListProps<TItem>
   extends Omit<ScrollViewProps, "maintainVisibleContentPosition"> {
   /**
@@ -248,7 +266,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 +314,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.
@@ -317,7 +338,9 @@ export interface FlashListProps<TItem>
    * List of `ViewabilityConfig`/`onViewableItemsChanged` pairs.
    * A specific `onViewableItemsChanged` will be called when its corresponding `ViewabilityConfig`'s conditions are met.
    */
-  viewabilityConfigCallbackPairs?: ViewabilityConfigCallbackPairs | undefined;
+  viewabilityConfigCallbackPairs?:
+    | ViewabilityConfigCallbackPairs<TItem>
+    | undefined;
 
   /**
    * FlashList attempts to measure size of horizontal lists by drawing an extra list item in advance. This can sometimes cause issues when used with `initialScrollIndex` in lists
@@ -334,6 +357,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.
@@ -343,7 +375,7 @@ export interface FlashListProps<TItem>
    * New arch only
    * If enabled, MasonryFlashList will try to reduce difference in column height by modifying item order.
    */
-  optimizeItemArrangement?: boolean; //TODO: Check if this breaks on item resize or is glitchy
+  optimizeItemArrangement?: boolean; // TODO: Check if this breaks on item resize or is glitchy
 
   /**
    * New arch only
@@ -360,12 +392,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.
@@ -391,6 +417,11 @@ export interface FlashListProps<TItem>
      * When content is added at the bottom, automatically scroll to maintain position if the user is within this threshold of the bottom
      */
     autoscrollToBottomThreshold?: number;
+    /**
+     * Scroll with animation whenever `autoscrollToBottom` is triggered. Default is `true`.
+     * Default is true.
+     */
+    animateAutoScrollToBottom?: boolean;
     /**
      * If true, initial render will start from the bottom of the list, useful for chat-like interfaces when there are only few messages
      */

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];