TanStack Form v1 مع Next.js 15: دليل شامل لبناء نماذج آمنة الأنواع

npx create-next-app@latest tanstack-form-demo --typescript --app --tailwind --no-src-dir
cd tanstack-form-demo
npm install @tanstack/react-form @tanstack/zod-form-adapter zod

npm run dev

import { z } from "zod"
 
export const ExperienceSchema = z.object({
  company: z.string().min(1, "اسم الشركة مطلوب"),
  role: z.string().min(1, "المسمى الوظيفي مطلوب"),
  years: z.number().min(0).max(50),
})
 
export const ApplicationSchema = z.object({
  fullName: z.string().min(2, "يجب أن يكون الاسم على الأقل حرفين"),
  email: z.string().email("عنوان بريد غير صالح"),
  phone: z.string().regex(/^\+?[0-9\s-]{8,}$/, "رقم هاتف غير صالح"),
  experience: z.array(ExperienceSchema).min(1, "أضف خبرة واحدة على الأقل"),
  portfolio: z.array(z.string().url("يجب أن يكون رابط صالح")).optional(),
  coverLetter: z.string().min(50, "يجب أن يكون خطاب التغطية على الأقل 50 حرف"),
})
 
export type Application = z.infer<typeof ApplicationSchema>
export type Experience = z.infer<typeof ExperienceSchema>

import type { AnyFieldApi } from "@tanstack/react-form"
 
interface TextFieldProps {
  field: AnyFieldApi
  label: string
  type?: string
  placeholder?: string
}
 
export function TextField({ field, label, type = "text", placeholder }: TextFieldProps) {
  const errors = field.state.meta.errors
  const hasError = field.state.meta.isTouched && errors.length > 0
 
  return (
    <div className="flex flex-col gap-1">
      <label htmlFor={field.name} className="text-sm font-medium">
        {label}
      </label>
      <input
        id={field.name}
        name={field.name}
        type={type}
        placeholder={placeholder}
        value={field.state.value ?? ""}
        onBlur={field.handleBlur}
        onChange={(e) => field.handleChange(e.target.value)}
        aria-invalid={hasError}
        aria-describedby={hasError ? `${field.name}-error` : undefined}
        className="rounded border px-3 py-2 focus:ring-2 focus:ring-blue-500"
      />
      {hasError && (
        <span id={`${field.name}-error`} className="text-sm text-red-600">
          {errors.map((err: { message?: string } | string) =>
            typeof err === "string" ? err : err.message
          ).join(", ")}
        </span>
      )}
    </div>
  )
}

"use client"
 
import { useForm } from "@tanstack/react-form"
import { zodValidator } from "@tanstack/zod-form-adapter"
import { ApplicationSchema } from "@/lib/schemas/application"
import { TextField } from "@/components/form/TextField"
import { submitApplication } from "./actions"
 
export default function ApplyPage() {
  const form = useForm({
    defaultValues: {
      fullName: "",
      email: "",
      phone: "",
      experience: [{ company: "", role: "", years: 0 }],
      portfolio: [],
      coverLetter: "",
    },
    validatorAdapter: zodValidator(),
    validators: {
      onChange: ApplicationSchema,
    },
    onSubmit: async ({ value }) => {
      const result = await submitApplication(value)
      if (!result.success) {
        throw new Error(result.error)
      }
    },
  })
 
  return (
    <form
      onSubmit={(e) => {
        e.preventDefault()
        e.stopPropagation()
        form.handleSubmit()
      }}
      className="mx-auto max-w-2xl space-y-6 p-6"
    >
      <h1 className="text-2xl font-bold">طلب وظيفة</h1>
 
      <form.Field name="fullName">
        {(field) => <TextField field={field} label="الاسم الكامل" />}
      </form.Field>
 
      <form.Field name="email">
        {(field) => <TextField field={field} label="البريد الإلكتروني" type="email" />}
      </form.Field>
 
      <form.Field name="phone">
        {(field) => <TextField field={field} label="الهاتف" type="tel" />}
      </form.Field>
    </form>
  )
}

<form.Field name="experience" mode="array">
  {(field) => (
    <div className="space-y-4">
      <div className="flex items-center justify-between">
        <h2 className="text-lg font-semibold">الخبرة العملية</h2>
        <button
          type="button"
          onClick={() =>
            field.pushValue({ company: "", role: "", years: 0 })
          }
          className="rounded bg-blue-600 px-3 py-1 text-white"
        >
          إضافة خبرة
        </button>
      </div>
 
      {field.state.value.map((_, index) => (
        <div key={index} className="space-y-2 rounded border p-4">
          <form.Field name={`experience[${index}].company`}>
            {(subField) => <TextField field={subField} label="الشركة" />}
          </form.Field>
          <form.Field name={`experience[${index}].role`}>
            {(subField) => <TextField field={subField} label="المسمى" />}
          </form.Field>
          <form.Field name={`experience[${index}].years`}>
            {(subField) => (
              <TextField field={subField} label="السنوات" type="number" />
            )}
          </form.Field>
          <button
            type="button"
            onClick={() => field.removeValue(index)}
            className="text-sm text-red-600"
          >
            إزالة
          </button>
        </div>
      ))}
    </div>
  )}
</form.Field>

<form.Field
  name="portfolio"
  mode="array"
  validators={{
    onChangeAsync: async ({ value }) => {
      if (!value || value.length === 0) return undefined
      const checks = await Promise.all(
        value.map(async (url) => {
          try {
            const res = await fetch(`/api/check-url?url=${encodeURIComponent(url)}`)
            const data = await res.json()
            return data.ok ? null : `${url} غير قابل للوصول`
          } catch {
            return `تعذر التحقق من ${url}`
          }
        })
      )
      const errors = checks.filter(Boolean)
      return errors.length > 0 ? errors.join(", ") : undefined
    },
    onChangeAsyncDebounceMs: 500,
  }}
>
  {(field) => (
    <div className="space-y-2">
      <h2 className="text-lg font-semibold">روابط المحفظة</h2>
      {field.state.value?.map((_, index) => (
        <form.Field key={index} name={`portfolio[${index}]`}>
          {(sub) => <TextField field={sub} label={`رابط ${index + 1}`} />}
        </form.Field>
      ))}
      <button
        type="button"
        onClick={() => field.pushValue("")}
        className="rounded border px-3 py-1"
      >
        إضافة رابط
      </button>
    </div>
  )}
</form.Field>

import { NextResponse } from "next/server"
 
export async function GET(request: Request) {
  const url = new URL(request.url).searchParams.get("url")
  if (!url) return NextResponse.json({ ok: false })
 
  try {
    const res = await fetch(url, { method: "HEAD", signal: AbortSignal.timeout(3000) })
    return NextResponse.json({ ok: res.ok })
  } catch {
    return NextResponse.json({ ok: false })
  }
}

"use server"
 
import { ApplicationSchema, type Application } from "@/lib/schemas/application"
import { revalidatePath } from "next/cache"
 
export async function submitApplication(data: Application) {
  const parsed = ApplicationSchema.safeParse(data)
  if (!parsed.success) {
    return {
      success: false as const,
      error: "بيانات طلب غير صالحة",
      issues: parsed.error.flatten(),
    }
  }
 
  try {
    await saveToDatabase(parsed.data)
    revalidatePath("/apply")
    return { success: true as const }
  } catch (error) {
    const message = error instanceof Error ? error.message : "خطأ غير معروف"
    return { success: false as const, error: message }
  }
}
 
async function saveToDatabase(data: Application) {
  console.info("حفظ الطلب", data.email)
}

<form.Subscribe
  selector={(state) => [state.canSubmit, state.isSubmitting]}
>
  {([canSubmit, isSubmitting]) => (
    <button
      type="submit"
      disabled={!canSubmit}
      className="w-full rounded bg-blue-600 py-3 font-semibold text-white disabled:opacity-50"
    >
      {isSubmitting ? "جاري الإرسال..." : "إرسال الطلب"}
    </button>
  )}
</form.Subscribe>

import { useEffect } from "react"
 
useEffect(() => {
  const stored = localStorage.getItem("application-draft")
  if (stored) {
    try {
      form.reset(JSON.parse(stored))
    } catch {
      console.warn("فشل استعادة المسودة")
    }
  }
}, [form])
 
useEffect(() => {
  const unsubscribe = form.store.subscribe(() => {
    localStorage.setItem("application-draft", JSON.stringify(form.state.values))
  })
  return unsubscribe
}, [form])

npm install -D vitest @testing-library/react @testing-library/user-event jsdom @vitejs/plugin-react

import { render, screen } from "@testing-library/react"
import userEvent from "@testing-library/user-event"
import ApplyPage from "./page"
 
test("يظهر خطأ لبريد غير صالح", async () => {
  render(<ApplyPage />)
  const user = userEvent.setup()
  const emailInput = screen.getByLabelText(/البريد/i)
 
  await user.type(emailInput, "not-an-email")
  await user.tab()
 
  expect(await screen.findByText(/غير صالح/i)).toBeInTheDocument()
})
 
test("زر الإرسال معطل حتى يصبح النموذج صالحاً", () => {
  render(<ApplyPage />)
  const button = screen.getByRole("button", { name: /إرسال/i })
  expect(button).toBeDisabled()
})