igniteui-angular 22.1.4 → 22.2.0-rc.1

package/types/igniteui-angular-virtual-scroll.d.ts

@@ -0,0 +1,408 @@
+import * as _angular_core from '@angular/core';
+import { OnDestroy, TemplateRef } from '@angular/core';
+
+/** Template context for a single item of the virtual scroll. */
+declare class IgxVsItemContext<T> {
+    /** 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;
+}
+/**
+ * How `scrollToIndex` positions the requested item in the viewport.
+ * The subset of `ScrollLogicalPosition` that the engine supports.
+ */
+type ScrollAlignment = "start" | "center" | "end";
+/** The currently rendered (visible plus over-scanned) range of items. */
+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. */
+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.
+ */
+interface VirtualDataWindow<T> {
+    /** 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.
+ */
+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
+ * <igx-virtual-scroll [data]="items" style="height: 400px">
+ *   <ng-template igxVirtualItem let-item let-i="index">
+ *     <div>{{ i }}: {{ item }}</div>
+ *   </ng-template>
+ * </igx-virtual-scroll>
+ * ```
+ */
+declare class IgxVirtualScrollComponent<T> 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;
+    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: _angular_core.InputSignal<T[]>;
+    /**
+     * Scroll orientation of the virtual scroll.
+     * Can be either "vertical" or "horizontal".
+     * Default is "vertical".
+     */
+    readonly orientation: _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: _angular_core.InputSignal<number>;
+    /**
+     * 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.
+     * Default is 50 pixels.
+     * Setting this to a value close to the actual average item size can improve initial rendering performance.
+     */
+    readonly estimatedItemSize: _angular_core.InputSignal<number>;
+    /**
+     * 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
+     * <igx-virtual-scroll [dataWindow]="page" (stateChange)="load($event)" style="height: 400px">
+     *   <ng-template igxVirtualItem let-item>{{ item?.name }}</ng-template>
+     * </igx-virtual-scroll>
+     * ```
+     */
+    readonly dataWindow: _angular_core.InputSignal<VirtualDataWindow<T> | 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: _angular_core.InputSignal<number>;
+    /**
+     * 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`.
+     */
+    readonly itemTemplate: _angular_core.InputSignal<TemplateRef<IgxVsItemContext<T>> | null>;
+    /** Emitted when the rendered virtual window changes. */
+    readonly stateChange: _angular_core.OutputEmitterRef<VirtualScrollState>;
+    /**
+     * 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: _angular_core.OutputEmitterRef<VirtualScrollDataRequest>;
+    protected readonly _isVertical: _angular_core.Signal<boolean>;
+    protected readonly _resolvedTemplate: _angular_core.Signal<TemplateRef<IgxVsItemContext<any>> | 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: _angular_core.Signal<number>;
+    /** The part of the rendered range a page actually covers. */
+    private readonly _loadedRange;
+    /** The item contexts for the currently rendered window, in render order. */
+    protected readonly _renderedItems: _angular_core.Signal<IgxVsItemContext<T>[]>;
+    /**
+     * 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: _angular_core.Signal<string>;
+    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<void>;
+    /**
+     * 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.
+     *
+     * @param index The index of the item to scroll to.
+     * @param options `block` / `inline` select the alignment (`start`,
+     * `center`, `end` or `nearest`); `behavior` selects `auto` or `smooth`.
+     */
+    scrollToIndex(index: number, options?: ScrollIntoViewOptions): Promise<void>;
+    /**
+     * 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.
+     *
+     * `nearest` keeps the current offset for an item already in view and
+     * otherwise brings the item to its nearer edge, as native `scrollIntoView`
+     * does.
+     */
+    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;
+    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;
+    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. `@for` tracks by
+     * slot and reuses the wrapper elements, 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 resize 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: _angular_core.ɵɵFactoryDeclaration<IgxVirtualScrollComponent<any>, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<IgxVirtualScrollComponent<any>, "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; }; }, { "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
+ * <igx-virtual-scroll [data]="items">
+ *   <ng-template igxVirtualItem let-item let-i="index">
+ *     <div>{{ i }}: {{ item }}</div>
+ *   </ng-template>
+ * </igx-virtual-scroll>
+ * ```
+ */
+declare class IgxVirtualItemDirective<T = unknown> {
+    readonly template: TemplateRef<IgxVsItemContext<T>>;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<IgxVirtualItemDirective<any>, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<IgxVirtualItemDirective<any>, "ng-template[igxVirtualItem]", never, {}, {}, never, never, true, never>;
+}
+
+export { IgxVirtualItemDirective, IgxVirtualScrollComponent, IgxVsItemContext };
+export type { ScrollAlignment, VirtualDataWindow, VirtualScrollDataRequest, VirtualScrollState, VisibleRange };

package/types/igniteui-angular.d.ts

@@ -42,3 +42,4 @@ export * from 'igniteui-angular/tabs';
 export * from 'igniteui-angular/time-picker';
 export * from 'igniteui-angular/toast';
 export * from 'igniteui-angular/tree';
+export * from 'igniteui-angular/virtual-scroll';