igniteui-webcomponents 7.2.4 → 7.3.0-beta.0

package/components/virtualization/virtualization.d.ts

@@ -0,0 +1,235 @@
+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 that efficiently renders large lists by only
+ * rendering the items currently visible in the viewport.
+ *
+ * @element igc-virtual-scroll
+ *
+ * @fires igcStateChange - Emitted when the rendered virtual window changes.
+ * @fires igcDataRequest - Emitted whenever the rendered window comes within a few items of the
+ * end of `data` - including on the very first render, when the loaded items don't fill the viewport.
+ *
+ * @csspart virtualization-track - The full-size element that gives the host its scrollable extent.
+ * @csspart virtualization-content - The wrapper holding the currently 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;
+    private _lastEmittedState;
+    private _hasPendingDataRequest;
+    private _layoutCompletePromise;
+    private _scrollRequestId;
+    /**
+     * The `startIndex` of the last emitted `igcDataRequest`, which is also the
+     * item count it was emitted at. See `_checkDataRequest`.
+     *
+     * Outlives a disconnect, like `_hasPendingDataRequest`: what the consumer has
+     * already been asked for does not become untrue by moving the element, and
+     * clearing only one of the two would re-open the request loop on reconnect.
+     */
+    private _lastDataRequestIndex;
+    /**
+     * The live scroll offset on the active axis. Deliberately *not* reactive:
+     * nothing in `render` reads it except through `_currentRange`, so
+     * `_handleScroll` schedules an update only when the window actually moves.
+     */
+    private _scrollPosition;
+    private _viewportSize;
+    /**
+     * The array of items to virtualize.
+     *
+     * Compared by reference: mutating the array
+     * in place (`data.push(...)`) produces no update. Assign a new array
+     * instead, which is also what the `igcDataRequest` flow expects.
+     */
+    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 may impact performance.
+     * @attr over-scan
+     * @default 2
+     */
+    overScan: 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.
+     * @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.
+     * If not provided, 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 ever in the DOM, so assistive technology
+     * cannot infer an item's position from the markup. Templates rendering 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 consumer clearing it with a nullish value. */
+    private get _items();
+    /**
+     * The window to render for the current scroll position and viewport. Empty
+     * until an `itemTemplate` is set, since nothing renders without one.
+     */
+    private _computeRange;
+    /**
+     * The scroll offset that aligns `index` within the viewport according to
+     * `options`, from the engine's *current* size data. As more items get
+     * measured, the same index/options can yield a different, more accurate
+     * result.
+     *
+     * For `block: 'nearest'` on an item already in view, returns the current
+     * offset, so that no scrolling takes place.
+     */
+    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 resulting
+     * scroll - instant or smooth - to settle.
+     *
+     * `scrollend` never fires when the requested offset doesn't actually move
+     * the scroll position, so that case is short-circuited rather than waiting
+     * for it. The timeout covers the rare case of the event never arriving at
+     * all, e.g. the element being disconnected mid-scroll.
+     */
+    private _scrollAndWaitForEnd;
+    /**
+     * Resolves with whichever comes first, `task` or a deadline of `ms`.
+     * Whichever wins, the loser is torn down through the signal instead of
+     * being left behind as a live timer or a dangling listener.
+     */
+    private _withDeadline;
+    private _waitForScrollEnd;
+    /**
+     * Resolves once no `scroll` event has arrived for `SCROLL_IDLE_MS`, the
+     * closest approximation of `scrollend` without it. The first timer is armed
+     * immediately, so a scroll that never moves still settles.
+     */
+    private _waitForScrollIdle;
+    private _timeout;
+    private _measureViewport;
+    /**
+     * Records the new scroll offset and schedules a render only if it moves the
+     * rendered window.
+     *
+     * `render` derives the track size, the content translate and the item slice
+     * from `_currentRange`, and nothing from the scroll offset itself, so
+     * scrolling within a single item would otherwise re-run every item template
+     * for a pixel-identical result. `willUpdate` still recomputes
+     * `_currentRange` for every other trigger, so this can only suppress a
+     * redundant pass, never a needed one.
+     */
+    private _handleScroll;
+    /**
+     * The number of leading items that kept their identity across a `data`
+     * change, i.e. the index of the first item whose measured size no longer
+     * describes what is rendered there. Appending (the `igcDataRequest` flow)
+     * retains everything; filtering or replacing retains only the untouched
+     * prefix.
+     */
+    private _firstChangedIndex;
+    private _handleItemResize;
+    /**
+     * Brings the item observer in sync with the rendered window, applying only
+     * the difference: re-observing an already observed element makes the browser
+     * deliver another initial measurement for it, so blanket re-registration
+     * would fire a callback for every rendered item on every update pass.
+     */
+    private _scheduleItemMeasurement;
+    /**
+     * Emits `igcStateChange`, unless the window is empty or identical to the one
+     * last reported: measurement passes re-render without moving the window.
+     */
+    private _emitStateChange;
+    private _checkDataRequest;
+    /**
+     * Resolves on the next animation frame, or after `LAYOUT_FRAME_TIMEOUT_MS`
+     * if one never arrives. A hidden tab or a disconnected element is never
+     * served frames, and `layoutComplete` must still settle there. There is no
+     * layout to wait for in that state, so resolving early costs nothing.
+     */
+    private _nextFrame;
+    /**
+     * Waits for the current update to finish and then gives any
+     * ResizeObserver-driven item measurements a chance to run. If those schedule
+     * a follow-up render - an estimated size being replaced with a measured one
+     * - the wait repeats until nothing is pending, up to a safety cap.
+     */
+    private _resolveLayoutComplete;
+    /**
+     * Resolves once the virtual scroll has fully settled: the current render
+     * pass has completed *and* so have any item-size measurements it triggers,
+     * along with the renders those in turn schedule.
+     *
+     * Unlike `updateComplete`, which reflects a single Lit render pass, this
+     * covers changing `data`, scrolling or resizing the viewport, where the
+     * stable DOM state is only reached after one or more follow-up renders.
+     */
+    get layoutComplete(): Promise<void>;
+    /**
+     * Programmatically scrolls to the specified item index.
+     *
+     * Items outside the rendered window only have an *estimated* size, so the
+     * first jump may land off target. The items around where it lands are then
+     * measured and the scroll position corrected, repeating - each pass landing
+     * closer to the true target - until the offset stabilizes.
+     *
+     * The returned promise resolves once the scroll has settled on that final,
+     * corrected offset, and can be ignored by callers that only care about the
+     * initial, approximate scroll.
+     */
+    scrollToIndex(index: number, options?: ScrollIntoViewOptions): Promise<void>;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'igc-virtual-scroll': IgcVirtualScrollComponent;
+    }
+}
+export {};