انتخاب کشور (CountryPicker)

معرفی

CountryPicker یک wrapper سبک روی MultiSelect است که از یک فهرست curated شامل ۸۰ کشور (همسایگان ایران، خلیج فارس، MENA، بازارهای غربی، آسیا-اقیانوسیه) تغذیه می‌شود. مقدار خروجی همواره کد ISO 3166-1 alpha-2 (دو حرف، uppercase) است و به‌صورت پیش‌فرض پرچم emoji قبل از نام نمایش داده می‌شود.

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

• داشبورد influencer که شکست مخاطب را به تفکیک کشور نشان می‌دهد
• فیلتر صحت‌سنجی منبع برای پست‌هایی که از خارج می‌آیند (AE, TR, IQ)
• تحلیل کمپین چندبازاری

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

• برای فیلتر دقیق‌تر روی استان‌های ایران — از RegionPicker استفاده کنید
• اگر به فهرست کامل ISO 3166 نیاز دارید — options خود را پاس بدهید (پیش‌فرض ۸۰ کشور است)
• برای زبان رابط کاربر — از Select ساده استفاده کنید

زمین بازی

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

استفاده

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

const [codes, setCodes] = React.useState<string[]>([])

;<CountryPicker value={codes} onValueChange={setCodes} placeholder="کشور را انتخاب کنید" />

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

پیش‌فرض با پرچم

<CountryPicker value={codes} onValueChange={setCodes} />

بدون پرچم (لیست متنی)

<CountryPicker showFlag={false} value={codes} onValueChange={setCodes} />

محدود به یک زیرمجموعه

<CountryPicker includeCodes={['IR', 'IQ', 'AF', 'TR', 'PK']} value={codes} onValueChange={setCodes} />

Single-select با سقف ۱

<CountryPicker maxSelected={1} value={codes} onValueChange={setCodes} />

دیتاست سفارشی (override کامل)

<CountryPicker
  options={[
    { code: 'XK', labels: { fa: 'کوزوو', ar: 'كوسوفو', en: 'Kosovo' } },
    { code: 'TW', labels: { fa: 'تایوان', ar: 'تايوان', en: 'Taiwan' } },
  ]}
  value={codes}
  onValueChange={setCodes}
/>

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

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

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

• روی MultiSelect ساخته شده — Tab برای فوکوس trigger، Space/Enter برای باز شدن popover، Arrow keys برای navigation در فهرست، Escape برای close.
• پرچم emoji با whitespace قبل از نام جدا می‌شود؛ screen reader نام کشور را به‌صورت کامل می‌خواند.
• مقدار trigger روی role="combobox" و aria-expanded به‌روزرسانی می‌شود.
• روی RTL، popover با align="start" به سمت منطقی align می‌شود.

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

• RegionPicker — اگر نیاز به انتخاب استان ایران دارید، نه کشور
• MultiSelect — اگر کامپوننت پایه‌ای می‌خواهید بدون دیتاست country-specific
• SocialPlatformBadge — برای نمایش پلتفرم نه کشور