@shopify/flash-list 1.2.2 → 1.3.0

package/src/__tests__/MasonryFlashList.test.ts

@@ -0,0 +1,235 @@
+import { ScrollView, Text, View } from "react-native";
+import "@quilted/react-testing/matchers";
+import { ProgressiveListView } from "recyclerlistview";
+import React from "react";
+
+import {
+  MasonryFlashListProps,
+  MasonryFlashListRef,
+} from "../MasonryFlashList";
+import FlashList from "../FlashList";
+
+import { mountMasonryFlashList } from "./helpers/mountMasonryFlashList";
+
+describe("MasonryFlashList", () => {
+  beforeEach(() => {
+    jest.clearAllMocks();
+    jest.useFakeTimers();
+  });
+
+  it("renders items and has 3 internal lists", () => {
+    const masonryFlashList = mountMasonryFlashList();
+    expect(masonryFlashList.findAll(ProgressiveListView).length).toBe(3);
+    expect(masonryFlashList).toContainReactComponent(Text, { children: "One" });
+    expect(masonryFlashList).toContainReactComponent(ProgressiveListView, {
+      isHorizontal: false,
+    });
+    masonryFlashList.unmount();
+  });
+  it("raised onLoad event only when first internal child mounts", () => {
+    const onLoadMock = jest.fn();
+    const ref = React.createRef<MasonryFlashListRef<string>>();
+    const masonryFlashList = mountMasonryFlashList(
+      {
+        onLoad: onLoadMock,
+      },
+      ref
+    );
+    expect(onLoadMock).not.toHaveBeenCalled();
+    masonryFlashList.findAll(ProgressiveListView)[1]?.instance.onItemLayout(0);
+    expect(onLoadMock).toHaveBeenCalledTimes(1);
+
+    // on load shouldn't be passed to wrapper list
+    expect((ref.current as FlashList<string>).props.onLoad).toBeUndefined();
+    masonryFlashList.unmount();
+  });
+  it("can resize columns using getColumnFlex", () => {
+    const masonryFlashList = mountMasonryFlashList({
+      getColumnFlex: (_, column) => (column === 0 ? 1 : 3),
+    });
+    const progressiveListView =
+      masonryFlashList.find(ProgressiveListView)!.instance;
+    expect(progressiveListView.getLayout(0).width).toBe(100);
+    expect(progressiveListView.getLayout(1).width).toBe(300);
+
+    expect(masonryFlashList.findAll(ProgressiveListView).length).toBe(3);
+    masonryFlashList.findAll(ProgressiveListView).forEach((plv, index) => {
+      if (index === 1) {
+        expect(plv.instance.props.layoutSize.width).toBe(100);
+      }
+      if (index === 2) {
+        expect(plv.instance.props.layoutSize.width).toBe(300);
+      }
+    });
+    masonryFlashList.unmount();
+  });
+  it("mounts a single ScrollView", () => {
+    const masonryFlashList = mountMasonryFlashList();
+    expect(masonryFlashList.findAll(ScrollView)).toHaveLength(1);
+    masonryFlashList.unmount();
+  });
+  it("forwards single onScroll event to external listener", () => {
+    const onScrollMock = jest.fn();
+    const masonryFlashList = mountMasonryFlashList({
+      onScroll: onScrollMock,
+    });
+    masonryFlashList.find(ScrollView)?.instance.props.onScroll({
+      nativeEvent: { contentOffset: { x: 0, y: 0 } },
+    });
+    expect(onScrollMock).toHaveBeenCalledTimes(1);
+    masonryFlashList.unmount();
+  });
+  it("updates scroll offset of all internal lists", () => {
+    const onScrollMock = jest.fn();
+    const masonryFlashList = mountMasonryFlashList({
+      onScroll: onScrollMock,
+    });
+    masonryFlashList.find(ScrollView)?.instance.props.onScroll({
+      nativeEvent: { contentOffset: { x: 0, y: 100 } },
+    });
+    masonryFlashList.findAll(ProgressiveListView).forEach((list) => {
+      expect(list.instance.getCurrentScrollOffset()).toBe(100);
+    });
+    masonryFlashList.unmount();
+  });
+  it("has a valid ref object", () => {
+    const ref = React.createRef<MasonryFlashListRef<string>>();
+    const masonryFlashList = mountMasonryFlashList({}, ref);
+    expect(ref.current).toBeDefined();
+    masonryFlashList.unmount();
+  });
+  it("forwards overrideItemLayout to internal lists", () => {
+    const overrideItemLayout = jest.fn((layout) => {
+      layout.size = 300;
+    });
+    const masonryFlashList = mountMasonryFlashList({
+      overrideItemLayout,
+    });
+    expect(masonryFlashList.findAll(ProgressiveListView).length).toBe(3);
+    masonryFlashList.findAll(ProgressiveListView).forEach((list, index) => {
+      if (index !== 0) {
+        expect(list.instance.getLayout(0).height).toBe(300);
+      }
+    });
+    masonryFlashList.unmount();
+  });
+  it("forwards keyExtractor to internal list", () => {
+    const keyExtractor = (_: string, index: number) => (index + 1).toString();
+    const masonryFlashList = mountMasonryFlashList({
+      keyExtractor,
+    });
+    expect(masonryFlashList.findAll(ProgressiveListView).length).toBe(3);
+    expect(
+      masonryFlashList
+        .findAll(ProgressiveListView)[0]
+        .instance.props.dataProvider.getStableId(0)
+    ).toBe("0");
+    expect(
+      masonryFlashList
+        .findAll(ProgressiveListView)[1]
+        .instance.props.dataProvider.getStableId(0)
+    ).toBe("1");
+    expect(
+      masonryFlashList
+        .findAll(ProgressiveListView)[2]
+        .instance.props.dataProvider.getStableId(0)
+    ).toBe("2");
+    masonryFlashList.unmount();
+  });
+  it("correctly maps list indices to actual indices", () => {
+    const data = new Array(20).fill(0).map((_, index) => index.toString());
+    const getItemType = (item: string, index: number) => {
+      expect(index.toString()).toBe(item);
+      return 0;
+    };
+    const renderItem: MasonryFlashListProps<string>["renderItem"] = ({
+      item,
+      index,
+    }) => {
+      expect(index.toString()).toBe(item);
+      return null;
+    };
+    const overrideItemLayout: MasonryFlashListProps<string>["overrideItemLayout"] =
+      (layout, item: string, index: number) => {
+        expect(index.toString()).toBe(item);
+      };
+    const keyExtractor = (item: string, index: number) => {
+      expect(index.toString()).toBe(item);
+      return index.toString();
+    };
+    const onViewableItemsChanged: MasonryFlashListProps<string>["onViewableItemsChanged"] =
+      (info) => {
+        info.viewableItems.forEach((viewToken) => {
+          expect(viewToken.index?.toString()).toBe(viewToken.item);
+        });
+      };
+
+    const masonryFlashList = mountMasonryFlashList({
+      data,
+      renderItem,
+      getItemType,
+      overrideItemLayout,
+      keyExtractor,
+      onViewableItemsChanged,
+    });
+    jest.advanceTimersByTime(1000);
+    masonryFlashList.unmount();
+  });
+  it("internal list height should be derived from the parent and width from itself", () => {
+    const masonryFlashList = mountMasonryFlashList({
+      testID: "MasonryProxyScrollView",
+    });
+    expect(masonryFlashList.findAll(ProgressiveListView).length).toBe(3);
+    masonryFlashList.findAll(View).forEach((view: any) => {
+      view.props?.onLayout?.({
+        nativeEvent: { layout: { width: 500, height: 500 } },
+      });
+    });
+    masonryFlashList.findAll(ProgressiveListView).forEach((list, index) => {
+      if (index !== 0) {
+        expect(list.instance.getRenderedSize().width).toBe(500);
+        expect(list.instance.getRenderedSize().height).toBe(900);
+      }
+    });
+    masonryFlashList.unmount();
+  });
+  it("can optimize item arrangement", () => {
+    const columnCount = 3;
+    const data = new Array(999).fill(null).map((_, index) => {
+      return "1";
+    });
+    const masonryFlashList = mountMasonryFlashList({
+      data,
+      optimizeItemArrangement: true,
+      numColumns: columnCount,
+      overrideItemLayout(layout, _, index, __, ___?) {
+        layout.size = ((index * 10) % 100) + 100 / ((index % columnCount) + 1);
+      },
+    });
+    expect(masonryFlashList.findAll(ProgressiveListView).length).toBe(4);
+
+    // I've verified that the following values are correct by observing the algorithm in action
+    // Captured values will help prevent regression in the future
+    expect(
+      Math.floor(
+        masonryFlashList
+          .findAll(ProgressiveListView)[1]
+          .instance.getContentDimension().height
+      )
+    ).toBe(35306);
+    expect(
+      Math.floor(
+        masonryFlashList
+          .findAll(ProgressiveListView)[2]
+          .instance.getContentDimension().height
+      )
+    ).toBe(35313);
+    expect(
+      Math.floor(
+        masonryFlashList
+          .findAll(ProgressiveListView)[3]
+          .instance.getContentDimension().height
+      )
+    ).toBe(35339);
+  });
+});

package/src/__tests__/helpers/mountMasonryFlashList.tsx

@@ -0,0 +1,65 @@
+import React from "react";
+import { Text } from "react-native";
+import "@quilted/react-testing/matchers";
+import { mount, 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: 900, 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 = mount(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/errors/ExceptionList.ts

@@ -19,5 +19,10 @@ const ExceptionList = {
       "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/index.ts

@@ -28,6 +28,13 @@ export {
   BlankAreaTrackerResult,
   BlankAreaTrackerConfig,
 } from "./benchmark/useBlankAreaTracker";
+export {
+  MasonryFlashList,
+  MasonryFlashListProps,
+  MasonryFlashListScrollEvent,
+  MasonryFlashListRef,
+  MasonryListItem,
+} from "./MasonryFlashList";
 export { JSFPSMonitor, JSFPSResult } from "./benchmark/JSFPSMonitor";
 export { autoScroll, Cancellable } from "./benchmark/AutoScrollHelper";
 export { default as ViewToken } from "./viewability/ViewToken";

package/src/viewability/ViewabilityManager.ts

@@ -68,7 +68,8 @@ export default class ViewabilityManager<T> {
 
   public updateViewableItems = (newViewableIndices?: number[]) => {
     const listSize =
-      this.flashListRef.recyclerlistview_unsafe?.getRenderedSize();
+      this.flashListRef.recyclerlistview_unsafe?.getRenderedSize() ??
+      this.flashListRef.props.estimatedListSize;
     if (listSize === undefined || !this.shouldListenToVisibleIndices) {
       return;
     }