@shopify/flash-list 1.0.1

package/src/__tests__/GridLayoutProviderWithProps.test.ts

@@ -0,0 +1,150 @@
+import { ScrollView } from "react-native";
+import { ProgressiveListView } from "recyclerlistview";
+
+import FlashList from "../FlashList";
+
+import { mountFlashList } from "./helpers/mountFlashList";
+
+describe("GridLayoutProviderWithProps", () => {
+  it("updates average window on layout manager change", () => {
+    const flashList = mountFlashList();
+    const oldAverageWindow = (flashList.instance as FlashList<any>).state
+      .layoutProvider["averageWindow"];
+
+    // width change from default 400 to 600 will force layout manager to change
+    flashList.find(ScrollView)?.trigger("onLayout", {
+      nativeEvent: { layout: { height: 900, width: 600 } },
+    });
+
+    const newAverageWindow =
+      flashList.instance.state.layoutProvider["averageWindow"];
+
+    expect(newAverageWindow).not.toBe(oldAverageWindow);
+    flashList.unmount();
+  });
+  it("average window's size is two times the number of items that will fill the screen", () => {
+    const flashList = mountFlashList({ numColumns: 2 });
+    expect(
+      flashList.instance.state.layoutProvider["averageWindow"]["inputValues"]
+        .length
+    ).toBe(20);
+    flashList.find(ScrollView)?.trigger("onLayout", {
+      nativeEvent: { layout: { height: 2000, width: 600 } },
+    });
+    expect(
+      flashList.instance.state.layoutProvider["averageWindow"]["inputValues"]
+        .length
+    ).toBe(40);
+    flashList.setProps({ numColumns: 1 });
+    expect(
+      flashList.instance.state.layoutProvider["averageWindow"]["inputValues"]
+        .length
+    ).toBe(20);
+    flashList.unmount();
+  });
+  it("average window should not be less than 6 in size", () => {
+    const flashList = mountFlashList();
+    flashList.find(ScrollView)?.trigger("onLayout", {
+      nativeEvent: { layout: { height: 100, width: 100 } },
+    });
+    expect(
+      flashList.instance.state.layoutProvider["averageWindow"]["inputValues"]
+        .length
+    ).toBe(6);
+    flashList.unmount();
+  });
+  it("vertical list: average should not update when widths change", () => {
+    const flashList = mountFlashList();
+    const layoutProvider = flashList.instance.state.layoutProvider;
+    const oldAverage = layoutProvider.averageItemSize;
+
+    layoutProvider.getLayoutManager()!.getLayouts()[0].width = 500;
+    flashList.find(ProgressiveListView)?.instance.onItemLayout(0);
+
+    expect(oldAverage).toBe(layoutProvider.averageItemSize);
+    flashList.unmount();
+  });
+  it("horizontal list: average should not update when heights change", () => {
+    const flashList = mountFlashList({ horizontal: true });
+    const layoutProvider = flashList.instance.state.layoutProvider;
+    const oldAverage = layoutProvider.averageItemSize;
+
+    layoutProvider.getLayoutManager()!.getLayouts()[0].height = 600;
+
+    // Can throw a no op set state warning. Should be handled in PLV.
+    flashList.find(ProgressiveListView)?.instance.onItemLayout(0);
+
+    expect(oldAverage).toBe(layoutProvider.averageItemSize);
+    flashList.unmount();
+  });
+  it("computes correct average", () => {
+    const flashList = mountFlashList();
+    const layoutProvider = flashList.instance.state.layoutProvider;
+    expect(layoutProvider.averageItemSize).toBe(200);
+
+    const layouts = layoutProvider.getLayoutManager()!.getLayouts();
+    const progressiveListView = flashList.find(ProgressiveListView);
+    layouts[0].height = 100;
+    layouts[1].height = 200;
+    layouts[2].height = 300;
+    layouts[3].height = 400;
+    progressiveListView?.instance.onItemLayout(0);
+    progressiveListView?.instance.onItemLayout(1);
+    progressiveListView?.instance.onItemLayout(2);
+    progressiveListView?.instance.onItemLayout(3);
+
+    // estimatedItemSize is treated as one of the values. That's why 240.
+    expect(layoutProvider.averageItemSize).toBe(240);
+    flashList.unmount();
+  });
+  it("updates all cached widths for vertical list and heights for horizontal list when orientation changes", () => {
+    const runCacheUpdateTest = (horizontal: boolean) => {
+      const flashList = mountFlashList({
+        data: new Array(20).fill("1"),
+        horizontal,
+      });
+      const progressiveListView = flashList.find(ProgressiveListView);
+      const layoutProvider = flashList.instance.state.layoutProvider;
+
+      layoutProvider
+        .getLayoutManager()!
+        .getLayouts()
+        .forEach((layout, index) => {
+          // marking layouts as if they're actual rendered sizes
+          progressiveListView?.instance.onItemLayout(index);
+
+          // checking size
+          if (horizontal) {
+            expect(layout.height).toBe(900);
+          } else {
+            expect(layout.width).toBe(400);
+          }
+        });
+
+      // simulates orientation change
+      flashList.find(ScrollView)?.trigger("onLayout", {
+        nativeEvent: { layout: { height: 400, width: 900 } },
+      });
+
+      layoutProvider
+        .getLayoutManager()!
+        .getLayouts()
+        .forEach((layout) => {
+          // making sure all widths or heights are updated
+          if (horizontal) {
+            expect(layout.height).toBe(400);
+          } else {
+            expect(layout.width).toBe(900);
+          }
+
+          // making sure extra keys don't make their way to layout unnecessarily
+          expect(Object.keys(layout).length).toBe(6);
+        });
+      flashList.unmount();
+    };
+    // vertical list
+    runCacheUpdateTest(false);
+    // horizontal list
+    runCacheUpdateTest(true);
+  });
+});

package/src/__tests__/PlatformHelper.web.test.ts

@@ -0,0 +1,29 @@
+import {
+  getCellContainerPlatformStyles,
+  getItemAnimator,
+} from "../utils/PlatformHelper.web";
+
+describe("Platform Helper Web", () => {
+  it("can compute right transform for web", () => {
+    const transformStyle = getCellContainerPlatformStyles(false, {
+      x: 20,
+      y: 70,
+    });
+    const transformInvertedStyle = getCellContainerPlatformStyles(true, {
+      x: 30,
+      y: 30,
+    });
+    const expectedTransform = "translate(20px,70px)";
+    const expectedTransformInverted = "translate(30px,30px) scaleY(-1)";
+
+    expect(transformStyle?.transform).toBe(expectedTransform);
+    expect(transformStyle?.WebkitTransform).toBe(expectedTransform);
+    expect(transformInvertedStyle?.transform).toBe(expectedTransformInverted);
+    expect(transformInvertedStyle?.WebkitTransform).toBe(
+      expectedTransformInverted
+    );
+  });
+  it("can return an animator", () => {
+    expect(getItemAnimator()!["animateWillMount"]).toBeDefined();
+  });
+});

package/src/__tests__/ViewabilityHelper.test.ts

@@ -0,0 +1,283 @@
+import { Dimension, Layout } from "recyclerlistview";
+
+import CustomError from "../errors/CustomError";
+import ExceptionList from "../errors/ExceptionList";
+import ViewabilityHelper from "../viewability/ViewabilityHelper";
+
+describe("ViewabilityHelper", () => {
+  const viewableIndicesChanged = jest.fn();
+  beforeEach(() => {
+    jest.resetAllMocks();
+    jest.useFakeTimers();
+  });
+
+  it("does not report any changes when indices have not changed", () => {
+    const viewabilityHelper = new ViewabilityHelper(
+      null,
+      viewableIndicesChanged
+    );
+    viewabilityHelper.possiblyViewableIndices = [0, 1, 2];
+    updateViewableItems({ viewabilityHelper });
+    // Initial call
+    expect(viewableIndicesChanged).toHaveBeenCalledWith(
+      [0, 1, 2],
+      [0, 1, 2],
+      []
+    );
+
+    // No changes
+    viewableIndicesChanged.mockReset();
+    updateViewableItems({ viewabilityHelper });
+    expect(viewableIndicesChanged).not.toHaveBeenCalled();
+  });
+
+  it("reports only viewable indices", () => {
+    const viewabilityHelper = new ViewabilityHelper(
+      null,
+      viewableIndicesChanged
+    );
+    viewabilityHelper.possiblyViewableIndices = [0, 1, 2, 3];
+    updateViewableItems({ viewabilityHelper });
+    // Items 0, 1, 2 are initially viewable
+    expect(viewableIndicesChanged).toHaveBeenCalledWith(
+      [0, 1, 2],
+      [0, 1, 2],
+      []
+    );
+
+    // After scroll, item 3 becomes viewable, too
+    updateViewableItems({ viewabilityHelper, scrollOffset: 50 });
+    expect(viewableIndicesChanged).toHaveBeenCalledWith([0, 1, 2, 3], [3], []);
+
+    // After additional scroll, the first item is no longer viewable
+    updateViewableItems({ viewabilityHelper, scrollOffset: 100 });
+    expect(viewableIndicesChanged).toHaveBeenCalledWith([1, 2, 3], [], [0]);
+  });
+
+  it("reports only viewable indices when horizontal", () => {
+    const viewabilityHelper = new ViewabilityHelper(
+      null,
+      viewableIndicesChanged
+    );
+    viewabilityHelper.possiblyViewableIndices = [0, 1, 2, 3];
+    const getLayout = (index: number) => {
+      return { x: index * 100, y: 0, height: 300, width: 100 } as Layout;
+    };
+    updateViewableItems({ viewabilityHelper, horizontal: true, getLayout });
+    expect(viewableIndicesChanged).toHaveBeenCalledWith(
+      [0, 1, 2],
+      [0, 1, 2],
+      []
+    );
+
+    updateViewableItems({
+      viewabilityHelper,
+      horizontal: true,
+      scrollOffset: 50,
+      getLayout,
+    });
+    expect(viewableIndicesChanged).toHaveBeenCalledWith([0, 1, 2, 3], [3], []);
+
+    updateViewableItems({
+      viewabilityHelper,
+      horizontal: true,
+      scrollOffset: 100,
+      getLayout,
+    });
+    expect(viewableIndicesChanged).toHaveBeenCalledWith([1, 2, 3], [], [0]);
+  });
+
+  it("reports items only after minimumViewTime has elapsed", () => {
+    const viewabilityHelper = new ViewabilityHelper(
+      { minimumViewTime: 500 },
+      viewableIndicesChanged
+    );
+    viewabilityHelper.possiblyViewableIndices = [0, 1, 2, 3];
+    updateViewableItems({ viewabilityHelper, runAllTimers: false });
+    expect(viewableIndicesChanged).not.toHaveBeenCalled();
+    jest.advanceTimersByTime(400);
+    expect(viewableIndicesChanged).not.toHaveBeenCalled();
+    jest.advanceTimersByTime(100);
+    expect(viewableIndicesChanged).toHaveBeenCalledWith(
+      [0, 1, 2],
+      [0, 1, 2],
+      []
+    );
+
+    viewableIndicesChanged.mockReset();
+    updateViewableItems({
+      viewabilityHelper,
+      scrollOffset: 50,
+      runAllTimers: false,
+    });
+    expect(viewableIndicesChanged).not.toHaveBeenCalled();
+    jest.advanceTimersByTime(500);
+    expect(viewableIndicesChanged).toHaveBeenCalledWith([0, 1, 2, 3], [3], []);
+
+    viewableIndicesChanged.mockReset();
+    updateViewableItems({
+      viewabilityHelper,
+      scrollOffset: 100,
+      runAllTimers: false,
+    });
+    expect(viewableIndicesChanged).not.toHaveBeenCalled();
+    jest.advanceTimersByTime(500);
+    expect(viewableIndicesChanged).toHaveBeenCalledWith([1, 2, 3], [], [0]);
+  });
+
+  it("reports items that only satisfy itemVisiblePercentThreshold", () => {
+    const viewabilityHelper = new ViewabilityHelper(
+      { itemVisiblePercentThreshold: 50 },
+      viewableIndicesChanged
+    );
+    viewabilityHelper.possiblyViewableIndices = [0, 1, 2, 3];
+    updateViewableItems({
+      viewabilityHelper,
+    });
+    expect(viewableIndicesChanged).toHaveBeenCalledWith(
+      [0, 1, 2],
+      [0, 1, 2],
+      []
+    );
+    viewableIndicesChanged.mockReset();
+
+    // User scrolled by 50 pixels, making both first and last item visible from 50 %
+    updateViewableItems({
+      viewabilityHelper,
+      scrollOffset: 50,
+    });
+    expect(viewableIndicesChanged).toHaveBeenCalledWith([0, 1, 2, 3], [3], []);
+    viewableIndicesChanged.mockReset();
+
+    // User scrolled by 55 pixels, first item no longer satisfies threshold
+    updateViewableItems({
+      viewabilityHelper,
+      scrollOffset: 55,
+    });
+    expect(viewableIndicesChanged).toHaveBeenCalledWith([1, 2, 3], [], [0]);
+  });
+
+  it("reports items that only satisfy viewAreaCoveragePercentThreshold", () => {
+    const getLayout = (index: number) => {
+      if (index === 4) {
+        return { x: 0, y: index * 100, width: 100, height: 25 } as Layout;
+      }
+      return { x: 0, y: index * 100, height: 100, width: 300 } as Layout;
+    };
+    const viewabilityHelper = new ViewabilityHelper(
+      { viewAreaCoveragePercentThreshold: 25 },
+      viewableIndicesChanged
+    );
+    viewabilityHelper.possiblyViewableIndices = [0, 1, 2, 3];
+    updateViewableItems({
+      viewabilityHelper,
+      getLayout,
+    });
+    expect(viewableIndicesChanged).toHaveBeenCalledWith(
+      [0, 1, 2],
+      [0, 1, 2],
+      []
+    );
+    viewableIndicesChanged.mockReset();
+
+    // User scrolled by 75 pixels.
+    // First item is visible only from 25 pixels, not meeting the threshold.
+    // The last item is visible from 75 pixels, which is exactly the threshold (300 / 4 = 75 where 300 is height of the list)
+    updateViewableItems({
+      viewabilityHelper,
+      scrollOffset: 75,
+      getLayout,
+    });
+    expect(viewableIndicesChanged).toHaveBeenCalledWith([1, 2, 3], [3], [0]);
+    viewableIndicesChanged.mockReset();
+
+    // User scrolled by 110 pixels, making the last small item only partially visible, not meeting the threshold.
+    viewabilityHelper.possiblyViewableIndices = [1, 2, 3, 4];
+    updateViewableItems({
+      viewabilityHelper,
+      scrollOffset: 110,
+      getLayout,
+    });
+    expect(viewableIndicesChanged).not.toHaveBeenCalled();
+
+    // User scrolled by 125 pixels, making the last small item completely visible, even when it is not meeting the threshold.
+    viewabilityHelper.possiblyViewableIndices = [1, 2, 3, 4];
+    updateViewableItems({
+      viewabilityHelper,
+      scrollOffset: 125,
+      getLayout,
+    });
+    expect(viewableIndicesChanged).toHaveBeenCalledWith([1, 2, 3, 4], [4], []);
+  });
+
+  it("reports viewable items only after interaction if waitForInteraction is set to true", () => {
+    const viewabilityHelper = new ViewabilityHelper(
+      { waitForInteraction: true },
+      viewableIndicesChanged
+    );
+    // Even when elements are visible, viewableIndicesChanged will not be called since interaction has not been recorded, yet
+    viewabilityHelper.possiblyViewableIndices = [0, 1, 2, 3];
+    updateViewableItems({
+      viewabilityHelper,
+    });
+    // View is scrolled but programatically - not resulting in an interaction
+    updateViewableItems({
+      viewabilityHelper,
+      scrollOffset: 50,
+    });
+    expect(viewableIndicesChanged).not.toHaveBeenCalled();
+
+    // Interaction is recorded, leading to trigger of viewableIndicesChanged
+    viewabilityHelper.hasInteracted = true;
+    updateViewableItems({
+      viewabilityHelper,
+      scrollOffset: 50,
+    });
+    expect(viewableIndicesChanged).toHaveBeenCalledWith(
+      [0, 1, 2, 3],
+      [0, 1, 2, 3],
+      []
+    );
+  });
+
+  it("throws multipleViewabilityThresholdTypesNotSupported exception when both viewAreaCoveragePercentThreshold and itemVisiblePercentThreshold are defined", () => {
+    const viewabilityHelper = new ViewabilityHelper(
+      { viewAreaCoveragePercentThreshold: 1, itemVisiblePercentThreshold: 1 },
+      viewableIndicesChanged
+    );
+    expect(() => updateViewableItems({ viewabilityHelper })).toThrow(
+      new CustomError(
+        ExceptionList.multipleViewabilityThresholdTypesNotSupported
+      )
+    );
+  });
+
+  const updateViewableItems = ({
+    viewabilityHelper,
+    horizontal,
+    scrollOffset,
+    listSize,
+    getLayout,
+    runAllTimers,
+  }: {
+    viewabilityHelper: ViewabilityHelper;
+    horizontal?: boolean;
+    scrollOffset?: number;
+    listSize?: Dimension;
+    getLayout?: (index: number) => Layout | undefined;
+    runAllTimers?: boolean;
+  }) => {
+    viewabilityHelper.updateViewableItems(
+      horizontal ?? false,
+      scrollOffset ?? 0,
+      listSize ?? { height: 300, width: 300 },
+      getLayout ??
+        ((index) => {
+          return { x: 0, y: index * 100, height: 100, width: 300 } as Layout;
+        })
+    );
+    if (runAllTimers ?? true) {
+      jest.runAllTimers();
+    }
+  };
+});

package/src/__tests__/helpers/mountFlashList.tsx

@@ -0,0 +1,62 @@
+import React from "react";
+import { ListRenderItem, Text } from "react-native";
+import "@quilted/react-testing/matchers";
+import { mount, Root } from "@quilted/react-testing";
+
+import FlashList from "../../FlashList";
+import { FlashListProps } from "../../FlashListProps";
+
+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: 900, width: 400 } },
+      });
+    }
+  }
+  return MockFlashList;
+});
+export type MockFlashListProps = Omit<
+  FlashListProps<string>,
+  "estimatedItemSize" | "data" | "renderItem"
+> & {
+  estimatedItemSize?: number;
+  data?: string[];
+  renderItem?: ListRenderItem<string>;
+  disableDefaultEstimatedItemSize?: boolean;
+};
+/**
+ * Helper to mount FlashList for testing.
+ */
+export const mountFlashList = (
+  props?: MockFlashListProps,
+  ref?: React.RefObject<FlashList<string>>
+) => {
+  const flashList = mount(renderFlashList(props, ref)) as Omit<
+    Root<FlashListProps<string>>,
+    "instance"
+  > & {
+    instance: FlashList<string>;
+  };
+  return flashList;
+};
+
+export function renderFlashList(
+  props?: MockFlashListProps,
+  ref?: React.RefObject<FlashList<string>>
+) {
+  return (
+    <FlashList
+      {...props}
+      ref={ref}
+      renderItem={props?.renderItem || (({ item }) => <Text>{item}</Text>)}
+      estimatedItemSize={
+        props?.estimatedItemSize ??
+        (props?.disableDefaultEstimatedItemSize ? undefined : 200)
+      }
+      data={props?.data || ["One", "Two", "Three", "Four"]}
+    />
+  );
+}