@odx/angular 6.0.0 → 6.1.0

package/sdk/lib/application-environment.d.ts

@@ -1,7 +1,66 @@
 import { ApplicationRef, InjectionToken } from '@angular/core';
 import { CacheStorageClient } from '@odx/angular/utils';
+/**
+ * A function type definition for loading environment data for an application.
+ * It's a generic loader function that accepts parameters and returns a Promise of environment data.
+ *
+ * @template EnvironmentData The type of the environment data to be loaded.
+ * @template Params The types of the parameters accepted by the loader function.
+ * @param {...Params} args - Parameters passed to the loader function.
+ * @returns {Promise<EnvironmentData>} A promise resolving to the loaded environment data.
+ */
 export type ApplicationEnvironmentLoader<EnvironmentData, Params extends unknown[]> = (...args: Params) => Promise<EnvironmentData>;
+/**
+ * Creates a loader function for fetching application environment data over HTTP and caching it.
+ * Utilizes `CacheStorageClient` for caching the fetched data to optimize performance and reduce network load.
+ *
+ * @template Data The type of the data expected from the HTTP request.
+ * @param {Function} handler - A function that processes the fetched data and returns a promise resolving to the desired environment data format.
+ * @returns {ApplicationEnvironmentLoader<Data, Parameters<CacheStorageClient['request']>>} A loader function that fetches, caches, and processes environment data.
+ * @example
+ * const environmentLoader = createHttpApplicationEnvironmentLoader(async (dto) => {
+ *   return { apiEndpoint: dto.apiEndpoint, featureFlags: dto.featureFlags };
+ * });
+ */
 export declare function createHttpApplicationEnvironmentLoader<Data>(handler: (dto: unknown) => Promise<Data>): ApplicationEnvironmentLoader<Data, Parameters<CacheStorageClient['request']>>;
+/**
+ * The application environment module can be used to load environment data before application startup,
+ * that can be used to load environment variables from an external URL.
+ *
+ * @template Data The type of the environment data.
+ * @template Params The types of the parameters accepted by the loader function.
+ * @param {ApplicationEnvironmentLoader<Data, Params>} loader - A loader function that asynchronously loads the environment data.
+ * @returns An object containing utilities for working with the application environment, including the InjectionToken
+ *          and functions for loading and bootstrapping the application with the environment.
+ * @example
+ * To add an application environment to your Angular application, follow the following steps:
+ * 1. Create the application environment with your loader:
+ * ```ts
+ * import { createApplicationEnvironment, createHttpApplicationEnvironmentLoader } from '@odx/angular/sdk';
+ * import { z } from 'zod';
+ *
+ * export const ApplicationConfigSchema = z.object({
+ *   environment: z.enum(['dev', 'stage', 'prod']),
+ *   appName: z.string().default('App'),
+ * });
+ *
+ * const httpEnvironmentLoader = createHttpApplicationEnvironmentLoader((res) => res.json().then(ApplicationConfigSchema.parse));
+ * export const { injectApplicationEnvironment, bootstrapApplicationWithEnvironment } = createApplicationEnvironment(httpEnvironmentLoader);
+ * ```
+ * This example creates an HTTP environment loader which parses the response as JSON and validate it against a schema
+ *
+ * 2. Provide the application environment:
+ * ```ts
+ * bootstrapApplicationWithEnvironment(['assets/config.json'], AppComponent, { providers: [] });
+ * ```
+ *
+ * 3. Use the application environment via DI
+ * ```ts
+ * class MyService {
+ *   private readonly environment = injectApplicationEnvironment();
+ * }
+ * ```
+ */
 export declare function createApplicationEnvironment<Data, Params extends unknown[]>(loader: ApplicationEnvironmentLoader<Data, Params>): {
     APPLICATION_ENVIRONMENT: InjectionToken<Data>;
     injectApplicationEnvironment: () => Data;

package/theming/lib/helpers/prefers-dark-theme.d.ts

@@ -1 +1,19 @@
+/**
+ * Determines whether the user's system preferences indicate a preference for dark themes.
+ * This is achieved by querying the '(prefers-color-scheme: dark)' media feature, which reflects
+ * the user's preference for a light or dark color scheme in their operating system's UI.
+ *
+ * @param {Window} view - The window object, typically `window`, from which to access the matchMedia method.
+ * @returns {boolean} `true` if the user prefers a dark theme, otherwise `false`.
+ *
+ * @example
+ * Example usage in a web application to toggle themes:
+ * ```ts
+ * if (prefersDarkTheme(window)) {
+ *   document.body.classList.add('dark-theme');
+ * } else {
+ *   document.body.classList.remove('dark-theme');
+ * }
+ * ```
+ */
 export declare function prefersDarkTheme(view: Window): boolean;

package/theming/lib/helpers/resolve-theme.d.ts

@@ -1,2 +1,27 @@
 import { Theme } from '../models';
+/**
+ * Resolves the specified theme by checking if it exists in the predefined list of available themes.
+ * This function ensures that only valid themes are used in the application, providing a safeguard
+ * against invalid theme names and facilitating the dynamic application of themes.
+ *
+ * @param {string | null} [theme] - The name of the theme to resolve. It's optional and can be `null`.
+ * @returns {Theme | null} - Returns the resolved `Theme` object if the theme is found within the list of `availableThemes`;
+ * otherwise, returns `null` to indicate the theme is not recognized or available.
+ *
+ * @example
+ * ```ts
+ * // Assuming 'dark' and 'light' are in the availableThemes array
+ * console.log(resolveTheme('dark')); // Outputs the 'dark' Theme object
+ * console.log(resolveTheme('unknown')); // Outputs null
+ *
+ * // Using resolveTheme to apply a user-selected theme
+ * const userSelectedTheme = getUserSelectedTheme(); // This function gets the user's theme choice
+ * const themeToApply = resolveTheme(userSelectedTheme);
+ * if (themeToApply) {
+ *   applyTheme(themeToApply); // This function applies the resolved theme to the application
+ * } else {
+ *   console.warn('Selected theme is not available.');
+ * }
+ * ```
+ */
 export declare function resolveTheme(theme?: string | null): Theme | null;

package/theming/lib/helpers/theme-storage.d.ts

@@ -1,4 +1,46 @@
 import { Theme } from '../models';
+/**
+ * The key used to store the selected theme in `Storage`.
+ * This constant ensures consistent access to the theme setting across the application.
+ */
 export declare const THEME_STORAGE_NAME = "@odx/angular/theming:SelectedTheme";
+/**
+ * Saves the specified theme to storage. This function abstracts the storage interaction,
+ * providing a fail-safe mechanism to avoid exceptions if the storage is not available.
+ *
+ * @param {Storage | null | undefined} storage - The storage mechanism to use, typically `localStorage` or `sessionStorage`.
+ * @param {Theme} theme - The theme to save. Should be a value that is recognized by the application's theming system.
+ * @throws Will silently catch and ignore any exceptions caused by storage limitations or permissions.
+ *
+ * @example
+ * ```ts
+ * // Example usage with localStorage
+ * saveTheme(localStorage, 'dark');
+ *
+ * // Using sessionStorage instead
+ * saveTheme(sessionStorage, 'light');
+ * ```
+ */
 export declare function saveTheme(storage: Storage | null | undefined, theme: Theme): void;
+/**
+ * Reads the theme from storage, attempting to resolve it to a valid application theme.
+ * If the theme cannot be found or is invalid, `null` is returned. This function also provides
+ * error handling for any storage access issues, ensuring the application can gracefully handle
+ * scenarios where storage is not available or accessible.
+ *
+ * @param {Storage | null} [storage] - The storage mechanism to use, typically `localStorage` or `sessionStorage`.
+ * @returns {Theme | null} - The resolved theme if found and valid; otherwise, `null`.
+ * @throws Will silently catch and ignore any exceptions caused by storage access, returning `null`.
+ *
+ * @example
+ * ```ts
+ * // Reading theme from localStorage
+ * const theme = readTheme(localStorage);
+ * if (theme) {
+ *   applyTheme(theme); // Assuming applyTheme is a function to apply the theme
+ * } else {
+ *   console.warn('No saved theme found or theme is invalid.');
+ * }
+ * ```
+ */
 export declare function readTheme(storage?: Storage | null): Theme | null;

package/theming/lib/theming.config.d.ts

@@ -1,10 +1,56 @@
 import { EnvironmentProviders } from '@angular/core';
 import { ConfigDependencies, ConfigProvider } from '@odx/angular/utils';
 import { Theme } from './models';
+/**
+ * Defines the structure for theming configuration options in the application.
+ */
 export interface ThemingConfig {
+    /**
+     * Determines whether the theme should be auto-detected based on system preferences.
+     */
     autoDetect: boolean;
+    /**
+     * Specifies the default theme to be used if auto-detection is not enabled or fails.
+     */
     defaultTheme: Theme;
+    /**
+     * The storage mechanism (like `localStorage` or `sessionStorage`) to persist theme settings,
+     * or `null` to disable persistence.
+     */
     storage?: Storage | null;
 }
+/**
+ * Utility created by `createConfigTokens` for managing theming configuration tokens and functions.
+ * Provides easy access to theming configuration, default values, and dependency injection utilities.
+ */
 export declare const ThemingConfig: import("@angular/core").InjectionToken<Partial<ThemingConfig>>, injectThemingConfig: () => ThemingConfig, provideThemingConfig: <D extends ConfigDependencies<unknown> = ConfigDependencies<Partial<ThemingConfig>>>(config: ConfigProvider<Partial<ThemingConfig>, D>) => import("@angular/core").FactoryProvider | import("@angular/core").ValueProvider;
+/**
+ * Provides the theming configuration to the application and initializes the `ThemingService`
+ * based on the provided configuration. This function simplifies the setup of a dynamic theming
+ * system, integrating with Angular's environment initializers to ensure proper initialization.
+ *
+ * @template D - The dependencies required by the theming configuration, if any.
+ * @param {ConfigProvider<Partial<ThemingConfig>, D>} config - The theming configuration or a configuration factory provider.
+ * @returns {EnvironmentProviders} An array of providers for setting up theming in the application.
+ *
+ * @example
+ * ```ts
+ * // Providing a simple theming configuration
+ * provideTheming({
+ *   autoDetect: true,
+ *   defaultTheme: Theme.DARK,
+ *   storage: localStorage,
+ * });
+ *
+ * // Providing a theming configuration with dependencies
+ * provideTheming({
+ *   useFactory: (deps: Dependencies) => ({
+ *     autoDetect: deps.setting,
+ *     defaultTheme: Theme.DARK,
+ *     storage: localStorage,
+ *   }),
+ *   deps: [SomeDependency],
+ * });
+ * ```
+ */
 export declare function provideTheming<D extends ConfigDependencies = ConfigDependencies<ThemingConfig>>(config: ConfigProvider<Partial<ThemingConfig>, D>): EnvironmentProviders;

package/theming/lib/theming.service.d.ts

@@ -1,17 +1,48 @@
 import { Theme } from './models';
 import * as i0 from "@angular/core";
 export declare const THEME_ATTRIBUTE_NAME = "odxTheme";
+/**
+ * Manages theming for the application. It allows for dynamic theme selection, automatically saves theme preferences,
+ * and applies the user's preferred theme or the default theme based on configuration settings.
+ *
+ * The service leverages the BehaviorSubject pattern to reactively handle theme changes across the application,
+ * ensuring that subscribers are notified whenever the theme changes. It also interacts with the DOM directly
+ * to apply the current theme and with the provided storage mechanism to persist theme preferences.
+ */
 export declare class ThemingService {
     private readonly config;
     private readonly document;
     private readonly windowRef;
     private readonly theme$$;
+    /**
+     * An observable stream of the current theme, emitting values whenever the theme changes.
+     * Subscribers to this observable can react to theme changes in real-time.
+     */
     readonly theme$: import("rxjs").Observable<Theme>;
     constructor();
+    /**
+     * Selects and applies a given theme by updating the BehaviorSubject and persisting the preference.
+     *
+     * @param {Theme} theme - The theme to apply.
+     */
     selectTheme(theme: Theme): void;
+    /**
+     * Retrieves the currently selected theme.
+     *
+     * @returns {Theme} The currently selected theme.
+     */
     getSelectedTheme(): Theme;
+    /**
+     * Toggles between dark and light themes, depending on the current theme.
+     */
     toggleDarkMode(): void;
+    /**
+     * Enables the dark mode theme.
+     */
     enableDarkMode(): void;
+    /**
+     * Enables the light mode theme.
+     */
     enableLightMode(): void;
     private getInitialTheme;
     static ɵfac: i0.ɵɵFactoryDeclaration<ThemingService, never>;

package/utils/lib/decorators/pure.d.ts

@@ -1 +1,52 @@
+/**
+ * A decorator that transforms a class method or getter into a pure function. For methods, it caches the result
+ * of the first invocation with a given set of arguments and returns the cached result on subsequent invocations
+ * with the same arguments. For getters, it caches the result of the first access and returns the cached value
+ * on subsequent accesses.
+ *
+ * This decorator is intended to improve performance by avoiding unnecessary recalculations or processing
+ * when the inputs have not changed.
+ *
+ * @template T The type of the property being decorated.
+ * @param {object} _target The prototype of the class.
+ * @param {string} propertyKey The name of the method or getter.
+ * @param {TypedPropertyDescriptor<T>} descriptor The property descriptor for the method or getter.
+ * @throws {Error} Throws an error if applied to non-function properties.
+ * @returns {TypedPropertyDescriptor<T>} A new descriptor with the getter or method patched for pure behavior.
+ *
+ * @example
+ * Usage with a getter:
+ * ```ts
+ * class ExampleClass {
+ *   private _value: number = Math.random();
+ *
+ *   @Pure
+ *   get value(): number {
+ *     console.log('Getter called');
+ *     return this._value;
+ *   }
+ * }
+ *
+ * const example = new ExampleClass();
+ * console.log(example.value); // Logs 'Getter called' and the value
+ * console.log(example.value); // Logs only the value, without calling the getter again
+ * ```
+ *
+ * Usage with a method:
+ * ```ts
+ * class Counter {
+ *   private count = 0;
+ *
+ *   @Pure
+ *   increment(step: number) {
+ *     console.log('Increment called');
+ *     return (this.count += step);
+ *   }
+ * }
+ *
+ * const counter = new Counter();
+ * console.log(counter.increment(1)); // Logs 'Increment called' and 1
+ * console.log(counter.increment(1)); // Logs 1 without calling increment again
+ * ```
+ */
 export declare function Pure<T>(_target: object, propertyKey: string, { get, enumerable, value }: TypedPropertyDescriptor<T>): TypedPropertyDescriptor<T>;

package/utils/lib/helpers/angular.d.ts

@@ -1,9 +1,45 @@
 import { ElementRef } from '@angular/core';
 import { Observable } from 'rxjs';
+/**
+ * Binds an observable to toggle a CSS class on the host element based on the truthiness of the emitted values.
+ * The subscription automatically ends when the component is destroyed.
+ *
+ * @template T The type of items emitted by the source observable.
+ * @param {Observable<T> | null | undefined} source$ The observable source emitting truthy or falsy values.
+ * @param {string} cssClass The CSS class to toggle based on the emitted values.
+ */
 export declare function reactiveClassBinding<T>(source$: Observable<T> | null | undefined, cssClass: string): void;
+/**
+ * Binds an observable to update attributes on the host element with the emitted values.
+ * The subscription automatically ends when the component is destroyed.
+ *
+ * @template T The type of items emitted by the source observable.
+ * @param {Observable<T> | null | undefined} source$ The observable source.
+ * @param {...string[]} attributes The attributes to set on the host element based on the emitted values.
+ */
 export declare function reactiveAttributeBinding<T>(source$: Observable<T> | null | undefined, ...attributes: string[]): void;
+/**
+ * Injects the ElementRef of the host element in an Angular component or directive.
+ *
+ * @template T The expected type of the native element.
+ * @returns {ElementRef<T>} The injected ElementRef instance.
+ */
 export declare function injectElement<T = HTMLElement>(): ElementRef<T>;
+/**
+ * Tracking function for use with `*ngFor` that tracks items by their index.
+ *
+ * @param {number} index The index of the item in the iterable.
+ * @returns {number} The index, used as the trackBy identity.
+ */
 export declare function trackByIndex(index: number): number;
+/**
+ * Tracking function for use with `*ngFor` that tracks items by their unique ID.
+ *
+ * @template T The type of the items in the iterable, must have an 'id' property.
+ * @param {number} _ The index of the item in the iterable, not used.
+ * @param {T} item The item in the iterable.
+ * @returns {T['id']} The item's ID, used as the trackBy identity.
+ */
 export declare function trackById<T extends {
     id: string | number | symbol;
 }>(_: number, { id }: T): T['id'];

package/utils/lib/helpers/array.d.ts

@@ -7,8 +7,10 @@
  * @param {K} key - The key whose values are to be plucked from each object in the array.
  * @returns {Array<T[K]>} An array of values corresponding to the specified key from each object.
  * @example
+ * ```ts
  * const users = [{ name: 'Alice' }, { name: 'Bob' }];
  * const names = pluckFromArray(users, 'name'); // ['Alice', 'Bob']
+ * ```
  */
 export declare function pluckFromArray<T, K extends keyof T>(arr: T[], key: K): Array<T[K]>;
 export type OrderByDirection = 'ASC' | 'DESC';
@@ -20,7 +22,9 @@ export type OrderByDirection = 'ASC' | 'DESC';
  * @param {OrderByDirection} [direction='ASC'] - The direction to sort ('ASC' for ascending, 'DESC' for descending).
  * @returns {(a: T, b: T) => number} A compare function that can be used in the array sort method.
  * @example
+ * ```ts
  * const items = [{ value: 10 }, { value: 5 }, { value: 7 }];
  * const sortedItems = items.sort(orderBy('value', 'ASC')); // Sorted by value in ascending order
+ * ```
  */
 export declare function orderBy<T>(key: keyof T, direction?: OrderByDirection): (a: T, b: T) => number;

package/utils/lib/helpers/build-url.d.ts

@@ -1 +1,21 @@
+/**
+ * Constructs a URL string from provided segments, ensuring proper slash separation without duplications.
+ * It gracefully handles `null`, `undefined`, and symbol values by omitting them from the final URL.
+ * Additionally, the function preserves the protocol part of the URL, if specified.
+ *
+ * @param {...Array<string | number | symbol | null | undefined>} args - The segments to concatenate into a URL.
+ * Can be a mix of strings, numbers, symbols (converted to strings), or `null`/`undefined` (which are omitted).
+ * @returns {string} The constructed URL string with correctly formatted slashes.
+ *
+ * @example
+ * ```ts
+ * // Basic usage
+ * console.log(buildUrl('http://example.com', 'path', 'to', 'resource'));
+ * // Outputs: "http://example.com/path/to/resource"
+ *
+ * // Removing duplicate slashes
+ * console.log(buildUrl('http://example.com/', '/path/', '//to', '/resource/'));
+ * // Outputs: "http://example.com/path/to/resource/"
+ * ```
+ */
 export declare function buildUrl(...args: Array<string | number | symbol | null | undefined>): string;

package/utils/lib/helpers/build-website-url.d.ts

@@ -15,11 +15,12 @@ export declare const DRAEGER_WEBSITE_URL = "https://www.draeger.com";
  * @returns {string} The fully constructed URL, including the base URL and all provided path segments.
  *
  * @example
+ * ```ts
  * // Returns 'https://www.draeger.com/about-us'
  * const url = buildWebsiteUrl('about-us');
  *
- * @example
  * // Can also handle multiple segments, returning 'https://www.draeger.com/products/search/123'
  * const productUrl = buildWebsiteUrl('products', 'search', 123);
+ * ```
  */
 export declare function buildWebsiteUrl(...segments: Array<string | number | symbol | null | undefined>): string;

package/utils/lib/helpers/cache-storage-client.d.ts

@@ -1,12 +1,63 @@
+/**
+ * The HTTP 'Etag' header, used for web cache validation.
+ */
 export declare const HTTP_ETAG_HEADER = "Etag";
+/**
+ * The HTTP 'If-None-Match' header, used in conditional requests to compare against the ETag.
+ */
 export declare const HTTP_IF_NONE_MATCH_HEADER = "If-None-Match";
+/**
+ * The HTTP 'Cache-Control' header, used to specify directives for caching mechanisms in requests and responses.
+ */
 export declare const HTTP_CACHE_CONTROL_HEADER = "Cache-Control";
+/**
+ * A client for managing cache storage for web applications. It simplifies interactions with the Cache Storage API,
+ * allowing for the caching, retrieval, and deletion of request responses. This class uses HTTP caching headers to
+ * optimize network requests and cache management.
+ *
+ * @example
+ * ```ts
+ * // Creating an instance of CacheStorageClient
+ * const cacheClient = new CacheStorageClient('my-cache');
+ *
+ * // Requesting and caching data
+ * cacheClient.request('https://api.example.com/data').then(data => {
+ *   console.log(data);
+ * });
+ *
+ * // Deleting a specific cache entry
+ * cacheClient.delete('https://api.example.com/data');
+ *
+ * // Clearing all cache entries
+ * cacheClient.deleteAll();
+ * ```
+ */
 export declare class CacheStorageClient {
     private readonly cacheKey;
     private readonly cacheStorage;
     constructor(cacheKey: string, cacheStorage?: CacheStorage);
+    /**
+     * Deletes a specific cache entry.
+     *
+     * @param {RequestInfo | URL} request - The request or URL to delete from the cache.
+     * @returns {Promise<boolean>} A promise that resolves to a boolean indicating whether the deletion was successful.
+     */
     delete(request: RequestInfo | URL): Promise<boolean>;
+    /**
+     * Deletes all entries from the cache.
+     *
+     * @returns {Promise<void>} A promise that resolves when all entries have been deleted.
+     */
     deleteAll(): Promise<void>;
+    /**
+     * Performs a request, caching the response if applicable. If a response is cached for the request and still valid,
+     * it returns the cached response instead of making a new network request.
+     *
+     * @template T - The expected response data type.
+     * @param {RequestInfo | URL} requestInfo - The request information or URL to fetch and cache.
+     * @param {(response: Response) => boolean} [shouldDelete=({ status }) => status >= 400 && status < 500] - An optional function to determine if the cache entry should be deleted based on the response.
+     * @returns {Promise<T | null>} A promise that resolves to the response data, or null if the request fails.
+     */
     request<T>(requestInfo: RequestInfo | URL, shouldDelete?: ({ status }: Response) => boolean): Promise<T | null>;
     protected getCache(): Promise<Cache>;
     protected prepareRequest(cache: Cache, requestInfo: RequestInfo | URL): Promise<Request>;

package/utils/lib/helpers/coercion.d.ts

@@ -1,2 +1,19 @@
+/**
+ * Coerces a value to an array. If the value is already an array, it is returned directly.
+ * If the value is not an array, it is wrapped in an array. This utility is useful for
+ * handling values that can be either single values or arrays, ensuring consistent array handling.
+ *
+ * @param {string | string[]} value - The value to coerce to an array. Can be a single string or an array of strings.
+ * @returns {string[]} The coerced value as an array of strings.
+ *
+ * @example
+ * ```ts
+ * // Coercing a single string to an array
+ * console.log(arrayAttribute('singleValue')); // Outputs: ['singleValue']
+ *
+ * // Returning an array directly
+ * console.log(arrayAttribute(['value1', 'value2'])); // Outputs: ['value1', 'value2']
+ * ```
+ */
 export declare function arrayAttribute(value: string | string[]): string[];
 export { coerceArray, coerceCssPixelValue, coerceElement, coerceStringArray } from '@angular/cdk/coercion';

package/utils/lib/helpers/debounce.d.ts

@@ -1 +1,28 @@
+/**
+ * Creates a debounced function that delays invoking the provided function until after `delay` milliseconds
+ * have elapsed since the last time the debounced function was invoked. Optionally, the function can be
+ * triggered immediately on the first call, then debounced for subsequent calls.
+ *
+ * @template Args - A tuple representing the types of arguments the `func` accepts.
+ * @param {(...args: Args) => void} func - The function to debounce.
+ * @param {number} delay - The number of milliseconds to delay.
+ * @param {boolean} [immediate=false] - Whether to trigger the function immediately on the first call,
+ * and then debounce subsequent calls.
+ * @returns {(...args: Args) => void} A new, debounced function.
+ *
+ * @example
+ * ```ts
+ * // Example usage with a window resize event
+ * const handleResize = debounce(() => {
+ *   console.log('Window resized');
+ * }, 250);
+ * window.addEventListener('resize', handleResize);
+ *
+ * // Example using immediate invocation
+ * const processKeyPress = debounce((event) => {
+ *   console.log('Key pressed:', event.key);
+ * }, 200, true);
+ * document.addEventListener('keypress', processKeyPress);
+ * ```
+ */
 export declare function debounce<Args extends unknown[]>(func: (...args: Args) => void, delay: number, immediate?: boolean): (...args: Args) => void;

package/utils/lib/helpers/defer-fn.d.ts

@@ -1 +1,21 @@
+/**
+ * Defers the execution of a function until the current call stack is clear.
+ * This is achieved by using `setTimeout` with a delay of `0`, effectively placing the function
+ * at the end of the event queue and allowing the browser to complete any pending tasks before execution.
+ *
+ * @param {() => void} fn - The function to be deferred.
+ *
+ * @example
+ * ```ts
+ * // Deferring a simple function
+ * deferFn(() => console.log('This will be logged after the current execution context completes.'));
+ *
+ * // Using deferFn to update the UI after a synchronous operation
+ * function updateUI() {
+ *   // UI update logic here
+ * }
+ * // Assume we're inside a synchronous block of code that updates data
+ * deferFn(updateUI); // Ensures UI is updated after data changes are fully applied
+ * ```
+ */
 export declare function deferFn(fn: () => void): void;

package/utils/lib/helpers/dom.d.ts

@@ -1,12 +1,82 @@
 import { Subscriber } from 'rxjs';
+/**
+ * Applies a set of CSS styles to an HTML element.
+ *
+ * @param {HTMLElement} element - The element to apply styles to.
+ * @param {Partial<CSSStyleDeclaration | Record<keyof CSSStyleDeclaration, string | null>>} styles - An object containing CSS properties and values to apply.
+ */
 export declare function applyStyles(element: HTMLElement, styles: Partial<CSSStyleDeclaration | Record<keyof CSSStyleDeclaration, string | null>>): void;
+/**
+ * Converts a boolean value to a corresponding attribute string.
+ *
+ * @param {boolean} state - The boolean state to convert.
+ * @returns {string} 'true' if the state is true; otherwise, 'false'.
+ */
 export declare function booleanToAttributeString(state: boolean): string;
+/**
+ * Converts a boolean value to 'true' or null, useful for setting attributes based on boolean conditions.
+ *
+ * @param {boolean} state - The boolean state to convert.
+ * @returns {string | null} 'true' if the state is true; otherwise, null.
+ */
 export declare function booleanToOptionalAttributeString(state: boolean): string | null;
+/**
+ * Converts a numeric value to a pixel string, appending 'px' to the number.
+ *
+ * @param {unknown} value - The value to convert to pixels.
+ * @returns {`${number}px`} The value in pixels, or '0px' if the input is not a number.
+ */
 export declare function px(value: unknown): `${number}px`;
+/**
+ * Generates a CSS translate3d string for given x and y values.
+ *
+ * @param {string | 0} x - The translation value along the x-axis.
+ * @param {string | 0} y - The translation value along the y-axis.
+ * @returns {`translate3d(${string | 0}, ${string | 0}, 0)`} The CSS translate3d value.
+ */
 export declare function cssTranslate(x: string | 0, y: string | 0): `translate3d(${string | 0}, ${string | 0}, 0)`;
+/**
+ * Disables or re-enables CSS transitions on an element.
+ *
+ * @param {HTMLElement} element - The element to modify.
+ * @param {boolean} disabled - Whether to disable CSS transitions.
+ */
 export declare function disableCSSTransitions(element: HTMLElement, disabled: boolean): void;
+/**
+ * Forces the browser to reflow the layout, useful for triggering CSS transitions or animations.
+ *
+ * @param {HTMLElement} element - The element to force a reflow on.
+ */
 export declare function forceLayoutReflow(element: HTMLElement): void;
+/**
+ * Sets an attribute on an HTML element, converting the value to a string if necessary.
+ *
+ * @param {HTMLElement} element - The element to set the attribute on.
+ * @param {string} attribute - The name of the attribute to set.
+ * @param {unknown} value - The value of the attribute; will be converted to a string if it's not null or undefined.
+ */
 export declare function setAttribute(element: HTMLElement, attribute: string, value?: unknown): void;
+/**
+ * Creates a ResizeObserver instance safely, falling back to a dummy if the API is not supported.
+ *
+ * @param {ResizeObserverCallback} callback - The callback to execute when an observed element's size changes.
+ * @returns {ResizeObserver} A ResizeObserver instance or a dummy object with no-op methods if unsupported.
+ */
 export declare function createResizeObserver(callback: ResizeObserverCallback): ResizeObserver;
+/**
+ * Creates a MutationObserver instance safely, falling back to a dummy if the API is not supported.
+ *
+ * @param {Subscriber<MutationRecord>} observer - The RxJS Subscriber to emit next values to.
+ * @param {(mutations: MutationRecord[]) => boolean} callback - The callback that determines whether to notify the observer based on mutations.
+ * @returns {MutationObserver} A MutationObserver instance or a dummy object with no-op methods if unsupported.
+ */
 export declare function createMutationObserver(observer: Subscriber<MutationRecord>, callback: (mutations: MutationRecord[]) => boolean): MutationObserver;
+/**
+ * Checks whether one element contains another in the DOM tree.
+ *
+ * @param {Element | null} parent - The parent element.
+ * @param {Element | null} other - The element to check for containment.
+ * @param {boolean} [inclusive=true] - Whether to consider an element as containing itself.
+ * @returns {boolean} True if the parent contains the other element; false otherwise.
+ */
 export declare function containsElement(parent?: Element | null, other?: Element | null, inclusive?: boolean): boolean;