@acorex/core 21.0.2-next.4 → 21.0.2-next.40

package/types/acorex-core-file.d.ts

@@ -1,6 +1,9 @@
 import * as i1 from '@acorex/core/format';
 import { AXFormatOptions, AXFormatter } from '@acorex/core/format';
 import * as i0 from '@angular/core';
+import { InjectionToken, Type, Provider, ModuleWithProviders } from '@angular/core';
+import * as i2 from '@acorex/core/validation';
+import { AXValidationRuleOptions, AXValidationRuleResult, AXValidationService, AXValidationRule } from '@acorex/core/validation';
 
 interface AXFileSizeFormatterOptions extends AXFormatOptions {
     format: string;
@@ -28,58 +31,283 @@ declare class AXFileSizeFormatter implements AXFormatter {
     static ɵprov: i0.ɵɵInjectableDeclaration<AXFileSizeFormatter>;
 }
 
+/** Human-readable file size (binary units, e.g. `41.5 MB`). */
+declare function formatFileSizeBytes(bytes: number): string;
+
+/** Structured copy payload from {@link AXFileType.copy}. */
+interface AXFileCopyData {
+    /** Primary plain-text value for clipboard or previews. */
+    text: string;
+    /** Optional type-specific metadata for consumers (URLs, names, mime types, …). */
+    meta?: Record<string, unknown>;
+}
+/** Return value of {@link AXFileType.copy} — shorthand string or structured data. */
+type AXFileCopyResult = string | AXFileCopyData | null | undefined;
+/** Resolves clipboard/plain text from a copy result. */
+declare function resolveFileCopyText(result: AXFileCopyResult): string | null;
+
+/** Generic rule executed via {@link AXValidationService}. */
+interface AXFileValidationRule {
+    rule: string;
+    options?: AXValidationRuleOptions;
+}
+/**
+ * Common file constraints shared by {@link AXFileType} and {@link AXFileTypeExtension}.
+ * Extension `validations` are partial and override the parent type field-by-field.
+ */
+interface AXFileValidations {
+    mimeTypes?: string[];
+    minSize?: number;
+    maxSize?: number;
+    rules?: AXFileValidationRule[];
+}
+/** Extension entry; `validations` override the parent {@link AXFileType.validations}. */
+interface AXFileTypeExtension {
+    name: string;
+    title?: string;
+    icon?: string;
+    validations?: Partial<AXFileValidations>;
+}
+/**
+ * Logical file category (image, video, …).
+ *
+ * - With type `validations` set: any file matching those rules is allowed; `extensions` only override when matched.
+ * - With empty / omitted `validations` and `extensions` listed: only those extensions are allowed.
+ */
+interface AXFileType<T = Record<string, (ctx: {
+    readAsDataUrl: (file: File | Blob) => Promise<string>;
+    platformId: object;
+}, ...args: unknown[]) => Promise<unknown> | unknown>> {
+    name: string;
+    title?: string;
+    icon?: string;
+    validations?: AXFileValidations;
+    extensions?: AXFileTypeExtension[];
+    /** Dynamic utility functions available for this file type. */
+    utilities?: T;
+    paste?: () => Promise<unknown>;
+    /**
+     * Produce copyable content from a payload (does not write to the clipboard).
+     * Returns a plain string or {@link AXFileCopyData} with `text` and optional `meta`.
+     */
+    copy?: (payload: unknown) => Promise<AXFileCopyResult> | AXFileCopyResult;
+}
+
+/** Contributes {@link AXFileType} entries (multi provider). */
+declare abstract class AXFileTypeInfoProvider {
+    abstract items(): Promise<AXFileType[]>;
+}
+declare const AX_FILE_TYPE_INFO_PROVIDER: InjectionToken<AXFileTypeInfoProvider[]>;
+declare function provideFileTypeInfoProvider(provider: Type<AXFileTypeInfoProvider>): Provider;
+
+declare class AXFileTypeRegistryService {
+    private readonly validation;
+    private readonly providers;
+    private readonly registeredTypes;
+    private cache;
+    /** Registers or replaces catalog entries (e.g. from feature bootstrap). */
+    registerTypes(types: AXFileType[]): void;
+    invalidateCache(): void;
+    private resolveTypes;
+    getTypes(): Promise<AXFileType[]>;
+    get(name: string): Promise<AXFileType | undefined>;
+    accept(typeNames?: string | string[]): Promise<string>;
+    matchType(file: File): Promise<AXFileType | undefined>;
+    validate(file: File, typeName: string): Promise<AXValidationRuleResult[]>;
+    validateAgainstTypes(file: File, typeNames: string | string[]): Promise<AXValidationRuleResult[]>;
+    validateMany(files: File[], typeNames: string | string[]): Promise<{
+        accepted: File[];
+        rejected: {
+            file: File;
+            errors: AXValidationRuleResult[];
+        }[];
+    }>;
+    private matchesMime;
+    static ɵfac: i0.ɵɵFactoryDeclaration<AXFileTypeRegistryService, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<AXFileTypeRegistryService>;
+}
+
+/** Merges type-level validations with extension overrides (extension wins per field). */
+declare function mergeFileValidations(base: AXFileValidations, override?: Partial<AXFileValidations>): AXFileValidations;
+/** Resolved validations for a type + optional extension. */
+declare function resolveFileValidations(type: AXFileType, extension?: AXFileTypeExtension): AXFileValidations;
+/** True when no mime/size/rules are defined on the type. */
+declare function isEmptyFileValidations(validations?: AXFileValidations): boolean;
+/**
+ * Extension-only mode: empty type `validations` and a non-empty `extensions` list.
+ * Files must match a listed extension; rules come from that extension entry.
+ */
+declare function isExtensionsOnlyType(type: AXFileType): boolean;
+/** File extension from name (lowercase, no dot). */
+declare function getFileExtension(fileName: string): string;
+/** Matching extension entry for a file within a type, if any. */
+declare function findFileTypeExtension(file: File, type: AXFileType): AXFileTypeExtension | undefined;
+
+/** Maps {@link AXFileValidations} to executable validation entries. */
+declare function fileValidationsToRules(validations: AXFileValidations): AXFileValidationRule[];
+/** Failed validation results; empty array means the file is valid. */
+declare function validateFileWithValidations(validation: AXValidationService, file: File, validations: AXFileValidations): Promise<AXValidationRuleResult[]>;
+/** Validates a file against a type; extension rules override when the file name matches. */
+declare function validateFileAgainstType(validation: AXValidationService, file: File, type: AXFileType, extension?: AXFileTypeExtension): Promise<AXValidationRuleResult[]>;
+
+declare const AX_AUDIO_FILE_TYPE: AXFileType;
+declare class AXAudioFileTypeProvider extends AXFileTypeInfoProvider {
+    items(): Promise<AXFileType[]>;
+    static ɵfac: i0.ɵɵFactoryDeclaration<AXAudioFileTypeProvider, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<AXAudioFileTypeProvider>;
+}
+
+/** Extension-only: no type `validations` — only listed extensions are allowed. */
+declare const AX_DOCUMENT_FILE_TYPE: AXFileType;
+declare class AXDocumentFileTypeProvider extends AXFileTypeInfoProvider {
+    items(): Promise<AXFileType[]>;
+    static ɵfac: i0.ɵɵFactoryDeclaration<AXDocumentFileTypeProvider, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<AXDocumentFileTypeProvider>;
+}
+
+declare const AX_FILE_FILE_TYPE: AXFileType;
+declare class AXFileFileTypeProvider extends AXFileTypeInfoProvider {
+    items(): Promise<AXFileType[]>;
+    static ɵfac: i0.ɵɵFactoryDeclaration<AXFileFileTypeProvider, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<AXFileFileTypeProvider>;
+}
+
+declare const AX_IMAGE_FILE_TYPE: AXFileType;
+declare class AXImageFileTypeProvider extends AXFileTypeInfoProvider {
+    items(): Promise<AXFileType[]>;
+    static ɵfac: i0.ɵɵFactoryDeclaration<AXImageFileTypeProvider, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<AXImageFileTypeProvider>;
+}
+
+declare const AX_VIDEO_FILE_TYPE: AXFileType;
+declare class AXVideoFileTypeProvider extends AXFileTypeInfoProvider {
+    items(): Promise<AXFileType[]>;
+    static ɵfac: i0.ɵɵFactoryDeclaration<AXVideoFileTypeProvider, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<AXVideoFileTypeProvider>;
+}
+
+/** Built-in file type provider classes (one logical type per provider). */
+declare const AX_BUILTIN_FILE_TYPE_PROVIDERS: readonly [typeof AXImageFileTypeProvider, typeof AXVideoFileTypeProvider, typeof AXAudioFileTypeProvider, typeof AXFileFileTypeProvider, typeof AXDocumentFileTypeProvider];
+/** Registers all built-in file type providers (image, video, audio, file, document). */
+declare function provideBuiltinFileTypeProviders(): Provider[];
+/** @deprecated Use {@link provideBuiltinFileTypeProviders}. */
+declare const provideDefaultFileTypeProviders: typeof provideBuiltinFileTypeProviders;
+
+interface AXFileMimeTypeValidationRuleOptions extends AXValidationRuleOptions {
+    /** MIME patterns, e.g. `image/*`, `image/png`. */
+    allowed: string[];
+}
+declare module '@acorex/core/validation' {
+    interface AXValidationRuleOptionsMap {
+        fileMimeType: AXFileMimeTypeValidationRuleOptions;
+    }
+}
+declare class AXFileMimeTypeValidationRule implements AXValidationRule {
+    get name(): string;
+    validate(value: File | Blob, options: AXFileMimeTypeValidationRuleOptions): Promise<AXValidationRuleResult>;
+    private matchesMime;
+    static ɵfac: i0.ɵɵFactoryDeclaration<AXFileMimeTypeValidationRule, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<AXFileMimeTypeValidationRule>;
+}
+
+interface AXFileMinSizeValidationRuleOptions extends AXValidationRuleOptions {
+    /** Minimum size in bytes. */
+    minSize: number;
+}
+declare module '@acorex/core/validation' {
+    interface AXValidationRuleOptionsMap {
+        fileMinSize: AXFileMinSizeValidationRuleOptions;
+    }
+}
+declare class AXFileMinSizeValidationRule implements AXValidationRule {
+    get name(): string;
+    validate(value: File | Blob, options: AXFileMinSizeValidationRuleOptions): Promise<AXValidationRuleResult>;
+    static ɵfac: i0.ɵɵFactoryDeclaration<AXFileMinSizeValidationRule, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<AXFileMinSizeValidationRule>;
+}
+
+interface AXFileMaxSizeValidationRuleOptions extends AXValidationRuleOptions {
+    /** Maximum size in bytes. */
+    maxSize: number;
+}
+declare module '@acorex/core/validation' {
+    interface AXValidationRuleOptionsMap {
+        fileMaxSize: AXFileMaxSizeValidationRuleOptions;
+    }
+}
+declare class AXFileMaxSizeValidationRule implements AXValidationRule {
+    get name(): string;
+    validate(value: File | Blob, options: AXFileMaxSizeValidationRuleOptions): Promise<AXValidationRuleResult>;
+    static ɵfac: i0.ɵɵFactoryDeclaration<AXFileMaxSizeValidationRule, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<AXFileMaxSizeValidationRule>;
+}
+
+/** Validation rule classes to register with {@link AXValidationModule}. */
+declare const AX_FILE_VALIDATION_RULES: readonly [typeof AXFileMimeTypeValidationRule, typeof AXFileMinSizeValidationRule, typeof AXFileMaxSizeValidationRule];
+/** Registers file validation rules with {@link AXValidationRegistryService}. */
+declare function provideFileValidationRules(): Provider;
+
+/**
+ * Registers validation rules and optional built-in file type providers.
+ * {@link AXFileTypeRegistryService} and {@link AXFileService} are `providedIn: 'root'`.
+ */
+declare function provideFileTypeSystem(): Provider[];
+
+interface AXFileModuleConfig {
+    fileTypeProviders?: Provider[];
+    includeDefaultFileTypes?: boolean;
+}
 declare class AXFileModule {
+    static forRoot(config?: AXFileModuleConfig): ModuleWithProviders<AXFileModule>;
+    static forChild(config?: AXFileModuleConfig): ModuleWithProviders<AXFileModule>;
     static ɵfac: i0.ɵɵFactoryDeclaration<AXFileModule, never>;
-    static ɵmod: i0.ɵɵNgModuleDeclaration<AXFileModule, never, [typeof i1.AXFormatModule], never>;
+    static ɵmod: i0.ɵɵNgModuleDeclaration<AXFileModule, never, [typeof i1.AXFormatModule, typeof i2.AXValidationModule], never>;
     static ɵinj: i0.ɵɵInjectorDeclaration<AXFileModule>;
 }
 
+interface AXFileChooseOptions {
+    /** Logical type name(s) from {@link AXFileTypeRegistryService}. When set, files are validated against the catalog. */
+    fileType?: string | string[];
+    accept?: string;
+    multiple?: boolean;
+}
 declare class AXFileService {
-    private document;
-    private platformID;
-    /**
-     * Opens a file selection dialog and returns the selected files.
-     *
-     * @param options - Optional configuration for file selection
-     * @param options.accept - File types to accept (e.g., 'image/*', '.pdf')
-     * @param options.multiple - Whether to allow multiple file selection
-     * @returns Promise<File[]> - Promise that resolves with the selected files
-     */
-    choose(options?: {
-        accept?: string;
-        multiple?: boolean;
-    }): Promise<File[]>;
+    private readonly document;
+    private readonly fileTypes;
+    getFileTypes(): Promise<AXFileType[]>;
+    getFileType(name: string): Promise<AXFileType | undefined>;
+    getAcceptAttribute(fileType?: string | string[]): Promise<string>;
+    matchFileType(file: File): Promise<AXFileType | undefined>;
+    validate(file: File, fileType: string | string[]): Promise<AXValidationRuleResult[]>;
+    validateMany(files: File[], fileType: string | string[]): Promise<{
+        accepted: File[];
+        rejected: {
+            file: File;
+            errors: AXValidationRuleResult[];
+        }[];
+    }>;
     /**
-     * Gets the size of a file, blob, or base64 string.
-     *
-     * @param file - The file, blob, or base64 string to get size for
-     * @returns number | false - The size in bytes or false if not a base64 string
-     */
-    blobToBase64: (blob: Blob) => Promise<string>;
-    /**
-     * Gets the size of a file, blob, or base64 string.
-     *
-     * @param file - The file, blob, or base64 string to get size for
-     * @returns number | false - The size in bytes or false if not a base64 string
+     * Opens a file selection dialog.
+     * With `fileType`, returns files that pass catalog validation (`accept` defaults from the catalog).
+     * Without `fileType`, returns all selected files (legacy `accept` / `multiple` only).
      */
+    chooseValidated(options: AXFileChooseOptions): Promise<{
+        accepted: File[];
+        rejected: {
+            file: File;
+            errors: AXValidationRuleResult[];
+        }[];
+    }>;
+    choose(options: AXFileChooseOptions): Promise<File[]>;
+    blobToBase64(blob: Blob): Promise<string>;
     getSize(file: File | Blob | string): number | false;
-    /**
-     * Checks if a string is a valid base64 string.
-     *
-     * @param base64 - The string to check
-     * @returns boolean - True if the string is a valid base64 string
-     */
     isBase64(base64: string): boolean;
-    /**
-     * Gets the size of a base64 string in bytes.
-     *
-     * @param base64 - The base64 string to get size for
-     * @returns number - The size in bytes
-     */
     getBase64Size(base64: string): number;
+    private resolveChooseOptions;
+    private openFileDialog;
     static ɵfac: i0.ɵɵFactoryDeclaration<AXFileService, never>;
     static ɵprov: i0.ɵɵInjectableDeclaration<AXFileService>;
 }
 
-export { AXFileModule, AXFileService, AXFileSizeFormatter };
-export type { AXFileSizeFormatterOptions };
+export { AXAudioFileTypeProvider, AXDocumentFileTypeProvider, AXFileFileTypeProvider, AXFileMaxSizeValidationRule, AXFileMimeTypeValidationRule, AXFileMinSizeValidationRule, AXFileModule, AXFileService, AXFileSizeFormatter, AXFileTypeInfoProvider, AXFileTypeRegistryService, AXImageFileTypeProvider, AXVideoFileTypeProvider, AX_AUDIO_FILE_TYPE, AX_BUILTIN_FILE_TYPE_PROVIDERS, AX_DOCUMENT_FILE_TYPE, AX_FILE_FILE_TYPE, AX_FILE_TYPE_INFO_PROVIDER, AX_FILE_VALIDATION_RULES, AX_IMAGE_FILE_TYPE, AX_VIDEO_FILE_TYPE, fileValidationsToRules, findFileTypeExtension, formatFileSizeBytes, getFileExtension, isEmptyFileValidations, isExtensionsOnlyType, mergeFileValidations, provideBuiltinFileTypeProviders, provideDefaultFileTypeProviders, provideFileTypeInfoProvider, provideFileTypeSystem, provideFileValidationRules, resolveFileCopyText, resolveFileValidations, validateFileAgainstType, validateFileWithValidations };
+export type { AXFileChooseOptions, AXFileCopyData, AXFileCopyResult, AXFileMaxSizeValidationRuleOptions, AXFileMimeTypeValidationRuleOptions, AXFileMinSizeValidationRuleOptions, AXFileModuleConfig, AXFileSizeFormatterOptions, AXFileType, AXFileTypeExtension, AXFileValidationRule, AXFileValidations };

package/types/acorex-core-locale.d.ts

@@ -146,8 +146,12 @@ declare class AXLocaleModule {
 declare class AXLocaleService {
     private provider;
     private config;
+    private document;
+    private platformId;
     private _activeProfile;
     activeProfile: i0.Signal<AXLocaleProfile>;
+    /** Whether the active locale uses right-to-left layout. */
+    readonly isRtl: i0.Signal<boolean>;
     profileChanged$: rxjs.Observable<AXLocaleProfile>;
     private originalProfile;
     /**
@@ -157,6 +161,7 @@ declare class AXLocaleService {
      * @returns Promise<void> - Resolves when the profile is loaded and activated.
      */
     setProfile(localeCode: string): Promise<void>;
+    private applyDocumentDirection;
     /**
      *
      */

package/types/acorex-core-translation.d.ts

@@ -113,13 +113,20 @@ declare class AXTranslationService {
     readonly langChanges$: Observable<string>;
     readonly currentLocale$: Observable<string>;
     constructor();
+    private preloadLocaleTranslations;
+    private peekTranslation;
     setActiveLang(lang: AXTranslateLang): void;
     getActiveLang(): AXTranslateLang;
     getDefaultLang(): AXTranslateLang;
+    /**
+     * @deprecated Use {@link translateAsync} instead. `translateAsync` now accepts
+     * `string | AXMultiLanguageMap | null | undefined` and performs the same
+     * multi-language resolution in addition to translation.
+     */
     resolve(value: string | AXMultiLanguageMap | null | undefined, locale?: string): string;
     toLocaleMap(value: string | AXMultiLanguageMap | null | undefined, activeLocale?: string): AXMultiLanguageMap;
     translate$(value: string | AXMultiLanguageMap | null | undefined, options?: AXTranslateOptions): Observable<string>;
-    translateAsync(text: string, options?: AXTranslateOptions): Promise<string>;
+    translateAsync(text: string | AXMultiLanguageMap | null | undefined, options?: AXTranslateOptions): Promise<string>;
     translateSync(text: string, options?: AXTranslateOptions & {
         waitForLoad?: boolean;
         timeoutMs?: number;

package/types/acorex-core-utils.d.ts

@@ -105,28 +105,6 @@ declare class AXHtmlUtil {
      * Utility function to find scrollable parent elements
      */
     static getScrollableParents(element: HTMLElement): HTMLElement[];
-    /**
-     * Resolves the closest ACoreX size for `element`: both the **HTMLElement** and the
-     * **class name** ({@link AX_SIZE_CLASSES}).
-     *
-     * 1. **Subtree of `element` only** — If any node under `element` (including itself)
-     *    has a size class, returns the **deepest** such node. This prefers an inner scope
-     *    (e.g. `ax-lg` on a child) when you start from a wrapper like `#ref` on a parent.
-     * 2. **Ancestors only** — Otherwise walks from `parentElement` up to `document.body`
-     *    (inclusive) and returns the **nearest** ancestor that has a size class.
-     *
-     * Step 2 never scans unrelated siblings (e.g. other `ax-button` instances elsewhere on
-     * the page), which would happen if an entire `body` subtree were searched.
-     *
-     * If an element has several size tokens (unusual), the first match in
-     * {@link AX_SIZE_CLASSES} order is used.
-     */
-    static findClosestAxSize(element: HTMLElement | null | undefined): AXClosestAxSizeMatch | null;
-    private static resolveClosestAxSizeElement;
-    private static getAxSizeClassOnElement;
-    private static elementHasAxSizeClass;
-    /** Deepest node under `root` (including `root`) whose `classList` contains a size token. */
-    private static findDeepestAxSizeInSubtree;
 }
 
 declare function AXAutoUnsubscriber(): (constructor: any) => void;