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

package/src/viewability/ViewToken.ts

@@ -0,0 +1,31 @@
+/**
+ * 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.
+ */
+
+export default interface ViewToken {
+  item: any;
+  key: string;
+  index: number | null;
+  isViewable: boolean;
+  timestamp: number;
+}

package/src/viewability/ViewabilityHelper.ts

@@ -0,0 +1,190 @@
+/**
+ * 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 { ViewabilityConfig } from "react-native";
+import { Dimension, Layout } from "recyclerlistview";
+
+import CustomError from "../errors/CustomError";
+import ExceptionList from "../errors/ExceptionList";
+
+/**
+ * Helper class for computing viewable items based on the passed `viewabilityConfig`.
+ * Note methods in this class will be invoked on every scroll and should be optimized for performance.
+ */
+class ViewabilityHelper {
+  /**
+   * Viewable indices regardless of the viewability config
+   */
+  possiblyViewableIndices: number[] = [];
+
+  hasInteracted = false;
+
+  private viewableIndices: number[] = [];
+  private lastReportedViewableIndices: number[] = [];
+
+  private viewabilityConfig: ViewabilityConfig | null | undefined;
+  private viewableIndicesChanged: (
+    indices: number[],
+    newlyVisibleIndicies: number[],
+    newlyNonvisibleIndices: number[]
+  ) => void;
+
+  private timers: Set<NodeJS.Timeout> = new Set();
+
+  constructor(
+    viewabilityConfig: ViewabilityConfig | null | undefined,
+    viewableIndicesChanged: (
+      indices: number[],
+      newlyVisibleIndicies: number[],
+      newlyNonvisibleIndices: number[]
+    ) => void
+  ) {
+    this.viewabilityConfig = viewabilityConfig;
+    this.viewableIndicesChanged = viewableIndicesChanged;
+  }
+
+  public dispose() {
+    // Clean up on dismount
+    this.timers.forEach(clearTimeout);
+  }
+
+  public updateViewableItems(
+    horizontal: boolean,
+    scrollOffset: number,
+    listSize: Dimension,
+    getLayout: (index: number) => Layout | undefined,
+    viewableIndices?: number[]
+  ) {
+    if (viewableIndices !== undefined) {
+      this.possiblyViewableIndices = viewableIndices;
+    }
+    if (
+      this.viewabilityConfig?.itemVisiblePercentThreshold !== null &&
+      this.viewabilityConfig?.itemVisiblePercentThreshold !== undefined &&
+      this.viewabilityConfig?.viewAreaCoveragePercentThreshold !== null &&
+      this.viewabilityConfig?.viewAreaCoveragePercentThreshold !== undefined
+    ) {
+      throw new CustomError(
+        ExceptionList.multipleViewabilityThresholdTypesNotSupported
+      );
+    }
+    if (
+      (this.viewabilityConfig?.waitForInteraction ?? false) &&
+      !this.hasInteracted
+    ) {
+      return;
+    }
+    const newViewableIndices = this.possiblyViewableIndices.filter((index) =>
+      this.isItemViewable(
+        index,
+        horizontal,
+        scrollOffset,
+        listSize,
+        this.viewabilityConfig?.viewAreaCoveragePercentThreshold,
+        this.viewabilityConfig?.itemVisiblePercentThreshold,
+        getLayout
+      )
+    );
+    this.viewableIndices = newViewableIndices;
+    const minimumViewTime = this.viewabilityConfig?.minimumViewTime ?? 250;
+    // Setting default to 250. Default of 0 can impact performance when user scrolls fast.
+    if (minimumViewTime > 0) {
+      const timeoutId = setTimeout(() => {
+        this.timers.delete(timeoutId);
+        this.checkViewableIndicesChanges(newViewableIndices);
+      }, minimumViewTime);
+      this.timers.add(timeoutId);
+    } else {
+      this.checkViewableIndicesChanges(newViewableIndices);
+    }
+  }
+
+  public checkViewableIndicesChanges(newViewableIndices: number[]) {
+    // Check if all viewable indices are still available (applicable if minimumViewTime > 0)
+    const currentlyNewViewableIndices = newViewableIndices.filter((index) =>
+      this.viewableIndices.includes(index)
+    );
+    const newlyVisibleItems = currentlyNewViewableIndices.filter(
+      (index) => !this.lastReportedViewableIndices.includes(index)
+    );
+    const newlyNonvisibleItems = this.lastReportedViewableIndices.filter(
+      (index) => !currentlyNewViewableIndices.includes(index)
+    );
+
+    if (newlyVisibleItems.length > 0 || newlyNonvisibleItems.length > 0) {
+      this.lastReportedViewableIndices = currentlyNewViewableIndices;
+      this.viewableIndicesChanged(
+        currentlyNewViewableIndices,
+        newlyVisibleItems,
+        newlyNonvisibleItems
+      );
+    }
+  }
+
+  public clearLastReportedViewableIndices() {
+    this.lastReportedViewableIndices = [];
+  }
+
+  private isItemViewable(
+    index: number,
+    horizontal: boolean,
+    scrollOffset: number,
+    listSize: Dimension,
+    viewAreaCoveragePercentThreshold: number | null | undefined,
+    itemVisiblePercentThreshold: number | null | undefined,
+    getLayout: (index: number) => Layout | undefined
+  ) {
+    const itemLayout = getLayout(index);
+    if (itemLayout === undefined) {
+      return false;
+    }
+    const itemTop = (horizontal ? itemLayout.x : itemLayout.y) - scrollOffset;
+    const itemSize = horizontal ? itemLayout.width : itemLayout.height;
+    const listMainSize = horizontal ? listSize.width : listSize.height;
+    const pixelsVisible =
+      Math.min(itemTop + itemSize, listMainSize) - Math.max(itemTop, 0);
+
+    // Always consider item fully viewable if it is fully visible, regardless of the `viewAreaCoveragePercentThreshold`
+    if (pixelsVisible === itemSize) {
+      return true;
+    }
+    // Skip checking item if it's not visible at all
+    if (pixelsVisible === 0) {
+      return false;
+    }
+    const viewAreaMode =
+      viewAreaCoveragePercentThreshold !== null &&
+      viewAreaCoveragePercentThreshold !== undefined;
+    const percent = viewAreaMode
+      ? pixelsVisible / listMainSize
+      : pixelsVisible / itemSize;
+    const viewableAreaPercentThreshold = viewAreaMode
+      ? viewAreaCoveragePercentThreshold * 0.01
+      : (itemVisiblePercentThreshold ?? 0) * 0.01;
+
+    return percent >= viewableAreaPercentThreshold;
+  }
+}
+
+export default ViewabilityHelper;

package/src/viewability/ViewabilityManager.ts

@@ -0,0 +1,169 @@
+/**
+ * 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 { ViewabilityConfig } from "react-native";
+
+import FlashList from "../FlashList";
+
+import ViewabilityHelper from "./ViewabilityHelper";
+import ViewToken from "./ViewToken";
+
+/**
+ * Manager for viewability tracking. It holds multiple viewability callback pairs and keeps them updated.
+ */
+export default class ViewabilityManager<T> {
+  private flashListRef: FlashList<T>;
+  private viewabilityHelpers: ViewabilityHelper[] = [];
+  private hasInteracted = false;
+
+  constructor(flashListRef: FlashList<T>) {
+    this.flashListRef = flashListRef;
+    if (
+      flashListRef.props.onViewableItemsChanged !== null &&
+      flashListRef.props.onViewableItemsChanged !== undefined
+    ) {
+      this.viewabilityHelpers.push(
+        this.createViewabilityHelper(
+          flashListRef.props.viewabilityConfig,
+          (info) => {
+            flashListRef.props.onViewableItemsChanged?.(info);
+          }
+        )
+      );
+    }
+    (flashListRef.props.viewabilityConfigCallbackPairs ?? []).forEach(
+      (pair, index) => {
+        this.viewabilityHelpers.push(
+          this.createViewabilityHelper(pair.viewabilityConfig, (info) => {
+            const callback =
+              flashListRef.props.viewabilityConfigCallbackPairs?.[index]
+                ?.onViewableItemsChanged;
+            callback?.(info);
+          })
+        );
+      }
+    );
+  }
+
+  /**
+   * @returns true if the viewability manager has any viewability callback pairs registered.
+   */
+  public get shouldListenToVisibleIndices() {
+    return this.viewabilityHelpers.length > 0;
+  }
+
+  public dispose = () => {
+    this.viewabilityHelpers.forEach((viewabilityHelper) =>
+      viewabilityHelper.dispose()
+    );
+  };
+
+  public onVisibleIndicesChanged = (all: number[]) => {
+    this.updateViewableItems(all);
+  };
+
+  public recordInteraction = () => {
+    if (this.hasInteracted) {
+      return;
+    }
+    this.hasInteracted = true;
+    this.viewabilityHelpers.forEach((viewabilityHelper) => {
+      viewabilityHelper.hasInteracted = true;
+    });
+    this.updateViewableItems();
+  };
+
+  public updateViewableItems = (newViewableIndices?: number[]) => {
+    const listSize =
+      this.flashListRef.getWindowSize() ??
+      this.flashListRef.props.estimatedListSize;
+    if (listSize === undefined || !this.shouldListenToVisibleIndices) {
+      return;
+    }
+    const scrollOffset =
+      (this.flashListRef.getAbsoluteLastScrollOffset() ?? 0) -
+      this.flashListRef.firstItemOffset;
+    this.viewabilityHelpers.forEach((viewabilityHelper) => {
+      viewabilityHelper.updateViewableItems(
+        this.flashListRef.props.horizontal ?? false,
+        scrollOffset,
+        listSize,
+        (index: number) => this.flashListRef.getLayout(index),
+        newViewableIndices
+      );
+    });
+  };
+
+  public recomputeViewableItems = () => {
+    this.viewabilityHelpers.forEach((viewabilityHelper) =>
+      viewabilityHelper.clearLastReportedViewableIndices()
+    );
+
+    this.updateViewableItems();
+  };
+
+  /**
+   * Creates a new `ViewabilityHelper` instance with `onViewableItemsChanged` callback and `ViewabilityConfig`
+   * @returns `ViewabilityHelper` instance
+   */
+  private createViewabilityHelper = (
+    viewabilityConfig: ViewabilityConfig | null | undefined,
+    onViewableItemsChanged:
+      | ((info: { viewableItems: ViewToken[]; changed: ViewToken[] }) => void)
+      | null
+      | undefined
+  ) => {
+    const mapViewToken: (index: number, isViewable: boolean) => ViewToken = (
+      index: number,
+      isViewable: boolean
+    ) => {
+      const item = this.flashListRef.props.data?.[index];
+      const key =
+        item === undefined || this.flashListRef.props.keyExtractor === undefined
+          ? index.toString()
+          : this.flashListRef.props.keyExtractor(item, index);
+      return {
+        index,
+        isViewable,
+        item,
+        key,
+        timestamp: Date.now(),
+      };
+    };
+    return new ViewabilityHelper(
+      viewabilityConfig,
+      (indices, newlyVisibleIndices, newlyNonvisibleIndices) => {
+        onViewableItemsChanged?.({
+          viewableItems: indices.map((index) => mapViewToken(index, true)),
+          changed: [
+            ...newlyVisibleIndices.map((index) => mapViewToken(index, true)),
+            ...newlyNonvisibleIndices.map((index) =>
+              mapViewToken(index, false)
+            ),
+          ],
+        });
+      }
+    );
+  };
+}