@odx/angular 12.26.1 → 13.0.1

package/rxjs/index.d.ts

@@ -1,5 +1,125 @@
-export * from './lib/delay-until';
-export * from './lib/from-element-mutation';
-export * from './lib/from-element-resize';
-export * from './lib/from-events';
-export * from './lib/from-query-list';
+import { Observable, MonoTypeOperatorFunction } from 'rxjs';
+import { HasEventTargetAddRemove } from 'rxjs/internal/observable/fromEvent';
+import { QueryList } from '@angular/core';
+
+/**
+ * Delays the emission of each value from the source Observable by a time span determined by the `delay` function.
+ * If the `notifier` Observable emits before the delay expires, the delayed emission is cancelled.
+ *
+ * This operator is useful for postponing the observable emissions until certain conditions are met,
+ * represented by the passage of time defined by `delay`. It also allows for a way to preemptively
+ * cancel the delay in response to another observable's emission.
+ *
+ * @template T The type of items emitted by the source Observable.
+ * @param {() => number} delay A function that returns the delay (in milliseconds) before the source Observable's values are emitted.
+ * @param {Observable<unknown>} notifier An Observable that cancels the delay when it emits.
+ * @returns {MonoTypeOperatorFunction<T>} An Observable that emits the source Observable's items with a delay if not cancelled.
+ * @example
+ * ```ts
+ * // Delay each number emission by 1 second, unless the 'cancel' button is clicked.
+ * const delayedNumbers$ = of(1, 2, 3).pipe(
+ *   delayUntil(() => 1000, fromEvent(cancelButton, 'click'))
+ * );
+ *
+ * delayedNumbers$.subscribe(console.log);
+ * ```
+ */
+declare function delayUntil<T>(delay: () => number, notifier: Observable<unknown>): MonoTypeOperatorFunction<T>;
+
+/**
+ * Creates an RxJS Observable that emits mutation records for changes in a DOM element's attributes,
+ * child list, and subtree. It uses the `MutationObserver` Web API to observe mutations on the specified
+ * element according to the options provided.
+ *
+ * @param {Element} element The DOM element to observe for mutations.
+ * @param {MutationObserverInit} options An object that specifies which DOM mutations should be reported.
+ * Options include attributes, childList, subtree, attributeOldValue, characterData, characterDataOldValue,
+ * and attributeFilter.
+ * @returns {Observable<MutationRecord>} An Observable that emits a `MutationRecord` each time a mutation
+ * matching the specified options occurs in the observed element.
+ * @example
+ * ```ts
+ * // Observing changes to the child list of an element
+ * const element = document.getElementById('my-element');
+ * const mutationOptions = { childList: true };
+ *
+ * fromElementMutation$(element, mutationOptions).subscribe((mutation) => console.log('Mutation detected:', mutation));
+ * ```
+ * Note: Always remember to unsubscribe from the observable to prevent memory leaks.
+ */
+declare function fromElementMutation$(element: Element, options: MutationObserverInit): Observable<MutationRecord>;
+
+/**
+ * Creates an RxJS Observable that emits an array of `ResizeObserverEntry` objects whenever
+ * the target element's size changes. This function provides a reactive way to observe
+ * and respond to changes in an element's dimensions, using the `ResizeObserver` Web API.
+ *
+ * The observable debounces the emitted values to improve performance and reduce the frequency
+ * of change detection runs in Angular applications. The debounce time can be adjusted via
+ * the `debounceDuration` parameter.
+ *
+ * @param {Element} element The DOM element to observe for size changes.
+ * @param {number} [debounceDuration=50] The time, in milliseconds, to debounce the emitted
+ * values. Defaults to 50ms.
+ * @returns {Observable<ResizeObserverEntry[]>} An Observable that emits the resize events
+ * for the observed element. Each emission is an array of `ResizeObserverEntry` objects, one
+ * for each observed element that experienced a resize.
+ * @example
+ * ```ts
+ * // Observing resize events of an element with a 100ms debounce duration
+ * const element = document.getElementById('resizable-element');
+ * fromElementResize$(element, 100).subscribe((entries) => console.log('Element resized:', entries));
+ * ```
+ *
+ * Always unsubscribe from the observable to clean up resources and prevent memory leaks.
+ */
+declare function fromElementResize$(element: Element, debounceDuration?: number): Observable<ResizeObserverEntry[]>;
+
+/**
+ * Creates an Observable that emits events of a specific type from one or multiple event targets.
+ * It listens to multiple event types on the given target(s) and emits the events through a single
+ * Observable stream, simplifying the handling of related event types.
+ *
+ * @template T The event object type that the Observable will emit.
+ * @param {HasEventTargetAddRemove<T> | HasEventTargetAddRemove<T>[]} target The DOM element(s) or event target(s) to listen on.
+ * @param {...string[]} events The names of the events to listen for on the target(s).
+ * @returns {Observable<T>} An Observable that emits an event each time one of the specified events occurs on the given target(s).
+ *
+ * @example
+ * ```ts
+ * // Listen to both 'click' and 'keyup' events on document
+ * fromEvents(document, 'click', 'keyup').subscribe(event => {
+ *   console.log('Event occurred:', event);
+ * });
+ *
+ * // Listen to 'mousemove' event on multiple elements
+ * const elements = [document.getElementById('first'), document.getElementById('second')];
+ * fromEvents(elements, 'mousemove').subscribe(event => {
+ *   console.log('Mouse moved over:', event.target);
+ * });
+ * ```
+ */
+declare function fromEvents<T>(target: HasEventTargetAddRemove<T> | HasEventTargetAddRemove<T>[], ...events: string[]): Observable<T>;
+
+/**
+ * Creates an Observable from an Angular QueryList. The Observable emits the initial state
+ * of the QueryList and continues to emit updates every time the QueryList changes.
+ * This utility function is useful for integrating Angular's QueryList changes into
+ * the RxJS reactive data flow, allowing developers to apply RxJS operators and
+ * subscriptions to respond to QueryList updates.
+ *
+ * @template T The type of elements contained within the QueryList.
+ * @param {QueryList<T>} queryList The QueryList instance to observe.
+ * @returns {Observable<QueryList<T>>} An Observable that emits the current state of the QueryList
+ * and updates whenever the QueryList changes.
+ * @example
+ * ```ts
+ * // Assuming 'items' is a QueryList of component instances or DOM elements
+ * fromQueryList(items).subscribe(queryList => {
+ *   console.log('QueryList changed:', queryList);
+ * });
+ * ```
+ */
+declare function fromQueryList<T>(queryList: QueryList<T>): Observable<QueryList<T>>;
+
+export { delayUntil, fromElementMutation$, fromElementResize$, fromEvents, fromQueryList };

package/sdk/index.d.ts

@@ -1 +1,74 @@
-export * from './lib/application-environment';
+import * as _angular_platform_browser from '@angular/platform-browser';
+import * as _angular_core from '@angular/core';
+import { InjectionToken, ApplicationRef } from '@angular/core';
+
+/**
+ * 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.
+ */
+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 };
+ * });
+ */
+declare function createHttpApplicationEnvironmentLoader<Data>(handler: (dto: unknown) => Promise<Data>): ApplicationEnvironmentLoader<Data, Parameters<typeof fetch>>;
+/**
+ * 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();
+ * }
+ * ```
+ */
+declare function createApplicationEnvironment<Data, Params extends unknown[]>(loader: ApplicationEnvironmentLoader<Data, Params>): {
+    APPLICATION_ENVIRONMENT: InjectionToken<Data>;
+    injectApplicationEnvironment: () => Data;
+    bootstrapApplicationWithEnvironment: (params: Parameters<typeof loader>, rootComponent: _angular_core.Type<unknown>, options?: _angular_core.ApplicationConfig | undefined, context?: _angular_platform_browser.BootstrapContext | undefined) => Promise<ApplicationRef>;
+    loadApplicationEnvironment: (...args: Parameters<typeof loader>) => Promise<Data>;
+};
+
+export { createApplicationEnvironment, createHttpApplicationEnvironmentLoader };
+export type { ApplicationEnvironmentLoader };

package/theming/index.d.ts

@@ -1,4 +1,213 @@
-export * from './lib/helpers';
-export * from './lib/models';
-export * from './lib/theming.config';
-export * from './lib/theming.service';
+import * as _angular_core from '@angular/core';
+import { EnvironmentProviders } from '@angular/core';
+import { ConfigDependencies, ConfigProvider } from '@odx/angular/utils';
+import * as rxjs from 'rxjs';
+
+/**
+ * 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');
+ * }
+ * ```
+ */
+declare function prefersDarkTheme(view: Window): boolean;
+
+type Theme = (typeof Theme)[keyof typeof Theme];
+declare const Theme: {
+    readonly DARK: "dark";
+    readonly LIGHT: "light";
+};
+declare const availableThemes: ("dark" | "light")[];
+
+/**
+ * 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.');
+ * }
+ * ```
+ */
+declare function resolveTheme(theme?: string | null): Theme | null;
+
+/**
+ * The key used to store the selected theme in `Storage`.
+ * This constant ensures consistent access to the theme setting across the application.
+ */
+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');
+ * ```
+ */
+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.');
+ * }
+ * ```
+ */
+declare function readTheme(storage?: Storage | null): Theme | null;
+
+/**
+ * Defines the structure for theming configuration options in the application.
+ */
+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.
+ */
+declare const ThemingConfig: _angular_core.InjectionToken<Partial<ThemingConfig>>;
+declare const injectThemingConfig: () => ThemingConfig;
+declare const provideThemingConfig: <D extends ConfigDependencies = ConfigDependencies<Partial<ThemingConfig>>>(config: ConfigProvider<Partial<ThemingConfig>, D>) => _angular_core.FactoryProvider | _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],
+ * });
+ * ```
+ */
+declare function provideTheming<D extends ConfigDependencies = ConfigDependencies<ThemingConfig>>(config: ConfigProvider<Partial<ThemingConfig>, D>): EnvironmentProviders;
+
+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.
+ */
+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.
+     *
+     * @emits {Theme} The currently selected theme.
+     */
+    readonly theme$: 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: _angular_core.ɵɵFactoryDeclaration<ThemingService, never>;
+    static ɵprov: _angular_core.ɵɵInjectableDeclaration<ThemingService>;
+}
+
+export { THEME_ATTRIBUTE_NAME, THEME_STORAGE_NAME, Theme, ThemingConfig, ThemingService, availableThemes, injectThemingConfig, prefersDarkTheme, provideTheming, provideThemingConfig, readTheme, resolveTheme, saveTheme };