@yuuvis/client-framework 3.4.1 → 3.5.0

package/fesm2022/yuuvis-client-framework.mjs

@@ -1,9 +1,11 @@
 import * as i0 from '@angular/core';
-import { inject, Injectable, signal, ChangeDetectionStrategy, Component, DestroyRef, makeEnvironmentProviders, provideAppInitializer, NgZone, NgModule } from '@angular/core';
+import { inject, Injectable, ApplicationRef, DestroyRef, signal, ChangeDetectionStrategy, Component, makeEnvironmentProviders, provideAppInitializer, NgZone, NgModule } from '@angular/core';
 import { takeUntilDestroyed, toSignal } from '@angular/core/rxjs-interop';
+import { SwUpdate } from '@angular/service-worker';
 import { TranslateService } from '@ngx-translate/core';
+import { ConfirmService } from '@yuuvis/client-framework/common';
+import { filter, first, concat, interval, finalize, timer, switchMap, map, debounceTime } from 'rxjs';
 import { AppCacheService, BackendService, UserService, EventService, YuvEventType } from '@yuuvis/client-core';
-import { finalize, timer, switchMap, map, debounceTime } from 'rxjs';
 import * as i1 from '@angular/material/button';
 import { MatButtonModule } from '@angular/material/button';
 import { MatSnackBar, MatSnackBarRef, MAT_SNACK_BAR_DATA, MatSnackBarLabel, MatSnackBarActions, MatSnackBarAction } from '@angular/material/snack-bar';
@@ -124,6 +126,22 @@ const haloFocusStyles = {
     transform: 'translateZ(0)'
 };
 
+/**
+ * Default interval (in milliseconds) for periodic PWA update checks.
+ *
+ * After the application stabilizes, {@link PwaUpdateService} polls the service
+ * worker for a newer deployed version on this interval. This complements the
+ * `VERSION_READY` event, which only fires while the tab is open and the service
+ * worker happens to detect a change — long-running sessions would otherwise
+ * never learn about a new release.
+ *
+ * Override via `providePwaUpdate({ checkInterval })`. Set `checkInterval` to `0`
+ * to disable polling and rely solely on `VERSION_READY`.
+ *
+ * @default 6 hours (21600000 milliseconds)
+ */
+const pwaUpdateDefaultCheckInterval = 6 * 60 * 60 * 1000; // 6 hours
+
 /**
  * Default session duration (in milliseconds) when no explicit duration is provided.
  *
@@ -948,6 +966,115 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.12", ngImpo
             type: Injectable
         }] });
 
+/**
+ * Detects newly deployed versions of the application (PWA) and lets the user
+ * decide when to apply them.
+ *
+ * **Flow (per the Angular `SwUpdate` documentation):**
+ * 1. **Check** — listens for the `VERSION_READY` event and, additionally, polls
+ *    `checkForUpdate()` on an interval once the app is stable. The update is
+ *    *not* applied automatically.
+ * 2. **Ask** — when a new version is ready, prompts the user via the framework
+ *    {@link ConfirmService} dialog instead of reloading silently.
+ * 3. **Apply** — only after the user confirms, calls `activateUpdate()` and then
+ *    reloads the page so the new version takes effect.
+ *
+ * The service is a no-op when the service worker is disabled (e.g. dev mode),
+ * so it is safe to provide unconditionally.
+ *
+ * Wire it up via `providePwaUpdate()` in `app.config.ts`. The service worker
+ * itself must still be registered separately via `provideServiceWorker(...)`.
+ *
+ * @see https://angular.dev/ecosystem/service-workers/communications
+ */
+class PwaUpdateService {
+    #swUpdate = inject(SwUpdate);
+    #confirm = inject(ConfirmService);
+    #translate = inject(TranslateService);
+    #appRef = inject(ApplicationRef);
+    #destroyRef = inject(DestroyRef);
+    /** Guards against opening multiple confirm dialogs while one is already open. */
+    #prompting = false;
+    /**
+     * Starts listening for updates. Called automatically by `providePwaUpdate()`.
+     * Does nothing when the service worker is not enabled.
+     */
+    init(config) {
+        if (!this.#swUpdate.isEnabled) {
+            return;
+        }
+        // 1a. React when the service worker has already downloaded a new version.
+        this.#swUpdate.versionUpdates
+            .pipe(filter((event) => event.type === 'VERSION_READY'), takeUntilDestroyed(this.#destroyRef))
+            .subscribe(() => this.#promptUpdate(config));
+        // 1b. Poll for updates: first once the app is stable, then on an interval.
+        const checkInterval = config?.checkInterval ?? pwaUpdateDefaultCheckInterval;
+        if (checkInterval > 0) {
+            const appStable$ = this.#appRef.isStable.pipe(first((stable) => stable));
+            concat(appStable$, interval(checkInterval))
+                .pipe(takeUntilDestroyed(this.#destroyRef))
+                .subscribe(() => void this.checkForUpdate());
+        }
+        // 1c. Offer a reload when the service worker is in a broken, unrecoverable state.
+        this.#swUpdate.unrecoverable
+            .pipe(takeUntilDestroyed(this.#destroyRef))
+            .subscribe(() => this.#promptUpdate(config, true));
+    }
+    /**
+     * Manually triggers an update check (e.g. from a "check for updates" button).
+     * Resolves to `true` when a new version was found. Network errors are swallowed
+     * and resolve to `false`.
+     */
+    checkForUpdate() {
+        if (!this.#swUpdate.isEnabled) {
+            return Promise.resolve(false);
+        }
+        return this.#swUpdate.checkForUpdate().catch(() => false);
+    }
+    #promptUpdate(config, unrecoverable = false) {
+        if (this.#prompting) {
+            return;
+        }
+        this.#prompting = true;
+        const messageKey = unrecoverable
+            ? (config?.unrecoverableMessage ?? 'yuv.pwa.update.unrecoverable.message')
+            : (config?.message ?? 'yuv.pwa.update.message');
+        this.#confirm
+            .confirm({
+            title: this.#translate.instant(config?.title ?? 'yuv.pwa.update.title'),
+            message: this.#translate.instant(messageKey),
+            confirmLabel: this.#translate.instant(config?.confirmLabel ?? 'yuv.pwa.update.confirm'),
+            cancelLabel: this.#translate.instant(config?.cancelLabel ?? 'yuv.pwa.update.cancel'),
+            // An unrecoverable worker cannot keep serving the app, so reloading is the only option.
+            hideCancelButton: unrecoverable,
+            level: 'info'
+        })
+            .subscribe((confirmed) => {
+            this.#prompting = false;
+            if (confirmed) {
+                this.#applyUpdate(unrecoverable);
+            }
+        });
+    }
+    #applyUpdate(unrecoverable) {
+        // In an unrecoverable state there is no pending version to activate — just reload.
+        if (unrecoverable) {
+            document.location.reload();
+            return;
+        }
+        void this.#swUpdate
+            .activateUpdate()
+            .catch(() => false)
+            .finally(() => document.location.reload());
+    }
+    static { this.ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.2.12", ngImport: i0, type: PwaUpdateService, deps: [], target: i0.ɵɵFactoryTarget.Injectable }); }
+    static { this.ɵprov = i0.ɵɵngDeclareInjectable({ minVersion: "12.0.0", version: "21.2.12", ngImport: i0, type: PwaUpdateService, providedIn: 'root' }); }
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.12", ngImport: i0, type: PwaUpdateService, decorators: [{
+            type: Injectable,
+            args: [{ providedIn: 'root' }]
+        }] });
+
 const SNACK_BAR_DEFAULT_DURATION = 3000;
 class SnackBarService {
     #snackBar;
@@ -1520,6 +1647,48 @@ function provideHaloFocus(config) {
     ]);
 }
 
+/**
+ * Provides and initializes PWA update detection for the application.
+ *
+ * On startup it boots {@link PwaUpdateService}, which watches for newly deployed
+ * versions of the app and, instead of reloading silently, asks the user to
+ * confirm before activating the update and reloading the page.
+ *
+ * **Detection:** reacts to the service worker `VERSION_READY` event and also
+ * polls `checkForUpdate()` on an interval (default 6 hours) once the app is
+ * stable, so long-running sessions still pick up new releases.
+ *
+ * **Prerequisite:** the service worker must be registered separately via
+ * `provideServiceWorker('ngsw-worker.js', { enabled: !isDevMode() })`. When the
+ * service worker is disabled (e.g. dev mode) this provider is a harmless no-op.
+ *
+ * @param config - Optional configuration (check interval, custom dialog labels/messages).
+ * @returns EnvironmentProviders for the PWA update feature.
+ *
+ * @example
+ * // app.config.ts
+ * export const appConfig: ApplicationConfig = {
+ *   providers: [
+ *     provideServiceWorker('ngsw-worker.js', { enabled: !isDevMode() }),
+ *     providePwaUpdate()
+ *   ]
+ * };
+ *
+ * @example
+ * // Custom check interval (1 hour) and labels
+ * providePwaUpdate({
+ *   checkInterval: 60 * 60 * 1000,
+ *   message: 'A new version is available. Reload now?'
+ * });
+ */
+function providePwaUpdate(config) {
+    return makeEnvironmentProviders([
+        provideAppInitializer(() => {
+            inject(PwaUpdateService).init(config);
+        })
+    ]);
+}
+
 /**
  * Provides and initializes the SessionService at application startup.
  *
@@ -1586,5 +1755,5 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.12", ngImpo
  * Generated bundle index. Do not edit.
  */
 
-export { ChannelMessage, HaloFocusService, HaloUtilityService, SessionService, SnackBarComponent, SnackBarService, YuuvisClientFrameworkModule, defaultHaloFocusOffset, haloExcludedElementsInMatFormField, haloFocusNavigationKeys, haloFocusStyles, provideHaloFocus, provideSession, sessionActivityWindowBeforeEnd, sessionDefaultDuration, sessionPopupBeforeEnd };
+export { ChannelMessage, HaloFocusService, HaloUtilityService, PwaUpdateService, SessionService, SnackBarComponent, SnackBarService, YuuvisClientFrameworkModule, defaultHaloFocusOffset, haloExcludedElementsInMatFormField, haloFocusNavigationKeys, haloFocusStyles, provideHaloFocus, providePwaUpdate, provideSession, pwaUpdateDefaultCheckInterval, sessionActivityWindowBeforeEnd, sessionDefaultDuration, sessionPopupBeforeEnd };
 //# sourceMappingURL=yuuvis-client-framework.mjs.map