سربرگ فرم (FormHeader)

معرفی

FormHeader رایج‌ترین الگوی سربرگِ بخشِ Supabase است: یک عنوان با توضیح اختیاری در ابتدای خط (line-start) و اقدامات اختیاری در انتهای خط (line-end)، که بالای یک فرم یا بخش جدول می‌نشیند. برگرفته از FormHeader.tsx واقعی Studio. چیدمان یک ردیف justify-between طبیعی است، پس بلوک عنوان در ابتدای خط و اقدامات در انتهای خط در هر دو جهت LTR و RTL درست قرار می‌گیرند — بدون چپ/راست فیزیکی.

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

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

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

• برای سربرگ کل صفحه (عنوان اصلی صفحه با breadcrumb) — از PageHeader یا PageHeaderRoot استفاده کنید
• برای سربرگ داخل یک کارت متریک/نمودار — از ChartCardHeader یا سربرگ Card استفاده کنید
• وقتی فقط یک برچسب فیلد می‌خواهید — از Label یا FormItemLayout استفاده کنید

استفاده

import { FormHeader, Button } from '@partodata/ui'

export default function CampaignSettings() {
  return (
    <FormHeader
      title="اطلاعات کمپین"
      description="نام و توضیحاتی که در گزارش‌های برند نمایش داده می‌شود."
      actions={
        <Button variant="outline" size="sm">
          راهنما
        </Button>
      }
    />
  )
}

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

بدون اقدامات

اگر actions را حذف کنید، فقط عنوان و توضیح می‌ماند.

<FormHeader title="تنظیمات اعلان" description="گزارش‌های دوره‌ای را این‌جا مدیریت کنید." />

تغییر سطح تیتر با as

عنوان به‌صورت پیش‌فرض h3 رندر می‌شود. برای جای‌گذاری درست در سلسله‌مراتب تیترها، سطح را با as تنظیم کنید.

<FormHeader as="h4" title="زیرمجموعهٔ تنظیمات" description="توضیح این زیرمجموعه." />

چند دکمه در اقدامات

<FormHeader
  title="کلیدهای API"
  description="کلیدهای دسترسی برنامه‌ای را مدیریت کنید."
  actions={
    <>
      <Button variant="outline" size="sm">
        مستندات
      </Button>
      <Button size="sm">کلید جدید</Button>
    </>
  }
/>

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

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

FormHeader

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

• عنوان یک المان تیتر واقعی (h1–h4) است؛ با as سطح درست را انتخاب کنید تا ناوبری تیترها برای صفحه‌خوان منسجم بماند
• توضیح در یک p جدا با کنتراست text-foreground-light است که در هر دو تم AA را رعایت می‌کند
• ترتیب DOM «عنوان → توضیح → اقدامات» است، پس صفحه‌خوان ابتدا زمینهٔ بخش و سپس اقدامات را می‌خواند

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

• PageHeader — اگر سربرگ کل صفحه (عنوان اصلی، breadcrumb، بازگشت) می‌خواهید، از PageHeader استفاده کنید
• FormItemLayout — برای چیدمان یک ردیف فرم (برچسب/کنترل/خطا)، از FormItemLayout استفاده کنید
• Callout — اگر توضیح بخش نیاز به تأکید یا هشدار دارد، از Callout استفاده کنید