@opentf/web-form 0.1.0 → 1.0.0

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.0.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": "workspace:*"
   },
   "publishConfig": {
     "access": "public"
+  },
+  "scripts": {
+    "test": "bun test --env=happy-dom"
+  },
+  "devDependencies": {
+    "@opentf/web": "workspace:*",
+    "@opentf/web-test": "workspace:*"
   }
-}
+}

package/tests/Basic.test.jsx

@@ -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.jsx

@@ -0,0 +1,79 @@
+import { expect, test, describe } from "bun:test";
+import { render, userEvent } from "@opentf/web-test";
+import { createForm } from "../index.js";
+
+export function ProfileForm() {
+  const form = createForm({
+    initialValues: { 
+      user: { name: "John" },
+      tags: ["js"]
+    },
+    validate: (v) => {
+      const errors = {};
+      if (v.user.name.length < 3) errors.user = { name: "Too short" };
+      return errors;
+    }
+  });
+
+  const addTag = () => form.values.tags.push(`tag-${form.values.tags.length}`);
+
+  return (
+    <div>
+      <h1 data-testid="title">{form.values.user.name}</h1>
+      <input {...form.register("user.name")} data-testid="name-input" />
+      <div data-testid="name-error">{form.errors.user?.name}</div>
+      
+      <ul data-testid="tag-list">
+        {form.values.tags.map((tag, i) => (
+          <li data-testid={`tag-${i}`}>{tag}</li>
+        ))}
+      </ul>
+      <button onclick={addTag} data-testid="add-tag">Add Tag</button>
+      
+      <div data-testid="status">{form.isValid ? "Valid" : "Invalid"}</div>
+    </div>
+  );
+}
+
+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>
+  );
+}

package/tests/DynamicArrays.test.jsx

@@ -0,0 +1,33 @@
+import { expect, test, describe } from "bun:test";
+import { render, userEvent } from "@opentf/web-test";
+import DynamicArrayForm from "./DynamicArrayForm.jsx";
+
+describe("Dynamic Arrays", () => {
+  test("adds and removes items", async () => {
+    const { getByTestId, getAllByRole, queryByTestId } = render(DynamicArrayForm);
+    const user = userEvent.setup();
+
+    const addBtn = getByTestId("add-item");
+    const list = getByTestId("item-list");
+
+    expect(getAllByRole("listitem").length).toBe(1);
+    expect(getByTestId("item-0").textContent).toContain("Item 1");
+
+    // Add item
+    await user.click(addBtn);
+    expect(getAllByRole("listitem").length).toBe(2);
+    expect(getByTestId("item-1").textContent).toContain("Item 2");
+
+    // Add another
+    await user.click(addBtn);
+    expect(getAllByRole("listitem").length).toBe(3);
+
+    // Remove middle item (Item 2 at index 1)
+    await user.click(getByTestId("remove-1"));
+    expect(getAllByRole("listitem").length).toBe(2);
+    
+    // Check remaining items
+    expect(getByTestId("item-0").textContent).toContain("Item 1");
+    expect(getByTestId("item-1").textContent).toContain("Item 3"); // Item 3 moved to index 1
+  });
+});

package/tests/DynamicListForm.jsx

@@ -0,0 +1,20 @@
+import { createForm } from "../index.js";
+
+export default function DynamicPrimitiveForm() {
+  const form = createForm({
+    initialValues: { skills: ["JavaScript", "HTML"] }
+  });
+
+  return (
+    <div>
+      {form.values.skills.map((skill, index) => (
+        <div data-testid={`row-${index}`}>
+          <input 
+            {...form.register(`skills.${index}`)} 
+            data-testid={`input-${index}`}
+          />
+        </div>
+      ))}
+    </div>
+  );
+}

package/tests/Logic.test.js

@@ -0,0 +1,153 @@
+import { expect, test, describe } from "bun:test";
+import { createForm } from "../index.js";
+
+describe("Web App Framework Forms Library - Pure Logic", () => {
+  test("initializes with flat values", () => {
+    const form = createForm({
+      initialValues: { username: "alice", email: "alice@example.com" }
+    });
+    
+    expect(form.values.username).toBe("alice");
+    expect(form.values.email).toBe("alice@example.com");
+  });
+
+  test("initializes with nested values", () => {
+    const form = createForm({
+      initialValues: {
+        profile: { firstName: "John", lastName: "Doe" }
+      }
+    });
+    
+    expect(form.values.profile.firstName).toBe("John");
+    expect(form.values.profile.lastName).toBe("Doe");
+  });
+
+  test("initializes with array values", () => {
+    const form = createForm({
+      initialValues: {
+        skills: ["JS", "Framework"]
+      }
+    });
+    
+    expect(form.values.skills[0]).toBe("JS");
+    expect(form.values.skills[1]).toBe("Framework");
+  });
+
+  test("updates values reactively", () => {
+    const form = createForm({
+      initialValues: { count: 0 }
+    });
+    
+    form.values.count = 1;
+    expect(form.values.count).toBe(1);
+  });
+
+  test("supports direct assignment to values proxy", () => {
+    const form = createForm({
+      initialValues: { user: { name: "A" } }
+    });
+    
+    form.values.user = { name: "B" };
+    expect(form.values.user.name).toBe("B");
+  });
+
+  test("validates values", () => {
+    const form = createForm({
+      mode: "onChange",
+      initialValues: { age: 20 },
+      validate: (v) => {
+        const errors = {};
+        if (v.age < 18) errors.age = "Too young";
+        return errors;
+      }
+    });
+    
+    expect(form.errors.age).toBeUndefined();
+    form.values.age = 10;
+    expect(form.errors.age).toBe("Too young");
+  });
+
+  test("errors proxy supports direct access", () => {
+    const form = createForm({
+      mode: "onChange",
+      initialValues: { username: "" },
+      validate: (v) => (v.username ? {} : { username: "Required" }),
+    });
+
+    expect(form.errors.username).toBe("Required");
+
+    form.values.username = "Alice";
+    expect(form.errors.username).toBeUndefined();
+  });
+
+
+  test("supports Zod-style validator returning { errors }", () => {
+    const form = createForm({
+      mode: "onChange",
+      initialValues: { email: "a" },
+      validator: (v) => {
+        return { errors: { email: "Invalid email" } };
+      },
+    });
+
+    expect(form.errors.email).toBe("Invalid email");
+  });
+
+  test("handles async validation", async () => {
+    const form = createForm({
+      mode: "onChange",
+      initialValues: { username: "abc" },
+      validate: async (v) => {
+        await new Promise((r) => setTimeout(r, 10));
+        return v.username.length < 3 ? { username: "Too short" } : {};
+      },
+    });
+
+    expect(form.isValidating).toBe(true); // Immediate validation in onChange mode
+    await new Promise((r) => setTimeout(r, 20));
+    expect(form.isValidating).toBe(false);
+    expect(form.errors.username).toBeUndefined();
+
+    form.values.username = "al";
+    expect(form.isValidating).toBe(true);
+    await new Promise((r) => setTimeout(r, 20));
+    expect(form.isValidating).toBe(false);
+    expect(form.errors.username).toBe("Too short");
+
+    form.values.username = "alice";
+    await new Promise((r) => setTimeout(r, 20));
+    expect(form.errors.username).toBeUndefined();
+    expect(form.isValid).toBe(true);
+  });
+
+  test("reactive array mutations (push/splice)", () => {
+    const form = createForm({
+      initialValues: { tags: ["js"] },
+    });
+
+    let changeCount = 0;
+    form._signals.values.subscribe(() => changeCount++);
+    expect(changeCount).toBe(1);
+
+    form.values.tags.push("web");
+    expect(form.values.tags).toEqual(["js", "web"]);
+    expect(changeCount).toBe(2);
+
+    form.values.tags.splice(0, 1);
+    expect(form.values.tags).toEqual(["web"]);
+    expect(changeCount).toBe(3);
+  });
+
+  test("reset() with custom values", () => {
+    const form = createForm({
+      initialValues: { a: 1 },
+    });
+
+    form.values.a = 2;
+    form.reset({ a: 10 });
+    expect(form.values.a).toBe(10);
+    expect(form.isChanged).toBe(false); // isChanged is against the NEW initialValues? 
+    // Actually, createForm stores initialValues from the constructor.
+    // If reset(newVals) is called, it should ideally update the reference for isChanged.
+  });
+});

package/tests/NestedFields.test.jsx

@@ -0,0 +1,28 @@
+import { expect, test, describe } from "bun:test";
+import { render, userEvent } from "@opentf/web-test";
+import NestedForm from "./NestedForm.jsx";
+
+describe("Nested Fields", () => {
+  test("handles deep object paths", async () => {
+    let submittedValues = null;
+    const { getByTestId } = render(NestedForm, { 
+      onSubmit: (v) => submittedValues = v 
+    });
+    const user = userEvent.setup();
+
+    const firstName = getByTestId("first-name");
+    const notifications = getByTestId("notifications");
+    const submit = getByTestId("submit");
+
+    expect(firstName.value).toBe("John");
+    expect(notifications.checked).toBe(true);
+
+    await user.clear(firstName);
+    await user.type(firstName, "Jane");
+    await user.click(notifications); // Uncheck
+
+    await user.click(submit);
+    expect(submittedValues.user.profile.firstName).toBe("Jane");
+    expect(submittedValues.user.settings.notifications).toBe(false);
+  });
+});

package/tests/NestedForm.jsx

@@ -0,0 +1,32 @@
+import { createForm } from "../index.js";
+
+export default function NestedForm({ onSubmit }) {
+  const form = createForm({
+    initialValues: {
+      user: {
+        profile: { firstName: "John" },
+        settings: { notifications: true }
+      }
+    }
+  });
+
+  return (
+    <div>
+      <input 
+        {...form.register("user.profile.firstName")} 
+        data-testid="first-name" 
+      />
+      <input 
+        type="checkbox"
+        {...form.register("user.settings.notifications")} 
+        data-testid="notifications" 
+      />
+      <button 
+        onclick={form.handleSubmit(onSubmit)} 
+        data-testid="submit"
+      >
+        Submit
+      </button>
+    </div>
+  );
+}

package/tests/Reactivity.test.jsx

@@ -0,0 +1,26 @@
+import { expect, test, describe } from "bun:test";
+import { render, userEvent } from "@opentf/web-test";
+import DynamicPrimitiveForm from "./DynamicListForm.jsx";
+
+describe("Web Form Capabilities", () => {
+  test("reactively updates dynamic primitive arrays without losing focus", async () => {
+    const { getByTestId } = render(DynamicPrimitiveForm);
+    const user = userEvent.setup();
+
+    const input0 = getByTestId("input-0");
+    const input1 = getByTestId("input-1");
+    
+    expect(input0.value).toBe("JavaScript");
+    expect(input1.value).toBe("HTML");
+
+    // Simulate typing a new character into the first input
+    await user.type(input0, "!");
+
+    // The value should update immediately via the form's reactivity loop
+    expect(input0.value).toBe("JavaScript!");
+    
+    // Crucially, the exact same DOM node should be retained (focus proves this).
+    // The node must not be destroyed and recreated.
+    expect(document.activeElement).toBe(input0);
+  });
+});

package/tests/RegisterMetadata.test.js

@@ -0,0 +1,83 @@
+import { test, expect } from "bun:test";
+import { createForm } from "../index.js";
+import { effect, signal, batch } from "@opentf/web";
+
+test("register() returns reactive metadata", async () => {
+  const form = createForm({
+    initialValues: { username: "" },
+    validator: (v) => {
+      const errors = {};
+      if (!v.username) errors.username = "Required";
+      return { errors };
+    },
+    mode: "onChange"
+  });
+
+  const field = form.register("username");
+  
+  expect(field.name).toBe("username");
+  expect(field.error.value).toBe("Required"); // Validated on init due to onChange mode
+  expect(field.isTouched.value).toBe(false);
+
+  // Update value to clear error
+  form.values.username = "valid";
+  expect(field.error.value).toBeUndefined();
+
+  // Trigger touch
+  field.onblur();
+  expect(field.isTouched.value).toBe(true);
+});
+
+test("register() handles nested metadata", () => {
+  const form = createForm({
+    initialValues: { profile: { firstName: "" } },
+    validator: (v) => {
+      const errors = {};
+      if (!v.profile?.firstName) errors.profile = { firstName: "Required" };
+      return { errors };
+    }
+  });
+
+  const field = form.register("profile.firstName");
+  
+  expect(field.name).toBe("profile.firstName");
+  expect(field.isTouched.value).toBe(false);
+
+  // Manual touch
+  field.onblur();
+  expect(field.isTouched.value).toBe(true);
+
+  // Manual error update
+  form._signals.errors.value = { profile: { firstName: "Too short" } };
+  form._notifySignals("e"); // Manual notify
+  expect(field.error.value).toBe("Too short");
+});
+
+test("register() metadata is reactive in effects", () => {
+  const form = createForm({
+    initialValues: { email: "" }
+  });
+
+  const field = form.register("email");
+  let caughtError = null;
+  let caughtTouched = null;
+
+  effect(() => {
+    caughtError = field.error.value;
+    caughtTouched = field.isTouched.value;
+  });
+
+  expect(caughtError).toBeUndefined();
+  expect(caughtTouched).toBe(false);
+
+  // Update state
+  batch(() => {
+    form._signals.errors.value = { email: "Invalid" };
+    form._signals.touched.value = { email: true };
+    form._notifySignals("e");
+    form._notifySignals("t");
+  });
+
+  expect(caughtError).toBe("Invalid");
+  expect(caughtTouched).toBe(true);
+});

package/tests/State.test.js

@@ -0,0 +1,93 @@
+import { expect, test, describe } from "bun:test";
+import { createForm } from "../index.js";
+import { sleep } from "@opentf/std";
+
+describe("Web App Framework Forms Library - State Helpers", () => {
+  test("isValid tracks error state", () => {
+    const form = createForm({
+      mode: "onChange",
+      initialValues: { name: "" },
+      validate: (v) => v.name ? {} : { name: "Error" }
+    });
+    
+    expect(form.isValid).toBe(false);
+    form.values.name = "Alice";
+    expect(form.isValid).toBe(true);
+  });
+
+  test("isChanged tracks deep equality with initial values", () => {
+    const form = createForm({
+      initialValues: { user: { name: "Alice" } }
+    });
+    
+    expect(form.isChanged).toBe(false);
+    expect(form.changed.user).toBe(false);
+    
+    form.values.user = { name: "Bob" };
+    expect(form.isChanged).toBe(true);
+    expect(form.changed.user).toBe(true);
+    
+    form.values.user = { name: "Alice" };
+    expect(form.isChanged).toBe(false);
+    expect(form.changed.user).toBe(false);
+  });
+
+  test("isTouched tracks field blur state", () => {
+    const form = createForm({
+      initialValues: { email: "" }
+    });
+    const { onblur } = form.register("email");
+    
+    expect(form.isTouched).toBe(false);
+    expect(form.touched.email).toBe(false);
+    
+    onblur();
+    expect(form.isTouched).toBe(true);
+    expect(form.touched.email).toBe(true);
+  });
+
+  test("isSubmitting and isSubmitted lifecycle", async () => {
+    let resolved = false;
+    const form = createForm({
+      initialValues: { name: "Alice" }
+    });
+    
+    const onSubmit = async () => {
+      await sleep(50);
+      resolved = true;
+    };
+    
+    const handler = form.handleSubmit(onSubmit);
+    
+    expect(form.isSubmitting).toBe(false);
+    expect(form.isSubmitted).toBe(false);
+    
+    const promise = handler();
+    expect(form.isSubmitting).toBe(true);
+    
+    await promise;
+    expect(resolved).toBe(true);
+    expect(form.isSubmitting).toBe(false);
+    expect(form.isSubmitted).toBe(true);
+  });
+
+  test("reset() restores initial state", () => {
+    const form = createForm({
+      initialValues: { count: 0 }
+    });
+    
+    form.values.count = 10;
+    form.register("count").onblur();
+    
+    expect(form.values.count).toBe(10);
+    expect(form.isChanged).toBe(true);
+    expect(form.isTouched).toBe(true);
+    
+    form.reset();
+    
+    expect(form.values.count).toBe(0);
+    expect(form.isChanged).toBe(false);
+    expect(form.isTouched).toBe(false);
+  });
+
+});