@k8ordo/form 0.1.0

package/dist/types.d.mts

@@ -0,0 +1,76 @@
+import { Rule } from "./rules/rules.mjs";
+//#region src/types.d.ts
+/** ValidityState flags a derived field can report a message for. */
+type ValidityFlag = 'badInput' | 'patternMismatch' | 'rangeOverflow' | 'rangeUnderflow' | 'stepMismatch' | 'tooLong' | 'tooShort' | 'typeMismatch' | 'valueMissing';
+/** Attributes spread onto the input element itself. */
+type FieldInput = {
+  name: string;
+  type?: string;
+  required?: boolean;
+  minLength?: number;
+  maxLength?: number;
+  pattern?: string;
+  min?: number | string;
+  max?: number | string;
+  step?: number | 'any';
+  defaultValue?: string;
+  defaultChecked?: boolean;
+};
+/**
+ * One field as derived from the schema. Serializable on purpose: it crosses the
+ * RSC boundary as props, which is what keeps zod out of the client bundle.
+ */
+type DerivedField = {
+  input: FieldInput;
+  /** Message per ValidityState flag, taken from zod itself. */
+  messages: Partial<Record<ValidityFlag, string>>;
+  /** True when the input must not be echoed back after a failed submit. */
+  secret: boolean;
+};
+/**
+ * A repeatable group. The item is described once; the row index is filled into
+ * the name when a row renders, because rows do not exist until then.
+ */
+type DerivedArray = {
+  path: string;
+  minItems?: number;
+  maxItems?: number;
+  /** Keyed by the path within one item; '' when the array holds scalars. */
+  item: Record<string, DerivedField>;
+};
+/** What a constraint-carrying check lost on its way to HTML. */
+type DroppedCheck = {
+  field: string;
+  reason: string;
+};
+type FormFields<FieldPath extends string = string, ArrayPath extends string = string> = {
+  fields: Record<FieldPath, DerivedField>;
+  arrays: Record<ArrayPath, DerivedArray>;
+  /** Checks HTML has no attribute for, evaluated identically on both sides. */
+  rules: Rule[];
+  /** Checks that HTML cannot express. Reported once, never silently discarded. */
+  dropped: DroppedCheck[];
+};
+/**
+ * What a Server Action hands back to the form. Keys are dotted paths, so an
+ * error on a row reads as `items[1].name`.
+ */
+type FormState = {
+  errors?: Record<string, string>;
+  /**
+   * Submitted values for re-render. Secret fields are never included; a name
+   * several controls share — a checkbox group — echoes as an array.
+   */
+  values?: Record<string, string | string[]>;
+  /** How many rows each array had, so a no-JS retry rebuilds them. */
+  rows?: Record<string, number>;
+  /** An error about the submission as a whole rather than one field. */
+  formError?: string;
+  /**
+   * Identity of one parse. Two identical failed submissions must still read
+   * as two on the client — content alone cannot tell them apart.
+   */
+  token?: string;
+};
+//#endregion
+export { DerivedArray, DerivedField, DroppedCheck, FieldInput, FormFields, FormState, ValidityFlag };

package/dist/types.mjs

@@ -0,0 +1 @@
+export {};

package/dist/use-form.d.mts

@@ -0,0 +1,44 @@
+import { FieldInput, FormFields, FormState } from "./types.mjs";
+import { FocusEvent, Ref, SyntheticEvent } from "react";
+//#region src/use-form.d.ts
+type FieldView = {
+  input: FieldInput;
+  error: string | undefined;
+  invalid: boolean;
+  required: boolean;
+};
+type RowView = {
+  key: string;
+  index: number;
+  field: (itemKey?: string) => FieldView;
+  remove: () => void;
+};
+type ArrayView = {
+  rows: RowView[];
+  add: () => void;
+  canAdd: boolean;
+  canRemove: boolean;
+  error: string | undefined;
+};
+type UseFormReturn<FieldPath extends string = string, ArrayPath extends string = string> = {
+  props: {
+    onBlur: (event: FocusEvent<HTMLFormElement>) => void;
+    onInput: (event: SyntheticEvent<HTMLFormElement>) => void;
+    ref: Ref<HTMLFormElement>;
+  };
+  field: (path: FieldPath) => FieldView;
+  array: (path: ArrayPath) => ArrayView;
+  /** True once any field differs from the value it was rendered with. */
+  isDirty: boolean;
+};
+/**
+ * Wire derived fields to a form.
+ *
+ * Values are never copied into React state — the DOM holds them. What lives
+ * here is only what the DOM cannot express: which message to show for a field
+ * the browser has judged invalid, which server errors are still current, the
+ * identity of each repeated row, and one dirty flag.
+ */
+declare const useForm: <FieldPath extends string, ArrayPath extends string>(fields: FormFields<FieldPath, ArrayPath>, state: FormState) => UseFormReturn<FieldPath, ArrayPath>;
+//#endregion
+export { ArrayView, FieldView, RowView, UseFormReturn, useForm };

package/dist/use-form.mjs

@@ -0,0 +1,309 @@
+"use client";
+import { breachOf } from "./rules/rules.mjs";
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+//#region src/use-form.ts
+const INDEX = "{index}";
+const FLAGS = [
+	"valueMissing",
+	"typeMismatch",
+	"patternMismatch",
+	"tooShort",
+	"tooLong",
+	"rangeUnderflow",
+	"rangeOverflow",
+	"stepMismatch",
+	"badInput"
+];
+const isControl = (target) => target instanceof HTMLInputElement || target instanceof HTMLSelectElement || target instanceof HTMLTextAreaElement;
+/**
+* A name shared by several controls — a checkbox group — comes back as a
+* RadioNodeList. Validity belongs to an element, so the group reports through
+* its first member.
+*/
+const controlNamed = (form, name) => {
+	if (form === null) return;
+	const found = form.elements.namedItem(name);
+	if (isControl(found)) return found;
+	if (found instanceof RadioNodeList) {
+		const first = found.item(0);
+		return isControl(first) ? first : void 0;
+	}
+};
+/**
+* Pick the message for whichever check the browser says failed. `customError`
+* is honoured first: it is set deliberately by the caller, so it outranks any
+* built-in flag.
+*/
+const messageFor = (control, field) => {
+	const { validity } = control;
+	if (validity.valid) return;
+	if (validity.customError) return control.validationMessage;
+	for (const flag of FLAGS) if (validity[flag]) return field.messages[flag];
+};
+const initialRows = (fields, state) => {
+	const rows = {};
+	for (const [path, array] of Object.entries(fields.arrays)) {
+		const count = state.rows?.[path] ?? array.minItems ?? 0;
+		rows[path] = Array.from({ length: count }, (_, index) => `${path}-${String(index)}`);
+	}
+	return rows;
+};
+const rowCountsOf = (rows) => Object.fromEntries(Object.entries(rows).map(([path, keys]) => [path, keys.length]));
+/**
+* Rename one concrete indexed name after the row at `removed` is gone: entries
+* on that row are dropped, entries on later rows slide down one index. Without
+* this, a message raised on `items[1].name` would reattach to whichever row
+* renders as index 1 next.
+*/
+const shiftName = (name, path, removed) => {
+	const prefix = `${path}[`;
+	if (!name.startsWith(prefix)) return name;
+	const close = name.indexOf("]", prefix.length);
+	const index = Number(name.slice(prefix.length, close));
+	if (!Number.isInteger(index)) return name;
+	if (index === removed) return null;
+	if (index > removed) return `${prefix}${String(index - 1)}${name.slice(close)}`;
+	return name;
+};
+const shiftRecord = (record, path, removed) => {
+	const next = {};
+	for (const [name, value] of Object.entries(record)) {
+		const renamed = shiftName(name, path, removed);
+		if (renamed !== null) next[renamed] = value;
+	}
+	return next;
+};
+const shiftSet = (set, path, removed) => {
+	const next = /* @__PURE__ */ new Set();
+	for (const name of set) {
+		const renamed = shiftName(name, path, removed);
+		if (renamed !== null) next.add(renamed);
+	}
+	return next;
+};
+/**
+* Wire derived fields to a form.
+*
+* Values are never copied into React state — the DOM holds them. What lives
+* here is only what the DOM cannot express: which message to show for a field
+* the browser has judged invalid, which server errors are still current, the
+* identity of each repeated row, and one dirty flag.
+*/
+const useForm = (fields, state) => {
+	const lookup = fields;
+	const formRef = useRef(null);
+	const nextKey = useRef(0);
+	const ownedRuleMessages = useRef(/* @__PURE__ */ new Map());
+	const [clientErrors, setClientErrors] = useState({});
+	const [edited, setEdited] = useState(/* @__PURE__ */ new Set());
+	const [domDirty, setDomDirty] = useState(false);
+	const [rowKeys, setRowKeys] = useState(() => initialRows(lookup, state));
+	const baselineRows = useRef(rowCountsOf(rowKeys));
+	const stateKey = JSON.stringify(state);
+	const lastKey = useRef(stateKey);
+	useEffect(() => {
+		if (lastKey.current === stateKey) return;
+		lastKey.current = stateKey;
+		setClientErrors({});
+		setEdited(/* @__PURE__ */ new Set());
+		setDomDirty(false);
+		const rows = initialRows(lookup, state);
+		baselineRows.current = rowCountsOf(rows);
+		setRowKeys(rows);
+		const firstErrored = Object.keys(state.errors ?? {})[0];
+		if (firstErrored !== void 0) controlNamed(formRef.current, firstErrored)?.focus();
+	}, [
+		stateKey,
+		state,
+		lookup
+	]);
+	const evaluate = useCallback((target, onlyIfShown) => {
+		if (!isControl(target)) return;
+		const form = formRef.current;
+		applyRules(form, lookup.rules, ownedRuleMessages.current);
+		const names = /* @__PURE__ */ new Set([target.name]);
+		for (const rule of lookup.rules) names.add(rule.field);
+		setClientErrors((previous) => {
+			let next = previous;
+			for (const name of names) {
+				const field = fieldFor(lookup, name);
+				if (field === void 0) continue;
+				const control = controlNamed(form, name) ?? (name === target.name ? target : void 0);
+				if (control === void 0) continue;
+				if ((name === target.name ? onlyIfShown : true) && next[name] === void 0) continue;
+				const message = messageFor(control, field);
+				if (next[name] === message) continue;
+				if (message === void 0) {
+					const { [name]: _cleared, ...rest } = next;
+					next = rest;
+				} else next = {
+					...next,
+					[name]: message
+				};
+			}
+			return next;
+		});
+	}, [lookup]);
+	const onBlur = useCallback((event) => {
+		evaluate(event.target, false);
+	}, [evaluate]);
+	const onInput = useCallback((event) => {
+		const { target } = event;
+		if (isControl(target)) {
+			setEdited((previous) => previous.has(target.name) ? previous : new Set(previous).add(target.name));
+			setDomDirty(isFormDirty(formRef.current));
+		}
+		evaluate(target, true);
+	}, [evaluate]);
+	const viewOf = useCallback((field, name) => {
+		const serverError = edited.has(name) ? void 0 : state.errors?.[name];
+		const error = clientErrors[name] ?? serverError;
+		const value = state.values?.[name];
+		const input = {
+			...field.input,
+			name
+		};
+		if (field.input.type === "checkbox") {
+			if (state.values !== void 0) input.defaultChecked = value !== void 0;
+		} else if (typeof value === "string") input.defaultValue = value;
+		return {
+			input,
+			error,
+			invalid: error !== void 0,
+			required: field.input.required ?? false
+		};
+	}, [
+		clientErrors,
+		edited,
+		state
+	]);
+	const field = useCallback((path) => {
+		const derived = lookup.fields[path];
+		if (derived === void 0) throw new Error(`[@k8ordo/form] スキーマに '${path}' がありません。繰り返しの中の欄なら array('...') を使ってください。`);
+		return viewOf(derived, derived.input.name);
+	}, [lookup, viewOf]);
+	const array = useCallback((path) => {
+		const derived = lookup.arrays[path];
+		if (derived === void 0) throw new Error(`[@k8ordo/form] スキーマに配列 '${path}' がありません。`);
+		const keys = rowKeys[path] ?? [];
+		const remove = (key) => {
+			const index = keys.indexOf(key);
+			if (index === -1) return;
+			setRowKeys((previous) => ({
+				...previous,
+				[path]: (previous[path] ?? []).filter((candidate) => candidate !== key)
+			}));
+			setClientErrors((previous) => shiftRecord(previous, path, index));
+			setEdited((previous) => shiftSet(previous, path, index));
+		};
+		return {
+			rows: keys.map((key, index) => ({
+				key,
+				index,
+				field: (itemKey = "") => {
+					const item = derived.item[itemKey];
+					if (item === void 0) throw new Error(`[@k8ordo/form] 配列 '${path}' に '${itemKey}' がありません。`);
+					return viewOf(item, item.input.name.replace(INDEX, String(index)));
+				},
+				remove: () => {
+					remove(key);
+				}
+			})),
+			add: () => {
+				nextKey.current += 1;
+				const key = `${path}-new-${String(nextKey.current)}`;
+				setRowKeys((previous) => ({
+					...previous,
+					[path]: [...previous[path] ?? [], key]
+				}));
+			},
+			canAdd: derived.maxItems === void 0 || keys.length < derived.maxItems,
+			canRemove: keys.length > (derived.minItems ?? 0),
+			error: state.errors?.[path]
+		};
+	}, [
+		lookup,
+		rowKeys,
+		state,
+		viewOf
+	]);
+	const ref = useCallback((node) => {
+		formRef.current = node;
+		if (node !== null) node.noValidate = true;
+	}, []);
+	const props = useMemo(() => ({
+		onBlur,
+		onInput,
+		ref
+	}), [
+		onBlur,
+		onInput,
+		ref
+	]);
+	const structuralDirty = Object.entries(rowKeys).some(([path, keys]) => keys.length !== (baselineRows.current[path] ?? 0));
+	return {
+		props,
+		field,
+		array,
+		isDirty: domDirty || structuralDirty
+	};
+};
+/** Look up the derived field for a submitted name, row index included. */
+const fieldFor = (fields, name) => {
+	const direct = fields.fields[name];
+	if (direct !== void 0) return direct;
+	const template = name.replaceAll(/\[\d+\]/gu, `[${INDEX}]`);
+	for (const array of Object.values(fields.arrays)) for (const item of Object.values(array.item)) if (item.input.name === template) return item;
+};
+/**
+* Apply the cross-field rules to the live form. `setCustomValidity` is what
+* makes the result indistinguishable from a built-in check: `:user-invalid`
+* lights up, `validity.customError` is set, and the message flows through the
+* same path as every other one.
+*
+* `owned` records what this function wrote, so a clean pass only clears its
+* own message — never an async check's answer sharing the same slot.
+*/
+const applyRules = (form, rules, owned) => {
+	if (form === null) return;
+	const data = new FormData(form);
+	const values = (name) => data.getAll(name).filter((value) => typeof value === "string");
+	const breaches = /* @__PURE__ */ new Map();
+	const involved = /* @__PURE__ */ new Set();
+	for (const rule of rules) {
+		involved.add(rule.field);
+		if (!breaches.has(rule.field)) {
+			const breach = breachOf(rule, values);
+			if (breach !== void 0) breaches.set(rule.field, breach);
+		}
+	}
+	for (const name of involved) {
+		const control = controlNamed(form, name);
+		if (control === void 0) continue;
+		const breach = breaches.get(name);
+		if (breach !== void 0) {
+			control.setCustomValidity(breach);
+			owned.set(name, breach);
+		} else if (owned.has(name)) {
+			if (control.validationMessage === owned.get(name)) control.setCustomValidity("");
+			owned.delete(name);
+		}
+	}
+};
+const isFormDirty = (form) => {
+	if (form === null) return false;
+	for (const element of form.elements) if (element instanceof HTMLInputElement) {
+		const { initial } = element.dataset;
+		if (initial !== void 0) {
+			if (element.value !== initial) return true;
+		} else if (element.type === "checkbox" || element.type === "radio") {
+			if (element.checked !== element.defaultChecked) return true;
+		} else if (element.value !== element.defaultValue) return true;
+	} else if (element instanceof HTMLTextAreaElement && element.value !== element.defaultValue) return true;
+	else if (element instanceof HTMLSelectElement) {
+		for (const option of element.options) if (option.selected !== option.defaultSelected) return true;
+	}
+	return false;
+};
+//#endregion
+export { useForm };