@acorex/core 21.0.0-next.6 → 21.0.0-next.61

package/format/index.d.ts

@@ -10,7 +10,16 @@ interface AXFormatOptionsMap {
 
 declare abstract class AXFormatter {
     abstract get name(): string;
+    /**
+     * Formats a value with optional options.
+     * @returns The formatted value.
+     */
     abstract format(value: unknown, options?: AXFormatOptions | string): string;
+    /**
+     * Optional update interval in milliseconds for formatters that need periodic updates.
+     * If specified, the format pipe will automatically refresh the formatted value at this interval.
+     */
+    updateInterval?: number;
 }
 
 declare class AXFormatterDirective implements OnInit {
@@ -25,7 +34,16 @@ declare class AXFormatterDirective implements OnInit {
 declare class AXFormatPipe implements PipeTransform {
     private formatService;
     private eventService;
+    private formatterRegistry;
     private triggers;
+    /**
+     * Angular pipe for formatting values reactively. Re-evaluates when system events (such as language change) occur.
+     *
+     * @param value - The input value to format.
+     * @param name - The formatter name.
+     * @param options - Optional options specific to the formatter.
+     * @returns Observable<string> - Emits the formatted string and updates on system events.
+     */
     transform(value: unknown, name: string, options?: AXFormatOptions | string): Observable<string>;
     static ɵfac: i0.ɵɵFactoryDeclaration<AXFormatPipe, never>;
     static ɵpipe: i0.ɵɵPipeDeclaration<AXFormatPipe, "format", true>;
@@ -35,7 +53,19 @@ interface AXFormatModuleConfigs {
     formatters: (new () => AXFormatter)[];
 }
 declare class AXFormatModule {
+    /**
+     * Configures the module for the root injector, optionally registering custom formatters.
+     *
+     * @param configs - Optional configuration containing custom formatter classes.
+     * @returns ModuleWithProviders<AXFormatModule>
+     */
     static forRoot(configs?: AXFormatModuleConfigs): ModuleWithProviders<AXFormatModule>;
+    /**
+     * Configures the module for a feature injector, optionally registering custom formatters.
+     *
+     * @param configs - Optional configuration containing custom formatter classes.
+     * @returns ModuleWithProviders<AXFormatModule>
+     */
     static forChild(configs?: AXFormatModuleConfigs): ModuleWithProviders<AXFormatModule>;
     /**
      * @ignore
@@ -52,9 +82,11 @@ declare class AXFormatterRegistryService {
     register(...plugins: (new () => AXFormatter)[]): void;
     get formatters(): AXFormatter[];
     /**
-     * Resolves a formatter by its name.
-     * @param name The name of the formatter.
-     * @returns The formatter if found, otherwise throws an error.
+     * Resolves a formatter instance by its name.
+     *
+     * @param name - The formatter name.
+     * @returns AXFormatter - The resolved formatter instance.
+     * @throws Error when no formatter with the given name exists.
      */
     get(name: string): AXFormatter;
     static ɵfac: i0.ɵɵFactoryDeclaration<AXFormatterRegistryService, never>;
@@ -64,8 +96,27 @@ declare class AXFormatService {
     private pluginRegistry;
     private renderSubject;
     onRender: rxjs.Observable<void>;
+    /**
+     * Triggers a render event for listeners that care about formatting updates.
+     *
+     * @returns void - Emits on the onRender observable.
+     */
     render(): void;
+    /**
+     * Formats a value using the specified formatter name.
+     *
+     * @param value - The input value to format.
+     * @param formatter - The formatter name to use (e.g., 'number', 'string').
+     * @param options - Optional options specific to the formatter.
+     * @returns string - The formatted string.
+     */
     format(value: unknown, formatter: string, options?: any): string;
+    /**
+     * Starts a fluent formatting chain.
+     *
+     * @param value - The input value to format.
+     * @returns AXFormatFluent - A fluent API object for chaining.
+     */
     format(value: unknown): AXFormatFluent;
     static ɵfac: i0.ɵɵFactoryDeclaration<AXFormatService, never>;
     static ɵprov: i0.ɵɵInjectableDeclaration<AXFormatService>;
@@ -91,7 +142,7 @@ interface AXNumberFormatterOptions extends AXFormatOptions {
     zeroPadLength?: number;
     locale?: string;
 }
-declare module '../format.types' {
+declare module "./index" {
     interface AXFormatOptionsMap {
         number: AXNumberFormatterOptions;
     }
@@ -108,7 +159,7 @@ declare class AXNumberFormatter implements AXFormatter {
 interface AXStringFormatterOptions extends AXFormatOptions {
     [key: string]: any;
 }
-declare module '../format.types' {
+declare module "./index" {
     interface AXFormatOptionsMap {
         string: AXStringFormatterOptions;
     }

package/image/index.d.ts

@@ -3,6 +3,14 @@ import * as i0 from '@angular/core';
 declare class AXImageService {
     private document;
     private platformID;
+    /**
+     * Resizes an image (File or HTMLImageElement) to fit within maxSize while preserving aspect ratio.
+     * @param options.maxSize Maximum width/height in pixels.
+     * @param options.source File or HTMLImageElement as source.
+     * @param options.type Output MIME type (default 'image/png').
+     * @param options.quality Output quality (0..1) for supported formats.
+     * @returns Promise<Blob> of the resized image.
+     */
     resize(options: {
         maxSize: number;
         source: HTMLImageElement | File;

package/locale/index.d.ts

@@ -15,12 +15,20 @@ declare module '@acorex/core/format' {
 }
 
 interface AXLocaleProfile {
+    /**
+     * Returns the locale info.
+     * @returns The locale info.
+     */
     localeInfo: {
         code: string;
         language: string;
         region: string;
         timezone: string;
     };
+    /**
+     * Returns the calendar.
+     * @returns The calendar.
+     */
     calendar: {
         system: 'gregorian' | 'solar-hijri' | string;
         week: {
@@ -31,6 +39,10 @@ interface AXLocaleProfile {
             format24Hour: boolean;
         };
     };
+    /**
+     * Returns the formats.
+     * @returns The formats.
+     */
     formats: {
         date: FormatPattern;
         time: FormatPattern;
@@ -46,6 +58,10 @@ interface AXLocaleProfile {
             postalCode: string;
         };
     };
+    /**
+     * Returns the units.
+     * @returns The units.
+     */
     units: {
         temperature: 'celsius' | 'fahrenheit';
         distance: 'kilometers' | 'miles';
@@ -55,6 +71,10 @@ interface AXLocaleProfile {
         area: 'square-meters' | 'square-feet';
         custom?: Record<string, string>;
     };
+    /**
+     * Returns the i18n meta.
+     * @returns The i18n meta.
+     */
     i18nMeta: {
         fallbackLocales?: string[];
         supportedLanguages?: string[];
@@ -82,9 +102,31 @@ declare class AXLocaleProfileProviderService {
     private resolvedCache;
     private isInitialized;
     private init;
+    /**
+     * Returns all available locale profiles by loading each registered provider.
+     *
+     * @returns Promise<AXLocaleProfile[]>
+     */
     getList(): Promise<AXLocaleProfile[]>;
+    /**
+     * Loads or returns from cache the locale profile associated with the given code.
+     *
+     * @param localeCode - The locale code to resolve.
+     * @returns Promise<AXLocaleProfile | undefined>
+     */
     getByLocale(localeCode: string): Promise<AXLocaleProfile | undefined>;
+    /**
+     * Clears caches and reloads all providers.
+     *
+     * @returns Promise<void>
+     */
     reload(): Promise<void>;
+    /**
+     * Indicates whether a loader has been registered for the given locale code.
+     *
+     * @param localeCode - The locale code to check.
+     * @returns boolean - True if a loader exists.
+     */
     has(localeCode: string): boolean;
     static ɵfac: i0.ɵɵFactoryDeclaration<AXLocaleProfileProviderService, never>;
     static ɵprov: i0.ɵɵInjectableDeclaration<AXLocaleProfileProviderService>;
@@ -108,13 +150,37 @@ declare class AXLocaleService {
     activeProfile: i0.Signal<AXLocaleProfile>;
     profileChanged$: rxjs.Observable<AXLocaleProfile>;
     private originalProfile;
+    /**
+     * Loads and activates a locale profile by its code (e.g., 'en-US', 'fa-IR').
+     *
+     * @param localeCode - Locale identifier to load.
+     * @returns Promise<void> - Resolves when the profile is loaded and activated.
+     */
     setProfile(localeCode: string): Promise<void>;
     /**
      *
      */
     constructor();
+    /**
+     * Applies overrides to the active profile using a deep-merge object.
+     *
+     * @param profile - Partial profile object whose properties override the active profile.
+     * @returns void
+     */
     apply(profile: Partial<AXLocaleProfile>): void;
+    /**
+     * Applies a single value override at the given path (dot notation).
+     *
+     * @param path - Dot-notated path (e.g., 'formats.date.short').
+     * @param value - The value to set at the path.
+     * @returns void
+     */
     apply(path: string, value: any): void;
+    /**
+     * Resets the active profile to its original loaded state (clears overrides).
+     *
+     * @returns void
+     */
     reset(): void;
     static ɵfac: i0.ɵɵFactoryDeclaration<AXLocaleService, never>;
     static ɵprov: i0.ɵɵInjectableDeclaration<AXLocaleService>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@acorex/core",
-  "version": "21.0.0-next.6",
+  "version": "21.0.0-next.61",
   "peerDependencies": {
     "@angular/common": "^20.0.0",
     "@angular/core": "^20.0.0",
@@ -88,13 +88,13 @@
       "types": "./translation/index.d.ts",
       "default": "./fesm2022/acorex-core-translation.mjs"
     },
-    "./utils": {
-      "types": "./utils/index.d.ts",
-      "default": "./fesm2022/acorex-core-utils.mjs"
-    },
     "./validation": {
       "types": "./validation/index.d.ts",
       "default": "./fesm2022/acorex-core-validation.mjs"
+    },
+    "./utils": {
+      "types": "./utils/index.d.ts",
+      "default": "./fesm2022/acorex-core-utils.mjs"
     }
   }
 }

package/pipes/index.d.ts

@@ -4,6 +4,12 @@ import { DomSanitizer, SafeHtml, SafeStyle, SafeScript, SafeUrl, SafeResourceUrl
 
 declare class AXSafePipe implements PipeTransform {
     protected sanitizer: DomSanitizer;
+    /**
+     * Marks values as safe for Angular binding via DomSanitizer.
+     * @param value The value to sanitize.
+     * @param type One of 'html' | 'style' | 'script' | 'url' | 'resourceUrl'.
+     * @throws Error when type is invalid.
+     */
     transform(value: any, type: string): SafeHtml | SafeStyle | SafeScript | SafeUrl | SafeResourceUrl;
     static ɵfac: i0.ɵɵFactoryDeclaration<AXSafePipe, never>;
     static ɵpipe: i0.ɵɵPipeDeclaration<AXSafePipe, "safe", true>;

package/platform/index.d.ts

@@ -59,12 +59,33 @@ declare class AXPlatform {
     isRtl(): boolean;
     isLandscape(): boolean;
     isPortrate(): boolean;
+    /**
+     * Checks whether the current environment matches the given platform/browser/technology/screen size keyword.
+     *
+     * @param name - One of AXPlatforms | AXBrowsers | AXTechnologies | AXScreenSizes.
+     */
     is(name: AXPlatforms | AXBrowsers | AXTechnologies | AXScreenSizes): boolean;
     get screenSize(): AXScreenSizes;
+    /**
+     * Switches to light mode and persists it.
+     * @returns 'light'
+     */
     switchLightMode(): string;
+    /**
+     * Switches to dark mode and persists it.
+     * @returns 'dark'
+     */
     switchDarkMode(): string;
     switchSystemMode(): void;
+    /**
+     * Reads persisted theme preference and applies it (returns the effective mode).
+     * @returns AXThemeMode
+     */
     autoDetectThemeMode(): "light" | "dark" | "system";
+    /**
+     * Sets theme mode explicitly and persists it.
+     * @param mode - Desired theme mode.
+     */
     setThemeMode(mode: AXThemeMode): void;
     private setFullHeightRatio;
     private autoSystemModeDetection;

package/storage/index.d.ts

@@ -122,11 +122,42 @@ declare class AXCookieStorageService {
 declare const AX_LOCALSTORAGE_SECRET_KEY: InjectionToken<string>;
 declare class AXLocalStorageService implements AXStorage {
     private secret_key;
+    /**
+     * Reads a value from localStorage and parses JSON.
+     *
+     * @param key - Storage key
+     * @returns T | null
+     */
     get<T = unknown>(key: string): T;
+    /**
+     * Writes a JSON-serialized value to localStorage.
+     *
+     * @param key - Storage key
+     * @param value - Value to persist
+     */
     set<T = unknown>(key: string, value: T): void;
     clear(): void;
+    /**
+     * Removes a single entry by key from localStorage.
+     *
+     * @param key - Storage key
+     */
     removeItem(key: string): void;
+    /**
+     * Encrypts the JSON-serialized value using AES and stores it.
+     * Requires providing AX_LOCALSTORAGE_SECRET_KEY.
+     *
+     * @param key - Storage key
+     * @param value - Value to encrypt and store
+     */
     setWithEncryption<T = unknown>(key: string, value: T): void;
+    /**
+     * Reads the encrypted value, decrypts it using AES and parses JSON.
+     * Requires providing AX_LOCALSTORAGE_SECRET_KEY.
+     *
+     * @param key - Storage key
+     * @returns T | null
+     */
     getWithEncription<T = unknown>(key: string): T;
     static ɵfac: i0.ɵɵFactoryDeclaration<AXLocalStorageService, never>;
     static ɵprov: i0.ɵɵInjectableDeclaration<AXLocalStorageService>;

package/validation/index.d.ts

@@ -34,7 +34,7 @@ type AXCallbackValidation<T> = (value: T, options?: AXCallbackValidationRuleOpti
 interface AXCallbackValidationRuleOptions<T> extends AXValidationRuleOptions {
     validate: AXCallbackValidation<T>;
 }
-declare module '../validation.types' {
+declare module "./index" {
     interface AXValidationRuleOptionsMap {
         callback: AXCallbackValidationRuleOptions<unknown>;
     }
@@ -49,7 +49,7 @@ declare class AXCallbackValidationRule<T> implements AXValidationRule {
 interface AXRegexValidationRuleOptions extends AXValidationRuleOptions {
     pattern: string | RegExp;
 }
-declare module '../validation.types' {
+declare module "./index" {
     interface AXValidationRuleOptionsMap {
         regex: AXRegexValidationRuleOptions;
     }
@@ -64,7 +64,7 @@ declare class AXRegexValidationRule implements AXValidationRule {
 
 interface AXRequiredValidationRuleOptions extends AXValidationRuleOptions {
 }
-declare module '../validation.types' {
+declare module "./index" {
     interface AXValidationRuleOptionsMap {
         required: AXRequiredValidationRuleOptions;
     }
@@ -81,7 +81,7 @@ interface AXLengthValidationRuleOptions extends AXValidationRuleOptions {
     min: number;
     max: number;
 }
-declare module '../validation.types' {
+declare module "./index" {
     interface AXValidationRuleOptionsMap {
         length: AXLengthValidationRuleOptions;
     }
@@ -96,7 +96,7 @@ declare class AXLengthValidationRule implements AXValidationRule {
 interface AXMaxLengthValidationRuleOptions extends AXValidationRuleOptions {
     value: number;
 }
-declare module '../validation.types' {
+declare module "./index" {
     interface AXValidationRuleOptionsMap {
         maxLength: AXMaxLengthValidationRuleOptions;
     }
@@ -111,7 +111,7 @@ declare class AXMaxLengthValidationRule implements AXValidationRule {
 interface AXMinLengthValidationRuleOptions extends AXValidationRuleOptions {
     value: number;
 }
-declare module '../validation.types' {
+declare module "./index" {
     interface AXValidationRuleOptionsMap {
         minLength: AXMinLengthValidationRuleOptions;
     }
@@ -128,7 +128,7 @@ interface AXBetweenValidationRuleOptions<T = number | Date> extends AXValidation
     upperValue: T;
     inclusive?: boolean;
 }
-declare module '../validation.types' {
+declare module "./index" {
     interface AXValidationRuleOptionsMap {
         between: AXBetweenValidationRuleOptions;
     }
@@ -144,7 +144,7 @@ interface AXEqualValidationRuleOptions extends AXValidationRuleOptions {
     value: any;
     not?: boolean;
 }
-declare module '../validation.types' {
+declare module "./index" {
     interface AXValidationRuleOptionsMap {
         equal: AXEqualValidationRuleOptions;
     }
@@ -160,7 +160,7 @@ interface AXGreaterThanValidationRuleOptions extends AXValidationRuleOptions {
     value: number;
     inclusive?: boolean;
 }
-declare module '../validation.types' {
+declare module "./index" {
     interface AXValidationRuleOptionsMap {
         greaterThan: AXGreaterThanValidationRuleOptions;
     }
@@ -176,7 +176,7 @@ interface AXLessThanValidationRuleOptions extends AXValidationRuleOptions {
     value: number;
     inclusive?: boolean;
 }
-declare module '../validation.types' {
+declare module "./index" {
     interface AXValidationRuleOptionsMap {
         lessThan: AXLessThanValidationRuleOptions;
     }
@@ -230,6 +230,10 @@ declare class AXValidationRegistryService {
 declare class AXValidationService {
     private translationService;
     private pluginRegistry;
+    /**
+     * Validates a value with optional options.
+     * @returns Promise<AXValidationRuleResult>
+     */
     validate(ruleName: string, value: unknown, options?: AXValidationRuleOptions): Promise<AXValidationRuleResult>;
     ruleFor(value: unknown): AXValidationRuleChain;
     static ɵfac: i0.ɵɵFactoryDeclaration<AXValidationService, never>;