@odx/angular 6.0.0 → 6.1.0

package/fesm2022/odx-angular.mjs

@@ -13,15 +13,40 @@ function controllerChanges(controllers) {
     const changes$ = pluckFromArray(controllers.filter(isPresent), 'change$');
     return changes$.length > 0 ? merge(...changes$) : EMPTY;
 }
+/**
+ * Sets up change detection for the provided controllers within the context of an Angular component or directive.
+ * It listens for changes from the specified controllers and triggers Angular's change detection mechanism in response.
+ *
+ * @param {...Array<Controller | undefined | null>} controllers - The controllers to monitor for changes.
+ * @returns {Observable<void>} An observable that emits whenever a change occurs in any of the provided controllers.
+ */
 function detectControllerChanges(...controllers) {
     const changeDetector = inject(ChangeDetectorRef);
     return controllerChanges(controllers).pipe(tap(() => changeDetector.markForCheck()));
 }
+/**
+ * An abstract base class representing a controller that can notify observers of changes in its state.
+ * It provides lifecycle hooks for ngOnChanges and ngOnDestroy to manage its internal change observable.
+ */
 class Controller {
     constructor() {
         this.change$$ = new Subject();
+        /**
+         * Represents an observable stream of changes.
+         * @readonly
+         */
         this.change$ = this.change$$.pipe(shareReplay({ bufferSize: 1, refCount: true }));
     }
+    /**
+     * Sets up a controller instance to emit change events and trigger Angular change detection whenever
+     * the controller's state changes. It is a utility method that can be used to initialize controllers
+     * that are managed outside of Angular's DI system.
+     *
+     * @static
+     * @param {Controller | null} controller - The controller instance to set up.
+     * @param {ChangeDetectorRef} changeDetector - The Angular change detector reference to trigger change detection.
+     * @returns {Controller | null} The same controller instance for chaining or null if the controller is not provided.
+     */
     static setup(controller, changeDetector) {
         controllerChanges([controller])
             .pipe(tap(() => changeDetector.markForCheck()))
@@ -46,22 +71,76 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "16.2.12", ngImpo
 
 const DISABLED_CONTROLLER = new InjectionToken('@odx/angular::DisabledWatchedController');
 const DISABLED_INTERNAL_CONTROLLER = new InjectionToken('@odx/angular::DisabledController');
+/**
+ * Directive that provides hierarchical disabled state management for Angular components or directives.
+ * It allows for a disabled state to be inherited from parent components, facilitating the propagation
+ * of disabled states down component trees. This is particularly useful in forms or complex component
+ * structures where nested components need to respond to disabled states dynamically.
+ *
+ * The `DisabledController` works by injecting itself or a parent `DisabledController` instance to determine
+ * the effective disabled state, taking into account both its own state and that of its parents.
+ *
+ * Usage:
+ * Apply the `disabled` attribute, potentially bound to a component property, to use this directive.
+ * The directive can be automatically provided to the component's children by calling the `connect`
+ * static method in the component's providers array.
+ *
+ * @example
+ * ```ts
+ * @Component({
+ *   selector: 'app-custom-input',
+ *   templateUrl: './custom-input.component.html',
+ *   providers: [DisabledController.connect()],
+ *   standalone: true,
+ * })
+ * export class CustomInputComponent {
+ *   constructor(private disabledCtrl: DisabledController) {}
+ * }
+ * ```
+ * ```html
+ * <input [disabled]="disabledCtrl.disabled" />
+ * ```
+ */
 class DisabledController extends Controller {
     constructor() {
         super(...arguments);
         this.parentController = inject(DISABLED_CONTROLLER, { optional: true, skipSelf: true });
         this.isDisabled = false;
+        /**
+         * A reactive representation of the current effective disabled state, considering both
+         * the controller's own state and that of its parent controllers.
+         *
+         * @emits {boolean} - The current disabled state.
+         */
         this.isDisabled$ = this.change$.pipe(map(() => this.disabled), distinctUntilChanged(), shareReplay({ bufferSize: 1, refCount: true }));
     }
+    /**
+     * Sets the disabled state of the current controller. If the state changes, updates the internal
+     * flag.
+     * @param {boolean} value - The new disabled state to be applied.
+     */
     set disabled(value) {
         this.isDisabled = value;
     }
     get disabled() {
         return this.isDisabled || !!this.parentController?.disabled;
     }
+    /**
+     * Retrieves an instance of the `DisabledController` class from the dependency injection container.
+     * If the `DisabledController` is not registered in the container, it returns `null`.
+     *
+     * @returns {DisabledController | null} An instance of the `DisabledController` class or `null` if not found.
+     */
     static inject() {
         return inject(DISABLED_CONTROLLER, { optional: true });
     }
+    /**
+     * Static method to facilitate the injection of the `DisabledController` within Angular's DI system.
+     * This method provides a way to connect a component with its closest `DisabledController` parent,
+     * allowing for disabled state inheritance.
+     *
+     * @returns {Provider[]} An array of providers to enable disabled state management within a component.
+     */
     static connect() {
         return [
             {
@@ -76,6 +155,11 @@ class DisabledController extends Controller {
             },
         ];
     }
+    /**
+     * Sets the disabled state of the current controller and triggers change detection if the state changes.
+     *
+     * @param {boolean} state - The new disabled state to be applied.
+     */
     setDisabledState(state) {
         if (this.disabled !== state) {
             this.disabled = state;
@@ -114,7 +198,45 @@ const ELEMENTS_WITH_READONLY_ATTRIBUTE = {
 };
 const READONLY_CONTROLLER = new InjectionToken('@odx/angular::ReadonlyWatchedController');
 const READONLY_INTERNAL_CONTROLLER = new InjectionToken('@odx/angular::ReadonlyController');
+/**
+ * Directive to manage and propagate the readonly state within Angular components or directives,
+ * particularly useful for form elements like input, textarea, and select. It supports hierarchical
+ * readonly state management, allowing a parent component's readonly state to be inherited by its children.
+ *
+ * The directive leverages Angular's dependency injection system to access parent readonly controllers,
+ * enabling a cascading readonly state. This is beneficial in scenarios where a form or a part of it
+ * should become readonly based on certain conditions.
+ *
+ * Usage:
+ * Apply the `readonly` attribute, potentially bound to a component property, to use this directive.
+ * The directive can automatically provide itself to the component's children by calling the `connect`
+ * static method in the component's providers array.
+ *
+ * @example
+ * ```ts
+ * @Component({
+ *   selector: 'app-custom-input',
+ *   templateUrl: './custom-input.component.html',
+ *   providers: [ReadonlyController.connect()],
+ *   standalone: true,
+ * })
+ * export class CustomInputComponent {
+ *   constructor(private readonlyCtrl: ReadonlyController) {}
+ * }
+ * ```
+ *
+ * Template for CustomInputComponent with conditional readonly state:
+ * ```html
+ * <input [readonly]="readonlyCtrl.readonly" />
+ * ```
+ */
 class ReadonlyController extends Controller {
+    /**
+     * Sets the readonly state of the current controller. If the state changes, updates the internal
+     * flag that controls the rendering of the `readonly` attribute in the host element.
+     *
+     * @param {boolean} value - The new readonly state to be applied.
+     */
     set readonly(value) {
         if (this.isReadonly === value)
             return;
@@ -129,12 +251,30 @@ class ReadonlyController extends Controller {
         this.parentController = inject(READONLY_CONTROLLER, { optional: true, skipSelf: true });
         this.isReadonly = false;
         this.hasReadonlyAttribute = false;
+        /**
+         * An observable that emits the current value of the `isReadonly` property whenever it changes.
+         * The emitted values are distinct and replayed to new subscribers.
+         *
+         * @emits {boolean} The current readonly state of the controller.
+         */
         this.isReadonly$ = this.change$.pipe(map(() => this.isReadonly), distinctUntilChanged(), shareReplay({ bufferSize: 1, refCount: true }));
         this.nodeName = element?.nativeElement.nodeName.toLowerCase() ?? '';
     }
+    /**
+     * Returns an instance of the ReadonlyController or null if it cannot be found.
+     *
+     * @returns {ReadonlyController | null} An instance of the ReadonlyController or null.
+     */
     static inject() {
         return inject(READONLY_CONTROLLER, { optional: true });
     }
+    /**
+     * Static method to facilitate the injection of the `ReadonlyController` within Angular's DI system.
+     * This method provides a way to connect a component with its closest `ReadonlyController` parent,
+     * allowing for readonly state inheritance.
+     *
+     * @returns {Provider} An array of providers to enable readonly state management within a component.
+     */
     static connect() {
         return [
             {
@@ -180,6 +320,25 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "16.2.12", ngImpo
                 args: [{ transform: booleanAttribute }]
             }] } });
 
+/**
+ * Directive to detect clicks outside of an element. When active, it listens for clicks outside
+ * the host element and emits an event through the `odxClickOutside` EventEmitter. This is useful
+ * for handling UI logic that depends on outside clicks, such as closing a dropdown or modal
+ * when the user clicks elsewhere on the page.
+ *
+ * Apply `odxClickOutside` to an element and bind an event handler to react to outside clicks.
+ * Optionally, use `[odxClickOutsideActive]="condition"` to enable or disable the detection dynamically.
+ *
+ * @example
+ * ```html
+ * <div
+ *   odxClickOutside
+ *   (odxClickOutside)="handleClickOutside()"
+ *   [odxClickOutsideActive]="isDropdownOpen">
+ *   <!-- Dropdown content -->
+ * </div>
+ * ```
+ */
 class ClickOutsideDirective {
     constructor() {
         this.element = injectElement();
@@ -192,7 +351,17 @@ class ClickOutsideDirective {
             const clickedOutside = hostElement.isConnected && targetElement.isConnected && !hostElement.contains(targetElement);
             return this.registerEventHandler('mouseup').pipe(debounceTime(0), tap(() => clickedOutside && this.odxClickOutside.emit(event)));
         }));
+        /**
+         * Controls whether the outside click detection is active. When `true`, the directive listens for outside clicks.
+         *
+         * @type {boolean}
+         */
         this.odxClickOutsideActive = true;
+        /**
+         * EventEmitter that emits the native Event object when an outside click is detected.
+         *
+         * @emits {Event}
+         */
         this.odxClickOutside = new EventEmitter();
     }
     ngOnInit() {
@@ -248,9 +417,23 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "16.2.12", ngImpo
                 type: Output
             }] } });
 
+/**
+ * A directive to manage focus within components. It emits events when the host component is focused,
+ * and dynamically updates the `tabindex` attribute to control focusability. This directive is particularly
+ * useful for custom components that require explicit focus management, such as custom input components
+ * or complex interactive components.
+ *
+ * The directive ensures that the component can be focused by setting `tabindex="0"`, making it reachable
+ * via keyboard navigation. When the component gains focus (`focusin`), it becomes non-focusable (`tabindex="-1"`)
+ * to manage focus delegation internally. It restores its focusability (`tabindex="0"`) when losing focus (`focusout`),
+ * allowing it to be focused again in the future.
+ */
 class DelegateFocusDirective {
     constructor() {
         this.tabindex = 0;
+        /**
+         * Emits an event when the element is focused.
+         */
         this.focused = new EventEmitter();
     }
     handleFocus() {
@@ -362,43 +545,109 @@ const Environment = {
     PROD: 'prod'
 };
 
+/**
+ * A service that wraps window and document functionalities, providing Angular-friendly ways to interact with the browser's window object,
+ * manage the document and its title, listen to online/offline events, and perform other browser-related operations.
+ */
 class WindowRef {
     constructor() {
         this.title = inject(Title);
+        /**
+         * Accesses the document object, ensuring Angular compatibility and potential SSR friendliness.
+         */
         this.document = inject(DOCUMENT);
+        /**
+         * Retrieves the native window object, with a fallback to the global window if necessary.
+         * This approach helps ensure compatibility with Angular's SSR features.
+         */
         this.nativeWindow = this.document.defaultView ?? window;
+        /**
+         * An observable that emits the online status of the browser, updating when the browser transitions between online and offline states.
+         */
         this.isOnline$ = fromEvents(this.nativeWindow, 'offline', 'online').pipe(startWith(null), map(() => this.isOnline()), distinctUntilChanged(), shareReplay({ bufferSize: 1, refCount: true }));
+        /**
+         * An observable that emits the current page title upon navigation ends, useful for updating document titles in SPA applications.
+         */
         this.pageTitle$ = (inject(Router, { optional: true })?.events ?? EMPTY).pipe(filter((event) => event instanceof NavigationEnd), startWith(null), debounceTime(0), map(() => this.title.getTitle()), shareReplay({ bufferSize: 1, refCount: true }));
     }
+    /**
+     * Gets the location object of the window.
+     * @returns The location object of the window.
+     */
     get location() {
         return this.nativeWindow.location;
     }
+    /**
+     * Determines if the browser is currently online.
+     * @returns {boolean} True if the browser is online; otherwise, false.
+     */
     isOnline() {
         return this.nativeWindow.navigator.onLine;
     }
+    /**
+     * Retrieves the browser's current language setting, falling back through several browser-specific properties.
+     * @returns {string} The current language setting of the browser.
+     */
     getLanguage() {
         const { language, languages, userLanguage } = this.nativeWindow.navigator;
         return languages?.[0] ?? userLanguage ?? language;
     }
+    /**
+     * Extracts the language code from the browser's current language setting.
+     * @returns {string} The language code part of the browser's language setting.
+     */
     getLanguageCode() {
         return getLanguageCode(this.getLanguage());
     }
+    /**
+     * Returns the origin of the current window location.
+     *
+     * @returns The origin of the current window location.
+     */
     getOrigin() {
         return this.location.origin;
     }
+    /**
+     * Opens a new browser tab or window and navigates to the specified URL.
+     * @param {string | URL} [url] - The URL to open.
+     * @param {string} [target] - The target window or tab.
+     * @param {string} [features] - String that specifies the window features.
+     * @returns {WindowProxy | null} A reference to the newly opened window or null if the call failed.
+     */
     openPage(url, target, features) {
         return this.nativeWindow.open(url, target, features);
     }
+    /**
+     * Reloads the current page.
+     */
     reloadPage() {
         return this.location.reload();
     }
+    /**
+     * Queries the DOM for an element associated with a specific Angular component type.
+     * @template T The component type to query for.
+     * @param {Type<T>} type - The Angular component type.
+     * @returns {HTMLElement | null} The HTML element associated with the component, or null if not found.
+     */
     queryByComponent(type) {
         const componentType = reflectComponentType(type);
         return componentType ? this.nativeWindow.document.querySelector(componentType.selector) : null;
     }
+    /**
+     * Retrieves the value of a CSS variable on a specified element.
+     * @param {string} name - The name of the CSS variable.
+     * @param {HTMLElement} [element=this.document.body] - The element from which to retrieve the CSS variable.
+     * @returns {string} The value of the CSS variable.
+     */
     getCSSVariable(name, element = this.document.body) {
         return this.nativeWindow.getComputedStyle(element).getPropertyValue(`--${name}`).trim();
     }
+    /**
+     * Extracts CSS color styles that match a specific filter from the document's stylesheets.
+     * @param {string} filter - The filter to apply to CSS variable names.
+     * @param {string} [selector=':root'] - The CSS selector to filter by.
+     * @returns {Record<string, string>} A record containing the filtered CSS color styles.
+     */
     getCSSColorStyles(filter, selector = ':root') {
         const selectorFilter = new RegExp(`^${selector}$`);
         const nameFilter = new RegExp(`^--${filter}`);
@@ -429,6 +678,30 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "16.2.12", ngImpo
         }] });
 
 const ODX_DEFAULT_IDENTITY_MATCHER = (item1, item2) => item1 === item2;
+/**
+ * An Angular `InjectionToken` for the `IdentityMatcher` function, allowing for the provision
+ * and injection of custom identity matching logic throughout the application. The token is
+ * provided with a default factory function that returns the `ODX_DEFAULT_IDENTITY_MATCHER`,
+ * which can be overridden with custom logic as needed.
+ *
+ * @type {InjectionToken<IdentityMatcher<unknown>>}
+ *
+ * @example
+ * ```ts
+ * // Providing a custom identity matcher in an Angular module
+ * @NgModule({
+ *   providers: [
+ *     { provide: ODX_IDENTITY_MATCHER, useValue: (item1, item2) => item1.id === item2.id }
+ *   ]
+ * })
+ * class AppModule {}
+ *
+ * // Injecting and using the custom provided identity matcher
+ * constructor(@Inject(ODX_IDENTITY_MATCHER) private identityMatcher: IdentityMatcher<MyType>) {
+ *   console.log(this.identityMatcher({ id: 1 }, { id: 1 })); // Depends on the custom logic provided
+ * }
+ * ```
+ */
 const ODX_IDENTITY_MATCHER = new InjectionToken('@odx/angular::StringHandler', {
     providedIn: 'root',
     factory: () => ODX_DEFAULT_IDENTITY_MATCHER,
@@ -437,12 +710,61 @@ const ODX_IDENTITY_MATCHER = new InjectionToken('@odx/angular::StringHandler', {
 const ODX_DEFAULT_STRING_SEARCH_HANDLER = (item, query) => {
     return item.toLocaleLowerCase().includes(query.toLocaleLowerCase());
 };
+/**
+ * An Angular `InjectionToken` for the `StringSearchHandler` function, allowing for the provision
+ * and injection of custom string search logic throughout the application. This token is provided with
+ * a default factory function that returns the `ODX_DEFAULT_STRING_SEARCH_HANDLER`, which can be overridden
+ * with custom logic as needed.
+ *
+ * @type {InjectionToken<StringSearchHandler>}
+ *
+ * @example
+ * ```ts
+ * // Providing a custom string search handler in an Angular module
+ * @NgModule({
+ *   providers: [
+ *     { provide: ODX_STRING_SEARCH_HANDLER, useValue: (item, query) => item.startsWith(query) }
+ *   ]
+ * })
+ * class AppModule {}
+ *
+ * // Injecting and using the custom provided string search handler
+ * constructor(@Inject(ODX_STRING_SEARCH_HANDLER) private searchHandler: StringSearchHandler) {
+ *   console.log(this.searchHandler('Angular', 'A')); // Depends on the custom logic provided
+ * }
+ * ```
+ */
 const ODX_STRING_SEARCH_HANDLER = new InjectionToken('@odx/angular::StringHandler', {
     providedIn: 'root',
     factory: () => ODX_DEFAULT_STRING_SEARCH_HANDLER,
 });
 
 const ODX_DEFAULT_STRINGIFY = (item) => (isPresent(item) ? String(item) : '');
+/**
+ * An Angular `InjectionToken` for the `StringifyFn` function, allowing the injection of custom
+ * stringification logic throughout an application. By default, it is provided with a factory
+ * function that returns `ODX_DEFAULT_STRINGIFY`. This setup permits easy customization of
+ * how items are converted to strings, facilitating different stringification strategies
+ * for various application needs.
+ *
+ * @type {InjectionToken<StringifyFn<unknown>>}
+ *
+ * @example
+ * ```ts
+ * // Providing a custom stringify function in an Angular module
+ * @NgModule({
+ *   providers: [
+ *     { provide: ODX_STRINGIFY, useValue: (item) => JSON.stringify(item) }
+ *   ]
+ * })
+ * class AppModule {}
+ *
+ * // Injecting and using the custom provided stringify function
+ * constructor(@Inject(ODX_STRINGIFY) private stringify: StringifyFn<unknown>) {
+ *   console.log(this.stringify({ key: 'value' })); // Outputs: '{"key":"value"}'
+ * }
+ * ```
+ */
 const ODX_STRINGIFY = new InjectionToken('@odx/angular::Stringify', {
     providedIn: 'root',
     factory: () => ODX_DEFAULT_STRINGIFY,