انتخاب بصری در فیلتر (FilterSectionChoices)

معرفی

ستون فیلتری که همهٔ بخش‌هایش فهرست چک‌باکس است، خواندن را کند می‌کند: هیجان بی‌رنگ، سطح بی‌شمار، زبان بی‌نشانه. FilterSectionChoices شکل کنترل را از نوع داده می‌گیرد و رنگ و آیکون هر مقدار را از همان توکن‌های DS که نشان و نمودار آن مقدار می‌کشند؛ پس فیلتر، کارت و نمودار یک زبان بصری دارند.

فهرست بلند اسمی (مثل دسته‌ها) همان FilterSectionOptions با جست‌وجو و شمار می‌ماند؛ عدد ترتیبی FilterSectionRange است (با slider و هیستوگرام)، و بلی/خیر یک Switch.

• رنگ هرگز تنها: هر گزینه کلمه و شمار دارد؛ انتخاب = زمینهٔ کم‌رنگ توکن + مرز در لایهٔ متنی AA + علامت ✓.
• رنگ فقط از توکن: tone یکی از emotion:*، flow:*، status:*، severity:* یا brand است؛ هیجان و دیدگاه آیکون نشان خودشان را هم می‌آورند (EMOTION_META، FLOW_META).
• صفر: کم‌رنگ و قابل‌انتخاب؛ در بارگذاری count را ندهید.
• نشانهٔ فعال: بخش دارای مقدار قرص پر برند می‌گیرد؛ بخشی که فقط پیش‌فرض سامانه دارد، نشان «پیش‌فرض» (FilterSection defaultActive)؛ سرِ ستون «فیلترها [N] · M پیش‌فرض» (FilterPanelTitle defaultCount).

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

• دسته‌ای کوتاه که رنگ یا آیکون معنایی دارد (هیجان، دیدگاه، سطح)
• چند مقدار با نشانهٔ قوی (منبع، زبان) یا 2 تا 4 مقدار انحصاری
• وقتی شمار هر سطح خودش خبر است (کارت سطح)

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

• فهرست بلند اسمی با جست‌وجو — از FilterSectionOptions استفاده کنید
• عدد ترتیبی (امتیاز، تعداد) — از FilterSectionRange استفاده کنید
• بیرون از ستون فیلتر، برای انتخاب در فرم — از RadioCards یا ToggleGroup استفاده کنید

استفاده

import { FilterSection, FilterSectionChoices, LanguageGlyph } from '@partodata/ui'

<FilterSection title="هیجان غالب" activeCount={emotions.length} onClear={() => setEmotions([])} defaultOpen={false}>
  <FilterSectionChoices
    variant="chips"
    options={[
      { value: 'anger', label: 'خشم', tone: 'emotion:anger', count: 9 },
      { value: 'fear', label: 'ترس', tone: 'emotion:fear', count: 4 },
    ]}
    value={emotions}
    onValueChange={setEmotions}
  />
</FilterSection>

<FilterSection title="زبان محتوا" activeCount={langs.length} defaultOpen={false}>
  <FilterSectionChoices
    variant="cards"
    options={[
      { value: 'fa', label: 'فارسی', icon: <LanguageGlyph lang="fa" />, count: 20 },
      { value: 'en', label: 'انگلیسی', icon: <LanguageGlyph lang="en" />, count: 2 },
    ]}
    value={langs}
    onValueChange={setLangs}
  />
</FilterSection>

بازهٔ زمانی در ستون فیلتر:

<FilterSectionPeriod
  title="بازهٔ زمانی"
  presets={[
    { value: '24h', label: '24 ساعت' },
    { value: '7d', label: '7 روز' },
    { value: '30d', label: '30 روز' },
  ]}
  defaultValue="7d"
  value={preset}
  onValueChange={setPreset}
  picker={<DateRangePicker value={range} onValueChange={setRange} presets={GA_PRESETS} />}
  comparison="در برابر 4 تا 10 مهر"
/>

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

Props

FilterSectionChoices

FilterSectionPeriod

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

• چندتایی: گروه role="group" با گزینه‌های role="checkbox" و aria-checked؛ تکی: role="radiogroup" و role="radio".
• یک توقف Tab برای کل گروه؛ فلش‌ها (در RTL فلش چپ = بعدی)، Home و End حرکت می‌دهند؛ در گروه تکی حرکت انتخاب هم می‌کند.
• نام دسترسی هر گزینه کلمه و شمار آن است؛ آیکون، نمونهٔ رنگ و میلهٔ سهم aria-hidden هستند.
• مرز و علامت انتخاب از لایهٔ -text توکن (AA در هر دو تم) می‌آیند؛ ارتفاع هدف ≥ 28px و در chips و cards ≥ 32px.

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

• فهرست بلند با جست‌وجو → FilterSectionOptions در FilterPanel
• عدد ترتیبی → FilterSectionRange
• نشانهٔ زبان → LanguageGlyph