@zoijs/forms 0.1.0 → 0.1.1

package/CHANGELOG.md

@@ -1,18 +1,31 @@
-# Changelog
-
-All notable changes to `@zoijs/forms` are documented here.
-
-## 0.1.0 — 2026-06-25
-
-Initial release of the tiny, native-forms-first helper for Zoijs.
-
-- `form(initialValues, options?)` returning reactive `values` / `errors` / `touched`
-  state plus per-field helpers: `value`, `set`, `error`, `setError`, `clearError`,
-  `touch`, and `reset`
-- `validate(rules?)` — a simple field → function rule map (no schemas, no deps),
-  with optional default rules via `options.validate`
-- `handleSubmit(fn)` — a thin wrapper that prevents the default reload and calls
-  `fn(values)`; the network call stays yours (use `@zoijs/action`)
-- Native-forms first: works with ordinary `<input>` / `<textarea>` and submission
-  via `@zoijs/action`
-- Built entirely on `@zoijs/core`'s public API — the core is unchanged
+# Changelog
+
+All notable changes to `@zoijs/forms` are documented here.
+
+## 0.1.1 — 2026-06-25
+
+Consistency hardening — **non-breaking, additive only.**
+
+- Added reader-style accessors that match the rest of the ecosystem
+  (`data()` / `loading()` / `value(name)` …): **`all()`** (all values),
+  **`allErrors()`** (all errors), **`allTouched()`** (all touched flags), and
+  **`isTouched(name)`** (one field's touched flag). All reactive inside a binding.
+- The raw reactive state `values` / `errors` / `touched` is **kept** for backward
+  compatibility (now documented as advanced/direct access). No existing code breaks.
+- Docs and the login example updated to prefer the reader methods.
+- No behavior changes, no new form features, no core changes.
+
+## 0.1.0 — 2026-06-25
+
+Initial release of the tiny, native-forms-first helper for Zoijs.
+
+- `form(initialValues, options?)` returning reactive `values` / `errors` / `touched`
+  state plus per-field helpers: `value`, `set`, `error`, `setError`, `clearError`,
+  `touch`, and `reset`
+- `validate(rules?)` — a simple field → function rule map (no schemas, no deps),
+  with optional default rules via `options.validate`
+- `handleSubmit(fn)` — a thin wrapper that prevents the default reload and calls
+  `fn(values)`; the network call stays yours (use `@zoijs/action`)
+- Native-forms first: works with ordinary `<input>` / `<textarea>` and submission
+  via `@zoijs/action`
+- Built entirely on `@zoijs/core`'s public API — the core is unchanged

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 Zoijs contributors
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 Zoijs contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,178 +1,192 @@
-<div align="center">
-
-# @zoijs/forms
-
-**A tiny, native-forms-first helper for [Zoijs](https://zoijs.com).** Reactive values, errors, and touched state — without a form framework.
-
-[![npm](https://img.shields.io/npm/v/@zoijs/forms.svg)](https://www.npmjs.com/package/@zoijs/forms)
-[![license](https://img.shields.io/npm/l/@zoijs/forms.svg)](LICENSE)
-
-[Website](https://zoijs.com) · [Documentation](https://zoijs.dev) · [Core package](https://www.npmjs.com/package/@zoijs/core)
-
-</div>
-
----
-
-`@zoijs/forms` is an **optional** package. Add it when a form needs a little
-structure — tracking values, errors, and which fields have been touched. You
-still write ordinary `<input>`s, and you still submit with
-[`@zoijs/action`](https://www.npmjs.com/package/@zoijs/action). Forms never
-touches the network.
-
-You can learn the whole thing in about 5 minutes.
-
-## Install
-
-```bash
-npm install @zoijs/core @zoijs/forms
-```
-
-Or with no install, from a CDN:
-
-```js
-import { form } from "https://esm.sh/@zoijs/forms";
-```
-
-## What `form()` does
-
-`form(initialValues, options?)` keeps your form's **values**, **errors**, and
-**touched** state in Zoijs reactive state, with small per-field helpers:
-
-```js
-import { form } from "@zoijs/forms";
-
-const login = form({ email: "", password: "" });
-
-login.values.get();                 // { email: "", password: "" }
-login.value("email");               // one field (reactive)
-login.set("email", "a@b.com");      // update one field
-login.error("email");               // one field's error (reactive)
-login.setError("email", "Required");
-login.clearError("email");
-login.touch("email");               // mark touched (e.g. on blur)
-login.reset();                      // restore initial values, clear errors + touched
-```
-
-## The API
-
-| Member | What it does |
-|---|---|
-| `form(initialValues, options?)` | Create a form helper |
-| `values` | Reactive state of all values — `values.get()` returns the object |
-| `value(name)` | Read one field's value (reactive) |
-| `set(name, value)` | Update one field |
-| `errors` | Reactive state of all errors |
-| `error(name)` | Read one field's error (reactive) |
-| `setError(name, message)` | Set one field's error |
-| `clearError(name)` | Clear one field's error |
-| `touched` | Reactive state of touched fields |
-| `touch(name)` | Mark a field touched |
-| `reset()` | Restore initial values; clear errors + touched |
-| `validate(rules?)` | Run rules, set errors, return whether valid |
-| `handleSubmit(fn)` | Wrap a submit handler: prevents reload, calls `fn(values)` |
-
-## Login form example
-
-Use native inputs — `value` reads from the form, `oninput` writes back, `onblur`
-marks touched:
-
-```js
-import { html, mount } from "@zoijs/core";
-import { form } from "@zoijs/forms";
-
-const login = form({ email: "", password: "" });
-
-function App() {
-  return html`
-    <input
-      name="email"
-      value=${() => login.value("email")}
-      oninput=${(e) => login.set("email", e.target.value)}
-      onblur=${() => login.touch("email")}
-    />
-    ${() => (login.error("email") ? html`<span class="err">${login.error("email")}</span>` : null)}
-  `;
-}
-
-mount(App, "#app");
-```
-
-See [`examples/login/`](examples/login/).
-
-## Contact form example
-
-A contact form with a textarea, default rules via `options.validate`, and
-`handleSubmit`. See [`examples/contact/`](examples/contact/).
-
-## Validation
-
-Validation is just a map of field → function. A rule returns a message when
-invalid, or a falsy value when valid. No schemas, no dependencies.
-
-```js
-const valid = login.validate({
-  email: (value) => (value.includes("@") ? null : "Enter a valid email"),
-  password: (value) => (value.length >= 8 ? null : "Minimum 8 characters"),
-});
-// valid === false, and login.error("email") is now set
-```
-
-You can also pass the rules once via options and call `validate()` with no args:
-
-```js
-const login = form({ email: "", password: "" }, {
-  validate: { email: (v) => (v.includes("@") ? null : "Enter a valid email") },
-});
-login.validate();
-```
-
-## Using it with `@zoijs/action`
-
-Forms holds state; **`@zoijs/action` does the request.** Validate, then submit:
-
-```js
-import { action } from "@zoijs/action";
-
-const submitLogin = action(async (values) => {
-  await api.login(values);
-});
-
-html`
-  <form onsubmit=${async (e) => {
-    e.preventDefault();
-    if (!login.validate(rules)) return;
-    await submitLogin.run(login.values.get());
-  }}>
-    ...
-    <button disabled=${() => submitLogin.pending()}>Sign in</button>
-  </form>
-`;
-```
-
-`handleSubmit` is a thin convenience that prevents the default reload for you:
-
-```js
-const onSubmit = login.handleSubmit((values) => submitLogin.run(values));
-html`<form onsubmit=${onSubmit}>...</form>`;
-```
-
-## Common mistakes
-
-- **Reading outside a binding.** Wrap reads in an arrow to make them live:
-  `value=${() => login.value("email")}`, not `value=${login.value("email")}`.
-- **Expecting forms to submit for you.** It doesn't — pair it with `@zoijs/action`.
-- **Expecting auto-validation.** `set()` only updates the value. Call `validate()`
-  (on submit or blur) when you want errors; `clearError()` to remove one.
-- **Reaching for field arrays / nested objects.** Keep values flat. For complex,
-  dynamic shapes, manage your own reactive state with `createState`.
-
-## What this package intentionally does *not* do
-
-By design, to stay tiny: no form provider/context, no field registration, no
-field arrays, no schema validation, no resolver system, no async-validation
-engine, no controlled-component framework, and no third-party validation
-dependency. It's the 90%-case helper — native forms, plus a little structure.
-
-## License
-
-[MIT](LICENSE) © Zoijs contributors
+<div align="center">
+
+# @zoijs/forms
+
+**A tiny, native-forms-first helper for [Zoijs](https://zoijs.dev).** Reactive values, errors, and touched state — without a form framework.
+
+[![npm](https://img.shields.io/npm/v/@zoijs/forms.svg)](https://www.npmjs.com/package/@zoijs/forms)
+[![license](https://img.shields.io/npm/l/@zoijs/forms.svg)](LICENSE)
+
+[Documentation](https://zoijs.dev) · [Core package](https://www.npmjs.com/package/@zoijs/core)
+
+</div>
+
+---
+
+`@zoijs/forms` is an **optional** package. Add it when a form needs a little
+structure — tracking values, errors, and which fields have been touched. You
+still write ordinary `<input>`s, and you still submit with
+[`@zoijs/action`](https://www.npmjs.com/package/@zoijs/action). Forms never
+touches the network.
+
+You can learn the whole thing in about 5 minutes.
+
+## Install
+
+```bash
+npm install @zoijs/core @zoijs/forms
+```
+
+Or with no install, from a CDN:
+
+```js
+import { form } from "https://esm.sh/@zoijs/forms@0.1";
+```
+
+## What `form()` does
+
+`form(initialValues, options?)` keeps your form's **values**, **errors**, and
+**touched** state in Zoijs reactive state, with small per-field helpers:
+
+```js
+import { form } from "@zoijs/forms";
+
+const login = form({ email: "", password: "" });
+
+login.all();                        // { email: "", password: "" } — all values (reactive)
+login.value("email");               // one field (reactive)
+login.set("email", "a@b.com");      // update one field
+login.error("email");               // one field's error (reactive)
+login.setError("email", "Required");
+login.clearError("email");
+login.isTouched("email");           // has this field been touched? (reactive)
+login.touch("email");               // mark touched (e.g. on blur)
+login.reset();                      // restore initial values, clear errors + touched
+```
+
+These reader methods (`all()`, `value()`, `error()`, `isTouched()`, …) match the
+rest of the ecosystem — the same shape as `data()`, `loading()`, and `pending()` —
+so once you've learned one Zoijs package, the others read the same way.
+
+## The API
+
+| Member | What it does |
+|---|---|
+| `form(initialValues, options?)` | Create a form helper |
+| `all()` | Read all values (reactive) |
+| `value(name)` | Read one field's value (reactive) |
+| `set(name, value)` | Update one field |
+| `allErrors()` | Read all errors (reactive) |
+| `error(name)` | Read one field's error (reactive) |
+| `setError(name, message)` | Set one field's error |
+| `clearError(name)` | Clear one field's error |
+| `allTouched()` | Read all touched flags (reactive) |
+| `isTouched(name)` | Has one field been touched? (reactive) |
+| `touch(name)` | Mark a field touched |
+| `reset()` | Restore initial values; clear errors + touched |
+| `validate(rules?)` | Run rules, set errors, return whether valid |
+| `handleSubmit(fn)` | Wrap a submit handler: prevents reload, calls `fn(values)` |
+
+### Advanced: raw state access
+
+The underlying reactive state is also exposed as `values`, `errors`, and `touched`
+(each a `createState`-shaped `{ get, set, peek }`). Prefer the reader methods above;
+reach for the raw state only when you need direct access — e.g. `login.values.peek()`
+to read without subscribing. These remain for backward compatibility and won't be
+removed in 0.x.
+
+## Login form example
+
+Use native inputs — `value` reads from the form, `oninput` writes back, `onblur`
+marks touched:
+
+```js
+import { html, mount } from "@zoijs/core";
+import { form } from "@zoijs/forms";
+
+const login = form({ email: "", password: "" });
+
+function App() {
+  return html`
+    <input
+      name="email"
+      value=${() => login.value("email")}
+      oninput=${(e) => login.set("email", e.target.value)}
+      onblur=${() => login.touch("email")}
+    />
+    ${() => (login.error("email") ? html`<span class="err">${login.error("email")}</span>` : null)}
+  `;
+}
+
+mount(App, "#app");
+```
+
+See [`examples/login/`](examples/login/).
+
+## Contact form example
+
+A contact form with a textarea, default rules via `options.validate`, and
+`handleSubmit`. See [`examples/contact/`](examples/contact/).
+
+## Validation
+
+Validation is just a map of field → function. A rule returns a message when
+invalid, or a falsy value when valid. No schemas, no dependencies.
+
+```js
+const valid = login.validate({
+  email: (value) => (value.includes("@") ? null : "Enter a valid email"),
+  password: (value) => (value.length >= 8 ? null : "Minimum 8 characters"),
+});
+// valid === false, and login.error("email") is now set
+```
+
+You can also pass the rules once via options and call `validate()` with no args:
+
+```js
+const login = form({ email: "", password: "" }, {
+  validate: { email: (v) => (v.includes("@") ? null : "Enter a valid email") },
+});
+login.validate();
+```
+
+## Using it with `@zoijs/action`
+
+Forms holds state; **`@zoijs/action` does the request.** Validate, then submit:
+
+```js
+import { action } from "@zoijs/action";
+
+const submitLogin = action(async (values) => {
+  await api.login(values);
+});
+
+html`
+  <form onsubmit=${async (e) => {
+    e.preventDefault();
+    if (!login.validate(rules)) return;
+    await submitLogin.run(login.all());
+  }}>
+    ...
+    <button disabled=${() => submitLogin.pending()}>Sign in</button>
+  </form>
+`;
+```
+
+`handleSubmit` is a thin convenience that prevents the default reload for you:
+
+```js
+const onSubmit = login.handleSubmit((values) => submitLogin.run(values));
+html`<form onsubmit=${onSubmit}>...</form>`;
+```
+
+## Common mistakes
+
+- **Reading outside a binding.** Wrap reads in an arrow to make them live:
+  `value=${() => login.value("email")}`, not `value=${login.value("email")}`.
+- **Expecting forms to submit for you.** It doesn't — pair it with `@zoijs/action`.
+- **Expecting auto-validation.** `set()` only updates the value. Call `validate()`
+  (on submit or blur) when you want errors; `clearError()` to remove one.
+- **Reaching for field arrays / nested objects.** Keep values flat. For complex,
+  dynamic shapes, manage your own reactive state with `createState`.
+
+## What this package intentionally does *not* do
+
+By design, to stay tiny: no form provider/context, no field registration, no
+field arrays, no schema validation, no resolver system, no async-validation
+engine, no controlled-component framework, and no third-party validation
+dependency. It's the 90%-case helper — native forms, plus a little structure.
+
+## License
+
+[MIT](LICENSE) © Zoijs contributors

package/package.json

@@ -1,61 +1,61 @@
-{
-  "name": "@zoijs/forms",
-  "version": "0.1.0",
-  "description": "A tiny, native-forms-first helper for Zoijs: reactive values, errors, and touched state. No JSX, no build step.",
-  "type": "module",
-  "main": "src/index.js",
-  "types": "src/index.d.ts",
-  "exports": {
-    ".": {
-      "types": "./src/index.d.ts",
-      "default": "./src/index.js"
-    }
-  },
-  "files": [
-    "src",
-    "README.md",
-    "LICENSE",
-    "CHANGELOG.md"
-  ],
-  "sideEffects": false,
-  "engines": {
-    "node": ">=18"
-  },
-  "author": "Zoijs contributors (https://zoijs.com)",
-  "license": "MIT",
-  "homepage": "https://zoijs.com",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/Zoijs/zoijs.git",
-    "directory": "forms"
-  },
-  "bugs": {
-    "url": "https://github.com/Zoijs/zoijs/issues"
-  },
-  "keywords": [
-    "zoijs",
-    "forms",
-    "form",
-    "validation",
-    "fields",
-    "reactive",
-    "no-build",
-    "no-jsx"
-  ],
-  "peerDependencies": {
-    "@zoijs/core": "^1.0.0"
-  },
-  "scripts": {
-    "test": "node --test --import ./tests/setup-dom.js",
-    "test:types": "tsc --noEmit -p tsconfig.json",
-    "test:browser": "playwright test",
-    "dev": "npx serve -l 3700 .."
-  },
-  "devDependencies": {
-    "@playwright/test": "^1.61.1",
-    "@zoijs/action": "file:../action",
-    "@zoijs/core": "file:../framework",
-    "jsdom": "^29.1.1",
-    "typescript": "^5.9.3"
-  }
-}
+{
+  "name": "@zoijs/forms",
+  "version": "0.1.1",
+  "description": "A tiny, native-forms-first helper for Zoijs: reactive values, errors, and touched state. No JSX, no build step.",
+  "type": "module",
+  "main": "src/index.js",
+  "types": "src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "default": "./src/index.js"
+    }
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=18"
+  },
+  "author": "Zoijs contributors (https://zoijs.dev)",
+  "license": "MIT",
+  "homepage": "https://zoijs.dev",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Zoijs/zoijs.git",
+    "directory": "forms"
+  },
+  "bugs": {
+    "url": "https://github.com/Zoijs/zoijs/issues"
+  },
+  "keywords": [
+    "zoijs",
+    "forms",
+    "form",
+    "validation",
+    "fields",
+    "reactive",
+    "no-build",
+    "no-jsx"
+  ],
+  "peerDependencies": {
+    "@zoijs/core": "^1.0.0"
+  },
+  "scripts": {
+    "test": "node --test --import ./tests/setup-dom.js",
+    "test:types": "tsc --noEmit -p tsconfig.json",
+    "test:browser": "playwright test",
+    "dev": "npx serve -l 3700 .."
+  },
+  "devDependencies": {
+    "@playwright/test": "^1.61.1",
+    "@zoijs/action": "file:../action",
+    "@zoijs/core": "file:../framework",
+    "jsdom": "^29.1.1",
+    "typescript": "^5.9.3"
+  }
+}

package/src/index.d.ts

@@ -1,70 +1,89 @@
-// Type definitions for @zoijs/forms.
-//
-// Authored in plain JavaScript; these declarations add editor autocomplete and
-// optional type-checking without requiring TypeScript.
-
-/** A reactive value (same shape as core's createState). */
-export interface State<T> {
-  get(): T;
-  set(value: T): void;
-  peek(): T;
-}
-
-/** A single field rule: return a message when invalid, or a falsy value when valid. */
-export type Rule<V = any, Values = Record<string, any>> = (
-  value: V,
-  values: Values
-) => string | null | undefined | false;
-
-/** A map of field name → rule. */
-export type Rules<V> = { [K in keyof V]?: Rule<V[K], V> };
-
-/** Options for {@link form}. */
-export interface FormOptions<V> {
-  /** Default rules used by `validate()` and when no rules are passed. */
-  validate?: Rules<V>;
-}
-
-/** A tiny reactive form helper created by {@link form}. */
-export interface Form<V extends Record<string, any>> {
-  /** All values (reactive). `values.get()` returns the whole object. */
-  values: State<V>;
-  /** Read one field's value (reactive). */
-  value<K extends keyof V>(name: K): V[K];
-  /** Update one field's value. */
-  set<K extends keyof V>(name: K, value: V[K]): void;
-  /** All errors keyed by field name (reactive). */
-  errors: State<Partial<Record<keyof V, string>>>;
-  /** Read one field's error (reactive), or `undefined`. */
-  error(name: keyof V): string | undefined;
-  /** Set one field's error message. */
-  setError(name: keyof V, message: string): void;
-  /** Clear one field's error. */
-  clearError(name: keyof V): void;
-  /** Which fields have been touched (reactive). */
-  touched: State<Partial<Record<keyof V, boolean>>>;
-  /** Mark a field touched (e.g. on blur). */
-  touch(name: keyof V): void;
-  /** Restore initial values and clear errors + touched. */
-  reset(): void;
-  /** Run rules (or the option rules), set errors, and return whether valid. */
-  validate(rules?: Rules<V>): boolean;
-  /** Wrap a submit handler: prevents the default reload and calls `fn(values)`. */
-  handleSubmit(fn: (values: V, event?: Event) => unknown): (event?: Event) => unknown;
-}
-
-/**
- * Create a tiny reactive form helper. Native-forms first: you write ordinary
- * `<input>`s and submit with `@zoijs/action` — forms only holds values, errors,
- * and touched state.
- *
- * ```ts
- * const login = form({ email: "", password: "" });
- * login.value("email");          // string
- * login.set("email", "a@b.com");
- * login.error("email");          // string | undefined
- * login.touch("email");
- * login.reset();
- * ```
- */
-export function form<V extends Record<string, any>>(initialValues: V, options?: FormOptions<V>): Form<V>;
+// Type definitions for @zoijs/forms.
+//
+// Authored in plain JavaScript; these declarations add editor autocomplete and
+// optional type-checking without requiring TypeScript.
+
+/** A reactive value (same shape as core's createState). */
+export interface State<T> {
+  get(): T;
+  set(value: T): void;
+  peek(): T;
+}
+
+/** A single field rule: return a message when invalid, or a falsy value when valid. */
+export type Rule<V = any, Values = Record<string, any>> = (
+  value: V,
+  values: Values
+) => string | null | undefined | false;
+
+/** A map of field name → rule. */
+export type Rules<V> = { [K in keyof V]?: Rule<V[K], V> };
+
+/** Options for {@link form}. */
+export interface FormOptions<V> {
+  /** Default rules used by `validate()` and when no rules are passed. */
+  validate?: Rules<V>;
+}
+
+/** A tiny reactive form helper created by {@link form}. */
+export interface Form<V extends Record<string, any>> {
+  // --- values ---
+  /** All values (reactive). Reader-style, like `data()` / `loading()`. */
+  all(): V;
+  /** Read one field's value (reactive). */
+  value<K extends keyof V>(name: K): V[K];
+  /** Update one field's value. */
+  set<K extends keyof V>(name: K, value: V[K]): void;
+
+  // --- errors ---
+  /** All errors keyed by field name (reactive). */
+  allErrors(): Partial<Record<keyof V, string>>;
+  /** Read one field's error (reactive), or `undefined`. */
+  error(name: keyof V): string | undefined;
+  /** Set one field's error message. */
+  setError(name: keyof V, message: string): void;
+  /** Clear one field's error. */
+  clearError(name: keyof V): void;
+
+  // --- touched ---
+  /** All touched flags keyed by field name (reactive). */
+  allTouched(): Partial<Record<keyof V, boolean>>;
+  /** Whether one field has been touched (reactive). */
+  isTouched(name: keyof V): boolean;
+  /** Mark a field touched (e.g. on blur). */
+  touch(name: keyof V): void;
+
+  // --- lifecycle ---
+  /** Restore initial values and clear errors + touched. */
+  reset(): void;
+  /** Run rules (or the option rules), set errors, and return whether valid. */
+  validate(rules?: Rules<V>): boolean;
+  /** Wrap a submit handler: prevents the default reload and calls `fn(values)`. */
+  handleSubmit(fn: (values: V, event?: Event) => unknown): (event?: Event) => unknown;
+
+  // --- raw reactive state (advanced / backward-compatible) ---
+  // Prefer all() / allErrors() / allTouched() above. These remain for direct
+  // state access (e.g. `values.peek()`), and won't be removed in 0.x.
+  /** Raw values state. Advanced — prefer {@link Form.all}. */
+  values: State<V>;
+  /** Raw errors state. Advanced — prefer {@link Form.allErrors}. */
+  errors: State<Partial<Record<keyof V, string>>>;
+  /** Raw touched state. Advanced — prefer {@link Form.allTouched}. */
+  touched: State<Partial<Record<keyof V, boolean>>>;
+}
+
+/**
+ * Create a tiny reactive form helper. Native-forms first: you write ordinary
+ * `<input>`s and submit with `@zoijs/action` — forms only holds values, errors,
+ * and touched state.
+ *
+ * ```ts
+ * const login = form({ email: "", password: "" });
+ * login.value("email");          // string
+ * login.set("email", "a@b.com");
+ * login.error("email");          // string | undefined
+ * login.touch("email");
+ * login.reset();
+ * ```
+ */
+export function form<V extends Record<string, any>>(initialValues: V, options?: FormOptions<V>): Form<V>;

package/src/index.js

@@ -1,105 +1,122 @@
-// @zoijs/forms — a tiny, optional form helper for Zoijs.
-//
-// form(initialValues, options?) keeps a form's values, errors, and touched state
-// in plain Zoijs reactive state, with small per-field helpers. It is native-forms
-// first: you still write ordinary <input>s and read e.target.value yourself, and
-// you still submit with @zoijs/action — forms never touches the network.
-//
-//   import { form } from "@zoijs/forms";
-//
-//   const login = form({ email: "", password: "" });
-//   login.value("email");               // read one field (reactive)
-//   login.set("email", "a@b.com");      // update one field
-//   login.error("email");               // read one field's error (reactive)
-//   login.setError("email", "Required"); login.clearError("email");
-//   login.touch("email");               // mark touched (e.g. on blur)
-//   login.reset();                      // restore initial values, clear errors+touched
-//
-// No provider, no field registration, no context, no schema, no resolver, no
-// async-validation engine. Built entirely on the core's public API (createState)
-// — the core is unchanged.
-
-import { createState } from "@zoijs/core";
-
-/**
- * Create a tiny reactive form helper.
- * @param {Record<string, any>} initialValues
- * @param {{ validate?: Record<string, (value:any, values:any)=>(string|null|undefined)> }} [options]
- */
-export function form(initialValues = {}, options = {}) {
-  const initial = { ...initialValues };
-  const values = createState({ ...initial });
-  const errors = createState({});
-  const touched = createState({});
-
-  const value = (name) => values.get()[name];
-
-  const set = (name, val) => {
-    values.set({ ...values.get(), [name]: val });
-  };
-
-  const error = (name) => errors.get()[name];
-
-  const setError = (name, message) => {
-    errors.set({ ...errors.get(), [name]: message });
-  };
-
-  const clearError = (name) => {
-    const next = { ...errors.get() };
-    delete next[name];
-    errors.set(next);
-  };
-
-  const touch = (name) => {
-    if (touched.get()[name]) return; // already touched — no needless update
-    touched.set({ ...touched.get(), [name]: true });
-  };
-
-  const reset = () => {
-    values.set({ ...initial });
-    errors.set({});
-    touched.set({});
-  };
-
-  // Run each rule against its field's current value. A rule returns a message
-  // string when invalid, or a falsy value when valid. Sets errors and returns
-  // whether the whole form is valid. Rules default to options.validate.
-  const validate = (rules) => {
-    const useRules = rules || options.validate || {};
-    const vals = values.get();
-    const next = {};
-    let valid = true;
-    for (const name in useRules) {
-      const message = useRules[name](vals[name], vals);
-      if (message) {
-        next[name] = message;
-        valid = false;
-      }
-    }
-    errors.set(next);
-    return valid;
-  };
-
-  // A thin submit wrapper: prevent the default page reload and call fn with the
-  // current values. Validation and the network call stay yours (use validate()
-  // and @zoijs/action) — forms never submits anything itself.
-  const handleSubmit = (fn) => (event) => {
-    if (event && typeof event.preventDefault === "function") event.preventDefault();
-    return fn(values.get(), event);
-  };
-
-  return {
-    values,
-    value,
-    set,
-    errors,
-    error,
-    setError,
-    clearError,
-    touched,
-    touch,
-    reset,
-    validate,
-    handleSubmit,
-  };
-}
+// @zoijs/forms — a tiny, optional form helper for Zoijs.
+//
+// form(initialValues, options?) keeps a form's values, errors, and touched state
+// in plain Zoijs reactive state, with small per-field helpers. It is native-forms
+// first: you still write ordinary <input>s and read e.target.value yourself, and
+// you still submit with @zoijs/action — forms never touches the network.
+//
+//   import { form } from "@zoijs/forms";
+//
+//   const login = form({ email: "", password: "" });
+//   login.value("email");               // read one field (reactive)
+//   login.set("email", "a@b.com");      // update one field
+//   login.error("email");               // read one field's error (reactive)
+//   login.setError("email", "Required"); login.clearError("email");
+//   login.touch("email");               // mark touched (e.g. on blur)
+//   login.reset();                      // restore initial values, clear errors+touched
+//
+// No provider, no field registration, no context, no schema, no resolver, no
+// async-validation engine. Built entirely on the core's public API (createState)
+// — the core is unchanged.
+
+import { createState } from "@zoijs/core";
+
+/**
+ * Create a tiny reactive form helper.
+ * @param {Record<string, any>} initialValues
+ * @param {{ validate?: Record<string, (value:any, values:any)=>(string|null|undefined)> }} [options]
+ */
+export function form(initialValues = {}, options = {}) {
+  const initial = { ...initialValues };
+  const values = createState({ ...initial });
+  const errors = createState({});
+  const touched = createState({});
+
+  const value = (name) => values.get()[name];
+
+  const set = (name, val) => {
+    values.set({ ...values.get(), [name]: val });
+  };
+
+  const error = (name) => errors.get()[name];
+
+  const setError = (name, message) => {
+    errors.set({ ...errors.get(), [name]: message });
+  };
+
+  const clearError = (name) => {
+    const next = { ...errors.get() };
+    delete next[name];
+    errors.set(next);
+  };
+
+  const touch = (name) => {
+    if (touched.get()[name]) return; // already touched — no needless update
+    touched.set({ ...touched.get(), [name]: true });
+  };
+
+  const reset = () => {
+    values.set({ ...initial });
+    errors.set({});
+    touched.set({});
+  };
+
+  // Run each rule against its field's current value. A rule returns a message
+  // string when invalid, or a falsy value when valid. Sets errors and returns
+  // whether the whole form is valid. Rules default to options.validate.
+  const validate = (rules) => {
+    const useRules = rules || options.validate || {};
+    const vals = values.get();
+    const next = {};
+    let valid = true;
+    for (const name in useRules) {
+      const message = useRules[name](vals[name], vals);
+      if (message) {
+        next[name] = message;
+        valid = false;
+      }
+    }
+    errors.set(next);
+    return valid;
+  };
+
+  // A thin submit wrapper: prevent the default page reload and call fn with the
+  // current values. Validation and the network call stay yours (use validate()
+  // and @zoijs/action) — forms never submits anything itself.
+  const handleSubmit = (fn) => (event) => {
+    if (event && typeof event.preventDefault === "function") event.preventDefault();
+    return fn(values.get(), event);
+  };
+
+  // Reader-style accessors for whole-form state, matching the rest of the
+  // ecosystem (data(), loading(), value(name), …). Reactive inside a binding.
+  const all = () => values.get();
+  const allErrors = () => errors.get();
+  const allTouched = () => touched.get();
+  const isTouched = (name) => !!touched.get()[name];
+
+  return {
+    // values
+    all,
+    value,
+    set,
+    // errors
+    allErrors,
+    error,
+    setError,
+    clearError,
+    // touched
+    allTouched,
+    isTouched,
+    touch,
+    // lifecycle
+    reset,
+    validate,
+    handleSubmit,
+    // raw reactive state — advanced / backward-compatible. Prefer all() /
+    // allErrors() / allTouched() above; these stay for direct state access.
+    values,
+    errors,
+    touched,
+  };
+}