Clean up notes about interaction

Author: SteveSandersonMS

src/Components/Web.JS/src/Services/NavigationEnhancement.ts

@@ -1,25 +1,31 @@
 import { synchronizeDomContent } from '../Rendering/DomMerging/DomSync';
-import { isNavigationInterceptionEnabled } from './NavigationManager';
-import { handleClickForNavigationInterception } from './NavigationUtils';
+import { handleClickForNavigationInterception, hasInteractiveRouter } from './NavigationUtils';
 
 /*
-We want this to work independently from all the existing logic for NavigationManager and EventDelegator, since
-this feature should be available in minimal .js bundles that don't include support for any interactive mode.
-So, this file should not import those modules. Likewise, we don't want NavigationManager.ts to import this module,
-since then it would have to bundle all the DOM-diffing logic in blazor.server|webassembly|webview.js.
-
-However, when NavigationManager/EventDelegator are being used, we do have to defer to them since SPA-style
-interactive navigation needs to take precedence. The approach is:
-- When blazor.web.js starts up, it will enable progressively-enhanced (PE) nav
-- If an interactive <Router/> is added, it will call enableNavigationInterception and that will disable PE nav's event listener.
-- When NavigationManager.ts sees a navigation occur, it goes through a complex flow (respecting @preventDefault,
-  triggering OnLocationChanging, evaluating the URL against the .NET route table, etc). Normally this will conclude
-  by picking a component page and rendering it without notifying the PE nav logic at all.
-  - But if no component page is matched, it then explicitly calls back into the PE nav logic to fall back on the logic
-  that would have happened if there was no interactive <Router/>. As such, PE nav isn't *really* disabled; it just only
-  runs as a fallback if <Router/> nav doesn't match the URL.
-  - If an interactive <Router/> is removed, we don't currently handle that. No notification goes back from .NET
-  to JS about that. But if the scenario becomes important, we could add some disableNavigationInterception and resume PE nav.
+In effect, we have two separate client-side navigation mechanisms:
+
+[1] Interactive client-side routing. This is the traditional Blazor Server/WebAssembly navigation mechanism for SPAs.
+    It is enabled whenever you have a <Router/> rendering as interactive. This intercepts all navigation within the
+    base href URI space and tries to display a corresponding [Route] component or the NotFoundContent.
+[2] Progressively-enhanced navigation. This is a new mechanism in .NET 8 and is only relevant for multi-page apps.
+    It is enabled when you load blazor.web.js and don't have an interactive <Router/>. This intercepts navigation within
+    the base href URI space and tries to load it via a `fetch` request and DOM syncing.
+
+Only one of these can be enabled at a time, otherwise both would be trying to intercept click/popstate and act on them.
+In fact even if we made the event handlers able to coexist, the two together would still not produce useful behaviors because
+[1] implies you have a <Router/>, and that will try to supply UI content for all pages or NotFoundContent if the URL doesn't
+match a [Route] component, so there would be nothing left for [2] to handle.
+
+So, whenever [1] is enabled, we automatically disable [2].
+
+However, a single site can use both [1] and [2] on different URLs.
+ - You can navigate from [1] to [2] by setting up the interactive <Router/> not to know about any [Route] components in your MPA,
+   and so it will fall back on a full-page load to get from the SPA URLs to the MPA URLs.
+ - You can navigate from [2] to [1] in that it just works by default. A <Router/> can be added dynamically and will then take
+   over and disable [2].
+
+Note that we don't reference NavigationManager.ts from NavigationEnhancement.ts or vice-versa. This is to ensure we could produce
+different bundles that only contain minimal content.
 */
 
 let currentEnhancedNavigationAbortController: AbortController | null;
@@ -30,7 +36,7 @@ export function attachProgressivelyEnhancedNavigationListener() {
 }
 
 function onBodyClicked(event: MouseEvent) {
-  if (isNavigationInterceptionEnabled()) {
+  if (hasInteractiveRouter()) {
     return;
   }
 
@@ -41,7 +47,7 @@ function onBodyClicked(event: MouseEvent) {
 }
 
 function onPopState(state: PopStateEvent) {
-  if (isNavigationInterceptionEnabled()) {
+  if (hasInteractiveRouter()) {
     return;
   }
 

src/Components/Web.JS/src/Services/NavigationManager.ts

@@ -4,9 +4,8 @@
 import '@microsoft/dotnet-js-interop';
 import { resetScrollAfterNextBatch } from '../Rendering/Renderer';
 import { EventDelegator } from '../Rendering/Events/EventDelegator';
-import { handleClickForNavigationInterception, isWithinBaseUriSpace, toAbsoluteUri } from './NavigationUtils';
+import { handleClickForNavigationInterception, hasInteractiveRouter, isWithinBaseUriSpace, setHasInteractiveRouter, toAbsoluteUri } from './NavigationUtils';
 
-let hasEnabledNavigationInterception = false;
 let hasRegisteredNavigationEventListeners = false;
 let hasLocationChangingEventListeners = false;
 let currentHistoryIndex = 0;
@@ -22,7 +21,7 @@ let resolveCurrentNavigation: ((shouldContinueNavigation: boolean) => void) | nu
 // These are the functions we're making available for invocation from .NET
 export const internalFunctions = {
   listenForNavigationEvents,
-  enableNavigationInterception,
+  enableNavigationInterception: setHasInteractiveRouter,
   setHasLocationChangingListeners,
   endLocationChanging,
   navigateTo: navigateToFromDotNet,
@@ -47,14 +46,6 @@ function listenForNavigationEvents(
   currentHistoryIndex = history.state?._index ?? 0;
 }
 
-function enableNavigationInterception(): void {
-  hasEnabledNavigationInterception = true;
-}
-
-export function isNavigationInterceptionEnabled(): boolean {
-  return hasEnabledNavigationInterception;
-}
-
 function setHasLocationChangingListeners(hasListeners: boolean) {
   hasLocationChangingEventListeners = hasListeners;
 }
@@ -75,7 +66,7 @@ export function attachToEventDelegator(eventDelegator: EventDelegator): void {
   // running its simulated bubbling process so that we can respect any preventDefault requests.
   // So instead of registering our own native event, register using the EventDelegator.
   eventDelegator.notifyAfterClick(event => {
-    if (!hasEnabledNavigationInterception) {
+    if (!hasInteractiveRouter()) {
       return;
     }
 

src/Components/Web.JS/src/Services/NavigationUtils.ts

@@ -1,3 +1,5 @@
+let hasInteractiveRouterValue = false;
+
 /**
  * Checks if a click event corresponds to an <a> tag referencing a URL within the base href, and that interception
  * isn't bypassed (e.g., by a 'download' attribute or the user holding a meta key while clicking).
@@ -90,3 +92,11 @@ function findClosestAnchorAncestorLegacy(element: Element | null, tagName: strin
   ? element
   : findClosestAnchorAncestorLegacy(element.parentElement, tagName);
 }
+
+export function hasInteractiveRouter(): boolean {
+  return hasInteractiveRouterValue;
+}
+
+export function setHasInteractiveRouter() {
+  hasInteractiveRouterValue = true;
+}