feat(virtual-scroll): add initial viewport hint

A list inside a popup is hidden until the change detection pass that
reveals it, so it has no size to measure and renders nothing in that
pass. initialViewportSize gives that first render a size to work from;
the measured size takes over as soon as the host can be measured.

Author: viktorkombov

projects/igniteui-angular/virtual-scroll/README.md

@@ -43,6 +43,36 @@ 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]`. |
+| `initialViewportSize` | `number` | `0` | Viewport size in pixels to render the **first** window against, for a list that cannot be measured when it is first rendered. A hint for that render only: once the host measures above zero, the measured size takes over and this input is not read again. Negative, `NaN` and infinite values count as no hint. See [Lists inside a popup](#lists-inside-a-popup). |
+
+
+### 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. In a Karma
+reproduction of a list revealed by a single synchronous pass, it stayed empty for two
+`requestAnimationFrame` iterations before filling in.
+
+A wrapper that reacts to whether the list has children can flip state between those passes,
+which Angular reports as `NG0100` in development mode.
+
+Pass the size the container gives the list and the first window renders with it:
+
+```html
+<igx-virtual-scroll [data]="items" [initialViewportSize]="320" style="height: 320px">
+  <ng-template igxVirtualItem let-item>{{ item }}</ng-template>
+</igx-virtual-scroll>
+```
+
+The value is a starting point, not an override. Once the host has been measured the measured
+size is the only one used, and later resizes are followed normally.
+
+A measurement of zero is not recorded, because a hidden host measures zero and that says
+nothing about how large it will be when it is shown again. Keeping the last real measurement
+is what lets the list render its window in the pass that reopens it. The deliberate
+consequence is that the rendered window stays in the DOM while the host is hidden.
 
 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.
 

projects/igniteui-angular/virtual-scroll/src/virtual-scroll/virtual-scroll.component.spec.ts

@@ -522,6 +522,33 @@ class TestHostComponent {
     }
 }
 
+@Component({
+    selector: 'test-virtual-scroll-popup',
+    template: `
+        <div [style.display]="open() ? 'block' : 'none'">
+            <igx-virtual-scroll
+                [data]="items()"
+                [initialViewportSize]="initialViewportSize()"
+                [style.height.px]="hostHeight()"
+                style="display: block"
+            >
+                <ng-template igxVirtualItem let-item let-i="index">
+                    <span class="item" style="display: block; height: 50px">{{ i }}: {{ item }}</span>
+                </ng-template>
+            </igx-virtual-scroll>
+        </div>
+    `,
+    imports: [IgxVirtualScrollComponent, IgxVirtualItemDirective],
+})
+class TestPopupHostComponent {
+    public readonly vs = viewChild.required(IgxVirtualScrollComponent);
+
+    public items = signal(generateItems(100));
+    public initialViewportSize = signal(0);
+    public hostHeight = signal<number | null>(300);
+    public open = signal(false);
+}
+
 @Component({
     selector: 'test-virtual-scroll-rtl',
     template: `
@@ -644,6 +671,7 @@ describe('IgxVirtualScrollComponent', () => {
                 TestRtlHostComponent,
                 TestNoTemplateHostComponent,
                 TestProgrammaticTemplateComponent,
+                TestPopupHostComponent,
             ],
         }).compileComponents();
     }));
@@ -762,6 +790,114 @@ describe('IgxVirtualScrollComponent', () => {
         });
     });
 
+    describe('initial viewport size', () => {
+        let popup: ComponentFixture<TestPopupHostComponent>;
+        let popupHost: TestPopupHostComponent;
+        let popupScroll: IgxVirtualScrollComponent<string>;
+
+        /** Creates the fixture with the list hidden, the way a closed drop-down holds one. */
+        async function createPopup(initialViewportSize = 0): Promise<void> {
+            popup = TestBed.createComponent(TestPopupHostComponent);
+            popupHost = popup.componentInstance;
+            popupHost.initialViewportSize.set(initialViewportSize);
+            popup.detectChanges();
+            popupScroll = popupHost.vs() as IgxVirtualScrollComponent<string>;
+        }
+
+        /** Shows the list in one synchronous pass, the way opening a drop-down does. */
+        function reveal(): void {
+            popupHost.open.set(true);
+            popup.detectChanges();
+        }
+
+        /** Settles repeatedly until `predicate` holds, so a resize report is not raced. */
+        async function settleUntil(predicate: () => boolean): Promise<void> {
+            for (let i = 0; i < 20 && !predicate(); i++) {
+                await settle(popup, popupScroll);
+            }
+        }
+
+        it('should render nothing in the pass that reveals it when the input is omitted', async () => {
+            await createPopup();
+            reveal();
+
+            expect(vsItems(popup).length).toBe(0);
+        });
+
+        it('should render the first window in the pass that reveals it', async () => {
+            await createPopup(300);
+            reveal();
+
+            // A 300px viewport of 50px rows shows 0..6, plus an over-scan of 2.
+            expect(vsIndices(popup)).toEqual([0, 1, 2, 3, 4, 5, 6, 7, 8]);
+        });
+
+        it('should let the measured size replace an initial value that was too large', async () => {
+            await createPopup(2000);
+            reveal();
+            await settleUntil(() => vsItems(popup).length === 9);
+
+            // The host is 300px, so the window settles at what it really holds rather than
+            // the 40 rows 2000px would.
+            expect(vsIndices(popup)).toEqual([0, 1, 2, 3, 4, 5, 6, 7, 8]);
+        });
+
+        it('should follow a later resize of the host', async () => {
+            await createPopup(300);
+            reveal();
+            expect(vsIndices(popup)).toEqual([0, 1, 2, 3, 4, 5, 6, 7, 8]);
+
+            popupHost.hostHeight.set(600);
+            await settleUntil(() => vsItems(popup).length > 9);
+
+            // 600px of 50px rows shows 0..12, plus an over-scan of 2.
+            expect(Math.max(...vsIndices(popup))).toBe(14);
+        });
+
+        it('should keep the last measured size when the host is hidden', async () => {
+            // The hint and the host disagree, so the window says which one is in use: the
+            // 300px hint gives 9 rows, the 600px host gives 15.
+            await createPopup(300);
+            popupHost.hostHeight.set(600);
+            reveal();
+            await settleUntil(() => vsItems(popup).length === 15);
+            expect(vsItems(popup).length).toBe(15);
+
+            // A value that would be unmistakable if the input were read again.
+            popupHost.initialViewportSize.set(2000);
+            popupHost.open.set(false);
+            await settle(popup, popupScroll);
+
+            expect(vsItems(popup).length).toBe(15);
+        });
+
+        it('should not start empty when the host is shown again', async () => {
+            await createPopup(300);
+            popupHost.hostHeight.set(600);
+            reveal();
+            await settleUntil(() => vsItems(popup).length === 15);
+
+            popupHost.open.set(false);
+            await settle(popup, popupScroll);
+            reveal();
+
+            expect(vsItems(popup).length).toBe(15);
+        });
+
+        for (const [label, value] of [
+            ['negative', -300],
+            ['NaN', Number.NaN],
+            ['infinite', Number.POSITIVE_INFINITY],
+        ] as [string, number][]) {
+            it(`should treat a ${label} initial size as no hint at all`, async () => {
+                await createPopup(value);
+                reveal();
+
+                expect(vsItems(popup).length).toBe(0);
+            });
+        }
+    });
+
     describe('orientation', () => {
         beforeEach(async () => {
             await createFixture();

projects/igniteui-angular/virtual-scroll/src/virtual-scroll/virtual-scroll.component.ts

@@ -152,6 +152,7 @@ export class IgxVirtualScrollComponent<T> implements OnDestroy {
   /** Bumped only when a scroll actually moves the rendered window. */
   private readonly _scrollTick = signal(0);
 
+  /** The last size the host measured above zero. See `_measureViewport`. */
   private readonly _viewportSize = signal(0);
 
   /** The `data` array as of the previous change, for `_firstChangedIndex`. */
@@ -213,6 +214,22 @@ export class IgxVirtualScrollComponent<T> implements OnDestroy {
    */
   public readonly estimatedItemSize = input<number>(DEFAULT_ESTIMATED_ITEM_SIZE);
 
+  /**
+   * Viewport size in pixels to render the first window against, for a list that is hidden
+   * until the change detection pass that reveals it and so has no size to measure in it.
+   *
+   * A hint for that first render only: once the host measures above zero the measured size
+   * takes over. Negative, `NaN` and infinite values count as no hint.
+   *
+   * @example
+   * ```html
+   * <igx-virtual-scroll [data]="items" [initialViewportSize]="320" style="height: 320px">
+   *   <ng-template igxVirtualItem let-item>{{ item }}</ng-template>
+   * </igx-virtual-scroll>
+   * ```
+   */
+  public readonly initialViewportSize = input<number>(0);
+
   /**
    * Item template provided programmatically. Takes precedence over a content
    * `ng-template[igxVirtualItem]` when both are provided.
@@ -259,6 +276,18 @@ export class IgxVirtualScrollComponent<T> implements OnDestroy {
   /** `data`, guarded against a nullish value set by the consumer. */
   private readonly _items = computed<T[]>(() => this.data() ?? []);
 
+  /** `initialViewportSize`, normalized to a non-negative number. */
+  private readonly _normalizedInitialViewportSize = computed(() => {
+    const value = Number(this.initialViewportSize());
+    return Number.isFinite(value) ? Math.max(0, value) : 0;
+  });
+
+  /** The measured size once the host has been measurable, the hint until then. */
+  private readonly _effectiveViewportSize = computed(() => {
+    const measured = this._viewportSize();
+    return measured > 0 ? measured : this._normalizedInitialViewportSize();
+  });
+
   /** The configured `overScan`, normalized to a non-negative integer. */
   private readonly _normalizedOverScan = computed(() => {
     const value = Number(this.overScan());
@@ -293,7 +322,7 @@ export class IgxVirtualScrollComponent<T> implements OnDestroy {
       return this._resolvedTemplate()
         ? this._engine.getVisibleRange(
             this._scrollPosition,
-            this._viewportSize(),
+            this._effectiveViewportSize(),
             this._normalizedOverScan(),
           )
         : EMPTY_RANGE;
@@ -383,6 +412,8 @@ export class IgxVirtualScrollComponent<T> implements OnDestroy {
           return;
         }
 
+        // The size of the previous axis says nothing about the new one.
+        this._viewportSize.set(0);
         this._measureViewport();
         this._scrollPosition = this._currentAxisScroll();
         this._scrollTick.update((v) => v + 1);
@@ -528,7 +559,7 @@ export class IgxVirtualScrollComponent<T> implements OnDestroy {
 
     if (
       requested === "nearest" &&
-      this._engine.isIndexInView(index, current, this._viewportSize())
+      this._engine.isIndexInView(index, current, this._effectiveViewportSize())
     ) {
       return current;
     }
@@ -538,7 +569,7 @@ export class IgxVirtualScrollComponent<T> implements OnDestroy {
 
     return this._engine.getAlignedScrollOffset(
       index,
-      this._viewportSize(),
+      this._effectiveViewportSize(),
       align,
     );
   }
@@ -694,7 +725,10 @@ export class IgxVirtualScrollComponent<T> implements OnDestroy {
     const host = this._hostRef.nativeElement;
     const size = this._isVertical() ? host.clientHeight : host.clientWidth;
 
-    if (size !== untracked(this._viewportSize)) {
+    // A hidden host measures zero, which says nothing about its size once shown. Keeping
+    // the last real measurement lets it render again in the pass that reveals it, at the
+    // cost of leaving the window rendered while it is hidden.
+    if (size > 0 && size !== untracked(this._viewportSize)) {
       this._viewportSize.set(size);
     }
   }
@@ -733,7 +767,7 @@ export class IgxVirtualScrollComponent<T> implements OnDestroy {
 
     const next = this._engine.getVisibleRange(
       this._scrollPosition,
-      untracked(this._viewportSize),
+      untracked(this._effectiveViewportSize),
       untracked(this._normalizedOverScan),
     );
 
@@ -847,7 +881,7 @@ export class IgxVirtualScrollComponent<T> implements OnDestroy {
     const state: VirtualScrollState = {
       startIndex,
       endIndex,
-      viewportSize: untracked(this._viewportSize),
+      viewportSize: untracked(this._effectiveViewportSize),
       totalSize: untracked(this._engine.totalSize),
     };