فیلتر بازهٔ عددی (FilterSectionRange)

معرفی

امتیاز اعتماد (0 تا 100)، سن اکانت و روز از آخرین ورود عددی با ترتیباند. چهار RadioCard تمام‌عرض نشان نمی‌دهد که بازه‌ها به هم می‌رسند و بازهٔ دلخواه («از 40 تا 69») را ممکن نمی‌کند؛ Slider تنها هم در فرم‌ها و فیلترها ممنوع است (از 7.12 اسلایدر فقط به‌صورت slider همین بخش و کنار دو فیلد، همراه هیستوگرام distribution). FilterSectionRange همین نیاز را یک‌جا می‌بندد: یک بخش کامل FilterPanel با دو NumberInputLocale («از» و «تا») و، در صورت نیاز، میان‌برهایی با شمار نتایج.

• اعتبارسنجی لحظه‌ای: جفتِ «از» بزرگ‌تر از «تا» به onValueChange نمی‌رسد؛ هر دو فیلد aria-invalid می‌گیرند و پیام «عدد «از» نباید بزرگ‌تر از «تا» باشد» همان لحظه دیده می‌شود. وقتی فوکوس از هر دو فیلد بیرون رود، بخش آخرین بازهٔ معتبر را نشان می‌دهد؛ هیچ‌وقت نتیجهٔ نمایش‌داده‌شده با مقدارِ فیلد ناسازگار نمی‌ماند.
• سمت باز: سر خالی یعنی «بی‌حد». [7, null] یعنی «7 روز و بیشتر»؛ همین است که «چند روز است وارد نشده» را می‌نویسد.
• مقدارِ فعال آشکار: وقتی بازه از min تا max باریک‌تر است، بخش خودش شمار فعال، «پاک کردن» و (در حالت بسته) خلاصهٔ مقدار («40 تا 69 روز») را زیر عنوان نشان می‌دهد؛ بدون اینکه بخش را باز کنید.
• رقم: در DOM فقط ASCII است؛ فونت رقم فارسی می‌کشد. ورودی فارسی و عربی هم پذیرفته می‌شود.

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

• عددی که ترتیب دارد و کاربر بازه یا آستانه می‌خواهد: امتیاز، سن، تعداد، روز از یک رویداد
• بازه‌ای که چند «باند» آماده دارد و شمار هر باند برای انتخاب کمک می‌کند (presets با count)

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

• برای بازهٔ تقویمی با تاریخ — از DateRangePicker استفاده کنید
• برای عدد تکی داخل یک فرم — از NumberInputLocale استفاده کنید
• برای چند گزینهٔ متمایز بی‌ترتیب — از FilterSectionOptions استفاده کنید

زمین بازی

استفاده

import { FilterPanel, FilterSectionRange, type FilterRangeValue } from '@partodata/ui'

const [trust, setTrust] = React.useState<FilterRangeValue>([null, null])

<FilterPanel>
  <FilterSectionRange
    title="امتیاز اعتماد"
    min={0}
    max={100}
    value={trust}
    onValueChange={setTrust}
    defaultOpen={false}
    presets={[
      { label: 'کم', value: [0, 39], count: 4 },
      { label: 'متوسط', value: [40, 69], count: 11 },
      { label: 'بالا', value: [70, 100], count: 17 },
    ]}
  />
</FilterPanel>

آستانهٔ بی‌حد (سن اکانت، «چند روز است وارد نشده»): max را ندهید و سمت «تا» را خالی بگذارید.

<FilterSectionRange
  title="روز از آخرین ورود"
  min={0}
  unit="روز"
  value={idle}
  onValueChange={setIdle}
  presets={[
    { label: 'بیش از 7 روز', value: [7, null], count: 9 },
    { label: 'بیش از 30 روز', value: [30, null], count: 3 },
  ]}
/>

value را به همان شکلی بدهید که فیلتر صفحه را می‌سازد: [null, null] یعنی فیلتر نیست (بازهٔ کامل min تا max هم همین است). onValueChange را به‌روز نگه دارید و درخواست را debounce کنید، نه این callback را. شمار هر میان‌بر را مثل FilterSectionOptions پیش از اعمال همین بُعد حساب کنید.

نوار فیلترهای فعال

بازهٔ فعال را هم مثل هر فیلتر دیگر به‌صورت چیپ قابل‌حذف بالای نتایج بیاورید و با [null, null] پاک کنید؛ متن چیپ همان خلاصهٔ بخش است («امتیاز اعتماد: 40 تا 69»).

Props

FilterSectionRange

activeCount، «پاک کردن» و خلاصه را خودِ کامپوننت از value می‌سازد؛ لازم نیست از بیرون بدهید. FilterSection هم حالا summary می‌گیرد، برای هر بخش دیگری که می‌خواهد مقدار فعالش را در حالت بسته نشان دهد.

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

• هر فیلد label دیداری دارد («از»، «تا») و دو فیلد در یک group با نام بخش‌اند.
• بازهٔ نامعتبر با aria-invalid و aria-describedby به پیام وصل است و پیام role="alert" است.
• خلاصهٔ مقدار فعال داخل دکمهٔ عنوان است و در نام دسترسی‌پذیر بخش می‌آید؛ شمار فعال هم «فیلترهای فعال» را می‌خواند.
• میان‌برها رادیو و با صفحه‌کلید قابل‌پیمایش‌اند؛ فیلدها از NumberInputLocale همهٔ رفتار ورودی عددی را می‌گیرند.

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

• بازهٔ تاریخ → DateRangePicker
• مقدارهای بی‌ترتیب با شمار → FilterSectionOptions در FilterPanel
• عدد تکی در فرم → NumberInputLocale