igniteui-angular 22.2.0-rc.0 → 22.2.0-rc.2

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

@@ -25,6 +25,8 @@ declare class IgxVsItemContext<T> {
     /** 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. */
+type VirtualScrollKeyFunction<T> = (item: T, index: number) => unknown;
 /**
  * How `scrollToIndex` positions the requested item in the viewport.
  * The subset of `ScrollLogicalPosition` that the engine supports.
@@ -156,6 +158,7 @@ declare class IgxVirtualScrollComponent<T> implements OnDestroy {
     /**
      * 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.
      */
@@ -206,8 +209,26 @@ declare class IgxVirtualScrollComponent<T> implements OnDestroy {
      * 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: _angular_core.InputSignal<TemplateRef<IgxVsItemContext<T>> | 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
+     * <igx-virtual-scroll [data]="people" [keyFunction]="byId">...</igx-virtual-scroll>
+     * ```
+     * ```ts
+     * byId = (person: Person) => person.id;
+     * ```
+     */
+    readonly keyFunction: _angular_core.InputSignal<VirtualScrollKeyFunction<T> | null>;
     /** Emitted when the rendered virtual window changes. */
     readonly stateChange: _angular_core.OutputEmitterRef<VirtualScrollState>;
     /**
@@ -243,6 +264,8 @@ declare class IgxVirtualScrollComponent<T> implements OnDestroy {
     protected readonly _spaceSize: _angular_core.Signal<number>;
     /** 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: _angular_core.Signal<(context: IgxVsItemContext<T>) => unknown>;
     /** The item contexts for the currently rendered window, in render order. */
     protected readonly _renderedItems: _angular_core.Signal<IgxVsItemContext<T>[]>;
     /**
@@ -266,11 +289,13 @@ declare class IgxVirtualScrollComponent<T> implements OnDestroy {
      * 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.
+     * 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`); `behavior` selects `auto` or `smooth`.
+     * `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<void>;
     /**
@@ -286,10 +311,6 @@ declare class IgxVirtualScrollComponent<T> implements OnDestroy {
      * 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;
     /**
@@ -330,6 +351,8 @@ declare class IgxVirtualScrollComponent<T> implements OnDestroy {
      * 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;
@@ -339,21 +362,26 @@ declare class IgxVirtualScrollComponent<T> implements OnDestroy {
      * 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. `@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.
+     * `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 resize dropped their sizes, and a wrapper whose size did not
+     * again: the engine dropped their sizes, and a wrapper whose size did not
      * change reports nothing on its own.
      */
     private _remeasureFrom;
@@ -381,7 +409,7 @@ declare class IgxVirtualScrollComponent<T> implements OnDestroy {
     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>;
+    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; }; "keyFunction": { "alias": "keyFunction"; "required": false; "isSignal": true; }; }, { "stateChange": "stateChange"; "dataRequest": "dataRequest"; }, ["_itemDirective"], never, true, never>;
 }
 
 /**
@@ -405,4 +433,4 @@ declare class IgxVirtualItemDirective<T = unknown> {
 }
 
 export { IgxVirtualItemDirective, IgxVirtualScrollComponent, IgxVsItemContext };
-export type { ScrollAlignment, VirtualDataWindow, VirtualScrollDataRequest, VirtualScrollState, VisibleRange };
+export type { ScrollAlignment, VirtualDataWindow, VirtualScrollDataRequest, VirtualScrollKeyFunction, VirtualScrollState, VisibleRange };

package/virtual-scroll/README.md

@@ -44,6 +44,7 @@ export class MyComponent {
 | `overScan` | `number` | `2` | Extra items to render beyond each edge of the viewport. Higher values reduce blank flashes during fast scrolling at the cost of slightly more DOM nodes. Normalized to a non-negative integer. |
 | `estimatedItemSize` | `number` | `50` | Pixel size used for items before they are measured in the DOM. Set this close to the real average size for the best initial-render accuracy. A non-positive value falls back to `50`. |
 | `itemTemplate` | `TemplateRef<IgxVsItemContext<T>> \| null` | `null` | Programmatic template that takes precedence over a content `ng-template[igxVirtualItem]`. |
+| `keyFunction` | `VirtualScrollKeyFunction<T> \| null` | `null` | Returns an item's key from the item and its index. Defaults to the index. See [Item elements and keys](#item-elements-and-keys). |
 
 
 ### Paged data
@@ -109,6 +110,8 @@ rendered window stays in the DOM while the host is away.
 
 Changing `estimatedItemSize` re-applies it to every item that has **not** yet been measured in the DOM. Items that have been measured keep their real size.
 
+Unmeasured items then take the average measured size, so the scrollbar tracks real content. Later averages apply only while every item before the rendered window is measured and the list fits the browser's scroll limit, so rendered items never shift. A new `estimatedItemSize` restarts the average.
+
 ---
 
 ## Outputs
@@ -147,7 +150,7 @@ await this.vs.scrollToIndex(500, { block: 'nearest' });
 | `inline` | same as `block` | Alignment on the horizontal axis; falls back to `block`. |
 | `behavior` | `'auto'` \| `'smooth'` | Defaults to `'auto'`. |
 
-`'nearest'` leaves the scroll position untouched when the item is already fully in view, or when the item is larger than the viewport and currently covers it. Otherwise it brings the item to its nearer edge: the start for an item before the viewport, the end for one past it. This matches native `scrollIntoView({ block: 'nearest' })`.
+`'nearest'` leaves the scroll position untouched when the item is already fully in view, or when the item is larger than the viewport and currently covers it. Otherwise it scrolls the smallest distance that brings the item into view, as native `scrollIntoView({ block: 'nearest' })` does.
 
 Out-of-range indices are clamped to the data, and the resulting offset is clamped to the largest reachable scroll position.
 
@@ -228,6 +231,34 @@ The component diffs the new array against the previous one to decide which item
 
 ---
 
+## Item elements and keys
+
+Item elements are recycled: an item that stays in the window keeps its element, and leaving items hand theirs to entering ones, so a scroll step updates only the entering items. A focused element is not moved while its item stays in the window, so it keeps focus.
+
+Without `keyFunction`, elements are keyed by index. Set it when items move within `data` (sort, insert, remove), so an element follows its item:
+
+```html
+<igx-virtual-scroll [data]="people" [keyFunction]="byId" style="height: 400px;">
+    <ng-template igxVirtualItem let-person>
+        <person-card [person]="person" />
+    </ng-template>
+</igx-virtual-scroll>
+```
+
+```ts
+byId = (person: Person) => person.id;
+```
+
+Unbound DOM state, such as a checkbox toggled without `[checked]`, stays with a recycled element and shows on another item. Angular writes a binding only when its value changes, so bind all item state and write user changes back to the item:
+
+```html
+<ng-template igxVirtualItem let-task>
+    <input type="checkbox" [checked]="task.done" (change)="task.done = $any($event.target).checked" />
+</ng-template>
+```
+
+---
+
 ## Horizontal scrolling
 
 Set `orientation="horizontal"`. Items are laid out in a row; ensure each item has an explicit `width` so the engine can measure sizes correctly.