# منتقي التاريخ الهجري

> للخدمات الحكومية والتمويل الإسلامي والحج والعمرة وكل نموذج يطلب تاريخًا هجريًا. على تقويم أم القرى، والتاريخ الميلادي ظاهر بجانبه دائمًا.

الصفحة: https://ritla.app/ar/ui/hijri-date-picker

## التثبيت

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

```bash
npx ritla add hijri-date-picker
```

أو بأداة shadcn:

```bash
npx shadcn@latest add @ritla/hijri-date-picker
```

الاعتماديات: `@base-ui/react`، `@phosphor-icons/react`، `react-day-picker`

## الاستخدام

```tsx
import { HijriDateInput } from "@/components/ui/hijri-date-picker";

// Store the Gregorian day; the field shows and takes it as Umm al-Qura.
const [date, setDate] = useState<Date | null>(null);

<HijriDateInput label="Date of birth (Hijri)" value={date} onValueChange={setDate} />
```

## أمثلة

### قائمة التاريخ الهجري

كل يوم هجري ومعه اليوم الميلادي صغيرًا تحته، ومدى الشهر الميلادي تحت العنوان («من 12 سبتمبر إلى 11 أكتوبر 2026»). مفتاح «هجري / ميلادي» يبقي اليوم المختار ويغيّر الشبكة فقط. الأسبوع يبدأ بالاثنين بالإنجليزية والسبت بالعربية، كما في منتقي التاريخ.

معاينة حيّة: https://ritla.app/_kanz/preview/arabic/hijri-date-picker-menu

### تاريخ في المستقبل

حالة الخطأ: الشارة حمراء والرسالة تقول كيف يُصلح («هذا التاريخ في المستقبل. تحقّق من السنة.»).

معاينة حيّة: https://ritla.app/_kanz/preview/arabic/hijri-date-picker-error

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

### `HijriDateInput`

| الخاصية | النوع | الافتراضي | الوصف |
| --- | --- | --- | --- |
| `value / onValueChange` | `Date \| null / (value: Date \| null) => void` | لا يوجد | اليوم الميلادي (خزّنه بتاريخ ISO)؛ الحقل يعرضه ويقبله بتقويم أم القرى. `null` ما دام اليوم غير موجود (30 من شهر من 29 يومًا). |
| `label / required / error` | `ReactNode / boolean` | لا يوجد | كما في حقل الإدخال. سمِّ الحقل هجريًا («تاريخ الميلاد (هجري)»). |
| `helperText` | `ReactNode` | لا يوجد | الافتراضي اليوم والشهر الهجريان ثم التاريخ الميلادي كاملًا («17 ربيع الآخر، الاثنين 28 سبتمبر 2026»). |
| `picker` | `boolean` | `true` | زر التقويم مع قائمة التاريخ الهجري. |
| `disabled` | `boolean` | لا يوجد | State = Disabled. |

### `HijriDatePickerMenu / HijriCalendar`

| الخاصية | النوع | الافتراضي | الوصف |
| --- | --- | --- | --- |
| `value / onApply / onCancel (Menu)` | `Date / (value: Date) => void / () => void` | لا يوجد | اليوم الذي تفتح عليه، و«تطبيق» و«إلغاء». |
| `HijriCalendar` | `DayPickerProps` | لا يوجد | الشبكة الهجرية وحدها، بخصائص react-day-picker كلها كما في التقويم. |
| `toHijri / fromHijri / hijriDateLib` | `functions` | لا يوجد | التحويل بين اليوم الميلادي وتاريخ أم القرى عبر Intl، ومكتبة التواريخ التي تشغّل الشبكة. |

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

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

- `Tab`: اليوم ثم الشهر ثم السنة، ثم زر التقويم.
- `ArrowLeft` + `ArrowRight` + `ArrowUp` + `ArrowDown`: في الشبكة: يومًا أو أسبوعًا؛ في العربية السهم الأيسر هو اليوم التالي.
- `PageUp` + `PageDown`: شهرًا هجريًا.

ARIA:

- كل يوم في الشبكة زر باسم تاريخه الهجري الكامل («الاثنين، 17 ربيع الآخر 1448 هـ»)؛ اليوم الميلادي تحته للعين فقط.
- التاريخ الميلادي الكامل في النص المساعد يُقرأ مع الحقل.
- مفتاح «نوع التقويم» مجموعة أزرار تبديل باسمها.

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

ينعكس:

- الشبكة من اليمين إلى اليسار. الأجزاء: اليوم على اليمين ثم الشهر ثم السنة على اليسار، والشارة وزر التقويم على اليسار.

لا ينعكس:

- أرقام الأيام نفسها.

الأرقام: أرقام غربية افتراضيًا في اللغتين، بطلب صريح من Intl (`-nu-latn`)، والمشرقية عند `numerals="arab"`.

الخط العربي: اليوم الهجري `body-14` واليوم الميلادي تحته `label-12`، في خلية ارتفاعها 48 بكسل.

النص ثنائي الاتجاه: تقويم أم القرى عبر Intl (`islamic-umalqura`). قد يبدأ الشهر قبل يوم أو بعده بعد رؤية الهلال في بعض البلدان، والقائمة تقول ذلك. لا تخلط الهجري والميلادي في حقل واحد.