تصاویر حالت خالی (EmptyIllustrations)

معرفی

پنج illustration SVG inline برای حالات خالی متداول. همه با currentColor رندر می‌شوند، پس consumer رنگ را با utility class تنظیم می‌کند (مثل text-foreground-muted پیش‌فرض). هیچ‌کدام جهت-وابسته نیستند، تم Light/Dark خودکار تطبیق می‌یابد، و چون stroke-only هستند هر کدام ~600 بایت بعد gzip است.

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

• تکمیل <Empty> primitive با یک visual که scan-time را کم کند
• error-state کلی صفحه (مثل 500 یا 403)
• onboarding cards در حالت first-run

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

• در table cells / button labels — این‌ها برای container-level empty states اند
• وقتی illustration اختصاصی برند نیاز است (سفارش طراحی) — این‌ها generic هستند

زمین بازی

با انتخاب نوع تصویر، گالری حالت‌های خالی را به‌صورت زنده مشاهده کنید.

استفاده

import { NoResultsIllustration } from '@partodata/ui'

<NoResultsIllustration className="size-32 text-foreground-muted" />

هر illustration یک کامپوننت SVG مستقل است؛ رنگ را با token class (به‌خاطر currentColor) و اندازه را با size-* تعیین کنید. هر پنج illustration به همین شکل import می‌شوند — composition کامل کنار Empty را در بخش بعد ببینید.

۵ Illustration

import {
  Empty,
  EmptyTitle,
  EmptyDescription,
  EmptyAction,
  Button,
  NoResultsIllustration,
  NoDataIllustration,
  FirstRunIllustration,
  ErrorIllustration,
  ForbiddenIllustration,
} from '@partodata/ui'

NoResultsIllustration — جستجو بدون نتیجه

<Empty>
  <NoResultsIllustration className="size-32 text-foreground-muted" />
  <EmptyTitle>نتیجه‌ای یافت نشد</EmptyTitle>
  <EmptyDescription>عبارت دیگری امتحان کنید یا فیلترها را پاک کنید</EmptyDescription>
  <EmptyAction>
    <Button variant="outline" onClick={clearFilters}>
      پاک کردن فیلترها
    </Button>
  </EmptyAction>
</Empty>

NoDataIllustration — مجموعه‌داده‌ی خالی

<Empty>
  <NoDataIllustration className="size-32 text-foreground-muted" />
  <EmptyTitle>هنوز داده‌ای ثبت نشده</EmptyTitle>
  <EmptyDescription>پس از اولین جمع‌آوری، این صفحه پر می‌شود</EmptyDescription>
</Empty>

FirstRunIllustration — onboarding اولیه

<Empty>
  <FirstRunIllustration className="size-32 text-brand" />
  <EmptyTitle>به Parto خوش آمدید</EmptyTitle>
  <EmptyDescription>برای شروع، اولین موضوع ردیابی خود را تعریف کنید</EmptyDescription>
  <EmptyAction>
    <Button onClick={startOnboarding}>شروع</Button>
  </EmptyAction>
</Empty>

ErrorIllustration — خطای generic

<Empty>
  <ErrorIllustration className="size-32 text-destructive" />
  <EmptyTitle>خطایی رخ داد</EmptyTitle>
  <EmptyDescription>لطفاً دوباره تلاش کنید یا با پشتیبانی تماس بگیرید</EmptyDescription>
  <EmptyAction>
    <Button variant="outline" onClick={retry}>
      تلاش مجدد
    </Button>
  </EmptyAction>
</Empty>

ForbiddenIllustration — عدم دسترسی

<Empty>
  <ForbiddenIllustration className="size-32 text-foreground-muted" />
  <EmptyTitle>دسترسی ندارید</EmptyTitle>
  <EmptyDescription>این صفحه محدود به ادمین‌هاست</EmptyDescription>
</Empty>

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

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

هر پنج illustration React.SVGProps<SVGSVGElement> می‌گیرند. مهم‌ترین:

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

• هر پنج illustration به‌صورت پیش‌فرض aria-hidden="true" دارند — به‌عنوان decoration در نظر گرفته می‌شوند و معنا از طریق EmptyTitle + EmptyDescription کنار آن منتقل می‌شود.
• اگر illustration به‌تنهایی اطلاعاتی منتقل می‌کند (که توصیه نمی‌شود)، با پاس دادن aria-label آن را override کنید.
• currentColor از token-class والد ارث می‌برد، پس کنتراست رنگ توسط token (مثل text-foreground-muted) تضمین می‌شود — رنگ inline ندهید.
• خطوط stroke-only هستند پس در prefers-reduced-motion و themeهای high-contrast بدون مشکل رندر می‌شوند.

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

• wrapper container → Empty + EmptyIcon + EmptyTitle + EmptyDescription + EmptyAction
• برای chart خالی → EmptyChart (با variants خاص chart)
• error catching component-level → ErrorBoundary
• error با full-screen → ErrorState