Forms with React Hook Form + Zod

# TaskFlow Phase 21 reference snapshot

This snapshot demonstrates the form architecture taught in Phase 21. It is a teaching reference, not a drop-in replacement for earlier phase source files. Integrate the changes deliberately.

The key design is: React Hook Form owns transient form state; Zod validates the client experience; NestJS validates the HTTP request again; business rules remain in services; PostgreSQL remains authoritative persistence.

import { z } from "zod";
import { taskDescriptionSchema, taskPrioritySchema, taskTitleSchema } from "@taskflow/validators/tasks";

export const createTaskSchema = z.strictObject({
  projectId: z.uuid(),
  title: taskTitleSchema,
  description: taskDescriptionSchema.nullable().optional(),
  priority: taskPrioritySchema.default("MEDIUM"),
  dueAt: z.iso.datetime().nullable().optional(),
});

export const updateTaskSchema = createTaskSchema.omit({ projectId: true }).partial().refine(
  (value) => Object.keys(value).length > 0,
  { message: "At least one field must be provided." },
);

.form { display: grid; gap: 1rem; max-width: 48rem; }
.field { display: grid; gap: .375rem; }
.field label { font-weight: 650; }
.field input, .field textarea, .field select { width: 100%; padding: .75rem; border: 1px solid var(--border); border-radius: .625rem; background: var(--surface); color: var(--text); }
.field [aria-invalid="true"] { border-color: #b42318; }
.field [role="alert"], .formError { margin: 0; color: #b42318; font-size: .875rem; }
.row { display: grid; grid-template-columns: 1fr 1fr; gap: 1rem; }
.actions { display: flex; justify-content: flex-end; }
.actions button { min-height: 2.75rem; padding: .625rem 1rem; }
.actions button:disabled { opacity: .6; cursor: not-allowed; }
@media (max-width: 640px) { .row { grid-template-columns: 1fr; } .actions button { width: 100%; } }

import { z } from "zod";
import { taskDescriptionSchema, taskPrioritySchema, taskTitleSchema } from "@taskflow/validators/tasks";

export const taskFormSchema = z.object({
  title: taskTitleSchema,
  description: taskDescriptionSchema,
  priority: taskPrioritySchema,
  dueAtLocal: z.string(),
});

export type TaskFormValues = z.infer<typeof taskFormSchema>;

"use client";

import { zodResolver } from "@hookform/resolvers/zod";
import { useRouter } from "next/navigation";
import { useForm } from "react-hook-form";
import { createTask, updateTask } from "@/lib/api/task-mutations";
import { taskFormSchema, type TaskFormValues } from "./task-form.schema";
import styles from "./task-form.module.css";

type Props = {
  mode: "create" | "edit";
  projectId: string;
  taskId?: string;
  defaultValues: TaskFormValues;
};

export function TaskForm({ mode, projectId, taskId, defaultValues }: Props) {
  const router = useRouter();
  const { register, handleSubmit, reset, setError, clearErrors, formState: { errors, isDirty, isSubmitting } } = useForm<TaskFormValues>({
    resolver: zodResolver(taskFormSchema),

import { createClient } from "@/lib/supabase/client";

const API_BASE_URL = process.env.NEXT_PUBLIC_API_BASE_URL!;

async function authHeaders() {
  const supabase = createClient();
  const { data, error } = await supabase.auth.getSession();
  if (error || !data.session?.access_token) throw new Error("Authentication required.");
  return {
    "Content-Type": "application/json",
    Authorization: `Bearer ${data.session.access_token}`,
  };
}

export async function createTask(input: unknown) {
  const response = await fetch(`${API_BASE_URL}/tasks`, {
    method: "POST",
    headers: await authHeaders(),
    body: JSON.stringify(input),
  });

{
  "name": "@taskflow/validators",
  "version": "0.0.0",
  "private": true,
  "type": "module",
  "exports": {
    "./tasks": "./src/tasks.ts"
  },
  "dependencies": {
    "zod": "4.6.5"
  }
}

import { z } from "zod";

export const taskTitleSchema = z.string().trim().min(1, "Title is required.").max(200);
export const taskDescriptionSchema = z.string().trim().max(2000);
export const taskPrioritySchema = z.enum(["LOW", "MEDIUM", "HIGH"]);
export const taskStatusSchema = z.enum(["TODO", "IN_PROGRESS", "DONE", "CANCELED"]);

# Phase 21 form test matrix

- Blank title -> inline error; request not sent.
- Unknown browser-only field -> not included in transport mapping.
- Create success -> navigate/refresh Task list.
- Edit success -> reset accepted values and clear dirty state.
- API 401 -> preserve values and show authentication/recovery message.
- API 403 -> preserve values and show permission message.
- API 409 -> preserve values and show conflict message.
- API 500 -> generic safe message; include requestId when client error helper exposes it.
- Double-click submit -> submit control disabled while isSubmitting is true.
- Keyboard-only -> labels, focus, errors and submit remain operable.
- Mobile width -> fields stack; button remains reachable without horizontal page overflow.