شارة (Badge)

يعرض مكوّن شارة (Badge) تسمية قصيرة داخل السطر لحالة أو فئة أو معلومة، مع أيقونة أو صورة رمزية أو زر إغلاق عند الحاجة.

التثبيت

bash

npx @smicolon/cli init
npx @smicolon/cli add badge

معاينة

جديدمدفوعمميّز

الأنماط (variant)

تحدد الخاصية variant وزن الشارة البصري، وتحدد tone معناها. أبرز الأنماط (variant) هو Solid، ويضع Soft لونًا خفيفًا فوق سطح البطاقة فيبدو كما هو أينما وُضع، وأهدؤها Outline.

جديدمسودةقيد المراجعةمدفوعبانتظار الدفعمتأخر

تجعل radius="standard" زوايا الشارة صغيرة بدل الشكل الكبسولي.

جديدجديدجديدجديد

الأحجام

الارتفاعات حدود دنيا: للإنجليزية 20px أو 22px أو 26px. أما العربية فسطرها أطول، فتكبر الشارة إلى 24px أو 24px أو 28px بدل أن يُضغط النص.

مميّزمميّزمميّز

الحالات

مرّر onClose فتحصل الشارة على زر إغلاق حقيقي. انتقل إليه بمفتاح Tab لترى حلقة التركيز، وهي تحيط بالشارة كلها على بُعد 2px.

التصميمالهندسةالبحثالتسويق

مميّزليلىمراجِعة

إتاحة الوصول (accessibility)

الشارة عنصر <span> بسيط. زر الإغلاق وحده تفاعلي، وهو عنصر <button> أصلي.
يُسمّى زر الإغلاق باسم التسمية: «إزالة القاهرة»، أو «Remove Cairo» حين تكون أقرب قيمة لـ lang هي الإنجليزية. ويتبع الاسم تغيير اللغة دون إعادة تحميل. مرّر closeLabel لسياق أوضح، مثل «إزالة عامل التصفية: القاهرة».
الأيقونة زخرفية ومخفية عن التقنيات المساعدة، أما الصورة الرمزية فلا. أعطِ مكوّن صورة رمزية (Avatar) قيمة name، أو مرّر name="" إذا كانت التسمية تذكر اسم الشخص.
لا تعتمد على اللون الدلالي (tone) وحده لنقل المعنى، بل اكتبه في التسمية.
تأخذ الشارة اتجاهها من السمة (attribute) dir، وليس من خاصية، فلا تختلف أبدًا عن اتجاه الصفحة.

الخصائص (props)

الخاصية	النوع	الافتراضي	الوصف
`children`	`ReactNode`	لا يوجد	نص التسمية.
`variant`	`"solid" \| "soft" \| "outline"`	`"solid"`	الوزن البصري.
`tone`	`"primary" \| "secondary" \| "info" \| "success" \| "warning" \| "destructive"`	`"primary"`	المعنى، ويظهر لونًا.
`size`	`"sm" \| "md" \| "lg"`	`"sm"`	حجم الشارة.
`radius`	`"rounded" \| "standard"`	`"rounded"`	شكل كبسولي أو زوايا صغيرة.
`icon`	`ReactNode`	لا يوجد	أيقونة قبل التسمية.
`avatar`	`ReactNode`	لا يوجد	صورة رمزية قبل التسمية.
`onClose`	`(event) => void`	لا يوجد	يضيف زر إغلاق، وتُستدعى عند الضغط عليه.
`closeLabel`	`string`	لا يوجد	اسم زر الإغلاق لقارئ الشاشة، ويتبع لغة الصفحة افتراضيًا.
`className`	`string`	لا يوجد	أصناف (class) إضافية للمكوّن.

الاستخدام

tsx

import { Badge } from "@/components/ui/badge"
import { Avatar } from "@/components/ui/avatar"

<Badge>جديد</Badge>
<Badge variant="soft" tone="success">مدفوع</Badge>
<Badge variant="outline" tone="destructive" size="md">متأخر</Badge>

// الأيقونة والصورة الرمزية: تحدد الشارة حجمهما ولونهما
<Badge icon={<Star />}>مميّز</Badge>
<Badge avatar={<Avatar size="12" radius="rounded" src={user.photo} name="" />}>
  {user.name}
</Badge>

// قابلة للإزالة
<Badge variant="soft" onClose={() => remove(tag)} closeLabel={`إزالة عامل التصفية: ${tag}`}>
  {tag}
</Badge>