کارت نمودار (ChartCard)

معرفی

ChartCard یک پوستهٔ واحد و قاعده‌مند برای قاب‌بندی هر نمودار پرتوست. به‌جای این‌که هر صفحه پوستهٔ خودش را بسازد، این کامپوننت یک قاب استاندارد می‌دهد: پس‌زمینهٔ surface-100، سایهٔ نازک، خط دور مویی و گوشهٔ rounded-md. آن را با ChartCardHeader (سربرگ دارای فاصلهٔ عمودی و شکست سطر که کنترل‌هایش sm، 30 پیکسل، هستند)، ChartCardContent و ChartCardFooter اختیاری ترکیب کنید.

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

• برای قاب‌بندی هر نمودار (خطی، میله‌ای، دایره‌ای، Sankey) با یک پوستهٔ یکنواخت
• وقتی نمودار به سربرگ عنوان‌دار و ردیف اقدامات (منو، بازهٔ زمانی) نیاز دارد
• برای فوتر با legend، caption یا اعداد خلاصه زیر نمودار

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

• برای یک نمودار کوچک و بدون قاب داخل جدول یا ردیف — از Sparkline استفاده کنید
• برای محتوای غیرنموداری عمومی — از Card استفاده کنید
• برای یک KPI عددی با روند — از MetricCard استفاده کنید (خودش sparkline دارد)

استفاده

import { ChartCard, ChartCardHeader, ChartCardContent, ChartCardFooter, PartoLineChart } from '@partodata/ui'

const data = [
  { name: 'شنبه', تعامل: 320 },
  { name: 'یکشنبه', تعامل: 410 },
  { name: 'دوشنبه', تعامل: 380 },
  { name: 'سه‌شنبه', تعامل: 460 },
]

export default function EngagementCard() {
  return (
    <ChartCard>
      <ChartCardHeader title="روند تعامل هفتگی کمپین" />
      <ChartCardContent>
        <PartoLineChart data={data} dataKeys={['تعامل']} />
      </ChartCardContent>
      <ChartCardFooter>
        <span className="text-xs text-foreground-lighter">به‌روزرسانی روزانه از همه پلتفرم‌ها</span>
      </ChartCardFooter>
    </ChartCard>
  )
}

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

سربرگ با اقدامات

ChartCardHeader یک prop title (به سبک text-subheading) و یک prop actions دارد که به انتهای ردیف (line-end) سنجاق می‌شود. سربرگ خودش اندازهٔ ردیف را تعیین می‌کند: هر کنترلی که size ندارد، دکمه، PeriodSelector، Select یا انتخابگر بازهٔ تاریخ، sm (30 پیکسل) و به اندازهٔ محتوایش می‌شود، و عنوان و اقدام‌ها در عرض کم به سطر بعد می‌روند. روی کنترل‌ها size ننویسید؛ برای ردیف فشرده‌تر یک ControlSizeProvider size="xs" دور کارت بگذارید.

<ChartCard>
  <ChartCardHeader
    title="روند تعامل هفتگی کمپین"
    actions={
      <>
        <DateRangePicker value={range} onChange={setRange} />
        <Button variant="ghost">خروجی</Button>
      </>
    }
  />
  <ChartCardContent>{/* نمودار */}</ChartCardContent>
</ChartCard>

سربرگ سفارشی (بدون prop title)

اگر title را حذف و به‌جای آن children بدهید، کنترل کامل محتوای سربرگ در دست شماست.

<ChartCard>
  <ChartCardHeader>
    <div className="flex items-center gap-2">
      <PlatformMark source="instagram" />
      <span className="text-subheading">تعامل اینستاگرام</span>
    </div>
  </ChartCardHeader>
  <ChartCardContent>{/* نمودار */}</ChartCardContent>
</ChartCard>

بدون فوتر

فوتر اختیاری است؛ اگر legend یا caption ندارید، ChartCardFooter را حذف کنید.

<ChartCard>
  <ChartCardHeader title="توزیع احساسات" />
  <ChartCardContent>{/* نمودار */}</ChartCardContent>
</ChartCard>

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

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

ChartCard

ChartCardHeader

ChartCardContent

ChartCardFooter

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

• ChartCard صرفاً یک پوستهٔ ساختاری است؛ دسترسی‌پذیری داده باید در خود نمودار (label محورها، جدول متنی جایگزین) تأمین شود
• عنوان در ChartCardHeader را معنادار بگذارید تا زمینهٔ نمودار برای صفحه‌خوان روشن باشد
• خط دور مویی و کنتراست پس‌زمینه در هر دو تم روشن و تیره AA را رعایت می‌کند

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

• Card — برای محتوای عمومی غیرنموداری، از Card پایه استفاده کنید
• MetricCard — اگر می‌خواهید یک KPI عددی همراه sparkline نشان دهید، از MetricCard استفاده کنید
• Sparkline — برای یک نمودار ریز و بدون قاب داخل ردیف یا سلول جدول، از Sparkline استفاده کنید

ChartCardHeader.description توضیح زمینه، مانند دورهٔ دقیق نمودار، را زیر عنوان نشان می‌دهد. ارتفاع ثابت 36 پیکسلی حذف شده است؛ فاصلهٔ بومی سربرگ را با h-9 یا padding سفارشی بازسازی نکنید.