feat: add form and page platform

src/presentation/forms/use-app-form.ts

@@ -0,0 +1,244 @@
+import {
+  useCallback,
+  useId,
+  useMemo,
+  useRef,
+  useState,
+  type ChangeEvent,
+  type FormEvent,
+} from "react";
+import type { ZodType, ZodIssue } from "zod";
+
+import {
+  mapValidationFailureToFields,
+  validationMessage,
+  type FieldErrors,
+  type FieldName,
+  type FormResult,
+  type FormResultState,
+  type FormValues,
+} from "./form-contracts.js";
+
+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 {
+    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(),
+  );
+  const [fieldErrors, setFieldErrors] = useState<FieldErrors<Values>>(
+    () => ({} as FieldErrors<Values>),
+  );
+  const [formErrors, setFormErrors] = useState<readonly string[]>([]);
+  const [pending, setPending] = useState(false);
+  const [result, setResult] = useState<FormResultState>("idle");
+  const pendingRef = useRef<Promise<FormResult<Output>> | 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("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) => {
+      setValues(nextValues);
+      setInitialValues(nextValues);
+      setTouched(new Set());
+      setFieldErrors({} as FieldErrors<Values>);
+      setFormErrors([]);
+      setResult("idle");
+    },
+    [defaultValues],
+  );
+
+  const submitForm = useCallback(
+    async (event?: FormEvent<HTMLFormElement>): Promise<FormResult<Output> | null> => {
+      event?.preventDefault();
+      if (pendingRef.current) return pendingRef.current;
+      setFieldErrors({} as FieldErrors<Values>);
+      setFormErrors([]);
+
+      const parsed = await schema.safeParseAsync(values);
+      if (!parsed.success) {
+        const errors = issuesToFieldErrors<Values>(
+          parsed.error.issues,
+          allowedServerFields,
+        );
+        setFieldErrors(errors);
+        setFormErrors(
+          parsed.error.issues.some(
+            (issue) => !allowedServerFields.includes(issue.path[0] as FieldName<Values>),
+          )
+            ? ["입력 구성을 다시 확인해 주세요."]
+            : [],
+        );
+        setTouched(new Set(allowedServerFields));
+        setResult("validation-error");
+        focusFirstError(errors);
+        return null;
+      }
+
+      const command = mapToCommand(parsed.data);
+      setPending(true);
+      const execution = submit(command);
+      pendingRef.current = execution;
+      try {
+        const outcome = await execution;
+        if (outcome.ok) {
+          setResult("success");
+          if (resetOnSuccess) {
+            setValues(defaultValues);
+            setInitialValues(defaultValues);
+            setTouched(new Set());
+          } else {
+            setInitialValues(parsed.data);
+          }
+          return outcome;
+        }
+        if (outcome.error.kind === "VALIDATION_REJECTED") {
+          const mapped = mapValidationFailureToFields<Values>(
+            outcome.error,
+            allowedServerFields,
+          );
+          setFieldErrors(mapped.fieldErrors);
+          setFormErrors(mapped.formErrors);
+          setResult("validation-error");
+          focusFirstError(mapped.fieldErrors);
+        } else if (outcome.error.kind === "CONFLICT") {
+          setFormErrors([
+            "다른 변경과 충돌했습니다. 입력은 유지되었으니 최신 상태를 확인해 주세요.",
+          ]);
+          setResult("conflict");
+        } else {
+          setFormErrors(["저장하지 못했습니다. 잠시 후 다시 시도해 주세요."]);
+          setResult("unavailable");
+        }
+        return outcome;
+      } finally {
+        pendingRef.current = null;
+        setPending(false);
+      }
+    },
+    [
+      allowedServerFields,
+      defaultValues,
+      focusFirstError,
+      mapToCommand,
+      resetOnSuccess,
+      schema,
+      submit,
+      values,
+    ],
+  );
+
+  return Object.freeze({
+    formId,
+    values,
+    dirty,
+    touched,
+    fieldErrors,
+    formErrors,
+    pending,
+    result,
+    field,
+    fieldId,
+    focusField,
+    setValue,
+    submitForm,
+    reset,
+  });
+}
+
+function issuesToFieldErrors<Values extends FormValues>(
+  issues: readonly ZodIssue[],
+  allowedFields: readonly FieldName<Values>[],
+): 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);
+  }
+  return Object.freeze(errors);
+}