igniteui-webcomponents 7.3.0-beta.0 → 7.3.0

package/components/virtualization/engine.d.ts

@@ -1,52 +1,53 @@
 import type { ScrollAlignment, VisibleRange } from './types.js';
 /**
- * Pure scroll-math engine for a single axis of virtual scrolling. All size
- * state is held in a Fenwick tree.
+ * Pure scroll-math engine for one axis of virtual scrolling. A Fenwick tree
+ * holds all size state.
  *
- * ### Virtual vs DOM coordinates
+ * ### Virtual and DOM coordinates
  *
- * Browsers cap how far an element can be scrolled. When the summed item size
- * exceeds that cap, the engine compresses the *virtual* space (`0…totalSize`)
- * into the *DOM* space the browser can represent (`0…domSize`) by the factor
- * `_virtualRatio`. Every offset crossing that boundary is scaled: incoming
- * scroll positions are multiplied by the ratio, outgoing offsets divided by
- * it. Item sizes render at their real px size and so are always virtual.
+ * Browsers limit how far an element can scroll. When the total item size is
+ * larger than that limit, the engine compresses the *virtual* space
+ * (`0…totalSize`) into the *DOM* space the browser can represent
+ * (`0…domSize`) by the factor `_virtualRatio`. Each offset that crosses that
+ * boundary is scaled: incoming scroll positions are multiplied by the ratio,
+ * and outgoing offsets are divided by it. Items render at their real pixel
+ * size, so item sizes are always virtual.
  */
 export declare class VirtualScrollEngine {
     private _maxBrowserSize;
     /**
-     * The ratio `totalSize / maxBrowserSize` when `totalSize` exceeds the
-     * maximum DOM coordinate the browser supports; `1` otherwise.
-     * Used to map virtual scroll positions to DOM scroll positions.
+     * The ratio `totalSize / maxBrowserSize` when `totalSize` is larger than
+     * the maximum DOM coordinate the browser supports; `1` otherwise.
+     * Maps virtual scroll positions to DOM scroll positions.
      */
     private _virtualRatio;
     /** Binary Indexed Tree for O(log N) size queries and updates. */
     private _tree;
     /**
-     * Called whenever item sizes or the item count change, e.g.
-     * `() => this.requestUpdate()`.
+     * Called when item sizes or the item count change.
+     * Example: `() => this.requestUpdate()`.
      */
     onSizeChange: (() => void) | null;
     /** Total virtual size of all items in px. */
     get totalSize(): number;
     /** Total size in DOM space, clamped to the maximum browser size. */
     get domSize(): number;
-    /** Probes the document for the maximum browser size and rescales. */
+    /** Measures the maximum browser size for the document and rescales. */
     initMaxBrowserSize(doc: Document): void;
     /**
-     * Grows or shrinks the internal sizes array to `length`. Measured sizes
-     * below `retainCount` are preserved; the rest is refilled with
-     * `estimatedSize` and marked unmeasured. Callers that only append can leave
-     * `retainCount` at its default; callers whose data changed identity at some
-     * index must pass it, so the stale measurements behind it are discarded.
+     * Resizes the internal sizes array to `length`. Measured sizes below
+     * `retainCount` are kept. The remainder is filled with `estimatedSize` and
+     * marked unmeasured. Callers that only append can keep the default
+     * `retainCount`. Callers whose data changed identity at some index must
+     * pass that index, so the stale measurements after it are discarded.
      */
     resize(length: number, estimatedSize: number, retainCount?: number): void;
     /** Records the measured DOM size for a single item. */
     measureItem(index: number, size: number): void;
     /**
-     * Applies a new estimated size to every item not yet measured in the DOM.
-     * Use this when `estimatedItemSize` changes but the item count doesn't, so
-     * `resize` would be a no-op.
+     * Applies a new estimated size to each item that is not measured in the
+     * DOM. Use this when `estimatedItemSize` changes but the item count does
+     * not, because `resize` is then a no-op.
      */
     updateEstimatedSize(estimatedSize: number): void;
     /**
@@ -56,36 +57,37 @@ export declare class VirtualScrollEngine {
     getScrollOffsetForIndex(index: number): number;
     /**
      * The largest DOM scroll offset the host can reach for the given viewport
-     * size. Requesting anything beyond it silently does nothing, so offsets
-     * handed out to a caller that waits for the scroll to settle are clamped
-     * to it.
+     * size. A request beyond it does nothing, so offsets given to a caller
+     * that waits for the scroll to settle are clamped to it.
      */
     private _getMaxScrollOffset;
     /**
-     * Returns the DOM scroll offset that positions the item at `index`
-     * according to `align` within a `viewportSize` px viewport, clamped to the
+     * Returns the DOM scroll offset that positions the item at `index` in a
+     * `viewportSize` px viewport, aligned by `align` and clamped to the
      * reachable scroll range.
      *
      * The slack is computed in virtual space against the item's real size and
-     * converted to DOM space once, at the end: a DOM pixel is worth
-     * `_virtualRatio` virtual pixels, so mixing the two would scale the slack.
+     * converted to DOM space once, at the end. One DOM pixel equals
+     * `_virtualRatio` virtual pixels, so mixed coordinates would scale the
+     * slack.
      */
     getAlignedScrollOffset(index: number, viewportSize: number, align: ScrollAlignment): number;
     /**
-     * Whether the item at `index` needs no scrolling to be seen at the given DOM
-     * scroll position: either it sits entirely inside the viewport, or it is
-     * larger than the viewport and already covers it end to end. The latter
-     * mirrors native `scrollIntoView({ block: 'nearest' })`.
+     * Whether the item at `index` is visible without more scrolling at the
+     * given DOM scroll position. True when the item is fully inside the
+     * viewport, or when it is larger than the viewport and covers it fully.
+     * The second case matches native `scrollIntoView({ block: 'nearest' })`.
      */
     isIndexInView(index: number, scrollPosition: number, viewportSize: number): boolean;
     /**
-     * Returns the visible + over-scanned item range for the given scroll state.
+     * Returns the visible and over-scanned item range for the given scroll
+     * state.
      */
     getVisibleRange(scrollPosition: number, viewportSize: number, overScan: number): VisibleRange;
     /**
-     * Sum of the actual sizes of the items in [startIndex, endIndex]. Clamps the
-     * content translate offset so rendered items never overflow past `domSize`
-     * under coordinate compression.
+     * Sum of the actual sizes of the items in [startIndex, endIndex]. The
+     * render pass uses it to clamp the content translate offset, so rendered
+     * items do not overflow past `domSize` under coordinate compression.
      */
     getPhysicalRangeSize(startIndex: number, endIndex: number): number;
     private _updateVirtualRatio;

package/components/virtualization/engine.js.map

@@ -1 +1 @@
-{"version":3,"file":"engine.js","sourceRoot":"","sources":["../../../src/components/virtualization/engine.ts"],"names":[],"mappings":"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","sourcesContent":["import { clamp } from '#internals/utils/math.js';\nimport type { ScrollAlignment, VisibleRange } from './types.js';\n\n/**\n * The maximum scrollable coordinate doesn't change over a document's lifetime,\n * so instances sharing one document share a single probe.\n */\nconst _maxBrowserSizeCache = new WeakMap<Document, number>();\n\n/**\n * Probes the browser for the maximum scrollable coordinate it supports.\n */\nfunction getMaxBrowserSizeProbePx(doc: Document): number {\n  const cached = _maxBrowserSizeCache.get(doc);\n  if (cached !== undefined) {\n    return cached;\n  }\n\n  const container = doc.body ?? doc.documentElement;\n  if (!container) {\n    return Number.POSITIVE_INFINITY;\n  }\n\n  const div = doc.createElement('div');\n  div.style.position = 'absolute';\n  div.style.top = `${Number.MAX_SAFE_INTEGER}px`;\n  div.style.width = '0';\n  div.style.height = '0';\n  div.style.visibility = 'hidden';\n  container.appendChild(div);\n  const scrollOffset = doc.documentElement?.scrollTop ?? 0;\n  const size = Math.abs(div.getBoundingClientRect().top) + scrollOffset;\n  container.removeChild(div);\n\n  _maxBrowserSizeCache.set(doc, size);\n  return size;\n}\n\n/**\n * Clamps `index` into `[0, length - 1]`, keeping both `prefixSum(index)` and\n * `prefixSum(index + 1)` addressable. Callers guard for `length > 0`.\n */\nfunction clampIndex(index: number, length: number): number {\n  return clamp(index, 0, length - 1);\n}\n\n/**\n * Fills `tree` - a 1-indexed Fenwick array of `sizes.length + 1` entries,\n * expected to be zeroed - with the partial range sums of `sizes` in a single\n * O(N) pass. Returns the grand total.\n */\nfunction buildTree(tree: Float64Array, sizes: Float64Array): number {\n  const length = sizes.length;\n  let total = 0;\n\n  for (let i = 1; i <= length; i++) {\n    tree[i] += sizes[i - 1];\n    total += sizes[i - 1];\n    const j = i + (i & -i);\n    if (j <= length) {\n      tree[j] += tree[i];\n    }\n  }\n  return total;\n}\n\n/**\n * Binary Indexed Tree (Fenwick tree) over item sizes. Every hot-path\n * operation is O(log N): point update (item measured), prefix sum (scroll\n * offset) and index at offset (scroll -> item, via binary lifting).\n */\nclass SizeTree {\n  public readonly length: number;\n\n  /** 1-indexed BIT; each cell holds a partial range sum. */\n  private readonly _tree: Float64Array;\n\n  /** Raw per-item sizes (0-indexed), kept for O(1) reads and delta calc. */\n  private readonly _sizes: Float64Array;\n\n  /**\n   * Which indices hold a real, DOM-measured size (`1`) rather than an\n   * estimate (`0`). Only the latter are touched by `applyEstimate`.\n   */\n  private readonly _measured: Uint8Array;\n\n  /** Running total maintained alongside tree updates in O(1). */\n  private _total: number;\n\n  /**\n   * Highest power-of-two <= `length`, for the binary lifting in\n   * `findIndexAtOffset`. Precomputed since that runs on every scroll event.\n   */\n  private readonly _topBit: number;\n\n  private constructor(\n    length: number,\n    sizes: Float64Array,\n    tree: Float64Array,\n    total: number,\n    measured: Uint8Array\n  ) {\n    this.length = length;\n    this._sizes = sizes;\n    this._tree = tree;\n    this._total = total;\n    this._measured = measured;\n    this._topBit = length > 0 ? 1 << (31 - Math.clz32(length)) : 0;\n  }\n\n  /**\n   * Creates a tree of `length` items all initialized to `fillSize`, none of\n   * which are considered measured yet. O(N).\n   */\n  public static filled(length: number, fillSize: number): SizeTree {\n    return SizeTree._build(\n      new Float64Array(length).fill(fillSize),\n      new Uint8Array(length)\n    );\n  }\n\n  /**\n   * Builds a tree from a sizes array and its matching measured-flags array. O(N).\n   */\n  private static _build(sizes: Float64Array, measured: Uint8Array): SizeTree {\n    const tree = new Float64Array(sizes.length + 1);\n    const total = buildTree(tree, sizes);\n    return new SizeTree(sizes.length, sizes, tree, total, measured);\n  }\n\n  /** Total size of all items. O(1). */\n  public get totalSize(): number {\n    return this._total;\n  }\n\n  /**\n   * Prefix sum of items [0, i) — the virtual scroll offset at the leading\n   * edge of item i. O(log N).\n   */\n  public prefixSum(i: number): number {\n    let sum = 0;\n    for (let j = i; j > 0; j -= j & -j) {\n      sum += this._tree[j];\n    }\n    return sum;\n  }\n\n  /**\n   * Update the size of the item at 0-based index. Marks the item as\n   * explicitly measured, exempting it from future `applyEstimate()` calls.\n   * Returns true when the size actually changed. O(log N).\n   */\n  public update(index: number, newSize: number): boolean {\n    if (index < 0 || index >= this.length) return false;\n\n    const old = this._sizes[index];\n    this._measured[index] = 1;\n    if (old === newSize) return false;\n\n    const delta = newSize - old;\n    this._sizes[index] = newSize;\n    this._total += delta;\n    for (let i = index + 1; i <= this.length; i += i & -i) {\n      this._tree[i] += delta;\n    }\n    return true;\n  }\n\n  /**\n   * Returns a new tree of `newLength` items in a single O(N) pass. Sizes and\n   * their measured flags are preserved up to\n   * `min(this.length, newLength, retainCount)`; the rest is filled with\n   * `fillSize` and marked unmeasured. Pass a `retainCount` below the item\n   * count when the data behind those indices changed identity.\n   */\n  public cloneResized(\n    newLength: number,\n    fillSize: number,\n    retainCount = newLength\n  ): SizeTree {\n    const sizes = new Float64Array(newLength).fill(fillSize);\n    const measured = new Uint8Array(newLength);\n    const retained = Math.max(0, Math.min(this.length, newLength, retainCount));\n    sizes.set(this._sizes.subarray(0, retained));\n    measured.set(this._measured.subarray(0, retained));\n    return SizeTree._build(sizes, measured);\n  }\n\n  /**\n   * Applies `estimatedSize` to every unmeasured item, leaving measured ones\n   * untouched. Returns true when at least one size changed.\n   *\n   * One estimate change can affect most of the list at once, so this rebuilds\n   * in a single O(N) pass instead of one O(log N) `update` per item.\n   */\n  public applyEstimate(estimatedSize: number): boolean {\n    let changed = false;\n    for (let i = 0; i < this.length; i++) {\n      if (!this._measured[i] && this._sizes[i] !== estimatedSize) {\n        this._sizes[i] = estimatedSize;\n        changed = true;\n      }\n    }\n    if (!changed) return false;\n\n    this._tree.fill(0);\n    this._total = buildTree(this._tree, this._sizes);\n    return true;\n  }\n\n  /**\n   * Returns the 0-based index of the item containing the scroll `offset`, i.e.\n   * the largest i where `prefixSum(i) <= offset < prefixSum(i + 1)`. O(log N).\n   */\n  public findIndexAtOffset(offset: number): number {\n    if (offset <= 0 || this.length === 0) return 0;\n\n    let idx = 0;\n    let remaining = offset;\n\n    for (let bit = this._topBit; bit > 0; bit >>= 1) {\n      const next = idx + bit;\n      if (next <= this.length && this._tree[next] <= remaining) {\n        idx = next;\n        remaining -= this._tree[idx];\n      }\n    }\n    return Math.min(this.length - 1, idx);\n  }\n}\n\n/**\n * Pure scroll-math engine for a single axis of virtual scrolling. All size\n * state is held in a Fenwick tree.\n *\n * ### Virtual vs DOM coordinates\n *\n * Browsers cap how far an element can be scrolled. When the summed item size\n * exceeds that cap, the engine compresses the *virtual* space (`0…totalSize`)\n * into the *DOM* space the browser can represent (`0…domSize`) by the factor\n * `_virtualRatio`. Every offset crossing that boundary is scaled: incoming\n * scroll positions are multiplied by the ratio, outgoing offsets divided by\n * it. Item sizes render at their real px size and so are always virtual.\n */\nexport class VirtualScrollEngine {\n  private _maxBrowserSize = Number.POSITIVE_INFINITY;\n\n  /**\n   * The ratio `totalSize / maxBrowserSize` when `totalSize` exceeds the\n   * maximum DOM coordinate the browser supports; `1` otherwise.\n   * Used to map virtual scroll positions to DOM scroll positions.\n   */\n  private _virtualRatio = 1;\n\n  /** Binary Indexed Tree for O(log N) size queries and updates. */\n  private _tree: SizeTree | null = null;\n\n  /**\n   * Called whenever item sizes or the item count change, e.g.\n   * `() => this.requestUpdate()`.\n   */\n  public onSizeChange: (() => void) | null = null;\n\n  /** Total virtual size of all items in px. */\n  public get totalSize(): number {\n    return this._tree?.totalSize ?? 0;\n  }\n\n  /** Total size in DOM space, clamped to the maximum browser size. */\n  public get domSize(): number {\n    return this._virtualRatio !== 1 ? this._maxBrowserSize : this.totalSize;\n  }\n\n  /** Probes the document for the maximum browser size and rescales. */\n  public initMaxBrowserSize(doc: Document): void {\n    this._maxBrowserSize = getMaxBrowserSizeProbePx(doc);\n    this._updateVirtualRatio();\n  }\n\n  /**\n   * Grows or shrinks the internal sizes array to `length`. Measured sizes\n   * below `retainCount` are preserved; the rest is refilled with\n   * `estimatedSize` and marked unmeasured. Callers that only append can leave\n   * `retainCount` at its default; callers whose data changed identity at some\n   * index must pass it, so the stale measurements behind it are discarded.\n   */\n  public resize(\n    length: number,\n    estimatedSize: number,\n    retainCount = length\n  ): void {\n    if (this._tree?.length === length && retainCount >= length) return;\n\n    this._tree = this._tree\n      ? this._tree.cloneResized(length, estimatedSize, retainCount)\n      : SizeTree.filled(length, estimatedSize);\n    this._updateVirtualRatio();\n    this.onSizeChange?.();\n  }\n\n  /** Records the measured DOM size for a single item. */\n  public measureItem(index: number, size: number): void {\n    if (!this._tree?.update(index, size)) return;\n\n    this._updateVirtualRatio();\n    this.onSizeChange?.();\n  }\n\n  /**\n   * Applies a new estimated size to every item not yet measured in the DOM.\n   * Use this when `estimatedItemSize` changes but the item count doesn't, so\n   * `resize` would be a no-op.\n   */\n  public updateEstimatedSize(estimatedSize: number): void {\n    if (!this._tree?.applyEstimate(estimatedSize)) return;\n\n    this._updateVirtualRatio();\n    this.onSizeChange?.();\n  }\n\n  /**\n   * Returns the DOM scroll offset in px that puts the item at `index` at the\n   * leading edge of the viewport.\n   */\n  public getScrollOffsetForIndex(index: number): number {\n    if (!this._tree || index <= 0) return 0;\n\n    const clamped = Math.min(index, this._tree.length);\n    return this._tree.prefixSum(clamped) / this._virtualRatio;\n  }\n\n  /**\n   * The largest DOM scroll offset the host can reach for the given viewport\n   * size. Requesting anything beyond it silently does nothing, so offsets\n   * handed out to a caller that waits for the scroll to settle are clamped\n   * to it.\n   */\n  private _getMaxScrollOffset(viewportSize: number): number {\n    return Math.max(0, this.domSize - viewportSize);\n  }\n\n  /**\n   * Returns the DOM scroll offset that positions the item at `index`\n   * according to `align` within a `viewportSize` px viewport, clamped to the\n   * reachable scroll range.\n   *\n   * The slack is computed in virtual space against the item's real size and\n   * converted to DOM space once, at the end: a DOM pixel is worth\n   * `_virtualRatio` virtual pixels, so mixing the two would scale the slack.\n   */\n  public getAlignedScrollOffset(\n    index: number,\n    viewportSize: number,\n    align: ScrollAlignment\n  ): number {\n    if (!this._tree || this._tree.length === 0) return 0;\n\n    const clamped = clampIndex(index, this._tree.length);\n    const itemStart = this._tree.prefixSum(clamped);\n    let offset = itemStart;\n\n    if (align !== 'start') {\n      const itemEnd = this._tree.prefixSum(clamped + 1);\n      const slack = viewportSize - Math.max(0, itemEnd - itemStart);\n      offset -= align === 'center' ? slack / 2 : slack;\n    }\n\n    return clamp(\n      offset / this._virtualRatio,\n      0,\n      this._getMaxScrollOffset(viewportSize)\n    );\n  }\n\n  /**\n   * Whether the item at `index` needs no scrolling to be seen at the given DOM\n   * scroll position: either it sits entirely inside the viewport, or it is\n   * larger than the viewport and already covers it end to end. The latter\n   * mirrors native `scrollIntoView({ block: 'nearest' })`.\n   */\n  public isIndexInView(\n    index: number,\n    scrollPosition: number,\n    viewportSize: number\n  ): boolean {\n    if (!this._tree || this._tree.length === 0) return false;\n\n    const clamped = clampIndex(index, this._tree.length);\n    const itemStart = this._tree.prefixSum(clamped);\n    const itemEnd = this._tree.prefixSum(clamped + 1);\n    const viewStart = Math.max(0, scrollPosition) * this._virtualRatio;\n    const viewEnd = viewStart + viewportSize;\n\n    const contained = itemStart >= viewStart && itemEnd <= viewEnd;\n    const spanning = itemStart <= viewStart && itemEnd >= viewEnd;\n\n    return contained || spanning;\n  }\n\n  /**\n   * Returns the visible + over-scanned item range for the given scroll state.\n   */\n  public getVisibleRange(\n    scrollPosition: number,\n    viewportSize: number,\n    overScan: number\n  ): VisibleRange {\n    if (!this._tree || this._tree.length === 0 || viewportSize <= 0) {\n      return { startIndex: 0, endIndex: -1 };\n    }\n\n    // The viewport is *not* scaled by the virtual ratio: items render at their\n    // real px size, so a `viewportSize` px viewport always shows that many\n    // virtual px worth of items, however compressed the scroll range is.\n    const startOffset = Math.max(0, scrollPosition) * this._virtualRatio;\n    const first = this._tree.findIndexAtOffset(startOffset);\n    const last = this._tree.findIndexAtOffset(startOffset + viewportSize);\n\n    return {\n      startIndex: Math.max(0, first - overScan),\n      endIndex: Math.min(this._tree.length - 1, last + overScan),\n    };\n  }\n\n  /**\n   * Sum of the actual sizes of the items in [startIndex, endIndex]. Clamps the\n   * content translate offset so rendered items never overflow past `domSize`\n   * under coordinate compression.\n   */\n  public getPhysicalRangeSize(startIndex: number, endIndex: number): number {\n    if (!this._tree) return 0;\n\n    const start = Math.max(0, startIndex);\n    const end = Math.min(Math.max(endIndex + 1, start), this._tree.length);\n    return this._tree.prefixSum(end) - this._tree.prefixSum(start);\n  }\n\n  private _updateVirtualRatio(): void {\n    const totalSize = this._tree?.totalSize ?? 0;\n    this._virtualRatio =\n      totalSize <= this._maxBrowserSize ? 1 : totalSize / this._maxBrowserSize;\n  }\n}\n"]}
+{"version":3,"file":"engine.js","sourceRoot":"","sources":["../../../src/components/virtualization/engine.ts"],"names":[],"mappings":"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","sourcesContent":["import { clamp } from '#internals/utils/math.js';\nimport type { ScrollAlignment, VisibleRange } from './types.js';\n\n/**\n * The maximum scrollable coordinate of a document does not change.\n * All instances in one document share one probe result.\n */\nconst _maxBrowserSizeCache = new WeakMap<Document, number>();\n\n/**\n * Measures the maximum scrollable coordinate that the browser supports.\n */\nfunction getMaxBrowserSizeProbePx(doc: Document): number {\n  const cached = _maxBrowserSizeCache.get(doc);\n  if (cached !== undefined) {\n    return cached;\n  }\n\n  const container = doc.body ?? doc.documentElement;\n  if (!container) {\n    return Number.POSITIVE_INFINITY;\n  }\n\n  const div = doc.createElement('div');\n  div.style.position = 'absolute';\n  div.style.top = `${Number.MAX_SAFE_INTEGER}px`;\n  div.style.width = '0';\n  div.style.height = '0';\n  div.style.visibility = 'hidden';\n  container.appendChild(div);\n  const scrollOffset = doc.documentElement?.scrollTop ?? 0;\n  const size = Math.abs(div.getBoundingClientRect().top) + scrollOffset;\n  container.removeChild(div);\n\n  _maxBrowserSizeCache.set(doc, size);\n  return size;\n}\n\n/**\n * Clamps `index` into `[0, length - 1]`. This keeps `prefixSum(index)` and\n * `prefixSum(index + 1)` valid. Callers make sure that `length > 0`.\n */\nfunction clampIndex(index: number, length: number): number {\n  return clamp(index, 0, length - 1);\n}\n\n/**\n * Fills `tree` with the partial range sums of `sizes` in one O(N) pass.\n * `tree` is a 1-indexed Fenwick array of `sizes.length + 1` zeroed entries.\n * Returns the total sum.\n */\nfunction buildTree(tree: Float64Array, sizes: Float64Array): number {\n  const length = sizes.length;\n  let total = 0;\n\n  for (let i = 1; i <= length; i++) {\n    tree[i] += sizes[i - 1];\n    total += sizes[i - 1];\n    const j = i + (i & -i);\n    if (j <= length) {\n      tree[j] += tree[i];\n    }\n  }\n  return total;\n}\n\n/**\n * Binary Indexed Tree (Fenwick tree) over item sizes. Each hot-path operation\n * is O(log N): point update (item measured), prefix sum (scroll offset), and\n * index at offset (scroll to item, through binary lifting).\n */\nclass SizeTree {\n  public readonly length: number;\n\n  /** A 1-indexed BIT. Each cell holds a partial range sum. */\n  private readonly _tree: Float64Array;\n\n  /** Raw per-item sizes, 0-indexed. Kept for O(1) reads and delta calculation. */\n  private readonly _sizes: Float64Array;\n\n  /**\n   * Flags the indices that hold a DOM-measured size (`1`) instead of an\n   * estimate (`0`). `applyEstimate` changes only the estimated entries.\n   */\n  private readonly _measured: Uint8Array;\n\n  /** Running total. Updated together with the tree in O(1). */\n  private _total: number;\n\n  /**\n   * The highest power of two <= `length`, for the binary lifting in\n   * `findIndexAtOffset`. Precomputed because that runs on each scroll event.\n   */\n  private readonly _topBit: number;\n\n  private constructor(\n    length: number,\n    sizes: Float64Array,\n    tree: Float64Array,\n    total: number,\n    measured: Uint8Array\n  ) {\n    this.length = length;\n    this._sizes = sizes;\n    this._tree = tree;\n    this._total = total;\n    this._measured = measured;\n    this._topBit = length > 0 ? 1 << (31 - Math.clz32(length)) : 0;\n  }\n\n  /**\n   * Creates a tree of `length` items, each set to `fillSize` and marked\n   * unmeasured. O(N).\n   */\n  public static filled(length: number, fillSize: number): SizeTree {\n    return SizeTree._build(\n      new Float64Array(length).fill(fillSize),\n      new Uint8Array(length)\n    );\n  }\n\n  /**\n   * Builds a tree from a sizes array and its matching measured-flags array. O(N).\n   */\n  private static _build(sizes: Float64Array, measured: Uint8Array): SizeTree {\n    const tree = new Float64Array(sizes.length + 1);\n    const total = buildTree(tree, sizes);\n    return new SizeTree(sizes.length, sizes, tree, total, measured);\n  }\n\n  /** Total size of all items. O(1). */\n  public get totalSize(): number {\n    return this._total;\n  }\n\n  /**\n   * Prefix sum of items [0, i): the virtual scroll offset at the leading\n   * edge of item i. O(log N).\n   */\n  public prefixSum(i: number): number {\n    let sum = 0;\n    for (let j = i; j > 0; j -= j & -j) {\n      sum += this._tree[j];\n    }\n    return sum;\n  }\n\n  /**\n   * Sets the size of the item at a 0-based index and marks the item as\n   * measured. Later `applyEstimate()` calls do not change measured items.\n   * Returns true when the size changed. O(log N).\n   */\n  public update(index: number, newSize: number): boolean {\n    if (index < 0 || index >= this.length) return false;\n\n    const old = this._sizes[index];\n    this._measured[index] = 1;\n    if (old === newSize) return false;\n\n    const delta = newSize - old;\n    this._sizes[index] = newSize;\n    this._total += delta;\n    for (let i = index + 1; i <= this.length; i += i & -i) {\n      this._tree[i] += delta;\n    }\n    return true;\n  }\n\n  /**\n   * Returns a new tree of `newLength` items in one O(N) pass. Sizes and\n   * measured flags are kept up to `min(this.length, newLength, retainCount)`.\n   * The remainder is filled with `fillSize` and marked unmeasured. Pass a\n   * `retainCount` below the item count when the data behind those indices\n   * changed identity.\n   */\n  public cloneResized(\n    newLength: number,\n    fillSize: number,\n    retainCount = newLength\n  ): SizeTree {\n    const sizes = new Float64Array(newLength).fill(fillSize);\n    const measured = new Uint8Array(newLength);\n    const retained = Math.max(0, Math.min(this.length, newLength, retainCount));\n    sizes.set(this._sizes.subarray(0, retained));\n    measured.set(this._measured.subarray(0, retained));\n    return SizeTree._build(sizes, measured);\n  }\n\n  /**\n   * Sets `estimatedSize` on each unmeasured item. Measured items do not\n   * change. Returns true when at least one size changed.\n   *\n   * One estimate change can touch most of the list, so this rebuilds in one\n   * O(N) pass instead of one O(log N) `update` per item.\n   */\n  public applyEstimate(estimatedSize: number): boolean {\n    let changed = false;\n    for (let i = 0; i < this.length; i++) {\n      if (!this._measured[i] && this._sizes[i] !== estimatedSize) {\n        this._sizes[i] = estimatedSize;\n        changed = true;\n      }\n    }\n    if (!changed) return false;\n\n    this._tree.fill(0);\n    this._total = buildTree(this._tree, this._sizes);\n    return true;\n  }\n\n  /**\n   * Returns the 0-based index of the item that contains the scroll `offset`:\n   * the largest i where `prefixSum(i) <= offset < prefixSum(i + 1)`. O(log N).\n   */\n  public findIndexAtOffset(offset: number): number {\n    if (offset <= 0 || this.length === 0) return 0;\n\n    let idx = 0;\n    let remaining = offset;\n\n    for (let bit = this._topBit; bit > 0; bit >>= 1) {\n      const next = idx + bit;\n      if (next <= this.length && this._tree[next] <= remaining) {\n        idx = next;\n        remaining -= this._tree[idx];\n      }\n    }\n    return Math.min(this.length - 1, idx);\n  }\n}\n\n/**\n * Pure scroll-math engine for one axis of virtual scrolling. A Fenwick tree\n * holds all size state.\n *\n * ### Virtual and DOM coordinates\n *\n * Browsers limit how far an element can scroll. When the total item size is\n * larger than that limit, the engine compresses the *virtual* space\n * (`0…totalSize`) into the *DOM* space the browser can represent\n * (`0…domSize`) by the factor `_virtualRatio`. Each offset that crosses that\n * boundary is scaled: incoming scroll positions are multiplied by the ratio,\n * and outgoing offsets are divided by it. Items render at their real pixel\n * size, so item sizes are always virtual.\n */\nexport class VirtualScrollEngine {\n  private _maxBrowserSize = Number.POSITIVE_INFINITY;\n\n  /**\n   * The ratio `totalSize / maxBrowserSize` when `totalSize` is larger than\n   * the maximum DOM coordinate the browser supports; `1` otherwise.\n   * Maps virtual scroll positions to DOM scroll positions.\n   */\n  private _virtualRatio = 1;\n\n  /** Binary Indexed Tree for O(log N) size queries and updates. */\n  private _tree: SizeTree | null = null;\n\n  /**\n   * Called when item sizes or the item count change.\n   * Example: `() => this.requestUpdate()`.\n   */\n  public onSizeChange: (() => void) | null = null;\n\n  /** Total virtual size of all items in px. */\n  public get totalSize(): number {\n    return this._tree?.totalSize ?? 0;\n  }\n\n  /** Total size in DOM space, clamped to the maximum browser size. */\n  public get domSize(): number {\n    return this._virtualRatio !== 1 ? this._maxBrowserSize : this.totalSize;\n  }\n\n  /** Measures the maximum browser size for the document and rescales. */\n  public initMaxBrowserSize(doc: Document): void {\n    this._maxBrowserSize = getMaxBrowserSizeProbePx(doc);\n    this._updateVirtualRatio();\n  }\n\n  /**\n   * Resizes the internal sizes array to `length`. Measured sizes below\n   * `retainCount` are kept. The remainder is filled with `estimatedSize` and\n   * marked unmeasured. Callers that only append can keep the default\n   * `retainCount`. Callers whose data changed identity at some index must\n   * pass that index, so the stale measurements after it are discarded.\n   */\n  public resize(\n    length: number,\n    estimatedSize: number,\n    retainCount = length\n  ): void {\n    if (this._tree?.length === length && retainCount >= length) return;\n\n    this._tree = this._tree\n      ? this._tree.cloneResized(length, estimatedSize, retainCount)\n      : SizeTree.filled(length, estimatedSize);\n    this._updateVirtualRatio();\n    this.onSizeChange?.();\n  }\n\n  /** Records the measured DOM size for a single item. */\n  public measureItem(index: number, size: number): void {\n    if (!this._tree?.update(index, size)) return;\n\n    this._updateVirtualRatio();\n    this.onSizeChange?.();\n  }\n\n  /**\n   * Applies a new estimated size to each item that is not measured in the\n   * DOM. Use this when `estimatedItemSize` changes but the item count does\n   * not, because `resize` is then a no-op.\n   */\n  public updateEstimatedSize(estimatedSize: number): void {\n    if (!this._tree?.applyEstimate(estimatedSize)) return;\n\n    this._updateVirtualRatio();\n    this.onSizeChange?.();\n  }\n\n  /**\n   * Returns the DOM scroll offset in px that puts the item at `index` at the\n   * leading edge of the viewport.\n   */\n  public getScrollOffsetForIndex(index: number): number {\n    if (!this._tree || index <= 0) return 0;\n\n    const clamped = Math.min(index, this._tree.length);\n    return this._tree.prefixSum(clamped) / this._virtualRatio;\n  }\n\n  /**\n   * The largest DOM scroll offset the host can reach for the given viewport\n   * size. A request beyond it does nothing, so offsets given to a caller\n   * that waits for the scroll to settle are clamped to it.\n   */\n  private _getMaxScrollOffset(viewportSize: number): number {\n    return Math.max(0, this.domSize - viewportSize);\n  }\n\n  /**\n   * Returns the DOM scroll offset that positions the item at `index` in a\n   * `viewportSize` px viewport, aligned by `align` and clamped to the\n   * reachable scroll range.\n   *\n   * The slack is computed in virtual space against the item's real size and\n   * converted to DOM space once, at the end. One DOM pixel equals\n   * `_virtualRatio` virtual pixels, so mixed coordinates would scale the\n   * slack.\n   */\n  public getAlignedScrollOffset(\n    index: number,\n    viewportSize: number,\n    align: ScrollAlignment\n  ): number {\n    if (!this._tree || this._tree.length === 0) return 0;\n\n    const clamped = clampIndex(index, this._tree.length);\n    const itemStart = this._tree.prefixSum(clamped);\n    let offset = itemStart;\n\n    if (align !== 'start') {\n      const itemEnd = this._tree.prefixSum(clamped + 1);\n      const slack = viewportSize - Math.max(0, itemEnd - itemStart);\n      offset -= align === 'center' ? slack / 2 : slack;\n    }\n\n    return clamp(\n      offset / this._virtualRatio,\n      0,\n      this._getMaxScrollOffset(viewportSize)\n    );\n  }\n\n  /**\n   * Whether the item at `index` is visible without more scrolling at the\n   * given DOM scroll position. True when the item is fully inside the\n   * viewport, or when it is larger than the viewport and covers it fully.\n   * The second case matches native `scrollIntoView({ block: 'nearest' })`.\n   */\n  public isIndexInView(\n    index: number,\n    scrollPosition: number,\n    viewportSize: number\n  ): boolean {\n    if (!this._tree || this._tree.length === 0) return false;\n\n    const clamped = clampIndex(index, this._tree.length);\n    const itemStart = this._tree.prefixSum(clamped);\n    const itemEnd = this._tree.prefixSum(clamped + 1);\n    const viewStart = Math.max(0, scrollPosition) * this._virtualRatio;\n    const viewEnd = viewStart + viewportSize;\n\n    const contained = itemStart >= viewStart && itemEnd <= viewEnd;\n    const spanning = itemStart <= viewStart && itemEnd >= viewEnd;\n\n    return contained || spanning;\n  }\n\n  /**\n   * Returns the visible and over-scanned item range for the given scroll\n   * state.\n   */\n  public getVisibleRange(\n    scrollPosition: number,\n    viewportSize: number,\n    overScan: number\n  ): VisibleRange {\n    if (!this._tree || this._tree.length === 0 || viewportSize <= 0) {\n      return { startIndex: 0, endIndex: -1 };\n    }\n\n    // The viewport is not scaled by the virtual ratio. Items render at their\n    // real pixel size, so a `viewportSize` px viewport always shows that many\n    // virtual pixels of items, at any compression of the scroll range.\n    const startOffset = Math.max(0, scrollPosition) * this._virtualRatio;\n    const first = this._tree.findIndexAtOffset(startOffset);\n    const last = this._tree.findIndexAtOffset(startOffset + viewportSize);\n\n    return {\n      startIndex: Math.max(0, first - overScan),\n      endIndex: Math.min(this._tree.length - 1, last + overScan),\n    };\n  }\n\n  /**\n   * Sum of the actual sizes of the items in [startIndex, endIndex]. The\n   * render pass uses it to clamp the content translate offset, so rendered\n   * items do not overflow past `domSize` under coordinate compression.\n   */\n  public getPhysicalRangeSize(startIndex: number, endIndex: number): number {\n    if (!this._tree) return 0;\n\n    const start = Math.max(0, startIndex);\n    const end = Math.min(Math.max(endIndex + 1, start), this._tree.length);\n    return this._tree.prefixSum(end) - this._tree.prefixSum(start);\n  }\n\n  private _updateVirtualRatio(): void {\n    const totalSize = this._tree?.totalSize ?? 0;\n    this._virtualRatio =\n      totalSize <= this._maxBrowserSize ? 1 : totalSize / this._maxBrowserSize;\n  }\n}\n"]}

package/components/virtualization/types.d.ts

@@ -1,5 +1,5 @@
 /**
- * Context passed to the item template: the item data, its index and utility
+ * Context passed to the item template: the item data, its index, and utility
  * properties for rendering.
  */
 export declare class VirtualScrollItemContext<T> {
@@ -16,8 +16,8 @@ export declare class VirtualScrollItemContext<T> {
     get isLast(): boolean;
 }
 /**
- * How `scrollToIndex` positions the requested item within the viewport.
- * Mirrors the subset of `ScrollLogicalPosition` the engine can act on.
+ * How `scrollToIndex` positions the requested item in the viewport.
+ * The subset of `ScrollLogicalPosition` that the engine supports.
  */
 export type ScrollAlignment = 'start' | 'center' | 'end';
 /** The currently visible (and over-scanned) range of items. */
@@ -39,8 +39,9 @@ export interface VirtualScrollState {
     totalSize: number;
 }
 /**
- * A request for more data, emitted when the rendered window comes near the end
- * of the loaded items. Consumers listen for it and append what it asks for.
+ * A request for more data, emitted when the rendered window comes near the
+ * end of the loaded items. Consumers listen for it and append the requested
+ * items.
  */
 export interface VirtualScrollDataRequest {
     /**

package/components/virtualization/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/components/virtualization/types.ts"],"names":[],"mappings":"AAIA,MAAM,OAAO,wBAAwB;IAQnC,YAAY,KAAQ,EAAE,KAAa,EAAE,KAAa;QAChD,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;QACnB,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;QACnB,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;IACrB,CAAC;IAGD,IAAW,OAAO;QAChB,OAAO,IAAI,CAAC,KAAK,KAAK,CAAC,CAAC;IAC1B,CAAC;IAGD,IAAW,MAAM;QACf,OAAO,IAAI,CAAC,KAAK,KAAK,IAAI,CAAC,KAAK,GAAG,CAAC,CAAC;IACvC,CAAC;CACF","sourcesContent":["/**\n * Context passed to the item template: the item data, its index and utility\n * properties for rendering.\n */\nexport class VirtualScrollItemContext<T> {\n  /** The current item in the virtual scroll */\n  public readonly value: T;\n  /** The index of the current item */\n  public readonly index: number;\n  /** The total number of items */\n  public readonly count: number;\n\n  constructor(value: T, index: number, count: number) {\n    this.value = value;\n    this.index = index;\n    this.count = count;\n  }\n\n  /** Whether the current item is the first item */\n  public get isFirst(): boolean {\n    return this.index === 0;\n  }\n\n  /** Whether the current item is the last item */\n  public get isLast(): boolean {\n    return this.index === this.count - 1;\n  }\n}\n\n/**\n * How `scrollToIndex` positions the requested item within the viewport.\n * Mirrors the subset of `ScrollLogicalPosition` the engine can act on.\n */\nexport type ScrollAlignment = 'start' | 'center' | 'end';\n\n/** The currently visible (and over-scanned) range of items. */\nexport interface VisibleRange {\n  /** Index of the first rendered item (inclusive) */\n  startIndex: number;\n  /** Index of the last rendered item (inclusive) */\n  endIndex: number;\n}\n\n/** Snapshot of the currently rendered virtual window */\nexport interface VirtualScrollState {\n  /** The index of the first item currently rendered in the viewport. */\n  startIndex: number;\n  /** The index of the last item currently rendered in the viewport (inclusive). */\n  endIndex: number;\n  /** The size of the viewport in pixels. */\n  viewportSize: number;\n  /** The total size of the virtual scroll content in pixels. */\n  totalSize: number;\n}\n\n/**\n * A request for more data, emitted when the rendered window comes near the end\n * of the loaded items. Consumers listen for it and append what it asks for.\n */\nexport interface VirtualScrollDataRequest {\n  /**\n   * The first index that does not yet have data.\n   * Append at least `count` more items starting here.\n   */\n  startIndex: number;\n  /** Number of items being requested. */\n  count: number;\n}\n"]}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/components/virtualization/types.ts"],"names":[],"mappings":"AAIA,MAAM,OAAO,wBAAwB;IAQnC,YAAY,KAAQ,EAAE,KAAa,EAAE,KAAa;QAChD,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;QACnB,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;QACnB,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;IACrB,CAAC;IAGD,IAAW,OAAO;QAChB,OAAO,IAAI,CAAC,KAAK,KAAK,CAAC,CAAC;IAC1B,CAAC;IAGD,IAAW,MAAM;QACf,OAAO,IAAI,CAAC,KAAK,KAAK,IAAI,CAAC,KAAK,GAAG,CAAC,CAAC;IACvC,CAAC;CACF","sourcesContent":["/**\n * Context passed to the item template: the item data, its index, and utility\n * properties for rendering.\n */\nexport class VirtualScrollItemContext<T> {\n  /** The current item in the virtual scroll */\n  public readonly value: T;\n  /** The index of the current item */\n  public readonly index: number;\n  /** The total number of items */\n  public readonly count: number;\n\n  constructor(value: T, index: number, count: number) {\n    this.value = value;\n    this.index = index;\n    this.count = count;\n  }\n\n  /** Whether the current item is the first item */\n  public get isFirst(): boolean {\n    return this.index === 0;\n  }\n\n  /** Whether the current item is the last item */\n  public get isLast(): boolean {\n    return this.index === this.count - 1;\n  }\n}\n\n/**\n * How `scrollToIndex` positions the requested item in the viewport.\n * The subset of `ScrollLogicalPosition` that the engine supports.\n */\nexport type ScrollAlignment = 'start' | 'center' | 'end';\n\n/** The currently visible (and over-scanned) range of items. */\nexport interface VisibleRange {\n  /** Index of the first rendered item (inclusive) */\n  startIndex: number;\n  /** Index of the last rendered item (inclusive) */\n  endIndex: number;\n}\n\n/** Snapshot of the currently rendered virtual window */\nexport interface VirtualScrollState {\n  /** The index of the first item currently rendered in the viewport. */\n  startIndex: number;\n  /** The index of the last item currently rendered in the viewport (inclusive). */\n  endIndex: number;\n  /** The size of the viewport in pixels. */\n  viewportSize: number;\n  /** The total size of the virtual scroll content in pixels. */\n  totalSize: number;\n}\n\n/**\n * A request for more data, emitted when the rendered window comes near the\n * end of the loaded items. Consumers listen for it and append the requested\n * items.\n */\nexport interface VirtualScrollDataRequest {\n  /**\n   * The first index that does not yet have data.\n   * Append at least `count` more items starting here.\n   */\n  startIndex: number;\n  /** Number of items being requested. */\n  count: number;\n}\n"]}

package/components/virtualization/virtualization.d.ts

@@ -9,18 +9,18 @@ export interface IgcVirtualScrollComponentEventMap {
 }
 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.
+ * 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 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.
+ * @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 holding the currently rendered items, translated
- * into position within the track.
+ * @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";
@@ -31,32 +31,39 @@ export default class IgcVirtualScrollComponent<T = any> extends IgcVirtualScroll
     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 it was emitted at. See `_checkDataRequest`.
+     * item count at that emit. 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.
+     * 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. Deliberately *not* reactive:
-     * nothing in `render` reads it except through `_currentRange`, so
-     * `_handleScroll` schedules an update only when the window actually moves.
+     * 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: mutating the array
-     * in place (`data.push(...)`) produces no update. Assign a new array
-     * instead, which is also what the `igcDataRequest` flow expects.
+     * 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[];
     /**
@@ -67,14 +74,14 @@ export default class IgcVirtualScrollComponent<T = any> extends IgcVirtualScroll
     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.
+     * 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.
-     * The engine replaces this with the actual measured size after the first render of each item.
+     * 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
      */
@@ -82,14 +89,14 @@ export default class IgcVirtualScrollComponent<T = any> extends IgcVirtualScroll
     /**
      * 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.
+     * 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 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
+     * 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;
@@ -109,21 +116,20 @@ export default class IgcVirtualScrollComponent<T = any> extends IgcVirtualScroll
     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. */
+    /** `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, since nothing renders without one.
+     * until an `itemTemplate` is set, because 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.
+     * 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 that no scrolling takes place.
+     * offset, so no scroll occurs.
      */
     private _getAlignedScrollOffset;
     /** Applies a scroll offset to the correct axis, accounting for RTL. */
@@ -131,99 +137,107 @@ export default class IgcVirtualScrollComponent<T = any> extends IgcVirtualScroll
     /** 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.
+     * Applies a scroll offset to the active axis and waits for the 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.
+     * `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 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.
+     * 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 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.
+     * 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 and schedules a render only if it moves the
-     * rendered window.
+     * 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`, 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.
+     * `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, 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
+     * 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;
     /**
-     * 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.
+     * 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`, unless the window is empty or identical to the one
-     * last reported: measurement passes re-render without moving the window.
+     * 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`
-     * 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.
+     * 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 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.
+     * 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 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.
+     * 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.
      *
-     * 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.
+     * `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>;
     /**
-     * Programmatically scrolls to the specified item index.
+     * 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.
+     * 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 once the scroll has settled on that final,
-     * corrected offset, and can be ignored by callers that only care about the
-     * initial, approximate scroll.
+     * 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>;
 }