@yuuvis/client-framework 2.6.3 → 2.8.0

package/fesm2022/yuuvis-client-framework.mjs

@@ -1,5 +1,5 @@
 import * as i0 from '@angular/core';
-import { NgModule, Injectable, inject, signal, Component, provideAppInitializer, NgZone } from '@angular/core';
+import { NgModule, inject, Injectable, signal, Component, makeEnvironmentProviders, provideAppInitializer, NgZone } from '@angular/core';
 import { CommonModule } from '@angular/common';
 import { MatSnackBar, MatSnackBarRef, MAT_SNACK_BAR_DATA, MatSnackBarLabel, MatSnackBarActions, MatSnackBarAction } from '@angular/material/snack-bar';
 import * as i1 from '@angular/material/button';
@@ -18,60 +18,234 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "19.2.15", ngImpo
         }] });
 
 /**
- * The purpose of this service is to create and manage a "halo focus" element that visually
- * highlights the currently focused element on the page, enhancing keyboard navigation visibility.
- * It listens for focus and blur events, and when an element receives focus, it positions
- * and styles the halo element around it. The halo updates its position and size in response
- * to window scrolls, resizes, and changes to the focused element itself.
+ * List of element selectors that should be excluded from halo focus
+ * when they are inside a Material form field component (mat-form-field).
  *
- * This service is initialized once and operates globally, ensuring that any focusable
- * element on the page can be highlighted when focused.
+ * These elements typically have their own built-in focus indicators provided
+ * by Angular Material, making the halo focus redundant or visually conflicting.
  *
- * Usage:
- * 1. Add provideHaloFocus() to your providers array in your app.config.ts
- * 2. The service will automatically append a halo element to the DOM and manage its visibility
+ * **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
  *
- *  Note: This service assumes that the application uses focus-visible styles to differentiate
- *  between keyboard and mouse focus. It only shows the halo for elements that match :focus-visible.
+ * **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
+ */
+const haloExcludedElementsInMatFormField = ['input', 'textarea', 'mat-select'];
+
+/**
+ * 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
+ */
+const haloFocusNavigationKeys = ['ArrowLeft', 'ArrowRight', 'ArrowUp', 'ArrowDown', 'Home', 'End', 'PageUp', 'PageDown'];
+
+/**
+ * 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
+ */
+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
+ */
+const haloFocusStyles = {
+    position: 'fixed',
+    pointerEvents: 'none',
+    zIndex: '9999',
+    border: '2px solid var(--ymt-primary)',
+    boxShadow: '0 0 0 4px rgba(from var(--ymt-primary) r g b / 0.2)',
+    borderRadius: '8px',
+    opacity: '0',
+    transform: 'translateZ(0)'
+};
+
+/**
+ * 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
  */
 class HaloFocusService {
-    #haloEl = null;
-    #currentEl = null;
+    //#region  Properties
+    #utility = inject(HaloUtilityService);
+    #config;
+    #haloElement = null;
+    #currentElement = null;
     #lastInteractionWasKeyboard = false;
     #rafId = null; //Request Animation Frame ID
     #resizeObserver;
     #mutationObserver;
-    #defaultPadding = 3;
-    #noPaddingComponents = ['yuv-shell-logo'];
+    //#endregion
+    //#region Init
     /**
-     * Initializes the HaloFocusService by appending the halo element to the DOM
-     * and setting up necessary event listeners and observers.
+     * 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
      *
-     * This method should be called once during the application startup.
+     * **Performance:**
+     * - Uses passive event listeners where applicable
+     * - Leverages requestAnimationFrame for efficient rendering
+     * - Observers are conditionally created only if browser supports them
      *
-     * @returns void
+     * @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() {
+    init(config) {
+        this.#initConfig(config);
         this.#appendHaloElementToDOM();
         this.#initListeners();
         this.#initObservers();
     }
+    #initConfig(config) {
+        this.#config = config;
+    }
     #appendHaloElementToDOM() {
-        this.#haloEl = document.createElement('div');
-        this.#haloEl.id = 'focus-halo';
-        this.#haloEl.setAttribute('aria-hidden', 'true');
-        Object.assign(this.#haloEl.style, {
-            position: 'fixed',
-            pointerEvents: 'none',
-            zIndex: '9999',
-            border: '2px solid var(--ymt-primary)',
-            boxShadow: '0 0 0 4px rgba(from var(--ymt-primary) r g b / 0.2)',
-            borderRadius: '8px',
-            opacity: '0',
-            transform: 'translateZ(0)'
-            // transition: 'opacity 120ms ease, transform 120ms ease, width 120ms ease, height 120ms ease, left 120ms ease, top 120ms ease'
-        });
-        document.body.appendChild(this.#haloEl);
+        this.#haloElement = document.createElement('div');
+        this.#haloElement.id = 'focus-halo';
+        this.#haloElement.setAttribute('aria-hidden', 'true');
+        Object.assign(this.#haloElement.style, this.#utility.getHaloFocusStyles(this.#config));
+        document.body.appendChild(this.#haloElement);
     }
     #initListeners() {
         document.addEventListener('focus', this.#onFocus, true);
@@ -84,132 +258,41 @@ class HaloFocusService {
     #initObservers() {
         if ('ResizeObserver' in window) {
             this.#resizeObserver = new ResizeObserver(() => {
-                if (this.#currentEl)
+                if (this.#currentElement)
                     this.#scheduleUpdate();
             });
         }
         if ('MutationObserver' in window) {
             this.#mutationObserver = new MutationObserver(() => {
-                if (this.#currentEl)
+                if (this.#currentElement)
                     this.#scheduleUpdate();
             });
         }
     }
-    #isFocusable(el) {
-        if (!el)
-            return false;
-        const h = el;
-        if (h.tabIndex >= 0)
-            return true;
-        return /^(A|BUTTON|INPUT|SELECT|TEXTAREA)$/.test(h.tagName) || h.isContentEditable;
-    }
-    #matchesFocusVisible(el) {
-        try {
-            const matches = el.matches(':focus-visible');
-            if (!matches)
-                return false;
-            return matches && this.#lastInteractionWasKeyboard;
-        }
-        catch {
-            return this.#lastInteractionWasKeyboard;
-        }
-    }
-    #isElementVisible(el) {
-        const rect = el.getBoundingClientRect();
-        // Check if element has dimensions
-        if (rect.width === 0 || rect.height === 0) {
-            return false;
-        }
-        // Check computed style on element itself
-        const style = getComputedStyle(el);
-        if (style.visibility === 'hidden' || style.display === 'none' || parseFloat(style.opacity) === 0) {
-            return false;
-        }
-        // Check if element is clipped by overflow:hidden parent OR if any parent is hidden
-        return this.#isParentVisible(el, rect);
-    }
-    #isParentVisible(el, rect) {
-        let parent = el.parentElement;
-        while (parent && parent !== document.body) {
-            const parentStyle = getComputedStyle(parent);
-            // Check if parent is hidden
-            if (parentStyle.display === 'none' || parentStyle.visibility === 'hidden' || parseFloat(parentStyle.opacity) === 0) {
-                return false;
-            }
-            const parentOverflow = parentStyle.overflow + parentStyle.overflowX + parentStyle.overflowY;
-            if (parentOverflow.includes('hidden') || parentOverflow.includes('clip')) {
-                const parentRect = parent.getBoundingClientRect();
-                // Calculate intersection - if there's no visible area, element is hidden
-                const visibleRight = Math.min(rect.right, parentRect.right);
-                const visibleLeft = Math.max(rect.left, parentRect.left);
-                const visibleBottom = Math.min(rect.bottom, parentRect.bottom);
-                const visibleTop = Math.max(rect.top, parentRect.top);
-                const visibleWidth = visibleRight - visibleLeft;
-                const visibleHeight = visibleBottom - visibleTop;
-                // If no intersection or intersection is too small (less than 1px), element is not visible
-                if (visibleWidth <= 0 || visibleHeight <= 0) {
-                    return false;
-                }
-            }
-            parent = parent.parentElement;
-        }
-        return true;
-    }
+    // #endregion
+    //#region Rendering
     #updateHaloRect = () => {
-        if (!this.#currentEl || !this.#haloEl || !document.contains(this.#currentEl)) {
-            this.#haloEl && (this.#haloEl.style.opacity = '0');
-            this.#currentEl = null;
+        if (!this.#currentElement || !this.#haloElement || !document.contains(this.#currentElement)) {
+            this.#haloElement && (this.#haloElement.style.opacity = '0');
+            this.#currentElement = null;
             return;
         }
         // Check if element is actually visible
-        if (!this.#isElementVisible(this.#currentEl)) {
-            this.#haloEl.style.opacity = '0';
+        if (!this.#utility.isElementVisible(this.#currentElement)) {
+            this.#haloElement.style.opacity = '0';
             return;
         }
-        const rect = this.#currentEl.getBoundingClientRect();
-        const padding = this.#getTargetPadding();
-        const left = Math.floor(rect.left - padding);
-        const top = Math.floor(rect.top - padding);
-        const width = Math.ceil(rect.width + padding * 2);
-        const height = Math.ceil(rect.height + padding * 2);
-        const cs = getComputedStyle(this.#currentEl);
-        this.#haloEl.style.left = `${left}px`;
-        this.#haloEl.style.top = `${top}px`;
-        this.#haloEl.style.width = `${width}px`;
-        this.#haloEl.style.height = `${height}px`;
-        this.#haloEl.style.borderRadius = cs.borderRadius || '8px';
-        this.#haloEl.style.opacity = '1';
+        this.#utility.setHaloElementSize(this.#currentElement, this.#haloElement);
+        this.#utility.setCustomColor(this.#currentElement, this.#haloElement, this.#config);
+        this.#haloElement.style.opacity = '1';
     };
-    #getTargetPadding() {
-        const parent = this.#currentEl?.parentElement;
-        if (parent && this.#noPaddingComponents.includes(parent.nodeName.toLowerCase())) {
-            return 0;
-        }
-        return this.#defaultPadding;
-    }
     #scheduleUpdate = () => {
         if (this.#rafId != null)
             cancelAnimationFrame(this.#rafId);
         this.#rafId = requestAnimationFrame(this.#updateHaloRect);
     };
-    #onKeydown = (e) => {
-        this.#lastInteractionWasKeyboard = true;
-        // Track arrow keys and other navigation keys that might move focused element
-        const navigationKeys = ['ArrowLeft', 'ArrowRight', 'ArrowUp', 'ArrowDown', 'Home', 'End', 'PageUp', 'PageDown'];
-        if (this.#currentEl && navigationKeys.includes(e.key)) {
-            this.#scheduleUpdate();
-        }
-    };
-    #onMouseDown = () => {
-        this.#lastInteractionWasKeyboard = false;
-        if (this.#haloEl) {
-            this.#haloEl.style.opacity = '0';
-            this.#currentEl = null;
-            this.#stopTracking();
-        }
-    };
     #startTracking(target) {
-        this.#currentEl = target;
+        this.#currentElement = target;
         this.#scheduleUpdate();
         // Track size changes on target element
         if (this.#resizeObserver) {
@@ -240,22 +323,44 @@ class HaloFocusService {
         if (this.#mutationObserver)
             this.#mutationObserver.disconnect();
     }
+    //#endregion
+    //#region Event handlers
+    #onKeydown = (e) => {
+        this.#lastInteractionWasKeyboard = true;
+        // Track arrow keys and other navigation keys that might move focused element
+        if (this.#currentElement && haloFocusNavigationKeys.includes(e.key)) {
+            this.#scheduleUpdate();
+        }
+    };
+    #onMouseDown = () => {
+        this.#lastInteractionWasKeyboard = false;
+        if (this.#haloElement) {
+            this.#haloElement.style.opacity = '0';
+            this.#currentElement = null;
+            this.#stopTracking();
+        }
+    };
     #onFocus = (e) => {
         const target = e.target;
-        if (!this.#isFocusable(target))
+        if (!this.#utility.isFocusable(target))
             return;
-        if (!this.#matchesFocusVisible(target)) {
-            this.#haloEl && (this.#haloEl.style.opacity = '0');
-            this.#currentEl = null;
+        const container = this.#utility.getHaloContainer(target);
+        // Check all skip conditions
+        if (target.hasAttribute('halo-skip') ||
+            this.#utility.shouldSkipElementInMatFormField(target) ||
+            (container && container.hasAttribute('halo-container-skip')) ||
+            !this.#utility.matchesFocusVisible(target, this.#lastInteractionWasKeyboard)) {
+            this.#haloElement && (this.#haloElement.style.opacity = '0');
+            this.#currentElement = null;
             return;
         }
         this.#stopTracking();
         this.#startTracking(target);
     };
     #onBlur = (e) => {
-        if (e.target === this.#currentEl && this.#haloEl) {
-            this.#haloEl.style.opacity = '0';
-            this.#currentEl = null;
+        if (e.target === this.#currentElement && this.#haloElement) {
+            this.#haloElement.style.opacity = '0';
+            this.#currentElement = null;
             this.#stopTracking();
         }
     };
@@ -353,24 +458,475 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "19.2.15", ngImpo
         }] });
 
 /**
- * Provides and initializes the HaloFocusService.
- * By calling this function in your ApplicationConfig providers,
- * the Halo Focus feature will be activated, allowing users to see a visual focus indicator.
- * The service will be initialized outside Angular zone for optimal performance.
+ * 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
+ */
+class HaloUtilityService {
+    //#region Validations
+    /**
+     * 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) {
+        if (!element)
+            return false;
+        const h = element;
+        if (h.tabIndex >= 0)
+            return true;
+        return /^(A|BUTTON|INPUT|SELECT|TEXTAREA)$/.test(h.tagName) || h.isContentEditable;
+    }
+    /**
+     * 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) {
+        let current = element;
+        while (current && current !== document.body) {
+            if (current.tagName.toLowerCase() === 'mat-form-field') {
+                return true;
+            }
+            current = current.parentElement;
+        }
+        return false;
+    }
+    /**
+     * 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) {
+        const tagName = element.tagName.toLowerCase();
+        const isExcludedElement = haloExcludedElementsInMatFormField.includes(tagName);
+        if (!isExcludedElement) {
+            return false;
+        }
+        return this.isElementInsideMatFormField(element);
+    }
+    /**
+     * 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, lastInteractionWasKeyboard) {
+        try {
+            const matches = element.matches(':focus-visible');
+            if (!matches)
+                return false;
+            return matches && lastInteractionWasKeyboard;
+        }
+        catch {
+            return lastInteractionWasKeyboard;
+        }
+    }
+    /**
+     * 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) {
+        const rect = element.getBoundingClientRect();
+        // Check if element has dimensions
+        if (rect.width === 0 || rect.height === 0) {
+            return false;
+        }
+        // Check computed style on element itself
+        const style = getComputedStyle(element);
+        if (style.visibility === 'hidden' || style.display === 'none' || parseFloat(style.opacity) === 0) {
+            return false;
+        }
+        // Check if element is clipped by overflow:hidden parent OR if any parent is hidden
+        return this.isParentVisible(element, rect);
+    }
+    /**
+     * 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, rect) {
+        let parent = element.parentElement;
+        while (parent && parent !== document.body) {
+            const parentStyle = getComputedStyle(parent);
+            // Check if parent is hidden
+            if (parentStyle.display === 'none' || parentStyle.visibility === 'hidden' || parseFloat(parentStyle.opacity) === 0) {
+                return false;
+            }
+            const parentOverflow = parentStyle.overflow + parentStyle.overflowX + parentStyle.overflowY;
+            if (parentOverflow.includes('hidden') || parentOverflow.includes('clip')) {
+                const parentRect = parent.getBoundingClientRect();
+                // Calculate intersection - if there's no visible area, element is hidden
+                const visibleRight = Math.min(rect.right, parentRect.right);
+                const visibleLeft = Math.max(rect.left, parentRect.left);
+                const visibleBottom = Math.min(rect.bottom, parentRect.bottom);
+                const visibleTop = Math.max(rect.top, parentRect.top);
+                const visibleWidth = visibleRight - visibleLeft;
+                const visibleHeight = visibleBottom - visibleTop;
+                // If no intersection or intersection is too small (less than 1px), element is not visible
+                if (visibleWidth <= 0 || visibleHeight <= 0) {
+                    return false;
+                }
+            }
+            parent = parent.parentElement;
+        }
+        return true;
+    }
+    //#endregion
+    // #region Utilities
+    /**
+     * 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) {
+        return {
+            ...haloFocusStyles,
+            border: config?.innerColor ? `2px solid ${config.innerColor}` : haloFocusStyles.border,
+            boxShadow: config?.outerColor ? `0 0 0 4px ${config.outerColor}` : haloFocusStyles.boxShadow
+        };
+    }
+    /**
+     * 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) {
+        let parent = element.parentElement;
+        while (parent && parent !== document.body) {
+            if (parent.hasAttribute('halo-container')) {
+                return parent;
+            }
+            parent = parent.parentElement;
+        }
+        return 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, alpha) {
+        // If already rgba, try to replace alpha
+        if (color.startsWith('rgba')) {
+            return color.replace(/[\d.]+\)$/, `${alpha})`);
+        }
+        // If rgb, convert to rgba
+        if (color.startsWith('rgb')) {
+            return color.replace('rgb', 'rgba').replace(')', `, ${alpha})`);
+        }
+        // If hex color, convert to rgba
+        if (color.startsWith('#')) {
+            const hex = color.replace('#', '');
+            const r = parseInt(hex.substring(0, 2), 16);
+            const g = parseInt(hex.substring(2, 4), 16);
+            const b = parseInt(hex.substring(4, 6), 16);
+            return `rgba(${r}, ${g}, ${b}, ${alpha})`;
+        }
+        // For named colors or other formats, wrap in rgba with color-mix (modern approach)
+        // Fallback to appending alpha as hex if browser doesn't support color-mix
+        return `rgba(from ${color} r g b / ${alpha})`;
+    }
+    /**
+     * 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) {
+        if (!element)
+            return defaultHaloFocusOffset;
+        // 1. Check element's own attributes first
+        const customOffset = element.getAttribute('halo-offset');
+        if (customOffset !== null) {
+            const parsed = parseFloat(customOffset);
+            if (!isNaN(parsed))
+                return parsed;
+        }
+        // 2. Check container attributes as fallback
+        const container = this.getHaloContainer(element);
+        if (container) {
+            const containerOffset = container.getAttribute('halo-container-offset');
+            if (containerOffset !== null) {
+                const parsed = parseFloat(containerOffset);
+                if (!isNaN(parsed))
+                    return parsed;
+            }
+        }
+        // 3. Default: positive offset (halo outside element)
+        return defaultHaloFocusOffset;
+    }
+    /**
+     * 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, haloElement, config) {
+        // 1. Check element's own color first
+        let customColor = element.getAttribute('halo-color');
+        // 2. If not found, check container color
+        if (!customColor) {
+            const container = this.getHaloContainer(element);
+            if (container) {
+                customColor = container.getAttribute('halo-container-color');
+            }
+        }
+        // Apply color or reset to default
+        if (customColor) {
+            haloElement.style.border = `2px solid ${customColor}`;
+            haloElement.style.boxShadow = `0 0 0 4px ${this.getColorWithAlpha(customColor, 0.2)}`;
+        }
+        else {
+            // Reset to default styles
+            haloElement.style.border = this.getHaloFocusStyles(config).border;
+            haloElement.style.boxShadow = this.getHaloFocusStyles(config).boxShadow;
+        }
+    }
+    /**
+     * Positions and sizes the halo element to surround the focused element.
+     *
+     * Calculates halo dimensions and position based on:
+     * - Element's bounding rectangle (viewport-relative position)
+     * - Calculated offset from getTargetOffset() (custom or default)
+     * - Element's border-radius for matching rounded corners
+     *
+     * **Calculation Details:**
+     * - Position: Element's top/left minus offset (for outside positioning)
+     * - Size: Element'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, haloElement) {
+        const rect = currentElement.getBoundingClientRect();
+        const offset = this.getTargetOffset(currentElement);
+        const left = Math.floor(rect.left - offset);
+        const top = Math.floor(rect.top - offset);
+        const width = Math.ceil(rect.width + offset * 2);
+        const height = Math.ceil(rect.height + offset * 2);
+        const cs = getComputedStyle(currentElement);
+        haloElement.style.left = `${left}px`;
+        haloElement.style.top = `${top}px`;
+        haloElement.style.width = `${width}px`;
+        haloElement.style.height = `${height}px`;
+        haloElement.style.borderRadius = cs.borderRadius || '8px';
+    }
+    static { this.ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "19.2.15", ngImport: i0, type: HaloUtilityService, deps: [], target: i0.ɵɵFactoryTarget.Injectable }); }
+    static { this.ɵprov = i0.ɵɵngDeclareInjectable({ minVersion: "12.0.0", version: "19.2.15", ngImport: i0, type: HaloUtilityService }); }
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "19.2.15", ngImport: i0, type: HaloUtilityService, decorators: [{
+            type: Injectable
+        }] });
+
+/**
+ * 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>
  *
- * @returns EnvironmentProviders
+ * @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>
  */
-function provideHaloFocus() {
-    return provideAppInitializer(() => {
-        const zone = inject(NgZone);
-        const haloFocus = inject(HaloFocusService);
-        zone.runOutsideAngular(() => haloFocus.init());
-    });
+function provideHaloFocus(config) {
+    return makeEnvironmentProviders([
+        HaloUtilityService,
+        provideAppInitializer(() => {
+            const zone = inject(NgZone);
+            const haloFocus = inject(HaloFocusService);
+            zone.runOutsideAngular(() => haloFocus.init(config));
+        })
+    ]);
 }
 
 /**
  * Generated bundle index. Do not edit.
  */
 
-export { HaloFocusService, SnackBarComponent, SnackBarService, YuuvisClientFrameworkModule, provideHaloFocus };
+export { HaloFocusService, HaloUtilityService, SnackBarComponent, SnackBarService, YuuvisClientFrameworkModule, provideHaloFocus };
 //# sourceMappingURL=yuuvis-client-framework.mjs.map