@menapo/forms 0.0.0-stage → 0.1.0

package/dist/view--JGPLHEo.js

@@ -0,0 +1,308 @@
+import { n as DEV, t as Instance } from "./instance-C1aijv06.js";
+import { n as get } from "./paths-DqNafpnl.js";
+//#region src/core/view.ts
+var View = class {
+	i;
+	/** The view that made the instance: it owns its lifecycle and options. */
+	own;
+	v = 0;
+	ls = [];
+	/** Kinds read per path, and form kinds read, since the last reset. */
+	rp = /* @__PURE__ */ new Map();
+	rb = 0;
+	/** The framework's tracker (Vue, Svelte, Solid). */
+	k = void 0;
+	/** The view object handed out, and the version it was made at. */
+	f = void 0;
+	fv = -1;
+	/** One view object for the component's life (Vue, Svelte, Solid, plain code). */
+	keep = false;
+	/** Plain code's subscription, given by the vanilla glue. */
+	u = void 0;
+	constructor(instance, own) {
+		this.i = instance;
+		this.own = own;
+		if (own) instance.ls.push(this);
+	}
+	hear(paths, mask, form) {
+		let moved = (form & this.rb) !== 0;
+		if (!moved) {
+			for (const path of paths) if ((this.rp.get(path) ?? 0) & mask) {
+				moved = true;
+				break;
+			}
+		}
+		if (!moved) return;
+		this.v++;
+		for (const listener of this.ls) listener();
+	}
+	read(path, kind) {
+		this.rp.set(path, (this.rp.get(path) ?? 0) | kind);
+		this.k?.();
+	}
+	readForm(kind) {
+		this.rb |= kind;
+		this.k?.();
+	}
+	/** A render starts: what it reads is what it shows. */
+	restart() {
+		this.rp.clear();
+		this.rb = 0;
+	}
+	current() {
+		if (!this.f || !this.keep && this.fv !== this.v) {
+			this.f = new FormViewImpl(this);
+			this.fv = this.v;
+		}
+		return this.f;
+	}
+	subscribe(listener) {
+		this.ls = [...this.ls, listener];
+		return () => {
+			this.ls = this.ls.filter((l) => l !== listener);
+		};
+	}
+	snapshot() {
+		return this.v;
+	}
+	setProps(props) {
+		if (this.own) this.i.options(props);
+	}
+	mount() {
+		if (!this.i.ls.includes(this)) this.i.ls.push(this);
+		if (this.own) this.i.mount();
+	}
+	unmount() {
+		const at = this.i.ls.indexOf(this);
+		if (at >= 0) this.i.ls.splice(at, 1);
+		if (this.own) this.i.unmount();
+	}
+	commit() {
+		if (this.own) this.i.commit();
+	}
+};
+/** The view object: `f.form`, `f.fields`, `f.errors`… (§5.3). */
+var FormViewImpl = class {
+	$;
+	/** Field views of this version by path, and groups by prefix (`""`, `"address."`). */
+	fs = /* @__PURE__ */ new Map();
+	constructor(view) {
+		this.$ = view;
+	}
+	get form() {
+		this.$.readForm(1);
+		return this.$.i.formParts().form;
+	}
+	get submit() {
+		this.$.readForm(1);
+		return this.$.i.formParts().submit;
+	}
+	get summary() {
+		return this.$.i.formParts().summary;
+	}
+	get fields() {
+		return group(this, "", shapeOf(this.$.i));
+	}
+	get errors() {
+		this.$.readForm(4);
+		return this.$.i.errors();
+	}
+	get error() {
+		this.$.readForm(2);
+		return this.$.i.error;
+	}
+	get pending() {
+		this.$.readForm(1);
+		return this.$.i.pending;
+	}
+	get progress() {
+		this.$.readForm(32);
+		return this.$.i.progress;
+	}
+	get dirty() {
+		this.$.readForm(8);
+		return this.$.i.dp.size > 0;
+	}
+	get data() {
+		this.$.readForm(16);
+		return this.$.i.data;
+	}
+	requestSubmit() {
+		return this.$.i.submit();
+	}
+	reset(values) {
+		this.$.i.reset(values);
+	}
+	subscribe(listener) {
+		const { $ } = this;
+		if ($.u) return $.u.subscribe(listener);
+		return $.subscribe(listener);
+	}
+	stop() {
+		if (this.$.u) this.$.u.stop();
+		else this.$.unmount();
+	}
+};
+var FieldViewImpl = class {
+	$;
+	r;
+	constructor(view, rec) {
+		this.$ = view;
+		this.r = rec;
+	}
+	get name() {
+		return this.r.p;
+	}
+	get id() {
+		return this.$.i.fid(this.r.p);
+	}
+	get value() {
+		this.$.read(this.r.p, 1);
+		return get(this.$.i.v, this.r.p);
+	}
+	get message() {
+		this.$.read(this.r.p, 2);
+		return this.r.e;
+	}
+	get touched() {
+		this.$.read(this.r.p, 4);
+		return this.r.t;
+	}
+	get dirty() {
+		this.$.read(this.r.p, 8);
+		const { dp } = this.$.i;
+		if (dp.has(this.r.p)) return true;
+		const prefix = `${this.r.p}.`;
+		for (const path of dp) if (path.startsWith(prefix)) return true;
+		return false;
+	}
+	get validating() {
+		this.$.read(this.r.p, 16);
+		return this.r.vd > 0;
+	}
+	get control() {
+		return parts(this).control;
+	}
+	get label() {
+		return parts(this).label;
+	}
+	get error() {
+		return parts(this).error;
+	}
+	/**
+	* Read, the hint is rendered, so the control links it. The control may
+	* have been spread already this render: the parts move and the views
+	* that showed them hear it after the render, once per field.
+	*/
+	get hint() {
+		const { r, $ } = this;
+		if (!r.h) {
+			r.h = true;
+			r.ver++;
+			queueMicrotask(() => $.i.tell([r.p], 32, 0));
+		}
+		return parts(this).hint;
+	}
+	get group() {
+		return parts(this).group;
+	}
+	set(value) {
+		const { i } = this.$;
+		if (!this.r.t) {
+			this.r.t = true;
+			i.tell([this.r.p], 4, 0);
+		}
+		i.set(this.r.p, value, false);
+	}
+	option(value) {
+		this.$.read(this.r.p, 34);
+		return this.$.i.optionParts(this.r, value);
+	}
+};
+/** A field's parts, read: they show its baseline, its hint and its error. */
+function parts(field) {
+	field.$.read(field.r.p, 34);
+	return field.$.i.fieldParts(field.r);
+}
+/** The field view at `path`, cached per version; `Field` is the array module's for an array. */
+function fieldAt(form, path, Field = FieldViewImpl) {
+	const { $ } = form;
+	let field = form.fs.get(path);
+	if (!field || field.r !== $.i.r.get(path)) {
+		const rec = $.i.rec(path);
+		rec.k = true;
+		form.fs.set(path, field = new Field($, rec));
+	}
+	return field;
+}
+/** A group's form view and prefix, under a symbol: no input key collides with it. */
+const G = Symbol();
+function define(Class, key, node) {
+	Object.defineProperty(Class.prototype, key, { get() {
+		return at(this[G][0], this[G][1] + key, node);
+	} });
+}
+function child(node, key) {
+	const keys = node.o ??= Object.create(null);
+	if (!keys[key]) {
+		keys[key] = {};
+		if (node.c) define(node.c, key, keys[key]);
+	}
+	return keys[key];
+}
+function fromValue(node, value) {
+	if (Array.isArray(value)) fromValue(node.a ??= {}, value[0]);
+	else if (value?.constructor === Object) for (const key in value) fromValue(child(node, key), value[key]);
+}
+function shapeOf(i) {
+	if (i.sh) return i.sh;
+	const F = i.F;
+	let root = F.sh;
+	if (!root) {
+		root = F.sh = {};
+		for (const pattern in F.f) {
+			let node = root;
+			for (const key of pattern.split(".")) node = key === "*" ? node.a ??= {} : child(node, key);
+			if (F.f[pattern].t === "array") node.a ??= {};
+		}
+	}
+	fromValue(root, i.v);
+	return i.sh = root;
+}
+/** The fields under `prefix`, cached per version. */
+function group(form, prefix, node) {
+	let found = form.fs.get(prefix);
+	if (!found) {
+		let Class = node.c;
+		if (!Class) {
+			Class = node.c = class {
+				[G];
+				constructor(form, prefix) {
+					this[G] = [form, prefix];
+				}
+			};
+			for (const key in node.o) define(Class, key, node.o[key]);
+		}
+		form.fs.set(prefix, found = new Class(form, prefix));
+	}
+	return found;
+}
+/** What lives at `path`: an array's field (with the array module), an object's fields, or a field. */
+function at(form, path, node) {
+	const array = form.$.i.F.a;
+	if (node.a && array) return array(form, path, node.a);
+	if (node.o && !node.a) return group(form, `${path}.`, node);
+	return fieldAt(form, path);
+}
+/** What the glue's adapters create: the owner's view of a new instance, or a child's of a parent view's. */
+const create = (source, N) => (id, props) => {
+	if (source instanceof FormViewImpl) return new View(source.$.i, false);
+	if (DEV && !(source instanceof Object && "x" in source)) throw new Error("[forms:NOT_A_FORM] useForm takes a form(…) definition or a parent's useForm view.");
+	return new View(new Instance(source, id, N, props), true);
+};
+/** Dev only: options as a getter where the framework reads an object on each render. */
+function objectOptions(options, framework) {
+	if (DEV && typeof options === "function") throw new Error(`[forms:OPTIONS] useForm was given options as a function, which only Vue, Svelte and Solid read; in ${framework} pass the options object on each render: useForm(form, { … }).`);
+}
+//#endregion
+export { objectOptions as a, fieldAt as i, at as n, create as r, FieldViewImpl as t };

package/dist/view-5_kyMWP3.d.ts

@@ -0,0 +1,331 @@
+import { S as UseFormOptions, b as ShownError, d as FormOptions, f as FormParts, n as Attrs, o as FieldParts, s as FieldSpec, u as Form$1, x as Spec, y as RouteFormOptions } from "./types-CdCFdlFp.js";
+import { ApiErrorLike, InputOf, MutationRoute, OutputOf, WriteOp } from "@menapo/query";
+import { StandardSchemaV1 } from "@standard-schema/spec";
+//#region ../glue/src/source.d.ts
+/**
+ * What a glue adapter binds to a framework (Adapter pattern): a store that
+ * tells of changes and numbers what a view shows. `@menapo/machine`'s
+ * components implement it; `@menapo/query`, the store and forms will too,
+ * so each framework's subscription code exists once (machine PLAN §5.1).
+ *
+ * The store filters its own change mask: `snapshot()` moves only when
+ * something a view shows changed, so the adapters never compare values.
+ */
+interface Source {
+  /** Calls `listener` after every change; returns the unsubscribe. */
+  subscribe(listener: () => void): () => void;
+  /** A number that moves when what a view shows changed. */
+  snapshot(): number;
+  /** The owner's props, as the component passes them. */
+  setProps(props: object): void;
+  /** After the first commit (and again after React's StrictMode remount): side effects may start. */
+  mount(): void;
+  /** Before the component goes: side effects stop. */
+  unmount(): void;
+  /** After the framework committed the DOM for a change: deferred side effects run. */
+  commit(): void;
+}
+//#endregion
+//#region src/core/form.d.ts
+/** What a call to submit takes: query's `CallOptions`. */
+interface Call {
+  readonly signal: AbortSignal;
+  readonly progress?: ((ratio: number) => void) | undefined;
+}
+/**
+ * How a definition submits (Strategy): a route form sends the raw input,
+ * which the server validates; a function form the validated output (D10).
+ */
+type Kind = (form: Form, input: unknown, output: unknown, call: Call) => Promise<unknown>;
+/** The checks module (D8, D17), present only on definitions with `checks`. */
+interface Checker {
+  /** A field's value changed: check it, debounced. */
+  run(instance: object, path: string, value: unknown): void;
+  /** Before a submit: every check due now, and every one running, settled. */
+  settle(instance: object): Promise<void>;
+  /** The instance unmounted: timers and calls stop. */
+  stop(instance: object): void;
+}
+/** The array module (D14): an array's field, with its items and edits. */
+type ArrayModule = (form: FormViewImpl, path: string, item: Shape) => object;
+/** The plugin's hidden argument: `{ n: "src/forms.ts#editProject", s, f, c, a }`. */
+interface Meta {
+  readonly n?: string;
+  /** The browser schema: the operation's own input (D4), or the function form's. */
+  readonly s?: StandardSchemaV1 | undefined;
+  readonly f?: Spec;
+  readonly c?: Checker;
+  /** Present when the input has an array (the spec's or the defaults'). */
+  readonly a?: ArrayModule;
+}
+type Submit = (values: unknown, options: {
+  readonly signal: AbortSignal;
+}) => unknown;
+declare class Form {
+  readonly "~types"?: {
+    input: unknown;
+    output: unknown;
+    error: unknown;
+  };
+  /** The name, for DevTools and errors. */
+  readonly n: string;
+  readonly s: StandardSchemaV1 | undefined;
+  readonly f: Spec;
+  readonly o: RouteFormOptions<Record<string, unknown>>;
+  readonly c: Checker | undefined;
+  readonly a: ArrayModule | undefined;
+  readonly x: Kind;
+  /** A route form's route, or a function form's submit. */
+  readonly r: string | Submit;
+  /** The input's shape, for `fields`; each instance's values extend it (view.ts). */
+  sh: Shape | undefined;
+  /** A route form's mutation, made by its kind. */
+  m: ((input: unknown, call: Call) => Promise<unknown>) | undefined;
+  constructor(source: string | Submit, schema: StandardSchemaV1 | undefined, options: FormOptions<never> | undefined, meta: Meta | undefined, kind: Kind, init?: (form: Form) => void);
+  get name(): string;
+}
+type Input<S> = S extends StandardSchemaV1<infer I, unknown> ? I : never;
+type Output<S> = S extends StandardSchemaV1<unknown, infer O> ? O : never;
+/**
+ * A form for an operation of the app's API, typed from query's `Register`
+ * (D3), or for anything else, from its Standard Schema.
+ *
+ * ```ts
+ * export const editProject = form("PATCH /projects/:id");
+ * export const contact = form(Contact, (values, { signal }) => send(values, signal));
+ * ```
+ */
+declare function form<S extends MutationRoute>(route: S, options?: RouteFormOptions<InputOf<WriteOp<S>>>): Form$1<InputOf<WriteOp<S>>, OutputOf<WriteOp<S>>, ApiErrorLike>;
+declare function form<S extends StandardSchemaV1, T>(schema: S, submit: (values: Output<S>, options: {
+  readonly signal: AbortSignal;
+}) => T | Promise<T>, options?: FormOptions<Input<S>>): Form$1<Input<S>, Awaited<T>, Error>;
+//#endregion
+//#region src/core/names.d.ts
+interface Names {
+  readonly id: string;
+  readonly name: string;
+  readonly htmlFor: string;
+  readonly tabIndex: string;
+  readonly method: string;
+  readonly encType: string;
+  readonly type: string;
+  readonly value: string;
+  readonly checked: string;
+  readonly required: string;
+  readonly minLength: string;
+  readonly maxLength: string;
+  readonly min: string;
+  readonly max: string;
+  readonly accept: string;
+  readonly multiple: string;
+  readonly onSubmit: string;
+  readonly onReset: string;
+  readonly onClick: string;
+  /** The keys the delegated input handler goes under. */
+  readonly input: readonly string[];
+  readonly blur: string;
+  /** Where a part carries its text (an error's message, a hint's description): JSX's `children`. */
+  readonly text: string | undefined;
+}
+//#endregion
+//#region src/core/instance.d.ts
+/** One field: its error, flags and cached parts. Values live in the instance's tree. */
+declare class Rec {
+  /** Its path: renamed when an array moves its item (D14). */
+  p: string;
+  e: string | undefined;
+  s: number;
+  t: boolean;
+  /** Checks or async validations running. */
+  vd: number;
+  /** A view read the hint: it is rendered, so the control links it. */
+  h: boolean;
+  /** A view asked for it, or the DOM has its control: issues at its path are its own. */
+  k: boolean;
+  /** Moves with what the parts show. */
+  ver: number;
+  pc: FieldParts | undefined;
+  pv: number;
+  oc: Map<unknown, {
+    control: Attrs;
+    label: Attrs;
+  }> | undefined;
+  constructor(path: string);
+}
+/** What an instance tells its views: the paths that moved, the field kinds and the form kinds. */
+interface Listener {
+  hear(paths: readonly string[], mask: number, form: number): void;
+}
+type Control = HTMLInputElement | HTMLSelectElement | HTMLTextAreaElement;
+declare class Instance {
+  #private;
+  readonly F: Form;
+  /** The DOM id the form's ids derive from. */
+  readonly id: string;
+  readonly N: Names;
+  /** Values: an immutable tree (paths.ts). */
+  v: Record<string, unknown>;
+  /** What `dirty` compares against: the defaults, then the last success's values. */
+  b: Record<string, unknown>;
+  /** The merged defaults (D11). */
+  d: Record<string, unknown>;
+  /** The hook's own `defaults`, as last given: a new object is followed. */
+  hd: unknown;
+  readonly r: Map<string, Rec>;
+  /** Paths whose value differs from the baseline. */
+  readonly dp: Set<string>;
+  readonly ls: Listener[];
+  onSuccess: ((data: unknown) => void) | undefined;
+  pending: boolean;
+  error: unknown;
+  /** The form error came from the schema (an issue with no field), so a valid run clears it. */
+  ce: boolean;
+  data: unknown;
+  progress: number;
+  /** A submit was attempted: errors now update on input and blur (D8). */
+  at: boolean;
+  /** The order of paths in the last issues, for `errors`. */
+  ord: string[];
+  /** `errors`, cached until an error changes. */
+  ec: ShownError[] | undefined;
+  /** Full validations started; a result for an older one is dropped. */
+  vv: number;
+  ac: AbortController | undefined;
+  /** After the next commit: focus the summary or the first invalid control (D12). */
+  fo: boolean;
+  /** Messages to announce after the next commit. */
+  an: string[];
+  /** Inside a submit: errors are announced by focus, not the live region. */
+  inSubmit: boolean;
+  mounted: boolean;
+  /** The form parts, cached by `pending`. */
+  fp: FormParts | undefined;
+  /** The delegated handlers, made with the first parts so their identity never changes (D6). */
+  hs: Readonly<Record<"i" | "b" | "s" | "r" | "c", (event: Event) => void>> | undefined;
+  fpv: boolean | undefined;
+  /** The array module's stable keys, by array path (D14). */
+  ak: Map<string, string[]> | undefined;
+  /** The checks module's state (D8). */
+  ck: unknown;
+  /** The definition's shape, once these values extended it (view.ts). */
+  sh: Shape | undefined;
+  constructor(F: Form, id: string, N: Names, options: UseFormOptions<unknown, unknown> | undefined);
+  rec(path: string): Rec;
+  spec(path: string): FieldSpec | undefined;
+  fid(path: string): string;
+  tell(paths: readonly string[], mask: number, form: number): void;
+  /** Every view moves: a reset, new defaults. */
+  all(): void;
+  /** Recomputes whether `path` is dirty; the form's bit when the set changed size between empty and not. */
+  dirty(path: string): number;
+  /** Writes a value: from the DOM (`dom`), or from code, which also writes the control. */
+  set(path: string, value: unknown, dom: boolean): void;
+  blur(el: Control): void;
+  /** Sets a field's error: one place, so the live region and the summary follow every change. */
+  error_(rec: Rec, message: string | undefined, source: number): boolean;
+  submit(): Promise<unknown>;
+  reset(values?: unknown): void;
+  /** The hook's options again (D11): pristine fields follow new defaults; edited ones keep their text. */
+  options(options: UseFormOptions<unknown, unknown> | undefined): void;
+  mount(): void;
+  unmount(): void;
+  /** After the framework committed: focus after a failed submit, then announcements (D12). */
+  commit(): void;
+  formParts(): FormParts;
+  /** A field's parts, rebuilt only when what they show moved; each one made when first read. */
+  fieldParts(rec: Rec): FieldParts;
+  /**
+   * The control's attributes (§5.3): id, name, value, aria wiring and
+   * constraints (D13). The value is the current one, not the baseline, so
+   * a server's `state` renders what was posted.
+   */
+  control(rec: Rec): Attrs;
+  /** One radio, or one checkbox of an array field. */
+  optionParts(rec: Rec, value: unknown): {
+    control: Attrs;
+    label: Attrs;
+  };
+  /** The errors shown, in the order the last issues listed them. */
+  errors(): ShownError[];
+}
+//#endregion
+//#region src/core/view.d.ts
+declare class View implements Source, Listener {
+  readonly i: Instance;
+  /** The view that made the instance: it owns its lifecycle and options. */
+  readonly own: boolean;
+  v: number;
+  ls: readonly (() => void)[];
+  /** Kinds read per path, and form kinds read, since the last reset. */
+  readonly rp: Map<string, number>;
+  rb: number;
+  /** The framework's tracker (Vue, Svelte, Solid). */
+  k: (() => unknown) | undefined;
+  /** The view object handed out, and the version it was made at. */
+  f: FormViewImpl | undefined;
+  fv: number;
+  /** One view object for the component's life (Vue, Svelte, Solid, plain code). */
+  keep: boolean;
+  /** Plain code's subscription, given by the vanilla glue. */
+  u: {
+    subscribe(listener: () => void): () => void;
+    stop(): void;
+  } | undefined;
+  constructor(instance: Instance, own: boolean);
+  hear(paths: readonly string[], mask: number, form: number): void;
+  read(path: string, kind: number): void;
+  readForm(kind: number): void;
+  /** A render starts: what it reads is what it shows. */
+  restart(): void;
+  current(): FormViewImpl;
+  subscribe(listener: () => void): () => void;
+  snapshot(): number;
+  setProps(props: object): void;
+  mount(): void;
+  unmount(): void;
+  commit(): void;
+}
+/** The view object: `f.form`, `f.fields`, `f.errors`… (§5.3). */
+declare class FormViewImpl {
+  readonly $: View;
+  /** Field views of this version by path, and groups by prefix (`""`, `"address."`). */
+  readonly fs: Map<string, object>;
+  constructor(view: View);
+  get form(): Attrs;
+  get submit(): Attrs;
+  get summary(): Attrs;
+  get fields(): object;
+  get errors(): readonly {
+    path: string;
+    message: string;
+    href: string;
+  }[];
+  get error(): unknown;
+  get pending(): boolean;
+  get progress(): number;
+  get dirty(): boolean;
+  get data(): unknown;
+  requestSubmit(): Promise<unknown>;
+  reset(values?: unknown): void;
+  subscribe(listener: () => void): () => void;
+  stop(): void;
+}
+/**
+ * The input's shape (D7): which keys are leaves, objects or arrays, from
+ * the field spec's patterns (the schema's) and the values (the defaults,
+ * or a server's `state`). One per definition, which each instance's values
+ * extend. Each object node gets a class whose keys are getters on its
+ * prototype, so `f.fields` costs one object and a read of `f.fields.name`
+ * makes that field's view only. Getters, not a Proxy: a key read stays a
+ * plain property read, and the keys are known up front.
+ */
+interface Shape {
+  /** An object's keys; no prototype, so a key named `constructor` is a key. */
+  o?: Record<string, Shape>;
+  /** An array's item. */
+  a?: Shape;
+  /** An object node's fields class, once made. */
+  c?: new (form: FormViewImpl, prefix: string) => object;
+}
+//#endregion
+export { Meta as a, Form as i, Shape as n, form as o, Checker as r, FormViewImpl as t };

package/dist/vite.d.ts

@@ -0,0 +1,20 @@
+import { Plugin } from "vite";
+//#region src/vite/index.d.ts
+/**
+ * The frameworks `useForm` has glue for. Written out because the published
+ * types cannot name the private `@menapo/glue`; the check below fails the
+ * type-check the moment the two differ.
+ */
+export type Framework = "react" | "preact" | "vue" | "svelte" | "solid" | "vanilla";
+export interface FormsPluginOptions {
+  /**
+   * The framework of plain `.js`/`.ts` modules that call `useForm`.
+   * Default: the framework the root `package.json` depends on, else none
+   * (vanilla). `.vue`, `.svelte` and JSX modules go by their own.
+   */
+  readonly framework?: Framework;
+}
+/** `plugins: [forms()]` in a Vite config, beside api's and query's. */
+export declare function forms(options?: FormsPluginOptions): Plugin[];
+//#endregion
+export { forms as default };