@menapo/forms 0.0.0-stage → 0.1.0

package/dist/names-D_TE3BpM.js

@@ -0,0 +1,62 @@
+//#region ../glue/src/naming.ts
+/** React's names whose DOM name is not their lowercase form. */
+const DOM = {
+	htmlFor: "for",
+	className: "class",
+	onDoubleClick: "onDblClick"
+};
+/** React's name as the DOM spells it, still camel-cased: `htmlFor` is `for`, `onDoubleClick` `onDblClick`. */
+const dom = (key) => DOM[key] ?? key;
+/** React: names as written. */
+const react = (key) => key;
+/** Preact and Solid take React's names but the DOM's attributes, and lowercase an event's name themselves. */
+const jsx = dom;
+/** Svelte and the DOM itself: lowercase (`onclick`, `tabindex`, `for`). */
+const lower = (key) => dom(key).toLowerCase();
+/**
+* Vue derives an event's name from the rest of an `on…` key, hyphenating
+* capitals (`onKeyDown` would listen for `key-down`), so a handler is
+* `onKeydown`; other names stay, but for the DOM's attributes.
+*/
+const vue = (key) => {
+	const name = dom(key);
+	return /^on[A-Z]/.test(name) ? name.slice(0, 3) + name.slice(3).toLowerCase() : name;
+};
+//#endregion
+//#region src/core/names.ts
+const KEYS = [
+	"id",
+	"name",
+	"htmlFor",
+	"tabIndex",
+	"method",
+	"encType",
+	"type",
+	"required",
+	"minLength",
+	"maxLength",
+	"min",
+	"max",
+	"accept",
+	"multiple",
+	"onSubmit",
+	"onReset",
+	"onClick"
+];
+/**
+* `jsx`: the framework takes `children` in spread props (React, Preact,
+* Solid), so `<p {...name.error} />` shows the message. Vue and Svelte
+* render a child instead; Svelte's spread refuses `textContent`.
+*/
+function names(naming, react, jsx = react) {
+	const out = {};
+	for (const key of KEYS) out[key] = naming(key);
+	out.value = react ? "defaultValue" : "value";
+	out.checked = react ? "defaultChecked" : "checked";
+	out.input = react ? ["onChange"] : [naming("onInput"), naming("onChange")];
+	out.blur = naming(react ? "onBlur" : "onFocusOut");
+	out.text = jsx ? "children" : void 0;
+	return out;
+}
+//#endregion
+export { vue as a, react as i, jsx as n, lower as r, names as t };

package/dist/paths-DqNafpnl.js

@@ -0,0 +1,73 @@
+//#region src/core/paths.ts
+/**
+* Paths are the `name` attributes (D7): `address.city`, `invites.0.email`.
+* Values are immutable: `set` copies the objects and arrays on the way to
+* the leaf and shares the rest, so a view comparing by identity sees what
+* changed. A numeric segment indexes an array.
+*/
+const INDEX = /^\d+$/;
+/** The value at `path`, or `undefined` when a step is missing. */
+function get(root, path) {
+	if (path === "") return root;
+	if (!path.includes(".")) return root !== null && typeof root === "object" ? root[path] : void 0;
+	let at = root;
+	for (const key of path.split(".")) {
+		if (at === null || typeof at !== "object") return void 0;
+		at = at[key];
+	}
+	return at;
+}
+/** A copy of `root` with `value` at `path`. */
+function set(root, path, value) {
+	return put(root, path.split("."), 0, value);
+}
+function put(at, keys, i, value) {
+	const key = keys[i];
+	const copy = Array.isArray(at) || at == null && INDEX.test(key) ? Array.isArray(at) ? [...at] : [] : { ...at };
+	copy[key] = i === keys.length - 1 ? value : put(at?.[key], keys, i + 1, value);
+	return copy;
+}
+const plain = (value) => value !== null && typeof value === "object" && Object.getPrototypeOf(value) === Object.prototype;
+/** Equal values: arrays and plain objects by content, the rest (a `File`, a `Date`) by identity. */
+function equal(a, b) {
+	if (Object.is(a, b)) return true;
+	if (Array.isArray(a)) {
+		if (!Array.isArray(b) || a.length !== b.length) return false;
+		for (let i = 0; i < a.length; i++) if (!equal(a[i], b[i])) return false;
+		return true;
+	}
+	if (!plain(a) || !plain(b)) return false;
+	const keys = Object.keys(a);
+	if (keys.length !== Object.keys(b).length) return false;
+	for (const key of keys) if (!equal(a[key], b[key])) return false;
+	return true;
+}
+/** Each leaf of `value` with its path: plain objects are walked, anything else is a leaf. */
+function leaves(value, path = "", out = []) {
+	if (plain(value) && Object.keys(value).length) for (const key of Object.keys(value)) leaves(value[key], path ? `${path}.${key}` : key, out);
+	else if (path) out.push([path, value]);
+	return out;
+}
+/** `{ ...a, ...b }` one level deep, with `b`'s `undefined` keys left out: defaults over defaults (D11). */
+function merge(a, b) {
+	const out = { ...a };
+	if (b && typeof b === "object") for (const key in b) {
+		const value = b[key];
+		if (value !== void 0) out[key] = value;
+	}
+	return out;
+}
+/** An issue's path as a name: `["invites", 2, "email"]` and `[{ key: "invites" }, …]` alike. */
+function nameOf(path) {
+	if (!path) return "";
+	let out = "";
+	for (const segment of path) {
+		const key = segment !== null && typeof segment === "object" ? segment.key : segment;
+		out += (out ? "." : "") + String(key);
+	}
+	return out;
+}
+/** The path's pattern in a field spec: indexes are `*` (`invites.*.email`). */
+const patternOf = (path) => path.includes(".") ? path.replace(/(^|\.)\d+(?=\.|$)/g, "$1*") : path;
+//#endregion
+export { nameOf as a, merge as i, get as n, patternOf as o, leaves as r, set as s, equal as t };

package/dist/route/files.d.ts

@@ -0,0 +1,5 @@
+import { FileLimits } from "@menapo/api/client";
+import { StandardSchemaV1 } from "@standard-schema/spec";
+//#region src/route/files.d.ts
+export declare function withFiles(schema: StandardSchemaV1 | undefined, files: Readonly<Record<string, FileLimits>>): StandardSchemaV1;
+//#endregion

package/dist/route/files.js

@@ -0,0 +1,34 @@
+import { checkFile } from "@menapo/api/client";
+//#region src/route/files.ts
+/**
+* Uploads in the browser (D15): an operation's `files` checked with api's
+* own `checkFile` (its rule and words, without the server) beside the
+* input's schema, as one Standard Schema the plugin's schema module
+* exports for a route form whose operation takes files. Internal: only the
+* plugin's generated module imports it, by file.
+*/
+function withFiles(schema, files) {
+	const validate = (value) => {
+		const values = value ?? {};
+		const issues = [];
+		const rest = { ...values };
+		for (const [name, limits] of Object.entries(files)) {
+			delete rest[name];
+			for (const message of checkFile(values[name], limits)) issues.push({
+				message,
+				path: [name]
+			});
+		}
+		const join = (result) => issues.length || result.issues ? { issues: [...result.issues ?? [], ...issues] } : { value: values };
+		if (!schema) return join({ value: rest });
+		const result = schema["~standard"].validate(rest);
+		return "then" in result ? result.then(join) : join(result);
+	};
+	return { "~standard": {
+		version: 1,
+		vendor: "menapo",
+		validate
+	} };
+}
+//#endregion
+export { withFiles };

package/dist/server.d.ts

@@ -0,0 +1,25 @@
+import { _ as OutputOf, h as InputOf, p as FormState, u as Form, x as Spec } from "./types-CdCFdlFp.js";
+//#region src/server/index.d.ts
+/** Form data as the input (D7): names are paths, types come from the spec. */
+export declare function decode(data: FormData, spec?: Spec): Record<string, unknown>;
+export type ActionResult<F> = {
+  readonly ok: true;
+  readonly data: OutputOf<F>;
+} | {
+  readonly ok: false;
+  readonly state: FormState;
+};
+/**
+ * Handles a post of `form`: `extra` adds what the URL holds (`{ id }`).
+ *
+ * ```ts
+ * const r = await action(editProject, request, { id: params.id });
+ * if (r.ok) redirect(303, `/projects/${params.id}`);
+ * return fail(400, { form: r.state });
+ * ```
+ */
+export declare function action<F extends Form<never, unknown, unknown> | {
+  readonly name: string;
+}>(form: F, request: Request, extra?: Partial<InputOf<F>>): Promise<ActionResult<F>>;
+//#endregion
+export type { FormState };

package/dist/server.js

@@ -0,0 +1,79 @@
+import { a as nameOf, i as merge, n as get, o as patternOf, r as leaves, s as set } from "./paths-DqNafpnl.js";
+//#region src/server/index.ts
+const isFile = (value) => typeof Blob !== "undefined" && value instanceof Blob;
+/** One posted value, by its field's spec: text stays text unless the input's type says otherwise. */
+function coerce(value, type) {
+	if (typeof value !== "string") return value.size === 0 && !value.name ? void 0 : value;
+	if (type === "number" || type === "integer") return value === "" ? void 0 : Number.isNaN(Number(value)) ? value : Number(value);
+	if (type === "boolean") return value === "on" || value === "true";
+	return value;
+}
+/** Form data as the input (D7): names are paths, types come from the spec. */
+function decode(data, spec = {}) {
+	let out = {};
+	for (const name of new Set(data.keys())) {
+		const field = spec[patternOf(name)];
+		const all = data.getAll(name);
+		const value = field?.t === "array" || field?.m ? all.map((item) => coerce(item, void 0)).filter((item) => item !== void 0) : coerce(all[0], field?.t);
+		out = set(out, name, value);
+	}
+	for (const [pattern, field] of Object.entries(spec)) if (field.t === "boolean" && !pattern.includes("*") && get(out, pattern) === void 0) out = set(out, pattern, false);
+	return out;
+}
+/** The state to render again: the values without files (they can't round-trip, D15), errors by path. */
+function state(values, issues, error, fields) {
+	const errors = {};
+	const unmatched = [];
+	for (const issue of issues) {
+		const path = nameOf(issue.path);
+		if (path && (fields.has(path) || get(values, path) !== void 0)) errors[path] ??= String(issue.message);
+		else unmatched.push(String(issue.message));
+	}
+	let kept = {};
+	for (const [path, value] of leaves(values)) if (!isFile(value) && !(Array.isArray(value) && value.some(isFile))) kept = set(kept, path, value);
+	const message = error instanceof Error ? issues.length && !unmatched.length ? void 0 : error.message : unmatched.length ? unmatched.join(" ") : void 0;
+	return {
+		values: kept,
+		errors,
+		...message !== void 0 && { error: message }
+	};
+}
+/**
+* Handles a post of `form`: `extra` adds what the URL holds (`{ id }`).
+*
+* ```ts
+* const r = await action(editProject, request, { id: params.id });
+* if (r.ok) redirect(303, `/projects/${params.id}`);
+* return fail(400, { form: r.state });
+* ```
+*/
+async function action(form, request, extra) {
+	const F = form;
+	const posted = decode(await request.formData(), F.f);
+	const input = merge(merge(F.o.defaults, posted), extra);
+	const fields = new Set(Object.keys(posted));
+	let output = input;
+	const schema = F.s;
+	if (schema) {
+		const result = await schema["~standard"].validate(input);
+		if (result.issues) return {
+			ok: false,
+			state: state(input, result.issues, void 0, fields)
+		};
+		output = result.value;
+	}
+	try {
+		return {
+			ok: true,
+			data: await F.x(F, input, output, { signal: request.signal })
+		};
+	} catch (error) {
+		const issues = error?.issues;
+		return {
+			ok: false,
+			state: state(input, Array.isArray(issues) ? issues : [], error, fields)
+		};
+	}
+}
+//#endregion
+export { action, decode };

package/dist/source-DdFTPjID.js

@@ -0,0 +1,15 @@
+//#region ../glue/src/source.ts
+/** Equal own values: a render passing equal props does not set them again. */
+function same(a, b) {
+	if (a === b) return true;
+	if (!a || !b) return false;
+	const keys = Object.keys(a);
+	if (keys.length !== Object.keys(b).length) return false;
+	for (const key of keys) if (!Object.is(a[key], b[key])) return false;
+	return true;
+}
+let ids = 0;
+/** An id for frameworks that give none (Svelte, vanilla): unique on the page, not across a server and its client. */
+const nextId = () => `m${++ids}`;
+//#endregion
+export { same as n, nextId as t };

package/dist/types-CdCFdlFp.d.ts

@@ -0,0 +1,200 @@
+//#region src/core/types.d.ts
+/**
+ * The public types (PLAN §5.3): the input's fields (D7), what a view
+ * reads, and the options a definition and a hook take. Types flow from the
+ * operation (query's `Register`, D3) or the schema; nothing here is
+ * declared twice.
+ */
+/** Attributes for one element, spelled as the framework spells them (glue's naming). */
+type Attrs = Readonly<Record<string, unknown>>;
+type Leaf = string | number | boolean | bigint | symbol | null | undefined | Date | Blob;
+/**
+ * `f.fields` (D7): one entry per key of the input. A leaf is a field, an
+ * object its own fields (`f.fields.address.city`), an array a field with
+ * its items and edits (`f.fields.invites.items[0].email`).
+ */
+type Fields<T> = { readonly [K in keyof T & string]-?: FieldOf<T[K]>; };
+/** What `f.fields.<key>` is for a value of type `V`. */
+type FieldOf<V> = NonNullable<V> extends Leaf ? FieldView<V> : NonNullable<V> extends readonly (infer E)[] ? ArrayField<V, E> : Fields<NonNullable<V>>;
+/** Defaults: any part of the input, nested. */
+type Defaults<T> = T extends Leaf ? T : T extends readonly unknown[] ? T : { readonly [K in keyof T]?: Defaults<T[K]> | undefined; };
+/** What `/server`'s `action()` hands back to the page: serialisable, files left out (§5.6). */
+interface FormState {
+  readonly values: Readonly<Record<string, unknown>>;
+  /** Field errors by path. */
+  readonly errors: Readonly<Record<string, string>>;
+  /** The form-level error's message. */
+  readonly error?: string | undefined;
+}
+/** `useForm`'s options; Vue, Svelte and Solid also take a getter returning them, so they are tracked. */
+interface UseFormOptions<I, O> {
+  /** Shallow-merged over the definition's; pristine fields follow a change (D11). */
+  readonly defaults?: Defaults<I> | null | undefined;
+  /** After a successful submit, with its output. */
+  readonly onSuccess?: ((data: O) => void) | undefined;
+  /** What `/server`'s `action()` returned for a post without JS (§5.6). */
+  readonly state?: FormState | null | undefined;
+}
+/** An error shown by a field, for the summary's links. */
+interface ShownError {
+  readonly path: string;
+  readonly message: string;
+  /** `#<the control's id>`. */
+  readonly href: string;
+}
+/** One radio, or one checkbox of an array field. */
+interface OptionParts {
+  readonly control: Attrs;
+  readonly label: Attrs;
+}
+interface FieldParts {
+  /** `id`, `name`, the initial value, `aria-invalid`, `aria-describedby` and constraint attributes. */
+  readonly control: Attrs;
+  readonly label: Attrs;
+  readonly error: Attrs;
+  readonly hint: Attrs;
+  /** A fieldset of radios or checkboxes: `aria-describedby` its error. */
+  readonly group: Attrs;
+}
+/**
+ * A field as a view reads it: tracked per field, so a component renders for
+ * what it shows. Its parts are attribute objects to spread on elements.
+ */
+interface FieldView<V> {
+  readonly name: string;
+  readonly id: string;
+  readonly value: V;
+  /** The error shown, as the schema or the server worded it (D16). */
+  readonly message: string | undefined;
+  readonly touched: boolean;
+  readonly dirty: boolean;
+  /** A `checks` call or an async schema is running for it. */
+  readonly validating: boolean;
+  /** For controls that emit no native events (a custom select); marks the field touched. */
+  set(value: V): void;
+  option(value: V extends readonly (infer E)[] ? E : V): OptionParts;
+  /** `id`, `name`, the initial value, `aria-invalid`, `aria-describedby` and constraint attributes. */
+  readonly control: Attrs;
+  readonly label: Attrs;
+  /** The error's element: its `id`, and in React, Preact and Solid the message as its children. */
+  readonly error: Attrs;
+  /**
+   * The hint's element: its `id`, and the schema's `description` as its
+   * children in React, Preact and Solid. Read, it is linked from the
+   * control's `aria-describedby`.
+   */
+  readonly hint: Attrs;
+  /** A fieldset of radios or checkboxes: `aria-describedby` its error. */
+  readonly group: Attrs;
+}
+/** An array's field (D14): itself a field (checkboxes, a group), its items, and the edits. */
+interface ArrayField<V, E> extends FieldView<V> {
+  /** One stable key per item, for rendering rows (`key={key}`). */
+  readonly keys: readonly string[];
+  /** Per item: its fields, or for an array of leaves its field. */
+  readonly items: readonly FieldOf<E>[];
+  append(item: E): void;
+  insert(index: number, item: E): void;
+  remove(index: number): void;
+  move(from: number, to: number): void;
+}
+/** The parts a field's `Parts` builds, each when first read. */
+interface FieldParts {
+  readonly control: Attrs;
+  readonly label: Attrs;
+  readonly error: Attrs;
+  readonly hint: Attrs;
+  readonly group: Attrs;
+}
+interface FormParts {
+  /** `id`, `method: "post"`, `encType` with files, `data-pending` and the delegated handlers (D6). */
+  readonly form: Attrs;
+  /** `type: "submit"`, and `aria-disabled` while pending (D12). */
+  readonly submit: Attrs;
+  /** The error summary: `id`, `tabIndex: -1`, and a click handler for its links. */
+  readonly summary: Attrs;
+}
+/** What a definition's types are read from. */
+interface Typed<I, O, E> {
+  readonly "~types"?: {
+    readonly input: I;
+    readonly output: O;
+    readonly error: E;
+  };
+}
+/** A form definition: `form("PATCH /projects/:id")` or `form(schema, submit)`. */
+type Form<I, O, E> = Typed<I, O, E> & {
+  readonly name: string;
+};
+type InputOf<F> = F extends Typed<infer I, unknown, unknown> ? I : never;
+type OutputOf<F> = F extends Typed<unknown, infer O, unknown> ? O : never;
+type ErrorOf<F> = F extends Typed<unknown, unknown, infer E> ? E : never;
+/** What `useForm` returns: `FormView<typeof editProject>`. */
+interface FormView<F> extends Typed<InputOf<F>, OutputOf<F>, ErrorOf<F>> {
+  /** `id`, `method: "post"`, `encType` with files, `data-pending` and the delegated handlers (D6). */
+  readonly form: Attrs;
+  /** `type: "submit"`, and `aria-disabled` while pending (D12). */
+  readonly submit: Attrs;
+  /** The error summary: `id`, `tabIndex: -1`, and a click handler for its links. */
+  readonly summary: Attrs;
+  /** The input's fields, from the schema's keys and the defaults': `const { name } = f.fields`. */
+  readonly fields: Fields<InputOf<F>>;
+  /** The errors shown, in the schema's order. */
+  readonly errors: readonly ShownError[];
+  /** The form-level error: api's `ApiError` for a route form, else an `Error`. */
+  readonly error: ErrorOf<F> | undefined;
+  readonly pending: boolean;
+  /** An upload's progress, 0 → 1. */
+  readonly progress: number;
+  /** Any field changed since the defaults or the last success. */
+  readonly dirty: boolean;
+  /** The last success's output. */
+  readonly data: OutputOf<F> | undefined;
+  /** The submit flow from code, as the form's own `requestSubmit()`: the output, or `undefined` after setting errors. */
+  requestSubmit(): Promise<OutputOf<F> | undefined>;
+  /** Back to the defaults, or to `values`. */
+  reset(values?: Defaults<InputOf<F>>): void;
+  /** Plain code: calls `listener` after each change this view shows; returns the unsubscribe. */
+  subscribe(listener: () => void): () => void;
+  /** Plain code: what a framework's unmount does. */
+  stop(): void;
+}
+/** Per-field async checks (D8): a message, or `undefined` when the value is fine. */
+type Checks<I> = { readonly [K in keyof I]?: (value: I[K], options: {
+  readonly signal: AbortSignal;
+}) => string | undefined | Promise<string | undefined>; };
+interface FormOptions<I> {
+  /** The definition's own defaults, under each hook's. */
+  readonly defaults?: Defaults<I> | undefined;
+  /** Server-side rules checked while typing, debounced 300 ms and aborted when superseded. */
+  readonly checks?: Checks<I> | undefined;
+}
+/** A query, as a route form's `refresh` reads it (query's `Refreshable`). */
+interface Refreshable {
+  refresh(): void;
+}
+/** A route form's options: a definition's, and query's `mutation()` options passed through (D2). */
+interface RouteFormOptions<I> extends FormOptions<I> {
+  readonly optimistic?: ((input: I) => void) | undefined;
+  readonly refresh?: readonly Refreshable[] | undefined;
+}
+/**
+ * A field's spec (D13), from the input's JSON Schema, by path pattern:
+ * type, required, lengths, bounds, `accept`, `multiple`, and an upload's
+ * size limit. A small literal per form.
+ */
+interface FieldSpec {
+  readonly t?: "string" | "number" | "integer" | "boolean" | "array" | "object" | "file";
+  readonly r?: 1;
+  readonly mn?: number;
+  readonly mx?: number;
+  readonly lo?: number;
+  readonly hi?: number;
+  readonly a?: string;
+  readonly m?: 1;
+  /** The schema's `description`: the hint's text. */
+  readonly d?: string;
+}
+type Spec = Readonly<Record<string, FieldSpec>>;
+//#endregion
+export { UseFormOptions as S, OutputOf as _, FieldOf as a, ShownError as b, FieldView as c, FormOptions as d, FormParts as f, OptionParts as g, InputOf as h, Defaults as i, Fields as l, FormView as m, Attrs as n, FieldParts as o, FormState as p, Checks as r, FieldSpec as s, ArrayField as t, Form as u, Refreshable as v, Spec as x, RouteFormOptions as y };