Virtualization supports variable-height items

src/Components/Web.JS/test/Virtualize.test.ts

@@ -0,0 +1,91 @@
+import { expect, test, describe, beforeEach, afterEach } from '@jest/globals';
+import { Virtualize } from '../src/Virtualize';
+
+const { measureRenderedItems } = Virtualize;
+
+function createDOM(heights: number[]): { before: HTMLDivElement; after: HTMLDivElement } {
+  const container = document.createElement('div');
+  document.body.appendChild(container);
+  const before = document.createElement('div');
+  const after = document.createElement('div');
+  container.appendChild(before);
+
+  // Build N+1 fence: comment, item, comment, item, ..., comment
+  for (const h of heights) {
+    const comment = document.createComment('virtualize:item');
+    container.appendChild(comment);
+    const item = document.createElement('div');
+    item.getBoundingClientRect = () => ({
+      height: h, width: 100, top: 0, left: 0, bottom: h, right: 100,
+      x: 0, y: 0, toJSON() { return this; },
+    });
+    container.appendChild(item);
+  }
+  if (heights.length > 0) {
+    container.appendChild(document.createComment('virtualize:item'));
+  }
+
+  container.appendChild(after);
+
+  // jsdom doesn't implement Range.getBoundingClientRect.
+  // Patch createRange to return a mock that sums item heights between start and end.
+  const origCreateRange = document.createRange.bind(document);
+  document.createRange = () => {
+    const range = origCreateRange();
+    let startNode: Node | null = null;
+    const origSetStartAfter = range.setStartAfter.bind(range);
+    const origSetEndBefore = range.setEndBefore.bind(range);
+    range.setStartAfter = (node: Node) => { startNode = node; origSetStartAfter(node); };
+    range.setEndBefore = (node: Node) => {
+      origSetEndBefore(node);
+      // Sum heights of element children between startNode and node
+      let totalHeight = 0;
+      if (startNode) {
+        for (let n = startNode.nextSibling; n && n !== node; n = n.nextSibling) {
+          if (n instanceof HTMLElement && n.getBoundingClientRect) {
+            totalHeight += n.getBoundingClientRect().height;
+          }
+        }
+      }
+      range.getBoundingClientRect = () => ({
+        height: totalHeight, width: 100, top: 0, left: 0, bottom: totalHeight, right: 100,
+        x: 0, y: 0, toJSON() { return this; },
+      } as DOMRect);
+    };
+    return range;
+  };
+
+  return { before, after };
+}
+
+describe('measureRenderedItems', () => {
+  test('returns aggregated sum and count for valid items', () => {
+    const { before, after } = createDOM([40, 60]);
+    const result = measureRenderedItems(before, after);
+    expect(result.heightSum).toBe(100);
+    expect(result.heightCount).toBe(2);
+  });
+
+  test('includes zero-height items in count', () => {
+    const { before, after } = createDOM([50, 0, 30]);
+    const result = measureRenderedItems(before, after);
+    // Total height is 80 (50+0+30), all 3 items counted
+    expect(result.heightSum).toBe(80);
+    expect(result.heightCount).toBe(3);
+  });
+
+  test('returns zero for empty item list', () => {
+    const { before, after } = createDOM([]);
+    const result = measureRenderedItems(before, after);
+    expect(result.heightSum).toBe(0);
+    expect(result.heightCount).toBe(0);
+  });
+
+  test('returns zero for single item (needs at least 2 delimiters)', () => {
+    // Single item has 2 delimiters which is the minimum
+    const { before, after } = createDOM([42]);
+    const result = measureRenderedItems(before, after);
+    expect(result.heightSum).toBe(42);
+    expect(result.heightCount).toBe(1);
+  });
+});

src/Components/Web/src/Virtualization/IVirtualizeJsCallbacks.cs

@@ -5,6 +5,6 @@ namespace Microsoft.AspNetCore.Components.Web.Virtualization;
 
 internal interface IVirtualizeJsCallbacks
 {
-    void OnBeforeSpacerVisible(float spacerSize, float spacerSeparation, float containerSize);
-    void OnAfterSpacerVisible(float spacerSize, float spacerSeparation, float containerSize);
+    void OnBeforeSpacerVisible(float spacerSize, float spacerSeparation, float containerSize, float measuredItemHeightSum, int measuredItemCount);
+    void OnAfterSpacerVisible(float spacerSize, float spacerSeparation, float containerSize, float measuredItemHeightSum, int measuredItemCount);
 }

src/Components/Web/src/Virtualization/Virtualize.cs

@@ -43,10 +43,14 @@ public sealed class Virtualize<TItem> : ComponentBase, IVirtualizeJsCallbacks, I
 
     private float _itemSize;
 
+    private float _lastSetItemSize;
+
     private IEnumerable<TItem>? _loadedItems;
 
     private CancellationTokenSource? _refreshCts;
 
+    private bool _skipNextDistributionRefresh;
+
     private Exception? _refreshException;
 
     private ItemsProviderDelegate<TItem> _itemsProvider = default!;
@@ -59,11 +63,17 @@ public sealed class Virtualize<TItem> : ComponentBase, IVirtualizeJsCallbacks, I
 
     private bool _loading;
 
+    internal float _totalMeasuredHeight;
+
+    internal int _measuredItemCount;
+
+    internal bool _pendingScrollToBottom;
+
     [Inject]
     private IJSRuntime JSRuntime { get; set; } = default!;
 
     /// <summary>
-    /// Gets or sets the item template for the list.
+    /// Gets or sets the item template for the list. See <see cref="ItemContent"/>.
     /// </summary>
     [Parameter]
     public RenderFragment<TItem>? ChildContent { get; set; }
@@ -112,7 +122,7 @@ public sealed class Virtualize<TItem> : ComponentBase, IVirtualizeJsCallbacks, I
     /// in the page.
     /// </summary>
     [Parameter]
-    public int OverscanCount { get; set; } = 3;
+    public int OverscanCount { get; set; } = 15;
 
     /// <summary>
     /// Gets or sets the tag name of the HTML element that will be used as the virtualization spacer.
@@ -148,6 +158,8 @@ public async Task RefreshDataAsync()
         // We don't auto-render after this operation because in the typical use case, the
         // host component calls this from one of its lifecycle methods, and will naturally
         // re-render afterwards anyway. It's not desirable to re-render twice.
+        _totalMeasuredHeight = 0;
+        _measuredItemCount = 0;
         await RefreshDataCoreAsync(renderOnSuccess: false);
     }
 
@@ -165,6 +177,15 @@ protected override void OnParametersSet()
             _itemSize = ItemSize;
         }
 
+        // Without this reset, visibleItemCapacity is under/over-estimated after a size change,
+        // causing extra provider calls that may never complete (e.g., async providers).
+        if (_lastSetItemSize != ItemSize)
+        {
+            _lastSetItemSize = ItemSize;
+            _totalMeasuredHeight = 0;
+            _measuredItemCount = 0;
+        }
+
         if (ItemsProvider != null)
         {
             if (Items != null)
@@ -208,6 +229,18 @@ protected override async Task OnAfterRenderAsync(bool firstRender)
             _jsInterop = new VirtualizeJsInterop(this, JSRuntime);
             await _jsInterop.InitializeAsync(_spacerBefore, _spacerAfter);
         }
+
+        if (_pendingScrollToBottom && _jsInterop is not null)
+        {
+            _pendingScrollToBottom = false;
+            await _jsInterop.ScrollToBottomAsync();
+        }
+
+        // After render the set of items could change. Tell JS to refresh ResizeObserver.
+        if (!firstRender && _jsInterop is not null)
+        {
+            await _jsInterop.RefreshObserversAsync();
+        }
     }
 
     /// <inheritdoc />
@@ -257,13 +290,19 @@ protected override void BuildRenderTree(RenderTreeBuilder builder)
 
             builder.OpenRegion(5);
 
-            // Render the loaded items.
+            // Render items with comment delimiters for JS height measurement (N+1 fence pattern).
             foreach (var item in itemsToShow)
             {
+                builder.AddMarkupContent(0, "<!--virtualize:item-->");
                 _itemTemplate(item)(builder);
                 _lastRenderedItemCount++;
             }
 
+            if (_lastRenderedItemCount > 0)
+            {
+                builder.AddMarkupContent(1, "<!--virtualize:item-->");
+            }
+
             renderIndex += _lastRenderedItemCount;
 
             builder.CloseRegion();
@@ -292,48 +331,71 @@ protected override void BuildRenderTree(RenderTreeBuilder builder)
     }
 
     private string GetSpacerStyle(int itemsInSpacer, int numItemsGapAbove)
-        => numItemsGapAbove == 0
-        ? GetSpacerStyle(itemsInSpacer)
-        : $"height: {(itemsInSpacer * _itemSize).ToString(CultureInfo.InvariantCulture)}px; flex-shrink: 0; transform: translateY({(numItemsGapAbove * _itemSize).ToString(CultureInfo.InvariantCulture)}px);";
+    {
+        var avgHeight = GetItemHeight();
+        return numItemsGapAbove == 0
+            ? GetSpacerStyle(itemsInSpacer)
+            : $"height: {(itemsInSpacer * avgHeight).ToString(CultureInfo.InvariantCulture)}px; flex-shrink: 0; transform: translateY({(numItemsGapAbove * avgHeight).ToString(CultureInfo.InvariantCulture)}px);";
+    }
 
     private string GetSpacerStyle(int itemsInSpacer)
-        => $"height: {(itemsInSpacer * _itemSize).ToString(CultureInfo.InvariantCulture)}px; flex-shrink: 0;";
+        => $"height: {(itemsInSpacer * GetItemHeight()).ToString(CultureInfo.InvariantCulture)}px; flex-shrink: 0;";
+
+    private float GetItemHeight()
+        => _measuredItemCount > 0 ? _totalMeasuredHeight / _measuredItemCount : _itemSize;
 
-    void IVirtualizeJsCallbacks.OnBeforeSpacerVisible(float spacerSize, float spacerSeparation, float containerSize)
+    private bool ProcessMeasurements(float measuredItemHeightSum, int measuredItemCount)
     {
-        CalcualteItemDistribution(spacerSize, spacerSeparation, containerSize, out var itemsBefore, out var visibleItemCapacity, out var unusedItemCapacity);
+        if (measuredItemCount <= 0)
+        {
+            return false;
+        }
+
+        _totalMeasuredHeight += measuredItemHeightSum;
+        _measuredItemCount += measuredItemCount;
+        return true;
+    }
+
+    void IVirtualizeJsCallbacks.OnBeforeSpacerVisible(float spacerSize, float spacerSeparation, float containerSize, float measuredItemHeightSum, int measuredItemCount)
+    {
+        ProcessMeasurements(measuredItemHeightSum, measuredItemCount);
 
-        // Since we know the before spacer is now visible, we absolutely have to slide the window up
-        // by at least one element. If we're not doing that, the previous item size info we had must
-        // have been wrong, so just move along by one in that case to trigger an update and apply the
-        // new size info.
-        if (itemsBefore == _itemsBefore && itemsBefore > 0)
+        CalculateItemDistribution(spacerSize, spacerSeparation, containerSize, out var itemsBefore, out var visibleItemCapacity, out var unusedItemCapacity);
+
+        // Slide window up by at least one if spacer is visible but position unchanged.
+        if (_lastRenderedItemCount > 0 && itemsBefore == _itemsBefore && itemsBefore > 0)
         {
             itemsBefore--;
         }
 
         UpdateItemDistribution(itemsBefore, visibleItemCapacity, unusedItemCapacity);
     }
 
-    void IVirtualizeJsCallbacks.OnAfterSpacerVisible(float spacerSize, float spacerSeparation, float containerSize)
+    void IVirtualizeJsCallbacks.OnAfterSpacerVisible(float spacerSize, float spacerSeparation, float containerSize, float measuredItemHeightSum, int measuredItemCount)
     {
-        CalcualteItemDistribution(spacerSize, spacerSeparation, containerSize, out var itemsAfter, out var visibleItemCapacity, out var unusedItemCapacity);
+        var hadNewMeasurements = ProcessMeasurements(measuredItemHeightSum, measuredItemCount);
+
+        CalculateItemDistribution(spacerSize, spacerSeparation, containerSize, out var itemsAfter, out var visibleItemCapacity, out var unusedItemCapacity);
 
         var itemsBefore = Math.Max(0, _itemCount - itemsAfter - visibleItemCapacity);
 
-        // Since we know the after spacer is now visible, we absolutely have to slide the window down
-        // by at least one element. If we're not doing that, the previous item size info we had must
-        // have been wrong, so just move along by one in that case to trigger an update and apply the
-        // new size info.
-        if (itemsBefore == _itemsBefore && itemsBefore < _itemCount - visibleItemCapacity)
+        // Slide window down by at least one if spacer is visible but position unchanged.
+        if (_lastRenderedItemCount > 0 && itemsBefore == _itemsBefore && itemsBefore < _itemCount - visibleItemCapacity)
         {
             itemsBefore++;
         }
 
+        // When we're at the very bottom and new measurements arrived,
+        // scroll to bottom so the viewport stays pinned while items converge.
+        if (itemsAfter == 0 && hadNewMeasurements)
+        {
+            _pendingScrollToBottom = true;
+        }
+
         UpdateItemDistribution(itemsBefore, visibleItemCapacity, unusedItemCapacity);
     }
 
-    private void CalcualteItemDistribution(
+    private void CalculateItemDistribution(
         float spacerSize,
         float spacerSeparation,
         float containerSize,
@@ -366,8 +428,15 @@ private void CalcualteItemDistribution(
         // the user has set a very low MaxItemCount and we end up in an infinite loading loop.
         maxItemCount += OverscanCount * 2;
 
-        itemsInSpacer = Math.Max(0, (int)Math.Floor(spacerSize / _itemSize) - OverscanCount);
-        visibleItemCapacity = (int)Math.Ceiling(containerSize / _itemSize) + 2 * OverscanCount;
+        // Use average measured height for calculations, falling back to _itemSize to avoid division by zero
+        var effectiveItemSize = GetItemHeight();
+        if (effectiveItemSize <= 0 || float.IsNaN(effectiveItemSize) || float.IsInfinity(effectiveItemSize))
+        {
+            effectiveItemSize = _itemSize;
+        }
+
+        itemsInSpacer = Math.Max(0, (int)Math.Floor(spacerSize / effectiveItemSize) - OverscanCount);
+        visibleItemCapacity = (int)Math.Ceiling(containerSize / effectiveItemSize) + 2 * OverscanCount;
         unusedItemCapacity = Math.Max(0, visibleItemCapacity - maxItemCount);
         visibleItemCapacity -= unusedItemCapacity;
     }
@@ -387,12 +456,30 @@ private void UpdateItemDistribution(int itemsBefore, int visibleItemCapacity, in
             _itemsBefore = itemsBefore;
             _visibleItemCapacity = visibleItemCapacity;
             _unusedItemCapacity = unusedItemCapacity;
-            var refreshTask = RefreshDataCoreAsync(renderOnSuccess: true);
 
-            if (!refreshTask.IsCompleted)
+            // After a successful data load, the ResizeObserver→IntersectionObserver cycle
+            // re-triggers with refined measurements. This one-shot flag skips the single
+            // redundant provider call that follows. At end-of-list, don't skip: refined
+            // capacity may reveal that more items are needed to fill the viewport.
+            var skipRefresh = _skipNextDistributionRefresh
+                && _loadedItems != null
+                && _loadedItemsStartIndex == _itemsBefore
+                && _itemsBefore + visibleItemCapacity < _itemCount;
+            _skipNextDistributionRefresh = false;
+
+            if (skipRefresh)
             {
                 StateHasChanged();
             }
+            else
+            {
+                var refreshTask = RefreshDataCoreAsync(renderOnSuccess: true);
+
+                if (!refreshTask.IsCompleted)
+                {
+                    StateHasChanged();
+                }
+            }
         }
     }
 
@@ -429,6 +516,7 @@ private async ValueTask RefreshDataCoreAsync(bool renderOnSuccess)
                 _loadedItems = result.Items;
                 _loadedItemsStartIndex = request.StartIndex;
                 _loading = false;
+                _skipNextDistributionRefresh = request.Count > 0;
 
                 if (renderOnSuccess)
                 {

src/Components/Web/src/Virtualization/VirtualizeJsInterop.cs

@@ -31,15 +31,25 @@ public async ValueTask InitializeAsync(ElementReference spacerBefore, ElementRef
     }
 
     [JSInvokable]
-    public void OnSpacerBeforeVisible(float spacerSize, float spacerSeparation, float containerSize)
+    public void OnSpacerBeforeVisible(float spacerSize, float spacerSeparation, float containerSize, float measuredItemHeightSum, int measuredItemCount)
     {
-        _owner.OnBeforeSpacerVisible(spacerSize, spacerSeparation, containerSize);
+        _owner.OnBeforeSpacerVisible(spacerSize, spacerSeparation, containerSize, measuredItemHeightSum, measuredItemCount);
     }
 
     [JSInvokable]
-    public void OnSpacerAfterVisible(float spacerSize, float spacerSeparation, float containerSize)
+    public void OnSpacerAfterVisible(float spacerSize, float spacerSeparation, float containerSize, float measuredItemHeightSum, int measuredItemCount)
     {
-        _owner.OnAfterSpacerVisible(spacerSize, spacerSeparation, containerSize);
+        _owner.OnAfterSpacerVisible(spacerSize, spacerSeparation, containerSize, measuredItemHeightSum, measuredItemCount);
+    }
+
+    public ValueTask ScrollToBottomAsync()
+    {
+        return _jsRuntime.InvokeVoidAsync($"{JsFunctionsPrefix}.scrollToBottom", _selfReference);
+    }
+
+    public ValueTask RefreshObserversAsync()
+    {
+        return _jsRuntime.InvokeVoidAsync($"{JsFunctionsPrefix}.refreshObservers", _selfReference);
     }
 
     public async ValueTask DisposeAsync()