kayforms 0.1.1

package/packages/devtools/src/timeline.ts

@@ -0,0 +1,283 @@
+// ============================================================================
+// @kayforms/devtools — Timeline Component
+// ============================================================================
+// Renders the action log timeline with scrubber controls.
+// Pure DOM manipulation — no framework dependencies.
+// ============================================================================
+
+import { createEffect, type DevToolsBridge, type HistoryEntry } from "@kayforms/core";
+
+// ---------------------------------------------------------------------------
+// Timeline Renderer
+// ---------------------------------------------------------------------------
+
+export function createTimeline(
+  container: HTMLElement,
+  bridge: DevToolsBridge
+): () => void {
+  const cleanups: (() => void)[] = [];
+
+  // --- Timeline entries list ---
+  const listEl = document.createElement("div");
+  listEl.className = "kf-timeline";
+  container.appendChild(listEl);
+
+  // --- Scrubber bar ---
+  const scrubberEl = document.createElement("div");
+  scrubberEl.className = "kf-scrubber";
+
+  const controlsEl = document.createElement("div");
+  controlsEl.className = "kf-scrubber-controls";
+
+  const undoBtn = document.createElement("button");
+  undoBtn.textContent = "⏪";
+  undoBtn.title = "Undo";
+  undoBtn.onclick = () => bridge.undo();
+
+  const redoBtn = document.createElement("button");
+  redoBtn.textContent = "⏩";
+  redoBtn.title = "Redo";
+  redoBtn.onclick = () => bridge.redo();
+
+  const resumeBtn = document.createElement("button");
+  resumeBtn.textContent = "▶";
+  resumeBtn.title = "Resume (live)";
+  resumeBtn.onclick = () => bridge.resume();
+
+  const clearBtn = document.createElement("button");
+  clearBtn.textContent = "🗑";
+  clearBtn.title = "Clear history";
+  clearBtn.onclick = () => bridge.clear();
+
+  controlsEl.append(undoBtn, redoBtn, resumeBtn, clearBtn);
+
+  const slider = document.createElement("input");
+  slider.type = "range";
+  slider.min = "0";
+  slider.max = "0";
+  slider.value = "0";
+  slider.addEventListener("input", () => {
+    const index = parseInt(slider.value, 10);
+    bridge.jumpTo(index);
+  });
+
+  const countEl = document.createElement("span");
+  countEl.className = "kf-scrubber-count";
+  countEl.textContent = "0";
+
+  scrubberEl.append(controlsEl, slider, countEl);
+  container.appendChild(scrubberEl);
+
+  // --- Render entries ---
+  function renderEntry(entry: HistoryEntry, index: number, isCurrent: boolean): HTMLElement {
+    const el = document.createElement("div");
+    el.className = `kf-timeline-entry${isCurrent ? " kf-current" : ""}`;
+    el.onclick = () => bridge.jumpTo(index);
+
+    // Color dot
+    const dot = document.createElement("div");
+    dot.className = `kf-entry-dot kf-action-${entry.action}`;
+    el.appendChild(dot);
+
+    // Content
+    const content = document.createElement("div");
+    content.className = "kf-entry-content";
+
+    // Action + path
+    const actionLine = document.createElement("div");
+    const actionSpan = document.createElement("span");
+    actionSpan.className = "kf-entry-action";
+    actionSpan.textContent = entry.action;
+    actionLine.appendChild(actionSpan);
+
+    if (entry.path) {
+      const pathSpan = document.createElement("span");
+      pathSpan.className = "kf-entry-path";
+      pathSpan.textContent = entry.path;
+      actionLine.appendChild(pathSpan);
+    }
+    content.appendChild(actionLine);
+
+    // Value change
+    if (entry.prevValue !== undefined || entry.nextValue !== undefined) {
+      const valuesEl = document.createElement("div");
+      valuesEl.className = "kf-entry-values";
+
+      if (entry.prevValue !== undefined && entry.action !== "INIT") {
+        const prevEl = document.createElement("span");
+        prevEl.className = "kf-entry-prev";
+        prevEl.textContent = truncate(JSON.stringify(entry.prevValue), 20);
+        valuesEl.appendChild(prevEl);
+
+        const arrow = document.createElement("span");
+        arrow.textContent = "→";
+        arrow.style.color = "#8899aa";
+        valuesEl.appendChild(arrow);
+      }
+
+      const nextEl = document.createElement("span");
+      nextEl.className = "kf-entry-next";
+      nextEl.textContent = truncate(JSON.stringify(entry.nextValue), 30);
+      valuesEl.appendChild(nextEl);
+
+      content.appendChild(valuesEl);
+    }
+
+    // Timestamp
+    const timeEl = document.createElement("div");
+    timeEl.className = "kf-entry-time";
+    const date = new Date(entry.timestamp);
+    timeEl.textContent = `${date.getHours().toString().padStart(2, "0")}:${date.getMinutes().toString().padStart(2, "0")}:${date.getSeconds().toString().padStart(2, "0")}.${date.getMilliseconds().toString().padStart(3, "0")}`;
+    content.appendChild(timeEl);
+
+    el.appendChild(content);
+    return el;
+  }
+
+  // --- Reactive updates ---
+  const disposeEffect = createEffect(() => {
+    const entries = bridge.history.value;
+    const cursorVal = bridge.cursor.value;
+    const currentIndex = cursorVal === -1 ? entries.length - 1 : cursorVal;
+
+    // Clear and re-render (simple approach — could be optimized with diffing)
+    listEl.innerHTML = "";
+
+    // Render in reverse (newest first)
+    for (let i = entries.length - 1; i >= 0; i--) {
+      const entryEl = renderEntry(entries[i], i, i === currentIndex);
+      listEl.appendChild(entryEl);
+    }
+
+    // Update scrubber
+    slider.max = String(Math.max(0, entries.length - 1));
+    slider.value = String(currentIndex);
+    countEl.textContent = `${currentIndex + 1}/${entries.length}`;
+
+    // Auto-scroll to current entry
+    if (cursorVal === -1 && listEl.firstChild) {
+      (listEl.firstChild as HTMLElement).scrollIntoView({ behavior: "smooth", block: "nearest" });
+    }
+  });
+  cleanups.push(disposeEffect);
+
+  return () => {
+    for (const cleanup of cleanups) {
+      cleanup();
+    }
+    listEl.remove();
+    scrubberEl.remove();
+  };
+}
+
+// ---------------------------------------------------------------------------
+// State Inspector
+// ---------------------------------------------------------------------------
+
+export function createInspector(
+  container: HTMLElement,
+  bridge: DevToolsBridge
+): () => void {
+  const inspectorEl = document.createElement("div");
+  inspectorEl.className = "kf-inspector";
+  container.appendChild(inspectorEl);
+
+  function renderTree(obj: unknown, depth = 0): HTMLElement {
+    const fragment = document.createElement("div");
+
+    if (obj === null || obj === undefined) {
+      const valueEl = document.createElement("span");
+      valueEl.className = "kf-tree-value";
+      valueEl.textContent = String(obj);
+      fragment.appendChild(valueEl);
+      return fragment;
+    }
+
+    if (typeof obj !== "object") {
+      const valueEl = document.createElement("span");
+      valueEl.className = "kf-tree-value";
+      valueEl.textContent = JSON.stringify(obj);
+      fragment.appendChild(valueEl);
+      return fragment;
+    }
+
+    const entries = Object.entries(obj as Record<string, unknown>);
+    for (const [key, value] of entries) {
+      const nodeEl = document.createElement("div");
+      nodeEl.className = "kf-tree-node";
+
+      const keyEl = document.createElement("span");
+      keyEl.className = "kf-tree-key";
+      keyEl.textContent = key;
+      nodeEl.appendChild(keyEl);
+
+      const colonEl = document.createElement("span");
+      colonEl.className = "kf-tree-bracket";
+      colonEl.textContent = ": ";
+      nodeEl.appendChild(colonEl);
+
+      if (typeof value === "object" && value !== null && !Array.isArray(value)) {
+        const bracketOpen = document.createElement("span");
+        bracketOpen.className = "kf-tree-bracket";
+        bracketOpen.textContent = "{";
+        nodeEl.appendChild(bracketOpen);
+
+        if (depth < 3) {
+          nodeEl.appendChild(renderTree(value, depth + 1));
+        } else {
+          const ellipsis = document.createElement("span");
+          ellipsis.className = "kf-tree-value";
+          ellipsis.textContent = "...";
+          nodeEl.appendChild(ellipsis);
+        }
+
+        const bracketClose = document.createElement("span");
+        bracketClose.className = "kf-tree-bracket";
+        bracketClose.textContent = "}";
+        nodeEl.appendChild(bracketClose);
+      } else {
+        const valueEl = document.createElement("span");
+        valueEl.className = "kf-tree-value";
+        valueEl.textContent = JSON.stringify(value);
+        nodeEl.appendChild(valueEl);
+      }
+
+      fragment.appendChild(nodeEl);
+    }
+
+    return fragment;
+  }
+
+  const disposeEffect = createEffect(() => {
+    const entries = bridge.history.value;
+    const cursorVal = bridge.cursor.value;
+    const currentIndex = cursorVal === -1 ? entries.length - 1 : cursorVal;
+
+    inspectorEl.innerHTML = "";
+
+    const snapshot = bridge.getSnapshotAt(currentIndex);
+    if (snapshot) {
+      inspectorEl.appendChild(renderTree(snapshot));
+    } else if (entries.length === 0) {
+      const emptyEl = document.createElement("div");
+      emptyEl.style.cssText =
+        "padding: 20px; text-align: center; color: var(--kf-text-muted);";
+      emptyEl.textContent = "No form data recorded yet";
+      inspectorEl.appendChild(emptyEl);
+    }
+  });
+
+  return () => {
+    disposeEffect();
+    inspectorEl.remove();
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function truncate(str: string, max: number): string {
+  if (str.length <= max) return str;
+  return str.slice(0, max - 1) + "…";
+}

package/packages/devtools/tsconfig.json

@@ -0,0 +1,8 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "./dist",
+    "rootDir": "./src"
+  },
+  "include": ["src"]
+}

package/packages/devtools/tsup.config.ts

@@ -0,0 +1,17 @@
+import { defineConfig } from "tsup";
+
+export default defineConfig({
+  entry: ["src/index.ts"],
+  format: ["esm", "cjs"],
+  dts: true,
+  clean: true,
+  sourcemap: true,
+  minify: false,
+  treeshake: true,
+  external: ["@kayforms/core"],
+  outExtension({ format }) {
+    return {
+      js: format === "cjs" ? ".cjs" : ".js",
+    };
+  },
+});

package/packages/react/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@kayforms/react",
+  "version": "0.1.0",
+  "description": "React adapter for Kayforms reactive form library",
+  "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"
+  },
+  "dependencies": {
+    "@kayforms/core": "workspace:*"
+  },
+  "peerDependencies": {
+    "react": ">=18.0.0",
+    "react-dom": ">=18.0.0"
+  },
+  "devDependencies": {
+    "@types/react": "^18.0.0",
+    "@types/react-dom": "^18.0.0",
+    "react": "^18.0.0",
+    "react-dom": "^18.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.5.0",
+    "rimraf": "^5.0.0"
+  },
+  "sideEffects": false,
+  "license": "MIT"
+}

package/packages/react/src/index.ts

@@ -0,0 +1,279 @@
+// ============================================================================
+// @kayforms/react — React Adapter
+// ============================================================================
+// Bridges Kayforms signals to React re-renders using useSyncExternalStore.
+// Each useField() subscribes only to its own FieldNode — parent components
+// never re-render on individual field changes.
+// ============================================================================
+
+import {
+  useSyncExternalStore,
+  useCallback,
+  useRef,
+  useEffect,
+  createContext,
+  useContext,
+  createElement,
+  type ReactNode,
+} from "react";
+import {
+  createForm,
+  type FormConfig,
+  type FormStore,
+  type FormErrors,
+  type FieldNode,
+  type Signal,
+  type Computed,
+} from "@kayforms/core";
+
+// ---------------------------------------------------------------------------
+// Signal → React bridge
+// ---------------------------------------------------------------------------
+
+/**
+ * Subscribe to a Kayforms signal inside a React component.
+ * Uses useSyncExternalStore for tear-free concurrent rendering.
+ */
+export function useSignalValue<T>(signal: Signal<T> | Computed<T>): T {
+  const subscribe = useCallback(
+    (onStoreChange: () => void) => {
+      return signal.subscribe(onStoreChange);
+    },
+    [signal]
+  );
+
+  const getSnapshot = useCallback(() => signal.value, [signal]);
+
+  return useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+}
+
+// ---------------------------------------------------------------------------
+// FormContext
+// ---------------------------------------------------------------------------
+
+const FormContext = createContext<FormStore | null>(null);
+
+function useFormContext(): FormStore {
+  const ctx = useContext(FormContext);
+  if (!ctx) {
+    throw new Error(
+      "[kayforms/react] useField must be used inside a <FormProvider>. " +
+        "Wrap your form with <FormProvider form={...}>."
+    );
+  }
+  return ctx;
+}
+
+// ---------------------------------------------------------------------------
+// FormProvider
+// ---------------------------------------------------------------------------
+
+export interface FormProviderProps {
+  form: FormStore;
+  children: ReactNode;
+}
+
+/**
+ * Provides form context to nested useField() hooks.
+ *
+ * @example
+ * ```tsx
+ * const form = useForm({ initialValues: { name: '' } });
+ * return (
+ *   <FormProvider form={form.store}>
+ *     <NameField />
+ *   </FormProvider>
+ * );
+ * ```
+ */
+export function FormProvider({ form, children }: FormProviderProps) {
+  return createElement(FormContext.Provider, { value: form }, children);
+}
+
+// ---------------------------------------------------------------------------
+// useForm
+// ---------------------------------------------------------------------------
+
+export interface UseFormReturn<T extends Record<string, unknown>> {
+  /** The reactive form store */
+  store: FormStore<T>;
+  /** Current values (reactive) */
+  values: T;
+  /** Current errors (reactive) */
+  errors: FormErrors<T>;
+  /** Whether the form is dirty */
+  dirty: boolean;
+  /** Whether the form is valid */
+  valid: boolean;
+  /** Whether the form is submitting */
+  submitting: boolean;
+  /** Handle form submission (pass to <form onSubmit>) */
+  handleSubmit: (e?: { preventDefault?: () => void }) => void;
+  /** Reset the form */
+  reset: (values?: Partial<T>) => void;
+  /** Get a field node by path */
+  getField: <V = unknown>(path: string) => FieldNode<V>;
+}
+
+/**
+ * Create and manage a Kayforms form in a React component.
+ *
+ * @example
+ * ```tsx
+ * function LoginForm() {
+ *   const { handleSubmit, getField, valid, submitting } = useForm({
+ *     initialValues: { email: '', password: '' },
+ *     fieldValidators: {
+ *       email: [validators.required(), validators.email()],
+ *       password: [validators.required(), validators.minLength(8)],
+ *     },
+ *     onSubmit: async (values) => {
+ *       await login(values);
+ *     },
+ *   });
+ *
+ *   return (
+ *     <form onSubmit={handleSubmit}>
+ *       <Field field={getField('email')} />
+ *       <Field field={getField('password')} type="password" />
+ *       <button disabled={!valid || submitting}>Login</button>
+ *     </form>
+ *   );
+ * }
+ * ```
+ */
+export function useForm<T extends Record<string, unknown>>(
+  config: FormConfig<T>
+): UseFormReturn<T> {
+  // Create form store once (stable reference)
+  const storeRef = useRef<FormStore<T> | null>(null);
+  if (!storeRef.current) {
+    storeRef.current = createForm(config);
+  }
+  const store = storeRef.current;
+
+  // Cleanup on unmount
+  useEffect(() => {
+    return () => {
+      store.dispose();
+    };
+  }, [store]);
+
+  // Subscribe to reactive values
+  const values = useSignalValue(store.values);
+  const errors = useSignalValue(store.errors);
+  const dirty = useSignalValue(store.dirty);
+  const valid = useSignalValue(store.valid);
+  const submitting = useSignalValue(store.submitting);
+
+  const handleSubmit = useCallback(
+    (e?: { preventDefault?: () => void }) => {
+      e?.preventDefault?.();
+      store.submit();
+    },
+    [store]
+  );
+
+  const reset = useCallback(
+    (newValues?: Partial<T>) => {
+      store.reset(newValues);
+    },
+    [store]
+  );
+
+  return {
+    store,
+    values,
+    errors,
+    dirty,
+    valid,
+    submitting,
+    handleSubmit,
+    reset,
+    getField: store.getField,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// useField
+// ---------------------------------------------------------------------------
+
+export interface UseFieldReturn<V = unknown> {
+  /** Current field value */
+  value: V;
+  /** Current error message (undefined = valid) */
+  error: string | undefined;
+  /** Whether the field has been touched */
+  touched: boolean;
+  /** Whether the field value differs from initial */
+  dirty: boolean;
+  /** Whether async validation is in progress */
+  validating: boolean;
+  /** Update the field value */
+  onChange: (value: V) => void;
+  /** Mark as touched (call on blur) */
+  onBlur: () => void;
+  /** Props to spread on an input element */
+  inputProps: {
+    value: V;
+    onChange: (e: { target: { value: unknown } }) => void;
+    onBlur: () => void;
+  };
+}
+
+/**
+ * Subscribe to a single field's reactive state.
+ * Only re-renders when THIS field changes — not other fields.
+ *
+ * @example
+ * ```tsx
+ * function EmailField() {
+ *   const { inputProps, error, touched } = useField<string>('email');
+ *   return (
+ *     <div>
+ *       <input {...inputProps} type="email" />
+ *       {touched && error && <span className="error">{error}</span>}
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export function useField<V = unknown>(path: string): UseFieldReturn<V> {
+  const store = useFormContext();
+  const field = store.getField<V>(path);
+
+  const value = useSignalValue(field.value);
+  const error = useSignalValue(field.error);
+  const touched = useSignalValue(field.touched);
+  const dirty = useSignalValue(field.dirty);
+  const validating = useSignalValue(field.validating);
+
+  const onChange = useCallback(
+    (v: V) => field.onChange(v),
+    [field]
+  );
+
+  const onBlur = useCallback(() => field.onBlur(), [field]);
+
+  const handleInputChange = useCallback(
+    (e: { target: { value: unknown } }) => {
+      field.onChange(e.target.value as V);
+    },
+    [field]
+  );
+
+  return {
+    value,
+    error,
+    touched,
+    dirty,
+    validating,
+    onChange,
+    onBlur,
+    inputProps: {
+      value,
+      onChange: handleInputChange,
+      onBlur,
+    },
+  };
+}

package/packages/react/tsconfig.json

@@ -0,0 +1,8 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "./dist",
+    "rootDir": "./src"
+  },
+  "include": ["src"]
+}

package/packages/react/tsup.config.ts

@@ -0,0 +1,17 @@
+import { defineConfig } from "tsup";
+
+export default defineConfig({
+  entry: ["src/index.ts"],
+  format: ["esm", "cjs"],
+  dts: true,
+  clean: true,
+  sourcemap: true,
+  minify: false,
+  treeshake: true,
+  external: ["react", "react-dom", "@kayforms/core"],
+  outExtension({ format }) {
+    return {
+      js: format === "cjs" ? ".cjs" : ".js",
+    };
+  },
+});

package/packages/solid/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@kayforms/solid",
+  "version": "0.1.0",
+  "description": "Solid JS adapter for Kayforms reactive form library",
+  "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"
+  },
+  "dependencies": {
+    "@kayforms/core": "workspace:*"
+  },
+  "peerDependencies": {
+    "solid-js": "^1.0.0"
+  },
+  "devDependencies": {
+    "solid-js": "^1.8.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.5.0",
+    "rimraf": "^5.0.0"
+  },
+  "sideEffects": false,
+  "license": "MIT"
+}