Virtualization support (#24179)

Author: MackinnonBuck

src/Components/Web.JS/dist/Release/blazor.server.js

@@ -1,6 +1,7 @@
 import { navigateTo, internalFunctions as navigationManagerInternalFunctions } from './Services/NavigationManager';
 import { attachRootComponentToElement } from './Rendering/Renderer';
 import { domFunctions } from './DomWrapper';
+import { Virtualize } from './Virtualize';
 
 // Make the following APIs available in global scope for invocation from JS
 window['Blazor'] = {
@@ -10,5 +11,6 @@ window['Blazor'] = {
     attachRootComponentToElement,
     navigationManager: navigationManagerInternalFunctions,
     domWrapper: domFunctions,
+    Virtualize,
   },
 };

src/Components/Web.JS/dist/Release/blazor.webassembly.js

@@ -0,0 +1,86 @@
+export const Virtualize = {
+  init,
+  dispose,
+};
+
+const observersByDotNetId = {};
+
+function findClosestScrollContainer(element: Element | null): Element | null {
+  if (!element) {
+    return null;
+  }
+
+  const style = getComputedStyle(element);
+
+  if (style.overflowY !== 'visible') {
+    return element;
+  }
+
+  return findClosestScrollContainer(element.parentElement);
+}
+
+function init(dotNetHelper: any, spacerBefore: HTMLElement, spacerAfter: HTMLElement, rootMargin = 50): void {
+  const intersectionObserver = new IntersectionObserver(intersectionCallback, {
+    root: findClosestScrollContainer(spacerBefore),
+    rootMargin: `${rootMargin}px`,
+  });
+
+  intersectionObserver.observe(spacerBefore);
+  intersectionObserver.observe(spacerAfter);
+
+  const mutationObserverBefore = createSpacerMutationObserver(spacerBefore);
+  const mutationObserverAfter = createSpacerMutationObserver(spacerAfter);
+
+  observersByDotNetId[dotNetHelper._id] = {
+    intersectionObserver,
+    mutationObserverBefore,
+    mutationObserverAfter,
+  };
+
+  function createSpacerMutationObserver(spacer: HTMLElement): MutationObserver {
+    // Without the use of thresholds, IntersectionObserver only detects binary changes in visibility,
+    // so if a spacer gets resized but remains visible, no additional callbacks will occur. By unobserving
+    // and reobserving spacers when they get resized, the intersection callback will re-run if they remain visible.
+    const mutationObserver = new MutationObserver((): void => {
+      intersectionObserver.unobserve(spacer);
+      intersectionObserver.observe(spacer);
+    });
+
+    mutationObserver.observe(spacer, { attributes: true });
+
+    return mutationObserver;
+  }
+
+  function intersectionCallback(entries: IntersectionObserverEntry[]): void {
+    entries.forEach((entry): void => {
+      if (!entry.isIntersecting) {
+        return;
+      }
+
+      const containerSize = entry.rootBounds?.height;
+
+      if (entry.target === spacerBefore) {
+        dotNetHelper.invokeMethodAsync('OnSpacerBeforeVisible', entry.intersectionRect.top - entry.boundingClientRect.top, containerSize);
+      } else if (entry.target === spacerAfter && spacerAfter.offsetHeight > 0) {
+        // When we first start up, both the "before" and "after" spacers will be visible, but it's only relevant to raise a
+        // single event to load the initial data. To avoid raising two events, skip the one for the "after" spacer if we know
+        // it's meaningless to talk about any overlap into it.
+        dotNetHelper.invokeMethodAsync('OnSpacerAfterVisible', entry.boundingClientRect.bottom - entry.intersectionRect.bottom, containerSize);
+      }
+    });
+  }
+}
+
+function dispose(dotNetHelper: any): void {
+  const observers = observersByDotNetId[dotNetHelper._id];
+
+  if (observers) {
+    observers.intersectionObserver.disconnect();
+    observers.mutationObserverBefore.disconnect();
+    observers.mutationObserverAfter.disconnect();
+
+    dotNetHelper.dispose();
+
+    delete observersByDotNetId[dotNetHelper._id];
+  }
+}

src/Components/Web.JS/src/GlobalExports.ts

@@ -0,0 +1,11 @@
+// Copyright (c) .NET Foundation. All rights reserved.
+// Licensed under the Apache License, Version 2.0. See License.txt in the project root for license information. 
+
+namespace Microsoft.AspNetCore.Components.Web.Virtualization
+{
+    internal interface IVirtualizeJsCallbacks
+    {
+        void OnBeforeSpacerVisible(float spacerSize, float containerSize);
+        void OnAfterSpacerVisible(float spacerSize, float containerSize);
+    }
+}

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

@@ -0,0 +1,15 @@
+// Copyright (c) .NET Foundation. All rights reserved.
+// Licensed under the Apache License, Version 2.0. See License.txt in the project root for license information. 
+
+using System.Threading.Tasks;
+
+namespace Microsoft.AspNetCore.Components.Web.Virtualization
+{
+    /// <summary>
+    /// A function that provides items to a virtualized source.
+    /// </summary>
+    /// <typeparam name="TItem">The type of the context for each item in the list.</typeparam>
+    /// <param name="request">The <see cref="ItemsProviderRequest"/> defining the request details.</param>
+    /// <returns>A <see cref="ValueTask"/> whose result is a <see cref="ItemsProviderResult{TItem}"/> upon successful completion.</returns>
+    public delegate ValueTask<ItemsProviderResult<TItem>> ItemsProviderDelegate<TItem>(ItemsProviderRequest request);
+}

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

@@ -0,0 +1,44 @@
+// Copyright (c) .NET Foundation. All rights reserved.
+// Licensed under the Apache License, Version 2.0. See License.txt in the project root for license information. 
+
+using System.Threading;
+
+namespace Microsoft.AspNetCore.Components.Web.Virtualization
+{
+    /// <summary>
+    /// Represents a request to an <see cref="ItemsProviderDelegate{TItem}"/>.
+    /// </summary>
+    public readonly struct ItemsProviderRequest
+    {
+        /// <summary>
+        /// The start index of the data segment requested.
+        /// </summary>
+        public int StartIndex { get; }
+
+        /// <summary>
+        /// The requested number of items to be provided. The actual number of provided items does not need to match
+        /// this value.
+        /// </summary>
+        public int Count { get; }
+
+        /// <summary>
+        /// The <see cref="System.Threading.CancellationToken"/> used to relay cancellation of the request.
+        /// </summary>
+        public CancellationToken CancellationToken { get; }
+
+        /// <summary>
+        /// Constructs a new <see cref="ItemsProviderRequest"/> instance.
+        /// </summary>
+        /// <param name="startIndex">The start index of the data segment requested.</param>
+        /// <param name="count">The requested number of items to be provided.</param>
+        /// <param name="cancellationToken">
+        /// The <see cref="System.Threading.CancellationToken"/> used to relay cancellation of the request.
+        /// </param>
+        public ItemsProviderRequest(int startIndex, int count, CancellationToken cancellationToken)
+        {
+            StartIndex = startIndex;
+            Count = count;
+            CancellationToken = cancellationToken;
+        }
+    }
+}

src/Components/Web/src/Virtualization/ItemsProviderDelegate.cs

@@ -0,0 +1,35 @@
+// Copyright (c) .NET Foundation. All rights reserved.
+// Licensed under the Apache License, Version 2.0. See License.txt in the project root for license information. 
+
+using System.Collections.Generic;
+
+namespace Microsoft.AspNetCore.Components.Web.Virtualization
+{
+    /// <summary>
+    /// Represents the result of a <see cref="ItemsProviderDelegate{TItem}"/>.
+    /// </summary>
+    /// <typeparam name="TItem">The type of the context for each item in the list.</typeparam>
+    public readonly struct ItemsProviderResult<TItem>
+    {
+        /// <summary>
+        /// The items to provide.
+        /// </summary>
+        public IEnumerable<TItem> Items { get; }
+
+        /// <summary>
+        /// The total item count in the source generating the items provided.
+        /// </summary>
+        public int TotalItemCount { get; }
+
+        /// <summary>
+        /// Instantiates a new <see cref="ItemsProviderResult{TItem}"/> instance.
+        /// </summary>
+        /// <param name="items">The items to provide.</param>
+        /// <param name="totalItemCount">The total item count in the source generating the items provided.</param>
+        public ItemsProviderResult(IEnumerable<TItem> items, int totalItemCount)
+        {
+            Items = items;
+            TotalItemCount = totalItemCount;
+        }
+    }
+}

src/Components/Web/src/Virtualization/ItemsProviderRequest.cs

@@ -0,0 +1,25 @@
+// Copyright (c) .NET Foundation. All rights reserved.
+// Licensed under the Apache License, Version 2.0. See License.txt in the project root for license information. 
+
+namespace Microsoft.AspNetCore.Components.Web.Virtualization
+{
+    /// <summary>
+    /// Contains context for a placeholder in a virtualized list.
+    /// </summary>
+    public readonly struct PlaceholderContext
+    {
+        /// <summary>
+        /// The item index of the placeholder.
+        /// </summary>
+        public int Index { get; }
+
+        /// <summary>
+        /// Constructs a new <see cref="PlaceholderContext"/> instance.
+        /// </summary>
+        /// <param name="index">The item index of the placeholder.</param>
+        public PlaceholderContext(int index)
+        {
+            Index = index;
+        }
+    }
+}