Skill experto en formularios y validación - Una receta de skill para Claude Code sobre manejo avanzado de formularios con React Hook Form, Zod y Server Actions

---
name: forms-validation-expert
description: "Manejo avanzado de formularios con React Hook Form, Zod y Server Actions. Úsalo cuando te pidan: form help, validation, Zod schema, form pattern, multi-step form, file upload form, react-hook-form, server action form, form errors."
allowed-tools: "Read, Write, Edit, Glob, Grep, Bash(npm:*), Bash(npx:*), Agent"
---
 
# Skill experto en formularios y validación
 
Eres un experto en formularios y validación para React y Next.js. Construyes formularios type-safe, accesibles, con mejora progresiva y fáciles de usar.
 
## Árbol de decisión de estrategia de validación
 
1. **¿Es un formulario con Server Action (sin JS en el cliente)?**
   - Sí -> Validación Zod en la Server Action + useActionState
   - No -> Continúa
 
2. **¿El formulario tiene interacciones complejas en el cliente?**
   - Sí (campos condicionales, multi-paso, arrays dinámicos) -> React Hook Form + Zod
   - No (formulario simple, pocos campos) -> Formulario con Server Action o validación HTML nativa
 
3. **¿Estás usando shadcn/ui?**
   - Sí -> Usa el componente Form de shadcn (envuelve React Hook Form)
   - No -> Usa React Hook Form directamente
 
## Patrones de esquemas Zod
 
### Esquema básico
```tsx
import \{ z \} from "zod";
 
const UserSchema = z.object(\{
  name: z.string().min(2, "El nombre debe tener al menos 2 caracteres"),
  email: z.string().email("Dirección de correo electrónico no válida"),
  age: z.coerce.number().min(13, "Debes tener al menos 13 años").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\}$/, "Debe tener 16 dígitos"),
    expiry: z.string().regex(/^\d\{2\}\/\d\{2\}$/, "Formato MM/AA"),
    cvv: z.string().regex(/^\d\{3,4\}$/, "3 o 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;
    \}, "El nombre de usuario ya está en uso"),
  email: z.string().email(),
  password: z.string().min(8),
  confirmPassword: z.string(),
\}).refine((data) => data.password === data.confirmPassword, \{
  message: "Las contraseñas no coinciden",
  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, "El archivo debe pesar menos de 5 MB")
    .refine(
      (f) => ACCEPTED_TYPES.includes(f.type),
      "Solo se aceptan JPEG, PNG y WebP"
    ),
\});

"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">Nombre</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">Correo electrónico</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: "¡Mensaje enviado!" \};
  \} catch \{
    return \{ success: false, message: "No se pudo enviar. Inténtalo de nuevo." \};
  \}
\}

// 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 mensaje"\}
    </button>
  );
\}
 
export function ContactForm() \{
  const [state, formAction] = useActionState(submitContact, \{
    success: false,
  \});
 
  return (
    <form action=\{formAction\}>
      <div>
        <label htmlFor="name">Nombre</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">Correo electrónico</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">Mensaje</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>Nombre de usuario</FormLabel>
              <FormControl>
                <Input placeholder="johndoe" \{...field\} />
              </FormControl>
              <FormDescription>Tu nombre público de visualización.</FormDescription>
              <FormMessage />
            </FormItem>
          )\}
        />
        <Button type="submit">Guardar</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) => \{
    // Validación final con el 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\}>Atrás</button>\}
        \{step < 2 ? (
          <button type="button" onClick=\{onNext\}>Siguiente</button>
        ) : (
          <button type="submit">Realizar pedido</button>
        )\}
      </div>
    </form>
  );
\}