import { useCallback, useId, useMemo, useRef, useState, type ChangeEvent, type FormEvent, } from "react"; import { flushSync } from "react-dom"; import type { ZodIssue, ZodType } from "../../contracts/zod.ts"; import type { AppFailure } from "../../contracts/errors.ts"; import { useLocale, type ParameterlessMessageKey, } from "../i18n/index.ts"; import { mapValidationFailureToFields, validationMessage, type FieldErrors, type FieldName, type FormResult, type FormResultState, type FormValues, } from "./form-contracts.ts"; type AppFormOptions< Values extends FormValues, Command, Output, > = Readonly<{ schema: ZodType; defaultValues: Values; allowedServerFields: readonly FieldName[]; mapToCommand(values: Values): Command; submit(command: Command): Promise>; resetOnSuccess?: boolean; }>; export function useAppForm< Values extends FormValues, Command, Output, >(options: AppFormOptions) { const { resolve } = useLocale(); const { schema, defaultValues, allowedServerFields, mapToCommand, submit, resetOnSuccess = true, } = options; const generatedId = useId().replaceAll(":", ""); const formId = `app-form-${generatedId}`; const [values, setValues] = useState(defaultValues); const [initialValues, setInitialValues] = useState(defaultValues); const [touched, setTouched] = useState>>( () => new Set(), ); // 08-10. Errors are held as message keys and translated on render, so a // locale change re-translates the ones already on screen. const [fieldErrorKeys, setFieldErrors] = useState>( () => ({} as FieldErrors), ); const [formErrorKeys, setFormErrors] = useState([]); const fieldErrors = useMemo( () => Object.freeze( Object.fromEntries( Object.entries(fieldErrorKeys).map(([name, key]) => [ name, resolve(String(key)), ]), ), ) as FieldErrors, [fieldErrorKeys, resolve], ); const formErrors = useMemo( () => formErrorKeys.map((key) => resolve(key)), [formErrorKeys, resolve], ); const [pending, setPending] = useState(false); const [result, setResult] = useState("idle"); const [statusFailure, setStatusFailure] = useState(null); const pendingRef = useRef | null> | null>(null); const unknownSubmissionRef = useRef(null); const dirty = useMemo( () => JSON.stringify(values) !== JSON.stringify(initialValues), [initialValues, values], ); const fieldId = useCallback( (name: FieldName) => `${formId}-${name}`, [formId], ); const focusField = useCallback( (name: FieldName) => { const field = document.getElementById(fieldId(name)); if (field instanceof HTMLElement) field.focus(); }, [fieldId], ); const focusFirstError = useCallback( (errors: FieldErrors) => { const first = allowedServerFields.find((name) => Boolean(errors[name])); if (first) focusField(first); }, [allowedServerFields, focusField], ); const setValue = useCallback( (name: FieldName, value: Values[FieldName]) => { setValues((current) => ({ ...current, [name]: value }) as Values); setFieldErrors((current) => { if (!current[name]) return current; const next = { ...current }; delete next[name]; return next; }); setFormErrors([]); setResult((current) => unknownSubmissionRef.current ? current : "idle", ); }, [], ); const field = useCallback( (name: FieldName) => ({ id: fieldId(name), name, value: String(values[name] ?? ""), onChange(event: ChangeEvent) { setValue(name, event.currentTarget.value as Values[FieldName]); }, onBlur() { setTouched((current) => new Set(current).add(name)); }, error: fieldErrors[name], "aria-invalid": fieldErrors[name] ? ("true" as const) : undefined, }), [fieldErrors, fieldId, setValue, values], ); const reset = useCallback( (nextValues: Values = defaultValues) => { unknownSubmissionRef.current = null; setValues(nextValues); setInitialValues(nextValues); setTouched(new Set()); setFieldErrors({} as FieldErrors); setFormErrors([]); setResult("idle"); }, [defaultValues], ); const settleSuccessfulValues = useCallback( (settledValues: Values) => { unknownSubmissionRef.current = null; // Committed before the caller continues: a `navigate()` right after a // save must meet a clean form, not the dirty guard of the last render. flushSync(() => { setFieldErrors({} as FieldErrors); setFormErrors([]); setResult("success"); if (resetOnSuccess) { setValues(defaultValues); setInitialValues(defaultValues); setTouched(new Set()); } else { setInitialValues(settledValues); } }); }, [defaultValues, resetOnSuccess], ); const settleApplied = useCallback(() => { const submittedValues = unknownSubmissionRef.current; if (!submittedValues) return; settleSuccessfulValues(submittedValues); }, [settleSuccessfulValues]); const settleNotApplied = useCallback(() => { if (!unknownSubmissionRef.current) return; unknownSubmissionRef.current = null; setFieldErrors({} as FieldErrors); setFormErrors([]); setResult("idle"); }, []); const applyOutcome = useCallback( (outcome: FormResult, submittedValues: Values) => { if (outcome.ok) { settleSuccessfulValues(submittedValues); return; } if (outcome.error.kind === "VALIDATION_REJECTED") { unknownSubmissionRef.current = null; const mapped = mapValidationFailureToFields( outcome.error, allowedServerFields, messageKey, ); setFieldErrors(mapped.fieldErrors); setFormErrors(mapped.formErrors); setResult("validation-error"); focusFirstError(mapped.fieldErrors); } else if (outcome.error.action === "reauth") { // D-2. Signing in again comes first, whatever the effect. unknownSubmissionRef.current = null; setFormErrors([]); setStatusFailure(outcome.error); setResult("reauth-required"); } else if (outcome.error.effect === "MAYBE_APPLIED") { unknownSubmissionRef.current = submittedValues; setFormErrors([]); setResult("effect-unknown"); } else if (outcome.error.effect === "APPLIED_CONFIRMED") { settleSuccessfulValues(submittedValues); } else if (outcome.error.kind === "CONFLICT") { unknownSubmissionRef.current = null; setFormErrors(["form.conflict"]); setResult("conflict"); } else if ( outcome.error.kind === "FORBIDDEN" || outcome.error.action === "retry" ) { unknownSubmissionRef.current = null; setFormErrors([]); setStatusFailure(outcome.error); setResult( outcome.error.kind === "FORBIDDEN" ? "forbidden" : "retry-later", ); } else { // F-10. Not an input error either: shown by FormFailureStatus. unknownSubmissionRef.current = null; setFormErrors([]); setStatusFailure(outcome.error); setResult("unavailable"); } }, [allowedServerFields, focusFirstError, settleSuccessfulValues], ); const validateAndSubmit = useCallback( async (): Promise | null> => { setFieldErrors({} as FieldErrors); setFormErrors([]); const parsed = await schema.safeParseAsync(values); if (!parsed.success) { const errors = issuesToFieldErrors( parsed.error.issues, allowedServerFields, messageKey, ); setFieldErrors(errors); setFormErrors( parsed.error.issues.some( (issue) => !allowedServerFields.includes(issue.path[0] as FieldName), ) ? ["form.validation.configuration"] : [], ); setTouched(new Set(allowedServerFields)); setResult("validation-error"); focusFirstError(errors); return null; } const command = mapToCommand(parsed.data); setPending(true); try { const outcome = await submit(command); applyOutcome(outcome, parsed.data); return outcome; } finally { setPending(false); } }, [ allowedServerFields, applyOutcome, focusFirstError, mapToCommand, schema, submit, values, ], ); const submitForm = useCallback( (event?: FormEvent): Promise | null> => { event?.preventDefault(); // One submission from validation to outcome: an async refine must not // let a second submit through before the command starts. if (pendingRef.current) return pendingRef.current; if (unknownSubmissionRef.current) return Promise.resolve(null); const submission = validateAndSubmit().finally(() => { pendingRef.current = null; }); pendingRef.current = submission; return submission; }, [validateAndSubmit], ); /** * D-1. Runs a resend of the unknown submission (for example * `mutation.resendUnknownEffect`) through the same outcome handling as a * submit. The form never builds a new command here: the caller resends the * original request with its original key. */ const resendUnknown = useCallback( ( send: () => Promise | null>, ): Promise | null> => { if (pendingRef.current) return pendingRef.current; // After a remount the form no longer holds the submitted values. const submittedValues = unknownSubmissionRef.current ?? values; const resend = (async () => { setPending(true); try { const outcome = await send(); if (outcome) applyOutcome(outcome, submittedValues); return outcome; } finally { setPending(false); } })().finally(() => { pendingRef.current = null; }); pendingRef.current = resend; return resend; }, [applyOutcome, values], ); return Object.freeze({ formId, values, dirty, touched, fieldErrors, formErrors, pending, result, /** * The save failure behind `reauth-required`, `forbidden`, `retry-later` * or `unavailable`. */ failure: STATUS_RESULTS.has(result) ? statusFailure : null, field, fieldId, focusField, setValue, submitForm, resendUnknown, reset, settleApplied, settleNotApplied, }); } /** Keeps the key: the form translates at render time. */ const messageKey = (key: ParameterlessMessageKey): string => key; const STATUS_RESULTS: ReadonlySet = new Set([ "reauth-required", "forbidden", "retry-later", "unavailable", ]); function issuesToFieldErrors( issues: readonly ZodIssue[], allowedFields: readonly FieldName[], message: (key: ParameterlessMessageKey) => string, ): FieldErrors { const allowed = new Set(allowedFields); const errors: Partial, string>> = {}; for (const issue of issues) { const field = issue.path[0]; if (!allowed.has(field)) continue; const name = field as FieldName; errors[name] ??= validationMessage(issue.code, message); } return Object.freeze(errors); }