rune-lab 0.4.8 → 0.5.0-rc.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Fernando Bryan Reza Campos
+
+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

@@ -0,0 +1,309 @@
+<h1 align="center">
+  <img src="https://raw.githubusercontent.com/Yrrrrrf/rune-lab/refs/heads/main/src/package/src/static/img/rune.png" alt="Rune Lab Icon" width="128" height="128" description="Icon representing the Svelte Runes system">
+  <div align="center">Rune Lab</div>
+</h1>
+
+<div align="center">
+
+[![JSR](https://jsr.io/badges/@yrrrrrf/rune-lab)](https://jsr.io/@yrrrrrf/rune-lab)
+[![NPM Package](https://img.shields.io/npm/v/rune-lab.svg)](https://www.npmjs.com/package/rune-lab)
+[![GitHub](https://img.shields.io/badge/GitHub-Yrrrrrf%2Frune--lab-blue)](https://github.com/Yrrrrrf/rune-lab)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://choosealicense.com/licenses/mit/)
+
+</div>
+
+## Overview
+
+**Rune Lab** is a modern, extensible **plugin-based UI shell** for **Svelte 5**
+applications. Harnessing the power of Svelte's new **Runes** system, it provides
+a complete application skeleton with built-in layout management, dynamic
+theming, i18n, keyboard shortcuts, a command palette, toast notifications, and a
+highly precise money/currency subsystem.
+
+Everything is wired through a centralized **Provider + Registry + Context**
+architecture, ensuring clean dependency injection and state isolation across
+your app.
+
+## Key Features
+
+- **✨ Svelte 5 Runes-First:** Built from the ground up using `$state`,
+  `$derived`, and `$effect`. No legacy Svelte 4 stores.
+- **🧩 Extensible Plugin Architecture:** Features are isolated into plugins
+  (`LayoutPlugin`, `PalettesPlugin`, `MoneyPlugin`). Only load what you need.
+- **🎨 Dynamic Theming & i18n:** 32 DaisyUI themes and 13 pre-configured locales
+  powered by Paraglide JS, with zero-flash SSR persistence.
+- **🔗 Declarative Callbacks:** Bridge store changes (theme, language, currency)
+  to your own system hooks via `RuneProvider` props.
+- **💾 Abstract Persistence Layer:** Swap between cookies, localStorage,
+  sessionStorage, or in-memory state seamlessly via generic drivers.
+- **💸 Robust Money Subsystem:** Backed by Dinero.js for floating-point-safe
+  precision arithmetic, complete with exchange rate strategies and masked
+  currency inputs.
+- **⌨️ Developer & Power-User Friendly:** Out-of-the-box Command Palette
+  (`Ctrl+K`) and interactive Shortcuts Palette (`Ctrl+/`).
+
+## Installation
+
+### Using NPM / Bun
+
+```bash
+npm install rune-lab
+# or
+bun install rune-lab
+```
+
+## Project Configuration (Required)
+
+After installing, two configuration steps are required to ensure the framework's
+components are compiled and styled correctly in your consuming project.
+
+### Step 1 — Vite: Process `rune-lab` through the Svelte compiler
+
+By default, Vite externalizes `node_modules` during SSR, bypassing the Svelte
+compiler. Add the following to your `vite.config.ts` to process `rune-lab`
+properly:
+
+```ts
+// vite.config.ts
+import { defineConfig } from "vite";
+import { sveltekit } from "@sveltejs/kit/vite";
+
+export default defineConfig({
+  plugins: [sveltekit()],
+  ssr: {
+    noExternal: ["rune-lab"], // 👈 CRITICAL for Svelte 5 components in node_modules
+  },
+});
+```
+
+### Step 2 — Tailwind CSS v4: Scan `rune-lab` for utility classes
+
+Tailwind only generates CSS for classes it finds by scanning your source files.
+Add a `@source` directive to your project's main CSS file so Tailwind compiles
+the DaisyUI classes used internally by `rune-lab`:
+
+```css
+/* app.css / layout.css / global.css */
+@import "tailwindcss";
+@source "../node_modules/rune-lab/dist"; /* 👈 add this */
+```
+
+## Quick Start
+
+Get your application shell running in less than 40 lines. Inside your
+`+layout.svelte`:
+
+```svelte
+<script lang="ts">
+import {
+  ConnectedNavigationPanel,
+  cookieDriver,
+  LayoutPlugin,
+  PalettesPlugin,
+  RuneProvider,
+  WorkspaceLayout,
+} from "rune-lab";
+import type { NavigationSection } from "rune-lab";
+import { setLocale } from "$lib/i18n/paraglide/runtime.js";
+
+let { children } = $props();
+
+const sections: NavigationSection[] = [
+  {
+    id: "main",
+    title: "Main Menu",
+    items: [
+      { id: "home", label: "Dashboard", icon: "🏠" },
+      { id: "settings", label: "Settings", icon: "⚙️" },
+    ],
+  },
+];
+</script>
+
+<!-- Initialize the system with your required plugins and callbacks -->
+<RuneProvider
+  config={{
+    app: { name: "My Startup", version: "1.0.0" },
+    persistence: cookieDriver,
+  }}
+  plugins={[LayoutPlugin, PalettesPlugin]}
+  onLanguageChange={(l) => setLocale(l.code)}
+  onThemeChange={(t) => console.log(`Theme changed to ${t.name}`)}
+>
+  <WorkspaceLayout>
+    {#snippet navigationPanel()}
+      <!-- Auto-wires to LayoutStore state -->
+      <ConnectedNavigationPanel {sections} />
+    {/snippet}
+
+    {#snippet content()}
+      <div class="p-8">
+        {@render children()}
+      </div>
+    {/snippet}
+  </WorkspaceLayout>
+</RuneProvider>
+```
+
+You now have a fully reactive layout, a keyboard command palette, a toast
+notification system, and theme/language switchers.
+
+## Money & Currency Plugin
+
+Rune Lab provides a robust money layer that handles precision arithmetic,
+formatting, and live exchange-rate triangulation. To use it, simply register the
+`MoneyPlugin`:
+
+```svelte
+<script lang="ts">
+import { MoneyPlugin } from "rune-lab";
+</script>
+
+<RuneProvider
+  config={{
+    "rune-lab.money": {
+      defaultCurrency: "USD",
+      exchangeRates: {
+        base: "USD",
+        rates: { MXN: 17.23, EUR: 0.91 },
+      },
+    },
+  }}
+  plugins={[LayoutPlugin, PalettesPlugin, MoneyPlugin]}
+>
+  <!-- App Content -->
+</RuneProvider>
+```
+
+### Displaying & Inputting Money
+
+```svelte
+<script lang="ts">
+import { CurrencySelector, MoneyDisplay, MoneyInput, useMoney } from "rune-lab";
+
+let price = $state(15000); // Minor units (e.g., cents) -> $150.00
+const { convert, format } = useMoney();
+</script>
+
+<!-- Select from available currencies -->
+<CurrencySelector />
+
+<!-- Formats safely and localizes based on the active LanguageStore -->
+<MoneyDisplay amount={price} currency="USD" />
+
+<!-- Compact notation ($1.5M) -->
+<MoneyDisplay amount={150000000} currency="USD" compact />
+
+<!-- Integer-backed masked input (prevents floating point errors) -->
+<MoneyInput bind:amount={price} currency="USD" />
+```
+
+## Persistence Drivers
+
+Rune Lab provides generic drivers to remember user preferences across reloads.
+Pass one to `config.persistence` on `<RuneProvider>`:
+
+- `cookieDriver`: Best for SSR applications (like SvelteKit) to prevent "theme
+  flash" on initial load.
+- `localStorageDriver`: Best for client-only applications (SPAs).
+- `sessionStorageDriver`: For preferences that should clear when the browser tab
+  closes.
+
+```svelte
+<script lang="ts">
+import { cookieDriver } from "rune-lab";
+</script>
+
+<RuneProvider config={{ persistence: cookieDriver }} plugins={[...]}>
+```
+
+## Advanced Patterns
+
+### Store Observers (`onChange`)
+
+Beyond the `RuneProvider` props, you can imperatively subscribe to any
+`ConfigStore` (theme, language, currency) from your own services or components.
+Callbacks include `try/catch` protection so they never crash the store.
+
+```ts
+import { getThemeStore } from "rune-lab";
+
+const themeStore = getThemeStore();
+
+// Returns an unsubscribe function
+const unsub = themeStore.onChange((newId, oldId) => {
+  console.log(`Theme swapped from ${oldId} to ${newId}`);
+});
+```
+
+### Keyboard Shortcuts (Auto-Cleanup)
+
+Any component deep in your tree can register its own keyboard shortcuts using
+the `useShortcuts` composable. It handles Svelte's `$effect` lifecycle
+internally, ensuring shortcuts unregister when the component unmounts:
+
+```svelte
+<script lang="ts">
+import { getToastStore, useShortcuts } from "rune-lab";
+
+const toasts = getToastStore();
+
+useShortcuts([
+  {
+    id: "feature.save",
+    keys: "ctrl+s, cmd+s", // Comma-separated alternative keys
+    label: "Save Document",
+    category: "Editor",
+    scope: "global",
+    handler: (e) => {
+      e.preventDefault();
+      toasts.success("Document Saved!");
+    },
+  },
+]);
+</script>
+```
+
+### SvelteKit Route Syncing
+
+To keep your layout's active navigation state synchronized with the SvelteKit
+router, use an `$effect` inside your `+layout.svelte` right after the provider:
+
+```svelte
+<script lang="ts">
+import { page } from "$app/state";
+import { getLayoutStore } from "rune-lab";
+
+const layoutStore = getLayoutStore();
+
+$effect(() => {
+  // Automatically open the correct nav tree branch
+  const segment = page.url.pathname.split("/")[1] || "home";
+  layoutStore.navigate(segment);
+});
+</script>
+```
+
+### Calling Toasts from Outside Svelte Components
+
+If you need to trigger a toast from a pure `.ts` file (like a fetching utility
+or global error handler), you can use the Toast Bridge:
+
+```ts
+import { createToastBridge } from "rune-lab";
+
+const { notify } = createToastBridge();
+
+export async function fetchUser() {
+  try {
+    // ...
+  } catch (err) {
+    // Safely queues the toast if the UI hasn't mounted yet
+    notify("Failed to fetch user data", "error");
+  }
+}
+```
+
+## License
+
+MIT License - See [LICENSE](LICENSE) for details.

package/dist/src/core/cells/define-cell.d.ts

@@ -0,0 +1,13 @@
+import { SubscriptionRef } from "effect";
+export declare class StateCell<T> {
+	ref: SubscriptionRef.SubscriptionRef<T>;
+	version: number;
+	private listeners;
+	constructor(ref: SubscriptionRef.SubscriptionRef<T>);
+	get(): T;
+	set(value: T): void;
+	getVersion(): number;
+	subscribe(listener: () => void): () => void;
+	private pendingNotify;
+	notify(): void;
+}

package/dist/src/core/cells/define-cell.js

@@ -0,0 +1,42 @@
+import { Effect, SubscriptionRef } from "effect";
+export class StateCell {
+	ref;
+	version = 0;
+	listeners = new Set();
+	constructor(ref) {
+		this.ref = ref;
+	}
+	get() {
+		return Effect.runSync(SubscriptionRef.get(this.ref));
+	}
+	set(value) {
+		Effect.runSync(SubscriptionRef.set(this.ref, value));
+	}
+	getVersion() {
+		return this.version;
+	}
+	subscribe(listener) {
+		this.listeners.add(listener);
+		return () => {
+			this.listeners.delete(listener);
+		};
+	}
+	pendingNotify = false;
+	notify() {
+		this.version++;
+		if (this.pendingNotify) {
+			return;
+		}
+		this.pendingNotify = true;
+		queueMicrotask(() => {
+			this.pendingNotify = false;
+			for (const listener of this.listeners) {
+				try {
+					listener();
+				} catch (e) {
+					console.error(`[StateCell] Listener error:`, e);
+				}
+			}
+		});
+	}
+}

package/dist/src/core/cells/persisted-cell.d.ts

@@ -0,0 +1,9 @@
+import { Schema } from "effect";
+import type { PersistenceHandle } from "../forge/descriptors.js";
+import { StateCell } from "./define-cell.js";
+export declare function createPersistedCell<T, TEncoded = T>(
+	schema: Schema.Schema<T, TEncoded, never>,
+	handle: PersistenceHandle,
+	initialValue: T,
+	key?: string,
+): StateCell<T>;

package/dist/src/core/cells/persisted-cell.js

@@ -0,0 +1,57 @@
+import { Effect, Schema, SubscriptionRef } from "effect";
+import { StateCell } from "./define-cell.js";
+export function createPersistedCell(schema, handle, initialValue, key = "") {
+	const ref = SubscriptionRef.make(initialValue).pipe(Effect.runSync);
+	const cell = new StateCell(ref);
+	const applyValue = (val) => {
+		if (val !== null && val !== undefined) {
+			try {
+				const parsed = JSON.parse(val);
+				const decoded = Schema.decodeUnknownSync(schema)(parsed);
+				cell.set(decoded);
+			} catch {
+				try {
+					const decoded = Schema.decodeUnknownSync(schema)(val);
+					cell.set(decoded);
+				} catch {
+					// ignore decoding errors, keep initial value
+				}
+			}
+		}
+	};
+	const saved = handle.get(key);
+	if (saved instanceof Promise) {
+		saved.then(applyValue).catch(() => {});
+	} else {
+		applyValue(saved);
+	}
+	const originalSet = cell.set.bind(cell);
+	cell.set = (value) => {
+		const oldValue = cell.get();
+		originalSet(value);
+		try {
+			const encoded = Schema.encodeSync(schema)(value);
+			const stringValue =
+				typeof encoded === "string" ? encoded : JSON.stringify(encoded);
+			const res = handle.set(key, stringValue);
+			if (res instanceof Promise) {
+				return res.catch((e) => {
+					originalSet(oldValue);
+					console.error(
+						`[PersistedCell] Failed to save value (reverted to old value):`,
+						e,
+					);
+					throw e;
+				});
+			}
+		} catch (e) {
+			originalSet(oldValue);
+			console.error(
+				`[PersistedCell] Failed to save value (reverted to old value):`,
+				e,
+			);
+			throw e;
+		}
+	};
+	return cell;
+}

package/dist/src/core/config/config-store.d.ts

@@ -0,0 +1,31 @@
+import type { PersistenceDriver } from "../ports/persistence.js";
+export type ConfigStore<T, K extends keyof T = keyof T> = {
+	current: T[K];
+	available: T[];
+	set(id: T[K]): void;
+	get(id: T[K]): T | undefined;
+	getProp<P extends keyof T>(prop: P, id?: T[K]): T[P] | undefined;
+	addItems(newItems: T[]): void;
+	onChange: (cb: (newId: T[K], oldId: T[K]) => void) => () => void;
+	setDriver: (driver: PersistenceDriver) => void;
+};
+export interface ConfigStoreOptions<T, K extends keyof T = keyof T> {
+	items: readonly T[];
+	storageKey: string;
+	displayName: string;
+	idKey: K;
+	icon?: string;
+	driver?: PersistenceDriver;
+}
+export declare class ConfigStoreImpl<T, K extends keyof T> {
+	#private;
+	current: T[K];
+	available: T[];
+	constructor(options: ConfigStoreOptions<T, K>);
+	setDriver(driver: PersistenceDriver): void;
+	set(id: T[K]): void;
+	onChange(cb: (newId: T[K], oldId: T[K]) => void): () => void;
+	get(id: T[K]): T | undefined;
+	getProp<P extends keyof T>(prop: P, id?: T[K]): T[P] | undefined;
+	addItems(newItems: T[]): void;
+}

package/dist/src/core/config/config-store.js

@@ -0,0 +1,79 @@
+import { createInMemoryDriver } from "../persistence/memory.js";
+export class ConfigStoreImpl {
+	current = null;
+	available = [];
+	#options;
+	#driver;
+	#callbacks = new Set();
+	constructor(options) {
+		this.#options = options;
+		const { items, idKey, driver = createInMemoryDriver() } = options;
+		this.#driver = driver;
+		this.available = [...items];
+		this.current = items[0][idKey];
+		this.#loadFromDriver(this.#driver);
+	}
+	#loadFromDriver(driver) {
+		const saved = driver.get(this.#options.storageKey);
+		if (saved instanceof Promise) {
+			saved
+				.then((val) => {
+					if (val && this.get(val)) {
+						const old = this.current;
+						this.current = val;
+						this.#notify(val, old);
+					}
+				})
+				.catch(() => {});
+		} else if (saved && this.get(saved)) {
+			this.current = saved;
+		}
+	}
+	setDriver(driver) {
+		this.#driver = driver;
+		this.#loadFromDriver(driver);
+	}
+	set(id) {
+		const item = this.get(id);
+		if (!item) {
+			console.warn(`${this.#options.displayName} "${id}" not found`);
+			return;
+		}
+		const old = this.current;
+		this.current = id;
+		this.#driver.set(this.#options.storageKey, String(id));
+		this.#notify(id, old);
+	}
+	#notify(newId, oldId) {
+		this.#callbacks.forEach((cb) => {
+			try {
+				cb(newId, oldId);
+			} catch (err) {
+				console.error(
+					`[rune-lab/core] Error in ${this.#options.displayName} onChange callback:`,
+					err,
+				);
+			}
+		});
+	}
+	onChange(cb) {
+		this.#callbacks.add(cb);
+		return () => this.#callbacks.delete(cb);
+	}
+	get(id) {
+		const idKey = this.#options.idKey;
+		return this.available.find((item) => item[idKey] === id);
+	}
+	getProp(prop, id) {
+		const targetId = id ?? this.current;
+		return this.get(targetId)?.[prop];
+	}
+	addItems(newItems) {
+		const idKey = this.#options.idKey;
+		for (const item of newItems) {
+			if (!this.get(item[idKey])) {
+				this.available.push(item);
+			}
+		}
+	}
+}

package/dist/src/core/forge/define-contribution.d.ts

@@ -0,0 +1,21 @@
+export interface ContributionKey<T> {
+	readonly id: string;
+	readonly __brand?: T;
+}
+export interface ContributionEntry<T = unknown> {
+	readonly key: ContributionKey<T>;
+	readonly items: T[];
+}
+export declare function defineContribution<T>(id: string): ContributionKey<T>;
+export declare function contribute<T>(
+	key: ContributionKey<T>,
+	...items: T[]
+): ContributionEntry<T>;
+export interface SettingsSectionContribution {
+	id: string;
+	label: string;
+	icon?: string;
+	fields?: unknown[];
+	component?: unknown;
+}
+export declare const settingsSections: ContributionKey<SettingsSectionContribution>;

package/dist/src/core/forge/define-contribution.js

@@ -0,0 +1,7 @@
+export function defineContribution(id) {
+	return { id };
+}
+export function contribute(key, ...items) {
+	return { key, items };
+}
+export const settingsSections = defineContribution("settingsSections");

package/dist/src/core/forge/define-plugin.d.ts

@@ -0,0 +1,33 @@
+import type { ContributionEntry } from "./define-contribution.js";
+import type { SettingsSchema } from "./define-settings.js";
+import type { BaseSlotSpec } from "./define-slot.js";
+import { type SlotDescriptor } from "./descriptors.js";
+export interface ForgedPlugin<
+	TId extends string = string,
+	TSlots extends Record<string, BaseSlotSpec> = Record<string, BaseSlotSpec>,
+> {
+	id: TId;
+	requires?: string[];
+	slots: TSlots;
+	settings?: SettingsSchema;
+	overlays?: unknown[];
+	contributions?: ContributionEntry<unknown>[];
+	descriptors: Record<keyof TSlots, SlotDescriptor>;
+}
+export type PluginInput =
+	| ForgedPlugin<string, Record<string, BaseSlotSpec>>
+	| PluginInput[]
+	| null
+	| undefined
+	| boolean;
+export declare function definePlugin<
+	TId extends string,
+	TSlots extends Record<string, BaseSlotSpec>,
+>(spec: {
+	id: TId;
+	requires?: string[];
+	slots?: TSlots;
+	settings?: SettingsSchema;
+	overlays?: unknown[];
+	contributions?: ContributionEntry<unknown>[];
+}): ForgedPlugin<TId, TSlots>;

package/dist/src/core/forge/define-plugin.js

@@ -0,0 +1,21 @@
+import { getAccessorName, getContextSymbol } from "./descriptors.js";
+export function definePlugin(spec) {
+	const slots = spec.slots || {};
+	const descriptors = {};
+	for (const slotName of Object.keys(slots)) {
+		descriptors[slotName] = {
+			slotName,
+			contextKey: getContextSymbol(spec.id, slotName),
+			accessorName: getAccessorName(slotName),
+		};
+	}
+	return {
+		id: spec.id,
+		requires: spec.requires,
+		slots: slots,
+		settings: spec.settings,
+		overlays: spec.overlays,
+		contributions: spec.contributions,
+		descriptors: descriptors,
+	};
+}

package/dist/src/core/forge/define-settings.d.ts

@@ -0,0 +1,33 @@
+export interface SettingsFieldSchema {
+	id: string;
+	label: string;
+	type: "select" | "toggle" | "text" | "number" | "range" | "color" | "custom";
+	component?: unknown;
+	options?: {
+		value: unknown;
+		label: string;
+	}[];
+	min?: number;
+	max?: number;
+	step?: number;
+	target:
+		| {
+				type: "cell";
+				name: string;
+		  }
+		| {
+				type: "store";
+				storeId: string;
+				property: string;
+		  }
+		| {
+				type: "callback";
+		  };
+}
+export interface SettingsSchema {
+	id: string;
+	label: string;
+	icon?: string;
+	fields: SettingsFieldSchema[];
+}
+export declare function defineSettings(schema: SettingsSchema): SettingsSchema;