@yuuvis/client-framework 2.10.3 → 2.11.0

package/fesm2022/yuuvis-client-framework.mjs

@@ -1,21 +1,12 @@
 import * as i0 from '@angular/core';
-import { NgModule, inject, Injectable, signal, Component, makeEnvironmentProviders, provideAppInitializer, NgZone } from '@angular/core';
-import { CommonModule } from '@angular/common';
+import { inject, Injectable, signal, Component, makeEnvironmentProviders, provideAppInitializer, NgZone, NgModule } from '@angular/core';
+import { finalize, timer, switchMap, map, debounceTime } from 'rxjs';
+import { TranslateService } from '@ngx-translate/core';
 import { MatSnackBar, MatSnackBarRef, MAT_SNACK_BAR_DATA, MatSnackBarLabel, MatSnackBarActions, MatSnackBarAction } from '@angular/material/snack-bar';
 import * as i1 from '@angular/material/button';
 import { MatButtonModule } from '@angular/material/button';
-
-class YuuvisClientFrameworkModule {
-    static { this.ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "19.2.15", ngImport: i0, type: YuuvisClientFrameworkModule, deps: [], target: i0.ɵɵFactoryTarget.NgModule }); }
-    static { this.ɵmod = i0.ɵɵngDeclareNgModule({ minVersion: "14.0.0", version: "19.2.15", ngImport: i0, type: YuuvisClientFrameworkModule, imports: [CommonModule] }); }
-    static { this.ɵinj = i0.ɵɵngDeclareInjector({ minVersion: "12.0.0", version: "19.2.15", ngImport: i0, type: YuuvisClientFrameworkModule, imports: [CommonModule] }); }
-}
-i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "19.2.15", ngImport: i0, type: YuuvisClientFrameworkModule, decorators: [{
-            type: NgModule,
-            args: [{
-                    imports: [CommonModule],
-                }]
-        }] });
+import { AppCacheService, BackendService, UserService } from '@yuuvis/client-core';
+import { CommonModule } from '@angular/common';
 
 /**
  * List of element selectors that should be excluded from halo focus
@@ -132,6 +123,152 @@ const haloFocusStyles = {
     transform: 'translateZ(0)'
 };
 
+/**
+ * Default session duration (in milliseconds) when no explicit duration is provided.
+ *
+ * This value is used as the fallback session lifetime when:
+ * - `provideSession()` is called without a duration parameter
+ * - Before `startSession(duration)` is called with a backend-provided value
+ *
+ * **Timeline:**
+ * ```
+ * [Session Start] ──────────────────────────────► [Session Expires]
+ *                 ← sessionDefaultDuration →
+ * ```
+ *
+ * **Override Methods:**
+ * - **At startup (known duration)**: `provideSession(customDuration)`
+ * - **After login (dynamic duration)**: `sessionService.startSession(backendDuration)`
+ *
+ * **Usage Scenarios:**
+ *
+ * Scenario 1 - Fixed duration:
+ * ```ts
+ * // app.config.ts
+ * providers: [
+ *   provideSession(45 * 60 * 1000) // Override to 45 minutes
+ * ]
+ * ```
+ *
+ * Scenario 2 - Backend-provided duration:
+ * ```ts
+ * // app.config.ts
+ * providers: [
+ *   provideSession() // Uses default 30 minutes initially
+ * ]
+ *
+ * // auth.service.ts (after login)
+ * login().subscribe(response => {
+ *   sessionService.startSession(response.sessionExpiresIn); // Update to backend value
+ * });
+ * ```
+ *
+ * **Related Constants:**
+ * - {@link sessionActivityWindowBeforeEnd} - When to start tracking user activity
+ * - {@link sessionPopupBeforeEnd} - When to show the expiry warning popup
+ *
+ * @default 30 minutes (1800000 milliseconds)
+ */
+const sessionDefaultDuration = 30 * 60 * 1000; // 30 minutes
+
+/**
+ * Time window (in milliseconds) before session expiry when user activity triggers auto-extension.
+ *
+ * During this window, the service tracks user interactions (mouse, keyboard, scroll) and HTTP activity.
+ * If any activity is detected, the session is automatically extended, preventing the expiry warning popup.
+ *
+ * **Session Timeline:**
+ * ```
+ * [Session Start] ──────────────────────────────► [Session Expires]
+ *                                     ▲         ▲
+ *                                     │         └─ sessionPopupBeforeEnd (1 min)
+ *                                     └─ Activity window starts (2 min)
+ *
+ * ┌─────────────────────────────────────────────┐
+ * │ Activity Window (2 minutes)                 │
+ * │ • Tracks: mousemove, keydown, click, scroll │
+ * │ • Tracks: HTTP requests (debounced)         │
+ * │ • If activity detected → auto-extend        │
+ * │ • If no activity → show warning popup       │
+ * └─────────────────────────────────────────────┘
+ * ```
+ *
+ * **Why This Matters:**
+ * - Prevents unnecessary interruptions for active users
+ * - Reduces server-side session renewal traffic by batching extensions
+ * - Provides a grace period before showing the expiry warning
+ *
+ * **Tracked Activities:**
+ * - **User interactions**: `mousemove`, `keydown`, `click`, `scroll` on `window`
+ * - **HTTP traffic**: Any request via `BackendService.httpCommunicationOccurred$` (debounced 500ms)
+ *
+ * **Interaction with Other Constants:**
+ * - Must be **greater than** {@link sessionPopupBeforeEnd} to allow the activity window before the popup
+ * - Typical relationship: `activityWindow > popupWarning` (e.g., 2 min > 1 min)
+ *
+ * **Performance Note:**
+ * Activity tracking is only active during this window, not throughout the entire session,
+ * minimizing performance impact of event listeners.
+ *
+ * @default 2 minutes (120000 milliseconds)
+ * @see {@link SessionService.setupUserActivityTracking} for implementation details
+ */
+const sessionActivityWindowBeforeEnd = 2 * 60 * 1000; // 2 minutes
+
+/**
+ * Time (in milliseconds) before session expiry when the warning popup is displayed.
+ *
+ * When this threshold is reached without detected user activity during the activity window,
+ * a snackbar notification appears, warning the user that their session will expire soon
+ * and providing an "Extend session" action button.
+ *
+ * **Session Timeline:**
+ * ```
+ * [Session Start] ──────────────────────────────► [Session Expires]
+ *                            ▲                 ▲
+ *                            │                 └─ Popup appears (1 min before expiry)
+ *                            └─ Activity window starts (2 min before expiry)
+ *
+ * User has no activity during the 2-minute window:
+ * ├─ 2 min before: Activity tracking starts
+ * ├─ 1 min before: ⚠️ Popup shows "Session expires in one minute"
+ * └─ 0 min: Auto-logout if no action taken
+ * ```
+ *
+ * **Popup Behavior:**
+ * - Displays a warning message: "Session expires in one minute"
+ * - Provides an action button: "Extend session"
+ * - Clicking "Extend session" → extends session by the full session duration
+ * - Ignoring the popup → automatic logout when timer reaches zero
+ * - Only one popup is shown at a time (subsequent extensions dismiss the existing popup)
+ *
+ * **Cross-Tab Synchronization:**
+ * If the user extends the session in one browser tab, all other tabs:
+ * - Automatically dismiss their popups (if shown)
+ * - Reset their timers to the new expiry time
+ * - Avoid showing redundant warnings
+ *
+ * **Interaction with Other Constants:**
+ * - Must be **less than** {@link sessionActivityWindowBeforeEnd}
+ * - Typical relationship: `activityWindow > popupWarning` (e.g., 2 min > 1 min)
+ * - The gap between them determines how long the activity window runs before the popup
+ *
+ * **UX Considerations:**
+ * - **1 minute** gives users enough time to react without being too intrusive
+ * - Too short (e.g., 10 seconds): Users may not have time to respond
+ * - Too long (e.g., 5 minutes): Users may be unnecessarily interrupted if they return
+ *
+ * @default 1 minute (60000 milliseconds)
+ * @see {@link SessionService.showPopup} for popup implementation
+ */
+const sessionPopupBeforeEnd = 60 * 1000; // 1 minute
+
+var ChannelMessage;
+(function (ChannelMessage) {
+    ChannelMessage["SessionExtended"] = "SessionExtended";
+    ChannelMessage["SessionLogout"] = "SessionLogout";
+})(ChannelMessage || (ChannelMessage = {}));
+
 /**
  * Service that creates and manages a visual "halo" border around keyboard-focused elements
  * to enhance navigation visibility and improve accessibility.
@@ -374,89 +511,6 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "19.2.15", ngImpo
                 }]
         }] });
 
-class SnackBarService {
-    #snackBar = inject(MatSnackBar);
-    info(message, action) {
-        return this.snack(message, { action, level: 'info' });
-    }
-    success(message, action) {
-        return this.snack(message, { action, level: 'success' });
-    }
-    warning(message, action) {
-        return this.snack(message, { action, level: 'warning' });
-    }
-    danger(message, action) {
-        return this.snack(message, { action, level: 'danger' });
-    }
-    snack(message, options) {
-        return this.#snackBar.openFromComponent(SnackBarComponent, {
-            data: {
-                level: options.level,
-                message,
-                action: options.action
-            },
-            duration: options.duration || 3000,
-            horizontalPosition: options.horizontalPosition,
-            verticalPosition: options.verticalPosition,
-            panelClass: ['yuv-snack-bar', 'level-' + options.level]
-        });
-    }
-    static { this.ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "19.2.15", ngImport: i0, type: SnackBarService, deps: [], target: i0.ɵɵFactoryTarget.Injectable }); }
-    static { this.ɵprov = i0.ɵɵngDeclareInjectable({ minVersion: "12.0.0", version: "19.2.15", ngImport: i0, type: SnackBarService, providedIn: 'root' }); }
-}
-i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "19.2.15", ngImport: i0, type: SnackBarService, decorators: [{
-            type: Injectable,
-            args: [{
-                    providedIn: 'root'
-                }]
-        }] });
-class SnackBarComponent {
-    constructor() {
-        this.#snackBarRef = inject(MatSnackBarRef);
-        this.#snackData = inject(MAT_SNACK_BAR_DATA);
-        this.level = signal(this.#snackData.level);
-        this.message = signal(this.#snackData.message);
-        this.action = signal(this.#snackData.action);
-    }
-    #snackBarRef;
-    #snackData;
-    dismiss(withAction = false) {
-        if (withAction) {
-            this.#snackBarRef.dismissWithAction();
-        }
-        else if (!this.action()) {
-            this.#snackBarRef.dismiss();
-        }
-    }
-    static { this.ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "19.2.15", ngImport: i0, type: SnackBarComponent, deps: [], target: i0.ɵɵFactoryTarget.Component }); }
-    static { this.ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "17.0.0", version: "19.2.15", type: SnackBarComponent, isStandalone: true, selector: "yuv-snack-bar-component", host: { properties: { "class.info": "level() === 'info'", "class.success": "level() === 'success'", "class.warning": "level() === 'warning'", "class.danger": "level() === 'danger'" } }, ngImport: i0, template: `
-    <span matSnackBarLabel (click)="dismiss()"> {{ message() }} </span>
-    @let a = action();
-    @if (a) {
-      <span matSnackBarActions>
-        <button mat-button matSnackBarAction (click)="dismiss(!!a)">{{ action() }}</button>
-      </span>
-    }
-  `, isInline: true, styles: [":host{display:flex}\n"], dependencies: [{ kind: "ngmodule", type: MatButtonModule }, { kind: "component", type: i1.MatButton, selector: "    button[mat-button], button[mat-raised-button], button[mat-flat-button],    button[mat-stroked-button]  ", exportAs: ["matButton"] }, { kind: "directive", type: MatSnackBarLabel, selector: "[matSnackBarLabel]" }, { kind: "directive", type: MatSnackBarActions, selector: "[matSnackBarActions]" }, { kind: "directive", type: MatSnackBarAction, selector: "[matSnackBarAction]" }] }); }
-}
-i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "19.2.15", ngImport: i0, type: SnackBarComponent, decorators: [{
-            type: Component,
-            args: [{ selector: 'yuv-snack-bar-component', template: `
-    <span matSnackBarLabel (click)="dismiss()"> {{ message() }} </span>
-    @let a = action();
-    @if (a) {
-      <span matSnackBarActions>
-        <button mat-button matSnackBarAction (click)="dismiss(!!a)">{{ action() }}</button>
-      </span>
-    }
-  `, imports: [MatButtonModule, MatSnackBarLabel, MatSnackBarActions, MatSnackBarAction], host: {
-                        '[class.info]': "level() === 'info'",
-                        '[class.success]': "level() === 'success'",
-                        '[class.warning]': "level() === 'warning'",
-                        '[class.danger]': "level() === 'danger'"
-                    }, styles: [":host{display:flex}\n"] }]
-        }] });
-
 /**
  * Utility service providing helper methods for the Halo Focus feature.
  *
@@ -854,6 +908,408 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "19.2.15", ngImpo
             type: Injectable
         }] });
 
+class SnackBarService {
+    #snackBar = inject(MatSnackBar);
+    info(message, action, duration) {
+        return this.snack(message, { action, level: 'info', ...(duration ? { duration } : {}) });
+    }
+    success(message, action, duration) {
+        return this.snack(message, { action, level: 'success', ...(duration ? { duration } : {}) });
+    }
+    warning(message, action, duration) {
+        return this.snack(message, { action, level: 'warning', ...(duration ? { duration } : {}) });
+    }
+    danger(message, action, duration) {
+        return this.snack(message, { action, level: 'danger', ...(duration ? { duration } : {}) });
+    }
+    snack(message, options) {
+        return this.#snackBar.openFromComponent(SnackBarComponent, {
+            data: {
+                level: options.level,
+                message,
+                action: options.action
+            },
+            ...(options.duration ? { duration: options.duration } : {}),
+            horizontalPosition: options.horizontalPosition,
+            verticalPosition: options.verticalPosition,
+            panelClass: ['yuv-snack-bar', 'level-' + options.level]
+        });
+    }
+    static { this.ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "19.2.15", ngImport: i0, type: SnackBarService, deps: [], target: i0.ɵɵFactoryTarget.Injectable }); }
+    static { this.ɵprov = i0.ɵɵngDeclareInjectable({ minVersion: "12.0.0", version: "19.2.15", ngImport: i0, type: SnackBarService, providedIn: 'root' }); }
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "19.2.15", ngImport: i0, type: SnackBarService, decorators: [{
+            type: Injectable,
+            args: [{
+                    providedIn: 'root'
+                }]
+        }] });
+class SnackBarComponent {
+    constructor() {
+        this.#snackBarRef = inject(MatSnackBarRef);
+        this.#snackData = inject(MAT_SNACK_BAR_DATA);
+        this.level = signal(this.#snackData.level);
+        this.message = signal(this.#snackData.message);
+        this.action = signal(this.#snackData.action);
+    }
+    #snackBarRef;
+    #snackData;
+    dismiss(withAction = false) {
+        if (withAction) {
+            this.#snackBarRef.dismissWithAction();
+        }
+        else if (!this.action()) {
+            this.#snackBarRef.dismiss();
+        }
+    }
+    static { this.ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "19.2.15", ngImport: i0, type: SnackBarComponent, deps: [], target: i0.ɵɵFactoryTarget.Component }); }
+    static { this.ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "17.0.0", version: "19.2.15", type: SnackBarComponent, isStandalone: true, selector: "yuv-snack-bar-component", host: { properties: { "class.info": "level() === 'info'", "class.success": "level() === 'success'", "class.warning": "level() === 'warning'", "class.danger": "level() === 'danger'" } }, ngImport: i0, template: `
+    <span matSnackBarLabel (click)="dismiss()"> {{ message() }} </span>
+    @let a = action();
+    @if (a) {
+      <span matSnackBarActions>
+        <button mat-button matSnackBarAction (click)="dismiss(!!a)">{{ action() }}</button>
+      </span>
+    }
+  `, isInline: true, styles: [":host{display:flex}\n"], dependencies: [{ kind: "ngmodule", type: MatButtonModule }, { kind: "component", type: i1.MatButton, selector: "    button[mat-button], button[mat-raised-button], button[mat-flat-button],    button[mat-stroked-button]  ", exportAs: ["matButton"] }, { kind: "directive", type: MatSnackBarLabel, selector: "[matSnackBarLabel]" }, { kind: "directive", type: MatSnackBarActions, selector: "[matSnackBarActions]" }, { kind: "directive", type: MatSnackBarAction, selector: "[matSnackBarAction]" }] }); }
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "19.2.15", ngImport: i0, type: SnackBarComponent, decorators: [{
+            type: Component,
+            args: [{ selector: 'yuv-snack-bar-component', template: `
+    <span matSnackBarLabel (click)="dismiss()"> {{ message() }} </span>
+    @let a = action();
+    @if (a) {
+      <span matSnackBarActions>
+        <button mat-button matSnackBarAction (click)="dismiss(!!a)">{{ action() }}</button>
+      </span>
+    }
+  `, imports: [MatButtonModule, MatSnackBarLabel, MatSnackBarActions, MatSnackBarAction], host: {
+                        '[class.info]': "level() === 'info'",
+                        '[class.success]': "level() === 'success'",
+                        '[class.warning]': "level() === 'warning'",
+                        '[class.danger]': "level() === 'danger'"
+                    }, styles: [":host{display:flex}\n"] }]
+        }] });
+
+/**
+ * Manages client-side session expiry: persists expiration, tracks user and HTTP activity,
+ * shows a pre-expiry popup with an extend CTA, and syncs state across tabs via BroadcastChannel.
+ *
+ * Key behaviors
+ * - Persists `expiresAt` in AppCacheService so multiple tabs share the same deadline
+ * - Automatically listens to BackendService HTTP activity (debounced) to extend sessions
+ * - Extends backend session by calling `/api-web/api/idm/whoami` endpoint (skipped when triggered by HTTP activity)
+ * - User activity (mouse, keyboard, scroll) inside a defined window will auto-extend the session
+ * - Displays a snack popup shortly before expiry; user can extend from the popup
+ * - Broadcasts `SessionExtended` / `SessionLogout` to keep tabs in sync
+ *
+ * Setup options
+ *
+ * Option 1: Known session duration at startup
+ * Use when the session duration is known in advance and remains constant.
+ * ```ts
+ * // app.config.ts
+ * export const appConfig: ApplicationConfig = {
+ *   providers: [
+ *     provideSession(30 * 60 * 1000), // 30 minutes - set at app startup
+ *   ]
+ * };
+ * ```
+ *
+ * Option 2: Dynamic session duration from backend
+ * Use when the session duration is determined after login (e.g., from backend response).
+ * ```ts
+ * // app.config.ts
+ * export const appConfig: ApplicationConfig = {
+ *   providers: [
+ *     provideSession(), // Initialize without duration (defaults to 30 minutes)
+ *   ]
+ * };
+ *
+ * // After login in AuthService:
+ * login().subscribe(response => {
+ *   const sessionDuration = response.sessionExpiresIn; // from backend
+ *   sessionService.startSession(sessionDuration);
+ * });
+ * ```
+ * Note: If no duration is provided to provideSession(), a default of 30 minutes is used until startSession() is called.
+ *
+ * Lifecycle notes
+ * - HTTP activity is automatically tracked via BackendService.httpCommunicationOccurred$
+ * - Backend session is extended via whoami endpoint, except when triggered by HTTP activity or cross-tab sync
+ * - Internal flag prevents recursive whoami calls when the endpoint itself triggers httpCommunicationOccurred$
+ * - Warning and logout timers are reset on every extend
+ * - All timers and the popup are cleared on logout
+ * - Broadcast messages are listened for and mirrored across tabs
+ * - For UI activity, this service listens to DOM events (mousemove, keydown, click, scroll)
+ */
+class SessionService {
+    constructor() {
+        //#region Dependencies
+        /**
+         * AppCacheService is used to persist the session expiry timestamp in localStorage.
+         *
+         * Why persist to storage instead of runtime memory:
+         * - Single source of truth: All browser tabs can read the same expiry value directly
+         *   from storage without inter-tab communication
+         * - Avoids master/slave tab pattern: No need to elect one "master" tab to hold the
+         *   authoritative expiry time and sync it to others
+         * - Survives page refresh: Users don't lose their session when refreshing the page
+         * - Simplifies synchronization: BroadcastChannel is only used for notifications about
+         *   changes (extend/logout), not for maintaining shared state
+         * - Consistent behavior: Every tab independently calculates timers based on the same
+         *   persisted expiry value, ensuring uniform warning/logout timing
+         */
+        this.#appCacheService = inject(AppCacheService);
+        this.#snackBarService = inject(SnackBarService);
+        this.#backendService = inject(BackendService);
+        this.#userService = inject(UserService);
+        this.translate = inject(TranslateService);
+        //#endregion
+        //#region Properties
+        this.#sessionDuration = sessionDefaultDuration;
+        this.#sessionStorageKey = 'session-expires-at';
+        this.#activityWindowBeforeEnd = sessionActivityWindowBeforeEnd;
+        this.#popupBeforeEnd = sessionPopupBeforeEnd;
+        this.#activityDetectedInWindow = false;
+        this.#trackingWindowActivity = false;
+        this.#userActivityTrackingInitialized = false;
+        this.#extendingSessionViaBackend = false;
+        this.#sessionChannel = new BroadcastChannel('session_channel');
+    }
+    //#region Dependencies
+    /**
+     * AppCacheService is used to persist the session expiry timestamp in localStorage.
+     *
+     * Why persist to storage instead of runtime memory:
+     * - Single source of truth: All browser tabs can read the same expiry value directly
+     *   from storage without inter-tab communication
+     * - Avoids master/slave tab pattern: No need to elect one "master" tab to hold the
+     *   authoritative expiry time and sync it to others
+     * - Survives page refresh: Users don't lose their session when refreshing the page
+     * - Simplifies synchronization: BroadcastChannel is only used for notifications about
+     *   changes (extend/logout), not for maintaining shared state
+     * - Consistent behavior: Every tab independently calculates timers based on the same
+     *   persisted expiry value, ensuring uniform warning/logout timing
+     */
+    #appCacheService;
+    #snackBarService;
+    #backendService;
+    #userService;
+    //#endregion
+    //#region Properties
+    #sessionDuration;
+    #sessionStorageKey;
+    #activityWindowBeforeEnd;
+    #popupBeforeEnd;
+    #activityWindowStart$;
+    #activityWindowEnd$;
+    #logoutTimer$;
+    #httpActivitySubscription$;
+    #activityDetectedInWindow;
+    #trackingWindowActivity;
+    #userActivityTrackingInitialized;
+    #extendingSessionViaBackend;
+    #sessionChannel;
+    #snackReference;
+    //#endregion
+    //#region Public methods
+    /**
+     * Initializes cross-tab listeners and activity hooks.
+     *
+     * IMPORTANT: This is automatically called by `provideSession()` via APP_INITIALIZER.
+     * You should NOT call this manually - just add `provideSession()` to your app providers.
+     *
+     * What it does:
+     * - Initializes session with provided or default duration value
+     * - Wires BroadcastChannel subscriptions for cross-tab sync
+     * - Subscribes to BackendService.httpCommunicationOccurred$ for automatic HTTP activity tracking
+     * - Attaches DOM event listeners (mousemove, keydown, click, scroll) for the activity window
+     */
+    init(sessionDuration) {
+        this.startSession(sessionDuration ?? sessionDefaultDuration);
+        this.listenToChannel();
+        this.setupHttpDebounce();
+        this.setupUserActivityTracking();
+    }
+    /**
+     * Sets the session duration and starts the session lifecycle.
+     *
+     * Use this method when you need to set or update the session duration dynamically,
+     * typically after receiving authentication/session information from the backend.
+     *
+     * This is the correct approach when:
+     * - Session duration is not known at application startup
+     * - Duration comes from a backend API response after login
+     * - You need to manually override the duration set via provideSession()
+     *
+     * Example:
+     * ```ts
+     * // After login in AuthService
+     * login().subscribe(response => {
+     *   this.sessionService.startSession(response.sessionExpiresIn);
+     * });
+     * ```
+     *
+     * @param duration Total session length in milliseconds
+     */
+    startSession(duration) {
+        this.#sessionDuration = duration;
+        this.extendSession(false, undefined, true);
+    }
+    /**
+     * Extends the session expiry, resets all timers, and optionally broadcasts to other tabs.
+     *
+     * @param broadcast When true (default), posts a BroadcastChannel message so other tabs sync
+     * @param expiresAt Optional custom expiry timestamp; if not provided, calculates based on session duration
+     * @param skipBackendCall When true, skips the whoami backend call (used when already triggered by HTTP activity)
+     */
+    extendSession(broadcast = true, expiresAt, skipBackendCall = false) {
+        const newExpiresAt = expiresAt ?? Date.now() + this.#sessionDuration;
+        this.setExpiresAt(newExpiresAt);
+        this.resetAllTimers();
+        if (!skipBackendCall && !this.#extendingSessionViaBackend) {
+            this.#extendingSessionViaBackend = true;
+            this.#backendService
+                .get('/idm/whoami')
+                .pipe(finalize(() => {
+                // Keep flag true longer than debounce time to prevent duplicate broadcasts
+                // from httpCommunicationOccurred$ triggered by this whoami call
+                setTimeout(() => {
+                    this.#extendingSessionViaBackend = false;
+                }, 600);
+                if (broadcast) {
+                    this.#sessionChannel.postMessage({
+                        type: ChannelMessage.SessionExtended,
+                        expiresAt: newExpiresAt
+                    });
+                }
+            }))
+                .subscribe();
+        }
+        else if (broadcast) {
+            this.#sessionChannel.postMessage({
+                type: ChannelMessage.SessionExtended,
+                expiresAt: newExpiresAt
+            });
+        }
+    }
+    //#endregion
+    //#region Core Logic
+    listenToChannel() {
+        this.#sessionChannel.onmessage = (event) => {
+            const message = event.data;
+            switch (message.type) {
+                case ChannelMessage.SessionExtended:
+                    this.extendSession(false, message.expiresAt, true);
+                    break;
+                case ChannelMessage.SessionLogout:
+                    this.performLogout(false);
+                    break;
+            }
+        };
+    }
+    scheduleActivityWindow() {
+        this.getExpiresAt().subscribe((expiresAt) => {
+            const activityWindowStartIn = expiresAt - Date.now() - this.#activityWindowBeforeEnd;
+            const activityWindowEndIn = expiresAt - Date.now() - this.#popupBeforeEnd;
+            this.#activityWindowStart$ = timer(Math.max(activityWindowStartIn, 0)).subscribe(() => {
+                this.#trackingWindowActivity = true;
+                this.#activityDetectedInWindow = false;
+            });
+            this.#activityWindowEnd$ = timer(Math.max(activityWindowEndIn, 0)).subscribe(() => {
+                this.#trackingWindowActivity = false;
+                if (this.#activityDetectedInWindow) {
+                    this.extendSession();
+                }
+                else {
+                    this.showPopup();
+                }
+            });
+        });
+    }
+    showPopup() {
+        if (this.#snackReference)
+            return;
+        const message = this.translate.instant('yuv.session.expires.message');
+        const action = this.translate.instant('yuv.session.extend.action');
+        this.#snackReference = this.#snackBarService.warning(message, action);
+        this.scheduleLogout();
+        this.#snackReference.onAction().subscribe(() => {
+            this.#snackReference?.dismiss();
+            this.extendSession();
+        });
+        this.#snackReference.afterDismissed().subscribe(() => {
+            this.#snackReference = undefined;
+        });
+    }
+    scheduleLogout() {
+        this.#logoutTimer$?.unsubscribe();
+        this.#logoutTimer$ = this.getExpiresAt()
+            .pipe(switchMap((expiresAt) => timer(Math.max(expiresAt - Date.now(), 0)).pipe(map(() => expiresAt))))
+            .subscribe((expiresAt) => {
+            if (Date.now() >= expiresAt) {
+                this.performLogout(true);
+            }
+        });
+    }
+    performLogout(broadcast = true) {
+        this.clearTimers();
+        this.#snackReference?.dismiss();
+        if (broadcast) {
+            this.#sessionChannel.postMessage({
+                type: ChannelMessage.SessionLogout
+            });
+        }
+        this.#userService.logout();
+    }
+    //#endregion
+    //#region Activity + HTTP
+    setupHttpDebounce() {
+        this.#httpActivitySubscription$?.unsubscribe();
+        this.#httpActivitySubscription$ = this.#backendService.httpCommunicationOccurred$.pipe(debounceTime(500)).subscribe(() => {
+            if (!this.#extendingSessionViaBackend) {
+                this.extendSession(true, undefined, true);
+            }
+        });
+    }
+    setupUserActivityTracking() {
+        if (this.#userActivityTrackingInitialized)
+            return;
+        ['mousemove', 'keydown', 'click', 'scroll'].forEach((event) => window.addEventListener(event, () => {
+            if (this.#trackingWindowActivity) {
+                this.#activityDetectedInWindow = true;
+            }
+        }));
+        this.#userActivityTrackingInitialized = true;
+    }
+    //#endregion
+    //#region Utilities
+    resetAllTimers() {
+        this.clearTimers();
+        this.scheduleActivityWindow();
+        this.#snackReference?.dismiss();
+    }
+    getExpiresAt() {
+        return this.#appCacheService.getItem(this.#sessionStorageKey);
+    }
+    setExpiresAt(expiresAt) {
+        this.#appCacheService.setItem(this.#sessionStorageKey, expiresAt).subscribe();
+    }
+    clearTimers() {
+        this.#activityWindowStart$?.unsubscribe();
+        this.#activityWindowEnd$?.unsubscribe();
+        this.#logoutTimer$?.unsubscribe();
+        this.#httpActivitySubscription$?.unsubscribe();
+    }
+    static { this.ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "19.2.15", ngImport: i0, type: SessionService, deps: [], target: i0.ɵɵFactoryTarget.Injectable }); }
+    static { this.ɵprov = i0.ɵɵngDeclareInjectable({ minVersion: "12.0.0", version: "19.2.15", ngImport: i0, type: SessionService, providedIn: 'root' }); }
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "19.2.15", ngImport: i0, type: SessionService, decorators: [{
+            type: Injectable,
+            args: [{ providedIn: 'root' }]
+        }] });
+
 /**
  * Provides and initializes the Halo Focus feature for the Angular application.
  *
@@ -924,9 +1380,71 @@ function provideHaloFocus(config) {
     ]);
 }
 
+/**
+ * Provides and initializes the SessionService at application startup.
+ *
+ * What it does
+ * - Registers SessionService as a singleton to manage session expiry across the app
+ * - Runs `session.init()` via APP_INITIALIZER when the app boots
+ * - Initializes cross-tab BroadcastChannel sync, HTTP debounce hooks, and user-activity listeners
+ * - Automatically tracks HTTP activity and user interactions to extend sessions
+ *
+ * Usage scenarios
+ *
+ * Scenario 1: Known session duration at startup
+ * When the session duration is predetermined and constant, provide it here.
+ * ```ts
+ * // app.config.ts
+ * export const appConfig: ApplicationConfig = {
+ *   providers: [
+ *     provideSession(30 * 60 * 1000), // 30 minutes
+ *   ]
+ * };
+ * ```
+ *
+ * Scenario 2: Dynamic session duration from backend
+ * When the session duration is determined after login (e.g., from backend response),
+ * omit the parameter here and call `startSession()` after receiving the duration.
+ * ```ts
+ * // app.config.ts
+ * export const appConfig: ApplicationConfig = {
+ *   providers: [
+ *     provideSession(), // Defaults to 30 minutes until startSession() is called
+ *   ]
+ * };
+ *
+ * // After login in AuthService:
+ * login().subscribe(response => {
+ *   sessionService.startSession(response.sessionExpiresIn); // Set actual duration
+ * });
+ * ```
+ *
+ * @param sessionDuration Optional session duration in milliseconds. If omitted, defaults to 30 minutes (1800000ms).
+ */
+function provideSession(sessionDuration) {
+    return makeEnvironmentProviders([
+        provideAppInitializer(() => {
+            const session = inject(SessionService);
+            session.init(sessionDuration);
+        })
+    ]);
+}
+
+class YuuvisClientFrameworkModule {
+    static { this.ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "19.2.15", ngImport: i0, type: YuuvisClientFrameworkModule, deps: [], target: i0.ɵɵFactoryTarget.NgModule }); }
+    static { this.ɵmod = i0.ɵɵngDeclareNgModule({ minVersion: "14.0.0", version: "19.2.15", ngImport: i0, type: YuuvisClientFrameworkModule, imports: [CommonModule] }); }
+    static { this.ɵinj = i0.ɵɵngDeclareInjector({ minVersion: "12.0.0", version: "19.2.15", ngImport: i0, type: YuuvisClientFrameworkModule, imports: [CommonModule] }); }
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "19.2.15", ngImport: i0, type: YuuvisClientFrameworkModule, decorators: [{
+            type: NgModule,
+            args: [{
+                    imports: [CommonModule],
+                }]
+        }] });
+
 /**
  * Generated bundle index. Do not edit.
  */
 
-export { HaloFocusService, HaloUtilityService, SnackBarComponent, SnackBarService, YuuvisClientFrameworkModule, provideHaloFocus };
+export { ChannelMessage, HaloFocusService, HaloUtilityService, SessionService, SnackBarComponent, SnackBarService, YuuvisClientFrameworkModule, defaultHaloFocusOffset, haloExcludedElementsInMatFormField, haloFocusNavigationKeys, haloFocusStyles, provideHaloFocus, provideSession, sessionActivityWindowBeforeEnd, sessionDefaultDuration, sessionPopupBeforeEnd };
 //# sourceMappingURL=yuuvis-client-framework.mjs.map