انتخاب استان (RegionPicker)

معرفی

RegionPicker یک wrapper سبک روی MultiSelect است که از داده‌ی canonical IRAN_PROVINCES تغذیه می‌شود. خروجی به‌صورت پیش‌فرض slug (مثل tehran) است که URL-friendly است؛ با keyBy="iso" می‌توانید کد ISO 3166-2:IR (مثل IR-07) دریافت کنید.

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

• داشبورد افکارسنجی scoped per province
• فیلتر گزارش بولتن استانی
• Pair با IranProvinceHeat برای فیلتر-and-render همزمان

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

• اگر به انتخاب کشور نیاز دارید — از CountryPicker استفاده کنید
• اگر می‌خواهید نقشه SVG قابل کلیک داشته باشید (Phase 5.4 deferred — هنوز shipped نیست)

زمین بازی

با تغییر تنظیمات زیر، انتخاب استان را به‌صورت زنده مشاهده کنید.

استفاده

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

const [provinces, setProvinces] = React.useState<string[]>([])

;<RegionPicker value={provinces} onValueChange={setProvinces} placeholder="استان را انتخاب کنید" />

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

پیش‌فرض (slug-based)

<RegionPicker value={provinces} onValueChange={setProvinces} />

خروجی به‌صورت کد ISO

<RegionPicker keyBy="iso" value={provinces} onValueChange={setProvinces} />
// خروجی: ['IR-07', 'IR-04', ...]

محدود به استان‌های منتخب

<RegionPicker
  includeSlugs={['tehran', 'isfahan', 'fars', 'khorasan-razavi']}
  value={provinces}
  onValueChange={setProvinces}
/>

Single-select

<RegionPicker maxSelected={1} value={provinces} onValueChange={setProvinces} />

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

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

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

• روی MultiSelect ساخته شده — تمام keyboard interactions به ارث می‌رسد.
• اسامی استان‌ها به فارسی روان screen reader را پیست می‌کنند؛ روی en/ar از label محلی استفاده می‌شود.
• role="combobox" با aria-label معنادار از placeholder یا value تأمین می‌شود.

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

• CountryPicker — اگر نیاز به انتخاب کشور دارید، نه استان
• IranProvinceHeat — برای نمایش choropleth-style توزیع داده روی استان‌ها
• MultiSelect — اگر کامپوننت پایه می‌خواهید بدون دیتاست استانی