@arsedizioni/ars-utils 21.2.207 → 21.2.208

package/types/arsedizioni-ars-utils-core.d.ts

@@ -1,98 +1,172 @@
 import * as i0 from '@angular/core';
-import { OnInit, OnDestroy, PipeTransform, AfterContentInit, EventEmitter, Signal } from '@angular/core';
+import { PipeTransform, EventEmitter, OnDestroy, Signal } from '@angular/core';
 import { Validator, AbstractControl, ValidationErrors } from '@angular/forms';
-import { SafeHtml } from '@angular/platform-browser';
-import { DateAdapter, MatDateFormats } from '@angular/material/core';
 import { Locale } from 'date-fns';
+import { SafeHtml, SafeResourceUrl } from '@angular/platform-browser';
+import { DateAdapter, MatDateFormats } from '@angular/material/core';
 import { SelectionModel } from '@angular/cdk/collections';
 import { Observable } from 'rxjs';
 
-declare class ValidatorDirective implements Validator {
-    readonly validator: i0.InputSignal<(control: AbstractControl) => ValidationErrors | null>;
+/**
+ * Directive that validates a file size against configurable minimum and maximum bounds.
+ * Bind `[fileSize]` together with `[size]="fileSizeInMb"`, `[maxSizeMb]`, and `[minSizeMb]`.
+ */
+declare class FileSizeValidatorDirective implements Validator {
+    /** Maximum allowed file size in megabytes. Defaults to 5. */
+    readonly maxSizeMb: i0.InputSignal<number>;
+    /** Minimum required file size in megabytes. Defaults to 0. */
+    readonly minSizeMb: i0.InputSignal<number>;
+    /** The actual file size in megabytes to validate against the bounds. */
+    readonly size: i0.InputSignal<number>;
+    /**
+     * Validates that the bound file size falls within the configured min/max range.
+     * Returns `null` when no control value is present.
+     * @param control - The form control to validate.
+     */
     validate(control: AbstractControl): ValidationErrors | null;
-    static ɵfac: i0.ɵɵFactoryDeclaration<ValidatorDirective, never>;
-    static ɵdir: i0.ɵɵDirectiveDeclaration<ValidatorDirective, "[validator]", never, { "validator": { "alias": "validator"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
+    static ɵfac: i0.ɵɵFactoryDeclaration<FileSizeValidatorDirective, never>;
+    static ɵdir: i0.ɵɵDirectiveDeclaration<FileSizeValidatorDirective, "[fileSize]", never, { "maxSizeMb": { "alias": "maxSizeMb"; "required": false; "isSignal": true; }; "minSizeMb": { "alias": "minSizeMb"; "required": false; "isSignal": true; }; "size": { "alias": "size"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
 }
+
+/**
+ * Directive that validates a control using the host object's `isValid()` method
+ * or a boolean expression passed via `[validIf]`.
+ */
 declare class ValidIfDirective implements Validator {
+    /** When `true`, the control is considered valid regardless of the bound value. */
     readonly validIf: i0.InputSignal<boolean>;
+    /**
+     * Validates the control value against a boolean flag or the value's own `isValid()` method.
+     * @param control - The form control to validate.
+     */
     validate(control: AbstractControl): ValidationErrors | null;
     static ɵfac: i0.ɵɵFactoryDeclaration<ValidIfDirective, never>;
     static ɵdir: i0.ɵɵDirectiveDeclaration<ValidIfDirective, "[validIf]", never, { "validIf": { "alias": "validIf"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
 }
+
+/**
+ * Directive that delegates validation to an externally provided validator function.
+ * Bind `[validator]="myFn"` where `myFn` is `(c: AbstractControl) => ValidationErrors | null`.
+ */
+declare class ValidatorDirective implements Validator {
+    /** The custom validator function to apply. */
+    readonly validator: i0.InputSignal<(control: AbstractControl) => ValidationErrors | null>;
+    /**
+     * Invokes the provided validator function against the given control.
+     * Returns `null` (valid) when no function is bound.
+     * @param control - The form control to validate.
+     */
+    validate(control: AbstractControl): ValidationErrors | null;
+    static ɵfac: i0.ɵɵFactoryDeclaration<ValidatorDirective, never>;
+    static ɵdir: i0.ɵɵDirectiveDeclaration<ValidatorDirective, "[validator]", never, { "validator": { "alias": "validator"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
+}
+
+/**
+ * Directive that validates that the host control's value equals the value of another control.
+ * Bind `[equals]="otherControl"`.
+ */
 declare class EqualsValidatorDirective implements Validator {
+    /** The control whose value must match the host control's value. */
     readonly equals: i0.InputSignal<AbstractControl<any, any, any>>;
+    /**
+     * Validates that the host control value equals the bound control's value.
+     * Returns `null` (valid) when no control is bound.
+     * @param control - The form control to validate.
+     */
     validate(control: AbstractControl): ValidationErrors | null;
     static ɵfac: i0.ɵɵFactoryDeclaration<EqualsValidatorDirective, never>;
     static ɵdir: i0.ɵɵDirectiveDeclaration<EqualsValidatorDirective, "[equals]", never, { "equals": { "alias": "equals"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
 }
-declare class NotEqualValidatorDirective implements Validator {
-    readonly notEqual: i0.InputSignal<AbstractControl<any, any, any>>;
-    validate(control: AbstractControl): ValidationErrors | null;
-    static ɵfac: i0.ɵɵFactoryDeclaration<NotEqualValidatorDirective, never>;
-    static ɵdir: i0.ɵɵDirectiveDeclaration<NotEqualValidatorDirective, "[notEqual]", never, { "notEqual": { "alias": "notEqual"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
-}
-declare class EmailsValidatorDirective implements Validator {
-    validate(control: AbstractControl): ValidationErrors | null;
-    static ɵfac: i0.ɵɵFactoryDeclaration<EmailsValidatorDirective, never>;
-    static ɵdir: i0.ɵɵDirectiveDeclaration<EmailsValidatorDirective, "[emails]", never, {}, {}, never, never, true, never>;
-}
+
+/**
+ * Directive that validates a control value as a GUID / UUID string.
+ * Apply `guid` to a text input that expects a valid UUID.
+ */
 declare class GuidValidatorDirective implements Validator {
+    /**
+     * Validates that the control value is a well-formed GUID / UUID.
+     * Returns `null` when the control is empty.
+     * @param control - The form control to validate.
+     */
     validate(control: AbstractControl): ValidationErrors | null;
     static ɵfac: i0.ɵɵFactoryDeclaration<GuidValidatorDirective, never>;
     static ɵdir: i0.ɵɵDirectiveDeclaration<GuidValidatorDirective, "[guid]", never, {}, {}, never, never, true, never>;
 }
-declare class SqlDateValidatorDirective implements Validator {
-    validate(control: AbstractControl): ValidationErrors | null;
-    static ɵfac: i0.ɵɵFactoryDeclaration<SqlDateValidatorDirective, never>;
-    static ɵdir: i0.ɵɵDirectiveDeclaration<SqlDateValidatorDirective, "[sqlDate]", never, {}, {}, never, never, true, never>;
-}
-declare class NotFutureValidatorDirective implements Validator {
+
+/**
+ * Directive that validates a semicolon-separated list of email addresses.
+ * Apply `emails` to a text input containing one or more addresses separated by `;`.
+ */
+declare class EmailsValidatorDirective implements Validator {
+    /**
+     * Validates each address in a semicolon-separated email list.
+     * Returns `null` when the control is empty.
+     * @param control - The form control to validate.
+     */
     validate(control: AbstractControl): ValidationErrors | null;
-    static ɵfac: i0.ɵɵFactoryDeclaration<NotFutureValidatorDirective, never>;
-    static ɵdir: i0.ɵɵDirectiveDeclaration<NotFutureValidatorDirective, "[notFuture]", never, {}, {}, never, never, true, never>;
+    static ɵfac: i0.ɵɵFactoryDeclaration<EmailsValidatorDirective, never>;
+    static ɵdir: i0.ɵɵDirectiveDeclaration<EmailsValidatorDirective, "[emails]", never, {}, {}, never, never, true, never>;
 }
+
+/**
+ * Directive that validates a control value as a well-formed URL.
+ * Apply `url` to a text input that expects a URL.
+ */
 declare class UrlValidatorDirective implements Validator {
+    /**
+     * Validates that the control value is a well-formed URL.
+     * Returns `null` (valid) when the control is empty.
+     * @param control - The form control to validate.
+     */
     validate(control: AbstractControl): ValidationErrors | null;
     static ɵfac: i0.ɵɵFactoryDeclaration<UrlValidatorDirective, never>;
     static ɵdir: i0.ɵɵDirectiveDeclaration<UrlValidatorDirective, "[url]", never, {}, {}, never, never, true, never>;
 }
-declare class FileSizeValidatorDirective implements Validator {
-    readonly maxSizeMb: i0.InputSignal<number>;
-    readonly minSizeMb: i0.InputSignal<number>;
-    readonly size: i0.InputSignal<number>;
-    validate(control: AbstractControl): ValidationErrors | null;
-    static ɵfac: i0.ɵɵFactoryDeclaration<FileSizeValidatorDirective, never>;
-    static ɵdir: i0.ɵɵDirectiveDeclaration<FileSizeValidatorDirective, "[fileSize]", never, { "maxSizeMb": { "alias": "maxSizeMb"; "required": false; "isSignal": true; }; "minSizeMb": { "alias": "minSizeMb"; "required": false; "isSignal": true; }; "size": { "alias": "size"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
-}
-declare class MaxTermsValidatorDirective implements Validator {
-    readonly maxTerms: i0.InputSignal<number>;
-    validate(control: AbstractControl): ValidationErrors | null;
-    static ɵfac: i0.ɵɵFactoryDeclaration<MaxTermsValidatorDirective, never>;
-    static ɵdir: i0.ɵɵDirectiveDeclaration<MaxTermsValidatorDirective, "[maxTerms]", never, { "maxTerms": { "alias": "maxTerms"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
-}
-declare class PasswordValidatorDirective implements Validator {
-    validate(control: AbstractControl): ValidationErrors | null;
-    static ɵfac: i0.ɵɵFactoryDeclaration<PasswordValidatorDirective, never>;
-    static ɵdir: i0.ɵɵDirectiveDeclaration<PasswordValidatorDirective, "[password]", never, {}, {}, never, never, true, never>;
-}
-declare class TimeValidatorDirective implements Validator {
-    readonly slots: i0.InputSignal<string>;
+
+/**
+ * Directive that validates that a control value is not a future date.
+ * Apply `notFuture` to a text input that expects a date on or before today.
+ */
+declare class NotFutureValidatorDirective implements Validator {
     /**
-     * Retrieve hours as a number from a time string (e: 12:00)
-     * @param value : the time string
-     * @returns the hours as a number or -1
+     * Validates that the control value represents a date that is not in the future.
+     * Returns `null` when the control is empty.
+     * @param control - The form control to validate.
      */
-    private getTime;
     validate(control: AbstractControl): ValidationErrors | null;
-    static ɵfac: i0.ɵɵFactoryDeclaration<TimeValidatorDirective, never>;
-    static ɵdir: i0.ɵɵDirectiveDeclaration<TimeValidatorDirective, "[time]", never, { "slots": { "alias": "slots"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
+    static ɵfac: i0.ɵɵFactoryDeclaration<NotFutureValidatorDirective, never>;
+    static ɵdir: i0.ɵɵDirectiveDeclaration<NotFutureValidatorDirective, "[notFuture]", never, {}, {}, never, never, true, never>;
 }
+
+/**
+ * Directive that validates that a string control value is not blank (whitespace-only).
+ * Apply `notEmpty` to a text input where non-blank content is required.
+ */
 declare class NotEmptyValidatorDirective implements Validator {
+    /**
+     * Validates that the control value is a non-blank string.
+     * Returns `null` when the control is empty or not a string.
+     * @param control - The form control to validate.
+     */
     validate(control: AbstractControl): ValidationErrors | null;
     static ɵfac: i0.ɵɵFactoryDeclaration<NotEmptyValidatorDirective, never>;
     static ɵdir: i0.ɵɵDirectiveDeclaration<NotEmptyValidatorDirective, "[notEmpty]", never, {}, {}, never, never, true, never>;
 }
 
+/**
+ * Directive that validates a control value as a sufficiently strong password.
+ * Apply `password` to a password input.
+ */
+declare class PasswordValidatorDirective implements Validator {
+    /**
+     * Validates that the control value meets the minimum password-strength requirements.
+     * @param control - The form control to validate.
+     */
+    validate(control: AbstractControl): ValidationErrors | null;
+    static ɵfac: i0.ɵɵFactoryDeclaration<PasswordValidatorDirective, never>;
+    static ɵdir: i0.ɵɵDirectiveDeclaration<PasswordValidatorDirective, "[password]", never, {}, {}, never, never, true, never>;
+}
+
 interface INode {
     id: string;
     name?: string;
@@ -155,12 +229,12 @@ declare class SystemUtils {
      */
     static arrayToNodes(items: INode[], parent?: INode): INode[];
     /**
-     * Used to copare items during an array of objects sorting
-     * @param key     : the property name to sort for
-     * @param order   : the order 'asc' or 'desc'
-     * @returns       : 0 if equals, 1 if bigger, -1 if lower
+     * Comparator factory for sorting arrays of objects by a given property key.
+     * @param key   - Name of the property to sort by.
+     * @param order - Sort direction: `'asc'` (default) or `'desc'`.
+     * @returns A comparator function that returns `0`, `1`, or `-1`.
      */
-    static arraySortCompare(key: string, order?: string): (a: any, b: any) => number;
+    static arraySortCompare(key: string, order?: string): (a: Record<string, unknown>, b: Record<string, unknown>) => number;
     /**
      * Format weight
      * @param gr    : grams
@@ -202,9 +276,9 @@ declare class SystemUtils {
      */
     static join(items?: string[], sep?: string, max?: number): string | undefined;
     /**
-     * Replace stuff in text html
-     * @param s   : the string to process
-     * @returns   : the replaced string
+     * Wraps bare URLs in the given string with `<a>` anchor tags.
+     * @param s - The plain-text or HTML string to process.
+     * @returns The string with URLs replaced by clickable links, or `''` when `s` is falsy.
      */
     static replaceAsHtml(s?: string): string;
     /**
@@ -268,21 +342,20 @@ declare class SystemUtils {
      */
     static clone<T>(obj: T): T;
     /**
-     * Clone an object using deep cloning
-     * @param obj   : the oblect to clone
-     * @returns     : a new object
+     * Creates a deep clone of an object by recursively copying all own properties.
+     * @param obj  - The source object to clone.
+     * @param dest - Optional pre-allocated destination object; a new instance is created when omitted.
+     * @returns A deep copy of `obj`.
      */
-    static deepClone<T>(obj: any, dest?: T): T;
+    static deepClone<T extends object>(obj: T, dest?: T): T;
     /**
-     * Check if a string is a valid UUID
-     * @param value   : the value to parse
-     * @returns       : true if is a valid UUID
+     * Returns `true` when `value` is a syntactically valid UUID string.
+     * @param value - The string to validate.
      */
     static parseUUID(value?: string): boolean;
     /**
-     * Parse and ensure that UUID is not empty
-     * @param value   : the value to parse
-     * @returns       : true if valid and not empty
+     * Returns `true` when `value` is a valid, non-empty (non-zero) UUID.
+     * @param value - The string to validate.
      */
     static parseUUIDNotEmpty(value?: string): boolean;
     /**
@@ -319,7 +392,7 @@ declare class SystemUtils {
      * @param locale  : the locale to use
      * @returns       : a valid Date object or null
      */
-    static parseDate(value?: string | Date, locale?: any): Date | undefined;
+    static parseDate(value?: string | Date, locale?: Locale): Date | undefined;
     /**
      * Format a date
      * @param value     : the date or string to format
@@ -327,13 +400,13 @@ declare class SystemUtils {
      * @param locale    : the locale to use (default is IT)
      * @returns         : the formatted string
      */
-    static formatDate(value?: Date | string, fmt?: DateFormat | string, locale?: any): string;
+    static formatDate(value?: Date | string, fmt?: DateFormat | string, locale?: Locale): string | undefined;
     /**
      * Return an italian local date
      * @param value  : the date
      * @returns     : the new date
      */
-    static toLocalDate(value?: Date | string): Date;
+    static toLocalDate(value?: Date | string): Date | undefined;
     /**
      * Update a DateInterval object according to a string
      * @param value       : string value
@@ -343,40 +416,40 @@ declare class SystemUtils {
      */
     static changeDateInterval(value: string, interval: DateInterval, end?: boolean, copy?: boolean): void;
     /**
-     * Format number
-     * @param value : the number to format
-     * @param decimals : the number of decimal places
-     * @param locale : the locale to use for formatting
-     * @returns : the formatted number as a string
+     * Formats a number using `Intl.NumberFormat`.
+     * @param value    - The number to format.
+     * @param decimals - Maximum decimal places (default: `2`).
+     * @param locale   - BCP 47 locale tag (default: `'it-IT'`).
+     * @returns The formatted number string.
      */
     static formatNumber(value: number, decimals?: number, locale?: string): string;
     /**
-     * Format currency
-     * @param value : the number to format
-     * @param currency : the currency code (e.g., 'EUR', 'USD')
-     * @param decimals : the number of decimal places
-     * @param locale : the locale to use for formatting
-     * @returns : the formatted currency as a string
+     * Formats a number as a currency string using `Intl.NumberFormat`.
+     * @param value    - The number to format.
+     * @param currency - ISO 4217 currency code (default: `'EUR'`).
+     * @param decimals - Maximum decimal places (default: `2`).
+     * @param locale   - BCP 47 locale tag (default: `'it-IT'`).
+     * @returns The formatted currency string.
      */
     static formatCurrency(value: number, currency?: string, decimals?: number, locale?: string): string;
     /**
-     * Encode url
-     * @param value : the value to encode
-     * @returns     : the url encoded string
+     * Percent-encodes a string for safe inclusion in a URL.
+     * @param value - The string to encode.
+     * @returns The encoded string, or `undefined` when `value` is empty.
      */
     static urlEncode(value: string): string | undefined;
     /**
-     * Decode url
-     * @param value : the url to decode
-     * @returns     : the decode url string
+     * Decodes a percent-encoded URL string, treating `+` as a space.
+     * @param value - The encoded string to decode.
+     * @returns The decoded string, or `undefined` when `value` is empty or absent.
      */
     static urlDecode(value?: string): string | undefined;
     /**
-     * Get a querystring parameter value
-     * @param name  : the parameter name
-     * @returns     : the string value
+     * Reads a query string parameter value from the current page URL.
+     * @param name - The parameter name to look up.
+     * @returns The decoded parameter value, or `undefined` when absent or running server-side.
      */
-    static getQueryStringValueByName(name: string): string;
+    static getQueryStringValueByName(name: string): string | undefined;
     /**
      * Generate a password
      * @returns : the password string
@@ -413,10 +486,11 @@ declare class SystemUtils {
      */
     private static _toNodes;
     /**
-   * Return the flags array to be used in selections
-   * @param value : the new value
-   * @param max: the max number of flags
-   */
+     * Returns an array of individual power-of-2 flag values that are set in `value`.
+     * @param value - The bitmask to decompose.
+     * @param max   - Upper-bound exponent: checks flags from `1` up to `1 << max` (default: `30`).
+     * @returns Array of set flag values, or an empty array when `value` is `0`.
+     */
     static getFlags(value: number, max?: number): number[];
     /**
      * Check if a color is light or dark
@@ -583,79 +657,241 @@ interface LoginResult<T> extends ApiResult<boolean> {
     requiresMfa?: boolean;
 }
 
-declare class DateIntervalChangeDirective implements OnInit, OnDestroy {
+/**
+ * Directive that listens to `keyup` events on a date input and debounces changes
+ * into a {@link DateInterval} model, converting shorthand strings (e.g. "d/m") to dates.
+ * Apply `[dateIntervalChange]="interval"` to the host `<input>` element.
+ */
+declare class DateIntervalChangeDirective {
+    /** The date interval model to update when the input value changes. */
     readonly dateIntervalChange: i0.InputSignal<DateInterval>;
+    /** When `true`, the directive updates the interval's end date; otherwise the start date. */
     readonly end: i0.InputSignal<boolean>;
     private readonly subject;
-    private subscription;
-    ngOnInit(): void;
-    ngOnDestroy(): void;
+    private readonly destroyRef;
+    constructor();
+    /**
+     * Handles `keyup` events on the host element.
+     * Prevents default browser behaviour for the space key and forwards the event to the debounce pipeline.
+     * @param e - The keyboard event emitted by the host input.
+     */
     onKeyup(e: KeyboardEvent): void;
     static ɵfac: i0.ɵɵFactoryDeclaration<DateIntervalChangeDirective, never>;
     static ɵdir: i0.ɵɵDirectiveDeclaration<DateIntervalChangeDirective, "[dateIntervalChange]", never, { "dateIntervalChange": { "alias": "dateIntervalChange"; "required": false; "isSignal": true; }; "end": { "alias": "end"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
 }
 
+/**
+ * Directive that validates a control value as a parseable SQL-compatible date string.
+ * Apply `sqlDate` to a text input that expects a date after year 1750.
+ */
+declare class SqlDateValidatorDirective implements Validator {
+    /**
+     * Validates that the control value can be parsed as a date after 1750.
+     * Returns `null` when the control is empty.
+     * @param control - The form control to validate.
+     */
+    validate(control: AbstractControl): ValidationErrors | null;
+    static ɵfac: i0.ɵɵFactoryDeclaration<SqlDateValidatorDirective, never>;
+    static ɵdir: i0.ɵɵDirectiveDeclaration<SqlDateValidatorDirective, "[sqlDate]", never, {}, {}, never, never, true, never>;
+}
+
+/**
+ * Impure pipe that filters an array of searchable items against a text query.
+ *
+ * Each item is matched either via its `searchBag.name` property (when present)
+ * or by converting the item itself to a lowercase string. The optional `metadata`
+ * argument is updated in-place with the total item count and the filtered count,
+ * making it usable in the template alongside `*ngFor`.
+ *
+ * Usage:
+ * ```html
+ * <div *ngFor="let item of items | search:filterText:meta">...</div>
+ * <div>Showing {{ meta.count }} of {{ meta.total }}</div>
+ * ```
+ */
 declare class SearchFilterPipe implements PipeTransform {
-    transform(items?: any[], value?: string, metadata?: SearchFilterMetadata): any;
+    /**
+     * Filters `items` by performing a case-insensitive substring match against `value`.
+     * When `items` or `value` is falsy the original array is returned unfiltered.
+     * @param items    - The source array to filter. May be `undefined`.
+     * @param value    - The search text to match against each item. May be `undefined`.
+     * @param metadata - Optional object that is updated with `total` and `count` after filtering.
+     * @returns The filtered array, the original array when no filter text is given,
+     *          or `undefined` when `items` is `undefined`.
+     */
+    transform(items?: any[], value?: string, metadata?: SearchFilterMetadata): any[] | undefined;
     static ɵfac: i0.ɵɵFactoryDeclaration<SearchFilterPipe, never>;
     static ɵpipe: i0.ɵɵPipeDeclaration<SearchFilterPipe, "search", true>;
 }
 
+/**
+ * Impure pipe that filters an array using a caller-provided predicate function.
+ * Because the pipe is impure it re-evaluates on every change-detection cycle,
+ * which is necessary when the predicate's captured state changes.
+ *
+ * Usage: `*ngFor="let item of items | callback:myFilter"`
+ */
 declare class SearchCallbackPipe implements PipeTransform {
-    transform<T>(items: T[] | undefined, callback: (item: T) => boolean): T[] | undefined;
+    /**
+     * Filters `items` by applying `callback` to each element.
+     * Returns the original array unchanged when either argument is falsy.
+     * @param items    - The source array to filter. May be `undefined`.
+     * @param callback - A predicate function that returns `true` for items to keep.
+     * @returns A new filtered array, the original array when no callback is provided,
+     *          or `undefined` when `items` is `undefined`.
+     */
+    transform<T>(items: T[] | undefined, callback: ((item: T) => boolean) | undefined): T[] | undefined;
     static ɵfac: i0.ɵɵFactoryDeclaration<SearchCallbackPipe, never>;
     static ɵpipe: i0.ɵɵPipeDeclaration<SearchCallbackPipe, "callback", true>;
 }
 
+/**
+ * Pipe that marks an HTML string as trusted so Angular does not escape it when
+ * bound via `[innerHTML]`.
+ *
+ * Usage: `<div [innerHTML]="html | safeHtml"></div>`
+ */
 declare class SafeHtmlPipe implements PipeTransform {
     private readonly sanitizer;
+    /**
+     * Bypasses Angular's HTML sanitization and returns a `SafeHtml` instance.
+     * @param value - The raw HTML string to trust. Treated as an empty string when `undefined`.
+     * @returns A `SafeHtml` value that can be bound to `[innerHTML]` without escaping.
+     */
     transform(value?: string): SafeHtml;
     static ɵfac: i0.ɵɵFactoryDeclaration<SafeHtmlPipe, never>;
     static ɵpipe: i0.ɵɵPipeDeclaration<SafeHtmlPipe, "safeHtml", true>;
 }
 
+/**
+ * Pipe that marks a URL string as a trusted resource URL so Angular does not block it
+ * when bound to attributes such as `[src]` or `[href]` on iframes, objects, or embeds.
+ *
+ * Usage: `<iframe [src]="url | safeUrl"></iframe>`
+ */
 declare class SafeUrlPipe implements PipeTransform {
     private readonly sanitizer;
-    transform(value?: string): SafeHtml;
+    /**
+     * Bypasses Angular's resource-URL sanitization and returns a `SafeResourceUrl` instance.
+     * @param value - The URL string to trust. Treated as an empty string when `undefined`.
+     * @returns A `SafeResourceUrl` that can be bound to resource URL attributes without blocking.
+     */
+    transform(value?: string): SafeResourceUrl;
     static ɵfac: i0.ɵɵFactoryDeclaration<SafeUrlPipe, never>;
     static ɵpipe: i0.ɵɵPipeDeclaration<SafeUrlPipe, "safeUrl", true>;
 }
 
+/**
+ * Pipe that applies a global regex replacement on a string and returns the result
+ * as sanitized HTML. When `regexValue` is `'\n'` and no `replaceValue` is given,
+ * newlines are replaced with `<br>` tags.
+ *
+ * Usage: `{{ text | replace:'\n':'' }}`
+ */
 declare class ReplacePipe implements PipeTransform {
     private readonly sanitizer;
-    transform(value: string | undefined, regexValue: string, replaceValue: string): SafeHtml;
+    /**
+     * Replaces all occurrences of `regexValue` in `value` with `replaceValue`.
+     * Returns `undefined` when `value` is empty or `undefined`.
+     * @param value        - The source string to process.
+     * @param regexValue   - The regex pattern string to match (applied with the global flag).
+     * @param replaceValue - The replacement string. Defaults to `'<br>'` when `regexValue` is `'\n'` and this is falsy.
+     * @returns A `SafeHtml` value with all matches replaced, or `undefined` when the input is empty.
+     */
+    transform(value: string | undefined, regexValue: string, replaceValue: string): SafeHtml | undefined;
     static ɵfac: i0.ɵɵFactoryDeclaration<ReplacePipe, never>;
     static ɵpipe: i0.ɵɵPipeDeclaration<ReplacePipe, "replace", true>;
 }
 
+/**
+ * General-purpose formatting pipe that converts a raw value to a locale-aware string
+ * based on the specified format type.
+ *
+ * Supported types: `'date'` / `'D'`, `'currency'` / `'C'`, `'number'` / `'N'`,
+ * `'number0'` / `'N0'`, `'percentage'` / `'P'`.
+ *
+ * Usage: `{{ value | format:'currency' }}`
+ */
 declare class FormatPipe implements PipeTransform {
+    /**
+     * Formats a value according to the specified type and optional pattern.
+     * Returns `undefined` when the value is `null` or `undefined`, or when the type is unrecognised.
+     * @param value   - The raw value to format.
+     * @param type    - The format type identifier (default: `'date'`).
+     * @param pattern - The date pattern used when `type` is `'date'` (default: `'dd/MM/yyyy'`).
+     * @returns A formatted string, or `undefined` when the value cannot be formatted.
+     */
     transform(value?: unknown, type?: string, pattern?: string): string | undefined;
     static ɵfac: i0.ɵɵFactoryDeclaration<FormatPipe, never>;
     static ɵpipe: i0.ɵɵPipeDeclaration<FormatPipe, "format", true>;
 }
 
+/**
+ * Pipe that converts plain-text newlines (`\r\n`, `\r`, `\n`) to HTML `<br>` tags
+ * and marks the result as trusted HTML so Angular does not escape it.
+ *
+ * Usage: `{{ text | formatHtml }}`
+ */
 declare class FormatHtmlPipe implements PipeTransform {
     private readonly sanitizer;
+    /**
+     * Transforms a plain-text string into sanitized HTML by replacing newline characters
+     * with `<br>` tags.
+     * @param value - The input string to transform. Treated as an empty string when `undefined`.
+     * @returns A `SafeHtml` value that can be rendered with `[innerHTML]`.
+     */
     transform(value?: string): SafeHtml;
     static ɵfac: i0.ɵɵFactoryDeclaration<FormatHtmlPipe, never>;
     static ɵpipe: i0.ɵɵPipeDeclaration<FormatHtmlPipe, "formatHtml", true>;
 }
 
+/**
+ * Directive that copies a string payload to the clipboard when the host element is clicked.
+ * Bind `[copyClipboard]="text"` to provide the content to copy and listen to `(copied)` for confirmation.
+ */
 declare class CopyClipboardDirective {
+    /** The text to copy to the clipboard. Bound via the `copyClipboard` attribute. */
     readonly payload: i0.InputSignal<string>;
+    /** Emits the copied text after a successful copy operation. */
     readonly copied: i0.OutputEmitterRef<string>;
+    /**
+     * Handles click events on the host element and copies the payload to the clipboard.
+     * Emits `copied` with the copied text on success.
+     * @param e - The mouse click event.
+     */
     onClick(e: MouseEvent): void;
     static ɵfac: i0.ɵɵFactoryDeclaration<CopyClipboardDirective, never>;
     static ɵdir: i0.ɵɵDirectiveDeclaration<CopyClipboardDirective, "[copyClipboard]", never, { "payload": { "alias": "copyClipboard"; "required": false; "isSignal": true; }; }, { "copied": "copied"; }, never, never, true, never>;
 }
 
-declare class AutoFocusDirective implements AfterContentInit {
+/**
+ * Directive that moves browser focus to the host element after the first render cycle.
+ * Apply `autoFocus` to any focusable element to set focus automatically on initialisation.
+ */
+declare class AutoFocusDirective {
     private readonly elementRef;
-    ngAfterContentInit(): void;
+    constructor();
     static ɵfac: i0.ɵɵFactoryDeclaration<AutoFocusDirective, never>;
     static ɵdir: i0.ɵɵDirectiveDeclaration<AutoFocusDirective, "[autoFocus]", never, {}, {}, never, never, true, never>;
 }
 
+/**
+ * Directive that validates that a control value does not exceed a maximum word count.
+ * Bind `[maxTerms]="10"` to allow at most 10 whitespace-separated terms.
+ */
+declare class MaxTermsValidatorDirective implements Validator {
+    /** The maximum number of whitespace-separated terms allowed. */
+    readonly maxTerms: i0.InputSignal<number>;
+    /**
+     * Validates that the control value contains no more than the configured number of terms.
+     * Returns `null` when the control is empty.
+     * @param control - The form control to validate.
+     */
+    validate(control: AbstractControl): ValidationErrors | null;
+    static ɵfac: i0.ɵɵFactoryDeclaration<MaxTermsValidatorDirective, never>;
+    static ɵdir: i0.ɵɵDirectiveDeclaration<MaxTermsValidatorDirective, "[maxTerms]", never, { "maxTerms": { "alias": "maxTerms"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
+}
+
 declare const Breakpoints: {
     XXSmall: string;
     XSmall: string;
@@ -673,291 +909,378 @@ declare const UtilsMessages: {
     UTILS_DIALOGS_SELECT_OPTIONS_CHANGED: string;
 };
 
+/**
+ * Generic selection model that tracks a set of selected items identified by a lookup field.
+ * Wraps Angular CDK's `SelectionModel` and adds lookup-based add/remove logic.
+ *
+ * @typeParam T - The item type held in the selection.
+ * @typeParam V - The type of the lookup key used to identify items.
+ */
 declare class SelectableModel<T, V> {
+    /**
+     * Emits whenever the selection changes.
+     * Carries the affected item, or `undefined` when the whole selection is cleared.
+     */
     readonly changed: EventEmitter<T>;
-    private _all;
+    private readonly _all;
+    /**
+     * Snapshot of all items currently tracked by this model (selected or previously toggled).
+     * Backed by a signal — reads are always up to date.
+     */
     get all(): T[];
-    private _current;
+    private readonly _current;
+    /** The underlying CDK `SelectionModel` (provides `.selected`, `.isSelected`, etc.). */
     get current(): SelectionModel<T>;
-    private _lookupFieldName;
+    private readonly _lookupFieldName;
+    /** Signal that is `true` when at least one item is selected. */
+    readonly hasValue: i0.Signal<boolean>;
+    /**
+     * @param allowMultiSelect - When `true` (default), multiple items can be selected simultaneously.
+     * @param lookupFieldName  - Name of the property used as the unique key when searching the internal list (default: `'id'`).
+     */
     constructor(allowMultiSelect?: boolean, lookupFieldName?: string);
     /**
-     * Update the view of an item
-     * @param item          : the item to update
-     * @param lookupValue   : the value
+     * Toggles the CDK selection state of an item that already exists in the tracked list.
+     * Has no effect when `lookupValue` does not match any tracked item.
+     * @param item        - The item whose selection state should be toggled.
+     * @param lookupValue - The key value used to locate the item in the internal list.
      */
     updateCurrent(item: T, lookupValue: V): void;
     /**
-     * Select an item
-     * @param item          : the item to update
-     * @param lookupValue   : the value
+     * Toggles an item in both the internal list and the CDK selection.
+     * Adds the item when it is not yet tracked; removes it when it is.
+     * @param item        - The item to toggle.
+     * @param lookupValue - The key value used to locate or register the item.
      */
     toggle(item: T, lookupValue?: V): void;
     /**
-     * Select an item
-     * @param item          : the item to update
-     * @param lookupValue   : the value
+     * Adds an item to the internal list (when not already present) and marks it as selected.
+     * @param item        - The item to select.
+     * @param lookupValue - The key value used to locate or register the item.
      */
     select(item: T, lookupValue?: V): void;
     /**
-     * Deselect an item
-     * @param item          : the item to update
-     * @param lookupValue   : the value
+     * Removes an item from the internal list and deselects it in the CDK model.
+     * Has no effect when the item is not currently tracked.
+     * @param item        - The item to deselect.
+     * @param lookupValue - The key value used to locate the item in the internal list.
      */
     deselect(item: T, lookupValue?: V): void;
     /**
-     * Deselect all specified item lookup values
-     * @param lookupValues : the values
+     * Deselects all items whose lookup key is contained in `lookupValues`.
+     * @param lookupValues - Array of key values identifying the items to deselect.
      */
     deselectByValues(lookupValues: V[]): void;
     /**
-     * Clear current view
-     * @param clearFunc : the function used to clear
+     * Runs `clearFunc` against every currently selected item, then clears the CDK selection.
+     * The internal tracked list is **not** affected; only the CDK selection is cleared.
+     * @param clearFunc - Callback invoked for each currently selected item before clearing.
      */
     clearCurrent(clearFunc: (item: T) => void): void;
     /**
-     * Deselect all items
+     * Clears both the internal tracked list and the CDK selection.
      */
     clear(): void;
     /**
-     * Checks if an item is selected using its lookup value
-     * @param lookupValue : the value
-     * @returns           : true if the value is selected
+     * Returns `true` when the item identified by `lookupValue` is present in the tracked list.
+     * @param lookupValue - The key value to look up.
      */
     isSelected(lookupValue?: V): boolean;
-    /**
-     * Checks if a selection exists
-     * @returns : true if at least one selection exists
-     */
-    hasValue(): boolean;
 }
 
 /**
  * Standard Broadcast Messages Manager
  * https://developer.mozilla.org/en-US/docs/Web/API/BroadcastChannel
  */
-/**
- * The message bag sent as a message
- */
+/** The typed message payload exchanged over the broadcast channel. */
 interface BroadcastChannelMessageBag<T> {
+    /** Unique identifier for the message type. */
     messageId: string;
+    /** Identifier of the sender. */
     sender: string;
+    /** Optional typed data attached to the message. */
     data?: T;
 }
-/**
- * Message subscription params
- */
+/** Subscription descriptor that pairs a message type identifier with its handler. */
 interface BroadcastChannelSubscriberInfo<T> {
+    /** The message type identifier to listen for. */
     messageId: string;
+    /** Callback invoked with the full message bag when a matching message is received. */
     action: (bag: BroadcastChannelMessageBag<T>) => void;
 }
 /**
- * Web Standard Broadcast Messages Manager
- * https://developer.mozilla.org/en-US/docs/Web/API/BroadcastChannel
+ * Wrapper around the native Web `BroadcastChannel` API that adds typed messaging,
+ * multiple named subscriptions, and a graceful disposal mechanism.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/API/BroadcastChannel
  */
 declare class BroadcastChannelManager {
     private channel?;
     private readonly subject;
     private subscriptions;
     /**
-     * Get the current channel registration
+     * The name of the underlying `BroadcastChannel`, or `undefined` when the API
+     * is not supported by the current browser.
      */
     get currentBus(): string | undefined;
+    /**
+     * Opens a `BroadcastChannel` with the given name (when the API is available).
+     * @param bus - The channel name to open (default: `'ARS-CHANNEL'`).
+     */
     constructor(bus?: string);
+    /**
+     * Closes the underlying channel and completes the internal subject after a short delay
+     * to allow any in-flight messages to be delivered.
+     */
     dispose(): void;
     /**
-     * Send a message
-     * @param bag The message, see also {@link BroadcastChannelMessageBag}
-     *
+     * Sends a typed message bag immediately.
+     * @param bag - The message bag to send.
      * @example
-     * channel.sendMessage({ messageId: 'my-broadcast-message', sender: 'the-sender', data: value });
+     * channel.sendMessage({ messageId: 'my-message', sender: 'me', data: value });
      */
     sendMessage<T>(bag: BroadcastChannelMessageBag<T>): void;
     /**
-     * Send a message
-     * @param bag The message, see also {@link BroadcastChannelMessageBag}
-     * @param delay The number of milliseconds to wait before sending the message, see also {@link setTimeout}
-     *
+     * Sends a typed message bag after an optional delay.
+     * @param bag   - The message bag to send.
+     * @param delay - Milliseconds to wait before posting the message.
      * @example
-     * channel.sendMessage({ messageId: 'my-broadcast-message', sender: 'the-sender', data: value }, 250);
+     * channel.sendMessage({ messageId: 'my-message', sender: 'me', data: value }, 250);
      */
     sendMessage<T>(bag: BroadcastChannelMessageBag<T>, delay?: number): void;
     /**
-     * Send a message
-     * @param messageId The message id
-     * @param data The data to send
-     *
+     * Sends a message identified by a string ID with optional data.
+     * @param messageId - The message type identifier.
+     * @param data      - Optional typed payload.
      * @example
-     * channel.sendMessage('my-broadcast-message', value);
+     * channel.sendMessage('my-message', value);
      */
     sendMessage<T>(messageId: string, data?: T): void;
     /**
-     * Send a message
-     * @param messageId The message id
-     * @param data The data to send
-     * @param delay The number of milliseconds to wait before sending the message
-     *
+     * Sends a message identified by a string ID with optional data after an optional delay.
+     * @param messageId - The message type identifier.
+     * @param data      - Optional typed payload.
+     * @param delay     - Milliseconds to wait before posting the message.
      * @example
-     * channel.sendMessage('my-broadcast-message', value, 250);
+     * channel.sendMessage('my-message', value, 250);
      */
     sendMessage<T>(messageId: string, data?: T, delay?: number): void;
     /**
-     * Subscribe to a message
-     * @param args The subscription info, see also {@link BroadcastChannelSubscriberInfo}
+     * Registers a handler for messages with the given `messageId`.
+     * If a handler for the same `messageId` is already registered it is replaced.
+     * @param args - The subscription descriptor containing the message ID and handler.
      */
     subscribe<T>(args: BroadcastChannelSubscriberInfo<T>): void;
     /**
-     * Remove a message subscription
-     * @param messageId The message id
+     * Removes the subscription for the given message ID, if one exists.
+     * @param messageId - The message type identifier whose subscription should be removed.
      */
     unsubscribe(messageId: string): void;
     /**
-     * Remove all the current subscriptions
+     * Removes all registered subscriptions.
      */
     unsubscribeAll(): void;
 }
 
+/** Payload carried by every in-process broadcast message. */
 interface BroadcastMessageInfo {
+    /** Unique identifier for the message type. */
     id: string;
+    /** Optional data attached to the message. */
     data?: any;
 }
+/**
+ * Application-level messaging service that combines two transports:
+ * - An in-process RxJS `Subject` for same-tab communication (`sendMessage` / `getMessage`).
+ * - A native `BroadcastChannel` for cross-tab communication (`sendChannelMessage` / `subscribeChannelMessage`).
+ */
 declare class BroadcastService implements OnDestroy {
     private readonly subject;
     private readonly channel;
     /**
-     * Get a new instance of broadcast channel
+     * Creates a new standalone `BroadcastChannelManager` instance bound to the shared ARS channel.
+     * Useful when a caller needs direct channel access outside the service.
+     * @returns A new `BroadcastChannelManager` connected to `'ARS-CHANNEL'`.
      */
     static GetChannel(): BroadcastChannelManager;
     ngOnDestroy(): void;
     /**
-     * Send a message
-     * @param id    : the message id
-     * @param data  : the data to send
-     * @param delay : the number of milliseconds to wait before sending the message
+     * Publishes a message to the in-process subject, optionally after a delay.
+     * @param id    - The message type identifier.
+     * @param data  - Optional payload to attach to the message.
+     * @param delay - Milliseconds to wait before publishing (default: `0`).
      */
     sendMessage(id: string, data?: any, delay?: number): void;
     /**
-   * Send a channel message
-   * @param id    : the message bag
-   * @param data  : the data bag
-   * @param delay : the number of milliseconds to wait before sending the message
-   */
+     * Publishes a typed message over the native `BroadcastChannel` (cross-tab), optionally after a delay.
+     * @param id    - The message type identifier.
+     * @param data  - Optional typed payload to send.
+     * @param delay - Milliseconds to wait before sending (forwarded to the channel manager).
+     */
     sendChannelMessage<T>(id: string, data?: T, delay?: number): void;
     /**
-     * Subscribe channel message
-     * @param id      : the message id
-     * @param action  : the actionto perform
+     * Registers a handler that is invoked whenever a channel message with the given `id` is received.
+     * @param id     - The message type identifier to listen for.
+     * @param action - Callback invoked with the full `BroadcastChannelMessageBag` when a matching message arrives.
      */
     subscribeChannelMessage<T>(id: string, action: (bag: BroadcastChannelMessageBag<T>) => void): void;
     /**
-     * Get the next message as observable
-     * @returns : the observable object
+     * Returns an `Observable` that emits every in-process message published via `sendMessage`.
+     * @returns An observable stream of `BroadcastMessageInfo` objects.
      */
     getMessage(): Observable<BroadcastMessageInfo>;
     static ɵfac: i0.ɵɵFactoryDeclaration<BroadcastService, never>;
     static ɵprov: i0.ɵɵInjectableDeclaration<BroadcastService>;
 }
 
+/**
+ * Application-wide environment configuration service.
+ * Exposes writable signals for the base URIs used throughout the application.
+ * Values should be set once during application bootstrap (e.g. in `APP_INITIALIZER`).
+ */
 declare class EnvironmentService {
-    private _appUri;
+    /** Writable signal holding the base URI of the frontend application (e.g. `https://app.example.com`). */
+    readonly appUriSignal: i0.WritableSignal<string>;
+    /** Writable signal holding the base URI of the backend API service (e.g. `https://api.example.com`). */
+    readonly appServiceUriSignal: i0.WritableSignal<string>;
+    /**
+     * Writable signal holding the redirect URI used after login.
+     * When empty, `appLoginRedirectUri` falls back to `appUri`.
+     */
+    readonly appLoginRedirectUriSignal: i0.WritableSignal<string>;
+    /**
+     * Writable signal holding the login endpoint URI of the backend service.
+     * When empty, `appServiceLoginUri` falls back to `appServiceUri`.
+     */
+    readonly appServiceLoginUriSignal: i0.WritableSignal<string>;
+    private readonly _effectiveLoginRedirectUri;
+    private readonly _effectiveServiceLoginUri;
+    /** Base URI of the frontend application. */
     get appUri(): string;
+    /** @param value - The base URI of the frontend application. */
     set appUri(value: string);
-    private _appServiceUri;
+    /** Base URI of the backend API service. */
     get appServiceUri(): string;
+    /** @param value - The base URI of the backend API service. */
     set appServiceUri(value: string);
-    private _appLoginRedirectUri;
+    /**
+     * Effective login redirect URI.
+     * Returns the explicitly set value, or falls back to `appUri` when empty.
+     */
     get appLoginRedirectUri(): string;
+    /** @param value - The redirect URI to use after login. */
     set appLoginRedirectUri(value: string);
-    private _appServiceLoginUri;
+    /**
+     * Effective service login URI.
+     * Returns the explicitly set value, or falls back to `appServiceUri` when empty.
+     */
     get appServiceLoginUri(): string;
+    /** @param value - The login endpoint URI of the backend service. */
     set appServiceLoginUri(value: string);
     static ɵfac: i0.ɵɵFactoryDeclaration<EnvironmentService, never>;
     static ɵprov: i0.ɵɵInjectableDeclaration<EnvironmentService>;
 }
 
+/**
+ * Service that exposes reactive screen and device-capability information.
+ */
 declare class ScreenService {
+    /**
+     * Writable signal that holds the current Material breakpoint alias
+     * (e.g. `'xs'`, `'sm'`, `'md'`, `'lg'`, `'xl'`).
+     * Updated externally by the breakpoint observer in the consuming component or module.
+     */
     readonly mq: i0.WritableSignal<string>;
+    /**
+     * Returns `true` when the primary input mechanism can hover over elements
+     * with coarse pointer precision (i.e. a touch screen).
+     */
     get isTouchable(): boolean;
+    /**
+     * Returns `true` when the current browser is Internet Explorer or the legacy Edge (EdgeHTML).
+     * Modern Chromium-based Edge reports a different user-agent and will return `false`.
+     */
     get isIEOrEdge(): boolean;
     static ɵfac: i0.ɵɵFactoryDeclaration<ScreenService, never>;
     static ɵprov: i0.ɵɵInjectableDeclaration<ScreenService>;
 }
 
+/** The three available theme modes: follow system preference, force light, or force dark. */
+type ThemeType = 'auto' | 'light' | 'dark';
 /**
- * Kind of themes: system default, light or dark
+ * Application-level theme management service.
+ *
+ * Responsibilities:
+ * - Persists the user's preferred theme in `localStorage`.
+ * - Applies `'light'` or `'dark'` CSS class to `<body>`.
+ * - Reacts to OS-level colour-scheme changes when the theme is set to `'auto'`.
+ * - Synchronises theme changes across browser tabs via `BroadcastChannel`.
+ * - Exposes reactive signals (`themeIcon`, `themeName`, `toggleTooltip`) for the UI.
  */
-type ThemeType = 'auto' | 'light' | 'dark';
 declare class ThemeService implements OnDestroy {
     private readonly broadcastChannel;
     private readonly broadcastMessage;
     private readonly prefersColorSchemeMediaQueryList;
     /**
-     * Theme changed e.
-     * Notify the consuming component about the incoming theme change.
+     * Observable that emits the resolved (`'light'` or `'dark'`) theme whenever it changes.
+     * Useful for components that cannot consume signals directly (e.g. class-based guards).
      * @example
-     * // React to theme changes
-     * this.themeService.themeChanged
-     *    .pipe(takeUntil(this.unsubscribe))
-     *    .subscribe((value: ThemeType) => {
-     *      // do the job done....
-     *    });
+     * this.themeService.changed
+     *   .pipe(takeUntilDestroyed(this.destroyRef))
+     *   .subscribe(theme => { ... });
      */
+    readonly changed: Observable<ThemeType>;
     private readonly themeChanged;
-    changed: Observable<ThemeType>;
     private readonly renderFactory2;
     private readonly renderer;
-    /**
-     * Current theme
-     */
+    /** The currently selected `ThemeType` (may be `'auto'`). */
     private readonly theme;
-    /**
-     * The current theme is "System default"
-     */
+    /** `true` when the theme is set to follow the system preference. */
     private readonly auto;
-    /**
-     * Configuration schema about the icon, the text and the toggle() sequence
-     */
     private readonly themeInfo;
-    /**
-     * Icon of the current theme (mat-icon code)
-     */
+    /** Reactive Material icon code for the current theme (use with `<mat-icon>`). */
     readonly themeIcon: Signal<string>;
-    /**
-     * Current theme name
-     */
+    /** Reactive human-readable name of the current theme. */
     readonly themeName: Signal<string>;
-    /**
-     * Tooltip text on toggle
-     */
+    /** Reactive tooltip text for the theme toggle button. */
     readonly toggleTooltip: Signal<string>;
+    constructor();
     /**
-     * Initialize
+     * Initialises the service: loads the preferred theme, registers OS-change listener,
+     * and subscribes to cross-tab broadcast messages.
+     * Call this once during application bootstrap (e.g. in `APP_INITIALIZER`).
+     * @param theme - The initial theme to apply (defaults to the value stored in `localStorage`).
      */
     initialize(theme?: ThemeType): void;
     ngOnDestroy(): void;
     /**
-     * Get the current preferred theme
+     * Advances the theme through the cycle: `auto` → `light` → `dark` → `auto`.
      */
-    private getPreferredTheme;
+    toggleTheme(): void;
     /**
-     * Check if a value string is a theme type
-     * @param value : th string value
-     * @returns true if the the value is a valid theme type
+     * Returns the resolved effective theme (`'light'` or `'dark'`), taking the OS preference
+     * into account when the current mode is `'auto'`.
+     * @returns `'light'` or `'dark'` — never `'auto'`.
      */
-    private isTheme;
+    getTheme(): ThemeType;
     /**
-     * Set the new theme
-     * @param theme the new theme
+     * Reads the theme stored in `localStorage` and validates it.
+     * Falls back to `'auto'` when the stored value is missing or invalid.
+     * @returns The persisted `ThemeType`, or `'auto'` as default.
      */
-    private setTheme;
+    private getPreferredTheme;
     /**
-     * Toggle theme
+     * Returns `true` when `value` is a valid `ThemeType` string.
+     * Acts as a TypeScript type guard.
+     * @param value - The string to check.
      */
-    toggleTheme(): void;
+    private isTheme;
     /**
-     * Get current real theme: light or dark
+     * Applies the given theme to `<body>` (CSS class), persists it to `localStorage`,
+     * notifies the `changed` observable, and broadcasts the change to other tabs.
+     * @param theme - The `ThemeType` to apply (defaults to `'auto'`).
      */
-    getTheme(): ThemeType;
+    private setTheme;
     static ɵfac: i0.ɵɵFactoryDeclaration<ThemeService, never>;
     static ɵprov: i0.ɵɵInjectableDeclaration<ThemeService>;
 }
@@ -969,36 +1292,138 @@ declare class ArsCoreModule {
 }
 
 declare const MAT_DATE_FNS_FORMATS: MatDateFormats;
-/** Adds date-fns support to Angular Material. */
+/**
+ * date-fns adapter that integrates Angular Material's date picker with the date-fns library,
+ * applying `Europe/Rome` timezone for all parsed and created dates.
+ */
 declare class DateFnsAdapter extends DateAdapter<Date, Locale> {
     constructor(...args: unknown[]);
+    /**
+     * Returns the year component of the given date.
+     * @param date - The source date.
+     */
     getYear(date: Date): number;
+    /**
+     * Returns the zero-based month index of the given date (0 = January).
+     * @param date - The source date.
+     */
     getMonth(date: Date): number;
+    /**
+     * Returns the day-of-month of the given date (1-based).
+     * @param date - The source date.
+     */
     getDate(date: Date): number;
+    /**
+     * Returns the day-of-week of the given date (0 = Sunday).
+     * @param date - The source date.
+     */
     getDayOfWeek(date: Date): number;
+    /**
+     * Returns an array of 12 month name strings formatted for the active locale.
+     * @param style - One of `'long'`, `'short'`, or `'narrow'`.
+     */
     getMonthNames(style: 'long' | 'short' | 'narrow'): string[];
+    /**
+     * Returns an array of 31 day-of-month label strings formatted using `Intl.DateTimeFormat`
+     * when available, falling back to plain numeric strings.
+     */
     getDateNames(): string[];
+    /**
+     * Returns an array of 7 day-of-week name strings formatted for the active locale.
+     * @param style - One of `'long'`, `'short'`, or `'narrow'`.
+     */
     getDayOfWeekNames(style: 'long' | 'short' | 'narrow'): string[];
+    /**
+     * Returns the four-digit year string for the given date.
+     * @param date - The source date.
+     */
     getYearName(date: Date): string;
+    /**
+     * Returns the first day of the week for the active locale (0 = Sunday, 1 = Monday, …).
+     */
     getFirstDayOfWeek(): number;
+    /**
+     * Returns the number of days in the month of the given date.
+     * @param date - The source date.
+     */
     getNumDaysInMonth(date: Date): number;
+    /**
+     * Creates an independent copy of the given date.
+     * @param date - The date to clone.
+     */
     clone(date: Date): Date;
+    /**
+     * Creates a `Date` in the `Europe/Rome` timezone for the given year, month, and day.
+     * Throws an `Error` when any component is out of range.
+     * @param year  - Full four-digit year.
+     * @param month - Zero-based month index (0 = January, 11 = December).
+     * @param date  - Day-of-month (1-based).
+     */
     createDate(year: number, month: number, date: number): Date;
+    /**
+     * Returns today's date in the local timezone.
+     */
     today(): Date;
+    /**
+     * Parses a value into a `Date`.
+     * - Strings are first attempted as ISO 8601, then matched against each format in `parseFormat`.
+     * - Numbers are treated as Unix timestamps (milliseconds).
+     * - Existing `Date` instances are cloned.
+     * @param value       - The value to parse.
+     * @param parseFormat - A format string or an array of format strings (date-fns tokens).
+     * @returns A valid `Date` in `Europe/Rome`, an invalid sentinel, or `null` for unrecognised input.
+     */
     parse(value: unknown, parseFormat: string | string[]): Date | null;
+    /**
+     * Formats a `Date` using the given date-fns display format string.
+     * Throws an `Error` when `date` is not valid.
+     * @param date          - The date to format.
+     * @param displayFormat - A date-fns format string (e.g. `'P'`, `'LLL uuuu'`).
+     */
     format(date: Date, displayFormat: string): string;
+    /**
+     * Adds the given number of whole years to a date.
+     * @param date  - The base date.
+     * @param years - Number of years to add (can be negative).
+     */
     addCalendarYears(date: Date, years: number): Date;
+    /**
+     * Adds the given number of whole months to a date.
+     * @param date   - The base date.
+     * @param months - Number of months to add (can be negative).
+     */
     addCalendarMonths(date: Date, months: number): Date;
+    /**
+     * Adds the given number of whole days to a date.
+     * @param date - The base date.
+     * @param days - Number of days to add (can be negative).
+     */
     addCalendarDays(date: Date, days: number): Date;
+    /**
+     * Serialises a date to an ISO 8601 date string (`yyyy-MM-dd`).
+     * @param date - The date to serialise.
+     */
     toIso8601(date: Date): string;
     /**
-     * Returns the given value if given a valid Date or undefined. Deserializes valid ISO 8601 strings
-     * (https://www.ietf.org/rfc/rfc3339.txt) into valid Dates and empty string into undefined. Returns an
-     * invalid date for all other values.
+     * Returns the given value when it is a valid `Date`, or `null` for an empty string.
+     * Deserialises valid ISO 8601 strings into `Date` instances.
+     * Delegates all other values to the base-class implementation.
+     * @param value - The raw value to deserialise.
      */
     deserialize(value: unknown): Date | null;
+    /**
+     * Returns `true` when `obj` is an instance of `Date`.
+     * @param obj - The object to test.
+     */
     isDateInstance(obj: unknown): boolean;
+    /**
+     * Returns `true` when `date` represents a valid point in time.
+     * @param date - The date to validate.
+     */
     isValid(date: Date): boolean;
+    /**
+     * Returns a sentinel `Date` that represents an invalid date (`new Date(NaN)`).
+     */
     invalid(): Date;
     static ɵfac: i0.ɵɵFactoryDeclaration<DateFnsAdapter, never>;
     static ɵprov: i0.ɵɵInjectableDeclaration<DateFnsAdapter>;
@@ -1009,15 +1434,76 @@ declare class ArsDateFnsModule {
     static ɵinj: i0.ɵɵInjectorDeclaration<ArsDateFnsModule>;
 }
 
+/**
+ * Directive that removes focus from the host element after it is clicked,
+ * preventing the browser from keeping a visible focus ring post-interaction.
+ * Apply `removeFocus` to any focusable element (e.g. a button).
+ */
 declare class RemoveFocusDirective {
     private readonly elementRef;
-    onClick(_event: Event): void;
+    /**
+     * Handles click events on the host element and blurs it on the next event-loop tick
+     * so that the click action completes before focus is removed.
+     */
+    onClick(): void;
     static ɵfac: i0.ɵɵFactoryDeclaration<RemoveFocusDirective, never>;
     static ɵdir: i0.ɵɵDirectiveDeclaration<RemoveFocusDirective, "[removeFocus]", never, {}, {}, never, never, true, never>;
 }
 
+/**
+ * Directive that validates that the host control's value is different from another control's value.
+ * Bind `[notEqual]="otherControl"`.
+ */
+declare class NotEqualValidatorDirective implements Validator {
+    /** The control whose value must differ from the host control's value. */
+    readonly notEqual: i0.InputSignal<AbstractControl<any, any, any>>;
+    /**
+     * Validates that the host control value is not equal to the bound control's value.
+     * Also clears the `notequal` error on the other control when the host becomes valid.
+     * Returns `null` (valid) when no control is bound.
+     * @param control - The form control to validate.
+     */
+    validate(control: AbstractControl): ValidationErrors | null;
+    static ɵfac: i0.ɵɵFactoryDeclaration<NotEqualValidatorDirective, never>;
+    static ɵdir: i0.ɵɵDirectiveDeclaration<NotEqualValidatorDirective, "[notEqual]", never, { "notEqual": { "alias": "notEqual"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
+}
+
+/**
+ * Directive that validates a time string against optional allowed time slot ranges.
+ * Bind `[time]` and optionally `[slots]="'08:00-12:00|14:00-18:00'"` (pipe-separated ranges).
+ */
+declare class TimeValidatorDirective implements Validator {
+    /** Optional pipe-separated list of allowed time ranges, e.g. `"08:00-12:00|14:00-18:00"`. */
+    readonly slots: i0.InputSignal<string>;
+    /**
+     * Parses a `"HH:MM"` time string into a comparable integer (e.g. `"09:30"` -> `930`).
+     * Returns `-1` when the string is not a valid time.
+     * @param value - The time string to parse.
+     */
+    private getTime;
+    /**
+     * Validates that the control value is a valid time string and, when slots are configured,
+     * that it falls within at least one of the allowed ranges.
+     * Returns `null` when the control is empty.
+     * @param control - The form control to validate.
+     */
+    validate(control: AbstractControl): ValidationErrors | null;
+    static ɵfac: i0.ɵɵFactoryDeclaration<TimeValidatorDirective, never>;
+    static ɵdir: i0.ɵɵDirectiveDeclaration<TimeValidatorDirective, "[time]", never, { "slots": { "alias": "slots"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
+}
+
+/**
+ * Pipe that converts a Markdown string to sanitized HTML using `SystemUtils.markdownToHtml`.
+ *
+ * Usage: `{{ text | formatMarkdown }}`
+ */
 declare class FormatMarkdownPipe implements PipeTransform {
     private readonly sanitizer;
+    /**
+     * Transforms a Markdown string into sanitized HTML.
+     * @param value - The Markdown input to convert. Treated as an empty string when `undefined`.
+     * @returns A `SafeHtml` value that can be rendered with `[innerHTML]`.
+     */
     transform(value?: string): SafeHtml;
     static ɵfac: i0.ɵɵFactoryDeclaration<FormatMarkdownPipe, never>;
     static ɵpipe: i0.ɵɵPipeDeclaration<FormatMarkdownPipe, "formatMarkdown", true>;