نقشه‌حرارتی استان‌ها (IranProvinceHeat)

معرفی

IranProvinceHeat یک لیست عمودی است که هر سطر آن یک استان ایران را با heat-bar افقی نشان می‌دهد؛ شدت رنگ پس‌زمینه با نسبت value / max رشد می‌کند. این الگو جایگزین سبک، قابل دسترس و تماماً RTL برای SVG-map نقشه ایران است — برای ۹۰٪ موارد توزیع per-province در dashboardهای افکارسنجی کافی است و بدون نیاز به topojson یا نقشه برداری دستی روی هر اندازه‌ی صفحه واکنش می‌دهد.

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

• توزیع جغرافیایی نظرات، شکایات، اخبار منتشره، یا هر متریک شمارشی per-province
• مقایسه‌ی سطح رضایت یا سطح ریسک بین استان‌ها (با scale معنا‌دار: sentiment / severity / flow)
• صفحه‌ی مقایسه‌ی استان‌ها با قابلیت کلیک برای drill-down
• بخش‌های report و bulletin که SVG-map سنگین نیست

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

• وقتی معنای geometry مهم است (همسایگی استان‌ها، فاصله، مرزها) — به نقشه‌ی واقعی نیاز دارید
• وقتی داده‌ای per-province نیست (مثلاً city-level یا national aggregate) — PartoBarChart افقی یا MetricCard بهتر است
• بیش از یک متریک هم‌زمان روی یک ردیف — DataTable با ستون‌های sparkline و progress استفاده کنید

زمین بازی

استفاده

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

export function ProvinceCommentsCard() {
  return (
    <IranProvinceHeat
      data={{
        tehran: 4820,
        isfahan: 2140,
        'razavi-khorasan': 1965,
      }}
      valueSuffix=" نظر"
      topN={8}
      hideMissing
      showRank
    />
  )
}

می‌توانید data را به دو شکل پاس بدهید: یک Record<string, number> یا آرایه‌ی { code, value }[]. کد می‌تواند slug انگلیسی باشد (مثل tehran) یا کد ISO 3166-2:IR (مثل IR-07). استان‌های ناشناس به‌سادگی نادیده گرفته می‌شوند (و در صورت وجود onUnknownCode گزارش می‌شوند).

scale — انتخاب توکن رنگ معنا‌دار

scale پیش‌فرض brand است؛ ولی بسته به نوع داده، یک scale معنایی انتخاب کنید:

sentiment-positive — رضایت / امتیاز خوب

برای داده‌ای که «بزرگ‌تر = مثبت‌تر» است: نرخ رضایت، نمره NPS، درصد رشد مثبت.

severity-urgent — هشدار / گزارش بحرانی

برای داده‌ای که «بزرگ‌تر = خطرناک‌تر» است: تعداد گزارش‌های فوری، حوادث، پیک شکایات. scale قرمز/نارنجی به سرعت توجه ایجاد می‌کند.

scaleهای موجود:

• brand (پیش‌فرض)
• sentiment-positive / sentiment-negative
• destructive / warning
• severity-urgent / severity-high
• flow-pro-gov / flow-internal-critic (برای داده‌ی کلاسترینگ افکارسنجی)

قابلیت کلیک برای drill-down

با تنظیم onProvinceClick، هر سطر به <button> تبدیل می‌شود (با focus ring + keyboard activation). callback یک object { slug, iso, value } دریافت می‌کند که برای navigation یا filter setup ایده‌آل است.

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

با isLoading لیست skeleton نمایش داده می‌شود (با role="status" برای screen readerها). الگوی Suspense-friendly — اول این، سپس داده.

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

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

توابع کمکی

علاوه بر کامپوننت، lib این utilityها را هم export می‌کند:

• IRAN_PROVINCES — آرایه‌ی readonly از ۳۱ استان با labels (fa/ar/en) و کد ISO
• findProvince(codeOrSlug) — جستجو بر اساس slug یا ISO، undefined برای ناشناس
• getProvinceLabel(codeOrSlug, locale) — برچسب locale-appropriate یا fallback به slug

import { IRAN_PROVINCES, findProvince, getProvinceLabel } from '@parto-system-design/ui'

// ساختن لیست استان‌ها برای یک <Select>
const options = IRAN_PROVINCES.map((p) => ({
  value: p.slug,
  label: p.labels.fa,
}))

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

• ریشه role="list" و هر سطر role="listitem" — screen reader آن را به‌عنوان لیست می‌خواند
• در حالت تعاملی، هر سطر <button type="button"> با aria-label="نام استان: مقدار" است
• focus-visible:ring-2 ring-brand برای navigation کلیدی Tab/Enter/Space
• data-rank روی هر سطر برای CSS hooks یا تله‌متری
• skeleton حالت role="status" aria-label="در حال بارگذاری" می‌گیرد
• بدون hardcoded color — تطبیق با Light/Dark theme خودکار

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

• برای انتخاب استان به‌عنوان فیلتر → RegionPicker (هنوز پیاده نشده — در roadmap است). این کامپوننت صرفاً نمایش‌گر است.
• اگر داده‌ی شما per-city یا per-county است → PartoBarChart افقی یا DataTable با ستون مقدار
• اگر می‌خواهید به‌عنوان heat-bar تک‌سطری در یک card نمایش دهید → Sparkline با variant bars کوچک‌تر است
• اگر می‌خواهید توزیع چند-دسته‌ای روی provinces نشان دهید (مثلاً flow distribution per-province) → DataTable با ستون FlowCell بسازید