نقشهٔ استان‌ها (IranMap)

معرفی

IranMap نقشهٔ رنگی (choropleth) 31 استان ایران است: یک SVG درون‌خطی با مرزهای ساده‌شده، بدون هیچ کتابخانهٔ نقشه. هر استان با طیف ترتیبی سیستم طراحی (--seq-1 تا --seq-7) و نسبت مقدارش به بیشترین مقدار رنگ می‌گیرد؛ استانی که داده ندارد «بدون داده» است. داده همان مدل IranProvinceHeat است، پس یک داده هر دو نما را می‌سازد.

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

• وقتی الگوی جغرافیایی خودش پیام است: همسایگی استان‌ها، تمرکز در یک منطقه، تفاوت شمال و جنوب
• فیلتر صفحه با کلیک روی یک استان (onProvinceClick و selected)
• کنار IranProvinceHeat یا یک جدول، وقتی هم «کجا» مهم است و هم «چقدر»

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

• وقتی مقایسهٔ دقیق مقدارها مهم است: چشم مساحت را هم می‌خواند و استان بزرگ پررنگ‌تر به نظر می‌رسد؛ IranProvinceHeat مرتب‌شده بهتر است
• وقتی جای کم است (کارت کوچک، ستون جدول): استان‌های کوچک (قم، البرز، تهران) دیگر دیده نمی‌شوند
• داده‌ای که مثبت و منفی دارد (تغییر نسبت به دورهٔ قبل): این طیف ترتیبی است، نه واگرا

استفاده

import { IranMap } from '@partodata/ui/iran-map'

export function ProvinceMentionsCard() {
  const [province, setProvince] = React.useState<string>()
  return (
    <IranMap
      data={{ tehran: 4820, isfahan: 2140, 'razavi-khorasan': 1965 }}
      valueSuffix=" نظر"
      label="نظرها به تفکیک استان"
      selected={province}
      onProvinceClick={(p) => setProvince((current) => (current === p.slug ? undefined : p.slug))}
    />
  )
}

IranMap فقط از زیرمسیر @partodata/ui/iran-map وارد می‌شود تا مرزهای استان‌ها (حدود 12 کیلوبایت) به بستهٔ اصلی اضافه نشوند. data مثل IranProvinceHeat یک Record<string, number> یا آرایهٔ { code, value }[] است؛ کد، slug انگلیسی (tehran) یا کد ISO 3166-2:IR (IR-07) است و کد ناشناس نادیده گرفته می‌شود.

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

رنگ و راهنما

مقدارها به هفت پلهٔ طیف ترتیبی (--seq-1 کمترین، --seq-7 بیشترین) تقسیم می‌شوند؛ این توکن‌ها در تم تاریک و روشن هر کدام ترتیب تأکید را حفظ می‌کنند، پس نقشه بدون هیچ تنظیمی در هر دو تم درست است. راهنمای رنگ زیر نقشه کمترین و بیشترین مقدار و نشان «بدون داده» را دارد (showLegend={false} آن را برمی‌دارد، مثلاً وقتی راهنما در کارت دیگری است).

استان‌های بدون داده با سطح خنثی و مرز مشخص در هر دو تم دیده می‌شوند؛ حتی اگر مجموعهٔ داده خالی باشد، شکل هر 31 استان حفظ می‌شود. نشان «بدون داده» در راهنما همین رنگ را دارد. مقدار اندازه‌گیری‌شدهٔ صفر، دادهٔ معتبر است و با پلهٔ نخست طیف ترتیبی نمایش داده می‌شود؛ آن را برای نبود داده جایگزین نکنید.

فیلتر با کلیک

با onProvinceClick هر استان یک دکمهٔ تغییر وضعیت می‌شود: کلیک، Enter یا Space آن را گزارش می‌کند و استان‌های selected با aria-pressed و خط دور پررنگ نشان داده می‌شوند. نقشه خودش چیزی را انتخاب نمی‌کند؛ صفحه انتخاب را نگه می‌دارد (معمولاً در فیلترهای URL) و به selected برمی‌گرداند. callback شیء { slug, iso, label, value } می‌گیرد.

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

• کل نقشه یک توقف Tab است: فوکوس روی استان انتخاب‌شده (یا پرمقدارترین) می‌نشیند و کلیدهای جهت، Home و End بین استان‌ها جابه‌جا می‌شوند، به همان ترتیب جدول.
• هر استان نامی مثل «تهران: 4,820 نظر» دارد و tooltip با اشاره‌گر و با فوکوس صفحه‌کلید هر دو باز می‌شود (Escape آن را می‌بندد).
• یک جدول پنهان (sr-only) با عنوان label همهٔ 31 استان و مقدارشان را دارد، برای صفحه‌خوانی که نقشه را نمی‌بیند.
• رنگ تنها حامل مقدار نیست: مقدار در نام، tooltip و جدول هم هست.

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

Props

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

• IranProvinceHeat — همان داده، به شکل فهرست مرتب با نوار مقدار
• RegionPicker — انتخاب استان در فرم و فیلتر