@c9up/aurora 0.1.8 → 0.1.9

package/README.md

@@ -24,7 +24,7 @@ providers: [
 
 ## Entry points
 
-- `@c9up/aurora` — main API: reactive primitives (`signal`/`effect`/`html`/`component`/`hydrate`) plus the client toolkit — `WebStorage`/`persistedSignal`, reactive browser signals (`prefersDark`/`online`/`windowSize`/…), SPA navigation (`navigate`/`queryParam`), `cookie`/`clipboard`/`share`, and the `HttpClient` fetch wrapper
+- `@c9up/aurora` — main API: reactive primitives (`signal`/`effect`/`html`/`component`/`hydrate`) plus the client toolkit — `WebStorage`/`persistedSignal`, reactive browser signals (`prefersDark`/`online`/`windowSize`/…), SPA navigation (`navigate`/`queryParam`), `cookie`/`clipboard`/`share`, the `HttpClient` fetch wrapper, `command()` (async action + reactive loading/data/error), and `form()` (reactive form controller; optional rune validation + rosetta i18n)
 - `@c9up/aurora/provider` — Ream IoC provider
 - `@c9up/aurora/services/main` — container service accessor
 - `@c9up/aurora/relay` — realtime adapter

package/dist/command.d.ts

@@ -0,0 +1,48 @@
+/**
+ * `command()` — wrap an async task (typically an `HttpClient` call) with reactive
+ * `loading` / `data` / `error` signals plus `onSuccess` / `onFail` handlers and a
+ * `run(...args)` launcher, so call sites never write `then`/`catch` or
+ * `await`+try/catch.
+ *
+ * `run` is re-runnable with different arguments each time; the signals reflect
+ * the LATEST run. A superseded (slower) run that resolves after a newer one is
+ * silently dropped — it never overwrites the latest state — which makes
+ * re-running safe for search-as-you-type / retry. Node-free — part of the client
+ * barrel.
+ *
+ * ```js
+ * import { command, HttpClient, isHttpError } from '@c9up/aurora'
+ * const api = new HttpClient()
+ *
+ * const login = command((creds) => api.post('/auth/login', creds))
+ *   .onSuccess((u) => { user(u); redirect('/app') })
+ *   .onFail((e) => formError(isHttpError(e) ? e.data : 'Network error'))
+ *
+ * login.run(creds())          // launch — no try/catch
+ * // bind login.loading() for a spinner / disabled button
+ * ```
+ */
+import { type ReadSignal } from "./reactive.js";
+export interface Command<TArgs extends unknown[], TData> {
+    /** Latest successful result, or `null` before the first success / after `reset`. */
+    readonly data: ReadSignal<TData | null>;
+    /** Latest run's error, or `null` when none. */
+    readonly error: ReadSignal<unknown>;
+    /** Whether the latest run is in flight. */
+    readonly loading: ReadSignal<boolean>;
+    /** Register a success handler (chainable; multiple allowed). */
+    onSuccess(handler: (data: TData) => void): this;
+    /** Register a failure handler — receives the thrown error (chainable). */
+    onFail(handler: (error: unknown) => void): this;
+    /** Register a handler that runs after success OR failure (chainable). */
+    onSettled(handler: () => void): this;
+    /** Launch the task with `args`. Always resolves (errors route to `onFail`). */
+    run(...args: TArgs): Promise<void>;
+    /** Clear `data`/`error`/`loading` and invalidate any in-flight run. */
+    reset(): void;
+}
+/**
+ * Create a re-runnable {@link Command} around an async `task`. See the module
+ * doc for usage.
+ */
+export declare function command<TArgs extends unknown[], TData>(task: (...args: TArgs) => Promise<TData>): Command<TArgs, TData>;

package/dist/command.js

@@ -0,0 +1,93 @@
+/**
+ * `command()` — wrap an async task (typically an `HttpClient` call) with reactive
+ * `loading` / `data` / `error` signals plus `onSuccess` / `onFail` handlers and a
+ * `run(...args)` launcher, so call sites never write `then`/`catch` or
+ * `await`+try/catch.
+ *
+ * `run` is re-runnable with different arguments each time; the signals reflect
+ * the LATEST run. A superseded (slower) run that resolves after a newer one is
+ * silently dropped — it never overwrites the latest state — which makes
+ * re-running safe for search-as-you-type / retry. Node-free — part of the client
+ * barrel.
+ *
+ * ```js
+ * import { command, HttpClient, isHttpError } from '@c9up/aurora'
+ * const api = new HttpClient()
+ *
+ * const login = command((creds) => api.post('/auth/login', creds))
+ *   .onSuccess((u) => { user(u); redirect('/app') })
+ *   .onFail((e) => formError(isHttpError(e) ? e.data : 'Network error'))
+ *
+ * login.run(creds())          // launch — no try/catch
+ * // bind login.loading() for a spinner / disabled button
+ * ```
+ */
+import { signal } from "./reactive.js";
+class CommandRunner {
+    #task;
+    #data = signal(null);
+    #error = signal(null);
+    #loading = signal(false);
+    #onSuccess = [];
+    #onFail = [];
+    #onSettled = [];
+    #runId = 0;
+    data = this.#data;
+    error = this.#error;
+    loading = this.#loading;
+    constructor(task) {
+        this.#task = task;
+    }
+    onSuccess(handler) {
+        this.#onSuccess.push(handler);
+        return this;
+    }
+    onFail(handler) {
+        this.#onFail.push(handler);
+        return this;
+    }
+    onSettled(handler) {
+        this.#onSettled.push(handler);
+        return this;
+    }
+    reset() {
+        this.#runId++; // invalidate any in-flight run so it can't write back
+        this.#data(null);
+        this.#error(null);
+        this.#loading(false);
+    }
+    async run(...args) {
+        const id = ++this.#runId;
+        this.#loading(true);
+        this.#error(null);
+        try {
+            const result = await this.#task(...args);
+            if (id !== this.#runId)
+                return; // superseded by a newer run — drop
+            this.#data(result);
+            for (const handler of this.#onSuccess)
+                handler(result);
+        }
+        catch (error) {
+            if (id !== this.#runId)
+                return; // superseded — drop
+            this.#error(error);
+            for (const handler of this.#onFail)
+                handler(error);
+        }
+        finally {
+            if (id === this.#runId) {
+                this.#loading(false);
+                for (const handler of this.#onSettled)
+                    handler();
+            }
+        }
+    }
+}
+/**
+ * Create a re-runnable {@link Command} around an async `task`. See the module
+ * doc for usage.
+ */
+export function command(task) {
+    return new CommandRunner(task);
+}

package/dist/form.d.ts

@@ -0,0 +1,89 @@
+/**
+ * `form()` — a minimal reactive form controller: per-field `value` / `error` /
+ * `touched` signals, validation, and a submit driven by {@link command} (so the
+ * submit's `loading` / `error` are reactive too). Call sites bind the signals in
+ * `html\`\`` and never hand-roll field state or try/catch.
+ *
+ * Validation is OPTIONAL and **agnostic**: pass a `validate` function returning a
+ * `{ field: message }` map, OR any object with a `.validate(values)` method
+ * (e.g. a `@c9up/rune` schema) — aurora never imports a validator, it only
+ * duck-types `.validate`. With no `validate`, the form simply never reports field
+ * errors. Node-free — part of the client barrel.
+ *
+ * ```js
+ * import { form, HttpClient, isHttpError } from '@c9up/aurora'
+ * import { rules, schema } from '@c9up/rune'   // optional
+ * const api = new HttpClient()
+ *
+ * const f = form({
+ *   initial: { email: '', password: '' },
+ *   validate: schema({ email: rules.string().email(), password: rules.string().min(8) }),
+ *   submit: (values) => api.post('/auth/login', values),
+ * })
+ *   .onSuccess(() => redirect('/app'))
+ *   .onFail((e) => { if (isHttpError(e)) f.setErrors(e.data?.errors ?? {}) })
+ *
+ * const email = f.field('email')
+ * // <input value=${email.value} @input=${(e) => email.set(e.target.value)} @blur=${email.markTouched}>
+ * // <button ?disabled=${f.submitting} @click=${(e) => f.handleSubmit(e)}>
+ * ```
+ */
+import { type ReadSignal } from "./reactive.js";
+/** A field-keyed error map: `{ email: "Invalid", … }`. Absent key ⇒ no error. */
+export type FieldErrors<T> = Partial<Record<keyof T, string>>;
+/** Anything `.validate()`-shaped (a `@c9up/rune` schema satisfies this). */
+export interface FormSchema<T> {
+    validate(values: T): {
+        valid: boolean;
+        errors?: ReadonlyArray<{
+            field?: string;
+            message: string;
+        }>;
+    };
+}
+/** Validation source — a function, a schema-like object, or omitted. */
+export type FormValidate<T> = ((values: T) => FieldErrors<T>) | FormSchema<T>;
+export interface FormOptions<T> {
+    /** Initial field values; its keys define the form's fields. */
+    initial: T;
+    /** The submit task (wrapped in a {@link command}). */
+    submit: (values: T) => Promise<unknown>;
+    /** Optional, agnostic validation (function OR `.validate`-shaped object). */
+    validate?: FormValidate<T>;
+}
+/** A single field's reactive handles + setters. */
+export interface FormField<V> {
+    readonly value: ReadSignal<V>;
+    readonly error: ReadSignal<string | null>;
+    readonly touched: ReadSignal<boolean>;
+    set(value: V): void;
+    markTouched(): void;
+}
+export interface Form<T> {
+    readonly values: ReadSignal<T>;
+    readonly errors: ReadSignal<FieldErrors<T>>;
+    /** Whether the last validation found no errors. */
+    readonly valid: ReadSignal<boolean>;
+    /** Whether the submit is in flight (the submit command's loading). */
+    readonly submitting: ReadSignal<boolean>;
+    /** The submit command's last error. */
+    readonly submitError: ReadSignal<unknown>;
+    field<K extends keyof T>(key: K): FormField<T[K]>;
+    set<K extends keyof T>(key: K, value: T[K]): void;
+    /** Run validation now, populate `errors`, and return whether it passed. */
+    validate(): boolean;
+    /** Validate then submit (no-op if invalid). Calls `event.preventDefault()`. */
+    handleSubmit(event?: {
+        preventDefault(): void;
+    }): Promise<void>;
+    /** Merge in errors (e.g. server-side field errors from `HttpError.data`). */
+    setErrors(errors: FieldErrors<T>): void;
+    /** Reset values to `initial` and clear errors / touched / submit state. */
+    reset(): void;
+    /** Submit success handler (chainable) — receives the resolved value. */
+    onSuccess(handler: (data: unknown) => void): this;
+    /** Submit failure handler (chainable) — receives the thrown error. */
+    onFail(handler: (error: unknown) => void): this;
+}
+/** Create a reactive {@link Form} controller. See the module doc for usage. */
+export declare function form<T>(options: FormOptions<T>): Form<T>;

package/dist/form.js

@@ -0,0 +1,130 @@
+/**
+ * `form()` — a minimal reactive form controller: per-field `value` / `error` /
+ * `touched` signals, validation, and a submit driven by {@link command} (so the
+ * submit's `loading` / `error` are reactive too). Call sites bind the signals in
+ * `html\`\`` and never hand-roll field state or try/catch.
+ *
+ * Validation is OPTIONAL and **agnostic**: pass a `validate` function returning a
+ * `{ field: message }` map, OR any object with a `.validate(values)` method
+ * (e.g. a `@c9up/rune` schema) — aurora never imports a validator, it only
+ * duck-types `.validate`. With no `validate`, the form simply never reports field
+ * errors. Node-free — part of the client barrel.
+ *
+ * ```js
+ * import { form, HttpClient, isHttpError } from '@c9up/aurora'
+ * import { rules, schema } from '@c9up/rune'   // optional
+ * const api = new HttpClient()
+ *
+ * const f = form({
+ *   initial: { email: '', password: '' },
+ *   validate: schema({ email: rules.string().email(), password: rules.string().min(8) }),
+ *   submit: (values) => api.post('/auth/login', values),
+ * })
+ *   .onSuccess(() => redirect('/app'))
+ *   .onFail((e) => { if (isHttpError(e)) f.setErrors(e.data?.errors ?? {}) })
+ *
+ * const email = f.field('email')
+ * // <input value=${email.value} @input=${(e) => email.set(e.target.value)} @blur=${email.markTouched}>
+ * // <button ?disabled=${f.submitting} @click=${(e) => f.handleSubmit(e)}>
+ * ```
+ */
+import { command } from "./command.js";
+import { memo, signal } from "./reactive.js";
+/** Normalize any validation source into a field-error map. */
+function computeErrors(validate, values) {
+    if (!validate)
+        return {};
+    if (typeof validate === "function")
+        return validate(values);
+    const result = validate.validate(values);
+    if (result.valid)
+        return {};
+    const errors = {};
+    for (const issue of result.errors ?? []) {
+        if (issue.field && !(issue.field in errors)) {
+            errors[issue.field] = issue.message;
+        }
+    }
+    // Boundary: a schema's errors are string-keyed and it doesn't know `keyof T`,
+    // so narrow the validated key space to the form's field type here.
+    return errors;
+}
+class FormController {
+    #initial;
+    #validate;
+    #values;
+    #errors = signal({});
+    #touched = signal(new Set());
+    #command;
+    values;
+    errors = this.#errors;
+    valid;
+    submitting;
+    submitError;
+    constructor(options) {
+        this.#initial = { ...options.initial };
+        this.#validate = options.validate;
+        this.#values = signal({ ...options.initial });
+        this.values = this.#values;
+        this.#command = command((values) => options.submit(values));
+        this.submitting = this.#command.loading;
+        this.submitError = this.#command.error;
+        this.valid = memo(() => Object.values(this.#errors()).every((message) => !message));
+    }
+    field(key) {
+        return {
+            value: memo(() => this.#values()[key]),
+            error: memo(() => this.#errors()[key] ?? null),
+            touched: memo(() => this.#touched().has(String(key))),
+            set: (value) => this.set(key, value),
+            markTouched: () => this.#markTouched(key),
+        };
+    }
+    set(key, value) {
+        const next = { ...this.#values() };
+        next[key] = value;
+        this.#values(next);
+        // Clear a stale error for this field as the user edits it.
+        if (this.#errors()[key] !== undefined) {
+            const errors = { ...this.#errors() };
+            delete errors[key];
+            this.#errors(errors);
+        }
+    }
+    validate() {
+        const errors = computeErrors(this.#validate, this.#values());
+        this.#errors(errors);
+        return Object.values(errors).every((message) => !message);
+    }
+    async handleSubmit(event) {
+        event?.preventDefault();
+        this.#touched(new Set(Object.keys(this.#values())));
+        if (!this.validate())
+            return;
+        await this.#command.run(this.#values());
+    }
+    setErrors(errors) {
+        this.#errors({ ...this.#errors(), ...errors });
+    }
+    reset() {
+        this.#values({ ...this.#initial });
+        this.#errors({});
+        this.#touched(new Set());
+        this.#command.reset();
+    }
+    onSuccess(handler) {
+        this.#command.onSuccess(handler);
+        return this;
+    }
+    onFail(handler) {
+        this.#command.onFail(handler);
+        return this;
+    }
+    #markTouched(key) {
+        this.#touched(new Set(this.#touched()).add(String(key)));
+    }
+}
+/** Create a reactive {@link Form} controller. See the module doc for usage. */
+export function form(options) {
+    return new FormController(options);
+}

package/dist/index.d.ts

@@ -1,6 +1,10 @@
 export type { CookieOptions, PersistedSignalOptions, ShareData, StorageArea, WebStorageOptions, WindowSize, } from "./browser.js";
 export { back, clipboard, cookie, forward, hash, mediaQuery, navigate, online, persistedSignal, prefersDark, queryParam, redirect, reload, replace, session, share, storage, visibility, WebStorage, windowSize, } from "./browser.js";
+export type { Command } from "./command.js";
+export { command } from "./command.js";
 export { component, onMount, onUnmount } from "./component.js";
+export type { FieldErrors, Form, FormField, FormOptions, FormSchema, FormValidate, } from "./form.js";
+export { form } from "./form.js";
 export { html, isTemplateResult } from "./html.js";
 export type { HttpClientOptions, HttpRequestOptions, HttpResult, } from "./http.js";
 export { HttpClient, HttpError, http, isAbortError, isHttpError, } from "./http.js";

package/dist/index.js

@@ -1,5 +1,7 @@
 export { back, clipboard, cookie, forward, hash, mediaQuery, navigate, online, persistedSignal, prefersDark, queryParam, redirect, reload, replace, session, share, storage, visibility, WebStorage, windowSize, } from "./browser.js";
+export { command } from "./command.js";
 export { component, onMount, onUnmount } from "./component.js";
+export { form } from "./form.js";
 export { html, isTemplateResult } from "./html.js";
 export { HttpClient, HttpError, http, isAbortError, isHttpError, } from "./http.js";
 export { hydrate } from "./hydrate.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@c9up/aurora",
-  "version": "0.1.8",
+  "version": "0.1.9",
   "description": "Aurora — reactive UI runtime for the Ream framework. Tagged-template DOM, signal-based state, isomorphic SSR + hydration, zero build step.",
   "license": "MIT",
   "type": "module",

package/src/command.ts

@@ -0,0 +1,119 @@
+/**
+ * `command()` — wrap an async task (typically an `HttpClient` call) with reactive
+ * `loading` / `data` / `error` signals plus `onSuccess` / `onFail` handlers and a
+ * `run(...args)` launcher, so call sites never write `then`/`catch` or
+ * `await`+try/catch.
+ *
+ * `run` is re-runnable with different arguments each time; the signals reflect
+ * the LATEST run. A superseded (slower) run that resolves after a newer one is
+ * silently dropped — it never overwrites the latest state — which makes
+ * re-running safe for search-as-you-type / retry. Node-free — part of the client
+ * barrel.
+ *
+ * ```js
+ * import { command, HttpClient, isHttpError } from '@c9up/aurora'
+ * const api = new HttpClient()
+ *
+ * const login = command((creds) => api.post('/auth/login', creds))
+ *   .onSuccess((u) => { user(u); redirect('/app') })
+ *   .onFail((e) => formError(isHttpError(e) ? e.data : 'Network error'))
+ *
+ * login.run(creds())          // launch — no try/catch
+ * // bind login.loading() for a spinner / disabled button
+ * ```
+ */
+
+import { type ReadSignal, signal } from "./reactive.js";
+
+export interface Command<TArgs extends unknown[], TData> {
+	/** Latest successful result, or `null` before the first success / after `reset`. */
+	readonly data: ReadSignal<TData | null>;
+	/** Latest run's error, or `null` when none. */
+	readonly error: ReadSignal<unknown>;
+	/** Whether the latest run is in flight. */
+	readonly loading: ReadSignal<boolean>;
+	/** Register a success handler (chainable; multiple allowed). */
+	onSuccess(handler: (data: TData) => void): this;
+	/** Register a failure handler — receives the thrown error (chainable). */
+	onFail(handler: (error: unknown) => void): this;
+	/** Register a handler that runs after success OR failure (chainable). */
+	onSettled(handler: () => void): this;
+	/** Launch the task with `args`. Always resolves (errors route to `onFail`). */
+	run(...args: TArgs): Promise<void>;
+	/** Clear `data`/`error`/`loading` and invalidate any in-flight run. */
+	reset(): void;
+}
+
+class CommandRunner<TArgs extends unknown[], TData>
+	implements Command<TArgs, TData>
+{
+	readonly #task: (...args: TArgs) => Promise<TData>;
+	readonly #data = signal<TData | null>(null);
+	readonly #error = signal<unknown>(null);
+	readonly #loading = signal(false);
+	readonly #onSuccess: Array<(data: TData) => void> = [];
+	readonly #onFail: Array<(error: unknown) => void> = [];
+	readonly #onSettled: Array<() => void> = [];
+	#runId = 0;
+
+	readonly data: ReadSignal<TData | null> = this.#data;
+	readonly error: ReadSignal<unknown> = this.#error;
+	readonly loading: ReadSignal<boolean> = this.#loading;
+
+	constructor(task: (...args: TArgs) => Promise<TData>) {
+		this.#task = task;
+	}
+
+	onSuccess(handler: (data: TData) => void): this {
+		this.#onSuccess.push(handler);
+		return this;
+	}
+
+	onFail(handler: (error: unknown) => void): this {
+		this.#onFail.push(handler);
+		return this;
+	}
+
+	onSettled(handler: () => void): this {
+		this.#onSettled.push(handler);
+		return this;
+	}
+
+	reset(): void {
+		this.#runId++; // invalidate any in-flight run so it can't write back
+		this.#data(null);
+		this.#error(null);
+		this.#loading(false);
+	}
+
+	async run(...args: TArgs): Promise<void> {
+		const id = ++this.#runId;
+		this.#loading(true);
+		this.#error(null);
+		try {
+			const result = await this.#task(...args);
+			if (id !== this.#runId) return; // superseded by a newer run — drop
+			this.#data(result);
+			for (const handler of this.#onSuccess) handler(result);
+		} catch (error) {
+			if (id !== this.#runId) return; // superseded — drop
+			this.#error(error);
+			for (const handler of this.#onFail) handler(error);
+		} finally {
+			if (id === this.#runId) {
+				this.#loading(false);
+				for (const handler of this.#onSettled) handler();
+			}
+		}
+	}
+}
+
+/**
+ * Create a re-runnable {@link Command} around an async `task`. See the module
+ * doc for usage.
+ */
+export function command<TArgs extends unknown[], TData>(
+	task: (...args: TArgs) => Promise<TData>,
+): Command<TArgs, TData> {
+	return new CommandRunner(task);
+}

package/src/form.ts

@@ -0,0 +1,203 @@
+/**
+ * `form()` — a minimal reactive form controller: per-field `value` / `error` /
+ * `touched` signals, validation, and a submit driven by {@link command} (so the
+ * submit's `loading` / `error` are reactive too). Call sites bind the signals in
+ * `html\`\`` and never hand-roll field state or try/catch.
+ *
+ * Validation is OPTIONAL and **agnostic**: pass a `validate` function returning a
+ * `{ field: message }` map, OR any object with a `.validate(values)` method
+ * (e.g. a `@c9up/rune` schema) — aurora never imports a validator, it only
+ * duck-types `.validate`. With no `validate`, the form simply never reports field
+ * errors. Node-free — part of the client barrel.
+ *
+ * ```js
+ * import { form, HttpClient, isHttpError } from '@c9up/aurora'
+ * import { rules, schema } from '@c9up/rune'   // optional
+ * const api = new HttpClient()
+ *
+ * const f = form({
+ *   initial: { email: '', password: '' },
+ *   validate: schema({ email: rules.string().email(), password: rules.string().min(8) }),
+ *   submit: (values) => api.post('/auth/login', values),
+ * })
+ *   .onSuccess(() => redirect('/app'))
+ *   .onFail((e) => { if (isHttpError(e)) f.setErrors(e.data?.errors ?? {}) })
+ *
+ * const email = f.field('email')
+ * // <input value=${email.value} @input=${(e) => email.set(e.target.value)} @blur=${email.markTouched}>
+ * // <button ?disabled=${f.submitting} @click=${(e) => f.handleSubmit(e)}>
+ * ```
+ */
+
+import { command } from "./command.js";
+import { memo, type ReadSignal, signal } from "./reactive.js";
+
+/** A field-keyed error map: `{ email: "Invalid", … }`. Absent key ⇒ no error. */
+export type FieldErrors<T> = Partial<Record<keyof T, string>>;
+
+/** Anything `.validate()`-shaped (a `@c9up/rune` schema satisfies this). */
+export interface FormSchema<T> {
+	validate(values: T): {
+		valid: boolean;
+		errors?: ReadonlyArray<{ field?: string; message: string }>;
+	};
+}
+
+/** Validation source — a function, a schema-like object, or omitted. */
+export type FormValidate<T> = ((values: T) => FieldErrors<T>) | FormSchema<T>;
+
+export interface FormOptions<T> {
+	/** Initial field values; its keys define the form's fields. */
+	initial: T;
+	/** The submit task (wrapped in a {@link command}). */
+	submit: (values: T) => Promise<unknown>;
+	/** Optional, agnostic validation (function OR `.validate`-shaped object). */
+	validate?: FormValidate<T>;
+}
+
+/** A single field's reactive handles + setters. */
+export interface FormField<V> {
+	readonly value: ReadSignal<V>;
+	readonly error: ReadSignal<string | null>;
+	readonly touched: ReadSignal<boolean>;
+	set(value: V): void;
+	markTouched(): void;
+}
+
+export interface Form<T> {
+	readonly values: ReadSignal<T>;
+	readonly errors: ReadSignal<FieldErrors<T>>;
+	/** Whether the last validation found no errors. */
+	readonly valid: ReadSignal<boolean>;
+	/** Whether the submit is in flight (the submit command's loading). */
+	readonly submitting: ReadSignal<boolean>;
+	/** The submit command's last error. */
+	readonly submitError: ReadSignal<unknown>;
+	field<K extends keyof T>(key: K): FormField<T[K]>;
+	set<K extends keyof T>(key: K, value: T[K]): void;
+	/** Run validation now, populate `errors`, and return whether it passed. */
+	validate(): boolean;
+	/** Validate then submit (no-op if invalid). Calls `event.preventDefault()`. */
+	handleSubmit(event?: { preventDefault(): void }): Promise<void>;
+	/** Merge in errors (e.g. server-side field errors from `HttpError.data`). */
+	setErrors(errors: FieldErrors<T>): void;
+	/** Reset values to `initial` and clear errors / touched / submit state. */
+	reset(): void;
+	/** Submit success handler (chainable) — receives the resolved value. */
+	onSuccess(handler: (data: unknown) => void): this;
+	/** Submit failure handler (chainable) — receives the thrown error. */
+	onFail(handler: (error: unknown) => void): this;
+}
+
+/** Normalize any validation source into a field-error map. */
+function computeErrors<T>(
+	validate: FormValidate<T> | undefined,
+	values: T,
+): FieldErrors<T> {
+	if (!validate) return {};
+	if (typeof validate === "function") return validate(values);
+	const result = validate.validate(values);
+	if (result.valid) return {};
+	const errors: Record<string, string> = {};
+	for (const issue of result.errors ?? []) {
+		if (issue.field && !(issue.field in errors)) {
+			errors[issue.field] = issue.message;
+		}
+	}
+	// Boundary: a schema's errors are string-keyed and it doesn't know `keyof T`,
+	// so narrow the validated key space to the form's field type here.
+	return errors as FieldErrors<T>;
+}
+
+class FormController<T> implements Form<T> {
+	readonly #initial: T;
+	readonly #validate?: FormValidate<T>;
+	readonly #values: ReturnType<typeof signal<T>>;
+	readonly #errors = signal<FieldErrors<T>>({});
+	readonly #touched = signal<ReadonlySet<string>>(new Set());
+	readonly #command: ReturnType<typeof command<[T], unknown>>;
+
+	readonly values: ReadSignal<T>;
+	readonly errors: ReadSignal<FieldErrors<T>> = this.#errors;
+	readonly valid: ReadSignal<boolean>;
+	readonly submitting: ReadSignal<boolean>;
+	readonly submitError: ReadSignal<unknown>;
+
+	constructor(options: FormOptions<T>) {
+		this.#initial = { ...options.initial };
+		this.#validate = options.validate;
+		this.#values = signal<T>({ ...options.initial });
+		this.values = this.#values;
+		this.#command = command((values: T) => options.submit(values));
+		this.submitting = this.#command.loading;
+		this.submitError = this.#command.error;
+		this.valid = memo(() =>
+			Object.values(this.#errors()).every((message) => !message),
+		);
+	}
+
+	field<K extends keyof T>(key: K): FormField<T[K]> {
+		return {
+			value: memo(() => this.#values()[key]),
+			error: memo(() => this.#errors()[key] ?? null),
+			touched: memo(() => this.#touched().has(String(key))),
+			set: (value: T[K]) => this.set(key, value),
+			markTouched: () => this.#markTouched(key),
+		};
+	}
+
+	set<K extends keyof T>(key: K, value: T[K]): void {
+		const next = { ...this.#values() };
+		next[key] = value;
+		this.#values(next);
+		// Clear a stale error for this field as the user edits it.
+		if (this.#errors()[key] !== undefined) {
+			const errors = { ...this.#errors() };
+			delete errors[key];
+			this.#errors(errors);
+		}
+	}
+
+	validate(): boolean {
+		const errors = computeErrors(this.#validate, this.#values());
+		this.#errors(errors);
+		return Object.values(errors).every((message) => !message);
+	}
+
+	async handleSubmit(event?: { preventDefault(): void }): Promise<void> {
+		event?.preventDefault();
+		this.#touched(new Set(Object.keys(this.#values() as object)));
+		if (!this.validate()) return;
+		await this.#command.run(this.#values());
+	}
+
+	setErrors(errors: FieldErrors<T>): void {
+		this.#errors({ ...this.#errors(), ...errors });
+	}
+
+	reset(): void {
+		this.#values({ ...this.#initial });
+		this.#errors({});
+		this.#touched(new Set());
+		this.#command.reset();
+	}
+
+	onSuccess(handler: (data: unknown) => void): this {
+		this.#command.onSuccess(handler);
+		return this;
+	}
+
+	onFail(handler: (error: unknown) => void): this {
+		this.#command.onFail(handler);
+		return this;
+	}
+
+	#markTouched(key: keyof T): void {
+		this.#touched(new Set(this.#touched()).add(String(key)));
+	}
+}
+
+/** Create a reactive {@link Form} controller. See the module doc for usage. */
+export function form<T>(options: FormOptions<T>): Form<T> {
+	return new FormController(options);
+}

package/src/index.ts

@@ -34,7 +34,18 @@ export {
 	WebStorage,
 	windowSize,
 } from "./browser.js";
+export type { Command } from "./command.js";
+export { command } from "./command.js";
 export { component, onMount, onUnmount } from "./component.js";
+export type {
+	FieldErrors,
+	Form,
+	FormField,
+	FormOptions,
+	FormSchema,
+	FormValidate,
+} from "./form.js";
+export { form } from "./form.js";
 export { html, isTemplateResult } from "./html.js";
 export type {
 	HttpClientOptions,