المكوّنات

مجموعة أزرار التبديل

خيارات مترابطة في صف واحد متصل، يُختار منها واحد: لتبديل طريقة العرض أو تصفية النتائج. الخيار الأول في بداية السطر، أي على اليمين في العربية.

المعاينة

المعكوسة هي المحتوى الإنجليزي نفسه من اليمين إلى اليسار، لتفصل خطأ الاتجاه عن خطأ الترجمة.

التثبيت

قريبًايُفتح التثبيت من السجل مع الإطلاق. حتى ذلك الحين، هذا هو الأمر الذي ستستخدمه.

npx shadcn@latest add @ritla/toggle-group

الاعتماديات التي يضيفها: @base-ui/react, @phosphor-icons/react

الاستخدام

import { ToggleGroup, ToggleGroupItem } from "@/components/ui/toggle-group";

<ToggleGroup aria-label="Period" defaultValue="week">
  <ToggleGroupItem value="day" label="Day" />
  <ToggleGroupItem value="week" label="Week" />
  <ToggleGroupItem value="month" label="Month" />
</ToggleGroup>

أمثلة

الأنماط

outline (الافتراضي) وtonal وfilled. الخيار المختار يأخذ لون الزر المضغوط، والفواصل والإطار بلون واحد. الخيار المعطّل يبقى ظاهراً.

الأحجام

بارتفاعات الزر: ‏56 و48 و40 و32 بكسل. مساحة النقر 48 بكسل على الأقل في sm وxs.

أيقونات فقط

showLabel={false} يُبقي الأيقونة وحدها لأشرطة الأدوات المدمجة، ويبقى label اسماً لقارئات الشاشة.

تصفية ولوحة المفاتيح

نسخة متحكَّم بها عبر value وonValueChange، والأعداد تتبع إعداد الأرقام. Tab يدخل المجموعة مرة واحدة، والأسهم تنتقل بين الخيارات: في العربية السهم الأيسر هو التالي.

مرجع الخصائص

ToggleGroup

الخاصية	النوع	الافتراضي	الوصف
`variant`	`"outline" \| "tonal" \| "filled"`	`"outline"`	خاصية Style.
`size`	`"lg" \| "md" \| "sm" \| "xs"`	`"lg"`	خاصية Size: ‏56 و48 و40 و32 بكسل.
`value`	`string`		قيمة الخيار المختار (متحكَّم به).
`defaultValue`	`string`		الخيار المختار في البداية. في Figma هو الأول.
`onValueChange`	`(value: string) => void`		يُستدعى بالقيمة الجديدة. الضغط على المختار مجدداً لا يلغي اختياره.
`disabled`	`boolean`	`false`	يعطّل كل الخيارات.
`aria-label`	`string`		اسم المجموعة («الفترة»، «طريقة العرض»).

ToggleGroupItem

الخاصية	النوع	الافتراضي	الوصف
`value`	`string`		معرّف الخيار.
`label`	`string`		مطلوب. خاصية Label، واسم الخيار حتى لو أُخفي النص.
`showLabel`	`boolean`	`true`	خاصية Show Label.
`iconLeading`	`IconComponent`		Icon leading: أيقونة قبل النص.
`disabled`	`boolean`	`false`	State = Disabled لهذا الخيار.

إمكانية الوصول

لوحة المفاتيح

المفاتيح مكتوبة للاتجاه من اليسار إلى اليمين. في الاتجاه من اليمين يتبادل السهمان دورهما: السهم المتجه مع اتجاه القراءة ينقلك إلى الأمام.

المفتاح	ما يفعله
`Tab`	يدخل المجموعة مرة واحدة، على الخيار المختار، ويخرج منها بالضغطة التالية.
`ArrowRightArrowLeft`	ينتقل إلى الخيار التالي أو السابق ويلتف عند الطرفين. في العربية ينعكس الاتجاه.
`EnterSpace`	يختار الخيار الذي عليه التركيز.

ARIA

مجموعة role="group" باسم من aria-label، وكل خيار زر أصلي يحمل aria-pressed.
الاختيار لا يعتمد على اللون وحده: يعلنه aria-pressed، ويبقى خيار واحد مختاراً دائماً.
في وضع الأيقونات فقط يصبح label قيمة aria-label للخيار.

ملاحظات العربية والاتجاه

ينعكس

ترتيب الخيارات ينعكس: الأول في بداية السطر (اليمين في العربية)، والفواصل حدود منطقية تتبع الاتجاه.
الأسهم تتبع اتجاه القراءة: السهم الأيسر ينتقل إلى الخيار التالي في العربية.

لا ينعكس

الأيقونات غير الاتجاهية (قائمة، شبكة، خريطة) لا تنعكس؛ الاتجاهية فقط تنعكس عبر <Icon>.

الأرقام: الأعداد داخل الخيارات («مفتوحة 12») تُنسّق بـformatNumber وتتبع إعداد الأرقام.
الخط العربي: body-16 (وbody-14 في xs) بوزن Semibold كالزر. الخيارات تأخذ عرض نصها، فالعربية الأقصر لا تُمدّ.
النص ثنائي الاتجاه: اسم لاتيني داخل خيار عربي («عرض Kanban») يُعرض صحيحاً في نهاية النص؛ في وسطه ضعه في <bdi>.