orcas-angular 1.0.5 → 1.0.6

package/async/README.md

@@ -0,0 +1,46 @@
+# async
+
+Utilities for working with asynchronous operations.
+
+## Files
+
+### `async.ts`
+
+The `Async` class provides static helper methods for common async patterns:
+
+- **`Async.delay(ms)`** — Returns a `Promise` that resolves after a given number of milliseconds. Useful for introducing deliberate pauses in async flows.
+- **`Async.until(check, timeoutMs?, frequencyMs?)`** — Polls a condition function at a given interval until it returns `true`. Throws a `Error` if the timeout is exceeded. Defaults to a 10-second timeout and 100 ms polling frequency.
+
+### `cancellation-token.ts`
+
+Provides a cooperative cancellation mechanism inspired by .NET's `CancellationToken` pattern:
+
+- **`CancellationToken`** *(interface)* — Read-only token that exposes `isCancelled()` and `throwIfCancelled()`. Passed to async operations to signal cancellation without forcing an abort.
+- **`CancellationTokenSource`** — Owns and controls a `CancellationToken`. Call `cancel()` to signal cancellation, or `newUnique(timeoutMs?)` to cancel the previous token and issue a fresh one (optionally with an auto-cancel timeout).
+- **`CancellationError`** — Error subclass thrown by `throwIfCancelled()` when cancellation has been requested.
+
+## Usage
+
+```typescript
+import { Async } from '@/lib/orcas-angular/async/async';
+import { CancellationTokenSource } from '@/lib/orcas-angular/async/cancellation-token';
+
+// Delay example
+await Async.delay(500);
+
+// Poll until condition
+await Async.until(() => someFlag === true);
+
+// Cancellation example
+const cts = new CancellationTokenSource();
+const token = cts.newUnique(5000); // auto-cancels after 5 s
+
+async function doWork() {
+    token.throwIfCancelled();
+    await Async.delay(100);
+    token.throwIfCancelled();
+    // ...
+}
+
+cts.cancel(); // cancel from outside
+```

package/dev/README.md

@@ -0,0 +1,41 @@
+# dev
+
+Development and debugging utilities. These helpers are meant for use during development only and should not be shipped as core application services.
+
+## Files
+
+### `console-hook.ts`
+
+`ConsoleHook` exposes a lightweight command registry that can be invoked from the browser console. It registers a global `window.r(command, ...args)` function so that developers can call application methods without needing to open Angular DevTools.
+
+**Methods:**
+- **`ConsoleHook.initialize()`** — Sets up `window.r` if it has not been set up yet.
+- **`ConsoleHook.register(commandName, method)`** — Registers a named command. Automatically calls `initialize()`.
+- **`ConsoleHook.run(input, ...additionalParams)`** — Parses the input string (command name + space-separated arguments) and executes the matching registered command.
+
+**Browser console usage:**
+```javascript
+// Call a registered command named "example" with no extra args
+r("example")
+
+// Call "myCommand" with arguments
+r("myCommand arg1 arg2")
+```
+
+### `debug.service.ts.example`
+
+A template showing how to integrate `ConsoleHook` into an Angular service. Copy this file, rename it to `debug.service.ts`, and adapt it to register the commands relevant to your application.
+
+The example registers two commands:
+- `"example"` — returns the injected `ExampleService` instance.
+- `"nop"` — logs `"nop"` to the console and returns `"1"`.
+
+## Usage
+
+```typescript
+import { ConsoleHook } from '@/lib/orcas-angular/dev/console-hook';
+
+// In any service or component constructor:
+ConsoleHook.register('reload', () => location.reload());
+ConsoleHook.register('clearStorage', () => localStorage.clear());
+```

package/framework/README.md

@@ -0,0 +1,34 @@
+# framework
+
+Angular framework utilities that help with application startup and service lifecycle management.
+
+## Files
+
+### `services-init.ts`
+
+`ServicesInit` is a root-level Angular service that provides a typed, async-aware way to retrieve and initialize other services during application bootstrap.
+
+**Why it exists:** Angular's DI container instantiates services lazily and synchronously. `ServicesInit` bridges the gap when a service needs async initialization (e.g. loading a file, fetching config) before the app is ready to use it.
+
+**Method:**
+
+```typescript
+async init<T>(serviceClass: any, ...params: unknown[]): Promise<T>
+```
+
+- Retrieves the service instance from the injector.
+- If the service has an `init(...params)` method, calls it and awaits completion.
+- If initialization parameters are provided to a service that has no `init` method, an error is thrown.
+- Returns the fully initialized service instance, typed as `T`.
+
+## Usage
+
+```typescript
+import { ServicesInit } from '@/lib/orcas-angular/framework/services-init';
+
+// In your app initialization (e.g. APP_INITIALIZER or main bootstrap):
+const servicesInit = injector.get(ServicesInit);
+
+await servicesInit.init(FileBoxService, 'app-data.json');
+await servicesInit.init(LocalizationService, 'assets/translations.json', 'en');
+```

package/localization/README.md

@@ -0,0 +1,73 @@
+# localization
+
+> A README.md is also available in the `localization` folder.
+
+Angular service and pipe for loading and applying multi-language translations at runtime.
+
+## Files
+
+### `localization.interface.ts`
+
+`ILocalizationService` — interface defining the public contract that any localization service implementation must satisfy.
+
+### `localization.service.ts`
+
+`LocalizationService` is the concrete implementation. It loads a JSON translation file over HTTP and exposes a reactive API based on Angular signals.
+
+**Key features:**
+- Loads translations from a configurable JSON file path (default: `assets/translations.json`).
+- Persists the active language in `localStorage` and restores it on startup.
+- Supports **nested keys** via dot notation (e.g. `"settings.title"`).
+- Supports **pluralization** via the `__1` suffix convention (e.g. a key named `"items__1"` is used when `params.count === 1`).
+- Supports **parameter substitution** using `{{index}}` (array) or `{{key}}` (object) placeholders.
+- Falls back to the default language if a key is missing for the active language.
+
+**Reactive signal:**
+- **`$currentLang`** — Computed signal that emits whenever the active language changes.
+
+**Methods:**
+
+| Method | Description |
+|---|---|
+| `init(jsonPath?, defaultLanguage?, storageKey?)` | Loads the translation file and configures defaults. Call during app bootstrap. |
+| `getLanguage()` | Returns the current language code. |
+| `getDefaultLanguage()` | Returns the default/fallback language code. |
+| `setActiveLanguage(lang)` | Switches the active language and persists it. |
+| `translate(key, params?, language?)` | Resolves a translation key with optional parameter substitution. |
+
+### `localize.pipe.ts`
+
+`LocalizePipe` (`| localize`) is an impure standalone pipe that wraps `LocalizationService.translate()`. It re-evaluates only when the language, key, or params change, keeping re-render cost minimal.
+
+## Translation file format
+
+```json
+{
+  "greeting": {
+    "en": "Hello, {{name}}!",
+    "es": "¡Hola, {{name}}!"
+  },
+  "items": {
+    "en": "{{count}} items",
+    "es": "{{count}} elementos"
+  },
+  "items__1": {
+    "en": "1 item",
+    "es": "1 elemento"
+  }
+}
+```
+
+## Usage
+
+```typescript
+// Bootstrap (e.g. in APP_INITIALIZER):
+await servicesInit.init(LocalizationService, 'assets/translations.json', 'en');
+
+// In a template:
+{{ 'greeting' | localize: { name: 'World' } }}
+
+// Programmatically:
+localizationService.translate('items', { count: 3 });
+localizationService.setActiveLanguage('es');
+```

package/log/README.md

@@ -0,0 +1,275 @@
+# Echo TypeScript
+
+TypeScript port of the Echo.cs logging library. This is a flexible and powerful logging library with support for log levels, system-based organization, and custom log writers.
+
+## Features
+
+- Structured logging with system tags
+- Customizable log levels (per system or global)
+- String formatting with parameters (only formatted when log will be written)
+- Log-once functionality to prevent duplicate messages
+- Extensible with custom log writers
+- Console log writer with colors and timestamps included
+- TypeScript type safety
+- Performance optimized - no allocations when logs are filtered out
+
+## Installation
+
+```bash
+# Install dependencies
+npm install
+
+# Build the library
+npm run build
+```
+
+The compiled JavaScript and type definitions will be in the `dist/` folder.
+
+## Quick Start
+
+```typescript
+import { EchoConsole, LogLevel } from './dist/echo';
+
+// Create an Echo instance with default console writer
+const echo = EchoConsole.new();
+
+// Get a logger
+const logger = echo.getLogger();
+
+// Log messages
+logger.debug("System", "Debug message");
+logger.info("System", "Info message");
+logger.warn("System", "Warning message");
+logger.error("System", "Error message");
+```
+
+## Usage Examples
+
+### Basic Logging
+
+```typescript
+import { EchoConsole } from './echo';
+
+const echo = EchoConsole.new();
+const logger = echo.getLogger();
+
+// Log with different levels
+logger.debug("GUI", "This is a debug message from the GUI system.");
+logger.info("Physics", "This is an info message from the Physics system.");
+logger.warn("AI", "This is a warning message from the AI system.");
+logger.error("Rendering", "This is an error message from the Rendering system.");
+```
+
+### System Logger
+
+```typescript
+// Get a system-specific logger (cached per system)
+const animationLogger = echo.getSystemLogger("Animation");
+
+// No need to specify system in subsequent calls
+animationLogger.debug("This is a debug message from the Animation system.");
+animationLogger.info("This is an info message from the Animation system.");
+animationLogger.warn("This is a warning message from the Animation system.");
+animationLogger.error("This is an error message from the Animation system.");
+```
+
+### String Formatting
+
+```typescript
+// Use formatted strings with parameters
+// Formatting is only done IF the log will be written (performance optimization)
+const playerName = "John";
+const playerHealth = 100;
+logger.info("General", "Player {0} has {1} health.", playerName, playerHealth);
+// Output: Player John has 100 health.
+```
+
+### Log Level Management
+
+```typescript
+import { LogLevel } from './echo';
+
+// Set default log level (applies to all systems)
+echo.settings.setDefaultLevel(LogLevel.Warn); // Only Warn and Error will be logged
+
+// Set system-specific log level
+echo.settings.setSystemLevel("Physics", LogLevel.Debug); // Physics logs everything
+
+// Get current log level for a system
+const level = echo.settings.getSystemLevel("Physics");
+
+// Clear a system-specific level (reverts to default)
+echo.settings.clearSystemLevel("Physics");
+
+// Clear all system-specific levels
+echo.settings.clearSystemLevels();
+```
+
+### Log Once
+
+```typescript
+// Log a message only once, even if called multiple times
+logger.debug1("System", "This will only appear once");
+logger.debug1("System", "This will only appear once"); // Won't be logged
+logger.debug1("System", "This will only appear once"); // Won't be logged
+
+// Also works with other log levels
+logger.info1("System", "Info once");
+logger.warn1("System", "Warn once");
+logger.error1("System", "Error once");
+```
+
+### Custom Configuration
+
+```typescript
+import { LogWriterConfig, SystemColor } from './echo';
+
+const config = new LogWriterConfig();
+config.timestamp = true;           // Include timestamps (default: true)
+config.levelLabels = true;         // Include log level labels (default: true)
+config.levelColors = true;         // Use colors for log levels (default: true)
+config.systemColor = SystemColor.LabelAndMessage; // Color both label and message
+
+const echo = EchoConsole.new(config);
+```
+
+### Custom Log Writer
+
+```typescript
+import { Echo, EchoLogWriter, LogLevel } from './echo';
+
+class CustomLogWriter implements EchoLogWriter {
+    writeLog(level: LogLevel, system: string, message: string): void {
+        // Custom log writing logic here
+        const timestamp = new Date().toISOString();
+        console.log(`${timestamp} | ${level} | [${system}] ${message}`);
+    }
+}
+
+// Use custom writer
+const customWriter = new CustomLogWriter();
+const echo = new Echo(customWriter);
+```
+
+## API Reference
+
+### Echo Class
+
+Main entry point for the library.
+
+```typescript
+constructor(writer: EchoLogWriter)
+```
+
+- **getLogger()**: Returns the main logger instance (cached)
+- **getSystemLogger(system: string)**: Returns a system-specific logger (cached per system)
+- **settings**: Access to EchoSettings for configuration
+
+### EchoLogger Class
+
+Main logger with system parameter required.
+
+**Methods** (all have the same signature pattern):
+- **debug(system: string, message: string, ...params: any[])**
+- **info(system: string, message: string, ...params: any[])**
+- **warn(system: string, message: string, ...params: any[])**
+- **error(system: string, message: string, ...params: any[])**
+
+**Log-once variants** (append `1` to method name):
+- **debug1, info1, warn1, error1** - Same signatures as above
+
+### EchoSystemLogger Class
+
+System-specific logger (system is set at creation).
+
+**Methods** (no system parameter needed):
+- **debug(message: string, ...params: any[])**
+- **info(message: string, ...params: any[])**
+- **warn(message: string, ...params: any[])**
+- **error(message: string, ...params: any[])**
+
+**Log-once variants**:
+- **debug1, info1, warn1, error1** - Same signatures as above
+
+### EchoSettings Class
+
+Configuration for log levels.
+
+- **defaultLevel**: Get/set the default log level
+- **setDefaultLevel(level: LogLevel)**: Set default log level for all systems
+- **setSystemLevel(system: string, level: LogLevel)**: Set log level for specific system
+- **getSystemLevel(system: string)**: Get log level for specific system
+- **clearSystemLevel(system: string)**: Remove system-specific level
+- **clearSystemLevels()**: Remove all system-specific levels
+- **getAllSystemLevels()**: Get all system-specific levels
+- **onUpdated(callback: () => void)**: Register callback for settings updates
+
+### LogLevel Enum
+
+```typescript
+enum LogLevel {
+    None = 0,   // No logging
+    Error = 1,  // Errors only
+    Warn = 2,   // Warnings and errors
+    Info = 3,   // Info, warnings, and errors
+    Debug = 4   // All logs (most verbose)
+}
+```
+
+### LogWriterConfig Class
+
+Configuration for the console log writer.
+
+- **timestamp**: Include timestamps (default: true)
+- **levelLabels**: Include log level labels (default: true)
+- **levelColors**: Use colors for log levels (default: true)
+- **systemColor**: Control system color usage (default: SystemColor.LabelOnly)
+
+### SystemColor Enum
+
+```typescript
+enum SystemColor {
+    None,              // No color
+    LabelOnly,         // Color only the system label
+    LabelAndMessage    // Color both label and message
+}
+```
+
+### EchoConsole Helper
+
+Factory for creating Echo instances with console writer.
+
+```typescript
+EchoConsole.new(config?: LogWriterConfig): Echo
+```
+
+## Differences from C# Version
+
+The TypeScript port maintains the same API signatures as the C# version with these differences:
+
+1. **Case Convention**: TypeScript methods use camelCase (e.g., `getLogger()`) instead of PascalCase
+2. **Generic Overloads**: Instead of C# generic type parameters, TypeScript uses rest parameters (`...params: any[]`)
+3. **Events**: Instead of C# events, use `onUpdated(callback)` method to register callbacks
+4. **Properties**: C# properties become TypeScript getters/setters
+5. **No Unity**: This port excludes all Unity-specific features
+
+## Running the Demo
+
+```bash
+# Compile
+tsc echo.demo.ts
+
+# Run
+node echo.demo.js
+```
+
+## Running Tests
+
+```bash
+# Compile and run tests
+tsc && node echo.test.js
+```
+
+## License
+
+Copyright © 2025 Racso

package/navigation/README.md

@@ -0,0 +1,47 @@
+# navigation
+
+Angular utilities for managing navigation history and providing a reliable "go back" behaviour.
+
+## Files
+
+### `navigation-stack.service.ts`
+
+`NavigationStackService` maintains an in-memory history stack by subscribing to Angular Router's `NavigationEnd` events. This gives the application precise control over back-navigation, including a safe fallback to the home route when the history is empty.
+
+**Methods:**
+- **`goBack()`** — Navigates to the previous route. Falls back to `"/"` if there is no history.
+- **`getBack(): string`** — Returns the URL of the previous route without navigating, or an empty string if unavailable.
+
+### `back-on-click.directive.ts`
+
+`BackOnClickDirective` (`[back-on-click]`) is a standalone directive that calls `NavigationStackService.goBack()` when the host element is clicked. It also prevents the default click behaviour so it can be safely applied to `<a>` elements.
+
+### `index.ts`
+
+Public barrel that re-exports both `NavigationStackService` and `BackOnClickDirective`.
+
+## Usage
+
+```typescript
+// In a standalone component:
+import { BackOnClickDirective } from '@/lib/orcas-angular/navigation';
+
+@Component({
+    imports: [BackOnClickDirective],
+    template: `<button back-on-click>← Back</button>`
+})
+export class MyComponent {}
+```
+
+```typescript
+// Programmatic back navigation:
+import { NavigationStackService } from '@/lib/orcas-angular/navigation';
+
+export class MyComponent {
+    private nav = inject(NavigationStackService);
+
+    onClose() {
+        this.nav.goBack();
+    }
+}
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "orcas-angular",
-  "version": "1.0.5",
+  "version": "1.0.6",
   "description": "A collection of reusable Angular utilities and services, with support for Tauri and Capacitor.",
   "keywords": [
     "angular",

package/storage/README.md

@@ -0,0 +1,75 @@
+# storage
+
+Reactive, file-backed storage layer for application and repository settings. Built on Angular signals and an abstract file service that can be backed by different platforms (Tauri, Capacitor, or `localStorage`).
+
+## Architecture overview
+
+```
+FilesService (abstract)
+    ├── TauriFilesService       — Tauri desktop file system
+    ├── CapacitorFilesService   — Capacitor mobile file system
+    └── LocalStorageFilesService — Browser localStorage (fallback)
+
+FileBoxService                  — reads/writes a single JSON file via FilesService
+    └── SettingsSignalsService (extends KeySignals)
+            └── SettingsService — scoped to the "app-settings" key
+```
+
+## Files
+
+### `files.ts`
+
+Abstract `FilesService` class. Defines the platform-agnostic contract for file operations:
+
+| Method | Description |
+|---|---|
+| `init(...args)` | Platform-specific setup |
+| `joinStoragePath(filePath)` | Resolves a path relative to the storage root |
+| `hasInStorage(filePath)` | Checks existence in writable storage |
+| `readFromStorage(filePath)` | Reads a file from writable storage |
+| `writeToStorage(filePath, data)` | Writes a file to writable storage |
+| `hasInProject(filePath)` | Checks existence in project assets |
+| `readFromProject(filePath)` | Reads a file from project assets |
+
+### `tauri-files.service.ts` / `capacitor-files.service.ts` / `local-storage-files.service.ts`
+
+Concrete implementations of `FilesService` for Tauri, Capacitor, and browser `localStorage`.
+
+### `file-box.service.ts`
+
+`FileBoxService` loads and persists an entire JSON file as a flat key→value map. It exposes a reactive `$data` signal so that anything that reads from the box re-renders automatically when data changes. Saves are debounced so that multiple rapid changes are flushed in a single write.
+
+**Init:** must be called once during bootstrap: `init(path: string)`.
+
+### `key-signals.ts`
+
+Abstract `KeySignals` base class. Provides a hierarchical key system where multiple string path segments are joined with a `|` separator to form a flat storage key. Subclasses implement the three abstract methods to wire `KeySignals` to an actual storage backend.
+
+**API:**
+
+| Method | Description |
+|---|---|
+| `getNewSignal<T>(defaultValue, ...path)` | Returns a computed `Signal<T>` for the given path |
+| `getValue<T>(defaultValue, ...path)` | Reads the value synchronously |
+| `set(value, ...path)` | Persists a value at the given path |
+| `clearByPrefix(...pathPrefix)` | Removes all keys that share a common prefix |
+
+### `settings-signals.service.ts`
+
+`SettingsSignalsService` extends `KeySignals` and connects it to `FileBoxService`. All reads and writes go through the reactive `$data` signal and the file-save pipeline.
+
+### `settings.service.ts`
+
+`SettingsService` wraps `SettingsSignalsService` with a fixed `"app-settings"` namespace, providing a clean API for global application settings.
+
+### `settings.service.spec.ts` / `signal-caching.spec.ts` / `key-signals.spec.ts`
+
+Unit tests for the storage layer.
+
+## Usage
+
+```typescript
+// Global app setting (persists across sessions)
+const isDarkMode = settingsService.getNewSignal(false, 'theme', 'dark');
+await settingsService.set(true, 'theme', 'dark');
+```

package/theme/README.md

@@ -0,0 +1,44 @@
+# theme
+
+Angular service for managing the application's visual theme (light / dark mode).
+
+## Files
+
+### `theme.service.ts`
+
+`ThemeService` reads and persists the user's theme preference via `SettingsService` and reflects it on the DOM in real time.
+
+**Signals:**
+- **`$theme`** — Reactive signal (`Signal<ThemeType>`) holding the current theme preference. Backed by persistent storage so the user's choice survives page reloads.
+- **`$darkMode`** — Computed `boolean` signal. Returns `true` when the effective theme is dark. When the stored preference is `ThemeType.Unset`, it automatically falls back to the OS-level `prefers-color-scheme: dark` media query.
+
+Whenever `$darkMode` changes, an Angular `effect` toggles the `dark` CSS class on `document.documentElement`, making the service compatible with Tailwind CSS's `darkMode: 'class'` strategy (or any similar class-based dark-mode approach).
+
+**Method:**
+- **`setTheme(theme: ThemeType)`** — Persists the chosen theme and updates the `$theme` signal.
+
+**`ThemeType` enum:**
+
+| Value | Description |
+|---|---|
+| `ThemeType.Unset` | Follow the OS preference |
+| `ThemeType.Light` | Force light mode |
+| `ThemeType.Dark` | Force dark mode |
+
+## Usage
+
+```typescript
+import { ThemeService, ThemeType } from '@/lib/orcas-angular/theme/theme.service';
+
+export class SettingsComponent {
+    private theme = inject(ThemeService);
+
+    // Read current dark-mode state reactively
+    isDark = this.theme.$darkMode;
+
+    async toggleTheme() {
+        const next = this.theme.$darkMode() ? ThemeType.Light : ThemeType.Dark;
+        await this.theme.setTheme(next);
+    }
+}
+```

package/ui/README.md

@@ -0,0 +1,42 @@
+# ui
+
+Reusable UI components for the application. Currently contains the context menu system.
+
+## Folders
+
+### `context-menu/`
+
+A fully self-contained context menu implementation built with Angular standalone components and directives. It handles viewport clamping automatically so that menus never render off-screen, and supports nested sub-menus.
+
+**Components and directives:**
+
+| File | Selector | Description |
+|---|---|---|
+| `context-menu.component.ts` | `<context-menu>` | Container that renders a floating menu panel at a given (x, y) coordinate. Can be used as a top-level menu or as an `isSubmenu` variant that positions itself adjacent to the parent button. |
+| `context-button.component.ts` | `<context-button>` | Menu item button. Supports `danger` and `disabled` inputs and an optional `hasSubmenu` flag that reveals a `▶` indicator and conditionally renders a nested `<context-menu>` on hover. |
+| `context-header.component.ts` | `<context-header>` | Non-interactive section header / label for grouping menu items. |
+| `context-menu-trigger.directive.ts` | `[appContextMenu]` | Applied to any element. Intercepts the `contextmenu` event, prevents the default browser menu, and calls `show(x, y)` on the bound `ContextMenuComponent`. Emits a `beforeOpen` output before the menu opens, which is useful for preparing dynamic menu content. |
+| `index.ts` | — | Public barrel re-exporting all of the above. |
+
+**Usage:**
+
+```html
+<div [appContextMenu]="menu" (beforeOpen)="prepareMenu()">
+    Right-click me
+</div>
+
+<context-menu #menu>
+    <context-header>Actions</context-header>
+
+    <context-button (click)="doSomething()">Do something</context-button>
+
+    <context-button danger (click)="deleteItem()">Delete</context-button>
+
+    <context-button [hasSubmenu]="true">
+        More…
+        <context-menu [isSubmenu]="true">
+            <context-button (click)="doNested()">Nested action</context-button>
+        </context-menu>
+    </context-button>
+</context-menu>
+```