kayforms 0.1.1

package/packages/core/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@kayforms/core",
+  "version": "0.1.2",
+  "description": "Framework-agnostic reactive form engine built on signals",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "clean": "rimraf dist",
+    "typecheck": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "tsup": "^8.0.0",
+    "typescript": "^5.5.0",
+    "rimraf": "^5.0.0"
+  },
+  "sideEffects": false,
+  "license": "MIT"
+}

package/packages/core/src/batch.ts

@@ -0,0 +1,106 @@
+// ============================================================================
+// @kayforms/core — Smart Batching Scheduler
+// ============================================================================
+// Provides intelligent scheduling for different types of form operations:
+//   - Sync validations → run immediately (microtask)
+//   - Async validations → debounced (configurable delay)
+//   - Derived/computed fields → lazy (on read)
+// ============================================================================
+
+export interface SchedulerOptions {
+  /** Debounce delay for async validators in ms (default: 300) */
+  asyncDebounce?: number;
+}
+
+export interface Scheduler {
+  /** Schedule a synchronous task to run in the current microtask */
+  immediate(fn: () => void): void;
+  /** Schedule an async task with debouncing by key */
+  debounced(key: string, fn: () => void | Promise<void>, delay?: number): void;
+  /** Cancel a pending debounced task by key */
+  cancel(key: string): void;
+  /** Cancel all pending tasks */
+  cancelAll(): void;
+  /** Flush all pending tasks immediately */
+  flush(): void;
+}
+
+/**
+ * Create a smart batching scheduler for form operations.
+ *
+ * @example
+ * ```ts
+ * const scheduler = createScheduler({ asyncDebounce: 300 });
+ * scheduler.immediate(() => runSyncValidation(field));
+ * scheduler.debounced('email', () => checkEmailExists(email), 500);
+ * ```
+ */
+export function createScheduler(options: SchedulerOptions = {}): Scheduler {
+  const defaultDelay = options.asyncDebounce ?? 300;
+  const pendingTimers = new Map<string, ReturnType<typeof setTimeout>>();
+  const pendingMicrotasks: (() => void)[] = [];
+  let microtaskScheduled = false;
+
+  function flushMicrotasks(): void {
+    microtaskScheduled = false;
+    const tasks = pendingMicrotasks.splice(0, pendingMicrotasks.length);
+    for (const task of tasks) {
+      task();
+    }
+  }
+
+  return {
+    immediate(fn: () => void): void {
+      pendingMicrotasks.push(fn);
+      if (!microtaskScheduled) {
+        microtaskScheduled = true;
+        queueMicrotask(flushMicrotasks);
+      }
+    },
+
+    debounced(
+      key: string,
+      fn: () => void | Promise<void>,
+      delay?: number
+    ): void {
+      // Cancel any existing timer for this key
+      const existing = pendingTimers.get(key);
+      if (existing !== undefined) {
+        clearTimeout(existing);
+      }
+
+      const timer = setTimeout(() => {
+        pendingTimers.delete(key);
+        fn();
+      }, delay ?? defaultDelay);
+
+      pendingTimers.set(key, timer);
+    },
+
+    cancel(key: string): void {
+      const timer = pendingTimers.get(key);
+      if (timer !== undefined) {
+        clearTimeout(timer);
+        pendingTimers.delete(key);
+      }
+    },
+
+    cancelAll(): void {
+      for (const timer of pendingTimers.values()) {
+        clearTimeout(timer);
+      }
+      pendingTimers.clear();
+      pendingMicrotasks.length = 0;
+    },
+
+    flush(): void {
+      // Flush microtasks
+      flushMicrotasks();
+      // Flush debounced
+      for (const [key, timer] of pendingTimers) {
+        clearTimeout(timer);
+        pendingTimers.delete(key);
+      }
+    },
+  };
+}

package/packages/core/src/devtools.ts

@@ -0,0 +1,329 @@
+// ============================================================================
+// @kayforms/core — Time-Travel DevTools Bridge
+// ============================================================================
+// Records every form mutation and enables time-travel debugging:
+//   - Snapshot + delta history
+//   - Undo / redo / jumpTo
+//   - Subscribable for external consumers (in-page panel, Chrome extension)
+// ============================================================================
+
+import { createSignal, type Signal } from "./signal";
+import { type FormStore } from "./form";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface HistoryEntry {
+  /** Monotonically increasing entry index */
+  index: number;
+  /** Unix timestamp in ms */
+  timestamp: number;
+  /** Action type */
+  action: string;
+  /** Field path (undefined for form-level actions like RESET, SUBMIT) */
+  path?: string;
+  /** Value before the action */
+  prevValue: unknown;
+  /** Value after the action */
+  nextValue: unknown;
+  /** Form ID (if registered) */
+  formId?: string;
+  /**
+   * Full form snapshot at this point.
+   * Only stored every N entries (configurable) to save memory.
+   * `undefined` for delta-only entries.
+   */
+  snapshot?: Record<string, unknown>;
+}
+
+export interface DevToolsBridge {
+  /** All recorded history entries */
+  readonly history: Signal<HistoryEntry[]>;
+  /** Current cursor position in the timeline (-1 = latest) */
+  readonly cursor: Signal<number>;
+  /** Whether time-travel is active (cursor !== -1) */
+  readonly isTimeTraveling: Signal<boolean>;
+
+  /** Jump to a specific history index */
+  jumpTo(index: number): void;
+  /** Undo the last action */
+  undo(): void;
+  /** Redo the next action */
+  redo(): void;
+  /** Resume live mode (cursor = latest) */
+  resume(): void;
+  /** Clear all history */
+  clear(): void;
+  /** Get the full form snapshot at a given history index */
+  getSnapshotAt(index: number): Record<string, unknown> | undefined;
+
+  /** Subscribe to new history entries */
+  subscribe(listener: (entry: HistoryEntry) => void): () => void;
+  /** Attach to a form store (starts recording) */
+  attach(form: FormStore): () => void;
+  /** Detach from all forms */
+  detach(): void;
+}
+
+export interface DevToolsConfig {
+  /** Store a full snapshot every N entries (default: 10) */
+  snapshotInterval?: number;
+  /** Maximum history entries to keep (default: 500) */
+  maxEntries?: number;
+  /** Enable in production? (default: false) */
+  enableInProduction?: boolean;
+}
+
+// ---------------------------------------------------------------------------
+// Implementation
+// ---------------------------------------------------------------------------
+
+/**
+ * Create a DevTools bridge for time-travel debugging.
+ *
+ * @example
+ * ```ts
+ * import { createDevTools } from '@kayforms/core';
+ *
+ * const devtools = createDevTools();
+ * const form = createForm({ id: 'login', initialValues: { email: '' } });
+ * devtools.attach(form);
+ *
+ * // In your debug panel:
+ * devtools.history.value; // all recorded actions
+ * devtools.jumpTo(5);     // rewind to entry 5
+ * devtools.undo();        // undo last action
+ * ```
+ */
+export function createDevTools(config: DevToolsConfig = {}): DevToolsBridge {
+  const {
+    snapshotInterval = 10,
+    maxEntries = 500,
+  } = config;
+
+  // Skip in production unless explicitly enabled
+  const isEnabled =
+    config.enableInProduction ||
+    typeof process === "undefined" ||
+    (typeof process !== "undefined" &&
+      (process as unknown as Record<string, Record<string, string>>).env?.NODE_ENV !== "production");
+
+  const history = createSignal<HistoryEntry[]>([]);
+  const cursor = createSignal(-1);
+  const isTimeTraveling = createSignal(false);
+
+  let entryCounter = 0;
+  const listeners = new Set<(entry: HistoryEntry) => void>();
+  const attachedForms = new Map<string | undefined, () => void>();
+  const formStores = new Map<string | undefined, FormStore>();
+
+  function record(
+    action: string,
+    path: string | undefined,
+    prevValue: unknown,
+    nextValue: unknown,
+    formId: string | undefined,
+    form: FormStore
+  ): void {
+    if (!isEnabled || isTimeTraveling.peek()) return;
+
+    const index = entryCounter++;
+    const entry: HistoryEntry = {
+      index,
+      timestamp: Date.now(),
+      action,
+      path,
+      prevValue,
+      nextValue,
+      formId,
+    };
+
+    // Store full snapshot at intervals
+    if (index % snapshotInterval === 0) {
+      entry.snapshot = structuredClone(form.values.peek()) as Record<string, unknown>;
+    }
+
+    const current = history.peek();
+    let next: HistoryEntry[];
+
+    // If we were time-traveling and new actions come in, truncate future
+    if (cursor.peek() >= 0 && cursor.peek() < current.length - 1) {
+      next = [...current.slice(0, cursor.peek() + 1), entry];
+      cursor.set(-1);
+    } else {
+      next = [...current, entry];
+    }
+
+    // Evict oldest entries if over limit
+    if (next.length > maxEntries) {
+      next = next.slice(next.length - maxEntries);
+    }
+
+    history.set(next);
+
+    // Notify listeners
+    for (const listener of listeners) {
+      listener(entry);
+    }
+  }
+
+  function reconstructFormState(formId: string | undefined, targetIndex: number) {
+    const entries = history.peek();
+    let values: Record<string, unknown> = {};
+    const touchedStates: Record<string, boolean> = {};
+
+    for (let i = 0; i <= targetIndex; i++) {
+      const entry = entries[i];
+      if (entry.formId !== formId) continue;
+
+      if (entry.action === "INIT" || entry.action === "RESET") {
+        values = structuredClone(entry.nextValue) as Record<string, unknown>;
+        for (const k of Object.keys(touchedStates)) {
+          touchedStates[k] = false;
+        }
+      } else if (entry.action === "SUBMIT") {
+        values = structuredClone(entry.nextValue) as Record<string, unknown>;
+        for (const k of Object.keys(touchedStates)) {
+          touchedStates[k] = true;
+        }
+      } else if (entry.action === "SET_VALUE") {
+        if (entry.path) {
+          setNestedValue(values, entry.path, entry.nextValue);
+        }
+      } else if (entry.action === "SET_TOUCHED") {
+        if (entry.path) {
+          touchedStates[entry.path] = !!entry.nextValue;
+        }
+      }
+    }
+
+    return { values, touchedStates };
+  }
+
+  function getSnapshotAt(index: number): Record<string, unknown> | undefined {
+    const firstFormId = formStores.keys().next().value;
+    return reconstructFormState(firstFormId, index).values;
+  }
+
+  function setNestedValue(
+    obj: Record<string, unknown>,
+    path: string,
+    value: unknown
+  ): void {
+    const keys = path.split(".");
+    let current = obj;
+    for (let i = 0; i < keys.length - 1; i++) {
+      if (!current[keys[i]] || typeof current[keys[i]] !== "object") {
+        current[keys[i]] = {};
+      }
+      current = current[keys[i]] as Record<string, unknown>;
+    }
+    current[keys[keys.length - 1]] = value;
+  }
+
+  const bridge: DevToolsBridge = {
+    history,
+    cursor,
+    isTimeTraveling,
+
+    jumpTo(index: number): void {
+      const entries = history.peek();
+      if (index < 0 || index >= entries.length) return;
+
+      isTimeTraveling.set(true);
+      cursor.set(index);
+
+      // Restore form state for all attached forms
+      for (const [formId, form] of formStores) {
+        const { values: restoredValues, touchedStates } = reconstructFormState(formId, index);
+        
+        // Reset form values to snapshot
+        form.reset(restoredValues);
+        
+        // Re-apply touched states
+        for (const [path, isTouched] of Object.entries(touchedStates)) {
+          if (isTouched) {
+            form.getField(path).touched.set(true);
+          }
+        }
+      }
+
+      isTimeTraveling.set(false);
+    },
+
+    undo(): void {
+      const entries = history.peek();
+      if (entries.length === 0) return;
+
+      const currentCursor = cursor.peek();
+      const target =
+        currentCursor === -1 ? entries.length - 2 : currentCursor - 1;
+
+      if (target >= 0) {
+        bridge.jumpTo(target);
+      }
+    },
+
+    redo(): void {
+      const entries = history.peek();
+      const currentCursor = cursor.peek();
+
+      if (currentCursor === -1 || currentCursor >= entries.length - 1) return;
+      bridge.jumpTo(currentCursor + 1);
+    },
+
+    resume(): void {
+      cursor.set(-1);
+    },
+
+    clear(): void {
+      history.set([]);
+      cursor.set(-1);
+      entryCounter = 0;
+    },
+
+    getSnapshotAt,
+
+    subscribe(listener: (entry: HistoryEntry) => void): () => void {
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+
+    attach(form: FormStore): () => void {
+      const formId = form.id;
+      formStores.set(formId, form);
+
+      // Wire up the form's action listener to record history
+      const prevOnAction = form._onAction;
+      form._onAction = (action, path, prevValue, nextValue) => {
+        prevOnAction?.(action, path, prevValue, nextValue);
+        record(action, path, prevValue, nextValue, formId, form);
+      };
+
+      // Record initial state
+      record("INIT", undefined, undefined, form.values.peek(), formId, form);
+
+      const detach = () => {
+        form._onAction = prevOnAction;
+        attachedForms.delete(formId);
+        formStores.delete(formId);
+      };
+
+      attachedForms.set(formId, detach);
+      return detach;
+    },
+
+    detach(): void {
+      for (const [, detachFn] of attachedForms) {
+        detachFn();
+      }
+      attachedForms.clear();
+      formStores.clear();
+    },
+  };
+
+  return bridge;
+}

package/packages/core/src/field.ts

@@ -0,0 +1,167 @@
+// ============================================================================
+// @kayforms/core — FieldNode
+// ============================================================================
+// Per-field reactive state. Each FieldNode is an isolated reactive island:
+// changing field A does NOT trigger subscribers of field B.
+// ============================================================================
+
+import { createSignal, createComputed, type Signal, type Computed } from "./signal";
+import {
+  type FieldValidator,
+  type FieldValidationConfig,
+  runFieldValidatorsSync,
+  runFieldValidators,
+} from "./validation";
+import { type Scheduler } from "./batch";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface FieldNode<V = unknown> {
+  /** Dot-separated path (e.g., 'address.city') */
+  readonly path: string;
+  /** Current value signal */
+  readonly value: Signal<V>;
+  /** Current error message (undefined = valid) */
+  readonly error: Signal<string | undefined>;
+  /** Whether the field has been touched (blurred) */
+  readonly touched: Signal<boolean>;
+  /** Whether the value differs from initial */
+  readonly dirty: Computed<boolean>;
+  /** Whether the field is currently validating (async) */
+  readonly validating: Signal<boolean>;
+
+  /** Update the value (triggers validation per config) */
+  onChange(value: V): void;
+  /** Mark as touched and trigger blur validation */
+  onBlur(): void;
+  /** Reset field to its initial value */
+  reset(value?: V): void;
+  /** Run validation manually */
+  validate(): Promise<string | undefined>;
+}
+
+export interface FieldNodeConfig<V = unknown> extends FieldValidationConfig<V> {
+  path: string;
+  initialValue: V;
+  scheduler: Scheduler;
+  validateOn: "change" | "blur" | "submit";
+  /** Callback when value changes (used by FormStore to update the values object) */
+  onValueChange?: (path: string, value: V) => void;
+  /** Callback when an action occurs (used by DevTools bridge) */
+  onAction?: (action: string, path: string, prevValue: V, nextValue: V) => void;
+}
+
+// ---------------------------------------------------------------------------
+// Implementation
+// ---------------------------------------------------------------------------
+
+export function createFieldNode<V = unknown>(
+  config: FieldNodeConfig<V>
+): FieldNode<V> {
+  const {
+    path,
+    initialValue,
+    validators: fieldValidators = [],
+    scheduler,
+    validateOn,
+    onValueChange,
+    onAction,
+  } = config;
+
+  let _initialValue = initialValue;
+
+  const value = createSignal<V>(initialValue);
+  const error = createSignal<string | undefined>(undefined);
+  const touched = createSignal(false);
+  const validating = createSignal(false);
+
+  const dirty = createComputed(() => !Object.is(value.value, _initialValue));
+
+  // Run sync validators immediately, schedule async validators
+  function runValidation(val: V): void {
+    // Immediate sync validation
+    const syncError = runFieldValidatorsSync(val, fieldValidators as FieldValidator<V>[]);
+    error.set(syncError);
+
+    // Check if there are async validators (functions that return promises)
+    const hasAsync = fieldValidators.some((v) => {
+      const result = v(val);
+      if (result instanceof Promise) {
+        // Clean up the test promise
+        result.catch(() => {});
+        return true;
+      }
+      return false;
+    });
+
+    if (hasAsync && !syncError) {
+      validating.set(true);
+      scheduler.debounced(`validate:${path}`, async () => {
+        const asyncError = await runFieldValidators(
+          val,
+          fieldValidators as FieldValidator<V>[]
+        );
+        error.set(asyncError);
+        validating.set(false);
+      });
+    }
+  }
+
+  const field: FieldNode<V> = {
+    path,
+    value,
+    error,
+    touched,
+    dirty,
+    validating,
+
+    onChange(next: V): void {
+      const prev = value.peek();
+      if (Object.is(prev, next)) return;
+
+      value.set(next);
+      onValueChange?.(path, next);
+      onAction?.("SET_VALUE", path, prev, next);
+
+      if (validateOn === "change") {
+        runValidation(next);
+      }
+    },
+
+    onBlur(): void {
+      if (!touched.peek()) {
+        touched.set(true);
+        onAction?.("SET_TOUCHED", path, false as unknown as V, true as unknown as V);
+      }
+
+      if (validateOn === "blur" || validateOn === "change") {
+        runValidation(value.peek());
+      }
+    },
+
+    reset(newValue?: V): void {
+      const resetValue = newValue ?? _initialValue;
+      _initialValue = resetValue;
+      value.set(resetValue);
+      error.set(undefined);
+      touched.set(false);
+      validating.set(false);
+      scheduler.cancel(`validate:${path}`);
+    },
+
+    async validate(): Promise<string | undefined> {
+      validating.set(true);
+      const result = await runFieldValidators(
+        value.peek(),
+        fieldValidators as FieldValidator<V>[]
+      );
+      error.set(result);
+      validating.set(false);
+      return result;
+    },
+  };
+
+  return field;
+}