@react-native-ohos/flash-list 1.6.4-rc.1

package/src/benchmark/JSFPSMonitor.ts

@@ -0,0 +1,74 @@
+import { roundToDecimalPlaces } from "./roundToDecimalPlaces";
+
+/**
+ * Can be used to monitor JS thread performance
+ * Use startTracking() and stopAndGetData() to start and stop tracking
+ */
+export class JSFPSMonitor {
+  private startTime = 0;
+  private frameCount = 0;
+  private timeWindow = {
+    frameCount: 0,
+    startTime: 0,
+  };
+
+  private minFPS = Number.MAX_SAFE_INTEGER;
+  private maxFPS = 0;
+  private averageFPS = 0;
+
+  private clearAnimationNumber = 0;
+
+  private measureLoop() {
+    // This looks weird but I'm avoiding a new closure
+    this.clearAnimationNumber = requestAnimationFrame(this.updateLoopCompute);
+  }
+
+  private updateLoopCompute = () => {
+    this.frameCount++;
+    const elapsedTime = (Date.now() - this.startTime) / 1000;
+    this.averageFPS = elapsedTime > 0 ? this.frameCount / elapsedTime : 0;
+
+    this.timeWindow.frameCount++;
+    const timeWindowElapsedTime =
+      (Date.now() - this.timeWindow.startTime) / 1000;
+    if (timeWindowElapsedTime >= 1) {
+      const timeWindowAverageFPS =
+        this.timeWindow.frameCount / timeWindowElapsedTime;
+      this.minFPS = Math.min(this.minFPS, timeWindowAverageFPS);
+      this.maxFPS = Math.max(this.maxFPS, timeWindowAverageFPS);
+      this.timeWindow.frameCount = 0;
+      this.timeWindow.startTime = Date.now();
+    }
+    this.measureLoop();
+  };
+
+  public startTracking() {
+    if (this.startTime !== 0) {
+      throw new Error(
+        "This FPS Monitor has already been run, please create a new instance"
+      );
+    }
+    this.startTime = Date.now();
+    this.timeWindow.startTime = Date.now();
+    this.measureLoop();
+  }
+
+  public stopAndGetData(): JSFPSResult {
+    cancelAnimationFrame(this.clearAnimationNumber);
+    if (this.minFPS === Number.MAX_SAFE_INTEGER) {
+      this.minFPS = this.averageFPS;
+      this.maxFPS = this.averageFPS;
+    }
+    return {
+      minFPS: roundToDecimalPlaces(this.minFPS, 1),
+      maxFPS: roundToDecimalPlaces(this.maxFPS, 1),
+      averageFPS: roundToDecimalPlaces(this.averageFPS, 1),
+    };
+  }
+}
+
+export interface JSFPSResult {
+  minFPS: number;
+  maxFPS: number;
+  averageFPS: number;
+}

package/src/benchmark/roundToDecimalPlaces.ts

@@ -0,0 +1,4 @@
+export function roundToDecimalPlaces(value: number, decimalPlaces: number) {
+  const multiplier = 10 ** decimalPlaces;
+  return Math.round(value * multiplier) / multiplier;
+}

package/src/benchmark/useBenchmark.ts

@@ -0,0 +1,240 @@
+import React, { useEffect } from "react";
+
+import FlashList from "../FlashList";
+
+import { autoScroll, Cancellable } from "./AutoScrollHelper";
+import { JSFPSMonitor, JSFPSResult } from "./JSFPSMonitor";
+import { roundToDecimalPlaces } from "./roundToDecimalPlaces";
+import {
+  BlankAreaTrackerResult,
+  useBlankAreaTracker,
+} from "./useBlankAreaTracker";
+
+export interface BenchmarkParams {
+  startDelayInMs?: number;
+
+  /**
+   * Can be used to increase or decrease speed of scrolling
+   */
+  speedMultiplier?: number;
+
+  /**
+   * Specify the number of times benchmark should repeat itself
+   */
+  repeatCount?: number;
+
+  /**
+   * When set to true, cumulative blank area will include sum of negative blank area values
+   * Blank area is negative when list is able to draw faster than the scroll speed.
+   */
+  sumNegativeBlankAreaValues?: boolean;
+}
+
+export interface BenchmarkResult {
+  js?: JSFPSResult;
+  interrupted: boolean;
+  suggestions: string[];
+  blankArea?: BlankAreaTrackerResult;
+  formattedString?: string;
+}
+
+/**
+ * Runs the benchmark on FlashList.
+ * Response object has a formatted string that can be printed to the console or shown as an alert.
+ * Result is posted to the callback method passed to the hook.
+ */
+
+export function useBenchmark(
+  flashListRef: React.RefObject<FlashList<any>>,
+  callback: (benchmarkResult: BenchmarkResult) => void,
+  params: BenchmarkParams = {}
+) {
+  const [blankAreaResult, blankAreaTracker] = useBlankAreaTracker(
+    flashListRef,
+    undefined,
+    { sumNegativeValues: params.sumNegativeBlankAreaValues, startDelayInMs: 0 }
+  );
+  useEffect(() => {
+    const cancellable = new Cancellable();
+    const suggestions: string[] = [];
+    if (flashListRef.current) {
+      if (!(Number(flashListRef.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(
+          flashListRef,
+          cancellable,
+          params.speedMultiplier || 1
+        );
+      }
+      const jsProfilerResponse = jsFPSMonitor.stopAndGetData();
+      if (jsProfilerResponse.averageFPS < 35) {
+        suggestions.push(
+          `Your average JS FPS is low. This can indicate that your components are doing too much work. Try to optimize your components and reduce re-renders if any`
+        );
+      }
+      computeSuggestions(flashListRef, suggestions);
+      const result: BenchmarkResult = generateResult(
+        jsProfilerResponse,
+        blankAreaResult,
+        suggestions,
+        cancellable
+      );
+      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 [blankAreaTracker];
+}
+
+export function getFormattedString(res: BenchmarkResult) {
+  return (
+    `Results:\n\n` +
+    `JS FPS: Avg: ${res.js?.averageFPS} | Min: ${res.js?.minFPS} | Max: ${res.js?.maxFPS}\n\n` +
+    `${
+      res.blankArea
+        ? `Blank Area: Max: ${res.blankArea?.maxBlankArea} Cumulative: ${res.blankArea?.cumulativeBlankArea}\n\n`
+        : ``
+    }` +
+    `${
+      res.suggestions.length > 0
+        ? `Suggestions:\n\n${res.suggestions
+            .map((value, index) => `${index + 1}. ${value}`)
+            .join("\n")}`
+        : ``
+    }`
+  );
+}
+
+function generateResult(
+  jsProfilerResponse: JSFPSResult,
+  blankAreaResult: BlankAreaTrackerResult,
+  suggestions: string[],
+  cancellable: Cancellable
+) {
+  return {
+    js: jsProfilerResponse,
+    blankArea:
+      blankAreaResult.maxBlankArea >= 0
+        ? {
+            maxBlankArea: roundToDecimalPlaces(blankAreaResult.maxBlankArea, 0),
+            cumulativeBlankArea: roundToDecimalPlaces(
+              blankAreaResult.cumulativeBlankArea,
+              0
+            ),
+          }
+        : undefined,
+    suggestions,
+    interrupted: cancellable.isCancelled(),
+  };
+}
+
+/**
+ * Scrolls to the end of the list and then back to the top
+ */
+async function runScrollBenchmark(
+  flashListRef: React.RefObject<FlashList<any> | null | undefined>,
+  cancellable: Cancellable,
+  scrollSpeedMultiplier: number
+): Promise<void> {
+  if (flashListRef.current) {
+    const horizontal = flashListRef.current.props.horizontal;
+    const rlv = flashListRef.current.recyclerlistview_unsafe;
+    if (rlv) {
+      const rlvSize = rlv.getRenderedSize();
+      const rlvContentSize = rlv.getContentDimension();
+
+      const fromX = 0;
+      const fromY = 0;
+      const toX = rlvContentSize.width - rlvSize.width;
+      const toY = rlvContentSize.height - rlvSize.height;
+
+      const scrollNow = (x: number, y: number) => {
+        flashListRef.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
+      );
+    }
+  }
+}
+function computeSuggestions(
+  flashListRef: React.RefObject<FlashList<any> | null | undefined>,
+  suggestions: string[]
+) {
+  if (flashListRef.current) {
+    if (flashListRef.current.props.data!!.length < 200) {
+      suggestions.push(
+        `Data count is low. Try to increase it to a large number (e.g 200) using the 'useDataMultiplier' hook.`
+      );
+    }
+    const distanceFromWindow = roundToDecimalPlaces(
+      flashListRef.current.firstItemOffset,
+      0
+    );
+    if (
+      (flashListRef.current.props.estimatedFirstItemOffset || 0) !==
+      distanceFromWindow
+    ) {
+      suggestions.push(
+        `estimatedFirstItemOffset can be set to ${distanceFromWindow}`
+      );
+    }
+    const rlv = flashListRef.current.recyclerlistview_unsafe;
+    const horizontal = flashListRef.current.props.horizontal;
+    if (rlv) {
+      const sizeArray = rlv.props.dataProvider
+        .getAllData()
+        .map((_, index) =>
+          horizontal
+            ? rlv.getLayout?.(index)?.width || 0
+            : rlv.getLayout?.(index)?.height || 0
+        );
+      const averageSize = Math.round(
+        sizeArray.reduce((prev, current) => prev + current, 0) /
+          sizeArray.length
+      );
+      if (
+        Math.abs(
+          averageSize -
+            (flashListRef.current.props.estimatedItemSize ??
+              flashListRef.current.state.layoutProvider
+                .defaultEstimatedItemSize)
+        ) > 5
+      ) {
+        suggestions.push(`estimatedItemSize can be set to ${averageSize}`);
+      }
+    }
+  }
+}

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> | null>,
+  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,28 @@
+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",
+  },
+  overrideItemLayoutRequiredForMasonryOptimization: {
+    message:
+      "optimizeItemArrangement has been enabled on `MasonryFlashList` but overrideItemLayout is not set.",
+    type: "InvariantViolation",
+  },
+};
+export default ExceptionList;

package/src/errors/Warnings.ts

@@ -0,0 +1,15 @@
+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.",
+  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/fabric/AutoLayoutNativeComponent.ts

@@ -0,0 +1,51 @@
+/*
+ * MIT License
+ *
+ * Copyright (C) 2023 Huawei Device Co., Ltd.
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+import codegenNativeComponent from "react-native/Libraries/Utilities/codegenNativeComponent";
+import type { ViewProps, HostComponent } from "react-native";
+import type {
+  Int32,
+  Double,
+  DirectEventHandler,
+} from "react-native/Libraries/Types/CodegenTypes";
+
+export type BlankAreaEvent = Readonly<{
+  offsetStart: Int32;
+  offsetEnd: Int32;
+}>;
+
+export type onBlankAreaEvent = DirectEventHandler<BlankAreaEvent>;
+
+interface NativeProps extends ViewProps {
+  horizontal?: boolean;
+  scrollOffset?: Double;
+  windowSize?: Double;
+  renderAheadOffset?: Double;
+  enableInstrumentation?: boolean;
+  disableAutoLayout?: boolean;
+  onBlankAreaEvent?: DirectEventHandler<BlankAreaEvent>;
+}
+
+export default codegenNativeComponent<NativeProps>(
+  "AutoLayoutView"
+) as HostComponent<NativeProps>;