wacom 21.1.24 → 21.2.0

package/README.md

@@ -54,6 +54,7 @@ export const appConfig = {
 | Name                                                                 |                             Description                             |
 | -------------------------------------------------------------------- | :-----------------------------------------------------------------: |
 | [**`Core`**](https://www.npmjs.com/package/wacom#core-service)       |     Common supportive function which can be used in any service     |
+| [**`Emitter`**](#emitter-service)                                    |            Lightweight app-wide event and task signaling            |
 | [**`Http`**](https://www.npmjs.com/package/wacom#http-service)       |                      Http layer for HttpClient                      |
 | [**`Store`**](https://www.npmjs.com/package/wacom#store-service)     |      Service responsible for keeping information on the device      |
 | [**`Meta`**](https://www.npmjs.com/package/wacom#meta-service)       |             Website meta tags management within router              |
@@ -65,65 +66,7 @@ export const appConfig = {
 | [**`RTC`**](https://www.npmjs.com/package/wacom#rtc-service)         |        Wraps WebRTC peer connections and local media streams        |
 | [**`Util`**](https://www.npmjs.com/package/wacom#util-service)       |      Utility methods for forms, validation, and CSS variables       |
 | [**`Theme`**](#theme-service)                                        |       Manages UI theme mode, density, and radius preferences        |
-| [**`Emitter`**](#emitter-service)                                    |            Lightweight app-wide event and task signaling            |
-
-## [Emitter Service](#emitter-service)
-
-The `EmitterService` provides a lightweight event bus and completion signaling built on Angular Signals and RxJS.
-
-### Events
-
-- `emit(id: string, data?: any): void`: Publish an event on a channel.
-- `on<T = any>(id: string): Observable<T>`: Subscribe to a channel (hot, no replay).
-- `off(id: string): void`: Close and remove a channel.
-- `offAll(): void`: Close and remove all channels.
-- `has(id: string): boolean`: Check if a channel exists.
-
-Example:
-
-```ts
-import { EmitterService } from 'wacom';
-
-constructor(private emitter: EmitterService) {}
-
-ngOnInit() {
-  this.emitter.on<string>('user:login').subscribe((uid) => {
-    console.log('Logged in:', uid);
-  });
-}
-
-login(uid: string) {
-  this.emitter.emit('user:login', uid);
-}
-```
-
-### Completion tasks
-
-Track once-off tasks and await their completion.
-
-- `complete<T = any>(task: string, value: T = true): void`: Mark task done with payload.
-- `clearCompleted(task: string): void`: Reset completion state.
-- `completed(task: string): any | undefined`: Read current payload or `undefined`.
-- `isCompleted(task: string): boolean`: Convenience check.
-- `onComplete(tasks: string | string[], opts?: { mode?: 'all' | 'any'; timeoutMs?: number; abort?: AbortSignal; }): Observable<any | any[]>`: Await task(s) completion.
-
-Example:
-
-```ts
-// Somewhere that waits for a single task
-this.emitter.onComplete("profile:loaded").subscribe(() => {
-	// safe to render UI
-});
-
-// Somewhere that fulfills it
-await api.loadProfile();
-this.emitter.complete("profile:loaded");
-
-// Wait for any of several tasks
-this.emitter
-	.onComplete(["a", "b"], { mode: "any", timeoutMs: 5000 })
-	.subscribe((which) => console.log("First done:", which));
-```
+| [**`Translation`**](#translation-service)                            |        Lightweight, signal-based runtime translation engine         |
 
 ## [Core Service](#core-service)
 
@@ -503,6 +446,64 @@ In this example:
 
 This ensures controlled access to the resource, preventing race conditions and ensuring data integrity.
 
+## [Emitter Service](#emitter-service)
+
+The `EmitterService` provides a lightweight event bus and completion signaling built on Angular Signals and RxJS.
+
+### Events
+
+- `emit(id: string, data?: any): void`: Publish an event on a channel.
+- `on<T = any>(id: string): Observable<T>`: Subscribe to a channel (hot, no replay).
+- `off(id: string): void`: Close and remove a channel.
+- `offAll(): void`: Close and remove all channels.
+- `has(id: string): boolean`: Check if a channel exists.
+
+Example:
+
+```ts
+import { EmitterService } from 'wacom';
+
+constructor(private emitter: EmitterService) {}
+
+ngOnInit() {
+  this.emitter.on<string>('user:login').subscribe((uid) => {
+    console.log('Logged in:', uid);
+  });
+}
+
+login(uid: string) {
+  this.emitter.emit('user:login', uid);
+}
+```
+
+### Completion tasks
+
+Track once-off tasks and await their completion.
+
+- `complete<T = any>(task: string, value: T = true): void`: Mark task done with payload.
+- `clearCompleted(task: string): void`: Reset completion state.
+- `completed(task: string): any | undefined`: Read current payload or `undefined`.
+- `isCompleted(task: string): boolean`: Convenience check.
+- `onComplete(tasks: string | string[], opts?: { mode?: 'all' | 'any'; timeoutMs?: number; abort?: AbortSignal; }): Observable<any | any[]>`: Await task(s) completion.
+
+Example:
+
+```ts
+// Somewhere that waits for a single task
+this.emitter.onComplete("profile:loaded").subscribe(() => {
+	// safe to render UI
+});
+
+// Somewhere that fulfills it
+await api.loadProfile();
+this.emitter.complete("profile:loaded");
+
+// Wait for any of several tasks
+this.emitter
+	.onComplete(["a", "b"], { mode: "any", timeoutMs: 5000 })
+	.subscribe((which) => console.log("First done:", which));
+```
+
 ## [Http Service](#http-service)
 
 The `HttpService` provides an HTTP layer for `HttpClient` in Angular, supporting both callbacks and observables for various HTTP operations.
@@ -712,224 +713,179 @@ httpService.unlock();
 
 ## [Store Service](#store-service)
 
-The `StoreService` manages local storage in a configurable manner. It can set, get, and remove items from storage, with support for asynchronous operations and JSON serialization.
-
-### Properties
-
-#### `_prefix: string`
-
-The prefix for storage keys.
+`StoreService` provides a unified, async-first API for working with storage (localStorage by default or a custom provider via config).
+It supports raw values, safe JSON handling, key prefixing, and optional lifecycle hooks.
 
-### Methods
+---
 
-#### `setPrefix(prefix: string): void`
+### Key features
 
-Sets the prefix for storage keys.
-**Parameters**:
+- async/await everywhere (no separate `*Async` methods)
+- optional side-effects via `options`
+- automatic JSON corruption handling
+- configurable storage backend
+- prefix support for namespacing
 
-- `prefix` (string): The prefix to set.
+---
 
-**Example**:
+### Prefixing keys
 
-```Typescript
-storeService.setPrefix('app_');
+```ts
+storeService.setPrefix("app_");
 ```
 
-#### `set(key: string, value: string, callback: () => void = () => {}, errCallback: () => void = () => {}): void`
+All keys will be stored as `app_<key>` (plus global config prefix if defined).
 
-Sets a value in storage.
-
-**Parameters**:
+---
 
-- `key` (string): The storage key.
-- `value` (string): The value to store.
-- `callback` (function): The callback to execute on success.
-- `errCallback` (function): The callback to execute on error.
+### set
 
-**Example**:
+Stores a raw string value.
 
-```Typescript
-storeService.set('key', 'value', () => console.log('Success'), () => console.log('Error'));
+```ts
+await storeService.set("token", "abc123");
 ```
 
-#### `setAsync(key: string, value: string): Promise<boolean>`
-
-Sets a value in storage asynchronously.
-
-**Parameters**:
-
-- `key` (string): The storage key.
-- `value` (string): The value to store.
-
-**Returns**:
-
-- `Promise<boolean>`: A promise that resolves to a boolean indicating success.
+With hooks:
 
-**Example**:
-
-```Typescript
-await storeService.setAsync('key', 'value');
+```ts
+await storeService.set("token", "abc123", {
+	onSuccess: () => console.log("saved"),
+	onError: console.error,
+});
 ```
 
-#### `get(key: string, callback: (value: string) => void = () => {}, errCallback: () => void = () => {}): void`
+**Returns:** `Promise<boolean>`
 
-Gets a value from storage.
-
-**Parameters**:
+---
 
-- `key` (string): The storage key.
-- `callback` (function): The callback to execute with the retrieved value.
-- `errCallback` (function): The callback to execute on error.
+### get
 
-**Example**:
+Retrieves a raw string value.
 
-```Typescript
-storeService.get('key', value => console.log(value), () => console.log('Error'));
+```ts
+const token = await storeService.get("token");
 ```
 
-#### `getAsync(key: string): Promise<string | null>`
-
-Gets a value from storage asynchronously.
-
-**Parameters**:
-
-- `key` (string): The storage key.
-
-**Returns**:
+With hooks:
 
-- `Promise<string | null>`: A promise that resolves to the retrieved value or `null` if the key is missing.
-
-**Example**:
-
-```Typescript
-const value = await storeService.getAsync('key');
+```ts
+const token = await storeService.get("token", {
+	onSuccess: (v) => console.log(v),
+	onError: console.error,
+});
 ```
 
-#### `setJson(key: string, value: any, callback: () => void = () => {}, errCallback: () => void = () => {}): void`
-
-Sets a JSON value in storage.
+**Returns:** `Promise<string | null>`
 
-**Parameters**:
+---
 
-- `key` (string): The storage key.
-- `value` (any): The value to store.
-- `callback` (function): The callback to execute on success.
-- `errCallback` (function): The callback to execute on error.
+### setJson
 
-**Example**:
+Stores a JSON-serializable value.
 
-```Typescript
-storeService.setJson('key', { data: 'value' }, () => console.log('Success'), () => console.log('Error'));
+```ts
+await storeService.setJson("profile", { name: "Den", role: "dev" });
 ```
 
-#### `setJsonAsync(key: string, value: any): Promise<boolean>`
-
-Sets a JSON value in storage asynchronously.
-
-**Parameters**:
-
-- `key` (string): The storage key.
-- `value` (any): The value to store.
-
-**Returns**:
-
-- `Promise<boolean>`: A promise that resolves to a boolean indicating success.
+With hooks:
 
-**Example**:
-
-```Typescript
-await storeService.setJsonAsync('key', { data: 'value' });
+```ts
+await storeService.setJson("profile", user, {
+	onSuccess: () => console.log("saved"),
+	onError: console.error,
+});
 ```
 
-#### `getJson(key: string, callback: (value: any) => void = () => {}, errCallback: () => void = () => {}): void`
+**Returns:** `Promise<boolean>`
 
-Gets a JSON value from storage.
+---
 
-**Parameters**:
+### getJson
 
-- `key` (string): The storage key.
-- `callback` (function): The callback to execute with the retrieved value.
-- `errCallback` (function): The callback to execute on error.
+Retrieves a JSON value safely.
 
-**Example**:
+- empty or missing → `null` (or `defaultValue`)
+- corrupted JSON → auto-cleared (by default)
 
-```Typescript
-storeService.getJson('key', value => console.log(value), () => console.log('Error'));
+```ts
+const profile = await storeService.getJson<User>("profile");
 ```
 
-#### `getJsonAsync<T = any>(key: string): Promise<T | null>`
-
-Gets a JSON value from storage asynchronously.
-
-**Parameters**:
-
-- `key` (string): The storage key.
-
-**Returns**:
-
-- `Promise<T | null>`: A promise that resolves to the retrieved value.
-
-**Example**:
+With defaults and error handling:
 
-```Typescript
-const value = await storeService.getJsonAsync('key');
+```ts
+const profile = await storeService.getJson<User>("profile", {
+	defaultValue: {},
+	onError: console.warn,
+});
 ```
 
-#### `remove(key: string, callback?: () => void, errCallback?: () => void): Promise<boolean>`
+Disable auto-clean:
 
-Removes a value from storage.
-
-**Parameters**:
+```ts
+await storeService.getJson("profile", {
+	clearOnError: false,
+});
+```
 
-- `key` (string): The storage key.
-- `callback` (function): The callback to execute on success.
-- `errCallback` (function): The callback to execute on error.
+**Returns:** `Promise<T | null>`
 
-**Returns**:
+---
 
-- `Promise<boolean>`: A promise that resolves to a boolean indicating success.
+### remove
 
-**Example**:
+Removes a single key.
 
-```Typescript
-await storeService.remove('key', () => console.log('Success'), () => console.log('Error'));
+```ts
+await storeService.remove("token");
 ```
 
-#### `clear(callback?: () => void, errCallback?: () => void): Promise<boolean>`
-
-Clears all values from storage.
+With hooks:
 
-**Parameters**:
+```ts
+await storeService.remove("token", {
+	onSuccess: () => console.log("removed"),
+	onError: console.error,
+});
+```
 
-- `callback` (function): The callback to execute on success.
-- `errCallback` (function): The callback to execute on error.
+**Returns:** `Promise<boolean>`
 
-**Returns**:
+---
 
-- `Promise<boolean>`: A promise that resolves to a boolean indicating success.
+### clear
 
-**Example**:
+Clears all stored values.
 
-```Typescript
-await storeService.clear(() => console.log('Success'), () => console.log('Error'));
+```ts
+await storeService.clear();
 ```
 
-#### `applyPrefix(key: string): string`
+With hooks:
 
-Applies the configured prefix to a storage key.
-
-**Parameters**:
+```ts
+await storeService.clear({
+	onSuccess: () => console.log("cleared"),
+	onError: console.error,
+});
+```
 
-- `key` (string): The storage key.
+**Returns:** `Promise<boolean>`
 
-**Returns**:
+---
 
-- `string`: The prefixed storage key.
+### Options object
 
-**Example**:
+All methods accept an optional `options` parameter:
 
-```Typescript
-const prefixedKey = storeService.applyPrefix('key');
+```ts
+interface StoreOptions<T = unknown> {
+	onSuccess?: (value?: T | null) => void;
+	onError?: (err: unknown) => void;
+	defaultValue?: T; // getJson only
+	clearOnError?: boolean; // getJson only (default: true)
+}
 ```
 
 ## [Meta Service](#meta-service)
@@ -2193,3 +2149,129 @@ ngOnInit() {
 	this.theme.setRadius("square");
 }
 ```
+
+## [Translation Service](#translation-service)
+
+Wacom includes a lightweight, signal-based runtime translation engine built for Angular Signals.
+
+It provides:
+
+- reactive translations via `WritableSignal<string>`
+- zero-config fallback (source text renders until translated)
+- persistent storage (auto-hydrates from `StoreService`)
+- directive + pipe for ergonomic template usage
+- instant language switching without reload
+
+Unlike compile-time Angular i18n, this works fully at runtime.
+
+---
+
+### Translation model
+
+```ts
+export interface Translation {
+	sourceText: string;
+	text: string;
+}
+```
+
+Each `sourceText` acts as both:
+
+- translation key
+- default visible UI text (fallback)
+
+---
+
+### Basic usage (signal API)
+
+```ts
+import { TranslationService } from "wacom";
+
+private _translationService = inject(TranslationService);
+
+title = this._translationService.translate("Create project");
+```
+
+The returned value is a `WritableSignal<string>`.
+
+If no translation exists yet, it renders:
+
+```
+Create project
+```
+
+automatically.
+
+---
+
+### Updating translations in bulk (language switch)
+
+```ts
+this._translationService.setMany([
+	{ sourceText: "Create project", text: "Створити проєкт" },
+	{ sourceText: "Save", text: "Зберегти" },
+]);
+```
+
+Behavior:
+
+- provided keys update reactively
+- missing keys reset back to original text
+- state persists in storage
+
+---
+
+### Updating a single translation
+
+```ts
+this._translationService.setOne({
+	sourceText: "Save",
+	text: "Зберегти",
+});
+```
+
+Useful for:
+
+- live editors
+- dynamic language loading
+- admin translation panels
+
+---
+
+### Translate pipe (template friendly)
+
+```html
+<h1>{{ 'Create project' | translate }}</h1>
+```
+
+Auto-reacts when translations change.
+
+---
+
+### Translate directive (zero-key mode)
+
+Automatically uses element’s original rendered text as translation key.
+
+```html
+<h1 translate>Create project</h1>
+<button translate>Save</button>
+```
+
+Optional explicit key:
+
+```html
+<h1 translate="Create project"></h1>
+```
+
+> The directive replaces `textContent` and is SSR-safe.
+
+---
+
+### Persistence
+
+Translations are automatically:
+
+- hydrated from storage on startup
+- synced after every update
+
+No extra config required.