الثيم كنز

المكوّنات

الإحصاءات والمؤشرات

رقم أساسي مع اتجاهه: بطاقة المؤشر للوحات التحكم، وعنصر المؤشر للمربعات المدمجة، والمقياس لقيمة ضمن نطاق معروف.

المعاينة

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

التثبيت

قريبًايُفتح التثبيت من السجل قريبًا، وهذه هي الأوامر التي ستشغّلها حينها.

npx ritla add metric

ويعمل أيضًا مع shadcn: npx shadcn@latest add @ritla/metric

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

التثبيت اليدوي ينسخ مصدر المكوّن إلى مشروعك. المصدر يأتي مع ترخيص Ritla UI، وأداة سطر الأوامر هي الطريق الأقصر إلى الملفات نفسها.

الاستخدام

import { MetricItem, MetricCard, MetricBars } from "@/components/ui/metric";

<MetricItem label="Transfers this month" value="1,284" trend={{ value: "12%", direction: "up" }} />
<MetricCard title="Card spending" value="1,240" trend={{ value: "25%", direction: "up" }} period="vs last month" chart={<MetricBars data={[25, 50, 100, 75, 50, 10]} />} />

أمثلة

بطاقة المؤشر

أعمدة بجانب الرقم، أو شريط تقدم فوقه، أو مقياس صغير. الأعمدة تبقى من اليسار إلى اليمين في العربية، والتقدم يمتلئ من بداية السطر.

احصل على الكود ›

أنواع عنصر المؤشر

‏type يختار تخطيط Figma: أيقونة في مربع، أو رسم صغير بجانب الرقم أو تحته، أو شريط عنوان. والتذييل زر إعدادات وزر «عرض التقرير».

احصل على الكود ›

المقياس

قيمة واحدة ضمن نطاق معروف بمناطق جيدة وسيئة. ‏scale يحدد أي طرف هو الجيد. في العربية ينعكس القرص فيبدأ المقياس من اليمين.

احصل على الكود ›

اللون يتبع المعنى

زيادة المدفوعات الفاشلة خبر سيئ: السهم يشير للأعلى، والوسم والخط باللون الأحمر (tone: "negative").

احصل على الكود ›

مرجع الخصائص

MetricItem

الخاصية	النوع	الافتراضي	الوصف
`type`	`"simple" \| "icon-01" … "icon-04" \| "chart-01" … "chart-04"`	`"simple"`	خاصية Type: تخطيط المربع.
`label`	`ReactNode`	لا يوجد	اسم المؤشر وفترته («المشاهدات خلال 24 ساعة»).
`value`	`ReactNode`	لا يوجد	الرقم منسقًا بوحدته.
`trend`	`{ value, direction: "up" \| "down", tone? }`	لا يوجد	التغير. ‏`tone` يحدد إن كان خبرًا جيدًا (أخضر) أو سيئًا (أحمر) بحسب المعنى لا الاتجاه.
`period`	`ReactNode`	لا يوجد	فترة المقارنة بعد الاتجاه («مقارنة بالشهر الماضي»).
`icon`	`IconComponent`	لا يوجد	الأيقونة في أنواع Icon وفي Chart 02.
`iconColor`	`"brand" \| "green" \| "red" \| "amber" \| "gray"`	`"brand"`	لون الدائرة في Icon 01 و02.
`chart`	`number[]`	لا يوجد	قيم الرسم الصغير بترتيب الزمن، الأقدم أولًا.
`chartLabel`	`string`	لا يوجد	ملخص نصي للرسم؛ دونه يُخفى عن قارئ الشاشة.
`menu`	`ReactNode`	لا يوجد	زر أيقونة يفتح قائمة، في أعلى نهاية السطر.
`footer`	`ReactNode`	لا يوجد	خاصية Actions: رابط أو أزرار في التذييل.

MetricCard

الخاصية	النوع	الافتراضي	الوصف
`title`	`ReactNode`	لا يوجد	اسم المؤشر وفترته.
`value / trend / period`	`…`	لا يوجد	كما في `MetricItem`؛ الاتجاه هنا وسم.
`type`	`"bar-chart" \| "progress"`	`"bar-chart"`	خاصية Type: الرسم بجانب الرقم أو شريط تقدم فوقه.
`chart`	`ReactNode`	لا يوجد	‏`MetricBars` أو `MetricProgress` أو `MetricGauge size="sm"`.
`menu / footer`	`ReactNode`	لا يوجد	زر القائمة، والتذييل (رابط «عرض التفاصيل» عادةً).

MetricBars / MetricSparkline / MetricProgress

الخاصية	النوع	الافتراضي	الوصف
`data`	`number[]`	لا يوجد	القيم بترتيب الزمن (الأعمدة من 2 إلى 6).
`highlight`	`number`	لا يوجد	العمود البارز؛ أعلاها افتراضيًا.
`size`	`"sm" \| "md" \| "lg"`	`"lg"`	مقاس الأعمدة: ‏12 أو 16 أو 24 بكسل.
`value / max / label`	`number, number, string`	لا يوجد	في `MetricProgress`: التقدم نحو هدف، مقياس باسم.

MetricGauge

الخاصية	النوع	الافتراضي	الوصف
`value / min / max`	`number`	لا يوجد	القيمة ونطاقها المعروف.
`scale`	`"high-is-good" \| "low-is-good"`	`"high-is-good"`	خاصية Scale: أي طرف هو الجيد، فيحدد ترتيب المناطق الحمراء والخضراء.
`size`	`"md" \| "sm"`	`"md"`	‏md مع القيمة والاسم وطرفي المقياس، وsm القرص وحده داخل بطاقة.
`label`	`string`	لا يوجد	ما يقيسه، يُطبع تحت القيمة وهو اسم المقياس.
`valueText / minText / maxText`	`ReactNode`	لا يوجد	القيمة وطرفا المقياس كما تُطبع.

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

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

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

المفتاح	ما يفعله
`Tab`	إلى زر القائمة ورابط التذييل وأزراره فقط؛ الأرقام والرسوم ليست تفاعلية.

ARIA

الاتجاه يُقرأ كلمات («ارتفاع 25%»)، والسهم مخفي، فلا يُعتمد على اللون والسهم وحدهما.
الرسوم الصغيرة مخفية عن قارئ الشاشة لأن المربع يقول الرقم؛ مرّر label لتعطيها ملخصًا.
المقياس وشريط التقدم عنصرا meter بحد أدنى وأقصى وقيمة.
زر القائمة يذكر اسم المؤشر («خيارات التحويلات هذا الشهر»).

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

ينعكس

الاسم والقيمة والاتجاه على اليمين، والقائمة على اليسار.
قرص المقياس ينعكس فيبدأ من اليمين.
شريط التقدم يمتلئ من بداية السطر، أي من اليمين.

لا ينعكس

الرسوم الصغيرة والأعمدة: الزمن يسير من اليسار إلى اليمين.
أسهم الاتجاه.
الأرقام والنسب تُقرأ من اليسار إلى اليمين.

الأرقام: الأرقام كما تمرّرها؛ نسّقها بـ formatNumber لتتبع أرقام المنتج، وبالصيغة نفسها في كل البطاقات.
الخط العربي: القيمة heading-28 بوزن Semibold في العنصر وheading-42 بوزن Medium في البطاقة، والاسم body-14 أو body-16، والاتجاه body-14 Medium.
النص ثنائي الاتجاه: القيمة والنسبة معزولتان باتجاه LTR، فلا تنقلب علامة النسبة أو الفاصلة داخل النص العربي.