import * as i0 from "@angular/core"; import { OnDestroy, TemplateRef } from "@angular/core"; /** Template context for a single item of the virtual scroll. */ export declare class IgxVsItemContext { /** The current item in the virtual scroll. */ $implicit: T; /** The index of the current item. */ index: number; /** The total number of items in the virtual scroll. */ count: number; constructor( /** The current item in the virtual scroll. */ $implicit: T, /** The index of the current item. */ index: number, /** The total number of items in the virtual scroll. */ count: number); /** Whether the current item is the first in the list. */ get first(): boolean; /** Whether the current item is the last in the list. */ get last(): boolean; /** Whether the current item is at an even index. */ get even(): boolean; /** Whether the current item is at an odd index. */ get odd(): boolean; } /** Returns an item's key from the item and its index in the whole collection. */ export type VirtualScrollKeyFunction = (item: T, index: number) => unknown; /** * How `scrollToIndex` positions the requested item in the viewport. * The subset of `ScrollLogicalPosition` that the engine supports. */ export type ScrollAlignment = "start" | "center" | "end"; /** The currently rendered (visible plus over-scanned) range of items. */ export interface VisibleRange { /** Index of the first rendered item, inclusive. */ startIndex: number; /** Index of the last rendered item, inclusive. */ endIndex: number; } /** Snapshot of the currently rendered virtual window. */ export interface VirtualScrollState extends VisibleRange { /** The size of the viewport in pixels. */ viewportSize: number; /** The total size of the virtual scroll content in pixels. */ totalSize: number; } /** * A loaded page of a larger collection, for data that arrives a page at a time. * * The list is sized by `totalCount` while only `items` are in memory. Indices are indices * in the whole collection: the item at `index` is `items[index - startIndex]`, and indices * the page does not cover render nothing. * * Measured sizes are kept per index across pages while `totalCount` holds: the indices still * mean the same records. A page with another `totalCount` is a different collection, and * every size is measured again. A page that keeps the count but puts different records at * the same indices keeps the sizes measured for the previous ones until those rows render. */ export interface VirtualDataWindow { /** The loaded items. */ readonly items: readonly T[]; /** The index `items[0]` has in the whole collection. */ readonly startIndex: number; /** How many items the whole collection has. */ readonly totalCount: number; } /** * Request for more data, emitted when the rendered window nears the end of * the loaded items. Listen to it to implement infinite / remote scrolling. */ export interface VirtualScrollDataRequest { /** The first index that does not yet have data. */ startIndex: number; /** Number of items being requested. */ count: number; } /** * A virtual scroll component for large lists. Only the items visible in the * viewport (plus a configurable over-scan) are rendered. * * @igxKeywords virtual, scroll, virtualization, list * @igxGroup Grids & Lists * * @example * ```html * * *
{{ i }}: {{ item }}
*
*
* ``` */ export declare class IgxVirtualScrollComponent implements OnDestroy { private readonly _hostRef; private readonly _zone; private readonly _document; private readonly _isBrowser; private readonly _engine; private _viewportResizeObserver; private _itemResizeObserver; private _onScroll; /** Elements currently registered with the item resize observer. */ private readonly _observedItems; /** The data index each observed wrapper element last hosted. */ private readonly _observedItemIndexes; /** * The live scroll offset on the active axis. A plain field, not a signal: * `_visibleRange` reads it but is invalidated by `_scrollTick`, so a scroll * that does not move the rendered window schedules no work. */ private _scrollPosition; /** Bumped only when a scroll actually moves the rendered window. */ private readonly _scrollTick; /** The measured viewport, or `null` while the host has never been laid out. */ private readonly _viewportSize; /** * Whether the host is laid out left-to-right, as of the last read of the * horizontal axis. `_contentTransform` depends on it, so a `dir` change * flips the wrapper even while the rendered window stays put. */ private readonly _ltr; /** What was loaded as of the previous change, for `_retainCount`. */ private _previousItems; private _lastEmittedState; /** Whether the host has been laid out, so a later detach is a removal rather than the pre-render state. */ private _wasLaidOut; /** Set when a report was skipped while detached, so re-attaching reports the window once. */ private _skippedWhileDetached; private readonly _attachTick; private _hasPendingDataRequest; /** * The `startIndex` of the last emitted `dataRequest`, which is also the * item count at that emit. See `_checkDataRequest`. */ private _lastDataRequestIndex; private _layoutCompletePromise; private _scrollRequestId; private readonly _itemDirective; private readonly _contentDivRef; /** * The array of items to virtualize. * * Compared by reference: mutating the array in place (`data.push(...)`) * causes no update. Assign a new array instead. The `dataRequest` flow * also expects a new array. */ readonly data: import("@angular/core").InputSignal; /** * Scroll orientation of the virtual scroll. * Can be either "vertical" or "horizontal". * Default is "vertical". */ readonly orientation: import("@angular/core").InputSignal<"vertical" | "horizontal">; /** * Number of extra items to render beyond the visible area of the viewport. * Higher values reduce blank flashes during fast scrolling but may impact performance. * Default is 2. */ readonly overScan: import("@angular/core").InputSignal; /** * Estimated item size in pixels used before an item is measured in the DOM. * The engine replaces this with the actual measured size after the first render of each item. * Unmeasured items then take the average measured size. * Default is 50 pixels. * Setting this to a value close to the actual average item size can improve initial rendering performance. */ readonly estimatedItemSize: import("@angular/core").InputSignal; /** * A loaded page of a larger collection, for data that arrives a page at a time. * * Takes the place of `data` while it is set. The list is as long as `totalCount`, so the * scrollbar spans the whole collection while only the page is in memory. Indices the page * does not cover render nothing; use `stateChange` to see which range is wanted and supply * the page that covers it. * * Measured sizes are kept per index across pages while `totalCount` holds: the indices still * mean the same records. A page with another `totalCount` is a different collection, and * every size is measured again. A page that keeps the count but puts different records at * the same indices keeps the sizes measured for the previous ones until those rows render. * * @example * ```html * * {{ item?.name }} * * ``` */ readonly dataWindow: import("@angular/core").InputSignal | null>; /** * @hidden @internal * * Viewport size in pixels to render the first window against, for a list that is hidden * until the change detection pass that reveals it and so has no size to measure in it. * * A hint for that first render: once the host has been laid out its own size takes over, * zero included. Changing `orientation` begins an axis with no measurement of its own, so * the hint applies again there. Negative, `NaN` and infinite values count as no hint. * * A workaround for the drop-down family, which reads and focuses items in the pass that * opens the list. To be removed once those components render their list on reveal. */ readonly initialViewportSize: import("@angular/core").InputSignal; /** * Item template provided programmatically. Takes precedence over a content * `ng-template[igxVirtualItem]` when both are provided. * * Items are measured by their border box, so margins accumulate as drift * down the list. Use padding on the item, or a gap on a wrapper, instead. * * Only the current window is in the DOM, so assistive technology cannot * infer an item's position from the markup. Templates that render a role * with set semantics (`listitem`, `option`, `row`, ...) should map the * context's `index` and `count` onto `aria-posinset` and `aria-setsize`. * * Item elements are recycled: bind all item state and write user changes * back to the item, or unbound DOM state (e.g. a toggled checkbox) shows on * another item. See `keyFunction`. */ readonly itemTemplate: import("@angular/core").InputSignal> | null>; /** * Returns a unique key from an item and its index in the whole collection. An item keeps its * element while its key stays rendered. Defaults to the index; set it when items move within * `data` (sort, insert, remove). * * @example * ```html * ... * ``` * ```ts * byId = (person: Person) => person.id; * ``` */ readonly keyFunction: import("@angular/core").InputSignal | null>; /** Emitted when the rendered virtual window changes. */ readonly stateChange: import("@angular/core").OutputEmitterRef; /** * Emitted when the rendered window comes within a few items of the end of * `data`. Also emitted on the first render, when the loaded items do not * fill the viewport. Listen to this event to append more items * (infinite / remote scrolling). */ readonly dataRequest: import("@angular/core").OutputEmitterRef; protected readonly _isVertical: import("@angular/core").Signal; protected readonly _resolvedTemplate: import("@angular/core").Signal> | null>; /** * What the component has to work with, from whichever data input is in use. A page is * trusted to be no longer than the collection it says it belongs to. */ private readonly _loaded; /** The measured size once the host has been laid out, the hint until then. */ private readonly _effectiveViewportSize; /** The configured `overScan`, normalized to a non-negative integer. */ private readonly _normalizedOverScan; /** The configured `estimatedItemSize`, normalized to a positive number. */ private readonly _normalizedItemSize; /** * The window to render for the current scroll position and viewport. Empty * until an item template is resolved, because nothing renders without one. * * The scroll position is read from the plain `_scrollPosition` field so * that a recompute triggered by a measurement uses the live offset, while * `_scrollTick` limits recomputes to scrolls that actually move the window. */ private readonly _visibleRange; /** The track size, in DOM space. */ protected readonly _spaceSize: import("@angular/core").Signal; /** The part of the rendered range a page actually covers. */ private readonly _loadedRange; /** The key of each rendered item: from `keyFunction`, or its index. */ protected readonly _itemKey: import("@angular/core").Signal<(context: IgxVsItemContext) => unknown>; /** The item contexts for the currently rendered window, in render order. */ protected readonly _renderedItems: import("@angular/core").Signal[]>; /** * The `translateY` / `translateX` for the content wrapper. It is absolutely * positioned at the origin of a `domSize` px track, so translating it to * the first rendered item's offset puts that item at its virtual position. */ protected readonly _contentTransform: import("@angular/core").Signal; constructor(); ngOnDestroy(): void; /** * Resolves when the virtual scroll has settled: the current render pass is * complete, the item-size measurements it triggers are complete, and so * are the renders those measurements schedule. */ get layoutComplete(): Promise; /** * Scrolls to the specified item index. * * Items outside the rendered window have only an estimated size, so the * first jump can miss the target. The items at the landing point are then * measured and the scroll position is corrected, until the offset is * stable. The returned promise resolves on that final offset; callers that * need only the first, approximate scroll can ignore it, because the first * jump is applied before the call returns. * * @param index The index of the item to scroll to. * @param options `block` / `inline` select the alignment (`start`, * `center`, `end` or `nearest`, which scrolls the smallest distance that * brings the item into view); `behavior` selects `auto` or `smooth`. */ scrollToIndex(index: number, options?: ScrollIntoViewOptions): Promise; /** * Re-reads the host's direction, which `dir` can change at runtime. `:dir()` * is a selector match, so this costs no layout. */ private _syncDirection; /** The current real scroll position on the active axis, normalized for RTL. */ private _currentAxisScroll; /** Applies a scroll offset to the active axis, accounting for RTL. */ private _applyScroll; /** * The scroll offset that aligns `index` in the viewport according to * `options`, from the engine's current size data. As more items are * measured, the same input can give a different, more accurate result. */ private _getAlignedScrollOffset; /** * Applies a scroll offset to the active axis and waits for the scroll, * instant or smooth, to settle. * * `scrollend` does not fire when the requested offset does not move the * scroll position, so that case resolves immediately. The deadline covers * an event that never arrives, for example when the element is detached * mid-scroll. */ private _scrollAndWaitForEnd; private _waitForScrollEnd; /** * Resolves when no `scroll` event arrives for `SCROLL_IDLE_MS`: the closest * replacement for `scrollend`. The first timer starts immediately, so a * scroll that does not move still settles. */ private _waitForScrollIdle; /** A promise whose subscription work stays out of the Angular zone. */ private _promiseOutsideZone; /** * Resolves with `task` or with a deadline of `ms`, whichever comes first. * The signal then tears down the other, so no live timer or dangling * listener remains. */ private _withDeadline; /** * Resolves on the next animation frame, or after `LAYOUT_FRAME_TIMEOUT_MS` * when no frame arrives. A hidden tab or a detached element gets no frames * and has no layout to wait for, so resolving early there is safe. */ private _nextFrame; /** * Waits out the frames in which the item measurements land. Each * measurement that changes a size bumps the engine's version and schedules * another render, so the layout has settled once the version holds still * across two consecutive frames. */ private _resolveLayoutComplete; /** Whether the host has a box, as opposed to being hidden or detached. */ private _isLaidOut; private _measureViewport; private _setupViewportResizeObserver; private _setupScrollListener; /** * Records the new scroll offset and invalidates the rendered window only * when it actually moves. Without the guard, a scroll inside a single item * would schedule a change detection pass for an identical result. */ private _handleScroll; /** * Re-reads the scroll offset outside a scroll event. Detaching the host resets the offset * without one, and the event for a scroll that was just applied may not have arrived yet. */ private _syncScrollPosition; private _handleItemResize; /** * Synchronizes the item observer with the rendered window, applying only * the difference. A newly observed element gets one initial measurement. * * An element whose `data-index` changed is re-registered, because * `observe` on an already observed element is a no-op. The wrapper elements * are recycled, so after a scroll the same element can host a different * item at an identical size. The observer stays quiet about that and the * new index would keep its estimated size. */ private _scheduleItemMeasurement; /** * Forgets the wrappers from `index` on, so the next pass registers them * again: the engine dropped their sizes, and a wrapper whose size did not * change reports nothing on its own. */ private _remeasureFrom; private _getItemResizeObserver; /** * The number of leading items that kept their identity across a `data` * change: the index of the first item whose measured size no longer * matches its rendered content. An append (the `dataRequest` flow) retains * all items. A filter or a replacement retains only the unchanged prefix. */ private _firstChangedIndex; /** * How many leading items keep their measured size across a change. A page of the same * collection keeps all of them - its indices still mean the same records. A page with * another `totalCount` comes from a filtered or otherwise different collection, and * switching inputs starts over, so neither keeps any. */ private _retainCount; /** * Emits `stateChange`. Skipped when the window is empty or equal to the * last reported one, because measurement passes re-render without a window * change. */ private _emitStateChange; private _checkDataRequest; private _teardown; static ɵfac: i0.ɵɵFactoryDeclaration, never>; static ɵcmp: i0.ɵɵComponentDeclaration, "igx-virtual-scroll", never, { "data": { "alias": "data"; "required": false; "isSignal": true; }; "orientation": { "alias": "orientation"; "required": false; "isSignal": true; }; "overScan": { "alias": "overScan"; "required": false; "isSignal": true; }; "estimatedItemSize": { "alias": "estimatedItemSize"; "required": false; "isSignal": true; }; "dataWindow": { "alias": "dataWindow"; "required": false; "isSignal": true; }; "initialViewportSize": { "alias": "initialViewportSize"; "required": false; "isSignal": true; }; "itemTemplate": { "alias": "itemTemplate"; "required": false; "isSignal": true; }; "keyFunction": { "alias": "keyFunction"; "required": false; "isSignal": true; }; }, { "stateChange": "stateChange"; "dataRequest": "dataRequest"; }, ["_itemDirective"], never, true, never>; } /** * Directive to mark an `ng-template` as the item template for the virtual scroll component. * The template provided by this directive will be used to render each item in the virtual scroll. * The context for the template will include the item data and its index. * * @example * ```html * * *
{{ i }}: {{ item }}
*
*
* ``` */ export declare class IgxVirtualItemDirective { readonly template: TemplateRef>; static ɵfac: i0.ɵɵFactoryDeclaration, never>; static ɵdir: i0.ɵɵDirectiveDeclaration, "ng-template[igxVirtualItem]", never, {}, {}, never, never, true, never>; }