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

معرفی

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

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

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

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

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

استفاده

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

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

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

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

ChartCardHeader یک prop title (به سبک text-meta) و یک prop actions دارد که به انتهای ردیف (line-end) سنجاق می‌شود.

<ChartCard>
  <ChartCardHeader
    title="روند تعامل هفتگی کمپین"
    actions={
      <Button variant="ghost" size="xs">
        شش هفته اخیر
      </Button>
    }
  />
  <ChartCardContent>{/* نمودار */}</ChartCardContent>
</ChartCard>

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

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

<ChartCard>
  <ChartCardHeader>
    <div className="flex items-center gap-2">
      <SocialPlatformBadge platform="instagram" />
      <span className="text-meta">تعامل اینستاگرام</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 استفاده کنید