کارت مفهوم (ConceptCard)

معرفی

ConceptCard کارت تک-مفهومی برای dashboardهای کلاسترینگ نظرات است: هر کارت یک خوشه (concept) از نظرات همگرا را نمایش می‌دهد. composition آن شامل وضعیت زنده (status pulse)، شدت (severity)، توزیع گرایش مخاطب (5-class)، توزیع sentiment (3-class)، trend sparkline، و یک خلاصه‌ی AI است. مناسب grid 3-ستونه در صفحه‌ی کلاسترها.

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

• صفحه‌ی کلاسترها/خوشه‌ها که ده‌ها concept را به‌صورت grid قابل-مقایسه نشان می‌دهد
• خروجی تحلیل ML که برای هر cluster signalهای متنوع تولید می‌کند (flow، emotion، trend)
• صفحه‌ی انتخاب چندتایی برای مقایسه — comparison prop checkbox header را اضافه می‌کند

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

• یک concept تکی در detail view → از MetricCard + Charts جداگانه برای هر signal استفاده کنید (نمایش بزرگ‌تر)
• لیست خبر/پست با کاربرد متفاوت → PostCard یا PostList
• وقتی فقط نام و یک متریک می‌خواهید → Card پایه

زمین بازی

استفاده

import { ConceptCard } from '@partodata/ui'
;<ConceptCard
  title="رونمایی گوشی جدید"
  subtitle="خوشه ۴ — ۱٬۲۴۰ پست"
  status="critical"
  severity="urgent"
  flow={{ 'pro-gov': 80, 'internal-critic': 320, 'internal-opponent': 540, 'external-opponent': 200, grey: 100 }}
  sentiment={{ positive: 120, negative: 920, neutral: 200 }}
  trend={[8, 12, 15, 22, 35, 48, 56, 78]}
  totalCount={1240}
  aiSummary="حجم نظرات منفی در ۲۴ ساعت اخیر سه برابر شده."
/>

حالت‌ها

مقایسه

با تنظیم comparison، یک checkbox در هدر کارت ظاهر می‌شود؛ هندلر کلیکِ کارت، کلیک‌هایی را که هدفشان داخل زیردرخت [data-slot="concept-card-comparison"] است نادیده می‌گیرد تا کلیک روی checkbox باعث activate شدن کل کارت نشود.

const [selected, setSelected] = React.useState(false)
<ConceptCard
  title="کمپین تخفیف فصلی"
  comparison={{ selected, onSelectionChange: setSelected, label: 'مقایسه' }}
  ...
/>

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

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

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

• وقتی interactive=true پاس شود، کارت role="button" + tabIndex=0 می‌گیرد و با Enter/Space قابل فعال‌سازی است؛ در غیر این صورت role="article".
• هندلر کلیکِ کارت، کلیک‌هایی با هدف داخل زیردرخت [data-slot="concept-card-comparison"] را نادیده می‌گیرد (بررسی closest())، بنابراین کلیک روی checkbox comparison باعث activate شدن کل کارت نمی‌شود و focus order مستقل است.
• status pulse با کلاس animate-pulse-subtle (از StatusBadge) رندر می‌شود؛ در prefers-reduced-motion از طریق قانون سراسری globals.css ساکن می‌ماند و معنا از رنگ + label status منتقل می‌شود.
• توزیع flow و sentiment به‌صورت segmentهای رنگی نمایش داده می‌شوند ولی متن جداگانه (مثل subtitle یا total count) معنا را منتقل می‌کند تا کاربر color-blind محروم نماند.
• aiSummary clamp خودکار ندارد و به‌طور کامل رندر می‌شود؛ متن را به ۱-۲ جمله محدود کنید یا در سمت مصرف‌کننده clamp اعمال کنید.

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

• برای پروفایل اکانت/پیج به‌جای مفهوم → PageCard
• برای کارت یک پست تکی → PostCard
• توزیع گرایش به‌صورت standalone → FlowDistribution
• برای ترکیب چندتا کارت در یک گزارش → ReportComposer + ConceptCard به‌عنوان children