igniteui-webcomponents 7.2.4 → 7.3.0-beta.1

package/components/virtualization/virtualization.d.ts

@@ -0,0 +1,249 @@
+import { LitElement, nothing, type PropertyValues, type TemplateResult } from 'lit';
+import type { Constructor } from '#internals/mixins/constructor.js';
+import { VirtualScrollEngine } from './engine.js';
+import { type VirtualScrollDataRequest, VirtualScrollItemContext, type VirtualScrollState } from './types.js';
+export type VirtualScrollItemTemplate<T> = (context: VirtualScrollItemContext<T>) => TemplateResult | typeof nothing;
+export interface IgcVirtualScrollComponentEventMap {
+    igcStateChange: CustomEvent<VirtualScrollState>;
+    igcDataRequest: CustomEvent<VirtualScrollDataRequest>;
+}
+declare const IgcVirtualScrollComponent_base: Constructor<import("#internals/mixins/event-emitter.js").EventEmitterInterface<IgcVirtualScrollComponentEventMap>> & Constructor<LitElement>;
+/**
+ * A virtual scroll component for large lists. Only the items visible in the
+ * viewport are rendered.
+ *
+ * @element igc-virtual-scroll
+ *
+ * @fires igcStateChange - Emitted when the rendered virtual window changes.
+ * @fires igcDataRequest - 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.
+ *
+ * @csspart virtualization-track - The full-size element that gives the host its scrollable extent.
+ * @csspart virtualization-content - The wrapper that holds the rendered items, translated into
+ * position within the track.
+ */
+export default class IgcVirtualScrollComponent<T = any> extends IgcVirtualScrollComponent_base {
+    static readonly tagName = "igc-virtual-scroll";
+    static register(): void;
+    private static _styleSheet;
+    private static _getStyleSheet;
+    protected readonly _engine: VirtualScrollEngine;
+    private readonly _contentRef;
+    private readonly _itemResizeController;
+    private _currentRange;
+    /**
+     * The item index each wrapper element was last observed under. Lit reuses
+     * the wrapper elements across renders. After a scroll, the same element
+     * can host a different item at an identical size, and a ResizeObserver
+     * does not report that. See `_scheduleItemMeasurement`.
+     */
+    private readonly _observedItemIndexes;
+    private _lastEmittedState;
+    private _hasPendingDataRequest;
+    private _layoutCompletePromise;
+    private _scrollRequestId;
+    /**
+     * The `startIndex` of the last emitted `igcDataRequest`, which is also the
+     * item count at that emit. See `_checkDataRequest`.
+     *
+     * Kept across a disconnect, like `_hasPendingDataRequest`: a move in the
+     * DOM does not undo what the consumer was already asked for. If only one
+     * of the two were cleared, the request loop would reopen on reconnect.
+     */
+    private _lastDataRequestIndex;
+    /**
+     * The live scroll offset on the active axis. Not reactive by design:
+     * `render` reads it only through `_currentRange`, so `_handleScroll`
+     * schedules an update only when the window moves.
+     */
+    private _scrollPosition;
+    private _viewportSize;
+    /**
+     * The array of items to virtualize.
+     *
+     * Compared by reference: a mutation in place (`data.push(...)`) causes no
+     * update. Assign a new array instead. The `igcDataRequest` flow also
+     * expects a new array.
+     */
+    data: T[];
+    /**
+     * Scroll orientation of the virtual scroll.
+     * @attr orientation
+     * @default 'vertical'
+     */
+    orientation: 'vertical' | 'horizontal';
+    /**
+     * Number of extra items to render beyond the visible area of the viewport.
+     * Higher values reduce blank flashes during fast scrolling but can lower performance.
+     * @attr over-scan
+     * @default 2
+     */
+    overScan: number;
+    /**
+     * Estimated item size in pixels, used before an item is measured in the DOM.
+     * After the first render of an item, the engine replaces the estimate with the measured size.
+     * @attr estimated-item-size
+     * @default 50
+     */
+    estimatedItemSize: number;
+    /**
+     * A function that renders each item in the virtual scroll list.
+     * Receives a VirtualScrollItemContext<T> with the item data, its index, and the total count.
+     * Without it, nothing is rendered.
+     *
+     * 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 (`option`, `listitem`, `row`, ...) should map the
+     * context's `index` and `count` onto `aria-posinset` and `aria-setsize`.
+     */
+    itemTemplate: VirtualScrollItemTemplate<T> | null;
+    private _adoptStyles;
+    constructor();
+    /** @internal */
+    createRenderRoot(): HTMLElement | DocumentFragment;
+    /** @internal */
+    connectedCallback(): void;
+    /** @internal */
+    disconnectedCallback(): void;
+    protected willUpdate(changed: PropertyValues<this>): void;
+    protected updated(_changed: PropertyValues<this>): void;
+    protected render(): TemplateResult;
+    private get _isVertical();
+    /** The configured `overScan`, normalized to a non-negative integer. */
+    private get _normalizedOverScan();
+    /** The configured `estimatedItemSize`, normalized to a positive number. */
+    private get _normalizedItemSize();
+    /** `data`, guarded against a nullish value set by the consumer. */
+    private get _items();
+    /**
+     * The window to render for the current scroll position and viewport. Empty
+     * until an `itemTemplate` is set, because nothing renders without one.
+     */
+    private _computeRange;
+    /**
+     * 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.
+     *
+     * For `block: 'nearest'` on an item already in view, returns the current
+     * offset, so no scroll occurs.
+     */
+    private _getAlignedScrollOffset;
+    /** Applies a scroll offset to the correct axis, accounting for RTL. */
+    private _applyScroll;
+    /** The current real scroll position on the active axis, normalized for RTL. */
+    private _currentAxisScroll;
+    /**
+     * 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 timeout covers
+     * an event that never arrives, for example when the element disconnects
+     * mid-scroll.
+     */
+    private _scrollAndWaitForEnd;
+    /**
+     * 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;
+    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;
+    private _timeout;
+    private _measureViewport;
+    /**
+     * Records the new scroll offset. Schedules a render only when the rendered
+     * window moves.
+     *
+     * `render` derives the track size, the content translate, and the item
+     * slice from `_currentRange`, not from the scroll offset. Without the
+     * guard, a scroll inside one item would re-run each item template for an
+     * identical result. `willUpdate` still recomputes `_currentRange` for each
+     * other trigger, so this suppresses only redundant passes, never a needed
+     * one.
+     */
+    private _handleScroll;
+    /**
+     * 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 `igcDataRequest` flow)
+     * retains all items. A filter or a replacement retains only the unchanged
+     * prefix.
+     */
+    private _firstChangedIndex;
+    private _handleItemResize;
+    /**
+     * Synchronizes the item observer with the rendered window and applies only
+     * the difference. A newly observed element gets one initial measurement.
+     * An `observe` call on an already observed element is a no-op, so a
+     * re-measurement on demand requires re-registration: unobserve, then
+     * observe.
+     *
+     * Re-registration is applied to each element whose `data-vs-index`
+     * changed. Lit reuses the wrapper elements across renders, so after a
+     * scroll the same element can host a different item at an identical size.
+     * The observer does not report that, and the new index would keep its
+     * estimated size.
+     */
+    private _scheduleItemMeasurement;
+    /**
+     * Emits `igcStateChange`. 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;
+    /**
+     * Resolves on the next animation frame, or after `LAYOUT_FRAME_TIMEOUT_MS`
+     * when no frame arrives. A hidden tab or a disconnected element gets no
+     * frames, and `layoutComplete` must still settle there. That state has no
+     * layout to wait for, so an early resolve is safe.
+     */
+    private _nextFrame;
+    /**
+     * Waits for the current update, then lets ResizeObserver item measurements
+     * run. When those schedule a follow-up render, for example an estimate
+     * replaced by a measured size, the wait repeats until nothing is pending,
+     * up to a safety cap.
+     */
+    private _resolveLayoutComplete;
+    /**
+     * 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.
+     *
+     * `updateComplete` covers one Lit render pass. This covers `data` changes,
+     * scrolls, and viewport resizes, where the stable DOM state comes after
+     * one or more follow-up renders.
+     */
+    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. This repeats until the
+     * offset is stable.
+     *
+     * The returned promise resolves when the scroll settles on the final,
+     * corrected offset. Callers that need only the first, approximate scroll
+     * can ignore it.
+     */
+    scrollToIndex(index: number, options?: ScrollIntoViewOptions): Promise<void>;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'igc-virtual-scroll': IgcVirtualScrollComponent;
+    }
+}
+export {};