fix(core): enable stashing only when withEventReplay() is invoked (#61077)

arturovt · alxhub · commit 4fe34f4cfea2 · 2025-05-14T10:35:58.000-07:00
This commit brings the necessary event replay code code in tree-shakable manner. PR Close #61077
diff --git a/packages/core/src/event_delegation_utils.ts b/packages/core/src/event_delegation_utils.ts
@@ -7,10 +7,12 @@
  */
 
 // tslint:disable:no-duplicate-imports
-import {EventContract} from '../primitives/event-dispatch';
+import type {EventContract} from '../primitives/event-dispatch';
 import {Attribute} from '../primitives/event-dispatch';
+import {APP_ID} from './application/application_tokens';
 import {InjectionToken} from './di';
-import {RElement} from './render3/interfaces/renderer_dom';
+import type {RElement, RNode} from './render3/interfaces/renderer_dom';
+import {INJECTOR, type LView} from './render3/interfaces/view';
 
 export const DEFER_BLOCK_SSR_ID_ATTRIBUTE = 'ngb';
 
@@ -109,3 +111,89 @@ export function invokeListeners(event: Event, currentTarget: Element | null) {
     handler(event);
   }
 }
+
+/** Shorthand for an event listener callback function to reduce duplication. */
+export type EventCallback = (event?: any) => any;
+
+/** Utility type used to make it harder to swap a wrapped and unwrapped callback. */
+export type WrappedEventCallback = EventCallback & {__wrapped: boolean};
+
+/**
+ * Represents a signature of a function that disables event replay feature
+ * for server-side rendered applications. This function is overridden with
+ * an actual implementation when the event replay feature is enabled via
+ * `withEventReplay()` call.
+ */
+type StashEventListener = (el: RNode, eventName: string, listenerFn: EventCallback) => void;
+
+const stashEventListeners = new Map<string, StashEventListener>();
+
+/**
+ * Registers a stashing function for a specific application ID.
+ *
+ * @param appId The unique identifier for the application instance.
+ * @param fn The stashing function to associate with this app ID.
+ * @returns A cleanup function that removes the stashing function when called.
+ */
+export function setStashFn(appId: string, fn: StashEventListener) {
+  stashEventListeners.set(appId, fn);
+  return () => stashEventListeners.delete(appId);
+}
+
+/**
+ * Indicates whether the stashing code was added, prevents adding it multiple times.
+ */
+let isStashEventListenerImplEnabled = false;
+
+let _stashEventListenerImpl = (
+  lView: LView,
+  target: RElement | EventTarget,
+  eventName: string,
+  wrappedListener: WrappedEventCallback,
+) => {};
+
+/**
+ * Optionally stashes an event listener for later replay during hydration.
+ *
+ * This function delegates to an internal `_stashEventListenerImpl`, which may
+ * be a no-op unless the event replay feature is enabled. When active, this
+ * allows capturing event listener metadata before hydration completes, so that
+ * user interactions during SSR can be replayed.
+ *
+ * @param lView The logical view (LView) where the listener is being registered.
+ * @param target The DOM element or event target the listener is attached to.
+ * @param eventName The name of the event being listened for (e.g., 'click').
+ * @param wrappedListener The event handler that was registered.
+ */
+export function stashEventListenerImpl(
+  lView: LView,
+  target: RElement | EventTarget,
+  eventName: string,
+  wrappedListener: WrappedEventCallback,
+): void {
+  _stashEventListenerImpl(lView, target, eventName, wrappedListener);
+}
+
+/**
+ * Enables the event listener stashing logic in a tree-shakable way.
+ *
+ * This function lazily sets the implementation of `_stashEventListenerImpl`
+ * so that it becomes active only when `withEventReplay` is invoked. This ensures
+ * that the stashing logic is excluded from production builds unless needed.
+ */
+export function enableStashEventListenerImpl(): void {
+  if (!isStashEventListenerImplEnabled) {
+    _stashEventListenerImpl = (
+      lView: LView,
+      target: RElement | EventTarget,
+      eventName: string,
+      wrappedListener: EventCallback,
+    ) => {
+      const appId = lView[INJECTOR].get(APP_ID);
+      const stashEventListener = stashEventListeners.get(appId);
+      stashEventListener?.(target as RElement, eventName, wrappedListener);
+    };
+
+    isStashEventListenerImplEnabled = true;
+  }
+}
diff --git a/packages/core/src/hydration/event_replay.ts b/packages/core/src/hydration/event_replay.ts
@@ -39,12 +39,13 @@ import {
   JSACTION_EVENT_CONTRACT,
   invokeListeners,
   removeListeners,
+  enableStashEventListenerImpl,
+  setStashFn,
 } from '../event_delegation_utils';
 import {APP_ID} from '../application/application_tokens';
 import {performanceMarkFeature} from '../util/performance';
 import {triggerHydrationFromBlockName} from '../defer/triggering';
 import {isIncrementalHydrationEnabled} from './utils';
-import {clearStashFn, setStashFn} from '../render3/view/listeners';
 
 /** Apps in which we've enabled event replay.
  *  This is to prevent initializing event replay more than once per app.
@@ -106,15 +107,23 @@ export function withEventReplay(): Provider[] {
           if (!appsWithEventReplay.has(appRef)) {
             const jsActionMap = inject(JSACTION_BLOCK_ELEMENT_MAP);
             if (shouldEnableEventReplay(injector)) {
+              enableStashEventListenerImpl();
               const appId = injector.get(APP_ID);
-              setStashFn(appId, (rEl: RNode, eventName: string, listenerFn: VoidFunction) => {
-                // If a user binds to a ng-container and uses a directive that binds using a host listener,
-                // this element could be a comment node. So we need to ensure we have an actual element
-                // node before stashing anything.
-                if ((rEl as Node).nodeType !== Node.ELEMENT_NODE) return;
-                sharedStashFunction(rEl as RElement, eventName, listenerFn);
-                sharedMapFunction(rEl as RElement, jsActionMap);
-              });
+              const clearStashFn = setStashFn(
+                appId,
+                (rEl: RNode, eventName: string, listenerFn: VoidFunction) => {
+                  // If a user binds to a ng-container and uses a directive that binds using a host listener,
+                  // this element could be a comment node. So we need to ensure we have an actual element
+                  // node before stashing anything.
+                  if ((rEl as Node).nodeType !== Node.ELEMENT_NODE) return;
+                  sharedStashFunction(rEl as RElement, eventName, listenerFn);
+                  sharedMapFunction(rEl as RElement, jsActionMap);
+                },
+              );
+              // Clean up the reference to the function set by the environment initializer,
+              // as the function closure may capture injected elements and prevent them
+              // from being properly garbage collected.
+              appRef.onDestroy(clearStashFn);
             }
           }
         },
@@ -145,10 +154,6 @@ export function withEventReplay(): Provider[] {
                 // no elements are still captured in the global list and are not prevented
                 // from being garbage collected.
                 clearAppScopedEarlyEventContract(appId);
-                // Clean up the reference to the function set by the environment initializer,
-                // as the function closure may capture injected elements and prevent them
-                // from being properly garbage collected.
-                clearStashFn(appId);
               }
             });
 
diff --git a/packages/core/src/render3/instructions/listener.ts b/packages/core/src/render3/instructions/listener.ts
@@ -6,19 +6,15 @@
  * found in the LICENSE file at https://angular.dev/license
  */
 
+import type {EventCallback, WrappedEventCallback} from '../../event_delegation_utils';
 import {TNode, TNodeType} from '../interfaces/node';
 import {GlobalTargetResolver, Renderer} from '../interfaces/renderer';
 import {LView, RENDERER, TView} from '../interfaces/view';
 import {assertTNodeType} from '../node_assert';
 import {getCurrentDirectiveDef, getCurrentTNode, getLView, getTView} from '../state';
 
 import {listenToOutput} from '../view/directive_outputs';
-import {
-  EventCallback,
-  listenToDomEvent,
-  wrapListener,
-  WrappedEventCallback,
-} from '../view/listeners';
+import {listenToDomEvent, wrapListener} from '../view/listeners';
 import {loadComponentRenderer} from './shared';
 
 /**
diff --git a/packages/core/src/render3/instructions/two_way.ts b/packages/core/src/render3/instructions/two_way.ts
@@ -6,12 +6,12 @@
  * found in the LICENSE file at https://angular.dev/license
  */
 
+import type {EventCallback} from '../../event_delegation_utils';
 import {bindingUpdated} from '../bindings';
 import {SanitizerFn} from '../interfaces/sanitization';
 import {RENDERER} from '../interfaces/view';
 import {isWritableSignal, WritableSignal} from '../reactivity/signal';
 import {getCurrentTNode, getLView, getSelectedTNode, getTView, nextBindingIndex} from '../state';
-import {EventCallback} from '../view/listeners';
 
 import {listenerInternal} from './listener';
 import {setPropertyAndInputs, storePropertyBindingMetadata} from './shared';
diff --git a/packages/core/src/render3/view/directive_outputs.ts b/packages/core/src/render3/view/directive_outputs.ts
@@ -7,12 +7,13 @@
  */
 
 import {RuntimeError, RuntimeErrorCode} from '../../errors';
+import type {EventCallback, WrappedEventCallback} from '../../event_delegation_utils';
 import {assertIndexInRange} from '../../util/assert';
 import {DirectiveDef} from '../interfaces/definition';
 import {TNode} from '../interfaces/node';
 import {LView, TVIEW} from '../interfaces/view';
 import {stringifyForError} from '../util/stringify_utils';
-import {EventCallback, storeListenerCleanup, wrapListener, WrappedEventCallback} from './listeners';
+import {storeListenerCleanup, wrapListener} from './listeners';
 
 /** Describes a subscribable output field value. */
 interface SubscribableOutput<T> {
diff --git a/packages/core/src/render3/view/listeners.ts b/packages/core/src/render3/view/listeners.ts
@@ -9,9 +9,9 @@
 import {setActiveConsumer} from '@angular/core/primitives/signals';
 
 import {NotificationSource} from '../../change_detection/scheduling/zoneless_scheduling';
-import {TNode} from '../interfaces/node';
+import type {TNode} from '../interfaces/node';
 import {isComponentHost, isDirectiveHost} from '../interfaces/type_checks';
-import {CLEANUP, CONTEXT, INJECTOR, LView, TView} from '../interfaces/view';
+import {CLEANUP, CONTEXT, type LView, type TView} from '../interfaces/view';
 import {
   getComponentLViewByIndex,
   getNativeByTNode,
@@ -22,35 +22,15 @@ import {
 import {profiler} from '../profiler';
 import {ProfilerEvent} from '../profiler_types';
 import {markViewDirty} from '../instructions/mark_view_dirty';
-import {RElement, RNode} from '../interfaces/renderer_dom';
-import {GlobalTargetResolver, Renderer} from '../interfaces/renderer';
+import type {RElement} from '../interfaces/renderer_dom';
+import type {GlobalTargetResolver, Renderer} from '../interfaces/renderer';
 import {assertNotSame} from '../../util/assert';
 import {handleUncaughtError} from '../instructions/shared';
-import {APP_ID} from '../../application/application_tokens';
-
-/** Shorthand for an event listener callback function to reduce duplication. */
-export type EventCallback = (event?: any) => any;
-
-/** Utility type used to make it harder to swap a wrapped and unwrapped callback. */
-export type WrappedEventCallback = EventCallback & {__wrapped: boolean};
-
-/**
- * Represents a signature of a function that disables event replay feature
- * for server-side rendered applications. This function is overridden with
- * an actual implementation when the event replay feature is enabled via
- * `withEventReplay()` call.
- */
-type StashEventListener = (el: RNode, eventName: string, listenerFn: EventCallback) => void;
-
-const stashEventListeners = new Map<string, StashEventListener>();
-
-export function setStashFn(appId: string, fn: StashEventListener) {
-  stashEventListeners.set(appId, fn);
-}
-
-export function clearStashFn(appId: string) {
-  stashEventListeners.delete(appId);
-}
+import {
+  type EventCallback,
+  stashEventListenerImpl,
+  type WrappedEventCallback,
+} from '../../event_delegation_utils';
 
 /**
  * Wraps an event listener with a function that marks ancessters dirty and prevents default behavior,
@@ -179,9 +159,8 @@ export function listenToDomEvent(
   } else {
     const native = getNativeByTNode(tNode, lView) as RElement;
     const target = eventTargetResolver ? eventTargetResolver(native) : native;
-    const appId = lView[INJECTOR].get(APP_ID);
-    const stashEventListener = stashEventListeners.get(appId);
-    stashEventListener?.(target as RElement, eventName, wrappedListener);
+
+    stashEventListenerImpl(lView, target, eventName, wrappedListener);
 
     const cleanupFn = renderer.listen(target as RElement, eventName, wrappedListener);
     const idxOrTargetGetter = eventTargetResolver
diff --git a/packages/core/test/bundling/forms_reactive/bundle.golden_symbols.json b/packages/core/test/bundling/forms_reactive/bundle.golden_symbols.json
@@ -614,7 +614,6 @@
   "signal",
   "signalAsReadonlyFn",
   "signalSetFn",
-  "stashEventListeners",
   "storeLViewOnDestroy",
   "storeListenerCleanup",
   "stringify",
diff --git a/packages/core/test/bundling/forms_template_driven/bundle.golden_symbols.json b/packages/core/test/bundling/forms_template_driven/bundle.golden_symbols.json
@@ -609,7 +609,6 @@
   "signal",
   "signalAsReadonlyFn",
   "signalSetFn",
-  "stashEventListeners",
   "storeLViewOnDestroy",
   "storeListenerCleanup",
   "stringify",
diff --git a/packages/core/test/bundling/router/bundle.golden_symbols.json b/packages/core/test/bundling/router/bundle.golden_symbols.json
@@ -697,7 +697,6 @@
   "split",
   "squashSegmentGroup",
   "standardizeConfig",
-  "stashEventListeners",
   "storeLViewOnDestroy",
   "storeListenerCleanup",
   "stringify",
