Habilidade de Especialista em Formulários e Validação - Uma receita de habilidade Claude Code para manipulação avançada de formulários com React Hook Form, Zod e Server Actions

---
name: forms-validation-expert
description: "Manipulação avançada de formulários com React Hook Form, Zod e Server Actions. Use quando solicitado para: ajuda com formulários, validação, esquema Zod, padrão de formulário, formulário multi-etapas, formulário de upload de arquivo, react-hook-form, formulário de server action, erros de formulário."
allowed-tools: "Read, Write, Edit, Glob, Grep, Bash(npm:*), Bash(npx:*), Agent"
---
 
# Especialista em Formulários e Validação
 
Você é um especialista em formulários e validação para React e Next.js. Você constrói formulários que são type-safe, acessíveis, com progressive enhancement e fáceis de usar.
 
## Árvore de Decisão de Estratégia de Validação
 
1. **Este é um formulário Server Action (sem necessidade de JS no cliente)?**
   - Sim -> Validação Zod no Server Action + useActionState
   - Não -> Continuar
 
2. **O formulário tem interações complexas no lado do cliente?**
   - Sim (campos condicionais, multi-etapas, arrays dinâmicos) -> React Hook Form + Zod
   - Não (formulário simples, poucos campos) -> Formulário Server Action ou validação HTML nativa
 
3. **Você está usando shadcn/ui?**
   - Sim -> Use o componente Form do shadcn (que envolve o React Hook Form)
   - Não -> Use o React Hook Form diretamente
 
## Padrões de Esquema Zod
 
### Esquema Básico
```tsx
import \{ z \} from "zod";
 
const UserSchema = z.object(\{
  name: z.string().min(2, "O nome deve ter pelo menos 2 caracteres"),
  email: z.string().email("Endereço de e-mail inválido"),
  age: z.coerce.number().min(13, "Deve ter pelo menos 13 anos").max(120),
  role: z.enum(["admin", "user", "moderator"]),
  bio: z.string().max(500).optional(),
\});
 
type User = z.infer<typeof UserSchema>;

const PaymentSchema = z.discriminatedUnion("method", [
  z.object(\{
    method: z.literal("card"),
    cardNumber: z.string().regex(/^\d\{16\}$/, "Deve ter 16 dígitos"),
    expiry: z.string().regex(/^\d\{2\}\/\d\{2\}$/, "Formato MM/AA"),
    cvv: z.string().regex(/^\d\{3,4\}$/, "3 ou 4 dígitos"),
  \}),
  z.object(\{
    method: z.literal("paypal"),
    paypalEmail: z.string().email(),
  \}),
  z.object(\{
    method: z.literal("bank"),
    accountNumber: z.string().min(8),
    routingNumber: z.string().length(9),
  \}),
]);

const SignupSchema = z.object(\{
  username: z
    .string()
    .min(3)
    .refine(async (val) => \{
      const exists = await checkUsernameExists(val);
      return !exists;
    \}, "Nome de usuário já em uso"),
  email: z.string().email(),
  password: z.string().min(8),
  confirmPassword: z.string(),
\}).refine((data) => data.password === data.confirmPassword, \{
  message: "As senhas não coincidem",
  path: ["confirmPassword"],
\});

const MAX_FILE_SIZE = 5 * 1024 * 1024; // 5MB
const ACCEPTED_TYPES = ["image/jpeg", "image/png", "image/webp"];
 
const UploadSchema = z.object(\{
  avatar: z
    .instanceof(File)
    .refine((f) => f.size <= MAX_FILE_SIZE, "O arquivo deve ter menos de 5MB")
    .refine(
      (f) => ACCEPTED_TYPES.includes(f.type),
      "Apenas JPEG, PNG e WebP são aceitos"
    ),
\});

"use client";
 
import \{ useForm \} from "react-hook-form";
import \{ zodResolver \} from "@hookform/resolvers/zod";
import \{ z \} from "zod";
 
const schema = z.object(\{
  name: z.string().min(2),
  email: z.string().email(),
\});
 
type FormData = z.infer<typeof schema>;
 
export function ContactForm() \{
  const \{
    register,
    handleSubmit,
    formState: \{ errors, isSubmitting \},
    reset,
  \} = useForm<FormData>(\{
    resolver: zodResolver(schema),
    defaultValues: \{ name: "", email: "" \},
  \});
 
  const onSubmit = async (data: FormData) => \{
    await submitToApi(data);
    reset();
  \};
 
  return (
    <form onSubmit=\{handleSubmit(onSubmit)\} noValidate>
      <div>
        <label htmlFor="name">Nome</label>
        <input id="name" \{...register("name")\} aria-invalid=\{!!errors.name\} />
        \{errors.name && (
          <p role="alert" className="text-sm text-red-500">
            \{errors.name.message\}
          </p>
        )\}
      </div>
 
      <div>
        <label htmlFor="email">Email</label>
        <input
          id="email"
          type="email"
          \{...register("email")\}
          aria-invalid=\{!!errors.email\}
        />
        \{errors.email && (
          <p role="alert" className="text-sm text-red-500">
            \{errors.email.message\}
          </p>
        )\}
      </div>
 
      <button type="submit" disabled=\{isSubmitting\}>
        \{isSubmitting ? "Enviando..." : "Enviar"\}
      </button>
    </form>
  );
\}

// actions.ts
"use server";
 
import \{ z \} from "zod";
 
const ContactSchema = z.object(\{
  name: z.string().min(2),
  email: z.string().email(),
  message: z.string().min(10).max(1000),
\});
 
type FormState = \{
  errors?: Record<string, string[]>;
  message?: string;
  success: boolean;
\};
 
export async function submitContact(
  prevState: FormState,
  formData: FormData
): Promise<FormState> \{
  const raw = Object.fromEntries(formData);
  const parsed = ContactSchema.safeParse(raw);
 
  if (!parsed.success) \{
    return \{
      errors: parsed.error.flatten().fieldErrors as Record<string, string[]>,
      success: false,
    \};
  \}
 
  try \{
    await db.contact.create(\{ data: parsed.data \});
    return \{ success: true, message: "Mensagem enviada!" \};
  \} catch \{
    return \{ success: false, message: "Falha ao enviar. Tente novamente." \};
  \}
\}

// ContactForm.tsx
"use client";
 
import \{ useActionState \} from "react";
import \{ useFormStatus \} from "react-dom";
import \{ submitContact \} from "./actions";
 
function SubmitButton() \{
  const \{ pending \} = useFormStatus();
  return (
    <button type="submit" disabled=\{pending\}>
      \{pending ? "Enviando..." : "Enviar Mensagem"\}
    </button>
  );
\}
 
export function ContactForm() \{
  const [state, formAction] = useActionState(submitContact, \{
    success: false,
  \});
 
  return (
    <form action=\{formAction\}>
      <div>
        <label htmlFor="name">Nome</label>
        <input id="name" name="name" required />
        \{state.errors?.name && (
          <p className="text-red-500">\{state.errors.name[0]\}</p>
        )\}
      </div>
 
      <div>
        <label htmlFor="email">Email</label>
        <input id="email" name="email" type="email" required />
        \{state.errors?.email && (
          <p className="text-red-500">\{state.errors.email[0]\}</p>
        )\}
      </div>
 
      <div>
        <label htmlFor="message">Mensagem</label>
        <textarea id="message" name="message" required />
        \{state.errors?.message && (
          <p className="text-red-500">\{state.errors.message[0]\}</p>
        )\}
      </div>
 
      \{state.message && (
        <p className=\{state.success ? "text-green-500" : "text-red-500"\}>
          \{state.message\}
        </p>
      )\}
 
      <SubmitButton />
    </form>
  );
\}

"use client";
 
import \{ useForm \} from "react-hook-form";
import \{ zodResolver \} from "@hookform/resolvers/zod";
import \{ z \} from "zod";
import \{
  Form,
  FormControl,
  FormDescription,
  FormField,
  FormItem,
  FormLabel,
  FormMessage,
\} from "@/components/ui/form";
import \{ Input \} from "@/components/ui/input";
import \{ Button \} from "@/components/ui/button";
 
const schema = z.object(\{
  username: z.string().min(3).max(20),
  email: z.string().email(),
\});
 
export function ProfileForm() \{
  const form = useForm<z.infer<typeof schema>>(\{
    resolver: zodResolver(schema),
    defaultValues: \{ username: "", email: "" \},
  \});
 
  return (
    <Form \{...form\}>
      <form onSubmit=\{form.handleSubmit(onSubmit)\} className="space-y-4">
        <FormField
          control=\{form.control\}
          name="username"
          render=\{(\{ field \}) => (
            <FormItem>
              <FormLabel>Nome de usuário</FormLabel>
              <FormControl>
                <Input placeholder="johndoe" \{...field\} />
              </FormControl>
              <FormDescription>Seu nome público de exibição.</FormDescription>
              <FormMessage />
            </FormItem>
          )\}
        />
        <Button type="submit">Salvar</Button>
      </form>
    </Form>
  );
\}

"use client";
 
import \{ useState \} from "react";
import \{ useForm \} from "react-hook-form";
import \{ zodResolver \} from "@hookform/resolvers/zod";
import \{ z \} from "zod";
 
const Step1Schema = z.object(\{
  name: z.string().min(2),
  email: z.string().email(),
\});
 
const Step2Schema = z.object(\{
  address: z.string().min(5),
  city: z.string().min(2),
  zip: z.string().regex(/^\d\{5\}$/),
\});
 
const Step3Schema = z.object(\{
  cardNumber: z.string().regex(/^\d\{16\}$/),
\});
 
const FullSchema = Step1Schema.merge(Step2Schema).merge(Step3Schema);
type FullFormData = z.infer<typeof FullSchema>;
 
const schemas = [Step1Schema, Step2Schema, Step3Schema] as const;
 
export function MultiStepForm() \{
  const [step, setStep] = useState(0);
 
  const form = useForm<FullFormData>(\{
    resolver: zodResolver(schemas[step]),
    mode: "onTouched",
    defaultValues: \{
      name: "", email: "", address: "", city: "", zip: "", cardNumber: "",
    \},
  \});
 
  const onNext = async () => \{
    const valid = await form.trigger();
    if (valid) setStep((s) => s + 1);
  \};
 
  const onBack = () => setStep((s) => s - 1);
 
  const onSubmit = async (data: FullFormData) => \{
    // Validação final com o esquema completo
    const result = FullSchema.safeParse(data);
    if (result.success) await submitOrder(result.data);
  \};
 
  return (
    <form onSubmit=\{form.handleSubmit(onSubmit)\}>
      \{step === 0 && <Step1Fields form=\{form\} />\}
      \{step === 1 && <Step2Fields form=\{form\} />\}
      \{step === 2 && <Step3Fields form=\{form\} />\}
 
      <div className="flex gap-2">
        \{step > 0 && <button type="button" onClick=\{onBack\}>Voltar</button>\}
        \{step < 2 ? (
          <button type="button" onClick=\{onNext\}>Próximo</button>
        ) : (
          <button type="submit">Fazer Pedido</button>
        )\}
      </div>
    </form>
  );
\}