# UI, Forms, and Development Tools Guide

## Field Control for Forms

### System Fields (Auto-Excluded)

Fields that are system-managed are automatically excluded from forms:

```yaml
models:
  Task:
    fields:
      # System fields - never in forms
      id:
        type: uuid
        system_field: true  # Auto-generated, not editable

      created_at:
        type: timestamp
        system_field: true  # Auto-set on create

      updated_at:
        type: timestamp
        system_field: true  # Auto-updated on save

      # User fields - included in forms
      title:
        type: string
        required: true

      description:
        type: text
```

**Generated form includes**: `title`, `description`
**Excluded from form**: `id`, `created_at`, `updated_at`

### Explicitly Excluded Fields

Exclude specific fields from forms:

```yaml
models:
  User:
    fields:
      email:
        type: string
        required: true

      password_hash:
        type: string
        required: true
        exclude_from_forms: true  # Never show in forms (use password widget instead)

      failed_login_count:
        type: integer
        default: 0
        exclude_from_forms: true  # Internal tracking, not user-editable

      avatar_url:
        type: string
        # Included in forms - use file upload widget
        form_widget: image-upload
```

**Generated form includes**: `email`, `avatar_url` (with custom widget)
**Excluded**: `password_hash`, `failed_login_count`

### Custom Form Widgets

Specify special input types:

```yaml
models:
  Post:
    fields:
      title:
        type: string
        # Default: text input

      content:
        type: text
        form_widget: rich-text-editor  # Use WYSIWYG editor

      cover_image:
        type: string
        form_widget: image-upload  # File upload with preview

      tags:
        type: array
        form_widget: tag-input  # Multi-value tag selector

      publish_date:
        type: timestamp
        form_widget: datetime-picker  # Calendar + time selector
```

---

## Custom Layouts

### Preset Layouts (Simple)

```yaml
ui:
  pages:
    # Grid layout (3 columns, responsive)
    - path: /products
      layout: grid

    # List layout (vertical list)
    - path: /tasks
      layout: list

    # Dashboard layout (widgets/cards)
    - path: /dashboard
      layout: dashboard
```

### Custom Layouts (Complex)

#### Pinterest-Style Masonry

```yaml
ui:
  pages:
    - path: /gallery
      title: Image Gallery
      layout: custom
      custom_layout:
        type: masonry
        config:
          columns: 4
          gap: 16px
          min_column_width: 250px
        responsive: true
        breakpoints:
          mobile:
            max_width: 640px
            columns: 1
          tablet:
            max_width: 1024px
            columns: 2
          desktop:
            min_width: 1024px
            columns: 4
```

**Generated CSS/Component**:
```tsx
<MasonryGrid
  columns={{ mobile: 1, tablet: 2, desktop: 4 }}
  gap="16px"
  minColumnWidth="250px"
>
  {items.map(item => <ImageCard key={item.id} {...item} />)}
</MasonryGrid>
```

#### Complex Grid + Flexbox

```yaml
ui:
  pages:
    - path: /dashboard
      title: Dashboard
      layout: custom
      custom_layout:
        type: grid
        config:
          template_areas: |
            "header header header"
            "sidebar main main"
            "sidebar footer footer"
          template_columns: "250px 1fr 1fr"
          template_rows: "auto 1fr auto"
          gap: 24px
        responsive: true
        breakpoints:
          mobile:
            max_width: 768px
            template_areas: |
              "header"
              "main"
              "sidebar"
              "footer"
            template_columns: "1fr"
```

**Generated Layout**:
```tsx
<DashboardGrid
  templateAreas={{
    desktop: '"header header header" "sidebar main main" "sidebar footer footer"',
    mobile: '"header" "main" "sidebar" "footer"'
  }}
  templateColumns={{ desktop: '250px 1fr 1fr', mobile: '1fr' }}
  gap="24px"
>
  <GridArea area="header"><Header /></GridArea>
  <GridArea area="sidebar"><Sidebar /></GridArea>
  <GridArea area="main"><MainContent /></GridArea>
  <GridArea area="footer"><Footer /></GridArea>
</DashboardGrid>
```

#### Flexbox with Custom Behavior

```yaml
ui:
  pages:
    - path: /products/compare
      title: Product Comparison
      layout: custom
      custom_layout:
        type: flex
        config:
          direction: row
          wrap: wrap
          justify: space-between
          align: stretch
          gap: 20px
        responsive: true
        breakpoints:
          mobile:
            max_width: 640px
            direction: column
```

---

## Development Tools

### Database Operations (Testing/Development)

These operations bypass the API and directly manipulate the database:

```yaml
technology:
  # ... frontend, backend, database config

  development:
    enabled: true  # Only enabled in local/dev stages

    database_operations:
      reset: true    # POST /dev/db/reset - drop all tables and recreate
      seed: true     # POST /dev/db/seed - populate with test data
      truncate: true # POST /dev/db/truncate - delete all data, keep tables

    test_data_generator: true  # Generate realistic test fixtures

    dev_endpoints:
      health_check: true      # GET /dev/health
      database_status: true   # GET /dev/db/status
      clear_cache: true       # POST /dev/cache/clear
```

### Generated Development Endpoints

#### Database Reset
```bash
POST /dev/db/reset
Authorization: Bearer <dev_token>

# Response:
{
  "success": true,
  "operations": [
    "Dropped all tables",
    "Ran migrations",
    "Created schema"
  ],
  "duration_ms": 1234
}
```

**Use case**: Fresh start between test runs

#### Database Seed
```bash
POST /dev/db/seed
Authorization: Bearer <dev_token>
Content-Type: application/json

{
  "models": ["User", "Product", "Task"],
  "count": 10
}

# Response:
{
  "success": true,
  "generated": {
    "User": 10,
    "Product": 10,
    "Task": 10
  }
}
```

**Use case**: Populate database with realistic test data

#### Database Truncate
```bash
POST /dev/db/truncate
Authorization: Bearer <dev_token>
Content-Type: application/json

{
  "tables": ["tasks", "orders"]  # Optional - truncate specific tables
}

# Response:
{
  "success": true,
  "truncated": ["tasks", "orders"]
}
```

**Use case**: Clear data without dropping schema (faster than reset)

### Stage-Specific Development Tools

```yaml
stages:
  local:
    domain: localhost:3000
    database: postgresql://localhost/myapp_dev
    config:
      development:
        enabled: true  # All dev tools available
        require_auth: false  # No auth needed for dev endpoints

  staging:
    domain: staging.myapp.com
    database: "{{ env.STAGING_DB }}"
    config:
      development:
        enabled: true  # Dev tools available
        require_auth: true  # Require admin auth

  production:
    domain: myapp.com
    database: "{{ env.PROD_DB }}"
    config:
      development:
        enabled: false  # Dev tools DISABLED in production
```

### Generated Middleware

```typescript
// Only in local/staging stages
if (config.development?.enabled) {
  app.post('/dev/db/reset',
    requireDevMode,
    requireAuth(config.development.require_auth),
    async (req, res) => {
      await db.dropAllTables();
      await db.runMigrations();
      res.json({ success: true });
    }
  );
}
```

---

## Complete Example

```yaml
models:
  Product:
    fields:
      # System fields
      id:
        type: uuid
        system_field: true

      created_at:
        type: timestamp
        system_field: true

      updated_at:
        type: timestamp
        system_field: true

      # User-editable fields
      name:
        type: string
        required: true
        max_length: 255

      description:
        type: text
        form_widget: rich-text-editor

      price:
        type: decimal
        required: true
        precision: 10
        scale: 2

      image_url:
        type: string
        form_widget: image-upload

      category:
        type: enum
        enum_values: [electronics, clothing, home, books]

      # Internal tracking
      view_count:
        type: integer
        default: 0
        exclude_from_forms: true

ui:
  pages:
    # Product grid with masonry layout
    - path: /products
      title: Products
      layout: custom
      custom_layout:
        type: masonry
        config:
          columns: 4
          gap: 20px
        responsive: true
        breakpoints:
          mobile: { max_width: 640px, columns: 1 }
          tablet: { max_width: 1024px, columns: 2 }

  forms:
    - id: product_form
      title: Product Details
      model: Product
      fields:
        # Auto-generated from model
        # Excludes: id, created_at, updated_at, view_count
        # Includes: name, description, price, image_url, category
        # Uses custom widgets for: description (rich-text), image_url (upload)

technology:
  development:
    enabled: true
    database_operations:
      reset: true
      seed: true
    test_data_generator: true

stages:
  local:
    config:
      development:
        enabled: true
        require_auth: false  # Easy local testing

  production:
    config:
      development:
        enabled: false  # Safety first
```

---

## Summary

### Form Field Control
- ✅ `system_field: true` - Auto-excluded (id, timestamps)
- ✅ `exclude_from_forms: true` - Explicitly excluded (passwords, tracking fields)
- ✅ `form_widget` - Custom input types (rich-text, image-upload, etc.)

### Custom Layouts
- ✅ Preset layouts: grid, list, dashboard
- ✅ Custom layouts: masonry, complex grid, flexbox
- ✅ Responsive breakpoints
- ✅ Full CSS Grid/Flexbox control

### Development Tools
- ✅ Database reset (drop + recreate)
- ✅ Database seed (generate test data)
- ✅ Database truncate (clear data, keep schema)
- ✅ Stage-specific (disabled in production)
- ✅ Auth-protected in non-local stages

These tools enable rapid development and testing without compromising production safety.
