@reforgium/presentia 1.0.0 → 1.1.0

package/fesm2022/reforgium-presentia.mjs

@@ -1,6 +1,6 @@
 import * as i0 from '@angular/core';
-import { InjectionToken, signal, computed, inject, afterRenderEffect, Injectable, input, TemplateRef, ViewContainerRef, effect, Directive, Pipe, makeEnvironmentProviders, LOCALE_ID, DestroyRef } from '@angular/core';
-import { SELECTED_LANG, SELECTED_THEME, CURRENT_DEVICE, deepEqual } from '@reforgium/internal';
+import { InjectionToken, signal, computed, inject, afterRenderEffect, Injectable, input, TemplateRef, ViewContainerRef, effect, Directive, ElementRef, Renderer2, afterNextRender, Pipe, makeEnvironmentProviders, LOCALE_ID, DestroyRef } from '@angular/core';
+import { TRANSLATION, SELECTED_LANG, SELECTED_THEME, CURRENT_DEVICE, deepEqual } from '@reforgium/internal';
 import { BreakpointObserver } from '@angular/cdk/layout';
 import { fromEvent, debounceTime, startWith, filter as filter$1, map } from 'rxjs';
 import { HttpClient } from '@angular/common/http';
@@ -9,67 +9,100 @@ import { Router, ActivatedRoute, NavigationEnd } from '@angular/router';
 import { filter } from 'rxjs/operators';
 import { takeUntilDestroyed } from '@angular/core/rxjs-interop';
 
+/**
+ * Default breakpoints for device type detection.
+ *
+ * Defines media queries for each device category:
+ * - `mobile` — screens up to 719px wide
+ * - `tablet` — screens from 720px to 1399px wide
+ * - `desktop-s` — small desktop screens from 1400px to 1919px wide
+ * - `desktop` — large desktop screens 1920px and wider
+ *
+ * These breakpoints are used by `AdaptiveService` to determine the current device type.
+ */
 const defaultBreakpoints = {
     'mobile': '(max-width: 719px)',
     'tablet': '(min-width: 720px) and (max-width: 1399px)',
     'desktop-s': '(min-width: 1400px) and (max-width: 1919px)',
     'desktop': '(min-width: 1920px)',
 };
+/**
+ * Injection token for providing custom device breakpoints.
+ *
+ * By default, provides `defaultBreakpoints`, but can be overridden
+ * at any level of the dependency injection tree to customize
+ * the device detection behavior.
+ *
+ * Example of overriding:
+ * ```typescript
+ * {
+ *   provide: DEVICE_BREAKPOINTS,
+ *   useValue: {
+ *     mobile: '(max-width: 599px)',
+ *     tablet: '(min-width: 600px) and (max-width: 1199px)',
+ *     'desktop-s': '(min-width: 1200px) and (max-width: 1799px)',
+ *     desktop: '(min-width: 1800px)'
+ *   }
+ * }
+ * ```
+ *
+ * Used by `AdaptiveService` to observe media query changes.
+ */
 const DEVICE_BREAKPOINTS = new InjectionToken('RE_DEVICE_BREAKPOINTS', {
     providedIn: 'root',
     factory: () => defaultBreakpoints,
 });
 
 /**
- * Сервис `AdaptiveService` отвечает за определение типа устройства, размеров окна и ориентации экрана.
+ * The `AdaptiveService` is responsible for determining the device type, window dimensions, and screen orientation.
  *
- * Используется для построения адаптивных интерфейсов, изменения поведения компонентов и стилей
- * в зависимости от текущего устройства или размера экрана.
+ * Used for building adaptive interfaces, changing component behavior and styles
+ * depending on the current device or screen size.
  *
- * Основные возможности:
- * - Реактивное отслеживание текущего устройства (`desktop`, `tablet`, `mobile`).
- * - Поддержка вычисляемых признаков (`isDesktop`, `isPortrait`).
- * - Автоматическое обновление при изменении размера окна и пересечении брейкпоинтов.
+ * Main features:
+ * - Reactive tracking of the current device (`desktop`, `tablet`, `mobile`).
+ * - Support for computed properties (`isDesktop`, `isPortrait`).
+ * - Automatic updates when the window is resized and breakpoints are crossed.
  *
- * Реализация основана на:
- * - `BreakpointObserver` из Angular CDK — для наблюдения за медиа-запросами.
- * - `signal` и `computed` — для реактивного состояния без зон.
- * - `fromEvent(window, 'resize')` — для обновления размеров окна с дебаунсом.
+ * Implementation is based on:
+ * - `BreakpointObserver` from Angular CDK — for observing media queries.
+ * - `signal` and `computed` — for reactive state without zones.
+ * - `fromEvent(window, 'resize')` — for updating window dimensions with debouncing.
  *
- * Сервис зарегистрирован как `providedIn: 'root'` и доступен во всём приложении.
+ * The service is registered as `providedIn: 'root'` and is available throughout the application.
  */
 class AdaptiveService {
-    /** @internal Сигнал текущего типа устройства. */
+    /** @internal Signal of the current device type. */
     #device = signal('desktop', ...(ngDevMode ? [{ debugName: "#device" }] : []));
-    /** @internal Сигналы текущей ширины и высоты окна. */
+    /** @internal Signals of the current window width and height. */
     #width = signal(0, ...(ngDevMode ? [{ debugName: "#width" }] : []));
     #height = signal(0, ...(ngDevMode ? [{ debugName: "#height" }] : []));
     /**
-     * Текущий тип устройства (reactive signal).
-     * Возможные значения: `'desktop' | 'tablet' | 'mobile'`.
+     * Current device type (reactive signal).
+     * Possible values: `'desktop' | 'tablet' | 'mobile'`.
      *
-     * Обновляется автоматически при изменении ширины экрана
-     * или при пересечении заданных брейкпоинтов (`DEVICE_BREAKPOINTS`).
+     * Updates automatically when screen width changes
+     * or when specified breakpoints are crossed (`DEVICE_BREAKPOINTS`).
      */
     device = this.#device.asReadonly();
     /**
-     * Текущая ширина окна браузера в пикселях.
-     * Обновляется реактивно при событии `resize`.
+     * Current browser window width in pixels.
+     * Updates reactively on `resize` event.
      */
     width = this.#width.asReadonly();
     /**
-     * Текущая высота окна браузера в пикселях.
-     * Обновляется реактивно при событии `resize`.
+     * Current browser window height in pixels.
+     * Updates reactively on `resize` event.
      */
     height = this.#height.asReadonly();
     /**
-     * Вычисляемый сигнал, показывающий, является ли текущее устройство десктопом.
-     * Используется для условного рендера или настройки макета.
+     * Computed signal indicating whether the current device is a desktop.
+     * Used for conditional rendering or layout configuration.
      */
     isDesktop = computed(() => this.#device() === 'desktop', ...(ngDevMode ? [{ debugName: "isDesktop" }] : []));
     /**
-     * Вычисляемый сигнал, определяющий, находится ли экран в портретной ориентации.
-     * Возвращает `true`, если высота окна больше ширины.
+     * Computed signal determining whether the screen is in portrait orientation.
+     * Returns `true` if window height is greater than width.
      */
     isPortrait = computed(() => this.#height() > this.#width(), ...(ngDevMode ? [{ debugName: "isPortrait" }] : []));
     deviceBreakpoints = inject(DEVICE_BREAKPOINTS);
@@ -102,24 +135,24 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.0.3", ngImpor
         }], ctorParameters: () => [] });
 
 /**
- * Структурная директива `*ssIfDevice`.
+ * Structural directive `*ssIfDevice`.
  *
- * Показывает или скрывает элемент в зависимости от текущего устройства,
- * определяемого через `AdaptiveService`.
+ * Shows or hides an element based on the current device type,
+ * as determined by `AdaptiveService`.
  *
- * Пример:
+ * Example:
  * ```html
- * <div *ssIfDevice="'desktop'">Только для десктопа</div>
- * <div *ssIfDevice="['mobile', 'tablet']">Для мобильных и планшетов</div>
- * <div *ssIfDevice="'mobile'; inverse: true">Скрыть на мобильных</div>
+ * <div *ssIfDevice="'desktop'">Desktop only</div>
+ * <div *ssIfDevice="['mobile', 'tablet']">For mobile and tablets</div>
+ * <div *ssIfDevice="'mobile'; inverse: true"> Hide on mobile</div>
  * ```
  *
- * Параметры:
- * - `ssIfDevice` — одно или несколько значений `Devices` (`'desktop' | 'tablet' | 'mobile'`)
- * - `inverse` — инвертирует условие показа
+ * Parameters:
+ * - `ssIfDevice` — one or more `Devices` values (`'desktop' | 'tablet' | 'mobile'`)
+ * - `inverse` — inverts the display condition
  *
- * Работает реактивно: при изменении типа устройства в `AdaptiveService`
- * шаблон автоматически добавляется или удаляется из DOM.
+ * Works reactively: when the device type changes in `AdaptiveService`,
+ * the template is automatically added or removed from the DOM.
  */
 class IfDeviceDirective {
     device = input(undefined, { ...(ngDevMode ? { debugName: "device" } : {}), alias: 'ssIfDevice' });
@@ -162,10 +195,28 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.0.3", ngImpor
                 }]
         }], ctorParameters: () => [], propDecorators: { device: [{ type: i0.Input, args: [{ isSignal: true, alias: "ssIfDevice", required: false }] }], inverse: [{ type: i0.Input, args: [{ isSignal: true, alias: "inverse", required: false }] }] } });
 
-const LANG_CONFIG = new InjectionToken('RE_LANG_CONFIG');
-
 const innerLangVal = Symbol('reInnerLangVal');
 
+/**
+ * Injection token for providing locale configuration to the language module.
+ *
+ * Used to inject `LocaleConfig` into services and components that require
+ * internationalization settings (e.g., locale, date formats, translations).
+ *
+ * Example:
+ * ```typescript
+ * providers: [
+ *   { provide: LANG_CONFIG, useValue: { locale: 'ru', ... } }
+ * ]
+ * ```
+ *
+ * The token can be injected using Angular's DI system:
+ * ```typescript
+ * private config = inject(LANG_CONFIG);
+ * ```
+ */
+const LANG_CONFIG = new InjectionToken('RE_LANG_CONFIG');
+
 /**
  * LangService provides functionality for managing and tracking language settings
  * and translations in the application. It is designed to handle localization needs,
@@ -185,11 +236,11 @@ class LangService {
      * - If private method `#lang` returns 'ru', this property will return 'ru'.
      * - If `#lang` returns another value, the `config.kgValue` property is checked:
      * - If `config.kgValue` is defined, the property will return its value.
-     * - If `config.kgValue` is not defined, the property will return default value 'kg'.
+     * - If `config.kgValue` is not defined, the property will return the default value 'kg'.
      */
     currentLang = computed(() => {
         const lang = this.#lang();
-        return lang === 'ru' ? 'ru' : (this.config.kgValue ?? 'kg');
+        return lang === 'ru' ? 'ru' : (this.config?.kgValue ?? 'kg');
     }, ...(ngDevMode ? [{ debugName: "currentLang" }] : []));
     /**
      * Extracts readonly value from private property `#lang` and assigns it to `innerLangVal`.
@@ -214,12 +265,12 @@ class LangService {
         }
     }
     /**
-     * Gets value based on provided query and optionally applies specified parameters.
+     * Gets value based on a provided query and optionally applies specified parameters.
      *
      * @param {string} query - Query string used to retrieve desired value.
      * @param {LangParams} [params] - Optional parameters to apply to retrieved value.
      * @return {string} Retrieved value after optional parameter application,
-     * or default value if query is not found.
+     * or default value if a query is not found.
      */
     get(query, params) {
         const value = this.getChainedValue(query);
@@ -229,13 +280,13 @@ class LangService {
         return value ?? this.config.defaultValue ?? query;
     }
     /**
-     * Observes changes to specified translation key and dynamically computes its value.
+     * Observes changes to a specified translation key and dynamically computes its value.
      *
      * @param {string} query - Translation key to observe, typically in format "namespace.key".
      * @param {LangParams} [params] - Optional parameters for interpolation or
      * dynamic content replacement in translation value.
      * @return {Signal<string>} Computed value that dynamically updates
-     * with translation matching provided query and parameters.
+     * with translation matching a provided query and parameters.
      */
     observe(query, params) {
         const [ns] = query.split('.');
@@ -248,8 +299,8 @@ class LangService {
      * Loads specified namespace, ensuring its caching and availability for use.
      *
      * @param {string} ns - Namespace name to load.
-     * @return {Promise<void>} Promise that resolves on successful namespace load,
-     * or rejects when error occurs during process.
+     * @return {Promise<void>} Promise that resolves on a successful namespace load,
+     * or rejects when error occurs during a process.
      */
     async loadNamespace(ns) {
         const key = this.makeNamespaceKey(ns);
@@ -318,16 +369,138 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.0.3", ngImpor
         }] });
 
 /**
- * Кастомный Angular-пайп, который преобразует языковой ключ и дополнительные параметры в локализованную строку.
+ * **LangDirective** — directive for automatic localization of attributes and text content.
  *
- * Пайп объявлен как standalone и impure — то есть он может использоваться без подключения модуля
- * и будет пересчитываться при изменении состояния (например, при смене языка).
+ * Replaces localization keys (format `namespace.key`) with translated strings via `LangService`.
+ * Supports `title`, `label`, `placeholder` attributes and text nodes.
  *
- * В своей работе пайп наблюдает и кэширует языковые ключи для повышения производительности,
- * используя LangService для получения переведённых строк в зависимости от текущего языка приложения.
+ * ### Usage
+ * ```html
+ * <!-- Localize all attributes and content -->
+ * <button reLang title="common.save">common.save</button>
  *
- * Трансформация заключается в том, чтобы принять строку-ключ и необязательные параметры,
- * сформировать ключ для кэша и вернуть локализованное значение, соответствующее этому запросу.
+ * <!-- Localize only title -->
+ * <button [reLang]="'only-title'" title="common.cancel">Cancel</button>
+ *
+ * <!-- Localize custom attribute -->
+ * <input reLang [langForAttr]="'aria-label'" aria-label="forms.username" />
+ * ```
+ *
+ * @publicApi
+ */
+class LangDirective {
+    /**
+     * Localization mode: defines which parts of the element will be translated.
+     * @default 'all'
+     */
+    lang = input('all', { ...(ngDevMode ? { debugName: "lang" } : {}), alias: 'reLang' });
+    /**
+     * Name of an additional attribute to localize (besides standard `title`, `label`, `placeholder`).
+     */
+    langForAttr = input(...(ngDevMode ? [undefined, { debugName: "langForAttr" }] : []));
+    el = inject(ElementRef);
+    renderer = inject(Renderer2);
+    service = inject(LangService);
+    constructor() {
+        afterNextRender(() => this.setAttributes());
+    }
+    /**
+     * Applies localization to the element according to `lang` and `langForAttr` settings.
+     * Called automatically after the component renders.
+     */
+    setAttributes() {
+        const native = this.el.nativeElement;
+        const langFor = this.lang() || 'all';
+        const langForAttr = this.langForAttr();
+        if (['all', 'only-title'].includes(langFor) && native.hasAttribute('title')) {
+            this.replaceAttrValue('title');
+        }
+        if (['all', 'only-label'].includes(langFor) && native.hasAttribute('label')) {
+            this.replaceAttrValue('label');
+        }
+        if (['all', 'only-placeholder'].includes(langFor) && native.hasAttribute('placeholder')) {
+            this.replaceAttrValue('placeholder');
+        }
+        if (['all', 'only-content'].includes(langFor)) {
+            this.replaceTextNodeValue();
+        }
+        if (langForAttr) {
+            this.replaceAttrValue(langForAttr);
+        }
+    }
+    /**
+     * Replaces attribute value with a localized string.
+     * If the value doesn't look like a localization key, outputs a warning.
+     *
+     * @param attributeName name of the attribute to replace
+     */
+    replaceAttrValue(attributeName) {
+        const native = this.el.nativeElement;
+        const title = native.getAttribute(attributeName)?.trim() || '';
+        if (!this.looksLikeKey(title)) {
+            console.warn(`Lang: Attribute ${attributeName} is not a lang key`, title);
+            return;
+        }
+        this.getLangValue(title).then((langed) => this.renderer.setAttribute(native, attributeName, langed));
+    }
+    /**
+     * Replaces element's text node with a localized string.
+     * Works only if the element contains no child elements (text only).
+     * If the content doesn't look like a localization key, outputs a warning.
+     */
+    replaceTextNodeValue() {
+        const native = this.el.nativeElement;
+        if (native.children.length > 0) {
+            console.warn('Lang: Element has children, text node replacement is skipped');
+            return;
+        }
+        const textNode = Array.from(native.childNodes).find((n) => n.nodeType === Node.TEXT_NODE);
+        const key = textNode?.nodeValue?.trim() || '';
+        if (!this.looksLikeKey(key)) {
+            console.warn('Lang: Text node is not a lang key', key);
+            return;
+        }
+        this.getLangValue(key).then((langed) => this.renderer.setValue(textNode, langed));
+    }
+    /**
+     * Checks if a string looks like a localization key (contains `.` and no spaces).
+     *
+     * @param value string to check
+     * @returns `true` if the string looks like a localization key
+     */
+    looksLikeKey(value) {
+        return !!value && value.includes('.') && !value.includes(' ');
+    }
+    /**
+     * Asynchronously loads namespace and retrieves localized value by key.
+     *
+     * @param key localization key in format `namespace.path.to.key`
+     * @returns localized string
+     */
+    async getLangValue(key) {
+        const [ns] = key.split('.', 1);
+        await this.service.loadNamespace(ns);
+        return this.service.get(key);
+    }
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.0.3", ngImport: i0, type: LangDirective, deps: [], target: i0.ɵɵFactoryTarget.Directive });
+    static ɵdir = i0.ɵɵngDeclareDirective({ minVersion: "17.1.0", version: "21.0.3", type: LangDirective, isStandalone: true, selector: "[reLang]", inputs: { lang: { classPropertyName: "lang", publicName: "reLang", isSignal: true, isRequired: false, transformFunction: null }, langForAttr: { classPropertyName: "langForAttr", publicName: "langForAttr", isSignal: true, isRequired: false, transformFunction: null } }, ngImport: i0 });
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.0.3", ngImport: i0, type: LangDirective, decorators: [{
+            type: Directive,
+            args: [{ selector: '[reLang]', standalone: true }]
+        }], ctorParameters: () => [], propDecorators: { lang: [{ type: i0.Input, args: [{ isSignal: true, alias: "reLang", required: false }] }], langForAttr: [{ type: i0.Input, args: [{ isSignal: true, alias: "langForAttr", required: false }] }] } });
+
+/**
+ * Custom Angular pipe that transforms a language key and additional parameters into a localized string.
+ *
+ * The pipe is declared as standalone and impure — meaning it can be used without importing a module
+ * and will be recalculated when the state changes (for example, when the language is switched).
+ *
+ * In its operation, the pipe observes and caches language keys to improve performance,
+ * using LangService to retrieve translated strings based on the current application language.
+ *
+ * The transformation involves accepting a key string and optional parameters,
+ * forming a cache key, and returning the localized value corresponding to that request.
  *
  * @implements {PipeTransform}
  */
@@ -349,22 +522,76 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.0.3", ngImpor
             args: [{ name: 'lang', standalone: true, pure: false }]
         }] });
 
+/**
+ * Type-safe mapping of available theme names.
+ *
+ * Provides a constant record that maps theme identifiers to their corresponding string values.
+ * This ensures compile-time safety when referencing theme names throughout the application.
+ *
+ * Available themes:
+ * - `light` - Light theme variant
+ * - `dark` - Dark theme variant
+ *
+ * @example
+ * ```typescript
+ * const currentTheme = themes.light; // 'light'
+ * const isDarkTheme = theme === themes.dark;
+ * ```
+ */
 const themes = {
     light: 'light',
     dark: 'dark',
 };
+/**
+ * CSS class prefix used for dark theme styling.
+ *
+ * This constant defines the prefix applied to HTML elements when the dark theme is active.
+ * It is typically added to the root element or specific components to enable dark theme styles.
+ *
+ * @example
+ * ```typescript
+ * document.body.classList.add(darkThemePrefix); // Applies 're-dark' class
+ * ```
+ */
 const darkThemePrefix = 're-dark';
 
+/**
+ * Default theme configuration object.
+ *
+ * Defines the initial theme settings for the application.
+ * By default, sets the light theme as the active theme.
+ *
+ * This configuration can be overridden when providing `THEME_CONFIG` token
+ * at the module or application level.
+ * ```
+ */
 const defaultThemeConfig = {
     defaultTheme: themes.light,
 };
+/**
+ * Injection token for theme configuration.
+ *
+ * Used to provide custom theme settings via Angular's dependency injection system.
+ * The token expects a value of type `ThemeConfig`.
+ *
+ * Example usage:
+ * ```typescript
+ * // In providers array:
+ * { provide: THEME_CONFIG, useValue: { defaultTheme: themes.dark } }
+ *
+ * // In service or component:
+ * private themeConfig = inject(THEME_CONFIG);
+ * ```
+ *
+ * If not provided, `defaultThemeConfig` will be used as fallback.
+ */
 const THEME_CONFIG = new InjectionToken('RE_THEME_CONFIG');
 
 /**
  * Service for managing application theme.
  *
  * Allows getting the current theme and switching between light and dark.
- * Automatically saves selected theme to `localStorage` and applies CSS class to `<html>` element.
+ * Automatically saves the selected theme to `localStorage` and applies CSS class to `<html>` element.
  *
  * Example:
  * ```ts
@@ -402,8 +629,8 @@ class ThemeService {
     /**
      * Switches theme.
      *
-     * If parameter is not provided — performs toggle between `light` and `dark`.
-     * Also automatically updates `<html>` class and saves selection to `localStorage`.
+     * If a parameter is not provided — performs toggle between `light` and `dark`.
+     * Also, automatically updates `<html>` class and saves selection to `localStorage`.
      *
      * @param theme — explicit theme value (`'light'` or `'dark'`).
      */
@@ -424,8 +651,34 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.0.3", ngImpor
                 }]
         }], ctorParameters: () => [] });
 
+/**
+ * Provides environment-level providers for Presentia application initialization.
+ *
+ * This function configures essential application services:
+ * - Language and localization settings
+ * - Theme configuration
+ * - Adaptive/responsive breakpoints
+ * - Current device detection
+ *
+ * @param {AppConfig} config - Configuration object containing locale, theme, and breakpoints settings.
+ * @returns {EnvironmentProviders} A collection of Angular providers for the application environment.
+ *
+ * @example
+ * ```typescript
+ * export const appConfig: ApplicationConfig = {
+ *   providers: [
+ *     provideReInit({
+ *       locale: { defaultLang: 'en', supportedLangs: ['en', 'ru'] },
+ *       theme: { defaultTheme: 'dark' },
+ *       breakpoints: { mobile: 768, tablet: 1024 }
+ *     })
+ *   ]
+ * };
+ * ```
+ */
 function provideReInit(config) {
     return makeEnvironmentProviders([
+        { provide: TRANSLATION, deps: [LangService], useFactory: (ls) => ls },
         { provide: SELECTED_LANG, deps: [LangService], useFactory: (ls) => ls[innerLangVal] },
         { provide: SELECTED_THEME, deps: [ThemeService], useFactory: (ls) => ls.theme },
         { provide: CURRENT_DEVICE, deps: [AdaptiveService], useFactory: (ls) => ls.device },
@@ -546,11 +799,36 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.0.3", ngImpor
             type: Injectable
         }] });
 
+/**
+ * Service that listens to Angular route changes and automatically updates SEO metadata
+ * (title, description, Open Graph, Twitter cards, JSON-LD, canonical URL, robots meta tag)
+ * based on route data configuration.
+ *
+ * @example
+ * ```typescript
+ * const routes: Routes = [{
+ *   path: 'about',
+ *   component: AboutComponent,
+ *   data: {
+ *     title: 'About Us',
+ *     description: 'Learn more about our company',
+ *     robots: 'index,follow'
+ *   }
+ * }];
+ * ```
+ */
 class SeoRouteListener {
     router = inject(Router);
     seo = inject(SeoService);
     ar = inject(ActivatedRoute);
     destroyRef = inject(DestroyRef);
+    /**
+     * Initializes the route listener to monitor navigation events and update SEO metadata.
+     * Subscribes to router NavigationEnd events and automatically unsubscribes on component destruction.
+     *
+     * @param baseUrl - The base URL of the application used for constructing canonical URLs.
+     *                  Trailing slashes will be removed automatically.
+     */
     init(baseUrl) {
         const sub = this.router.events.pipe(filter((e) => e instanceof NavigationEnd)).subscribe(() => {
             const route = this.deepest(this.ar);
@@ -571,6 +849,13 @@ class SeoRouteListener {
         });
         this.destroyRef.onDestroy(() => sub.unsubscribe());
     }
+    /**
+     * Recursively finds the deepest (most nested) activated route in the route tree.
+     * This is used to extract route data from the currently active leaf route.
+     *
+     * @param r - The root activated route to start traversing from.
+     * @returns The deepest child route in the hierarchy.
+     */
     deepest(r) {
         let cur = r;
         while (cur.firstChild) {
@@ -667,5 +952,5 @@ function joinUrl(segments) {
  * Generated bundle index. Do not edit.
  */
 
-export { AdaptiveService, DEVICE_BREAKPOINTS, IfDeviceDirective, LANG_CONFIG, LangPipe, LangService, RouteWatcher, SeoRouteListener, SeoService, THEME_CONFIG, ThemeService, darkThemePrefix, defaultBreakpoints, defaultThemeConfig, provideReInit, themes };
+export { AdaptiveService, DEVICE_BREAKPOINTS, IfDeviceDirective, LANG_CONFIG, LangDirective, LangPipe, LangService, RouteWatcher, SeoRouteListener, SeoService, THEME_CONFIG, ThemeService, darkThemePrefix, defaultBreakpoints, defaultThemeConfig, innerLangVal, provideReInit, themes };
 //# sourceMappingURL=reforgium-presentia.mjs.map