rune-lab 0.4.0 → 0.4.1

package/src/kernel/src/context/app.svelte.ts

@@ -0,0 +1,98 @@
+// src/kernel/src/context/app.svelte.ts
+import { getContext } from "svelte";
+import { RUNE_LAB_CONTEXT } from "./context.ts";
+import { DEV } from "esm-env";
+
+/**
+ * Application metadata interface
+ */
+export interface AppData {
+  name: string;
+  version: string;
+  description: string;
+  author: string;
+  repository?: string;
+  license?: string;
+  homepage?: string;
+}
+
+/**
+ * App Store
+ * Manages application metadata and identity
+ */
+export class AppStore {
+  // State
+  name: string = $state("Rune Lab");
+  version: string = $state("0.0.1");
+  description: string = $state("Modern toolkit for Svelte 5 Runes");
+  author: string = $state("Yrrrrrf");
+  repository: string = $state("https://github.com/Yrrrrrf/rune-lab");
+  license: string = $state("MIT");
+  homepage: string = $state("https://jsr.io/@yrrrrrf/rune-lab");
+  customIcons: Record<string, string> = $state<Record<string, string>>({});
+
+  #initialized = false;
+
+  /**
+   * Initialize app store with metadata.
+   */
+  init(data: Partial<AppData>): void {
+    if (this.#initialized) {
+      if (DEV) {
+        console.warn(
+          "AppStore.init() called multiple times. Ignoring subsequent calls.",
+          "Overwritten properties would have been:",
+          data,
+        );
+      }
+      return;
+    }
+
+    if (data.name) this.name = data.name;
+    if (data.version) this.version = data.version;
+    if (data.description) this.description = data.description;
+    if (data.author) this.author = data.author;
+    if (data.repository) this.repository = data.repository;
+    if (data.license) this.license = data.license;
+    if (data.homepage) this.homepage = data.homepage;
+
+    this.#initialized = true;
+  }
+
+  /**
+   * @internal Test-only. Resets initialization guard.
+   */
+  __reset(): void {
+    this.#initialized = false;
+  }
+
+  /**
+   * Get full app information object
+   */
+  get info(): AppData {
+    return {
+      name: this.name,
+      version: this.version,
+      description: this.description,
+      author: this.author,
+      repository: this.repository,
+      license: this.license,
+      homepage: this.homepage,
+    };
+  }
+
+  /**
+   * Registers custom SVG icons to be available globally in the Icon component
+   */
+  registerIcons(icons: Record<string, string>) {
+    this.customIcons = { ...this.customIcons, ...icons };
+  }
+}
+
+export function createAppStore(): AppStore {
+  return new AppStore();
+}
+
+export function getAppStore(): AppStore {
+  return getContext<AppStore>(RUNE_LAB_CONTEXT.app);
+}

package/src/kernel/src/context/context.ts

@@ -0,0 +1,31 @@
+// src/lib/context.ts
+
+export const RUNE_LAB_CONTEXT: {
+  app: symbol;
+  api: symbol;
+  toast: symbol;
+  theme: symbol;
+  language: symbol;
+  currency: symbol;
+  shortcut: symbol;
+  layout: symbol;
+  commands: symbol;
+  persistence: symbol;
+  cart: symbol;
+  session: symbol;
+  exchangeRate: symbol;
+} = {
+  app: Symbol("rl:app"),
+  api: Symbol("rl:api"),
+  toast: Symbol("rl:toast"),
+  theme: Symbol("rl:theme"),
+  language: Symbol("rl:language"),
+  currency: Symbol("rl:currency"),
+  shortcut: Symbol("rl:shortcut"),
+  layout: Symbol("rl:layout"),
+  commands: Symbol("rl:commands"),
+  persistence: Symbol("rl:persistence"),
+  cart: Symbol("rl:cart"),
+  session: Symbol("rl:session"),
+  exchangeRate: Symbol("rl:exchange-rate"),
+} as const;

package/src/kernel/src/context/stores.svelte.ts

@@ -0,0 +1,96 @@
+import { getContext } from "svelte";
+import { RUNE_LAB_CONTEXT } from "./context.ts";
+import type { ConfigStore } from "../persistence/createConfigStore.svelte.ts";
+import type {
+  Command,
+  Currency,
+  Language,
+  Theme,
+  Toast,
+  ToastType,
+} from "./types.ts";
+import type { LayoutStore } from "../../../runes/layout/src/store.svelte.ts";
+import type { ShortcutStore } from "../../../runes/palettes/src/shortcuts/store.svelte.ts";
+
+/**
+ * Common store interfaces
+ */
+
+export interface ICommandStore {
+  commands: Command[];
+  register(command: Command): void;
+  unregister(id: string): void;
+  search(query: string, parentId?: string): Command[];
+}
+
+export interface IToastStore {
+  toasts: Toast[];
+  send(message: string, type?: ToastType, duration?: number): void;
+  success(msg: string): void;
+  error(msg: string): void;
+  warn(msg: string): void;
+  info(msg: string): void;
+  dismiss(id: string): void;
+}
+
+export interface ICurrencyStore extends ConfigStore<Currency> {
+  canConvert: boolean;
+  convertAmount(amount: number, fromCode: string, toCode?: string): number;
+  addCurrency(meta: Currency, dineroDef?: unknown): void;
+}
+
+/**
+ * Store context accessors
+ */
+
+export function getLayoutStore(): LayoutStore {
+  return getContext<LayoutStore>(RUNE_LAB_CONTEXT.layout);
+}
+
+export function getLanguageStore(): ConfigStore<Language> {
+  return getContext<ConfigStore<Language>>(RUNE_LAB_CONTEXT.language);
+}
+
+export function getThemeStore(): ConfigStore<Theme> {
+  return getContext<ConfigStore<Theme>>(RUNE_LAB_CONTEXT.theme);
+}
+
+export function getShortcutStore(): ShortcutStore {
+  return getContext<ShortcutStore>(RUNE_LAB_CONTEXT.shortcut);
+}
+
+export function getCommandStore(): ICommandStore {
+  return getContext<ICommandStore>(RUNE_LAB_CONTEXT.commands);
+}
+
+export function getToastStore(): IToastStore {
+  return getContext<IToastStore>(RUNE_LAB_CONTEXT.toast);
+}
+
+export function getCurrencyStore(): ICurrencyStore {
+  return getContext<ICurrencyStore>(RUNE_LAB_CONTEXT.currency);
+}
+
+/**
+ * Standard layout shortcuts
+ */
+export const LAYOUT_SHORTCUTS = {
+  TOGGLE_NAV: {
+    id: "layout:toggle-nav",
+    keys: "ctrl+b",
+    label: "Toggle Sidebar",
+    category: "Layout",
+  },
+  TOGGLE_DETAIL: {
+    id: "layout:toggle-detail",
+    keys: "ctrl+alt+b",
+    label: "Toggle Detail Panel",
+    category: "Layout",
+  },
+  OPEN_SHORTCUTS: {
+    id: "layout:open-shortcuts",
+    keys: "ctrl+/",
+    label: "Show Shortcuts",
+    category: "Layout",
+  },
+} as const;

package/src/kernel/src/context/types.ts

@@ -0,0 +1,110 @@
+/**
+ * Layout configuration
+ */
+export interface LayoutZone {
+  id: string;
+  component?: unknown;
+  storeKey?: string;
+  width?: string;
+  collapsible?: boolean;
+  conditional?: string;
+  minWidth?: string;
+  position?: "start" | "end";
+}
+
+export type LayoutConfig = LayoutZone[];
+
+/**
+ * Currency
+ */
+export interface Currency {
+  code: string;
+  symbol: string;
+  decimals: number;
+}
+
+/**
+ * Navigation & Workspace items
+ */
+export interface WorkspaceItem {
+  id: string;
+  icon: string;
+  label: string;
+  badge?: string | number;
+  href?: string;
+  onClick?: () => void;
+}
+
+export interface NavigationItem {
+  id: string;
+  label: string;
+  icon?: string;
+  href?: string;
+  badge?: string | number;
+  isActive?: boolean;
+  onClick?: () => void;
+  children?: NavigationItem[];
+}
+
+export interface NavigationSection {
+  id: string;
+  title: string;
+  items: NavigationItem[];
+}
+
+/**
+ * i18n
+ */
+export interface Language {
+  code: string;
+  flag?: string;
+}
+
+/**
+ * Theme
+ */
+export interface Theme {
+  name: string;
+  icon?: string;
+}
+
+/**
+ * Shortcuts
+ */
+export interface ShortcutConfig {
+  id: string;
+  keys: string;
+  handler: (event: KeyboardEvent) => void;
+  when?: () => boolean;
+  label?: string;
+  category?: string;
+  scope?: "global" | "layout" | `panel:${string}`;
+}
+
+export interface ShortcutEntry extends ShortcutConfig {
+  enabled?: boolean;
+}
+
+/**
+ * Commands
+ */
+export interface Command {
+  id: string;
+  label: string;
+  category?: string;
+  icon?: string;
+  action?: () => void;
+  children?: Command[];
+}
+
+/**
+ * Toasts
+ */
+export type ToastType = "info" | "success" | "warning" | "error";
+
+export interface Toast {
+  id: string;
+  message: string;
+  type: ToastType;
+  duration?: number;
+}

package/src/kernel/src/context/useRuneLab.ts

@@ -0,0 +1,38 @@
+import {
+  getAppStore,
+  getCommandStore,
+  getCurrencyStore,
+  getLanguageStore,
+  getLayoutStore,
+  getShortcutStore,
+  getThemeStore,
+  getToastStore,
+} from "../../../mod.ts";
+
+export interface RuneLabContext {
+  app: ReturnType<typeof getAppStore>;
+  toast: ReturnType<typeof getToastStore>;
+  theme: ReturnType<typeof getThemeStore>;
+  language: ReturnType<typeof getLanguageStore>;
+  currency: ReturnType<typeof getCurrencyStore>;
+  shortcut: ReturnType<typeof getShortcutStore>;
+  layout: ReturnType<typeof getLayoutStore>;
+  commands: ReturnType<typeof getCommandStore>;
+}
+
+/**
+ * Retrieves all Rune Lab stores from the Svelte context tree.
+ * Must be called during component initialization (in the `<script>` block).
+ */
+export function useRuneLab(): RuneLabContext {
+  return {
+    app: getAppStore(),
+    toast: getToastStore(),
+    theme: getThemeStore(),
+    language: getLanguageStore(),
+    currency: getCurrencyStore(),
+    shortcut: getShortcutStore(),
+    layout: getLayoutStore(),
+    commands: getCommandStore(),
+  };
+}

package/src/kernel/src/mod.ts

@@ -0,0 +1,13 @@
+export * from "./context/context.ts";
+export * from "./context/types.ts";
+export * from "./context/app.svelte.ts";
+export * from "./context/stores.svelte.ts";
+export * from "./persistence/types.ts";
+export * from "./persistence/drivers.ts";
+export * from "./persistence/provider.ts";
+export * from "./persistence/usePersistence.ts";
+export * from "./persistence/createConfigStore.svelte.ts";
+export * from "./registry/mod.ts";
+export * from "./tokens/props.ts";
+export * from "./actions/portal.ts";
+export * from "./actions/shortcut-listener.ts";

package/src/kernel/src/persistence/createConfigStore.svelte.ts

@@ -0,0 +1,120 @@
+import type { PersistenceDriver } from "@rune-lab/kernel";
+import { createInMemoryDriver } from "./drivers.ts";
+import { DEV } from "esm-env";
+
+export type ConfigStore<T = unknown> = {
+  current: unknown;
+  available: T[];
+  set: (id: unknown) => void;
+  get: (id: unknown) => T | undefined;
+  getProp: <K extends keyof T>(prop: K, id?: unknown) => T[K] | undefined;
+  /** Append additional items (e.g. custom themes/currencies from the consuming app) */
+  addItems: (newItems: T[]) => void;
+};
+
+export interface ConfigStoreOptions<T = unknown> {
+  /** Array of available items */
+  items: readonly T[];
+  /** Storage key used by the persistence driver */
+  storageKey: string;
+  /** Display name for logging (e.g., "Theme", "Language") */
+  displayName: string;
+  /** Key to use as identifier (e.g., "code", "name") */
+  idKey: keyof T;
+  /** Icon for logs */
+  icon?: string;
+  /** Persistence driver */
+  driver?: PersistenceDriver;
+}
+
+/**
+ * Internal class implementation for configuration stores.
+ * Stable class definition avoids potential issues with multiple definitions in SSR.
+ */
+class ConfigStoreImpl<T = unknown> {
+  current: unknown = $state(null);
+  available: T[] = $state([]);
+
+  #options: ConfigStoreOptions<T>;
+  #driver: PersistenceDriver;
+
+  constructor(options: ConfigStoreOptions<T>) {
+    this.#options = options;
+    const { items, idKey, storageKey, driver = createInMemoryDriver() } =
+      options;
+    this.#driver = driver;
+
+    this.available = [...items] as T[];
+    this.current = items[0]?.[idKey] ?? "";
+
+    const saved = this.#driver.get(storageKey);
+    // Only load saved if it actually exists in our available items
+    if (saved && this.get(saved)) {
+      this.current = saved;
+    }
+
+    if (DEV) {
+      console.log(
+        `${options.icon ?? "⚙️"} ${options.displayName} configured:`,
+        {
+          current: this.current,
+        },
+      );
+    }
+  }
+
+  /**
+   * Set current item with validation
+   */
+  set(id: unknown): void {
+    const item = this.get(id);
+    if (!item) {
+      console.warn(`${this.#options.displayName} "${id}" not found`);
+      return;
+    }
+    this.current = id;
+    this.#driver.set(this.#options.storageKey, String(id));
+  }
+
+  /**
+   * Get item by id
+   */
+  get(id: unknown): T | undefined {
+    const idKey = this.#options.idKey;
+    return this.available.find(
+      (item: T) => (item as Record<string, unknown>)[idKey as string] === id,
+    );
+  }
+
+  /**
+   * Get property from current or specified item
+   */
+  getProp<K extends keyof T>(prop: K, id?: unknown): T[K] | undefined {
+    const targetId = id ?? this.current;
+    return (this.get(targetId) as Record<string, unknown> | undefined)
+      ?.[prop as string] as
+        | T[K]
+        | undefined;
+  }
+
+  /**
+   * Append additional items (deduplicates by idKey)
+   */
+  addItems(newItems: T[]): void {
+    const idKey = this.#options.idKey;
+    for (const item of newItems) {
+      if (!this.get((item as Record<string, unknown>)[idKey as string])) {
+        this.available.push(item);
+      }
+    }
+  }
+}
+
+/**
+ * Creates a reactive configuration store with persistence
+ */
+export function createConfigStore<T = unknown>(
+  options: ConfigStoreOptions<T>,
+): ConfigStore<T> {
+  return new ConfigStoreImpl(options) as unknown as ConfigStore<T>;
+}

package/src/kernel/src/persistence/drivers.test.ts

@@ -0,0 +1,95 @@
+import { describe, expect, it } from "vite-plus/test";
+import { createInMemoryDriver, inMemoryDriver } from "./drivers.ts";
+
+describe("PersistenceDriver Contract Tests", () => {
+  describe("createInMemoryDriver (factory)", () => {
+    it("should return null for missing keys", () => {
+      const driver = createInMemoryDriver();
+      expect(driver.get("nonexistent")).toBeNull();
+    });
+
+    it("should set and get a value", () => {
+      const driver = createInMemoryDriver();
+      driver.set("key", "value");
+      expect(driver.get("key")).toBe("value");
+    });
+
+    it("should overwrite existing values", () => {
+      const driver = createInMemoryDriver();
+      driver.set("key", "v1");
+      driver.set("key", "v2");
+      expect(driver.get("key")).toBe("v2");
+    });
+
+    it("should remove a key", () => {
+      const driver = createInMemoryDriver();
+      driver.set("key", "value");
+      driver.remove("key");
+      expect(driver.get("key")).toBeNull();
+    });
+
+    it("should not throw when removing a nonexistent key", () => {
+      const driver = createInMemoryDriver();
+      expect(() => driver.remove("nonexistent")).not.toThrow();
+    });
+
+    it("should handle empty string values", () => {
+      const driver = createInMemoryDriver();
+      driver.set("key", "");
+      expect(driver.get("key")).toBe("");
+    });
+
+    it("should handle JSON string values", () => {
+      const driver = createInMemoryDriver();
+      const json = JSON.stringify({ theme: "dark", fontSize: 14 });
+      driver.set("settings", json);
+      expect(JSON.parse(driver.get("settings")!)).toEqual({
+        theme: "dark",
+        fontSize: 14,
+      });
+    });
+  });
+
+  describe("Factory isolation", () => {
+    it("should create isolated instances (no cross-contamination)", () => {
+      const driverA = createInMemoryDriver();
+      const driverB = createInMemoryDriver();
+
+      driverA.set("shared-key", "fromA");
+      driverB.set("shared-key", "fromB");
+
+      expect(driverA.get("shared-key")).toBe("fromA");
+      expect(driverB.get("shared-key")).toBe("fromB");
+    });
+
+    it("remove on one instance does not affect another", () => {
+      const driverA = createInMemoryDriver();
+      const driverB = createInMemoryDriver();
+
+      driverA.set("key", "valueA");
+      driverB.set("key", "valueB");
+
+      driverA.remove("key");
+
+      expect(driverA.get("key")).toBeNull();
+      expect(driverB.get("key")).toBe("valueB");
+    });
+  });
+
+  describe("inMemoryDriver singleton", () => {
+    it("should implement the full PersistenceDriver interface", () => {
+      expect(typeof inMemoryDriver.get).toBe("function");
+      expect(typeof inMemoryDriver.set).toBe("function");
+      expect(typeof inMemoryDriver.remove).toBe("function");
+    });
+
+    it("should function as a working driver", () => {
+      // Use unique keys to avoid test interference
+      const key = `test-${Date.now()}`;
+      inMemoryDriver.set(key, "singleton-value");
+      expect(inMemoryDriver.get(key)).toBe("singleton-value");
+      inMemoryDriver.remove(key);
+      expect(inMemoryDriver.get(key)).toBeNull();
+    });
+  });
+});

package/src/kernel/src/persistence/drivers.ts

@@ -0,0 +1,77 @@
+// sdk/state/src/persistence/drivers.ts
+import type { PersistenceDriver } from "@rune-lab/kernel";
+import { BROWSER as browser } from "esm-env";
+
+export function createInMemoryDriver(): PersistenceDriver {
+  const store = new Map<string, string>();
+  return {
+    get: (key: string) => store.get(key) ?? null,
+    set: (key: string, value: string) => store.set(key, value),
+    remove: (key: string) => {
+      store.delete(key);
+    },
+  };
+}
+
+export const inMemoryDriver: PersistenceDriver = createInMemoryDriver();
+
+export const localStorageDriver: PersistenceDriver = {
+  get: (key: string) => {
+    if (!browser) return null;
+    return globalThis.localStorage.getItem(key);
+  },
+  set: (key: string, value: string) => {
+    if (!browser) return;
+    globalThis.localStorage.setItem(key, value);
+  },
+  remove: (key: string) => {
+    if (!browser) return;
+    globalThis.localStorage.removeItem(key);
+  },
+};
+
+export const sessionStorageDriver: PersistenceDriver = {
+  get: (key: string) => {
+    if (!browser) return null;
+    return globalThis.sessionStorage.getItem(key);
+  },
+  set: (key: string, value: string) => {
+    if (!browser) return;
+    globalThis.sessionStorage.setItem(key, value);
+  },
+  remove: (key: string) => {
+    if (!browser) return;
+    globalThis.sessionStorage.removeItem(key);
+  },
+};
+
+export const createCookieDriver = (
+  options: {
+    path?: string;
+    maxAge?: number;
+    sameSite?: "Lax" | "Strict" | "None";
+  } = {},
+): PersistenceDriver => ({
+  get: (key: string) => {
+    if (!browser) return null;
+    const match = document.cookie.match(new RegExp(`(^| )${key}=([^;]+)`));
+    return match ? decodeURIComponent(match[2]) : null;
+  },
+  set: (key: string, value: string) => {
+    if (!browser) return;
+    let cookie = `${key}=${encodeURIComponent(value)}`;
+    if (options.path) cookie += `; path=${options.path}`;
+    if (options.maxAge) cookie += `; max-age=${options.maxAge}`;
+    if (options.sameSite) cookie += `; samesite=${options.sameSite}`;
+    document.cookie = cookie;
+  },
+  remove: (key: string) => {
+    if (!browser) return;
+    document.cookie = `${key}=; max-age=0; path=${options.path || "/"}`;
+  },
+});
+
+/** Default cookie driver singleton (path='/') */
+export const cookieDriver: PersistenceDriver = createCookieDriver({
+  path: "/",
+});