@k8ordo/form 0.1.1 → 1.1.0

package/dist/use-form.d.mts

@@ -1,33 +1,53 @@
-import { FieldInput, FormFields, FormState } from "./types.mjs";
-import { FocusEvent, Ref, SyntheticEvent } from "react";
+import { FieldInput, FormFields, FormState, StringCheckboxInput } from "./types.mjs";
+import { FocusEvent, Ref, SubmitEvent, SyntheticEvent } from "react";
 //#region src/use-form.d.ts
-type FieldView = {
-  input: FieldInput;
+export type FieldView<Input extends FieldInput = FieldInput> = {
+  input: Input;
   error: string | undefined;
   invalid: boolean;
   required: boolean;
 };
-type RowView = {
+export type RowView = {
   key: string;
   index: number;
   field: (itemKey?: string) => FieldView;
   remove: () => void;
 };
-type ArrayView = {
+export type ArrayView = {
   rows: RowView[];
   add: () => void;
   canAdd: boolean;
   canRemove: boolean;
   error: string | undefined;
+  /** Spread onto the element that shows `error`, so focus can land on it. */
+  errorProps: {
+    id: string;
+    tabIndex: -1;
+  };
 };
-type UseFormReturn<FieldPath extends string = string, ArrayPath extends string = string> = {
+export type FormErrorView = {
+  /** `state.formError`: the failure no field owns. */
+  message: string | undefined;
+  /** Spread onto the element that shows `message`, so focus can land on it. */
+  props: {
+    id: string;
+    tabIndex: -1;
+  };
+};
+export type UseFormReturn<FieldPath extends string = string, ArrayPath extends string = string, StringCheckboxPath extends string = never> = {
   props: {
     onBlur: (event: FocusEvent<HTMLFormElement>) => void;
     onInput: (event: SyntheticEvent<HTMLFormElement>) => void;
+    onReset: () => void;
+    onSubmit: (event: SubmitEvent<HTMLFormElement>) => void;
     ref: Ref<HTMLFormElement>;
   };
-  field: (path: FieldPath) => FieldView;
+  field: {
+    (path: StringCheckboxPath): FieldView<StringCheckboxInput>;
+    (path: FieldPath): FieldView;
+  };
   array: (path: ArrayPath) => ArrayView;
+  formError: FormErrorView;
   /** True once any field differs from the value it was rendered with. */
   isDirty: boolean;
 };
@@ -37,8 +57,8 @@ type UseFormReturn<FieldPath extends string = string, ArrayPath extends string =
  * 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.
+ * identity of each repeated row, one dirty flag, and the row counts adding or
+ * removing a row is measured against.
  */
-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 };
+export declare const useForm: <FieldPath extends string, ArrayPath extends string, StringCheckboxPath extends string = never>(fields: FormFields<FieldPath, ArrayPath, StringCheckboxPath>, state?: FormState) => UseFormReturn<FieldPath, ArrayPath, StringCheckboxPath>;
+//#endregion

package/dist/use-form.mjs

@@ -1,6 +1,6 @@
 "use client";
 import { breachOf } from "./rules/rules.mjs";
-import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { useCallback, useEffect, useId, useLayoutEffect, useMemo, useRef, useState } from "react";
 //#region src/use-form.ts
 const INDEX = "{index}";
 const FLAGS = [
@@ -40,15 +40,19 @@ const messageFor = (control, field) => {
 	if (validity.customError) return control.validationMessage;
 	for (const flag of FLAGS) if (validity[flag]) return field.messages[flag];
 };
-const initialRows = (fields, state) => {
+const rowCountsFor = (fields, state) => {
+	const counts = {};
+	for (const [path, array] of Object.entries(fields.arrays)) counts[path] = state.rows?.[path] ?? array.minItems ?? 0;
+	return counts;
+};
+const rowKeysFor = (counts, current = {}) => {
 	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)}`);
+	for (const [path, count] of Object.entries(counts)) {
+		const kept = current[path];
+		rows[path] = kept?.length === count ? kept : 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
@@ -87,9 +91,10 @@ const shiftSet = (set, path, removed) => {
 * 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.
+* identity of each repeated row, one dirty flag, and the row counts adding or
+* removing a row is measured against.
 */
-const useForm = (fields, state) => {
+const useForm = (fields, state = {}) => {
 	const lookup = fields;
 	const formRef = useRef(null);
 	const nextKey = useRef(0);
@@ -97,8 +102,10 @@ const useForm = (fields, state) => {
 	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 [baselineRows, setBaselineRows] = useState(() => rowCountsFor(lookup, state));
+	const [rowKeys, setRowKeys] = useState(() => rowKeysFor(baselineRows));
+	const formErrorId = useId();
+	const arrayErrorIdBase = useId();
 	const stateKey = JSON.stringify(state);
 	const lastKey = useRef(stateKey);
 	useEffect(() => {
@@ -107,16 +114,21 @@ const useForm = (fields, state) => {
 		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();
+		const counts = rowCountsFor(lookup, state);
+		setBaselineRows(counts);
+		setRowKeys((previous) => rowKeysFor(counts, previous));
+		const messageIds = [...state.formError === void 0 ? [] : [formErrorId], ...Object.keys(lookup.arrays).filter((path) => state.errors?.[path] !== void 0).map((path) => arrayErrorId(arrayErrorIdBase, path))];
+		firstFailure(formRef.current, state.errors ?? {}, messageIds)?.focus();
 	}, [
 		stateKey,
 		state,
-		lookup
+		lookup,
+		formErrorId,
+		arrayErrorIdBase
 	]);
+	useLayoutEffect(() => {
+		writeEchoToSelects(formRef.current, lookup, state.values);
+	}, [lookup, state.values]);
 	const evaluate = useCallback((target, onlyIfShown) => {
 		if (!isControl(target)) return;
 		const form = formRef.current;
@@ -155,6 +167,35 @@ const useForm = (fields, state) => {
 		}
 		evaluate(target, true);
 	}, [evaluate]);
+	const onSubmit = useCallback((event) => {
+		const { submitter } = event;
+		if ((submitter instanceof HTMLButtonElement || submitter instanceof HTMLInputElement) && submitter.formNoValidate) return;
+		const form = event.currentTarget;
+		applyRules(form, lookup.rules, ownedRuleMessages.current);
+		const failed = firstFailed(form, (control) => control.willValidate && !control.validity.valid);
+		if (failed === void 0) return;
+		event.preventDefault();
+		const messages = messagesIn(form, lookup);
+		setClientErrors(messages);
+		failed.focus();
+		if (!Object.hasOwn(messages, failed.name)) failed.reportValidity();
+	}, [lookup]);
+	const onReset = useCallback(() => {
+		setClientErrors({});
+		setEdited(/* @__PURE__ */ new Set());
+		const counts = rowCountsFor(lookup, state);
+		setBaselineRows(counts);
+		setRowKeys((previous) => rowKeysFor(counts, previous));
+		const form = formRef.current;
+		for (const [name, message] of ownedRuleMessages.current) {
+			const control = controlNamed(form, name);
+			if (control?.validationMessage === message) control.setCustomValidity("");
+		}
+		ownedRuleMessages.current.clear();
+		setTimeout(() => {
+			setDomDirty(isFormDirty(formRef.current));
+		}, 0);
+	}, [lookup, state]);
 	const viewOf = useCallback((field, name) => {
 		const serverError = edited.has(name) ? void 0 : state.errors?.[name];
 		const error = clientErrors[name] ?? serverError;
@@ -219,13 +260,18 @@ const useForm = (fields, state) => {
 			},
 			canAdd: derived.maxItems === void 0 || keys.length < derived.maxItems,
 			canRemove: keys.length > (derived.minItems ?? 0),
-			error: state.errors?.[path]
+			error: state.errors?.[path],
+			errorProps: {
+				id: arrayErrorId(arrayErrorIdBase, path),
+				tabIndex: -1
+			}
 		};
 	}, [
 		lookup,
 		rowKeys,
 		state,
-		viewOf
+		viewOf,
+		arrayErrorIdBase
 	]);
 	const ref = useCallback((node) => {
 		formRef.current = node;
@@ -234,20 +280,68 @@ const useForm = (fields, state) => {
 	const props = useMemo(() => ({
 		onBlur,
 		onInput,
+		onReset,
+		onSubmit,
 		ref
 	}), [
 		onBlur,
 		onInput,
+		onReset,
+		onSubmit,
 		ref
 	]);
-	const structuralDirty = Object.entries(rowKeys).some(([path, keys]) => keys.length !== (baselineRows.current[path] ?? 0));
+	const formError = useMemo(() => ({
+		message: state.formError,
+		props: {
+			id: formErrorId,
+			tabIndex: -1
+		}
+	}), [state.formError, formErrorId]);
+	const structuralDirty = Object.entries(rowKeys).some(([path, keys]) => keys.length !== (baselineRows[path] ?? 0));
 	return {
 		props,
 		field,
 		array,
+		formError,
 		isDirty: domDirty || structuralDirty
 	};
 };
+/**
+* An object key may hold whitespace, which an id must not — it would also
+* split an `aria-describedby` list — so the path is encoded, not appended.
+*/
+const arrayErrorId = (base, path) => `${base}-${encodeURIComponent(path)}`;
+/**
+* The first failure in document order: a failed control, or the element
+* showing a failure no control owns — the form-level message or an array's
+* own. `state.errors` cannot say which comes first — its keys follow the
+* order zod reported the issues in, which is the schema's, not the page's.
+*/
+const firstFailure = (form, errors, messageIds) => {
+	if (form === null) return;
+	const candidates = messageIds.map((id) => form.ownerDocument.querySelector(`#${CSS.escape(id)}`)).filter((message) => message !== null);
+	const field = firstFailed(form, (control) => errors[control.name] !== void 0);
+	if (field !== void 0) candidates.push(field);
+	return candidates.toSorted((a, b) => a.compareDocumentPosition(b) & Node.DOCUMENT_POSITION_FOLLOWING ? -1 : 1)[0];
+};
+/** The first control in document order that `failed` picks out. */
+const firstFailed = (form, failed) => [...form.elements].find((element) => isControl(element) && failed(element));
+/**
+* The message every field of the form shows right now, read from the DOM —
+* the untouched fields included, which is what a submit has to report.
+*/
+const messagesIn = (form, fields) => {
+	const messages = {};
+	for (const element of form.elements) {
+		if (!isControl(element) || Object.hasOwn(messages, element.name)) continue;
+		const field = fieldFor(fields, element.name);
+		const control = controlNamed(form, element.name);
+		if (field === void 0 || control === void 0) continue;
+		const message = messageFor(control, field);
+		if (message !== void 0) messages[element.name] = message;
+	}
+	return messages;
+};
 /** Look up the derived field for a submitted name, row index included. */
 const fieldFor = (fields, name) => {
 	const direct = fields.fields[name];
@@ -290,6 +384,17 @@ const applyRules = (form, rules, owned) => {
 		}
 	}
 };
+const writeEchoToSelects = (form, fields, values) => {
+	if (form === null || values === void 0) return;
+	for (const element of form.elements) {
+		if (!(element instanceof HTMLSelectElement) || fieldFor(fields, element.name) === void 0) continue;
+		if (element.matches(":disabled")) continue;
+		const echoed = values[element.name];
+		if (echoed === void 0) continue;
+		const chosen = new Set([echoed].flat());
+		for (const option of element.options) option.defaultSelected = chosen.has(option.value);
+	}
+};
 const isFormDirty = (form) => {
 	if (form === null) return false;
 	for (const element of form.elements) if (element instanceof HTMLInputElement) {
@@ -300,10 +405,19 @@ const isFormDirty = (form) => {
 			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;
-	}
+	else if (element instanceof HTMLSelectElement && isSelectDirty(element)) return true;
 	return false;
 };
+/**
+* A drop-down with no option marked as the default still shows one — its
+* first option — and a reset goes back to that one too, so the baseline is
+* the option a reset would select, not each option's `defaultSelected`.
+*/
+const isSelectDirty = (select) => {
+	const options = [...select.options];
+	if (select.multiple) return options.some((option) => option.selected !== option.defaultSelected);
+	const baseline = options.filter((option) => option.defaultSelected).at(-1) ?? (select.size > 1 ? void 0 : options.find((option) => !option.disabled));
+	return select.selectedIndex !== (baseline?.index ?? -1);
+};
 //#endregion
 export { useForm };