@zeno-lib/forms 0.3.0 → 0.5.0

package/dist/create-zeno-form.mjs

@@ -3,11 +3,13 @@ import { applyValidationError } from "./lib/apply-validation-error.mjs";
 import { fieldContext, formContext } from "./lib/contexts.mjs";
 import { deepMergeDefaults, extractZodDefaults } from "./lib/schema-defaults.mjs";
 import { getRequiredPaths } from "./lib/schema-required.mjs";
+import { DEFAULT_VALIDATION_MODE, setFormZenoState } from "./lib/validation-modes.mjs";
+import { withEmptyStartValues } from "./lib/empty-value.mjs";
+import { setSubmitError } from "./lib/submit-error.mjs";
 import { useRebasedDefaultValues } from "./lib/use-rebased-default-values.mjs";
 import { useUnsavedChangesWarning } from "./lib/use-unsaved-changes-warning.mjs";
 import { ValidationError } from "./lib/validation-error.mjs";
 import { blurThenChangeLogic } from "./lib/validation-logic.mjs";
-import { DEFAULT_VALIDATION_MODE, setFormZenoState } from "./lib/validation-modes.mjs";
 import { createFormHook } from "@tanstack/react-form";
 import { useMemo } from "react";
 import { jsx } from "react/jsx-runtime";
@@ -76,6 +78,7 @@ function createZenoForm(config) {
 			resolvedValidationLogic = mode === "blur-then-change" ? blurThenChangeLogic : void 0;
 		}
 		const wrappedOnSubmit = userOnSubmit ? (async (props) => {
+			const { submissionAttempts } = props.formApi.state;
 			try {
 				await userOnSubmit(props);
 			} catch (error) {
@@ -83,11 +86,13 @@ function createZenoForm(config) {
 					applyValidationError(props.formApi, error);
 					return;
 				}
+				const { state } = props.formApi;
+				if (state.values === props.value && state.submissionAttempts === submissionAttempts) setSubmitError(props.formApi, error);
 				throw error;
 			}
 		}) : void 0;
-		const requiredFields = useMemo(() => schema && requiredIndicator ? getRequiredPaths(schema) : /* @__PURE__ */ new Set(), [schema, requiredIndicator]);
-		const schemaDefaults = useMemo(() => schema ? extractZodDefaults(schema) : void 0, [schema]);
+		const requiredFields = useMemo(() => schema ? getRequiredPaths(schema) : /* @__PURE__ */ new Set(), [schema]);
+		const schemaDefaults = useMemo(() => schema ? withEmptyStartValues(schema, extractZodDefaults(schema)) : void 0, [schema]);
 		const mergedDefaultValues = useMemo(() => schemaDefaults ? deepMergeDefaults(schemaDefaults, userDefaultValues) : userDefaultValues, [schemaDefaults, userDefaultValues]);
 		const rebased = useRebasedDefaultValues(mergedDefaultValues);
 		const listeners = withMountListener(rest.listeners, rebased.onMount);
@@ -103,6 +108,7 @@ function createZenoForm(config) {
 			hideFieldErrors,
 			requiredFields,
 			requiredIndicator,
+			schema,
 			...schemaMode === void 0 ? {} : { validation: schemaMode }
 		});
 		useUnsavedChangesWarning(form, unsavedChangesWarning);

package/dist/form-element.mjs

@@ -1,5 +1,7 @@
 "use client";
 import { FormProvider as FormProvider$1, useFormContext } from "./lib/contexts.mjs";
+import { reportSubmitError } from "./lib/submit-error.mjs";
+import { focusFirstInvalid, restoreFocus } from "./lib/focus-first-invalid.mjs";
 import { jsx } from "react/jsx-runtime";
 //#region src/form-element.tsx
 function FormProvider({ children, form }) {
@@ -17,11 +19,11 @@ function Form({ children, className, ...props }) {
 			event.preventDefault();
 			event.stopPropagation();
 			const node = event.currentTarget;
-			await Promise.resolve(form.handleSubmit()).catch(() => void 0);
-			if (!form.state.isValid) {
-				const invalid = node.querySelector("[aria-invalid=\"true\"]");
-				(invalid ? [invalid, ...invalid.querySelectorAll("*")] : []).find((el) => el.tabIndex >= 0)?.focus();
-			}
+			const focused = node.ownerDocument.activeElement;
+			await Promise.resolve(form.handleSubmit()).catch(reportSubmitError);
+			const { isSubmitSuccessful, isValid } = form.state;
+			if (!isValid && focusFirstInvalid(node)) return;
+			if (!(isValid && isSubmitSuccessful)) restoreFocus(focused);
 		},
 		...props,
 		children

package/dist/index.d.mts

@@ -6,7 +6,7 @@ import { FieldMessage, ValidationError } from "./lib/validation-error.mjs";
 import { applyValidationError } from "./lib/apply-validation-error.mjs";
 import { useFieldContext, useFormContext } from "./lib/contexts.mjs";
 import { SubmitActionOptions, SubmitActionSchema, applyActionError, submitAction } from "./lib/submit-action.mjs";
-import { useHideFieldErrors, useIsFieldRequired, useIsInvalid } from "./lib/use-is-invalid.mjs";
+import { useHideFieldErrors, useIsFieldRequired, useIsFieldRequiredBySchema, useIsInvalid } from "./lib/use-is-invalid.mjs";
 import { blurThenChangeLogic } from "./lib/validation-logic.mjs";
 import { useSelector } from "@tanstack/react-form";
-export { type ActionError, type ActionIssue, type ActionResult, type FieldMessage, Form, FormProvider, type SubmitActionOptions, type SubmitActionSchema, ValidationError, type ValidationMode, applyActionError, applyValidationError, blurThenChangeLogic, createZenoForm, submitAction, toActionError, toFieldName, useFieldContext, useFormContext, useHideFieldErrors, useIsFieldRequired, useIsInvalid, useSelector };
+export { type ActionError, type ActionIssue, type ActionResult, type FieldMessage, Form, FormProvider, type SubmitActionOptions, type SubmitActionSchema, ValidationError, type ValidationMode, applyActionError, applyValidationError, blurThenChangeLogic, createZenoForm, submitAction, toActionError, toFieldName, useFieldContext, useFormContext, useHideFieldErrors, useIsFieldRequired, useIsFieldRequiredBySchema, useIsInvalid, useSelector };

package/dist/index.mjs

@@ -1,11 +1,11 @@
 import { applyValidationError } from "./lib/apply-validation-error.mjs";
 import { useFieldContext, useFormContext } from "./lib/contexts.mjs";
+import { toActionError, toFieldName } from "./lib/action-result.mjs";
 import { ValidationError } from "./lib/validation-error.mjs";
 import { blurThenChangeLogic } from "./lib/validation-logic.mjs";
 import { createZenoForm } from "./create-zeno-form.mjs";
 import { Form, FormProvider } from "./form-element.mjs";
-import { toActionError, toFieldName } from "./lib/action-result.mjs";
 import { applyActionError, submitAction } from "./lib/submit-action.mjs";
-import { useHideFieldErrors, useIsFieldRequired, useIsInvalid } from "./lib/use-is-invalid.mjs";
+import { useHideFieldErrors, useIsFieldRequired, useIsFieldRequiredBySchema, useIsInvalid } from "./lib/use-is-invalid.mjs";
 import { useSelector } from "@tanstack/react-form";
-export { Form, FormProvider, ValidationError, applyActionError, applyValidationError, blurThenChangeLogic, createZenoForm, submitAction, toActionError, toFieldName, useFieldContext, useFormContext, useHideFieldErrors, useIsFieldRequired, useIsInvalid, useSelector };
+export { Form, FormProvider, ValidationError, applyActionError, applyValidationError, blurThenChangeLogic, createZenoForm, submitAction, toActionError, toFieldName, useFieldContext, useFormContext, useHideFieldErrors, useIsFieldRequired, useIsFieldRequiredBySchema, useIsInvalid, useSelector };

package/dist/lib/empty-value.d.mts

@@ -0,0 +1,12 @@
+import { StandardSchemaLike } from "./schema-required.mjs";
+import { AnyFieldApi } from "@tanstack/react-form";
+//#region src/lib/empty-value.d.ts
+declare function emptyValueFor(schema: StandardSchemaLike | undefined, values: unknown, name: string, fallback: unknown): unknown;
+declare function withEmptyStartValues(schema: StandardSchemaLike, defaults: Record<string, unknown>): Record<string, unknown>;
+/**
+ * The value `field` takes when the user clears it, by the rule above. Typed as
+ * the field's value, since the same schema decides both.
+ */
+declare function getEmptyValue<T>(field: AnyFieldApi, fallback: T): T;
+//#endregion
+export { emptyValueFor, getEmptyValue, withEmptyStartValues };

package/dist/lib/empty-value.mjs

@@ -0,0 +1,68 @@
+import { toFieldName } from "./action-result.mjs";
+import { extractZodDefaultAt } from "./schema-defaults.mjs";
+import { validateSync } from "./schema-required.mjs";
+import { getFormSchema } from "./validation-modes.mjs";
+//#region src/lib/empty-value.ts
+const NAME_SEGMENT = /[^.[\]]+/g;
+const INDEX = /^\d+$/;
+function toPathKeys(name) {
+	return (name.match(NAME_SEGMENT) ?? []).map((part) => INDEX.test(part) ? Number(part) : part);
+}
+function valueAt(root, keys) {
+	let node = root;
+	for (const key of keys) {
+		if (typeof node !== "object" || node === null) return;
+		node = node[key];
+	}
+	return node;
+}
+function withValueAt(root, keys, value) {
+	const [key, ...rest] = keys;
+	if (key === void 0) return value;
+	const node = root ?? (typeof key === "number" ? [] : {});
+	const copy = Array.isArray(node) ? [...node] : { ...node };
+	copy[key] = withValueAt(node[key], rest, value);
+	return copy;
+}
+function emptyValueFor(schema, values, name, fallback) {
+	if (!schema) return fallback;
+	const keys = toPathKeys(name);
+	const fieldName = toFieldName(keys);
+	const typeEmpty = extractZodDefaultAt(schema, keys);
+	const candidates = typeEmpty.ok ? [
+		null,
+		void 0,
+		typeEmpty.value
+	] : [null, void 0];
+	for (const candidate of candidates) {
+		const issues = validateSync(schema, withValueAt(values, keys, candidate));
+		if (!issues) return fallback;
+		if (!issues.some((issue) => toFieldName(issue.path) === fieldName)) return candidate;
+	}
+	return fallback;
+}
+function isTypeEmpty(value) {
+	return value === "" || Array.isArray(value) && value.length === 0;
+}
+function withEmptyStartValues(schema, defaults) {
+	const issues = validateSync(schema, defaults);
+	let result = defaults;
+	for (const issue of issues ?? []) {
+		const name = toFieldName(issue.path);
+		const keys = toPathKeys(name);
+		const start = valueAt(defaults, keys);
+		if (keys.length === 0 || !isTypeEmpty(start)) continue;
+		const empty = emptyValueFor(schema, result, name, start);
+		if (empty !== start) result = withValueAt(result, keys, empty);
+	}
+	return result;
+}
+/**
+* The value `field` takes when the user clears it, by the rule above. Typed as
+* the field's value, since the same schema decides both.
+*/
+function getEmptyValue(field, fallback) {
+	return emptyValueFor(getFormSchema(field.form), field.form.state.values, field.name, fallback);
+}
+//#endregion
+export { emptyValueFor, getEmptyValue, withEmptyStartValues };

package/dist/lib/focus-first-invalid.d.mts

@@ -0,0 +1,23 @@
+//#region src/lib/focus-first-invalid.d.ts
+/**
+ * Move focus to the first invalid control inside `root` (a `<form>`): the
+ * first element with `aria-invalid="true"`, or, for a group root that can't
+ * take focus itself (radio group, slider), its first tabbable descendant. An
+ * invalid control that won't take focus (disabled, hidden) is skipped for the
+ * next one. Call it after `await form.handleSubmit()` leaves the form invalid.
+ * Searching only `root` keeps focus inside the submitted form, so a dialog's
+ * form never sends it to the page behind. Returns the focused element, or
+ * `null`.
+ */
+declare function focusFirstInvalid(root: ParentNode | null | undefined): HTMLElement | null;
+/**
+ * Give focus back to `element`, what had it when the submit started, if the
+ * submit dropped it to the body. A submit button that disables itself while
+ * submitting does that in browsers, so a failed submit with no invalid field
+ * to focus would otherwise leave the user nowhere. It doesn't scroll, so a
+ * user who scrolled away during a slow submit stays put. Returns whether it
+ * moved focus.
+ */
+declare function restoreFocus(element: Element | null): boolean;
+//#endregion
+export { focusFirstInvalid, restoreFocus };

package/dist/lib/focus-first-invalid.mjs

@@ -0,0 +1,37 @@
+//#region src/lib/focus-first-invalid.ts
+/**
+* Move focus to the first invalid control inside `root` (a `<form>`): the
+* first element with `aria-invalid="true"`, or, for a group root that can't
+* take focus itself (radio group, slider), its first tabbable descendant. An
+* invalid control that won't take focus (disabled, hidden) is skipped for the
+* next one. Call it after `await form.handleSubmit()` leaves the form invalid.
+* Searching only `root` keeps focus inside the submitted form, so a dialog's
+* form never sends it to the page behind. Returns the focused element, or
+* `null`.
+*/
+function focusFirstInvalid(root) {
+	const invalid = root?.querySelectorAll("[aria-invalid=\"true\"]");
+	for (const element of invalid ?? []) for (const target of [element, ...element.querySelectorAll("*")]) {
+		if (target.tabIndex < 0) continue;
+		target.focus();
+		if (target.ownerDocument.activeElement === target) return target;
+	}
+	return null;
+}
+/**
+* Give focus back to `element`, what had it when the submit started, if the
+* submit dropped it to the body. A submit button that disables itself while
+* submitting does that in browsers, so a failed submit with no invalid field
+* to focus would otherwise leave the user nowhere. It doesn't scroll, so a
+* user who scrolled away during a slow submit stays put. Returns whether it
+* moved focus.
+*/
+function restoreFocus(element) {
+	if (!(element instanceof HTMLElement && element.isConnected)) return false;
+	const active = element.ownerDocument.activeElement;
+	if (active !== null && active !== element.ownerDocument.body) return false;
+	element.focus({ preventScroll: true });
+	return element.ownerDocument.activeElement === element;
+}
+//#endregion
+export { focusFirstInvalid, restoreFocus };

package/dist/lib/schema-defaults.d.mts

@@ -9,9 +9,17 @@ type SchemaDef = {
   readonly innerType?: SchemaNode;
   readonly shape?: Record<string, SchemaNode>;
   readonly in?: SchemaNode;
+  readonly element?: SchemaNode;
   readonly defaultValue?: unknown;
 };
+type ExtractResult = {
+  ok: true;
+  value: unknown;
+} | {
+  ok: false;
+};
 declare function extractZodDefaults(schema: SchemaNode): Record<string, unknown>;
+declare function extractZodDefaultAt(schema: SchemaNode, keys: readonly PropertyKey[]): ExtractResult;
 declare function deepMergeDefaults(schemaDefaults: Record<string, unknown>, userDefaults: Record<string, unknown> | undefined): Record<string, unknown>;
 //#endregion
-export { deepMergeDefaults, extractZodDefaults };
+export { deepMergeDefaults, extractZodDefaultAt, extractZodDefaults };

package/dist/lib/schema-defaults.mjs

@@ -57,6 +57,38 @@ function extractZodDefaults(schema) {
 		return {};
 	}
 }
+function childAt(node, key) {
+	let current = node;
+	for (let depth = 0; depth < MAX_WRAPPER_DEPTH; depth += 1) {
+		const def = getDef(current);
+		switch (def?.type) {
+			case "object": return typeof key === "string" && def.shape?.[key] || null;
+			case "array": return typeof key === "number" && def.element || null;
+			case "default":
+			case "nonoptional":
+			case "nullable":
+			case "optional":
+			case "prefault":
+			case "readonly":
+				current = def.innerType;
+				continue;
+			case "pipe":
+				current = def.in;
+				continue;
+			default: return null;
+		}
+	}
+	return null;
+}
+function extractZodDefaultAt(schema, keys) {
+	try {
+		let node = schema;
+		for (const key of keys) node = node && childAt(node, key);
+		return node && keys.length > 0 ? extractDefaultForField(node) : { ok: false };
+	} catch {
+		return { ok: false };
+	}
+}
 function isPlainObject(value) {
 	return typeof value === "object" && value !== null && Object.getPrototypeOf(value) === Object.prototype;
 }
@@ -72,4 +104,4 @@ function deepMergeDefaults(schemaDefaults, userDefaults) {
 	return result;
 }
 //#endregion
-export { deepMergeDefaults, extractZodDefaults };
+export { deepMergeDefaults, extractZodDefaultAt, extractZodDefaults };

package/dist/lib/schema-required.d.mts

@@ -20,6 +20,7 @@ type StandardSchemaLike = {
  * `getRequiredPaths` records (`members[0].name`).
  */
 declare function toRequiredPathKey(name: string): string;
+declare function validateSync(schema: StandardSchemaLike, value: unknown): readonly StandardIssue[] | undefined;
 declare function getRequiredPaths(schema: StandardSchemaLike): Set<string>;
 //#endregion
-export { type StandardSchemaLike, getRequiredPaths, toRequiredPathKey };
+export { type StandardSchemaLike, getRequiredPaths, toRequiredPathKey, validateSync };

package/dist/lib/schema-required.mjs

@@ -1,5 +1,5 @@
 //#region src/lib/schema-required.ts
-const MAX_PROBE_DEPTH = 8;
+const MAX_PROBE_DEPTH = 16;
 const INDEX_SEGMENT = /^\d+$/;
 const INDEX_IN_NAME = /\[\d+\]|\.(\d+)(?=\.|\[|$)/g;
 function pathKey(part) {
@@ -23,15 +23,14 @@ function toRequiredPathKey(name) {
 	return name.replace(INDEX_IN_NAME, "[0]");
 }
 function probeValue(expected) {
-	if (typeof expected !== "string") return;
-	switch (expected.toLowerCase()) {
+	switch (typeof expected === "string" ? expected.toLowerCase() : void 0) {
 		case "object": return {};
-		case "array": return [{}];
+		case "array": return [];
 		case "string": return "";
-		default: return;
+		default: return null;
 	}
 }
-function fillAt(root, keys, value) {
+function fillAt(root, keys, value, replace = false) {
 	let node = root;
 	for (const key of keys.slice(0, -1)) {
 		const next = node[key];
@@ -39,7 +38,7 @@ function fillAt(root, keys, value) {
 		node = next;
 	}
 	const last = keys.at(-1);
-	if (node[last] !== void 0) return false;
+	if (!replace && node[last] !== void 0) return false;
 	node[last] = value;
 	return true;
 }
@@ -53,41 +52,70 @@ function validateSync(schema, value) {
 	if (result instanceof Promise) return;
 	return "issues" in result && result.issues ? result.issues : [];
 }
-function recordPass(issues, probe, required) {
+function recordPass(issues, probe, required, cleared) {
 	const failing = /* @__PURE__ */ new Set();
-	const filledStrings = [];
-	let descended = false;
+	const filled = [];
 	for (const issue of issues) {
 		const keys = issue.path?.map(pathKey) ?? [];
 		if (keys.length === 0) continue;
 		const path = joinPath(keys);
 		failing.add(path);
-		required.add(path);
+		if (!cleared.has(path)) required.add(path);
 		const value = probeValue(issue.expected);
-		if (value !== void 0 && fillAt(probe, keys, value)) {
+		if (value !== void 0 && fillAt(probe, keys, value)) filled.push({
+			keys,
+			path,
+			value
+		});
+	}
+	return {
+		failing,
+		filled
+	};
+}
+function isEmptyProbe(value) {
+	return value === "" || value === null || Array.isArray(value);
+}
+function settleEmptied(emptied, failing, probe, required, cleared) {
+	const next = [];
+	let descended = false;
+	for (const fill of emptied) {
+		const passed = !failing.has(fill.path);
+		if (passed) {
+			required.delete(fill.path);
+			cleared.add(fill.path);
+		}
+		if (Array.isArray(fill.value)) {
+			fill.value.push(void 0);
+			descended = true;
+		} else if (!passed && fill.value === "") {
+			fillAt(probe, fill.keys, null, true);
+			next.push({
+				...fill,
+				value: null
+			});
 			descended = true;
-			if (value === "") filledStrings.push(path);
 		}
 	}
 	return {
 		descended,
-		failing,
-		filledStrings
+		next
 	};
 }
 function getRequiredPaths(schema) {
 	const required = /* @__PURE__ */ new Set();
+	const cleared = /* @__PURE__ */ new Set();
 	const probe = {};
-	let filledStrings = [];
+	let emptied = [];
 	for (let depth = 0; depth < MAX_PROBE_DEPTH; depth += 1) {
 		const issues = validateSync(schema, probe);
 		if (!issues) return required;
-		const { descended, failing, filledStrings: filled } = recordPass(issues, probe, required);
-		for (const path of filledStrings) if (!failing.has(path)) required.delete(path);
-		filledStrings = filled;
-		if (!descended) break;
+		const { failing, filled } = recordPass(issues, probe, required, cleared);
+		const settled = settleEmptied(emptied, failing, probe, required, cleared);
+		emptied = [...filled.filter(({ value }) => isEmptyProbe(value)), ...settled.next];
+		if (filled.length === 0 && !settled.descended) break;
 	}
 	return required;
 }
 //#endregion
-export { getRequiredPaths, toRequiredPathKey };
+export { getRequiredPaths, toRequiredPathKey, validateSync };

package/dist/lib/submit-action.mjs

@@ -1,6 +1,6 @@
 import { applyValidationError } from "./apply-validation-error.mjs";
-import { ValidationError } from "./validation-error.mjs";
 import { toActionError } from "./action-result.mjs";
+import { ValidationError } from "./validation-error.mjs";
 //#region src/lib/submit-action.ts
 function applyActionError(formApi, error) {
 	const fields = {};

package/dist/lib/submit-error.d.mts

@@ -0,0 +1,36 @@
+//#region src/lib/submit-error.d.ts
+type SubmitErrorState = {
+  readonly submissionAttempts: number;
+  readonly values: unknown;
+};
+type SubmitErrorForm = {
+  readonly state: SubmitErrorState;
+  readonly store: {
+    subscribe: (listener: () => void) => {
+      unsubscribe: () => void;
+    };
+  };
+};
+type SubmitError = {
+  /** What the submit handler threw. */
+  readonly error: unknown;
+};
+/**
+ * Record that `form`'s submit threw `error`. `useForm` calls it for what
+ * `onSubmit` throws; call it for a failure your own submit code catches
+ * outside `onSubmit`. The error lasts until the values change or the next
+ * submit starts (`reset()` does both), so an edit or a retry clears it. A
+ * Next.js navigation (`redirect()`, `notFound()`) is ignored.
+ */
+declare function setSubmitError(form: SubmitErrorForm, error: unknown): void;
+/**
+ * Report a submit rejection that is caught so the user can retry, as
+ * `<Form>` and `FormDialog` do: `reportError` logs it and passes it to the
+ * page's `error` listeners (where error monitoring hooks in), as if it were
+ * uncaught. A Next.js navigation is skipped.
+ */
+declare function reportSubmitError(error: unknown): void;
+/** The error `form`'s last submit threw, until it went stale. */
+declare function useSubmitError(form: SubmitErrorForm): SubmitError | undefined;
+//#endregion
+export { type SubmitError, type SubmitErrorForm, reportSubmitError, setSubmitError, useSubmitError };

package/dist/lib/submit-error.mjs

@@ -0,0 +1,66 @@
+"use client";
+import { useCallback, useSyncExternalStore } from "react";
+//#region src/lib/submit-error.ts
+const entries = /* @__PURE__ */ new WeakMap();
+const listeners = /* @__PURE__ */ new WeakMap();
+function notify(key) {
+	for (const listener of listeners.get(key) ?? []) listener();
+}
+function clear(key) {
+	const entry = entries.get(key);
+	if (entry) {
+		entry.unsubscribe();
+		entries.delete(key);
+		notify(key);
+	}
+}
+function isNavigationError(error) {
+	if (typeof error !== "object" || error === null || !("digest" in error)) return false;
+	return typeof error.digest === "string" && error.digest.startsWith("NEXT_");
+}
+/**
+* Record that `form`'s submit threw `error`. `useForm` calls it for what
+* `onSubmit` throws; call it for a failure your own submit code catches
+* outside `onSubmit`. The error lasts until the values change or the next
+* submit starts (`reset()` does both), so an edit or a retry clears it. A
+* Next.js navigation (`redirect()`, `notFound()`) is ignored.
+*/
+function setSubmitError(form, error) {
+	if (isNavigationError(error)) return;
+	const key = form.store;
+	entries.get(key)?.unsubscribe();
+	const { submissionAttempts, values } = form.state;
+	const subscription = form.store.subscribe(() => {
+		const { state } = form;
+		if (state.values !== values || state.submissionAttempts !== submissionAttempts) clear(key);
+	});
+	entries.set(key, {
+		submitError: { error },
+		unsubscribe: subscription.unsubscribe
+	});
+	notify(key);
+}
+/**
+* Report a submit rejection that is caught so the user can retry, as
+* `<Form>` and `FormDialog` do: `reportError` logs it and passes it to the
+* page's `error` listeners (where error monitoring hooks in), as if it were
+* uncaught. A Next.js navigation is skipped.
+*/
+function reportSubmitError(error) {
+	if (!isNavigationError(error)) globalThis.reportError?.(error);
+}
+/** The error `form`'s last submit threw, until it went stale. */
+function useSubmitError(form) {
+	const key = form.store;
+	const subscribe = useCallback((listener) => {
+		const set = listeners.get(key) ?? /* @__PURE__ */ new Set();
+		listeners.set(key, set);
+		set.add(listener);
+		return () => {
+			set.delete(listener);
+		};
+	}, [key]);
+	return useSyncExternalStore(subscribe, () => entries.get(key)?.submitError, () => void 0);
+}
+//#endregion
+export { reportSubmitError, setSubmitError, useSubmitError };

package/dist/lib/use-form-dialog.d.mts

@@ -47,6 +47,11 @@ declare function useFormDialog<TValues>(options?: UseFormDialogOptions<TValues>)
 type UseLeaveGuardOptions = {
   /** Whether leaving now would lose changes. */
   hasUnsavedChanges: boolean;
+  /**
+   * Save the changes and resolve whether that worked. Backs `saveAndLeave`,
+   * so the confirm UI can offer Save next to Discard.
+   */
+  onSave?: () => boolean | Promise<boolean>;
 };
 type LeaveGuard = {
   /**
@@ -60,9 +65,18 @@ type LeaveGuard = {
   confirmLeave: () => void;
   /** The user chose to stay: drop the held leave. */
   cancelLeave: () => void;
+  /**
+   * The user chose to save: run `onSave`, then the held leave if it saved.
+   * Either way the confirm UI closes; after a failed save the user stays.
+   * Resolves whether it saved. A rejection from `onSave` keeps the leave held
+   * and propagates.
+   */
+  saveAndLeave: () => Promise<boolean>;
+  /** Whether `saveAndLeave` is waiting on `onSave`. */
+  isSaving: boolean;
 };
 /** Ask before a leave (close, navigate, switch record) drops unsaved changes. */
-declare function useLeaveGuard({ hasUnsavedChanges }: UseLeaveGuardOptions): LeaveGuard;
+declare function useLeaveGuard({ hasUnsavedChanges, onSave }: UseLeaveGuardOptions): LeaveGuard;
 /**
  * Find the element to focus for field `name` inside `root`: the control with
  * `id={name}` (fields that use the name as their id), else, inside the field

package/dist/lib/use-form-dialog.mjs

@@ -44,9 +44,10 @@ function useFormDialog(options = {}) {
 	};
 }
 /** Ask before a leave (close, navigate, switch record) drops unsaved changes. */
-function useLeaveGuard({ hasUnsavedChanges }) {
+function useLeaveGuard({ hasUnsavedChanges, onSave }) {
 	const pending = useRef(null);
 	const [isConfirming, setIsConfirming] = useState(false);
+	const [isSaving, setIsSaving] = useState(false);
 	const requestLeave = useCallback((proceed) => {
 		if (!hasUnsavedChanges) {
 			proceed();
@@ -68,7 +69,24 @@ function useLeaveGuard({ hasUnsavedChanges }) {
 		}, []),
 		confirmLeave,
 		isConfirming,
-		requestLeave
+		isSaving,
+		requestLeave,
+		saveAndLeave: useCallback(async () => {
+			const proceed = pending.current;
+			if (!(proceed && onSave)) return false;
+			setIsSaving(true);
+			let saved = false;
+			try {
+				saved = await onSave();
+			} finally {
+				setIsSaving(false);
+			}
+			if (pending.current !== proceed) return saved;
+			pending.current = null;
+			setIsConfirming(false);
+			if (saved) proceed();
+			return saved;
+		}, [onSave])
 	};
 }
 const FOCUSABLE = "input:not([type=\"hidden\"]):not([disabled]), textarea:not([disabled]), select:not([disabled]), button:not([disabled]), [tabindex]:not([tabindex=\"-1\"])";

package/dist/lib/use-is-invalid.d.mts

@@ -3,5 +3,6 @@ import { AnyFieldApi } from "@tanstack/react-form";
 declare function useIsInvalid(field: AnyFieldApi): boolean;
 declare function useHideFieldErrors(field: AnyFieldApi): boolean;
 declare function useIsFieldRequired(field: AnyFieldApi): boolean;
+declare function useIsFieldRequiredBySchema(field: AnyFieldApi): boolean;
 //#endregion
-export { useHideFieldErrors, useIsFieldRequired, useIsInvalid };
+export { useHideFieldErrors, useIsFieldRequired, useIsFieldRequiredBySchema, useIsInvalid };

package/dist/lib/use-is-invalid.mjs

@@ -1,5 +1,5 @@
 "use client";
-import { getFormHideFieldErrors, getFormValidationMode, isFieldRequired } from "./validation-modes.mjs";
+import { getFormHideFieldErrors, getFormValidationMode, isFieldRequired, isFieldRequiredBySchema } from "./validation-modes.mjs";
 import { useSelector } from "@tanstack/react-form";
 //#region src/lib/use-is-invalid.ts
 function hasFieldLevelError(errorMap, errorSourceMap, cause) {
@@ -27,5 +27,8 @@ function useHideFieldErrors(field) {
 function useIsFieldRequired(field) {
 	return isFieldRequired(field.form, field.name);
 }
+function useIsFieldRequiredBySchema(field) {
+	return isFieldRequiredBySchema(field.form, field.name);
+}
 //#endregion
-export { useHideFieldErrors, useIsFieldRequired, useIsInvalid };
+export { useHideFieldErrors, useIsFieldRequired, useIsFieldRequiredBySchema, useIsInvalid };