ngx-kit 8.5.0 → 9.0.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ngx-kit",
-  "version": "8.5.0",
+  "version": "9.0.1",
   "description": "Angular input components",
   "author": "Mohammadreza Samani <mr.samani1368@gmail.com>",
   "license": "MIT",
@@ -13,7 +13,43 @@
     "url": "https://github.com/mr-samani/ngx-kit/issues"
   },
   "keywords": [
-    "angular"
+    "angular",
+    "i18n",
+    "translate",
+    "signals",
+    "lazy",
+    "scopes",
+    "input-color",
+    "color-picker",
+    "gradient-picker",
+    "select-angle",
+    "date-picker",
+    "calendar",
+    "file",
+    "drop-zone",
+    "image-viewer",
+    "draggable",
+    "resizable",
+    "kanban-view",
+    "drag-drop",
+    "shadow",
+    "message",
+    "notify",
+    "alert",
+    "dialog",
+    "modal",
+    "time-picker",
+    "tooltip",
+    "data-table",
+    "table",
+    "pagination",
+    "drop-zone",
+    "image-editor",
+    "media-control",
+    "media-player",
+    "audio-player",
+    "infinit-scroll",
+    "virtual-scroll"
   ],
   "peerDependencies": {
     "@angular/common": ">=22.0.0",
@@ -23,6 +59,9 @@
     "tslib": "^2.3.0"
   },
   "sideEffects": false,
+  "bin": {
+    "ngx-lazy-i18n-extract": "./lazy-i18n/bin/extract.mjs"
+  },
   "module": "fesm2022/ngx-kit.mjs",
   "typings": "types/ngx-kit.d.ts",
   "exports": {
@@ -93,6 +132,10 @@
       "types": "./types/ngx-kit-infinite-scroll.d.ts",
       "default": "./fesm2022/ngx-kit-infinite-scroll.mjs"
     },
+    "./lazy-i18n": {
+      "types": "./types/ngx-kit-lazy-i18n.d.ts",
+      "default": "./fesm2022/ngx-kit-lazy-i18n.mjs"
+    },
     "./media-control": {
       "types": "./types/ngx-kit-media-control.d.ts",
       "default": "./fesm2022/ngx-kit-media-control.mjs"

package/types/ngx-kit-lazy-i18n.d.ts

@@ -0,0 +1,281 @@
+import * as i0 from '@angular/core';
+import { InjectionToken, Type, PipeTransform, Signal, EnvironmentProviders } from '@angular/core';
+import { Observable } from 'rxjs';
+import { CanActivateChildFn } from '@angular/router';
+
+/** A (possibly nested) translation file as returned by the server. */
+interface Dictionary {
+    [key: string]: string | number | boolean | null | Dictionary | Array<unknown>;
+}
+type Params = Record<string, unknown>;
+type TranslateFn = (key: string, params?: Params) => string;
+type MissingHandler = (key: string, lang: string) => string;
+type Transpiler = (value: string, params: Params | undefined, lang: string) => string;
+interface I18nLoader {
+    /** `scope === undefined` means the global file. */
+    load(lang: string, scope?: string): Observable<Dictionary> | Promise<Dictionary>;
+}
+/**
+ * Every option is optional so the library can be provided at startup and completed later
+ * (for example after your own APP_INITIALIZER has fetched the language list from the backend):
+ * see `I18nService.init()` / `I18nService.configure()`.
+ */
+interface I18nConfig {
+    /** All supported languages. Required before the first language is activated. */
+    langs?: string[];
+    /** Language used when nothing is stored or detected. Required before the first language is activated. */
+    defaultLang?: string;
+    /** Looked up (in order) when a key is empty/missing in the active language. */
+    fallbackLangs?: string[];
+    /** Default `'key'` (returns the key itself). */
+    missing?: 'key' | 'empty' | MissingHandler;
+    /** Log each missing key once. Default: `isDevMode()`. */
+    warnMissing?: boolean;
+    /** Replace the default `{{ name }}` interpolation (ICU, plurals, ...). */
+    transpile?: Transpiler;
+    /** Custom loader class (must be `@Injectable({providedIn:'root'})` or constructible without args). Default: HTTP. Provide-time only. */
+    loader?: Type<I18nLoader>;
+    /** Default HTTP loader: base URL. Default `'/i18n'` -> `/i18n/fa.json`, `/i18n/setting/fa.json`. Slashes are normalised. */
+    baseUrl?: string;
+    /** Default HTTP loader: file extension appended to the URL, e.g. `'.json'`. Default `'.json'`; use `''` for none. */
+    fileExtension?: string;
+    /** Default HTTP loader: full control over the URL. */
+    url?: (lang: string, scope?: string) => string;
+    /** Retries per failed request. Default `1`. */
+    retries?: number;
+    /** localStorage key used to remember the language. `null` disables. Default `'lazy-i18n.lang'`. */
+    storageKey?: string | null;
+    /** Pick the initial language from `navigator.languages` when nothing is stored. Default `false`. */
+    detectBrowserLang?: boolean;
+    /** Keep `<html lang dir>` in sync. Default `true`. */
+    manageDocument?: boolean;
+    /**
+     * Activate the initial language in an APP_INITIALIZER created by `provideI18n()`.
+     * Default: `true` when both `langs` and `defaultLang` are given to `provideI18n()`, otherwise `false`
+     * (then you call `I18nService.init()` yourself, typically from your own initializer).
+     * Provide-time only.
+     */
+    autoInit?: boolean;
+}
+/** Options that can be changed after the app has started. */
+type I18nRuntimeConfig = Omit<I18nConfig, 'loader' | 'autoInit'>;
+/** `I18nService.init()` options: runtime config + the language to start with. */
+interface I18nInitOptions extends I18nRuntimeConfig {
+    /** Preferred starting language (e.g. the user's saved language from the backend). Ignored if not in `langs`. */
+    lang?: string;
+}
+/** Defaults applied by `provideI18n()`. */
+declare const I18N_DEFAULTS: I18nConfig;
+declare const I18N_CONFIG: InjectionToken<I18nConfig>;
+declare const I18N_LOADER: InjectionToken<I18nLoader>;
+
+/**
+ * `{{ 'orders.title' | tr }}`  /  `{{ 'hello' | tr: { name } }}`
+ *
+ * Impure on purpose (it must follow signals), but memoised: when key, params and the
+ * service revision are unchanged it returns the cached string in O(1) with no lookup.
+ */
+declare class TrPipe implements PipeTransform {
+    private readonly svc;
+    private k?;
+    private p?;
+    private rev;
+    private out;
+    transform(key: string | null | undefined, params?: Params): string;
+    static ɵfac: i0.ɵɵFactoryDeclaration<TrPipe, never>;
+    static ɵpipe: i0.ɵɵPipeDeclaration<TrPipe, "tr", true>;
+}
+
+interface TrContext {
+    $implicit: TranslateFn;
+    t: TranslateFn;
+    lang: Signal<string>;
+}
+/**
+ * Structural directive. The view is created ONCE; `t` reads signals, so only the bindings that use it update.
+ *
+ *   <ng-container *tr="let t; prefix: 'orders'">
+ *     <h1>{{ t('title') }}</h1>            <!-- orders.title -->
+ *   </ng-container>
+ */
+declare class TrDirective {
+    private readonly tpl;
+    private readonly vcr;
+    private readonly svc;
+    private readonly prefix;
+    /** `prefix: 'orders'` in the microsyntax. */
+    set trPrefix(v: string | undefined);
+    static ngTemplateContextGuard(_dir: TrDirective, _ctx: unknown): _ctx is TrContext;
+    constructor();
+    static ɵfac: i0.ɵɵFactoryDeclaration<TrDirective, never>;
+    static ɵdir: i0.ɵɵDirectiveDeclaration<TrDirective, "[tr],[translate]", never, { "trPrefix": { "alias": "trPrefix"; "required": false; }; }, {}, never, never, true, never>;
+}
+/**
+ * Attribute directive.
+ *   <span trKey="orders.title"></span>
+ *   <input trKey="form.name" trAttr="placeholder" />
+ *   <p trKey="hello" [trParams]="{ name: user.name }"></p>
+ */
+declare class TrKeyDirective {
+    private readonly key;
+    private readonly params;
+    private readonly attr;
+    private readonly prefix;
+    set trKey(v: string | undefined);
+    set trParams(v: Params | undefined);
+    set trAttr(v: string | undefined);
+    set trPrefix(v: string | undefined);
+    constructor();
+    static ɵfac: i0.ɵɵFactoryDeclaration<TrKeyDirective, never>;
+    static ɵdir: i0.ɵɵDirectiveDeclaration<TrKeyDirective, "[trKey]", never, { "trKey": { "alias": "trKey"; "required": false; }; "trParams": { "alias": "trParams"; "required": false; }; "trAttr": { "alias": "trAttr"; "required": false; }; "trPrefix": { "alias": "trPrefix"; "required": false; }; }, {}, never, never, true, never>;
+}
+
+/** Flatten a nested dictionary into `target` (dot-separated keys). Non-string leaves are stringified. */
+declare function flatten(dict: Dictionary, target?: Map<string, string>, onConflict?: (key: string) => void, prefix?: string): Map<string, string>;
+/** `Hello {{ name }}` + `{name:'Ali'}` -> `Hello Ali`. Unknown placeholders are left untouched. */
+declare function interpolate(text: string, params?: Params): string;
+/** Identity function the extractor recognises: `const k = marker('orders.title')`. */
+declare function marker<T extends string>(key: T): T;
+/**
+ * Build `{base}/{scope}/{lang}{ext}` without ever producing `undefined`, `//` or a trailing slash problem:
+ *   ("/i18n",            undefined, "fa", ".json") -> "/i18n/fa.json"
+ *   ("https://x.com/",   "setting", "fa", "json")  -> "https://x.com/setting/fa.json"
+ *   (undefined | "",     undefined, "fa")          -> "/fa"
+ * The protocol part of `base` ("https://") is left alone.
+ */
+declare function buildI18nUrl(base: string | null | undefined, scope: string | null | undefined, lang: string, ext?: string | null | undefined): string;
+
+/**
+ * Default loader: GET `{baseUrl}/{lang}{ext}` and `{baseUrl}/{scope}/{lang}{ext}`.
+ * Goes through your HttpClient interceptors.
+ * Config is read on every request, so values supplied later via `I18nService.init()` /
+ * `configure()` (for example `baseUrl`) are picked up.
+ */
+declare class HttpI18nLoader implements I18nLoader {
+    private readonly http;
+    private readonly cfg;
+    load(lang: string, scope?: string): Observable<Dictionary>;
+    static ɵfac: i0.ɵɵFactoryDeclaration<HttpI18nLoader, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<HttpI18nLoader>;
+}
+
+declare class I18nService {
+    private readonly cfg;
+    private readonly loader;
+    private readonly doc;
+    private readonly _lang;
+    private readonly _rev;
+    private readonly _langs;
+    private readonly _ready;
+    /** Active language (reactive). */
+    readonly lang: Signal<string>;
+    /** Bumps whenever the active language or any dictionary changes. */
+    readonly revision: Signal<number>;
+    readonly dir: Signal<"rtl" | "ltr">;
+    /** Supported languages (a signal: they may be supplied after startup via `init()` / `configure()`). */
+    readonly langs: Signal<readonly string[]>;
+    /** `true` once the first language has been activated. Handy for a splash screen. */
+    readonly ready: Signal<boolean>;
+    private get fallbacks();
+    private get warn();
+    private readonly dicts;
+    private readonly loaded;
+    private readonly inflight;
+    private readonly scopes;
+    private readonly pending;
+    private readonly warned;
+    private useToken;
+    /** Translate. Reads signals, so it is reactive inside `computed`, `effect` and templates. */
+    t(key: string, params?: Params): string;
+    /** Same as `t`, but never creates a reactive dependency. */
+    instant(key: string, params?: Params): string;
+    /** `computed` signal for one key. `params` may be a function reading other signals. */
+    select(key: string, params?: Params | (() => Params)): Signal<string>;
+    /** True when the key has a non-empty value in the active language or a fallback. */
+    has(key: string): boolean;
+    /** Returns every key below `prefix` as a nested object (values are raw, not interpolated). */
+    getObject(prefix: string): Dictionary;
+    private lookup;
+    private resolve;
+    private onMissing;
+    /**
+     * Load global + all registered scopes (and fallback languages) for `lang`, THEN activate it.
+     * Nothing renders half-translated and no "missing" flash occurs.
+     */
+    use(lang: string): Promise<void>;
+    /**
+     * Complete the configuration and activate the first language in one call. Use it from your own
+     * APP_INITIALIZER when the language list is only known at runtime (e.g. from the backend):
+     *
+     * ```ts
+     * await i18n.init({ langs: ['fa', 'en'], defaultLang: 'fa', baseUrl: apiUrl, lang: user.lang });
+     * ```
+     * `lang` is used when it is in `langs`; otherwise stored > browser (opt-in) > `defaultLang`.
+     * Rejects when the files cannot be loaded, so the initializer can show an error page.
+     */
+    init(options?: I18nInitOptions): Promise<void>;
+    /**
+     * Update options after startup (languages, baseUrl, fallbacks, ...). Already downloaded files stay cached.
+     * `loader` and `autoInit` can only be set in `provideI18n()`.
+     */
+    configure(patch: I18nRuntimeConfig): void;
+    private syncLangs;
+    private activate;
+    /** Download a language without activating it. */
+    preload(lang: string): Promise<void>;
+    /** Language to start with: stored > browser (opt-in) > default. */
+    detectInitialLang(): string;
+    /** Register a scope and start loading it for the active language. Idempotent. Used by `provideI18nScope`. */
+    registerScope(scope: string): void;
+    /** Resolves once every scope registered so far is available. Never rejects. */
+    whenReady(): Promise<void>;
+    /** Manually set translations (tests, SSR transfer state, ...). */
+    setTranslation(lang: string, dict: Dictionary, merge?: boolean): void;
+    private merge;
+    private fetch;
+    private loadLang;
+    private isComplete;
+    private storageKey;
+    private persist;
+    private applyDocument;
+    static ɵfac: i0.ɵɵFactoryDeclaration<I18nService, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<I18nService>;
+}
+
+/**
+ * Static configuration (everything known at build time):
+ * ```ts
+ * provideHttpClient(),
+ * provideI18n({ langs: ['fa', 'en'], defaultLang: 'fa', fallbackLangs: ['en'] })
+ * ```
+ * The global dictionary of the initial language is then loaded before the app starts.
+ *
+ * Deferred configuration (languages come from your backend): omit `langs`/`defaultLang`
+ * and call `await inject(I18nService).init({ langs, defaultLang, baseUrl, lang })`
+ * from your own APP_INITIALIZER once you know them:
+ * ```ts
+ * provideI18n({ fallbackLangs: ['fa'] }),              // no automatic initializer
+ * provideAppInitializer(() => AppInitializer()),       // calls i18n.init(...)
+ * ```
+ * Pass `autoInit: false` to force this mode even when `langs` is given.
+ */
+declare function provideI18n(config?: I18nConfig): EnvironmentProviders;
+
+/**
+ * Put in `route.providers`. Runs when the route injector is created (before guards),
+ * so loading starts as early as possible. Child routes need nothing.
+ */
+declare function provideI18nScope(scope: string | string[]): EnvironmentProviders;
+/** Put ONCE on the root path-less route: `canActivateChild: [i18nReadyGuard]`. Waits for every registered scope. */
+declare const i18nReadyGuard: CanActivateChildFn;
+
+/** `readonly title = translateSignal('orders.title')`  (injection context) */
+declare function translateSignal(key: string, params?: Params | (() => Params)): Signal<string>;
+/** `const t = injectT();  computed(() => t('a.b'))` — reactive translate function. */
+declare function injectT(): TranslateFn;
+
+/** `imports: [TR]` brings the pipe and both directives into a standalone component. */
+declare const TR: readonly [typeof TrPipe, typeof TrDirective, typeof TrKeyDirective];
+
+export { HttpI18nLoader, I18N_CONFIG, I18N_DEFAULTS, I18N_LOADER, I18nService, TR, TrDirective, TrKeyDirective, TrPipe, buildI18nUrl, flatten, i18nReadyGuard, injectT, interpolate, marker, provideI18n, provideI18nScope, translateSignal };
+export type { Dictionary, I18nConfig, I18nInitOptions, I18nLoader, I18nRuntimeConfig, MissingHandler, Params, TrContext, TranslateFn, Transpiler };