react-dynamic-form-builder-reactquery/COMPLETE_GUIDE.md

A flexible and powerful dynamic form builder for React with Ant Design - 23 components, responsive layout, React Query integration, field dependencies, conditional fields, full TypeScript support

# 📖 React Dynamic Form Builder - სრული გზამკვლევი

## 📦 პაკეტის სრული სტრუქტურა

```
@ladojibladze/react-dynamic-form-builder
│
├── 🎯 DynamicForm               # მთავარი დინამიური ფორმის კომპონენტი
│
├── 📝 Form Input Components (13)
│   ├── MyInput                  # ტექსტური ველი
│   ├── MyTextArea              # მრავალხაზიანი ტექსტი
│   ├── MySelect                # სელექტი (single/multiple)
│   ├── MyCascader              # იერარქიული სელექტი
│   ├── MyDatePicker            # თარიღის არჩევა
│   ├── MyRangePicker           # თარიღების დიაპაზონი
│   ├── MyTimePicker            # დროის არჩევა
│   ├── MyTimeRangePicker       # დროის დიაპაზონი
│   ├── MyCheckbox              # ჩეკბოქსები
│   ├── MyRadio                 # რადიო ღილაკები
│   ├── MySwitch                # გადამრთველი
│   ├── MySlider                # სლაიდერი
│   ├── MyRate                  # შეფასება (ვარსკვლავები)
│   └── MyUpload                # ფაილების ატვირთვა
│
├── 🎨 UI Components (8)
│   ├── MyButton                # ღილაკი (gradient, shadow)
│   ├── MyCard                  # ბარათი (elevated, bordered)
│   ├── MyModal                 # მოდალური ფანჯარა
│   ├── MyDrawer                # გამოსაწევი პანელი
│   ├── MyPopover               # Popover
│   ├── MyTable                 # ცხრილი
│   ├── MyCollapse              # Collapse პანელები
│   ├── MyForm                  # ფორმის wrapper
│   └── MyFormItem              # ფორმის ელემენტის wrapper
│
└── 🔧 Utilities (3)
    ├── useFieldDependencies    # ველების დამოკიდებულებები
    ├── useFormDirty            # ცვლილებების თრექინგი
    └── useConditionalFields    # პირობითი ველები

**სულ: 22 კომპონენტი + 3 utility hook**
```

---

## 🎯 DynamicForm - როგორ მუშაობს?

### 📋 კონფიგურაციის სტრუქტურა

```typescript
import { DynamicForm, FormConfig } from '@ladojibladze/react-dynamic-form-builder';

const formConfig: FormConfig = {
  // 1. ველების განსაზღვრა
  fields: [
    {
      name: 'username',
      type: 'input',
      label: 'სახელი',
      rules: [{ required: true }],
      span: { xs: 24, md: 12 }  // Responsive!
    }
  ],

  // 2. ან სექციებად დაყოფა
  sections: [
    {
      title: 'პირადი ინფორმაცია',
      description: 'შეავსეთ პირადი მონაცემები',
      collapsible: true,
      fields: [...]
    }
  ],

  // 3. ფორმის პარამეტრები
  layout: 'vertical',        // 'horizontal' | 'vertical' | 'inline'
  columns: 2,                // სვეტების რაოდენობა
  submitText: 'გაგზავნა',
  showReset: true
};
```

### 🔄 CRUD Modes

```typescript
// CREATE MODE
<DynamicForm
  mode="create"
  config={formConfig}
  onSubmit={handleCreate}
/>

// EDIT MODE
<DynamicForm
  mode="edit"
  initialValues={existingData}
  config={formConfig}
  onSubmit={handleUpdate}
/>

// VIEW MODE (Readonly)
<DynamicForm
  mode="view"
  initialValues={data}
  config={formConfig}
/>
```

### 📊 isDirty Tracking

```typescript
const [isDirty, setIsDirty] = useState(false);

<DynamicForm
  config={formConfig}
  initialValues={data}
  onDirtyChange={setIsDirty}  // მოიძებნება ცვლილებები
  onSubmit={handleSubmit}
/>

// ახლა შეგიძლიათ გამოიყენოთ isDirty
{isDirty && <div>გაქვთ შეუნახავი ცვლილებები!</div>}
```

---

## 📱 Responsive Grid System (24-Column)

### Breakpoints

| Breakpoint | ზომა | მოწყობილობა | გამოყენება |
|-----------|------|------------|-----------|
| **xs** | <576px | Mobile | span: 24 (სრული) |
| **sm** | ≥576px | Tablet | span: 12 (ნახევარი) |
| **md** | ≥768px | Tablet | span: 12, 8 |
| **lg** | ≥992px | Desktop | span: 8, 6 |
| **xl** | ≥1200px | Desktop+ | span: 6, 4 |
| **xxl** | ≥1600px | 4K | span: 4, 3 |

### Mobile-First Example

```typescript
const config = {
  fields: [
    {
      name: 'firstName',
      type: 'input',
      // Mobile: სრული სიგანე
      // Tablet: ნახევარი
      // Desktop: მესამედი
      span: { xs: 24, sm: 12, lg: 8 }
    },
    {
      name: 'lastName',
      type: 'input',
      span: { xs: 24, sm: 12, lg: 8 }
    },
    {
      name: 'email',
      type: 'input',
      span: { xs: 24, sm: 24, lg: 8 }  // Tablet-ზე სრული
    }
  ]
}
```

### Advanced Layout

```typescript
{
  name: 'field',
  span: { xs: 24, lg: 12 },      // სიგანე
  offset: { lg: 6 },              // ცარიელი ადგილი მარცხნიდან
  push: { md: 2 },                // გადაადგილება მარჯვნივ
  pull: { md: 2 },                // გადაადგილება მარცხნივ
  style: { padding: '10px' },     // Custom style
  formItemStyle: { marginBottom: '20px' }
}
```

---

## 🔗 Field Dependencies (დამოკიდებული ველები)

### Simple Dependency

```typescript
{
  fields: [
    {
      name: 'country',
      type: 'select',
      options: [
        { label: 'საქართველო', value: 'ge' },
        { label: 'USA', value: 'us' }
      ]
    },
    {
      name: 'city',
      type: 'select',
      dependsOn: 'country',  // დამოკიდებულია country-ზე
      dependencies: [{
        field: 'country',
        getOptions: (countryValue) => {
          if (countryValue === 'ge') {
            return [
              { label: 'თბილისი', value: 'tbilisi' },
              { label: 'ბათუმი', value: 'batumi' }
            ];
          }
          return [
            { label: 'New York', value: 'ny' },
            { label: 'LA', value: 'la' }
          ];
        }
      }]
    }
  ]
}
```

### Multi-level Cascader (Backend Integration)

```typescript
{
  name: 'location',
  type: 'cascader',
  cascaderOptions: await fetchLocations(),
  dependencies: [{
    loadData: async (selectedOptions) => {
      const targetOption = selectedOptions[selectedOptions.length - 1];
      targetOption.loading = true;

      // Backend-დან მონაცემების მიღება
      const children = await api.getSubLocations(targetOption.value);
      targetOption.children = children;
      targetOption.loading = false;
    }
  }]
}
```

---

## 🎭 Conditional Fields (პირობითი ველები)

### Simple Condition

```typescript
{
  name: 'hasVehicle',
  type: 'radio',
  options: [
    { label: 'დიახ', value: 'yes' },
    { label: 'არა', value: 'no' }
  ],
  conditionalFields: [
    {
      when: 'hasVehicle',     // როდესაც hasVehicle
      is: ['yes'],             // არის 'yes'
      fields: [                // გამოჩნდეს ეს ველები
        {
          name: 'vehicleType',
          type: 'select',
          options: [
            { label: 'მანქანა', value: 'car' },
            { label: 'მოტოციკლი', value: 'moto' }
          ]
        }
      ]
    }
  ]
}
```

### Nested Conditions

```typescript
{
  name: 'employmentStatus',
  type: 'select',
  options: [
    { label: 'დასაქმებული', value: 'employed' },
    { label: 'სტუდენტი', value: 'student' }
  ],
  conditionalFields: [
    {
      when: 'employmentStatus',
      is: 'employed',
      fields: [
        {
          name: 'companyName',
          type: 'input',
          // Nested condition!
          conditionalFields: [{
            when: 'companyName',
            condition: (value) => value?.length > 0,
            fields: [
              { name: 'position', type: 'input' },
              { name: 'salary', type: 'number' }
            ]
          }]
        }
      ]
    }
  ]
}
```

---

## ✅ Validation System

### Built-in Rules

```typescript
{
  name: 'email',
  type: 'email',
  rules: [
    { required: true, message: 'ელ-ფოსტა სავალდებულოა' },
    { type: 'email', message: 'არასწორი ფორმატი' },
    {
      pattern: /^[^\s@]+@[^\s@]+\.[^\s@]+$/,
      message: 'გთხოვთ შეიყვანოთ სწორი ელ-ფოსტა'
    }
  ]
}
```

### Custom Validation

```typescript
{
  name: 'password',
  type: 'password',
  rules: [
    {
      validator: async (_, value) => {
        if (!value) {
          return Promise.reject('პაროლი სავალდებულოა');
        }
        if (value.length < 8) {
          return Promise.reject('მინიმუმ 8 სიმბოლო');
        }
        if (!/[A-Z]/.test(value)) {
          return Promise.reject('უნდა შეიცავდეს დიდ ასოს');
        }
        return Promise.resolve();
      }
    }
  ]
}
```

### Async Validation

```typescript
{
  name: 'username',
  type: 'input',
  rules: [
    {
      validator: async (_, value) => {
        const available = await api.checkUsername(value);
        if (!available) {
          return Promise.reject('ეს სახელი უკვე დაკავებულია');
        }
        return Promise.resolve();
      }
    }
  ]
}
```

---

## 🎨 CSS Customization - როგორ მოვარგოთ სტილი?

### 1. CSS Classes

ყველა კომპონენტს აქვს className prop და სპეციალური კლასები:

```css
/* FormField tooltips */
.form-field-tooltip-icon {
  color: #888;
  font-size: 14px;
}

/* DynamicForm sections */
.dynamic-form-section {
  margin-bottom: 24px;
}

.dynamic-form-section-title {
  margin-bottom: 16px;
  font-size: 18px;
  font-weight: 600;
}

.dynamic-form-section-description {
  color: #888;
  margin-bottom: 16px;
}

.dynamic-form-section-collapse {
  margin-bottom: 16px;
}

/* Form actions */
.dynamic-form-actions {
  margin-top: 24px;
  margin-bottom: 0;
}
```

### 2. SCSS Support

```scss
.my-form {
  .dynamic-form-section {
    &-title {
      color: $primary-color;
      border-bottom: 2px solid $border-color;
      padding-bottom: 10px;
    }

    &-description {
      font-style: italic;
      color: lighten($text-color, 20%);
    }
  }
}
```

### 3. Tailwind CSS

```typescript
<DynamicForm
  className="space-y-4 p-6 bg-white rounded-lg shadow-lg"
  config={{
    fields: [
      {
        name: 'name',
        type: 'input',
        className: 'mb-4',
        formItemStyle: { marginBottom: 0 }
      }
    ]
  }}
/>
```

### 4. CSS-in-JS (Styled Components)

```typescript
import styled from 'styled-components';

const StyledForm = styled.div`
  .dynamic-form-section {
    background: #f5f5f5;
    padding: 20px;
    border-radius: 8px;
    margin-bottom: 20px;
  }

  .form-field-tooltip-icon {
    color: ${props => props.theme.primary};
  }
`;

<StyledForm>
  <DynamicForm config={config} />
</StyledForm>
```

### 5. Per-Field Styling

```typescript
{
  name: 'field',
  type: 'input',
  style: {                    // Col wrapper style
    padding: '0 10px'
  },
  formItemStyle: {            // Form.Item style
    marginBottom: '30px',
    '.ant-form-item-label': {
      fontWeight: 'bold'
    }
  },
  className: 'custom-field',  // Custom class
  componentProps: {           // Input component style
    style: {
      borderRadius: '8px',
      border: '2px solid #1890ff'
    }
  }
}
```

---

## 📝 Form Input Components - დეტალური გზამკვლევი

### 1. MyInput

```typescript
import { MyInput } from '@ladojibladze/react-dynamic-form-builder';

<MyInput
  value={value}
  onChange={setValue}
  type="text"          // 'text' | 'password' | 'email' | 'number' | 'phone'
  placeholder="შეიყვანეთ ტექსტი"
  disabled={false}
  readonly={false}
  maxLength={100}
  prefix={<UserOutlined />}
  suffix={<CheckCircleOutlined />}
  addonBefore="https://"
  addonAfter=".com"
  allowClear
/>
```

**DynamicForm-ში:**
```typescript
{
  name: 'website',
  type: 'input',
  componentProps: {
    addonBefore: 'https://',
    addonAfter: '.com',
    placeholder: 'mysite'
  }
}
```

### 2. MySelect

```typescript
<MySelect
  value={value}
  onChange={setValue}
  options={[
    { label: 'Option 1', value: '1' },
    { label: 'Option 2', value: '2', disabled: true }
  ]}
  mode="multiple"      // undefined | 'multiple' | 'tags'
  showSearch
  allowClear
  placeholder="აირჩიეთ..."
  loading={false}
  filterOption={(input, option) =>
    option?.label.toLowerCase().includes(input.toLowerCase())
  }
/>
```

### 3. MyCascader (Multi-Level)

```typescript
<MyCascader
  value={value}
  onChange={setValue}
  options={[
    {
      label: 'საქართველო',
      value: 'ge',
      children: [
        {
          label: 'თბილისი',
          value: 'tbilisi',
          children: [
            { label: 'ვაკე', value: 'vake' },
            { label: 'საბურთალო', value: 'saburtalo' }
          ]
        }
      ]
    }
  ]}
  multiple={false}
  showSearch
  changeOnSelect        // გამოჩნდეს შუალედური არჩევანი
  expandTrigger="hover" // 'click' | 'hover'
  loadData={async (selectedOptions) => {
    // Dynamic load from backend
  }}
/>
```

### 4. MyDatePicker & MyRangePicker

```typescript
<MyDatePicker
  value={date}
  onChange={setDate}
  format="YYYY-MM-DD"
  showTime={{ format: 'HH:mm' }}
  picker="date"         // 'date' | 'week' | 'month' | 'quarter' | 'year'
  disabledDate={(current) => current && current < dayjs()}
/>

<MyRangePicker
  value={[startDate, endDate]}
  onChange={setDates}
  format="YYYY-MM-DD HH:mm"
  showTime
/>
```

### 5. MyTimePicker

```typescript
<MyTimePicker
  value={time}
  onChange={setTime}
  format="HH:mm:ss"
  use12Hours={false}
  showNow
  hourStep={1}
  minuteStep={15}
  secondStep={30}
/>
```

### 6. MyCheckbox & MyRadio

```typescript
<MyCheckbox
  value={['option1', 'option3']}
  onChange={setValue}
  options={[
    { label: 'Option 1', value: 'option1' },
    { label: 'Option 2', value: 'option2', disabled: true },
    { label: 'Option 3', value: 'option3' }
  ]}
/>

<MyRadio
  value="yes"
  onChange={setValue}
  options={[
    { label: 'დიახ', value: 'yes' },
    { label: 'არა', value: 'no' }
  ]}
  optionType="button"   // 'default' | 'button'
  buttonStyle="solid"   // 'outline' | 'solid'
/>
```

### 7. MySlider

```typescript
<MySlider
  value={50}
  onChange={setValue}
  min={0}
  max={100}
  step={10}
  marks={{
    0: '0°C',
    25: '25°C',
    50: '50°C',
    75: '75°C',
    100: '100°C'
  }}
  range           // Range slider
  vertical        // Vertical orientation
  tooltipVisible  // Always show tooltip
/>
```

### 8. MyRate

```typescript
<MyRate
  value={4.5}
  onChange={setValue}
  count={5}
  allowHalf
  allowClear
  character={<HeartOutlined />}  // Custom icon
  tooltips={['terrible', 'bad', 'normal', 'good', 'wonderful']}
/>
```

### 9. MyUpload

```typescript
<MyUpload
  value={fileList}
  onChange={setFileList}
  uploadType="dragger"    // 'button' | 'dragger' | 'avatar'
  maxCount={5}
  accept="image/*"
  listType="picture-card" // 'text' | 'picture' | 'picture-card'
  beforeUpload={(file) => {
    const isJpgOrPng = file.type === 'image/jpeg' || file.type === 'image/png';
    if (!isJpgOrPng) {
      message.error('მხოლოდ JPG/PNG ფაილები!');
    }
    return isJpgOrPng;
  }}
  customRequest={async ({ file, onSuccess, onError }) => {
    try {
      const url = await uploadToServer(file);
      onSuccess({ url });
    } catch (error) {
      onError(error);
    }
  }}
/>
```

---

## 🎨 UI Components - დეტალური გზამკვლევი

### 1. MyButton

```typescript
<MyButton
  buttonVariant="primary"  // 'primary' | 'secondary' | 'success' | 'danger' | 'warning' | 'info'
  gradient                 // Gradient background
  rounded                  // Rounded corners
  shadow                   // Box shadow
  type="primary"           // Ant Design type
  size="large"            // 'small' | 'middle' | 'large'
  loading={isLoading}
  disabled={false}
  icon={<SearchOutlined />}
  onClick={handleClick}
>
  ძებნა
</MyButton>
```

**Gradient ვარიანტები:**
- `primary`: Blue gradient
- `success`: Green gradient
- `danger`: Red gradient
- `warning`: Orange gradient

### 2. MyCard

```typescript
<MyCard
  cardVariant="elevated"   // 'default' | 'bordered' | 'elevated' | 'gradient'
  shadow="lg"              // 'none' | 'sm' | 'md' | 'lg' | 'xl'
  title="ბარათის სათაური"
  extra={<a href="#">More</a>}
  hoverable                // Hover effect
  bordered={false}
  style={{ width: 300 }}
>
  <p>ბარათის შიგთავსი</p>
</MyCard>
```

### 3. MyModal

```typescript
const [open, setOpen] = useState(false);

<MyModal
  open={open}
  onOk={() => {
    // Handle OK
    setOpen(false);
  }}
  onCancel={() => setOpen(false)}
  title="მოდალური ფანჯარა"
  width={600}
  centered
  footer={[
    <MyButton key="back" onClick={() => setOpen(false)}>
      გაუქმება
    </MyButton>,
    <MyButton key="submit" buttonVariant="primary" onClick={handleOk}>
      დადასტურება
    </MyButton>
  ]}
>
  <p>შიგთავსი</p>
</MyModal>
```

### 4. MyDrawer

```typescript
<MyDrawer
  open={open}
  onClose={() => setOpen(false)}
  title="გამოსაწევი პანელი"
  placement="right"    // 'left' | 'right' | 'top' | 'bottom'
  width={400}
  extra={
    <Space>
      <MyButton onClick={() => setOpen(false)}>დახურვა</MyButton>
      <MyButton buttonVariant="primary">შენახვა</MyButton>
    </Space>
  }
>
  <p>პანელის შიგთავსი</p>
</MyDrawer>
```

### 5. MyCollapse

```typescript
// Option 1: Using panels prop
<MyCollapse
  panels={[
    {
      key: '1',
      header: 'პანელი 1',
      children: <p>შიგთავსი 1</p>
    },
    {
      key: '2',
      header: 'პანელი 2',
      children: <p>შიგთავსი 2</p>,
      disabled: true
    }
  ]}
  defaultActiveKey={['1']}
  accordion          // Only one panel open at a time
  ghost              // Borderless style
/>

// Option 2: Using children
<MyCollapse defaultActiveKey={['1']}>
  <MyCollapse.Panel key="1" header="პანელი 1">
    <p>შიგთავსი 1</p>
  </MyCollapse.Panel>
  <MyCollapse.Panel key="2" header="პანელი 2">
    <p>შიგთავსი 2</p>
  </MyCollapse.Panel>
</MyCollapse>
```

### 6. MyTable

```typescript
interface DataType {
  key: string;
  name: string;
  age: number;
  address: string;
}

<MyTable<DataType>
  dataSource={data}
  columns={[
    {
      title: 'სახელი',
      dataIndex: 'name',
      key: 'name',
      sorter: (a, b) => a.name.localeCompare(b.name),
      filters: [
        { text: 'Joe', value: 'Joe' },
        { text: 'Jim', value: 'Jim' }
      ],
      onFilter: (value, record) => record.name.indexOf(value as string) === 0
    },
    {
      title: 'ასაკი',
      dataIndex: 'age',
      key: 'age'
    }
  ]}
  tableVariant="striped"  // 'default' | 'bordered' | 'striped' | 'compact'
  pagination={{
    pageSize: 10,
    showSizeChanger: true,
    showTotal: (total) => `სულ: ${total}`
  }}
  rowSelection={{
    type: 'checkbox',
    onChange: (selectedRowKeys, selectedRows) => {
      console.log(selectedRows);
    }
  }}
/>
```

### 7. MyForm & MyFormItem

```typescript
import { MyForm, MyFormItem, MyInput, MyButton } from '@ladojibladze/react-dynamic-form-builder';

const [form] = MyForm.useForm();

<MyForm
  form={form}
  layout="vertical"
  onFinish={handleSubmit}
  initialValues={{ username: 'admin' }}
>
  <MyFormItem
    name="username"
    label="მომხმარებელი"
    rules={[{ required: true }]}
  >
    <MyInput placeholder="შეიყვანეთ სახელი" />
  </MyFormItem>

  <MyFormItem
    name="email"
    label="ელ-ფოსტა"
    rules={[
      { required: true },
      { type: 'email' }
    ]}
  >
    <MyInput type="email" />
  </MyFormItem>

  <MyFormItem>
    <MyButton
      type="primary"
      htmlType="submit"
      buttonVariant="primary"
      gradient
    >
      გაგზავნა
    </MyButton>
  </MyFormItem>
</MyForm>
```

---

## 🔧 Utility Hooks

### 1. useFormDirty

```typescript
import { useFormDirty } from '@ladojibladze/react-dynamic-form-builder';

const MyComponent = () => {
  const [form] = Form.useForm();
  const initialValues = { name: 'John' };

  const { isDirty, checkDirtyState, resetDirtyState } = useFormDirty(
    form,
    initialValues,
    (dirty) => {
      console.log('Form dirty state changed:', dirty);
    }
  );

  return (
    <>
      <Form form={form} initialValues={initialValues}>
        {/* fields */}
      </Form>
      {isDirty && <Alert message="გაქვთ შეუნახავი ცვლილებები" />}
    </>
  );
};
```

### 2. useFieldDependencies

```typescript
import { useFieldDependencies } from '@ladojibladze/react-dynamic-form-builder';

const { dependentOptions, loadingFields, handleDependencyChange } = useFieldDependencies(
  form,
  fields
);

// dependentOptions - დინამიურად დატვირთული ოფშენები
// loadingFields - loading state თითოეული ველისთვის
// handleDependencyChange - მანუალური დამოკიდებულების მართვა
```

### 3. useConditionalFields

```typescript
import { useConditionalFields } from '@ladojibladze/react-dynamic-form-builder';

const allFields = useConditionalFields(
  baseFields,      // ძირითადი ველები
  formValues,      // ფორმის მიმდინარე მნიშვნელობები
  5                // max depth (circular reference protection)
);

// allFields - შეიცავს ძირითად და პირობით ველებს
```

---

## 🚀 Advanced Use Cases

### 1. Multi-Step Form

```typescript
const [step, setStep] = useState(0);

const steps = [
  {
    title: 'პირადი ინფორმაცია',
    fields: [
      { name: 'firstName', type: 'input' },
      { name: 'lastName', type: 'input' }
    ]
  },
  {
    title: 'საკონტაქტო',
    fields: [
      { name: 'email', type: 'email' },
      { name: 'phone', type: 'phone' }
    ]
  }
];

<Steps current={step}>
  {steps.map((s, i) => <Step key={i} title={s.title} />)}
</Steps>

<DynamicForm
  config={{ fields: steps[step].fields }}
  onSubmit={(values) => {
    if (step < steps.length - 1) {
      setStep(step + 1);
    } else {
      // Final submit
    }
  }}
/>
```

### 2. Form Builder UI

```typescript
const [fields, setFields] = useState<FieldConfig[]>([]);

const addField = (type: FieldType) => {
  setFields([...fields, {
    name: `field_${Date.now()}`,
    type,
    label: `New ${type} field`
  }]);
};

<div>
  <MyButton onClick={() => addField('input')}>Add Input</MyButton>
  <MyButton onClick={() => addField('select')}>Add Select</MyButton>

  <DynamicForm
    config={{ fields }}
    mode="create"
  />
</div>
```

### 3. Backend Integration

```typescript
const formConfig: FormConfig = {
  fields: [
    {
      name: 'category',
      type: 'select',
      dependencies: [{
        field: 'category',
        getOptions: async (value) => {
          const response = await api.getSubcategories(value);
          return response.data;
        }
      }]
    }
  ]
};

<DynamicForm
  config={formConfig}
  onSubmit={async (values) => {
    try {
      await api.createItem(values);
      message.success('შენახულია!');
    } catch (error) {
      message.error('შეცდომა!');
    }
  }}
/>
```

---

## 📦 Installation & Setup

```bash
npm install @ladojibladze/react-dynamic-form-builder
npm install react react-dom antd
```

```typescript
import '@ladojibladze/react-dynamic-form-builder/dist/style.css'; // თუ არის
import 'antd/dist/reset.css'; // Ant Design styles

import {
  DynamicForm,
  MyButton,
  MyCard,
  // ... other components
} from '@ladojibladze/react-dynamic-form-builder';
```

---

## 🎯 Best Practices

### 1. Performance

```typescript
// ✅ კარგი - useMemo for config
const formConfig = useMemo(() => ({
  fields: [...]
}), [dependencies]);

// ❌ ცუდი - config ქმნის ყოველ render-ზე
const formConfig = {
  fields: [...]
};
```

### 2. TypeScript

```typescript
// ✅ კარგი - Type safety
import { FormConfig, FieldConfig } from '@ladojibladze/react-dynamic-form-builder';

const config: FormConfig = {
  fields: [
    { name: 'test', type: 'input' } as FieldConfig
  ]
};
```

### 3. Error Handling

```typescript
<DynamicForm
  config={config}
  onSubmit={handleSubmit}
  onValidationFail={(errors) => {
    console.error('Validation errors:', errors);
    message.error('გთხოვთ შეავსოთ ყველა სავალდებულო ველი');
  }}
/>
```

---

## 🔍 Troubleshooting

### Circular Reference Warning

```
⚠️ Warning: useConditionalFields: Maximum depth (5) reached
```

**გადაწყვეტა:**
- შეამოწმეთ conditionalFields-ის სტრუქტურა
- გაზარდეთ maxDepth თუ საჭიროა
- თავიდან აირიდეთ ველის საკუთარ თავზე დამოკიდებულება

### Styles Not Applied

**გადაწყვეტა:**
- დარწმუნდით რომ Ant Design CSS იმპორტირებულია
- შეამოწმეთ className-ების სწორად დაწერა
- გამოიყენეთ browser DevTools სტილების შესამოწმებლად

---

**🎉 ეს არის სრული გზამკვლევი! გამოიყენეთ და შექმენით შესანიშნავი ფორმები! 🚀**