ng-virtual-list/index.d.ts

Maximum performance for extremely large lists.<br/> Animation of elements is supported.

import * as ng_virtual_list from 'ng-virtual-list';
import * as _angular_core from '@angular/core';
import { WritableSignal, TemplateRef, AfterViewInit, OnInit, OnDestroy } from '@angular/core';
import { Observable } from 'rxjs';

/**
 * Identifier type
 * @link https://github.com/DjonnyX/ng-virtual-list/blob/20.x/projects/ng-virtual-list/src/lib/types/id.ts
 * @author Evgenii Grebennikov
 * @email djonnyx@gmail.com
 */
type Id = string | number;

/**
 * Area area Interface
 * @link https://github.com/DjonnyX/ng-virtual-list/blob/20.x/projects/ng-virtual-list/src/lib/types/size.ts
 * @author Evgenii Grebennikov
 * @email djonnyx@gmail.com
 */
interface ISize {
    /**
     * Width value.
     */
    width: number;
    /**
     * Height value.
     */
    height: number;
}

/**
 * Rectangular area interface
 * @link https://github.com/DjonnyX/ng-virtual-list/blob/20.x/projects/ng-virtual-list/src/lib/types/rect.ts
 * @author Evgenii Grebennikov
 * @email djonnyx@gmail.com
 */
interface IRect extends ISize {
    /**
     * X coordinate.
     */
    x: number;
    /**
     * Y coordinate.
     */
    y: number;
}

/**
 * Virtual list element model
 * @link https://github.com/DjonnyX/ng-virtual-list/blob/20.x/projects/ng-virtual-list/src/lib/models/item.model.ts
 * @author Evgenii Grebennikov
 * @email djonnyx@gmail.com
 */
type IVirtualListItem<E = Object> = E & {
    /**
     * Unique identifier of the element.
     */
    id: Id;
    [x: string]: any;
};

/**
 * Object with configuration parameters for IRenderVirtualListItem
 * @link https://github.com/DjonnyX/ng-virtual-list/blob/20.x/projects/ng-virtual-list/src/lib/models/render-item-config.model.ts
 * @author Evgenii Grebennikov
 * @email djonnyx@gmail.com
 *
 */
interface IRenderVirtualListItemConfig {
    /**
     * If greater than 0, the element will have a sticky position with the given zIndex.
     */
    sticky: number;
    /**
     * Specifies whether the element will snap.
     */
    snap: boolean;
    /**
     * Indicates that the element is snapped.
     */
    snapped: boolean;
    /**
     * Indicates that the element is being shifted by another snap element.
     */
    snappedOut: boolean;
    /**
     * Indicates that the element is a vertical list item.
     */
    isVertical: boolean;
    /**
     * Specifies that the element adapts to the size of its content.
     */
    dynamic: boolean;
    /**
     * Returns true if the snapping method is advanced
     */
    isSnappingMethodAdvanced: boolean;
    /**
     * z-index
     */
    zIndex: string;
}

/**
 * List screen element model
 * @link https://github.com/DjonnyX/ng-virtual-list/blob/20.x/projects/ng-virtual-list/src/lib/models/render-item.model.ts
 * @author Evgenii Grebennikov
 * @email djonnyx@gmail.com
 */
interface IRenderVirtualListItem {
    /**
     * Unique identifier of the element.
     */
    id: Id;
    /**
     * Element metrics.
     */
    measures: IRect & {
        /**
         * Delta is calculated for Snapping Method.ADVANCED
         */
        delta: number;
    };
    /**
     * Element data.
     */
    data: IVirtualListItem;
    /**
     * Object with configuration parameters for IRenderVirtualListItem.
     */
    config: IRenderVirtualListItemConfig;
}

/**
 * Virtual List Item Interface
 * @link https://github.com/DjonnyX/ng-virtual-list/blob/19.x/projects/ng-virtual-list/src/lib/models/base-virtual-list-item-component.ts
 * @author Evgenii Grebennikov
 * @email djonnyx@gmail.com
 */
declare abstract class BaseVirtualListItemComponent {
    abstract get id(): number;
    abstract data: WritableSignal<IRenderVirtualListItem | undefined>;
    abstract regular: boolean;
    abstract set regularLength(v: string);
    abstract set item(v: IRenderVirtualListItem | null | undefined);
    abstract get item(): IRenderVirtualListItem | null | undefined;
    abstract get itemId(): Id | undefined;
    abstract itemRenderer: WritableSignal<TemplateRef<any> | undefined>;
    abstract set renderer(v: TemplateRef<any> | undefined);
    abstract get element(): HTMLElement;
    abstract getBounds(): ISize;
    abstract show(): void;
    abstract hide(): void;
}

/**
 * Virtual list item component
 * @link https://github.com/DjonnyX/ng-virtual-list/blob/20.x/projects/ng-virtual-list/src/lib/components/ng-virtual-list-item.component.ts
 * @author Evgenii Grebennikov
 * @email djonnyx@gmail.com
 */
declare class NgVirtualListItemComponent extends BaseVirtualListItemComponent {
    private static __nextId;
    private _id;
    get id(): number;
    regular: boolean;
    data: _angular_core.WritableSignal<IRenderVirtualListItem | undefined>;
    private _data;
    set item(v: IRenderVirtualListItem | undefined);
    private _regularLength;
    set regularLength(v: string);
    get item(): IRenderVirtualListItem | undefined;
    get itemId(): ng_virtual_list.Id | undefined;
    itemRenderer: _angular_core.WritableSignal<TemplateRef<any> | undefined>;
    set renderer(v: TemplateRef<any> | undefined);
    private _elementRef;
    get element(): HTMLElement;
    private _listItemRef;
    constructor();
    private update;
    getBounds(): ISize;
    show(): void;
    hide(): void;
    static ɵfac: _angular_core.ɵɵFactoryDeclaration<NgVirtualListItemComponent, never>;
    static ɵcmp: _angular_core.ɵɵComponentDeclaration<NgVirtualListItemComponent, "ng-virtual-list-item", never, {}, {}, never, never, true, never>;
}

/**
 * A value of -1 indicates the direction is up or left (if the list direction is horizontal).
 * A value of 1 indicates the direction is down or right (if the list direction is horizontal).
 */
type ScrollDirection = -1 | 1 | 0;

/**
 * Interface IScrollEvent.
 * @link https://github.com/DjonnyX/ng-virtual-list/blob/20.x/projects/ng-virtual-list/src/lib/models/scroll-event.model.ts
 * @author Evgenii Grebennikov
 * @email djonnyx@gmail.com
 */
interface IScrollEvent {
    /**
     * Scroll area offset
     */
    scrollSize: number;
    /**
     * Full size of the scroll area
     */
    scrollWeight: number;
    /**
     * Viewport size
     */
    size: number;
    /**
     * Size of the list of elements
     */
    listSize: number;
    /**
     * Specifies whether the list orientation is vertical.
     */
    isVertical: boolean;
    /**
     * A value of -1 indicates the direction is up or left (if the list direction is horizontal).
     * A value of 1 indicates the direction is down or right (if the list direction is horizontal).
     */
    direction: ScrollDirection;
    /**
     * If true then indicates that the list has been scrolled to the end.
     */
    isStart: boolean;
    /**
     * If true then indicates that the list has been scrolled to the end.
     */
    isEnd: boolean;
    /**
     * Delta of marked and unmarked area
     */
    delta: number;
    /**
     * Scroll delta
     */
    scrollDelta: number;
}

/**
 * Dictionary zIndex by id of the list element. If the value is not set or equal to 0, then a simple element is displayed,
 * if the value is greater than 0, then the sticky position mode is enabled for the element. 1 - position start, 2 - position end.
 * @link https://github.com/DjonnyX/ng-virtual-list/blob/20.x/projects/ng-virtual-list/src/lib/models/sticky-map.model.ts
 * @author Evgenii Grebennikov
 * @email djonnyx@gmail.com
 */
interface IVirtualListStickyMap {
    /**
     * Sets zIndex for the element ID. If zIndex is greater than 0, then sticky position is applied.
     * 1 - position start, 2 - position end.
     */
    [id: string]: 0 | 1 | 2;
}

/**
 * Virtual list elements collection interface
 * @link https://github.com/DjonnyX/ng-virtual-list/blob/20.x/projects/ng-virtual-list/src/lib/models/collection.model.ts
 * @author Evgenii Grebennikov
 * @email djonnyx@gmail.com
 */
interface IVirtualListCollection<E = Object> extends Array<IVirtualListItem<E>> {
}

/**
 * Axis of the arrangement of virtual list elements.
 * @link https://github.com/DjonnyX/ng-virtual-list/blob/20.x/projects/ng-virtual-list/src/lib/enums/directions.ts
 * @author Evgenii Grebennikov
 * @email djonnyx@gmail.com
 */
declare enum Directions {
    /**
     * Horizontal axis.
     */
    HORIZONTAL = "horizontal",
    /**
     * Vertical axis.
     */
    VERTICAL = "vertical"
}

/**
 * Axis of the arrangement of virtual list elements.
 * @link https://github.com/DjonnyX/ng-virtual-list/blob/20.x/projects/ng-virtual-list/src/lib/enums/direction.ts
 * @author Evgenii Grebennikov
 * @email djonnyx@gmail.com
 */
type Direction = Directions | 'horizontal' | 'vertical';

/**
 * Snapping method.
 * @link https://github.com/DjonnyX/ng-virtual-list/blob/20.x/projects/ng-virtual-list/src/lib/enums/snapping-method.ts
 * @author Evgenii Grebennikov
 * @email djonnyx@gmail.com
 */
declare enum SnappingMethods {
    /**
     * Normal group rendering.
     */
    NORMAL = "normal",
    /**
     * The group is rendered on a transparent background. List items below the group are not rendered.
     */
    ADVANCED = "advanced"
}

/**
 * Snapping method.
 * 'normal' - Normal group rendering.
 * 'advanced' - The group is rendered on a transparent background. List items below the group are not rendered.
 * @link https://github.com/DjonnyX/ng-virtual-list/blob/20.x/projects/ng-virtual-list/src/lib/enums/snapping-method.ts
 * @author Evgenii Grebennikov
 * @email djonnyx@gmail.com
 */
type SnappingMethod = SnappingMethods | 'normal' | 'advanced';

/**
 * Virtual list component.
 * Maximum performance for extremely large lists.
 * It is based on algorithms for virtualization of screen objects.
 * @link https://github.com/DjonnyX/ng-virtual-list/blob/20.x/projects/ng-virtual-list/src/lib/ng-virtual-list.component.ts
 * @author Evgenii Grebennikov
 * @email djonnyx@gmail.com
 */
declare class NgVirtualListComponent implements AfterViewInit, OnInit, OnDestroy {
    private static __nextId;
    private _id;
    /**
     * Readonly. Returns the unique identifier of the component.
     */
    get id(): number;
    private _listContainerRef;
    private _snapContainerRef;
    private _snappedContainer;
    private _container;
    private _list;
    /**
     * Fires when the list has been scrolled.
     */
    onScroll: _angular_core.OutputEmitterRef<IScrollEvent>;
    /**
     * Fires when the list has completed scrolling.
     */
    onScrollEnd: _angular_core.OutputEmitterRef<IScrollEvent>;
    private _itemsOptions;
    /**
     * Collection of list items.
     */
    items: _angular_core.InputSignal<IVirtualListCollection<Object>>;
    /**
     * Determines whether elements will snap. Default value is "true".
     */
    snap: _angular_core.InputSignal<boolean>;
    /**
     * Experimental!
     * Enables buffer optimization.
     * Can only be used if items in the collection are not added or updated. Otherwise, artifacts in the form of twitching of the scroll area are possible.
     * Works only if the property dynamic = true
     */
    enabledBufferOptimization: _angular_core.InputSignal<boolean>;
    /**
     * Rendering element template.
     */
    itemRenderer: _angular_core.InputSignal<TemplateRef<any>>;
    private _itemRenderer;
    /**
     * Dictionary zIndex by id of the list element. If the value is not set or equal to 0,
     * then a simple element is displayed, if the value is greater than 0, then the sticky position mode is enabled for the element.
     */
    stickyMap: _angular_core.InputSignal<IVirtualListStickyMap>;
    private _itemSizeOptions;
    /**
     * If direction = 'vertical', then the height of a typical element. If direction = 'horizontal', then the width of a typical element.
     * Ignored if the dynamicSize property is true.
     */
    itemSize: _angular_core.InputSignal<number>;
    /**
     * If true then the items in the list can have different sizes and the itemSize property is ignored.
     * If false then the items in the list have a fixed size specified by the itemSize property. The default value is false.
     */
    dynamicSize: _angular_core.InputSignal<boolean>;
    /**
     * Determines the direction in which elements are placed. Default value is "vertical".
     */
    direction: _angular_core.InputSignal<Direction>;
    private _itemOffsetTransform;
    /**
     * Number of elements outside the scope of visibility. Default value is 2.
     * @deprecated "itemOffset" parameter is deprecated. Use "bufferSize" and "maxBufferSize".
     */
    itemsOffset: _angular_core.InputSignal<number>;
    /**
     * Number of elements outside the scope of visibility. Default value is 2.
     */
    bufferSize: _angular_core.InputSignal<number>;
    private _maxBufferSizeTransform;
    /**
     * Maximum number of elements outside the scope of visibility. Default value is 100.
     * If maxBufferSize is set to be greater than bufferSize, then adaptive buffer mode is enabled.
     * The greater the scroll size, the more elements are allocated for rendering.
     */
    maxBufferSize: _angular_core.InputSignal<number>;
    /**
     * Snapping method.
     * 'default' - Normal group rendering.
     * 'advanced' - The group is rendered on a transparent background. List items below the group are not rendered.
     */
    snappingMethod: _angular_core.InputSignal<SnappingMethod>;
    private _isSnappingMethodAdvanced;
    get isSnappingMethodAdvanced(): boolean;
    private _isVertical;
    private _displayComponents;
    private _snapedDisplayComponent;
    private _bounds;
    private _scrollSize;
    private _resizeObserver;
    private _resizeSnappedComponentHandler;
    private _resizeSnappedObserver;
    private _componentsResizeObserver;
    private _onResizeHandler;
    private _onScrollHandler;
    private _elementRef;
    private _initialized;
    readonly $initialized: Observable<boolean>;
    /**
     * The name of the property by which tracking is performed
     */
    trackBy: _angular_core.InputSignal<string>;
    /**
     * Base class of the element component
     */
    private _itemComponentClass;
    /**
     * Base class trackBox
     */
    private _trackBoxClass;
    /**
     * Dictionary of element sizes by their id
     */
    private _trackBox;
    private _onTrackBoxChangeHandler;
    private _cacheVersion;
    constructor();
    private onInit;
    private listenCacheChangesIfNeed;
    private getIsSnappingMethodAdvanced;
    private getIsVertical;
    private createDisplayComponentsIfNeed;
    private updateRegularRenderer;
    private resetRenderers;
    /**
     * Tracking by id
     */
    private tracking;
    private resetBoundsSize;
    /**
     * Returns the bounds of an element with a given id
     */
    getItemBounds(id: Id): ISize | undefined;
    /**
     * The method scrolls the list to the element with the given id and returns the value of the scrolled area.
     * Behavior accepts the values ​​"auto", "instant" and "smooth".
     */
    scrollTo(id: Id, behavior?: ScrollBehavior): void;
    private _scrollToRepeatExecutionTimeout;
    private clearScrollToRepeatExecutionTimeout;
    private scrollToExecutor;
    /**
     * Scrolls the scroll area to the desired element with the specified ID.
     */
    scrollToEnd(behavior?: ScrollBehavior): void;
    private _onContainerScrollHandler;
    private _onContainerScrollEndHandler;
    private afterViewInit;
    private dispose;
    static ɵfac: _angular_core.ɵɵFactoryDeclaration<NgVirtualListComponent, never>;
    static ɵcmp: _angular_core.ɵɵComponentDeclaration<NgVirtualListComponent, "ng-virtual-list", never, { "items": { "alias": "items"; "required": true; "isSignal": true; }; "snap": { "alias": "snap"; "required": false; "isSignal": true; }; "enabledBufferOptimization": { "alias": "enabledBufferOptimization"; "required": false; "isSignal": true; }; "itemRenderer": { "alias": "itemRenderer"; "required": true; "isSignal": true; }; "stickyMap": { "alias": "stickyMap"; "required": false; "isSignal": true; }; "itemSize": { "alias": "itemSize"; "required": false; "isSignal": true; }; "dynamicSize": { "alias": "dynamicSize"; "required": false; "isSignal": true; }; "direction": { "alias": "direction"; "required": false; "isSignal": true; }; "itemsOffset": { "alias": "itemsOffset"; "required": false; "isSignal": true; }; "bufferSize": { "alias": "bufferSize"; "required": false; "isSignal": true; }; "maxBufferSize": { "alias": "maxBufferSize"; "required": false; "isSignal": true; }; "snappingMethod": { "alias": "snappingMethod"; "required": false; "isSignal": true; }; "trackBy": { "alias": "trackBy"; "required": false; "isSignal": true; }; }, { "onScroll": "onScroll"; "onScrollEnd": "onScrollEnd"; }, never, never, true, never>;
}

/**
 * Simple debounce function.
 * @link https://github.com/DjonnyX/ng-virtual-list/blob/20.x/projects/ng-virtual-list/src/lib/utils/debounce.ts
 * @author Evgenii Grebennikov
 * @email djonnyx@gmail.com
 */
declare const debounce: (cb: (...args: Array<any>) => void, debounceTime?: number) => {
    /**
     *  Call handling method
     */
    execute: (...args: Array<any>) => void;
    /**
     * Method of destroying handlers
     */
    dispose: () => void;
};

/**
 * Switch css classes
 * @link https://github.com/DjonnyX/ng-virtual-list/blob/20.x/projects/ng-virtual-list/src/lib/utils/toggleClassName.ts
 * @author Evgenii Grebennikov
 * @email djonnyx@gmail.com
 */
declare const toggleClassName: (el: HTMLElement, className: string, removeClassName?: string) => void;

declare const WIDTH_PROP_NAME = "width";
declare const HEIGHT_PROP_NAME = "height";

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;
}

interface IScrollEventParams {
    direction: ScrollDirection;
    container: HTMLElement;
    list: HTMLElement;
    delta: number;
    scrollDelta: number;
    isVertical: boolean;
}
/**
 * Scroll event.
 * @link https://github.com/DjonnyX/ng-virtual-list/blob/20.x/projects/ng-virtual-list/src/lib/utils/scrollEvent.ts
 * @author Evgenii Grebennikov
 * @email djonnyx@gmail.com
 */
declare class ScrollEvent implements IScrollEvent {
    private _direction;
    get direction(): ScrollDirection;
    private _scrollSize;
    get scrollSize(): number;
    private _scrollWeight;
    get scrollWeight(): number;
    private _isVertical;
    get isVertical(): boolean;
    private _listSize;
    get listSize(): number;
    private _size;
    get size(): number;
    private _isStart;
    get isStart(): boolean;
    private _isEnd;
    get isEnd(): boolean;
    private _delta;
    get delta(): number;
    private _scrollDelta;
    get scrollDelta(): number;
    constructor(params: IScrollEventParams);
}

export { Directions, NgVirtualListComponent, NgVirtualListItemComponent, ScrollEvent, SnappingMethods, debounce, toggleClassName };
export type { Direction, IMetrics, IRect, IScrollEvent, ISize, IVirtualListCollection, IVirtualListItem, IVirtualListStickyMap, Id, ScrollDirection, SnappingMethod };