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

package/src/MasonryFlashList.tsx

@@ -0,0 +1,499 @@
+/**
+ * MIT License
+ *
+ * Copyright (C) 2024 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 React, { useCallback, useRef, useEffect, useMemo } from "react";
+import {
+  View,
+  Dimensions,
+  ScrollViewProps,
+  LayoutChangeEvent,
+  NativeScrollEvent,
+  NativeSyntheticEvent,
+} from "react-native";
+
+import CustomError from "./errors/CustomError";
+import ExceptionList from "./errors/ExceptionList";
+import FlashList from "./FlashList";
+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>,
+    | "horizontal"
+    | "initialScrollIndex"
+    | "inverted"
+    | "onBlankArea"
+    | "renderItem"
+    | "viewabilityConfigCallbackPairs"
+  > {
+  /**
+   * Allows you to change the column widths of the list. This is helpful if you want some columns to be wider than the others.
+   * e.g, if `numColumns` is `3`, you can return `2` for `index 1` and `1` for the rest to achieve a `1:2:1` split by width.
+   */
+  getColumnFlex?: (
+    items: MasonryListItem<T>[],
+    columnIndex: number,
+    maxColumns: number,
+    extraData?: any
+  ) => number;
+
+  /**
+   * If enabled, MasonryFlashList will try to reduce difference in column height by modifying item order.
+   * `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"];
+const defaultEstimatedItemSize = 100;
+
+export interface MasonryFlashListScrollEvent extends NativeScrollEvent {
+  doNotPropagate?: boolean;
+}
+
+export interface MasonryListItem<T> {
+  originalIndex: number;
+  originalItem: T;
+}
+
+/**
+ * MasonryFlashListRef with support for scroll related methods
+ */
+export interface MasonryFlashListRef<T> {
+  scrollToOffset: FlashList<T>["scrollToOffset"];
+  scrollToEnd: FlashList<T>["scrollToEnd"];
+  getScrollableNode: FlashList<T>["getScrollableNode"];
+}
+
+/**
+ * FlashList variant that enables rendering of masonry layouts.
+ * If you want `MasonryFlashList` to optimize item arrangement, enable `optimizeItemArrangement` and pass a valid `overrideItemLayout` function.
+ */
+const MasonryFlashListComponent = React.forwardRef(
+  <T,>(
+    /**
+     * Forward Ref will force cast generic parament T to unknown. Export has a explicit cast to solve this.
+     */
+    props: MasonryFlashListProps<T>,
+    forwardRef: React.ForwardedRef<MasonryFlashListRef<T>>
+  ) => {
+    const columnCount = props.numColumns || 1;
+    const drawDistance = props.drawDistance;
+    const estimatedListSize = props.estimatedListSize ??
+      Dimensions.get("window") ?? { height: 500, width: 500 };
+
+    if (props.optimizeItemArrangement && !props.overrideItemLayout) {
+      throw new CustomError(
+        ExceptionList.overrideItemLayoutRequiredForMasonryOptimization
+      );
+    }
+    const dataSet = useDataSet(
+      columnCount,
+      Boolean(props.optimizeItemArrangement),
+      props.data,
+      props.overrideItemLayout,
+      props.extraData
+    );
+
+    const totalColumnFlex = useTotalColumnFlex(dataSet, props);
+
+    const propsRef = useRef(props);
+    propsRef.current = props;
+
+    const onScrollRef = useRef<OnScrollCallback[]>([]);
+    const emptyScrollEvent = useRef(getEmptyScrollEvent())
+      .current as NativeSyntheticEvent<MasonryFlashListScrollEvent>;
+    const ScrollComponent = useRef(
+      getFlashListScrollView(onScrollRef, () => {
+        return (
+          getListRenderedSize(parentFlashList)?.height ||
+          estimatedListSize.height
+        );
+      })
+    ).current;
+
+    const onScrollProxy = useRef<OnScrollCallback>(
+      (scrollEvent: NativeSyntheticEvent<MasonryFlashListScrollEvent>) => {
+        emptyScrollEvent.nativeEvent.contentOffset.y =
+          scrollEvent.nativeEvent.contentOffset.y -
+          (parentFlashList.current?.firstItemOffset ?? 0);
+        onScrollRef.current?.forEach((onScrollCallback) => {
+          onScrollCallback?.(emptyScrollEvent);
+        });
+        if (!scrollEvent.nativeEvent.doNotPropagate) {
+          propsRef.current.onScroll?.(scrollEvent);
+        }
+      }
+    ).current;
+
+    /**
+     * We're triggering an onScroll on internal lists so that they register the correct offset which is offset - header size.
+     * This will make sure viewability callbacks are triggered correctly.
+     * 32 ms is equal to two frames at 60 fps. Faster framerates will not cause any problems.
+     */
+    const onLoadForNestedLists = useRef((args: { elapsedTimeInMs: number }) => {
+      setTimeout(() => {
+        emptyScrollEvent.nativeEvent.doNotPropagate = true;
+        onScrollProxy?.(emptyScrollEvent);
+        emptyScrollEvent.nativeEvent.doNotPropagate = false;
+      }, 32);
+      propsRef.current.onLoad?.(args);
+    }).current;
+
+    const [parentFlashList, getFlashList] =
+      useRefWithForwardRef<FlashList<MasonryListItem<T>[]>>(forwardRef);
+
+    const {
+      renderItem,
+      getItemType,
+      getColumnFlex,
+      overrideItemLayout,
+      viewabilityConfig,
+      keyExtractor,
+      onLoad,
+      onViewableItemsChanged,
+      data,
+      stickyHeaderIndices,
+      CellRendererComponent,
+      ItemSeparatorComponent,
+      ...remainingProps
+    } = props;
+
+    const firstColumnHeight =
+      (dataSet[0]?.length ?? 0) *
+      (props.estimatedItemSize ?? defaultEstimatedItemSize);
+
+    const insetForLayoutManager = applyContentContainerInsetForLayoutManager(
+      { height: 0, width: 0 },
+      props.contentContainerStyle,
+      false
+    );
+
+    return (
+      <FlashList
+        ref={getFlashList}
+        {...remainingProps}
+        horizontal={false}
+        numColumns={columnCount}
+        data={dataSet}
+        onScroll={onScrollProxy}
+        estimatedItemSize={firstColumnHeight || estimatedListSize.height}
+        renderItem={(args) => {
+          return (
+            <FlashList
+              renderScrollComponent={ScrollComponent}
+              estimatedItemSize={props.estimatedItemSize}
+              data={args.item}
+              onLoad={args.index === 0 ? onLoadForNestedLists : undefined}
+              renderItem={(innerArgs) => {
+                return (
+                  renderItem?.({
+                    ...innerArgs,
+                    item: innerArgs.item.originalItem,
+                    index: innerArgs.item.originalIndex,
+                    columnSpan: 1,
+                    columnIndex: args.index,
+                  }) ?? null
+                );
+              }}
+              keyExtractor={
+                keyExtractor
+                  ? (item, _) => {
+                      return keyExtractor?.(
+                        item.originalItem,
+                        item.originalIndex
+                      );
+                    }
+                  : undefined
+              }
+              getItemType={
+                getItemType
+                  ? (item, _, extraData) => {
+                      return getItemType?.(
+                        item.originalItem,
+                        item.originalIndex,
+                        extraData
+                      );
+                    }
+                  : undefined
+              }
+              drawDistance={drawDistance}
+              estimatedListSize={{
+                height: estimatedListSize.height,
+                width:
+                  (((getListRenderedSize(parentFlashList)?.width ||
+                    estimatedListSize.width) +
+                    insetForLayoutManager.width) /
+                    totalColumnFlex) *
+                  (getColumnFlex?.(
+                    args.item,
+                    args.index,
+                    columnCount,
+                    props.extraData
+                  ) ?? 1),
+              }}
+              extraData={props.extraData}
+              CellRendererComponent={CellRendererComponent}
+              ItemSeparatorComponent={ItemSeparatorComponent}
+              viewabilityConfig={viewabilityConfig}
+              onViewableItemsChanged={
+                onViewableItemsChanged
+                  ? (info) => {
+                      updateViewTokens(info.viewableItems);
+                      updateViewTokens(info.changed);
+                      onViewableItemsChanged?.(info);
+                    }
+                  : undefined
+              }
+              overrideItemLayout={
+                overrideItemLayout
+                  ? (layout, item, _, __, extraData) => {
+                      overrideItemLayout?.(
+                        layout,
+                        item.originalItem,
+                        item.originalIndex,
+                        columnCount,
+                        extraData
+                      );
+                      layout.span = undefined;
+                    }
+                  : undefined
+              }
+            />
+          );
+        }}
+        overrideItemLayout={
+          getColumnFlex
+            ? (layout, item, index, maxColumns, extraData) => {
+                layout.span =
+                  (columnCount *
+                    getColumnFlex(item, index, maxColumns, extraData)) /
+                  totalColumnFlex;
+              }
+            : undefined
+        }
+      />
+    );
+  }
+);
+
+/**
+ * Splits data for each column's FlashList
+ */
+const useDataSet = <T,>(
+  columnCount: number,
+  optimizeItemArrangement: boolean,
+  sourceData?: FlashListProps<T>["data"],
+  overrideItemLayout?: MasonryFlashListProps<T>["overrideItemLayout"],
+  extraData?: MasonryFlashListProps<T>["extraData"]
+): MasonryListItem<T>[][] => {
+  return useMemo(() => {
+    if (!sourceData || sourceData.length === 0) {
+      return [];
+    }
+    const columnHeightTracker = new Array<number>(columnCount).fill(0);
+    const layoutObject: { size: number | undefined } = { size: undefined };
+    const dataSet = new Array<MasonryListItem<T>[]>(columnCount);
+    const dataSize = sourceData.length;
+
+    for (let i = 0; i < columnCount; i++) {
+      dataSet[i] = [];
+    }
+    for (let i = 0; i < dataSize; i++) {
+      let nextColumnIndex = i % columnCount;
+      if (optimizeItemArrangement) {
+        for (let j = 0; j < columnCount; j++) {
+          if (columnHeightTracker[j] < columnHeightTracker[nextColumnIndex]) {
+            nextColumnIndex = j;
+          }
+        }
+        // update height of column
+        layoutObject.size = undefined;
+        overrideItemLayout!(
+          layoutObject,
+          sourceData[i],
+          i,
+          columnCount,
+          extraData
+        );
+        columnHeightTracker[nextColumnIndex] +=
+          layoutObject.size ?? defaultEstimatedItemSize;
+      }
+      dataSet[nextColumnIndex].push({
+        originalItem: sourceData[i],
+        originalIndex: i,
+      });
+    }
+    return dataSet;
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [sourceData, columnCount, optimizeItemArrangement, extraData]);
+};
+
+const useTotalColumnFlex = <T,>(
+  dataSet: MasonryListItem<T>[][],
+  props: MasonryFlashListProps<T>
+): number => {
+  return useMemo(() => {
+    const columnCount = props.numColumns || 1;
+    if (!props.getColumnFlex) {
+      return columnCount;
+    }
+    let totalFlexSum = 0;
+    const dataSize = dataSet.length;
+    for (let i = 0; i < dataSize; i++) {
+      totalFlexSum += props.getColumnFlex(
+        dataSet[i],
+        i,
+        columnCount,
+        props.extraData
+      );
+    }
+    return totalFlexSum;
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [dataSet, props.getColumnFlex, props.extraData]);
+};
+
+/**
+ * Handle both function refs and refs with current property
+ */
+const useRefWithForwardRef = <T,>(
+  forwardRef: any
+): [React.MutableRefObject<T | null>, (instance: T | null) => void] => {
+  const ref: React.MutableRefObject<T | null> = useRef(null);
+  return [
+    ref,
+    useCallback(
+      (instance: T | null) => {
+        ref.current = instance;
+        if (typeof forwardRef === "function") {
+          forwardRef(instance);
+        } else if (forwardRef) {
+          forwardRef.current = instance;
+        }
+      },
+      [forwardRef]
+    ),
+  ];
+};
+
+/**
+ * This ScrollView is actually just a view mimicking a scrollview. We block the onScroll event from being passed to the parent list directly.
+ * We manually drive onScroll from the parent and thus, achieve recycling.
+ */
+const getFlashListScrollView = (
+  onScrollRef: React.RefObject<OnScrollCallback[]>,
+  getParentHeight: () => number
+) => {
+  const FlashListScrollView = React.forwardRef(
+    (props: ScrollViewProps, ref: React.ForwardedRef<View>) => {
+      const { onLayout, onScroll, ...rest } = props;
+      const onLayoutProxy = useCallback(
+        (layoutEvent: LayoutChangeEvent) => {
+          onLayout?.({
+            nativeEvent: {
+              layout: {
+                height: getParentHeight(),
+                width: layoutEvent.nativeEvent.layout.width,
+              },
+            },
+          } as LayoutChangeEvent);
+        },
+        [onLayout]
+      );
+      useEffect(() => {
+        if (onScroll) {
+          onScrollRef.current?.push(onScroll);
+        }
+        return () => {
+          if (!onScrollRef.current || !onScroll) {
+            return;
+          }
+          const indexToDelete = onScrollRef.current.indexOf(onScroll);
+          if (indexToDelete > -1) {
+            onScrollRef.current.splice(indexToDelete, 1);
+          }
+        };
+      }, [onScroll]);
+      return <View ref={ref} {...rest} onLayout={onLayoutProxy} />;
+    }
+  );
+  FlashListScrollView.displayName = "FlashListScrollView";
+  return FlashListScrollView;
+};
+const updateViewTokens = (tokens: ViewToken[]) => {
+  const length = tokens.length;
+  for (let i = 0; i < length; i++) {
+    const token = tokens[i];
+    if (token.index !== null && token.index !== undefined) {
+      if (token.item) {
+        token.index = token.item.originalIndex;
+        token.item = token.item.originalItem;
+      } else {
+        token.index = null;
+        token.item = undefined;
+      }
+    }
+  }
+};
+
+const getEmptyScrollEvent = () => {
+  return {
+    nativeEvent: { contentOffset: { y: 0, x: 0 } },
+  };
+};
+const getListRenderedSize = <T,>(
+  parentFlashList: React.MutableRefObject<FlashList<T[]> | null>
+) => {
+  return parentFlashList?.current?.recyclerlistview_unsafe?.getRenderedSize();
+};
+MasonryFlashListComponent.displayName = "MasonryFlashList";
+
+/**
+ * FlashList variant that enables rendering of masonry layouts.
+ * If you want `MasonryFlashList` to optimize item arrangement, enable `optimizeItemArrangement` and pass a valid `overrideItemLayout` function.
+ */
+export const MasonryFlashList = MasonryFlashListComponent as <T>(
+  props: MasonryFlashListProps<T> & {
+    ref?: React.RefObject<MasonryFlashListRef<T>>;
+  }
+) => React.ReactElement;

package/src/PureComponentWrapper.tsx

@@ -0,0 +1,65 @@
+/**
+ * MIT License
+ *
+ * Copyright (C) 2024 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 React, { JSX } from "react";
+
+export interface PureComponentWrapperProps {
+  renderer: (arg: unknown) => JSX.Element | null;
+
+  /** Renderer is called with this argument.
+   * Don't change this value everytime or else component will always rerender. Prefer primitives. */
+  arg?: unknown;
+  enabled?: boolean;
+  [other: string]: unknown;
+}
+
+/**
+ * Pure component wrapper that can be used to prevent renders of the `renderer` method passed to the component. Any change in props will lead to `renderer` getting called.
+ */
+export class PureComponentWrapper extends React.PureComponent<PureComponentWrapperProps> {
+  static defaultProps = {
+    enabled: true,
+  };
+
+  private overrideEnabled: boolean | undefined = undefined;
+
+  /** Once set explicitly, prop will be ignored. Not using state because of performance reasons. */
+  public setEnabled(enabled: boolean) {
+    if (enabled !== this.overrideEnabled) {
+      this.overrideEnabled = enabled;
+      this.forceUpdate();
+    }
+  }
+
+  render() {
+    if (this.overrideEnabled === undefined) {
+      return (
+        (this.props.enabled && this.props.renderer(this.props.arg)) || null
+      );
+    } else {
+      return (
+        (this.overrideEnabled && this.props.renderer(this.props.arg)) || null
+      );
+    }
+  }
+}

package/src/benchmark/AutoScrollHelper.ts

@@ -0,0 +1,94 @@
+/**
+ * MIT License
+ *
+ * Copyright (C) 2024 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.
+ */
+
+/**
+ * This method can be used to trigger scroll events that can be forwarded to an element. Anything that implements scrollable can leverage this.
+ * @param scroll The scrollable element
+ * @param fromX The x offset to start from
+ * @param fromY The y offset to start from
+ * @param toX the x offset to end scroll at
+ * @param toY the y offset to end scroll at
+ * @param speedMultiplier  the speed multiplier to use
+ * @param cancellable can be used to cancel the scroll
+ * @returns Promise that resolves when the scroll is complete
+ */
+export function autoScroll(
+  scroll: (x: number, y: number, animated: boolean) => void,
+  fromX: number,
+  fromY: number,
+  toX: number,
+  toY: number,
+  speedMultiplier = 1,
+  cancellable: Cancellable = new Cancellable()
+): Promise<boolean> {
+  return new Promise((resolve) => {
+    scroll(fromX, fromY, false);
+    // Very fast scrolls on Android/iOS typically move content 7px every millisecond.
+    const incrementPerMs = 7 * speedMultiplier;
+    const directionMultiplierX = toX > fromX ? 1 : -1;
+    const directionMultiplierY = toY > fromY ? 1 : -1;
+    const comparatorX = toX > fromX ? Math.min : Math.max;
+    const comparatorY = toY > fromY ? Math.min : Math.max;
+    let startTime = Date.now();
+    let startX = fromX;
+    let startY = fromY;
+    // Computes the number of pixels to scroll in the given time
+    // Also invokes the scrollable to update the scroll position
+    const animationLoop = () => {
+      requestAnimationFrame(() => {
+        if (cancellable.isCancelled()) {
+          resolve(false);
+          return;
+        }
+        const currentTime = Date.now();
+        const timeElapsed = currentTime - startTime;
+        const distanceToCover = incrementPerMs * timeElapsed;
+        startX += distanceToCover * directionMultiplierX;
+        startY += distanceToCover * directionMultiplierY;
+        scroll(comparatorX(toX, startX), comparatorY(toY, startY), false);
+        startTime = currentTime;
+        if (
+          comparatorX(toX, startX) !== toX ||
+          comparatorY(toY, startY) !== toY
+        ) {
+          return animationLoop();
+        }
+        resolve(true);
+      });
+    };
+    animationLoop();
+  });
+}
+
+export class Cancellable {
+  public cancel() {
+    this._isCancelled = true;
+  }
+
+  public isCancelled(): boolean {
+    return this._isCancelled;
+  }
+
+  public _isCancelled = false;
+}