@opentf/web-form 0.1.0 → 1.1.0

package/index.js

@@ -1,163 +1,350 @@
-import { signal, effect, computed, batch } from "@preact/signals-core";
+import {
+  signal,
+  computed,
+  effect,
+  batch,
+  untracked,
+  getCurrentInstance,
+  reactive,
+  toRawValue,
+  snapshot,
+} from "@opentf/web";
+
+export { signal, computed, batch, effect, untracked, reactive, getCurrentInstance };
+
+import { clone, isEql } from "@opentf/std";
 
 /**
- * Helper to set a nested property in an object.
+ * Path-based reactive forms engine for OTF Web.
+ *
+ * The form's values/errors/touched/changed trees are `reactive()` stores
+ * (@opentf/web), so `form.values.user.name` and `form.errors.email` are read
+ * directly in JSX with fine-grained reactivity — no provider object, no bespoke
+ * proxy. The engine layers field registration, validation modes, and submit
+ * orchestration on top.
  */
-const setPath = (obj, path, value) => {
-  const parts = path.split('.');
-  let current = obj;
-  for (let i = 0; i < parts.length - 1; i++) {
-    const part = parts[i];
-    const next = parts[i + 1];
-    if (!current[part]) {
-      current[part] = !isNaN(next) ? [] : {};
+
+const INST_FORMS_REGISTRY = new WeakMap();
+
+export function createForm(options = {}) {
+  // Scope the form to the mounting component so re-entrant `createForm` calls
+  // (e.g. the component body running again) return the same instance. Outside a
+  // component (module scope, tests) there is no instance — just build one.
+  const inst = getCurrentInstance();
+  if (!inst) return _createForm(options);
+
+  let forms = INST_FORMS_REGISTRY.get(inst);
+  if (!forms) INST_FORMS_REGISTRY.set(inst, (forms = new Map()));
+
+  const key = options.key || JSON.stringify({ initialValues: options.initialValues });
+  if (forms.has(key)) {
+    const form = forms.get(key);
+    form._updateConfig?.(options.mode, options.reValidateMode);
+    return form;
+  }
+  const form = _createForm(options);
+  forms.set(key, form);
+  return form;
+}
+
+function _createForm(options = {}) {
+  let initialValues = clone(options.initialValues || {});
+
+  const valuesStore = reactive(clone(initialValues));
+  const errorsStore = reactive({});
+  // touched mirrors the value tree with `false` leaves, so a field reads `false`
+  // (not undefined) before it is ever blurred. `changed` is filled by the
+  // creation effect below (top-level booleans vs. initial values).
+  const touchedStore = reactive(mirrorLeaves(initialValues, false));
+  const changedStore = reactive({});
+
+  const modeSig = signal(options.mode);
+  const reValidateModeSig = signal(options.reValidateMode);
+  const isSubmittingSig = signal(false);
+  const isValidatingSig = signal(false);
+  const isSubmittedSig = signal(false);
+  const submitCountSig = signal(0);
+
+  const normMode = (m) =>
+    ((m && typeof m === "object" && "value" in m ? m.value : m) || "onBlur");
+  const normReValidate = (m) =>
+    ((m && typeof m === "object" && "value" in m ? m.value : m) || "onChange");
+
+  const activeValidator = options.validator || options.validate;
+
+  // --- path helpers: walk the reactive store so reads subscribe & writes notify
+  function readPath(store, path) {
+    if (!path) return store;
+    let node = store;
+    for (const p of path.split(".")) {
+      if (node == null) return undefined;
+      node = node[p];
     }
-    current = current[part];
+    return node;
   }
-  current[parts[parts.length - 1]] = value;
-};
 
-/**
- * Creates a reactive form state manager.
- */
-export function createForm({ initialValues = {}, validate, schema, validator } = {}) {
-  const fields = {}; // Stores field signals by path
-  const touched = {}; // Stores touched signals by path
-  const fieldPaths = signal([]); // Track list of paths for computed to depend on
-
-  function ensureField(path, initVal) {
-    if (!fields[path]) {
-      fields[path] = signal(initVal === undefined ? "" : initVal);
-      touched[path] = signal(false);
+  function writePath(store, path, value) {
+    const parts = path.split(".");
+    let node = store;
+    for (let i = 0; i < parts.length - 1; i++) {
+      const p = parts[i];
+      let next = node[p];
+      if (next == null || typeof next !== "object") {
+        node[p] = {};
+        next = node[p];
+      }
+      node = next;
     }
-    if (!fieldPaths.value.includes(path)) {
-      fieldPaths.value = [...fieldPaths.value, path];
+    node[parts[parts.length - 1]] = value;
+  }
+
+  function deletePath(store, path) {
+    const parts = path.split(".");
+    let node = store;
+    for (let i = 0; i < parts.length - 1; i++) {
+      node = node[parts[i]];
+      if (node == null || typeof node !== "object") return;
     }
-    if (initVal !== undefined) {
-      fields[path].value = initVal;
+    delete node[parts[parts.length - 1]];
+  }
+
+  // Reconcile a reactive store in place to match a plain object, touching only
+  // the leaves that actually differ (fine-grained — no wholesale replace).
+  function syncStore(store, next) {
+    next = next || {};
+    const raw = toRawValue(store);
+    for (const k of Object.keys(raw)) {
+      if (!(k in next)) delete store[k];
+    }
+    for (const k of Object.keys(next)) {
+      const nv = next[k];
+      const cur = raw[k];
+      if (nv && typeof nv === "object" && cur && typeof cur === "object") {
+        syncStore(store[k], nv);
+      } else if (!isEql(cur, nv)) {
+        store[k] = nv;
+      }
     }
-    return fields[path];
   }
 
-  const walk = (obj, path = "") => {
-    if (obj && typeof obj === "object" && obj !== null) {
-      Object.keys(obj).forEach(key => {
-        const fullPath = path ? `${path}.${key}` : key;
-        walk(obj[key], fullPath);
-      });
-    } else if (path) {
-      ensureField(path, obj);
+  // --- validation
+  const normalizeErrors = (r) => (r && r.errors !== undefined ? r.errors : r) || {};
+
+  function applyErrors(errorsObj, fieldPath) {
+    if (fieldPath) {
+      const fieldErr = readRaw(errorsObj, fieldPath);
+      if (fieldErr) writePath(errorsStore, fieldPath, fieldErr);
+      else deletePath(errorsStore, fieldPath);
+    } else {
+      syncStore(errorsStore, errorsObj);
     }
-  };
+  }
+
+  let validationToken = 0;
+  function runValidation(fieldPath) {
+    if (!activeValidator) return;
+    const token = ++validationToken;
+    const result = activeValidator(snapshot(valuesStore));
+    if (result instanceof Promise) {
+      isValidatingSig.value = true;
+      return result
+        .then((r) => {
+          if (token === validationToken) applyErrors(normalizeErrors(r), fieldPath);
+        })
+        .finally(() => {
+          if (token === validationToken) isValidatingSig.value = false;
+        });
+    }
+    applyErrors(normalizeErrors(result), fieldPath);
+  }
 
-  // Initial population
-  batch(() => walk(initialValues));
+  // --- changed tracking: per top-level key, deep-compared to initial values.
+  function recomputeChanged() {
+    const v = toRawValue(valuesStore);
+    const keys = new Set([...Object.keys(v), ...Object.keys(initialValues)]);
+    for (const k of keys) {
+      const ch = !isEql(v[k], initialValues[k]);
+      if (toRawValue(changedStore)[k] !== ch) changedStore[k] = ch;
+    }
+  }
 
-  // Computed state object
-  const values = computed(() => {
-    const res = {};
-    fieldPaths.value.forEach(path => {
-      setPath(res, path, fields[path].value);
+  // One effect observes every value change and (a) recomputes `changed`, and
+  // (b) in onChange mode, revalidates — covering inputs, direct assignment, and
+  // array mutation alike. Writes are untracked so it never depends on its own
+  // output. Validates once on creation, satisfying onChange's "validate on init".
+  effect(() => {
+    deepTrack(valuesStore);
+    const mode = normMode(modeSig.value);
+    untracked(() => {
+      recomputeChanged();
+      if (mode === "onChange") runValidation();
     });
-    return res;
   });
 
-  const errors = signal({});
-
-  // Reactive validation
-  effect(() => {
-    const currentValues = values.value;
-    if (validator) {
-      const result = validator(currentValues, schema);
-      errors.value = result.errors || {};
-    } else if (validate) {
-      errors.value = validate(currentValues) || {};
+  // --- field registration
+  function updateValue(path, val) {
+    writePath(valuesStore, path, val);
+    const mode = normMode(modeSig.peek());
+    if (mode === "onChange") return; // the effect above revalidates
+    if (hasTruthy(toRawValue(errorsStore)) && normReValidate(reValidateModeSig.peek()) === "onChange") {
+      runValidation(path);
     }
+  }
+
+  const register = (path) => ({
+    name: path,
+    value: readPath(valuesStore, path),
+    checked: readPath(valuesStore, path),
+    error: computed(() => readPath(errorsStore, path)),
+    isTouched: computed(() => readPath(touchedStore, path) ?? false),
+    oninput: (e) => {
+      const t = e.target;
+      updateValue(path, t.type === "checkbox" ? t.checked : t.value);
+    },
+    onblur: () => {
+      writePath(touchedStore, path, true);
+      const mode = normMode(modeSig.peek());
+      if (mode === "onBlur") runValidation(path);
+      else if (
+        hasTruthy(toRawValue(errorsStore)) &&
+        normReValidate(reValidateModeSig.peek()) === "onBlur"
+      ) {
+        runValidation(path);
+      }
+    },
   });
 
-  function register(name) {
-    const s = ensureField(name);
-    return {
-      name,
-      value: s, 
-      oninput: (e) => {
-        s.value = e.target.type === 'checkbox' ? e.target.checked : e.target.value;
-      },
-      onblur: () => {
-        if (touched[name]) touched[name].value = true;
+  // --- submit / reset
+  const handleSubmit = (fn) => async (e) => {
+    if (e && e.preventDefault) e.preventDefault();
+    syncStore(touchedStore, mirrorLeaves(snapshot(valuesStore), true));
+    isSubmittingSig.value = true;
+    submitCountSig.value++;
+    await runValidation();
+    if (!hasTruthy(toRawValue(errorsStore))) {
+      try {
+        await fn(snapshot(valuesStore));
+        isSubmittedSig.value = true;
+      } finally {
+        isSubmittingSig.value = false;
       }
-    };
-  }
+    } else {
+      isSubmittingSig.value = false;
+    }
+  };
+
+  const reset = (newValues) => {
+    batch(() => {
+      if (newValues !== undefined) initialValues = clone(newValues);
+      syncStore(valuesStore, clone(initialValues));
+      syncStore(errorsStore, {});
+      syncStore(touchedStore, mirrorLeaves(initialValues, false));
+      syncStore(changedStore, {});
+      isSubmittedSig.value = false;
+    });
+  };
 
-  function handleSubmit(onSubmit) {
-    return (e) => {
-      if (e && e.preventDefault) e.preventDefault();
-      
-      // Mark all fields as touched on submit
+  // --- derived flags
+  const isValidSig = computed(() => !hasTruthy(errorsStore));
+  const isTouchedSig = computed(() => hasTruthy(touchedStore));
+  const isChangedSig = computed(() => hasTruthy(changedStore));
+
+  const form = {
+    register,
+    handleSubmit,
+    reset,
+    _updateConfig(newMode, newReValidateMode) {
       batch(() => {
-        fieldPaths.value.forEach(path => {
-          if (touched[path]) touched[path].value = true;
-        });
+        modeSig.value = newMode;
+        reValidateModeSig.value = newReValidateMode;
       });
+    },
+    _notifySignals() {}, // legacy no-op: reactive stores notify on write
+    get values() { return valuesStore; },
+    get errors() { return errorsStore; },
+    get touched() { return touchedStore; },
+    get changed() { return changedStore; },
+    _signals: {
+      values: storeSignal(valuesStore),
+      errors: storeSignal(errorsStore),
+      touched: storeSignal(touchedStore),
+      changed: storeSignal(changedStore),
+    },
+  };
 
-      const currentValues = values.value;
-      let currentErrors = {};
-      if (validator) {
-        currentErrors = validator(currentValues, schema).errors || {};
-      } else if (validate) {
-        currentErrors = validate(currentValues) || {};
-      }
-      
-      errors.value = currentErrors;
-      
-      if (Object.keys(currentErrors).length === 0) {
-        onSubmit(currentValues);
-      }
-    };
-  }
+  Object.defineProperties(form, {
+    isValid: { get: () => isValidSig.value, enumerable: true },
+    isChanged: { get: () => isChangedSig.value, enumerable: true },
+    isTouched: { get: () => isTouchedSig.value, enumerable: true },
+    isSubmitting: { get: () => isSubmittingSig.value, enumerable: true },
+    isValidating: { get: () => isValidatingSig.value, enumerable: true },
+    isSubmitted: { get: () => isSubmittedSig.value, enumerable: true },
+    submitCount: { get: () => submitCountSig.value, enumerable: true },
+  });
 
-  function setValues(newValues) {
-    batch(() => {
-      const keysToUpdate = Object.keys(newValues);
-      const remainingPaths = fieldPaths.value.filter(path => {
-        return !keysToUpdate.some(k => path === k || path.startsWith(k + "."));
-      });
-      fieldPaths.value = remainingPaths;
-      walk(newValues);
-    });
+  return form;
+}
+
+// --- shared helpers (no per-form state)
+
+/** Raw (non-reactive) deep read by dot-path. */
+function readRaw(obj, path) {
+  let node = obj;
+  for (const p of path.split(".")) {
+    if (node == null) return undefined;
+    node = node[p];
   }
+  return node;
+}
+
+/** Whether any leaf is truthy — the basis of isValid/isTouched/isChanged. */
+function hasTruthy(obj) {
+  if (obj == null || typeof obj !== "object") return !!obj;
+  return Object.values(obj).some(hasTruthy);
+}
 
-  function array(path) {
-    return computed(() => values.value[path] || []);
+/** Mirror a tree's structure, replacing every leaf with `leaf`. */
+function mirrorLeaves(obj, leaf) {
+  if (obj == null || typeof obj !== "object") return leaf;
+  const res = Array.isArray(obj) ? [] : {};
+  for (const k of Object.keys(obj)) res[k] = mirrorLeaves(obj[k], leaf);
+  return res;
+}
+
+/** Subscribe the active consumer to every path in a store (deep). */
+function deepTrack(store) {
+  const raw = toRawValue(store);
+  if (raw == null || typeof raw !== "object") return;
+  for (const k of Object.keys(store)) {
+    const v = store[k];
+    if (v && typeof v === "object") deepTrack(v);
   }
+}
 
+/**
+ * A preact-style signal facade over a reactive store for the advanced `_signals`
+ * API: `.value` snapshots/replaces the whole tree, `.subscribe(cb)` fires
+ * immediately then once per change.
+ */
+function storeSignal(store) {
   return {
-    register,
-    handleSubmit,
-    setValues,
-    getValues: () => values.value,
-    array,
-    values: new Proxy({}, {
-      get: (_, key) => values.value[key],
-      set: (_, key, val) => {
-        setValues({ [key]: val });
-        return true;
-      },
-      ownKeys: (_) => Object.keys(values.value),
-      getOwnPropertyDescriptor: (_, key) => {
-        const val = values.value[key];
-        return val !== undefined ? {
-          enumerable: true,
-          configurable: true,
-          value: val,
-          writable: true
-        } : undefined;
-      }
-    }),
-    errors,
-    touched: new Proxy({}, {
-      get: (_, key) => touched[key]
-    }),
-    fields // Also expose the raw signals map for advanced usage
+    get value() {
+      return snapshot(store);
+    },
+    set value(v) {
+      const next = v || {};
+      const raw = toRawValue(store);
+      for (const k of Object.keys(raw)) if (!(k in next)) delete store[k];
+      for (const k of Object.keys(next)) store[k] = next[k];
+    },
+    peek() {
+      return toRawValue(store);
+    },
+    subscribe(cb) {
+      return effect(() => {
+        deepTrack(store);
+        cb(snapshot(store));
+      });
+    },
   };
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@opentf/web-form",
-  "version": "0.1.0",
-  "description": "A high-performance, path-based reactive forms library for Web App Framework and beyond.",
+  "version": "1.1.0",
+  "description": "A high-performance, path-based reactive forms engine for the native-first OTF Web.",
   "main": "index.js",
   "module": "index.js",
   "type": "module",
@@ -9,12 +9,19 @@
     ".": "./index.js"
   },
   "dependencies": {
-    "@preact/signals-core": "^1.14.1"
+    "@opentf/std": "^1.0.0-beta.2"
   },
   "peerDependencies": {
-    "zod": "^4.3.6"
+    "@opentf/web": "*"
   },
   "publishConfig": {
     "access": "public"
+  },
+  "scripts": {
+    "test": "bun test --env=happy-dom"
+  },
+  "devDependencies": {
+    "@opentf/web": "0.6.0",
+    "@opentf/web-test": "1.1.0"
   }
-}
+}

package/tests/Basic.test.js

@@ -0,0 +1,37 @@
+import { expect, test, describe } from "bun:test";
+import { render, userEvent } from "@opentf/web-test";
+import BasicForm from "./BasicForm.jsx";
+
+describe("Basic Form", () => {
+  test("initializes and handles submission", async () => {
+    let submittedValues = null;
+    const { getByTestId, queryByTestId } = render(BasicForm, { 
+      onSubmit: (v) => submittedValues = v 
+    });
+    const user = userEvent.setup();
+
+    const username = getByTestId("username");
+    const email = getByTestId("email");
+    const submit = getByTestId("submit");
+
+    expect(username.value).toBe("alice");
+    expect(email.value).toBe("");
+
+    // Try to submit with invalid email
+    await user.click(submit);
+    expect(submittedValues).toBeNull();
+    expect(getByTestId("email-error").textContent).toBe("Invalid email");
+
+    // Correct the email
+    await user.type(email, "alice@example.com");
+    expect(queryByTestId("email-error")).toBeNull();
+
+    // Change username
+    await user.clear(username);
+    await user.type(username, "bob");
+    
+    // Submit
+    await user.click(submit);
+    expect(submittedValues).toEqual({ username: "bob", email: "alice@example.com" });
+  });
+});

package/tests/BasicForm.jsx

@@ -0,0 +1,29 @@
+import { createForm } from "../index.js";
+
+export default function BasicForm({ onSubmit }) {
+  const form = createForm({
+    initialValues: { username: "alice", email: "" },
+    validate: (values) => {
+      const errs = {};
+      if (!values.username) errs.username = "Username required";
+      if (!values.email.includes("@")) errs.email = "Invalid email";
+      return errs;
+    }
+  });
+
+  return (
+    <form onsubmit={form.handleSubmit(onSubmit)}>
+      <div>
+        <label for="username">Username</label>
+        <input {...form.register("username")} id="username" data-testid="username" />
+        {form.errors.username && <span data-testid="username-error">{form.errors.username}</span>}
+      </div>
+      <div>
+        <label for="email">Email</label>
+        <input {...form.register("email")} id="email" data-testid="email" />
+        {form.errors.email && <span data-testid="email-error">{form.errors.email}</span>}
+      </div>
+      <button type="submit" data-testid="submit">Submit</button>
+    </form>
+  );
+}

package/tests/Component.test.js

@@ -0,0 +1,46 @@
+import { expect, test, describe } from "bun:test";
+import { render, userEvent } from "@opentf/web-test";
+import ProfileForm from "./ProfileForm.jsx";
+
+describe("Web Form Component Integration", () => {
+  test("updates nested values and validation state in UI", async () => {
+    const { getByTestId } = render(ProfileForm);
+    const user = userEvent.setup();
+
+    const input = getByTestId("name-input");
+    const error = getByTestId("name-error");
+    const status = getByTestId("status");
+    const title = getByTestId("title");
+
+    expect(title.textContent).toBe("John");
+    expect(status.textContent).toBe("Valid");
+
+    await user.clear(input);
+    await user.type(input, "Jo");
+    // Mode is onBlur by default, so we need to blur
+    await user.tab();
+
+    expect(title.textContent).toBe("Jo");
+    expect(error.textContent).toBe("Too short");
+    expect(status.textContent).toBe("Invalid");
+
+    await user.type(input, "hnny");
+    await user.tab();
+    expect(error.textContent).toBe("");
+    expect(status.textContent).toBe("Valid");
+  });
+
+  test("handles dynamic array mutations in UI", async () => {
+    const { getByTestId, getAllByRole } = render(ProfileForm);
+    const user = userEvent.setup();
+
+    const list = getByTestId("tag-list");
+    const addBtn = getByTestId("add-tag");
+
+    expect(list.children.length).toBe(1);
+
+    await user.click(addBtn);
+    expect(list.children.length).toBe(2);
+    expect(getByTestId("tag-1").textContent).toBe("tag-1");
+  });
+});

package/tests/DynamicArrayForm.jsx

@@ -0,0 +1,32 @@
+import { createForm } from "../index.js";
+
+export default function DynamicArrayForm() {
+  const form = createForm({
+    initialValues: { items: ["Item 1"] }
+  });
+
+  const addItem = () => {
+    const items = form.values.items;
+    form.values.items = [...items, `Item ${items.length + 1}`];
+  };
+
+  const removeItem = (index) => {
+    const newItems = [...form.values.items];
+    newItems.splice(index, 1);
+    form.values.items = newItems;
+  };
+
+  return (
+    <div>
+      <button onclick={addItem} data-testid="add-item">Add Item</button>
+      <ul data-testid="item-list">
+        {form.values.items.map((item, index) => (
+          <li data-testid={`item-${index}`}>
+            {item}
+            <button onclick={() => removeItem(index)} data-testid={`remove-${index}`}>Remove</button>
+          </li>
+        ))}
+      </ul>
+    </div>
+  );
+}