[Blazor] APIs to preserve content between enhanced navigations (#50437)

# APIs to preserve content between enhanced navigations

Adds APIs to enable the preservation of DOM content between enhanced navigations.

## Description

This PR introduces two new ways to preserve content between enhanced navigations:
1. The `data-permanent` HTML attribute
    * Elements that contain this attribute will have their content preserved between enhanced page updates. The `id` attribute on an element marked as `data-permanent` will be used to match up data permanent elements when performing DOM synchronization.
    * Note that the data permanent element itself is still subject to removal via SSR update if the updated region includes the existing `data-permanent` element. Therefore, the `data-permanent` element itself should **not** be added dynamically via JS, (but its _content_ can be, which is the primary use case).
2. `Blazor.registerEnhancedPageUpdateCallback(callback)`
    * This API can be used in cases where the `data-permanent` attribute is not sufficient. It lets you get notified when an enhanced page update occurs so changes to the DOM can be made in response.
    * Callbacks will be invoked any time the document changes due to an enhanced update, including streaming rendering updates and enhanced form posts. It does not _only_ get involved when a navigation occurs.
    * Callbacks do not get invoked automatically upon registration or after the initial page load.

Fixes #49613

Author: MackinnonBuck

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

@@ -8,6 +8,7 @@ import { setCircuitOptions, startServer } from './Boot.Server.Common';
 import { ServerComponentDescriptor, discoverComponents } from './Services/ComponentDescriptorDiscovery';
 import { DotNet } from '@microsoft/dotnet-js-interop';
 import { InitialRootComponentsList } from './Services/InitialRootComponentsList';
+import { JSEventRegistry } from './Services/JSEventRegistry';
 
 let started = false;
 
@@ -19,6 +20,7 @@ function boot(userOptions?: Partial<CircuitStartOptions>): Promise<void> {
 
   setCircuitOptions(userOptions);
 
+  JSEventRegistry.create(Blazor);
   const serverComponents = discoverComponents(document, 'server') as ServerComponentDescriptor[];
   const components = new InitialRootComponentsList(serverComponents);
   return startServer(components);

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

@@ -15,10 +15,11 @@ import { shouldAutoStart } from './BootCommon';
 import { Blazor } from './GlobalExports';
 import { WebStartOptions } from './Platform/WebStartOptions';
 import { attachStreamingRenderingListener } from './Rendering/StreamingRendering';
-import { attachProgressivelyEnhancedNavigationListener } from './Services/NavigationEnhancement';
+import { NavigationEnhancementCallbacks, attachProgressivelyEnhancedNavigationListener } from './Services/NavigationEnhancement';
 import { WebRootComponentManager } from './Services/WebRootComponentManager';
-import { attachComponentDescriptorHandler, registerAllComponentDescriptors } from './Rendering/DomMerging/DomSync';
 import { hasProgrammaticEnhancedNavigationHandler, performProgrammaticEnhancedNavigation } from './Services/NavigationUtils';
+import { attachComponentDescriptorHandler, registerAllComponentDescriptors } from './Rendering/DomMerging/DomSync';
+import { JSEventRegistry } from './Services/JSEventRegistry';
 
 let started = false;
 let rootComponentManager: WebRootComponentManager;
@@ -44,12 +45,23 @@ function boot(options?: Partial<WebStartOptions>) : Promise<void> {
   setWebAssemblyOptions(options?.webAssembly);
 
   rootComponentManager = new WebRootComponentManager(options?.ssr?.circuitInactivityTimeoutMs ?? 2000);
+  const jsEventRegistry = JSEventRegistry.create(Blazor);
+
+  const navigationEnhancementCallbacks: NavigationEnhancementCallbacks = {
+    documentUpdated: () => {
+      rootComponentManager.onDocumentUpdated();
+      jsEventRegistry.dispatchEvent('enhancedload', {});
+    },
+    enhancedNavigationCompleted() {
+      rootComponentManager.onEnhancedNavigationCompleted();
+    },
+  };
 
   attachComponentDescriptorHandler(rootComponentManager);
-  attachStreamingRenderingListener(options?.ssr, rootComponentManager);
+  attachStreamingRenderingListener(options?.ssr, navigationEnhancementCallbacks);
 
   if (!options?.ssr?.disableDomPreservation) {
-    attachProgressivelyEnhancedNavigationListener(rootComponentManager);
+    attachProgressivelyEnhancedNavigationListener(navigationEnhancementCallbacks);
   }
 
   // Wait until the initial page response completes before activating interactive components.
@@ -66,7 +78,7 @@ function boot(options?: Partial<WebStartOptions>) : Promise<void> {
 
 function onInitialDomContentLoaded() {
   registerAllComponentDescriptors(document);
-  rootComponentManager.documentUpdated();
+  rootComponentManager.onDocumentUpdated();
 }
 
 Blazor.start = boot;

src/Components/Web.JS/src/Boot.Server.ts

@@ -10,6 +10,7 @@ import { setWebAssemblyOptions, startWebAssembly } from './Boot.WebAssembly.Comm
 import { WebAssemblyComponentDescriptor, discoverComponents } from './Services/ComponentDescriptorDiscovery';
 import { DotNet } from '@microsoft/dotnet-js-interop';
 import { InitialRootComponentsList } from './Services/InitialRootComponentsList';
+import { JSEventRegistry } from './Services/JSEventRegistry';
 
 let started = false;
 
@@ -21,6 +22,7 @@ async function boot(options?: Partial<WebAssemblyStartOptions>): Promise<void> {
 
   setWebAssemblyOptions(options);
 
+  JSEventRegistry.create(Blazor);
   const webAssemblyComponents = discoverComponents(document, 'webassembly') as WebAssemblyComponentDescriptor[];
   const components = new InitialRootComponentsList(webAssemblyComponents);
   await startWebAssembly(components);

src/Components/Web.JS/src/Boot.Web.ts

@@ -18,6 +18,7 @@ import { RootComponentsFunctions } from './Rendering/JSRootComponents';
 import { attachWebRendererInterop } from './Rendering/WebRendererInteropMethods';
 import { WebStartOptions } from './Platform/WebStartOptions';
 import { RuntimeAPI } from 'dotnet';
+import { JSEventRegistry } from './Services/JSEventRegistry';
 
 // TODO: It's kind of hard to tell which .NET platform(s) some of these APIs are relevant to.
 // It's important to know this information when dealing with the possibility of mulitple .NET platforms being available.
@@ -29,10 +30,12 @@ import { RuntimeAPI } from 'dotnet';
 // * Blazor._internal.{foo}: internal, platform-agnostic Blazor APIs
 // * Blazor.platform.{somePlatformName}.{foo}: public, platform-specific Blazor APIs (would be empty at first, so no initial breaking changes)
 // * Blazor.platform.{somePlatformName}.{_internal}.{foo}: internal, platform-specific Blazor APIs
-interface IBlazor {
+export interface IBlazor {
   navigateTo: (uri: string, options: NavigationOptions) => void;
   registerCustomEventType: (eventName: string, options: EventTypeOptions) => void;
 
+  addEventListener?: typeof JSEventRegistry.prototype.addEventListener;
+  removeEventListener?: typeof JSEventRegistry.prototype.removeEventListener;
   disconnect?: () => void;
   reconnect?: (existingConnection?: HubConnection) => Promise<boolean>;
   defaultReconnectionHandler?: DefaultReconnectionHandler;
@@ -104,7 +107,7 @@ export const Blazor: IBlazor = {
     InputFile,
     NavigationLock,
     getJSDataStreamChunk: getNextChunk,
-    attachWebRendererInterop
+    attachWebRendererInterop,
   },
 };
 

src/Components/Web.JS/src/Boot.WebAssembly.ts

@@ -0,0 +1,15 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+const dataPermanentAttributeName = 'data-permanent';
+
+export function isDataPermanentElement(elem: Element): boolean {
+  return elem.hasAttribute(dataPermanentAttributeName);
+}
+
+export function cannotMergeDueToDataPermanentAttributes(elementA: Element, elementB: Element) {
+  const dataPermanentAttributeValueA = elementA.getAttribute(dataPermanentAttributeName);
+  const dataPermanentAttributeValueB = elementB.getAttribute(dataPermanentAttributeName);
+
+  return dataPermanentAttributeValueA !== dataPermanentAttributeValueB;
+}

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

@@ -6,6 +6,7 @@ import { isInteractiveRootComponentElement } from '../BrowserRenderer';
 import { applyAnyDeferredValue } from '../DomSpecialPropertyUtil';
 import { LogicalElement, getLogicalChildrenArray, getLogicalNextSibling, getLogicalParent, getLogicalRootDescriptor, insertLogicalChild, insertLogicalChildBefore, isLogicalElement, toLogicalElement, toLogicalRootCommentElement } from '../LogicalElements';
 import { synchronizeAttributes } from './AttributeSync';
+import { cannotMergeDueToDataPermanentAttributes, isDataPermanentElement } from './DataPermanentElementSync';
 import { UpdateCost, ItemList, Operation, computeEditScript } from './EditScript';
 
 let descriptorHandler: DescriptorHandler | null = null;
@@ -184,7 +185,12 @@ function treatAsMatch(destination: Node, source: Node) {
       const editableElementValue = getEditableElementValue(source as Element);
       synchronizeAttributes(destination as Element, source as Element);
       applyAnyDeferredValue(destination as Element);
-      synchronizeDomContentCore(destination as Element, source as Element);
+
+      if (isDataPermanentElement(destination as Element)) {
+        // The destination element's content should be retained, so we avoid recursing into it.
+      } else {
+        synchronizeDomContentCore(destination as Element, source as Element);
+      }
 
       // This is a much simpler alternative to the deferred-value-assignment logic we use in interactive rendering.
       // Because this sync algorithm goes depth-first, we know all the attributes and descendants are fully in sync
@@ -288,7 +294,18 @@ function domNodeComparer(a: Node, b: Node): UpdateCost {
       //       to return UpdateCost.Infinite if either has a key but they don't match. This will prevent unwanted retention.
       //       For the converse (forcing retention, even if that means reordering), we could post-process the list of
       //       inserts/deletes to find matches based on key to treat those pairs as 'move' operations.
-      return (a as Element).tagName === (b as Element).tagName ? UpdateCost.None : UpdateCost.Infinite;
+      if ((a as Element).tagName !== (b as Element).tagName) {
+        return UpdateCost.Infinite;
+      }
+
+      // The two elements must have matching 'data-permanent' attribute values for them to be merged. If they don't match, either:
+      // [1] We're comparing a data-permanent element to a non-data-permanent one.
+      // [2] We're comparing elements that represent two different data-permanent containers.
+      if (cannotMergeDueToDataPermanentAttributes(a as Element, b as Element)) {
+        return UpdateCost.Infinite;
+      }
+
+      return UpdateCost.None;
     case Node.DOCUMENT_TYPE_NODE:
       // It's invalid to insert or delete doctype, and we have no use case for doing that. So just skip such
       // nodes by saying they are always unchanged.

src/Components/Web.JS/src/Rendering/DomMerging/DataPermanentElementSync.ts

@@ -0,0 +1,56 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+import { IBlazor } from '../GlobalExports';
+
+// The base Blazor event type.
+// Properties listed here get assigned by the event registry in 'dispatchEvent'.
+interface BlazorEvent {
+  type: keyof BlazorEventMap;
+}
+
+// Maps Blazor event names to the argument type passed to registered listeners.
+export interface BlazorEventMap {
+  'enhancedload': BlazorEvent;
+}
+
+export class JSEventRegistry {
+  private readonly _eventListeners = new Map<string, Set<(ev: any) => void>>();
+
+  static create(blazor: IBlazor): JSEventRegistry {
+    const result = new JSEventRegistry();
+    blazor.addEventListener = result.addEventListener.bind(result);
+    blazor.removeEventListener = result.removeEventListener.bind(result);
+    return result;
+  }
+
+  public addEventListener<K extends keyof BlazorEventMap>(type: K, listener: (ev: BlazorEventMap[K]) => void): void {
+    let listenersForEventType = this._eventListeners.get(type);
+    if (!listenersForEventType) {
+      listenersForEventType = new Set();
+      this._eventListeners.set(type, listenersForEventType);
+    }
+
+    listenersForEventType.add(listener);
+  }
+
+  public removeEventListener<K extends keyof BlazorEventMap>(type: K, listener: (ev: BlazorEventMap[K]) => void): void {
+    this._eventListeners.get(type)?.delete(listener);
+  }
+
+  public dispatchEvent<K extends keyof BlazorEventMap>(type: K, ev: Omit<BlazorEventMap[K], keyof BlazorEvent>): void {
+    const listenersForEventType = this._eventListeners.get(type);
+    if (!listenersForEventType) {
+      return;
+    }
+
+    const event: BlazorEventMap[K] = {
+      ...ev,
+      type,
+    };
+
+    for (const listener of listenersForEventType) {
+      listener(event);
+    }
+  }
+}

src/Components/Web.JS/src/Rendering/DomMerging/DomSync.ts

@@ -37,6 +37,7 @@ let performingEnhancedPageLoad: boolean;
 
 export interface NavigationEnhancementCallbacks {
   documentUpdated: () => void;
+  enhancedNavigationCompleted: () => void;
 }
 
 export function isPageLoading() {
@@ -250,7 +251,7 @@ export async function performEnhancedPageLoad(internalDestinationHref: string, f
     }
 
     performingEnhancedPageLoad = false;
-    navigationEnhancementCallbacks.documentUpdated();
+    navigationEnhancementCallbacks.enhancedNavigationCompleted();
   }
 }