Drawer

کامپوننت Drawer یک پنل کشویی است که از کنار صفحه باز می‌شود؛ مثل منوی موبایل، سبد خرید یا فیلترهای جستجو. مشابه Modal روی document.body رندر می‌شود و هنگام باز بودن اسکرول صفحه قفل می‌شود.

Import

import { Drawer } from "fara-ui";

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

Basic Usage

const [open, setOpen] = useState(false);

<Button onClick={() => setOpen(true)}>نمایش Drawer</Button>
<Drawer open={open} onClose={() => setOpen(false)} title="سبد خرید">
  <p>محتوای کشو اینجاست.</p>
</Drawer>;

Playground

title

sidestartend

<Drawer open={open} onClose={() => setOpen(false)} title="عنوان کشو" side="end">
  محتوا
</Drawer>

Side

در صفحه‌ی RTL (که هدف اصلی FaraUI است):

• "end" (پیش‌فرض) — سمت چپ صفحه
• "start" — سمت راست صفحه

Closing Behavior

• کلیک روی دکمه‌ی ✕ در هدر
• کلیک روی پس‌زمینه‌ی تیره (overlay)
• فشردن کلید Escape

Behavior

• قفل اسکرول: هنگام باز بودن، اسکرول صفحه‌ی اصلی قفل می‌شود و عرض اسکرول‌بار جبران می‌شود.
• انیمیشن: پنل با انیمیشن slide باز و بسته می‌شود و بعد از پایان انیمیشن خروج از DOM حذف می‌شود.
• بدنه‌ی کشو (children) اسکرول عمودی خودش را دارد، پس محتوای بلند مشکل‌ساز نیست.

className روی پنل اصلی Drawer اعمال می‌شود، نه روی overlay. برای تغییر عرض یا ظاهر پنل از همین prop استفاده کن:

<Drawer open={open} onClose={() => setOpen(false)} className="cart-drawer" title="سبد خرید">
  {/* محتوا */}
</Drawer>

Accessibility

• بستن با کلید Escape پشتیبانی می‌شود.
• دکمه‌ی بستن دارای aria-label="بستن" است.
• برای عنوان‌های معنادار از title استفاده کن و داخل children یک ساختار منطقی برای navigation یا فرم قرار بده.
• پیاده‌سازی فعلی role="dialog"، aria-modal و focus trap خودکار ندارد؛ اگر Drawer برای جریان‌های حساس یا keyboard navigation کامل استفاده می‌شود، این ویژگی‌ها را در wrapper خودت اضافه کن یا کامپوننت را بهبود بده.

Data Attributes and Customize CSS

Drawer hookهای زیر را ارائه می‌کند:

Attribute	کاربرد
data-fara-drawer-overlay	overlay تمام‌صفحه
data-open	روی overlay و پنل فقط هنگام visible بودن
data-fara-drawer	پنل اصلی
data-side	سمت پنل: start یا end
data-fara-drawer-header	header پنل
data-fara-drawer-title	heading عنوان
data-fara-drawer-close	دکمه‌ی بستن
data-fara-drawer-body	بدنه‌ی قابل اسکرول

[data-fara-drawer][data-side="end"] {
  width: min(420px, 90vw);
}

[data-fara-drawer-overlay][data-open] {
  background: rgb(15 23 42 / 45%);
}

[data-fara-drawer-body] {
  padding: 20px;
}

چون Drawer با Portal در document.body رندر می‌شود، selectorهای پنل و overlay را به container والد وابسته نکن.

Props

Prop	Type	Default	Description
open	boolean	-	باز یا بسته بودن کشو (الزامی)
onClose	() => void	-	هنگام بسته شدن صدا زده می‌شود (الزامی)
children	ReactNode	-	محتوای بدنه‌ی کشو (الزامی)
title	string	-	عنوان هدر کشو
side	"start" | "end"	"end"	سمت باز شدن کشو
className	string	-	کلاس CSS اضافی روی پنل کشو