orcas-angular 1.0.0

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/navigation/back-on-click.directive.ts

@@ -0,0 +1,19 @@
+import {Directive, HostListener} from '@angular/core';
+import {NavigationStackService} from './navigation-stack.service';
+
+@Directive({
+    selector: '[back-on-click]',
+    standalone: true
+})
+export class BackOnClickDirective {
+    constructor(private navigationStack: NavigationStackService) {
+    }
+
+    @HostListener('click', ['$event'])
+    onClick(event: Event): void {
+        if (event)
+            event.preventDefault();
+
+        this.navigationStack.goBack();
+    }
+}

package/navigation/index.ts

@@ -0,0 +1,3 @@
+export * from './navigation-stack.service';
+export * from './back-on-click.directive';
+

package/navigation/navigation-stack.service.ts

@@ -0,0 +1,33 @@
+import {Injectable} from '@angular/core';
+import {Location} from '@angular/common';
+import {Router, NavigationEnd} from '@angular/router';
+
+@Injectable({
+    providedIn: 'root'
+})
+export class NavigationStackService {
+    private history: string[] = [];
+
+    constructor(private router: Router, private location: Location) {
+        this.router.events.subscribe((event: any) => {
+            if (event instanceof NavigationEnd)
+                this.history.push(event.urlAfterRedirects);
+        });
+    }
+
+    public goBack(): void {
+        this.history.pop();
+        if (this.history.length > 0)
+            this.location.back();
+        else
+            this.router.navigateByUrl("/").then();
+        this.history.pop();
+    }
+
+    public getBack(): string {
+        if (this.history.length > 1)
+            return this.history[this.history.length - 2];
+
+        return '';
+    }
+}

package/package.json

@@ -0,0 +1,29 @@
+{
+    "name": "orcas-angular",
+    "version": "1.0.0",
+    "description": "A collection of reusable Angular utilities and services, with support for Tauri and Capacitor.",
+    "main": "index.ts",
+    "types": "index.ts",
+    "keywords": [
+        "angular",
+        "tauri",
+        "capacitor",
+        "storage",
+        "localization",
+        "logging"
+    ],
+    "author": "Racso",
+    "license": "MPL-2.0",
+    "peerDependencies": {
+        "@angular/common": "^21.0.0",
+        "@angular/core": "^21.0.0",
+        "@angular/cdk": "^21.0.3",
+        "rxjs": "~7.8.0"
+    },
+    "optionalDependencies": {
+        "@tauri-apps/api": "^2.0.0",
+        "@tauri-apps/plugin-fs": "^2.0.0",
+        "@capacitor/filesystem": "^6.0.0",
+        "@capacitor/preferences": "^6.0.0"
+    }
+}

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/storage/capacitor-files.service.ts

@@ -0,0 +1,38 @@
+import { Injectable } from '@angular/core';
+import { FilesService } from './files';
+
+@Injectable()
+export class CapacitorFilesService extends FilesService {
+    static isSupported(): boolean {
+        // Capacitor is not yet implemented, so returning false
+        return false;
+    }
+
+    async init() {
+        throw new Error('CapacitorFilesService not implemented');
+    }
+
+    async joinStoragePath(filePath: string): Promise<string | null> {
+        return null;
+    }
+
+    async hasInStorage(filePath: string): Promise<boolean> {
+        throw new Error('Method not implemented.');
+    }
+
+    async readFromStorage(filePath: string): Promise<string> {
+        throw new Error('Method not implemented.');
+    }
+
+    async writeToStorage(filePath: string, data: string): Promise<void> {
+        throw new Error('Method not implemented.');
+    }
+
+    async hasInProject(filePath: string): Promise<boolean> {
+        throw new Error('Method not implemented.');
+    }
+
+    async readFromProject(filePath: string): Promise<string> {
+        throw new Error('Method not implemented.');
+    }
+}

package/storage/file-box.service.ts

@@ -0,0 +1,112 @@
+import { computed, inject, Injectable, signal } from '@angular/core';
+import { FilesService } from './files';
+import { Async } from "../async/async";
+
+enum Status {
+    NotInitialized,
+    Loading,
+    Idle,
+    Saving
+}
+
+interface BoxData {
+    [key: string]: any;
+}
+
+@Injectable({
+    providedIn: 'root'
+})
+export class FileBoxService {
+    private files: FilesService = inject(FilesService);
+    private status: Status = Status.NotInitialized;
+    private path: string = '';
+
+    private saveEnqueued: boolean = false;
+
+    private $dataWritable = signal<BoxData>({});
+    public $data = computed(() => {
+        if (this.status === Status.NotInitialized)
+            console.error('Service is not initialized.');
+        else if (this.status === Status.Loading)
+            console.error('Service is loading.');
+
+        return this.$dataWritable();
+    });
+
+    async init(path: string) {
+        if (this.status !== Status.NotInitialized) {
+            console.error('Service is already initialized.');
+            return;
+        }
+
+        this.path = path;
+
+        try {
+            this.status = Status.Loading;
+            if (await this.files.hasInStorage(this.path)) {
+                const fileContent = await this.files.readFromStorage(this.path);
+                this.$dataWritable.set(JSON.parse(fileContent));
+            }
+        }
+        catch (error) {
+            console.error('Failed to load file:', error);
+            this.$dataWritable.set({});
+        }
+        finally {
+            this.status = Status.Idle;
+        }
+    }
+
+    has(key: string): boolean {
+        return key in this.$data();
+    }
+
+    set(key: string, value: any): void {
+        this.checkType(value);
+        const newData = { ...this.$dataWritable() };
+        newData[key] = value;
+        this.$dataWritable.set(newData);
+    }
+
+    setAll(data: BoxData): void {
+        this.$dataWritable.set(data);
+    }
+
+    remove(key: string): void {
+        const newData = { ...this.$dataWritable() };
+        delete newData[key];
+        this.$dataWritable.set(newData);
+    }
+
+    private checkType(value: any) {
+        if (value instanceof Function)
+            throw new Error('Cannot save functions.');
+
+        if (value instanceof Promise)
+            throw new Error('Cannot save promises.');
+    }
+
+    async save() {
+        if (this.saveEnqueued)
+            return;
+
+        this.saveEnqueued = true;
+
+        while (this.status === Status.Saving)
+            await Async.delay(100);
+
+        this.saveEnqueued = false;
+
+        try {
+            this.status = Status.Saving;
+            const dataString = JSON.stringify(this.$data());
+            await this.files.writeToStorage(this.path, dataString);
+        }
+        catch (error) {
+            console.error('Failed to save file:', error);
+        }
+        finally {
+            this.status = Status.Idle;
+        }
+    }
+}

package/storage/files.ts

@@ -0,0 +1,42 @@
+import { Injectable } from '@angular/core';
+
+@Injectable()
+export abstract class FilesService {
+    /**
+     * Initializes the service. 
+     * This should handle any setup required by the specific implementation.
+     */
+    abstract init(...args: any[]): Promise<void>;
+
+    /**
+     * Joins a filename with the storage base directory to get a full path.
+     * Returns a string or a Promise of a string depending on implementation.
+     * In some platforms, this may return null if paths are not supported.
+     */
+    abstract joinStoragePath(filePath: string): Promise<string | null>;
+
+    /**
+     * Checks if a file exists in the platform-specific storage.
+     */
+    abstract hasInStorage(filePath: string): Promise<boolean>;
+
+    /**
+     * Reads a file from the platform-specific storage.
+     */
+    abstract readFromStorage(filePath: string): Promise<string>;
+
+    /**
+     * Writes data to a file in the platform-specific storage.
+     */
+    abstract writeToStorage(filePath: string, data: string): Promise<void>;
+
+    /**
+     * Checks if a file exists in the project's assets/resources.
+     */
+    abstract hasInProject(filePath: string): Promise<boolean>;
+
+    /**
+     * Reads a file from the project's assets/resources.
+     */
+    abstract readFromProject(filePath: string): Promise<string>;
+}

package/storage/key-signals.ts

@@ -0,0 +1,49 @@
+import { computed, Signal } from '@angular/core';
+
+export abstract class KeySignals {
+    protected abstract $data(): Record<string, any>;
+    protected abstract setRawValue(key: string, value: any): Promise<void>;
+    protected abstract setMultipleRawValues(values: Record<string, any>): Promise<void>;
+
+    protected readonly SEPARATOR = '|';
+
+    public getCanonicalKey(path: string[]): string {
+        return path.join(this.SEPARATOR);
+    }
+
+    public getNewSignal<T>(defaultValue: T, ...path: string[]): Signal<T> {
+        return computed(() => this.getValue(defaultValue, ...path));
+    }
+
+    public getValue<T>(defaultValue: T, ...path: string[]): T {
+        const key = this.getCanonicalKey(path);
+        const data = this.$data();
+        return key in data ? data[key] : defaultValue;
+    }
+
+    public async set(value: any, ...path: string[]): Promise<void> {
+        const key = this.getCanonicalKey(path);
+        await this.setRawValue(key, value);
+    }
+
+    /**
+     * Clears all keys that start with the given prefix.
+     */
+    public async clearByPrefix(...pathPrefix: string[]): Promise<void> {
+        const prefix = this.getCanonicalKey(pathPrefix) + this.SEPARATOR;
+        const data = this.$data();
+        const updatedData = { ...data };
+        let changed = false;
+
+        for (const key in updatedData) {
+            if (key.startsWith(prefix)) {
+                delete updatedData[key];
+                changed = true;
+            }
+        }
+
+        if (changed) {
+            await this.setMultipleRawValues(updatedData);
+        }
+    }
+}

package/storage/local-storage-files.service.ts

@@ -0,0 +1,49 @@
+import { Injectable, inject } from '@angular/core';
+import { HttpClient } from '@angular/common/http';
+import { lastValueFrom } from 'rxjs';
+import { FilesService } from './files';
+
+@Injectable()
+export class LocalStorageFilesService extends FilesService {
+    private http = inject(HttpClient);
+
+    static isSupported(): boolean {
+        return typeof window !== 'undefined' && !!window.localStorage;
+    }
+
+    async init() {
+        // LocalStorage is ready immediately
+    }
+
+    async joinStoragePath(filePath: string): Promise<string | null> {
+        return null;
+    }
+
+    async hasInStorage(filePath: string): Promise<boolean> {
+        return localStorage.getItem(filePath) !== null;
+    }
+
+    async readFromStorage(filePath: string): Promise<string> {
+        const data = localStorage.getItem(filePath);
+        if (data === null) throw new Error(`File not found in localStorage: ${filePath}`);
+        return data;
+    }
+
+    async writeToStorage(filePath: string, data: string): Promise<void> {
+        localStorage.setItem(filePath, data);
+    }
+
+    async hasInProject(filePath: string): Promise<boolean> {
+        try {
+            // In a browser, we check if we can fetch it via HTTP
+            await lastValueFrom(this.http.head(filePath));
+            return true;
+        } catch {
+            return false;
+        }
+    }
+
+    async readFromProject(filePath: string): Promise<string> {
+        return await lastValueFrom(this.http.get(filePath, { responseType: 'text' }));
+    }
+}

package/storage/settings-signals.service.ts

@@ -0,0 +1,24 @@
+import { inject, Injectable } from '@angular/core';
+import { KeySignals } from './key-signals';
+import { FileBoxService } from './file-box.service';
+
+@Injectable({
+    providedIn: 'root'
+})
+export class SettingsSignalsService extends KeySignals {
+    private filebox = inject(FileBoxService);
+
+    protected override $data(): Record<string, any> {
+        return this.filebox.$data();
+    }
+
+    protected override async setRawValue(key: string, value: any): Promise<void> {
+        this.filebox.set(key, value);
+        await this.filebox.save();
+    }
+
+    protected override async setMultipleRawValues(values: Record<string, any>): Promise<void> {
+        this.filebox.setAll(values);
+        await this.filebox.save();
+    }
+}

package/storage/settings.service.ts

@@ -0,0 +1,24 @@
+import { inject, Injectable, Signal } from "@angular/core";
+import { FileBoxService } from "./file-box.service";
+import { SettingsSignalsService } from "./settings-signals.service";
+
+@Injectable({
+    providedIn: "root"
+})
+export class SettingsService {
+    private fileboxService = inject(FileBoxService);
+    private sss = inject(SettingsSignalsService);
+    private readonly SETTINGS_KEY = "app-settings";
+
+    public getNewSignal<T>(defaultValue: T, ...path: string[]): Signal<T> {
+        return this.sss.getNewSignal(defaultValue, this.SETTINGS_KEY, ...path);
+    }
+
+    public async set(value: any, ...path: string[]): Promise<void> {
+        await this.sss.set(value, this.SETTINGS_KEY, ...path);
+    }
+
+    public async save(): Promise<void> {
+        await this.fileboxService.save();
+    }
+}

package/storage/tauri-files.service.ts

@@ -0,0 +1,69 @@
+import { Injectable } from '@angular/core';
+import { FilesService } from './files';
+
+@Injectable()
+export class TauriFilesService extends FilesService {
+    private static _isTauri: boolean | null = null;
+
+    static isSupported(): boolean {
+        if (this._isTauri !== null) return this._isTauri;
+
+        try {
+            // Check for window.__TAURI_INTERNALS__ which is usually present in v2
+            this._isTauri = !!((window as any).__TAURI_INTERNALS__);
+        } catch {
+            this._isTauri = false;
+        }
+        return this._isTauri;
+    }
+
+    async init() {
+        // No special initialization needed for Tauri FS plugin beyond what is handled lazily
+    }
+
+    async joinStoragePath(filePath: string): Promise<string | null> {
+        const { appLocalDataDir, join } = await import('@tauri-apps/api/path');
+        const dataDir = await appLocalDataDir();
+        return await join(dataDir, filePath);
+    }
+
+    async hasInStorage(filePath: string): Promise<boolean> {
+        try {
+            const { exists } = await import('@tauri-apps/plugin-fs');
+            const { BaseDirectory } = await import('@tauri-apps/api/path');
+            return await exists(filePath, { baseDir: BaseDirectory.AppLocalData });
+        } catch (error) {
+            console.error('TauriFilesService.hasInStorage error:', error);
+            return false;
+        }
+    }
+
+    async readFromStorage(filePath: string): Promise<string> {
+        const { readTextFile } = await import('@tauri-apps/plugin-fs');
+        const { BaseDirectory } = await import('@tauri-apps/api/path');
+        return await readTextFile(filePath, { baseDir: BaseDirectory.AppLocalData });
+    }
+
+    async writeToStorage(filePath: string, data: string): Promise<void> {
+        const { writeTextFile } = await import('@tauri-apps/plugin-fs');
+        const { BaseDirectory } = await import('@tauri-apps/api/path');
+        await writeTextFile(filePath, data, { baseDir: BaseDirectory.AppLocalData });
+    }
+
+    async hasInProject(filePath: string): Promise<boolean> {
+        try {
+            const response = await fetch(filePath, { method: 'HEAD' });
+            return response.ok;
+        } catch {
+            return false;
+        }
+    }
+
+    async readFromProject(filePath: string): Promise<string> {
+        const response = await fetch(filePath);
+        if (!response.ok) {
+            throw new Error(`Failed to read project file: ${filePath} (${response.status})`);
+        }
+        return await response.text();
+    }
+}

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);
+    }
+}
+```