@yuuvis/client-framework 2.20.1 → 3.0.0-beta.20.1

package/index.d.ts

@@ -1,6 +1,909 @@
-export * from './lib/config';
-export * from './lib/enums';
-export * from './lib/models';
-export * from './lib/providers';
-export * from './lib/services';
-export * from './lib/yuuvis-client-framework.module';
+import { MatSnackBarHorizontalPosition, MatSnackBarVerticalPosition, MatSnackBarRef } from '@angular/material/snack-bar';
+import * as i0 from '@angular/core';
+import { EnvironmentProviders } from '@angular/core';
+import * as i1 from '@angular/common';
+
+/**
+ * List of element selectors that should be excluded from halo focus
+ * when they are inside a Material form field component (mat-form-field).
+ *
+ * These elements typically have their own built-in focus indicators provided
+ * by Angular Material, making the halo focus redundant or visually conflicting.
+ *
+ * **Included Selectors:**
+ * - `input` - Text inputs, number inputs, etc. inside mat-form-field
+ * - `textarea` - Multi-line text inputs inside mat-form-field
+ * - `mat-select` - Material select dropdowns inside mat-form-field
+ *
+ * **Why Exclude These:**
+ * Angular Material form fields provide their own focus styling with floating labels,
+ * underlines, and color changes. Adding a halo around these elements would:
+ * - Create visual clutter and redundancy
+ * - Potentially conflict with Material's focus styling
+ * - Reduce the clarity of Material Design's established patterns
+ *
+ * **Note:** These elements will still receive halo focus if they appear OUTSIDE
+ * of mat-form-field containers. The exclusion only applies when they're wrapped
+ * in a mat-form-field.
+ *
+ * @see {@link HaloUtilityService.shouldSkipElementInMatFormField} for implementation
+ */
+declare const haloExcludedElementsInMatFormField: string[];
+
+/**
+ * List of keyboard navigation keys that trigger halo position updates.
+ *
+ * When any of these keys are pressed while an element is focused, the halo service
+ * schedules an immediate position update to ensure the halo follows the focused element
+ * if it moves within the page (e.g., scrolling a list, moving through a table).
+ *
+ * **Included Keys:**
+ * - `ArrowLeft`, `ArrowRight`, `ArrowUp`, `ArrowDown` - Directional navigation
+ * - `Home`, `End` - Jump to start/end of content
+ * - `PageUp`, `PageDown` - Page-level scrolling
+ *
+ * **Why This Matters:**
+ * Arrow keys and navigation keys can cause the focused element to scroll or move within
+ * its container (e.g., scrolling a select dropdown, moving focus in a grid). By tracking
+ * these keys, the halo can immediately update its position to follow the element, preventing
+ * visual misalignment.
+ *
+ * **Performance Note:**
+ * Updates are scheduled using requestAnimationFrame, so even rapid key presses won't
+ * cause performance issues.
+ *
+ * @see {@link HaloFocusService} for the implementation of keydown handling
+ */
+declare const haloFocusNavigationKeys: string[];
+
+/**
+ * Default offset (in pixels) between the halo border and the focused element's edges.
+ *
+ * This value determines how far the halo appears from the focused element:
+ * - **Positive value** (default: 3): Halo appears outside the element
+ * - **Zero (0)**: Halo aligns exactly with element edges (neutral offset)
+ * - **Negative value**: Halo appears inside the element (inset)
+ *
+ * **Override Methods:**
+ * - **Per-element**: Use `halo-offset="value"` attribute
+ * - **Per-container**: Use `halo-container-offset="value"` or preset attributes
+ *
+ * @example
+ * ```html
+ * <!-- Uses default 3px offset (outside) -->
+ * <button>Default</button>
+ *
+ * <!-- Custom 5px offset -->
+ * <input halo-offset="5" />
+ *
+ * ```
+ *
+ * @default 3
+ */
+declare const defaultHaloFocusOffset = 3;
+
+/**
+ * Default CSS styles for the halo focus element.
+ *
+ * These styles define the visual appearance and behavior of the halo border that
+ * highlights keyboard-focused elements. The halo is a fixed-position overlay that
+ * follows the focused element across the page.
+ *
+ * **Style Properties:**
+ * - `position: 'fixed'` - Keeps halo in viewport regardless of scroll position
+ * - `pointerEvents: 'none'` - Allows click-through; halo doesn't block interactions
+ * - `zIndex: '9999'` - Ensures halo appears above most other elements
+ * - `border` - Primary border using CSS variable `--ymt-primary` (2px solid)
+ * - `boxShadow` - Soft shadow with 20% opacity for subtle depth effect
+ * - `borderRadius` - Default 8px rounded corners for modern appearance
+ * - `opacity: '0'` - Initially hidden; visibility controlled by service
+ * - `transform: 'translateZ(0)'` - Creates GPU layer for smoother animations
+ *
+ * **CSS Variable Dependencies:**
+ * - `--ymt-primary` - Primary theme color for border and shadow
+ *
+ * **Note:** These are base styles that can be overridden globally via HaloFocusConfig
+ * or per-element using halo-* attributes.
+ *
+ * @see {@link HaloFocusConfig} for global style customization
+ */
+declare const haloFocusStyles: Partial<CSSStyleDeclaration>;
+
+/**
+ * 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)
+ */
+declare const sessionDefaultDuration: number;
+
+/**
+ * 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
+ */
+declare const sessionActivityWindowBeforeEnd: number;
+
+/**
+ * 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
+ */
+declare const sessionPopupBeforeEnd: number;
+
+declare enum ChannelMessage {
+    SessionExtended = "SessionExtended",
+    SessionLogout = "SessionLogout"
+}
+
+/**
+ * Configuration options for the Halo Focus service.
+ *
+ * These settings define the default visual appearance of the focus halo.
+ * Individual elements can override these defaults using halo-* attributes,
+ * and containers can set defaults for their children using halo-container-* attributes.
+ *
+ * @example
+ * const config: HaloFocusConfig = {
+ *   innerColor: '#007bff',
+ *   outerColor: 'rgba(0, 123, 255, 0.25)'
+ * };
+ */
+interface HaloFocusConfig {
+    /**
+     * Inner color for the halo element.
+     *
+     * Accepts any valid CSS color value:
+     * - Named colors: 'blue', 'red'
+     * - Hex: '#007bff', '#f00'
+     * - RGB: 'rgb(0, 123, 255)'
+     * - RGBA: 'rgba(0, 123, 255, 0.5)'
+     * - CSS variables: 'var(--primary-color)'
+     * - Modern CSS: 'rgba(from var(--color) r g b / 0.5)'
+     *
+     * @default 'var(--ymt-primary)'
+     *
+     * @example
+     * innerColor: '#007bff'
+     * innerColor: 'var(--accent-color)'
+     */
+    innerColor?: string;
+    /**
+     * Outer color that appears around the halo element.
+     *
+     * Creates a subtle glow effect around the focused element.
+     * The outer color is 4px wide and surrounds the inner color.
+     *
+     * Accepts any valid CSS color value with alpha transparency recommended.
+     *
+     * @default 'rgba(from var(--ymt-primary) r g b / 0.2)'
+     *
+     * @example
+     * outerColor: 'rgba(0, 123, 255, 0.25)'
+     * outerColor: 'rgba(from var(--accent) r g b / 0.3)'
+     */
+    outerColor?: string;
+}
+
+type ChannelPayload = {
+    type: ChannelMessage;
+    expiresAt?: number;
+};
+
+type SnackBarLevel = 'info' | 'success' | 'warning' | 'danger';
+
+interface SnackBarData {
+    level: SnackBarLevel;
+    message: string;
+    action?: string;
+}
+
+interface SnackBarOptions {
+    duration?: number;
+    horizontalPosition?: MatSnackBarHorizontalPosition;
+    verticalPosition?: MatSnackBarVerticalPosition;
+    action?: string;
+    level?: SnackBarLevel;
+}
+
+/**
+ * Provides and initializes the Halo Focus feature for the Angular application.
+ *
+ * This function sets up a global visual accessibility enhancement that creates a
+ * "halo" border around keyboard-focused elements, making navigation more visible
+ * and improving the user experience for keyboard users.
+ *
+ * **What It Does:**
+ * - Registers HaloFocusService and HaloUtility as application-wide providers
+ * - Automatically initializes the service during app startup via APP_INITIALIZER
+ * - Runs initialization outside Angular zone for optimal performance
+ * - Creates a persistent halo element that tracks focus throughout the application
+ *
+ * **Key Features:**
+ * - Keyboard-only focus indication (respects CSS :focus-visible)
+ * - Performance-optimized with requestAnimationFrame and zone-free execution
+ * - Fully customizable via global config or per-element attributes
+ * - Supports container-level defaults for consistent styling
+ * - Automatic visibility detection and responsive to DOM changes
+ *
+ * **Configuration Options:**
+ * @param config - Optional global configuration object
+ * @param config.innerColor - Inner color of the halo (default: 'var(--ymt-primary)')
+ * @param config.outerColor - Outer color around the halo (default: 'rgba(from var(--ymt-primary) r g b / 0.2)')
+ *
+ * @returns EnvironmentProviders for the Halo Focus feature
+ *
+ * @example
+ * // Basic usage in app.config.ts
+ * export const appConfig: ApplicationConfig = {
+ *   providers: [
+ *     provideHaloFocus()
+ *   ]
+ * };
+ *
+ * @example
+ * // With custom configuration
+ * export const appConfig: ApplicationConfig = {
+ *   providers: [
+ *     provideHaloFocus({
+ *       innerColor: '#007bff',
+ *       outerColor: 'rgba(0, 123, 255, 0.25)'
+ *     })
+ *   ]
+ * };
+ *
+ * @example
+ * // Using element-level attributes in your template
+ * <button halo-color="red">Custom Red Halo</button>
+ * <input halo-offset="5" />
+ * <select halo-skip>No Halo</select>
+ *
+ * @example
+ * // Using container-level attributes
+ * <form halo-container halo-container-color="blue" halo-container-offset="5">
+ *   <input /> <!-- Will use blue color and 5px offset -->
+ *   <button halo-color="red">Submit</button> <!-- Overrides with red -->
+ * </form>
+ */
+declare function provideHaloFocus(config?: HaloFocusConfig): EnvironmentProviders;
+
+/**
+ * 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).
+ */
+declare function provideSession(sessionDuration?: number): EnvironmentProviders;
+
+/**
+ * Service that creates and manages a visual "halo" border around keyboard-focused elements
+ * to enhance navigation visibility and improve accessibility.
+ *
+ * This service operates globally across the application, automatically tracking focus events
+ * and dynamically positioning a halo element around the currently focused element. The halo
+ * responds to window scrolls, resizes, and DOM mutations to maintain accurate positioning.
+ *
+ * **Key Features:**
+ * - Keyboard-only focus indication (respects :focus-visible)
+ * - Performance-optimized with requestAnimationFrame and runs outside Angular zone
+ * - Element-level and container-level customization support
+ * - Automatic visibility detection (handles clipping, hidden elements, etc.)
+ * - Responsive to dynamic DOM changes via ResizeObserver and MutationObserver
+ * - Smart exclusion for Angular Material form fields (prevents redundant styling)
+ *
+ * **Usage:**
+ * 1. Add `provideHaloFocus()` to your providers array in app.config.ts
+ * 2. The service initializes automatically and appends a halo element to the DOM
+ * 3. Optionally customize appearance globally or per-element using attributes
+ *
+ * **Element-Level Attributes:**
+ * - `halo-skip` - Excludes element from halo highlighting
+ * - `halo-color="color"` - Custom halo color (e.g., "blue", "#00ff00", "rgb(255,0,0)")
+ * - `halo-offset="value"` - Custom numeric offset in pixels (default: 3)
+ *
+ * **Container-Level Attributes:**
+ * Define default halo styles for all focused children. Child elements can override
+ * container settings with their own halo-* attributes.
+ *
+ * - `halo-container` - Marks element as a halo container (required for other attributes)
+ * - `halo-container-skip` - Excludes all focused children from halo highlighting
+ * - `halo-container-color="color"` - Default halo color for focused children
+ * - `halo-container-offset="value"` - Default offset for focused children
+ *
+ * **Material Form Field Integration:**
+ * Elements inside Angular Material form fields (mat-form-field) are automatically excluded
+ * from halo focus to prevent visual conflicts with Material's built-in focus styling.
+ * Excluded elements: input, mat-select (configurable via haloExcludedElementsInMatFormField)
+ *
+ * @example
+ * ```html
+ * <!-- Element-level customization -->
+ * <button halo-color="red">Custom Red Halo</button>
+ * <input halo-offset="5" />
+ * <select halo-skip>No Halo</select>
+ *
+ * <!-- Container-level defaults -->
+ * <form halo-container halo-container-color="blue" halo-container-offset="5">
+ *   <input /> <!-- Inherits blue color and 5px offset -->
+ *   <button halo-color="red">Submit</button> <!-- Overrides with red, keeps 5px offset -->
+ * </form>
+ * ```
+ *
+ * **Performance Notes:**
+ * - Service runs outside Angular's zone to prevent unnecessary change detection
+ * - Uses requestAnimationFrame for smooth rendering
+ * - Only shows halo for keyboard interactions (respects :focus-visible)
+ *
+ * @see {@link provideHaloFocus} for initialization and configuration
+ * @see {@link HaloFocusConfig} for global configuration options
+ */
+declare class HaloFocusService {
+    #private;
+    /**
+     * Initializes the Halo Focus service and sets up the global halo tracking system.
+     *
+     * This method performs the following initialization steps:
+     * 1. Applies optional configuration for halo appearance (inner and outer colors)
+     * 2. Creates and appends the halo DIV element to the document body
+     * 3. Attaches global event listeners for focus, blur, keyboard, mouse, scroll, and resize events
+     * 4. Sets up ResizeObserver and MutationObserver for tracking dynamic DOM changes
+     *
+     * **Lifecycle:**
+     * - Called automatically by `provideHaloFocus()` during app initialization
+     * - Runs outside Angular's zone to prevent triggering change detection
+     * - Initializes only once per application lifecycle
+     *
+     * **Performance:**
+     * - Uses passive event listeners where applicable
+     * - Leverages requestAnimationFrame for efficient rendering
+     * - Observers are conditionally created only if browser supports them
+     *
+     * @param config - Optional configuration object for customizing halo appearance
+     * @param config.innerColor - Custom inner color (overrides default primary color)
+     * @param config.outerColor - Custom outer color (overrides default shadow)
+     *
+     * @internal This method should not be called manually; use `provideHaloFocus()` instead
+     */
+    init(config?: HaloFocusConfig): void;
+    static ɵfac: i0.ɵɵFactoryDeclaration<HaloFocusService, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<HaloFocusService>;
+}
+
+/**
+ * Utility service providing helper methods for the Halo Focus feature.
+ *
+ * This service contains pure utility functions for:
+ * - Element validation (focusability, visibility, focus-visible state)
+ * - Material form field detection and exclusion logic
+ * - Style calculations (colors, offsets, positioning)
+ * - DOM traversal (finding halo containers, checking parent visibility)
+ * - Halo element manipulation (size, color, position)
+ *
+ * **Scope & Performance:**
+ * This service is intentionally NOT provided in root (`providedIn: 'root'` is omitted).
+ * Instead, it's provided locally via `provideHaloFocus()`, ensuring it's only instantiated
+ * when the Halo Focus feature is actually used. This optimization prevents unnecessary
+ * service creation in applications that don't use halo focus.
+ *
+ * **Note:** This service is used exclusively by `HaloFocusService` and should not be
+ * injected or used elsewhere in the application.
+ *
+ * @internal
+ */
+declare class HaloUtilityService {
+    /**
+     * Checks if an element is focusable (can receive keyboard focus).
+     *
+     * An element is considered focusable if:
+     * - It has a non-negative tabIndex (>= 0), OR
+     * - It's a natively focusable element (A, BUTTON, INPUT, SELECT, TEXTAREA), OR
+     * - It has contentEditable enabled
+     *
+     * @param element - Element to check
+     * @returns true if element can receive focus, false otherwise
+     */
+    isFocusable(element: Element | null): element is HTMLElement;
+    /**
+     * Checks if an element is inside a Material form field (mat-form-field).
+     *
+     * Traverses up the DOM tree from the element to check if any parent
+     * has the `mat-form-field` tag name. This is used to determine if
+     * certain elements should skip halo focus because they're already
+     * styled by Angular Material.
+     *
+     * **Search Scope:**
+     * - Starts from element itself
+     * - Stops at document.body
+     * - Returns true on first mat-form-field match
+     *
+     * @param element - The element to check
+     * @returns true if element is inside a mat-form-field, false otherwise
+     */
+    isElementInsideMatFormField(element: HTMLElement): boolean;
+    /**
+     * Determines if an element should be excluded from halo focus when inside mat-form-field.
+     *
+     * Checks two conditions:
+     * 1. Element tag name matches one of the excluded selectors (input, mat-select, etc.)
+     * 2. Element is inside a mat-form-field component
+     *
+     * If both conditions are true, the element should skip halo focus because
+     * Angular Material already provides adequate focus styling.
+     *
+     * **Excluded Elements (configurable via haloExcludedElementsInMatFormField):**
+     * - `input` elements inside mat-form-field
+     * - `textarea` elements inside mat-form-field
+     * - `mat-select` elements inside mat-form-field
+     *
+     * **Note:** Elements outside mat-form-field will NOT be skipped, even if
+     * their tag matches the exclusion list.
+     *
+     * @param element - The focused element to check
+     * @returns true if element should be skipped (no halo), false if halo should be shown
+     */
+    shouldSkipElementInMatFormField(element: HTMLElement): boolean;
+    /**
+     * Determines if an element should display the halo based on :focus-visible state.
+     *
+     * This method respects the CSS :focus-visible pseudo-class, which indicates that
+     * focus was triggered by keyboard navigation (not mouse clicks). The halo only appears
+     * when both conditions are met:
+     * 1. Element matches :focus-visible (browser determines this)
+     * 2. Last user interaction was via keyboard (tracked by service)
+     *
+     * **Fallback:** If browser doesn't support :focus-visible, falls back to checking
+     * lastInteractionWasKeyboard only.
+     *
+     * @param element - The currently focused element
+     * @param lastInteractionWasKeyboard - Whether the last interaction was a keyboard event
+     * @returns true if halo should be visible, false otherwise
+     */
+    matchesFocusVisible(element: HTMLElement, lastInteractionWasKeyboard: boolean): boolean;
+    /**
+     * Checks if an element is actually visible on the page.
+     *
+     * Performs comprehensive visibility checks including:
+     * - Element has non-zero dimensions (width and height > 0)
+     * - Element is not hidden via CSS (display: none, visibility: hidden, opacity: 0)
+     * - Element is not clipped by parent containers with overflow: hidden/clip
+     * - All parent elements in the hierarchy are visible
+     *
+     * This prevents the halo from appearing around technically focused but visually
+     * hidden elements (e.g., elements in collapsed sections, off-screen elements).
+     *
+     * @param element - Element to check for visibility
+     * @returns true if element is visible to the user, false otherwise
+     */
+    isElementVisible(element: HTMLElement): boolean;
+    /**
+     * Calculates the visible portion of an element considering overflow clipping from parent containers.
+     *
+     * Traverses up the DOM tree checking for parents with overflow clipping (hidden/clip/auto/scroll).
+     * For each clipping parent, calculates the intersection between the element's current visible area
+     * and the parent's boundaries, progressively clipping the visible rectangle.
+     *
+     * This is essential for showing halo focus only around the visible portion of elements that are
+     * partially scrolled out of view.
+     *
+     * @param element - The element to calculate visible rectangle for
+     * @returns The visible rectangle, or null if element is completely hidden
+     */
+    getVisibleRect(element: HTMLElement): DOMRect | null;
+    /**
+     * Recursively checks if all parent elements are visible and not clipping the target element.
+     *
+     * Traverses up the DOM tree from the element to document.body, checking each parent for:
+     * - Hidden state (display: none, visibility: hidden, opacity: 0)
+     * - Overflow clipping (overflow: hidden/clip) that completely hides the element
+     *
+     * If any parent has overflow clipping, calculates the visible intersection area.
+     * Returns false if element is completely clipped (no visible area).
+     *
+     * @param element - The element whose parents should be checked
+     * @param rect - The bounding rectangle of the element
+     * @returns true if element has visible area within all parent containers, false otherwise
+     */
+    isParentVisible(element: HTMLElement, rect: DOMRect): boolean;
+    /**
+     * Generates the complete CSS styles for the halo element, merging defaults with custom config.
+     *
+     * Takes the base styles from `haloFocusStyles` constant and overrides specific properties
+     * if custom configuration is provided. This allows global style customization while
+     * maintaining all required base styles.
+     *
+     * **Configurable Properties:**
+     * - Inner color (via config.innerColor)
+     * - Outer color (via config.outerColor)
+     *
+     * **Non-configurable Properties:**
+     * - position, pointerEvents, zIndex, opacity, transform (always use defaults)
+     *
+     * @param config - Optional global configuration object
+     * @returns Complete CSS style declaration object for the halo element
+     */
+    getHaloFocusStyles(config?: HaloFocusConfig): Partial<CSSStyleDeclaration>;
+    /**
+     * Finds the nearest parent element marked as a halo container.
+     *
+     * Traverses up the DOM tree looking for an element with the `halo-container` attribute.
+     * Container elements can define default halo styles (color, offset) that apply to all
+     * their focused children, unless overridden by child-specific halo-* attributes.
+     *
+     * **Search Scope:**
+     * - Starts from element's immediate parent
+     * - Stops at document.body (does not check body itself)
+     * - Returns first matching ancestor
+     *
+     * @param element - The focused element to search from
+     * @returns The nearest halo container element, or null if none found
+     */
+    getHaloContainer(element: HTMLElement): HTMLElement | null;
+    /**
+     * Converts any CSS color format to rgba with specified alpha transparency.
+     *
+     * Handles multiple color formats:
+     * - **rgba**: Replaces existing alpha value
+     * - **rgb**: Converts to rgba by appending alpha
+     * - **Hex** (#RRGGBB): Converts to rgba format
+     * - **Named colors**: Uses modern CSS `color-mix` function with alpha
+     *
+     * Used internally to create outer colors with reduced opacity from inner colors.
+     *
+     * @param color - CSS color in any valid format (rgba, rgb, hex, named)
+     * @param alpha - Alpha transparency value (0-1)
+     * @returns Color in rgba format with specified alpha
+     */
+    getColorWithAlpha(color: string, alpha: number): string;
+    /**
+     * Calculates the offset (distance) between the halo border and element edges.
+     *
+     * Determines offset using the following priority order:
+     * 1. **Element's own attributes** (highest priority):
+     *    - `halo-offset="value"` - Custom numeric value
+     * 2. **Parent container attributes** (if element has no offset):
+     *    - `halo-container-offset="value"`
+     * 3. **Default offset** (if nothing specified): 3px
+     *
+     * @param element - The focused element to calculate offset for
+     * @returns Offset value in pixels
+     */
+    getTargetOffset(element: HTMLElement | null): number;
+    /**
+     * Applies custom color styling to the halo element based on element or container attributes.
+     *
+     * Color resolution priority:
+     * 1. **Element's own color**: `halo-color="color"` attribute (highest priority)
+     * 2. **Container's color**: `halo-container-color="color"` from nearest halo container
+     * 3. **Default color**: From global config or base styles (if no custom color found)
+     *
+     * When custom color is found:
+     * - Sets inner color (2px solid border) with the custom color
+     * - Sets outer color (shadow) to match, with 20% alpha transparency for subtle depth
+     *
+     * When no custom color:
+     * - Resets to default styles from config or haloFocusStyles constant
+     *
+     * @param element - The focused element (checked for halo-color attribute)
+     * @param haloElement - The halo DIV element to apply styles to
+     * @param config - Optional global config for default colors
+     */
+    setCustomColor(element: HTMLElement, haloElement: HTMLDivElement, config?: HaloFocusConfig): void;
+    /**
+     * Positions and sizes the halo element to surround the focused element.
+     *
+     * Calculates halo dimensions and position based on:
+     * - Element's visible bounding rectangle (considering overflow clipping)
+     * - Calculated offset from getTargetOffset() (custom or default)
+     * - Element's border-radius for matching rounded corners
+     *
+     * **Calculation Details:**
+     * - Uses getVisibleRect to get only the visible portion of the element
+     * - Position: Visible rect's top/left minus offset (for outside positioning)
+     * - Size: Visible rect's width/height plus 2× offset (to extend on all sides)
+     * - Border radius: Inherited from focused element's computed style
+     *
+     * Uses Math.floor for position and Math.ceil for dimensions to prevent
+     * subpixel rendering issues and ensure full element coverage.
+     *
+     * @param currentElement - The currently focused element to surround
+     * @param haloElement - The halo DIV element to position and size
+     */
+    setHaloElementSize(currentElement: HTMLElement, haloElement: HTMLDivElement): void;
+    static ɵfac: i0.ɵɵFactoryDeclaration<HaloUtilityService, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<HaloUtilityService>;
+}
+
+/**
+ * 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)
+ */
+declare class SessionService {
+    #private;
+    private translate;
+    /**
+     * 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?: number): void;
+    /**
+     * 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: number): void;
+    /**
+     * 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?: boolean, expiresAt?: number, skipBackendCall?: boolean): void;
+    private listenToChannel;
+    private scheduleActivityWindow;
+    private showPopup;
+    private scheduleLogout;
+    private performLogout;
+    private setupHttpDebounce;
+    private setupUserActivityTracking;
+    private resetAllTimers;
+    private getExpiresAt;
+    private setExpiresAt;
+    private clearTimers;
+    static ɵfac: i0.ɵɵFactoryDeclaration<SessionService, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<SessionService>;
+}
+
+declare class SnackBarService {
+    #private;
+    info(message: string, action?: string, duration?: number): MatSnackBarRef<SnackBarComponent>;
+    success(message: string, action?: string, duration?: number): MatSnackBarRef<SnackBarComponent>;
+    warning(message: string, action?: string, duration?: number): MatSnackBarRef<SnackBarComponent>;
+    danger(message: string, action?: string, duration?: number): MatSnackBarRef<SnackBarComponent>;
+    snack(message: string, options: SnackBarOptions): MatSnackBarRef<SnackBarComponent>;
+    static ɵfac: i0.ɵɵFactoryDeclaration<SnackBarService, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<SnackBarService>;
+}
+declare class SnackBarComponent {
+    #private;
+    level: i0.WritableSignal<SnackBarLevel>;
+    message: i0.WritableSignal<string>;
+    action: i0.WritableSignal<string | undefined>;
+    dismiss(withAction?: boolean): void;
+    static ɵfac: i0.ɵɵFactoryDeclaration<SnackBarComponent, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<SnackBarComponent, "yuv-snack-bar-component", never, {}, {}, never, never, true, never>;
+}
+
+declare class YuuvisClientFrameworkModule {
+    static ɵfac: i0.ɵɵFactoryDeclaration<YuuvisClientFrameworkModule, never>;
+    static ɵmod: i0.ɵɵNgModuleDeclaration<YuuvisClientFrameworkModule, never, [typeof i1.CommonModule], never>;
+    static ɵinj: i0.ɵɵInjectorDeclaration<YuuvisClientFrameworkModule>;
+}
+
+export { ChannelMessage, HaloFocusService, HaloUtilityService, SessionService, SnackBarComponent, SnackBarService, YuuvisClientFrameworkModule, defaultHaloFocusOffset, haloExcludedElementsInMatFormField, haloFocusNavigationKeys, haloFocusStyles, provideHaloFocus, provideSession, sessionActivityWindowBeforeEnd, sessionDefaultDuration, sessionPopupBeforeEnd };
+export type { ChannelPayload, HaloFocusConfig, SnackBarData, SnackBarLevel, SnackBarOptions };