rune-lab 0.4.0 → 0.4.1

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

@@ -0,0 +1,58 @@
+import { describe, expect, it } from "vite-plus/test";
+import { resolveDriver } from "./provider.ts";
+import type { PersistenceDriver } from "./types.ts";
+
+describe("DriverProvider", () => {
+  describe("resolveDriver", () => {
+    it("should return inMemoryDriver when given undefined", () => {
+      const driver = resolveDriver(undefined);
+      expect(driver).toBeDefined();
+      expect(typeof driver.get).toBe("function");
+      expect(typeof driver.set).toBe("function");
+      expect(typeof driver.remove).toBe("function");
+    });
+
+    it("should pass through a concrete PersistenceDriver", () => {
+      const mockDriver: PersistenceDriver = {
+        get: () => null,
+        set: () => {},
+        remove: () => {},
+      };
+      const driver = resolveDriver(mockDriver);
+      expect(driver).toBe(mockDriver);
+    });
+
+    it("should resolve a factory function to a concrete driver", () => {
+      const mockDriver: PersistenceDriver = {
+        get: () => null,
+        set: () => {},
+        remove: () => {},
+      };
+      const driver = resolveDriver(() => mockDriver);
+      expect(driver).toBe(mockDriver);
+    });
+
+    it("should fall back to inMemoryDriver when factory returns undefined", () => {
+      const driver = resolveDriver(() => undefined);
+      expect(driver).toBeDefined();
+      expect(typeof driver.get).toBe("function");
+    });
+
+    it("inMemoryDriver fallback should be functional", () => {
+      const driver = resolveDriver(undefined);
+      driver.set("test-key", "test-value");
+      expect(driver.get("test-key")).toBe("test-value");
+      driver.remove("test-key");
+      expect(driver.get("test-key")).toBeNull();
+    });
+
+    it("should create isolated inMemoryDriver instances per call", () => {
+      const driverA = resolveDriver(undefined);
+      const driverB = resolveDriver(undefined);
+      driverA.set("key", "A");
+      driverB.set("key", "B");
+      expect(driverA.get("key")).toBe("A");
+      expect(driverB.get("key")).toBe("B");
+    });
+  });
+});

package/{dist/state/persistence/provider.js → src/kernel/src/persistence/provider.ts}

@@ -2,19 +2,29 @@
 // Context-based persistence driver injection.
 // Resolves the driver once (handling function-vs-instance duality)
 // and guarantees a concrete PersistenceDriver is always available.
+
 import { getContext, setContext } from "svelte";
+import type { PersistenceDriver } from "../mod.ts";
 import { createInMemoryDriver } from "./drivers.ts";
+
 const DRIVER_CONTEXT_KEY = Symbol("rl:driver-provider");
+
 /**
  * Resolves a driver input (function or instance) into a concrete PersistenceDriver.
  * If the input is null/undefined, returns an inMemoryDriver as the Null Object.
  *
  * This is the single place where function-form drivers are unwrapped.
  */
-export function resolveDriver(driver) {
-    const resolved = typeof driver === "function" ? driver() : driver;
-    return resolved ?? createInMemoryDriver();
+export function resolveDriver(
+  driver?:
+    | PersistenceDriver
+    | (() => PersistenceDriver | undefined)
+    | undefined,
+): PersistenceDriver {
+  const resolved = typeof driver === "function" ? driver() : driver;
+  return resolved ?? createInMemoryDriver();
 }
+
 /**
  * Sets the persistence driver context at the RuneProvider root.
  * Should be called exactly once, before any store factories run.
@@ -22,22 +32,27 @@ export function resolveDriver(driver) {
  * @param driver - A PersistenceDriver instance, a factory function, or undefined.
  *                 Undefined falls back to inMemoryDriver.
  */
-export function setDriverContext(driver) {
-    const resolved = resolveDriver(driver);
-    setContext(DRIVER_CONTEXT_KEY, resolved);
-    return resolved;
+export function setDriverContext(
+  driver?: PersistenceDriver | (() => PersistenceDriver | undefined),
+): PersistenceDriver {
+  const resolved = resolveDriver(driver);
+  setContext(DRIVER_CONTEXT_KEY, resolved);
+  return resolved;
 }
+
 /**
  * Retrieves the persistence driver from context.
  * Always returns a concrete PersistenceDriver — never null or undefined.
  *
  * @throws Error if called outside a RuneProvider tree (no context set).
  */
-export function getDriverContext() {
-    const driver = getContext(DRIVER_CONTEXT_KEY);
-    if (!driver) {
-        throw new Error("[DriverProvider] getDriverContext() called outside a <RuneProvider> tree. " +
-            "Wrap your application in <RuneProvider> to provide persistence.");
-    }
-    return driver;
+export function getDriverContext(): PersistenceDriver {
+  const driver = getContext<PersistenceDriver | undefined>(DRIVER_CONTEXT_KEY);
+  if (!driver) {
+    throw new Error(
+      "[DriverProvider] getDriverContext() called outside a <RuneProvider> tree. " +
+        "Wrap your application in <RuneProvider> to provide persistence.",
+    );
+  }
+  return driver;
 }

package/src/kernel/src/persistence/types.ts

@@ -0,0 +1,19 @@
+// src/lib/persistence/types.ts
+
+/**
+ * Synchronous persistence driver interface for Svelte stores
+ */
+export interface PersistenceDriver {
+  /**
+   * Get a value by key. Should return null if not found.
+   */
+  get(key: string): string | null;
+  /**
+   * Set a value by key.
+   */
+  set(key: string, value: string): void;
+  /**
+   * Remove a value by key.
+   */
+  remove(key: string): void;
+}

package/src/kernel/src/persistence/usePersistence.ts

@@ -0,0 +1,9 @@
+import { getContext } from "svelte";
+import { RUNE_LAB_CONTEXT } from "../mod.ts";
+import type { PersistenceDriver } from "../mod.ts";
+
+export function usePersistence(): PersistenceDriver | undefined {
+  return getContext<PersistenceDriver | undefined>(
+    RUNE_LAB_CONTEXT.persistence,
+  );
+}

package/src/kernel/src/registry/mod.ts

@@ -0,0 +1,221 @@
+import type { PersistenceDriver } from "@rune-lab/kernel";
+import type { Component } from "svelte";
+
+/**
+ * Factory function signature for creating a store.
+ * Receives the resolved config, driver, and a map of already-created store instances.
+ * The `stores` map enables dependency injection between stores.
+ */
+export type StoreFactory<TConfig = unknown, TStore = unknown> = (
+  config: TConfig,
+  driver: PersistenceDriver,
+  stores: Map<string, unknown>,
+) => TStore | null;
+
+/**
+ * An entry in the Store Registry.
+ * Maps a context key to its factory function and metadata.
+ */
+export interface StoreRegistryEntry<TConfig = unknown, TStore = unknown> {
+  /** Unique id (previously key) matching the RUNE_LAB_CONTEXT key */
+  id: string;
+  /** The symbol used for Svelte context (e.g., RUNE_LAB_CONTEXT.theme) */
+  contextKey?: symbol;
+  /** The ID of the plugin that registered this store */
+  pluginId?: string;
+  /** Factory function that creates the store */
+  factory: StoreFactory<TConfig, TStore>;
+  /** If true, the store is optional — null return from factory means "skip" */
+  optional?: boolean;
+  /** If true, the store does not use persistence at all */
+  noPersistence?: boolean;
+  /**
+   * Keys of other stores that must be created before this one.
+   * The registry initializer topologically sorts entries by this field.
+   */
+  dependsOn?: string[];
+  /**
+   * Config key that must be present for this store to be created.
+   * Used for opt-in stores (e.g., "cart", "auth").
+   * When undefined, the store is always created.
+   */
+  conditional?: string;
+}
+
+/**
+ * A RunePlugin is a collection of stores and overlays.
+ */
+export interface RunePlugin {
+  /** dot-namespaced: "rune-lab.layout" */
+  id: string;
+  /** one or more store slots */
+  stores: StoreRegistryEntry[];
+  /** Svelte components, no required props */
+  overlays?: Component<Record<never, never>>[];
+}
+
+/**
+ * The global store registry.
+ * Pre-populated with built-in stores by RuneProvider.
+ * Third-party plugins can register additional entries before mounting.
+ *
+ * @example
+ * ```ts
+ * // Plugin registration (before RuneProvider mounts)
+ * registerStore({
+ *   id: "analytics",
+ *   factory: (config, driver) => createAnalyticsStore(config),
+ *   optional: true,
+ *   noPersistence: true,
+ * });
+ * ```
+ */
+const STORE_REGISTRY: Map<string, StoreRegistryEntry> = new Map<
+  string,
+  StoreRegistryEntry
+>();
+
+/**
+ * Register a store entry in the global registry.
+ * Must be called before RuneProvider mounts for the store to be auto-wired.
+ *
+ * @param entry - Store registry entry with id, factory, and options.
+ * @throws Error if a store with the same id is already registered.
+ */
+export function registerStore<TConfig = unknown, TStore = unknown>(
+  entry: StoreRegistryEntry<TConfig, TStore>,
+): void {
+  if (STORE_REGISTRY.has(entry.id)) {
+    console.warn(
+      `[StoreRegistry] Overwriting existing store registration for id "${entry.id}"`,
+    );
+  }
+  STORE_REGISTRY.set(entry.id, entry as StoreRegistryEntry);
+}
+
+/**
+ * Define a Rune plugin and register its stores.
+ */
+export function defineRune(plugin: RunePlugin): RunePlugin {
+  for (const slot of plugin.stores) {
+    if (!slot.pluginId) {
+      slot.pluginId = plugin.id;
+    }
+    registerStore(slot);
+  }
+  return plugin;
+}
+
+/**
+ * Get a registered store entry by key.
+ */
+export function getRegisteredStore(
+  key: string,
+): StoreRegistryEntry | undefined {
+  return STORE_REGISTRY.get(key);
+}
+
+/**
+ * Get all registered store entries.
+ */
+export function getAllRegisteredStores(): Map<string, StoreRegistryEntry> {
+  return STORE_REGISTRY;
+}
+
+/**
+ * Remove a store registration (primarily useful for testing).
+ */
+export function unregisterStore(key: string): boolean {
+  return STORE_REGISTRY.delete(key);
+}
+
+/**
+ * Clear all store registrations (primarily useful for testing).
+ */
+export function clearRegistry(): void {
+  STORE_REGISTRY.clear();
+}
+
+/**
+ * Topologically sort registry entries by `dependsOn` to ensure correct creation order.
+ * Entries with no dependencies come first; entries depending on others come after.
+ */
+function topologicalSort(entries: StoreRegistryEntry[]): StoreRegistryEntry[] {
+  const sorted: StoreRegistryEntry[] = [];
+  const visited = new Set<string>();
+  const visiting = new Set<string>(); // cycle detection
+
+  const entryMap = new Map(entries.map((e) => [e.id, e]));
+
+  function visit(entry: StoreRegistryEntry) {
+    if (visited.has(entry.id)) return;
+    if (visiting.has(entry.id)) {
+      throw new Error(
+        `[StoreRegistry] Circular dependency detected involving "${entry.id}"`,
+      );
+    }
+
+    visiting.add(entry.id);
+
+    for (const depKey of entry.dependsOn ?? []) {
+      const dep = entryMap.get(depKey);
+      if (dep) visit(dep);
+    }
+
+    visiting.delete(entry.id);
+    visited.add(entry.id);
+    sorted.push(entry);
+  }
+
+  for (const entry of entries) {
+    visit(entry);
+  }
+
+  return sorted;
+}
+
+/**
+ * Initialize all registered stores using the provided plugins, config, and driver.
+ * Resolves dependencies via topological sort and returns a map of key → store instance.
+ *
+ * @param _plugins - The list of active RunePlugins (unused but kept for API stability)
+ * @param config - The RuneLabConfig (Record<string, unknown>)
+ * @param driver - The resolved PersistenceDriver
+ * @returns Map of store key → created store instance
+ */
+export function initializeStores(
+  _plugins: unknown[], // RunePlugin[] - avoid circular import if possible
+  config: Record<string, unknown>,
+  driver: PersistenceDriver,
+): Map<string, unknown> {
+  const entries = Array.from(STORE_REGISTRY.values());
+  const sorted = topologicalSort(entries);
+  const stores = new Map<string, unknown>();
+
+  for (const entry of sorted) {
+    // Extract plugin-specific config slice if pluginId is present
+    // Fallback to root config for backward compat with top-level props
+    const pluginConfig = entry.pluginId && config[entry.pluginId]
+      ? (config[entry.pluginId] as Record<string, unknown>)
+      : config;
+
+    // Skip conditional stores when their config key is absent
+    if (entry.conditional && !(entry.conditional in pluginConfig)) {
+      continue;
+    }
+
+    const store = entry.factory(pluginConfig, driver, stores);
+
+    if (store === null && entry.optional) {
+      continue; // Optional store chose not to create
+    }
+
+    if (store !== null && store !== undefined) {
+      stores.set(entry.id, store);
+    }
+  }
+
+  return stores;
+}
+
+export { STORE_REGISTRY };

package/src/kernel/src/registry/registry.test.ts

@@ -0,0 +1,162 @@
+import { beforeEach, describe, expect, it } from "vite-plus/test";
+import type { PersistenceDriver } from "../persistence/types.ts";
+import {
+  clearRegistry,
+  getAllRegisteredStores,
+  getRegisteredStore,
+  registerStore,
+  STORE_REGISTRY,
+  unregisterStore,
+} from "./mod.ts";
+
+describe("StoreRegistry", () => {
+  // Clean slate for each test
+  beforeEach(() => {
+    clearRegistry();
+  });
+
+  describe("registerStore", () => {
+    it("should register a store entry", () => {
+      registerStore({
+        id: "test",
+        factory: () => ({ value: 42 }),
+      });
+
+      expect(STORE_REGISTRY.size).toBe(1);
+      expect(STORE_REGISTRY.has("test")).toBe(true);
+    });
+
+    it("should allow overwriting with a warning", () => {
+      registerStore({ id: "test", factory: () => "v1" });
+      registerStore({ id: "test", factory: () => "v2" });
+
+      expect(STORE_REGISTRY.size).toBe(1);
+      const entry = getRegisteredStore("test");
+      // Factory should be the second one
+      expect(
+        entry?.factory(
+          {} as Record<string, unknown>,
+          {} as PersistenceDriver,
+          new Map(),
+        ),
+      ).toBe("v2");
+    });
+
+    it("should register multiple entries", () => {
+      registerStore({ id: "a", factory: () => "A" });
+      registerStore({ id: "b", factory: () => "B" });
+      registerStore({ id: "c", factory: () => "C" });
+
+      expect(STORE_REGISTRY.size).toBe(3);
+    });
+  });
+
+  describe("getRegisteredStore", () => {
+    it("should return the entry for a registered key", () => {
+      registerStore({
+        id: "theme",
+        factory: () => "theme-store",
+        optional: false,
+      });
+
+      const entry = getRegisteredStore("theme");
+      expect(entry).toBeDefined();
+      expect(entry!.id).toBe("theme");
+      expect(entry!.optional).toBe(false);
+    });
+
+    it("should return undefined for unregistered keys", () => {
+      expect(getRegisteredStore("nonexistent")).toBeUndefined();
+    });
+  });
+
+  describe("getAllRegisteredStores", () => {
+    it("should return all registered stores", () => {
+      registerStore({ id: "a", factory: () => "A" });
+      registerStore({ id: "b", factory: () => "B" });
+
+      const all = getAllRegisteredStores();
+      expect(all.size).toBe(2);
+      expect(all.has("a")).toBe(true);
+      expect(all.has("b")).toBe(true);
+    });
+  });
+
+  describe("unregisterStore", () => {
+    it("should remove a registered store", () => {
+      registerStore({ id: "test", factory: () => "val" });
+      expect(STORE_REGISTRY.has("test")).toBe(true);
+
+      const result = unregisterStore("test");
+      expect(result).toBe(true);
+      expect(STORE_REGISTRY.has("test")).toBe(false);
+    });
+
+    it("should return false for non-existent keys", () => {
+      expect(unregisterStore("nope")).toBe(false);
+    });
+  });
+
+  describe("clearRegistry", () => {
+    it("should remove all entries", () => {
+      registerStore({ id: "a", factory: () => "A" });
+      registerStore({ id: "b", factory: () => "B" });
+      expect(STORE_REGISTRY.size).toBe(2);
+
+      clearRegistry();
+      expect(STORE_REGISTRY.size).toBe(0);
+    });
+  });
+
+  describe("StoreFactory contract", () => {
+    it("factory receives config and driver, returns store", () => {
+      const mockDriver: PersistenceDriver = {
+        get: () => null,
+        set: () => {},
+        remove: () => {},
+      };
+
+      registerStore<
+        Record<string, unknown>,
+        { type: string; hasDriver: boolean; apiUrl: unknown }
+      >(
+        {
+          id: "analytics",
+          factory: (config, driver) => ({
+            type: "analytics",
+            hasDriver: !!driver,
+            apiUrl: config.apiUrl,
+          }),
+          optional: true,
+          noPersistence: true,
+        },
+      );
+
+      const entry = getRegisteredStore("analytics")!;
+      const store = entry.factory({ apiUrl: "test" }, mockDriver, new Map());
+
+      expect(store).toEqual({
+        type: "analytics",
+        hasDriver: true,
+        apiUrl: "test",
+      });
+    });
+
+    it("optional factory can return null", () => {
+      registerStore({
+        id: "optional-feature",
+        factory: () => null,
+        optional: true,
+      });
+
+      const entry = getRegisteredStore("optional-feature")!;
+      expect(
+        entry.factory(
+          {} as Record<string, unknown>,
+          {} as PersistenceDriver,
+          new Map(),
+        ),
+      ).toBeNull();
+    });
+  });
+});

package/src/kernel/src/tokens/props.ts

@@ -0,0 +1,94 @@
+// sdk/core/src/design-tokens/props.ts
+// Canonical shared prop interfaces for design tokens.
+// No CSS-framework-specific logic here — class maps live in sdk/ui.
+
+// ── Size Tokens ────────────────────────────────────────────────────────────────
+
+/** Standard size scale used across all components. */
+export type SizeToken = "xs" | "sm" | "md" | "lg" | "xl";
+
+/** Mixin interface for components that accept a size prop. */
+export interface WithSizing {
+  /** Visual size variant. Defaults to "md" if omitted. */
+  size?: SizeToken;
+}
+
+// ── Variant Tokens ─────────────────────────────────────────────────────────────
+
+/**
+ * Semantic variant tokens aligned with DaisyUI's theme system.
+ * Kept as a union type for TypeScript inference; consumers can extend via
+ * `string & {}` if they need custom variants.
+ */
+export type VariantToken =
+  | "primary"
+  | "secondary"
+  | "accent"
+  | "neutral"
+  | "ghost"
+  | "info"
+  | "success"
+  | "warning"
+  | "error";
+
+/** Mixin interface for components that accept a variant prop. */
+export interface WithVariant {
+  /** Semantic color variant. */
+  variant?: VariantToken;
+}
+
+// ── Class Passthrough ──────────────────────────────────────────────────────────
+
+/** Mixin interface for components that accept a custom CSS class. */
+export interface WithClass {
+  /** Additional CSS class string to merge with component classes. */
+  class?: string;
+}
+
+// ── Combined ───────────────────────────────────────────────────────────────────
+
+/**
+ * Convenience intersection of all design-token mixins.
+ * Use when a component supports size, variant, and custom class.
+ */
+export type WithDesignTokens = WithSizing & WithVariant & WithClass;
+
+// ── Resolution Utilities ───────────────────────────────────────────────────────
+
+/**
+ * Maps a size token to a CSS class string using a component-specific map.
+ * Returns the mapped class or an empty string for unknown tokens.
+ *
+ * @param size - The size token to resolve
+ * @param classMap - Component-specific mapping of tokens to CSS classes
+ * @param fallback - Fallback size if `size` is undefined (default: "md")
+ *
+ * @example
+ * ```ts
+ * const btnSizeMap = { xs: "btn-xs", sm: "btn-sm", md: "btn-md", lg: "btn-lg", xl: "btn-xl" };
+ * resolveSize("lg", btnSizeMap); // "btn-lg"
+ * resolveSize(undefined, btnSizeMap); // "btn-md"
+ * ```
+ */
+export function resolveSize(
+  size: SizeToken | undefined,
+  classMap: Partial<Record<SizeToken, string>>,
+  fallback: SizeToken = "md",
+): string {
+  const token = size ?? fallback;
+  return classMap[token] ?? "";
+}
+
+/**
+ * Maps a variant token to a CSS class string using a component-specific map.
+ *
+ * @param variant - The variant token to resolve
+ * @param classMap - Component-specific mapping of tokens to CSS classes
+ */
+export function resolveVariant(
+  variant: VariantToken | undefined,
+  classMap: Partial<Record<VariantToken, string>>,
+): string {
+  if (!variant) return "";
+  return classMap[variant] ?? "";
+}

package/src/mod.ts

@@ -0,0 +1,10 @@
+export { default as RuneProvider } from "./RuneProvider.svelte";
+// export { default as Icon } from "./Icon.svelte";
+
+export * from "./kernel/src/mod.ts";
+export * from "./runes/layout/src/mod.ts";
+export * from "./runes/palettes/src/mod.ts";
+export * from "./runes/plugins/money/src/mod.ts";
+
+import denoConfig from "../deno.json" with { type: "json" };
+export const version = (): string => denoConfig.version;

package/src/runes/layout/deno.json

@@ -0,0 +1,5 @@
+{
+  "name": "@rune-lab/layout",
+  "version": "0.1.0",
+  "exports": "./mod.ts"
+}