@cocoar/localization 0.1.0-beta.155 → 0.1.0

package/fesm2022/cocoar-localization.mjs

@@ -1,10 +1,10 @@
 import * as i0 from '@angular/core';
 import { signal, computed, Injectable, InjectionToken, inject, DestroyRef, makeEnvironmentProviders, APP_INITIALIZER, Pipe, ChangeDetectorRef } from '@angular/core';
-import { of, switchMap, tap, catchError, forkJoin, combineLatest, BehaviorSubject, Subject, lastValueFrom, map as map$1, distinctUntilChanged as distinctUntilChanged$1 } from 'rxjs';
+import { forkJoin, catchError, of, map, distinctUntilChanged, switchMap, tap, combineLatest, BehaviorSubject, Subject, lastValueFrom } from 'rxjs';
 import { ReadonlyState, BehaviorSubjectProxy } from '@cocoar/ts-utils';
-import { takeUntilDestroyed, toSignal } from '@angular/core/rxjs-interop';
+import { toSignal, takeUntilDestroyed } from '@angular/core/rxjs-interop';
 import { HttpClient } from '@angular/common/http';
-import { map, distinctUntilChanged } from 'rxjs/operators';
+import { map as map$1, distinctUntilChanged as distinctUntilChanged$1 } from 'rxjs/operators';
 import { Temporal } from '@js-temporal/polyfill';
 
 /**
@@ -64,6 +64,63 @@ class CoarLocalizationDataStore {
     clear() {
         this.store.set(new Map());
     }
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.0.6", ngImport: i0, type: CoarLocalizationDataStore, deps: [], target: i0.ɵɵFactoryTarget.Injectable });
+    static ɵprov = i0.ɵɵngDeclareInjectable({ minVersion: "12.0.0", version: "21.0.6", ngImport: i0, type: CoarLocalizationDataStore, providedIn: 'root' });
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.0.6", ngImport: i0, type: CoarLocalizationDataStore, decorators: [{
+            type: Injectable,
+            args: [{ providedIn: 'root' }]
+        }] });
+
+/**
+ * Deep merge utility for locale data.
+ * Later sources override earlier sources at the field level.
+ *
+ * @example
+ * ```ts
+ * const intl = { date: { pattern: 'dd.mm.yyyy', firstDayOfWeek: 1 }, number: {...} };
+ * const http = { date: { firstDayOfWeek: 0 } }; // Only override firstDayOfWeek
+ *
+ * const result = mergeLocalizationData([intl, http]);
+ * // Result: { date: { pattern: 'dd.mm.yyyy', firstDayOfWeek: 0 }, number: {...} }
+ * ```
+ */
+function mergeLocalizationData(sources) {
+    if (sources.length === 0)
+        return null;
+    const result = {};
+    for (const source of sources) {
+        if (!source)
+            continue;
+        // Merge code
+        if (source.code) {
+            result.code = source.code;
+        }
+        // Deep merge date
+        if (source.date) {
+            result.date = { ...result.date, ...source.date };
+        }
+        // Deep merge number
+        if (source.number) {
+            result.number = { ...result.number, ...source.number };
+        }
+        // Deep merge currency
+        if (source.currency) {
+            result.currency = {
+                ...result.currency,
+                ...source.currency,
+                symbols: { ...result.currency?.symbols, ...source.currency.symbols },
+            };
+        }
+        // Deep merge percent
+        if (source.percent) {
+            result.percent = { ...result.percent, ...source.percent };
+        }
+    }
+    // Ensure we have at least a code
+    if (!result.code)
+        return null;
+    return result;
 }
 
 /**
@@ -79,12 +136,19 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.0.6", ngImpor
             args: [{ providedIn: 'root' }]
         }] });
 /**
- * HTTP-based locale data loader.
- * Loads locale data from JSON files via HTTP.
+ * HTTP-based locale data loader with BCP 47 fallback.
  *
- * Supports custom URL patterns and headers for authentication/configuration.
+ * Loads locale data from JSON files via HTTP.
  * Typically used as a second source (after Intl) to provide business-specific overrides.
  *
+ * When a full BCP 47 tag is used (e.g., `de-AT`), the loader:
+ * 1. Loads the base language file (`de.json`)
+ * 2. Tries to load the regional file (`de-AT.json`)
+ * 3. Deep-merges them — regional fields override base fields
+ *
+ * If the regional file doesn't exist, the base file is used as-is.
+ * If the base file doesn't exist either, the loader fails (propagated to caller).
+ *
  * @example
  * ```typescript
  * // Simple base path
@@ -100,6 +164,15 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.0.6", ngImpor
  *   { 'Authorization': 'Bearer token' }
  * )
  * ```
+ *
+ * ## Expected file structure
+ * ```
+ * /locales/
+ *   en.json       ← base English overrides
+ *   en-AT.json    ← optional: Austrian-specific overrides on top of en.json
+ *   de.json       ← base German overrides
+ *   de-AT.json    ← optional: Austrian-specific overrides on top of de.json
+ * ```
  */
 class CoarHttpLocaleDataLoader extends CoarLocalizationDataLoader {
     httpClient;
@@ -112,12 +185,42 @@ class CoarHttpLocaleDataLoader extends CoarLocalizationDataLoader {
         this.headers = headers;
     }
     loadLocaleData(locale) {
+        const baseLanguage = extractBaseLanguage$1(locale);
+        if (baseLanguage) {
+            // BCP 47 tag with region (e.g., 'de-AT'):
+            // Load base ('de') first, then try regional ('de-AT'), deep-merge them.
+            return forkJoin([
+                this.loadFile(baseLanguage),
+                this.loadFile(locale).pipe(catchError(() => of(null))),
+            ]).pipe(map(([base, regional]) => {
+                if (!regional)
+                    return base;
+                return mergeLocalizationData([base, regional]) ?? base;
+            }));
+        }
+        // Simple language code (e.g., 'de'): load directly.
+        return this.loadFile(locale);
+    }
+    loadFile(locale) {
         const url = this.urlFn(locale);
         return this.httpClient.get(url, {
             headers: this.headers,
         });
     }
 }
+/**
+ * Extract the base language from a BCP 47 tag.
+ * Returns `null` if the tag has no region component.
+ *
+ * @example
+ * extractBaseLanguage('de-AT') // → 'de'
+ * extractBaseLanguage('en-US') // → 'en'
+ * extractBaseLanguage('de')    // → null
+ */
+function extractBaseLanguage$1(language) {
+    const hyphenIndex = language.indexOf('-');
+    return hyphenIndex > 0 ? language.substring(0, hyphenIndex) : null;
+}
 
 /**
  * Locale data loader that detects formatting from browser's Intl API.
@@ -353,6 +456,39 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.0.6", ngImpor
  */
 const COAR_I18N_PROVIDER = new InjectionToken('COAR_I18N_PROVIDER');
 
+/**
+ * Determines if a translation result should be considered "missing".
+ *
+ * A translation is considered missing if it is:
+ * - null or undefined
+ * - an empty string (after trim)
+ * - exactly equal to the requested key
+ *
+ * This provides unified missing-key semantics across different i18n engines.
+ *
+ * @param key - The translation key that was requested
+ * @param result - The result returned by the i18n service
+ * @returns true if the translation is missing, false otherwise
+ *
+ * @example
+ * ```ts
+ * coarIsMissingTranslation('coar.button.save', null) // true
+ * coarIsMissingTranslation('coar.button.save', '') // true
+ * coarIsMissingTranslation('coar.button.save', 'coar.button.save') // true
+ * coarIsMissingTranslation('coar.button.save', 'Save') // false
+ * ```
+ */
+function coarIsMissingTranslation(key, result) {
+    if (result == null) {
+        return true;
+    }
+    const trimmed = result.trim();
+    if (!trimmed) {
+        return true;
+    }
+    return trimmed === key;
+}
+
 /**
  * Interpolates {placeholders} in a template string using the given params.
  *
@@ -379,6 +515,75 @@ function coarInterpolate(template, params) {
     });
 }
 
+class CoarI18n {
+    provider = inject(COAR_I18N_PROVIDER, { optional: true });
+    locale = inject(CoarLocalizationService, { optional: true });
+    t(key, fallbackOrParams, maybeParams) {
+        let fallback;
+        let params;
+        if (typeof fallbackOrParams === 'string') {
+            // t(key, 'Fallback') or t(key, 'Fallback', params)
+            fallback = fallbackOrParams;
+            params = maybeParams;
+        }
+        else {
+            // t(key) or t(key, params)
+            params = fallbackOrParams;
+            fallback = undefined;
+        }
+        if (!this.provider) {
+            return coarInterpolate(fallback ?? key, params);
+        }
+        const raw = this.provider.t(key, params);
+        const base = coarIsMissingTranslation(key, raw) ? (fallback ?? key) : (raw ?? '');
+        // Important: the fallback (and even the key) may contain {placeholders}
+        return coarInterpolate(base, params);
+    }
+    /**
+     * Reactive variant that updates when the language changes.
+     * Uses CoarLocalizationService to detect language changes.
+     */
+    t$(key, params, fallback) {
+        if (!this.locale) {
+            return of(this.callT(key, params, fallback));
+        }
+        // Re-evaluate on every language change from CoarLocalizationService
+        return this.locale.languageState.value$.pipe(map(() => this.callT(key, params, fallback)), distinctUntilChanged());
+    }
+    /**
+     * Signal variant that updates when the language changes.
+     * Uses CoarLocalizationService to detect language changes.
+     */
+    tSignal(key, params, fallback) {
+        const obs$ = this.t$(key, params, fallback);
+        return toSignal(obs$, {
+            initialValue: this.callT(key, params, fallback),
+        });
+    }
+    // Small helper so t$ doesn't need to replicate the overload matrix.
+    callT(key, params, fallback) {
+        if (params && fallback !== undefined) {
+            // t(key, fallback, params)
+            return this.t(key, fallback, params);
+        }
+        if (params) {
+            // t(key, params)
+            return this.t(key, params);
+        }
+        if (fallback !== undefined) {
+            // t(key, fallback)
+            return this.t(key, fallback);
+        }
+        // t(key)
+        return this.t(key);
+    }
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.0.6", ngImport: i0, type: CoarI18n, deps: [], target: i0.ɵɵFactoryTarget.Injectable });
+    static ɵprov = i0.ɵɵngDeclareInjectable({ minVersion: "12.0.0", version: "21.0.6", ngImport: i0, type: CoarI18n });
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.0.6", ngImport: i0, type: CoarI18n, decorators: [{
+            type: Injectable
+        }] });
+
 /**
  * Injection token for translation loaders (multi-provider).
  * Loaders are executed in order and results are deep-merged.
@@ -409,10 +614,21 @@ const COAR_TRANSLATION_LOADERS = new InjectionToken('COAR_TRANSLATION_LOADERS');
 class CoarTranslationLoader {
 }
 /**
- * HTTP-based translation loader.
+ * HTTP-based translation loader with BCP 47 fallback.
  *
  * Loads translation JSON files from a configurable URL function.
  *
+ * When a full BCP 47 tag is used (e.g., `de-AT`), the loader:
+ * 1. Loads the base language file (`de.json`)
+ * 2. Tries to load the regional file (`de-AT.json`)
+ * 3. Merges them — regional keys override base keys
+ *
+ * If the regional file doesn't exist, the base file is used as-is.
+ * If the base file doesn't exist either, the loader fails (propagated to caller).
+ *
+ * This means `en.json` serves all English variants. An optional `en-AT.json`
+ * only needs to contain keys that differ from the base.
+ *
  * ## Usage
  * ```ts
  * const loader = new CoarHttpTranslationLoader();
@@ -420,6 +636,15 @@ class CoarTranslationLoader {
  * loader.headers = { 'Authorization': 'Bearer token' };
  * ```
  *
+ * ## Expected file structure
+ * ```
+ * /i18n/
+ *   en.json       ← base English (used for en-US, en-GB, en-AT, etc.)
+ *   en-AT.json    ← optional: only keys that differ from en.json
+ *   de.json       ← base German
+ *   de-AT.json    ← optional: Austrian overrides (if any)
+ * ```
+ *
  * ## Expected JSON format
  * ```json
  * {
@@ -436,6 +661,22 @@ class CoarHttpTranslationLoader {
     /** Optional HTTP headers */
     headers;
     loadTranslations(language) {
+        const baseLanguage = extractBaseLanguage(language);
+        if (baseLanguage) {
+            // BCP 47 tag with region (e.g., 'de-AT'):
+            // Load base ('de') first, then try regional ('de-AT'), merge them.
+            return forkJoin([
+                this.loadFile(baseLanguage),
+                this.loadFile(language).pipe(catchError(() => of(null))),
+            ]).pipe(map(([base, regional]) => ({
+                ...base,
+                ...(regional ?? {}),
+            })));
+        }
+        // Simple language code (e.g., 'de'): load directly.
+        return this.loadFile(language);
+    }
+    loadFile(language) {
         const url = this.urlFn(language);
         return this.http.get(url, {
             headers: this.headers,
@@ -447,6 +688,19 @@ class CoarHttpTranslationLoader {
 i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.0.6", ngImport: i0, type: CoarHttpTranslationLoader, decorators: [{
             type: Injectable
         }] });
+/**
+ * Extract the base language from a BCP 47 tag.
+ * Returns `null` if the tag has no region component.
+ *
+ * @example
+ * extractBaseLanguage('de-AT') // → 'de'
+ * extractBaseLanguage('en-US') // → 'en'
+ * extractBaseLanguage('de')    // → null
+ */
+function extractBaseLanguage(language) {
+    const hyphenIndex = language.indexOf('-');
+    return hyphenIndex > 0 ? language.substring(0, hyphenIndex) : null;
+}
 
 /**
  * Flattens nested translation objects into dot notation.
@@ -1020,13 +1274,13 @@ class CoarTimeZoneService {
         const providerStreams = allProviders.map((provider) => provider.timeZone$);
         this.timeZone$ = combineLatest(providerStreams).pipe(
         // Find first non-null value in priority order
-        map((timeZones) => {
+        map$1((timeZones) => {
             const resolved = timeZones.find((tz) => tz !== null);
             // UTC as safety net if all providers return null (shouldn't happen)
             return resolved ?? 'UTC';
         }), 
         // Prevent unnecessary emissions when value doesn't actually change
-        distinctUntilChanged());
+        distinctUntilChanged$1());
         // Initialize signal after timeZone$ is set up
         this.currentTimeZone = toSignal(this.timeZone$, { requireSync: true });
     }
@@ -1107,6 +1361,8 @@ function provideCoarLocalization(config) {
             provide: COAR_I18N_PROVIDER,
             useClass: CoarI18nService,
         },
+        // i18n: Convenience service used by CoarI18nPipe and consumers
+        CoarI18n,
         // i18n: Auto-include Intl source as first translation loader (provides common defaults)
         {
             provide: COAR_TRANSLATION_LOADERS,
@@ -1142,57 +1398,6 @@ function provideCoarLocalization(config) {
     ]);
 }
 
-/**
- * Deep merge utility for locale data.
- * Later sources override earlier sources at the field level.
- *
- * @example
- * ```ts
- * const intl = { date: { pattern: 'dd.mm.yyyy', firstDayOfWeek: 1 }, number: {...} };
- * const http = { date: { firstDayOfWeek: 0 } }; // Only override firstDayOfWeek
- *
- * const result = mergeLocalizationData([intl, http]);
- * // Result: { date: { pattern: 'dd.mm.yyyy', firstDayOfWeek: 0 }, number: {...} }
- * ```
- */
-function mergeLocalizationData(sources) {
-    if (sources.length === 0)
-        return null;
-    const result = {};
-    for (const source of sources) {
-        if (!source)
-            continue;
-        // Merge code
-        if (source.code) {
-            result.code = source.code;
-        }
-        // Deep merge date
-        if (source.date) {
-            result.date = { ...result.date, ...source.date };
-        }
-        // Deep merge number
-        if (source.number) {
-            result.number = { ...result.number, ...source.number };
-        }
-        // Deep merge currency
-        if (source.currency) {
-            result.currency = {
-                ...result.currency,
-                ...source.currency,
-                symbols: { ...result.currency?.symbols, ...source.currency.symbols },
-            };
-        }
-        // Deep merge percent
-        if (source.percent) {
-            result.percent = { ...result.percent, ...source.percent };
-        }
-    }
-    // Ensure we have at least a code
-    if (!result.code)
-        return null;
-    return result;
-}
-
 /**
  * Core locale service responsible for language management.
  *
@@ -1663,105 +1868,8 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.0.6", ngImpor
                 }]
         }] });
 
-/**
- * Determines if a translation result should be considered "missing".
- *
- * A translation is considered missing if it is:
- * - null or undefined
- * - an empty string (after trim)
- * - exactly equal to the requested key
- *
- * This provides unified missing-key semantics across different i18n engines.
- *
- * @param key - The translation key that was requested
- * @param result - The result returned by the i18n service
- * @returns true if the translation is missing, false otherwise
- *
- * @example
- * ```ts
- * coarIsMissingTranslation('coar.button.save', null) // true
- * coarIsMissingTranslation('coar.button.save', '') // true
- * coarIsMissingTranslation('coar.button.save', 'coar.button.save') // true
- * coarIsMissingTranslation('coar.button.save', 'Save') // false
- * ```
- */
-function coarIsMissingTranslation(key, result) {
-    if (result == null) {
-        return true;
-    }
-    const trimmed = result.trim();
-    if (!trimmed) {
-        return true;
-    }
-    return trimmed === key;
-}
-
-class CoarI18n {
-    provider = inject(COAR_I18N_PROVIDER);
-    locale = inject(CoarLocalizationService);
-    t(key, fallbackOrParams, maybeParams) {
-        let fallback;
-        let params;
-        if (typeof fallbackOrParams === 'string') {
-            // t(key, 'Fallback') or t(key, 'Fallback', params)
-            fallback = fallbackOrParams;
-            params = maybeParams;
-        }
-        else {
-            // t(key) or t(key, params)
-            params = fallbackOrParams;
-            fallback = undefined;
-        }
-        const raw = this.provider.t(key, params);
-        const base = coarIsMissingTranslation(key, raw) ? (fallback ?? key) : (raw ?? '');
-        // Important: the fallback (and even the key) may contain {placeholders}
-        return coarInterpolate(base, params);
-    }
-    /**
-     * Reactive variant that updates when the language changes.
-     * Uses CoarLocalizationService to detect language changes.
-     */
-    t$(key, params, fallback) {
-        // Re-evaluate on every language change from CoarLocalizationService
-        return this.locale.languageState.value$.pipe(map$1(() => this.callT(key, params, fallback)), distinctUntilChanged$1());
-    }
-    /**
-     * Signal variant that updates when the language changes.
-     * Uses CoarLocalizationService to detect language changes.
-     */
-    tSignal(key, params, fallback) {
-        const obs$ = this.t$(key, params, fallback);
-        return toSignal(obs$, {
-            initialValue: this.callT(key, params, fallback),
-        });
-    }
-    // Small helper so t$ doesn't need to replicate the overload matrix.
-    callT(key, params, fallback) {
-        if (params && fallback !== undefined) {
-            // t(key, fallback, params)
-            return this.t(key, fallback, params);
-        }
-        if (params) {
-            // t(key, params)
-            return this.t(key, params);
-        }
-        if (fallback !== undefined) {
-            // t(key, fallback)
-            return this.t(key, fallback);
-        }
-        // t(key)
-        return this.t(key);
-    }
-    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.0.6", ngImport: i0, type: CoarI18n, deps: [], target: i0.ɵɵFactoryTarget.Injectable });
-    static ɵprov = i0.ɵɵngDeclareInjectable({ minVersion: "12.0.0", version: "21.0.6", ngImport: i0, type: CoarI18n, providedIn: 'root' });
-}
-i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.0.6", ngImport: i0, type: CoarI18n, decorators: [{
-            type: Injectable,
-            args: [{ providedIn: 'root' }]
-        }] });
-
 class CoarI18nPipe {
-    i18n = inject(CoarI18n);
+    i18n = inject(CoarI18n, { optional: true });
     cdr = inject(ChangeDetectorRef);
     subject = new BehaviorSubjectProxy('');
     lastKey;
@@ -1795,6 +1903,10 @@ class CoarI18nPipe {
                 fallback = maybeFallbackOrParams;
             }
         }
+        // No i18n service available — return fallback or key
+        if (!this.i18n) {
+            return coarInterpolate(fallback ?? key, params);
+        }
         // Compare inputs to determine if a new subscription is needed
         const paramsJson = params ? JSON.stringify(params) : undefined;
         if (key !== this.lastKey ||