@seliseblocks/blocks-angular-localization 0.0.1

package/dist/index.d.ts

@@ -0,0 +1,701 @@
+import * as i0 from '@angular/core';
+import { InjectionToken, Signal, PipeTransform, TemplateRef } from '@angular/core';
+import { Subject, Observable } from 'rxjs';
+
+/**
+ * Controls how translations are loaded at application startup.
+ *
+ * - `'modular'` — Lazy per-route loading via `provideUilmScope()`.
+ *   Shows empty placeholders while fetching. Best for large apps
+ *   with many modules where loading everything upfront is wasteful.
+ *
+ * - `'eager'` — All modules listed in `preloadModules` are fetched
+ *   before the app renders. Blocks bootstrap via `APP_INITIALIZER`.
+ *   Best for smaller apps or when avoiding placeholder flicker matters.
+ */
+type UilmLoadingStrategy = 'modular' | 'eager';
+/**
+ * Controls where translations are persisted.
+ *
+ * - `'memory'`   — In-memory cache only (cleared on page reload).
+ * - `'indexeddb'` — Persists to IndexedDB alongside in-memory cache.
+ *   Translations load instantly from disk on subsequent visits while
+ *   the in-memory L1 cache provides zero-latency lookups within a session.
+ */
+type UilmCacheStorage = 'memory' | 'indexeddb';
+/**
+ * Controls where the active language preference is persisted.
+ *
+ * - `'localStorage'`   — Persists across browser sessions (default).
+ * - `'sessionStorage'` — Persists only for the current tab/session.
+ * - `'none'`           — No persistence; always starts with `defaultLang`.
+ */
+type UilmLangStorage = 'localStorage' | 'sessionStorage' | 'none';
+/** A module entry: plain string or an object with an optional alias. */
+type UilmModuleEntry = string | {
+    module: string;
+    alias?: string;
+};
+/**
+ * Root configuration for the blocks-localization library.
+ *
+ * @publicApi
+ */
+interface BlocksLocalizationConfig {
+    /** UILM API base URL, e.g. `'https://api.seliseblocks.com/uilm/v1'` */
+    uilmApiBaseUrl: string;
+    /** Project key sent as `x-blocks-key` header. */
+    projectKey: string;
+    /** Optional Bearer token for authenticated UILM access. */
+    accessToken?: string;
+    /** Short language codes, e.g. `['en', 'de', 'fr', 'it']`. */
+    availableLangs: readonly string[];
+    /** Default language short code, e.g. `'en'`. */
+    defaultLang: string;
+    /** Maps short codes → full locale codes, e.g. `{ en: 'en-US', de: 'de-DE' }`. */
+    localeMapping?: Readonly<Record<string, string>>;
+    /**
+     * Cache TTL in milliseconds. `0` means no expiry — cached translations are served
+     * until explicitly cleared or the session ends (memory) / storage is cleared (IndexedDB).
+     * @defaultValue `0`
+     */
+    cacheTimeout?: number;
+    /**
+     * Where to persist the translation cache.
+     *
+     * - `'memory'`    — In-memory only (default, current behavior).
+     * - `'indexeddb'`  — Persists to IndexedDB. Translations survive page reloads
+     *   and are available instantly on subsequent visits. In-memory cache still
+     *   serves as L1 for zero-latency lookups within the same session.
+     *
+     * @defaultValue `'memory'`
+     */
+    cacheStorage?: UilmCacheStorage;
+    /**
+     * When `cacheStorage` is `'indexeddb'` and a cached entry exists, serve
+     * it immediately and revalidate from the API in the background.
+     * Updated translations are merged into the store silently without blocking the UI.
+     * Has no effect when `cacheStorage` is `'memory'`.
+     * @defaultValue `false`
+     */
+    revalidateInBackground?: boolean;
+    /**
+     * Prefix translation keys with the module name/alias
+     * (e.g. `"dashboard.LABEL.HELLO"`).
+     * @defaultValue `false`
+     */
+    prefixKeysWithModule?: boolean;
+    /**
+     * Enable production mode (suppresses console warnings).
+     * @defaultValue `false`
+     */
+    prodMode?: boolean;
+    /**
+     * Fall back to local JSON files when the UILM API request fails.
+     *
+     * Local files are expected at `{localAssetsPath}/{moduleName}/{lang}.json`
+     * (nested JSON is flattened to dot-notation keys automatically).
+     * For modules with an empty-string alias (e.g. `common`), the path is
+     * `{localAssetsPath}/{lang}.json`.
+     *
+     * @defaultValue `true`
+     */
+    fallbackToLocal?: boolean;
+    /**
+     * Base path for local fallback JSON files (relative to the app's public root).
+     * @defaultValue `'assets/i18n'`
+     */
+    localAssetsPath?: string;
+    /**
+     * Where to persist the active language preference.
+     *
+     * - `'localStorage'`   — Persists across browser sessions (default).
+     * - `'sessionStorage'` — Persists only for the current tab/session.
+     * - `'none'`           — No persistence; always starts with `defaultLang`.
+     *
+     * The storage key used is `uilmLang` (or custom via `langStorageKey`).
+     *
+     * @defaultValue `'localStorage'`
+     */
+    langStorage?: UilmLangStorage;
+    /**
+     * Custom storage key for persisting the active language.
+     * @defaultValue `'uilmLang'`
+     */
+    langStorageKey?: string;
+    /**
+     * Translation loading strategy.
+     *
+     * - `'modular'` — lazy per-route loading, empty placeholders while fetching
+     * - `'eager'`   — all `preloadModules` fetched on startup, blocks rendering until ready
+     *
+     * @defaultValue `'modular'`
+     */
+    strategy?: UilmLoadingStrategy;
+    /**
+     * Modules to preload at app startup (before any route loads).
+     *
+     * In `'modular'` mode these are loaded alongside route-level modules.
+     * In `'eager'` mode these should include **all** module scopes — route-level
+     * `provideUilmScope()` calls will skip fetching if translations are already cached.
+     *
+     * @example
+     * ```typescript
+     * preloadModules: ['common', { module: 'shared', alias: 'sh' }]
+     * ```
+     */
+    preloadModules?: UilmModuleEntry[];
+}
+/** Language entity returned by the UILM API. */
+interface UilmLanguage {
+    itemId: string;
+    languageName: string;
+    languageCode: string;
+    isDefault: boolean;
+    projectKey: string | null;
+}
+/** Module entity returned by the UILM API. */
+interface UilmModule {
+    moduleName: string;
+    name: string | null;
+    itemId: string;
+    createDate: string;
+    lastUpdateDate: string;
+    createdBy: string | null;
+    lastUpdatedBy: string | null;
+    tenantId: string | null;
+}
+
+/**
+ * Provides all UILM translation infrastructure for an Angular application.
+ *
+ * ## Strategies
+ *
+ * ### `'modular'` (default)
+ * Preloads only the modules listed in `preloadModules` at startup.
+ * Additional modules are lazily loaded per route via `provideUilmScope()`.
+ * Shows empty placeholders while translations are loading.
+ *
+ * ### `'eager'`
+ * All modules in `preloadModules` are fetched at startup (non-blocking).
+ * Use `UilmLoadingScreenComponent` with `UilmStore.ready` to gate the UI
+ * until translations are available. Route-level `provideUilmScope()` calls
+ * become cache hits.
+ *
+ * @example
+ * ```typescript
+ * // Eager — all modules upfront with loading screen
+ * provideBlocksLocalization({
+ *   strategy: 'eager',
+ *   preloadModules: [
+ *     { module: 'common', alias: '' },
+ *     'dashboard',
+ *     { module: 'opportunity', alias: 'op' },
+ *   ],
+ *   // ...
+ * })
+ *
+ * // app.component.html
+ * // @if (!store.ready()) {
+ * //   <uilm-loading-screen />
+ * // } @else {
+ * //   <router-outlet />
+ * // }
+ * ```
+ *
+ * @publicApi
+ */
+declare function provideBlocksLocalization(config: BlocksLocalizationConfig): i0.EnvironmentProviders;
+
+/**
+ * Injection token for the blocks-localization configuration.
+ * Provided by `provideBlocksLocalization()` at the application root.
+ */
+declare const BLOCKS_LOCALIZATION_CONFIG: InjectionToken<BlocksLocalizationConfig>;
+
+/** Flat key → value translation map. */
+type TranslationMap = Record<string, string>;
+/**
+ * Core reactive translation store.
+ *
+ * Holds translations per language, tracks the active language via signals,
+ * and persists language preference to `localStorage`.
+ *
+ * @publicApi
+ */
+declare class UilmStore {
+    private readonly config;
+    private readonly destroyRef;
+    private readonly storageKey;
+    /** Internal translation maps: `lang → flat key-value pairs` */
+    private readonly store;
+    /** Toggled on every `setTranslation` call to trigger signal reactivity. */
+    private readonly _version;
+    private versionCounter;
+    /** Active language short code. */
+    readonly activeLang: i0.WritableSignal<string>;
+    /**
+     * When `true`, `translate()` returns the raw key instead of the translated value.
+     * Toggled via `window.postMessage({ action: 'keymode', keymode: true/false })`.
+     * Useful for testing with a browser extension.
+     */
+    readonly keyMode: i0.WritableSignal<boolean>;
+    /** Read-only version signal — depend on this to react to translation changes. */
+    readonly version: i0.Signal<number>;
+    /** `true` when translations have been loaded for the active language. */
+    readonly ready: i0.Signal<boolean>;
+    constructor();
+    /**
+     * Translate a key for the active language.
+     * Supports interpolation: `{{ name }}` in values is replaced by `params.name`.
+     *
+     * Returns the raw key if no translation is found.
+     */
+    translate(key: string, params?: Record<string, unknown>): string;
+    /** Check if a translation key exists for the active language. */
+    has(key: string): boolean;
+    /** Merge translations into the store for a given language. */
+    setTranslation(data: TranslationMap, lang: string): void;
+    /** Set active language and persist to `localStorage`. Ignores invalid language codes. */
+    setActiveLang(lang: string): void;
+    /** Get configured available languages. */
+    getAvailableLangs(): string[];
+    private getStorage;
+    private loadPersistedLang;
+    private persistLang;
+    /**
+     * Listen for `window.postMessage` events to toggle key mode.
+     *
+     * Expected payload: `{ action: 'keymode', keymode: boolean }`
+     *
+     * Only messages from the same window and origin are accepted.
+     * Toggling key mode bumps the version signal so all translated
+     * values reactively update across the UI.
+     */
+    private listenForKeyModeToggle;
+    static ɵfac: i0.ɵɵFactoryDeclaration<UilmStore, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<UilmStore>;
+}
+
+/**
+ * IndexedDB persistence layer for UILM translation cache.
+ *
+ * Stores translation maps keyed by `{prefix}::{lang}` with timestamps
+ * for TTL-based invalidation. Falls back gracefully to `null` when
+ * IndexedDB is unavailable (SSR, restrictive incognito, etc.).
+ *
+ * All public methods are **fire-and-forget safe** — they never throw
+ * and resolve to `null` / `void` on any failure.
+ *
+ * @publicApi
+ */
+declare class UilmIndexedDbCache {
+    private dbReady;
+    constructor();
+    /** Re-open the database connection (used after unexpected close). */
+    private reconnect;
+    /**
+     * Retrieve a cached entry if it exists and hasn't exceeded the TTL.
+     *
+     * @param key   Cache key (`{prefix}::{lang}`)
+     * @param ttl   Time-to-live in ms. `0` disables expiry (entry is always valid).
+     * @returns The translation map, or `null` on miss / expiry / error.
+     */
+    get(key: string, ttl: number): Promise<TranslationMap | null>;
+    /**
+     * Retrieve a stale entry (ignoring TTL) for fallback purposes.
+     *
+     * @param key Cache key
+     * @returns The translation map regardless of age, or `null` if absent.
+     */
+    getStale(key: string): Promise<TranslationMap | null>;
+    /**
+     * Persist a translation map.
+     *
+     * @param key  Cache key
+     * @param data Flat key→value translation map
+     */
+    set(key: string, data: TranslationMap): Promise<void>;
+    /** Remove all cached translations from IndexedDB. */
+    clear(): Promise<void>;
+    private openDb;
+    private txGet;
+    private txPut;
+    private txClear;
+    static ɵfac: i0.ɵɵFactoryDeclaration<UilmIndexedDbCache, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<UilmIndexedDbCache>;
+}
+
+/**
+ * Low-level HTTP client for fetching translations from the UILM API.
+ *
+ * ## Caching architecture (two-tier)
+ *
+ * | Layer | Storage         | Lifetime        | When enabled              |
+ * |-------|-----------------|-----------------|---------------------------|
+ * | L1    | In-memory `Map` | Current session | Always                    |
+ * | L2    | IndexedDB       | Cross-session   | `cacheStorage: 'indexeddb'`|
+ *
+ * ### Lookup order
+ * 1. **L1 hit** (valid TTL) → return immediately
+ * 2. **In-flight dedup** → share existing Observable
+ * 3. **L2 hit** (valid TTL, if enabled) → populate L1, return
+ * 4. **HTTP fetch** → populate L1 + L2, return
+ * 5. **Error fallback chain**: stale L1 → stale L2 → local JSON → empty `{}`
+ *
+ * @publicApi
+ */
+declare class UilmLoader {
+    private readonly http;
+    private readonly config;
+    private readonly idbCache;
+    private readonly destroyRef;
+    /** L1 in-memory cache. */
+    private readonly memCache;
+    /** Tracks in-flight HTTP observables for request deduplication. */
+    private readonly inflight;
+    /** Emits when a background revalidation produces updated translations. */
+    readonly revalidated$: Subject<{
+        lang: string;
+        data: TranslationMap;
+    }>;
+    private availableModules;
+    private availableLanguages;
+    private shortToFullMapping;
+    private modulesLoaded;
+    private languagesLoaded;
+    private metadataInflight$;
+    constructor();
+    private get cacheTimeout();
+    private get shouldPrefixKeys();
+    private get useIndexedDb();
+    private get shouldRevalidate();
+    private get shouldFallbackToLocal();
+    private get localAssetsPath();
+    /**
+     * Fetch a single UILM module's translations.
+     *
+     * @param lang       Short language code (e.g. `'en'`)
+     * @param moduleName UILM module name as registered in the API
+     * @param alias      Optional alias used as the key prefix instead of the module name
+     * @returns Observable emitting the (optionally prefixed) key→value map
+     */
+    fetchModuleTranslations(lang: string, moduleName: string, alias?: string): Observable<TranslationMap>;
+    /**
+     * Attempt to load translations from IndexedDB cache only (no API, no metadata).
+     * Returns `null` if IndexedDB is disabled or the entry is missing.
+     * Used for instant store hydration before metadata is available.
+     */
+    loadFromCacheOnly(lang: string, moduleName: string, alias?: string): Observable<TranslationMap | null>;
+    /** Ensure modules and languages metadata are loaded (fetches once, then no-ops). */
+    ensureMetadataLoaded(): Observable<void>;
+    /** Clear all translation caches (L1 in-memory, in-flight, and L2 IndexedDB if enabled). */
+    clearCache(): void;
+    /** Fetch available languages from the UILM API. */
+    getAvailableLanguages(): Observable<UilmLanguage[]>;
+    /** Fetch available modules from the UILM API. */
+    getAvailableModules(): Observable<UilmModule[]>;
+    /** Get cached languages (empty until `ensureMetadataLoaded()` resolves). */
+    getLanguages(): UilmLanguage[];
+    /** Get cached modules (empty until `ensureMetadataLoaded()` resolves). */
+    getModules(): UilmModule[];
+    private buildCacheKey;
+    /** Check whether the L1 entry is present and within TTL. `cacheTimeout=0` means no expiry. */
+    private isL1Valid;
+    /** Write data to L1 (always) and L2 (when enabled). */
+    private populateCache;
+    /**
+     * Resolve translations through the full L2 → HTTP → fallback chain.
+     * Called only when L1 misses and no in-flight request exists.
+     */
+    private resolveTranslation;
+    /** Issue the HTTP request and handle success / error with full fallback chain. */
+    private fetchFromApi;
+    /**
+     * Fallback chain on HTTP failure:
+     * 1. Stale L1 (in-memory)
+     * 2. Stale L2 (IndexedDB, if enabled)
+     * 3. Local JSON file (if enabled)
+     * 4. Empty map
+     */
+    private resolveFromFallbacks;
+    /** Attempt local JSON fallback, or return empty map. */
+    private localFallbackOrEmpty;
+    /**
+     * Fetch translations from a local JSON file.
+     * Nested JSON is automatically flattened to dot-notation keys.
+     *
+     * Path convention:
+     * - Module with content: `{localAssetsPath}/{moduleName}/{lang}.json`
+     * - Root/common module (empty alias): `{localAssetsPath}/{lang}.json`
+     */
+    private fetchLocalFallback;
+    /**
+     * Fire-and-forget API fetch that silently updates caches and emits on
+     * `revalidated$` when the response differs from the currently cached data.
+     */
+    private revalidateFromApi;
+    private buildHeaders;
+    /** Ensure API response is a valid flat object. Returns empty map for malformed responses. */
+    private sanitizeApiResponse;
+    /** Shallow key-by-key equality check for flat TranslationMaps. */
+    private shallowEqual;
+    private prefixKeys;
+    static ɵfac: i0.ɵɵFactoryDeclaration<UilmLoader, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<UilmLoader>;
+}
+
+interface UilmScopeConfig {
+    /**
+     * UILM modules to load for this route.
+     *
+     * Each entry can be:
+     * - A plain string (module name, used as-is for prefixing)
+     * - An object `{ module: string, alias?: string }` to remap the prefix
+     *
+     * @example
+     * ```typescript
+     * provideUilmScope({
+     *   modules: [
+     *     'dashboard',
+     *     { module: 'opportunity', alias: 'op' },
+     *     { module: 'backend', alias: 'be' },
+     *   ],
+     * })
+     * ```
+     */
+    modules: UilmModuleEntry[];
+}
+/**
+ * Route-level provider that lazily loads specific UILM modules on navigation.
+ *
+ * In `'eager'` strategy mode, translations are typically already cached
+ * from the initial `APP_INITIALIZER` load. The loader's cache deduplication
+ * ensures no redundant HTTP calls are made.
+ *
+ * Re-fetches automatically when the active language changes.
+ * Subscriptions are auto-cleaned via `DestroyRef`.
+ *
+ * @publicApi
+ */
+declare function provideUilmScope(config: UilmScopeConfig): i0.EnvironmentProviders;
+
+/**
+ * Headless language switching service.
+ * Provides programmatic control over the active language.
+ */
+declare class BlocksLangSwitcher {
+    private readonly store;
+    private readonly loader;
+    /** Active language as a signal. */
+    readonly activeLang: Signal<string>;
+    /** Get the currently active short language code. */
+    getActiveLang(): string;
+    /** Get the list of configured available language codes. */
+    getAvailableLangs(): string[];
+    /**
+     * Switch the active language.
+     * @param lang Short language code (e.g. 'en', 'de')
+     * @param reload Whether to reload the page after switching. Default: false
+     */
+    setActiveLang(lang: string, reload?: boolean): void;
+    /** Fetch available languages from the UILM API. */
+    getAvailableLanguagesFromApi(): Observable<UilmLanguage[]>;
+    /** Clear the translation cache. */
+    clearCache(): void;
+    static ɵfac: i0.ɵɵFactoryDeclaration<BlocksLangSwitcher, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<BlocksLangSwitcher>;
+}
+
+/**
+ * Structural directive that provides a translation function to the template.
+ * Re-renders when the active language or translations change.
+ *
+ * @example
+ * ```html
+ * <section *uilmTranslate="let t">
+ *   <p>{{ t('dashboard.LABEL.TITLE') }}</p>
+ * </section>
+ * ```
+ *
+ * With scope (auto-prefixes keys):
+ * ```html
+ * <section *uilmTranslate="let t; scope: 'dashboard'">
+ *   <p>{{ t('LABEL.TITLE') }}</p>  <!-- resolves to dashboard.LABEL.TITLE -->
+ * </section>
+ * ```
+ */
+declare class UilmTranslateDirective {
+    private readonly store;
+    private readonly templateRef;
+    private readonly vcr;
+    private viewRef;
+    /** Optional scope prefix */
+    readonly uilmTranslateScope: i0.InputSignal<string>;
+    constructor();
+    private ensureView;
+    static ngTemplateContextGuard(_dir: UilmTranslateDirective, _ctx: unknown): _ctx is UilmTranslateContext;
+    static ɵfac: i0.ɵɵFactoryDeclaration<UilmTranslateDirective, never>;
+    static ɵdir: i0.ɵɵDirectiveDeclaration<UilmTranslateDirective, "[uilmTranslate]", never, { "uilmTranslateScope": { "alias": "uilmTranslateScope"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
+}
+interface UilmTranslateContext {
+    $implicit: (key: string, params?: Record<string, unknown>) => string;
+    uilmTranslate: (key: string, params?: Record<string, unknown>) => string;
+}
+
+/**
+ * Resolves a multilingual object to the value matching the current active language.
+ *
+ * @example
+ * ```html
+ * <!-- Given: { en: 'Hello', de: 'Hallo', fr: 'Bonjour' } -->
+ * {{ item.name | multiLang }}  <!-- outputs 'Hello' when lang is 'en' -->
+ * ```
+ */
+declare class MultiLangPipe implements PipeTransform {
+    private readonly store;
+    transform(value: Record<string, string> | string | null | undefined): string;
+    static ɵfac: i0.ɵɵFactoryDeclaration<MultiLangPipe, never>;
+    static ɵpipe: i0.ɵɵPipeDeclaration<MultiLangPipe, "multiLang", true>;
+}
+
+/**
+ * Impure pipe that translates a key using the UILM store.
+ * Re-evaluates when the active language or translations change.
+ *
+ * @example
+ * ```html
+ * <p>{{ 'dashboard.LABEL.TITLE' | uilmTranslate }}</p>
+ * <p>{{ 'LABEL.HELLO' | uilmTranslate: { name: userName } }}</p>
+ * ```
+ */
+declare class UilmTranslatePipe implements PipeTransform {
+    private readonly store;
+    private lastKey;
+    private lastLang;
+    private lastVersion;
+    private lastParamsJson;
+    private lastValue;
+    transform(key: string, params?: Record<string, unknown>): string;
+    static ɵfac: i0.ɵɵFactoryDeclaration<UilmTranslatePipe, never>;
+    static ɵpipe: i0.ɵɵPipeDeclaration<UilmTranslatePipe, "uilmTranslate", true>;
+}
+
+/**
+ * Translation service for component classes.
+ * Fully signal-based with sync helpers.
+ *
+ * @example
+ * ```typescript
+ * private readonly uilm = inject(UilmTranslateService);
+ *
+ * // Signal-based (reactive, updates on lang change + translation load)
+ * title = this.uilm.t('dashboard.LABEL.TITLE');
+ * // In template: {{ title() }}
+ *
+ * // Sync snapshot (does NOT react)
+ * label = this.uilm.translate('dashboard.LABEL.TITLE');
+ * ```
+ */
+declare class UilmTranslateService {
+    private readonly store;
+    /** Active language as a signal. */
+    readonly activeLang: Signal<string>;
+    /**
+     * Signal-based translation. Auto-updates on language change
+     * and when new translations are loaded.
+     */
+    t(key: string, params?: Record<string, unknown>): Signal<string>;
+    /** Synchronous translation snapshot. Does NOT react to changes. */
+    translate(key: string, params?: Record<string, unknown>): string;
+    /** Current active language code. */
+    getActiveLang(): string;
+    /** Set active language. */
+    setActiveLang(lang: string): void;
+    /**
+     * Signal-based batch translation. Reactive to lang and translation changes.
+     */
+    tMany(keys: string[], params?: Record<string, unknown>): Signal<Record<string, string>>;
+    /** Synchronous batch translation snapshot. */
+    translateMany(keys: string[], params?: Record<string, unknown>): Record<string, string>;
+    static ɵfac: i0.ɵɵFactoryDeclaration<UilmTranslateService, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<UilmTranslateService>;
+}
+
+declare class UilmLoadingScreenComponent {
+    readonly title: i0.InputSignal<string>;
+    readonly description: i0.InputSignal<string>;
+    /**
+     * Optional custom template to replace the entire default loading UI.
+     *
+     * @example
+     * ```html
+     * <ng-template #customLoading>
+     *   <div class="my-loading">
+     *     <img src="assets/logo.svg" />
+     *     <p>Please wait...</p>
+     *   </div>
+     * </ng-template>
+     *
+     * <uilm-loading-screen [customTemplate]="customLoading" />
+     * ```
+     */
+    readonly customTemplate: i0.InputSignal<TemplateRef<unknown> | undefined>;
+    static ɵfac: i0.ɵɵFactoryDeclaration<UilmLoadingScreenComponent, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<UilmLoadingScreenComponent, "uilm-loading-screen", never, { "title": { "alias": "title"; "required": false; "isSignal": true; }; "description": { "alias": "description"; "required": false; "isSignal": true; }; "customTemplate": { "alias": "customTemplate"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
+}
+
+/**
+ * Flattens a nested object into dot-notation keys.
+ *
+ * @example
+ * ```typescript
+ * flattenJson({ LABEL: { HELLO: 'Hello', WORLD: 'World' }, BTN: { SAVE: 'Save' } })
+ * // → { 'LABEL.HELLO': 'Hello', 'LABEL.WORLD': 'World', 'BTN.SAVE': 'Save' }
+ * ```
+ */
+declare function flattenJson(obj: Record<string, unknown>, parentKey?: string, separator?: string, _visited?: Set<object>): Record<string, string>;
+
+/**
+ * Creates an empty record with keys for each provided language.
+ * Useful for initializing multilingual form models.
+ *
+ * @example
+ * createI18nRecord(['en', 'de', 'fr']) // { en: '', de: '', fr: '' }
+ */
+declare function createI18nRecord(langs: string[]): Record<string, string>;
+
+/**
+ * Convert a short language code to a full locale code using the provided mapping.
+ * Returns the original code if no mapping is found or if it's already a full code.
+ */
+declare function toFullLangCode(lang: string, mapping: Record<string, string>): string;
+/**
+ * Convert a full locale code (e.g. 'en-US') to a short code (e.g. 'en').
+ */
+declare function toShortLangCode(fullCode: string): string;
+/**
+ * Build a reverse mapping from full locale codes to short codes.
+ */
+declare function buildReverseMapping(localeMapping: Record<string, string>): Record<string, string>;
+
+/**
+ * Provides a test-friendly translation setup with in-memory translations.
+ * No HTTP calls are made.
+ *
+ * @example
+ * ```typescript
+ * TestBed.configureTestingModule({
+ *   providers: [
+ *     provideBlocksLocalizationTesting({
+ *       en: { 'dashboard.LABEL.HELLO': 'Hello', 'dashboard.LABEL.WORLD': 'World' },
+ *       de: { 'dashboard.LABEL.HELLO': 'Hallo', 'dashboard.LABEL.WORLD': 'Welt' },
+ *     }),
+ *   ],
+ * });
+ * ```
+ */
+declare function provideBlocksLocalizationTesting(translations?: Record<string, Record<string, string>>, config?: Partial<BlocksLocalizationConfig>): i0.EnvironmentProviders;
+
+export { BLOCKS_LOCALIZATION_CONFIG, BlocksLangSwitcher, MultiLangPipe, UilmIndexedDbCache, UilmLoader, UilmLoadingScreenComponent, UilmStore, UilmTranslateDirective, UilmTranslatePipe, UilmTranslateService, buildReverseMapping, createI18nRecord, flattenJson, provideBlocksLocalization, provideBlocksLocalizationTesting, provideUilmScope, toFullLangCode, toShortLangCode };
+export type { BlocksLocalizationConfig, TranslationMap, UilmCacheStorage, UilmLangStorage, UilmLanguage, UilmLoadingStrategy, UilmModule, UilmModuleEntry, UilmScopeConfig };