نقشه گرمایی (Heat Map)

معرفی

کامپوننت PartoHeatMap یک نقشه گرمایی سفارشی بر پایه SVG خالص و کتابخانه Visx ارائه می‌دهد. این کامپوننت برای نمایش الگوی شدت داده‌ها در دو بعد طراحی شده است؛ مانند فعالیت کاربران در طول روزهای هفته و ساعات شبانه‌روز. از دو زبان فارسی و انگلیسی پشتیبانی می‌کند.

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

• برای نمایش الگوی فعالیت در ماتریس دو بُعدی (مثلاً روز × ساعت)
• برای شناسایی نقاط اوج و فرود در داده‌های grid-based
• برای نمایش ماتریس همبستگی یا توزیع شدت

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

• برای داده‌های غیر matrix — HeatMap برای داده دو بُعدی (X × Y) است
• برای کمتر از ۳×۳ نقطه داده — از BarChart استفاده کنید

استفاده پایه

import { PartoHeatMap, toPersianDigits } from '@parto-system-design/ui'

const persianWeekdays = ['شنبه', 'یکشنبه', 'دوشنبه', 'سه‌شنبه', 'چهارشنبه', 'پنج‌شنبه', 'جمعه']

const data = persianWeekdays.map((day) => ({
  id: day,
  data: Array.from({ length: 24 }, (_, hour) => ({
    x: toPersianDigits(String(hour).padStart(2, '0')) + ':۰۰',
    y: Math.floor(Math.random() * 100),
  })),
}))

<div className="h-[400px]">
  <PartoHeatMap
    data={data}
    locale="fa"
    margin={{ top: 60, right: 50, bottom: 60, left: 150 }}
    xTickFilter={(_, i) => i % 3 === 0}
  />
</div>

نمونه‌های کاربردی

پشتیبانی از زبان فارسی

<PartoHeatMap
  data={dataFa}
  locale="fa"
  yAxisLabel="روز هفته"
  xAxisLabel="ساعات"
  margin={{ top: 60, right: 50, bottom: 60, left: 150 }}
  xTickFilter={(_, i) => i % 3 === 0}
/>

پشتیبانی از زبان انگلیسی

<PartoHeatMap
  data={dataEn}
  locale="en"
  yAxisLabel="Day of Week"
  xAxisLabel="Hours"
  margin={{ top: 60, right: 50, bottom: 60, left: 150 }}
  xTickFilter={(_, i) => i % 3 === 0}
/>

فیلتر تیک‌های محور X

برای جلوگیری از شلوغی برچسب‌ها، از xTickFilter استفاده کنید تا فقط برخی تیک‌ها نمایش داده شوند.

{
  /* نمایش هر ۳ ساعت یک‌بار */
}
;<PartoHeatMap data={data} xTickFilter={(_, index) => index % 3 === 0} />

{
  /* نمایش فقط ساعات زوج */
}
;<PartoHeatMap data={data} xTickFilter={(value, _) => parseInt(value) % 2 === 0} />

سفارشی‌سازی رنگ‌ها

به‌طور پیش‌فرض از رنگ برند (تیل) استفاده می‌شود. می‌توانید تابع رنگ سفارشی ارائه دهید.

<PartoHeatMap
  data={data}
  colorScale={(value, max) => {
    const intensity = value / max
    return `hsl(280, 70%, ${90 - intensity * 60}%)`
  }}
/>

تنظیم شعاع و فاصله سلول‌ها

<PartoHeatMap data={data} cellRadius={8} cellGap={4} />

Tooltip سفارشی

<PartoHeatMap
  data={data}
  renderTooltip={(cell) => (
    <div className="bg-popover text-popover-foreground rounded-md shadow-lg px-3 py-2 border border-border">
      <div className="font-semibold">
        {cell.rowId} - {cell.x}
      </div>
      <div>
        فعالیت: <span className="font-bold">{cell.value}</span>
      </div>
    </div>
  )}
/>

حالت بارگذاری

<PartoHeatMap data={[]} isLoading={true} />

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

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

زبان (locale)

حالت بارگذاری (isLoading)

با isLoading={true} یک Skeleton متحرک به‌جای نمودار نمایش داده می‌شود.

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

ساختار داده‌ها

مقدار id در هر ردیف باید نام توصیفی باشد (نه عدد). مقدار x در هر سلول برچسب ستون و y مقدار عددی شدت است.

// درست
const data = [
  { id: 'شنبه', data: [{ x: '۰۰:۰۰', y: 45 }, { x: '۰۱:۰۰', y: 30 }] },
  { id: 'یکشنبه', data: [{ x: '۰۰:۰۰', y: 20 }, { x: '۰۱:۰۰', y: 55 }] },
]

// اشتباه — از عدد به‌عنوان id استفاده نکنید
const data = [
  { id: 1, data: [...] },
  { id: 2, data: [...] },
]

تم‌بندی خودکار

این کامپوننت به‌طور خودکار از متغیرهای CSS سیستم طراحی استفاده می‌کند:

• رنگ پیش‌فرض سلول‌ها از رنگ برند (تیل) مشتق می‌شود
• با هر دو تم (روشن و تاریک) سازگار است
• محورها و برچسب‌ها با رنگ‌های foreground و muted-foreground هماهنگ هستند

کاربردها

• نمایش الگوی فعالیت کاربران در طول روز و هفته
• تحلیل داده‌های سری زمانی
• نمایش ماتریس همبستگی
• تحلیل توزیع داده‌های دوبعدی با شدت متفاوت

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

• کامپوننت دارای role="img" و پشتیبانی از ariaLabel برای صفحه‌خوان‌ها است
• در حالت بارگذاری از role="status" استفاده می‌شود
• برچسب‌های محورها (xAxisLabel و yAxisLabel) به درک محتوای نمودار کمک می‌کنند
• Tooltip با تعامل ماوس فعال می‌شود و اطلاعات دقیق هر سلول را نمایش می‌دهد

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

• BarChart — اگر داده‌های شما یک بُعدی هستند و نیاز به مقایسه categorical دارید، BarChart مناسب‌تر است
• RadarChart — اگر می‌خواهید چند بُعد را برای یک موجودیت واحد مقایسه کنید، RadarChart انتخاب بهتری است
• LineChart — اگر یک بُعد شما زمان است و فقط یک سری داده دارید، LineChart ساده‌تر است
• داده‌نمایی — راهنمای کامل رنگ‌بندی و تم نمودارها