@opentf/web-form 0.1.0-alpha.1 → 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,8 @@
+# @opentf/web-form
+
+## 1.0.0
+
+### Patch Changes
+
+- Updated dependencies [bb1c71b]
+  - @opentf/web@0.5.0

package/README.md

@@ -0,0 +1,141 @@
+# @opentf/web-form
+
+A reactive form management library for **OTF Web**.
+
+## Features
+
+- ✅ **Reactive Binding**: Seamlessly bind form values to signals.
+- 🌲 **Nested State**: Support for complex, nested form structures.
+- 🛡️ **Validation**: Flexible validation system with Zod or custom logic.
+- 🚀 **High Performance**: Direct DOM updates without VDOM overhead.
+- 🛠️ **Simple API**: Featuring a `register` pattern for clean boilerplate-free code.
+
+## Installation
+
+```bash
+npm install @opentf/web-form
+```
+
+## Basic Usage
+
+### Using the `register` Pattern
+
+The `register` function returns all necessary props (`name`, `value`, `oninput`, `onblur`) to bind a field to an input element.
+
+```jsx
+import { createForm } from '@opentf/web-form';
+
+const form = createForm({
+  initialValues: { username: '' }
+});
+
+// In your component
+<input {...form.register('username')} />
+```
+
+## Validation with Zod
+
+You can easily integrate **Zod** for schema-based validation by providing a `validator` function.
+
+```javascript
+import { createForm } from '@opentf/web-form';
+import { z } from 'zod';
+
+const schema = z.object({
+  username: z.string().min(3, 'Too short'),
+  email: z.string().email('Invalid email')
+});
+
+// A simple Zod validator wrapper
+const zodValidator = (values, schema) => {
+  const result = schema.safeParse(values);
+  if (result.success) return {};
+  const errors = {};
+  result.error.errors.forEach(e => {
+    errors[e.path.join('.')] = e.message;
+  });
+  return { errors };
+};
+
+const form = createForm({
+  initialValues: { username: '', email: '' },
+  schema,
+  validator: zodValidator // Can return { errors: ... } or direct errors object
+});
+
+const onSubmit = (values) => {
+  console.log('Form Submitted:', values);
+};
+
+// In your component
+<form onsubmit={form.handleSubmit(onSubmit)}>
+  <div>
+    <input {...form.register('username')} placeholder="Username" />
+    <span className="error">{form.errors.username}</span>
+  </div>
+  
+  <div>
+    <input {...form.register('email')} placeholder="Email" />
+    <span className="error">{form.errors.email}</span>
+  </div>
+
+  <button type="submit">Submit</button>
+</form>
+```
+
+## Form State Helpers
+
+`createForm` returns several reactive signals and proxies to track the form lifecycle:
+
+| Helper | Type | Description |
+| :--- | :--- | :--- |
+| `isValid` | `Signal<boolean>` | `true` if there are no validation errors. |
+| `isChanged` | `Signal<boolean>` | `true` if the form values differ from `initialValues`. |
+| `isTouched` | `Signal<boolean>` | `true` if any field has been blurred. |
+| `isSubmitting` | `Signal<boolean>` | `true` while the `onSubmit` handler is running. |
+| `isSubmitted` | `Signal<boolean>` | `true` if the form has been successfully submitted. |
+| `touched` | `Proxy<boolean>` | Access per-field touched state: `form.touched.email`. |
+| `changed` | `Proxy<boolean>` | Access per-field changed state: `form.changed.email`. |
+
+## Validation Modes
+
+You can customize when validation triggers using `mode` and `reValidateMode`.
+
+```javascript
+const form = createForm({
+  mode: 'onBlur',          // Initial validation: 'onSubmit', 'onBlur', 'onTouched', 'onChange'
+  reValidateMode: 'onChange' // Re-validation: 'onChange', 'onBlur', 'onSubmit'
+});
+```
+
+- **Default mode**: `onBlur`
+- **Default reValidateMode**: `onChange`
+
+### Resetting the Form
+
+You can restore the form to its `initialValues` and clear all status flags using the `reset()` method.
+
+```javascript
+<button type="button" onclick={() => form.reset()}>
+  Reset Form
+</button>
+```
+
+## Custom Validation
+
+For simpler cases, you can use the `validate` function which expects you to return the errors object directly.
+
+```javascript
+const form = createForm({
+  initialValues: { age: 0 },
+  validate: (values) => {
+    const errors = {};
+    if (values.age < 18) errors.age = 'Too young';
+    return errors;
+  }
+});
+```
+
+## License
+
+MIT © [Open Tech Foundation](https://github.com/Open-Tech-Foundation)

package/bunfig.toml

@@ -0,0 +1,6 @@
+[test]
+env = "happy-dom"
+preload = ["../web-test/setup.js"]
+
+[jsx]
+runtime = "classic"

package/index.js

@@ -1,163 +1,377 @@
-import { signal, effect, computed, batch } from "@preact/signals-core";
+
+import {
+  signal,
+  computed,
+  batch,
+  effect,
+  untracked,
+  getCurrentInstance,
+} from "@opentf/web";
+
+export { signal, computed, batch, effect, untracked, getCurrentInstance };
+
+import { set, get, unset, clone, isEql } from "@opentf/std";
 
 /**
- * Helper to set a nested property in an object.
+ * Enterprise Form Reactivity Engine
+ * 
+ * Features:
+ * - Mount-Aware Stability Cache
+ * - Setup-Phase Subscription Isolation
+ * - Deep Reactive Proxy with Array Mutation Support
  */
-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) ? [] : {};
-    }
-    current = current[part];
+
+const INST_FORMS_REGISTRY = new WeakMap();
+let isSetup = false;
+
+export function createForm(options = {}) {
+  const inst = getCurrentInstance();
+  if (!inst) return _createForm(options);
+
+  if (!INST_FORMS_REGISTRY.has(inst)) {
+    INST_FORMS_REGISTRY.set(inst, new Map());
   }
-  current[parts[parts.length - 1]] = value;
-};
+  const forms = INST_FORMS_REGISTRY.get(inst);
 
-/**
- * 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);
-    }
-    if (!fieldPaths.value.includes(path)) {
-      fieldPaths.value = [...fieldPaths.value, path];
-    }
-    if (initVal !== undefined) {
-      fields[path].value = initVal;
+  const key = options.key || JSON.stringify({
+    initialValues: options.initialValues
+  });
+  
+  if (forms.has(key)) {
+    const form = forms.get(key);
+    if (form._updateConfig) {
+      form._updateConfig(options.mode, options.reValidateMode);
     }
-    return fields[path];
+    return form;
   }
 
-  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);
+  isSetup = true;
+  try {
+    const form = _createForm(options);
+    forms.set(key, form);
+    return form;
+  } finally {
+    isSetup = false;
+  }
+}
+
+function _createForm(options = {}) {
+  const initialValuesSig = signal(clone(options.initialValues || {}));
+  const valuesSig = signal(clone(initialValuesSig.value));
+  const errorsSig = signal({});
+  const touchedSig = signal({});
+  const changedSig = signal({});
+  const isSubmittingSig = signal(false);
+  const isValidatingSig = signal(false);
+  const isSubmittedSig = signal(false);
+  const submitCountSig = signal(0);
+  const modeSig = signal(options.mode);
+  const reValidateModeSig = signal(options.reValidateMode);
+
+  const signalsCache = new Map();
+
+  function getSignal(sigType, path, defaultValue) {
+    const key = `${sigType}:${path}`;
+    if (signalsCache.has(key)) return signalsCache.get(key);
+    const initialVal = get(
+      sigType === "v" ? valuesSig.peek() : sigType === "e" ? errorsSig.peek() : sigType === "t" ? touchedSig.peek() : changedSig.peek(),
+      path
+    );
+    const sig = signal(initialVal ?? defaultValue);
+    signalsCache.set(key, sig);
+    return sig;
+  }
+
+  function notifySignals(sigType) {
+    const prefix = `${sigType}:`;
+    const fullData = sigType === "v" ? valuesSig.peek() : sigType === "e" ? errorsSig.peek() : sigType === "t" ? touchedSig.peek() : changedSig.peek();
+    
+    for (const [cacheKey, sig] of signalsCache) {
+      if (!cacheKey.startsWith(prefix)) continue;
+      const path = cacheKey.slice(prefix.length);
+      const newVal = path === "" ? fullData : get(fullData, path);
+      sig.value = newVal;
     }
-  };
+  }
 
-  // Initial population
-  batch(() => walk(initialValues));
+  const getMode = () => {
+    const m = modeSig.value;
+    return (m instanceof Object && 'value' in m ? m.value : m) || "onBlur";
+  };
+  const getReValidateMode = () => {
+    const rm = reValidateModeSig.value;
+    return (rm instanceof Object && 'value' in rm ? rm.value : rm) || "onChange";
+  };
+  const activeValidator = options.validator || options.validate;
 
-  // Computed state object
-  const values = computed(() => {
-    const res = {};
-    fieldPaths.value.forEach(path => {
-      setPath(res, path, fields[path].value);
+  function hasErrors(obj) {
+    if (!obj || typeof obj !== "object") return false;
+    return Object.values(obj).some((v) => {
+      if (v === undefined || v === null) return false;
+      if (typeof v === "object") return hasErrors(v);
+      return true;
     });
-    return res;
-  });
+  }
 
-  const errors = signal({});
+  const isValidSig = computed(() => !hasErrors(errorsSig.value));
+  const isTouchedSig = computed(() => hasErrors(touchedSig.value));
+  const isDirtySig = computed(() => !isEql(valuesSig.value, initialValuesSig.value));
 
-  // 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) || {};
+  function updateErrors(results, fieldPath) {
+    const currentErrors = results && results.errors ? results.errors : results || {};
+    if (fieldPath) {
+      const fieldError = get(currentErrors, fieldPath);
+      const newErrors = clone(errorsSig.value || {});
+      if (fieldError) set(newErrors, fieldPath, fieldError);
+      else unset(newErrors, fieldPath);
+      errorsSig.value = newErrors;
+    } else {
+      errorsSig.value = currentErrors || {};
     }
-  });
+    notifySignals("e");
+  }
+
+  function runValidation(fieldPath) {
+    if (!activeValidator) return;
+
+    untracked(() => {
+      const results = activeValidator(valuesSig.peek());
+      if (results instanceof Promise) {
+        isValidatingSig.value = true;
+        return results.then((res) => updateErrors(res, fieldPath)).finally(() => isValidatingSig.value = false);
+      }
+      updateErrors(results, fieldPath);
+    });
+  }
 
-  function register(name) {
-    const s = ensureField(name);
+  function updateValue(path, val) {
+    batch(() => {
+      const newState = clone(valuesSig.peek());
+      if (path === "") {
+        valuesSig.value = clone(val);
+      } else {
+        set(newState, path, val);
+        valuesSig.value = newState;
+      }
+      notifySignals("v");
+
+      const isFieldChanged = !isEql(val, path === "" ? initialValuesSig.peek() : get(initialValuesSig.peek(), path));
+      const newChanged = clone(changedSig.peek() || {});
+      if (path === "") {
+        // Root changed?
+      } else {
+        set(newChanged, path, isFieldChanged);
+        changedSig.value = newChanged;
+      }
+      notifySignals("c");
+
+      const mode = getMode();
+      const hasAnyErrors = hasErrors(errorsSig.peek());
+      const reValidateMode = getReValidateMode();
+
+      if (mode === "onChange") runValidation(path);
+      else if (hasAnyErrors && reValidateMode === "onChange") runValidation(path);
+    });
+  }
+  const register = (path) => {
+    const valSig = getSignal("v", path);
+    const errSig = getSignal("e", path);
+    const touchSig = getSignal("t", path, false);
+    
     return {
-      name,
-      value: s, 
+      name: path,
+      value: valSig,
+      checked: valSig,
+      error: errSig,
+      isTouched: touchSig,
       oninput: (e) => {
-        s.value = e.target.type === 'checkbox' ? e.target.checked : e.target.value;
+        const val = e.target.type === "checkbox" ? e.target.checked : e.target.value;
+        updateValue(path, val);
       },
       onblur: () => {
-        if (touched[name]) touched[name].value = true;
-      }
+        const newTouched = clone(touchedSig.value || {});
+        set(newTouched, path, true);
+        touchedSig.value = newTouched;
+        notifySignals("t", path, touchedSig.value);
+        const mode = getMode();
+        if (mode === "onBlur") runValidation(path);
+      },
     };
-  }
+  };
 
-  function handleSubmit(onSubmit) {
-    return (e) => {
-      if (e && e.preventDefault) e.preventDefault();
-      
-      // Mark all fields as touched on submit
-      batch(() => {
-        fieldPaths.value.forEach(path => {
-          if (touched[path]) touched[path].value = true;
-        });
-      });
+  function markAllTouched(obj) {
+    if (!obj || typeof obj !== "object") return true;
+    const res = Array.isArray(obj) ? [] : {};
+    Object.keys(obj).forEach((key) => {
+      res[key] = markAllTouched(obj[key]);
+    });
+    return res;
+  }
 
-      const currentValues = values.value;
-      let currentErrors = {};
-      if (validator) {
-        currentErrors = validator(currentValues, schema).errors || {};
-      } else if (validate) {
-        currentErrors = validate(currentValues) || {};
+  const handleSubmit = (fn) => async (e) => {
+    if (e && e.preventDefault) e.preventDefault();
+    touchedSig.value = markAllTouched(valuesSig.value);
+    notifySignals("t");
+    isSubmittingSig.value = true;
+    submitCountSig.value++;
+    await runValidation();
+    if (isValidSig.value) {
+      try {
+        await fn(valuesSig.value);
+        isSubmittedSig.value = true;
+      } finally {
+        isSubmittingSig.value = false;
       }
-      
-      errors.value = currentErrors;
-      
-      if (Object.keys(currentErrors).length === 0) {
-        onSubmit(currentValues);
-      }
-    };
-  }
+    } else {
+      isSubmittingSig.value = false;
+    }
+  };
 
-  function setValues(newValues) {
+  const reset = (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);
+      if (newValues !== undefined) initialValuesSig.value = clone(newValues);
+      valuesSig.value = clone(initialValuesSig.value);
+      errorsSig.value = {};
+      touchedSig.value = {};
+      changedSig.value = {};
+      isSubmittedSig.value = false;
+      notifySignals("v");
+      notifySignals("e");
+      notifySignals("t");
+      notifySignals("c");
     });
-  }
+  };
 
-  function array(path) {
-    return computed(() => values.value[path] || []);
-  }
+  const proxyCache = new Map();
 
-  return {
-    register,
-    handleSubmit,
-    setValues,
-    getValues: () => values.value,
-    array,
-    values: new Proxy({}, {
-      get: (_, key) => values.value[key],
-      set: (_, key, val) => {
-        setValues({ [key]: val });
+  function createDeepProxy(sig, path = [], defaultValue = undefined) {
+
+    const pathStr = path.join(".");
+    // Use signal identity in cache key to avoid collisions between values/errors/etc.
+    const sigKey = sig === valuesSig ? "v" : sig === errorsSig ? "e" : sig === touchedSig ? "t" : "c";
+    const cacheKey = `${sigKey}:${pathStr}:${defaultValue}`;
+    if (proxyCache.has(cacheKey)) return proxyCache.get(cacheKey);
+
+    const val = untracked(() => (path.length === 0 ? sig.value : get(sig.value, pathStr)));
+
+    const proxy = new Proxy(val || {}, {
+      get(_, prop) {
+        const latestVal = untracked(() => (path.length === 0 ? sig.value : get(sig.value, pathStr)));
+
+        if (prop === Symbol.toStringTag) {
+          return Array.isArray(latestVal) ? "Array" : "Object";
+        }
+        if (prop === "toJSON") {
+          return () => (path.length === 0 ? sig.value : get(sig.value, pathStr));
+        }
+        if (prop === Symbol.iterator) {
+          return latestVal[Symbol.iterator].bind(latestVal);
+        }
+        if (typeof prop === "symbol") return undefined;
+        if (["__proto__", "constructor", "prototype"].includes(prop)) return undefined;
+
+        const currentPathStr = pathStr ? `${pathStr}.${prop}` : prop;
+        const value = latestVal ? latestVal[prop] : undefined;
+
+        if (Array.isArray(latestVal) && ["push", "pop", "shift", "unshift", "splice", "reverse", "sort"].includes(prop)) {
+          return (...args) => {
+            const nextArr = [...latestVal];
+            const result = nextArr[prop](...args);
+            updateValue(pathStr, nextArr);
+            return result;
+          };
+        }
+
+        if (typeof value === "function") {
+          return value.bind(latestVal);
+        }
+
+        // Subscribe to path-specific signal
+        const subSig = getSignal(sigKey, currentPathStr, value ?? defaultValue);
+        if (!isSetup) subSig.value;
+
+        if (value && typeof value === "object") {
+          return createDeepProxy(sig, [...path, prop], defaultValue);
+        }
+
+        return value ?? defaultValue;
+      },
+      set(_, prop, val) {
+
+        const currentPathStr = [...path, prop].join(".");
+        if (sig === valuesSig) updateValue(currentPathStr, val);
+        else {
+          const newState = clone(sig.value);
+          set(newState, currentPathStr, val);
+          sig.value = newState;
+        }
         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;
+      ownKeys() {
+        const val = untracked(() => (path.length === 0 ? sig.value : get(sig.value, pathStr)));
+        if (!isSetup) {
+          const subSig = getSignal(sigKey, pathStr, val);
+          subSig.value;
+        }
+        const keys = Object.keys(val || {});
+        if (Array.isArray(val) && !keys.includes("length")) {
+          keys.push("length");
+        }
+        return keys;
+      },
+      getOwnPropertyDescriptor(_, prop) {
+        const latestVal = untracked(() => (path.length === 0 ? sig.value : get(sig.value, pathStr)));
+        if (latestVal && typeof latestVal === "object" && prop in latestVal) {
+          return Object.getOwnPropertyDescriptor(latestVal, prop);
+        }
+        return undefined;
       }
-    }),
-    errors,
-    touched: new Proxy({}, {
-      get: (_, key) => touched[key]
-    }),
-    fields // Also expose the raw signals map for advanced usage
+    });
+
+    proxyCache.set(cacheKey, proxy);
+    return proxy;
+  }
+
+  const form = {
+    register,
+    handleSubmit,
+    reset,
+    _updateConfig(newMode, newReValidateMode) {
+      batch(() => {
+        modeSig.value = newMode;
+        reValidateModeSig.value = newReValidateMode;
+      });
+    },
+    _notifySignals: notifySignals,
+    get values() { return createDeepProxy(valuesSig); },
+    get errors() { return createDeepProxy(errorsSig); },
+    get touched() { return createDeepProxy(touchedSig, [], false); },
+    get changed() { return createDeepProxy(changedSig, [], false); },
+    _signals: {
+      values: valuesSig,
+      errors: errorsSig,
+      touched: touchedSig,
+      changed: changedSig,
+      initialValues: initialValuesSig,
+    }
   };
+
+  const getSafe = (sig) => (isSetup ? untracked(() => sig.value) : sig.value);
+
+  Object.defineProperties(form, {
+    isValid: { get: () => getSafe(isValidSig), enumerable: true },
+    isChanged: { get: () => getSafe(isDirtySig), enumerable: true },
+    isTouched: { get: () => getSafe(isTouchedSig), enumerable: true },
+    isSubmitting: { get: () => getSafe(isSubmittingSig), enumerable: true },
+    isValidating: { get: () => getSafe(isValidatingSig), enumerable: true },
+    isSubmitted: { get: () => getSafe(isSubmittedSig), enumerable: true },
+    submitCount: { get: () => getSafe(submitCountSig), enumerable: true },
+  });
+
+  // Initial validation (only if onChange mode)
+  if (getMode() === "onChange") {
+    runValidation();
+  }
+
+  return form;
 }