@shopify/flash-list 2.0.0 → 2.0.2-rc.1

package/src/__tests__/helpers/mountMasonryFlashList.tsx

@@ -0,0 +1,70 @@
+import React from "react";
+import { Text } from "react-native";
+import "@quilted/react-testing/matchers";
+import { render, Root } from "@quilted/react-testing";
+
+import { ListRenderItem } from "../../FlashListProps";
+import {
+  MasonryFlashList,
+  MasonryFlashListProps,
+  MasonryFlashListRef,
+} from "../../MasonryFlashList";
+
+jest.mock("../../FlashList", () => {
+  const ActualFlashList = jest.requireActual("../../FlashList").default;
+  class MockFlashList extends ActualFlashList {
+    componentDidMount() {
+      super.componentDidMount();
+      this.rlvRef?._scrollComponent?._scrollViewRef?.props.onLayout({
+        nativeEvent: {
+          layout: {
+            height: this.props.estimatedListSize?.height ?? 900,
+            width: this.props.estimatedListSize?.width ?? 400,
+          },
+        },
+      });
+    }
+  }
+  return MockFlashList;
+});
+
+export type MockMasonryFlashListProps = Omit<
+  MasonryFlashListProps<string>,
+  "estimatedItemSize" | "data" | "renderItem"
+> & {
+  estimatedItemSize?: number;
+  data?: string[];
+  renderItem?: ListRenderItem<string>;
+};
+
+/**
+ * Helper to mount MasonryFlashList for testing.
+ */
+export const mountMasonryFlashList = (
+  props?: MockMasonryFlashListProps,
+  ref?: React.RefObject<MasonryFlashListRef<string>>
+) => {
+  const flashList = render(renderMasonryFlashList(props, ref)) as Omit<
+    Root<MasonryFlashListProps<string>>,
+    "instance"
+  > & {
+    instance: MasonryFlashListRef<string>;
+  };
+  return flashList;
+};
+
+export function renderMasonryFlashList(
+  props?: MockMasonryFlashListProps,
+  ref?: React.RefObject<MasonryFlashListRef<string>>
+) {
+  return (
+    <MasonryFlashList
+      {...props}
+      ref={ref}
+      numColumns={props?.numColumns ?? 2}
+      renderItem={props?.renderItem || (({ item }) => <Text>{item}</Text>)}
+      estimatedItemSize={props?.estimatedItemSize ?? 200}
+      data={props?.data || ["One", "Two", "Three", "Four"]}
+    />
+  );
+}

package/src/__tests__/useBlankAreaTracker.test.tsx

@@ -0,0 +1,206 @@
+import React, { useEffect } from "react";
+import { render } from "@quilted/react-testing";
+
+import {
+  BlankAreaTrackerConfig,
+  BlankAreaTrackerResult,
+  useBlankAreaTracker,
+} from "../benchmark/useBlankAreaTracker";
+import FlashList from "../FlashList";
+
+import { MockFlashListProps, renderFlashList } from "./helpers/mountFlashList";
+
+type BlankTrackingFlashListProps = MockFlashListProps & {
+  onCumulativeBlankAreaResult?: (result: BlankAreaTrackerResult) => void;
+  onCumulativeBlankAreaChange?: (updatedResult: BlankAreaTrackerResult) => void;
+  blankAreaTrackerConfig?: BlankAreaTrackerConfig;
+  instance?: React.RefObject<FlashList<any>>;
+};
+
+const BlankTrackingFlashList = (props?: BlankTrackingFlashListProps) => {
+  const ref = props?.instance!;
+  const [blankAreaTrackerResult, onBlankArea] = useBlankAreaTracker(
+    ref,
+    props?.onCumulativeBlankAreaChange,
+    {
+      startDelayInMs: props?.blankAreaTrackerConfig?.startDelayInMs ?? 500,
+      sumNegativeValues:
+        props?.blankAreaTrackerConfig?.sumNegativeValues ?? false,
+    }
+  );
+  useEffect(() => {
+    return () => {
+      props?.onCumulativeBlankAreaResult?.(blankAreaTrackerResult);
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+  return renderFlashList(
+    { ...props, onBlankArea, estimatedItemSize: 400 },
+    ref
+  );
+};
+
+const mountBlankTrackingFlashList = (props?: BlankTrackingFlashListProps) => {
+  const flashListRef: React.RefObject<FlashList<any>> = {
+    current: null,
+  };
+  const blankTrackingFlashList = render(
+    <BlankTrackingFlashList {...props} instance={flashListRef} />
+  );
+  return {
+    root: blankTrackingFlashList,
+    instance: flashListRef.current!,
+  };
+};
+
+describe("useBlankAreaTracker Hook", () => {
+  beforeEach(() => {
+    jest.clearAllMocks();
+    jest.useFakeTimers();
+  });
+
+  it("ignores blank events for 500ms on mount and if content is not enough to fill the list", () => {
+    const onCumulativeBlankAreaChange = jest.fn();
+    const flashList = mountBlankTrackingFlashList({
+      onCumulativeBlankAreaChange,
+    });
+    flashList.instance.props.onBlankArea!({
+      blankArea: 100,
+      offsetEnd: 100,
+      offsetStart: 0,
+    });
+    flashList.instance.props.onBlankArea!({
+      blankArea: 100,
+      offsetEnd: 100,
+      offsetStart: 0,
+    });
+    jest.advanceTimersByTime(400);
+    flashList.instance.props.onBlankArea!({
+      blankArea: 100,
+      offsetEnd: 100,
+      offsetStart: 0,
+    });
+    expect(onCumulativeBlankAreaChange).toHaveBeenCalledTimes(0);
+    jest.advanceTimersByTime(100);
+    flashList.instance.props.onBlankArea!({
+      blankArea: 100,
+      offsetEnd: 100,
+      offsetStart: 0,
+    });
+    expect(onCumulativeBlankAreaChange).toHaveBeenCalledTimes(1);
+    onCumulativeBlankAreaChange.mockClear();
+
+    flashList.root.setProps({ data: ["1"] });
+    flashList.instance.props.onBlankArea!({
+      blankArea: 100,
+      offsetEnd: 100,
+      offsetStart: 0,
+    });
+    expect(onCumulativeBlankAreaChange).toHaveBeenCalledTimes(0);
+    flashList.root.unmount();
+  });
+  it("keeps result object updated with correct values on unmount", () => {
+    let resultObjectCopy: BlankAreaTrackerResult | undefined;
+    const onCumulativeBlankAreaChange = jest.fn(
+      (result: BlankAreaTrackerResult) => {
+        if (!resultObjectCopy) {
+          resultObjectCopy = result;
+        }
+      }
+    );
+    const onCumulativeBlankAreaResult = jest.fn();
+    const flashList = mountBlankTrackingFlashList({
+      onCumulativeBlankAreaResult,
+      onCumulativeBlankAreaChange,
+      blankAreaTrackerConfig: { startDelayInMs: 300 },
+    });
+    flashList.instance.props.onBlankArea!({
+      blankArea: 100,
+      offsetEnd: 100,
+      offsetStart: 0,
+    });
+    jest.advanceTimersByTime(300);
+    flashList.instance.props.onBlankArea!({
+      blankArea: 100,
+      offsetEnd: 100,
+      offsetStart: 0,
+    });
+    expect(resultObjectCopy!.cumulativeBlankArea).toBe(100);
+    expect(resultObjectCopy!.maxBlankArea).toBe(100);
+
+    flashList.instance.props.onBlankArea!({
+      blankArea: 200,
+      offsetEnd: 200,
+      offsetStart: 0,
+    });
+    flashList.instance.props.onBlankArea!({
+      blankArea: -200,
+      offsetEnd: -200,
+      offsetStart: 0,
+    });
+    expect(resultObjectCopy!.cumulativeBlankArea).toBe(300);
+    expect(resultObjectCopy!.maxBlankArea).toBe(200);
+
+    flashList.root.unmount();
+    expect(onCumulativeBlankAreaResult).toHaveBeenCalledWith(resultObjectCopy!);
+  });
+  it("can track negative values on demand", () => {
+    const onCumulativeBlankAreaResult = jest.fn();
+    const flashList = mountBlankTrackingFlashList({
+      onCumulativeBlankAreaResult,
+      blankAreaTrackerConfig: { sumNegativeValues: true },
+    });
+    flashList.instance.props.onBlankArea!({
+      blankArea: -200,
+      offsetEnd: -200,
+      offsetStart: 0,
+    });
+    jest.advanceTimersByTime(500);
+    flashList.instance.props.onBlankArea!({
+      blankArea: -200,
+      offsetEnd: -200,
+      offsetStart: 0,
+    });
+    flashList.instance.props.onBlankArea!({
+      blankArea: -200,
+      offsetEnd: -200,
+      offsetStart: 0,
+    });
+    flashList.root.unmount();
+    expect(onCumulativeBlankAreaResult).toHaveBeenCalledWith({
+      cumulativeBlankArea: -400,
+      maxBlankArea: 0,
+    });
+  });
+  it("only calls onCumulativeBlankAreaChange when values have a change", () => {
+    const onCumulativeBlankAreaChange = jest.fn();
+    const flashList = mountBlankTrackingFlashList({
+      onCumulativeBlankAreaChange,
+    });
+    flashList.instance.props.onBlankArea!({
+      blankArea: -200,
+      offsetEnd: -200,
+      offsetStart: 0,
+    });
+    jest.advanceTimersByTime(500);
+    flashList.instance.props.onBlankArea!({
+      blankArea: -200,
+      offsetEnd: -200,
+      offsetStart: 0,
+    });
+    expect(onCumulativeBlankAreaChange).toHaveBeenCalledTimes(0);
+    flashList.instance.props.onBlankArea!({
+      blankArea: -100,
+      offsetEnd: -100,
+      offsetStart: 0,
+    });
+    expect(onCumulativeBlankAreaChange).toHaveBeenCalledTimes(0);
+    flashList.instance.props.onBlankArea!({
+      blankArea: 100,
+      offsetEnd: 100,
+      offsetStart: 0,
+    });
+    expect(onCumulativeBlankAreaChange).toHaveBeenCalledTimes(1);
+    flashList.root.unmount();
+  });
+});

package/src/benchmark/JSFPSMonitor.ts

@@ -1,5 +1,3 @@
-import { ErrorMessages } from "../errors/ErrorMessages";
-
 import { roundToDecimalPlaces } from "./roundToDecimalPlaces";
 
 /**
@@ -46,7 +44,9 @@ export class JSFPSMonitor {
 
   public startTracking() {
     if (this.startTime !== 0) {
-      throw new Error(ErrorMessages.fpsMonitorAlreadyRunning);
+      throw new Error(
+        "This FPS Monitor has already been run, please create a new instance"
+      );
     }
     this.startTime = Date.now();
     this.timeWindow.startTime = Date.now();

package/src/benchmark/useBenchmark.ts

@@ -1,10 +1,14 @@
 import React, { useEffect } from "react";
 
-import { FlashListRef } from "../FlashListRef";
-import { ErrorMessages } from "../errors/ErrorMessages";
+import FlashList from "../FlashList";
 
 import { autoScroll, Cancellable } from "./AutoScrollHelper";
 import { JSFPSMonitor, JSFPSResult } from "./JSFPSMonitor";
+import { roundToDecimalPlaces } from "./roundToDecimalPlaces";
+import {
+  BlankAreaTrackerResult,
+  useBlankAreaTracker,
+} from "./useBlankAreaTracker";
 
 export interface BenchmarkParams {
   startDelayInMs?: number;
@@ -30,6 +34,7 @@ export interface BenchmarkResult {
   js?: JSFPSResult;
   interrupted: boolean;
   suggestions: string[];
+  blankArea?: BlankAreaTrackerResult;
   formattedString?: string;
 }
 
@@ -40,16 +45,21 @@ export interface BenchmarkResult {
  */
 
 export function useBenchmark(
-  flashListRef: React.RefObject<FlashListRef<any>>,
+  flashListRef: React.RefObject<FlashList<any>>,
   callback: (benchmarkResult: BenchmarkResult) => void,
   params: BenchmarkParams = {}
 ) {
+  const [blankAreaResult, blankAreaTracker] = useBlankAreaTracker(
+    flashListRef,
+    undefined,
+    { sumNegativeValues: params.sumNegativeBlankAreaValues, startDelayInMs: 0 }
+  );
   useEffect(() => {
     const cancellable = new Cancellable();
     const suggestions: string[] = [];
     if (flashListRef.current) {
       if (!(Number(flashListRef.current.props.data?.length) > 0)) {
-        throw new Error(ErrorMessages.dataEmptyCannotRunBenchmark);
+        throw new Error("Data is empty, cannot run benchmark");
       }
     }
     const cancelTimeout = setTimeout(async () => {
@@ -71,6 +81,7 @@ export function useBenchmark(
       computeSuggestions(flashListRef, suggestions);
       const result: BenchmarkResult = generateResult(
         jsProfilerResponse,
+        blankAreaResult,
         suggestions,
         cancellable
       );
@@ -85,12 +96,18 @@ export function useBenchmark(
     };
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, []);
+  return [blankAreaTracker];
 }
 
 export function getFormattedString(res: BenchmarkResult) {
   return (
     `Results:\n\n` +
     `JS FPS: Avg: ${res.js?.averageFPS} | Min: ${res.js?.minFPS} | Max: ${res.js?.maxFPS}\n\n` +
+    `${
+      res.blankArea
+        ? `Blank Area: Max: ${res.blankArea?.maxBlankArea} Cumulative: ${res.blankArea?.cumulativeBlankArea}\n\n`
+        : ``
+    }` +
     `${
       res.suggestions.length > 0
         ? `Suggestions:\n\n${res.suggestions
@@ -103,11 +120,22 @@ export function getFormattedString(res: BenchmarkResult) {
 
 function generateResult(
   jsProfilerResponse: JSFPSResult,
+  blankAreaResult: BlankAreaTrackerResult,
   suggestions: string[],
   cancellable: Cancellable
 ) {
   return {
     js: jsProfilerResponse,
+    blankArea:
+      blankAreaResult.maxBlankArea >= 0
+        ? {
+            maxBlankArea: roundToDecimalPlaces(blankAreaResult.maxBlankArea, 0),
+            cumulativeBlankArea: roundToDecimalPlaces(
+              blankAreaResult.cumulativeBlankArea,
+              0
+            ),
+          }
+        : undefined,
     suggestions,
     interrupted: cancellable.isCancelled(),
   };
@@ -117,21 +145,21 @@ function generateResult(
  * Scrolls to the end of the list and then back to the top
  */
 async function runScrollBenchmark(
-  flashListRef: React.RefObject<FlashListRef<any> | null | undefined>,
+  flashListRef: React.RefObject<FlashList<any> | null | undefined>,
   cancellable: Cancellable,
   scrollSpeedMultiplier: number
 ): Promise<void> {
   if (flashListRef.current) {
     const horizontal = flashListRef.current.props.horizontal;
-    const rv = flashListRef.current;
-    if (rv) {
-      const rvSize = rv.getWindowSize();
-      const rvContentSize = rv.getChildContainerDimensions();
+    const rlv = flashListRef.current.recyclerlistview_unsafe;
+    if (rlv) {
+      const rlvSize = rlv.getRenderedSize();
+      const rlvContentSize = rlv.getContentDimension();
 
       const fromX = 0;
       const fromY = 0;
-      const toX = rvContentSize.width - rvSize.width;
-      const toY = rvContentSize.height - rvSize.height;
+      const toX = rlvContentSize.width - rlvSize.width;
+      const toY = rlvContentSize.height - rlvSize.height;
 
       const scrollNow = (x: number, y: number) => {
         flashListRef.current?.scrollToOffset({
@@ -162,7 +190,7 @@ async function runScrollBenchmark(
   }
 }
 function computeSuggestions(
-  flashListRef: React.RefObject<FlashListRef<any> | null | undefined>,
+  flashListRef: React.RefObject<FlashList<any> | null | undefined>,
   suggestions: string[]
 ) {
   if (flashListRef.current) {

package/src/benchmark/useBlankAreaTracker.ts

@@ -0,0 +1,117 @@
+import React, { useCallback, useRef } from "react";
+import { RecyclerListView, RecyclerListViewProps } from "recyclerlistview";
+
+import { BlankAreaEvent } from "../native/auto-layout/AutoLayoutView";
+import FlashList from "../FlashList";
+
+export interface BlankAreaTrackerResult {
+  /**
+   * Max blank area displayed
+   */
+  maxBlankArea: number;
+  /**
+   * Sum of all blank area values across all frames
+   */
+  cumulativeBlankArea: number;
+}
+export interface BlankAreaTrackerConfig {
+  /**
+   * When set to true the hook will also sum all negative blank area values.
+   * Blank area is negative when list is able to draw faster than the scroll speed.
+   */
+  sumNegativeValues?: boolean;
+  /**
+   * By default, the hook ignores blank events for 1s after the list load. This value can be changed using this parameter.
+   * Please note that this duration kicks in after the list has loaded and not after the first scroll.
+   */
+  startDelayInMs?: number;
+}
+
+/**
+ * Can be used to track visible blank area in production
+ * @param flashListRef Ref to the FlashList component
+ * @param onBlankAreaChange This event handler will be called when the blank area changes
+ * @param config additional configuration for the blank area tracker
+ * @returns blankAreaTrackerResult - maxBlankArea, cumulativeBlankArea this object is mutated and kept up to date. Also returns a callback that needs to be forwarded to FlashList.
+ */
+export function useBlankAreaTracker(
+  flashListRef: React.RefObject<FlashList<any>>,
+  onBlankAreaChange?: (value: BlankAreaTrackerResult) => void,
+  config?: BlankAreaTrackerConfig
+): [BlankAreaTrackerResult, (event: BlankAreaEvent) => void] {
+  const startDelay = config?.startDelayInMs ?? 1000;
+  const blankAreaResult = useRef({
+    maxBlankArea: 0,
+    cumulativeBlankArea: 0,
+  }).current;
+  const waitOperations = useRef({ inProgress: false, complete: false }).current;
+  const onBlankAreaChangeRef = useRef(onBlankAreaChange);
+  onBlankAreaChangeRef.current = onBlankAreaChange;
+
+  const blankAreaTracker = useCallback(
+    (event: BlankAreaEvent) => {
+      // we're ignoring some of the events that will be fired on list load
+      // initial events are fired on mount and thus, this won't lead to missing events during scroll
+      if (!waitOperations.complete && startDelay > 0) {
+        if (!waitOperations.inProgress) {
+          waitOperations.inProgress = true;
+          setTimeout(() => {
+            waitOperations.complete = true;
+          }, startDelay);
+        }
+        return;
+      }
+      const rlv = flashListRef.current?.recyclerlistview_unsafe;
+      const horizontal = Boolean(flashListRef.current?.props.horizontal);
+      if (rlv) {
+        processBlankAreaChange(
+          rlv,
+          horizontal,
+          blankAreaResult,
+          event,
+          onBlankAreaChangeRef.current,
+          config
+        );
+      }
+    },
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [flashListRef]
+  );
+  return [blankAreaResult, blankAreaTracker];
+}
+
+function processBlankAreaChange(
+  rlv: RecyclerListView<RecyclerListViewProps, any>,
+  horizontal: boolean,
+  blankAreaResult: BlankAreaTrackerResult,
+  event: BlankAreaEvent,
+  onBlankAreaChange?: (value: BlankAreaTrackerResult) => void,
+  config?: BlankAreaTrackerConfig
+) {
+  const listSize = horizontal
+    ? rlv.getRenderedSize().width
+    : rlv.getRenderedSize().height;
+  const contentSize = horizontal
+    ? rlv.getContentDimension().width
+    : rlv.getContentDimension().height;
+
+  // ignores blank events when there isn't enough content to fill the list
+  if (contentSize > listSize) {
+    const lastMaxBlankArea = blankAreaResult.maxBlankArea;
+    const lastCumulativeBlankArea = blankAreaResult.cumulativeBlankArea;
+    blankAreaResult.maxBlankArea = Math.max(
+      blankAreaResult.maxBlankArea,
+      event.blankArea,
+      0
+    );
+    blankAreaResult.cumulativeBlankArea += config?.sumNegativeValues
+      ? event.blankArea
+      : Math.max(event.blankArea, 0);
+    if (
+      lastCumulativeBlankArea !== blankAreaResult.cumulativeBlankArea ||
+      lastMaxBlankArea !== blankAreaResult.maxBlankArea
+    ) {
+      onBlankAreaChange?.(blankAreaResult);
+    }
+  }
+}

package/src/benchmark/useFlatListBenchmark.ts

@@ -1,8 +1,6 @@
 import { useEffect } from "react";
 import { FlatList } from "react-native";
 
-import { ErrorMessages } from "../errors/ErrorMessages";
-
 import { autoScroll, Cancellable } from "./AutoScrollHelper";
 import { JSFPSMonitor } from "./JSFPSMonitor";
 import {
@@ -29,7 +27,7 @@ export function useFlatListBenchmark(
     const cancellable = new Cancellable();
     if (flatListRef.current && flatListRef.current.props) {
       if (!(Number(flatListRef.current.props.data?.length) > 0)) {
-        throw new Error(ErrorMessages.dataEmptyCannotRunBenchmark);
+        throw new Error("Data is empty, cannot run benchmark");
       }
     }
     const cancelTimeout = setTimeout(async () => {

package/src/enableNewCore.ts

@@ -0,0 +1,24 @@
+import { Platform } from "react-native";
+
+let useNewCore: boolean | undefined;
+export function enableNewCore(enable: boolean) {
+  useNewCore = enable;
+}
+
+export function isNewCoreEnabled() {
+  return useNewCore ?? isReactNativeNewArchitecture();
+}
+
+function isReactNativeNewArchitecture(): boolean {
+  try {
+    // Check for Fabric UI Manager
+    const hasFabricUIManager = Boolean((global as any)?.nativeFabricUIManager);
+
+    // Check for TurboModule system
+    const hasTurboModule = Boolean((global as any)?.__turboModuleProxy);
+
+    return hasFabricUIManager || hasTurboModule || Platform.OS === "web";
+  } catch {
+    return false;
+  }
+}

package/src/errors/CustomError.ts

@@ -0,0 +1,10 @@
+export default class CustomError extends Error {
+  constructor(exception: Exception) {
+    super(`${exception.type}: ${exception.message}`);
+    this.name = exception.type;
+  }
+}
+export interface Exception {
+  type: string;
+  message: string;
+}

package/src/errors/ExceptionList.ts

@@ -0,0 +1,28 @@
+const ExceptionList = {
+  refreshBooleanMissing: {
+    message:
+      "`refreshing` prop must be set as a boolean in order to use `onRefresh`, but got `undefined`.",
+    type: "InvariantViolation",
+  },
+  stickyWhileHorizontalNotSupported: {
+    message:
+      "sticky headers are not supported when list is in horizontal mode. Remove `stickyHeaderIndices` prop.",
+    type: "NotSupportedException",
+  },
+  columnsWhileHorizontalNotSupported: {
+    message:
+      "numColumns is not supported when list is in horizontal mode. Please remove or set numColumns to 1.",
+    type: "NotSupportedException",
+  },
+  multipleViewabilityThresholdTypesNotSupported: {
+    message:
+      "You can set exactly one of itemVisiblePercentThreshold or viewAreaCoveragePercentThreshold. Specifying both is not supported.",
+    type: "MultipleViewabilityThresholdTypesException",
+  },
+  overrideItemLayoutRequiredForMasonryOptimization: {
+    message:
+      "optimizeItemArrangement has been enabled on `MasonryFlashList` but overrideItemLayout is not set.",
+    type: "InvariantViolation",
+  },
+};
+export default ExceptionList;

package/src/errors/Warnings.ts

@@ -0,0 +1,15 @@
+const WarningList = {
+  styleUnsupported:
+    "You have passed a style to FlashList. This list doesn't support styling, use contentContainerStyle or wrap the list in a parent and apply style to it instead.",
+  styleContentContainerUnsupported:
+    "FlashList only supports padding related props and backgroundColor in contentContainerStyle. Please remove other values as they're not used.",
+  unusableRenderedSize:
+    "FlashList's rendered size is not usable. Either the height or width is too small (<2px). " +
+    "Please make sure that the parent view of the list has a valid size. FlashList will match the size of the parent.",
+  missingKeyExtractor:
+    "FlashList requires a keyExtractor prop to be defined when animating elements. Without it, the animations will not run as expected.",
+  estimatedItemSizeMissingWarning:
+    "estimatedItemSize FlashList prop is not defined - based on current configuration you can set it to @size to optimize list performance. " +
+    "Refer to FlashList documentation for more details.",
+};
+export default WarningList;