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

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

الصفحة: https://ritla.app/ar/ui/metric

## التثبيت

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

```bash
npx ritla add metric
```

أو بأداة shadcn:

```bash
npx shadcn@latest add @ritla/metric
```

الاعتماديات: `@phosphor-icons/react`

## الاستخدام

```tsx
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]} />} />
```

## أمثلة

### بطاقة المؤشر

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

معاينة حيّة: https://ritla.app/_kanz/preview/arabic/metric-cards

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

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

معاينة حيّة: https://ritla.app/_kanz/preview/arabic/metric-types

### المقياس

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

معاينة حيّة: https://ritla.app/_kanz/preview/arabic/metric-gauge

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

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

معاينة حيّة: https://ritla.app/_kanz/preview/arabic/metric-meaning

## مرجع الخصائص

### `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، فلا تنقلب علامة النسبة أو الفاصلة داخل النص العربي.