# التقويم

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

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

## التثبيت

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

```bash
npx ritla add calendar
```

أو بأداة shadcn:

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

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

## الاستخدام

```tsx
import { Calendar } from "@/components/ui/calendar";

const [day, setDay] = useState<Date | undefined>(new Date());

<Calendar mode="single" selected={day} onSelect={setDay} />
```

## أمثلة

### فترة

`mode="range"`: البداية ثم النهاية، والأيام بينهما بشريط فاتح. اختيار نهاية قبل البداية يبدّلهما بهدوء.

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

### أيام غير متاحة

`disabled` يعطّل الأيام التي لا تُختار (قبل أول موعد، أيام الجمعة)، و`footer` يقول السبب تحت الشبكة، فلا تعتمد الحالة على اللون وحده.

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

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

### `Calendar`

خصائص react-day-picker كلها، كما في Calendar من shadcn.

| الخاصية | النوع | الافتراضي | الوصف |
| --- | --- | --- | --- |
| `mode` | `"single" \| "range" \| "multiple"` | لا يوجد | خاصية Mode: يوم واحد أو فترة. |
| `selected / onSelect` | `Date \| DateRange` | لا يوجد | اليوم أو الفترة المختارة. |
| `month / defaultMonth / onMonthChange` | `Date` | لا يوجد | الشهر المعروض. افتح على أول شهر متاح، لا شهرًا فارغًا. |
| `disabled` | `Matcher \| Matcher[]` | لا يوجد | الأيام التي لا تُختار؛ قل السبب في `footer`. |
| `weekStartsOn` | `0 to 6` | لا يوجد | الافتراضي من اللغة والمنطقة: الاثنين بالإنجليزية والسبت بالعربية، والأحد في ar-SA والاثنين في ar-AE. |
| `numberOfMonths` | `number` | `1` | شهران على سطح المكتب للفترات. |
| `framed` | `boolean` | `true` | لوحة Figma (إطار رمادي، زوايا 12، حشوة 16). أطفئها داخل قائمة لها لوحتها. |
| `numerals` | `"latn" \| "arab"` | لا يوجد | الافتراضي من `KanzProvider`. |

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

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

- `ArrowLeft` + `ArrowRight`: يومًا للسابق أو التالي؛ في العربية السهم الأيسر هو اليوم التالي.
- `ArrowUp` + `ArrowDown`: أسبوعًا.
- `PageUp` + `PageDown`: شهرًا؛ ومع Shift سنة.
- `Home` + `End`: طرفا الأسبوع.
- `Enter` + `Space`: يختار اليوم.

ARIA:

- الشبكة `role="grid"` باسم الشهر، وكل يوم زر باسمه الكامل («الخميس، 17 سبتمبر 2026»)، مع «اليوم» و«محدد» حين يصح.
- اسم الشهر في منطقة حيّة (`aria-live="polite"`)، فيُعلَن حين يتغير.
- زرّا الشهر السابق والتالي باسميهما بلغة الصفحة، ومساحة لمس 48 بكسل.

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

ينعكس:

- الشبكة: أول أيام الأسبوع على اليمين.
- «الشهر السابق» في بداية السطر (اليمين) ويشير إلى اليمين، و«الشهر التالي» على اليسار.
- شريط الفترة يمتد من اليمين إلى اليسار.

لا ينعكس:

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

الأرقام: أرقام الأيام والسنة تتبع `numerals`.

الخط العربي: الأيام `body-14` والعنوان `label-16` بوزن Semibold. أسماء الأيام العربية من Intl بلا «ال» («سبت») و`label-12`، لتتسع لعمود 44 بكسل.

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