@shopify/flash-list 1.3.0 → 1.4.0

package/src/MasonryFlashList.tsx

@@ -11,9 +11,20 @@ import {
 import CustomError from "./errors/CustomError";
 import ExceptionList from "./errors/ExceptionList";
 import FlashList from "./FlashList";
-import { FlashListProps } from "./FlashListProps";
+import { FlashListProps, ListRenderItemInfo } from "./FlashListProps";
+import { applyContentContainerInsetForLayoutManager } from "./utils/ContentContainerUtils";
 import ViewToken from "./viewability/ViewToken";
 
+export interface MasonryListRenderItemInfo<TItem>
+  extends ListRenderItemInfo<TItem> {
+  columnSpan: number;
+  columnIndex: number;
+}
+
+export type MasonryListRenderItem<TItem> = (
+  info: MasonryListRenderItemInfo<TItem>
+) => React.ReactElement | null;
+
 export interface MasonryFlashListProps<T>
   extends Omit<
     FlashListProps<T>,
@@ -21,6 +32,7 @@ export interface MasonryFlashListProps<T>
     | "initialScrollIndex"
     | "inverted"
     | "onBlankArea"
+    | "renderItem"
     | "viewabilityConfigCallbackPairs"
   > {
   /**
@@ -39,6 +51,14 @@ export interface MasonryFlashListProps<T>
    * `overrideItemLayout` is required to make this work.
    */
   optimizeItemArrangement?: boolean;
+
+  /**
+   * Extends typical `renderItem` to include `columnIndex` and `columnSpan` (number of columns the item spans).
+   * `columnIndex` gives the consumer column information in case they might need to treat items differently based on column.
+   * This information may not otherwise be derived if using the `optimizeItemArrangement` feature, as the items will no
+   * longer be linearly distributed across the columns; instead they are allocated to the column with the least estimated height.
+   */
+  renderItem: MasonryListRenderItem<T> | null | undefined;
 }
 
 type OnScrollCallback = ScrollViewProps["onScroll"];
@@ -157,6 +177,12 @@ const MasonryFlashListComponent = React.forwardRef(
       (dataSet[0]?.length ?? 0) *
       (props.estimatedItemSize ?? defaultEstimatedItemSize);
 
+    const insetForLayoutManager = applyContentContainerInsetForLayoutManager(
+      { height: 0, width: 0 },
+      props.contentContainerStyle,
+      false
+    );
+
     return (
       <FlashList
         ref={getFlashList}
@@ -179,6 +205,8 @@ const MasonryFlashListComponent = React.forwardRef(
                     ...innerArgs,
                     item: innerArgs.item.originalItem,
                     index: innerArgs.item.originalIndex,
+                    columnSpan: 1,
+                    columnIndex: args.index,
                   }) ?? null
                 );
               }}
@@ -207,8 +235,9 @@ const MasonryFlashListComponent = React.forwardRef(
               estimatedListSize={{
                 height: estimatedListSize.height,
                 width:
-                  ((getListRenderedSize(parentFlashList)?.width ||
-                    estimatedListSize.width) /
+                  (((getListRenderedSize(parentFlashList)?.width ||
+                    estimatedListSize.width) +
+                    insetForLayoutManager.width) /
                     totalColumnFlex) *
                   (getColumnFlex?.(
                     args.item,
@@ -410,8 +439,13 @@ const updateViewTokens = (tokens: ViewToken[]) => {
   for (let i = 0; i < length; i++) {
     const token = tokens[i];
     if (token.index !== null && token.index !== undefined) {
-      token.index = token.item.originalIndex;
-      token.item = token.item.originalItem;
+      if (token.item) {
+        token.index = token.item.originalIndex;
+        token.item = token.item.originalItem;
+      } else {
+        token.index = null;
+        token.item = undefined;
+      }
     }
   }
 };

package/src/__tests__/ContentContainerUtils.test.ts

@@ -0,0 +1,130 @@
+import {
+  applyContentContainerInsetForLayoutManager,
+  getContentContainerPadding,
+  hasUnsupportedKeysInContentContainerStyle,
+  updateContentStyle,
+} from "../utils/ContentContainerUtils";
+
+describe("ContentContainerUtils", () => {
+  it("detects unsupported keys in style", () => {
+    expect(hasUnsupportedKeysInContentContainerStyle({ flex: 1 })).toBe(true);
+    expect(hasUnsupportedKeysInContentContainerStyle({ paddingTop: 0 })).toBe(
+      false
+    );
+    expect(
+      hasUnsupportedKeysInContentContainerStyle({
+        paddingTop: 1,
+        paddingVertical: 1,
+      })
+    ).toBe(false);
+    expect(
+      hasUnsupportedKeysInContentContainerStyle({
+        paddingTop: 1,
+        paddingVertical: 1,
+        padding: 1,
+        paddingLeft: 1,
+        paddingRight: 1,
+        paddingBottom: 1,
+        backgroundColor: "red",
+        paddingHorizontal: 1,
+      })
+    ).toBe(false);
+    expect(hasUnsupportedKeysInContentContainerStyle({ margin: 1 })).toBe(true);
+    expect(hasUnsupportedKeysInContentContainerStyle({ padding: 1 })).toBe(
+      false
+    );
+    expect(
+      hasUnsupportedKeysInContentContainerStyle({ backgroundColor: "red" })
+    ).toBe(false);
+  });
+  it("updated content style to have all supported styles defined", () => {
+    expect(
+      updateContentStyle({}, { padding: 1, backgroundColor: "red" })
+    ).toEqual({
+      paddingTop: 1,
+      paddingBottom: 1,
+      paddingLeft: 1,
+      paddingRight: 1,
+      backgroundColor: "red",
+    });
+    expect(updateContentStyle({}, { paddingHorizontal: 1 })).toEqual({
+      paddingTop: 0,
+      paddingBottom: 0,
+      paddingLeft: 1,
+      paddingRight: 1,
+    });
+    expect(updateContentStyle({}, { paddingVertical: 1 })).toEqual({
+      paddingTop: 1,
+      paddingBottom: 1,
+      paddingLeft: 0,
+      paddingRight: 0,
+    });
+    expect(
+      updateContentStyle({}, { paddingLeft: "1", paddingVertical: "1" })
+    ).toEqual({
+      paddingTop: 1,
+      paddingBottom: 1,
+      paddingLeft: 1,
+      paddingRight: 0,
+    });
+  });
+  it("computes correct layout manager insets", () => {
+    expect(
+      applyContentContainerInsetForLayoutManager(
+        { height: 0, width: 0 },
+        { padding: 1 },
+        false
+      )
+    ).toEqual({ height: 0, width: -2 });
+    expect(
+      applyContentContainerInsetForLayoutManager(
+        { height: 0, width: 0 },
+        { padding: 1 },
+        true
+      )
+    ).toEqual({ height: -2, width: 0 });
+    expect(
+      applyContentContainerInsetForLayoutManager(
+        { height: 0, width: 0 },
+        { paddingVertical: 1 },
+        true
+      )
+    ).toEqual({ height: -2, width: 0 });
+  });
+  it("calculated correct padding for scrollview content", () => {
+    expect(
+      getContentContainerPadding(
+        {
+          paddingLeft: 1,
+          paddingTop: 1,
+          paddingBottom: 1,
+          paddingRight: 1,
+          backgroundColor: "red",
+        },
+        true
+      )
+    ).toEqual({
+      paddingTop: 1,
+      paddingBottom: 1,
+      paddingLeft: undefined,
+      paddingRight: undefined,
+    });
+    expect(
+      getContentContainerPadding(
+        {
+          paddingLeft: 1,
+          paddingTop: 1,
+          paddingBottom: 1,
+          paddingRight: 1,
+          backgroundColor: "red",
+        },
+        false
+      )
+    ).toEqual({
+      paddingTop: undefined,
+      paddingBottom: undefined,
+      paddingLeft: 1,
+      paddingRight: 1,
+    });
+  });
+});

package/src/__tests__/FlashList.test.tsx

@@ -824,4 +824,36 @@ describe("FlashList", () => {
     expect(scrollToOffset).toBeCalledWith(1800, 1800, false, true);
     flashList.unmount();
   });
+  it("applies horizontal content container padding for vertical list", () => {
+    const flashList = mountFlashList({
+      numColumns: 4,
+      contentContainerStyle: { paddingHorizontal: 10 },
+    });
+    let hasLayoutItems = false;
+    flashList.instance.state.layoutProvider
+      .getLayoutManager()!
+      .getLayouts()
+      .forEach((layout) => {
+        hasLayoutItems = true;
+        expect(layout.width).toBe(95);
+      });
+    expect(hasLayoutItems).toBe(true);
+    flashList.unmount();
+  });
+  it("applies vertical content container padding for horizontal list", () => {
+    const flashList = mountFlashList({
+      horizontal: true,
+      contentContainerStyle: { paddingVertical: 10 },
+    });
+    let hasLayoutItems = false;
+    flashList.instance.state.layoutProvider
+      .getLayoutManager()!
+      .getLayouts()
+      .forEach((layout) => {
+        hasLayoutItems = true;
+        expect(layout.height).toBe(880);
+      });
+    expect(hasLayoutItems).toBe(true);
+    flashList.unmount();
+  });
 });

package/src/__tests__/GridLayoutProviderWithProps.test.ts

@@ -147,4 +147,33 @@ describe("GridLayoutProviderWithProps", () => {
     // horizontal list
     runCacheUpdateTest(true);
   });
+  it("expires if column count or padding changes", () => {
+    const flashList = mountFlashList();
+    const baseProps = flashList.instance.props;
+    expect(
+      flashList.instance.state.layoutProvider.updateProps({
+        ...baseProps,
+        contentContainerStyle: { paddingTop: 10 },
+      }).hasExpired
+    ).toBe(false);
+    expect(
+      flashList.instance.state.layoutProvider.updateProps({
+        ...baseProps,
+        contentContainerStyle: { paddingBottom: 10 },
+      }).hasExpired
+    ).toBe(false);
+    expect(
+      flashList.instance.state.layoutProvider.updateProps({
+        ...baseProps,
+        contentContainerStyle: { paddingLeft: 10 },
+      }).hasExpired
+    ).toBe(true);
+    flashList.instance.state.layoutProvider["_hasExpired"] = false;
+    expect(
+      flashList.instance.state.layoutProvider.updateProps({
+        ...baseProps,
+        numColumns: 2,
+      }).hasExpired
+    ).toBe(true);
+  });
 });

package/src/__tests__/MasonryFlashList.test.ts

@@ -26,6 +26,35 @@ describe("MasonryFlashList", () => {
     });
     masonryFlashList.unmount();
   });
+  it("invokes renderItem with columnIndex and columnSpan", () => {
+    const mockRenderItem = jest.fn(() => null);
+    const masonryFlashList = mountMasonryFlashList({
+      renderItem: mockRenderItem,
+      data: ["One", "Two", "Three"],
+      numColumns: 3,
+    });
+    expect(mockRenderItem).toHaveBeenCalledWith(
+      expect.objectContaining({
+        columnIndex: 0,
+        columnSpan: 1,
+      })
+    );
+
+    expect(mockRenderItem).toHaveBeenCalledWith(
+      expect.objectContaining({
+        columnIndex: 1,
+        columnSpan: 1,
+      })
+    );
+
+    expect(mockRenderItem).toHaveBeenCalledWith(
+      expect.objectContaining({
+        columnSpan: 1,
+        columnIndex: 2,
+      })
+    );
+    masonryFlashList.unmount();
+  });
   it("raised onLoad event only when first internal child mounts", () => {
     const onLoadMock = jest.fn();
     const ref = React.createRef<MasonryFlashListRef<string>>();
@@ -232,4 +261,32 @@ describe("MasonryFlashList", () => {
       )
     ).toBe(35339);
   });
+  it("applies horizontal content container padding to the list", () => {
+    const masonryFlashList = mountMasonryFlashList({
+      numColumns: 4,
+      contentContainerStyle: { paddingHorizontal: 10 },
+    });
+    expect(masonryFlashList.findAll(ProgressiveListView).length).toBe(5);
+    masonryFlashList.findAll(ProgressiveListView).forEach((list, index) => {
+      if (index === 0) {
+        expect(list.instance.getRenderedSize().width).toBe(400);
+        expect(list.instance.getRenderedSize().height).toBe(900);
+      } else {
+        expect(list.instance.getRenderedSize().width).toBe(95);
+        expect(list.instance.getRenderedSize().height).toBe(900);
+      }
+    });
+    masonryFlashList.unmount();
+  });
+  it("divides columns equally if no getColumnFlex is passed", () => {
+    const masonryFlashList = mountMasonryFlashList({
+      numColumns: 4,
+    });
+    const progressiveListView =
+      masonryFlashList.find(ProgressiveListView)!.instance;
+    expect(progressiveListView.getLayout(0).width).toBe(100);
+    expect(progressiveListView.getLayout(1).width).toBe(100);
+    expect(progressiveListView.getLayout(2).width).toBe(100);
+    expect(progressiveListView.getLayout(3).width).toBe(100);
+  });
 });

package/src/__tests__/helpers/mountMasonryFlashList.tsx

@@ -16,7 +16,12 @@ jest.mock("../../FlashList", () => {
     componentDidMount() {
       super.componentDidMount();
       this.rlvRef?._scrollComponent?._scrollViewRef?.props.onLayout({
-        nativeEvent: { layout: { height: 900, width: 400 } },
+        nativeEvent: {
+          layout: {
+            height: this.props.estimatedListSize?.height ?? 900,
+            width: this.props.estimatedListSize?.width ?? 400,
+          },
+        },
       });
     }
   }

package/src/errors/Warnings.ts

@@ -2,10 +2,7 @@ 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. In case of vertical lists horizontal padding is ignored and vice versa, if you need it apply padding to your items instead.",
-  styleUnsupportedPaddingType:
-    "FlashList will ignore horizontal padding in case of vertical lists and vertical padding if the list is horizontal. If you need to have it apply relevant padding to your items instead.",
+    "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.",

package/src/index.ts

@@ -34,6 +34,8 @@ export {
   MasonryFlashListScrollEvent,
   MasonryFlashListRef,
   MasonryListItem,
+  MasonryListRenderItem,
+  MasonryListRenderItemInfo,
 } from "./MasonryFlashList";
 export { JSFPSMonitor, JSFPSResult } from "./benchmark/JSFPSMonitor";
 export { autoScroll, Cancellable } from "./benchmark/AutoScrollHelper";

package/src/utils/ContentContainerUtils.ts

@@ -0,0 +1,92 @@
+import { ViewStyle } from "react-native";
+import { Dimension } from "recyclerlistview";
+
+import { ContentStyle } from "../FlashListProps";
+
+export interface ContentStyleExplicit {
+  paddingTop: number;
+  paddingBottom: number;
+  paddingLeft: number;
+  paddingRight: number;
+  backgroundColor?: string;
+}
+
+export const updateContentStyle = (
+  contentStyle: ContentStyle,
+  contentContainerStyleSource: ContentStyle | undefined
+): ContentStyleExplicit => {
+  const {
+    paddingTop,
+    paddingRight,
+    paddingBottom,
+    paddingLeft,
+    padding,
+    paddingVertical,
+    paddingHorizontal,
+    backgroundColor,
+  } = (contentContainerStyleSource ?? {}) as ViewStyle;
+  contentStyle.paddingLeft = Number(
+    paddingLeft || paddingHorizontal || padding || 0
+  );
+  contentStyle.paddingRight = Number(
+    paddingRight || paddingHorizontal || padding || 0
+  );
+  contentStyle.paddingTop = Number(
+    paddingTop || paddingVertical || padding || 0
+  );
+  contentStyle.paddingBottom = Number(
+    paddingBottom || paddingVertical || padding || 0
+  );
+  contentStyle.backgroundColor = backgroundColor;
+  return contentStyle as ContentStyleExplicit;
+};
+
+export const hasUnsupportedKeysInContentContainerStyle = (
+  contentContainerStyleSource: ViewStyle | undefined
+) => {
+  const {
+    paddingTop,
+    paddingRight,
+    paddingBottom,
+    paddingLeft,
+    padding,
+    paddingVertical,
+    paddingHorizontal,
+    backgroundColor,
+    ...rest
+  } = (contentContainerStyleSource ?? {}) as ViewStyle;
+  return Object.keys(rest).length > 0;
+};
+
+/** Applies padding corrections to given dimension. Mutates the dim object that was passed and returns it. */
+export const applyContentContainerInsetForLayoutManager = (
+  dim: Dimension,
+  contentContainerStyle: ViewStyle | undefined,
+  horizontal: boolean | undefined | null
+) => {
+  const contentStyle = updateContentStyle({}, contentContainerStyle);
+  if (horizontal) {
+    dim.height -= contentStyle.paddingTop + contentStyle.paddingBottom;
+  } else {
+    dim.width -= contentStyle.paddingLeft + contentStyle.paddingRight;
+  }
+  return dim;
+};
+
+/** Returns padding to be applied on content container and will ignore paddings that have already been handled. */
+export const getContentContainerPadding = (
+  contentStyle: ContentStyleExplicit,
+  horizontal: boolean | undefined | null
+) => {
+  if (horizontal) {
+    return {
+      paddingTop: contentStyle.paddingTop,
+      paddingBottom: contentStyle.paddingBottom,
+    };
+  } else {
+    return {
+      paddingLeft: contentStyle.paddingLeft,
+      paddingRight: contentStyle.paddingRight,
+    };
+  }
+};