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

package/src/index.ts

@@ -1,17 +1,25 @@
-// Keep this unmodified for TS type checking
-import { isNewArch } from "./isNewArch";
-import { ErrorMessages } from "./errors/ErrorMessages";
+// eslint-disable-next-line import/no-named-default
+import { default as OriginalFlashList } from "./FlashList";
+import { isNewCoreEnabled } from "./enableNewCore";
+import { RecyclerView } from "./recyclerview/RecyclerView";
 
-export { FlashList } from "./FlashList";
+// Keep this unmodified for TS type checking
+export { default as FlashList } from "./FlashList";
 export { FlashListRef } from "./FlashListRef";
 export {
   FlashListProps,
+  ContentStyle,
   ListRenderItem,
   ListRenderItemInfo,
   RenderTarget,
   RenderTargetOptions,
 } from "./FlashListProps";
 export { default as AnimatedFlashList } from "./AnimatedFlashList";
+export {
+  useOnNativeBlankAreaEvents,
+  BlankAreaEventHandler,
+  BlankAreaEvent,
+} from "./native/auto-layout/AutoLayoutView";
 export {
   useBenchmark,
   BenchmarkParams,
@@ -22,18 +30,46 @@ export {
   useFlatListBenchmark,
   FlatListBenchmarkParams,
 } from "./benchmark/useFlatListBenchmark";
+export {
+  useBlankAreaTracker,
+  BlankAreaTrackerResult,
+  BlankAreaTrackerConfig,
+} from "./benchmark/useBlankAreaTracker";
+export {
+  MasonryFlashList,
+  MasonryFlashListProps,
+  MasonryFlashListScrollEvent,
+  MasonryFlashListRef,
+  MasonryListItem,
+  MasonryListRenderItem,
+  MasonryListRenderItemInfo,
+} from "./MasonryFlashList";
 export { useLayoutState } from "./recyclerview/hooks/useLayoutState";
 export { useRecyclingState } from "./recyclerview/hooks/useRecyclingState";
 export { useMappingHelper } from "./recyclerview/hooks/useMappingHelper";
 export { JSFPSMonitor, JSFPSResult } from "./benchmark/JSFPSMonitor";
 export { autoScroll, Cancellable } from "./benchmark/AutoScrollHelper";
-export { default as ViewToken } from "./recyclerview/viewability/ViewToken";
+export { default as ViewToken } from "./viewability/ViewToken";
+export { default as CellContainer } from "./native/cell-container/CellContainer";
+export { RecyclerView } from "./recyclerview/RecyclerView";
+export { RecyclerViewProps } from "./recyclerview/RecyclerViewProps";
 export { useFlashListContext } from "./recyclerview/RecyclerViewContextProvider";
 export {
   LayoutCommitObserver,
   LayoutCommitObserverProps,
 } from "./recyclerview/LayoutCommitObserver";
 
-if (!isNewArch()) {
-  throw new Error(ErrorMessages.flashListV2OnlySupportsNewArchitecture);
+// @ts-ignore - This is ignored by TypeScript but will be present in the compiled JS
+// In the compiled JS, this will override the previous FlashList export with a conditional one
+if (
+  typeof module !== "undefined" &&
+  module.exports &&
+  process?.env?.NODE_ENV !== "test"
+) {
+  Object.defineProperty(module.exports, "FlashList", {
+    get() {
+      return isNewCoreEnabled() ? RecyclerView : OriginalFlashList;
+    },
+    configurable: true,
+  });
 }

package/src/native/auto-layout/AutoLayoutView.tsx

@@ -0,0 +1,73 @@
+import React, { useEffect, ReactNode } from "react";
+import { LayoutChangeEvent } from "react-native";
+
+import AutoLayoutViewNativeComponent from "./AutoLayoutViewNativeComponent";
+import { OnBlankAreaEvent } from "./AutoLayoutViewNativeComponentProps";
+
+export type BlankAreaEventHandler = (blankAreaEvent: BlankAreaEvent) => void;
+const listeners: BlankAreaEventHandler[] = [];
+
+export const useOnNativeBlankAreaEvents = (
+  onBlankAreaEvent: (blankAreaEvent: BlankAreaEvent) => void
+) => {
+  useEffect(() => {
+    listeners.push(onBlankAreaEvent);
+    return () => {
+      listeners.filter((callback) => callback !== onBlankAreaEvent);
+    };
+  }, [onBlankAreaEvent]);
+};
+
+export interface BlankAreaEvent {
+  offsetStart: number;
+  offsetEnd: number;
+  blankArea: number;
+}
+
+export interface AutoLayoutViewProps {
+  children?: ReactNode;
+  onBlankAreaEvent?: BlankAreaEventHandler;
+  onLayout?: (event: LayoutChangeEvent) => void;
+  disableAutoLayout?: boolean;
+}
+
+class AutoLayoutView extends React.Component<AutoLayoutViewProps> {
+  private onBlankAreaEventCallback = ({
+    nativeEvent,
+  }: OnBlankAreaEvent): void => {
+    const blankArea = Math.max(nativeEvent.offsetStart, nativeEvent.offsetEnd);
+    const blankEventValue = {
+      blankArea,
+      offsetStart: nativeEvent.offsetStart,
+      offsetEnd: nativeEvent.offsetEnd,
+    };
+    this.broadcastBlankEvent(blankEventValue);
+    if (this.props.onBlankAreaEvent) {
+      this.props.onBlankAreaEvent(blankEventValue);
+    }
+  };
+
+  private broadcastBlankEvent(value: BlankAreaEvent) {
+    const len = listeners.length;
+    for (let i = 0; i < len; i++) {
+      listeners[i](value);
+    }
+  }
+
+  render() {
+    return (
+      <AutoLayoutViewNativeComponent
+        {...this.props}
+        onBlankAreaEvent={this.onBlankAreaEventCallback}
+        enableInstrumentation={
+          listeners.length !== 0 || Boolean(this.props.onBlankAreaEvent)
+        }
+        disableAutoLayout={this.props.disableAutoLayout}
+      >
+        {this.props.children}
+      </AutoLayoutViewNativeComponent>
+    );
+  }
+}
+
+export default AutoLayoutView;

package/src/native/auto-layout/AutoLayoutViewNativeComponent.android.ts

@@ -0,0 +1,7 @@
+import { requireNativeComponent } from "react-native";
+
+import { AutoLayoutViewNativeComponentProps } from "./AutoLayoutViewNativeComponentProps";
+
+const AutoLayoutViewNativeComponent =
+  requireNativeComponent<AutoLayoutViewNativeComponentProps>("AutoLayoutView");
+export default AutoLayoutViewNativeComponent;

package/src/native/auto-layout/AutoLayoutViewNativeComponent.ios.ts

@@ -0,0 +1,7 @@
+import { requireNativeComponent } from "react-native";
+
+import { AutoLayoutViewNativeComponentProps } from "./AutoLayoutViewNativeComponentProps";
+
+const AutoLayoutViewNativeComponent =
+  requireNativeComponent<AutoLayoutViewNativeComponentProps>("AutoLayoutView");
+export default AutoLayoutViewNativeComponent;

package/src/native/auto-layout/AutoLayoutViewNativeComponent.ts

@@ -0,0 +1,7 @@
+import { HostComponent, View } from "react-native";
+
+import { AutoLayoutViewNativeComponentProps } from "./AutoLayoutViewNativeComponentProps";
+
+const AutoLayoutViewNativeComponent =
+  View as any as HostComponent<AutoLayoutViewNativeComponentProps>;
+export default AutoLayoutViewNativeComponent;

package/src/native/auto-layout/AutoLayoutViewNativeComponentProps.ts

@@ -0,0 +1,17 @@
+import { ReactNode } from "react";
+
+export interface OnBlankAreaEvent {
+  nativeEvent: {
+    offsetStart: number;
+    offsetEnd: number;
+  };
+}
+
+type OnBlankAreaEventHandler = (event: OnBlankAreaEvent) => void;
+
+export interface AutoLayoutViewNativeComponentProps {
+  children?: ReactNode;
+  onBlankAreaEvent: OnBlankAreaEventHandler;
+  enableInstrumentation: boolean;
+  disableAutoLayout?: boolean;
+}

package/src/native/cell-container/CellContainer.android.ts

@@ -0,0 +1,7 @@
+import { requireNativeComponent } from "react-native";
+
+/**
+ * Behaves as a regular `View` with an extra `index` prop that is saved in the native layer.
+ */
+const CellContainer = requireNativeComponent("CellContainer");
+export default CellContainer;

package/src/native/cell-container/CellContainer.ios.ts

@@ -0,0 +1,7 @@
+import { requireNativeComponent } from "react-native";
+
+/**
+ * Behaves as a regular `View` with an extra `index` prop that is saved in the native layer.
+ */
+const CellContainer = requireNativeComponent("CellContainer");
+export default CellContainer;

package/src/native/cell-container/CellContainer.tsx

@@ -0,0 +1,14 @@
+import React from "react";
+import { View, ViewProps } from "react-native";
+
+export interface CellContainerProps extends ViewProps {
+  index: number;
+}
+
+const CellContainer = React.forwardRef(
+  (props: CellContainerProps, ref: any) => {
+    return <View ref={ref} {...props} />;
+  }
+);
+CellContainer.displayName = "CellContainer";
+export default CellContainer;

package/src/native/cell-container/CellContainer.web.tsx

@@ -0,0 +1,9 @@
+import React from "react";
+/**
+ * On web we use a view instead of cell container till we build native web implementations
+ */
+const CellContainer = React.forwardRef((props: any, ref) => {
+  return <div ref={ref} {...props} />;
+});
+CellContainer.displayName = "CellContainer";
+export default CellContainer;

package/src/native/config/PlatformHelper.android.ts

@@ -1,7 +1,31 @@
+import { BaseItemAnimator } from "recyclerlistview";
+
 const PlatformConfig = {
   defaultDrawDistance: 250,
   supportsOffsetCorrection: true,
   trackAverageRenderTimeForOffsetProjection: true,
+  // Using rotate instead of scaleY on Android to avoid performance issues. Issue: https://github.com/Shopify/flash-list/issues/751
+  invertedTransformStyle: { transform: [{ rotate: "180deg" }] },
+  invertedTransformStyleHorizontal: { transform: [{ rotate: "180deg" }] },
+};
+const getCellContainerPlatformStyles = (
+  inverted: boolean,
+  parentProps: { x: number; y: number; isHorizontal?: boolean }
+): { transform: string; WebkitTransform: string } | undefined => {
+  return undefined;
+};
+
+const getItemAnimator = (): BaseItemAnimator | undefined => {
+  return undefined;
 };
 
-export { PlatformConfig };
+const getFooterContainer = (): React.ComponentClass | undefined => {
+  return undefined;
+};
+
+export {
+  PlatformConfig,
+  getCellContainerPlatformStyles,
+  getItemAnimator,
+  getFooterContainer,
+};

package/src/native/config/PlatformHelper.ios.ts

@@ -1,7 +1,30 @@
+import { BaseItemAnimator } from "recyclerlistview";
+
 const PlatformConfig = {
   defaultDrawDistance: 250,
   supportsOffsetCorrection: true,
   trackAverageRenderTimeForOffsetProjection: false,
+  invertedTransformStyle: { transform: [{ scaleY: -1 }] },
+  invertedTransformStyleHorizontal: { transform: [{ scaleX: -1 }] },
+};
+const getCellContainerPlatformStyles = (
+  inverted: boolean,
+  parentProps: { x: number; y: number; isHorizontal?: boolean }
+): { transform: string; WebkitTransform: string } | undefined => {
+  return undefined;
+};
+
+const getItemAnimator = (): BaseItemAnimator | undefined => {
+  return undefined;
 };
 
-export { PlatformConfig };
+const getFooterContainer = (): React.ComponentClass | undefined => {
+  return undefined;
+};
+
+export {
+  PlatformConfig,
+  getCellContainerPlatformStyles,
+  getItemAnimator,
+  getFooterContainer,
+};

package/src/native/config/PlatformHelper.ts

@@ -1,7 +1,31 @@
+import { BaseItemAnimator } from "recyclerlistview";
+import { DefaultJSItemAnimator } from "recyclerlistview/dist/reactnative/platform/reactnative/itemanimators/defaultjsanimator/DefaultJSItemAnimator";
+
 const PlatformConfig = {
   defaultDrawDistance: 250,
   supportsOffsetCorrection: false,
   trackAverageRenderTimeForOffsetProjection: false,
+  invertedTransformStyle: { transform: [{ scaleY: -1 }] },
+  invertedTransformStyleHorizontal: { transform: [{ scaleX: -1 }] },
+};
+const getCellContainerPlatformStyles = (
+  inverted: boolean,
+  parentProps: { x: number; y: number; isHorizontal?: boolean }
+): { transform: string; WebkitTransform: string } | undefined => {
+  return undefined;
+};
+
+const getItemAnimator = (): BaseItemAnimator | undefined => {
+  return new DefaultJSItemAnimator();
 };
 
-export { PlatformConfig };
+const getFooterContainer = (): React.ComponentClass | undefined => {
+  return undefined;
+};
+
+export {
+  PlatformConfig,
+  getCellContainerPlatformStyles,
+  getItemAnimator,
+  getFooterContainer,
+};

package/src/native/config/PlatformHelper.web.ts

@@ -1,7 +1,36 @@
+import React from "react";
+import { View } from "react-native";
+import { BaseItemAnimator } from "recyclerlistview";
+import { DefaultJSItemAnimator } from "recyclerlistview/dist/reactnative/platform/reactnative/itemanimators/defaultjsanimator/DefaultJSItemAnimator";
+
 const PlatformConfig = {
   defaultDrawDistance: 500,
   supportsOffsetCorrection: false,
   trackAverageRenderTimeForOffsetProjection: false,
+  invertedTransformStyle: { transform: [{ scaleY: -1 }] },
+  invertedTransformStyleHorizontal: { transform: [{ scaleX: -1 }] },
+};
+const getCellContainerPlatformStyles = (
+  inverted: boolean,
+  parentProps: { x: number; y: number; isHorizontal?: boolean }
+): { transform: string; WebkitTransform: string } | undefined => {
+  const transformValue = `translate(${parentProps.x}px,${parentProps.y}px)${
+    inverted ? ` ${parentProps.isHorizontal ? `scaleX` : `scaleY`}(-1)` : ``
+  }`;
+  return { transform: transformValue, WebkitTransform: transformValue };
+};
+
+const getItemAnimator = (): BaseItemAnimator | undefined => {
+  return new DefaultJSItemAnimator();
 };
 
-export { PlatformConfig };
+const getFooterContainer = (): React.ComponentClass | undefined => {
+  return View;
+};
+
+export {
+  PlatformConfig,
+  getCellContainerPlatformStyles,
+  getItemAnimator,
+  getFooterContainer,
+};

package/src/recyclerview/RecyclerView.tsx

@@ -20,7 +20,6 @@ import {
 } from "react-native";
 
 import { FlashListRef } from "../FlashListRef";
-import { ErrorMessages } from "../errors/ErrorMessages";
 
 import { RVDimension } from "./layout-managers/LayoutManager";
 import {
@@ -209,8 +208,18 @@ const RecyclerViewComponent = <T,>(
       return { index, dimensions: layout };
     });
 
+    const hasExceededMaxRendersWithoutCommit =
+      renderTimeTracker.hasExceededMaxRendersWithoutCommit();
+
+    if (hasExceededMaxRendersWithoutCommit) {
+      console.warn(
+        "FlashList: Exceeded max renders without commit, check for duplicate keys or parent being a ScrollView"
+      );
+    }
+
     if (
-      recyclerViewManager.modifyChildrenLayout(layoutInfo, data?.length ?? 0)
+      recyclerViewManager.modifyChildrenLayout(layoutInfo, data?.length ?? 0) &&
+      !hasExceededMaxRendersWithoutCommit
     ) {
       // Trigger re-render if layout modifications were made
       setRenderId((prev) => prev + 1);
@@ -385,9 +394,6 @@ const RecyclerViewComponent = <T,>(
       stickyHeaderIndices &&
       stickyHeaderIndices.length > 0
     ) {
-      if (horizontal) {
-        throw new Error(ErrorMessages.stickyHeadersNotSupportedForHorizontal);
-      }
       return (
         <StickyHeaders
           stickyHeaderIndices={stickyHeaderIndices}
@@ -406,7 +412,6 @@ const RecyclerViewComponent = <T,>(
     stickyHeaderIndices,
     renderItem,
     scrollY,
-    horizontal,
     recyclerViewManager,
     extraData,
   ]);

package/src/recyclerview/RecyclerViewManager.ts

@@ -1,6 +1,5 @@
-import { ErrorMessages } from "../errors/ErrorMessages";
+import ViewabilityManager from "../viewability/ViewabilityManager";
 
-import ViewabilityManager from "./viewability/ViewabilityManager";
 import { ConsecutiveNumbers } from "./helpers/ConsecutiveNumbers";
 import { RVGridLayoutManagerImpl } from "./layout-managers/GridLayoutManager";
 import {
@@ -132,7 +131,9 @@ export class RecyclerViewManager<T> {
 
   getLayout(index: number) {
     if (!this.layoutManager) {
-      throw new Error(ErrorMessages.layoutManagerNotInitializedLayoutInfo);
+      throw new Error(
+        "LayoutManager is not initialized, layout info is unavailable"
+      );
     }
     return this.layoutManager.getLayout(index);
   }
@@ -151,7 +152,9 @@ export class RecyclerViewManager<T> {
   // Doesn't include header / foot etc
   getChildContainerDimensions() {
     if (!this.layoutManager) {
-      throw new Error(ErrorMessages.layoutManagerNotInitializedChildContainer);
+      throw new Error(
+        "LayoutManager is not initialized, child container layout is unavailable"
+      );
     }
     return this.layoutManager.getLayoutSize();
   }
@@ -162,7 +165,9 @@ export class RecyclerViewManager<T> {
 
   getWindowSize() {
     if (!this.layoutManager) {
-      throw new Error(ErrorMessages.layoutManagerNotInitializedWindowSize);
+      throw new Error(
+        "LayoutManager is not initialized, window size is unavailable"
+      );
     }
     return this.layoutManager.getWindowsSize();
   }
@@ -206,7 +211,9 @@ export class RecyclerViewManager<T> {
       Boolean(this.layoutManager?.isHorizontal()) !==
         Boolean(this.propsRef.horizontal)
     ) {
-      throw new Error(ErrorMessages.horizontalPropCannotBeToggled);
+      throw new Error(
+        "Horizontal prop cannot be toggled, you can use a key on FlashList to recreate it."
+      );
     }
     if (this._isLayoutManagerDirty) {
       this.layoutManager = undefined;
@@ -238,7 +245,9 @@ export class RecyclerViewManager<T> {
 
   computeVisibleIndices() {
     if (!this.layoutManager) {
-      throw new Error(ErrorMessages.layoutManagerNotInitializedVisibleIndices);
+      throw new Error(
+        "LayoutManager is not initialized, visible indices are not unavailable"
+      );
     }
     return this.engagedIndicesTracker.computeVisibleIndices(this.layoutManager);
   }
@@ -351,10 +360,10 @@ export class RecyclerViewManager<T> {
   private getLayoutManagerClass() {
     // throw errors for incompatible props
     if (this.propsRef.masonry && this.propsRef.horizontal) {
-      throw new Error(ErrorMessages.masonryAndHorizontalIncompatible);
+      throw new Error("Masonry and horizontal props are incompatible");
     }
     if (this.numColumns > 1 && this.propsRef.horizontal) {
-      throw new Error(ErrorMessages.numColumnsAndHorizontalIncompatible);
+      throw new Error("numColumns and horizontal props are incompatible");
     }
     return this.propsRef.masonry
       ? RVMasonryLayoutManagerImpl

package/src/recyclerview/RecyclerViewProps.ts

@@ -1 +1,11 @@
-export { FlashListProps as RecyclerViewProps } from "../FlashListProps";
+import { ScrollViewProps } from "react-native";
+
+import { FlashListProps } from "../FlashListProps";
+
+export interface RecyclerViewProps<TItem>
+  extends Omit<FlashListProps<TItem>, "contentContainerStyle"> {
+  /**
+   * Style for the RecyclerView's parent container.
+   */
+  contentContainerStyle?: ScrollViewProps["contentContainerStyle"];
+}

package/src/recyclerview/helpers/RenderTimeTracker.ts

@@ -6,8 +6,11 @@ export class RenderTimeTracker {
   private lastTimerStartedAt = -1;
   private maxRenderTime = 32; // TODO: Improve this even more
   private defaultRenderTime = 16;
+  private rendersWithoutCommit = 0;
+  private maxRendersWithoutCommit = 40;
 
   startTracking() {
+    this.rendersWithoutCommit++;
     if (!PlatformConfig.trackAverageRenderTimeForOffsetProjection) {
       return;
     }
@@ -17,6 +20,7 @@ export class RenderTimeTracker {
   }
 
   markRenderComplete() {
+    this.rendersWithoutCommit = 0;
     if (!PlatformConfig.trackAverageRenderTimeForOffsetProjection) {
       return;
     }
@@ -26,6 +30,10 @@ export class RenderTimeTracker {
     }
   }
 
+  hasExceededMaxRendersWithoutCommit() {
+    return this.rendersWithoutCommit >= this.maxRendersWithoutCommit;
+  }
+
   getRawValue() {
     return this.renderTimeAvgWindow.currentValue;
   }

package/src/recyclerview/hooks/useRecyclerViewController.tsx

@@ -21,7 +21,6 @@ import { adjustOffsetForRTL } from "../utils/adjustOffsetForRTL";
 import { RVLayout } from "../layout-managers/LayoutManager";
 import { ScrollAnchorRef } from "../components/ScrollAnchor";
 import { PlatformConfig } from "../../native/config/PlatformHelper";
-import { WarningMessages } from "../../errors/WarningMessages";
 
 import { useUnmountFlag } from "./useUnmountFlag";
 import { useUnmountAwareTimeout } from "./useUnmountAwareCallbacks";
@@ -549,9 +548,6 @@ export function useRecyclerViewController<T>(
        * Disables item recycling in preparation for layout animations.
        */
       prepareForLayoutAnimationRender: () => {
-        if (!recyclerViewManager.props.keyExtractor) {
-          console.warn(WarningMessages.keyExtractorNotDefinedForAnimation);
-        }
         recyclerViewManager.animationOptimizationsEnabled = true;
       },
     };

package/src/recyclerview/layout-managers/LayoutManager.ts

@@ -7,7 +7,6 @@ import {
   findLastVisibleIndex,
 } from "../utils/findVisibleIndex";
 import { areDimensionsNotEqual } from "../utils/measureLayout";
-import { ErrorMessages } from "../../errors/ErrorMessages";
 
 /**
  * Base abstract class for layout managers in the recycler view system.
@@ -225,7 +224,7 @@ export abstract class RVLayoutManager {
    */
   getLayout(index: number): RVLayout {
     if (index >= this.layouts.length) {
-      throw new Error(ErrorMessages.indexOutOfBounds);
+      throw new Error("index out of bounds, not enough layouts");
     }
     let layout = this.layouts[index];
     if (!layout) {

package/src/specs/AutoLayoutNativeComponent.ts

@@ -0,0 +1,24 @@
+import codegenNativeComponent from "react-native/Libraries/Utilities/codegenNativeComponent";
+import type { ViewProps } from "react-native";
+import type {
+  Int32,
+  Double,
+  DirectEventHandler,
+} from "react-native/Libraries/Types/CodegenTypes";
+
+type BlankAreaEvent = Readonly<{
+  offsetStart: Int32;
+  offsetEnd: Int32;
+}>;
+
+interface NativeProps extends ViewProps {
+  horizontal?: boolean;
+  scrollOffset?: Double;
+  windowSize?: Double;
+  renderAheadOffset?: Double;
+  enableInstrumentation?: boolean;
+  disableAutoLayout?: boolean;
+  onBlankAreaEvent?: DirectEventHandler<BlankAreaEvent>;
+}
+
+export default codegenNativeComponent<NativeProps>("AutoLayoutView");

package/src/specs/CellContainerNativeComponent.ts

@@ -0,0 +1,9 @@
+import codegenNativeComponent from "react-native/Libraries/Utilities/codegenNativeComponent";
+import type { Int32 } from "react-native/Libraries/Types/CodegenTypes";
+import type { ViewProps } from "react-native";
+
+interface NativeProps extends ViewProps {
+  index?: Int32;
+}
+
+export default codegenNativeComponent<NativeProps>("CellContainer");