ngx-kit 8.5.0 → 9.0.0

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

@@ -0,0 +1,213 @@
+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>;
+}
+declare class I18nConfig {
+    /** All supported languages. */
+    langs: string[];
+    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. */
+    loader?: Type<I18nLoader>;
+    /** Default HTTP loader: base URL. Default `'/i18n'` -> `/i18n/fa`, `/i18n/setting/fa`. */
+    baseUrl?: string;
+    /** Default HTTP loader: file extension appended to the URL, e.g. `'.json'`. Default `'.json'`. */
+    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;
+}
+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;
+
+/** Default loader: GET `{baseUrl}/{lang}` and `{baseUrl}/{scope}/{lang}`. Goes through your HttpClient interceptors. */
+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;
+    /** 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">;
+    readonly langs: readonly string[];
+    private readonly fallbacks;
+    private readonly 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>;
+    /** 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>;
+}
+
+/**
+ * ```ts
+ * provideHttpClient(),
+ * provideI18n({ langs: ['fa', 'en'], defaultLang: 'fa', fallbackLangs: ['en'] })
+ * ```
+ * The global dictionary of the initial language is loaded before the app starts.
+ */
+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_LOADER, I18nConfig, I18nService, TR, TrDirective, TrKeyDirective, TrPipe, flatten, i18nReadyGuard, injectT, interpolate, marker, provideI18n, provideI18nScope, translateSignal };
+export type { Dictionary, I18nLoader, MissingHandler, Params, TrContext, TranslateFn, Transpiler };