igniteui-angular 22.1.4 → 22.2.0-rc.1

package/virtual-scroll/README.md

@@ -0,0 +1,332 @@
+# IgxVirtualScrollComponent
+
+A high-performance virtual-scrolling component that renders only the items visible inside the viewport (plus a configurable over-scan buffer). It supports both vertical and horizontal axes, variable item sizes measured at runtime, lists far larger than the browser's maximum scroll coordinate, and remote / infinite scrolling through the `dataRequest` event.
+
+## Imports
+
+```ts
+import {
+    IgxVirtualScrollComponent,
+    IgxVirtualItemDirective,
+} from 'igniteui-angular/virtual-scroll';
+```
+
+---
+
+## Basic usage
+
+Define your list and provide a template using the `igxVirtualItem` directive:
+
+```html
+<igx-virtual-scroll [data]="items" style="height: 400px;">
+    <ng-template igxVirtualItem let-item let-i="index">
+        <div class="list-row">{{ i }}: {{ item.name }}</div>
+    </ng-template>
+</igx-virtual-scroll>
+```
+
+```ts
+@Component({ /* ... */ })
+export class MyComponent {
+    items = Array.from({ length: 10_000 }, (_, i) => ({ name: `Item ${i}` }));
+}
+```
+
+---
+
+## Inputs
+
+| Input | Type | Default | Description |
+|---|---|---|---|
+| `data` | `T[]` | `[]` | The array of items to virtualize. Compared by reference. See [Updating `data`](#updating-data). |
+| `dataWindow` | `VirtualDataWindow<T> \| null` | `null` | A loaded page of a larger collection. Takes the place of `data` while it is set. See [Paged data](#paged-data). |
+| `orientation` | `'vertical' \| 'horizontal'` | `'vertical'` | Scroll axis. |
+| `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]`. |
+
+
+### Paged data
+
+For data that arrives a page at a time, bind `dataWindow` instead of `data`:
+
+```ts
+interface VirtualDataWindow<T> {
+    readonly items: readonly T[]; // The loaded page
+    readonly startIndex: number;  // The index items[0] has in the whole collection
+    readonly totalCount: number;  // How many items the whole collection has
+}
+```
+
+The list is as long as `totalCount`, so the scrollbar spans the whole collection while only
+the page is in memory. An index in the list is an index in that collection: the item at
+`index` is `items[index - startIndex]`, and `IgxVsItemContext.index` and `.count` are the
+global index and the total. Indices the page does not cover render nothing, so no template
+is instantiated for an item that has not arrived.
+
+`stateChange` reports the range the viewport wants, which is what a consumer supplies the
+next page from:
+
+```ts
+load(state: VirtualScrollState) {
+    const startIndex = state.startIndex;
+    this.service.fetch(startIndex, state.endIndex - startIndex + 1)
+        .subscribe(page => this.window = { items: page.rows, startIndex, totalCount: page.total });
+}
+```
+
+Sizes are measured and kept per index, and the rows a new page renders are measured again in
+the DOM, so moving the window costs the page rather than the collection. This assumes the
+indexing stays stable while `totalCount` holds. A page with another `totalCount` is taken as a
+different collection, a filtered one for instance, and every size is measured again. A sort that
+keeps the count but puts different records at the same indices leaves the sizes measured for the
+previous ones in place, for the indices that are not re-rendered.
+
+`dataRequest` is not emitted in this mode — it asks for items to append, which a sized
+collection does not need.
+
+Paging keeps the *items* down to a page, not the size bookkeeping. The engine holds one size
+entry per index, so its memory grows with `totalCount` rather than with the page: roughly
+17 MB per million items. Give `totalCount` the size of the collection the consumer really
+pages through; a value far beyond what the platform can allocate fails at the allocation.
+
+### Lists inside a popup
+
+A list inside a drop-down, dialog or any other container that is hidden until it opens has
+no size to measure in the change detection pass that reveals it. The component learns its
+size from a `ResizeObserver` and from `afterNextRender`, both of which run after a render,
+so that first render is laid out against a viewport of zero and produces no rows. The rows
+arrive in the next frame, once the host has been measured.
+
+A wrapper that reacts to whether the list has children can flip state between those passes,
+which Angular reports as `NG0100` in development mode. Read the rows after `layoutComplete`
+instead.
+
+A host with no box at all — hidden or detached — is not measured, because the zero it reports
+says nothing about how large it will be once shown. Its last measurement is kept so the list
+renders its window in the pass that reveals it again. The deliberate consequence is that the
+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.
+
+---
+
+## Outputs
+
+| Output | Payload | Description |
+|---|---|---|
+| `stateChange` | `VirtualScrollState` | Emitted when the virtual window changes. It reports the range the viewport wants, over-scan included; with `dataWindow` bound that range can reach past the loaded page, so it is not always the set of rows in the DOM. Consecutive renders that produce an identical window are not re-emitted. |
+| `dataRequest` | `VirtualScrollDataRequest` | Emitted when the rendered window comes within a few items of the end of `data`. Use this to implement infinite / remote scrolling. |
+
+---
+
+## Public API
+
+### `scrollToIndex(index: number, options?: ScrollIntoViewOptions): Promise<void>`
+
+Scrolls the viewport to the item at `index`.
+
+Items outside the rendered window only have an *estimated* size, so the first jump can miss the target. The component measures the items at the landing point and corrects the scroll position, repeating until the offset is stable. The returned promise resolves on that final offset; callers that only need the first, approximate scroll can ignore it.
+
+```ts
+@ViewChild(IgxVirtualScrollComponent) vs!: IgxVirtualScrollComponent<any>;
+
+// Leading edge, instant (the default).
+await this.vs.scrollToIndex(500);
+
+// Centered, animated.
+await this.vs.scrollToIndex(500, { block: 'center', behavior: 'smooth' });
+
+// Only scroll if the item is not already fully visible.
+await this.vs.scrollToIndex(500, { block: 'nearest' });
+```
+
+| Option | Values | Notes |
+|---|---|---|
+| `block` | `'start'` \| `'center'` \| `'end'` \| `'nearest'` | Alignment on the vertical axis. Defaults to `'start'`. |
+| `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' })`.
+
+Out-of-range indices are clamped to the data, and the resulting offset is clamped to the largest reachable scroll position.
+
+### `layoutComplete: Promise<void>`
+
+Resolves once the virtual scroll has settled: the current render pass is complete, the item-size measurements it triggered are complete, and so are the renders those measurements scheduled.
+
+Useful when you need to read the resulting DOM after a `data` change, a scroll, or a viewport resize:
+
+```ts
+this.items = await this.service.fetch();
+await this.vs.layoutComplete;
+// The rendered window and the track size now reflect the new data.
+```
+
+---
+
+## `IgxVirtualItemDirective`
+
+Marks an `ng-template` as the item template for the nearest `igx-virtual-scroll`. The template context is typed as `IgxVsItemContext<T>`.
+
+### Template context variables
+
+| Variable | Type | Description |
+|---|---|---|
+| `$implicit` (or `let-item`) | `T` | The current item. |
+| `index` | `number` | The item's index within the full data array. |
+| `count` | `number` | Total number of items in `data`. |
+| `first` | `boolean` | `true` when `index === 0`. |
+| `last` | `boolean` | `true` when `index === count - 1`. |
+| `even` | `boolean` | `true` when `index` is even. |
+| `odd` | `boolean` | `true` when `index` is odd. |
+
+```html
+<ng-template igxVirtualItem let-item let-i="index" let-first="first">
+    <div [class.first-row]="first">{{ i }}: {{ item }}</div>
+</ng-template>
+```
+
+---
+
+## Output type reference
+
+### `VirtualScrollState`
+
+```ts
+interface VirtualScrollState {
+    startIndex: number;   // First item index of the wanted range
+    endIndex: number;     // Last item index of the wanted range (inclusive)
+    viewportSize: number; // Viewport height (or width) in px
+    totalSize: number;    // Total virtual content size in px
+}
+```
+
+The range is what the viewport wants, the over-scan buffer included. Bound to `data` that is
+the set of rows in the DOM. Bound to `dataWindow` it is the range to load next, and the rows
+actually rendered are its intersection with the page - which can be narrower, or empty.
+
+### `VirtualScrollDataRequest`
+
+```ts
+interface VirtualScrollDataRequest {
+    startIndex: number; // First index that does not yet have data
+    count: number;      // Suggested number of items to fetch
+}
+```
+
+---
+
+## Updating `data`
+
+`data` is compared **by reference**. Mutating the array in place (`items.push(...)`) does not trigger an update. Assign a new array instead.
+
+The component diffs the new array against the previous one to decide which item measurements it can keep:
+
+* **Appending** (`[...items, ...more]`) keeps the identity of every existing index, so all previous measurements are retained.
+* **Replacing, filtering or sorting** invalidates every index from the first difference onwards; those items are measured again on their next render.
+
+---
+
+## 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.
+
+```html
+<igx-virtual-scroll [data]="items" orientation="horizontal" style="width: 100%; height: 60px;">
+    <ng-template igxVirtualItem let-item>
+        <div class="col" style="width: 120px; height: 60px;">{{ item }}</div>
+    </ng-template>
+</igx-virtual-scroll>
+```
+
+Right-to-left (RTL) layouts are fully supported. When the component (or an ancestor) sets `dir="rtl"`, horizontal scrolling, content positioning, and `scrollToIndex` are mirrored automatically. No extra configuration is required.
+
+---
+
+## Infinite / remote scrolling
+
+Listen to the `dataRequest` output and append more items to the `data` array:
+
+```html
+<igx-virtual-scroll [data]="items" (dataRequest)="loadMore($event)" style="height: 500px;">
+    <ng-template igxVirtualItem let-item>
+        <div class="row">{{ item.label }}</div>
+    </ng-template>
+</igx-virtual-scroll>
+```
+
+```ts
+loadMore(req: VirtualScrollDataRequest) {
+    this.myService.fetch(req.startIndex, req.count).subscribe(newItems => {
+        this.items = [...this.items, ...newItems];
+    });
+}
+```
+
+`dataRequest` is also emitted on the **first render** when the initially loaded items do not fill the viewport, so a short initial `data` array is enough to start the loading chain. An **empty** array is not: with nothing loaded there is no rendered window to run out of, so load the first page yourself and let `dataRequest` carry the rest.
+
+Only one request is in flight at a time: the next one is emitted after `data` changes. If your source is exhausted and you reassign `data` without adding items, the component will not ask again for the same `startIndex`.
+
+---
+
+## Programmatic template
+
+Pass a `TemplateRef` via `[itemTemplate]` when the template is defined outside the component:
+
+```html
+<ng-template #myTpl let-item>
+    <div>{{ item }}</div>
+</ng-template>
+
+<igx-virtual-scroll [data]="items" [itemTemplate]="myTpl" style="height: 400px;" />
+```
+
+---
+
+## Styling and DOM structure
+
+```html
+<igx-virtual-scroll class="igx-virtual-scroll" data-orientation="vertical" role="list">
+    <div class="igx-virtual-scroll__track" role="presentation">      <!-- full virtual extent -->
+        <div class="igx-virtual-scroll__content" role="presentation"><!-- translated into position -->
+            <div class="igx-virtual-item" role="presentation" data-index="12">
+                <!-- your item template -->
+            </div>
+            ...
+        </div>
+    </div>
+</igx-virtual-scroll>
+```
+
+| Class / attribute | Element | Notes |
+|---|---|---|
+| `igx-virtual-scroll` | Host | Always present. |
+| `data-orientation` | Host | Reflects the `orientation` input: `"vertical"` or `"horizontal"`. |
+| `igx-virtual-scroll__track` | Inner spacer div | Sized to the full virtual height/width. |
+| `igx-virtual-scroll__content` | Rendered-items wrapper | Absolutely positioned; translated to the correct virtual offset. |
+| `igx-virtual-item` | Per-item wrapper | One per rendered item; carries `data-index` and is the element the engine measures. |
+
+The host element must have a **fixed height** (vertical) or **fixed width** (horizontal) and `overflow: auto` or `overflow: scroll`. The default styles already set this.
+
+### Item sizing
+
+Items are measured by their **border box**, so margins are not included and accumulate as drift down the list. Use `padding` on the item, or a `gap` on a wrapper, instead of margins.
+
+### Accessibility
+
+Only the current window is in the DOM, so assistive technology cannot infer an item's position from the markup. The host carries `role="list"`; if your template renders a role with set semantics (`listitem`, `option`, `row`, ...), map the context's `index` and `count` onto `aria-posinset` and `aria-setsize`:
+
+```html
+<ng-template igxVirtualItem let-item let-i="index" let-count="count">
+    <div role="listitem" [attr.aria-posinset]="i + 1" [attr.aria-setsize]="count">
+        {{ item }}
+    </div>
+</ng-template>
+```
+
+---
+
+## Very large lists
+
+Browsers cap how far an element can scroll. When the total item size exceeds that limit, the component compresses the virtual coordinate space into the range the browser can represent and scales scroll positions accordingly. Items still render at their real pixel size, so lists of millions of items scroll correctly with no configuration.