اسپارک‌لاین (Sparkline)

معرفی

Sparkline یک نمودار کوچک SVG است که در فضای محدود کنار متن یا عدد می‌نشیند و روند یک متریک را نشان می‌دهد. رنگ بر اساس مقایسه‌ی اولین و آخرین نقطه خودکار انتخاب می‌شود (سبز/قرمز/خاکستری) — یا می‌توانید دستی override کنید.

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

• سلول جدول — روند ۷/۳۰ روزه کنار ستون عددی (دنبال‌کننده، تعامل، بازدید)
• کارت متریک — خلاصه‌ی روند پشت عدد اصلی
• کارت پروفایل / concept — نمایش سریع سلامت یک شاخص

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

• محور زمانی مهم است (شما باید ببینید کدام روز اوج بود) — LineChart یا AreaChart کامل
• داده کمتر از ۲ نقطه دارد — یک عدد تنها کافی است
• نیاز به tooltip / hover — sparkline آگاهانه non-interactive طراحی شده؛ برای hover از LineChart استفاده کنید

زمین بازی

استفاده

import { Sparkline } from '@parto-system-design/ui'

export function FollowersMetric() {
  return (
    <div className="flex items-center justify-between">
      <span>دنبال‌کنندگان: ۱۲۳٬۴۵۰</span>
      <Sparkline data={[18, 22, 19, 25, 28, 26, 31]} aria-label="روند ۷ روز اخیر" />
    </div>
  )
}

Sparkline فقط یک آرایه از اعداد می‌گیرد؛ scale و padding را خودکار محاسبه می‌کند. رنگ در حالت پیش‌فرض trend="auto" از --sentiment-* استفاده می‌کند.

انواع

• variant="line" — فقط خط (پیش‌فرض، سبک‌ترین)
• variant="area" — خط + پرکردن زیر آن با ۱۸٪ شفافیت
• variant="bars" — میله‌های جداگانه (مناسب داده‌ی شمارشی روزانه)

رنگ — trend خودکار + سفارشی

• trend="auto" (پیش‌فرض): اولین و آخرین نقطه مقایسه می‌شود
• trend="up" | "down" | "neutral" — اگر می‌خواهید کنترل کنید
• color="..." — هر مقدار CSS (توکن برند، hex، rgb) که trend را نادیده می‌گیرد

رنگ‌ها از توکن‌های --sentiment-* می‌آیند، پس در هر دو تم light/dark درست کار می‌کنند.

ترکیب با جدول

در ستون‌های روند، showEndDot را فعال کنید تا نقطه‌ی پایانی برجسته شود. ارتفاع 20px و عرض 80px در اکثر جدول‌ها مناسب است.

Props

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

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

• بدون aria-label — aria-hidden="true" (زینتی؛ screen reader رد می‌شود)
• با aria-label — role="img" و label به‌عنوان توضیح خوانده می‌شود
• فقط SVG — بدون JavaScript runtime، قابل رندر در SSR
• vectorEffect="non-scaling-stroke" — ضخامت خط ثابت می‌ماند حتی اگر width تغییر کند

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

• MetricCard — دارای MetricCardSparkline داخلی اختصاصی‌تر (با lablel و tooltip)
• LineChart — نسخه‌ی کامل با axis، tooltip، legend — وقتی جزئیات مهم است
• TrendIndicator — فقط درصد تغییر با پیکان بالا/پایین — مناسب کنار sparkline