@reforgium/presentia 1.3.0 → 1.4.0

package/README.md

@@ -3,195 +3,490 @@
 [![npm version](https://badge.fury.io/js/%40reforgium%2Fpresentia.svg)](https://www.npmjs.com/package/@reforgium/presentia)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-**Signals-first state stores and caching utilities for Angular (18+).**
-
-Presentia Contents:
-- Providers and initialization: [`provideReInit`](`src/providers/init.provider.ts`) (locale, themes, breakpoints).
-- Localization: [`LangService`](`src/lang/lang.service.ts`), [`LangPipe`](`src/lang/lang.pipe.ts`), [`LangDirective`](`src/lang/lang.directive.ts`).
-- Themes: [`ThemeService`](`src/theme/theme.service.ts`).
-- Adaptivity: [`AdaptiveService`](`src/adaptive/adaptive.service.ts`), [`IfDeviceDirective`](`src/adaptive/device-type.directive.ts`).
-
-Designed for **application infrastructure**.
-
----
-
-## Installation
+Infrastructure package for Angular applications:
+- localization (`LangService`, `lang` pipe, `reLang` directive),
+- theming (`ThemeService`),
+- adaptive behavior (`AdaptiveService`, `*reIfDevice`),
+- route state helper (`RouteWatcher`),
+- SEO automation (`SeoService`, `SeoRouteListener`).
+
+## Release Highlights (1.4.0)
+
+- Extended localization HTTP pipeline:
+`requestBuilder`, `requestOptionsFactory`, `responseAdapter`.
+- Batch namespace loading:
+`loadNamespaces`, `batchRequestBuilder`, `batchResponseAdapter`.
+- Namespace cache policy:
+`namespaceCache.maxNamespaces`, `namespaceCache.ttlMs`,
+plus `evictNamespace` and `clearNamespaceCache`.
+- Typed localization keys support:
+`LangKeyRegistry` extension point for `get()` and `observe()`.
+- Consumer CLI for key generation:
+`presentia-gen-lang-keys`.
+
+## Install
 
 ```bash
-npm install @reforgium/presentia
+npm i @reforgium/presentia
 ```
 
-The provider factory [`provideReInit(config: AppConfig)`](`src/providers/init.provider.ts`) performs basic application setup: localization, adaptive breakpoints, store config, and DI tokens for validation messages.
-Location: [`init.provider.ts`](`src/providers/init.provider.ts`).
+## Quick Start
 
-What it does:
-- Registers DI tokens:
-  - `DEVICE_BREAKPOINTS` (breakpoints for AdaptiveService).
-  - `THEME_CONFIG` (theme configuration and dark theme prefix).
-  - `LANG_CONFIG`, `LOCALE_ID` (languages and dictionaries for `LangService`).
-  - `LANG_PIPE_CONFIG` (optional cache settings for `LangPipe`).
-
-Example integration in the root application:
 ```ts
+import { bootstrapApplication } from '@angular/platform-browser';
+import { provideReInit } from '@reforgium/presentia';
+
 bootstrapApplication(AppComponent, {
   providers: [
     provideReInit({
       locale: {
+        url: '/assets/i18n',
         isFromAssets: true,
         defaultLang: 'ru',
+        fallbackLang: 'en',
+        supportedLangs: ['de'],
+        preloadNamespaces: ['layout', 'common'],
       },
       langPipe: {
-        ttlMs: 300000,
+        ttlMs: 300_000,
         maxCacheSize: 500,
+        placeholder: '...',
       },
-      theme: {
-        defaultTheme: 'dark',
-        darkThemePrefix: 're-dark',
-      },
-      breakpoints: {
-        'mobile': '(max-width: 719px)',
-        'tablet': '(min-width: 720px) and (max-width: 1399px)',
-        'desktop-s': '(min-width: 1400px) and (max-width: 1919px)',
-        'desktop': '(min-width: 1920px)',
-      },
+      langMissingKeyHandler: (key, ctx) => `[${ctx.lang}] ${key}`,
+      theme: { defaultTheme: 'light', darkThemePrefix: 'dark' },
     }),
   ],
 });
 ```
 
----
+## What You Get
+
+Main provider:
+- `provideReInit(config: AppConfig)`
+
+Localization exports:
+- `LangService`
+- `LangPipe`
+- `LangDirective`
+- `LANG_CONFIG`
+- `LANG_PIPE_CONFIG`
+- `LANG_MISSING_KEY_HANDLER`
+- Types: `LocaleConfig`, `LangModel`, `LangDto`, `LangParams`, `LangKey`, `LangKeyRegistry`, etc.
+
+Theme exports:
+- `ThemeService`
+- `THEME_CONFIG`
+- `themes`, `darkThemePrefix`
 
-## Package Structure
+Adaptive exports:
+- `AdaptiveService`
+- `IfDeviceDirective`
+- `DEVICE_BREAKPOINTS`, `defaultBreakpoints`
 
-- **seo** - SEO management (title, meta, open graph, twitter, json-ld) with route tracking.
-- **lang** - signals-based localization with dynamic dictionary loading.
-- **theme** - light/dark theme management with system sync.
-- **adaptive** - responsive breakpoints tracking and device-specific rendering.
+Routes and SEO exports:
+- `RouteWatcher`
+- `SeoService`
+- `SeoRouteListener`
 
----
+## `provideReInit` Configuration
 
-## Localization: LangService, LangPipe, LangDirective
+`AppConfig` includes:
+- `locale: LocaleConfig` (required)
+- `theme?: ThemeConfig`
+- `breakpoints?: DeviceBreakpoints`
+- `langPipe?: LangPipeConfig`
+- `langMissingKeyHandler?: LangMissingKeyHandler`
 
-- [`LangService`](`src/lang/lang.service.ts`) - manages current language and dictionaries (static/dynamic), provides signal selectors for translation by key.
-- [`LangPipe`](`src/lang/lang.pipe.ts`), `pure: false` - dynamically translates strings by key and parameters: `{{ 'app.hello' | lang:{ name: userName } }}`. Cache options: provide `LANG_PIPE_CONFIG` (defaults: `ttlMs: 300000`, `maxCacheSize: 500`, optional `placeholder`).
-- [`LangDirective`](`src/lang/lang.directive.ts`) - directive for automatic translation of attributes (`title`, `label`, `placeholder`) and text. Usage: `<input placeholder="common.search" reLang />`. Explicit key: `<div [reLang]="'common.hello'"></div>` or `<div [reLangKey]="'common.hello'"></div>`. Explicit attribute map: `<input [reLangAttrs]="{ 'aria-label': 'forms.username' }" />`. Config object: `<div [reLang]="{ mode: 'only-content', textKey: 'common.hello', attrs: { 'aria-label': 'forms.username' } }"></div>`.
-- [`LANG_CONFIG`] - InjectionToken with translation source configuration.
-- Types: `Langs`, `LangParams`, `LangModel`, `LangDto`, `LocaleConfig`.
+It also wires integration tokens from `@reforgium/internal`:
+- `TRANSLATION`
+- `SELECTED_LANG`
+- `CHANGE_LANG`
+- `SELECTED_THEME`
+- `CHANGE_THEME`
+- `CURRENT_DEVICE`
+
+## Localization
+
+### `LocaleConfig`
 
-Example:
 ```ts
-import { Component, computed, inject } from '@angular/core';
-import { LangPipe, LangService } from '.../lang';
-
-@Component({
-  selector: 'app-hello',
-  standalone: true,
-  imports: [LangPipe],
-  template: `
-    <h1>{{ 'common.hello' | lang }}</h1>
-    <p>{{ 'users.welcome' | lang: { name: userName } }}</p>
-    <button (click)="switch()">RU/KG</button>
-  `,
-})
-export class HelloComponent {
-  private lang = inject(LangService);
-  userName = 'Vasya';
-
-  switch() {
-    this.lang.setLang(this.lang.currentLang() === 'ru' ? 'kg' : 'ru');
-  }
-}
+type LocaleConfig = {
+  url: string;
+  isFromAssets: boolean;
+  defaultLang?: Langs;
+  fallbackLang?: Langs;
+  defaultValue?: string;
+  kgValue?: 'kg' | 'ky';
+  supportedLangs?: readonly string[];
+  preloadNamespaces?: readonly string[];
+  requestBuilder?: (ctx: {
+    ns: string;
+    lang: Langs;
+    isFromAssets: boolean;
+    baseUrl: string;
+  }) => string;
+  requestOptionsFactory?: (ctx: {
+    ns: string;
+    lang: Langs;
+    isFromAssets: boolean;
+    baseUrl: string;
+  }) => {
+    headers?: HttpHeaders | Record<string, string | string[]>;
+    params?: HttpParams | Record<string, string | number | boolean | readonly (string | number | boolean)[]>;
+    withCredentials?: boolean;
+    responseType?: 'json' | 'text' | 'blob' | 'arraybuffer';
+    context?: HttpContext;
+    transferCache?: boolean | { includeHeaders?: string[] };
+  };
+  responseAdapter?: (response: unknown, ctx: {
+    ns: string;
+    lang: Langs;
+    isFromAssets: boolean;
+  }) => LangModel | LangDto[];
+  batchRequestBuilder?: (ctx: {
+    namespaces: readonly string[];
+    lang: Langs;
+    isFromAssets: boolean;
+    baseUrl: string;
+  }) => string;
+  batchResponseAdapter?: (response: unknown, ctx: {
+    namespaces: readonly string[];
+    lang: Langs;
+    isFromAssets: boolean;
+  }) => Record<string, LangModel | LangDto[]>;
+  namespaceCache?: {
+    maxNamespaces?: number;
+    ttlMs?: number;
+  };
+};
 ```
 
----
+### Behavior Notes
 
-## Theming: ThemeService
+- Built-in languages: `ru`, `kg`, `en`.
+- Alias `ky` is accepted and normalized to internal `kg`.
+- `supportedLangs` lets you add custom language codes.
+- If key is missing, `defaultValue` is used (or missing key handler result).
+- Stale HTTP responses are ignored when language changes mid-flight.
 
-- [`ThemeService`](`src/theme/theme.service.ts`) - manages light/dark theme.
-  - Methods: `switch()`, `isLight()`, etc.
+### Basic Usage
 
----
+```ts
+const lang = inject(LangService);
 
-## Adaptivity: AdaptiveService and IfDeviceDirective
+lang.setLang('en');
+await lang.loadNamespace('layout');
 
-- [`AdaptiveService`](`src/adaptive/adaptive.service.ts`) - tracks sizes, device type (mobile/tablet/desktop), supports signals for width/height/orientation.
-- [`IfDeviceDirective`](`src/adaptive/device-type.directive.ts`) - structural directive for conditional display by device type.
+const title = lang.get('layout.title');
+const welcome = lang.get('layout.welcome', { name: 'John' });
+```
 
-How `IfDeviceDirective` works:
-- Selector: `[reIfDevice]` (standalone).
-- Inputs:
-  - `reIfDevice: Devices | Devices[]` - allowed device types (one or list).
-  - `inverse?: boolean` - invert condition (show everywhere except specified devices).
-- Reactively tracks current device type from `AdaptiveService.device`, creates/clears embedded view.
+### API Mode With Custom Payload
 
-Usage examples:
-```html
-<!-- 1) Mobile only -->
-<div *reIfDevice="'mobile'">Mobile phones only</div>
+```ts
+provideReInit({
+  locale: {
+    url: '/api/i18n',
+    isFromAssets: false,
+    requestBuilder: ({ ns, lang, baseUrl }) => `${baseUrl}/${ns}?language=${lang}`,
+    requestOptionsFactory: () => ({
+      headers: { 'x-tenant-id': 'tenant-1' },
+      withCredentials: true,
+      responseType: 'json',
+    }),
+    responseAdapter: (response) => (response as { data: LangDto[] }).data,
+  },
+});
+```
+
+### Batch Namespace Loading
+
+```ts
+provideReInit({
+  locale: {
+    url: '/api/i18n',
+    isFromAssets: false,
+    batchRequestBuilder: ({ lang, namespaces }) =>
+      `/api/i18n/batch?language=${lang}&ns=${namespaces.join(',')}`,
+    batchResponseAdapter: (response) => response as Record<string, LangDto[]>,
+  },
+});
 
-<!-- 2) Tablets and desktops -->
-<div *reIfDevice="['tablet', 'desktop']">Tablet and desktop</div>
+const lang = inject(LangService);
+await lang.loadNamespaces(['layout', 'common', 'breadcrumbs']);
+```
+
+### Namespace Cache Policy
 
-<!-- 3) Hide on desktop (inverse) -->
-<div *reIfDevice="'desktop'; inverse: true">Visible everywhere except desktop</div>
+```ts
+provideReInit({
+  locale: {
+    url: '/assets/i18n',
+    isFromAssets: true,
+    namespaceCache: {
+      maxNamespaces: 20,
+      ttlMs: 10 * 60 * 1000,
+    },
+  },
+});
 ```
 
----
+Cache control methods:
+- `lang.evictNamespace('layout')`
+- `lang.clearNamespaceCache()`
+
+### Copy-Paste Recipes
 
-## SEO: SeoService and SeoRouteListener
-- [`SeoService`](`src/seo/seo.service.ts`) - service for working with SEO
+#### 1. Assets JSON (simple frontend-only i18n)
 
-Example:
 ```ts
-const service = inject(SeoService);
+provideReInit({
+  locale: {
+    url: '/assets/locales',
+    isFromAssets: true,
+    defaultLang: 'en',
+    fallbackLang: 'en',
+    preloadNamespaces: ['layout', 'common'],
+  },
+});
+```
+
+Expected files:
+- `/assets/locales/layout.en.json`
+- `/assets/locales/common.en.json`
 
-service.setTitle('My page');
-service.setDescription('My page description');
-service.setKeywords(['angular', 'signals', 'seo', 'meta']);
-service.setCanonical('https://example.com/page');
-service.setTwitter({ card: 'summary_large_image', site: '@myapp' });
+#### 2. Flat API DTO (`LangDto[]`)
+
+```ts
+provideReInit({
+  locale: {
+    url: '/api/i18n',
+    isFromAssets: false,
+    requestBuilder: ({ ns, lang, baseUrl }) => `${baseUrl}/${ns}?language=${lang}`,
+    // default parser already supports LangDto[]
+  },
+});
 ```
 
-- [`SeoRouteListener`](`src/seo/seo-route.listener.ts`) - service for working with SEO, with route tracking
+Expected payload:
+
+```json
+[
+  { "namespace": "layout", "code": "layout.title", "localization": "Dashboard" }
+]
+```
+
+#### 3. Envelope API DTO (`{ data: [...] }`)
 
-Example:
 ```ts
-bootstrapApplication(AppComponent, {
-  providers: [provideRouter(routes)],
-}).then(ref => {
-  // base site URL
-  ref.injector.get(SeoRouteListener).init('https://example.com');
+provideReInit({
+  locale: {
+    url: '/api/i18n',
+    isFromAssets: false,
+    responseAdapter: (response) => (response as { data: LangDto[] }).data,
+  },
 });
+```
 
-export default [
-  {
-    path: '',
-    loadComponent: () => import('./pages/home.page').then(m => m.HomePage),
-    data: {
-      title: 'Home - MyApp',
-      description: 'Home page description',
-      og: { image: 'https://example.com/og/home.png', type: 'website', site_name: 'MyApp' },
-      twitter: { card: 'summary_large_image', site: '@myapp' },
-      jsonld: {
-        '@context': 'https://schema.org',
-        '@type': 'WebSite',
-        name: 'MyApp',
-        url: 'https://example.com'
-      }
-    },
+Expected payload:
+
+```json
+{
+  "data": [{ "namespace": "layout", "code": "layout.title", "localization": "Dashboard" }]
+}
+```
+
+#### 4. Multi-tenant API with headers and params
+
+```ts
+provideReInit({
+  locale: {
+    url: '/api/i18n',
+    isFromAssets: false,
+    requestOptionsFactory: ({ lang }) => ({
+      headers: { 'x-tenant-id': 'tenant-1' },
+      params: { region: 'eu', language: lang },
+      withCredentials: true,
+    }),
+    requestBuilder: ({ ns, baseUrl }) => `${baseUrl}/${ns}`,
   },
-]
+});
+```
+
+#### 5. Batch endpoint (`/batch`) for many namespaces
+
+```ts
+provideReInit({
+  locale: {
+    url: '/api/i18n',
+    isFromAssets: false,
+    batchRequestBuilder: ({ namespaces, lang, baseUrl }) =>
+      `${baseUrl}/batch?language=${lang}&ns=${namespaces.join(',')}`,
+    batchResponseAdapter: (response) =>
+      response as Record<string, LangDto[]>,
+  },
+});
+
+const lang = inject(LangService);
+await lang.loadNamespaces(['layout', 'common', 'breadcrumbs']);
+```
+
+## `LangPipe`
+
+- Name: `lang`
+- Standalone, impure pipe (`pure: false`)
+- Internal cache with TTL and max size
+- Configurable placeholder while namespace is loading
+
+```html
+<h1>{{ 'layout.title' | lang }}</h1>
+<p>{{ 'users.welcome' | lang: { name: userName, count: 12 } }}</p>
+```
+
+`LangPipeConfig` (via `LANG_PIPE_CONFIG` or `provideReInit.langPipe`):
+- `ttlMs?: number`
+- `maxCacheSize?: number`
+- `placeholder?: string | ((query: string) => string)`
+
+## `reLang` Directive
+
+Auto-localizes text and selected attributes.
+
+Supported modes:
+- `'all'`
+- `'only-content'`
+- `'only-placeholder'`
+- `'only-label'`
+- `'only-title'`
+
+Examples:
+
+```html
+<button reLang title="common.save">common.save</button>
+<button [reLang]="'only-title'" title="common.cancel">Cancel</button>
+<input reLang [langForAttr]="'aria-label'" aria-label="forms.username" />
+<div [reLang]="{ mode: 'only-content', textKey: 'layout.title' }"></div>
+```
+
+## Typed Lang Keys (Opt-in)
+
+`LangService.get()` and `LangService.observe()` support typed keys via module augmentation.
+
+Generate keys from locale JSON in consumer app:
+
+```bash
+npx presentia-gen-lang-keys --locales src/assets/locales --out src/types/presentia-lang-keys.d.ts
+```
+
+This generates:
+- `declare module '@reforgium/presentia'`
+- `interface LangKeyRegistry { keys: 'layout.title' | 'common.save' | ... }`
+
+After generation, invalid keys in `get()`/`observe()` are compile-time errors.
+
+## Theme
+
+`ThemeService`:
+- `theme()` current theme (`'light' | 'dark'`)
+- `isLight()`
+- `switch(theme?)` explicit switch or toggle
+
+```ts
+const theme = inject(ThemeService);
+theme.switch('dark');
 ```
 
----
+`ThemeConfig`:
+- `defaultTheme?: 'light' | 'dark'`
+- `darkThemePrefix?: string`
 
-## Compatibility
+## Adaptive
 
-- Angular: 18+
-- Signals: required
-- Zone.js: optional
+`AdaptiveService` provides reactive signals:
+- `device()` -> `'desktop' | 'tablet' | 'mobile'`
+- `width()`
+- `height()`
+- `isDesktop()`
+- `isPortrait()`
+
+`*reIfDevice` structural directive:
+
+```html
+<div *reIfDevice="'desktop'">Desktop only</div>
+<div *reIfDevice="['mobile', 'tablet']">Mobile and tablet</div>
+<div *reIfDevice="'mobile'; inverse: true">Hidden on mobile</div>
+```
+
+Breakpoints are configurable via `DeviceBreakpoints`.
+
+## Route State Helper
+
+`RouteWatcher` gives reactive deepest-route snapshot:
+- `params()`
+- `query()`
+- `data()`
+- `url()`
+- `fragment()`
+- `state()`
+- `selectData<T>(key)`
+
+Use when you want route-derived UI state without manual router subscriptions.
+
+## SEO
+
+### `SeoService`
+
+Methods:
+- `setTitle`
+- `setDescription`
+- `setKeywords`
+- `setRobots`
+- `setCanonical`
+- `setOg`
+- `setTwitter`
+- `setJsonLd`
+
+### `SeoRouteListener`
+
+Auto-applies SEO from route `data` on navigation:
+
+```ts
+const seoRoute = inject(SeoRouteListener);
+seoRoute.init('https://example.com');
+```
 
----
+Expected route `data` keys:
+- `title`
+- `description`
+- `robots`
+- `canonical`
+- `og`
+- `twitter`
+- `jsonld`
+
+## Performance Notes
+
+- Use `preloadNamespaces` for first-screen keys.
+- Use `loadNamespaces` + batch hooks for chatty APIs.
+- Use `namespaceCache` limits to control memory in long-lived sessions.
+- Keep `LangPipe.maxCacheSize` realistic for your screen complexity.
+
+## Troubleshooting
+
+If some texts appear untranslated until reload:
+- Ensure keys are valid (`namespace.key` format).
+- Confirm namespace is loaded for current language.
+- Check API adapter (`responseAdapter`) returns correct shape.
+- Verify route/lazy components do not call `get()` before namespace load if you require strict first render.
+- Prefer `observe()` / `lang` pipe for reactive updates.
+
+If custom language is ignored:
+- Add it to `supportedLangs`.
+- Pass lowercase code or rely on normalization.
+
+If `ky`/`kg` behavior is unexpected:
+- `ky` input is normalized to internal `kg`.
+- `currentLang()` returns `kgValue` when language is `kg`.
 
 ## License