ngx-kit 9.0.0 → 9.1.0

package/lazy-i18n/README.md

@@ -17,21 +17,22 @@ Flat keys, route-level scopes, pipe, directives, fallbacks and a key extractor C
 
 1. [Install](#install)
 2. [Quick start](#quick-start)
-3. [Concepts](#concepts)
-4. [Using translations](#using-translations)
-5. [Scopes and routing](#scopes-and-routing)
-6. [Language switching](#language-switching)
-7. [Fallbacks and missing keys](#fallbacks-and-missing-keys)
-8. [Interpolation, plurals and ICU](#interpolation-plurals-and-icu)
-9. [Loaders](#loaders)
-10. [Key extractor CLI](#key-extractor-cli)
-11. [Configuration reference](#configuration-reference)
-12. [API reference](#api-reference)
-13. [Testing your app](#testing-your-app)
-14. [Performance notes](#performance-notes)
-15. [Migrating from Transloco](#migrating-from-transloco)
-16. [Limitations](#limitations)
-17. [Developing this library](#developing-this-library)
+3. [Deferred configuration (languages from the backend)](#deferred-configuration-languages-from-the-backend)
+4. [Concepts](#concepts)
+5. [Using translations](#using-translations)
+6. [Scopes and routing](#scopes-and-routing)
+7. [Language switching](#language-switching)
+8. [Fallbacks and missing keys](#fallbacks-and-missing-keys)
+9. [Interpolation, plurals and ICU](#interpolation-plurals-and-icu)
+10. [Loaders](#loaders)
+11. [Key extractor CLI](#key-extractor-cli)
+12. [Configuration reference](#configuration-reference)
+13. [API reference](#api-reference)
+14. [Testing your app](#testing-your-app)
+15. [Performance notes](#performance-notes)
+16. [Migrating from Transloco](#migrating-from-transloco)
+17. [Limitations](#limitations)
+18. [Developing this library](#developing-this-library)
 
 ---
 
@@ -116,6 +117,62 @@ export class RequestsComponent {
 }
 ```
 
+## Deferred configuration (languages from the backend)
+
+Often the list of languages, the default language and the user's saved language only exist **after** your own
+`APP_INITIALIZER` has talked to the backend. Do not try to build the config earlier (no `setTimeout`, no mutating
+the config token, no async `useFactory`): provide the library **without** languages and finish the setup with
+`I18nService.init()` when you know them.
+
+```ts
+// app.config.ts
+provideHttpClient(),
+provideI18n({ fallbackLangs: ['fa'] }),      // no langs/defaultLang -> no automatic initializer
+provideAppInitializer(() => AppInitializer()),
+```
+
+```ts
+// app-initializer.ts
+export async function AppInitializer(): Promise<void> {
+  const http = inject(HttpClient);
+  const platformLocation = inject(PlatformLocation);
+  const i18n = inject(I18nService);
+  inject(ColorSchemaService).load();
+
+  // 1) appconfig.json  2) /api/Common/InitialApp  (as you do today)
+  const config = await firstValueFrom(http.get<any>(configUrl(platformLocation)));
+  AppConst.apiUrl = config.apiUrl; /* … */
+  const resp = await firstValueFrom(http.get<InitialAppDto>(AppConst.apiUrl + '/api/Common/InitialApp'));
+  AppConst.languageList = resp.languages ?? [];
+  AppConst.defaultLang = resp.defaultLang ?? 'fa';
+
+  // 3) finish the i18n setup and load the first language. AWAIT it: the app starts when translations are ready.
+  await i18n.init({
+    langs: AppConst.languageList.map((l) => l.culture),
+    defaultLang: AppConst.defaultLang,
+    baseUrl: AppConst.apiUrl,          // read at request time, so a value known only now is fine
+    lang: AppConst.currentLanguage,    // optional: user's saved language; ignored if not in `langs`
+  });
+}
+```
+
+What `init()` does: merges the options into the live config (`configure()`), picks the language
+(`lang` if supported, otherwise stored > browser (opt-in) > `defaultLang`), downloads the global file, every scope
+registered so far and the fallback languages, and only then activates the language. It rejects if loading fails, so
+you can catch it in the initializer and show an error page.
+
+Notes:
+
+- `loader` and `autoInit` can only be set in `provideI18n()`. Everything else can be changed later with
+  `i18n.configure({...})`; files that are already downloaded stay cached.
+- When `langs` **and** `defaultLang` are given to `provideI18n()`, an initializer is added automatically
+  (`autoInit` defaults to `true`). Use `autoInit: false` if you prefer to call `init()` yourself.
+- `i18n.langs` is a **signal** (`i18n.langs()`) because the list can arrive after startup. `i18n.ready()` becomes
+  `true` after the first language is active.
+- Scopes registered before `init()` (for example by an early service) are remembered and loaded by `init()`.
+  `whenReady()` and `i18nReadyGuard` also wait for an in-flight `init()` / `use()`.
+- Do not call `use()` without awaiting it inside an initializer: the app would start before the files arrive.
+
 ## Concepts
 
 | Term | Meaning |
@@ -250,6 +307,11 @@ Use a real ICU library (for example `intl-messageformat`) inside `transpile` for
 
 The default `HttpI18nLoader` uses `HttpClient`, so your interceptors (auth, base URL, retry) apply.
 
+URLs are built as `{baseUrl}/{scope}/{lang}{fileExtension}` (global file: `{baseUrl}/{lang}{fileExtension}`).
+The builder is safe by construction: a missing scope never becomes `undefined`, repeated or trailing slashes
+are collapsed (`'https://api.x.com/'` + no scope -> `https://api.x.com/fa.json`), and the extension may be written
+with or without the dot. `buildI18nUrl()` is exported if you need the same logic in a custom loader.
+
 ```ts
 provideI18n({
   …,
@@ -333,15 +395,16 @@ Add to `package.json` scripts: `"i18n": "ngx-lazy-i18n-extract"`, `"i18n:check":
 
 | Option | Type | Default | Description |
 |---|---|---|---|
-| `langs` | `string[]` | required | Supported languages. |
-| `defaultLang` | `string` | required | Used when nothing is stored or detected. |
+| `langs` | `string[]` | required before first activation | Supported languages. May be supplied later with `init()`. |
+| `defaultLang` | `string` | required before first activation | Used when nothing is stored or detected. May be supplied later. |
+| `autoInit` | `boolean` | `true` if `langs` and `defaultLang` are given | Add an APP_INITIALIZER that activates the initial language. Provide-time only. |
 | `fallbackLangs` | `string[]` | `[]` | Languages tried, in order, for missing/empty keys. |
 | `missing` | `'key' \| 'empty' \| (key, lang) => string` | `'key'` | What to render for a missing key. |
 | `warnMissing` | `boolean` | `isDevMode()` | Log each missing key once. |
 | `transpile` | `(value, params, lang) => string` | built-in `{{ }}` | Custom message formatter. |
 | `loader` | `Type<I18nLoader>` | `HttpI18nLoader` | Custom loader class. |
 | `baseUrl` | `string` | `'/i18n'` | HTTP loader base. |
-| `fileExtension` | `string` | `''` | HTTP loader extension (e.g. `.json`). |
+| `fileExtension` | `string` | `'.json'` | HTTP loader extension; `''` for none. |
 | `url` | `(lang, scope?) => string` | none | HTTP loader full URL control. |
 | `retries` | `number` | `1` | Retries per failed request (250 ms delay). |
 | `storageKey` | `string \| null` | `'lazy-i18n.lang'` | Persist language; `null` disables. |
@@ -363,7 +426,10 @@ Add to `package.json` scripts: `"i18n": "ngx-lazy-i18n-extract"`, `"i18n:check":
 | `lang: Signal<string>` | Active language. |
 | `dir: Signal<'rtl' \| 'ltr'>` | Direction for the active language. |
 | `revision: Signal<number>` | Changes on every language/dictionary change. |
-| `langs: readonly string[]` | Supported languages. |
+| `langs: Signal<readonly string[]>` | Supported languages (reactive; may arrive after startup). |
+| `ready: Signal<boolean>` | `true` after the first language is active. |
+| `init({ langs, defaultLang, baseUrl, lang, … })` | Complete the config and activate the first language. Use in your own initializer. |
+| `configure(patch)` | Change options after startup (not `loader`/`autoInit`). |
 | `t(key, params?)` | Translate (reactive). |
 | `instant(key, params?)` | Translate (non-reactive). |
 | `select(key, params?)` | `Signal<string>`; `params` may be a function. |
@@ -371,7 +437,7 @@ Add to `package.json` scripts: `"i18n": "ngx-lazy-i18n-extract"`, `"i18n:check":
 | `use(lang)` | Load everything, then activate. |
 | `preload(lang)` | Download without activating. |
 | `registerScope(scope)` | Register and start loading a scope. |
-| `whenReady()` | Resolves when all registered scopes are loaded. Never rejects. |
+| `whenReady()` | Resolves when all registered scopes and any in-flight `init()`/`use()` are done. Never rejects. |
 | `setTranslation(lang, dict, merge = true)` | Inject translations manually. |
 | `detectInitialLang()` | Stored, browser (opt-in) or default. |
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ngx-kit",
-  "version": "9.0.0",
+  "version": "9.1.0",
   "description": "Angular input components",
   "author": "Mohammadreza Samani <mr.samani1368@gmail.com>",
   "license": "MIT",

package/types/ngx-kit-drag-resize.d.ts

@@ -268,6 +268,8 @@ declare class DragRef<T = unknown> {
     private sourceDisplay;
     private sourcePointerEvents;
     private sourceTransition;
+    private sourceWillChange;
+    private sourceTransform;
     /** True while a drop-list drag (body preview + placeholder) is in progress. Free drag: always false. */
     private listDrag;
     private cachedLists;
@@ -399,7 +401,6 @@ declare class NgxDraggable<T = unknown> implements OnInit, OnDestroy, AfterConte
     readonly dragEnd: _angular_core.OutputEmitterRef<IPosition>;
     readonly _ref: DragRef<T>;
     readonly dragging: _angular_core.WritableSignal<boolean>;
-    private readonly doc;
     private readonly service;
     private readonly scroller;
     private down;
@@ -444,7 +445,7 @@ declare class NgxDraggable<T = unknown> implements OnInit, OnDestroy, AfterConte
     static ɵdir: _angular_core.ɵɵDirectiveDeclaration<NgxDraggable<any>, "[NgxDraggable],[ngxDraggable]", never, { "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; "boundary": { "alias": "boundary"; "required": false; "isSignal": true; }; "dragRootElement": { "alias": "dragRootElement"; "required": false; "isSignal": true; }; "dragHandle": { "alias": "dragHandle"; "required": false; "isSignal": true; }; "lockAxis": { "alias": "lockAxis"; "required": false; "isSignal": true; }; "dragThreshold": { "alias": "dragThreshold"; "required": false; "isSignal": true; }; "keyboardStep": { "alias": "keyboardStep"; "required": false; "isSignal": true; }; "autoScroll": { "alias": "autoScroll"; "required": false; "isSignal": true; }; "data": { "alias": "data"; "required": false; }; }, { "disabled": "disabledChange"; "dragRootElement": "dragRootElementChange"; "dragHandle": "dragHandleChange"; "dragStart": "dragStart"; "dragMove": "dragMove"; "dragEnd": "dragEnd"; }, ["customPreview"], never, true, never>;
 }
 
-declare class NgxResizable {
+declare class NgxResizable implements OnDestroy {
     private readonly el;
     disabled: _angular_core.ModelSignal<boolean>;
     readonly minWidth: _angular_core.ModelSignal<number>;
@@ -472,11 +473,18 @@ declare class NgxResizable {
     private beforeHeight;
     private beforeTransform;
     private pointerId;
+    private startWidth;
+    private startHeight;
+    private removeDocumentListeners;
+    private readonly renderer;
     constructor(el: ElementRef<HTMLElement>);
+    ngOnDestroy(): void;
     onPointerDown(e: PointerEvent): void;
     onPointerMove(e: PointerEvent): void;
     onPointerUp(e: PointerEvent): void;
     onDocumentKeyDown(e: KeyboardEvent): void;
+    private onPointerCancel;
+    private restoreBeforeResize;
     onHandleKeyDown(e: KeyboardEvent): void;
     private calculate;
     private apply;
@@ -597,9 +605,9 @@ declare function clampResizeWithinBoundary(boundaryRect: DOMRect | undefined, st
     top: number;
 };
 /** Current page zoom level (1 = 100%). Falls back to devicePixelRatio pre visualViewport. */
-declare function getPageZoom(): number;
+declare function getPageZoom(element?: HTMLElement): number;
 /** Adjusts a raw pointer-derived value for the current page zoom level. */
-declare function adjustForZoom(value: number): number;
+declare function adjustForZoom(value: number, element?: HTMLElement): number;
 
 /**
  * Auto-scrolls the nearest scrollable ancestor (or window) while the pointer
@@ -609,6 +617,7 @@ declare function adjustForZoom(value: number): number;
 declare class AutoScroller {
     private raf;
     private container;
+    private win?;
     private speed;
     private onTick?;
     private readonly edge;

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

@@ -15,10 +15,16 @@ 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;
+/**
+ * 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). */
@@ -27,11 +33,11 @@ declare class I18nConfig {
     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. */
+    /** 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`, `/i18n/setting/fa`. */
+    /** 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'`. */
+    /** 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;
@@ -43,7 +49,23 @@ declare class I18nConfig {
     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>;
 
@@ -114,8 +136,21 @@ declare function flatten(dict: Dictionary, target?: Map<string, string>, onConfl
 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}` and `{baseUrl}/{scope}/{lang}`. Goes through your HttpClient interceptors. */
+/**
+ * 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;
@@ -130,14 +165,19 @@ declare class I18nService {
     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">;
-    readonly langs: readonly string[];
-    private readonly fallbacks;
-    private readonly warn;
+    /** 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;
@@ -163,6 +203,24 @@ declare class I18nService {
      * 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. */
@@ -185,13 +243,23 @@ declare class 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 loaded before the app starts.
+ * 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;
+declare function provideI18n(config?: I18nConfig): EnvironmentProviders;
 
 /**
  * Put in `route.providers`. Runs when the route injector is created (before guards),
@@ -209,5 +277,5 @@ 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 };
+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 };