فرم (Form)

معرفی

کامپوننت Form برای مدیریت فرم‌ها با استفاده از react-hook-form و zod استفاده می‌شود.

چه زمانی استفاده کنیم:

• وقتی فرم نیاز به اعتبارسنجی (validation) دارد
• برای فرم‌های چند فیلدی با مدیریت state پیچیده
• وقتی نیاز به پیام‌های خطای فارسی و بازخورد بصری دارید

چه زمانی استفاده نکنیم:

• برای یک یا دو فیلد ساده بدون validation — از Input مستقیم استفاده کنید
• وقتی از کتابخانه validation دیگری استفاده می‌کنید — Form wrapper با react-hook-form integrate شده

نصب Dependencies

pnpm add react-hook-form @hookform/resolvers zod

استفاده

import { useForm } from 'react-hook-form'
import { zodResolver } from '@hookform/resolvers/zod'
import * as z from 'zod'
import {
  Form,
  FormControl,
  FormDescription,
  FormField,
  FormItem,
  FormLabel,
  FormMessage,
} from '@parto-system-design/ui'
import { Input, Button } from '@parto-system-design/ui'

const formSchema = z.object({
  username: z.string().min(2, 'نام کاربری باید حداقل 2 کاراکتر باشد'),
})

export default function MyForm() {
  const form = useForm<z.infer<typeof formSchema>>({
    resolver: zodResolver(formSchema),
    defaultValues: {
      username: '',
    },
  })

  function onSubmit(values: z.infer<typeof formSchema>) {
    console.log(values)
  }

  return (
    <Form {...form}>
      <form onSubmit={form.handleSubmit(onSubmit)} className="space-y-4">
        <FormField
          control={form.control}
          name="username"
          render={({ field }) => (
            <FormItem>
              <FormLabel>نام کاربری</FormLabel>
              <FormControl>
                <Input placeholder="نام کاربری" {...field} />
              </FormControl>
              <FormDescription>این نام کاربری عمومی شما است</FormDescription>
              <FormMessage />
            </FormItem>
          )}
        />
        <Button type="submit">ارسال</Button>
      </form>
    </Form>
  )
}

کامپوننت‌ها

• Form — provider اصلی (FormProvider از react-hook-form)
• FormField — wrapper یک فیلد با کنترل react-hook-form
• FormItem — ظرف یک آیتم فرم (label + input + description + message)
• FormLabel — برچسب فیلد (به‌صورت خودکار قرمز در حالت خطا)
• FormControl — wrapper اطراف input که aria props را تزریق می‌کند
• FormDescription — متن توضیحی زیر فیلد
• FormMessage — پیام خطای validation

Props

FormField

FormItem

FormLabel

FormControl

FormDescription

FormMessage

حالت‌ها و انواع

فرم ساده

یک فیلد با validation ساده (مانند حداقل طول کاراکتر).

فرم چند فیلدی

ترکیب چندین FormField در یک فرم با schema واحد.

با Zod Schema

استفاده از zodResolver برای اعتبارسنجی type-safe.

راهنمای استفاده

دسترسی‌پذیری

• FormControl به‌صورت خودکار aria-invalid و aria-describedby را تنظیم می‌کند
• FormLabel با htmlFor به فیلد مرتبط می‌شود
• FormMessage با id مشخص، توسط screen reader خوانده می‌شود
• در حالت خطا، FormLabel به رنگ قرمز تغییر می‌کند و بازخورد بصری ارائه می‌دهد
• پشتیبانی کامل از RTL

کامپوننت‌های مرتبط

• اگر نیاز به فیلدهای فرم بدون react-hook-form دارید → Field
• اگر نیاز به راهنمای کامل طراحی فرم دارید → الگوهای فرم
• اگر نیاز به جزئیات اعتبارسنجی Zod دارید → اعتبارسنجی فرم
• اگر فقط نیاز به یک label مستقل دارید → Label