@menapo/forms 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 menapo
+
+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,46 @@
-# Temporary Holding Version
+# @menapo/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.
+Form state for kit apps: `form("PATCH /projects/:id")` is a form typed and
+validated by the app's own `@menapo/api` operation, submitted through
+`@menapo/query`'s mutation, with the server's field issues on their fields;
+`form(schema, submit)` is one for anything else. Controls are uncontrolled
+and the `<form>` listens once, so typing re-renders nothing that doesn't
+show the change; every control gets its ids and `aria-*` from its parts,
+and a failed submit moves focus. Read with `useForm` in React, Preact, Vue,
+Svelte, Solid and plain code.
+
+**Status: built, private until 1.0.** Definitions, validation timing,
+server issues, defaults that follow a query, rows, uploads, checks, the
+plugin (the browser's copy of each operation's input schema, cut from its
+module; constraint attributes from its JSON Schema; glue for six
+frameworks), `/server`'s `action()` and the DevTools panel are implemented
+and tested; `examples/forms-react` and `examples/forms-svelte` run in
+Chromium with axe. The release waits on the owner's review.
+
+```ts
+// forms.ts: no framework, no second schema
+export const newOrg = form("POST /orgs");
+export const contact = form(Contact, (values, { signal }) => send(values, signal));
+```
+
+```tsx
+const f = useForm(newOrg, { onSuccess: (org) => navigate(`/${org.slug}`) });
+const { name, slug } = f.fields;
+<form {...f.form}>
+  <label {...name.label}>Name</label>
+  <input {...name.control} />
+  <p {...name.error} />
+  <label {...slug.label}>Address</label>
+  <input {...slug.control} />
+  <p {...slug.hint}>Lowercase letters and dashes</p>
+  <p {...slug.error} />
+  <button {...f.submit}>Create</button>
+</form>;
+```
+
+- [Guide](docs/guide/README.md): getting started and the reference.
+- [Plan](docs/PLAN.md): the design, the decisions and the measurements.
+- Entries: `@menapo/forms` (`form`, `useForm`, `inspect`, types),
+  `@menapo/forms/server` (`action`, `decode`), `@menapo/forms/vite`.
+
+MIT licensed.

package/dist/array.d.ts

@@ -0,0 +1,5 @@
+import { n as Shape, t as FormViewImpl } from "./view-5_kyMWP3.js";
+//#region src/array/index.d.ts
+/** The field of the array at `path` (`Meta.a`): a field, and its items. */
+export declare function arrayField(form: FormViewImpl, path: string, item: Shape): object;
+//#endregion

package/dist/array.js

@@ -0,0 +1,101 @@
+import { n as get, s as set } from "./paths-DqNafpnl.js";
+import { i as fieldAt, n as at, t as FieldViewImpl } from "./view--JGPLHEo.js";
+//#region src/array/index.ts
+/**
+* Field arrays (D14): `f.fields.invites` is a field with stable `keys` to
+* render rows by, its `items`' fields, and `append`, `insert`, `remove`
+* and `move`. A field's state (error, touched, dirty) follows its item,
+* not its index: the records under a moved item are renamed with it, and
+* its row keeps its key, so the uncontrolled controls keep their text. A
+* module of its own, which the plugin hands only a form whose input has an
+* array, so a form without one ships none of it (AGENTS.md: features are
+* modules).
+*/
+let next = 0;
+/** The keys of the array at `path`, as many as it has items. */
+function keysOf(i, path) {
+	const all = i.ak ??= /* @__PURE__ */ new Map();
+	let keys = all.get(path);
+	if (!keys) all.set(path, keys = []);
+	const length = get(i.v, path)?.length ?? 0;
+	while (keys.length < length) keys.push(`k${++next}`);
+	keys.length = length;
+	return keys;
+}
+/** Renames what lives under `path.<index>` to where `order` now has that index; gone, it drops. */
+function remap(i, path, order) {
+	const prefix = `${path}.`;
+	const rename = (p) => {
+		if (!p.startsWith(prefix)) return p;
+		const [, index, rest] = /^(\d+)(.*)$/s.exec(p.slice(prefix.length)) ?? [];
+		const moved = order.indexOf(Number(index));
+		return moved < 0 ? void 0 : prefix + moved + rest;
+	};
+	const records = [...i.r.values()];
+	i.r.clear();
+	for (const rec of records) {
+		const p = rename(rec.p);
+		if (p === void 0) continue;
+		if (p !== rec.p) {
+			rec.p = p;
+			rec.ver++;
+		}
+		i.r.set(p, rec);
+	}
+	const dirty = [...i.dp];
+	i.dp.clear();
+	for (const p of dirty) {
+		const renamed = rename(p);
+		if (renamed !== void 0) i.dp.add(renamed);
+	}
+	i.dirty(path);
+	i.ord = i.ord.map(rename).filter((p) => p !== void 0);
+}
+/**
+* Applies `change` to the array (with `item`), to its keys (with a new key)
+* and to the old indexes, which then say where each record moves: one
+* rule for the four edits rather than an index formula per edit.
+*/
+function edit(i, path, item, change) {
+	const list = [...get(i.v, path) ?? []];
+	const order = list.map((_, index) => index);
+	change(list, item);
+	change(order, -1);
+	change(keysOf(i, path), `k${++next}`);
+	i.v = set(i.v, path, list);
+	remap(i, path, order);
+	i.all();
+}
+var ArrayFieldImpl = class extends FieldViewImpl {
+	/** The form view, for its items' cached views, and the item's shape. */
+	f = void 0;
+	s = {};
+	get keys() {
+		this.$.read(this.r.p, 64);
+		return keysOf(this.$.i, this.r.p);
+	}
+	get items() {
+		return this.keys.map((_, n) => at(this.f, `${this.r.p}.${n}`, this.s));
+	}
+	append(item) {
+		edit(this.$.i, this.r.p, item, (list, it) => void list.push(it));
+	}
+	insert(index, item) {
+		edit(this.$.i, this.r.p, item, (list, it) => void list.splice(index, 0, it));
+	}
+	remove(index) {
+		edit(this.$.i, this.r.p, void 0, (list) => void list.splice(index, 1));
+	}
+	move(from, to) {
+		edit(this.$.i, this.r.p, void 0, (list) => void list.splice(to, 0, ...list.splice(from, 1)));
+	}
+};
+/** The field of the array at `path` (`Meta.a`): a field, and its items. */
+function arrayField(form, path, item) {
+	const field = fieldAt(form, path, ArrayFieldImpl);
+	field.f = form;
+	field.s = item;
+	return field;
+}
+//#endregion
+export { arrayField };

package/dist/checks.d.ts

@@ -0,0 +1,4 @@
+import { r as Checker } from "./view-5_kyMWP3.js";
+//#region src/checks/index.d.ts
+export declare const checks: Checker;
+//#endregion

package/dist/checks.js

@@ -0,0 +1,53 @@
+//#region src/checks/index.ts
+const DEBOUNCE = 300;
+function start(i, path, run) {
+	run.t = void 0;
+	const controller = run.c = new AbortController();
+	const rec = i.rec(path);
+	const done = (message) => {
+		if (controller.signal.aborted) return;
+		run.c = void 0;
+		rec.vd--;
+		const changed = i.error_(rec, typeof message === "string" ? message : void 0, 1);
+		i.tell([path], 16 | (changed ? 34 : 0), changed ? 4 : 0);
+	};
+	run.p = Promise.resolve().then(() => run.k(run.v, { signal: controller.signal })).then(done, () => done(void 0));
+}
+const checks = {
+	run(instance, path, value) {
+		const i = instance;
+		const check = i.F.o.checks?.[path];
+		if (!check) return;
+		const all = i.ck ??= /* @__PURE__ */ new Map();
+		let run = all.get(path);
+		if (!run) all.set(path, run = { k: check });
+		if (!run.t && !run.c) {
+			i.rec(path).vd++;
+			i.tell([path], 16, 0);
+		}
+		clearTimeout(run.t);
+		run.c?.abort();
+		run.v = value;
+		const due = run;
+		run.t = setTimeout(() => start(i, path, due), DEBOUNCE);
+	},
+	async settle(instance) {
+		const waiting = [];
+		for (const [path, run] of instance.ck ?? []) {
+			if (run.t !== void 0) {
+				clearTimeout(run.t);
+				start(instance, path, run);
+			}
+			if (run.c) waiting.push(run.p);
+		}
+		await Promise.all(waiting);
+	},
+	stop(instance) {
+		for (const run of instance.ck?.values() ?? []) {
+			clearTimeout(run.t);
+			run.c?.abort();
+		}
+	}
+};
+//#endregion
+export { checks };

package/dist/factories/fn.d.ts

@@ -0,0 +1,8 @@
+import { a as Meta, i as Form } from "../view-5_kyMWP3.js";
+import { d as FormOptions } from "../types-CdCFdlFp.js";
+import { StandardSchemaV1 } from "@standard-schema/spec";
+//#region src/factories/fn.d.ts
+type Submit = ConstructorParameters<typeof Form>[0];
+export declare const fnForm: (schema: StandardSchemaV1, submit: Submit, options?: FormOptions<never>, meta?: Meta) => Form;
+//#endregion
+export {};

package/dist/factories/fn.js

@@ -0,0 +1,5 @@
+import { n as fnKind, t as Form } from "../form-BZ2OH06z.js";
+//#region src/factories/fn.ts
+const fnForm = (schema, submit, options, meta) => new Form(submit, schema, options, meta, fnKind);
+//#endregion
+export { fnForm };

package/dist/factories/route.d.ts

@@ -0,0 +1,5 @@
+import { a as Meta, i as Form } from "../view-5_kyMWP3.js";
+import { d as FormOptions } from "../types-CdCFdlFp.js";
+//#region src/factories/route.d.ts
+export declare const routeForm: (route: string, options?: FormOptions<never>, meta?: Meta) => Form;
+//#endregion

package/dist/factories/route.js

@@ -0,0 +1,31 @@
+import { t as Form } from "../form-BZ2OH06z.js";
+import * as query from "@menapo/query";
+//#region src/route/index.ts
+/**
+* Route forms (D2): `form("PATCH /projects/:id")` submits through
+* `@menapo/query`'s `mutation()`, so the convention's refresh, the
+* optimistic journal, upload progress, `ApiError` and the request's client
+* on a server (`withClient`) are query's, not a second copy here. The raw
+* input is sent; the server validates it (D10). Only route forms import
+* this module, so a function form ships nothing of query (D17).
+*/
+/** Makes the definition's mutation, with `optimistic` and `refresh` passed through unchanged. */
+function routeInit(form) {
+	const { optimistic, refresh } = form.o;
+	form.m = query.mutation(form.r, {
+		...optimistic && { optimistic },
+		...refresh && { refresh }
+	});
+}
+const routeKind = (form, input, _output, call) => form.m(input, call);
+//#endregion
+//#region src/factories/route.ts
+/**
+* The route form's factory (D17): what the plugin points a top-level
+* `form("METHOD /path")` at, with its hidden last argument (the name, the
+* operation's browser schema, D4, and the field spec, D13). Internal:
+* resolved by file, never a package entry.
+*/
+const routeForm = (route, options, meta) => new Form(route, void 0, options, meta, routeKind, routeInit);
+//#endregion
+export { routeForm };

package/dist/form-BZ2OH06z.js

@@ -0,0 +1,48 @@
+import { i as fail } from "./instance-C1aijv06.js";
+import { arrayField } from "./array.js";
+import { checks } from "./checks.js";
+//#region src/core/form.ts
+var Form = class {
+	/** The name, for DevTools and errors. */
+	n;
+	s;
+	f;
+	o;
+	c;
+	a;
+	x;
+	/** A route form's route, or a function form's submit. */
+	r;
+	/** The input's shape, for `fields`; each instance's values extend it (view.ts). */
+	sh = void 0;
+	/** A route form's mutation, made by its kind. */
+	m = void 0;
+	constructor(source, schema, options, meta, kind, init) {
+		this.r = source;
+		this.s = meta?.s ?? schema;
+		this.f = meta?.f ?? {};
+		this.o = options ?? {};
+		this.c = meta?.c;
+		this.a = meta?.a;
+		this.x = kind;
+		this.n = meta?.n ?? (typeof source === "string" ? `form("${source}")` : "form(schema, submit)");
+		init?.(this);
+	}
+	get name() {
+		return this.n;
+	}
+};
+/** A function form's kind: `submit(output, { signal })` (D10). */
+const fnKind = async (form, _input, output, call) => form.r(output, { signal: call.signal });
+/** A route form without the plugin: its kind lives in `route/`, which only the plugin points it at. */
+const noRoute = (form) => Promise.reject(fail("NO_PLUGIN", `${form.n} submits through @menapo/query, which the Vite plugin wires; add forms() from "@menapo/forms/vite" to vite.config.ts.`));
+function form(a, b, c) {
+	const options = typeof a === "string" ? b : c;
+	const meta = options?.checks ? {
+		a: arrayField,
+		c: checks
+	} : { a: arrayField };
+	return typeof a === "string" ? new Form(a, void 0, options, meta, noRoute) : new Form(b, a, options, meta, fnKind);
+}
+//#endregion
+export { fnKind as n, form as r, Form as t };

package/dist/glue/preact.d.ts

@@ -0,0 +1,4 @@
+import { i as Form, t as FormViewImpl } from "../view-5_kyMWP3.js";
+//#region src/glue/preact.d.ts
+export declare function useForm(source: Form | FormViewImpl, options?: object): FormViewImpl;
+//#endregion

package/dist/glue/preact.js

@@ -0,0 +1,59 @@
+import { a as objectOptions, r as create } from "../view--JGPLHEo.js";
+import { n as jsx, t as names } from "../names-D_TE3BpM.js";
+import { n as same } from "../source-DdFTPjID.js";
+import { useId, useLayoutEffect, useState } from "preact/hooks";
+//#region ../glue/src/preact.ts
+/**
+* Preact (machine PLAN §5.5): React's shape on `preact/hooks`, which has no
+* `useSyncExternalStore`: a state update when the snapshot moved, checked
+* again once subscribed so a change between render and subscription is not
+* lost. Side effects start in a layout effect, props are taken after each
+* commit.
+*/
+function useSource(create, props) {
+	const id = useId();
+	const [binding] = useState(() => ({
+		source: create(id, props),
+		seen: 0,
+		props
+	}));
+	const [, render] = useState(0);
+	const { source } = binding;
+	binding.seen = source.snapshot();
+	useLayoutEffect(() => {
+		const check = () => {
+			const now = source.snapshot();
+			if (now !== binding.seen) render(now);
+		};
+		const off = source.subscribe(check);
+		source.mount();
+		check();
+		return () => {
+			off();
+			source.unmount();
+		};
+	}, [source]);
+	useLayoutEffect(() => {
+		if (props && !same(props, binding.props)) source.setProps(binding.props = props);
+		source.commit();
+	});
+	return source;
+}
+//#endregion
+//#region src/glue/preact.ts
+/**
+* `useForm` in Preact (PLAN §5.2): the shared glue's hooks
+* adapter. Reads are tracked again on each render, so the component renders
+* only when something it read changed; the view object is new per version
+* (as in React). Options are taken after each
+* commit, so a render that never commits changes nothing.
+*/
+const N = names(jsx, false, true);
+function useForm(source, options) {
+	objectOptions(options, "Preact");
+	const view = useSource(create(source, N), options);
+	view.restart();
+	return view.current();
+}
+//#endregion
+export { useForm };

package/dist/glue/react.d.ts

@@ -0,0 +1,4 @@
+import { i as Form, t as FormViewImpl } from "../view-5_kyMWP3.js";
+//#region src/glue/react.d.ts
+export declare function useForm(source: Form | FormViewImpl, options?: object): FormViewImpl;
+//#endregion

package/dist/glue/react.js

@@ -0,0 +1,55 @@
+import { a as objectOptions, r as create } from "../view--JGPLHEo.js";
+import { i as react, t as names } from "../names-D_TE3BpM.js";
+import { n as same } from "../source-DdFTPjID.js";
+import { useId, useLayoutEffect, useState, useSyncExternalStore } from "react";
+//#region ../glue/src/react.ts
+/**
+* React (machine PLAN §5.5, spike S3): the source lives in `useState`, so a
+* render React throws away (StrictMode, a concurrent render) never mutates
+* a live one; `useSyncExternalStore` renders once per snapshot move and
+* never tears; side effects start in a layout effect, after the DOM is
+* committed, and stop on unmount (StrictMode's mount, unmount and mount
+* leave one running). Props are taken after each commit, so a render that
+* never commits never changes the source. No `flushSync`.
+*/
+function useSource(create, props) {
+	const id = useId();
+	const [binding] = useState(() => {
+		const source = create(id, props);
+		return {
+			source,
+			subscribe: (listener) => source.subscribe(listener),
+			snapshot: () => source.snapshot(),
+			props
+		};
+	});
+	const { source } = binding;
+	useSyncExternalStore(binding.subscribe, binding.snapshot, binding.snapshot);
+	useLayoutEffect(() => {
+		source.mount();
+		return () => source.unmount();
+	}, [source]);
+	useLayoutEffect(() => {
+		if (props && !same(props, binding.props)) source.setProps(binding.props = props);
+		source.commit();
+	});
+	return source;
+}
+//#endregion
+//#region src/glue/react.ts
+/**
+* `useForm` in React (PLAN §5.2): the shared glue's `useSyncExternalStore`
+* adapter. Reads are tracked again on each render, so the component renders
+* only when something it read changed; the view object is new per version
+* (React's Compiler compares by identity). Options are taken after each
+* commit, so a render that never commits changes nothing.
+*/
+const N = names(react, true);
+function useForm(source, options) {
+	objectOptions(options, "React");
+	const view = useSource(create(source, N), options);
+	view.restart();
+	return view.current();
+}
+//#endregion
+export { useForm };

package/dist/glue/solid.d.ts

@@ -0,0 +1,4 @@
+import { i as Form, t as FormViewImpl } from "../view-5_kyMWP3.js";
+//#region src/glue/solid.d.ts
+export declare function useForm(source: Form | FormViewImpl, options?: object | (() => object)): FormViewImpl;
+//#endregion

package/dist/glue/solid.js

@@ -0,0 +1,48 @@
+import { r as create } from "../view--JGPLHEo.js";
+import { n as jsx, t as names } from "../names-D_TE3BpM.js";
+import { createComputed, createSignal, createUniqueId, onCleanup, onMount, untrack } from "solid-js";
+//#region ../glue/src/solid.ts
+/**
+* Solid (machine PLAN §5.5): a signal holding the snapshot, read through
+* the returned tracker, so only the computations that read it re-run, and
+* Solid's own spread applies only the attributes that changed. Props given
+* as a function are read in a computation; side effects start in `onMount`
+* and run after each change, once Solid has updated the DOM.
+*/
+function useSource(create, props) {
+	const read = typeof props === "function" ? props : void 0;
+	const source = create(createUniqueId(), read ? untrack(read) : props);
+	const [version, set] = createSignal(source.snapshot());
+	const commit = () => source.commit();
+	const off = source.subscribe(() => {
+		set(source.snapshot());
+		queueMicrotask(commit);
+	});
+	if (read) createComputed(() => {
+		const next = read();
+		untrack(() => source.setProps(next));
+	});
+	onMount(() => source.mount());
+	onCleanup(() => {
+		off();
+		source.unmount();
+	});
+	return [source, version];
+}
+//#endregion
+//#region src/glue/solid.ts
+/**
+* `useForm` in Solid (PLAN §5.2): the shared glue's signal adapter;
+* every read calls the tracker, and options given as a getter are watched,
+* so pristine fields follow new defaults (D11). Handlers are named
+* `onInput`, `onFocusOut`, which Solid lowercases.
+*/
+const N = names(jsx, false, true);
+function useForm(source, options) {
+	const [view, track] = useSource(create(source, N), options);
+	view.k = track;
+	view.keep = true;
+	return view.current();
+}
+//#endregion
+export { useForm };

package/dist/glue/svelte.svelte.d.ts

@@ -0,0 +1,4 @@
+import { i as Form, t as FormViewImpl } from "../view-5_kyMWP3.js";
+//#region src/glue/svelte.svelte.d.ts
+export declare function useForm(source: Form | FormViewImpl, options?: object | (() => object)): FormViewImpl;
+//#endregion

package/dist/glue/svelte.svelte.js

@@ -0,0 +1,62 @@
+import { r as create } from "../view--JGPLHEo.js";
+import { r as lower, t as names } from "../names-D_TE3BpM.js";
+import { t as nextId } from "../source-DdFTPjID.js";
+import { onMount, tick, untrack } from "svelte";
+import { createSubscriber } from "svelte/reactivity";
+//#region ../glue/src/svelte.svelte.ts
+/**
+* Svelte 5 (machine PLAN §5.5): `createSubscriber` re-runs the effects and
+* deriveds that read the tracker when the snapshot moves; props given as a
+* getter are taken in `$effect.pre`, before the DOM updates. Side effects
+* start in `onMount` and run after each update that follows a change.
+* Svelte gives a module no id of its own, so ids come from a counter (or
+* the owner's `id`, which SSR needs).
+*/
+function useSource(create, props) {
+	const read = typeof props === "function" ? props : void 0;
+	const source = create(nextId(), read ? read() : props);
+	let update;
+	let seen = source.snapshot();
+	const track = createSubscriber((u) => {
+		update = u;
+		return () => update = void 0;
+	});
+	const commit = () => source.commit();
+	const off = source.subscribe(() => {
+		const now = source.snapshot();
+		if (now !== seen) {
+			seen = now;
+			update?.();
+		}
+		tick().then(commit);
+	});
+	if (read) $effect.pre(() => {
+		const next = read();
+		untrack(() => source.setProps(next));
+	});
+	onMount(() => {
+		source.mount();
+		return () => {
+			off();
+			source.unmount();
+		};
+	});
+	return [source, track];
+}
+//#endregion
+//#region src/glue/svelte.svelte.ts
+/**
+* `useForm` in Svelte 5 (PLAN §5.2): the shared glue's `createSubscriber` adapter;
+* every read calls the tracker, and options given as a getter are watched,
+* so pristine fields follow new defaults (D11). Handlers are named
+* `oninput`, `onfocusout` (glue's naming).
+*/
+const N = names(lower, false);
+function useForm(source, options) {
+	const [view, track] = useSource(create(source, N), options);
+	view.k = track;
+	view.keep = true;
+	return view.current();
+}
+//#endregion
+export { useForm };

package/dist/glue/vanilla.d.ts

@@ -0,0 +1,4 @@
+import { i as Form, t as FormViewImpl } from "../view-5_kyMWP3.js";
+//#region src/glue/vanilla.d.ts
+export declare function useForm(source: Form | FormViewImpl, options?: object): FormViewImpl;
+//#endregion