الثيم كنز

المكوّنات

النموذج

كيف تجتمع حقول كنز في نموذج: أقسام بعنوان وسبب قصير، وحقول بترتيب القراءة، وشريط إجراءات واحد واضح، ورسائل خطأ تقول كيف يُصلح الخطأ. لا مكتبة نماذج مدمجة: يعمل مع حالتك الخاصة أو مع react-hook-form وZod.

Figmaالمقابل في shadcnform

المعاينة

«معكوس» هو المحتوى الإنجليزي نفسه من اليمين إلى اليسار، ليفصل خطأ الاتجاه عن خطأ الترجمة.

التثبيت

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

npx ritla add form

ويعمل أيضًا مع shadcn: npx shadcn@latest add @ritla/form

الاعتماديات التي يضيفها: @base-ui/react, @phosphor-icons/react

التثبيت اليدوي ينسخ مصدر المكوّن إلى مشروعك. المصدر يأتي مع ترخيص Ritla UI، وأداة سطر الأوامر هي الطريق الأقصر إلى الملفات نفسها.

الاستخدام

import { Form, FormActions, FormErrorSummary, FormSection } from "@/components/ui/form";
import { Button } from "@/components/ui/button";
import { Input } from "@/components/ui/input";

<Form onSubmit={save}>
  <FormSection title="Personal details" description="We use these on receipts and transfers.">
    <FormErrorSummary errors={summary} focusKey={submitCount} />
    <Input id="email" label="Email" required type="email" error={errors.email} />
    <FormActions status="Saved 2 minutes ago">
      <Button variant="outline" size="md">Cancel</Button>
      <Button size="md" type="submit">Save changes</Button>
    </FormActions>
  </FormSection>
</Form>

أمثلة

مكدّس، مع أخطاء

layout="stacked" للجوال والنوافذ والأعمدة الضيقة، وalign="full-width" يضع «حفظ» فوق «إلغاء» بعرض كامل. بعد حفظ فشل، الملخص في الأعلى وكل حقل يعرض خطأه في مكانه. FormOptional يكتب «(اختياري)» بعد تسمية الحقل؛ علّم الحقول الاختيارية القليلة لا المطلوبة الكثيرة.

احصل على الكود ›

مع react-hook-form وZod

لفرق تستخدمهما أصلًا. كنز لا يضيف أيًا منهما: ثبّتهما بنفسك (npm install react-hook-form zod @hookform/resolvers). register يعطي كل حقل اسمه ومرجعه ومعالجاته، ورسائل المخطط تذهب إلى error وإلى الملخص، وsubmitCount يعيد التركيز إلى الملخص عند كل حفظ، وshouldFocusError: false يترك التركيز للملخص.

احصل على الكود ›

مرجع الخصائص

Form

الخاصية	النوع	الافتراضي	الوصف
`onSubmit`	`(event) => void`	لا يوجد	عند الإرسال. تحقّق من كل الحقول هنا، واعرض الملخص إن وُجدت أخطاء.
`noValidate`	`boolean`	`true`	يطفئ فقاعات الخطأ في المتصفح، فتظهر الأخطاء في حقول كنز وفي الملخص.

FormSection

الخاصية	النوع	الافتراضي	الوصف
`title`	`ReactNode`	لا يوجد	عنوان القسم («البيانات الشخصية»). القسم `<section>` باسم عنوانه.
`description`	`ReactNode`	لا يوجد	السبب القصير تحت العنوان: لماذا تطلب هذه البيانات.
`layout`	`"auto" \| "two-column" \| "stacked"`	`"auto"`	خاصية Layout: عمودان للإعدادات على سطح المكتب (السبب في جهة والحقول في الأخرى)، أو مكدّس. `auto` مكدّس تحت نقطة التوقف lg.

FormRow / FormOptional

الخاصية	النوع	الافتراضي	الوصف
`children (FormRow)`	`ReactNode`	لا يوجد	حقلان متجاوران حين تتسع المساحة (الاسم الأول واسم العائلة)، ومكدّسان على الجوال.
`FormOptional`	`component`	لا يوجد	يكتب «(اختياري)» بلغة الصفحة بعد تسمية الحقل.

FormErrorSummary

الخاصية	النوع	الافتراضي	الوصف
`errors`	`{ id, label, message }[]`	لا يوجد	حقل لكل خطأ، بترتيب النموذج. `id` معرّف عنصر الحقل، فينقل الرابط التركيز إليه. لا يظهر شيء والقائمة فارغة.
`title`	`ReactNode`	لا يوجد	العنوان. الافتراضي «صحّح الحقول التالية:» بالعربية و"Fix 2 things before you save" بالإنجليزية، بالعدد بأرقام الصفحة.
`focusKey`	`unknown`	لا يوجد	يأخذ التركيز كلما تغيّر: مرّر عدد مرات الإرسال، فيصل كل إرسال فاشل إلى الملخص، ولا يُسحب التركيز من حقل أثناء إصلاحه.
`autoFocus`	`boolean`	`true`	يأخذ التركيز حين يظهر.

FormActions

الخاصية	النوع	الافتراضي	الوصف
`children`	`ReactNode`	لا يوجد	الأزرار بترتيب القراءة: «إلغاء» (Outline) ثم «حفظ» (Filled، الزر الممتلئ الوحيد).
`status`	`ReactNode`	لا يوجد	حالة الحفظ في بداية الشريط («تم الحفظ قبل دقيقتين»)، تُعلَن دون مقاطعة (`aria-live="polite"`) حين تتغير.
`align`	`"auto" \| "end" \| "full-width"`	`"auto"`	خاصية Align: الحفظ في النهاية على سطح المكتب، أو «حفظ» فوق «إلغاء» بعرض كامل على الجوال. `auto` بعرض كامل تحت نقطة التوقف sm.

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

لوحة المفاتيح

المفاتيح مكتوبة للاتجاه من اليسار إلى اليمين. في الاتجاه من اليمين يتبادل السهمان دورهما: السهم المتجه مع اتجاه القراءة ينقلك إلى الأمام.

المفتاح	ما يفعله
`Tab`	عبر الحقول بترتيب القراءة، ثم «إلغاء» و«حفظ».
`Enter`	في حقل نصي يرسل النموذج؛ على رابط في الملخص ينقل التركيز إلى حقله.

ARIA

الملخص role="alert" ويأخذ التركيز بعد إرسال فاشل، فيصل إليه المستخدم بلوحة المفاتيح وقارئ الشاشة مباشرة؛ كل سطر فيه رابط إلى حقله.
تحقّق من الحقل حين يغادره المستخدم، لا أثناء الكتابة؛ ويختفي الخطأ فور صحة القيمة.
كل حقل بتسمية ظاهرة. النجمة زخرفة: required على الحقل هو ما يُعلَن «مطلوب».
رسالة الخطأ تسمّي الحقل والإصلاح («أدخل عنوانًا مثل name@example.com»)، لا «غير صالح» وحدها.

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

ينعكس

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

لا ينعكس

البريد الإلكتروني ورقم الهاتف والآيبان تبقى من اليسار إلى اليمين، معزولة داخل الصفحة العربية.
أيقونة التحذير لا تنعكس.

الأرقام: العدد في عنوان الملخص الافتراضي يتبع numerals، وكذلك أي رقم تكتبه في الرسائل عبر formatNumber.
الخط العربي: عنوان القسم body-18 بوزن Semibold والسبب label-14؛ الأسطر العربية أطول، فلا ارتفاعات ثابتة على النص.
النص ثنائي الاتجاه: سطر الملخص dir="auto": رسالة إنجليزية من الخادم في صفحة عربية تبقى صحيحة الترتيب.