@react-native-tvos/virtualized-lists 0.73.4-0

package/Lists/ViewabilityHelper.js

@@ -0,0 +1,348 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * @flow
+ * @format
+ */
+
+'use strict';
+
+import type {CellMetricProps} from './ListMetricsAggregator';
+import ListMetricsAggregator from './ListMetricsAggregator';
+
+const invariant = require('invariant');
+
+export type ViewToken = {
+  item: any,
+  key: string,
+  index: ?number,
+  isViewable: boolean,
+  section?: any,
+  ...
+};
+
+export type ViewabilityConfigCallbackPair = {
+  viewabilityConfig: ViewabilityConfig,
+  onViewableItemsChanged: (info: {
+    viewableItems: Array<ViewToken>,
+    changed: Array<ViewToken>,
+    ...
+  }) => void,
+  ...
+};
+
+export type ViewabilityConfig = {|
+  /**
+   * Minimum amount of time (in milliseconds) that an item must be physically viewable before the
+   * viewability callback will be fired. A high number means that scrolling through content without
+   * stopping will not mark the content as viewable.
+   */
+  minimumViewTime?: number,
+
+  /**
+   * Percent of viewport that must be covered for a partially occluded item to count as
+   * "viewable", 0-100. Fully visible items are always considered viewable. A value of 0 means
+   * that a single pixel in the viewport makes the item viewable, and a value of 100 means that
+   * an item must be either entirely visible or cover the entire viewport to count as viewable.
+   */
+  viewAreaCoveragePercentThreshold?: number,
+
+  /**
+   * Similar to `viewAreaPercentThreshold`, but considers the percent of the item that is visible,
+   * rather than the fraction of the viewable area it covers.
+   */
+  itemVisiblePercentThreshold?: number,
+
+  /**
+   * Nothing is considered viewable until the user scrolls or `recordInteraction` is called after
+   * render.
+   */
+  waitForInteraction?: boolean,
+|};
+
+/**
+ * A Utility class for calculating viewable items based on current metrics like scroll position and
+ * layout.
+ *
+ * An item is said to be in a "viewable" state when any of the following
+ * is true for longer than `minimumViewTime` milliseconds (after an interaction if `waitForInteraction`
+ * is true):
+ *
+ * - Occupying >= `viewAreaCoveragePercentThreshold` of the view area XOR fraction of the item
+ *   visible in the view area >= `itemVisiblePercentThreshold`.
+ * - Entirely visible on screen
+ */
+class ViewabilityHelper {
+  _config: ViewabilityConfig;
+  _hasInteracted: boolean = false;
+  _timers: Set<number> = new Set();
+  _viewableIndices: Array<number> = [];
+  _viewableItems: Map<string, ViewToken> = new Map();
+
+  constructor(
+    config: ViewabilityConfig = {viewAreaCoveragePercentThreshold: 0},
+  ) {
+    this._config = config;
+  }
+
+  /**
+   * Cleanup, e.g. on unmount. Clears any pending timers.
+   */
+  dispose() {
+    /* $FlowFixMe[incompatible-call] (>=0.63.0 site=react_native_fb) This
+     * comment suppresses an error found when Flow v0.63 was deployed. To see
+     * the error delete this comment and run Flow. */
+    this._timers.forEach(clearTimeout);
+  }
+
+  /**
+   * Determines which items are viewable based on the current metrics and config.
+   */
+  computeViewableItems(
+    props: CellMetricProps,
+    scrollOffset: number,
+    viewportHeight: number,
+    listMetrics: ListMetricsAggregator,
+    // Optional optimization to reduce the scan size
+    renderRange?: {
+      first: number,
+      last: number,
+      ...
+    },
+  ): Array<number> {
+    const itemCount = props.getItemCount(props.data);
+    const {itemVisiblePercentThreshold, viewAreaCoveragePercentThreshold} =
+      this._config;
+    const viewAreaMode = viewAreaCoveragePercentThreshold != null;
+    const viewablePercentThreshold = viewAreaMode
+      ? viewAreaCoveragePercentThreshold
+      : itemVisiblePercentThreshold;
+    invariant(
+      viewablePercentThreshold != null &&
+        (itemVisiblePercentThreshold != null) !==
+          (viewAreaCoveragePercentThreshold != null),
+      'Must set exactly one of itemVisiblePercentThreshold or viewAreaCoveragePercentThreshold',
+    );
+    const viewableIndices = [];
+    if (itemCount === 0) {
+      return viewableIndices;
+    }
+    let firstVisible = -1;
+    const {first, last} = renderRange || {first: 0, last: itemCount - 1};
+    if (last >= itemCount) {
+      console.warn(
+        'Invalid render range computing viewability ' +
+          JSON.stringify({renderRange, itemCount}),
+      );
+      return [];
+    }
+    for (let idx = first; idx <= last; idx++) {
+      const metrics = listMetrics.getCellMetrics(idx, props);
+      if (!metrics) {
+        continue;
+      }
+      const top = Math.floor(metrics.offset - scrollOffset);
+      const bottom = Math.floor(top + metrics.length);
+
+      if (top < viewportHeight && bottom > 0) {
+        firstVisible = idx;
+        if (
+          _isViewable(
+            viewAreaMode,
+            viewablePercentThreshold,
+            top,
+            bottom,
+            viewportHeight,
+            metrics.length,
+          )
+        ) {
+          viewableIndices.push(idx);
+        }
+      } else if (firstVisible >= 0) {
+        break;
+      }
+    }
+    return viewableIndices;
+  }
+
+  /**
+   * Figures out which items are viewable and how that has changed from before and calls
+   * `onViewableItemsChanged` as appropriate.
+   */
+  onUpdate(
+    props: CellMetricProps,
+    scrollOffset: number,
+    viewportHeight: number,
+    listMetrics: ListMetricsAggregator,
+    createViewToken: (
+      index: number,
+      isViewable: boolean,
+      props: CellMetricProps,
+    ) => ViewToken,
+    onViewableItemsChanged: ({
+      viewableItems: Array<ViewToken>,
+      changed: Array<ViewToken>,
+      ...
+    }) => void,
+    // Optional optimization to reduce the scan size
+    renderRange?: {
+      first: number,
+      last: number,
+      ...
+    },
+  ): void {
+    const itemCount = props.getItemCount(props.data);
+    if (
+      (this._config.waitForInteraction && !this._hasInteracted) ||
+      itemCount === 0 ||
+      !listMetrics.getCellMetrics(0, props)
+    ) {
+      return;
+    }
+    let viewableIndices: Array<number> = [];
+    if (itemCount) {
+      viewableIndices = this.computeViewableItems(
+        props,
+        scrollOffset,
+        viewportHeight,
+        listMetrics,
+        renderRange,
+      );
+    }
+    if (
+      this._viewableIndices.length === viewableIndices.length &&
+      this._viewableIndices.every((v, ii) => v === viewableIndices[ii])
+    ) {
+      // We might get a lot of scroll events where visibility doesn't change and we don't want to do
+      // extra work in those cases.
+      return;
+    }
+    this._viewableIndices = viewableIndices;
+    if (this._config.minimumViewTime) {
+      const handle: TimeoutID = setTimeout(() => {
+        /* $FlowFixMe[incompatible-call] (>=0.63.0 site=react_native_fb) This
+         * comment suppresses an error found when Flow v0.63 was deployed. To
+         * see the error delete this comment and run Flow. */
+        this._timers.delete(handle);
+        this._onUpdateSync(
+          props,
+          viewableIndices,
+          onViewableItemsChanged,
+          createViewToken,
+        );
+      }, this._config.minimumViewTime);
+      /* $FlowFixMe[incompatible-call] (>=0.63.0 site=react_native_fb) This
+       * comment suppresses an error found when Flow v0.63 was deployed. To see
+       * the error delete this comment and run Flow. */
+      this._timers.add(handle);
+    } else {
+      this._onUpdateSync(
+        props,
+        viewableIndices,
+        onViewableItemsChanged,
+        createViewToken,
+      );
+    }
+  }
+
+  /**
+   * clean-up cached _viewableIndices to evaluate changed items on next update
+   */
+  resetViewableIndices() {
+    this._viewableIndices = [];
+  }
+
+  /**
+   * Records that an interaction has happened even if there has been no scroll.
+   */
+  recordInteraction() {
+    this._hasInteracted = true;
+  }
+
+  _onUpdateSync(
+    props: CellMetricProps,
+    viewableIndicesToCheck: Array<number>,
+    onViewableItemsChanged: ({
+      changed: Array<ViewToken>,
+      viewableItems: Array<ViewToken>,
+      ...
+    }) => void,
+    createViewToken: (
+      index: number,
+      isViewable: boolean,
+      props: CellMetricProps,
+    ) => ViewToken,
+  ) {
+    // Filter out indices that have gone out of view since this call was scheduled.
+    viewableIndicesToCheck = viewableIndicesToCheck.filter(ii =>
+      this._viewableIndices.includes(ii),
+    );
+    const prevItems = this._viewableItems;
+    const nextItems = new Map(
+      viewableIndicesToCheck.map(ii => {
+        const viewable = createViewToken(ii, true, props);
+        return [viewable.key, viewable];
+      }),
+    );
+
+    const changed = [];
+    for (const [key, viewable] of nextItems) {
+      if (!prevItems.has(key)) {
+        changed.push(viewable);
+      }
+    }
+    for (const [key, viewable] of prevItems) {
+      if (!nextItems.has(key)) {
+        changed.push({...viewable, isViewable: false});
+      }
+    }
+    if (changed.length > 0) {
+      this._viewableItems = nextItems;
+      onViewableItemsChanged({
+        viewableItems: Array.from(nextItems.values()),
+        changed,
+        viewabilityConfig: this._config,
+      });
+    }
+  }
+}
+
+function _isViewable(
+  viewAreaMode: boolean,
+  viewablePercentThreshold: number,
+  top: number,
+  bottom: number,
+  viewportHeight: number,
+  itemLength: number,
+): boolean {
+  if (_isEntirelyVisible(top, bottom, viewportHeight)) {
+    return true;
+  } else {
+    const pixels = _getPixelsVisible(top, bottom, viewportHeight);
+    const percent =
+      100 * (viewAreaMode ? pixels / viewportHeight : pixels / itemLength);
+    return percent >= viewablePercentThreshold;
+  }
+}
+
+function _getPixelsVisible(
+  top: number,
+  bottom: number,
+  viewportHeight: number,
+): number {
+  const visibleHeight = Math.min(bottom, viewportHeight) - Math.max(top, 0);
+  return Math.max(0, visibleHeight);
+}
+
+function _isEntirelyVisible(
+  top: number,
+  bottom: number,
+  viewportHeight: number,
+): boolean {
+  return top >= 0 && bottom <= viewportHeight && bottom > top;
+}
+
+module.exports = ViewabilityHelper;

package/Lists/VirtualizeUtils.js

@@ -0,0 +1,245 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * @flow
+ * @format
+ */
+
+'use strict';
+
+import type ListMetricsAggregator, {
+  CellMetricProps,
+} from './ListMetricsAggregator';
+
+/**
+ * Used to find the indices of the frames that overlap the given offsets. Useful for finding the
+ * items that bound different windows of content, such as the visible area or the buffered overscan
+ * area.
+ */
+export function elementsThatOverlapOffsets(
+  offsets: Array<number>,
+  props: CellMetricProps,
+  listMetrics: ListMetricsAggregator,
+  zoomScale: number = 1,
+): Array<number> {
+  const itemCount = props.getItemCount(props.data);
+  const result = [];
+  for (let offsetIndex = 0; offsetIndex < offsets.length; offsetIndex++) {
+    const currentOffset = offsets[offsetIndex];
+    let left = 0;
+    let right = itemCount - 1;
+
+    while (left <= right) {
+      const mid = left + Math.floor((right - left) / 2);
+      const frame = listMetrics.getCellMetricsApprox(mid, props);
+      const scaledOffsetStart = frame.offset * zoomScale;
+      const scaledOffsetEnd = (frame.offset + frame.length) * zoomScale;
+
+      // We want the first frame that contains the offset, with inclusive bounds. Thus, for the
+      // first frame the scaledOffsetStart is inclusive, while for other frames it is exclusive.
+      if (
+        (mid === 0 && currentOffset < scaledOffsetStart) ||
+        (mid !== 0 && currentOffset <= scaledOffsetStart)
+      ) {
+        right = mid - 1;
+      } else if (currentOffset > scaledOffsetEnd) {
+        left = mid + 1;
+      } else {
+        result[offsetIndex] = mid;
+        break;
+      }
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Computes the number of elements in the `next` range that are new compared to the `prev` range.
+ * Handy for calculating how many new items will be rendered when the render window changes so we
+ * can restrict the number of new items render at once so that content can appear on the screen
+ * faster.
+ */
+export function newRangeCount(
+  prev: {
+    first: number,
+    last: number,
+    ...
+  },
+  next: {
+    first: number,
+    last: number,
+    ...
+  },
+): number {
+  return (
+    next.last -
+    next.first +
+    1 -
+    Math.max(
+      0,
+      1 + Math.min(next.last, prev.last) - Math.max(next.first, prev.first),
+    )
+  );
+}
+
+/**
+ * Custom logic for determining which items should be rendered given the current frame and scroll
+ * metrics, as well as the previous render state. The algorithm may evolve over time, but generally
+ * prioritizes the visible area first, then expands that with overscan regions ahead and behind,
+ * biased in the direction of scroll.
+ */
+export function computeWindowedRenderLimits(
+  props: CellMetricProps,
+  maxToRenderPerBatch: number,
+  windowSize: number,
+  prev: {
+    first: number,
+    last: number,
+  },
+  listMetrics: ListMetricsAggregator,
+  scrollMetrics: {
+    dt: number,
+    offset: number,
+    velocity: number,
+    visibleLength: number,
+    zoomScale: number,
+    ...
+  },
+): {
+  first: number,
+  last: number,
+} {
+  const itemCount = props.getItemCount(props.data);
+  if (itemCount === 0) {
+    return {first: 0, last: -1};
+  }
+  const {offset, velocity, visibleLength, zoomScale = 1} = scrollMetrics;
+
+  // Start with visible area, then compute maximum overscan region by expanding from there, biased
+  // in the direction of scroll. Total overscan area is capped, which should cap memory consumption
+  // too.
+  const visibleBegin = Math.max(0, offset);
+  const visibleEnd = visibleBegin + visibleLength;
+  const overscanLength = (windowSize - 1) * visibleLength;
+
+  // Considering velocity seems to introduce more churn than it's worth.
+  const leadFactor = 0.5; // Math.max(0, Math.min(1, velocity / 25 + 0.5));
+
+  const fillPreference =
+    velocity > 1 ? 'after' : velocity < -1 ? 'before' : 'none';
+
+  const overscanBegin = Math.max(
+    0,
+    visibleBegin - (1 - leadFactor) * overscanLength,
+  );
+  const overscanEnd = Math.max(0, visibleEnd + leadFactor * overscanLength);
+
+  const lastItemOffset =
+    listMetrics.getCellMetricsApprox(itemCount - 1, props).offset * zoomScale;
+  if (lastItemOffset < overscanBegin) {
+    // Entire list is before our overscan window
+    return {
+      first: Math.max(0, itemCount - 1 - maxToRenderPerBatch),
+      last: itemCount - 1,
+    };
+  }
+
+  // Find the indices that correspond to the items at the render boundaries we're targeting.
+  let [overscanFirst, first, last, overscanLast] = elementsThatOverlapOffsets(
+    [overscanBegin, visibleBegin, visibleEnd, overscanEnd],
+    props,
+    listMetrics,
+    zoomScale,
+  );
+  overscanFirst = overscanFirst == null ? 0 : overscanFirst;
+  first = first == null ? Math.max(0, overscanFirst) : first;
+  overscanLast = overscanLast == null ? itemCount - 1 : overscanLast;
+  last =
+    last == null
+      ? Math.min(overscanLast, first + maxToRenderPerBatch - 1)
+      : last;
+  const visible = {first, last};
+
+  // We want to limit the number of new cells we're rendering per batch so that we can fill the
+  // content on the screen quickly. If we rendered the entire overscan window at once, the user
+  // could be staring at white space for a long time waiting for a bunch of offscreen content to
+  // render.
+  let newCellCount = newRangeCount(prev, visible);
+
+  while (true) {
+    if (first <= overscanFirst && last >= overscanLast) {
+      // If we fill the entire overscan range, we're done.
+      break;
+    }
+    const maxNewCells = newCellCount >= maxToRenderPerBatch;
+    const firstWillAddMore = first <= prev.first || first > prev.last;
+    const firstShouldIncrement =
+      first > overscanFirst && (!maxNewCells || !firstWillAddMore);
+    const lastWillAddMore = last >= prev.last || last < prev.first;
+    const lastShouldIncrement =
+      last < overscanLast && (!maxNewCells || !lastWillAddMore);
+    if (maxNewCells && !firstShouldIncrement && !lastShouldIncrement) {
+      // We only want to stop if we've hit maxNewCells AND we cannot increment first or last
+      // without rendering new items. This let's us preserve as many already rendered items as
+      // possible, reducing render churn and keeping the rendered overscan range as large as
+      // possible.
+      break;
+    }
+    if (
+      firstShouldIncrement &&
+      !(fillPreference === 'after' && lastShouldIncrement && lastWillAddMore)
+    ) {
+      if (firstWillAddMore) {
+        newCellCount++;
+      }
+      first--;
+    }
+    if (
+      lastShouldIncrement &&
+      !(fillPreference === 'before' && firstShouldIncrement && firstWillAddMore)
+    ) {
+      if (lastWillAddMore) {
+        newCellCount++;
+      }
+      last++;
+    }
+  }
+  if (
+    !(
+      last >= first &&
+      first >= 0 &&
+      last < itemCount &&
+      first >= overscanFirst &&
+      last <= overscanLast &&
+      first <= visible.first &&
+      last >= visible.last
+    )
+  ) {
+    throw new Error(
+      'Bad window calculation ' +
+        JSON.stringify({
+          first,
+          last,
+          itemCount,
+          overscanFirst,
+          overscanLast,
+          visible,
+        }),
+    );
+  }
+  return {first, last};
+}
+
+export function keyExtractor(item: any, index: number): string {
+  if (typeof item === 'object' && item?.key != null) {
+    return item.key;
+  }
+  if (typeof item === 'object' && item?.id != null) {
+    return item.id;
+  }
+  return String(index);
+}