@react-native-tvos/virtualized-lists 0.73.4

package/Interaction/Batchinator.js

@@ -0,0 +1,76 @@
+/**
+ * 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.
+ *
+ * @format
+ * @flow strict-local
+ */
+
+'use strict';
+
+const {InteractionManager} = require('react-native');
+
+/**
+ * A simple class for batching up invocations of a low-pri callback. A timeout is set to run the
+ * callback once after a delay, no matter how many times it's scheduled. Once the delay is reached,
+ * InteractionManager.runAfterInteractions is used to invoke the callback after any hi-pri
+ * interactions are done running.
+ *
+ * Make sure to cleanup with dispose().  Example:
+ *
+ *   class Widget extends React.Component {
+ *     _batchedSave: new Batchinator(() => this._saveState, 1000);
+ *     _saveSate() {
+ *       // save this.state to disk
+ *     }
+ *     componentDidUpdate() {
+ *       this._batchedSave.schedule();
+ *     }
+ *     componentWillUnmount() {
+ *       this._batchedSave.dispose();
+ *     }
+ *     ...
+ *   }
+ */
+class Batchinator {
+  _callback: () => void;
+  _delay: number;
+  _taskHandle: ?{cancel: () => void, ...};
+  constructor(callback: () => void, delayMS: number) {
+    this._delay = delayMS;
+    this._callback = callback;
+  }
+  /*
+   * Cleanup any pending tasks.
+   *
+   * By default, if there is a pending task the callback is run immediately. Set the option abort to
+   * true to not call the callback if it was pending.
+   */
+  dispose(options: {abort: boolean, ...} = {abort: false}) {
+    if (this._taskHandle) {
+      this._taskHandle.cancel();
+      if (!options.abort) {
+        this._callback();
+      }
+      this._taskHandle = null;
+    }
+  }
+  schedule() {
+    if (this._taskHandle) {
+      return;
+    }
+    const timeoutHandle = setTimeout(() => {
+      this._taskHandle = InteractionManager.runAfterInteractions(() => {
+        // Note that we clear the handle before invoking the callback so that if the callback calls
+        // schedule again, it will actually schedule another task.
+        this._taskHandle = null;
+        this._callback();
+      });
+    }, this._delay);
+    this._taskHandle = {cancel: () => clearTimeout(timeoutHandle)};
+  }
+}
+
+module.exports = Batchinator;

package/Lists/CellRenderMask.js

@@ -0,0 +1,155 @@
+/**
+ * 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 strict
+ * @format
+ */
+
+import invariant from 'invariant';
+
+export type CellRegion = {
+  first: number,
+  last: number,
+  isSpacer: boolean,
+};
+
+export class CellRenderMask {
+  _numCells: number;
+  _regions: Array<CellRegion>;
+
+  constructor(numCells: number) {
+    invariant(
+      numCells >= 0,
+      'CellRenderMask must contain a non-negative number os cells',
+    );
+
+    this._numCells = numCells;
+
+    if (numCells === 0) {
+      this._regions = [];
+    } else {
+      this._regions = [
+        {
+          first: 0,
+          last: numCells - 1,
+          isSpacer: true,
+        },
+      ];
+    }
+  }
+
+  enumerateRegions(): $ReadOnlyArray<CellRegion> {
+    return this._regions;
+  }
+
+  addCells(cells: {first: number, last: number}): void {
+    invariant(
+      cells.first >= 0 &&
+        cells.first < this._numCells &&
+        cells.last >= -1 &&
+        cells.last < this._numCells &&
+        cells.last >= cells.first - 1,
+      'CellRenderMask.addCells called with invalid cell range',
+    );
+
+    // VirtualizedList uses inclusive ranges, where zero-count states are
+    // possible. E.g. [0, -1] for no cells, starting at 0.
+    if (cells.last < cells.first) {
+      return;
+    }
+
+    const [firstIntersect, firstIntersectIdx] = this._findRegion(cells.first);
+    const [lastIntersect, lastIntersectIdx] = this._findRegion(cells.last);
+
+    // Fast-path if the cells to add are already all present in the mask. We
+    // will otherwise need to do some mutation.
+    if (firstIntersectIdx === lastIntersectIdx && !firstIntersect.isSpacer) {
+      return;
+    }
+
+    // We need to replace the existing covered regions with 1-3 new regions
+    // depending whether we need to split spacers out of overlapping regions.
+    const newLeadRegion: Array<CellRegion> = [];
+    const newTailRegion: Array<CellRegion> = [];
+    const newMainRegion: CellRegion = {
+      ...cells,
+      isSpacer: false,
+    };
+
+    if (firstIntersect.first < newMainRegion.first) {
+      if (firstIntersect.isSpacer) {
+        newLeadRegion.push({
+          first: firstIntersect.first,
+          last: newMainRegion.first - 1,
+          isSpacer: true,
+        });
+      } else {
+        newMainRegion.first = firstIntersect.first;
+      }
+    }
+
+    if (lastIntersect.last > newMainRegion.last) {
+      if (lastIntersect.isSpacer) {
+        newTailRegion.push({
+          first: newMainRegion.last + 1,
+          last: lastIntersect.last,
+          isSpacer: true,
+        });
+      } else {
+        newMainRegion.last = lastIntersect.last;
+      }
+    }
+
+    const replacementRegions: Array<CellRegion> = [
+      ...newLeadRegion,
+      newMainRegion,
+      ...newTailRegion,
+    ];
+    const numRegionsToDelete = lastIntersectIdx - firstIntersectIdx + 1;
+    this._regions.splice(
+      firstIntersectIdx,
+      numRegionsToDelete,
+      ...replacementRegions,
+    );
+  }
+
+  numCells(): number {
+    return this._numCells;
+  }
+
+  equals(other: CellRenderMask): boolean {
+    return (
+      this._numCells === other._numCells &&
+      this._regions.length === other._regions.length &&
+      this._regions.every(
+        (region, i) =>
+          region.first === other._regions[i].first &&
+          region.last === other._regions[i].last &&
+          region.isSpacer === other._regions[i].isSpacer,
+      )
+    );
+  }
+
+  _findRegion(cellIdx: number): [CellRegion, number] {
+    let firstIdx = 0;
+    let lastIdx = this._regions.length - 1;
+
+    while (firstIdx <= lastIdx) {
+      const middleIdx = Math.floor((firstIdx + lastIdx) / 2);
+      const middleRegion = this._regions[middleIdx];
+
+      if (cellIdx >= middleRegion.first && cellIdx <= middleRegion.last) {
+        return [middleRegion, middleIdx];
+      } else if (cellIdx < middleRegion.first) {
+        lastIdx = middleIdx - 1;
+      } else if (cellIdx > middleRegion.last) {
+        firstIdx = middleIdx + 1;
+      }
+    }
+
+    invariant(false, `A region was not found containing cellIdx ${cellIdx}`);
+  }
+}

package/Lists/ChildListCollection.js

@@ -0,0 +1,72 @@
+/**
+ * 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 strict
+ * @format
+ */
+
+import invariant from 'invariant';
+
+export default class ChildListCollection<TList> {
+  _cellKeyToChildren: Map<string, Set<TList>> = new Map();
+  _childrenToCellKey: Map<TList, string> = new Map();
+
+  add(list: TList, cellKey: string): void {
+    invariant(
+      !this._childrenToCellKey.has(list),
+      'Trying to add already present child list',
+    );
+
+    const cellLists = this._cellKeyToChildren.get(cellKey) ?? new Set();
+    cellLists.add(list);
+    this._cellKeyToChildren.set(cellKey, cellLists);
+
+    this._childrenToCellKey.set(list, cellKey);
+  }
+
+  remove(list: TList): void {
+    const cellKey = this._childrenToCellKey.get(list);
+    invariant(cellKey != null, 'Trying to remove non-present child list');
+    this._childrenToCellKey.delete(list);
+
+    const cellLists = this._cellKeyToChildren.get(cellKey);
+    invariant(cellLists, '_cellKeyToChildren should contain cellKey');
+    cellLists.delete(list);
+
+    if (cellLists.size === 0) {
+      this._cellKeyToChildren.delete(cellKey);
+    }
+  }
+
+  forEach(fn: TList => void): void {
+    for (const listSet of this._cellKeyToChildren.values()) {
+      for (const list of listSet) {
+        fn(list);
+      }
+    }
+  }
+
+  forEachInCell(cellKey: string, fn: TList => void): void {
+    const listSet = this._cellKeyToChildren.get(cellKey) ?? [];
+    for (const list of listSet) {
+      fn(list);
+    }
+  }
+
+  anyInCell(cellKey: string, fn: TList => boolean): boolean {
+    const listSet = this._cellKeyToChildren.get(cellKey) ?? [];
+    for (const list of listSet) {
+      if (fn(list)) {
+        return true;
+      }
+    }
+    return false;
+  }
+
+  size(): number {
+    return this._childrenToCellKey.size;
+  }
+}

package/Lists/FillRateHelper.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 {CellMetricProps} from './ListMetricsAggregator';
+import ListMetricsAggregator from './ListMetricsAggregator';
+
+export type FillRateInfo = Info;
+
+class Info {
+  any_blank_count: number = 0;
+  any_blank_ms: number = 0;
+  any_blank_speed_sum: number = 0;
+  mostly_blank_count: number = 0;
+  mostly_blank_ms: number = 0;
+  pixels_blank: number = 0;
+  pixels_sampled: number = 0;
+  pixels_scrolled: number = 0;
+  total_time_spent: number = 0;
+  sample_count: number = 0;
+}
+
+const DEBUG = false;
+
+let _listeners: Array<(Info) => void> = [];
+let _minSampleCount = 10;
+let _sampleRate = DEBUG ? 1 : null;
+
+/**
+ * A helper class for detecting when the maximem fill rate of `VirtualizedList` is exceeded.
+ * By default the sampling rate is set to zero and this will do nothing. If you want to collect
+ * samples (e.g. to log them), make sure to call `FillRateHelper.setSampleRate(0.0-1.0)`.
+ *
+ * Listeners and sample rate are global for all `VirtualizedList`s - typical usage will combine with
+ * `SceneTracker.getActiveScene` to determine the context of the events.
+ */
+class FillRateHelper {
+  _anyBlankStartTime: ?number = null;
+  _enabled = false;
+  _listMetrics: ListMetricsAggregator;
+  _info: Info = new Info();
+  _mostlyBlankStartTime: ?number = null;
+  _samplesStartTime: ?number = null;
+
+  static addListener(callback: FillRateInfo => void): {
+    remove: () => void,
+    ...
+  } {
+    if (_sampleRate === null) {
+      console.warn('Call `FillRateHelper.setSampleRate` before `addListener`.');
+    }
+    _listeners.push(callback);
+    return {
+      remove: () => {
+        _listeners = _listeners.filter(listener => callback !== listener);
+      },
+    };
+  }
+
+  static setSampleRate(sampleRate: number) {
+    _sampleRate = sampleRate;
+  }
+
+  static setMinSampleCount(minSampleCount: number) {
+    _minSampleCount = minSampleCount;
+  }
+
+  constructor(listMetrics: ListMetricsAggregator) {
+    this._listMetrics = listMetrics;
+    this._enabled = (_sampleRate || 0) > Math.random();
+    this._resetData();
+  }
+
+  activate() {
+    if (this._enabled && this._samplesStartTime == null) {
+      DEBUG && console.debug('FillRateHelper: activate');
+      this._samplesStartTime = global.performance.now();
+    }
+  }
+
+  deactivateAndFlush() {
+    if (!this._enabled) {
+      return;
+    }
+    const start = this._samplesStartTime; // const for flow
+    if (start == null) {
+      DEBUG &&
+        console.debug('FillRateHelper: bail on deactivate with no start time');
+      return;
+    }
+    if (this._info.sample_count < _minSampleCount) {
+      // Don't bother with under-sampled events.
+      this._resetData();
+      return;
+    }
+    const total_time_spent = global.performance.now() - start;
+    const info: any = {
+      ...this._info,
+      total_time_spent,
+    };
+    if (DEBUG) {
+      const derived = {
+        avg_blankness: this._info.pixels_blank / this._info.pixels_sampled,
+        avg_speed: this._info.pixels_scrolled / (total_time_spent / 1000),
+        avg_speed_when_any_blank:
+          this._info.any_blank_speed_sum / this._info.any_blank_count,
+        any_blank_per_min:
+          this._info.any_blank_count / (total_time_spent / 1000 / 60),
+        any_blank_time_frac: this._info.any_blank_ms / total_time_spent,
+        mostly_blank_per_min:
+          this._info.mostly_blank_count / (total_time_spent / 1000 / 60),
+        mostly_blank_time_frac: this._info.mostly_blank_ms / total_time_spent,
+      };
+      for (const key in derived) {
+        // $FlowFixMe[prop-missing]
+        derived[key] = Math.round(1000 * derived[key]) / 1000;
+      }
+      console.debug('FillRateHelper deactivateAndFlush: ', {derived, info});
+    }
+    _listeners.forEach(listener => listener(info));
+    this._resetData();
+  }
+
+  computeBlankness(
+    props: {
+      ...CellMetricProps,
+      initialNumToRender?: ?number,
+      ...
+    },
+    cellsAroundViewport: {
+      first: number,
+      last: number,
+      ...
+    },
+    scrollMetrics: {
+      dOffset: number,
+      offset: number,
+      velocity: number,
+      visibleLength: number,
+      ...
+    },
+  ): number {
+    if (
+      !this._enabled ||
+      props.getItemCount(props.data) === 0 ||
+      cellsAroundViewport.last < cellsAroundViewport.first ||
+      this._samplesStartTime == null
+    ) {
+      return 0;
+    }
+    const {dOffset, offset, velocity, visibleLength} = scrollMetrics;
+
+    // Denominator metrics that we track for all events - most of the time there is no blankness and
+    // we want to capture that.
+    this._info.sample_count++;
+    this._info.pixels_sampled += Math.round(visibleLength);
+    this._info.pixels_scrolled += Math.round(Math.abs(dOffset));
+    const scrollSpeed = Math.round(Math.abs(velocity) * 1000); // px / sec
+
+    // Whether blank now or not, record the elapsed time blank if we were blank last time.
+    const now = global.performance.now();
+    if (this._anyBlankStartTime != null) {
+      this._info.any_blank_ms += now - this._anyBlankStartTime;
+    }
+    this._anyBlankStartTime = null;
+    if (this._mostlyBlankStartTime != null) {
+      this._info.mostly_blank_ms += now - this._mostlyBlankStartTime;
+    }
+    this._mostlyBlankStartTime = null;
+
+    let blankTop = 0;
+    let first = cellsAroundViewport.first;
+    let firstFrame = this._listMetrics.getCellMetrics(first, props);
+    while (
+      first <= cellsAroundViewport.last &&
+      (!firstFrame || !firstFrame.isMounted)
+    ) {
+      firstFrame = this._listMetrics.getCellMetrics(first, props);
+      first++;
+    }
+    // Only count blankTop if we aren't rendering the first item, otherwise we will count the header
+    // as blank.
+    if (firstFrame && first > 0) {
+      blankTop = Math.min(
+        visibleLength,
+        Math.max(0, firstFrame.offset - offset),
+      );
+    }
+    let blankBottom = 0;
+    let last = cellsAroundViewport.last;
+    let lastFrame = this._listMetrics.getCellMetrics(last, props);
+    while (
+      last >= cellsAroundViewport.first &&
+      (!lastFrame || !lastFrame.isMounted)
+    ) {
+      lastFrame = this._listMetrics.getCellMetrics(last, props);
+      last--;
+    }
+    // Only count blankBottom if we aren't rendering the last item, otherwise we will count the
+    // footer as blank.
+    if (lastFrame && last < props.getItemCount(props.data) - 1) {
+      const bottomEdge = lastFrame.offset + lastFrame.length;
+      blankBottom = Math.min(
+        visibleLength,
+        Math.max(0, offset + visibleLength - bottomEdge),
+      );
+    }
+    const pixels_blank = Math.round(blankTop + blankBottom);
+    const blankness = pixels_blank / visibleLength;
+    if (blankness > 0) {
+      this._anyBlankStartTime = now;
+      this._info.any_blank_speed_sum += scrollSpeed;
+      this._info.any_blank_count++;
+      this._info.pixels_blank += pixels_blank;
+      if (blankness > 0.5) {
+        this._mostlyBlankStartTime = now;
+        this._info.mostly_blank_count++;
+      }
+    } else if (scrollSpeed < 0.01 || Math.abs(dOffset) < 1) {
+      this.deactivateAndFlush();
+    }
+    return blankness;
+  }
+
+  enabled(): boolean {
+    return this._enabled;
+  }
+
+  _resetData() {
+    this._anyBlankStartTime = null;
+    this._info = new Info();
+    this._mostlyBlankStartTime = null;
+    this._samplesStartTime = null;
+  }
+}
+
+module.exports = FillRateHelper;