Alert

کامپوننت Alert برای نمایش پیام‌های مهم به کاربر استفاده می‌شود؛ مثل اطلاع‌رسانی، تأیید موفقیت یا هشدار خطا. برخلاف Toast که موقتی است، Alert بخشی از محتوای صفحه است و تا زمانی که کاربر آن را نبندد باقی می‌ماند.

Import

import { Alert } from "fara-ui";

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

Basic Usage

<Alert variant="success">تغییرات با موفقیت ذخیره شد.</Alert>

Playground

این یک پیام اطلاع‌رسانی است.

variantinfosuccesswarningdanger

closable

children

<Alert variant="info">
  این یک پیام اطلاع‌رسانی است.
</Alert>

نکته: چون Alert بسته‌شده دیگر رندر نمی‌شود، برای دیدن دوباره‌ی آن در Playground مثلاً variant را تغییر بده.

Variant

• info (پیش‌فرض) — پیام اطلاع‌رسانی معمولی
• success — تأیید موفقیت یک عملیات
• warning — هشدار؛ نیازمند توجه کاربر
• danger — خطا یا وضعیت بحرانی

Dismissing the Alert

با closable دکمه‌ی ✕ در سمت چپ پیام نمایش داده می‌شود. کلیک روی آن ابتدا انیمیشن خروج را اجرا می‌کند و بعد از آن onClose صدا زده می‌شود — بهترین جا برای به‌روزرسانی state خودت.

function SaveMessage() {
  const [open, setOpen] = useState(true);

  if (!open) return null;

  return (
    <Alert
      variant="success"
      closable
      closeLabel="بستن پیام ذخیره‌سازی"
      onClose={() => setOpen(false)}
    >
      تغییرات با موفقیت ذخیره شد.
    </Alert>
  );
}

بسته‌شدن درون کامپوننت مدیریت می‌شود و پس از پایان transition، onClose فراخوانی می‌شود. برای نمایش دوباره‌ی پیام، آن را با state والد دوباره mount کن؛ تغییر propها به‌تنهایی dismissed بودن داخلی را reset نمی‌کند.

Icon

با icon می‌توانی یک آیکون (مثلاً SVG سفارشی) در ابتدای پیام نمایش بدهی.

<Alert variant="warning" icon={<span aria-hidden="true">⚠️</span>}>
  اتصال اینترنت ناپایدار است.
</Alert>

Accessibility

• کامپوننت با role="alert" پیاده شده، پس برای screen reader ها به‌صورت خودکار اعلام می‌شود.
• دکمه‌ی بستن دارای aria-label است (متن آن با closeLabel قابل تغییر است).
• اگر icon صرفاً تزئینی است، برای آن aria-hidden="true" قرار بده؛ متن پیام باید به‌تنهایی مفهوم وضعیت را منتقل کند.
• انیمیشن با prefers-reduced-motion: reduce غیرفعال می‌شود.

Data Attributes and Customize CSS

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

Attribute	کاربرد
data-fara-alert	ریشه‌ی پیام
data-variant	نوع پیام: info، success، warning یا danger
data-open	فقط هنگام visible بودن Alert
data-fara-alert-content	wrapper محتوای پیام
data-fara-alert-close	دکمه‌ی بستن

<Alert className="save-alert" variant="success" closable>
  ذخیره شد.
</Alert>

[data-fara-alert][data-variant="success"] {
  border-inline-start-width: 4px;
}

[data-fara-alert]:not([data-open]) {
  pointer-events: none;
}

[data-fara-alert-close] {
  min-width: 28px;
  min-height: 28px;
}

className روی ریشه اعمال می‌شود؛ برای تشخیص variant یا مرحله‌ی باز/بسته از data-variant و data-open استفاده کن.

Props

Prop	Type	Default	Description
variant	"info" | "success" | "warning" | "danger"	"info"	نوع و رنگ پیام
icon	ReactNode	-	آیکون ابتدای پیام
closable	boolean	false	نمایش دکمه‌ی بستن
closeLabel	string	"بستن"	متن aria-label دکمه‌ی بستن
onClose	() => void	-	پس از تکمیل انیمیشن بسته‌شدن صدا زده می‌شود
className	string	-	کلاس CSS اضافی برای سفارشی‌سازی
ref	Ref<HTMLDivElement>	-	دسترسی مستقیم به المان DOM

علاوه بر موارد بالا، تمام ویژگی‌های استاندارد <div> نیز پشتیبانی می‌شوند.