formAtom

Reactive form field — Atom plus sync validation, dirty/errors, and numeric helpers.

import { formAtom, isRequired, isEmail, minLength } from "mates";

// validators: ValidatorFn[] or () => ValidatorFn[] (re-read every check)
const email = formAtom("", [isRequired(), isEmail()]);
const name = formAtom("", () => [isRequired(), minLength(2)]);

email();                 // reactive read (preferred)
email.get(); email.val;  // same

email.set("ada@ex.com"); // dirty + sync validate → .errors
email.errors;            // string[]
email.isValid;           // live boolean — does NOT write .errors
email.dirty;             // true after non-silent set or validate()
email.validate();        // force-run; marks dirty; returns string[]
email.resetValidation(); // clear errors + dirty (value unchanged)

// Numeric helpers (parse current value; never NaN/Infinity)
email.toFloat();         // number (2 dp)
email.toFloatString();   // string
email.toValidNumber();   // finite number or 0

// Sync only — a Promise-returning validator throws

Overview

formAtom(initial, validators?) extends atom with sync validation. Validators are a ValidatorFn[] or a factory () => ValidatorFn[] re-read on every check (so rules can close over other fields).

.errors stays [] until the field is dirty or you call validate(). .isValid is a live getter that re-runs validators without writing .errors or marking dirty.

Async validators are not supported — a Promise-returning rule throws. Use schema / validateObject for I/O checks.

formAtom vs atom vs schema

API	Role	Prefer when
`formAtom`	Field + sync validate	Inputs with inline errors
`atom`	Plain reactive cell	No built-in validation
`schema`	Plain snapshot	Submit / server; async OK

Bind inputs to formAtom

set() marks dirty and runs sync validators. Show errors when dirty.

import { html, formAtom, isRequired, isEmail, minLength, renderApp } from "mates";

const App = () => {

const name = formAtom("", [isRequired(), minLength(2)]);

const email = formAtom("", [isRequired(), isEmail()]);

const hint = (fa) =>

fa.dirty && fa.errors[0]

? html`<span class="tag tag-danger">${fa.errors[0]}</span>`

: "";

return () => html`

Name

<input .value=${name()} @input=${(e) => name.set(e.target.value)} />

${hint(name)}

</label>

<input .value=${email()} @input=${(e) => email.set(e.target.value)} />

${hint(email)}

</label>

both valid ${name.isValid && email.isValid}

</span>

</div>

};

renderApp(App, document.getElementById("app"));

errors, isValid, dirty, reset

isValid re-runs without writing errors. validate() marks dirty. resetValidation() clears both.

import { html, formAtom, isRequired, minLength, renderApp } from "mates";

const App = () => {

const name = formAtom("", [isRequired(), minLength(3)]);

return () => html`

<p class="muted m-t-5">Pristine required: errors=[] but isValid is live false.</p>

Name

<input .value=${name()} @input=${(e) => name.set(e.target.value)} />

</label>

<span class="tag">value "${name()}"</span>

isValid ${name.isValid}

</span>

<span class="tag">dirty ${name.dirty}</span>

<span class="tag">errors ${JSON.stringify(name.errors)}</span>

</div>

<button @click=${() => name.validate()}>validate()</button>

<button @click=${() => name.resetValidation()}>resetValidation()</button>

</div>

};

renderApp(App, document.getElementById("app"));

Cross-field — factory validators

Pass () => [...] so confirm can read password() on every check. isEqualTo takes a getter.

import { html, formAtom, validateAll, isRequired, isEqualTo, minLength, renderApp } from "mates";

const App = () => {

const password = formAtom("", [isRequired(), minLength(8)]);

// Factory list so confirm can close over password() on every check

const confirm = formAtom("", () => [

isRequired(),

isEqualTo(() => password(), "Must match password"),

]);

const msg = formAtom("");

const hint = (fa) =>

fa.dirty && fa.errors[0]

? html`<span class="tag tag-danger">${fa.errors[0]}</span>`

: "";

return () => html`

Password

<input type="password" .value=${password()} @input=${(e) => password.set(e.target.value)} />

${hint(password)}

</label>

Confirm

<input type="password" .value=${confirm()} @input=${(e) => confirm.set(e.target.value)} />

${hint(confirm)}

</label>

<button class="btn-primary" @click=${() => {

const { isValid } = validateAll({ password, confirm });

msg.set(isValid ? "Passwords match" : "Fix the fields");

}}>Submit</button>

${msg() ? html`<span class="tag">${msg()}</span>` : ""}

</div>

};

Numeric helpers

toFloat, toFloatString, and toValidNumber parse without changing the atom.

import { html, formAtom, isMin, renderApp } from "mates";

const App = () => {

const price = formAtom("19.999", [isMin(0)]);

return () => html`

Price (string in the atom)

<input .value=${price()} @input=${(e) => price.set(e.target.value)} />

</label>

<span class="tag">toFloat() ${price.toFloat()}</span>

<span class="tag">toFloatString() ${price.toFloatString()}</span>

<span class="tag">toValidNumber() ${price.toValidNumber()}</span>

</div>

};

renderApp(App, document.getElementById("app"));

API — formAtom

import { formAtom, isFormAtom, isFormValid, validateAll } from 'mates'

Prop / Option	Type	Default	Description
`formAtom(initial, validators?, config?)`	`FormAtom`	—	Create a FormAtom. validators is ValidatorFn[] \| () => ValidatorFn[] (default []). Optional AtomConfig. Literals widen ("" → string).
`field()`	`T`	—	Reactive read — same as .get() / .val.
`field.set(v \| updater, silently?)`	`void`	—	Write like atom. Non-silent writes mark dirty and run sync validators into .errors. Silent skips dirty/validate.
`field.update(fn, silently?)`	`void`	—	In-place mutation for objects/arrays (same as atom.update).
`field.errors`	`string[]`	—	Last written error list. Empty until dirty or validate().
`field.isValid`	`boolean`	—	Live validity — re-runs validators; does not write .errors or mark dirty.
`field.dirty`	`boolean`	—	True after first non-silent write or validate().
`field.validate()`	`string[]`	—	Mark dirty, run validators, write .errors, return them.
`field.resetValidation()`	`void`	—	Clear .errors and dirty; value unchanged.
`field.toFloat()`	`number`	—	Parse value as float rounded to 2 dp; unparseable → 0.
`field.toFloatString()`	`string`	—	toFloat then string.
`field.toValidNumber()`	`number`	—	Finite number or 0 (never NaN/Infinity).
`field.__isFormAtom__`	`true`	—	Brand for isFormAtom / walks.
`isFormAtom(value)`	`value is FormAtom`	—	Type guard for FormAtom instances.
`isFormValid(mol)`	`boolean`	—	molecule.every over nested FormAtoms' .isValid. Does not aggregate .errors.
`validateAll(shape)`	`ValidateAllResult`	—	Walk object/array, call .validate() on every FormAtom. Returns { isValid, errors, errorsByField }.