Popover

کامپوننت Popover برای نمایش محتوای بیشتر با کلیک روی یک عنصر استفاده می‌شود؛ مثل پنل فیلترها یا کارت اطلاعات کاربر. برخلاف Tooltip که با hover و برای متن کوتاه است، Popover با کلیک باز می‌شود و می‌تواند محتوای تعاملی داشته باشد.

Import

import { Popover } from "fara-ui";

اگر هنوز FaraUI را نصب و راه‌اندازی نکرده‌ای، ابتدا صفحه‌ی شروع به کار را ببین.

Basic Usage

<Popover trigger={<Button variant="secondary">فیلترها</Button>}>
  <p>محتوای پنل اینجاست.</p>
</Popover>

Playground

alignstartend

trigger

<Popover trigger={<Button variant="secondary">فیلترها</Button>} align="start">
  محتوا
</Popover>

Align

• "start" (پیش‌فرض) — لبه‌ی شروع پنل با trigger تراز می‌شود
• "end" — لبه‌ی پایان پنل با trigger تراز می‌شود

Closing Behavior

• کلیک دوباره روی trigger (toggle)
• کلیک بیرون از پنل
• فشردن کلید Escape

وضعیت Popover در API فعلی داخلی است و prop کنترل‌شده‌ای مثل open یا onOpenChange ندارد. برای باز و بسته شدن از همان trigger و رفتارهای داخلی استفاده کن.

Accessibility

• پنل با role="dialog" پیاده شده است.
• بستن با Escape و کلیک بیرون پشتیبانی می‌شود.
• trigger را یک عنصر تعاملی واقعی مثل Button بده؛ wrapper داخلی Popover خودش role="button" یا مدیریت keyboard اضافه نمی‌کند.
• اگر پنل عنوان دارد، داخل children heading مناسب قرار بده؛ خود Popover prop عنوان یا aria-labelledby ندارد.

Data Attributes and Customize CSS

Popover hookهای زیر را تولید می‌کند:

Attribute	کاربرد
data-fara-popover	wrapper اصلی
data-fara-popover-trigger	wrapper trigger
data-fara-popover-content	پنل محتوا که در Portal رندر می‌شود

<Popover className="filter-popover" trigger={<Button variant="secondary">فیلترها</Button>}>
  <div className="filter-panel">
    <h2>فیلترها</h2>
    {/* کنترل‌های فیلتر */}
  </div>
</Popover>

[data-fara-popover] {
  display: inline-block;
}

[data-fara-popover-content] {
  min-width: 240px;
}

.filter-panel {
  display: grid;
  gap: 12px;
}

چون پنل با Portal رندر می‌شود، selector پنل را به [data-fara-popover] وابسته نکن. className روی wrapper است و برای خود پنل از selector data-fara-popover-content استفاده کن.

Props

Prop	Type	Default	Description
trigger	ReactNode	-	عنصر بازکننده‌ی پنل (الزامی)
children	ReactNode	-	محتوای پنل (الزامی)
align	"start" | "end"	"start"	تراز پنل نسبت به trigger
className	string	-	کلاس CSS اضافی روی wrapper