@reforgium/presentia 1.5.0 → 2.1.0

package/CHANGELOG.md

@@ -0,0 +1,163 @@
+## [2.1.0]: 05.04.2026
+### Refactor:
+- replaced presentia-specific persistence adapter behavior with storage contracts and strategies backed by `@reforgium/internal`
+- `LangService` and `ThemeService` now persist through storage interface bindings instead of direct localStorage-specific adapter semantics
+
+### Feat:
+- added grouped `storage` / `persistence` options for `providePresentia(...)` theme and lang config
+- kept `persistenceAdapter` as a compatibility alias during the transition to storage-based persistence
+
+### Fix:
+- aligned `persistence: 'none'` with a real no-op storage instead of pseudo-persistent in-memory behavior
+- preserved raw `lang` / `theme` browser storage keys while moving persistence onto shared storage contracts
+
+### Test:
+- updated provider and theme tests for the storage-based persistence contract
+- verified `presentia` typecheck, Vitest suite, and Angular package build after the persistence migration
+
+---
+
+## [2.0.0]: 04.04.2026
+### Feat:
+- added grouped `providePresentia(...)` v2 entry point and marked `provideReInit(...)` as legacy in dev mode
+- extended `ThemeService` with DOM strategies, theme registry validation, and configurable persistence adapter support
+- extended `AdaptiveService` with named breakpoint helpers (`breakpoint`, `is`, `isAtLeast`, `isBetween`, `isMobile`, `isTablet`, `isDesktopSmall`)
+- extended `IfDeviceDirective` with `reIfDeviceAtLeast` and `reIfDeviceBetween`
+- extended `RouteWatcher` with `deepestParams`, `mergedData`, `routePattern`, `selectParam`, and path matching helpers
+- aligned `SeoRouteListener` with merged route data and normalized route-tree path resolution
+
+### Docs:
+- documented grouped v2 config, theme DOM/persistence options, and adaptive breakpoint helpers
+- documented recommended v2 setup, extended route watcher state, and adaptive range directives
+- promoted `V2-MIGRATION.md` from draft to working migration guide and refreshed `V2-CONFIG.md` / `ROADMAP-2.0.0.md`
+- moved compatibility-only surface out of primary README export lists and into explicit legacy notes
+
+### Test:
+- added provider and runtime coverage for grouped theme config, persistence adapters, theme registry constraints, and adaptive helper methods
+- added route watcher coverage for merged/deepest selectors and adaptive directive coverage for range-based rendering
+- added SEO listener regression coverage for merged route-data application and canonical path normalization
+
+---
+
+## [1.6.0]: 03.04.2026
+### Feat:
+- added route-aware namespace preload via `LocaleConfig.routeNamespacePreload` with `blocking` / `lazy` modes
+- added strict preload failure handling via `routeNamespacePreload.onError = 'throw'`
+- added route namespace generator CLI `presentia-gen-namespaces`
+- added generator report mode (`--report`, `--print-report`) for unresolved lazy imports and unsupported static-analysis cases
+- extended generator extraction for route data namespaces, `reLangAttrs`, object-style `reLang`, standalone imports, `loadComponent`, and `loadChildren`
+- added route preload diagnostics for late namespace loads after navigation
+- added batch namespace diagnostics and `maxBatchSize` chunking in `LangService.loadNamespaces(...)`
+
+### Docs:
+- documented route preload modes, manifest generation, report mode, and consumer CLI defaults in `README`
+- clarified `LangPipe.placeholder` as the loading-time value while `LocaleConfig.defaultValue` remains a missing-key fallback
+
+### Test:
+- added integration coverage for real router navigation with route preload
+- added regression coverage for custom `dataKey`, `mergeStrategy: 'replace'`, manifest parent/child merge, strict preload failures, batch diagnostics, and `maxBatchSize`
+- extended generator smoke coverage for report output, `reLangAttrs`, and const-based `presentiaNamespaces`
+
+---
+
+## [1.5.0]: 16.03.2026
+### Fix:
+- `SeoRouteListener.init(...)` no longer duplicates router subscriptions on repeated calls and now reuses normalized `baseUrl`
+- `ThemeService` now normalizes persisted/requested theme values before switching
+- `LangPipe` now warns once in dev mode when a namespace is loaded but the requested key is unresolved
+
+### Feat:
+- added `LangService.has(...)` for explicit translation key existence checks
+- `SeoService` is now provided in root
+
+### Refactor:
+- removed lightweight `rxjs` usage from `AdaptiveService` resize listener and route event listeners (`RouteWatcher`, `SeoRouteListener`) in favor of native subscriptions/cleanup
+- tightened `provideReInit(...)` factories for `CHANGE_LANG` / `CHANGE_THEME`
+- improved presentia package metadata and test setup for storage-backed specs
+
+### Test:
+- added regression coverage for repeated `SeoRouteListener.init(...)`, `ThemeService` contract behavior, init provider wiring, and unresolved lang key warnings
+- kept adaptive/seo regression coverage green after the refactor
+
+---
+
+## [1.4.4]: 05.03.2026
+### Fix:
+- improved `RouteWatcher.params` to merge params from `pathFromRoot` (parent to deepest child), not only from deepest snapshot
+
+### Test:
+- added a regression test for parent-child params inheritance in nested routes with parent component
+
+---
+
+## [1.4.3]: 27.02.2026
+### Fix:
+- fixed `RouteWatcher.url` to build a full path from `pathFromRoot` instead of only deepest snapshot segments
+
+### Test:
+- added a regression test for nested route URL composition (`/orgs/:orgId/users/:id`)
+
+---
+
+## [1.4.2]: 16.02.2026
+### Fix:
+- fixed `LangService.getChainedValue` deep lookup for keys with flat namespace prefix (e.g. `common.some-key.sub-key.target`)
+
+### Test:
+- added a regression test for nested translation resolution via flat namespace prefix key
+
+---
+
+## [1.4.0]: 15.02.2026
+### Feat:
+- added `LocaleConfig.requestBuilder` and `LocaleConfig.responseAdapter` for custom API url/payload mapping
+- added `LocaleConfig.requestOptionsFactory` to pass `HttpClient` options (`headers`, `params`, `withCredentials`, `responseType`, `context`, `transferCache`)
+- added batch namespace loading support: `loadNamespaces`, `batchRequestBuilder`, `batchResponseAdapter`
+- added namespace cache controls: `namespaceCache.maxNamespaces`, `namespaceCache.ttlMs`
+- added `LangService.evictNamespace` and `LangService.clearNamespaceCache`
+- added typed lang key extension point (`LangKeyRegistry`, `LangKey`) for `LangService.get/observe`
+- added package CLI `presentia-gen-lang-keys` for generating key unions from locale json
+
+### Test:
+- added integration test for language switch across multiple namespaces without page reload
+- added smoke test for CLI generator output
+- extended `LangService` tests for request options, batch mode, stale response protection, and namespace cache policies
+
+### Docs:
+- updated README for new `LocaleConfig` options, service methods, typed keys, and CLI usage
+
+---
+
+## [1.2.0]: 16.01.2026
+### Feat:
+- added implementation providers: `CHANGE_LANG` and `CHANGE_THEME`
+
+---
+
+## [1.1.1]: 14.01.2026
+
+### Feat:
+- added `translate` method to `LangDirective`
+
+### Fix:
+- fixed `reIfDevice` directive name
+
+---
+
+## [1.1.0]: 14.01.2026
+
+### Feat:
+- added `LangDirective`, auto translate
+
+---
+
+## [1.0.1]: 11.01.2026
+
+### Chore:
+- updated docs
+
+---
+
+## [1.0.0]: 26.12.2025
+
+- Init

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 rtommievich
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -10,19 +10,13 @@ Infrastructure package for Angular applications:
 - 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`.
+## Release Highlights (2.0.0)
+
+- Grouped `v2` provider via `providePresentia(...)`.
+- Route-aware namespace preload with generated manifests, diagnostics, and strict failure handling.
+- Extended `ThemeService` with theme registry, configurable DOM strategy, and persistence adapter.
+- Breakpoint-first adaptive helpers with `reIfDeviceAtLeast` and `reIfDeviceBetween`.
+- Richer `RouteWatcher` state with merged/deepest selectors and route matching helpers.
 
 ## Install
 
@@ -30,30 +24,45 @@ plus `evictNamespace` and `clearNamespaceCache`.
 npm i @reforgium/presentia
 ```
 
+## Recommended Setup
+
+For new integrations prefer:
+- `providePresentia(...)`
+- route namespace preload in `blocking` mode
+- `theme.registry` even if you currently use only `light` / `dark`
+- explicit `adaptive.breakpoints` when app breakpoints differ from defaults
+
+Legacy integrations can keep `provideReInit(...)` temporarily, but it is now the compatibility path, not the recommended one.
+
 ## Quick Start
 
 ```ts
 import { bootstrapApplication } from '@angular/platform-browser';
-import { provideReInit } from '@reforgium/presentia';
+import { providePresentia } from '@reforgium/presentia';
 
 bootstrapApplication(AppComponent, {
   providers: [
-    provideReInit({
-      locale: {
-        url: '/assets/i18n',
-        isFromAssets: true,
-        defaultLang: 'ru',
-        fallbackLang: 'en',
-        supportedLangs: ['de'],
-        preloadNamespaces: ['layout', 'common'],
+    providePresentia({
+      lang: {
+        source: {
+          url: '/assets/i18n',
+          fromAssets: true,
+          defaultLang: 'ru',
+          fallbackLang: 'en',
+          supportedLangs: ['de'],
+        },
+        preload: {
+          global: ['layout', 'common'],
+        },
+        rendering: {
+          placeholder: '...',
+        },
+        missingKeyHandler: (key, ctx) => `[${ctx.lang}] ${key}`,
       },
-      langPipe: {
-        ttlMs: 300_000,
-        maxCacheSize: 500,
-        placeholder: '...',
+      theme: {
+        defaultTheme: 'light',
+        dom: { darkClassName: 'dark' },
       },
-      langMissingKeyHandler: (key, ctx) => `[${ctx.lang}] ${key}`,
-      theme: { defaultTheme: 'light', darkThemePrefix: 'dark' },
     }),
   ],
 });
@@ -62,7 +71,58 @@ bootstrapApplication(AppComponent, {
 ## What You Get
 
 Main provider:
-- `provideReInit(config: AppConfig)`
+- `providePresentia(config: PresentiaConfig)`
+
+`providePresentia(...)` is the new grouped config entry point.
+`provideReInit(...)` remains available as the legacy `1.x` style provider.
+
+## Migration Snapshot
+
+Typical `1.x -> v2` provider migration:
+
+```ts
+// 1.x
+provideReInit({
+  locale: {
+    url: '/assets/i18n',
+    isFromAssets: true,
+    preloadNamespaces: ['layout', 'common'],
+  },
+  theme: {
+    defaultTheme: 'light',
+    darkThemePrefix: 're-dark',
+  },
+  breakpoints: {
+    mobile: '(max-width: 719px)',
+  },
+});
+
+// v2
+providePresentia({
+  lang: {
+    source: {
+      url: '/assets/i18n',
+      fromAssets: true,
+    },
+    preload: {
+      global: ['layout', 'common'],
+    },
+  },
+  theme: {
+    defaultTheme: 'light',
+    dom: {
+      darkClassName: 're-dark',
+    },
+  },
+  adaptive: {
+    breakpoints: {
+      mobile: '(max-width: 719px)',
+    },
+  },
+});
+```
+
+For a fuller mapping see [`V2-MIGRATION.md`](./V2-MIGRATION.md).
 
 Localization exports:
 - `LangService`
@@ -71,12 +131,14 @@ Localization exports:
 - `LANG_CONFIG`
 - `LANG_PIPE_CONFIG`
 - `LANG_MISSING_KEY_HANDLER`
+- `PRESENTIA_ROUTE_NAMESPACES_DATA_KEY`
 - Types: `LocaleConfig`, `LangModel`, `LangDto`, `LangParams`, `LangKey`, `LangKeyRegistry`, etc.
 
 Theme exports:
 - `ThemeService`
+- `Theme`
 - `THEME_CONFIG`
-- `themes`, `darkThemePrefix`
+- `themes`
 
 Adaptive exports:
 - `AdaptiveService`
@@ -88,7 +150,63 @@ Routes and SEO exports:
 - `SeoService`
 - `SeoRouteListener`
 
-## `provideReInit` Configuration
+Legacy compatibility surface:
+- `provideReInit(config: AppConfig)`
+- `darkThemePrefix`
+- `defaultThemeConfig`
+- `defaultThemePersistenceAdapter`
+- `RouteNamespaceDiagnosticsService`
+
+## Provider Configuration
+
+### `providePresentia`
+
+```ts
+providePresentia({
+  lang: {
+    source: {
+      url: '/assets/i18n',
+      fromAssets: true,
+      defaultLang: 'ru',
+      fallbackLang: 'en',
+    },
+    rendering: {
+      placeholder: '...',
+      missingValue: '--',
+    },
+    preload: {
+      global: ['layout', 'common'],
+      routes: {
+        mode: 'blocking',
+      },
+    },
+  },
+  theme: {
+    registry: ['light', 'dark'],
+    defaultTheme: 'dark',
+    persistence: 'localStorage',
+    dom: {
+      strategy: 'root-class',
+      darkClassName: 're-dark',
+    },
+  },
+  adaptive: {
+    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)',
+    },
+  },
+});
+```
+
+Use `providePresentia(...)` for new integrations.
+Use `provideReInit(...)` only when you need the legacy flat config shape.
+
+### `provideReInit`
+
+Legacy compatibility provider. Prefer `providePresentia(...)` for new integrations.
 
 `AppConfig` includes:
 - `locale: LocaleConfig` (required)
@@ -158,6 +276,14 @@ type LocaleConfig = {
     maxNamespaces?: number;
     ttlMs?: number;
   };
+  routeNamespacePreload?: {
+    mode?: 'blocking' | 'lazy';
+    dataKey?: string;
+    manifest?: Record<string, readonly string[]>;
+    mergeStrategy?: 'append' | 'replace';
+    onError?: 'continue' | 'throw';
+    diagnostics?: boolean;
+  };
 };
 ```
 
@@ -167,6 +293,8 @@ type LocaleConfig = {
 - 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).
+- `defaultValue` is a missing-key fallback, not a loading placeholder.
+- `LangPipe.placeholder` is used while a namespace is still loading.
 - Stale HTTP responses are ignored when language changes mid-flight.
 
 ### Basic Usage
@@ -216,6 +344,135 @@ const lang = inject(LangService);
 await lang.loadNamespaces(['layout', 'common', 'breadcrumbs']);
 ```
 
+### Route Namespace Preload
+
+Use this when first-paint localization must be ready before page activation.
+`presentia` patches router config automatically via `providePresentia(...)` or `provideReInit(...)`,
+so no extra resolver wiring is required in the consumer app.
+
+Behavior summary:
+- `mode: 'blocking'` waits for route namespaces before route activation.
+- `mode: 'lazy'` starts namespace loading without delaying navigation.
+- `onError: 'continue'` keeps navigation alive if preload fails.
+- `onError: 'throw'` cancels navigation by rethrowing the preload error.
+
+Route data mode:
+
+```ts
+providePresentia({
+  lang: {
+    source: {
+      url: '/assets/i18n',
+      fromAssets: true,
+    },
+    preload: {
+      routes: {},
+    },
+  },
+});
+
+export const routes: Routes = [
+  {
+    path: 'profile',
+    component: ProfilePage,
+    data: {
+      presentiaNamespaces: ['profile', 'layout', 'common'],
+    },
+  },
+];
+```
+
+Manifest mode:
+
+```ts
+const PRESENTIA_ROUTE_NAMESPACES = {
+  '/': ['home', 'layout', 'common'],
+  '/profile': ['profile', 'layout', 'common'],
+  '/users/:id': ['users', 'layout', 'common'],
+} as const;
+
+providePresentia({
+  lang: {
+    source: {
+      url: '/assets/i18n',
+      fromAssets: true,
+    },
+    preload: {
+      routes: {
+        manifest: PRESENTIA_ROUTE_NAMESPACES,
+        mode: 'blocking',
+      },
+    },
+    diagnostics: {
+      lateNamespaceLoads: true,
+    },
+  },
+});
+```
+
+Legacy `1.x` projects can keep using `provideReInit(...)`,
+but new integrations should prefer `providePresentia(...)`.
+
+Generate the manifest in a consumer app:
+
+```bash
+npx presentia-gen-namespaces
+```
+
+Default paths:
+- `--routes src/app/app.routes.ts`
+- `--project src`
+- `--tsconfig tsconfig.json`
+- `--out src/app/presentia-route-namespaces.ts`
+
+Explicit paths:
+
+```bash
+npx presentia-gen-namespaces \
+  --routes src/app/app.routes.ts \
+  --project src \
+  --tsconfig tsconfig.json \
+  --locales src/assets/locales \
+  --out src/app/presentia-route-namespaces.ts
+```
+
+The public CLI is `presentia-gen-namespaces`.
+Repository scripts such as `libs/presentia/scripts/generate-sandbox-namespaces.mjs`
+are internal helpers for local demo verification only.
+
+Best-effort extraction sources:
+- route `data` lang keys such as `title: 'profile.title'`
+- route `data.presentiaNamespaces`
+- `{{ 'namespace.key' | lang }}`
+- `reLang` / `reLangKey`
+- `reLangAttrs`
+- `lang.get('namespace.key')`
+- `lang.observe('namespace.key')`
+- imported local standalone components from component `imports: [...]`
+
+When `--locales` is provided, generator validates discovered keys and namespaces
+against real locale JSON files to reduce false positives.
+
+Optional report mode:
+
+```bash
+npx presentia-gen-namespaces \
+  --locales src/assets/locales \
+  --report src/app/presentia-route-namespaces.report.json \
+  --print-report
+```
+
+This emits a JSON report with static-analysis gaps such as unresolved lazy imports
+or unsupported `presentiaNamespaces` expressions.
+
+Options:
+- `mode: 'blocking' | 'lazy'` - waits for namespaces before route activation, or starts loading without blocking.
+- `dataKey` - custom route-data field name instead of default `presentiaNamespaces`.
+- `manifest` - generated or handwritten `route -> namespaces[]` map.
+- `mergeStrategy: 'append' | 'replace'` - merge manifest and route-data namespaces, or let route data override manifest entries.
+- `onError: 'continue' | 'throw'` - in blocking mode either keep navigation alive on preload failure, or cancel it by rethrowing the load error.
+- `diagnostics` - in dev mode warns when a namespace starts loading only after route activation.
+
 ### Namespace Cache Policy
 
 ```ts
@@ -387,8 +644,10 @@ After generation, invalid keys in `get()`/`observe()` are compile-time errors.
 ## Theme
 
 `ThemeService`:
-- `theme()` current theme (`'light' | 'dark'`)
+- `theme()` current theme (`Theme = BaseTheme | string`)
 - `isLight()`
+- `isDark()`
+- `is(theme | theme[])`
 - `switch(theme?)` explicit switch or toggle
 
 ```ts
@@ -397,17 +656,60 @@ theme.switch('dark');
 ```
 
 `ThemeConfig`:
-- `defaultTheme?: 'light' | 'dark'`
+- `registry?: readonly Theme[]`
+- `defaultTheme?: Theme`
 - `darkThemePrefix?: string`
+- `dom?: { strategy?: 'root-class' | 'data-attribute'; rootSelector?: string; darkThemePrefix?: string; attributeName?: string; themeClassPrefix?: string; classNameBuilder?: (theme) => string }`
+
+`providePresentia(...).theme` additionally supports:
+- `persistence?: 'localStorage' | 'none'`
+- `persistenceAdapter?: PersistenceAdapter`
+- `dom.darkClassName` as a consumer-friendly alias for `darkThemePrefix`
+- `dom.classPrefix` as a consumer-friendly alias for `themeClassPrefix`
+
+Example:
+
+```ts
+providePresentia({
+  lang: {
+    source: {
+      url: '/assets/i18n',
+      fromAssets: true,
+    },
+  },
+  theme: {
+    registry: ['light', 'dark', 'sepia'],
+    defaultTheme: 'light',
+    persistence: 'localStorage',
+    dom: {
+      strategy: 'root-class',
+      darkClassName: 're-dark',
+      classPrefix: 're-theme-',
+    },
+  },
+});
+```
+
+With that config:
+- `dark` still applies the legacy dark class (`re-dark`)
+- every registered theme also gets a prefixed class such as `re-theme-light`, `re-theme-dark`, `re-theme-sepia`
+- for fully custom naming, use `dom.classNameBuilder`
 
 ## Adaptive
 
 `AdaptiveService` provides reactive signals:
-- `device()` -> `'desktop' | 'tablet' | 'mobile'`
+- `device()` -> `'desktop' | 'desktop-s' | 'tablet' | 'mobile'`
+- `breakpoint()` alias for the current device bucket
 - `width()`
 - `height()`
+- `isMobile()`
+- `isTablet()`
+- `isDesktopSmall()`
 - `isDesktop()`
 - `isPortrait()`
+- `is(device | device[])`
+- `isAtLeast(device)`
+- `isBetween(min, max)`
 
 `*reIfDevice` structural directive:
 
@@ -415,20 +717,29 @@ theme.switch('dark');
 <div *reIfDevice="'desktop'">Desktop only</div>
 <div *reIfDevice="['mobile', 'tablet']">Mobile and tablet</div>
 <div *reIfDevice="'mobile'; inverse: true">Hidden on mobile</div>
+<div *reIfDeviceAtLeast="'tablet'">Tablet and larger</div>
+<div *reIfDeviceBetween="['tablet', 'desktop']">Tablet to desktop</div>
 ```
 
 Breakpoints are configurable via `DeviceBreakpoints`.
 
 ## Route State Helper
 
-`RouteWatcher` gives reactive deepest-route snapshot:
+`RouteWatcher` gives reactive route state:
 - `params()`
+- `deepestParams()`
 - `query()`
 - `data()`
+- `mergedData()`
 - `url()`
+- `routePattern()`
 - `fragment()`
 - `state()`
 - `selectData<T>(key)`
+- `selectData<T>(key, 'merged')`
+- `selectParam(key)`
+- `selectParam(key, 'deepest')`
+- `matchesPath(path | regexp)`
 
 Use when you want route-derived UI state without manual router subscriptions.