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

> التاريخ يُكتب حين يعرفه الناس (تاريخ الميلاد، مستند)، ويُختار من التقويم حين يتصفحون موعدًا، والفترات تأتي بفترات جاهزة، والوقت له حقله. في العربية تنعكس الحقول والشبكة، ويبدأ الأسبوع حسب اللغة والمنطقة.

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

## التثبيت

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

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

أو بأداة shadcn:

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

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

## الاستخدام

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

const [date, setDate] = useState<Date | null>(null);

<DateInput label="Transfer date" value={date} onValueChange={setDate} />
```

## أمثلة

### تاريخ يعرفه الناس

تاريخ الميلاد يُكتب ولا يُتصفح: `picker={false}` يزيل زر التقويم، و`showAge` يعرض العمر ليتأكد الناس من السنة. الأجزاء بترتيب المنطقة (اليوم أولًا في العربية)، وتقبل الأرقام الهندية حين تُكتب.

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

### الوقت

`TimeInput`: الساعة والدقيقة، ثم ص / م، والمنطقة الزمنية حين تهم. الساعة تبقى بترتيبها في العربية: الساعة ثم الدقيقة من اليسار.

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

### فترة بفترات جاهزة

`DateRangePicker`: الفترات الجاهزة التي يستخدمها الناس فعلًا، وشهران على سطح المكتب وشهر واحد على الجوال، والفترة المختارة مكتوبة بالكلمات في الحقل («من 1 إلى 15 مارس 2026»).

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

### قائمة منتقي التاريخ

`DatePickerMenu` وحدها: زرّا الشهر والسنة يفتحان قائمتيهما، ثم «إلغاء» و«تطبيق». ضعها في نافذة منبثقة أو حوار أو ورقة سفلية حسب الشاشة.

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

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

### `DateInput`

| الخاصية | النوع | الافتراضي | الوصف |
| --- | --- | --- | --- |
| `value / onValueChange` | `Date \| null / (value: Date \| null) => void` | لا يوجد | تاريخ كامل، أو `null` ما دام فارغًا أو غير صحيح (31 فبراير ليس تاريخًا). |
| `label / required / helperText / error` | `ReactNode / boolean` | لا يوجد | كما في حقل الإدخال. قل الصيغة في النص المساعد حين قد تُقرأ خطأ. |
| `showAge` | `boolean` | `false` | شارة العمر في Figma لتاريخ الميلاد. |
| `picker` | `boolean` | `true` | زر التقويم الذي يفتح قائمة منتقي التاريخ. |
| `min / max` | `Date` | لا يوجد | أول تاريخ وآخر تاريخ تعرضهما القائمة. |
| `order` | `("day" \| "month" \| "year")[]` | لا يوجد | الافتراضي ترتيب المنطقة: اليوم أولًا في العربية، والشهر أولًا في en-US. |
| `disabled / readOnly` | `boolean` | لا يوجد | خاصية State. |

### `TimeInput`

| الخاصية | النوع | الافتراضي | الوصف |
| --- | --- | --- | --- |
| `value / onValueChange` | `{ hours, minutes } \| null` | لا يوجد | الساعات من 0 إلى 23. |
| `hourCycle` | `"h12" \| "h23"` | `"h12"` | 12 ساعة مع ص / م، أو 24 ساعة. |
| `timeZone` | `ReactNode` | لا يوجد | المنطقة الزمنية في نهاية الحقل حين تهم («UTC +03:00»). |

### `DatePicker / DatePickerMenu`

| الخاصية | النوع | الافتراضي | الوصف |
| --- | --- | --- | --- |
| `trigger (DatePicker)` | `ReactElement` | لا يوجد | العنصر الذي يفتح القائمة في نافذة منبثقة. |
| `value / onApply / onCancel (Menu)` | `Date / (value: Date) => void / () => void` | لا يوجد | اليوم الذي تفتح عليه القائمة، و«تطبيق» و«إلغاء». |
| `fromYear / toYear (Menu)` | `number` | لا يوجد | مدى قائمة السنوات. |

### `DateRangePicker / DateRangeMenu`

| الخاصية | النوع | الافتراضي | الوصف |
| --- | --- | --- | --- |
| `value / onValueChange` | `DateRange` | لا يوجد | الفترة `{ from, to }`. |
| `presets` | `{ label, range }[]` | لا يوجد | الافتراضي ثماني فترات Figma: اليوم، أمس، هذا الأسبوع، الأسبوع الماضي، هذا الشهر، الشهر الماضي، هذه السنة، السنة الماضية. |
| `numberOfMonths (Menu)` | `1 \| 2` | `2` | شهران على سطح المكتب، وشهر على الجوال. |

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

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

- `Tab`: من جزء إلى الجزء التالي، ثم زر التقويم.
- `ArrowUp` + `ArrowDown`: يزيد الجزء أو ينقصه؛ وفي ص / م يبدّل بينهما.
- `Backspace`: في جزء فارغ يعود إلى الجزء السابق.
- `Enter`: على زر التقويم يفتح القائمة؛ وفي الشبكة يختار اليوم (انظر التقويم).
- `Escape`: يغلق القائمة دون تغيير.

ARIA:

- الحقل مجموعة باسم تسميته، وكل جزء حقل رقمي باسمه («اليوم»، «الشهر»، «السنة»).
- الكتابة هي البديل المتاح للتقويم دائمًا؛ التقويم وحده لا يكفي.
- ص / م زر تدوير بقيمته مقروءة. شارة العمر تُقرأ «العمر 34».
- زر التقويم وأزرار الشهر والسنة بأسماء بلغة الصفحة، وقائمتا الشهور والسنوات `listbox`.

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

ينعكس:

- أجزاء التاريخ: اليوم على اليمين ثم الشهر ثم السنة على اليسار، وزر التقويم وشارة العمر على اليسار.
- قائمة الفترات الجاهزة في بداية القائمة (اليمين)، و«تطبيق» في نهاية الأزرار.

لا ينعكس:

- الساعة: الساعة ثم الدقيقة من اليسار، كما على الساعة.
- أرقام كل جزء ومنطقة UTC الزمنية.

الأرقام: الأجزاء والشبكة وشارة العمر تتبع `numerals`، والكتابة تقبل النظامين.

الخط العربي: الأجزاء `label-16`، وأزرار الشهر والسنة `body-16` بوزن Semibold.

النص ثنائي الاتجاه: لا تخلط التاريخ الهجري والميلادي في حقل واحد: للهجري منتقي التاريخ الهجري.