Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> # Conflicts: # config/contracts/registry-change-evidence.json
397 lines
12 KiB
TypeScript
397 lines
12 KiB
TypeScript
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<Values>;
|
|
defaultValues: Values;
|
|
allowedServerFields: readonly FieldName<Values>[];
|
|
mapToCommand(values: Values): Command;
|
|
submit(command: Command): Promise<FormResult<Output>>;
|
|
resetOnSuccess?: boolean;
|
|
}>;
|
|
|
|
export function useAppForm<
|
|
Values extends FormValues,
|
|
Command,
|
|
Output,
|
|
>(options: AppFormOptions<Values, Command, Output>) {
|
|
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<Values>(defaultValues);
|
|
const [initialValues, setInitialValues] = useState<Values>(defaultValues);
|
|
const [touched, setTouched] = useState<ReadonlySet<FieldName<Values>>>(
|
|
() => 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<FieldErrors<Values>>(
|
|
() => ({} as FieldErrors<Values>),
|
|
);
|
|
const [formErrorKeys, setFormErrors] = useState<readonly string[]>([]);
|
|
const fieldErrors = useMemo(
|
|
() =>
|
|
Object.freeze(
|
|
Object.fromEntries(
|
|
Object.entries(fieldErrorKeys).map(([name, key]) => [
|
|
name,
|
|
resolve(String(key)),
|
|
]),
|
|
),
|
|
) as FieldErrors<Values>,
|
|
[fieldErrorKeys, resolve],
|
|
);
|
|
const formErrors = useMemo(
|
|
() => formErrorKeys.map((key) => resolve(key)),
|
|
[formErrorKeys, resolve],
|
|
);
|
|
const [pending, setPending] = useState(false);
|
|
const [result, setResult] = useState<FormResultState>("idle");
|
|
const [statusFailure, setStatusFailure] = useState<AppFailure | null>(null);
|
|
const pendingRef = useRef<Promise<FormResult<Output> | null> | null>(null);
|
|
const unknownSubmissionRef = useRef<Values | null>(null);
|
|
|
|
const dirty = useMemo(
|
|
() => JSON.stringify(values) !== JSON.stringify(initialValues),
|
|
[initialValues, values],
|
|
);
|
|
|
|
const fieldId = useCallback(
|
|
(name: FieldName<Values>) => `${formId}-${name}`,
|
|
[formId],
|
|
);
|
|
|
|
const focusField = useCallback(
|
|
(name: FieldName<Values>) => {
|
|
const field = document.getElementById(fieldId(name));
|
|
if (field instanceof HTMLElement) field.focus();
|
|
},
|
|
[fieldId],
|
|
);
|
|
|
|
const focusFirstError = useCallback(
|
|
(errors: FieldErrors<Values>) => {
|
|
const first = allowedServerFields.find((name) => Boolean(errors[name]));
|
|
if (first) focusField(first);
|
|
},
|
|
[allowedServerFields, focusField],
|
|
);
|
|
|
|
const setValue = useCallback(
|
|
(name: FieldName<Values>, value: Values[FieldName<Values>]) => {
|
|
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<Values>) => ({
|
|
id: fieldId(name),
|
|
name,
|
|
value: String(values[name] ?? ""),
|
|
onChange(event: ChangeEvent<HTMLInputElement | HTMLTextAreaElement>) {
|
|
setValue(name, event.currentTarget.value as Values[FieldName<Values>]);
|
|
},
|
|
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<Values>);
|
|
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<Values>);
|
|
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<Values>);
|
|
setFormErrors([]);
|
|
setResult("idle");
|
|
}, []);
|
|
|
|
const applyOutcome = useCallback(
|
|
(outcome: FormResult<Output>, submittedValues: Values) => {
|
|
if (outcome.ok) {
|
|
settleSuccessfulValues(submittedValues);
|
|
return;
|
|
}
|
|
if (outcome.error.kind === "VALIDATION_REJECTED") {
|
|
unknownSubmissionRef.current = null;
|
|
const mapped = mapValidationFailureToFields<Values>(
|
|
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<FormResult<Output> | null> => {
|
|
setFieldErrors({} as FieldErrors<Values>);
|
|
setFormErrors([]);
|
|
|
|
const parsed = await schema.safeParseAsync(values);
|
|
if (!parsed.success) {
|
|
const errors = issuesToFieldErrors<Values>(
|
|
parsed.error.issues,
|
|
allowedServerFields,
|
|
messageKey,
|
|
);
|
|
setFieldErrors(errors);
|
|
setFormErrors(
|
|
parsed.error.issues.some(
|
|
(issue) => !allowedServerFields.includes(issue.path[0] as FieldName<Values>),
|
|
)
|
|
? ["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<HTMLFormElement>): Promise<FormResult<Output> | 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<FormResult<Output> | null>,
|
|
): Promise<FormResult<Output> | 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<FormResultState> = new Set([
|
|
"reauth-required",
|
|
"forbidden",
|
|
"retry-later",
|
|
"unavailable",
|
|
]);
|
|
|
|
function issuesToFieldErrors<Values extends FormValues>(
|
|
issues: readonly ZodIssue[],
|
|
allowedFields: readonly FieldName<Values>[],
|
|
message: (key: ParameterlessMessageKey) => string,
|
|
): FieldErrors<Values> {
|
|
const allowed = new Set<PropertyKey>(allowedFields);
|
|
const errors: Partial<Record<FieldName<Values>, string>> = {};
|
|
for (const issue of issues) {
|
|
const field = issue.path[0];
|
|
if (!allowed.has(field)) continue;
|
|
const name = field as FieldName<Values>;
|
|
errors[name] ??= validationMessage(issue.code, message);
|
|
}
|
|
return Object.freeze(errors);
|
|
}
|