فیلد (Field)

معرفی

کامپوننت Field یک wrapper کامل برای مدیریت فیلدهای فرم است که شامل label، description، error و layout می‌شود.

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

• وقتی نیاز به نمایش label، توضیحات و پیام خطا در کنار فیلد دارید
• برای ساختاردهی فرم‌ها بدون نیاز به react-hook-form
• وقتی چینش افقی یا عمودی فیلدها مورد نیاز است

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

• برای input های بدون label — از Input مستقیم استفاده کنید
• در context هایی که از react-hook-form + Form استفاده می‌کنید — از FormField استفاده کنید

استفاده

import { Field, FieldLabel, FieldDescription, FieldError, Input } from '@parto-system-design/ui'

export default function MyComponent() {
  return (
    <Field>
      <FieldLabel>نام کاربری</FieldLabel>
      <Input placeholder="نام کاربری خود را وارد کنید" />
      <FieldDescription>نام کاربری شما باید یکتا باشد</FieldDescription>
    </Field>
  )
}

با خطا

<Field data-invalid="true">
  <FieldLabel>ایمیل</FieldLabel>
  <Input type="email" aria-invalid="true" />
  <FieldError>ایمیل معتبر نیست</FieldError>
</Field>

چینش افقی

<Field orientation="horizontal">
  <FieldLabel>تنظیمات</FieldLabel>
  <FieldContent>
    <Switch />
    <FieldDescription>فعال‌سازی اعلان‌ها</FieldDescription>
  </FieldContent>
</Field>

FieldSet برای گروه‌بندی

<FieldSet>
  <FieldLegend>اطلاعات شخصی</FieldLegend>
  <FieldGroup>
    <Field>
      <FieldLabel>نام</FieldLabel>
      <Input />
    </Field>
    <Field>
      <FieldLabel>نام خانوادگی</FieldLabel>
      <Input />
    </Field>
  </FieldGroup>
</FieldSet>

با جداکننده

<FieldGroup>
  <Field>
    <FieldLabel>فیلد اول</FieldLabel>
    <Input />
  </Field>
  <FieldSeparator>یا</FieldSeparator>
  <Field>
    <FieldLabel>فیلد دوم</FieldLabel>
    <Input />
  </Field>
</FieldGroup>

Props

Field

FieldLegend

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

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

Label بالای فیلد و توضیحات/خطا زیر آن.

چینش افقی

با orientation="horizontal" برای فیلدهایی مانند Switch یا Toggle.

حالت خطا

با data-invalid="true" تمام زیرکامپوننت‌ها به رنگ خطا تغییر می‌کنند.

گروه‌بندی با FieldSet

چندین فیلد مرتبط را با FieldSet و FieldLegend گروه‌بندی کنید.

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

کامپوننت‌ها

• Field — wrapper اصلی (orientation و data-invalid)
• FieldLabel — برچسب فیلد (بر پایه Label)
• FieldDescription — توضیحات زیر فیلد
• FieldError — پیام خطا (رنگ destructive)
• FieldGroup — گروه‌بندی چند Field در کنار هم
• FieldSet — <fieldset> HTML برای فرم‌های گروه‌بندی شده
• FieldLegend — عنوان FieldSet (variant: legend|label)
• FieldSeparator — جداکننده بین Field‌ها (با متن اختیاری)
• FieldContent — محتوای جانبی در layout افقی
• FieldTitle — عنوان بدون ربط به input (نه label)

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

• FieldLabel به صورت خودکار با htmlFor به فیلد مرتبط لینک می‌شود
• FieldError با aria-live="polite" برای screen reader اعلام می‌شود
• FieldSet از تگ <fieldset> استاندارد HTML استفاده می‌کند
• FieldDescription با aria-describedby به فیلد مرتبط متصل می‌شود
• پشتیبانی کامل از RTL

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

• اگر نیاز به مدیریت فرم با validation و react-hook-form دارید → Form
• اگر فقط نیاز به یک input ساده بدون wrapper دارید → Input
• اگر فقط نیاز به یک label مستقل دارید → Label