Form

کامپوننت Form مقدار فیلدها، اعتبارسنجی و ارسال فرم را مدیریت می‌کند. برای اتصال هر input از Form.Field استفاده کن. این کامپوننت یک render function دریافت می‌کند و props لازم برای کنترل فیلد، پیام خطا و ref را به آن می‌دهد.

Import

import { Form, Input, Checkbox, Button } from "fara-ui";

Complete Example

function ProfileForm() {
  return (
    <Form
      initialValues={{ name: "", email: "" }}
      onSubmit={(values) => {
        console.log("submitted:", values);
      }}
    >
      <Form.Field name="name">
        {({ value, onChange, onBlur, ref }, error) => (
          <div>
            <label htmlFor="profile-name">نام</label>
            <Input
              id="profile-name"
              ref={ref}
              value={value}
              onChange={onChange}
              onBlur={onBlur}
              error={Boolean(error)}
            />
            {error && <small role="alert">{error}</small>}
          </div>
        )}
      </Form.Field>

      <Form.Field name="email">
        {({ value, onChange, onBlur, ref }, error) => (
          <div>
            <label htmlFor="profile-email">ایمیل</label>
            <Input
              id="profile-email"
              type="email"
              ref={ref}
              value={value}
              onChange={onChange}
              onBlur={onBlur}
              error={Boolean(error)}
            />
            {error && <small role="alert">{error}</small>}
          </div>
        )}
      </Form.Field>

      <Button type="submit">ذخیره</Button>
    </Form>
  );
}

Validation

قوانین را با rules بر اساس نام فیلد تعریف کن. اعتبارسنجی هنگام blur و submit انجام می‌شود. اگر فیلدی نامعتبر باشد، onSubmit اجرا نمی‌شود و focus روی اولین فیلد نامعتبر قرار می‌گیرد.

<Form
  initialValues={{ email: "", age: 0 }}
  rules={{
    email: {
      required: "ایمیل الزامی است",
      pattern: [/^[^\s@]+@[^\s@]+\.[^\s@]+$/, "فرمت ایمیل صحیح نیست"],
    },
    age: {
      min: [18, "سن باید حداقل ۱۸ باشد"],
      max: [120, "سن باید حداکثر ۱۲۰ باشد"],
    },
  }}
  onSubmit={(values) => console.log(values)}
>
  {/* Form.Fieldها */}
</Form>

Boolean Fields

اگر مقدار اولیه‌ی فیلد boolean باشد، Form.Field به‌جای value، propهای checked, onChange, onBlur و ref را تحویل می‌دهد:

<Form
  initialValues={{ terms: false }}
  rules={{ terms: { required: "پذیرش قوانین الزامی است" } }}
  onSubmit={(values) => console.log(values)}
>
  <Form.Field name="terms">
    {({ checked, onChange, onBlur, ref }, error) => (
      <div>
        <Checkbox
          ref={ref}
          checked={checked}
          onChange={onChange}
          onBlur={onBlur}
          label="قوانین را می‌پذیرم"
        />
        {error && <small role="alert">{error}</small>}
      </div>
    )}
  </Form.Field>
  <Button type="submit">ادامه</Button>
</Form>

برای boolean، مقدار false خالی محسوب می‌شود؛ بنابراین required برای checkbox به معنی «باید فعال باشد» است.

String and Numeric Rules

قوانین داخلی موجود:

const rules = {
  username: {
    required: "نام کاربری الزامی است",
    minLength: [3, "حداقل ۳ کاراکتر وارد کنید"],
    maxLength: [30, "حداکثر ۳۰ کاراکتر وارد کنید"],
    pattern: [/^[a-z0-9_]+$/, "فقط حروف انگلیسی، عدد و _ مجاز است"],
  },
  age: {
    min: [18, "حداقل سن ۱۸ سال است"],
    max: [120, "حداکثر سن ۱۲۰ سال است"],
  },
};

minLength, maxLength و pattern برای رشته‌ها و min و max برای عددها استفاده می‌شوند.

Custom Validation

در validate می‌توانی به مقدار همان فیلد و همه‌ی مقدارهای فرم دسترسی داشته باشی:

<Form
  initialValues={{ password: "", confirmation: "" }}
  rules={{
    confirmation: {
      validate: (value, values) =>
        value !== values.password ? "تکرار رمز عبور یکسان نیست" : undefined,
    },
  }}
  onSubmit={(values) => console.log(values)}
>
  {/* Form.Fieldهای password و confirmation */}
</Form>

Form.Field

Form.Field خودش عنصر DOM جداگانه‌ای رندر نمی‌کند؛ فقط props را به render function می‌دهد:

prop دریافتی	کاربرد
value	مقدار فیلدهای غیر boolean
checked	مقدار فیلدهای boolean
onChange	به input وصل کن
onBlur	برای اجرای اعتبارسنجی blur وصل کن
ref	برای focus خودکار روی اولین فیلد نامعتبر وصل کن

Form.Field باید داخل Form استفاده شود؛ استفاده‌ی آن خارج از Form خطا ایجاد می‌کند.

Data Attributes and Customize CSS

Form روی عنصر <form> این hook را قرار می‌دهد:

<form data-fara-form>
  <!-- فیلدهای شما -->
</form>

برای تغییر ظاهر یک فرم خاص از className استفاده کن:

<Form className="profile-form" initialValues={{ name: "" }} onSubmit={handleSubmit}>
  {/* Form.Field */}
</Form>

[data-fara-form] {
  display: grid;
  gap: 16px;
}

.profile-form {
  max-width: 480px;
}

Form.Field wrapper DOM اختصاصی ندارد؛ اگر برای یک فیلد layout یا استایل جداگانه لازم داری، داخل render function یک div قرار بده.

Props

Form

Prop	Type	Default	توضیح
initialValues	T	-	مقدار اولیه‌ی فیلدها
rules	FormRules<T>	{}	قوانین اعتبارسنجی
onSubmit	(values: T) => void	-	callback فرم معتبر
children	ReactNode	-	فیلدها و محتوای فرم
className	string	-	کلاس روی عنصر <form>

Form.Field

Prop	Type	توضیح
name	string	نام فیلد؛ باید با کلید initialValues هماهنگ باشد
children	(props, error?) => ReactNode	render function فیلد

Accessibility

• برای هر input یک label مرتبط با htmlFor قرار بده.
• پیام خطا را با role="alert" نمایش بده.
• ref دریافت‌شده از Form.Field را به input پاس بده تا focus خطای اولیه کار کند.
• برای فرم‌های فارسی، dir="rtl" را روی ریشه‌ی برنامه یا فرم قرار بده.