@xoong/forms 0.0.0-stage → 0.0.35

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Duong Tran Xuan
+
+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,3 +1,30 @@
-# Temporary Holding Version
+# @xoong/forms
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Forms for xoong: a draft model with per-field state, validation from the OpenAPI request schema, your own rules, payload normalisation and dirty tracking, bound to plain `<form xo-submit>` markup.
+
+## Install
+
+```bash
+npm install @xoong/forms
+```
+
+## Use
+
+```html
+<xo-view get="getPerson" p-id="1">
+  <form xo-submit="updatePerson">
+    <input name="name"> <input name="email" type="email">
+    <button>Save</button>
+  </form>
+</xo-view>
+```
+Importing `@xoong/ui` (or `@xoong/forms` itself) turns every `<form xo-submit>` into a form with a model: `form.model`, `$form.dirty`, server errors by field.
+
+## More
+
+* Documentation and demos: https://github.com/fpt-duongtx/xoong#readme
+* Source: https://github.com/fpt-duongtx/xoong/tree/main/packages/forms
+* All packages share one version number and are released together: https://github.com/fpt-duongtx/xoong/releases
+* xoong is a working prototype (0.0.x): the HTML syntax is still Draft.
+
+MIT licence.

package/package.json

@@ -1,6 +1,46 @@
 {
   "name": "@xoong/forms",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.0.35",
+  "description": "xoong forms: a typed draft model with per-path state, validation rules taken from the OpenAPI request schema, custom rules, payload normalisation and dirty tracking. Zero dependencies besides @xoong/core and @xoong/data.",
+  "type": "module",
+  "main": "src/index.js",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "default": "./src/index.js"
+    },
+    "./model": "./src/form-model.js",
+    "./schema": "./src/schema.js"
+  },
+  "sideEffects": true,
+  "files": [
+    "src"
+  ],
+  "keywords": [
+    "xoong",
+    "forms",
+    "validation",
+    "openapi"
+  ],
+  "license": "MIT",
+  "author": "Duong Tran Xuan <duongtx1505@icloud.com>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/fpt-duongtx/xoong.git",
+    "directory": "packages/forms"
+  },
+  "bugs": {
+    "url": "https://github.com/fpt-duongtx/xoong/issues"
+  },
+  "homepage": "https://github.com/fpt-duongtx/xoong#readme",
+  "dependencies": {
+    "@xoong/core": "0.0.35",
+    "@xoong/data": "0.0.35"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=22.12"
+  }
+}

package/src/form-dom.js

@@ -0,0 +1,265 @@
+// @ts-check
+/**
+ * The binder (ADR-0009): attaches a form model to a <form> element. Controls are found by their `name` path; the model is the
+ * single source of truth and the DOM is a view of it.
+ *
+ *   DOM -> model   one delegated `input` / `change` listener per form (a form of 800 fields has two listeners, not 800)
+ *   model -> DOM   one small effect per control: its value, its error, and attributes completed from the schema
+ *   errors         shown on blur (touched) and on submit; `aria-invalid`, `aria-describedby`, a message element; the model decides,
+ *                  never the browser (the form gets `novalidate`, so a hidden invalid control cannot block submit)
+ *
+ * Used by `xo-submit` (packages/data/src/view.js) for every operation that has a request schema.
+ */
+import { effect, untracked } from '@xoong/core/signals';
+import { createForm } from './form-model.js';
+import { parsePath, nodeAt, isRequired, defaults } from './schema.js';
+
+/** @typedef {import('./schema.js').Node} Node */
+
+const CONTROL = 'input,select,textarea';
+
+/** Is it a custom control (an `XoControl`, or any form-associated element with a value)? */
+const isCustom = (el) => el.localName.includes('-') && /** @type {any} */ (el.constructor).formAssociated === true;
+const isControl = (el) => (el.matches?.(CONTROL) && el.type !== 'submit' && el.type !== 'button' && el.type !== 'reset' && el.type !== 'file') || isCustom(el);
+
+/** ISO UTC string -> value of an <input type="datetime-local"> (local time, minutes). */
+export function isoToLocal(iso) {
+  const d = new Date(iso);
+  if (Number.isNaN(d.getTime())) return '';
+  const p = (n) => String(n).padStart(2, '0');
+  return `${d.getFullYear()}-${p(d.getMonth() + 1)}-${p(d.getDate())}T${p(d.getHours())}:${p(d.getMinutes())}`;
+}
+/** Value of a datetime-local input (local time) -> ISO UTC string. */
+export function localToIso(local) {
+  const d = new Date(local);
+  return local === '' || Number.isNaN(d.getTime()) ? '' : d.toISOString();
+}
+
+/** The text a control shows for a model value. */
+const show = (v) => (v === undefined || v === null ? '' : typeof v === 'object' ? JSON.stringify(v) : String(v));
+
+/**
+ * @param {HTMLFormElement} form
+ * @param {{ schema: Node, record?: () => any, hadRecord?: boolean }} options
+ *   `record`: the record being edited (called inside an effect, so a live update refreshes the model); none for a create form.
+ */
+export function attach(form, { schema, record, hadRecord = !!record }) {
+  form.setAttribute('novalidate', ''); // the model validates; the browser must not block on controls it cannot focus
+  const model = createForm({ schema, value: record?.() });
+  /** @type {Map<Element, { name: string, stops: (() => void)[] }>} */
+  const bound = new Map();
+  let writing = /** @type {Element | null} */ (null);
+  let errorSeq = 0;
+
+  // ---- controls ---------------------------------------------------------------------------------------------------------
+
+  /** Fill in only what the author left out; an attribute in the HTML always wins. */
+  function complete(el, node, name) {
+    const set = (attr, value) => { if (value !== undefined && value !== null && value !== false && !el.hasAttribute(attr)) el.setAttribute(attr, value === true ? '' : String(value)); };
+    if (!node) return;
+    if (el.tagName === 'INPUT') {
+      if (!el.hasAttribute('type')) {
+        const t = node.t === 'boolean' ? 'checkbox' : node.t === 'integer' || node.t === 'number' ? 'number'
+          : node.format === 'email' ? 'email' : node.format === 'uri' || node.format === 'url' ? 'url' : node.format === 'password' ? 'password'
+            : node.format === 'date' ? 'date' : node.format === 'date-time' ? 'datetime-local' : 'text';
+        el.setAttribute('type', t);
+      }
+      if (node.t === 'integer') set('step', 1); else if (node.t === 'number') set('step', node.multipleOf ?? 'any');
+      set('min', node.minimum ?? (node.exclusiveMinimum !== undefined ? node.exclusiveMinimum : undefined));
+      set('max', node.maximum ?? (node.exclusiveMaximum !== undefined ? node.exclusiveMaximum : undefined));
+    }
+    if (el.tagName === 'INPUT' || el.tagName === 'TEXTAREA') {
+      set('minlength', node.minLength); set('maxlength', node.maxLength);
+      if (node.pattern && el.tagName === 'INPUT') set('pattern', node.pattern);
+      set('placeholder', node.placeholder);
+    }
+    if (el.tagName === 'SELECT' && node.enum && !el.options.length) {
+      const option = (text) => { const o = document.createElement('option'); o.value = o.textContent = text; return o; };
+      if (!isRequired(schema, parsePath(name), model.value)) el.append(option(''));
+      for (const v of node.enum) el.append(option(String(v)));
+    }
+    if (node.readOnly) set('readonly', true);
+    if (isRequired(schema, parsePath(name), model.value) && node.t !== 'boolean') set('required', true);
+    if (isCustom(el)) { // an open registry of widgets: any XoControl gets its schema node, its hints and the form model
+      const hints = { ...(node.hints ?? {}), label: node.title, hint: node.description, placeholder: node.placeholder, order: node.order, group: node.group };
+      Object.assign(el, { schema: node, hints, xoForm: model });
+    }
+  }
+
+  function bind(el) {
+    const name = el.getAttribute('name');
+    if (!name) return;
+    const prev = bound.get(el);
+    if (prev) { if (prev.name === name) return; unbind(el); }
+    const parts = parsePath(name);
+    const node = nodeAt(schema, parts, model.value);
+    complete(el, node, name);
+    const field = model.field(name);
+    const stops = [];
+    // model -> DOM
+    stops.push(effect(() => {
+      const v = field.value;
+      const clean = !field.dirty; // the model has no change here: what is written is the baseline (a record on open, a refresh, a saved value)
+      if (writing === el) return; // this control is where the change came from: do not rewrite what the person is typing
+      const at = nodeAt(schema, parts, model.value);
+      untracked(() => { write(el, v, at); if (clean && isCustom(el)) /** @type {any} */ (el).markPristine?.(); }); // so the control's own `dirty` agrees with the form's; only the model drives this effect: whatever the control reads or sets inside (its own value, its validity) must not subscribe it
+    }));
+    // errors -> DOM, only once the field has been visited (or submit touched everything)
+    stops.push(effect(() => { const message = field.touched ? field.error : ''; untracked(() => showError(el, message)); }));
+    bound.set(el, { name, stops });
+  }
+
+  function unbind(el) {
+    const b = bound.get(el);
+    if (!b) return;
+    b.stops.forEach((s) => s());
+    bound.delete(el);
+    showError(el, '');
+  }
+
+  /** Model value -> control. */
+  function write(el, v, node) {
+    // the control's own value is read untracked: only the model drives this write (a control that sets its value and then fires `input` must not be reverted before the model hears)
+    if (isCustom(el)) { if (JSON.stringify(untracked(() => el.value)) !== JSON.stringify(v ?? '')) el.setValue(v ?? ''); return; }
+    if (el.type === 'checkbox') { el.checked = v === true; return; }
+    if (el.type === 'radio') { el.checked = show(v) === el.value; return; }
+    if (el.tagName === 'SELECT' && el.multiple) { const set = new Set(Array.isArray(v) ? v.map(String) : []); for (const o of el.options) o.selected = set.has(o.value); return; }
+    const text = el.type === 'datetime-local' ? (typeof v === 'string' ? isoToLocal(v) : '') : show(v);
+    if (el.value !== text) el.value = text;
+    void node;
+  }
+
+  /** The message of a field, as the browser's own validity, `aria-invalid` and a visible note. */
+  function showError(el, message) {
+    const note = /** @type {any} */ (el)._xoNote;
+    if (!message) {
+      note?.remove();
+      /** @type {any} */ (el)._xoNote = undefined;
+      el.removeAttribute?.('aria-invalid');
+      const ids = (el.getAttribute?.('aria-describedby') ?? '').split(' ').filter((i) => i && i !== note?.id);
+      if (ids.length) el.setAttribute('aria-describedby', ids.join(' ')); else el.removeAttribute?.('aria-describedby');
+      el.setCustomValidity?.('');
+      return;
+    }
+    let n = note;
+    if (!n) {
+      n = document.createElement('small');
+      n.className = 'xo-error';
+      n.dataset.xoError = '';
+      n.id = `xo-err-${++errorSeq}-${Math.random().toString(36).slice(2, 6)}`;
+      el.after(n);
+      /** @type {any} */ (el)._xoNote = n;
+      el.setAttribute('aria-describedby', [el.getAttribute('aria-describedby'), n.id].filter(Boolean).join(' '));
+    }
+    n.textContent = message;
+    el.setAttribute('aria-invalid', 'true');
+    el.setCustomValidity?.(message);
+  }
+
+  // ---- DOM -> model ---------------------------------------------------------------------------------------------------------
+
+  const target = (e) => /** @type {Element | null} */ (e.target)?.closest?.('[name]');
+
+  function onInput(e) {
+    const el = target(e);
+    if (!el || !isControl(el)) return;
+    const name = el.getAttribute('name') ?? '';
+    writing = el;
+    try {
+      if (isCustom(el)) model.set(name, /** @type {any} */ (el).value, { coerced: true });
+      else if (el.type === 'checkbox') model.set(name, /** @type {HTMLInputElement} */ (el).checked);
+      else if (el.type === 'radio') { if (/** @type {HTMLInputElement} */ (el).checked) model.set(name, /** @type {HTMLInputElement} */ (el).value); }
+      else if (el.tagName === 'SELECT' && /** @type {HTMLSelectElement} */ (el).multiple) model.set(name, [...(/** @type {HTMLSelectElement} */ (el)).selectedOptions].map((o) => o.value), { coerced: true });
+      else if (el.type === 'datetime-local') model.set(name, localToIso(/** @type {HTMLInputElement} */ (el).value), { coerced: false });
+      else model.set(name, /** @type {HTMLInputElement} */ (el).value);
+    } finally { writing = null; }
+  }
+
+  function onBlur(e) {
+    const el = target(e);
+    if (el && isControl(el) && el.getAttribute('name')) model.touch(/** @type {string} */ (el.getAttribute('name')));
+  }
+
+  form.addEventListener('input', onInput);
+  form.addEventListener('change', onInput);
+  form.addEventListener('focusout', onBlur);
+
+  // Controls that appear later (xo-each rows, a revealed tab) and controls whose name changes (reordered rows).
+  const waiting = new Set();
+  const scan = (root) => {
+    for (const el of root.querySelectorAll?.('[name]') ?? []) { if (isControl(el)) bind(el); else waitFor(el); }
+    if (root.matches?.('[name]')) { if (isControl(root)) bind(root); else waitFor(root); }
+  };
+  /** A custom element used before its class is defined is a plain element for now: look again when the browser has upgraded it. */
+  const waitFor = (/** @type {Element} */ el) => {
+    const tag = el.localName;
+    if (!tag.includes('-') || waiting.has(tag) || typeof customElements === 'undefined' || customElements.get(tag)) return;
+    waiting.add(tag);
+    customElements.whenDefined(tag).then(() => { waiting.delete(tag); if (form.isConnected) scan(form); });
+  };
+  scan(form);
+  const observer = typeof MutationObserver !== 'undefined' ? new MutationObserver((records) => {
+    for (const r of records) {
+      if (r.type === 'attributes') { const el = /** @type {Element} */ (r.target); if (isControl(el)) { const b = bound.get(el); if (b && b.name !== el.getAttribute('name')) bind(el); else if (!b) bind(el); } continue; }
+      for (const n of r.removedNodes) if (n.nodeType === 1) { for (const el of [...bound.keys()]) if (!form.contains(el)) unbind(el); }
+      for (const n of r.addedNodes) if (n.nodeType === 1) scan(/** @type {Element} */ (n));
+    }
+  }) : null;
+  observer?.observe(form, { childList: true, subtree: true, attributes: true, attributeFilter: ['name'] });
+
+  // A dirty form announces itself (a router asks before the page is left), and says when it is clean again.
+  const stopArrays = model.onArrayChange((detail) => form.dispatchEvent(new CustomEvent('xo-array-change', { bubbles: true, detail }))); // the add, remove and move buttons, a drag, or code
+  const stopDirty = effect(() => form.dispatchEvent(new CustomEvent('xo-dirty', { bubbles: true, detail: { dirty: model.dirty } })));
+
+  // ---- the record underneath: a live update refreshes a pristine form, a dirty one keeps its draft ----------------------------
+  const stopRecord = record ? effect(() => { const r = record(); if (r !== undefined) model.refresh(r); }) : () => {};
+
+  // ---- submit ------------------------------------------------------------------------------------------------------------------
+
+  const controlFor = (path) => [...bound.entries()].find(([, b]) => parsePath(b.name).join('\u0000') === parsePath(path).join('\u0000'))?.[0];
+
+  /** The first invalid path in the order controls appear on the page (hidden or not rendered ones come after, in model order). */
+  function firstInvalid(errors) {
+    const paths = Object.keys(errors);
+    const ordered = [...form.querySelectorAll('[name]')].map((el) => el.getAttribute('name') ?? '').filter(Boolean);
+    return ordered.find((n) => paths.some((p) => parsePath(p).join('\u0000') === parsePath(n).join('\u0000'))) ?? paths[0];
+  }
+
+  /**
+   * The submit pipeline: touch all, validate, and when invalid ask the app to reveal the field (`xo-reveal`, cancelable) before focusing it.
+   * @param {(body: any) => Promise<any>} send
+   */
+  async function submit(send) {
+    const outcome = await model.submit(send, { after: hadRecord ? undefined : (form.hasAttribute('xo-keep') ? () => model.markPristine() : () => { model.markPristine(defaults(schema) ?? {}); model.reset(); }) }); // a sent form starts empty again: untouched, with no old errors
+    if (outcome.ok) return outcome;
+    const path = firstInvalid(outcome.errors);
+    const ev = new CustomEvent('xo-reveal', { detail: { path }, bubbles: true, cancelable: true });
+    const handled = !form.dispatchEvent(ev); // the app answers by switching a tab or selecting a block
+    if (handled) await new Promise((r) => setTimeout(r, 30)); // let that render
+    const el = controlFor(path);
+    if (el) (/** @type {any} */ (el).focusTarget ?? el).focus?.();
+    return { ...outcome, first: path };
+  }
+
+  function detach() {
+    form.removeEventListener('input', onInput);
+    form.removeEventListener('change', onInput);
+    form.removeEventListener('focusout', onBlur);
+    observer?.disconnect();
+    stopRecord();
+    stopDirty();
+    stopArrays();
+    form.dispatchEvent(new CustomEvent('xo-dirty', { bubbles: true, detail: { dirty: false } }));
+    for (const el of [...bound.keys()]) unbind(el);
+  }
+
+  // `form.rules` and `form.serialize` are set on the element, as the docs say
+  Object.defineProperties(form, {
+    rules: { get: () => model.rules, set: (r) => { model.rules = r; }, configurable: true },
+    serialize: { get: () => model.serialize, set: (fn) => { model.serialize = fn; }, configurable: true },
+    model: { value: model, configurable: true },
+  });
+
+  form.dispatchEvent(new CustomEvent('xo-form-ready', { bubbles: true, detail: { model } })); // `form.model` exists from here: a child control that needs it listens for this
+  return { model, submit, detach, rescan: () => scan(form) };
+}

package/src/form-model.js

@@ -0,0 +1,362 @@
+// @ts-check
+/**
+ * The form model (ADR-0009): a typed draft of a record, the baseline it came from, and derived state per path. No DOM here: the
+ * binder in form-dom.js connects it to a <form>, and tests drive it directly.
+ *
+ *   const form = createForm({ schema, value: record, rules: { slug: (v, { record }) => taken(v) ? 'Already used' : '' } });
+ *   form.set('title.en', 'Hello');          // a control's raw value, coerced by the schema
+ *   form.field('title.en').error            // reactive: read it inside an effect or a template
+ *   form.dirty, form.valid, form.errors['title.vi'], form.touched['title.vi'], form.filled['title.vi']
+ *   await form.submit((body) => client.mutate('updateArticle', { id }, body));
+ *
+ * Per-path state lives in one signal per path that has been asked for, updated only when its own value changes, so an edit in one
+ * field wakes the readers of that field (and its ancestors), not the other few hundred.
+ */
+import { signal, batch } from '@xoong/core/signals';
+import { parsePath, pathKey, getAt, setAt, nodeAt, variant, coerce, defaults, validate } from './schema.js';
+
+/** @typedef {import('./schema.js').Node} Node */
+
+const clone = (v) => (v === undefined ? undefined : structuredClone(v));
+/** Equality for "dirty": null and absent are the same (a cleared optional field is not a change from a record that never had it). */
+const strip = (v) => {
+  if (Array.isArray(v)) return v.map(strip);
+  if (v && typeof v === 'object') { const o = {}; for (const [k, x] of Object.entries(v)) if (x !== null && x !== undefined) o[k] = strip(x); return o; }
+  return v;
+};
+const same = (a, b) => JSON.stringify(strip(a)) === JSON.stringify(strip(b));
+const nothing = (v) => v === undefined || v === null || v === '';
+
+/**
+ * What is sent, and what "dirty" compares: the draft reduced to the request schema.
+ *  - only properties of the schema are kept (ids, timestamps and other server-owned fields of the record drop out; read-only too);
+ *  - an empty value follows `emptyAs` ("omit" by default, or "null"; an untouched field counts as empty); an explicit null is kept for a nullable field;
+ *    a nullable property the schema lists as required is sent as null when empty (the key must be present);
+ *  - `pruneEmpty` on an object removes its empty members, and an object left empty follows its own `emptyAs`;
+ *  - a node of type `any` is kept as it is.
+ * @param {Node | undefined} node @param {any} v
+ */
+export function normalize(node, v) {
+  if (!node || node.t === 'any') return v;
+  if (v === undefined) return node.emptyAs === 'null' && node.t !== 'object' ? null : undefined; // a field never touched is still empty, and empty follows emptyAs (an object that was never created sends nothing)
+  const asEmpty = () => (node.emptyAs === 'null' ? null : undefined);
+  if (v === null) return node.nullable ? null : asEmpty();
+  if (node.t === 'union') { const picked = variant(node, v); return picked ? normalize(picked, v) : undefined; }
+  if (node.t === 'object') {
+    if (typeof v !== 'object' || Array.isArray(v)) return v;
+    const out = {};
+    for (const [k, child] of Object.entries(node.props ?? {})) {
+      if (child.readOnly) continue;
+      let n = normalize(child, v[k]);
+      if (n === undefined && child.nullable && (node.required ?? []).includes(k)) n = null; // the key must be there, and null is its "empty"
+      if (n !== undefined && !(node.pruneEmpty && (n === null ? !child.nullable : nothing(n) || (typeof n === 'object' && !Array.isArray(n) && !Object.keys(n).length)))) out[k] = n;
+    }
+    if (node.pruneEmpty && !Object.keys(out).length) return node.nullable && node.emptyAs !== 'omit' ? null : asEmpty();
+    return out;
+  }
+  if (node.t === 'array') return Array.isArray(v) ? v.map((item) => normalize(node.items, item)) : v;
+  if (v === '') return asEmpty();
+  return v;
+}
+
+/** Is there something in the value after normalisation? (A filled-in field, for "missing translation" markers.) */
+function isFilled(node, v) {
+  const n = normalize(node, v);
+  if (n === undefined || n === null || n === '') return false;
+  if (Array.isArray(n)) return n.length > 0;
+  if (typeof n === 'object') return Object.keys(n).length > 0;
+  return true;
+}
+
+/**
+ * @param {{ schema?: Node, value?: any, rules?: Record<string, Function>, serialize?: (draft: any, body: any) => any }} [options]
+ *   `schema`: the request body node; `value`: the record to edit (the baseline); `rules`: custom rules by path; `serialize`: the escape hatch.
+ */
+export function createForm({ schema, value, rules = {}, serialize: serializeFn } = {}) {
+  let baseline = clone(value ?? defaults(schema) ?? {});
+  let draft = clone(baseline);
+  /** @type {Record<string, string>} */ let errors = {};
+  /** @type {Record<string, string>} */ let serverErrors = {};
+  /** @type {Set<(change: { path: string, op: 'add' | 'remove' | 'move', from?: number, to?: number }) => void>} */ const arrayListeners = new Set();
+  const arrayChanged = (/** @type {any[]} */ parent, op, from, to) => { const change = { path: pathKey(parent), op, from, to }; for (const fn of arrayListeners) fn(change); };
+  /** @type {Record<string, string>} */ let asyncErrors = {};
+  const asyncToken = new Map();
+  const touchedSet = new Set();
+  /** @type {Map<string, { parts: (string|number)[], value: any, error: any, touched: any, dirty: any, filled: any }>} */
+  const fields = new Map();
+  const state = { value: signal(draft), dirty: signal(false), valid: signal(true), submitting: signal(false), pending: signal(0), stale: signal(false) };
+  let currentRules = rules;
+
+  // ---- rules ----------------------------------------------------------------------------------------------------------------
+
+  /** The concrete paths a rule key applies to; `items[].title` covers every item. */
+  function expand(key) {
+    if (key === '*') return [[]];
+    let out = [[]];
+    for (const seg of key.replace(/\[\]/g, '.[]').split('.').filter(Boolean)) {
+      const next = [];
+      for (const base of out) {
+        if (seg === '[]') { const arr = getAt(draft, base); if (Array.isArray(arr)) arr.forEach((_, i) => next.push([...base, i])); } else next.push([...base, ...parsePath(seg)]);
+      }
+      out = next;
+    }
+    return out;
+  }
+
+  /** Rule keys known to return promises (learned the first time they run): they are re-run only for the path that changed, never on every publish. */
+  const asyncRules = new Set();
+
+  /**
+   * Run the custom rules. Synchronous ones always (they are cheap); asynchronous ones only for the paths in `only` (or all of them for
+   * `'all'`), because running them again is a network call. Returns the synchronous messages; promises are collected in `collect`.
+   * @param {Set<string> | 'all' | undefined} only @param {Promise<any>[]} [collect]
+   */
+  function runRules(only, collect) {
+    /** @type {Record<string, string>} */ const sync = {};
+    for (const [key, fn] of Object.entries(currentRules)) {
+      for (const parts of expand(key)) {
+        const k = pathKey(parts);
+        if (asyncRules.has(key) && !(only === 'all' || (only && (key === '*' || only.has(k))))) continue;
+        let result;
+        try { result = key === '*' ? fn(draft) : fn(getAt(draft, parts), { record: draft, path: k, form }); } catch (e) { result = String(e?.message ?? e); }
+        if (result && typeof result.then === 'function') { asyncRules.add(key); const p = settle(k, key === '*', result); collect?.push(p); }
+        else if (key === '*') { if (result && typeof result === 'object') Object.assign(sync, result); } else if (result) sync[k] = String(result);
+      }
+    }
+    return sync;
+  }
+
+  /** An async rule: the field is pending until it answers; an answer for an older value is ignored. */
+  function settle(k, tree, promise) {
+    const token = (asyncToken.get(k) ?? 0) + 1;
+    asyncToken.set(k, token);
+    state.pending.value += 1;
+    return promise.then((r) => {
+      if (asyncToken.get(k) !== token) return;
+      if (tree && r && typeof r === 'object') Object.assign(asyncErrors, r);
+      else if (r) asyncErrors[k] = String(r); else delete asyncErrors[k];
+    }, (e) => { if (asyncToken.get(k) === token) asyncErrors[k] = String(e?.message ?? e); })
+      .finally(() => { state.pending.value -= 1; publish(runRules(undefined)); });
+  }
+
+  // ---- derived state --------------------------------------------------------------------------------------------------------
+
+  /** Schema errors first, then custom rules, then async answers, then what the server said. */
+  function compute(syncRules) {
+    return { ...serverErrors, ...asyncErrors, ...syncRules, ...validate(schema, draft) };
+  }
+
+  function dirtyAt(parts) {
+    const node = nodeAt(schema, parts, draft);
+    return !same(normalize(node, getAt(draft, parts)), normalize(node, getAt(baseline, parts)));
+  }
+
+  /** Recompute everything derived and push it to the signals whose value actually changed. */
+  function publish(syncRules = runRules(undefined)) {
+    errors = compute(syncRules);
+    batch(() => {
+      state.value.value = draft;
+      state.dirty.value = !same(normalize(schema, draft), normalize(schema, baseline));
+      state.valid.value = !Object.keys(errors).length && state.pending.peek() === 0;
+      for (const [k, f] of fields) {
+        f.value.value = getAt(draft, f.parts);
+        f.error.value = errors[k] ?? '';
+        f.touched.value = touchedSet.has(k);
+        f.dirty.value = dirtyAt(f.parts);
+        f.filled.value = isFilled(nodeAt(schema, f.parts, draft), getAt(draft, f.parts));
+      }
+    });
+  }
+
+  /** After items of an array moved: touched paths follow their item, and per-path messages of that array are dropped (they are recomputed). */
+  function remap(parent, to) {
+    const prefix = pathKey(parent);
+    const re = new RegExp(`^${prefix.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\[(\\d+)\\](.*)$`);
+    const touched = [...touchedSet];
+    for (const k of touched) {
+      const m = re.exec(k);
+      if (!m) continue;
+      touchedSet.delete(k);
+      const n = to(Number(m[1]));
+      if (n >= 0) touchedSet.add(`${prefix}[${n}]${m[2]}`);
+    }
+    for (const map of [serverErrors, asyncErrors]) for (const k of Object.keys(map)) if (re.test(k)) delete map[k];
+  }
+
+  /** @param {string | (string|number)[]} path */
+  function field(path) {
+    const parts = typeof path === 'string' ? parsePath(path) : path;
+    const k = pathKey(parts);
+    let f = fields.get(k);
+    if (!f) {
+      const node = nodeAt(schema, parts, draft);
+      f = { parts, value: signal(getAt(draft, parts)), error: signal(errors[k] ?? ''), touched: signal(touchedSet.has(k)), dirty: signal(dirtyAt(parts)), filled: signal(isFilled(node, getAt(draft, parts))) };
+      fields.set(k, f);
+    }
+    const s = f;
+    return {
+      path: k,
+      get node() { return nodeAt(schema, parts, draft); },
+      get value() { return s.value.value; },
+      get error() { return s.error.value; },
+      get touched() { return s.touched.value; },
+      get dirty() { return s.dirty.value; },
+      get filled() { return s.filled.value; },
+      get valid() { return s.error.value === ''; },
+    };
+  }
+
+  /** `form.errors['title.vi']` style readers: each read tracks only that path. */
+  const view = (prop, listKeys) => new Proxy({}, {
+    get: (_, key) => (typeof key === 'string' && !key.startsWith('$') && key !== 'then' && key !== 'toJSON' ? field(key)[prop] : undefined),
+    has: (_, key) => typeof key === 'string' && !!field(key)[prop],
+    ownKeys: () => (listKeys ? listKeys() : []),
+    getOwnPropertyDescriptor: (_, key) => (typeof key === 'string' && listKeys?.().includes(key) ? { enumerable: true, configurable: true, value: field(key)[prop] } : undefined),
+  });
+
+  // ---- the model -------------------------------------------------------------------------------------------------------------
+
+  const form = {
+    /** The record being edited, as a signal-backed value: `form.value` (read inside an effect to track it). */
+    get value() { return state.value.value; },
+    get baseline() { return baseline; },
+    get dirty() { return state.dirty.value; },
+    get valid() { return state.valid.value; },
+    get submitting() { return state.submitting.value; },
+    get pending() { return state.pending.value > 0; },
+    /** True when the record changed underneath a dirty form (a live update): the draft is kept. */
+    get stale() { return state.stale.value; },
+    get rules() { return currentRules; },
+    set rules(r) { currentRules = r ?? {}; publish(); },
+    get serialize() { return serializeFn; },
+    set serialize(fn) { serializeFn = fn; },
+    field,
+    errors: view('error', () => (state.value.value, Object.keys(errors))),
+    touched: view('touched', () => [...touchedSet]),
+    filled: view('filled', undefined),
+    dirtyAt: view('dirty', undefined),
+
+    /** Read the draft at a path. */
+    get(path) { return getAt(draft, parsePath(path)); },
+
+    /** A control's raw value (string or boolean) written into the draft, coerced to the schema's type; clears the server error of that path. */
+    set(path, raw, { coerced = false } = {}) {
+      const parts = parsePath(path);
+      const k = pathKey(parts);
+      const next = coerced ? raw : coerce(nodeAt(schema, parts, draft), raw);
+      draft = setAt(draft, parts, next);
+      delete serverErrors[k];
+      delete asyncErrors[k];
+      publish(runRules(new Set([k])));
+      return next;
+    },
+
+    /**
+     * Add an item to the array at `path`. `value` is the new item; for a union item only `{ [key]: variant }` is needed, the variant's defaults are filled in.
+     * With no value a string item is '' and an object item starts from its schema defaults. Returns the new item's index.
+     */
+    append(path, initial) {
+      const parts = parsePath(path);
+      const node = nodeAt(schema, parts, draft);
+      const items = node?.items;
+      const list = getAt(draft, parts);
+      const current = Array.isArray(list) ? list : [];
+      let item = initial;
+      if (items?.t === 'union' && item && typeof item === 'object') item = { ...defaults(variant(items, item)), ...item };
+      else if (item === undefined) item = items?.t === 'string' ? '' : defaults(items) ?? (items?.t === 'object' ? {} : undefined);
+      draft = setAt(draft, parts, [...current, item]);
+      publish(runRules(undefined));
+      arrayChanged(parts, 'add', undefined, current.length);
+      return current.length;
+    },
+
+    /** Remove the array item at `path` (`blocks[2]`): the rows after it move up, and touched/error state follows them. */
+    removeAt(path) {
+      const parts = parsePath(path);
+      const index = parts.at(-1);
+      const parent = parts.slice(0, -1);
+      const list = getAt(draft, parent);
+      if (!Array.isArray(list) || typeof index !== 'number' || index >= list.length) return;
+      draft = setAt(draft, parent, list.filter((_, i) => i !== index));
+      remap(parent, (i) => (i === index ? -1 : i > index ? i - 1 : i));
+      publish(runRules(undefined));
+      arrayChanged(parent, 'remove', index, undefined);
+    },
+
+    /** Move the array item at `path` by `delta` places (-1 up, +1 down); a move past either end does nothing. */
+    moveItem(path, delta) {
+      const parts = parsePath(path);
+      const from = parts.at(-1);
+      const parent = parts.slice(0, -1);
+      const list = getAt(draft, parent);
+      if (!Array.isArray(list) || typeof from !== 'number') return;
+      const to = from + delta;
+      if (to < 0 || to >= list.length || to === from) return;
+      const next = [...list];
+      const [item] = next.splice(from, 1);
+      next.splice(to, 0, item);
+      draft = setAt(draft, parent, next);
+      remap(parent, (i) => (i === from ? to : from < to ? (i > from && i <= to ? i - 1 : i) : (i >= to && i < from ? i + 1 : i)));
+      publish(runRules(undefined));
+      arrayChanged(parent, 'move', from, to);
+    },
+
+    /** Be told when an array gains, loses or reorders an item, from any source (buttons, a drag, code): `{ path, op, from, to }`. Returns the stop function. */
+    onArrayChange(fn) { arrayListeners.add(fn); return () => arrayListeners.delete(fn); },
+
+    touch(path) { touchedSet.add(pathKey(parsePath(path))); publish(); },
+    /** Mark every field and every field with an error as touched (what submit does, so all errors show). */
+    touchAll() { for (const k of fields.keys()) touchedSet.add(k); for (const k of Object.keys(errors)) touchedSet.add(k); publish(); },
+
+    /** Server field errors, by path ({ 'title.en': 'taken' }); each clears when that field is edited. */
+    setServerErrors(map) { serverErrors = Object.fromEntries(Object.entries(map ?? {}).map(([k, v]) => [pathKey(parsePath(k)), v])); publish(); },
+
+    /** Back to the baseline, untouched. */
+    reset() { draft = clone(baseline); touchedSet.clear(); serverErrors = {}; asyncErrors = {}; state.stale.value = false; publish(); },
+    /** The saved record becomes the baseline (after a successful save). The draft is replaced when a record is given. */
+    markPristine(record) { if (record !== undefined) { baseline = clone(record); draft = clone(record); } else baseline = clone(draft); state.stale.value = false; publish(); },
+    /** The record changed in the store: a pristine form follows it, a dirty one keeps the draft and becomes stale. */
+    refresh(record) {
+      if (same(record, baseline)) return;
+      if (!state.dirty.peek()) { baseline = clone(record); draft = clone(record); publish(); } else state.stale.value = true;
+    },
+
+    /** The body that would be sent now. */
+    body() {
+      const body = normalize(schema, draft);
+      return serializeFn ? serializeFn(draft, body) : body;
+    },
+
+    /** Run everything, wait for async rules, and return all errors by path (empty when valid). */
+    async validate() {
+      const collected = [];
+      publish(runRules('all', collected));
+      await Promise.allSettled(collected);
+      publish();
+      return { ...errors };
+    },
+
+    /**
+     * Submit: touch everything, validate (async rules included), and when valid call `send(body)`. A thrown error with `fields` is shown on
+     * those paths. Resolves `{ ok: true, result }` or `{ ok: false, errors, first }` (the first invalid path, in schema order).
+     */
+    async submit(send, { after } = {}) {
+      form.touchAll();
+      const found = await form.validate();
+      const paths = Object.keys(found);
+      if (paths.length) return { ok: false, errors: found, first: paths[0] };
+      state.submitting.value = true;
+      try {
+        const result = await send(form.body());
+        if (after) after(result); else form.markPristine(result && typeof result === 'object' && !Array.isArray(result) ? result : undefined);
+        return { ok: true, result };
+      } catch (e) {
+        if (e && typeof e === 'object' && /** @type {any} */ (e).fields) form.setServerErrors(/** @type {any} */ (e).fields);
+        throw e;
+      } finally { state.submitting.value = false; }
+    },
+  };
+
+  publish(runRules('all'));
+  return form;
+}

package/src/index.d.ts

@@ -0,0 +1,71 @@
+// Types for @xoong/forms. The runtime is plain JavaScript; this file describes the form model and what the package exports.
+
+/** A node of the request schema (`bodySchema` in operations.json). */
+export interface SchemaNode {
+  t: 'string' | 'integer' | 'number' | 'boolean' | 'object' | 'array' | 'union' | 'entity' | 'any' | string;
+  nullable?: boolean; required?: string[]; props?: Record<string, SchemaNode>; items?: SchemaNode;
+  enum?: unknown[]; format?: string; pattern?: string; minLength?: number; maxLength?: number; minimum?: number; maximum?: number; minItems?: number; maxItems?: number;
+  default?: unknown; readOnly?: boolean; title?: string; description?: string; widget?: string; emptyAs?: 'null' | 'omit'; pruneEmpty?: boolean;
+  [key: string]: unknown;
+}
+
+/** A rule returns '' when the value is fine, or the message (it may be asynchronous). `'*'` gets the whole record and returns messages by path. */
+export type Rule = (value: any, context: { record: any }) => string | undefined | Promise<string | undefined>;
+export type Rules = Record<string, Rule | ((record: any) => Record<string, string> | Promise<Record<string, string>>)>;
+
+export interface ArrayChange { path: string; op: 'add' | 'remove' | 'move'; from?: number; to?: number }
+
+/** The draft of one form. `errors`, `touched`, `filled` and `dirtyAt` are read by path: `model.errors['title.en']`. */
+export interface FormModel {
+  readonly value: any;
+  readonly baseline: any;
+  readonly dirty: boolean;
+  readonly valid: boolean;
+  readonly submitting: boolean;
+  readonly pending: boolean;
+  readonly stale: boolean;
+  rules: Rules;
+  serialize: ((draft: any, body: any) => any) | undefined;
+  readonly errors: Record<string, string>;
+  readonly touched: Record<string, boolean>;
+  readonly filled: Record<string, boolean>;
+  readonly dirtyAt: Record<string, boolean>;
+  field(path: string): any;
+  get(path: string): any;
+  set(path: string, raw: unknown, options?: { coerced?: boolean }): unknown;
+  append(path: string, initial?: unknown): number;
+  removeAt(path: string): void;
+  moveItem(path: string, delta: number): void;
+  onArrayChange(fn: (change: ArrayChange) => void): () => void;
+  touch(path: string): void;
+  touchAll(): void;
+  setServerErrors(map: Record<string, string> | undefined): void;
+  reset(): void;
+  markPristine(record?: any): void;
+  refresh(record: any): void;
+  body(): any;
+  submit(send: (body: any) => Promise<any>, options?: { after?: () => void }): Promise<{ ok: boolean; result?: any; errors?: Record<string, string> }>;
+  [key: string]: any;
+}
+
+export function createForm(options?: { schema?: SchemaNode; value?: any; rules?: Rules; serialize?: (draft: any, body: any) => any }): FormModel;
+/** What is sent: the draft reduced to the request schema (empty values follow `emptyAs`, nullable required properties become null). */
+export function normalize(node: SchemaNode | undefined, value: any): any;
+/** Attach a model to a `<form>`: the binder that `<form xo-submit>` uses. */
+export function attach(form: HTMLFormElement, options: { schema: SchemaNode; record?: () => any; hadRecord?: boolean }): { model: FormModel; submit(send: (body: any) => Promise<any>): Promise<any>; detach(): void; rescan(): void };
+export function isoToLocal(iso: string): string;
+export function localToIso(local: string): string;
+
+export function parsePath(path: string): (string | number)[];
+export function pathKey(parts: (string | number)[]): string;
+export function getAt(value: any, parts: (string | number)[]): any;
+export function setAt(value: any, parts: (string | number)[], next: unknown): any;
+export function nodeAt(node: SchemaNode | undefined, parts: (string | number)[], value?: any): SchemaNode | undefined;
+export function variant(node: SchemaNode | undefined, value: any): SchemaNode | undefined;
+export function coerce(node: SchemaNode | undefined, raw: unknown): unknown;
+export function defaults(node: SchemaNode | undefined): unknown;
+export function validate(node: SchemaNode, value: any, at?: (string | number)[]): Record<string, string>;
+export function checkValue(node: SchemaNode, value: unknown): string;
+export function setMessages(partial: Record<string, (params: Record<string, any>) => string>): void;
+export function resetMessages(): void;
+export function message(code: string, params?: Record<string, any>): string;

package/src/index.js

@@ -0,0 +1,8 @@
+// @xoong/forms: importing it makes every <form xo-submit> use the schema-driven model (see form-dom.js once it is registered).
+export { createForm, normalize } from './form-model.js';
+export { attach, isoToLocal, localToIso } from './form-dom.js';
+
+import { setFormEngine } from '@xoong/data/view';
+import { attach as attachForm } from './form-dom.js';
+setFormEngine({ attach: attachForm }); // from now on, every xo-submit form with a request schema uses the form model
+export { parsePath, pathKey, getAt, setAt, nodeAt, variant, coerce, defaults, validate, checkValue, setMessages, resetMessages, message } from './schema.js';

package/src/schema.js

@@ -0,0 +1,250 @@
+// @ts-check
+/**
+ * The request schema model behind forms (ADR-0009). Pure functions, no DOM, no signals: everything here is testable in plain Node.
+ *
+ * A schema node is the JSON that `xoong sync` writes into `operations.json` as `bodySchema`:
+ *   { t: 'string', format?, enum?, minLength?, maxLength?, pattern?, nullable?, readOnly?, default?, title?, description?, widget? }
+ *   { t: 'integer' | 'number', minimum?, maximum?, exclusiveMinimum?, exclusiveMaximum?, multipleOf?, ... }
+ *   { t: 'boolean' }
+ *   { t: 'object', props: { name: node }, required?: string[] }
+ *   { t: 'array', items: node, minItems?, maxItems?, uniqueItems? }
+ *   { t: 'union', key: 'type', map: { value: node } }        a oneOf told apart by a property
+ *   { t: 'any' }                                              anything we cannot describe: accepted as it is
+ */
+
+import { text } from '@xoong/core';
+
+/** @typedef {{ t: string, [k: string]: any }} Node */
+
+// ---- paths ----------------------------------------------------------------------------------------------------------------
+
+/** "items[2].title" and "items.2.title" are the same path: ['items', 2, 'title']. */
+export function parsePath(path) {
+  const parts = [];
+  for (const raw of String(path).replace(/\[(\d+)\]/g, '.$1').split('.')) {
+    if (raw === '') continue;
+    parts.push(/^\d+$/.test(raw) ? Number(raw) : raw);
+  }
+  return parts;
+}
+
+/** The canonical string of a path: ['items', 2, 'title'] -> "items[2].title". */
+export function pathKey(parts) {
+  return parts.map((p, i) => (typeof p === 'number' ? `[${p}]` : i ? `.${p}` : p)).join('');
+}
+
+/** Read a value at a path (undefined when any step is missing). */
+export function getAt(value, parts) {
+  let v = value;
+  for (const p of parts) { if (v == null || typeof v !== 'object') return undefined; v = v[p]; }
+  return v;
+}
+
+/** A copy of `value` with `next` written at the path (creating objects and arrays on the way; `undefined` deletes the key). */
+export function setAt(value, parts, next) {
+  if (!parts.length) return next;
+  const [head, ...rest] = parts;
+  const base = value != null && typeof value === 'object' ? value : typeof head === 'number' ? [] : {};
+  const copy = Array.isArray(base) ? [...base] : { ...base };
+  const child = setAt(copy[head], rest, next);
+  if (child === undefined && !rest.length) { if (Array.isArray(copy)) copy[/** @type {number} */ (head)] = undefined; else delete copy[head]; } else copy[head] = child;
+  return copy;
+}
+
+// ---- walking the schema ------------------------------------------------------------------------------------------------------
+
+/**
+ * The schema node for a path, or undefined. For a union the variant is chosen from `value` (the record at that level).
+ * @param {Node | undefined} node @param {(string|number)[]} parts @param {any} [value]
+ */
+export function nodeAt(node, parts, value) {
+  let cur = node;
+  let val = value;
+  for (const p of parts) {
+    cur = variant(cur, val);
+    if (!cur) return undefined;
+    if (cur.t === 'object') cur = cur.props?.[p];
+    else if (cur.t === 'array' && typeof p === 'number') cur = cur.items;
+    else return undefined;
+    val = val != null && typeof val === 'object' ? val[p] : undefined;
+  }
+  return cur;
+}
+
+/** The concrete node of a union for a value (or the node itself). */
+export function variant(node, value) {
+  if (!node || node.t !== 'union') return node;
+  const tag = value != null && typeof value === 'object' ? value[node.key] : undefined;
+  return tag !== undefined ? node.map?.[tag] : undefined;
+}
+
+// ---- values ---------------------------------------------------------------------------------------------------------------
+
+/**
+ * A control's raw value (a string, or a boolean for a checkbox) as the typed value the schema wants.
+ * Empty text is "nothing entered": null for a nullable field, otherwise undefined (the key is left out).
+ * @param {Node | undefined} node @param {any} raw
+ */
+export function coerce(node, raw) {
+  if (!node) return raw;
+  if (node.t === 'boolean') return raw === true || raw === 'true' || raw === 'on';
+  if (raw === '' || raw === undefined || raw === null) return node.nullable || raw === null ? null : undefined;
+  if (node.t === 'integer' || node.t === 'number') { const n = Number(raw); return Number.isNaN(n) ? raw : n; } // a bad number stays text and fails validation
+  return raw;
+}
+
+/** The value a new record starts from: explicit defaults, and `{}` for required nested objects. */
+export function defaults(node) {
+  if (!node) return undefined;
+  if (node.default !== undefined) return structuredClone(node.default);
+  if (node.t === 'object') {
+    const out = {};
+    for (const [k, child] of Object.entries(node.props ?? {})) {
+      const d = defaults(child);
+      if (d !== undefined && (child.default !== undefined || (node.required ?? []).includes(k))) out[k] = d;
+    }
+    return out;
+  }
+  if (node.t === 'array' && (node.minItems ?? 0) > 0) return [];
+  return undefined;
+}
+
+// ---- messages -------------------------------------------------------------------------------------------------------------
+
+/** The default (English) messages. Replace any of them, for any language, with `setMessages({ required: () => '...' })`. */
+const catalogue = {
+  required: () => text('xoong.validation.required', 'Please fill in this field.'),
+  type: ({ type }) => (type === 'integer' ? text('xoong.validation.type.integer', 'Enter a whole number.') : type === 'number' ? text('xoong.validation.type.number', 'Enter a number.') : text('xoong.validation.type.other', 'This value is not valid.')),
+  minimum: ({ min }) => text('xoong.validation.minimum', 'Must be at least {min}.', { min }),
+  maximum: ({ max }) => text('xoong.validation.maximum', 'Must be at most {max}.', { max }),
+  exclusiveMinimum: ({ min }) => text('xoong.validation.exclusiveMinimum', 'Must be greater than {min}.', { min }),
+  exclusiveMaximum: ({ max }) => text('xoong.validation.exclusiveMaximum', 'Must be less than {max}.', { max }),
+  multipleOf: ({ step }) => text('xoong.validation.multipleOf', 'Must be a multiple of {step}.', { step }),
+  minLength: ({ min }) => text('xoong.validation.minLength', 'Use at least {min, plural, one {# character} other {# characters}}.', { min }),
+  maxLength: ({ max }) => text('xoong.validation.maxLength', 'Use at most {max, plural, one {# character} other {# characters}}.', { max }),
+  pattern: () => text('xoong.validation.pattern', 'This does not match the expected format.'),
+  format: ({ format }) => ({
+    email: text('xoong.validation.format.email', 'Enter a valid email address.'),
+    uri: text('xoong.validation.format.uri', 'Enter a valid URL.'),
+    url: text('xoong.validation.format.uri', 'Enter a valid URL.'),
+    uuid: text('xoong.validation.format.uuid', 'Enter a valid ID.'),
+    date: text('xoong.validation.format.date', 'Enter a valid date.'),
+    'date-time': text('xoong.validation.format.dateTime', 'Enter a valid date and time.'),
+  }[format] ?? text('xoong.validation.type.other', 'This value is not valid.')),
+  enum: () => text('xoong.validation.enum', 'Choose one of the listed values.'),
+  minItems: ({ min }) => text('xoong.validation.minItems', 'Add at least {min}.', { min }),
+  maxItems: ({ max }) => text('xoong.validation.maxItems', 'Add at most {max}.', { max }),
+  uniqueItems: () => text('xoong.validation.uniqueItems', 'Items must be different from each other.'),
+  variant: () => text('xoong.validation.variant', 'Choose a type.'),
+};
+/** @type {Record<string, (params: any) => string>} */
+let messages = { ...catalogue };
+
+/** Replace some messages (for another language, or your own wording). Each receives its parameters, for example `{ min: 3 }`. */
+export function setMessages(partial) { messages = { ...messages, ...partial }; }
+/** Back to the built-in English messages. */
+export function resetMessages() { messages = { ...catalogue }; }
+/** The message for a rule code. */
+export function message(code, params = {}) { return (messages[code] ?? catalogue.type)(params); }
+
+// ---- validation -----------------------------------------------------------------------------------------------------------
+
+const FORMATS = {
+  email: (s) => /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(s),
+  uri: (s) => { try { new URL(s); return true; } catch { return false; } },
+  url: (s) => { try { new URL(s); return true; } catch { return false; } },
+  uuid: (s) => /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(s),
+  date: (s) => /^\d{4}-\d{2}-\d{2}$/.test(s) && !Number.isNaN(Date.parse(s)),
+  'date-time': (s) => /^\d{4}-\d{2}-\d{2}[T ]\d{2}:\d{2}/.test(s) && !Number.isNaN(Date.parse(s)),
+};
+
+const isEmpty = (v) => v === undefined || v === null || v === '';
+
+/**
+ * The first rule a single value breaks, as a message, or '' when it is fine. `required` is decided by the parent (see validate).
+ * @param {Node} node @param {any} value
+ */
+export function checkValue(node, value) {
+  if (value === undefined || value === null) return '';
+  switch (node.t) {
+    case 'string': {
+      if (typeof value !== 'string') return message('type', { type: 'string' });
+      if (node.enum && !node.enum.includes(value)) return message('enum');
+      if (node.minLength != null && value.length < node.minLength) return message('minLength', { min: node.minLength });
+      if (node.maxLength != null && value.length > node.maxLength) return message('maxLength', { max: node.maxLength });
+      if (node.pattern) { try { if (!new RegExp(node.pattern, 'u').test(value)) return message('pattern', { pattern: node.pattern }); } catch { /* a pattern JavaScript cannot read: do not block the form */ } }
+      if (node.format && FORMATS[node.format] && !FORMATS[node.format](value)) return message('format', { format: node.format });
+      return '';
+    }
+    case 'integer':
+    case 'number': {
+      if (typeof value !== 'number' || Number.isNaN(value) || (node.t === 'integer' && !Number.isInteger(value))) return message('type', { type: node.t });
+      if (node.enum && !node.enum.includes(value)) return message('enum');
+      if (node.minimum != null && value < node.minimum) return message('minimum', { min: node.minimum });
+      if (node.maximum != null && value > node.maximum) return message('maximum', { max: node.maximum });
+      if (node.exclusiveMinimum != null && value <= node.exclusiveMinimum) return message('exclusiveMinimum', { min: node.exclusiveMinimum });
+      if (node.exclusiveMaximum != null && value >= node.exclusiveMaximum) return message('exclusiveMaximum', { max: node.exclusiveMaximum });
+      if (node.multipleOf) { const q = value / node.multipleOf; if (Math.abs(q - Math.round(q)) > 1e-9) return message('multipleOf', { step: node.multipleOf }); }
+      return '';
+    }
+    default:
+      return '';
+  }
+}
+
+/**
+ * Every error in a record, by canonical path: { 'title.en': 'message', 'tags[1]': 'message' }. Empty object when valid.
+ * Read-only properties are not checked (the server owns them). Unknown properties are accepted.
+ * @param {Node | undefined} node @param {any} value @param {(string|number)[]} [at]
+ * @returns {Record<string, string>}
+ */
+export function validate(node, value, at = []) {
+  /** @type {Record<string, string>} */
+  const errors = {};
+  walk(node, value, at, errors);
+  return errors;
+}
+
+function walk(node, value, at, errors) {
+  if (!node || node.readOnly) return;
+  const key = pathKey(at);
+  if (node.t === 'union') {
+    const picked = variant(node, value);
+    if (!picked) { if (value != null) errors[pathKey([...at, node.key])] = message('variant'); return; }
+    walk(picked, value, at, errors);
+    return;
+  }
+  if (node.t === 'object') {
+    if (value == null) return;
+    if (typeof value !== 'object' || Array.isArray(value)) { errors[key] = message('type', { type: 'object' }); return; }
+    for (const [name, child] of Object.entries(node.props ?? {})) {
+      const v = value[name];
+      if ((node.required ?? []).includes(name) && !child.readOnly && isEmpty(v)) {
+        if (child.nullable) continue; // a nullable field may be left empty (it is sent as null): "required" only means the key is present
+        errors[pathKey([...at, name])] = message('required');
+        continue;
+      }
+      walk(child, v, [...at, name], errors);
+    }
+    return;
+  }
+  if (node.t === 'array') {
+    if (value == null) return;
+    if (!Array.isArray(value)) { errors[key] = message('type', { type: 'array' }); return; }
+    if (node.minItems != null && value.length < node.minItems) errors[key] = message('minItems', { min: node.minItems });
+    else if (node.maxItems != null && value.length > node.maxItems) errors[key] = message('maxItems', { max: node.maxItems });
+    else if (node.uniqueItems && new Set(value.map((x) => JSON.stringify(x))).size !== value.length) errors[key] = message('uniqueItems');
+    value.forEach((item, i) => walk(node.items, item, [...at, i], errors));
+    return;
+  }
+  const problem = checkValue(node, value);
+  if (problem) errors[key] = problem;
+}
+
+/** Is a path required? (Its parent object lists it as required.) */
+export function isRequired(root, parts, value) {
+  if (!parts.length) return false;
+  const parent = nodeAt(root, parts.slice(0, -1), value);
+  const p = variant(parent, getAt(value, parts.slice(0, -1)));
+  return !!p && p.t === 'object' && (p.required ?? []).includes(parts.at(-1)) && !p.props?.[parts.at(-1)]?.nullable; // a nullable field may be left empty
+}