feat(core): support IntersectionObserver options in viewport triggers (#64130)

Adds support for customizing the `IntersectionObserver` options for the `on viewport`, `prefetch on viewport` and `hydrate on viewport` triggers.

Note that the options need to be a static object literal, e.g. `@defer (on viewport(trigger, {rootMargin: '123px'})`.

Fixes #52799.

PR Close #64130

Author: crisbeto

packages/core/primitives/defer/src/triggers.ts

@@ -19,7 +19,7 @@ const hoverTriggers = new WeakMap<Element, DeferEventEntry>();
 const interactionTriggers = new WeakMap<Element, DeferEventEntry>();
 
 /** Currently-registered `viewport` triggers. */
-export const viewportTriggers = new WeakMap<Element, DeferEventEntry>();
+export const viewportTriggers = new WeakMap<Element, Map<string, DeferEventEntry>>();
 
 /** Names of the events considered as interaction events. */
 export const interactionEventNames = ['click', 'keydown'] as const;
@@ -28,10 +28,7 @@ export const interactionEventNames = ['click', 'keydown'] as const;
 export const hoverEventNames = ['mouseenter', 'mouseover', 'focusin'] as const;
 
 /** `IntersectionObserver` used to observe `viewport` triggers. */
-let intersectionObserver: IntersectionObserver | null = null;
-
-/** Number of elements currently observed with `viewport` triggers. */
-let observedViewportElements = 0;
+const intersectionObservers = new Map<string, {observer: IntersectionObserver; count: number}>();
 
 /** Object keeping track of registered callbacks for a deferred block trigger. */
 class DeferEventEntry {
@@ -130,14 +127,15 @@ export function onHover(trigger: Element, callback: VoidFunction): VoidFunction
  * Used to create an IntersectionObserver instance.
  * @return IntersectionObserver that is used by onViewport
  */
-export function createIntersectionObserver() {
+export function createIntersectionObserver(options?: IntersectionObserverInit) {
+  const key = getIntersectionObserverKey(options);
   return new IntersectionObserver((entries) => {
     for (const current of entries) {
       if (current.isIntersecting && viewportTriggers.has(current.target)) {
-        viewportTriggers.get(current.target)!.listener();
+        viewportTriggers.get(current.target)?.get(key)?.listener();
       }
     }
-  });
+  }, options);
 }
 
 /**
@@ -152,37 +150,71 @@ export function createIntersectionObserver() {
 export function onViewport(
   trigger: Element,
   callback: VoidFunction,
-  observerFactoryFn: () => IntersectionObserver,
+  observerFactoryFn: (options?: IntersectionObserverInit) => IntersectionObserver,
+  options?: IntersectionObserverInit,
 ): VoidFunction {
-  let entry = viewportTriggers.get(trigger);
+  const key = getIntersectionObserverKey(options);
+  let entry = viewportTriggers.get(trigger)?.get(key);
+
+  if (!intersectionObservers.has(key)) {
+    intersectionObservers.set(key, {observer: observerFactoryFn(options), count: 0});
+  }
 
-  intersectionObserver = intersectionObserver || observerFactoryFn();
+  const config = intersectionObservers.get(key)!;
 
   if (!entry) {
     entry = new DeferEventEntry();
-    intersectionObserver!.observe(trigger);
-    viewportTriggers.set(trigger, entry);
-    observedViewportElements++;
+    config.observer.observe(trigger);
+
+    let triggerConfig = viewportTriggers.get(trigger);
+
+    if (triggerConfig) {
+      triggerConfig.set(key, entry);
+    } else {
+      triggerConfig = new Map();
+      viewportTriggers.set(trigger, triggerConfig);
+    }
+
+    triggerConfig.set(key, entry);
+    config.count++;
   }
 
   entry.callbacks.add(callback);
 
   return () => {
-    if (!viewportTriggers.has(trigger)) {
+    if (!viewportTriggers.get(trigger)?.has(key)) {
       return;
     }
 
     entry!.callbacks.delete(callback);
 
     if (entry!.callbacks.size === 0) {
-      intersectionObserver?.unobserve(trigger);
-      viewportTriggers.delete(trigger);
-      observedViewportElements--;
+      config.observer.unobserve(trigger);
+      config.count--;
+
+      const triggerConfig = viewportTriggers.get(trigger);
+
+      if (triggerConfig) {
+        triggerConfig.delete(key);
+
+        if (triggerConfig.size === 0) {
+          viewportTriggers.delete(trigger);
+        }
+      }
     }
 
-    if (observedViewportElements === 0) {
-      intersectionObserver?.disconnect();
-      intersectionObserver = null;
+    if (config.count === 0) {
+      config.observer.disconnect();
+      intersectionObservers.delete(key);
     }
   };
 }
+
+/** Generates a string that can be used to find identical intersection observer option objects. */
+function getIntersectionObserverKey(options: IntersectionObserverInit | undefined): string {
+  if (!options) {
+    return '';
+  }
+
+  return `${options.rootMargin}/${typeof options.threshold === 'number' ? options.threshold : options.threshold?.join('\n')}`;
+}

packages/core/src/defer/dom_triggers.ts

@@ -39,12 +39,18 @@ import {getLDeferBlockDetails} from './utils';
  * @param callback Callback to be invoked when the trigger comes into the viewport.
  * @param injector Injector that can be used by the trigger to resolve DI tokens.
  */
-export function onViewportWrapper(trigger: Element, callback: VoidFunction, injector: Injector) {
+export function onViewportWrapper(
+  trigger: Element,
+  callback: VoidFunction,
+  injector: Injector,
+  wrapperOptions?: IntersectionObserverInit,
+) {
   const ngZone = injector.get(NgZone);
   return onViewport(
     trigger,
     () => ngZone.run(callback),
-    () => ngZone.runOutsideAngular(() => createIntersectionObserver()),
+    (options) => ngZone.runOutsideAngular(() => createIntersectionObserver(options)),
+    wrapperOptions,
   );
 }
 
@@ -59,7 +65,7 @@ export function onViewportWrapper(trigger: Element, callback: VoidFunction, inje
 export function getTriggerLView(
   deferredHostLView: LView,
   deferredTNode: TNode,
-  walkUpTimes: number | undefined,
+  walkUpTimes: number | undefined | null,
 ): LView | null {
   // The trigger is in the same view, we don't need to traverse.
   if (walkUpTimes == null) {
@@ -113,14 +119,20 @@ export function getTriggerElement(triggerLView: LView, triggerIndex: number): El
  *     the deferred block.
  * @param type Trigger type to distinguish between regular and prefetch triggers.
  */
-export function registerDomTrigger(
+export function registerDomTrigger<O>(
   initialLView: LView,
   tNode: TNode,
   triggerIndex: number,
-  walkUpTimes: number | undefined,
-  registerFn: (element: Element, callback: VoidFunction, injector: Injector) => VoidFunction,
+  walkUpTimes: number | undefined | null,
+  registerFn: (
+    element: Element,
+    callback: VoidFunction,
+    injector: Injector,
+    options?: O,
+  ) => VoidFunction,
   callback: VoidFunction,
   type: TriggerType,
+  options?: O,
 ) {
   const injector = initialLView[INJECTOR];
   const zone = injector.get(NgZone);
@@ -173,6 +185,7 @@ export function registerDomTrigger(
         });
       },
       injector,
+      options,
     );
 
     // The trigger and deferred block might be in different LViews.

packages/core/src/defer/instructions.ts

@@ -541,7 +541,7 @@ export function ɵɵdeferHydrateOnTimer(delay: number) {
   if (!shouldAttachTrigger(TriggerType.Hydrate, lView, tNode)) return;
 
   const hydrateTriggers = getHydrateTriggers(getTView(), tNode);
-  hydrateTriggers.set(DeferBlockTrigger.Timer, {delay});
+  hydrateTriggers.set(DeferBlockTrigger.Timer, {type: DeferBlockTrigger.Timer, delay});
 
   if (typeof ngServerMode !== 'undefined' && ngServerMode) {
     // We are on the server and SSR for defer blocks is enabled.
@@ -751,15 +751,26 @@ export function ɵɵdeferHydrateOnInteraction() {
  * @param walkUpTimes Number of times to walk up/down the tree hierarchy to find the trigger.
  * @codeGenApi
  */
-export function ɵɵdeferOnViewport(triggerIndex: number, walkUpTimes?: number) {
+export function ɵɵdeferOnViewport(
+  triggerIndex: number,
+  walkUpTimes?: number | null,
+  options?: IntersectionObserverInit,
+) {
   const lView = getLView();
   const tNode = getCurrentTNode()!;
 
   if (ngDevMode) {
+    const args: string[] = [];
+    if (walkUpTimes !== undefined && walkUpTimes !== -1) {
+      args.push('<target>');
+    }
+    if (options) {
+      args.push(JSON.stringify(options));
+    }
     trackTriggerForDebugging(
       lView[TVIEW],
       tNode,
-      `on viewport${walkUpTimes === -1 ? '' : '(<target>)'}`,
+      `on viewport${args.length === 0 ? '' : `(${args.join(', ')})`}`,
     );
   }
 
@@ -777,6 +788,7 @@ export function ɵɵdeferOnViewport(triggerIndex: number, walkUpTimes?: number)
       onViewportWrapper,
       () => triggerDeferBlock(TriggerType.Regular, lView, tNode),
       TriggerType.Regular,
+      options,
     );
   }
 }
@@ -787,15 +799,26 @@ export function ɵɵdeferOnViewport(triggerIndex: number, walkUpTimes?: number)
  * @param walkUpTimes Number of times to walk up/down the tree hierarchy to find the trigger.
  * @codeGenApi
  */
-export function ɵɵdeferPrefetchOnViewport(triggerIndex: number, walkUpTimes?: number) {
+export function ɵɵdeferPrefetchOnViewport(
+  triggerIndex: number,
+  walkUpTimes?: number | null,
+  options?: IntersectionObserverInit,
+) {
   const lView = getLView();
   const tNode = getCurrentTNode()!;
 
   if (ngDevMode) {
+    const args: string[] = [];
+    if (walkUpTimes !== undefined && walkUpTimes !== -1) {
+      args.push('<target>');
+    }
+    if (options) {
+      args.push(JSON.stringify(options));
+    }
     trackTriggerForDebugging(
       lView[TVIEW],
       tNode,
-      `prefetch on viewport${walkUpTimes === -1 ? '' : '(<target>)'}`,
+      `prefetch on viewport${args.length === 0 ? '' : `(${args.join(', ')})`}`,
     );
   }
 
@@ -813,6 +836,7 @@ export function ɵɵdeferPrefetchOnViewport(triggerIndex: number, walkUpTimes?:
       onViewportWrapper,
       () => triggerPrefetching(tDetails, lView, tNode),
       TriggerType.Prefetch,
+      options,
     );
   }
 }
@@ -821,18 +845,30 @@ export function ɵɵdeferPrefetchOnViewport(triggerIndex: number, walkUpTimes?:
  * Creates runtime data structures for the `on viewport` hydrate trigger.
  * @codeGenApi
  */
-export function ɵɵdeferHydrateOnViewport() {
+export function ɵɵdeferHydrateOnViewport(options?: IntersectionObserverInit) {
   const lView = getLView();
   const tNode = getCurrentTNode()!;
 
   if (ngDevMode) {
-    trackTriggerForDebugging(lView[TVIEW], tNode, 'hydrate on viewport');
+    trackTriggerForDebugging(
+      lView[TVIEW],
+      tNode,
+      `hydrate on viewport${options ? `(${JSON.stringify(options)})` : ''}`,
+    );
   }
 
   if (!shouldAttachTrigger(TriggerType.Hydrate, lView, tNode)) return;
 
   const hydrateTriggers = getHydrateTriggers(getTView(), tNode);
-  hydrateTriggers.set(DeferBlockTrigger.Viewport, null);
+  hydrateTriggers.set(
+    DeferBlockTrigger.Viewport,
+    options
+      ? {
+          type: DeferBlockTrigger.Viewport,
+          intersectionObserverOptions: options,
+        }
+      : null,
+  );
 
   if (typeof ngServerMode !== 'undefined' && ngServerMode) {
     // We are on the server and SSR for defer blocks is enabled.

packages/core/src/defer/interfaces.ts

@@ -203,13 +203,20 @@ export const enum DeferBlockTrigger {
   Never,
 }
 
-/** * Describes specified delay (in ms) in the `hydrate on timer()` trigger. */
+/** Describes specified delay (in ms) in the `hydrate on timer()` trigger. */
 export interface HydrateTimerTriggerDetails {
-  delay: number;
+  type: DeferBlockTrigger.Timer;
+  delay?: number;
+}
+
+/** Describes the config for a `hydrate on viewport` trigger. */
+export interface HydrateViewportTriggerDetails {
+  type: DeferBlockTrigger.Viewport;
+  intersectionObserverOptions?: IntersectionObserverInit;
 }
 
 /** * Describes all possible hydration trigger details specified in a template. */
-export type HydrateTriggerDetails = HydrateTimerTriggerDetails;
+export type HydrateTriggerDetails = HydrateTimerTriggerDetails | HydrateViewportTriggerDetails;
 
 /**
  * Describes the initial state of this defer block instance.

packages/core/src/defer/triggering.ts

@@ -682,6 +682,9 @@ export function processAndInitTriggers(
           timerElements.push(elementTrigger);
         }
         if (blockSummary.hydrate.viewport) {
+          if (typeof blockSummary.hydrate.viewport !== 'boolean') {
+            elementTrigger.intersectionObserverOptions = blockSummary.hydrate.viewport;
+          }
           viewportElements.push(elementTrigger);
         }
       }
@@ -711,6 +714,7 @@ function setViewportTriggers(injector: Injector, elementTriggers: ElementTrigger
         elementTrigger.el,
         () => triggerHydrationFromBlockName(injector, elementTrigger.blockName),
         injector,
+        elementTrigger.intersectionObserverOptions,
       );
       registry.addCleanupFn(elementTrigger.blockName, cleanupFn);
     }

packages/core/src/hydration/annotate.ts

@@ -492,8 +492,10 @@ function serializeHydrateTriggers(
     if (serializableDeferBlockTrigger.has(trigger)) {
       if (details === null) {
         triggers.push(trigger);
-      } else {
+      } else if (details.type === DeferBlockTrigger.Timer) {
         triggers.push({trigger, delay: details.delay});
+      } else {
+        triggers.push({trigger, intersectionObserverOptions: details.intersectionObserverOptions});
       }
     }
   }

packages/core/src/hydration/interfaces.ts

@@ -187,6 +187,7 @@ export interface SerializedDeferBlock {
 export interface SerializedTriggerDetails {
   trigger: DeferBlockTrigger;
   delay?: number;
+  intersectionObserverOptions?: IntersectionObserverInit;
 }
 
 /**
@@ -285,7 +286,12 @@ export interface DehydratedIcuData {
  */
 export interface BlockSummary {
   data: SerializedDeferBlock;
-  hydrate: {idle: boolean; immediate: boolean; viewport: boolean; timer: number | null};
+  hydrate: {
+    idle: boolean;
+    immediate: boolean;
+    viewport: true | IntersectionObserverInit | null;
+    timer: number | null;
+  };
 }
 
 /**
@@ -295,4 +301,5 @@ export interface ElementTrigger {
   el: HTMLElement;
   blockName: string;
   delay?: number;
+  intersectionObserverOptions?: IntersectionObserverInit;
 }