@lukfel/ng-scaffold 22.0.6 → 22.1.1

package/README.md

@@ -1,7 +1,7 @@
 # Documentation
 ## Introduction
 
-This Angular library provides a foundational scaffold for modern web and mobile applications. It includes essential UI elements such as a header, sidebar, drawer, footer, floating button, and built-in services for theme switching, snackbar notifications, dialog management, and breakpoint detection. Simply wrap your `router-outlet` with the `lf-scaffold` element and configure the `ScaffoldConfig` within the `ScaffoldService`.
+This Angular library provides a foundational scaffold for modern web and mobile applications. It includes essential UI elements such as a header, sidebar, drawer, footer, floating button, and built-in services for theme switching, language switching, snackbar notifications, dialog management, and breakpoint detection. Simply wrap your `router-outlet` with the `lf-scaffold` element and configure the `ScaffoldConfig` within the `ScaffoldService`.
 
 - **NPM**: [@lukfel/ng-scaffold](https://www.npmjs.com/package/@lukfel/ng-scaffold)
 - **Demo**: [lukfel.github.io/ng-scaffold](https://lukfel.github.io/ng-scaffold)
@@ -278,6 +278,7 @@ This library includes several utility services:
 - **`RouterService`** – Track route changes and retrieve route history
 - **`SeoService`** – Manage meta tags
 - **`LocalStorageService`** – Handle local storage
+- **`TranslationService`** – Switch languages at runtime with per-locale JSON files
 
 ### Logger
 Logs information during development and hides all logs during production.
@@ -394,6 +395,52 @@ export class AppComponent {
 }
 ```
 
+### TranslationService
+Switches the application language at runtime by loading a separate JSON file per locale (e.g. `de.json`, `en.json`) that share the same keys. Keys missing from a locale are automatically resolved from the `fallbackLocale`.
+
+* **Note:** Configure the available locales in the `provideScaffold` provider and serve the `<locale>.json` files from the configured `path` (default `assets/i18n/`)
+
+```ts
+import { provideScaffold } from '@lukfel/ng-scaffold';
+
+  ...
+  providers: [
+    provideScaffold({
+      language: {
+        locales: ['de', 'en'],    // available locales (also drives a language picker)
+        fallbackLocale: 'en',     // used when a locale is unknown or a key is missing
+        path: 'assets/i18n/',     // (Optional) base path of the <locale>.json files
+        persist: true             // (Optional) store the active locale in local storage
+      }
+    })
+  ]
+```
+
+Inject the `TranslationService` to read the translations and switch the locale. Each app keeps its own strongly-typed `TransMap` interface and reads the labels through the typed accessors.
+
+```ts
+import { TranslationService } from '@lukfel/ng-scaffold';
+
+export class AppComponent {
+
+  private translationService = inject(TranslationService);
+
+  // Typed signal of the active translations (empty until the first load)
+  public transMap = this.translationService.transMapAs<TransMap>();
+
+  // Active locale and all configured locales (e.g. for a language picker)
+  public locale = this.translationService.locale;
+  public locales = this.translationService.locales;
+
+  // Switch the active language (persisted according to the config)
+  public changeLanguage(locale: string): void {
+    this.translationService.setLocale(locale);
+  }
+}
+```
+
+* **Note:** For observable consumers use `locale$` and `transMap$` (or the typed `transMapStream<TransMap>()`, which only emits once translations are loaded). Track the loading state with the `loading` signal or `loading$`.
+
 
 
 

package/fesm2022/lukfel-ng-scaffold.mjs

@@ -1,17 +1,18 @@
 import * as i0 from '@angular/core';
-import { InjectionToken, makeEnvironmentProviders, inject, Injectable, PLATFORM_ID, DOCUMENT, input, output, ChangeDetectionStrategy, Component, signal, effect, DestroyRef, viewChild, computed, model, afterNextRender, linkedSignal, TemplateRef, Directive, contentChild } from '@angular/core';
+import { InjectionToken, makeEnvironmentProviders, inject, Injectable, PLATFORM_ID, DOCUMENT, signal, input, output, ChangeDetectionStrategy, Component, effect, DestroyRef, viewChild, computed, model, afterNextRender, linkedSignal, TemplateRef, Directive, contentChild } from '@angular/core';
 import { BreakpointObserver, Breakpoints } from '@angular/cdk/layout';
 import { isPlatformBrowser, NgClass, NgTemplateOutlet, KeyValuePipe } from '@angular/common';
-import { toSignal, takeUntilDestroyed } from '@angular/core/rxjs-interop';
+import { toObservable, toSignal, takeUntilDestroyed } from '@angular/core/rxjs-interop';
 import * as i1$3 from '@angular/router';
 import { Router, RouteConfigLoadStart, RouteConfigLoadEnd, NavigationEnd, RouterModule, ActivatedRoute } from '@angular/router';
-import { distinctUntilChanged, firstValueFrom, BehaviorSubject, take, tap, map, fromEvent, debounceTime, finalize } from 'rxjs';
+import { distinctUntilChanged, firstValueFrom, BehaviorSubject, take, filter, tap, map, fromEvent, debounceTime, finalize } from 'rxjs';
 import { MatDialog, MatDialogRef, MAT_DIALOG_DATA } from '@angular/material/dialog';
 import { Overlay } from '@angular/cdk/overlay';
 import * as i1$2 from '@angular/cdk/portal';
 import { ComponentPortal, PortalModule } from '@angular/cdk/portal';
 import { Title, Meta } from '@angular/platform-browser';
 import { MatSnackBar } from '@angular/material/snack-bar';
+import { HttpClient } from '@angular/common/http';
 import * as i1 from '@angular/material/button';
 import { MatButtonModule } from '@angular/material/button';
 import * as i2 from '@angular/material/icon';
@@ -683,6 +684,179 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.0.5", ngImpor
                 }]
         }], ctorParameters: () => [] });
 
+const DEFAULT_CONFIG = {
+    path: 'assets/i18n/',
+    persist: true,
+};
+/**
+ * Runtime translation service that switches between per-locale JSON files.
+ *
+ * Configure it through `provideScaffold({ language: { ... } })`. Each app keeps
+ * its own strongly-typed `TransMap` interface and reads the labels via
+ * {@link TranslationService.transMapAs}.
+ */
+class TranslationService {
+    constructor() {
+        this.http = inject(HttpClient);
+        this.document = inject(DOCUMENT);
+        this.platformId = inject(PLATFORM_ID);
+        this.storage = inject(LocalStorageService);
+        this.logger = inject(Logger);
+        this.config = this.resolveConfig(inject(CONFIG, { optional: true })?.language);
+        this.STORAGE_KEY = 'LANGUAGE';
+        /** In-memory cache of raw (un-merged) locale files, keyed by locale. */
+        this.cache = new Map();
+        /** Distinct empty seed so `transMap$` can suppress the pre-load emission. */
+        this.EMPTY = {};
+        this._locale = signal(this.config.fallbackLocale, /* @ts-ignore */
+        ...(ngDevMode ? [{ debugName: "_locale" }] : /* istanbul ignore next */ []));
+        this._transMap = signal(this.EMPTY, /* @ts-ignore */
+        ...(ngDevMode ? [{ debugName: "_transMap" }] : /* istanbul ignore next */ []));
+        this._loading = signal(false, /* @ts-ignore */
+        ...(ngDevMode ? [{ debugName: "_loading" }] : /* istanbul ignore next */ []));
+        /** The active locale, e.g. `'de'`. */
+        this.locale = this._locale.asReadonly();
+        /** Labels for the active locale (with fallback keys merged in). */
+        this.transMap = this._transMap.asReadonly();
+        /** `true` while a locale file is being fetched. */
+        this.loading = this._loading.asReadonly();
+        /** All configured locales — drives a language picker. */
+        this.locales = this.config.locales;
+        /** Observable interop for `| async` templates and rxjs consumers. */
+        this.locale$ = toObservable(this._locale);
+        // Suppress the empty seed so subscribers only see loaded translations —
+        // consumers that guard on a falsy `transMap` (null/undefined) keep working.
+        this.transMap$ = toObservable(this._transMap).pipe(filter((transMap) => transMap !== this.EMPTY));
+        this.loading$ = toObservable(this._loading);
+        this.init();
+    }
+    /**
+     * Typed signal accessor: reads the active labels as the app's own `TransMap`
+     * shape, preserving compile-time key checking. Emits `{}` until the first load.
+     */
+    transMapAs() {
+        return this._transMap;
+    }
+    /**
+     * Typed observable accessor: like {@link transMapAs} but as a stream that only
+     * emits once translations are loaded (never the empty seed) — matching a
+     * `null`/`undefined`-until-loaded consumption pattern.
+     */
+    transMapStream() {
+        return this.transMap$;
+    }
+    /**
+     * Switch the active locale. Unknown locales fall back to `fallbackLocale`.
+     * Persistence is governed by the `persist` config option.
+     *
+     * @param locale target locale (must be one of the configured `locales`)
+     */
+    async setLocale(locale) {
+        await this.applyLocale(locale, this.config.persist);
+    }
+    async applyLocale(locale, persist) {
+        const target = this.config.locales.includes(locale)
+            ? locale
+            : this.config.fallbackLocale;
+        this._locale.set(target);
+        this.setHtmlLangAttribute(target);
+        if (persist) {
+            this.storage.setItem(this.STORAGE_KEY, target);
+        }
+        await this.loadTranslations(target);
+    }
+    init() {
+        // No locales configured — stay inert (no stray request to `<fallback>.json`).
+        if (!this.config.locales.length) {
+            return;
+        }
+        const stored = this.config.persist
+            ? this.storage.getItem(this.STORAGE_KEY)
+            : null;
+        const initial = stored && this.config.locales.includes(stored) ? stored : this.detectLocale();
+        // Already persisted (or intentionally not) — don't rewrite storage on startup.
+        this.applyLocale(initial, false);
+    }
+    detectLocale() {
+        if (!isPlatformBrowser(this.platformId)) {
+            return this.config.fallbackLocale;
+        }
+        const browserLocale = navigator.language.slice(0, 2);
+        return this.config.locales.includes(browserLocale) ? browserLocale : this.config.fallbackLocale;
+    }
+    async loadTranslations(locale) {
+        this._loading.set(true);
+        try {
+            const active = await this.fetchLocale(locale);
+            let merged = active;
+            if (locale !== this.config.fallbackLocale) {
+                try {
+                    const fallback = await this.fetchLocale(this.config.fallbackLocale);
+                    merged = deepMerge(fallback, active);
+                }
+                catch (error) {
+                    // Fallback file unavailable — keep the loaded active locale rather than
+                    // discarding it and rendering blank.
+                    this.logger.warn(`[TRANSLATION] Fallback locale '${this.config.fallbackLocale}' failed to load`, error);
+                }
+            }
+            // Ignore stale responses if the locale changed while loading.
+            if (this._locale() === locale) {
+                this._transMap.set(merged);
+            }
+        }
+        catch (error) {
+            this.logger.error(`[TRANSLATION] Failed to load locale '${locale}'`, error);
+        }
+        finally {
+            this._loading.set(false);
+        }
+    }
+    async fetchLocale(locale) {
+        const cached = this.cache.get(locale);
+        if (cached) {
+            return cached;
+        }
+        const data = await firstValueFrom(this.http.get(`${this.config.path}${locale}.json`));
+        this.cache.set(locale, data);
+        return data;
+    }
+    setHtmlLangAttribute(locale) {
+        this.document?.documentElement?.setAttribute('lang', locale);
+    }
+    resolveConfig(config) {
+        const path = config?.path ?? DEFAULT_CONFIG.path;
+        return {
+            locales: config?.locales ?? [],
+            fallbackLocale: config?.fallbackLocale ?? config?.locales?.[0] ?? 'en',
+            path: path.endsWith('/') ? path : `${path}/`,
+            persist: config?.persist ?? DEFAULT_CONFIG.persist,
+        };
+    }
+    static { this.ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "22.0.5", ngImport: i0, type: TranslationService, deps: [], target: i0.ɵɵFactoryTarget.Injectable }); }
+    static { this.ɵprov = i0.ɵɵngDeclareInjectable({ minVersion: "12.0.0", version: "22.0.5", ngImport: i0, type: TranslationService, providedIn: 'root' }); }
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.0.5", ngImport: i0, type: TranslationService, decorators: [{
+            type: Injectable,
+            args: [{ providedIn: 'root' }]
+        }], ctorParameters: () => [] });
+/** Deep-merges `override` onto `base`, returning a new object (pure). */
+function deepMerge(base, override) {
+    const result = { ...base };
+    for (const key of Object.keys(override)) {
+        const overrideValue = override[key];
+        const baseValue = result[key];
+        result[key] =
+            isTransMap(baseValue) && isTransMap(overrideValue)
+                ? deepMerge(baseValue, overrideValue)
+                : overrideValue;
+    }
+    return result;
+}
+function isTransMap(value) {
+    return typeof value === 'object' && value !== null;
+}
+
 class BottomBarComponent {
     constructor() {
         this.libraryConfig = input(null, /* @ts-ignore */
@@ -1669,5 +1843,5 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.0.5", ngImpor
  * Generated bundle index. Do not edit.
  */
 
-export { BreakpointService, CONFIG, ColorPickerComponent, DialogService, FileUploadComponent, ListComponent, ListItemAvatarDirective, ListItemButtonsDirective, ListItemSubtitleDirective, ListItemTitleDirective, LocalStorageService, Logger, NotificationComponent, OverlayService, PlaceholderComponent, RouterService, ScaffoldComponent, ScaffoldLoadingInterceptor, ScaffoldService, SeoService, SnackbarService, ThemeService, provideScaffold };
+export { BreakpointService, CONFIG, ColorPickerComponent, DialogService, FileUploadComponent, ListComponent, ListItemAvatarDirective, ListItemButtonsDirective, ListItemSubtitleDirective, ListItemTitleDirective, LocalStorageService, Logger, NotificationComponent, OverlayService, PlaceholderComponent, RouterService, ScaffoldComponent, ScaffoldLoadingInterceptor, ScaffoldService, SeoService, SnackbarService, ThemeService, TranslationService, provideScaffold };
 //# sourceMappingURL=lukfel-ng-scaffold.mjs.map