المكوّنات
منتقي التاريخ
التاريخ يُكتب حين يعرفه الناس (تاريخ الميلاد، مستند)، ويُختار من التقويم حين يتصفحون موعدًا، والفترات تأتي بفترات جاهزة، والوقت له حقله. في العربية تنعكس الحقول والشبكة، ويبدأ الأسبوع حسب اللغة والمنطقة.
date-pickerالمعاينة
«معكوس» هو المحتوى الإنجليزي نفسه من اليمين إلى اليسار، ليفصل خطأ الاتجاه عن خطأ الترجمة.
التثبيت
npx ritla add date-pickerويعمل أيضًا مع shadcn: npx shadcn@latest add @ritla/date-picker
الاعتماديات التي يضيفها: @base-ui/react, @phosphor-icons/react, react-day-picker
التثبيت اليدوي ينسخ مصدر المكوّن إلى مشروعك. المصدر يأتي مع ترخيص Ritla UI، وأداة سطر الأوامر هي الطريق الأقصر إلى الملفات نفسها.
الاستخدام
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 يعرض العمر ليتأكد الناس من السنة. الأجزاء بترتيب المنطقة (اليوم أولًا في العربية)، وتقبل الأرقام الهندية حين تُكتب.
الوقت
TimeInput: الساعة والدقيقة، ثم ص / م، والمنطقة الزمنية حين تهم. الساعة تبقى بترتيبها في العربية: الساعة ثم الدقيقة من اليسار.
فترة بفترات جاهزة
DateRangePicker: الفترات الجاهزة التي يستخدمها الناس فعلًا، وشهران على سطح المكتب وشهر واحد على الجوال، والفترة المختارة مكتوبة بالكلمات في الحقل («من 1 إلى 15 مارس 2026»).
مرجع الخصائص
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 | من جزء إلى الجزء التالي، ثم زر التقويم. |
| ArrowUpArrowDown | يزيد الجزء أو ينقصه؛ وفي ص / م يبدّل بينهما. |
| Backspace | في جزء فارغ يعود إلى الجزء السابق. |
| Enter | على زر التقويم يفتح القائمة؛ وفي الشبكة يختار اليوم (انظر التقويم). |
| Escape | يغلق القائمة دون تغيير. |
ARIA
- الحقل مجموعة باسم تسميته، وكل جزء حقل رقمي باسمه («اليوم»، «الشهر»، «السنة»).
- الكتابة هي البديل المتاح للتقويم دائمًا؛ التقويم وحده لا يكفي.
- ص / م زر تدوير بقيمته مقروءة. شارة العمر تُقرأ «العمر 34».
- زر التقويم وأزرار الشهر والسنة بأسماء بلغة الصفحة، وقائمتا الشهور والسنوات
listbox.
ملاحظات العربية والاتجاه
ينعكس
- أجزاء التاريخ: اليوم على اليمين ثم الشهر ثم السنة على اليسار، وزر التقويم وشارة العمر على اليسار.
- قائمة الفترات الجاهزة في بداية القائمة (اليمين)، و«تطبيق» في نهاية الأزرار.
لا ينعكس
- الساعة: الساعة ثم الدقيقة من اليسار، كما على الساعة.
- أرقام كل جزء ومنطقة UTC الزمنية.
- الأرقام
- الأجزاء والشبكة وشارة العمر تتبع
numerals، والكتابة تقبل النظامين. - الخط العربي
- الأجزاء
label-16، وأزرار الشهر والسنةbody-16بوزن Semibold. - النص ثنائي الاتجاه
- لا تخلط التاريخ الهجري والميلادي في حقل واحد: للهجري منتقي التاريخ الهجري.