@odx/angular 6.0.0 → 6.0.1

package/fesm2022/odx-angular-utils.mjs

@@ -7,6 +7,57 @@ export { coerceArray, coerceCssPixelValue, coerceElement, coerceStringArray } fr
 import { deepmerge } from '@odx/angular/internal';
 import { startWith, map, shareReplay, distinctUntilChanged, filter, concatAll, share } from 'rxjs/operators';
 
+/**
+ * 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
+ * ```
+ */
 function Pure(_target, propertyKey, { get, enumerable, value }) {
     if (get) {
         return {
@@ -44,49 +95,143 @@ function Pure(_target, propertyKey, { get, enumerable, value }) {
     };
 }
 
+/**
+ * Checks if the given value is a `ViewContainerRef`.
+ *
+ * @param {unknown} value - The value to check.
+ * @returns {value is ViewContainerRef} `true` if the value is a `ViewContainerRef`, otherwise `false`.
+ */
 function isViewContainer(value) {
     return isFunction(value?.createComponent);
 }
+/**
+ * Checks if the given value is a `TemplateRef`.
+ *
+ * @template T - The embedded view type.
+ * @param {unknown} value - The value to check.
+ * @returns {value is TemplateRef<T>} `true` if the value is a `TemplateRef`, otherwise `false`.
+ */
 function isTemplateRef(value) {
     return value instanceof TemplateRef;
 }
+/**
+ * Checks if the given value is an Angular component class.
+ *
+ * @template T - The component class type.
+ * @param {unknown} value - The value to check.
+ * @returns {value is Type<T>} `true` if the value is a component class, otherwise `false`.
+ */
 function isComponent(value) {
     return isFunction(value);
 }
+/**
+ * Checks if the given value is a string.
+ *
+ * @param {unknown} value - The value to check.
+ * @returns {value is string} `true` if the value is a string, otherwise `false`.
+ */
 function isString(value) {
     return typeof value === 'string';
 }
+/**
+ * Checks if the given value is a non-empty string.
+ *
+ * @param {unknown} value - The value to check.
+ * @returns {value is string} `true` if the value is a non-empty string, otherwise `false`.
+ */
 function isNonEmptyString(value) {
     return isString(value) && value.length > 0;
 }
+/**
+ * Checks if the given value is a boolean.
+ *
+ * @param {unknown} value - The value to check.
+ * @returns {value is boolean} `true` if the value is a boolean, otherwise `false`.
+ */
 function isBoolean(value) {
     return value === true || value === false;
 }
+/**
+ * Checks if the given value is a function.
+ *
+ * @param {unknown} value - The value to check.
+ * @returns {value is CallableFunction} `true` if the value is a function, otherwise `false`.
+ */
 function isFunction(value) {
     return typeof value === 'function';
 }
+/**
+ * Checks if the given value is present (not null or undefined).
+ *
+ * @template T - The value type.
+ * @param {T | null | undefined} value - The value to check.
+ * @returns {value is NonNullable<T>} `true` if the value is present, otherwise `false`.
+ */
 function isPresent(value) {
     return value !== null && value !== undefined;
 }
+/**
+ * Checks if the given value is a number.
+ *
+ * @param {unknown} value - The value to check.
+ * @returns {value is number} `true` if the value is a number, otherwise `false`.
+ */
 function isNumber(value) {
     return typeof value === 'number';
 }
 
+/**
+ * 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.
+ */
 function applyStyles(element, styles) {
     Object.assign(element.style, styles);
 }
+/**
+ * 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'.
+ */
 function booleanToAttributeString(state) {
     return booleanToOptionalAttributeString(state) ?? 'false';
 }
+/**
+ * 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.
+ */
 function booleanToOptionalAttributeString(state) {
     return state ? 'true' : 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.
+ */
 function px(value) {
     return isNumber(value) ? `${value}px` : '0px';
 }
+/**
+ * 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.
+ */
 function cssTranslate(x, y) {
     return `translate3d(${x}, ${y}, 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.
+ */
 function disableCSSTransitions(element, disabled) {
     if (disabled) {
         applyStyles(element, { transition: 'none' });
@@ -96,9 +241,21 @@ function disableCSSTransitions(element, disabled) {
         applyStyles(element, { transition: null });
     }
 }
+/**
+ * Forces the browser to reflow the layout, useful for triggering CSS transitions or animations.
+ *
+ * @param {HTMLElement} element - The element to force a reflow on.
+ */
 function forceLayoutReflow(element) {
     element.offsetHeight;
 }
+/**
+ * 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.
+ */
 function setAttribute(element, attribute, value) {
     if (isString(value) || isNumber(value)) {
         element.setAttribute(attribute, value.toString());
@@ -107,6 +264,12 @@ function setAttribute(element, attribute, value) {
         element.toggleAttribute(attribute, !!value);
     }
 }
+/**
+ * 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.
+ */
 function createResizeObserver(callback) {
     try {
         return new ResizeObserver(callback);
@@ -115,6 +278,13 @@ function createResizeObserver(callback) {
         return { observe: () => void 0, disconnect: () => void 0, unobserve: () => void 0 };
     }
 }
+/**
+ * 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.
+ */
 function createMutationObserver(observer, callback) {
     try {
         return new MutationObserver((mutations) => {
@@ -127,6 +297,14 @@ function createMutationObserver(observer, callback) {
         return { disconnect: () => void 0, observe: () => void 0, takeRecords: () => [] };
     }
 }
+/**
+ * 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.
+ */
 function containsElement(parent, other, inclusive = true) {
     if (!parent || !other)
         return false;
@@ -135,6 +313,44 @@ function containsElement(parent, other, inclusive = true) {
     return parent.contains(other);
 }
 
+/**
+ * Creates a MonoTypeOperatorFunction that automatically unsubscribes from observables when the host component or service is destroyed.
+ * It uses Angular's `DestroyRef` to detect when the component or service is destroyed and triggers the unsubscription at that point.
+ * This utility function helps in managing subscriptions and prevents memory leaks by ensuring observables are unsubscribed when no longer needed.
+ *
+ * @returns A function that returns a `MonoTypeOperatorFunction<T>`, which can be used in an RxJS pipe to automatically unsubscribe
+ * based on the component's or service's lifecycle.
+ *
+ * @example
+ * ```ts
+ * // In an Angular component or service
+ * import { Component } from '@angular/core';
+ * import { Observable } from 'rxjs';
+ * import { untilDestroyed } from './path/to/untilDestroyed';
+ *
+ * @Component({
+ *   selector: 'app-example',
+ *   template: `<div>Example Component</div>`,
+ * })
+ * export class ExampleComponent {
+ *   private readonly takeUntilDestroyed = untilDestroyed();
+ *
+ *   constructor() {
+ *     const exampleObservable$ = new Observable(observer => {
+ *       // Observable logic here
+ *     });
+ *
+ *     exampleObservable$.pipe(
+ *       this.takeUntilDestroyed(),
+ *     ).subscribe(data => {
+ *       // Subscription logic here
+ *     });
+ *   }
+ *
+ *   // No need to manually implement ngOnDestroy to unsubscribe
+ * }
+ * ```
+ */
 function untilDestroyed() {
     const destroyRef = inject(DestroyRef);
     return () => takeUntilDestroyed(destroyRef);
@@ -144,12 +360,28 @@ function reactiveBinding(updateFn) {
     const takeUntilDestroyed = untilDestroyed();
     return (source$) => source$.pipe(tap((state) => updateFn(state)), takeUntilDestroyed());
 }
+/**
+ * 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.
+ */
 function reactiveClassBinding(source$, cssClass) {
     const { nativeElement } = injectElement();
     if (source$) {
         source$.pipe(reactiveBinding((state) => nativeElement.classList.toggle(cssClass, !!state))).subscribe();
     }
 }
+/**
+ * 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.
+ */
 function reactiveAttributeBinding(source$, ...attributes) {
     const { nativeElement } = injectElement();
     if (source$) {
@@ -162,12 +394,32 @@ function reactiveAttributeBinding(source$, ...attributes) {
             .subscribe();
     }
 }
+/**
+ * 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.
+ */
 function injectElement() {
     return inject(ElementRef);
 }
+/**
+ * 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.
+ */
 function trackByIndex(index) {
     return index;
 }
+/**
+ * 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.
+ */
 function trackById(_, { id }) {
     return id;
 }
@@ -181,8 +433,10 @@ function trackById(_, { id }) {
  * @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']
+ * ```
  */
 function pluckFromArray(arr, key) {
     return arr.map((value) => value[key]);
@@ -195,8 +449,10 @@ function pluckFromArray(arr, key) {
  * @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
+ * ```
  */
 function orderBy(key, direction = 'ASC') {
     return (a, b) => {
@@ -218,6 +474,26 @@ function orderBy(key, direction = 'ASC') {
     };
 }
 
+/**
+ * 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/"
+ * ```
+ */
 function buildUrl(...args) {
     return args.join('/').replace(/(^.*)(https?:\/\/)|(\/)+/g, '$2$3');
 }
@@ -239,35 +515,87 @@ 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);
+ * ```
  */
 function buildWebsiteUrl(...segments) {
     return buildUrl(DRAEGER_WEBSITE_URL, ...segments);
 }
 
+/**
+ * The HTTP 'Etag' header, used for web cache validation.
+ */
 const HTTP_ETAG_HEADER = 'Etag';
+/**
+ * The HTTP 'If-None-Match' header, used in conditional requests to compare against the ETag.
+ */
 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.
+ */
 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();
+ * ```
+ */
 class CacheStorageClient {
     constructor(cacheKey, cacheStorage = window.caches) {
         this.cacheKey = cacheKey;
         this.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.
+     */
     async delete(request) {
         const cache = await this.getCache();
         return cache.delete(request);
     }
+    /**
+     * Deletes all entries from the cache.
+     *
+     * @returns {Promise<void>} A promise that resolves when all entries have been deleted.
+     */
     async deleteAll() {
         const cache = await this.getCache();
         for (const key of await cache.keys()) {
             await cache.delete(key);
         }
     }
+    /**
+     * 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.
+     */
     async request(requestInfo, shouldDelete = ({ status }) => status >= 400 && status < 500) {
         const cache = await this.getCache();
         const request = await this.prepareRequest(cache, requestInfo);
@@ -303,10 +631,54 @@ class CacheStorageClient {
     }
 }
 
+/**
+ * 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']
+ * ```
+ */
 function arrayAttribute(value) {
     return coerceArray(value);
 }
 
+/**
+ * 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);
+ * ```
+ */
 function debounce(func, delay, immediate = false) {
     let timeout = null;
     return function (...args) {
@@ -328,15 +700,68 @@ function debounce(func, delay, immediate = false) {
     };
 }
 
+/**
+ * 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
+ * ```
+ */
 function deferFn(fn) {
     setTimeout(fn, 0);
 }
 
 let uniqueIdCache = {};
+/**
+ * Generates a unique identifier for a given key. If the key has previously been used,
+ * the function increments a counter associated with that key to ensure uniqueness.
+ * The generated ID is in the format of `${key}-${counter}`.
+ *
+ * @param {string} key - The key for which to generate a unique identifier.
+ * @returns {string} A unique identifier string based on the provided key.
+ *
+ * @example
+ * ```ts
+ * const id1 = getUniqueId('component');
+ * console.log(id1); // Outputs: "component-1"
+ *
+ * const id2 = getUniqueId('component');
+ * console.log(id2); // Outputs: "component-2"
+ * ```
+ */
 function getUniqueId(key) {
     uniqueIdCache[key] = (uniqueIdCache[key] ?? 0) + 1;
     return `${key}-${uniqueIdCache[key]}`;
 }
+/**
+ * Clears the cache used by `getUniqueId` to generate unique identifiers. This function
+ * resets all counters associated with each key, effectively restarting the generation
+ * of unique IDs from their initial state.
+ *
+ * This can be useful in scenarios such as testing or when starting a new session that
+ * requires resetting the state of unique ID generation.
+ *
+ * @example
+ * ```ts
+ * getUniqueId('component'); // Returns "component-1"
+ * getUniqueId('component'); // Returns "component-2"
+ * clearUniqueIdCache();
+ * getUniqueId('component'); // Returns "component-1" after cache reset
+ * ```
+ */
 function clearUniqueIdCache() {
     uniqueIdCache = {};
 }
@@ -412,10 +837,47 @@ const Side = {
     LEFT: 'left',
 };
 
+/**
+ * Extracts the side part from a position string. The position format generally combines
+ * a side (e.g., "top", "bottom", "left", "right") with an optional alignment
+ * (e.g., "left", "center", "right" for vertical positions or "top", "middle", "bottom" for horizontal positions).
+ *
+ * @param {Position} position - The position string from which to extract the side.
+ * @returns {Side} The side part of the position, indicating the general placement direction.
+ *
+ * @example
+ * ```ts
+ * // Extracting the side from a position with alignment
+ * console.log(getSide('top-left')); // Outputs: 'top'
+ *
+ * // Extracting the side from a simple position
+ * console.log(getSide('bottom')); // Outputs: 'bottom'
+ * ```
+ */
 function getSide(position) {
     return position.split('-')[0];
 }
 
+/**
+ * Determines the axis associated with a given position. The function first extracts the side from the position,
+ * then evaluates whether that side corresponds to the X-axis (left or right) or the Y-axis (top or bottom).
+ *
+ * @param {Position} position - The position string, which includes a side (top, bottom, left, right) and possibly an alignment.
+ * @returns {Axis} The axis (X or Y) associated with the given position's side.
+ *
+ * @example
+ * ```ts
+ * // Determining the axis for different positions
+ * console.log(getAxis('top-left')); // Outputs: 'Y'
+ * console.log(getAxis('right'));    // Outputs: 'X'
+ *
+ * // Using getAxis in UI element positioning logic
+ * const elementPosition = 'bottom';
+ * const axis = getAxis(elementPosition);
+ * // Assuming a function that adjusts UI elements based on the axis
+ * adjustElementAlongAxis(axis);
+ * ```
+ */
 function getAxis(position) {
     const side = getSide(position);
     switch (side) {
@@ -428,11 +890,49 @@ function getAxis(position) {
     }
 }
 
+/**
+ * Extracts the language code from a language string that may include both a language and a region code.
+ * The function supports language strings formatted with either a hyphen (`-`) or an underscore (`_`) as the separator.
+ *
+ * @param {string} language - The complete language string, potentially including both language and region codes.
+ * @returns {string} The extracted language code, converted to lower case.
+ *
+ * @example
+ * ```ts
+ * // Extracting language code from a language-region string
+ * console.log(getLanguageCode('en-US')); // Outputs: 'en'
+ * console.log(getLanguageCode('zh_CN')); // Outputs: 'zh'
+ *
+ * // Handling language codes without region codes
+ * console.log(getLanguageCode('fr'));    // Outputs: 'fr'
+ * ```
+ */
 function getLanguageCode(language) {
     const [languageCode] = language.split(/-|_/);
     return languageCode?.toLowerCase();
 }
 
+/**
+ * Determines the opposite side for a given position. This function is useful for scenarios
+ * where you need to dynamically calculate the positioning or alignment opposite to the current one,
+ * such as inverting tooltips, popovers, or any UI elements that adjust based on available viewport space.
+ *
+ * @param {Position} position - The position string, which includes a side and possibly an alignment.
+ * @returns {Side} The opposite side relative to the provided position's side.
+ *
+ * @example
+ * ```ts
+ * // Getting the opposite side of a given position
+ * console.log(getOppositeSide('top-left')); // Outputs: 'bottom'
+ * console.log(getOppositeSide('right'));    // Outputs: 'left'
+ *
+ * // Using getOppositeSide to adjust UI elements
+ * const currentSide = 'left';
+ * const newPosition = getOppositeSide(currentSide);
+ * // Assuming an element's position or orientation needs to be dynamically updated
+ * updateElementPosition(newPosition);
+ * ```
+ */
 function getOppositeSide(position) {
     switch (getSide(position)) {
         case Side.TOP:
@@ -446,13 +946,82 @@ function getOppositeSide(position) {
     }
 }
 
+/**
+ * Checks if a given value is a valid URL matcher, which can be either a string or a regular expression.
+ * This function serves as a type guard to facilitate URL matching operations by verifying the type of the filter.
+ *
+ * @param {unknown} value - The value to check for being a valid URL matcher.
+ * @returns {value is string | RegExp} `true` if the value is a string or RegExp, indicating it can be used for URL matching; otherwise, `false`.
+ *
+ * @example
+ * ```ts
+ * // Checking a string URL matcher
+ * console.log(isUrlMatcher('https://example.com')); // true
+ *
+ * // Checking a RegExp URL matcher
+ * console.log(isUrlMatcher(/https:\/\/example\.com/)); // true
+ *
+ * // Checking a non-matcher value
+ * console.log(isUrlMatcher(123)); // false
+ * ```
+ */
 function isUrlMatcher(value) {
     return isString(value) || value instanceof RegExp;
 }
+/**
+ * Determines if a given URL matches a specified filter, which can be either a string or a regular expression.
+ * For string filters, the function checks if the URL starts with the filter value. For RegExp filters,
+ * it checks if the URL matches the regular expression pattern.
+ *
+ * @param {string} url - The URL to be checked against the filter.
+ * @param {string | RegExp} filter - The filter used to match the URL, which can be a prefix string or a RegExp pattern.
+ * @returns {boolean} `true` if the URL matches the filter; otherwise, `false`.
+ *
+ * @example
+ * ```ts
+ * // Matching a URL with a string filter
+ * console.log(matchUrl('https://example.com/page', 'https://example.com')); // true
+ *
+ * // Matching a URL with a RegExp filter
+ * console.log(matchUrl('https://example.com/page', /example\.com\/page/)); // true
+ *
+ * // A non-matching example
+ * console.log(matchUrl('https://example.com/page', 'https://another.com')); // false
+ * ```
+ */
 function matchUrl(url, filter) {
     return isString(filter) ? url.startsWith(filter) : !!url.match(filter);
 }
 
+/**
+ * Checks if the specified property or properties have changed in the current change detection cycle.
+ * Optionally ignores changes that occur during the first change detection cycle (e.g., initialization).
+ *
+ * @template U - The component or directive class.
+ * @template T - The type representing the changes, typically `NgChanges<U>`.
+ * @template K - The key or keys representing the properties to check for changes.
+ * @param {T} changes - The `NgChanges` object containing information about all changes.
+ * @param {K | K[]} keyOrKeys - The property name(s) to check for changes.
+ * @param {boolean} [ignoreFirstChange=true] - Whether to ignore changes that occur during the first change detection cycle.
+ * @returns {boolean} `true` if the specified property or properties have changed, otherwise `false`.
+ *
+ * @example
+ * ```ts
+ * // Example usage within an Angular component's `ngOnChanges` method
+ * ngOnChanges(changes: NgChanges<MyComponent>): void {
+ *   if (hasChanged(changes, 'name')) {
+ *     console.log('Name has changed');
+ *   }
+ * }
+ *
+ * // Checking multiple properties for changes
+ * ngOnChanges(changes: NgChanges<MyComponent>): void {
+ *   if (hasChanged(changes, ['name', 'age'], false)) {
+ *     console.log('Name or age has changed (including first change)');
+ *   }
+ * }
+ * ```
+ */
 function hasChanged(changes, keyOrKeys, ignoreFirstChange = true) {
     if (Array.isArray(keyOrKeys)) {
         for (const key of keyOrKeys) {
@@ -467,6 +1036,35 @@ function hasChanged(changes, keyOrKeys, ignoreFirstChange = true) {
     }
 }
 
+/**
+ * Provides a configuration object or a factory for creating the configuration object, optionally applying a transformation function.
+ * This utility simplifies the process of defining and injecting configuration objects throughout an Angular application.
+ *
+ * @template T - The type of the configuration object.
+ * @template D - The dependencies required by the configuration factory, if any.
+ * @param {InjectionToken<T> | string} token - The injection token or string token associated with the configuration.
+ * @param {ConfigProvider<T, D>} config - The configuration object or a factory provider that produces the configuration.
+ * @param {ConfigTransformFn<T>} [transform=() => ({}))] - An optional transformation function to apply to the configuration object.
+ * @returns {FactoryProvider | ValueProvider} - An Angular provider object for the given configuration.
+ *
+ * @example
+ * ```ts
+ * // Define a simple configuration object
+ * const appConfig = { apiEndpoint: 'https://api.example.com' };
+ *
+ * // Provide the configuration with an optional transformation function
+ * provideConfig(appConfigToken, appConfig, (config) => ({
+ *   ...config,
+ *   apiEndpoint: `${config.apiEndpoint}/v2`,
+ * }));
+ *
+ * // Using a factory provider for dynamic configuration
+ * provideConfig(appConfigToken, {
+ *   useFactory: (envService) => ({ apiEndpoint: envService.getApiEndpoint() }),
+ *   deps: [EnvironmentService],
+ * });
+ * ```
+ */
 function provideConfig(token, config, transform = () => ({})) {
     const prepareConfig = (value) => deepmerge(value, transform(value));
     if ('useFactory' in config) {
@@ -487,6 +1085,33 @@ function mergeConfig(token, defaultValue) {
     const parentConfig = inject(token, { skipSelf: true, optional: true }) ?? {};
     return deepmerge(defaultValue, parentConfig, config);
 }
+/**
+ * Generates a set of configuration-related tokens and utility functions for managing configuration in an Angular application.
+ * This function creates a standardized way to define, provide, and inject configurations, including defaults and transformations.
+ *
+ * @template T - The type of the configuration object.
+ * @template N - The name of the configuration, used to generate token names and utility functions.
+ * @param {N} name - The name of the configuration.
+ * @param {string} prefix - A prefix for the injection token to ensure uniqueness across the application.
+ * @param {T} defaultValue - The default value for the configuration.
+ * @param {ConfigTransformFn<T>} [transform] - An optional transformation function to be applied to the configuration.
+ * @returns An object containing the generated injection token, default configuration, and utility functions for the configuration.
+ *
+ * @example
+ * ```ts
+ * // Create configuration tokens and utilities for "appConfig" with a default value and optional transform function
+ * const { appConfigConfig, provideAppConfigConfig } = createConfigTokens('appConfig', 'myPrefix', { debug: false }, (config) => ({
+ *   ...config,
+ *   debug: true, // Enable debug mode by default
+ * }));
+ *
+ * // Later, in a module or component, provide the customized configuration
+ * @NgModule({
+ *   providers: [provideAppConfigConfig({ apiEndpoint: 'https://api.example.com' })]
+ * })
+ * class AppModule {}
+ * ```
+ */
 function createConfigTokens(name, prefix, defaultValue, transform) {
     const configName = `${name}Config`;
     const defaultConfigName = `${name}DefaultConfig`;
@@ -505,6 +1130,13 @@ function createConfigTokens(name, prefix, defaultValue, transform) {
 function isQueueItemId(value) {
     return isString(value) || isNumber(value);
 }
+/**
+ * A class representing a queue structure with advanced functionalities including adding, removing,
+ * updating items, and observing changes through RxJS observables. It supports generic queue item types,
+ * allowing for flexible usage across different contexts.
+ *
+ * @template T - The type of items stored in the queue. Each item must extend an object containing a unique `id`.
+ */
 class Queue {
     constructor() {
         this.queue = new Map();
@@ -512,29 +1144,82 @@ class Queue {
         this.values = [];
         this.firstItem = null;
         this.lastItem = null;
+        /**
+         * An observable that emits when an item is added to the queue.
+         * @type {Observable<T>}
+         */
         this.onAdd$ = this.createEventObserver('add');
+        /**
+         * An observable that emits when an item in the queue is updated.
+         * @type {Observable<T>}
+         */
         this.onUpdate$ = this.createEventObserver('update');
+        /**
+         * An observable that emits when an item is removed from the queue.
+         * @type {Observable<T>}
+         */
         this.onRemove$ = this.createEventObserver('remove');
+        /**
+         * An observable representing the current state of the queue as an array of items.
+         * @type {Observable<QueueItem<T>[]>}
+         */
         this.value$ = this.events$$.pipe(startWith(() => void 0), map(() => this.values), shareReplay({ bufferSize: 1, refCount: true }));
+        /**
+         * An observable that emits the current size of the queue.
+         * @type {Observable<number>}
+         */
         this.size$ = this.value$.pipe(map(() => this.size), distinctUntilChanged(), shareReplay({ bufferSize: 1, refCount: true }));
     }
+    /**
+     * Gets the size of the queue.
+     * @returns The number of elements in the queue.
+     */
     get size() {
         return this.queue.size;
     }
+    /**
+     * Checks if the specified item is the first item in the queue.
+     * @param {QueueItem<T>} item - The item to check.
+     * @returns {boolean} - Returns `true` if the item is the first item in the queue, `false` otherwise.
+     */
     isFirst({ id }) {
         return this.firstItem?.id === id;
     }
+    /**
+     * Checks if the specified item is the last item in the queue.
+     * @param {QueueItem<T>} item - The item to check.
+     * @returns {boolean} - Returns true if the item is the last item, otherwise returns false.
+     */
     isLast({ id }) {
         return this.lastItem?.id === id;
     }
+    /**
+     * Retrieves a queue item from the queue based on the provided item or item ID.
+     * @param itemOrId - The queue item or item ID to retrieve.
+     * @returns The queue item if found, or `null` if not found.
+     */
     get(itemOrId) {
         const id = isQueueItemId(itemOrId) ? itemOrId.toString() : itemOrId.id.toString();
         return this.queue.get(id) ?? null;
     }
+    /**
+     * Adds an item to the queue, optionally emitting an event.
+     *
+     * @param {QueueItem<T>} item - The item to add.
+     * @param {boolean} [emitEvent=true] - Whether to emit an event for this action.
+     * @returns {QueueItem<T>} The item added to the queue.
+     */
     add(item, emitEvent = true) {
         this.remove(item, false);
         return this.addMany([item], emitEvent)[0];
     }
+    /**
+     * Adds multiple items to the queue.
+     *
+     * @param items - An array of items to be added to the queue.
+     * @param emitEvent - (Optional) A boolean indicating whether to emit an event after adding the items. Default is true.
+     * @returns An array of added items.
+     */
     addMany(items, emitEvent = true) {
         const addedItems = [];
         const updatedItems = [];
@@ -555,9 +1240,22 @@ class Queue {
         }
         return items;
     }
+    /**
+     * Removes an item from the queue.
+     *
+     * @param itemOrId - The item or ID of the item to be removed.
+     * @param emitEvent - Whether to emit an event after removing the item. Default is `true`.
+     * @returns The removed item, or `null` if the item was not found.
+     */
     remove(itemOrId, emitEvent = true) {
         return this.removeMany([itemOrId], emitEvent)[0];
     }
+    /**
+     * Removes multiple items from the queue based on the provided item or item IDs.
+     * @param itemOrIds - An array of QueueItem or QueueItemId objects representing the items to be removed.
+     * @param emitEvent - A boolean indicating whether to emit an event after removing the items. Default is true.
+     * @returns An array of removed QueueItem objects or null values.
+     */
     removeMany(itemOrIds, emitEvent = true) {
         const items = itemOrIds.map((itemOrId) => this.get(itemOrId)).filter(Boolean);
         const removedItems = [];
@@ -570,11 +1268,21 @@ class Queue {
         this.notify({ type: 'remove', items: removedItems }, emitEvent);
         return items;
     }
+    /**
+     * Clears the queue by removing all items.
+     *
+     * @param emitEvent - Whether to emit an event after clearing the queue. Default is true.
+     */
     clear(emitEvent = true) {
         const items = this.toArray();
         this.queue.clear();
         this.notify({ type: 'remove', items }, emitEvent);
     }
+    /**
+     * Returns an array representation of the queue.
+     *
+     * @returns An array containing all the items in the queue.
+     */
     toArray() {
         return this.values;
     }