orcas-angular 1.0.3 → 1.0.5

package/dev/debug.service.ts.example

@@ -1,29 +0,0 @@
-import {inject, Injectable} from '@angular/core';
-import {ConsoleHook} from "@/lib/orcas-angular/dev/console-hook";
-
-@Injectable({
-    providedIn: 'root'
-})
-class DebugService {
-    private exampleService: ExampleService = inject(ExampleService);
-
-    constructor() {
-        ConsoleHook.register("example", this.getExample);
-        ConsoleHook.register("nop", this.nop);
-    }
-
-    private getExample = async () => {
-        return this.exampleService;
-    };
-
-    private nop() {
-        console.log("nop");
-        return "1";
-    }
-}
-
-class ExampleService {
-    async foo() {
-        return "bar";
-    }
-}

package/framework/README.md

@@ -1,34 +0,0 @@
-# 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/framework/services-init.ts

@@ -1,25 +0,0 @@
-import { Injectable, Injector, Type } from '@angular/core';
-
-@Injectable({ providedIn: 'root' })
-export class ServicesInit {
-  constructor(private injector: Injector) {
-  }
-
-  async init<T>(serviceClass: any, ...params: unknown[]): Promise<T> {
-    let className = `${serviceClass.name || 'unknown'}`;
-    const instance = this.injector.get(serviceClass) as any;
-
-    if (!instance)
-      throw new Error(`Service not found: ${className}`);
-
-    const hasInit = typeof instance.init === 'function';
-
-    if (params.length > 0 && !hasInit)
-      throw new Error(`Service ${className} has no init method but initialization parameters were provided.`);
-
-    if (hasInit)
-      await instance.init(...params);
-
-    return instance as T;
-  }
-}

package/index.ts

@@ -1,25 +0,0 @@
-export * from './async/async.ts';
-export * from './async/cancellation-token.ts';
-export * from './dev/console-hook.ts';
-export * from './framework/services-init.ts';
-export * from './localization/localization.service.ts';
-export * from './localization/localize.pipe.ts';
-export * from './localization/localization.interface.ts';
-export * from './log/echo.ts';
-export * from './log/log-systems.ts';
-export * from './log/echo-provider.ts';
-export * from './navigation/navigation-stack.service.ts';
-export * from './navigation/back-on-click.directive.ts';
-export * from './storage/files.ts';
-export * from './storage/file-box.service.ts';
-export * from './storage/key-signals.ts';
-export * from './storage/settings-signals.service.ts';
-export * from './storage/settings.service.ts';
-export * from './storage/tauri-files.service.ts';
-export * from './storage/capacitor-files.service.ts';
-export * from './storage/local-storage-files.service.ts';
-export * from './theme/theme.service.ts';
-export * from './ui/context-menu/context-menu.component.ts';
-export * from './ui/context-menu/context-header.component.ts';
-export * from './ui/context-menu/context-button.component.ts';
-export * from './ui/context-menu/context-menu-trigger.directive.ts';

package/localization/README.md

@@ -1,73 +0,0 @@
-# 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/localization/localization.interface.ts

@@ -1,18 +0,0 @@
-import {Signal} from '@angular/core';
-
-export interface ILocalizationService {
-    /** Emits the current language as a signal */
-    $currentLang: Signal<string>;
-
-    /** Gets the current active language code */
-    getLanguage(): string;
-
-    /** Gets the default language code */
-    getDefaultLanguage(): string;
-
-    /** Sets the current active language */
-    setActiveLanguage(lang: string): void;
-
-    /** Translates a key, possibly with params and for a specific language */
-    translate(key: string, params?: any, language?: string): string;
-}

package/localization/localization.service.ts

@@ -1,131 +0,0 @@
-import { computed, inject, Injectable, signal } from '@angular/core';
-import { HttpClient } from '@angular/common/http';
-import { ILocalizationService } from './localization.interface.ts';
-
-@Injectable({
-  providedIn: 'root'
-})
-export class LocalizationService implements ILocalizationService {
-  private defaultLanguage = 'en';
-  private storageKey = 'orcas-language';
-
-  private translations: any = {};
-  private loaded = false;
-
-  private $language: ReturnType<typeof signal<string>>;
-  public $currentLang = computed(() => this.$language());
-
-  private http = inject(HttpClient);
-
-  constructor() {
-    this.$language = signal(this.getStoredLanguage());
-  }
-
-  public async init(
-    jsonPath: string = 'assets/translations.json',
-    defaultLanguage: string = 'en',
-    storageKey: string = 'orcas-language'
-  ): Promise<void> {
-    this.defaultLanguage = defaultLanguage;
-    this.storageKey = storageKey;
-    this.$language.set(this.getStoredLanguage());
-
-    try {
-      this.translations = await this.http.get(jsonPath).toPromise();
-      this.loaded = true;
-    }
-    catch (err) {
-      console.error('Failed to load translations:', err);
-    }
-  }
-
-  getLanguage(): string {
-    return this.$language();
-  }
-
-  getDefaultLanguage(): string {
-    return this.defaultLanguage;
-  }
-
-  setActiveLanguage(lang: string): void {
-    if (lang !== this.$language()) {
-      localStorage.setItem(this.storageKey, lang);
-      this.$language.set(lang);
-    }
-  }
-
-  translate(key: string, params?: any, language?: string): string {
-    const lang = language || this.getLanguage();
-
-    if (!this.loaded) {
-      console.error('Localization: Translations not loaded yet!');
-      return key;
-    }
-
-    let translation = null;
-
-    // Handle pluralization: try singular suffix __1 first if count is 1
-    if (params && params.count === 1)
-      translation = this.resolveKey(`${key}__1`);
-
-    if (!translation)
-      translation = this.resolveKey(key);
-
-    if (!translation) {
-      console.warn(`Localization: Key not found for "${key}".`);
-      return key;
-    }
-
-    let translatedText = translation[lang];
-
-    if (!translatedText) {
-      console.warn(`Localization: Key "${key}" not found for language "${lang}". Falling back to default language.`);
-      translatedText = translation[this.defaultLanguage];
-    }
-
-    if (!translatedText) {
-      console.error(`Localization: Key "${key}" not found for default language "${this.defaultLanguage}".`);
-      return key;
-    }
-
-    if (params) {
-      if (Array.isArray(params))
-        return this.replaceArrayParams(translatedText, params);
-      else
-        return this.replaceObjectParams(translatedText, params);
-    }
-
-    return translatedText;
-  }
-
-  private resolveKey(key: string): any {
-    const keys = key.split('.');
-    let translation = this.translations;
-    for (const k of keys) {
-      if (!translation[k])
-        return null;
-      translation = translation[k];
-    }
-    return translation;
-  }
-
-  private getStoredLanguage(): string {
-    return localStorage.getItem(this.storageKey) || this.defaultLanguage;
-  }
-
-  private replaceArrayParams(text: string, params: any[]): string {
-    let result = text;
-    params.forEach((param, index) => {
-      result = result.replace(new RegExp(`\\{\\{${index}\\}\\}`, 'g'), param.toString());
-    });
-    return result;
-  }
-
-  private replaceObjectParams(text: string, params: any): string {
-    let result = text;
-    Object.keys(params).forEach(key => {
-      result = result.replace(new RegExp(`\\{\\{${key}\\}\\}`, 'g'), params[key].toString());
-    });
-    return result;
-  }
-}

package/localization/localize.pipe.ts

@@ -1,30 +0,0 @@
-import {Pipe, PipeTransform} from '@angular/core';
-import {LocalizationService} from './localization.service.ts';
-
-@Pipe({
-    name: 'localize',
-    standalone: true,
-    pure: false
-})
-export class LocalizePipe implements PipeTransform {
-    private lastLanguage: string = '';
-    private lastKey: string = '';
-    private lastParams: any;
-    private lastResult: string = '';
-
-    constructor(private localizationService: LocalizationService) {
-    }
-
-    transform(key: string, params?: any): string {
-        if (this.localizationService.$currentLang() !== this.lastLanguage
-            || key !== this.lastKey
-            || params !== this.lastParams) {
-            this.lastLanguage = this.localizationService.$currentLang();
-            this.lastKey = key;
-            this.lastParams = params;
-            this.lastResult = this.localizationService.translate(key, params);
-        }
-
-        return this.lastResult;
-    }
-}

package/log/README.md

@@ -1,275 +0,0 @@
-# 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/log/echo-provider.ts

@@ -1,27 +0,0 @@
-/**
- * Echo provider for Angular dependency injection.
- * Provides a singleton Echo instance with console writer.
- */
-import { InjectionToken, Provider } from '@angular/core';
-import { Echo, EchoConsole } from './echo.ts';
-
-/**
- * Injection token for Echo logger instance
- */
-export const ECHO = new InjectionToken<Echo>('Echo Logger Instance');
-
-/**
- * Factory function to create Echo instance
- */
-export function echoFactory(): Echo {
-  return EchoConsole.new();
-}
-
-/**
- * Provider for Echo logger
- * Use this in your module providers or inject it in services
- */
-export const ECHO_PROVIDER: Provider = {
-  provide: ECHO,
-  useFactory: echoFactory
-};