@lukfel/ng-scaffold 22.0.6 → 22.1.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lukfel/ng-scaffold",
-  "version": "22.0.6",
+  "version": "22.1.2",
   "description": "This Angular library provides a basic UI scaffold and services for modern web and mobile apps",
   "license": "MIT",
   "author": {

package/types/lukfel-ng-scaffold.d.ts

@@ -1,5 +1,5 @@
 import * as _angular_core from '@angular/core';
-import { InjectionToken, EnvironmentProviders, ElementRef, TemplateRef, Type } from '@angular/core';
+import { InjectionToken, EnvironmentProviders, ElementRef, TemplateRef, Type, Signal } from '@angular/core';
 import { ComponentType, ComponentPortal, TemplatePortal } from '@angular/cdk/portal';
 import { CdkDragDrop } from '@angular/cdk/drag-drop';
 import { MatCheckboxChange } from '@angular/material/checkbox';
@@ -115,9 +115,36 @@ interface HeaderInputConfig {
     autoFocus?: boolean;
 }
 
+interface TranslationConfig {
+    /**
+     * Available locales, e.g. `['de', 'en', 'fr']`. Drives the language picker and
+     * the browser-language detection on startup.
+     */
+    locales: string[];
+    /**
+     * Locale used when the requested one is unknown or fails to load, and
+     * deep-merged under the active locale so keys missing from a partial locale
+     * resolve to its text instead of rendering blank, e.g. `'en'`.
+     */
+    fallbackLocale: string;
+    /**
+     * Base path the `<locale>.json` files are served from.
+     *
+     * @default 'assets/i18n/'
+     */
+    path?: string;
+    /**
+     * Persist the active locale in the LocalStorage and restore it on startup.
+     *
+     * @default true
+     */
+    persist?: boolean;
+}
+
 interface ScaffoldLibraryConfig {
     production?: boolean;
     debugging?: boolean;
+    language?: TranslationConfig;
 }
 
 interface ListItem {
@@ -204,6 +231,17 @@ interface SeoConfig {
     autoTrim?: boolean;
 }
 
+/**
+ * Recursive shape of a loaded translation JSON file.
+ *
+ * The library stays intentionally loose here: each consuming app owns its own
+ * strongly-typed `TransMap` interface and reads the service through
+ * `TranslationService.transMapAs<AppTransMap>()` to keep full type-safety.
+ */
+type TransMap = {
+    [key: string]: string | TransMap;
+};
+
 declare const CONFIG: InjectionToken<ScaffoldLibraryConfig>;
 declare function provideScaffold(config?: ScaffoldLibraryConfig): EnvironmentProviders;
 
@@ -630,6 +668,70 @@ declare class ThemeService {
     static ɵprov: _angular_core.ɵɵInjectableDeclaration<ThemeService>;
 }
 
+/**
+ * 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}.
+ */
+declare class TranslationService {
+    private readonly http;
+    private readonly document;
+    private readonly platformId;
+    private readonly storage;
+    private readonly logger;
+    private readonly config;
+    private readonly STORAGE_KEY;
+    /** In-memory cache of raw (un-merged) locale files, keyed by locale. */
+    private readonly cache;
+    /** Distinct empty seed so `transMap$` can suppress the pre-load emission. */
+    private readonly EMPTY;
+    private readonly _locale;
+    private readonly _transMap;
+    private readonly _loading;
+    /** The active locale, e.g. `'de'`. */
+    readonly locale: Signal<string>;
+    /** Labels for the active locale (with fallback keys merged in). */
+    readonly transMap: Signal<TransMap>;
+    /** `true` while a locale file is being fetched. */
+    readonly loading: Signal<boolean>;
+    /** All configured locales — drives a language picker. */
+    readonly locales: readonly string[];
+    /** Observable interop for `| async` templates and rxjs consumers. */
+    readonly locale$: Observable<string>;
+    readonly transMap$: Observable<TransMap>;
+    readonly loading$: Observable<boolean>;
+    constructor();
+    /**
+     * 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<T>(): Signal<T>;
+    /**
+     * 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<T>(): Observable<T>;
+    /**
+     * 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`)
+     */
+    setLocale(locale: string): Promise<void>;
+    private applyLocale;
+    private init;
+    private detectLocale;
+    private loadTranslations;
+    private fetchLocale;
+    private setHtmlLangAttribute;
+    private resolveConfig;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<TranslationService, never>;
+    static ɵprov: _angular_core.ɵɵInjectableDeclaration<TranslationService>;
+}
+
 declare class ScaffoldLoadingInterceptor implements HttpInterceptor {
     libraryConfig: ScaffoldLibraryConfig | null;
     private scaffoldService;
@@ -642,5 +744,5 @@ declare class ScaffoldLoadingInterceptor implements HttpInterceptor {
     static ɵprov: _angular_core.ɵɵInjectableDeclaration<ScaffoldLoadingInterceptor>;
 }
 
-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 type { BottomBarConfig, Button, ConfirmDialogConfig, ContentTitleCardConfig, DrawerConfig, FloatingButtonConfig, FooterConfig, HeaderConfig, HeaderInputConfig, HeaderResponsiveConfig, ListConfig, ListHeader, ListItem, LoadingOverlayConfig, MenuButton, NavbarConfig, NavigationLink, PlaceholderConfig, ScaffoldConfig, ScaffoldLibraryConfig, SeoConfig };
+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 };
+export type { BottomBarConfig, Button, ConfirmDialogConfig, ContentTitleCardConfig, DrawerConfig, FloatingButtonConfig, FooterConfig, HeaderConfig, HeaderInputConfig, HeaderResponsiveConfig, ListConfig, ListHeader, ListItem, LoadingOverlayConfig, MenuButton, NavbarConfig, NavigationLink, PlaceholderConfig, ScaffoldConfig, ScaffoldLibraryConfig, SeoConfig, TransMap, TranslationConfig };