react-dynamic-form-builder-reactquery/LAYOUT_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

# 📐 Layout & Positioning Guide

## პოზიციონირებისა და განლაგების სრული გზამკვლევი

### 🎯 ძირითადი კონცეფცია

ფორმა იყენებს **Ant Design Grid System**-ს (24 column layout).

## 1️⃣ Form-Level Layout

### Layout Types
```typescript
const formConfig: FormConfig = {
  layout: 'vertical',   // Labels თავზე
  // layout: 'horizontal', // Labels მარცხნივ
  // layout: 'inline',     // ყველაფერი ერთ ხაზზე
  columns: 2, // რამდენ სვეტად დაიყოს
}
```

## 2️⃣ Field-Level Positioning

### Basic Span (სვეტების რაოდენობა)
```typescript
{
  name: 'firstName',
  span: 12, // ნახევარი სიგანე (12/24)
}

{
  name: 'fullWidth',
  span: 24, // სრული სიგანე
}

{
  name: 'third',
  span: 8, // ერთი მესამედი (8/24)
}
```

### Offset (ცარიელი ადგილი მარცხნიდან)
```typescript
{
  name: 'centered',
  span: 12,
  offset: 6, // 6 სვეტი ცარიელია მარცხნიდან, შემდეგ 12 სვეტი ველი
}
```

### Push & Pull (ველების გადაადგილება)
```typescript
{
  name: 'first',
  span: 12,
  push: 12, // გადააადგილე მარჯვნივ 12 სვეტით
},
{
  name: 'second',
  span: 12,
  pull: 12, // გადააადგილე მარცხნივ 12 სვეტით
}
// ეს ველები გაცვლიან ადგილებს!
```

### Custom Styles
```typescript
{
  name: 'customField',
  span: 12,
  style: {
    padding: '0 10px',
    background: '#f0f0f0',
  },
  formItemStyle: {
    marginBottom: '32px',
    border: '1px solid #ddd',
  }
}
```

### Label & Wrapper Layout (Horizontal Layout-ისთვის)
```typescript
{
  name: 'horizontalField',
  label: 'Label',
  labelCol: { span: 6 }, // Label იკავებს 6 სვეტს
  wrapperCol: { span: 18 }, // Input იკავებს 18 სვეტს
}
```

## 3️⃣ პრაქტიკული მაგალითები

### მაგალითი 1: 2-Column Layout
```typescript
const formConfig = {
  columns: 2,
  fields: [
    { name: 'firstName', span: 12 }, // მარცხენა სვეტი
    { name: 'lastName', span: 12 },  // მარჯვენა სვეტი
    { name: 'email', span: 24 },     // სრული სიგანე
  ]
}
```

### მაგალითი 2: 3-Column Layout
```typescript
const formConfig = {
  columns: 3,
  fields: [
    { name: 'field1', span: 8 },
    { name: 'field2', span: 8 },
    { name: 'field3', span: 8 },
  ]
}
```

### მაგალითი 3: კომპლექსური Layout
```typescript
const formConfig = {
  fields: [
    // სრული სიგანე
    { name: 'title', span: 24 },

    // 2 ველი თანაბრად
    { name: 'firstName', span: 12 },
    { name: 'lastName', span: 12 },

    // 3 ველი თანაბრად
    { name: 'day', span: 8 },
    { name: 'month', span: 8 },
    { name: 'year', span: 8 },

    // 1/3 + 2/3
    { name: 'code', span: 8 },
    { name: 'description', span: 16 },

    // ცენტრში განთავსებული ველი
    { name: 'centered', span: 12, offset: 6 },
  ]
}
```

### მაგალითი 4: Responsive Layout (Mobile-Friendly) ⭐
```typescript
import { ResponsiveSpan } from 'react-dynamic-form-builder';

const formConfig = {
  fields: [
    {
      name: 'responsiveField',
      label: 'Responsive Field',
      type: 'input',
      // Mobile (xs): სრული სიგანე
      // Tablet (sm/md): ნახევარი
      // Desktop (lg+): მესამედი
      span: { xs: 24, sm: 12, md: 12, lg: 8 } as ResponsiveSpan,
    },
    {
      name: 'firstName',
      span: { xs: 24, sm: 12, lg: 8 },
    },
    {
      name: 'lastName',
      span: { xs: 24, sm: 12, lg: 8 },
    },
    {
      name: 'email',
      span: { xs: 24, sm: 24, lg: 8 },
    }
  ]
}
```

### მაგალითი 4.1: Responsive Offset და Push/Pull
```typescript
const formConfig = {
  fields: [
    {
      name: 'centeredOnDesktop',
      type: 'input',
      // Mobile-ზე სრული სიგანე, Desktop-ზე ცენტრში
      span: { xs: 24, lg: 12 },
      offset: { xs: 0, lg: 6 }, // Desktop-ზე ცენტრირება
    },
    {
      name: 'pushPullExample',
      span: { xs: 24, md: 12 },
      push: { md: 12 }, // Tablet-ზე და ზემოთ გადაადგილება
    }
  ]
}
```

### მაგალითი 5: Form with Sections
```typescript
const formConfig = {
  columns: 2,
  sections: [
    {
      title: 'Section 1',
      fields: [
        { name: 'field1', span: 12 },
        { name: 'field2', span: 12 },
      ]
    },
    {
      title: 'Section 2 - Full Width',
      fields: [
        { name: 'field3', span: 24 },
      ]
    }
  ]
}
```

## 4️⃣ Grid Examples

### 24-Column Grid ვიზუალიზაცია:
```
|--1--|--2--|--3--|--4--|--5--|--6--|--7--|--8--|--9--|--10-|--11-|--12-|--13-|--14-|--15-|--16-|--17-|--18-|--19-|--20-|--21-|--22-|--23-|--24-|
```

**span: 24** - სრული სიგანე
```
|============================================================================|
```

**span: 12** - ნახევარი
```
|=====================================|                                     |
```

**span: 8** - ერთი მესამედი
```
|========================|                        |                        |
```

**span: 6** - ერთი მეოთხედი
```
|==================|              |              |              |
```

## 5️⃣ Advanced Techniques

### ასიმეტრიული Layout
```typescript
{
  fields: [
    { name: 'small', span: 6 },
    { name: 'large', span: 18 },
  ]
}
```

### ველების დაჯგუფება
```typescript
{
  fields: [
    { name: 'group1field1', span: 8, group: 'group1' },
    { name: 'group1field2', span: 8, group: 'group1' },
    { name: 'group1field3', span: 8, group: 'group1' },

    { name: 'group2field1', span: 12, group: 'group2' },
    { name: 'group2field2', span: 12, group: 'group2' },
  ]
}
```

### CSS Grid Alternative
```typescript
{
  name: 'customGrid',
  span: 24,
  style: {
    display: 'grid',
    gridTemplateColumns: 'repeat(3, 1fr)',
    gap: '16px',
  }
}
```

## 6️⃣ Best Practices

### ✅ DO:
- გამოიყენეთ `columns` prop simple layouts-ისთვის
- გამოიყენეთ `span` თითოეული ველისთვის individual control-ისთვის
- დაიცავით consistency განლაგებაში
- გამოიყენეთ `offset` centering-ისთვის
- გამოიყენეთ sections complex forms-ისთვის

### ❌ DON'T:
- არ გამოიყენოთ span > 24
- არ დაივიწყოთ mobile responsiveness
- არ გააკეთოთ ძალიან დატვირთული layouts

## 7️⃣ Cheat Sheet

| რას გინდა | როგორ გააკეთო |
|-----------|---------------|
| 2 ველი თანაბრად | `span: 12` ორივეს |
| 3 ველი თანაბრად | `span: 8` ყველას |
| 4 ველი თანაბრად | `span: 6` ყველას |
| სრული სიგანე | `span: 24` |
| ცენტრირება | `span: 12, offset: 6` |
| 1/3 + 2/3 | `span: 8` და `span: 16` |
| 1/4 + 3/4 | `span: 6` და `span: 18` |

## 8️⃣ Live Example

```typescript
const complexForm: FormConfig = {
  layout: 'vertical',
  columns: 1,
  sections: [
    {
      title: 'პირადი ინფორმაცია',
      fields: [
        // სრული სიგანე
        { name: 'avatar', type: 'upload', span: 24 },

        // 2 ველი თანაბრად
        { name: 'firstName', type: 'input', span: 12 },
        { name: 'lastName', type: 'input', span: 12 },

        // 3 ველი (დაბადების თარიღი)
        { name: 'day', type: 'select', span: 8, placeholder: 'DD' },
        { name: 'month', type: 'select', span: 8, placeholder: 'MM' },
        { name: 'year', type: 'select', span: 8, placeholder: 'YYYY' },
      ]
    },
    {
      title: 'საკონტაქტო',
      fields: [
        // სრული სიგანე email
        { name: 'email', type: 'email', span: 24 },

        // 1/3 country code + 2/3 phone
        {
          name: 'countryCode',
          type: 'select',
          span: 8,
          style: { paddingRight: '8px' }
        },
        {
          name: 'phone',
          type: 'phone',
          span: 16,
          style: { paddingLeft: '8px' }
        },
      ]
    }
  ]
};
```

---

## 9️⃣ 📱 Responsive Design - Mobile-Friendly

### Breakpoint სისტემა

Ant Design Grid იყენებს შემდეგ breakpoint-ებს:

| Breakpoint | ეკრანის ზომა | მოწყობილობა | გამოყენება |
|-----------|-------------|-------------|------------|
| **xs** | <576px | Mobile | სრული სიგანე (24) |
| **sm** | ≥576px | Large Mobile/Small Tablet | 12 ან 24 |
| **md** | ≥768px | Tablet | 12, 8 |
| **lg** | ≥992px | Desktop | 8, 6, 12 |
| **xl** | ≥1200px | Large Desktop | 6, 8 |
| **xxl** | ≥1600px | Extra Large | 6, 4 |

### Responsive Best Practices ⭐

#### 1. Mobile-First Approach
```typescript
// ✅ კარგი: Mobile-დან Desktop-ისკენ
{
  name: 'field',
  span: { xs: 24, sm: 12, lg: 8 }
  // xs: mobile - სრული სიგანე
  // sm: tablet - ნახევარი
  // lg: desktop - მესამედი
}

// ❌ ცუდი: ძალიან ბევრი breakpoint
{
  name: 'field',
  span: { xs: 24, sm: 20, md: 16, lg: 12, xl: 10, xxl: 8 }
}
```

#### 2. საერთო Responsive პატერნები

**პატერნი A: სრული სიგანე → ნახევარი → მესამედი**
```typescript
{
  fields: [
    {
      name: 'name',
      span: { xs: 24, sm: 12, lg: 8 },
    },
    {
      name: 'email',
      span: { xs: 24, sm: 12, lg: 8 },
    },
    {
      name: 'phone',
      span: { xs: 24, sm: 12, lg: 8 },
    },
  ]
}
// Mobile: 3 ველი ერთმანეთის ქვეშ
// Tablet: 2 სვეტად (name/email → phone)
// Desktop: 3 სვეტად
```

**პატერნი B: სრული სიგანე → ნახევარი**
```typescript
{
  fields: [
    {
      name: 'firstName',
      span: { xs: 24, md: 12 },
    },
    {
      name: 'lastName',
      span: { xs: 24, md: 12 },
    },
  ]
}
// Mobile & Small Tablet: ვერტიკალურად
// Desktop: 2 სვეტად
```

**პატერნი C: Title სრული, ველები responsive**
```typescript
{
  fields: [
    {
      name: 'title',
      type: 'input',
      span: 24, // ყოველთვის სრული სიგანე
    },
    {
      name: 'category',
      span: { xs: 24, sm: 12, lg: 6 },
    },
    {
      name: 'status',
      span: { xs: 24, sm: 12, lg: 6 },
    },
    {
      name: 'priority',
      span: { xs: 24, sm: 12, lg: 6 },
    },
    {
      name: 'assignee',
      span: { xs: 24, sm: 12, lg: 6 },
    },
  ]
}
```

#### 3. კომპლექსური Responsive Form
```typescript
import { FormConfig, ResponsiveSpan } from 'react-dynamic-form-builder';

const responsiveForm: FormConfig = {
  layout: 'vertical', // Mobile-ზე vertical უკეთესია
  sections: [
    {
      title: 'პირადი ინფორმაცია',
      fields: [
        {
          name: 'avatar',
          type: 'upload',
          span: 24, // ყოველთვის სრული
        },
        {
          name: 'firstName',
          type: 'input',
          span: { xs: 24, sm: 12 } as ResponsiveSpan,
        },
        {
          name: 'lastName',
          type: 'input',
          span: { xs: 24, sm: 12 },
        },
        {
          name: 'email',
          type: 'email',
          span: { xs: 24, md: 12 },
        },
        {
          name: 'phone',
          type: 'phone',
          span: { xs: 24, md: 12 },
        },
      ]
    },
    {
      title: 'მისამართი',
      fields: [
        {
          name: 'country',
          type: 'select',
          span: { xs: 24, sm: 12, lg: 8 },
        },
        {
          name: 'city',
          type: 'select',
          span: { xs: 24, sm: 12, lg: 8 },
        },
        {
          name: 'district',
          type: 'select',
          span: { xs: 24, sm: 24, lg: 8 },
        },
        {
          name: 'street',
          type: 'input',
          span: 24,
        },
      ]
    }
  ]
};
```

#### 4. Responsive Centering
```typescript
{
  name: 'submitButton',
  type: 'custom',
  // Mobile: სრული სიგანე
  // Desktop: ცენტრში 12 სვეტი
  span: { xs: 24, lg: 12 },
  offset: { xs: 0, lg: 6 },
}
```

### Mobile UX Tips 📱

1. **Mobile-ზე ყოველთვის `span: 24`** - ერთი ველი ერთ줄ზე
2. **Tablet-დან იწყე დაყოფა** - `sm: 12` ან `md: 12`
3. **Desktop-ზე 3-4 სვეტი მაქსიმუმ** - `lg: 8` ან `lg: 6`
4. **Vertical layout Mobile-ზე** - უკეთესი UX
5. **Horizontal layout Desktop-ზე** - ეკონომიური სივრცე

### შეჯამება

```typescript
// ✅ იდეალური Responsive პატერნი
const perfectResponsive = {
  fields: [
    {
      name: 'anyField',
      span: {
        xs: 24,  // Mobile: სრული სიგანე
        sm: 12,  // Tablet: ნახევარი
        lg: 8,   // Desktop: მესამედი
      }
    }
  ]
}

// Mobile First!
// თქვენ ყოველთვის უნდა იფიქროთ:
// 1. როგორ გამოიყურება Mobile-ზე?
// 2. როგორ გამოიყურება Tablet-ზე?
// 3. როგორ გამოიყურება Desktop-ზე?
```

---

ეს სისტემა გაძლევთ **სრულ კონტროლს** ფორმის განლაგებაზე და **მაქსიმალურ Responsive/Mobile-Friendly ფუნქციონალს**! 🎨📱