@shopify/flash-list 1.0.1

package/src/benchmark/useBlankAreaTracker.ts

@@ -0,0 +1,117 @@
+import React, { useCallback, useRef } from "react";
+import { RecyclerListView, RecyclerListViewProps } from "recyclerlistview";
+
+import { BlankAreaEvent } from "../native/auto-layout/AutoLayoutView";
+import FlashList from "../FlashList";
+
+export interface BlankAreaTrackerResult {
+  /**
+   * Max blank area displayed
+   */
+  maxBlankArea: number;
+  /**
+   * Sum of all blank area values across all frames
+   */
+  cumulativeBlankArea: number;
+}
+export interface BlankAreaTrackerConfig {
+  /**
+   * When set to true the hook will also sum all negative blank area values.
+   * Blank area is negative when list is able to draw faster than the scroll speed.
+   */
+  sumNegativeValues?: boolean;
+  /**
+   * By default, the hook ignores blank events for 1s after the list load. This value can be changed using this parameter.
+   * Please note that this duration kicks in after the list has loaded and not after the first scroll.
+   */
+  startDelayInMs?: number;
+}
+
+/**
+ * Can be used to track visible blank area in production
+ * @param flashListRef Ref to the FlashList component
+ * @param onBlankAreaChange This event handler will be called when the blank area changes
+ * @param config additional configuration for the blank area tracker
+ * @returns blankAreaTrackerResult - maxBlankArea, cumulativeBlankArea this object is mutated and kept up to date. Also returns a callback that needs to be forwarded to FlashList.
+ */
+export function useBlankAreaTracker(
+  flashListRef: React.RefObject<FlashList<any>>,
+  onBlankAreaChange?: (value: BlankAreaTrackerResult) => void,
+  config?: BlankAreaTrackerConfig
+): [BlankAreaTrackerResult, (event: BlankAreaEvent) => void] {
+  const startDelay = config?.startDelayInMs ?? 1000;
+  const blankAreaResult = useRef({
+    maxBlankArea: 0,
+    cumulativeBlankArea: 0,
+  }).current;
+  const waitOperations = useRef({ inProgress: false, complete: false }).current;
+  const onBlankAreaChangeRef = useRef(onBlankAreaChange);
+  onBlankAreaChangeRef.current = onBlankAreaChange;
+
+  const blankAreaTracker = useCallback(
+    (event: BlankAreaEvent) => {
+      // we're ignoring some of the events that will be fired on list load
+      // initial events are fired on mount and thus, this won't lead to missing events during scroll
+      if (!waitOperations.complete && startDelay > 0) {
+        if (!waitOperations.inProgress) {
+          waitOperations.inProgress = true;
+          setTimeout(() => {
+            waitOperations.complete = true;
+          }, startDelay);
+        }
+        return;
+      }
+      const rlv = flashListRef.current?.recyclerlistview_unsafe;
+      const horizontal = Boolean(flashListRef.current?.props.horizontal);
+      if (rlv) {
+        processBlankAreaChange(
+          rlv,
+          horizontal,
+          blankAreaResult,
+          event,
+          onBlankAreaChangeRef.current,
+          config
+        );
+      }
+    },
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [flashListRef]
+  );
+  return [blankAreaResult, blankAreaTracker];
+}
+
+function processBlankAreaChange(
+  rlv: RecyclerListView<RecyclerListViewProps, any>,
+  horizontal: boolean,
+  blankAreaResult: BlankAreaTrackerResult,
+  event: BlankAreaEvent,
+  onBlankAreaChange?: (value: BlankAreaTrackerResult) => void,
+  config?: BlankAreaTrackerConfig
+) {
+  const listSize = horizontal
+    ? rlv.getRenderedSize().width
+    : rlv.getRenderedSize().height;
+  const contentSize = horizontal
+    ? rlv.getContentDimension().width
+    : rlv.getContentDimension().height;
+
+  // ignores blank events when there isn't enough content to fill the list
+  if (contentSize > listSize) {
+    const lastMaxBlankArea = blankAreaResult.maxBlankArea;
+    const lastCumulativeBlankArea = blankAreaResult.cumulativeBlankArea;
+    blankAreaResult.maxBlankArea = Math.max(
+      blankAreaResult.maxBlankArea,
+      event.blankArea,
+      0
+    );
+    blankAreaResult.cumulativeBlankArea += config?.sumNegativeValues
+      ? event.blankArea
+      : Math.max(event.blankArea, 0);
+    if (
+      lastCumulativeBlankArea !== blankAreaResult.cumulativeBlankArea ||
+      lastMaxBlankArea !== blankAreaResult.maxBlankArea
+    ) {
+      onBlankAreaChange?.(blankAreaResult);
+    }
+  }
+}

package/src/benchmark/useDataMultiplier.ts

@@ -0,0 +1,19 @@
+/**
+ * Increases the data size by duplicating it, it's kept in hook format so that in future we can add auto pagination support.
+ * If you're using this with FlatList then make sure you remove `keyExtractor` because this method might duplicate ids that might be in the data.
+ * @param data The data to duplicate
+ * @param count Final count of data to be returned from this hook
+ * @returns Multiplied data.
+ */
+export function useDataMultiplier<T>(data: T[], count: number): [T[]] {
+  const len = data.length;
+  const arr = new Array<T>(count);
+  let isObject = false;
+  if (typeof data[0] === "object") {
+    isObject = true;
+  }
+  for (let i = 0; i < count; i++) {
+    arr[i] = isObject ? { ...data[i % len] } : data[i % len];
+  }
+  return [arr];
+}

package/src/benchmark/useFlatListBenchmark.ts

@@ -0,0 +1,107 @@
+import { useEffect } from "react";
+import { FlatList } from "react-native";
+
+import { autoScroll, Cancellable } from "./AutoScrollHelper";
+import { JSFPSMonitor } from "./JSFPSMonitor";
+import {
+  BenchmarkParams,
+  BenchmarkResult,
+  getFormattedString,
+} from "./useBenchmark";
+
+export interface FlatListBenchmarkParams extends BenchmarkParams {
+  targetOffset: number;
+}
+
+/**
+ * Runs the benchmark on FlatList and calls the callback method with the result.
+ * Target offset is mandatory in params.
+ * It's recommended to remove pagination while running the benchmark. Removing the onEndReached callback is the easiest way to do that.
+ */
+export function useFlatListBenchmark(
+  flatListRef: React.RefObject<FlatList<any>>,
+  callback: (benchmarkResult: BenchmarkResult) => void,
+  params: FlatListBenchmarkParams
+) {
+  useEffect(() => {
+    const cancellable = new Cancellable();
+    if (flatListRef.current) {
+      if (!(Number(flatListRef.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(
+          flatListRef,
+          params.targetOffset,
+          cancellable,
+          params.speedMultiplier || 1
+        );
+      }
+      const jsProfilerResponse = jsFPSMonitor.stopAndGetData();
+      const result: BenchmarkResult = {
+        js: jsProfilerResponse,
+        suggestions: [],
+        interrupted: cancellable.isCancelled(),
+      };
+      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 [];
+}
+
+/**
+ * Scrolls to the target offset and then back to 0
+ */
+async function runScrollBenchmark(
+  flatListRef: React.RefObject<FlatList<any> | null | undefined>,
+  targetOffset: number,
+  cancellable: Cancellable,
+  scrollSpeedMultiplier: number
+): Promise<void> {
+  if (flatListRef.current) {
+    const horizontal = flatListRef.current.props.horizontal;
+
+    const fromX = 0;
+    const fromY = 0;
+    const toX = horizontal ? targetOffset : 0;
+    const toY = horizontal ? 0 : targetOffset;
+
+    const scrollNow = (x: number, y: number) => {
+      flatListRef.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
+    );
+  }
+}

package/src/errors/CustomError.ts

@@ -0,0 +1,10 @@
+export default class CustomError extends Error {
+  constructor(exception: Exception) {
+    super(`${exception.type}: ${exception.message}`);
+    this.name = exception.type;
+  }
+}
+export interface Exception {
+  type: string;
+  message: string;
+}

package/src/errors/ExceptionList.ts

@@ -0,0 +1,23 @@
+const ExceptionList = {
+  refreshBooleanMissing: {
+    message:
+      "`refreshing` prop must be set as a boolean in order to use `onRefresh`, but got `undefined`.",
+    type: "InvariantViolation",
+  },
+  stickyWhileHorizontalNotSupported: {
+    message:
+      "sticky headers are not supported when list is in horizontal mode. Remove `stickyHeaderIndices` prop.",
+    type: "NotSupportedException",
+  },
+  columnsWhileHorizontalNotSupported: {
+    message:
+      "numColumns is not supported when list is in horizontal mode. Please remove or set numColumns to 1.",
+    type: "NotSupportedException",
+  },
+  multipleViewabilityThresholdTypesNotSupported: {
+    message:
+      "You can set exactly one of itemVisiblePercentThreshold or viewAreaCoveragePercentThreshold. Specifying both is not supported.",
+    type: "MultipleViewabilityThresholdTypesException",
+  },
+};
+export default ExceptionList;

package/src/errors/Warnings.ts

@@ -0,0 +1,18 @@
+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.",
+  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.",
+  missingKeyExtractor:
+    "FlashList requires a keyExtractor prop to be defined when animating elements. Without it, the animations will not run as expected.",
+  estimatedItemSizeMissingWarning:
+    "estimatedItemSize FlashList prop is not defined - based on current configuration you can set it to @size to optimize list performance. " +
+    "Refer to FlashList documentation for more details.",
+};
+export default WarningList;

package/src/index.ts

@@ -0,0 +1,32 @@
+export { default as FlashList } from "./FlashList";
+export {
+  FlashListProps,
+  ContentStyle,
+  ListRenderItem,
+  ListRenderItemInfo,
+} from "./FlashListProps";
+export { default as AnimatedFlashList } from "./AnimatedFlashList";
+export {
+  useOnNativeBlankAreaEvents,
+  BlankAreaEventHandler,
+  BlankAreaEvent,
+} from "./native/auto-layout/AutoLayoutView";
+export {
+  useBenchmark,
+  BenchmarkParams,
+  BenchmarkResult,
+} from "./benchmark/useBenchmark";
+export { useDataMultiplier } from "./benchmark/useDataMultiplier";
+export {
+  useFlatListBenchmark,
+  FlatListBenchmarkParams,
+} from "./benchmark/useFlatListBenchmark";
+export {
+  useBlankAreaTracker,
+  BlankAreaTrackerResult,
+  BlankAreaTrackerConfig,
+} from "./benchmark/useBlankAreaTracker";
+export { JSFPSMonitor, JSFPSResult } from "./benchmark/JSFPSMonitor";
+export { autoScroll, Cancellable } from "./benchmark/AutoScrollHelper";
+export { default as ViewToken } from "./viewability/ViewToken";
+export { default as CellContainer } from "./native/cell-container/CellContainer";

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

@@ -0,0 +1,72 @@
+import React, { useEffect } 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 {
+  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.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.web.ts

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

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

@@ -0,0 +1,14 @@
+export interface OnBlankAreaEvent {
+  nativeEvent: {
+    offsetStart: number;
+    offsetEnd: number;
+  };
+}
+
+type OnBlankAreaEventHandler = (event: OnBlankAreaEvent) => void;
+
+export interface AutoLayoutViewNativeComponentProps {
+  onBlankAreaEvent: OnBlankAreaEventHandler;
+  enableInstrumentation: boolean;
+  disableAutoLayout?: boolean;
+}

package/src/native/cell-container/CellContainer.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.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/utils/AverageWindow.ts

@@ -0,0 +1,49 @@
+/**
+ * Helper class to calculate running average of the most recent n values
+ */
+export class AverageWindow {
+  private currentAverage: number;
+  private currentCount: number;
+  private inputValues: (number | undefined)[];
+  private nextIndex: number = 0;
+  constructor(size: number, startValue?: number) {
+    this.inputValues = new Array<number>(Math.max(1, size));
+    this.currentAverage = startValue ?? 0;
+    this.currentCount = startValue === undefined ? 0 : 1;
+    this.nextIndex = this.currentCount;
+    this.inputValues[0] = startValue;
+  }
+
+  /**
+   * Can be used to get the current average value
+   */
+  public get currentValue(): number {
+    return this.currentAverage;
+  }
+
+  /**
+   *
+   * @param value Add new value to the average window and updated current average
+   */
+  public addValue(value: number): void {
+    const target = this.getNextIndex();
+    const oldValue = this.inputValues[target];
+    const newCount =
+      oldValue === undefined ? this.currentCount + 1 : this.currentCount;
+
+    this.inputValues[target] = value;
+
+    this.currentAverage =
+      this.currentAverage * (this.currentCount / newCount) +
+      (value - (oldValue ?? 0)) / newCount;
+
+    this.currentCount = newCount;
+  }
+
+  private getNextIndex(): number {
+    // starts from 0 once we reach end of the array
+    const newTarget = this.nextIndex;
+    this.nextIndex = (this.nextIndex + 1) % this.inputValues.length;
+    return newTarget;
+  }
+}

package/src/utils/PlatformHelper.ts

@@ -0,0 +1,16 @@
+import { BaseItemAnimator } from "recyclerlistview";
+
+const PlatformConfig = {
+  defaultDrawDistance: 250,
+};
+const getCellContainerPlatformStyles = (
+  inverted: boolean,
+  parentProps: { x: number; y: number }
+): { transform: string; WebkitTransform: string } | undefined => {
+  return undefined;
+};
+
+const getItemAnimator = (): BaseItemAnimator | undefined => {
+  return undefined;
+};
+export { PlatformConfig, getCellContainerPlatformStyles, getItemAnimator };

package/src/utils/PlatformHelper.web.ts

@@ -0,0 +1,20 @@
+import { BaseItemAnimator } from "recyclerlistview";
+import { DefaultJSItemAnimator } from "recyclerlistview/dist/reactnative/platform/reactnative/itemanimators/defaultjsanimator/DefaultJSItemAnimator";
+
+const PlatformConfig = {
+  defaultDrawDistance: 2000,
+};
+const getCellContainerPlatformStyles = (
+  inverted: boolean,
+  parentProps: { x: number; y: number }
+): { transform: string; WebkitTransform: string } | undefined => {
+  const transformValue = `translate(${parentProps.x}px,${parentProps.y}px)${
+    inverted ? ` scaleY(-1)` : ``
+  }`;
+  return { transform: transformValue, WebkitTransform: transformValue };
+};
+
+const getItemAnimator = (): BaseItemAnimator | undefined => {
+  return new DefaultJSItemAnimator();
+};
+export { PlatformConfig, getCellContainerPlatformStyles, getItemAnimator };

package/src/viewability/ViewToken.ts

@@ -0,0 +1,7 @@
+export default interface ViewToken {
+  item: any;
+  key: string;
+  index: number | null;
+  isViewable: boolean;
+  timestamp: number;
+}