rcx-virtual-list
Version:
Maximum performance for extremely large lists.<br/> Flexible, and actively maintained React library that excels with high-performance, feature-rich virtualized lists—including grouping, sticky headers, snapping, animations, and both scroll directions. Wh
206 lines (205 loc) • 7.97 kB
TypeScript
/// <reference types="react" />
import { IRenderVirtualListCollection } from "../models/render-collection.model";
import { Id } from "../types/id";
import { CacheMap, CMap } from "./cacheMap";
import { Tracker } from "./tracker";
import { ISize } from "../types";
import { HEIGHT_PROP_NAME, WIDTH_PROP_NAME } from "../const";
import { IVirtualListStickyMap } from "../models";
import { IVirtualListItemMethods } from "../models/virtual-list-item-ref-methods.model";
export declare const TRACK_BOX_CHANGE_EVENT_NAME = "change";
export interface IMetrics {
delta: number;
normalizedItemWidth: number;
normalizedItemHeight: number;
width: number;
height: number;
dynamicSize: boolean;
itemSize: number;
itemsFromStartToScrollEnd: number;
itemsFromStartToDisplayEnd: number;
itemsOnDisplayWeight: number;
itemsOnDisplayLength: number;
isVertical: boolean;
leftHiddenItemsWeight: number;
leftItemLength: number;
leftItemsWeight: number;
renderItems: number;
rightItemLength: number;
rightItemsWeight: number;
scrollSize: number;
leftSizeOfAddedItems: number;
sizeProperty: typeof HEIGHT_PROP_NAME | typeof WIDTH_PROP_NAME;
snap: boolean;
snippedPos: number;
startIndex: number;
startPosition: number;
totalItemsToDisplayEndWeight: number;
totalLength: number;
totalSize: number;
typicalItemSize: number;
isFromItemIdFound: boolean;
}
export interface IRecalculateMetricsOptions<I extends {
id: Id;
}, C extends Array<I>> {
bounds: ISize;
collection: C;
isVertical: boolean;
itemSize: number;
bufferSize: number;
maxBufferSize: number;
dynamicSize: boolean;
scrollSize: number;
snap: boolean;
enabledBufferOptimization: boolean;
fromItemId?: Id;
previousTotalSize: number;
crudDetected: boolean;
deletedItemsMap: {
[index: number]: ISize;
};
}
export interface IGetItemPositionOptions<I extends {
id: Id;
}, C extends Array<I>> extends Omit<IRecalculateMetricsOptions<I, C>, 'previousTotalSize' | 'crudDetected' | 'deletedItemsMap'> {
}
export interface IUpdateCollectionOptions<I extends {
id: Id;
}, C extends Array<I>> extends Omit<IRecalculateMetricsOptions<I, C>, 'collection' | 'previousTotalSize' | 'crudDetected' | 'deletedItemsMap'> {
}
export type CacheMapEvents = typeof TRACK_BOX_CHANGE_EVENT_NAME;
export type OnChangeEventListener = (version: number) => void;
export type CacheMapListeners = OnChangeEventListener;
export declare enum ItemDisplayMethods {
CREATE = 0,
UPDATE = 1,
DELETE = 2,
NOT_CHANGED = 3
}
export interface IUpdateCollectionReturns {
displayItems: IRenderVirtualListCollection;
totalSize: number;
delta: number;
crudDetected: boolean;
}
/**
* An object that performs tracking, calculations and caching.
* @link https://github.com/DjonnyX/rcx-virtual-list/tree/main/src/lib/src/utils/trackBox.ts
* @author Evgenii Grebennikov
* @email djonnyx@gmail.com
*/
export declare class TrackBox<C extends IVirtualListItemMethods = any> extends CacheMap<Id, ISize & {
method?: ItemDisplayMethods;
}, CacheMapEvents, CacheMapListeners> {
protected _tracker: Tracker<C>;
protected _items: IRenderVirtualListCollection | null | undefined;
set items(v: IRenderVirtualListCollection | null | undefined);
protected _displayComponents: Array<React.RefObject<C>> | null | undefined;
set displayComponents(v: Array<React.RefObject<C>> | null | undefined);
protected _snapedDisplayComponent: React.RefObject<C> | null | undefined;
set snapedDisplayComponent(v: React.RefObject<C> | null | undefined);
protected _isSnappingMethodAdvanced: boolean;
set isSnappingMethodAdvanced(v: boolean);
/**
* Set the trackBy property
*/
set trackingPropertyName(v: string);
constructor(trackingPropertyName: string);
set(id: Id, bounds: ISize): CMap<Id, ISize>;
protected _previousCollection: Array<{
id: Id;
}> | null | undefined;
protected _deletedItemsMap: {
[index: number]: ISize;
};
protected _crudDetected: boolean;
get crudDetected(): boolean;
protected fireChangeIfNeed(): void;
protected _previousTotalSize: number;
protected _scrollDelta: number;
get scrollDelta(): number;
isAdaptiveBuffer: boolean;
protected _bufferSequenceExtraThreshold: number;
protected _maxBufferSequenceLength: number;
protected _bufferSizeSequence: Array<number>;
protected _bufferSize: number;
get bufferSize(): number;
protected _defaultBufferSize: number;
protected _maxBufferSize: number;
protected _resetBufferSizeTimeout: number;
protected _resetBufferSizeTimer: number | undefined;
protected lifeCircle(): void;
/**
* Scans the collection for deleted items and flushes the deleted item cache.
*/
resetCollection<I extends {
id: Id;
}, C extends Array<I>>(currentCollection: C | null | undefined, itemSize: number): void;
/**
* Update the cache of items from the list
*/
protected updateCache<I extends {
id: Id;
}, C extends Array<I>>(previousCollection: C | null | undefined, currentCollection: C | null | undefined, itemSize: number): void;
/**
* Finds the position of a collection element by the given Id
*/
getItemPosition<I extends {
id: Id;
}, C extends Array<I>>(id: Id, stickyMap: IVirtualListStickyMap, options: IGetItemPositionOptions<I, C>): number;
/**
* Updates the collection of display objects
*/
updateCollection<I extends {
id: Id;
}, C extends Array<I>>(items: C, stickyMap: IVirtualListStickyMap, options: IUpdateCollectionOptions<I, C>): IUpdateCollectionReturns;
/**
* Finds the closest element in the collection by scrollSize
*/
getNearestItem<I extends {
id: Id;
}, C extends Array<I>>(scrollSize: number, items: C, itemSize: number, isVertical: boolean): I | undefined;
protected _previousScrollSize: number;
protected updateAdaptiveBufferParams(metrics: IMetrics, totalItemsLength: number): void;
protected startResetBufferSizeTimer(): void;
protected disposeClearBufferSizeTimer(): void;
/**
* Calculates the position of an element based on the given scrollSize
*/
protected getElementFromStart<I extends {
id: Id;
}, C extends Array<I>>(scrollSize: number, collection: C, map: CMap<Id, ISize>, typicalItemSize: number, isVertical: boolean): I | undefined;
/**
* Calculates the entry into the overscroll area and returns the number of overscroll elements
*/
protected getElementNumToEnd<I extends {
id: Id;
}, C extends Array<I>>(i: number, collection: C, map: CMap<Id, ISize>, typicalItemSize: number, size: number, isVertical: boolean, indexOffset?: number): {
num: number;
offset: number;
};
/**
* Calculates list metrics
*/
protected recalculateMetrics<I extends {
id: Id;
}, C extends Array<I>>(options: IRecalculateMetricsOptions<I, C>): IMetrics;
clearDeltaDirection(): void;
clearDelta(clearDirectionDetector?: boolean): void;
changes(): void;
protected generateDisplayCollection<I extends {
id: Id;
}, C extends Array<I>>(items: C, stickyMap: IVirtualListStickyMap, metrics: IMetrics): IRenderVirtualListCollection;
/**
* tracking by propName
*/
track(): void;
setDisplayObjectIndexMapById(v: {
[id: number]: number;
}): void;
untrackComponentByIdProperty(component?: C | undefined): void;
getItemBounds(id: Id): ISize | undefined;
protected cacheElements(): void;
dispose(): void;
}