@directive-run/knowledge 0.2.0

package/examples/theme-locale.ts

@@ -0,0 +1,204 @@
+// Example: theme-locale
+// Source: examples/theme-locale/src/theme-locale.ts
+// Pure module file — no DOM wiring
+
+/**
+ * Theme & Locale — Directive Modules
+ *
+ * Two modules:
+ * - `preferences` — theme, locale, sidebar, translations, system dark preference
+ * - `layout` — responsive breakpoint tracking
+ *
+ * Demonstrates multi-module composition, auto-tracked derivations,
+ * effects for DOM side-effects, and persistence plugin for user prefs.
+ */
+
+import { type ModuleSchema, createModule, t } from "@directive-run/core";
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export interface Translations {
+  greeting: string;
+  settings: string;
+  theme: string;
+  language: string;
+  sidebar: string;
+}
+
+export type ThemeChoice = "light" | "dark" | "system";
+export type Breakpoint = "mobile" | "tablet" | "desktop";
+
+// ============================================================================
+// Translation data
+// ============================================================================
+
+const TRANSLATIONS: Record<string, Translations> = {
+  en: {
+    greeting: "Hello",
+    settings: "Settings",
+    theme: "Theme",
+    language: "Language",
+    sidebar: "Sidebar",
+  },
+  es: {
+    greeting: "Hola",
+    settings: "Configuraci\u00f3n",
+    theme: "Tema",
+    language: "Idioma",
+    sidebar: "Barra lateral",
+  },
+  fr: {
+    greeting: "Bonjour",
+    settings: "Param\u00e8tres",
+    theme: "Th\u00e8me",
+    language: "Langue",
+    sidebar: "Barre lat\u00e9rale",
+  },
+};
+
+function getTranslations(locale: string): Translations {
+  return TRANSLATIONS[locale] ?? TRANSLATIONS.en;
+}
+
+// ============================================================================
+// Preferences Schema
+// ============================================================================
+
+export const preferencesSchema = {
+  facts: {
+    theme: t.string<ThemeChoice>(),
+    locale: t.string(),
+    sidebarOpen: t.boolean(),
+    systemPrefersDark: t.boolean(),
+    loadedLocale: t.string(),
+    translations: t.object<Translations>(),
+  },
+  derivations: {
+    effectiveTheme: t.string(),
+    isRTL: t.boolean(),
+  },
+  events: {
+    setTheme: { value: t.string() },
+    setLocale: { value: t.string() },
+    toggleSidebar: {},
+    setSystemPreference: { value: t.boolean() },
+  },
+  requirements: {},
+} satisfies ModuleSchema;
+
+// ============================================================================
+// Layout Schema
+// ============================================================================
+
+export const layoutSchema = {
+  facts: {
+    breakpoint: t.string<Breakpoint>(),
+  },
+  derivations: {},
+  events: {
+    setBreakpoint: { value: t.string() },
+  },
+  requirements: {},
+} satisfies ModuleSchema;
+
+// ============================================================================
+// Preferences Module
+// ============================================================================
+
+export const preferencesModule = createModule("preferences", {
+  schema: preferencesSchema,
+
+  init: (facts) => {
+    facts.theme = "system";
+    facts.locale = "en";
+    facts.sidebarOpen = true;
+    facts.systemPrefersDark = false;
+    facts.loadedLocale = "en";
+    facts.translations = getTranslations("en");
+  },
+
+  // ============================================================================
+  // Derivations
+  // ============================================================================
+
+  derive: {
+    effectiveTheme: (facts) => {
+      if (facts.theme === "system") {
+        return facts.systemPrefersDark ? "dark" : "light";
+      }
+
+      return facts.theme;
+    },
+
+    isRTL: (facts) => {
+      const rtlLocales = ["ar", "he", "fa", "ur"];
+
+      return rtlLocales.includes(facts.locale as string);
+    },
+  },
+
+  // ============================================================================
+  // Events
+  // ============================================================================
+
+  events: {
+    setTheme: (facts, { value }) => {
+      facts.theme = value;
+    },
+
+    setLocale: (facts, { value }) => {
+      facts.locale = value;
+      facts.loadedLocale = value;
+      facts.translations = getTranslations(value);
+    },
+
+    toggleSidebar: (facts) => {
+      facts.sidebarOpen = !facts.sidebarOpen;
+    },
+
+    setSystemPreference: (facts, { value }) => {
+      facts.systemPrefersDark = value;
+    },
+  },
+
+  // ============================================================================
+  // Effects
+  // ============================================================================
+
+  effects: {
+    applyTheme: {
+      run: (facts) => {
+        const effective =
+          facts.theme === "system"
+            ? facts.systemPrefersDark
+              ? "dark"
+              : "light"
+            : facts.theme;
+        document.documentElement.setAttribute(
+          "data-theme",
+          effective as string,
+        );
+      },
+    },
+  },
+});
+
+// ============================================================================
+// Layout Module
+// ============================================================================
+
+export const layoutModule = createModule("layout", {
+  schema: layoutSchema,
+
+  init: (facts) => {
+    facts.breakpoint = "desktop";
+  },
+
+  events: {
+    setBreakpoint: (facts, { value }) => {
+      facts.breakpoint = value;
+    },
+  },
+});

package/examples/time-machine.ts

@@ -0,0 +1,225 @@
+// Example: time-machine
+// Source: examples/time-machine/src/main.ts
+// Extracted for AI rules — DOM wiring stripped
+
+/**
+ * Time Machine — Time-Travel Debugging
+ *
+ * Drawing canvas where each stroke is a fact mutation. Full time-travel:
+ * undo/redo, export/import JSON, replay animation, changesets, snapshot slider.
+ */
+
+import {
+  type ModuleSchema,
+  createModule,
+  createSystem,
+  t,
+} from "@directive-run/core";
+import { devtoolsPlugin } from "@directive-run/core/plugins";
+
+// ============================================================================
+// Types
+// ============================================================================
+
+interface Stroke {
+  id: string;
+  x: number;
+  y: number;
+  color: string;
+  size: number;
+}
+
+interface TimelineEntry {
+  time: number;
+  event: string;
+  detail: string;
+  type:
+    | "stroke"
+    | "undo"
+    | "redo"
+    | "changeset"
+    | "export"
+    | "import"
+    | "replay"
+    | "goto";
+}
+
+// ============================================================================
+// Timeline
+// ============================================================================
+
+const timeline: TimelineEntry[] = [];
+
+function addTimeline(
+  event: string,
+  detail: string,
+  type: TimelineEntry["type"],
+) {
+  timeline.unshift({ time: Date.now(), event, detail, type });
+  if (timeline.length > 50) {
+    timeline.length = 50;
+  }
+}
+
+// ============================================================================
+// Schema
+// ============================================================================
+
+const schema = {
+  facts: {
+    strokes: t.object<Stroke[]>(),
+    currentColor: t.string(),
+    brushSize: t.number(),
+    changesetActive: t.boolean(),
+    changesetLabel: t.string(),
+  },
+  derivations: {
+    strokeCount: t.number(),
+    canUndo: t.boolean(),
+    canRedo: t.boolean(),
+    currentIndex: t.number(),
+    totalSnapshots: t.number(),
+  },
+  events: {
+    addStroke: { x: t.number(), y: t.number() },
+    setColor: { value: t.string() },
+    setBrushSize: { value: t.number() },
+    clearCanvas: {},
+  },
+  requirements: {},
+} satisfies ModuleSchema;
+
+// ============================================================================
+// Module
+// ============================================================================
+
+const canvasModule = createModule("canvas", {
+  schema,
+
+  init: (facts) => {
+    facts.strokes = [];
+    facts.currentColor = "#5ba3a3";
+    facts.brushSize = 12;
+    facts.changesetActive = false;
+    facts.changesetLabel = "";
+  },
+
+  derive: {
+    strokeCount: (facts) => facts.strokes.length,
+    // These will be updated from the time-travel manager
+    canUndo: () => false,
+    canRedo: () => false,
+    currentIndex: () => 0,
+    totalSnapshots: () => 0,
+  },
+
+  events: {
+    addStroke: (facts, { x, y }) => {
+      const stroke: Stroke = {
+        id: `s${Date.now()}-${Math.random().toString(36).slice(2, 6)}`,
+        x,
+        y,
+        color: facts.currentColor,
+        size: facts.brushSize,
+      };
+      facts.strokes = [...facts.strokes, stroke];
+    },
+    setColor: (facts, { value }) => {
+      facts.currentColor = value;
+    },
+    setBrushSize: (facts, { value }) => {
+      facts.brushSize = value;
+    },
+    clearCanvas: (facts) => {
+      facts.strokes = [];
+    },
+  },
+});
+
+// ============================================================================
+// System with Time-Travel
+// ============================================================================
+
+const system = createSystem({
+  module: canvasModule,
+  debug: { timeTravel: true, maxSnapshots: 200, runHistory: true },
+  plugins: [devtoolsPlugin({ name: "time-machine" })],
+});
+system.start();
+
+const tt = system.debug!;
+
+// ============================================================================
+// DOM References
+// ============================================================================
+
+const ctx = canvasEl.getContext("2d")!;
+  "tm-brush-size",
+  "tm-snapshot-slider",
+  "tm-export-area",
+  "tm-begin-changeset",
+  "tm-end-changeset",
+
+// Timeline
+
+// ============================================================================
+// Canvas Rendering
+// ============================================================================
+
+function drawCanvas(): void {
+  ctx.fillStyle = "#0f172a";
+  ctx.fillRect(0, 0, canvasEl.width, canvasEl.height);
+
+  const strokes = system.facts.strokes as Stroke[];
+  for (const stroke of strokes) {
+    ctx.beginPath();
+    ctx.arc(stroke.x, stroke.y, stroke.size / 2, 0, Math.PI * 2);
+    ctx.fillStyle = stroke.color;
+    ctx.fill();
+  }
+}
+
+// ============================================================================
+// Render
+// ============================================================================
+
+function escapeHtml(text: string): string {
+
+  return div.innerHTML;
+}
+
+
+// ============================================================================
+// Subscribe
+// ============================================================================
+
+const allKeys = [...Object.keys(schema.facts)];
+system.subscribe(allKeys, render);
+
+// ============================================================================
+// Canvas Interaction (pointer events for mouse + touch)
+// ============================================================================
+
+let isDrawing = false;
+
+function canvasCoords(e: PointerEvent): { x: number; y: number } {
+  const scaleX = canvasEl.width / rect.width;
+  const scaleY = canvasEl.height / rect.height;
+
+  return {
+    x: Math.round((e.clientX - rect.left) * scaleX),
+    y: Math.round((e.clientY - rect.top) * scaleY),
+  };
+}
+
+
+// ============================================================================
+// Controls
+// ============================================================================
+
+
+// ============================================================================
+// Initial Render
+// ============================================================================
+
+render();