kayforms 0.1.1

package/packages/core/src/signal.ts

@@ -0,0 +1,399 @@
+// ============================================================================
+// @kayforms/core — Signal Engine
+// ============================================================================
+// Minimal, high-performance reactive primitives with automatic dependency
+// tracking. Inspired by Solid, Preact Signals, and the TC39 Signals proposal.
+//
+// Architecture:
+//   Signal<T>   — writable reactive value
+//   Computed<T> — read-only derived value (lazy, cached, glitch-free)
+//   Effect      — side-effect that auto-tracks dependencies
+//   batch()     — defer notifications until all writes complete
+// ============================================================================
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/** A reactive value that can be read and written */
+export interface Signal<T> {
+  /** Read the current value (tracks dependency if inside a computed/effect) */
+  readonly value: T;
+  /** Write a new value and notify subscribers */
+  set(next: T): void;
+  /** Read without tracking (useful in event handlers) */
+  peek(): T;
+  /** Subscribe to changes (returns unsubscribe function) */
+  subscribe(listener: (value: T) => void): () => void;
+}
+
+/** A read-only derived value that recomputes when dependencies change */
+export interface Computed<T> {
+  /** Read the current value (recomputes if stale, tracks dependency) */
+  readonly value: T;
+  /** Read without tracking */
+  peek(): T;
+  /** Subscribe to changes */
+  subscribe(listener: (value: T) => void): () => void;
+}
+
+/** Cleanup function returned by effects */
+export type EffectCleanup = () => void;
+
+// ---------------------------------------------------------------------------
+// Internals
+// ---------------------------------------------------------------------------
+
+/** Base class for all reactive nodes in the dependency graph */
+interface ReactiveNode {
+  /** Nodes that depend on this node */
+  subscribers: Set<ReactiveNode>;
+  /** Nodes this node depends on */
+  dependencies: Set<ReactiveNode>;
+  /** Called when a dependency changes */
+  notify(): void;
+  /** Unique ID for debugging */
+  _id: number;
+}
+
+let nodeIdCounter = 0;
+
+/** Stack of currently-evaluating subscribers (for automatic tracking) */
+const subscriberStack: ReactiveNode[] = [];
+
+/** Current batch depth (0 = not batching) */
+let batchDepth = 0;
+
+/** Pending notifications deferred during a batch */
+const batchQueue = new Set<ReactiveNode>();
+
+// ---------------------------------------------------------------------------
+// Dependency Tracking
+// ---------------------------------------------------------------------------
+
+function getCurrentSubscriber(): ReactiveNode | undefined {
+  return subscriberStack[subscriberStack.length - 1];
+}
+
+function trackDependency(source: ReactiveNode): void {
+  const subscriber = getCurrentSubscriber();
+  if (subscriber) {
+    source.subscribers.add(subscriber);
+    subscriber.dependencies.add(source);
+  }
+}
+
+function notifySubscribers(source: ReactiveNode): void {
+  // Copy to avoid mutation during iteration
+  const subs = [...source.subscribers];
+  for (const sub of subs) {
+    if (batchDepth > 0) {
+      batchQueue.add(sub);
+    } else {
+      sub.notify();
+    }
+  }
+}
+
+function cleanupDependencies(node: ReactiveNode): void {
+  for (const dep of node.dependencies) {
+    dep.subscribers.delete(node);
+  }
+  node.dependencies.clear();
+}
+
+// ---------------------------------------------------------------------------
+// Signal — Writable reactive value
+// ---------------------------------------------------------------------------
+
+class SignalImpl<T> implements ReactiveNode {
+  _id: number;
+  subscribers = new Set<ReactiveNode>();
+  dependencies = new Set<ReactiveNode>(); // Always empty for signals
+  private _value: T;
+  private _listeners = new Set<(value: T) => void>();
+
+  constructor(initial: T) {
+    this._id = nodeIdCounter++;
+    this._value = initial;
+  }
+
+  get value(): T {
+    trackDependency(this);
+    return this._value;
+  }
+
+  set(next: T): void {
+    if (Object.is(this._value, next)) return;
+    this._value = next;
+    notifySubscribers(this);
+    // Notify plain listeners
+    for (const listener of this._listeners) {
+      listener(next);
+    }
+  }
+
+  peek(): T {
+    return this._value;
+  }
+
+  subscribe(listener: (value: T) => void): () => void {
+    this._listeners.add(listener);
+    return () => {
+      this._listeners.delete(listener);
+    };
+  }
+
+  notify(): void {
+    // Signals don't get notified — they are leaf sources
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Computed — Derived reactive value (lazy + cached)
+// ---------------------------------------------------------------------------
+
+const enum ComputedState {
+  Clean,
+  Dirty,
+  Computing,
+}
+
+class ComputedImpl<T> implements ReactiveNode {
+  _id: number;
+  subscribers = new Set<ReactiveNode>();
+  dependencies = new Set<ReactiveNode>();
+  private _value: T | undefined = undefined;
+  private _fn: () => T;
+  private _state: ComputedState = ComputedState.Dirty;
+  private _listeners = new Set<(value: T) => void>();
+
+  constructor(fn: () => T) {
+    this._id = nodeIdCounter++;
+    this._fn = fn;
+  }
+
+  get value(): T {
+    trackDependency(this);
+    if (this._state !== ComputedState.Clean) {
+      this._recompute();
+    }
+    return this._value as T;
+  }
+
+  peek(): T {
+    if (this._state !== ComputedState.Clean) {
+      this._recompute();
+    }
+    return this._value as T;
+  }
+
+  subscribe(listener: (value: T) => void): () => void {
+    this._listeners.add(listener);
+    return () => {
+      this._listeners.delete(listener);
+    };
+  }
+
+  notify(): void {
+    const oldState = this._state;
+    this._state = ComputedState.Dirty;
+
+    // Only propagate if we were clean (avoid cascading re-notifications)
+    if (oldState === ComputedState.Clean) {
+      // Eagerly recompute to check if value actually changed
+      const oldValue = this._value;
+      this._recompute();
+      if (!Object.is(oldValue, this._value)) {
+        notifySubscribers(this);
+        for (const listener of this._listeners) {
+          listener(this._value as T);
+        }
+      }
+    }
+  }
+
+  private _recompute(): void {
+    if (this._state === ComputedState.Computing) {
+      throw new Error(
+        `[kayforms] Circular dependency detected in computed (node #${this._id})`
+      );
+    }
+    this._state = ComputedState.Computing;
+    cleanupDependencies(this);
+
+    subscriberStack.push(this);
+    try {
+      this._value = this._fn();
+    } finally {
+      subscriberStack.pop();
+      this._state = ComputedState.Clean;
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Effect — Side effect with automatic dependency tracking
+// ---------------------------------------------------------------------------
+
+class EffectImpl implements ReactiveNode {
+  _id: number;
+  subscribers = new Set<ReactiveNode>();
+  dependencies = new Set<ReactiveNode>();
+  private _fn: () => void | EffectCleanup;
+  private _cleanup: EffectCleanup | undefined;
+  private _disposed = false;
+
+  constructor(fn: () => void | EffectCleanup) {
+    this._id = nodeIdCounter++;
+    this._fn = fn;
+    // Run immediately to establish initial dependencies
+    this._run();
+  }
+
+  notify(): void {
+    if (!this._disposed) {
+      this._run();
+    }
+  }
+
+  private _run(): void {
+    // Run previous cleanup
+    if (this._cleanup) {
+      this._cleanup();
+      this._cleanup = undefined;
+    }
+
+    cleanupDependencies(this);
+
+    subscriberStack.push(this);
+    try {
+      const result = this._fn();
+      if (typeof result === "function") {
+        this._cleanup = result;
+      }
+    } finally {
+      subscriberStack.pop();
+    }
+  }
+
+  dispose(): void {
+    this._disposed = true;
+    if (this._cleanup) {
+      this._cleanup();
+      this._cleanup = undefined;
+    }
+    cleanupDependencies(this);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Create a writable reactive signal.
+ *
+ * @example
+ * ```ts
+ * const count = createSignal(0);
+ * console.log(count.value); // 0
+ * count.set(1);
+ * console.log(count.value); // 1
+ * ```
+ */
+export function createSignal<T>(initial: T): Signal<T> {
+  return new SignalImpl(initial);
+}
+
+/**
+ * Create a read-only computed signal that derives its value from other signals.
+ * Recomputes lazily only when dependencies change.
+ *
+ * @example
+ * ```ts
+ * const firstName = createSignal('Kay');
+ * const lastName = createSignal('Forms');
+ * const fullName = createComputed(() => `${firstName.value} ${lastName.value}`);
+ * console.log(fullName.value); // 'Kay Forms'
+ * ```
+ */
+export function createComputed<T>(fn: () => T): Computed<T> {
+  return new ComputedImpl(fn);
+}
+
+/**
+ * Create a side effect that automatically re-runs when its dependencies change.
+ * Returns a dispose function to stop the effect.
+ *
+ * @example
+ * ```ts
+ * const name = createSignal('World');
+ * const dispose = createEffect(() => {
+ *   console.log(`Hello, ${name.value}!`);
+ *   return () => console.log('cleanup');
+ * });
+ * name.set('Kayforms'); // logs cleanup, then 'Hello, Kayforms!'
+ * dispose(); // stops tracking
+ * ```
+ */
+export function createEffect(fn: () => void | EffectCleanup): EffectCleanup {
+  const effect = new EffectImpl(fn);
+  return () => effect.dispose();
+}
+
+/**
+ * Batch multiple signal writes into a single notification flush.
+ * Subscribers are only notified after the batch completes.
+ *
+ * @example
+ * ```ts
+ * const a = createSignal(1);
+ * const b = createSignal(2);
+ * batch(() => {
+ *   a.set(10);
+ *   b.set(20);
+ *   // No notifications fired yet
+ * });
+ * // All subscribers notified once here
+ * ```
+ */
+export function batch(fn: () => void): void {
+  batchDepth++;
+  try {
+    fn();
+  } finally {
+    batchDepth--;
+    if (batchDepth === 0) {
+      // Flush all pending notifications
+      const pending = [...batchQueue];
+      batchQueue.clear();
+      for (const node of pending) {
+        node.notify();
+      }
+    }
+  }
+}
+
+/**
+ * Run a function without tracking any signal reads as dependencies.
+ * Useful for reading signals inside event handlers or effects without
+ * creating unwanted subscriptions.
+ *
+ * @example
+ * ```ts
+ * createEffect(() => {
+ *   const tracked = name.value; // tracked
+ *   const untracked = untrack(() => other.value); // NOT tracked
+ * });
+ * ```
+ */
+export function untrack<T>(fn: () => T): T {
+  // Temporarily clear the subscriber stack so no dependencies are tracked
+  const saved = subscriberStack.splice(0, subscriberStack.length);
+  try {
+    return fn();
+  } finally {
+    subscriberStack.push(...saved);
+  }
+}

package/packages/core/src/time-travel.ts

@@ -0,0 +1,275 @@
+// ============================================================================
+// @kayforms/core — Time-Travel Debugging
+// ============================================================================
+// Records form history and exposes undo/redo/jumpTo APIs.
+// Fits within a <1KB bundle budget.
+// ============================================================================
+
+import { createEffect, batch } from "./signal";
+import { type FormStore } from "./form";
+
+export interface TimeTravelEntry {
+  timestamp: number;
+  values: any;
+  errors: any;
+  formLevelErrors?: any;
+  changedField?: string;
+  touched?: Record<string, boolean>;
+}
+
+export interface TimeTravelOptions {
+  maxHistory?: number;
+}
+
+export interface TimeTravelMethods {
+  undo(): void;
+  redo(): void;
+  jumpTo(index: number): void;
+  clearHistory(): void;
+  getHistory(): TimeTravelEntry[];
+  getCursor(): number;
+  importHistory(importedHistory: TimeTravelEntry[]): void;
+}
+
+// Global hook for Chrome Extension / DevTools bridge
+if (typeof window !== "undefined") {
+  const g = window as any;
+  if (!g.__KAYFORMS_DEVTOOLS__) {
+    const listeners = new Set<() => void>();
+    g.__KAYFORMS_DEVTOOLS__ = {
+      forms: {},
+      listeners,
+      onHistoryChange(listener: () => void) {
+        listeners.add(listener);
+        return () => listeners.delete(listener);
+      },
+    };
+  }
+}
+
+/**
+ * Enable time-travel debugging on a FormStore instance.
+ * Attaches undo, redo, jumpTo, clearHistory, and getHistory methods to the form.
+ */
+export function enableTimeTravel<T extends Record<string, unknown>>(
+  form: FormStore<T>,
+  options: TimeTravelOptions = {}
+): FormStore<T> & TimeTravelMethods {
+  const maxHistory = options.maxHistory ?? 100;
+  let history: TimeTravelEntry[] = [];
+  let cursor = -1;
+  let isRestoring = false;
+
+  // Tiny dot-path differences finder
+  function findDiffPath(a: any, b: any, prefix = ""): string | undefined {
+    if (a === b) return undefined;
+    if (typeof a !== "object" || typeof b !== "object" || a === null || b === null) {
+      return prefix;
+    }
+    const keys = new Set([...Object.keys(a), ...Object.keys(b)]);
+    for (const key of keys) {
+      const nextPrefix = prefix ? `${prefix}.${key}` : key;
+      const diff = findDiffPath(a[key], b[key], nextPrefix);
+      if (diff !== undefined) return diff;
+    }
+    return undefined;
+  }
+
+  // Tiny nested getByPath
+  function getByPath(obj: any, path: string): any {
+    return path.split(".").reduce((acc, part) => acc && acc[part], obj);
+  }
+
+  // Effect tracks changes to values, errors, and touched signals
+  const unsubscribe = createEffect(() => {
+    const vals = form.values.value;
+    const errs = form.errors.value;
+
+    const touched: Record<string, boolean> = {};
+    const fields = (form as any)._fields;
+    if (fields) {
+      for (const [path, field] of fields) {
+        touched[path] = field.touched.value;
+      }
+    }
+
+    if (isRestoring) return;
+
+    const clonedVals = structuredClone(vals);
+    const clonedErrs = structuredClone(errs);
+    const formLevelSignal = (form as any)._formLevelErrors;
+    const formLevelErrors = formLevelSignal ? structuredClone(formLevelSignal.value) : {};
+
+    const prevEntry = history[history.length - 1];
+    let changedField: string | undefined = undefined;
+
+    if (prevEntry) {
+      changedField = findDiffPath(prevEntry.values, clonedVals);
+      if (
+        changedField === undefined &&
+        JSON.stringify(prevEntry.errors) === JSON.stringify(clonedErrs) &&
+        JSON.stringify(prevEntry.touched) === JSON.stringify(touched)
+      ) {
+        return;
+      }
+    }
+
+    const entry: TimeTravelEntry = {
+      timestamp: Date.now(),
+      values: clonedVals,
+      errors: clonedErrs,
+      formLevelErrors,
+      touched,
+      changedField,
+    };
+
+    if (cursor >= 0 && cursor < history.length - 1) {
+      history = history.slice(0, cursor + 1);
+    }
+
+    history.push(entry);
+    if (history.length > maxHistory) {
+      history.shift();
+    }
+    cursor = history.length - 1;
+
+    // Notify listeners and DevTools Chrome Extension
+    if (typeof window !== "undefined") {
+      const g = window as any;
+      if (g.__KAYFORMS_DEVTOOLS__) {
+        for (const l of g.__KAYFORMS_DEVTOOLS__.listeners) {
+          try { l(); } catch (_) {}
+        }
+      }
+      window.dispatchEvent(
+        new CustomEvent("kayforms:history-change", {
+          detail: { formId: form.id || "default", cursor, historyLength: history.length },
+        })
+      );
+    }
+  });
+
+  function jumpTo(index: number): void {
+    if (index < 0 || index >= history.length) return;
+    cursor = index;
+    const entry = history[index];
+
+    isRestoring = true;
+    batch(() => {
+      // 1. Restore form level values
+      form.values.set(structuredClone(entry.values));
+
+      // 2. Restore form-level errors
+      const formLevelSignal = (form as any)._formLevelErrors;
+      if (formLevelSignal && entry.formLevelErrors) {
+        formLevelSignal.set(structuredClone(entry.formLevelErrors));
+      }
+
+      // 3. Restore field specific values, errors, touched
+      const fields = (form as any)._fields;
+      if (fields) {
+        for (const [path, field] of fields) {
+          const val = getByPath(entry.values, path);
+          field.value.set(val);
+
+          const err = getByPath(entry.errors, path);
+          field.error.set(err);
+
+          const isTouched = entry.touched?.[path] ?? false;
+          field.touched.set(isTouched);
+        }
+      }
+    });
+    isRestoring = false;
+
+    if (typeof window !== "undefined") {
+      window.dispatchEvent(
+        new CustomEvent("kayforms:history-change", {
+          detail: { formId: form.id || "default", cursor, historyLength: history.length },
+        })
+      );
+    }
+  }
+
+  const methods: TimeTravelMethods = {
+    undo() {
+      if (cursor > 0) {
+        jumpTo(cursor - 1);
+      }
+    },
+    redo() {
+      if (cursor < history.length - 1) {
+        jumpTo(cursor + 1);
+      }
+    },
+    jumpTo,
+    clearHistory() {
+      history = [];
+      cursor = -1;
+      
+      const fields = (form as any)._fields;
+      const touched: Record<string, boolean> = {};
+      if (fields) {
+        for (const [path, field] of fields) {
+          touched[path] = field.touched.peek();
+        }
+      }
+
+      history.push({
+        timestamp: Date.now(),
+        values: structuredClone(form.values.peek()),
+        errors: structuredClone(form.errors.peek()),
+        formLevelErrors: (form as any)._formLevelErrors ? structuredClone((form as any)._formLevelErrors.peek()) : {},
+        touched,
+      });
+      cursor = 0;
+
+      if (typeof window !== "undefined") {
+        window.dispatchEvent(
+          new CustomEvent("kayforms:history-change", {
+            detail: { formId: form.id || "default", cursor, historyLength: history.length },
+          })
+        );
+      }
+    },
+    getHistory() {
+      return history;
+    },
+    getCursor() {
+      return cursor;
+    },
+    importHistory(importedHistory) {
+      if (!Array.isArray(importedHistory) || importedHistory.length === 0) return;
+      history = importedHistory;
+      cursor = history.length - 1;
+      jumpTo(cursor);
+    },
+  };
+
+  // Attach methods to form instance
+  Object.assign(form, methods);
+
+  // Register with global devtools registry
+  const formId = form.id || "default";
+  if (typeof window !== "undefined") {
+    const g = window as any;
+    if (g.__KAYFORMS_DEVTOOLS__) {
+      g.__KAYFORMS_DEVTOOLS__.forms[formId] = form;
+    }
+  }
+
+  // Hook form dispose
+  const originalDispose = form.dispose;
+  form.dispose = () => {
+    unsubscribe();
+    if (typeof window !== "undefined") {
+      const g = window as any;
+      if (g.__KAYFORMS_DEVTOOLS__) {
+        delete g.__KAYFORMS_DEVTOOLS__.forms[formId];
+      }
+    }
+    originalDispose.call(form);
+  };
+
+  return form as FormStore<T> & TimeTravelMethods;
+}