feat(template): add runtime enable/disable support for VirtualView

eneajaho · eneajaho · commit ba1874df91e1 · 2026-01-31T22:34:02.000+01:00
Introduced runtime support for enabling/disabling `RxVirtualView`, including new configuration options (`enabled`, `enableAfterHydration`) and reactive signals. Improved platform detection with `PLATFORM` token, updated resize observer and visibility logic for server/browser context compatibility, and adjusted content/placeholder lifecycle handling.
diff --git a/libs/template/virtual-view/src/lib/resize-observer.ts b/libs/template/virtual-view/src/lib/resize-observer.ts
@@ -1,6 +1,7 @@
 import { DestroyRef, inject, Injectable } from '@angular/core';
-import { Observable, ReplaySubject, Subject } from 'rxjs';
+import { EMPTY, Observable, ReplaySubject, Subject } from 'rxjs';
 import { distinctUntilChanged, finalize } from 'rxjs/operators';
+import { PLATFORM } from './util';
 
 /**
  * A service that observes the resize of the elements.
@@ -10,35 +11,45 @@ import { distinctUntilChanged, finalize } from 'rxjs/operators';
 @Injectable()
 export class RxaResizeObserver {
   #destroyRef = inject(DestroyRef);
-  #resizeObserver = new ResizeObserver((entries) => {
-    entries.forEach((entry) => {
-      if (this.#elements.has(entry.target))
-        this.#elements.get(entry.target)!.next(entry);
-    });
-  });
+  #platform = inject(PLATFORM);
+
+  #resizeObserver: ResizeObserver | null = null;
 
   /** @internal */
   #elements = new Map<Element, Subject<ResizeObserverEntry>>();
 
   constructor() {
+    if (this.#platform.isBrowser) {
+      this.#resizeObserver = new ResizeObserver((entries) => {
+        entries.forEach((entry) => {
+          if (this.#elements.has(entry.target))
+            this.#elements.get(entry.target)!.next(entry);
+        });
+      });
+    }
+
     this.#destroyRef.onDestroy(() => {
       this.#elements.clear();
-      this.#resizeObserver.disconnect();
+      this.#resizeObserver?.disconnect();
     });
   }
 
   observeElement(
     element: Element,
     options?: ResizeObserverOptions,
   ): Observable<ResizeObserverEntry> {
+    if (!this.#resizeObserver) {
+      return EMPTY;
+    }
+
     const resizeEvent$ = new ReplaySubject<ResizeObserverEntry>(1);
     this.#elements.set(element, resizeEvent$);
     this.#resizeObserver.observe(element, options);
 
     return resizeEvent$.pipe(
       distinctUntilChanged(),
       finalize(() => {
-        this.#resizeObserver.unobserve(element);
+        this.#resizeObserver?.unobserve(element);
         this.#elements.delete(element);
       }),
     );
diff --git a/libs/template/virtual-view/src/lib/virtual-view-observer.directive.ts b/libs/template/virtual-view/src/lib/virtual-view-observer.directive.ts
@@ -11,12 +11,14 @@ import {
   BehaviorSubject,
   combineLatest,
   Observable,
+  of,
   ReplaySubject,
   Subject,
 } from 'rxjs';
 import { distinctUntilChanged, finalize, map } from 'rxjs/operators';
 import { _RxVirtualViewObserver } from './model';
 import { RxaResizeObserver } from './resize-observer';
+import { PLATFORM } from './util';
 import { VirtualViewCache } from './virtual-view-cache';
 
 /**
@@ -50,6 +52,7 @@ export class RxVirtualViewObserver
   extends _RxVirtualViewObserver
   implements OnInit, OnDestroy
 {
+  #platform = inject(PLATFORM);
   #elementRef = inject<ElementRef<HTMLElement>>(ElementRef);
 
   #observer: IntersectionObserver | null = null;
@@ -97,19 +100,21 @@ export class RxVirtualViewObserver
   #forcedHidden$ = new BehaviorSubject(false);
 
   ngOnInit(): void {
-    this.#observer = new IntersectionObserver(
-      (entries) => {
-        entries.forEach((entry) => {
-          if (this.#elements.has(entry.target))
-            this.#elements.get(entry.target)?.next(entry.isIntersecting);
-        });
-      },
-      {
-        root: this.#rootElement(),
-        rootMargin: this.rootMargin(),
-        threshold: this.threshold(),
-      },
-    );
+    if (this.#platform.isBrowser) {
+      this.#observer = new IntersectionObserver(
+        (entries) => {
+          entries.forEach((entry) => {
+            if (this.#elements.has(entry.target))
+              this.#elements.get(entry.target)?.next(entry.isIntersecting);
+          });
+        },
+        {
+          root: this.#rootElement(),
+          rootMargin: this.rootMargin(),
+          threshold: this.threshold(),
+        },
+      );
+    }
   }
 
   ngOnDestroy() {
@@ -143,6 +148,10 @@ export class RxVirtualViewObserver
   }
 
   observeElementVisibility(virtualView: HTMLElement) {
+    if (this.#platform.isServer) {
+      return of(true);
+    }
+
     const isVisible$ = new ReplaySubject<boolean>(1);
 
     // Store the view and the visibility state in the map.
diff --git a/libs/template/virtual-view/src/lib/virtual-view.config.ts b/libs/template/virtual-view/src/lib/virtual-view.config.ts
@@ -1,4 +1,4 @@
-import { InjectionToken, Provider } from '@angular/core';
+import { InjectionToken, Provider, Signal } from '@angular/core';
 import { RxStrategyNames } from '@rx-angular/cdk/render-strategies';
 
 export const VIRTUAL_VIEW_CONFIG_TOKEN =
@@ -8,13 +8,23 @@ export const VIRTUAL_VIEW_CONFIG_TOKEN =
   });
 
 export interface RxVirtualViewConfig {
+  enabled: boolean | Signal<boolean>;
   keepLastKnownSize: boolean;
   useContentVisibility: boolean;
   useContainment: boolean;
   placeholderStrategy: RxStrategyNames<string>;
   contentStrategy: RxStrategyNames<string>;
   cacheEnabled: boolean;
   startWithPlaceholderAsap: boolean;
+
+  /**
+   * Whether to enable the visibility after hydration. (DEFAULT: true)
+   *
+   * If `false`, the elements that were hydrated, won't go back to render placeholder anymore on hydration.
+   * You can disable this to avoid destroying components that were just hydrated.
+   */
+  enableAfterHydration: boolean;
+
   cache: {
     /**
      * The maximum number of contents that can be stored in the cache.
@@ -31,13 +41,16 @@ export interface RxVirtualViewConfig {
 }
 
 export const VIRTUAL_VIEW_CONFIG_DEFAULT: RxVirtualViewConfig = {
+  enabled: true,
   keepLastKnownSize: false,
   useContentVisibility: false,
   useContainment: true,
   placeholderStrategy: 'low',
   contentStrategy: 'normal',
   startWithPlaceholderAsap: false,
   cacheEnabled: true,
+  enableAfterHydration: true,
+
   cache: {
     contentCacheSize: 20,
     placeholderCacheSize: 20,
@@ -74,10 +87,25 @@ export const VIRTUAL_VIEW_CONFIG_DEFAULT: RxVirtualViewConfig = {
  * @returns An object that can be provided to the `VirtualView` service.
  */
 export function provideVirtualViewConfig(
-  config: Partial<
-    RxVirtualViewConfig & { cache?: Partial<RxVirtualViewConfig['cache']> }
-  >,
+  config: VVConfig | (() => VVConfig),
 ): Provider {
+  if (typeof config === 'function') {
+    return {
+      provide: VIRTUAL_VIEW_CONFIG_TOKEN,
+      useFactory: () => {
+        const cfg = config();
+        return {
+          ...VIRTUAL_VIEW_CONFIG_DEFAULT,
+          ...cfg,
+          cache: {
+            ...VIRTUAL_VIEW_CONFIG_DEFAULT.cache,
+            ...(cfg?.cache ?? {}),
+          },
+        };
+      },
+    } satisfies Provider;
+  }
+
   return {
     provide: VIRTUAL_VIEW_CONFIG_TOKEN,
     useValue: {
@@ -87,3 +115,7 @@ export function provideVirtualViewConfig(
     },
   } satisfies Provider;
 }
+
+type VVConfig = Partial<
+  RxVirtualViewConfig & { cache?: Partial<RxVirtualViewConfig['cache']> }
+>;
diff --git a/libs/template/virtual-view/src/lib/virtual-view.directive.ts b/libs/template/virtual-view/src/lib/virtual-view.directive.ts
