چیدمان آیتم فرم (FormItemLayout)

معرفی

FormItemLayout عنصرِ پایهٔ چیدمان یک ردیف فرم است: داربست برچسب/توضیح/خطا را می‌سازد و کنترل (input، switch، select) را به‌عنوان children جای می‌دهد. برگرفته از FormLayout واقعی Supabase و برای RTL بازطراحی شده. عمداً مستقل است و هیچ وابستگی‌ای به react-hook-form ندارد، پس در بارل امن می‌ماند. برای استفاده داخل RHF، کنترل را در FormControl خودتان بپیچید و error={fieldState.error?.message} را صریح پاس دهید.

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

• برای یک ردیف فرم استاندارد با برچسب، توضیح و پیام خطا
• وقتی به شکل‌های مختلف چیدمان نیاز دارید (عمودی، افقی، ردیف toggle)
• برای یک‌دست‌کردن فاصله‌گذاری و ترتیب برچسب/کنترل/خطا در کل فرم‌ها

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

• برای مدیریت state و اعتبارسنجی فرم — از Form (react-hook-form) استفاده کنید و FormItemLayout را داخل آن به‌عنوان چیدمان به کار ببرید
• برای فقط یک برچسب بدون کنترل — از Label استفاده کنید
• برای سربرگ یک بخش فرم — از FormHeader استفاده کنید

استفاده

import { FormItemLayout, Input } from '@partodata/ui'

export default function CampaignNameField() {
  return (
    <FormItemLayout label="نام کمپین" description="نامی که در گزارش‌ها نمایش داده می‌شود." id="campaign-name">
      <Input id="campaign-name" placeholder="کمپین تخفیف فصلی" />
    </FormItemLayout>
  )
}

id (یا name) روی FormItemLayout به‌عنوان htmlFor برچسب استفاده می‌شود؛ همان مقدار را روی کنترل هم بگذارید تا کلیک روی برچسب کنترل را فوکوس کند.

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

prop layout

چهار شکل ردیف، دقیقاً مطابق FormLayout واقعی Supabase:

• vertical (پیش‌فرض) — برچسب بالای کنترل، به‌صورت پشته.
• horizontal — گرید ۱۲ ستونی، برچسب ۴ ستون / کنترل ۸ ستون.
• flex — ستون برچسب+توضیح در کنار کنترل.
• flex-row-reverse — شکل «ردیف toggle»: برچسب در ابتدای خط، کنترل در انتهای خط، روی یک خط.

عمودی (پیش‌فرض)

<FormItemLayout label="نام کمپین" description="نامی که در گزارش‌ها نمایش داده می‌شود." id="name">
  <Input id="name" placeholder="کمپین تخفیف فصلی" />
</FormItemLayout>

افقی

<FormItemLayout
  layout="horizontal"
  label="دامنه برند"
  labelOptional="(اختیاری)"
  description="آدرس سایت برند را بدون https وارد کنید."
  id="domain"
>
  <Input id="domain" dir="ltr" placeholder="brand.example.com" />
</FormItemLayout>

ردیف toggle با flex-row-reverse

این حالت برای ردیف‌های سوییچ/چک‌باکس است: برچسب و توضیح در ابتدای خط، کنترل در انتهای خط.

<FormItemLayout
  layout="flex-row-reverse"
  label="اعلان گزارش هفتگی"
  description="هر هفته یک خلاصه عملکرد ایمیل می‌شود."
  id="weekly"
>
  <Switch id="weekly" defaultChecked />
</FormItemLayout>

نمایش خطا

با ست‌کردن error، پیام در تینت destructive رندر می‌شود. با hideMessage می‌توانید اسلات خطا را حتی وقتی error ست است پنهان کنید.

<FormItemLayout label="ایمیل" error="ایمیل واردشده معتبر نیست." id="email">
  <Input id="email" aria-invalid dir="ltr" />
</FormItemLayout>

برچسب‌های کمکی

<FormItemLayout
  label="کلید API"
  labelOptional="(اختیاری)"
  beforeLabel={<Lock className="size-3.5" />}
  afterLabel="— فقط خواندنی"
  id="api-key"
>
  <Input id="api-key" dir="ltr" />
</FormItemLayout>

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

جدول ویژگی‌ها

FormItemLayout

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

• برچسب یک Label واقعی با htmlFor است؛ اگر id/name را روی کنترل هم بگذارید، کلیک روی برچسب کنترل را فوکوس می‌کند
• پیام خطا در یک p جداست؛ برای اتصال به کنترل، aria-invalid و در صورت نیاز aria-describedby را روی خود کنترل ست کنید
• چیدمان flex-row-reverse از جریان منطقی استفاده می‌کند، پس ترتیب خواندن صفحه‌خوان (برچسب → توضیح → کنترل) در هر دو جهت درست می‌ماند

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

• Form — برای مدیریت state و اعتبارسنجی (react-hook-form)، از Form استفاده کنید و FormItemLayout را داخلش برای چیدمان به کار ببرید
• Field — جایگزین سبک‌تر برای ردیف‌های فرم ساده بدون حالت‌های چیدمان چندگانه
• FormHeader — برای سربرگ یک بخش از فرم (عنوان + توضیح + اقدامات)، از FormHeader استفاده کنید
• Label — اگر فقط یک برچسب مستقل می‌خواهید، از Label استفاده کنید