kayforms 0.1.1

package/packages/core/src/form.ts

@@ -0,0 +1,448 @@
+// ============================================================================
+// @kayforms/core — FormStore
+// ============================================================================
+// The main entry point for creating and managing forms. Creates a reactive
+// FormStore with per-field granularity, form-level validation, and integration
+// hooks for DevTools and cross-form registry.
+// ============================================================================
+
+import {
+  createSignal,
+  createComputed,
+  batch,
+  type Signal,
+  type Computed,
+} from "./signal";
+import { createFieldNode, type FieldNode, type FieldNodeConfig } from "./field";
+import {
+  type ValidatorFn,
+  type ValidationResult,
+  type FieldValidator,
+} from "./validation";
+import { createScheduler, type Scheduler, type SchedulerOptions } from "./batch";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/** Nested error type: mirrors the form values shape with string errors */
+export type FormErrors<T> = {
+  [K in keyof T]?: T[K] extends Record<string, unknown>
+    ? FormErrors<T[K]>
+    : string;
+};
+
+/** Configuration for per-field validators */
+export type FieldValidators<T> = {
+  [K in keyof T]?: FieldValidator<T[K]>[];
+};
+
+/** Form configuration passed to createForm() */
+export interface FormConfig<T extends Record<string, unknown>> {
+  /** Unique form ID (required for cross-form signals and DevTools) */
+  id?: string;
+  /** Initial values for all fields */
+  initialValues: T;
+  /** Form-level validation function */
+  validate?: ValidatorFn<T>;
+  /** Per-field validators */
+  fieldValidators?: FieldValidators<T>;
+  /** When to trigger validation (default: 'blur') */
+  validateOn?: "change" | "blur" | "submit";
+  /** Submit handler */
+  onSubmit?: (values: T) => void | Promise<void>;
+  /** Scheduler options */
+  scheduler?: SchedulerOptions;
+}
+
+/** The reactive form store returned by createForm() */
+export interface FormStore<T extends Record<string, unknown> = Record<string, unknown>> {
+  /** Unique form ID */
+  readonly id: string | undefined;
+  /** Reactive object containing all current values */
+  readonly values: Signal<T>;
+  /** Computed form-level errors */
+  readonly errors: Computed<FormErrors<T>>;
+  /** Whether any field has been touched */
+  readonly touched: Computed<boolean>;
+  /** Whether any field value differs from initial */
+  readonly dirty: Computed<boolean>;
+  /** Whether all fields are valid (no errors) */
+  readonly valid: Computed<boolean>;
+  /** Whether the form is currently submitting */
+  readonly submitting: Signal<boolean>;
+  /** Number of fields currently async-validating */
+  readonly validating: Computed<boolean>;
+
+  /** Get or create a FieldNode by dot-path */
+  getField<V = unknown>(path: string): FieldNode<V>;
+  /** Set a field value programmatically */
+  setFieldValue(path: string, value: unknown): void;
+  /** Set a field as touched */
+  setFieldTouched(path: string, isTouched?: boolean): void;
+  /** Reset the entire form (optionally with new initial values) */
+  reset(values?: Partial<T>): void;
+  /** Submit the form */
+  submit(): Promise<void>;
+  /** Validate all fields and return errors */
+  validateAll(): Promise<FormErrors<T>>;
+  /** Dispose the form and all subscriptions */
+  dispose(): void;
+
+  /** Access the internal scheduler */
+  readonly _scheduler: Scheduler;
+  /** Internal map of field nodes (for DevTools/time-travel) */
+  readonly _fields?: Map<string, FieldNode<any>>;
+  /** Internal form-level errors signal (for DevTools/time-travel) */
+  readonly _formLevelErrors?: Signal<Record<string, string | undefined>>;
+  /** DevTools action listener */
+  _onAction?: (
+    action: string,
+    path: string | undefined,
+    prevValue: unknown,
+    nextValue: unknown
+  ) => void;
+}
+
+// ---------------------------------------------------------------------------
+// Utilities
+// ---------------------------------------------------------------------------
+
+/** Get a value from a nested object by dot path */
+function getByPath(obj: Record<string, unknown>, path: string): unknown {
+  const keys = path.split(".");
+  let current: unknown = obj;
+  for (const key of keys) {
+    if (current === null || current === undefined) return undefined;
+    current = (current as Record<string, unknown>)[key];
+  }
+  return current;
+}
+
+/** Set a value in a nested object by dot path (immutable — returns new object) */
+function setByPath<T extends Record<string, unknown>>(
+  obj: T,
+  path: string,
+  value: unknown
+): T {
+  const keys = path.split(".");
+  if (keys.length === 1) {
+    return { ...obj, [keys[0]]: value } as T;
+  }
+
+  const [head, ...rest] = keys;
+  const child = (obj[head] ?? {}) as Record<string, unknown>;
+  return {
+    ...obj,
+    [head]: setByPath(child, rest.join("."), value),
+  } as T;
+}
+
+/** Flatten a nested object into dot-path keys */
+function flattenKeys(
+  obj: Record<string, unknown>,
+  prefix = ""
+): string[] {
+  const keys: string[] = [];
+  for (const key of Object.keys(obj)) {
+    const fullPath = prefix ? `${prefix}.${key}` : key;
+    const value = obj[key];
+    if (
+      value !== null &&
+      typeof value === "object" &&
+      !Array.isArray(value)
+    ) {
+      keys.push(...flattenKeys(value as Record<string, unknown>, fullPath));
+    } else {
+      keys.push(fullPath);
+    }
+  }
+  return keys;
+}
+
+// ---------------------------------------------------------------------------
+// createForm()
+// ---------------------------------------------------------------------------
+
+/**
+ * Create a reactive form store.
+ *
+ * @example
+ * ```ts
+ * const form = createForm({
+ *   id: 'login',
+ *   initialValues: { email: '', password: '' },
+ *   fieldValidators: {
+ *     email: [validators.required(), validators.email()],
+ *     password: [validators.required(), validators.minLength(8)],
+ *   },
+ *   validateOn: 'blur',
+ *   onSubmit: async (values) => {
+ *     await api.login(values);
+ *   },
+ * });
+ * ```
+ */
+export function createForm<T extends Record<string, unknown>>(
+  config: FormConfig<T>
+): FormStore<T> {
+  const {
+    id,
+    initialValues,
+    validate: formValidator,
+    fieldValidators: fieldValidatorsMap = {} as FieldValidators<T>,
+    validateOn = "blur",
+    onSubmit,
+    scheduler: schedulerOptions,
+  } = config;
+
+  const scheduler = createScheduler(schedulerOptions);
+  const fieldNodes = new Map<string, FieldNode>();
+  let _initialValues = { ...initialValues };
+
+  // --- Core signals ---
+  const values = createSignal<T>({ ...initialValues });
+  const submitting = createSignal(false);
+  const formLevelErrors = createSignal<ValidationResult>({});
+
+  // DevTools action listener (set by registry/devtools)
+  let _onAction:
+    | ((
+        action: string,
+        path: string | undefined,
+        prevValue: unknown,
+        nextValue: unknown
+      ) => void)
+    | undefined;
+
+  // --- Computed signals ---
+  const errors = createComputed<FormErrors<T>>(() => {
+    const allErrors: Record<string, string | undefined> = {
+      ...formLevelErrors.value,
+    };
+
+    // Collect field-level errors
+    for (const [path, field] of fieldNodes) {
+      const fieldError = field.error.value;
+      if (fieldError) {
+        allErrors[path] = fieldError;
+      }
+    }
+
+    // Convert flat errors to nested object matching T shape
+    const nested: Record<string, unknown> = {};
+    for (const [path, error] of Object.entries(allErrors)) {
+      if (error) {
+        const keys = path.split(".");
+        let current = nested;
+        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]] = error;
+      }
+    }
+
+    return nested as FormErrors<T>;
+  });
+
+  const touched = createComputed(() => {
+    for (const field of fieldNodes.values()) {
+      if (field.touched.value) return true;
+    }
+    return false;
+  });
+
+  const dirty = createComputed(() => {
+    for (const field of fieldNodes.values()) {
+      if (field.dirty.value) return true;
+    }
+    return false;
+  });
+
+  const valid = createComputed(() => {
+    // Check form-level errors
+    const fErrors = formLevelErrors.value;
+    for (const key of Object.keys(fErrors)) {
+      if (fErrors[key]) return false;
+    }
+    // Check field-level errors
+    for (const field of fieldNodes.values()) {
+      if (field.error.value) return false;
+    }
+    return true;
+  });
+
+  const validating = createComputed(() => {
+    for (const field of fieldNodes.values()) {
+      if (field.validating.value) return true;
+    }
+    return false;
+  });
+
+  // --- Field management ---
+  function getField<V = unknown>(path: string): FieldNode<V> {
+    let field = fieldNodes.get(path);
+    if (!field) {
+      const initialValue = getByPath(_initialValues, path);
+      const fieldConfig: FieldNodeConfig = {
+        path,
+        initialValue,
+        validators: (fieldValidatorsMap as Record<string, FieldValidator[]>)[path] ?? [],
+        scheduler,
+        validateOn,
+        onValueChange: (p: string, v: unknown) => {
+          const current = values.peek();
+          values.set(setByPath(current, p, v));
+
+          // Run form-level validation if configured
+          if (formValidator) {
+            scheduler.debounced("form-validate", () => {
+              const result = formValidator(values.peek());
+              if (result instanceof Promise) {
+                result.then((r) => formLevelErrors.set(r));
+              } else {
+                formLevelErrors.set(result);
+              }
+            });
+          }
+        },
+        onAction: (action, p, prev, next) => {
+          _onAction?.(action, p, prev, next);
+        },
+      };
+      field = createFieldNode(fieldConfig);
+      fieldNodes.set(path, field);
+    }
+    return field as FieldNode<V>;
+  }
+
+  // Pre-create field nodes for all initial value paths
+  const initialPaths = flattenKeys(initialValues as Record<string, unknown>);
+  for (const path of initialPaths) {
+    getField(path);
+  }
+
+  // --- Form store ---
+  const store: FormStore<T> = {
+    id,
+    values,
+    errors,
+    touched,
+    dirty,
+    valid,
+    submitting,
+    validating,
+    _scheduler: scheduler,
+    _fields: fieldNodes,
+    _formLevelErrors: formLevelErrors,
+
+    get _onAction() {
+      return _onAction;
+    },
+    set _onAction(
+      fn:
+        | ((
+            action: string,
+            path: string | undefined,
+            prevValue: unknown,
+            nextValue: unknown
+          ) => void)
+        | undefined
+    ) {
+      _onAction = fn;
+    },
+
+    getField,
+
+    setFieldValue(path: string, value: unknown): void {
+      const field = getField(path);
+      field.onChange(value);
+    },
+
+    setFieldTouched(path: string, isTouched = true): void {
+      const field = getField(path);
+      if (isTouched) {
+        field.onBlur();
+      }
+    },
+
+    reset(newValues?: Partial<T>): void {
+      const resetValues = { ..._initialValues, ...newValues } as T;
+      _initialValues = { ...resetValues };
+
+      batch(() => {
+        values.set({ ...resetValues });
+        formLevelErrors.set({});
+        submitting.set(false);
+
+        // Reset all field nodes
+        for (const [path, field] of fieldNodes) {
+          const fieldValue = getByPath(resetValues, path);
+          field.reset(fieldValue);
+        }
+      });
+
+      _onAction?.("RESET", undefined, undefined, resetValues);
+    },
+
+    async submit(): Promise<void> {
+      // Touch all fields
+      for (const field of fieldNodes.values()) {
+        field.onBlur();
+      }
+
+      // Validate all fields
+      const allErrors = await store.validateAll();
+      const hasErrors = Object.keys(allErrors).length > 0;
+
+      if (hasErrors) {
+        return;
+      }
+
+      submitting.set(true);
+      _onAction?.("SUBMIT", undefined, undefined, values.peek());
+
+      try {
+        await onSubmit?.(values.peek());
+      } finally {
+        submitting.set(false);
+      }
+    },
+
+    async validateAll(): Promise<FormErrors<T>> {
+      const fieldErrors: Record<string, string | undefined> = {};
+
+      // Validate all fields
+      const validationPromises = [...fieldNodes.entries()].map(
+        async ([path, field]) => {
+          const error = await field.validate();
+          if (error) {
+            fieldErrors[path] = error;
+          }
+        }
+      );
+      await Promise.all(validationPromises);
+
+      // Run form-level validation
+      if (formValidator) {
+        const result = formValidator(values.peek());
+        const formErrors =
+          result instanceof Promise ? await result : result;
+        formLevelErrors.set(formErrors);
+        Object.assign(fieldErrors, formErrors);
+      }
+
+      return fieldErrors as FormErrors<T>;
+    },
+
+    dispose(): void {
+      scheduler.cancelAll();
+      fieldNodes.clear();
+    },
+  };
+
+  return store;
+}

package/packages/core/src/index.ts

@@ -0,0 +1,71 @@
+// ============================================================================
+// @kayforms/core — Public API
+// ============================================================================
+
+// Signal primitives
+export {
+  createSignal,
+  createComputed,
+  createEffect,
+  batch,
+  untrack,
+  type Signal,
+  type Computed,
+  type EffectCleanup,
+} from "./signal";
+
+// Form engine
+export {
+  createForm,
+  type FormConfig,
+  type FormStore,
+  type FormErrors,
+  type FieldValidators,
+} from "./form";
+
+// Field nodes
+export { createFieldNode, type FieldNode, type FieldNodeConfig } from "./field";
+
+// Validation
+export {
+  validators,
+  withSchema,
+  runFieldValidators,
+  runFieldValidatorsSync,
+  type ValidatorFn,
+  type FieldValidator,
+  type FieldValidationConfig,
+  type ValidationResult,
+} from "./validation";
+
+// Batching / Scheduling
+export {
+  createScheduler,
+  type Scheduler,
+  type SchedulerOptions,
+} from "./batch";
+
+// Cross-form registry
+export {
+  getFormRegistry,
+  createFormRegistry,
+  resetGlobalRegistry,
+  type FormRegistry,
+} from "./registry";
+
+// DevTools
+export {
+  createDevTools,
+  type DevToolsBridge,
+  type DevToolsConfig,
+  type HistoryEntry,
+} from "./devtools";
+
+// Time-Travel
+export {
+  enableTimeTravel,
+  type TimeTravelEntry,
+  type TimeTravelOptions,
+  type TimeTravelMethods,
+} from "./time-travel";
+

package/packages/core/src/registry.ts

@@ -0,0 +1,126 @@
+// ============================================================================
+// @kayforms/core — Cross-Form Signal Registry
+// ============================================================================
+// Enables reactive cross-form communication. Form A can react to Form B's
+// values, validity, or any derived state — all through the same signal graph.
+// ============================================================================
+
+import { createSignal, type Signal } from "./signal";
+import { type FormStore } from "./form";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface FormRegistry {
+  /** Register a form in the registry */
+  register<T extends Record<string, unknown>>(form: FormStore<T>): void;
+  /** Unregister a form */
+  unregister(id: string): void;
+  /** Get a registered form by ID */
+  get<T extends Record<string, unknown>>(id: string): FormStore<T> | undefined;
+  /** Get all registered form IDs */
+  getIds(): string[];
+  /** Signal that fires when the registry changes (form added/removed) */
+  readonly changed: Signal<number>;
+  /** Dispose the registry */
+  dispose(): void;
+}
+
+// ---------------------------------------------------------------------------
+// Singleton registry
+// ---------------------------------------------------------------------------
+
+let _globalRegistry: FormRegistry | undefined;
+
+/**
+ * Get or create the global form registry.
+ * Forms with an `id` auto-register here on creation.
+ *
+ * @example
+ * ```ts
+ * const registry = getFormRegistry();
+ *
+ * const profileForm = createForm({ id: 'profile', initialValues: { name: '' } });
+ * registry.register(profileForm);
+ *
+ * const paymentForm = createForm({ id: 'payment', initialValues: { card: '' } });
+ * registry.register(paymentForm);
+ *
+ * // Cross-form computed
+ * const canCheckout = createComputed(() => {
+ *   const profile = registry.get('profile');
+ *   const payment = registry.get('payment');
+ *   return (profile?.valid.value ?? false) && (payment?.valid.value ?? false);
+ * });
+ * ```
+ */
+export function getFormRegistry(): FormRegistry {
+  if (!_globalRegistry) {
+    _globalRegistry = createFormRegistry();
+  }
+  return _globalRegistry;
+}
+
+/**
+ * Create a new isolated form registry (useful for testing or SSR).
+ */
+export function createFormRegistry(): FormRegistry {
+  const forms = new Map<string, FormStore>();
+  const changed = createSignal(0);
+
+  return {
+    register<T extends Record<string, unknown>>(form: FormStore<T>): void {
+      if (!form.id) {
+        throw new Error(
+          "[kayforms] Cannot register a form without an id. Pass `id` to createForm()."
+        );
+      }
+      if (forms.has(form.id)) {
+        console.warn(
+          `[kayforms] Form with id "${form.id}" is already registered. Overwriting.`
+        );
+      }
+      forms.set(form.id, form as FormStore);
+      changed.set(changed.peek() + 1);
+    },
+
+    unregister(id: string): void {
+      if (forms.delete(id)) {
+        changed.set(changed.peek() + 1);
+      }
+    },
+
+    get<T extends Record<string, unknown>>(
+      id: string
+    ): FormStore<T> | undefined {
+      // Reading `changed` signal creates a dependency so computeds
+      // that access the registry will re-evaluate when forms are added/removed
+      const _version = changed.value;
+      void _version;
+      return forms.get(id) as FormStore<T> | undefined;
+    },
+
+    getIds(): string[] {
+      return [...forms.keys()];
+    },
+
+    changed,
+
+    dispose(): void {
+      for (const form of forms.values()) {
+        form.dispose();
+      }
+      forms.clear();
+      changed.set(0);
+    },
+  };
+}
+
+/**
+ * Reset the global registry (useful for testing).
+ */
+export function resetGlobalRegistry(): void {
+  _globalRegistry?.dispose();
+  _globalRegistry = undefined;
+}