@hps1978/react-native-web-tv 0.21.2-tv.0

package/src/vendor/react-native/VirtualizedList/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 'fbjs/lib/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/src/vendor/react-native/VirtualizedList/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 'fbjs/lib/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/src/vendor/react-native/VirtualizedList/RLV_ADAPTER_STATUS.md

@@ -0,0 +1,257 @@
+# RLV Adapter Implementation Status
+
+## Overview
+
+**Purpose:** Bridge React Native `FlatList` → `VirtualizedList` → `RecyclerListView` for high-performance web virtualization with TV support.
+
+**Component:** `VirtualizedListRLVAdapter`  
+**Current Phase:** Core implementation complete; TV features pending  
+**Last Updated:** February 1, 2026  
+**Key Dependencies:** 
+- `recyclerlistview` - High-performance list virtualization engine
+- `StyleSheet` - React Native Web styling system
+
+---
+
+## Architectural Overview
+
+```
+FlatList (React Native)
+    ↓
+VirtualizedList (RNW adapter)
+    ↓
+VirtualizedListRLVAdapter (This file)
+    ├─ RNWDataProvider (wraps data for RLV)
+    ├─ RNWLayoutProvider (converts RN layout to RLV format) -> Uses GridLayoutProvider for grid
+    └─ RecyclerListView (core virtualization engine)
+```
+
+**Data Flow:**
+1. Props accepted from parent (FlatList or VirtualizedList)
+2. Data/Layout providers normalize to RecyclerListView API
+3. RLV renders visible items via rowRenderer callback
+4. Scroll/viewability events normalized back to React Native format
+
+---
+
+## Implementation Status by Prop
+
+### Data Management
+
+| Prop | Type | Status | Notes |
+|------|------|--------|-------|
+| `data` | `array` | ✅ Full | Stored in RNWDataProvider; supports any array |
+| `rowHasChanged` | `(r1, r2) => boolean` | ✅ Full | Custom change detection; defaults to `r1 !== r2`. Added only for RLV for better App control on data change  |
+| `getItem` | `(data, index) => item` | ✅ Full | Direct array access; `getItem(data, i) = data[i]` |
+| `getItemCount` | `(data) => number` | ✅ Full | Returns `data.length` or 0 |
+| `extraData` | `any` | ✅ Full | Passed to RLV as `extendedState` for re-render triggers |
+
+**Implementation Details:**
+- `RNWDataProvider` wraps raw data with header/footer markers
+- Index mapping: `getItemMetaForIndex()` translates RLV indices to data items
+- Header/footer are synthetic items (not in original data array)
+- Empty state: Renders synthetic empty item when `data.length === 0`
+
+---
+
+### Layout & Sizing
+
+| Prop | Type | Status | Notes |
+|------|------|--------|-------|
+| `getItemLayout` | `(data, index) => {length, offset}` | ✅ Full | Converted to RLV dimension format |
+| `layoutProvider` | `RLVLayoutProvider` | ✅ Full | **Preferred** over `getItemLayout`; full RLV API support. Added only for RLV for better layout feature support |
+| `rowHasChanged` | `(r1, r2) => boolean` | ✅ Full |  Added only for RLV to allow better App control over data change. Falls back to r1 !== r1 |
+| `_numColumns` | `number` | ✅ Grid | Enables `GridLayoutProvider` when `> 1` |
+| `horizontal` | `boolean` | ✅ Full | Passed to RLV; affects layout direction & scroll axis |
+
+**Implementation Details:**
+- `RNWLayoutProvider` extends/wraps RecyclerListView layout classes
+- **Format conversion:** RN's `{length, offset}` → RLV's `{width, height}`
+  - **Vertical (default):** `length` = height along scroll axis; width = container width
+  - **Horizontal:** `length` = width along scroll axis; height = container height
+- **Grid mode:** `_numColumns > 1` activates `GridLayoutProvider` with per-column span logic
+- **Header/Footer measurement:** Heights captured via `getBoundingClientRect()` post-render
+
+---
+
+### Rendering & Content
+
+| Prop | Type | Status | Notes |
+|------|------|--------|-------|
+| `renderItem` | `({item, index, separators}) => ReactNode` | ✅ Full | Wrapped by `_rowRenderer` for RLV compatibility |
+| `ListItemComponent` | `Component` | ✅ Full | Fallback when `renderItem` not provided |
+| `ListHeaderComponent` | `Component \| function` | ✅ Full | Virtualized as synthetic header; measured on mount |
+| `ListFooterComponent` | `Component \| function` | ✅ Full | Virtualized as synthetic footer; measured on mount |
+| `ListEmptyComponent` | `Component \| function` | ✅ Full | Renders when `data.length === 0` |
+| `ItemSeparatorComponent` | `Component` | ✅ Full | Rendered between items (excludes header/footer) |
+
+**Implementation Details:**
+- `_rowRenderer()` dispatches based on `type` (header/footer/item/empty)
+- Header/footer rendered once, measured via offscreen container
+- Separators attached to each item in `_rowRenderer`, not virtualized separately
+- Empty component wrapped in full-height `View` to fill container
+
+---
+
+### Scroll Behavior
+
+| Prop | Type | Status | Notes |
+|------|------|--------|-------|
+| `horizontal` | `boolean` | ✅ Full | Passed to RLV & scroll props |
+| `scrollEnabled` | `boolean` | ⚠️ To be tested | Passed to `scrollViewProps` |
+| `inverted` | `boolean` | ⚠️ To be tested | Passed to `scrollViewProps` |
+| `onScroll` | `(event) => void` | ✅ Full | Normalized & throttled event emission |
+| `scrollEventThrottle` | `number` | ✅ Full | Throttles scroll event fires (ms) |
+| `showsHorizontalScrollIndicator` | `boolean` | ✅ Full | Passed to `scrollViewProps` |
+| `showsVerticalScrollIndicator` | `boolean` | ✅ Full | Passed to `scrollViewProps` |
+| `nestedScrollEnabled` | `boolean` | ⚠️ To be tested | Passed to `scrollViewProps` |
+
+**Implementation Details:**
+- `_handleScroll()` receives RLV offset events, normalizes to React Native format
+- Throttle: Skip events if `now - lastTick < scrollEventThrottle`
+- Event normalization: `{nativeEvent: {contentOffset, contentSize, layoutMeasurement}}`
+- Scroll metrics stored in ref (not state) to avoid re-renders
+
+---
+
+### Viewability & Item Visibility
+
+| Prop | Type | Status | Notes |
+|------|------|--------|-------|
+| `onViewableItemsChanged` | `(info: {viewableItems, changed}) => void` | ⚠️ Partial | Implemented but needs refinement |
+| `viewabilityConfig` | `{itemVisiblePercentThreshold: number, ...}` | ⚠️ Partial | Uses `ViewabilityHelper`; may not align perfectly with RLV behavior |
+| `viewabilityConfigCallbackPairs` | `Array<{viewabilityConfig, onViewableItemsChanged}>` | ⚠️ Partial | First pair only; multiple callbacks untested |
+
+**Implementation Details:**
+- `ViewabilityHelper` called on scroll to determine visible items
+- Fallback to `DEFAULT_VIEWABILITY_CONFIG` if not provided
+- **Caveat:** RLV's item lifecycle may differ from React Native's; viewability calculation may be approximate
+
+---
+
+### Styling & Container
+
+| Prop | Type | Status | Notes |
+|------|------|--------|-------|
+| `style` | `StyleObj` | ✅ Full | Applied to outer `View` container |
+| `columnWrapperStyle` | `StyleObj` | ⚠️ Not implemented | Challenges on how this can be implemented |
+
+**Implementation Details:**
+- Container has `flex: 1` by default
+- RLV wrapper also has `flex: 1` to fill parent
+
+---
+
+### TV & Focus Features
+
+**Implementation Details:**
+- No direct change required for handling focus
+
+---
+
+## Server-Side Rendering (SSR)
+
+| Aspect | Status | Notes |
+|--------|--------|-------|
+| Initial Render | ✅ Pass | Renders placeholder `<View>` on server |
+| Client Hydration | ✅ Pass | RLV initializes after mount; SSR mismatch acceptable |
+| Next.js Compatibility | ✅ Pass | Lazy `require()` prevents RLV load on server |
+
+**Implementation Details:**
+- `if (typeof window === 'undefined')` guard in render; returns empty `View`
+- `ensureRLVLoaded()` uses try-catch for safe lazy loading
+- RecyclerListView only activates on client side
+
+---
+
+## Known Limitations & Open Issues
+
+### Current Limitations
+
+1. **Viewability Calculation** – Simplified; may not perfectly match React Native behavior on all edge cases
+2. **Header/Footer Measurement** – Causes layout shift on first render (header/footer measured post-mount)
+3. **Multiple Viewability Callbacks** – Only first pair in `viewabilityConfigCallbackPairs` is used
+4. **Scroll Position Restoration** – Not yet implemented for list unmount/remount
+5. **Sticky Headers** – Not supported by current RLV integration
+
+### Planned Improvements (Phase 2)
+
+- [ ] Scroll position memory for navigation back to list
+- [ ] Multiple viewability callback pairs support
+- [ ] Sticky header support (if RLV provides)
+- [ ] Accessibility improvements (ARIA labels, semantic HTML)
+
+---
+
+## Testing Status
+
+| Scenario | Status | Notes |
+|----------|--------|-------|
+| Basic list virtualization | ✅ Pass | Items render & unmount correctly |
+| Grid layout (numColumns > 1) | ✅ Pass | GridLayoutProvider active; columns render |
+| Header/Footer virtualization | ✅ Pass | Measured and cached; appears in correct position |
+| Scroll events | ✅ Pass | Normalized events match React Native format |
+| Throttled scroll | ✅ Pass | Events throttled per `scrollEventThrottle` |
+| Empty state | ✅ Pass | `ListEmptyComponent` renders when data.length === 0 |
+| Separator rendering | ✅ Pass | Separators between items; excluded from header/footer |
+| Item key stability | ⚠️ Partial | Uses index-based keys; may cause issues with dynamic data |
+| Large datasets (2k+ items) | ⚠️ Partial | Profiling available through performance test examples |
+| Complex nested layouts | ⏳ TBD | Real-world testing needed |
+| Horizontal scroll | ⏳ TBD | Basic support present; edge cases untested |
+
+---
+
+## Implementation Files
+
+| File / Class | Purpose |
+|------|---------|
+| `VirtualizedListRLVAdapter.js` | Main adapter class; props bridge & RLV integration |
+| `RNWDataProvider` (inner class) | Wraps data for RLV; handles header/footer indexing |
+| `RNWLayoutProvider` (inner class) | Converts RN layout format to RLV dimensions |
+| `getItemMetaForIndex()` (helper) | Maps RLV index to data/header/footer/empty |
+| `normalizeScrollEvent()` (helper) | Converts RLV scroll format to React Native |
+| `getTotalSize()` (helper) | Calculates total virtualized items (data + header + footer + empty) |
+
+---
+
+## Grid specific notes:
+Grid Layout implementation using RLV grid feature requried exposure to additional props (already available to FlatList):
+        
+1. _originalRenderItem: props.renderItem 
+2. _numColumns: numColumns
+3. _columnWrapperStyle: columnWrapperStyle ⚠️ Not utilized yet so will have visual impacts if App provides it 
+
+
+## Usage Examples
+
+### Basic FlatList with RLV Adapter
+
+```javascript
+<FlatList
+  data={items}
+  renderItem={({item}) => <ItemView item={item} />}
+  keyExtractor={(item, idx) => idx}
+  ListHeaderComponent={<HeaderView />}
+  ListFooterComponent={<FooterView />}
+/>
+```
+
+### Grid Layout
+
+```javascript
+<FlatList
+  data={items}
+  renderItem={({item}) => <GridCell item={item} />}
+  numColumns={3}
+  layoutProvider={() => ({
+      getLayoutTypeForIndex: (index) => return 'item',
+      getDimensionForType: () => ({
+        width: itemWidth,
+        height: ITEM_HEIGHT
+      })
+    })}
+/>
+```
+
+---
+

package/src/vendor/react-native/VirtualizedList/StateSafePureComponent.js

@@ -0,0 +1,85 @@
+/**
+ * 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 'fbjs/lib/invariant';
+import * as React from 'react';
+
+/**
+ * `setState` is called asynchronously, and should not rely on the value of
+ * `this.props` or `this.state`:
+ * https://reactjs.org/docs/state-and-lifecycle.html#state-updates-may-be-asynchronous
+ *
+ * SafePureComponent adds runtime enforcement, to catch cases where these
+ * variables are read in a state updater function, instead of the ones passed
+ * in.
+ */
+export default class StateSafePureComponent<
+  Props,
+  State: interface {},
+> extends React.PureComponent<Props, State> {
+  _inAsyncStateUpdate = false;
+
+  constructor(props: Props) {
+    super(props);
+    this._installSetStateHooks();
+  }
+
+  setState(
+    partialState: ?($Shape<State> | ((State, Props) => ?$Shape<State>)),
+    callback?: () => mixed,
+  ): void {
+    if (typeof partialState === 'function') {
+      super.setState((state, props) => {
+        this._inAsyncStateUpdate = true;
+        let ret;
+        try {
+          ret = partialState(state, props);
+        } catch (err) {
+          throw err;
+        } finally {
+          this._inAsyncStateUpdate = false;
+        }
+        return ret;
+      }, callback);
+    } else {
+      super.setState(partialState, callback);
+    }
+  }
+
+  _installSetStateHooks() {
+    const that = this;
+    let {props, state} = this;
+
+    Object.defineProperty(this, 'props', {
+      get() {
+        invariant(
+          !that._inAsyncStateUpdate,
+          '"this.props" should not be accessed during state updates',
+        );
+        return props;
+      },
+      set(newProps: Props) {
+        props = newProps;
+      },
+    });
+    Object.defineProperty(this, 'state', {
+      get() {
+        invariant(
+          !that._inAsyncStateUpdate,
+          '"this.state" should not be acceessed during state updates',
+        );
+        return state;
+      },
+      set(newState: State) {
+        state = newState;
+      },
+    });
+  }
+}