# عنصر جهة الاتصال

> شخص بصورته واسمه وسطر واحد من السياق، مثل البريد أو آخر ظهور. وبطاقة جهة الاتصال تضيف إجراءً واحدًا: قائمة إجراءات، أو زر اختيار، أو رابط.

الصفحة: https://ritla.app/ar/ui/contact-item

## التثبيت

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

```bash
npx ritla add contact-item
```

أو بأداة shadcn:

```bash
npx shadcn@latest add @ritla/contact-item
```

## الاستخدام

```tsx
import { ContactItem, ContactCard } from "@/components/ui/contact-item";

<ContactItem name="Layla Amiriah" supportingText="Active now" status="online" />
<ContactCard href="/contacts/layla" name="Layla Amiriah" supportingText="layla@kanz.example" action="View" />
```

## أمثلة

### بطاقات بإجراء واحد

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

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

### اختيار المستلم

‏`ContactRadioCard` داخل `RadioGroup`: البطاقة كلها تسمية زر الاختيار، والاسم والحالة يسمّيانه والنص المساعد يصفه.

معاينة حيّة: https://ritla.app/_kanz/preview/arabic/contact-item-picker

### البريد والهاتف من اليسار إلى اليمين

النص المساعد يأخذ اتجاهه من نصه. البريد يحدده بنفسه، أما رقم الهاتف فلا حروف فيه، فضعه في `<bdi dir="ltr">`.

معاينة حيّة: https://ritla.app/_kanz/preview/arabic/contact-item-ltr-details

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

### `ContactItem`

| الخاصية | النوع | الافتراضي | الوصف |
| --- | --- | --- | --- |
| `name` | `string` | لا يوجد | خاصية Name: الاسم الذي يعرفه الناس، بالخط الذي كتبه صاحبه. |
| `supportingText` | `ReactNode` | لا يوجد | خاصية Supporting text: سطر واحد مفيد، مثل البريد أو الدور أو آخر ظهور. |
| `src` | `string` | لا يوجد | صورة الشخص. دونها تظهر الأحرف الأولى من اسمه. |
| `status` | `"none" \| "online" \| "away" \| "offline" \| "verified"` | `"none"` | خاصية Status: نقطة أو شارة على الصورة، وتُقرأ كلمةً بعد الاسم. |
| `size` | `"md" \| "lg"` | `"lg"` | خاصية Size: صورة 40 أو 48 بكسل. |

### `ContactCard`

| الخاصية | النوع | الافتراضي | الوصف |
| --- | --- | --- | --- |
| `action` | `ReactNode` | لا يوجد | خاصية Action Type: زر أيقونة (Icon Button) أو كلمة قصيرة (Text)، تُنسَّق لك إن كانت نصًا. |
| `href` | `string` | لا يوجد | يجعل البطاقة كلها رابطًا واحدًا يفتح جهة الاتصال. |
| `render` | `ReactElement` | لا يوجد | رابط التوجيه (`<Link>`) بمظهر البطاقة. |
| `…` | `ContactItem props` | لا يوجد | كل خصائص `ContactItem`. |

### `ContactRadioCard`

| الخاصية | النوع | الافتراضي | الوصف |
| --- | --- | --- | --- |
| `value` | `string` | لا يوجد | قيمة هذا الشخص في `RadioGroup`. |
| `disabled` | `boolean` | لا يوجد | لا يمكن اختياره، والنصوص باللون المعطّل. |
| `…` | `ContactItem props` | لا يوجد | كل خصائص `ContactItem`. |

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

لوحة المفاتيح (المفاتيح مكتوبة للاتجاه من اليسار إلى اليمين، ويتبادل السهمان في الاتجاه من اليمين إلى اليسار):

- `Tab`: إلى البطاقة إن كانت رابطًا، أو زر الإجراء، أو مجموعة أزرار الاختيار.
- `Enter`: يفتح جهة الاتصال أو قائمة الإجراءات.
- `ArrowDown` + `ArrowUp`: بين الأشخاص في مجموعة الاختيار، ويختار من يصل إليه.

ARIA:

- الصورة زخرفية لأن الاسم ظاهر بجانبها، فلا يُقرأ الاسم مرتين.
- الحالة كلمة تُقرأ بعد الاسم («ليلى العامرية، متصل»)، لا النقطة الملوّنة وحدها.
- زر الإجراء له اسمه الخاص الذي يذكر الشخص («إجراءات أخرى لليلى»).
- في بطاقة الاختيار يسمّي الاسمُ والحالة زرَّ الاختيار، ويصفه النص المساعد.

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

ينعكس:

- الصورة والاسم يبدآن من اليمين، والإجراء في النهاية على اليسار.
- نقطة الحالة وشارة التوثيق تنتقلان إلى أسفل يسار الصورة.

لا ينعكس:

- البريد وأرقام الهاتف والحسابات في النص المساعد تبقى من اليسار إلى اليمين.
- أيقونة النقاط الثلاث وشارة التوثيق.

الأرقام: الأرقام في النصوص كما تمرّرها؛ نسّق الأوقات والأعداد بـ `formatNumber`، واترك أرقام الهاتف والحسابات كما هي.

الخط العربي: الاسم `body-18` بوزن Semibold والسطر `body-14` في الحجم الكبير، و`body-14` و`body-12` في المتوسط. النصوص تلتف بدل أن تُقص، فالاسم العربي الأطول يبقى كاملًا.

النص ثنائي الاتجاه: الاسم والنص المساعد كلٌّ معزول بـ `dir="auto"`؛ ورقم الهاتف يحتاج `<bdi dir="ltr">`.