@zeno-lib/forms 0.4.0 → 0.5.0

package/dist/create-zeno-form.mjs

@@ -5,6 +5,7 @@ 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";
@@ -77,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) {
@@ -84,6 +86,8 @@ 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;

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/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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zeno-lib/forms",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "repository": {
     "url": "https://github.com/zeno-lib/zeno.git",
     "directory": "packages/forms"

package/src/create-form.tsx

@@ -8,6 +8,7 @@ import { CheckboxGroupField } from "./fields/checkbox-group-field"
 import { ComboboxField } from "./fields/combobox-field"
 import { DatePickerField } from "./fields/date-picker-field"
 import { EmailField } from "./fields/email-field"
+import { FormError } from "./fields/form-error"
 import { InputField } from "./fields/input-field"
 import { MoneyField } from "./fields/money-field"
 import { MultiSelectField } from "./fields/multi-select-field"
@@ -48,6 +49,7 @@ const { useAppForm, useForm, withFieldGroup, withForm } = createZenoForm({
     YearField,
   },
   formComponents: {
+    FormError,
     ResetButton,
     SubmitButton,
   },

package/src/create-zeno-form.tsx

@@ -18,6 +18,7 @@ import {
   getRequiredPaths,
   type StandardSchemaLike,
 } from "./lib/schema-required"
+import { setSubmitError } from "./lib/submit-error"
 import { useRebasedDefaultValues } from "./lib/use-rebased-default-values"
 import { useUnsavedChangesWarning } from "./lib/use-unsaved-changes-warning"
 import { ValidationError } from "./lib/validation-error"
@@ -439,6 +440,7 @@ export function createZenoForm<
 
     const wrappedOnSubmit = userOnSubmit
       ? ((async (props: { formApi: AnyFormApi; value: TFormData }) => {
+          const { submissionAttempts } = props.formApi.state
           try {
             await (
               userOnSubmit as unknown as (
@@ -450,6 +452,16 @@ export function createZenoForm<
               applyValidationError(props.formApi, error)
               return
             }
+            // Kept for `FormError`, unless an edit, a reset (a dialog closed
+            // meanwhile) or a newer submit came first: then it is about
+            // values no longer on screen.
+            const { state } = props.formApi
+            if (
+              state.values === props.value &&
+              state.submissionAttempts === submissionAttempts
+            ) {
+              setSubmitError(props.formApi, error)
+            }
             throw error
           }
         }) as typeof userOnSubmit)

package/src/fields/form-error.tsx

@@ -0,0 +1,61 @@
+"use client"
+
+import { useFormContext } from "@zeno-lib/forms/lib/contexts"
+import { useSubmitError } from "@zeno-lib/forms/lib/submit-error"
+import { useSelector } from "@zeno-lib/forms/tanstack"
+import type { ComponentProps, ReactNode } from "react"
+import { FieldError } from "@/components/ui/field"
+
+type FormErrorProps = Omit<
+  ComponentProps<typeof FieldError>,
+  "children" | "errors"
+> & {
+  /**
+   * Shown when the submit handler throws (a network failure, an unexpected
+   * server error). Defaults to `"Something went wrong. Try again."`. A
+   * function gets what was thrown.
+   */
+  submitErrorMessage?: ReactNode | ((error: unknown) => ReactNode)
+}
+
+/**
+ * The form-level error, as a `role="alert"` message: the `formErrors` an
+ * action returns through `submitAction`, a `ValidationError`'s `formError`,
+ * or `submitErrorMessage` when the submit throws. Renders nothing otherwise.
+ * It clears when the user edits the form, and a thrown one also when they
+ * submit again.
+ */
+function FormError({
+  submitErrorMessage = "Something went wrong. Try again.",
+  ...props
+}: FormErrorProps) {
+  const form = useFormContext()
+  const formError = useSelector(form.store, (state) => state.errorMap.onSubmit)
+  const submitError = useSubmitError(form)
+
+  // `submitAction` joins several messages with a line break. A schema's
+  // form-level result is an object, not a message, and isn't shown here. It
+  // wins over a thrown submit: it says what went wrong.
+  if (typeof formError === "string" && formError !== "") {
+    return (
+      <FieldError
+        data-slot="form-error"
+        errors={formError.split("\n").map((message) => ({ message }))}
+        {...props}
+      />
+    )
+  }
+  if (!submitError) {
+    return null
+  }
+  return (
+    <FieldError data-slot="form-error" {...props}>
+      {typeof submitErrorMessage === "function"
+        ? submitErrorMessage(submitError.error)
+        : submitErrorMessage}
+    </FieldError>
+  )
+}
+
+export type { FormErrorProps }
+export { FormError }

package/src/fields/index.ts

@@ -4,6 +4,7 @@ export * from "./checkbox-group-field"
 export * from "./combobox-field"
 export * from "./date-picker-field"
 export * from "./email-field"
+export * from "./form-error"
 export * from "./input-field"
 export * from "./money-field"
 export * from "./multi-select-field"