Move VirtualCollection components into react-native-github (#56256)

Summary:
Pull Request resolved: https://github.com/facebook/react-native/pull/56256

Moves the core Fling virtual collection components (VirtualRow, VirtualColumn,
VirtualCollectionView, and supporting files) from xplat/js/RKJSModules/Libraries/List/ into xplat/js/react-native-github/packages/react-native/src/private/components/virtualcollection/.

Updated 40 consumer files to import from 'react-native' instead of Haste and regenerated BUCK files

# Changelog: [Internal]

Key changes:
- Moved 10 files (Virtual, VirtualCollectionView, FlingConstants, VirtualColumn,
  VirtualColumnGenerator, VirtualRow, VirtualRowGenerator, FlingDebugItemOverlay,
  getScrollParent, isScrollableNode) into react-native-github
- Resolved all fb_internal imports (ReactNativeElement, ReadOnlyElement,
  ReactNativeFeatureFlags, createHiddenVirtualView) to use relative paths
  within src/private/
- Converted copyright headers from proprietary to MIT license
- Added public re-exports to react-native index.js and index.js.flow
  (VirtualColumn, VirtualRow, VirtualArray, VirtualCollection, VirtualItem,
  createVirtualCollectionView, VirtualColumnGenerator, getScrollParent,
  DEFAULT_INITIAL_NUM_TO_RENDER)

Reviewed By: mdvacca, lunaleaps

Differential Revision: D98039999

fbshipit-source-id: c0164f6933f19225fafc001cc0049d534032f2b2
This commit is contained in:
Calix Tang authored and meta-codesync[bot] committed 2026-03-30 17:00:16 -07:00
1 parent 6747cd2a6c
commit 231d53ac13
12 files changed
+674

No files matched your search

+28
View File
@@ -157,6 +157,34 @@ module.exports = {
get unstable_VirtualView() {
return require('./src/private/components/virtualview/VirtualView').default;
},
get unstable_VirtualArray() {
return require('./src/private/components/virtualcollection/Virtual')
.VirtualArray;
},
get unstable_createVirtualCollectionView() {
return require('./src/private/components/virtualcollection/VirtualCollectionView')
.createVirtualCollectionView;
},
get unstable_VirtualColumn() {
return require('./src/private/components/virtualcollection/column/VirtualColumn')
.default;
},
get unstable_VirtualColumnGenerator() {
return require('./src/private/components/virtualcollection/column/VirtualColumnGenerator')
.default;
},
get unstable_VirtualRow() {
return require('./src/private/components/virtualcollection/row/VirtualRow')
.default;
},
get unstable_getScrollParent() {
return require('./src/private/components/virtualcollection/dom/getScrollParent')
.default;
},
get unstable_DEFAULT_INITIAL_NUM_TO_RENDER() {
return require('./src/private/components/virtualcollection/FlingConstants')
.DEFAULT_INITIAL_NUM_TO_RENDER;
},
// #endregion
// #region APIs
get AccessibilityInfo() {
+17
View File
@@ -476,4 +476,21 @@ export {
} from './src/private/components/virtualview/VirtualView';
export type {ModeChangeEvent} from './src/private/components/virtualview/VirtualView';
export {VirtualArray as unstable_VirtualArray} from './src/private/components/virtualcollection/Virtual';
export type {
Item as unstable_VirtualItem,
VirtualCollection as unstable_VirtualCollection,
} from './src/private/components/virtualcollection/Virtual';
export {createVirtualCollectionView as unstable_createVirtualCollectionView} from './src/private/components/virtualcollection/VirtualCollectionView';
export type {
VirtualCollectionGenerator as unstable_VirtualCollectionGenerator,
VirtualCollectionLayoutComponent as unstable_VirtualCollectionLayoutComponent,
VirtualCollectionViewComponent as unstable_VirtualCollectionViewComponent,
} from './src/private/components/virtualcollection/VirtualCollectionView';
export {default as unstable_VirtualColumn} from './src/private/components/virtualcollection/column/VirtualColumn';
export {default as unstable_VirtualColumnGenerator} from './src/private/components/virtualcollection/column/VirtualColumnGenerator';
export {default as unstable_VirtualRow} from './src/private/components/virtualcollection/row/VirtualRow';
export {default as unstable_getScrollParent} from './src/private/components/virtualcollection/dom/getScrollParent';
export {DEFAULT_INITIAL_NUM_TO_RENDER as unstable_DEFAULT_INITIAL_NUM_TO_RENDER} from './src/private/components/virtualcollection/FlingConstants';
// #endregion
@@ -0,0 +1,21 @@
/**
* 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-local
* @format
*/
import Dimensions from '../../../../Libraries/Utilities/Dimensions';
export const DEFAULT_INITIAL_NUM_TO_RENDER = 7;
export const INITIAL_NUM_TO_RENDER: number = DEFAULT_INITIAL_NUM_TO_RENDER;
export const FALLBACK_ESTIMATED_HEIGHT: number =
Dimensions.get('window').height / DEFAULT_INITIAL_NUM_TO_RENDER;
export const FALLBACK_ESTIMATED_WIDTH: number =
Dimensions.get('window').width / DEFAULT_INITIAL_NUM_TO_RENDER;
@@ -0,0 +1,62 @@
/**
* 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
*/
/**
* An item to virtualize must be an item. It can optionally have a string `id`
* parameter, but that is not currently represented because it makes the Flow
* types more complicated.
*/
export interface Item {}
/**
* An interface for a collection of items, without requiring that each item be
* eagerly (or lazily) allocated.
*/
export interface VirtualCollection<+T extends Item> {
/**
* The number of items in the collection. This can either be a numeric scalar
* or a getter function that is computed on access. However, it should remain
* constant for the lifetime of this object.
*/
+size: number;
/**
* If an item exists at the supplied index, this should return a consistent
* item for the lifetime of this object. If an item does not exist at the
* supplied index, this should throw an error.
*/
at(index: number): T;
}
/**
* An implementation of `VirtualCollection` that wraps an array. Although easy to
* use, this is not recommended for larger arrays because each element of an
* array is eagerly allocated.
*/
export class VirtualArray<+T extends Item> implements VirtualCollection<T> {
+size: number;
+at: (index: number) => T;
constructor(input: Readonly<$ArrayLike<T>>) {
const array = [...input];
// NOTE: This is implemented this way because Flow does not permit `input`
// to be a read-only instance property (even a private one).
this.size = array.length;
this.at = (index: number): T => {
if (index < 0 || index >= this.size) {
throw new RangeError(
`Cannot get index ${index} from a collection of size ${this.size}`,
);
}
return array[index];
};
}
}
@@ -0,0 +1,238 @@
/**
* 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-local
* @format
*/
import type {ViewStyleProp} from '../../../../Libraries/StyleSheet/StyleSheet';
import type {ModeChangeEvent} from '../virtualview/VirtualView';
import type {Item, VirtualCollection} from './Virtual';
import VirtualView from '../virtualview/VirtualView';
import {
VirtualViewMode,
createHiddenVirtualView,
} from '../virtualview/VirtualView';
import FlingItemOverlay from './debug/FlingItemOverlay';
import * as React from 'react';
import {useCallback, useMemo, useState} from 'react';
export type VirtualCollectionLayoutComponent<TLayoutProps extends {...}> =
component(
children: ReadonlyArray<React.Node>,
spacer: React.Node,
...TLayoutProps
);
export type VirtualCollectionGenerator = Readonly<{
initial: Readonly<{
itemCount: number,
spacerStyle: (itemCount: number) => ViewStyleProp,
}>,
next: (event: ModeChangeEvent) => {
itemCount: number,
spacerStyle: (itemCount: number) => ViewStyleProp,
},
}>;
export type VirtualCollectionViewComponent<TLayoutProps extends {...}> =
component<+TItem extends Item>(
children: (item: TItem, key: string) => React.Node,
items: VirtualCollection<TItem>,
itemToKey?: (TItem) => string,
removeClippedSubviews?: boolean,
testID?: ?string,
...TLayoutProps
);
/**
* Creates a component that virtually renders a collection of items and manages
* lazy rendering, memoization, and pagination. The resulting component accepts
* the following base props:
*
* - `children`: A function maps an item to a React node.
* - `items`: A collection of items to render.
* - `itemToKey`: A function maps an item to a unique key.
*
* The first argument is a layout component that defines layout of the item and
* spacer. It always receives the following props:
*
* - `children`: An array of React nodes (for items rendered so far).
* - `spacer`: A React node (estimates layout for items not yet rendered).
*
* The layout component must render `children` and `spacer`. It can also define
* additional props that will be passed through from the resulting component.
*
* The second argument is a generator that defines the initial rendering and
* pagination behavior. The initial rendering behavior is defined by the
* `initial` property with the following properties:
*
* - `itemCount`: Number of items to render initially.
* - `spacerStyle`: A function that estimates the layout of the spacer. It
* receives the number of items being rendered as an argument.
*
* The pagination behavior is defined by the `next` function that receives a
* `ModeChangeEvent` and then returns an object with the following properties:
*
* - `itemCount`: Number of additional items needed to fill `thresholdRect`.
* - `spacerStyle`: A function that estimates the layout of the spacer. It
* receives the number of items being rendered as an argument.
*
*/
export function createVirtualCollectionView<TLayoutProps extends {...}>(
VirtualLayout: VirtualCollectionLayoutComponent<TLayoutProps>,
{initial, next}: VirtualCollectionGenerator,
): VirtualCollectionViewComponent<TLayoutProps> {
component VirtualCollectionView<+TItem extends Item>(
children: (item: TItem, key: string) => React.Node,
items: VirtualCollection<TItem>,
itemToKey: TItem => string = defaultItemToKey,
removeClippedSubviews: boolean = false,
testID?: ?string,
...layoutProps: TLayoutProps
) {
const [desiredItemCount, setDesiredItemCount] = useState(
Math.ceil(initial.itemCount),
);
const renderItem = useMemoCallback(
useCallback(
(item: TItem) => {
const key = itemToKey(item);
return (
<VirtualView
key={key}
nativeID={key}
removeClippedSubviews={removeClippedSubviews}>
{FlingItemOverlay == null ? null : (
<FlingItemOverlay nativeID={key} />
)}
{children(item, key)}
</VirtualView>
);
},
[children, itemToKey, removeClippedSubviews],
),
);
const mountedItemCount = Math.min(desiredItemCount, items.size);
const mountedItemViews = Array.from(
{length: mountedItemCount},
(_, index) => renderItem(items.at(index)),
);
const virtualItemCount = items.size - mountedItemCount;
const virtualItemSpacer = useMemo(
() =>
virtualItemCount === 0 ? null : (
<VirtualCollectionSpacer
nativeID={`${testID ?? ''}:Spacer`}
virtualItemCount={virtualItemCount}
onRenderMoreItems={(itemCount: number) => {
setDesiredItemCount(
prevElementCount => prevElementCount + itemCount,
);
}}
/>
),
[virtualItemCount, testID],
);
return (
<VirtualLayout {...layoutProps} spacer={virtualItemSpacer}>
{mountedItemViews}
</VirtualLayout>
);
}
function createSpacerView(spacerStyle: (itemCount: number) => ViewStyleProp) {
component SpacerView(
itemCount: number,
ref?: React.RefSetter<React.RefOf<VirtualView> | null>,
...props: Omit<React.PropsOf<VirtualView>, 'ref'>
) {
const HiddenVirtualView = useMemo(
() => createHiddenVirtualView(spacerStyle(itemCount)),
[itemCount],
);
return <HiddenVirtualView ref={ref} {...props} />;
}
return SpacerView;
}
const initialSpacerView = {
SpacerView: createSpacerView(initial.spacerStyle),
};
component VirtualCollectionSpacer(
nativeID: string,
virtualItemCount: number,
onRenderMoreItems: (itemCount: number) => void,
) {
// NOTE: Store `SpacerView` in a wrapper object because otherwise, `useState`
// will confuse `SpacerView` (a component) as being an updater function.
const [{SpacerView}, setSpacerView] = useState(initialSpacerView);
const handleModeChange = (event: ModeChangeEvent) => {
if (event.mode === VirtualViewMode.Hidden) {
// This should never happen; this starts hidden and otherwise unmounts.
return;
}
const {itemCount, spacerStyle} = next(event);
// Refine the estimated item size when computing spacer size.
setSpacerView({
SpacerView: createSpacerView(spacerStyle),
});
// Render more items to fill `thresholdRect`.
onRenderMoreItems(Math.min(Math.ceil(itemCount), virtualItemCount));
};
return (
<SpacerView
itemCount={virtualItemCount}
nativeID={nativeID}
onModeChange={handleModeChange}
/>
);
}
return VirtualCollectionView;
}
hook useMemoCallback<TInput extends interface {}, TOutput>(
callback: TInput => TOutput,
): TInput => TOutput {
return useMemo(() => memoize(callback), [callback]);
}
function memoize<TInput extends interface {}, TOutput>(
callback: TInput => TOutput,
): TInput => TOutput {
const cache = new WeakMap<TInput, TOutput>();
return (input: TInput) => {
let output = cache.get(input);
if (output == null) {
output = callback(input);
cache.set(input, output);
}
return output;
};
}
function defaultItemToKey(item: Item): string {
// $FlowExpectedError[prop-missing] - Flow cannot model this dynamic pattern.
const key = item.key;
if (typeof key !== 'string') {
throw new TypeError(
`Expected 'id' of item to be a string, got: ${typeof key}`,
);
}
return key;
}
@@ -0,0 +1,43 @@
/**
* 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-local
* @format
*/
import type {Item, VirtualCollection} from '../Virtual';
import {createVirtualCollectionView} from '../VirtualCollectionView';
import VirtualColumnGenerator from './VirtualColumnGenerator';
import * as React from 'react';
component VirtualColumnLayout(
children: ReadonlyArray<React.Node>,
spacer: React.Node,
) {
return (
<>
{children}
{spacer}
</>
);
}
const VirtualColumn = createVirtualCollectionView(
VirtualColumnLayout,
VirtualColumnGenerator,
);
// TODO: Figure out component generic resolution.
// @see https://fb.workplace.com/groups/flow/posts/29355518614070041
// export default VirtualColumn as VirtualCollectionViewComponent<VirtualColumnLayoutProps>;
export default VirtualColumn as component<+TItem extends Item>(
children: (item: TItem, key: string) => React.Node,
items: VirtualCollection<TItem>,
itemToKey?: (TItem) => string,
removeClippedSubviews?: boolean,
testID?: ?string,
);
@@ -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-local
* @format
*/
import type ReadOnlyElement from '../../../webapis/dom/nodes/ReadOnlyElement';
import type {ModeChangeEvent} from '../../virtualview/VirtualView';
import type {VirtualCollectionGenerator} from '../VirtualCollectionView';
import ReactNativeElement from '../../../webapis/dom/nodes/ReactNativeElement';
import {
FALLBACK_ESTIMATED_HEIGHT,
INITIAL_NUM_TO_RENDER,
} from '../FlingConstants';
function isVirtualView(element: ReadOnlyElement) {
// True for `VirtualView` and `VirtualViewExperimental`.
return element.nodeName.startsWith('RN:VirtualView');
}
const VirtualColumnGenerator: VirtualCollectionGenerator = {
initial: {
itemCount: INITIAL_NUM_TO_RENDER,
spacerStyle: (itemCount: number) => ({
height: itemCount * FALLBACK_ESTIMATED_HEIGHT,
}),
},
next({target, targetRect, thresholdRect}: ModeChangeEvent) {
if (!(target instanceof ReactNativeElement)) {
throw new Error(
'Expected target to be a ReactNativeElement. VirtualColumn requires DOM APIs to be enabled in React Native.',
);
}
const heightToFill =
Math.min(
targetRect.y + targetRect.height,
thresholdRect.y + thresholdRect.height,
) - Math.max(targetRect.y, thresholdRect.y);
// Estimate each item's size by averaging up to the 3 last items.
let previous: ReadOnlyElement = target;
let count = 0;
let maybePrevious = previous.previousElementSibling;
while (count < 3 && maybePrevious != null && isVirtualView(maybePrevious)) {
previous = maybePrevious;
count++;
maybePrevious = previous.previousElementSibling;
}
const itemHeight =
count > 0
? (target.getBoundingClientRect().top -
previous.getBoundingClientRect().top) /
count
: FALLBACK_ESTIMATED_HEIGHT;
return {
itemCount: heightToFill / itemHeight,
spacerStyle: (itemCount: number) => ({
height: itemCount * itemHeight,
}),
};
},
};
export default VirtualColumnGenerator;
@@ -0,0 +1,13 @@
/**
* 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-local
* @format
*/
const FlingItemOverlay: ?component(nativeID: string) = null;
export default FlingItemOverlay;
@@ -0,0 +1,43 @@
/**
* 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-local
* @format
*/
import ReactNativeElement from '../../../webapis/dom/nodes/ReactNativeElement';
import isScrollableNode from './isScrollableNode';
/**
* Finds the nearest ancestor of the supplied node that is a scrollable node.
*
* Unlike the web-equivalent function, the return type is nullable because the
* root is not an implicitly scrollable node.
*/
export default function getScrollParent(
node: ReactNativeElement,
): ReactNativeElement | null {
let element: ReactNativeElement | null = node;
while (element != null) {
if (isScrollableNode(element)) {
return element;
}
const parent = element.parentElement;
// Currently, the only subclass of `ReadOnlyNode` is `ReactNativeElement`.
if (parent instanceof ReactNativeElement || parent == null) {
element = parent;
} else {
console.error(
'Expected `element.parentElement` to be `?ReactNativeElement`, got: %s',
parent,
);
element = null;
}
// So this is equivalent to a null check with type safety.
element = parent instanceof ReactNativeElement ? parent : null;
}
return null;
}
@@ -0,0 +1,22 @@
/**
* 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-local
* @format
*/
import type ReactNativeElement from '../../../webapis/dom/nodes/ReactNativeElement';
/**
* Checks whether the supplied node is a scrollable node, ignoring whether
* there is sufficient content to scroll or whether scrolling is disabled.
*/
export default function isScrollableNode(node: ReactNativeElement): boolean {
// Applies for vertical and horizontal `ScrollView` on both Android and iOS.
// The content container might have a different `nodeName`, but its parent
// always has this `nodeName`.
return node.nodeName === 'RN:ScrollView';
}
@@ -0,0 +1,43 @@
/**
* 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-local
* @format
*/
import type {Item, VirtualCollection} from '../Virtual';
import {createVirtualCollectionView} from '../VirtualCollectionView';
import VirtualRowGenerator from './VirtualRowGenerator';
import * as React from 'react';
component VirtualRowLayout(
children: ReadonlyArray<React.Node>,
spacer: React.Node,
) {
return (
<>
{children}
{spacer}
</>
);
}
const VirtualRow = createVirtualCollectionView(
VirtualRowLayout,
VirtualRowGenerator,
);
// TODO: Figure out component generic resolution.
// @see https://fb.workplace.com/groups/flow/posts/29355518614070041
// export default VirtualRow as VirtualCollectionViewComponent<VirtualRowLayoutProps>;
export default VirtualRow as component<+TItem extends Item>(
children: (item: TItem, key: string) => React.Node,
items: VirtualCollection<TItem>,
itemToKey?: (TItem) => string,
removeClippedSubviews?: boolean,
testID?: ?string,
);
@@ -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-local
* @format
*/
import type ReadOnlyElement from '../../../webapis/dom/nodes/ReadOnlyElement';
import type {ModeChangeEvent} from '../../virtualview/VirtualView';
import type {VirtualCollectionGenerator} from '../VirtualCollectionView';
import ReactNativeElement from '../../../webapis/dom/nodes/ReactNativeElement';
import {
FALLBACK_ESTIMATED_WIDTH,
INITIAL_NUM_TO_RENDER,
} from '../FlingConstants';
function isVirtualView(element: ReadOnlyElement) {
// True for `VirtualView` and `VirtualViewExperimental`.
return element.nodeName.startsWith('RN:VirtualView');
}
const VirtualRowGenerator: VirtualCollectionGenerator = {
initial: {
itemCount: INITIAL_NUM_TO_RENDER,
spacerStyle: (itemCount: number) => ({
width: itemCount * FALLBACK_ESTIMATED_WIDTH,
}),
},
next({target, targetRect, thresholdRect}: ModeChangeEvent) {
if (!(target instanceof ReactNativeElement)) {
throw new Error(
'Expected target to be a ReactNativeElement. VirtualRow requires DOM APIs to be enabled in React Native.',
);
}
const widthToFill =
Math.min(
targetRect.x + targetRect.width,
thresholdRect.x + thresholdRect.width,
) - Math.max(targetRect.x, thresholdRect.x);
// Estimate each item's size by averaging up to the 3 last items.
let previous: ReadOnlyElement = target;
let count = 0;
let maybePrevious = previous.previousElementSibling;
while (count < 3 && maybePrevious != null && isVirtualView(maybePrevious)) {
previous = maybePrevious;
count++;
maybePrevious = previous.previousElementSibling;
}
const itemWidth =
count > 0
? (target.getBoundingClientRect().left -
previous.getBoundingClientRect().left) /
count
: FALLBACK_ESTIMATED_WIDTH;
return {
itemCount: widthToFill / itemWidth,
spacerStyle: (itemCount: number) => ({
width: itemCount * itemWidth,
}),
};
},
};
export default VirtualRowGenerator;