@shopify/flash-list 1.0.1

package/src/__tests__/useBlankAreaTracker.test.tsx

@@ -0,0 +1,206 @@
+import React, { useEffect } from "react";
+import { mount } 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 = mount(
+    <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/AutoScrollHelper.ts

@@ -0,0 +1,70 @@
+/**
+ * This method can be used to trigger scroll events that can be forwarded to an element. Anything that implements scrollable can leverage this.
+ * @param scroll The scrollable element
+ * @param fromX The x offset to start from
+ * @param fromY The y offset to start from
+ * @param toX the x offset to end scroll at
+ * @param toY the y offset to end scroll at
+ * @param speedMultiplier  the speed multiplier to use
+ * @param cancellable can be used to cancel the scroll
+ * @returns Promise that resolves when the scroll is complete
+ */
+export function autoScroll(
+  scroll: (x: number, y: number, animated: boolean) => void,
+  fromX: number,
+  fromY: number,
+  toX: number,
+  toY: number,
+  speedMultiplier = 1,
+  cancellable: Cancellable = new Cancellable()
+): Promise<boolean> {
+  return new Promise((resolve) => {
+    scroll(fromX, fromY, false);
+    // Very fast scrolls on Android/iOS typically move content 7px every millisecond.
+    const incrementPerMs = 7 * speedMultiplier;
+    const directionMultiplierX = toX > fromX ? 1 : -1;
+    const directionMultiplierY = toY > fromY ? 1 : -1;
+    const comparatorX = toX > fromX ? Math.min : Math.max;
+    const comparatorY = toY > fromY ? Math.min : Math.max;
+    let startTime = Date.now();
+    let startX = fromX;
+    let startY = fromY;
+    // Computes the number of pixels to scroll in the given time
+    // Also invokes the scrollable to update the scroll position
+    const animationLoop = () => {
+      requestAnimationFrame(() => {
+        if (cancellable.isCancelled()) {
+          resolve(false);
+          return;
+        }
+        const currentTime = Date.now();
+        const timeElapsed = currentTime - startTime;
+        const distanceToCover = incrementPerMs * timeElapsed;
+        startX += distanceToCover * directionMultiplierX;
+        startY += distanceToCover * directionMultiplierY;
+        scroll(comparatorX(toX, startX), comparatorY(toY, startY), false);
+        startTime = currentTime;
+        if (
+          comparatorX(toX, startX) !== toX ||
+          comparatorY(toY, startY) !== toY
+        ) {
+          return animationLoop();
+        }
+        resolve(true);
+      });
+    };
+    animationLoop();
+  });
+}
+
+export class Cancellable {
+  public cancel() {
+    this._isCancelled = true;
+  }
+
+  public isCancelled(): boolean {
+    return this._isCancelled;
+  }
+
+  public _isCancelled: boolean = false;
+}

package/src/benchmark/JSFPSMonitor.ts

@@ -0,0 +1,74 @@
+import { roundToDecimalPlaces } from "./roundToDecimalPlaces";
+
+/**
+ * Can be used to monitor JS thread performance
+ * Use startTracking() and stopAndGetData() to start and stop tracking
+ */
+export class JSFPSMonitor {
+  private startTime = 0;
+  private frameCount = 0;
+  private timeWindow = {
+    frameCount: 0,
+    startTime: 0,
+  };
+
+  private minFPS = Number.MAX_SAFE_INTEGER;
+  private maxFPS = 0;
+  private averageFPS = 0;
+
+  private clearAnimationNumber = 0;
+
+  private measureLoop() {
+    // This looks weird but I'm avoiding a new closure
+    this.clearAnimationNumber = requestAnimationFrame(this.updateLoopCompute);
+  }
+
+  private updateLoopCompute = () => {
+    this.frameCount++;
+    const elapsedTime = (Date.now() - this.startTime) / 1000;
+    this.averageFPS = elapsedTime > 0 ? this.frameCount / elapsedTime : 0;
+
+    this.timeWindow.frameCount++;
+    const timeWindowElapsedTime =
+      (Date.now() - this.timeWindow.startTime) / 1000;
+    if (timeWindowElapsedTime >= 1) {
+      const timeWindowAverageFPS =
+        this.timeWindow.frameCount / timeWindowElapsedTime;
+      this.minFPS = Math.min(this.minFPS, timeWindowAverageFPS);
+      this.maxFPS = Math.max(this.maxFPS, timeWindowAverageFPS);
+      this.timeWindow.frameCount = 0;
+      this.timeWindow.startTime = Date.now();
+    }
+    this.measureLoop();
+  };
+
+  public startTracking() {
+    if (this.startTime !== 0) {
+      throw new Error(
+        "This FPS Monitor has already been run, please create a new instance"
+      );
+    }
+    this.startTime = Date.now();
+    this.timeWindow.startTime = Date.now();
+    this.measureLoop();
+  }
+
+  public stopAndGetData(): JSFPSResult {
+    cancelAnimationFrame(this.clearAnimationNumber);
+    if (this.minFPS === Number.MAX_SAFE_INTEGER) {
+      this.minFPS = this.averageFPS;
+      this.maxFPS = this.averageFPS;
+    }
+    return {
+      minFPS: roundToDecimalPlaces(this.minFPS, 1),
+      maxFPS: roundToDecimalPlaces(this.maxFPS, 1),
+      averageFPS: roundToDecimalPlaces(this.averageFPS, 1),
+    };
+  }
+}
+
+export interface JSFPSResult {
+  minFPS: number;
+  maxFPS: number;
+  averageFPS: number;
+}

package/src/benchmark/roundToDecimalPlaces.ts

@@ -0,0 +1,4 @@
+export function roundToDecimalPlaces(value: number, decimalPlaces: number) {
+  const multiplier = 10 ** decimalPlaces;
+  return Math.round(value * multiplier) / multiplier;
+}

package/src/benchmark/useBenchmark.ts

@@ -0,0 +1,240 @@
+import React, { useEffect } from "react";
+
+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;
+
+  /**
+   * Can be used to increase or decrease speed of scrolling
+   */
+  speedMultiplier?: number;
+
+  /**
+   * Specify the number of times benchmark should repeat itself
+   */
+  repeatCount?: number;
+
+  /**
+   * When set to true, cumulative blank area will include sum of negative blank area values
+   * Blank area is negative when list is able to draw faster than the scroll speed.
+   */
+  sumNegativeBlankAreaValues?: boolean;
+}
+
+export interface BenchmarkResult {
+  js?: JSFPSResult;
+  interrupted: boolean;
+  suggestions: string[];
+  blankArea?: BlankAreaTrackerResult;
+  formattedString?: string;
+}
+
+/**
+ * Runs the benchmark on FlashList.
+ * Response object has a formatted string that can be printed to the console or shown as an alert.
+ * Result is posted to the callback method passed to the hook.
+ */
+
+export function useBenchmark(
+  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("Data is empty, cannot run benchmark");
+      }
+    }
+    const cancelTimeout = setTimeout(async () => {
+      const jsFPSMonitor = new JSFPSMonitor();
+      jsFPSMonitor.startTracking();
+      for (let i = 0; i < (params.repeatCount || 1); i++) {
+        await runScrollBenchmark(
+          flashListRef,
+          cancellable,
+          params.speedMultiplier || 1
+        );
+      }
+      const jsProfilerResponse = jsFPSMonitor.stopAndGetData();
+      if (jsProfilerResponse.averageFPS < 35) {
+        suggestions.push(
+          `Your average JS FPS is low. This can indicate that your components are doing too much work. Try to optimize your components and reduce re-renders if any`
+        );
+      }
+      computeSuggestions(flashListRef, suggestions);
+      const result: BenchmarkResult = generateResult(
+        jsProfilerResponse,
+        blankAreaResult,
+        suggestions,
+        cancellable
+      );
+      if (!cancellable.isCancelled()) {
+        result.formattedString = getFormattedString(result);
+      }
+      callback(result);
+    }, params.startDelayInMs || 3000);
+    return () => {
+      clearTimeout(cancelTimeout);
+      cancellable.cancel();
+    };
+    // 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
+            .map((value, index) => `${index + 1}. ${value}`)
+            .join("\n")}`
+        : ``
+    }`
+  );
+}
+
+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(),
+  };
+}
+
+/**
+ * Scrolls to the end of the list and then back to the top
+ */
+async function runScrollBenchmark(
+  flashListRef: React.RefObject<FlashList<any> | null | undefined>,
+  cancellable: Cancellable,
+  scrollSpeedMultiplier: number
+): Promise<void> {
+  if (flashListRef.current) {
+    const horizontal = flashListRef.current.props.horizontal;
+    const rlv = flashListRef.current.recyclerlistview_unsafe;
+    if (rlv) {
+      const rlvSize = rlv.getRenderedSize();
+      const rlvContentSize = rlv.getContentDimension();
+
+      const fromX = 0;
+      const fromY = 0;
+      const toX = rlvContentSize.width - rlvSize.width;
+      const toY = rlvContentSize.height - rlvSize.height;
+
+      const scrollNow = (x: number, y: number) => {
+        flashListRef.current?.scrollToOffset({
+          offset: horizontal ? x : y,
+          animated: false,
+        });
+      };
+
+      await autoScroll(
+        scrollNow,
+        fromX,
+        fromY,
+        toX,
+        toY,
+        scrollSpeedMultiplier,
+        cancellable
+      );
+      await autoScroll(
+        scrollNow,
+        toX,
+        toY,
+        fromX,
+        fromY,
+        scrollSpeedMultiplier,
+        cancellable
+      );
+    }
+  }
+}
+function computeSuggestions(
+  flashListRef: React.RefObject<FlashList<any> | null | undefined>,
+  suggestions: string[]
+) {
+  if (flashListRef.current) {
+    if (flashListRef.current.props.data!!.length < 200) {
+      suggestions.push(
+        `Data count is low. Try to increase it to a large number (e.g 200) using the 'useDataMultiplier' hook.`
+      );
+    }
+    const distanceFromWindow = roundToDecimalPlaces(
+      flashListRef.current.firstItemOffset,
+      0
+    );
+    if (
+      (flashListRef.current.props.estimatedFirstItemOffset || 0) !==
+      distanceFromWindow
+    ) {
+      suggestions.push(
+        `estimatedFirstItemOffset can be set to ${distanceFromWindow}`
+      );
+    }
+    const rlv = flashListRef.current.recyclerlistview_unsafe;
+    const horizontal = flashListRef.current.props.horizontal;
+    if (rlv) {
+      const sizeArray = rlv.props.dataProvider
+        .getAllData()
+        .map((_, index) =>
+          horizontal
+            ? rlv.getLayout?.(index)?.width || 0
+            : rlv.getLayout?.(index)?.height || 0
+        );
+      const averageSize = Math.round(
+        sizeArray.reduce((prev, current) => prev + current, 0) /
+          sizeArray.length
+      );
+      if (
+        Math.abs(
+          averageSize -
+            (flashListRef.current.props.estimatedItemSize ??
+              flashListRef.current.state.layoutProvider
+                .defaultEstimatedItemSize)
+        ) > 5
+      ) {
+        suggestions.push(`estimatedItemSize can be set to ${averageSize}`);
+      }
+    }
+  }
+}