MyClub/DOCS/VISUAL_ELEMENT_EDITOR.md

# Visual Element Editor System

## Overview

The Visual Element Editor system allows admins to configure different visual variants for page elements without writing code. Each element (header, hero, news section, etc.) can have multiple style variants that can be switched through a visual interface.

## Architecture

### Backend

**Database:**
- Table: `page_element_configs`
- Stores: `page_type`, `element_name`, `variant`, `settings` (JSONB)

**Models:**
- `internal/models/page_element_config.go` - Data model with JSONB support

**Controllers:**
- `internal/controllers/page_element_config_controller.go`
  - `GetPageElementConfigs` - Public endpoint for fetching configs
  - `CreateOrUpdatePageElementConfig` - Admin endpoint for saving
  - `BatchUpdatePageElementConfigs` - Batch update for multiple elements

**API Endpoints:**
```
GET    /api/v1/page-elements?page_type=homepage           - Public
GET    /api/v1/admin/page-elements                        - Admin: Get all
POST   /api/v1/admin/page-elements                        - Admin: Create/Update
PUT    /api/v1/admin/page-elements/:id                    - Admin: Update
DELETE /api/v1/admin/page-elements/:id                    - Admin: Delete
POST   /api/v1/admin/page-elements/batch                  - Admin: Batch update
```

### Frontend

**Services:**
- `frontend/src/services/pageElements.ts`
  - API client functions
  - Element variant definitions (ELEMENT_VARIANTS constant)

**Hooks:**
- `frontend/src/hooks/usePageElementConfig.ts`
  - `usePageElementConfig(pageType, elementName, defaultVariant)` - Single element
  - `useAllPageElementConfigs(pageType)` - All elements for a page

**Components:**
- `frontend/src/components/editor/VisualPageEditor.tsx`
  - Floating button overlay for admins
  - Drawer interface for selecting variants
  - Save & reload functionality

**Element Variants:**
- `frontend/src/components/home/HeaderVariants.tsx`
  - Unified: Classic header with logo and navigation
  - Edge: Modern edge-to-edge with gradient
  - Minimal: Clean minimal header
  - Modern: Bold modern with accent colors

## Usage

### For Admins

1. **Open Visual Editor:**
   - Navigate to the homepage
   - As admin, you'll see a purple floating button (bottom right)
   - Click to open the Visual Editor drawer

2. **Configure Elements:**
   - Toggle "Editing" mode ON
   - Select variants for each element (header, hero, news, matches, sponsors)
   - Preview shows current selection

3. **Save Changes:**
   - Click "Save & Reload"
   - Page will reload with new configurations
   - Changes are persisted in database

### For Developers

#### Adding New Element Variants

1. **Define Variants:**
```typescript
// In services/pageElements.ts
export const ELEMENT_VARIANTS: Record<string, ElementVariant[]> = {
  myElement: [
    { value: 'variant1', label: 'Variant 1', description: 'Description' },
    { value: 'variant2', label: 'Variant 2', description: 'Description' },
  ],
};
```

2. **Create Variant Component:**
```tsx
// MyElementVariants.tsx
interface MyElementVariantsProps {
  variant: 'variant1' | 'variant2';
  // ...other props
}

const MyElementVariants: React.FC<MyElementVariantsProps> = ({ variant, ...props }) => {
  if (variant === 'variant1') {
    return <div>Variant 1 Implementation</div>;
  }
  
  if (variant === 'variant2') {
    return <div>Variant 2 Implementation</div>;
  }
  
  return null;
};
```

3. **Use in Page:**
```tsx
import { useAllPageElementConfigs } from '../hooks/usePageElementConfig';
import MyElementVariants from '../components/MyElementVariants';

const MyPage = () => {
  const { getVariant } = useAllPageElementConfigs('mypage');
  const elementVariant = getVariant('myElement', 'variant1');
  
  return (
    <div>
      <MyElementVariants variant={elementVariant} {...props} />
    </div>
  );
};
```

#### Database Migration

Run migration to create the table:
```bash
# The migration files are already created:
# database/migrations/000020_create_page_element_configs.up.sql
# database/migrations/000020_create_page_element_configs.down.sql

# Run migrations
make migrate-up
```

## Available Element Variants

### Header
- **unified**: Classic header with logo and navigation
- **edge**: Modern edge-to-edge header with gradient background
- **minimal**: Clean minimal header, centered
- **modern**: Bold modern header with accent colors

### Hero
- **grid**: News grid layout
- **swiper**: Swipeable carousel
- **swiper_full**: Full-width swipeable hero
- **edge**: Edge-style hero from ?style=edge

### News
- **grid**: Card grid layout
- **scroller**: Horizontal scroller
- **list**: Vertical list layout
- **magazine**: Magazine-style layout

### Matches
- **compact**: Compact match cards
- **expanded**: Detailed match information
- **timeline**: Timeline view

### Sponsors
- **grid**: Grid layout with title sponsor
- **slider**: Animated slider
- **scroller**: Horizontal scroller
- **pyramid**: Pyramid layout

## Benefits

1. **No Code Changes:** Admins can switch styles without developer intervention
2. **Unified System:** Single base style with element variants instead of multiple complete themes
3. **Persistent:** Configurations saved in database
4. **Live Preview:** Changes apply immediately after save
5. **Per-Element Control:** Mix and match different variants

## Migration from Old System

The old system used complete page styles (unified, magazine, pro, edge). The new system:

1. **Keeps unified as base:** All pages use unified CSS as foundation
2. **Adds element variants:** Individual elements can have different styles
3. **Removes custom styles:** No more separate magazine.css, pro.css, edge.css
4. **Database-driven:** Preferences stored in database instead of settings

### Migration Steps

1. Run database migration
2. Admin configures preferred variants through Visual Editor
3. Old style query parameters (?style=edge) still work for backwards compatibility
4. Gradually remove old style CSS files as variants are implemented

## Future Enhancements

- [ ] Add preview mode without reload
- [ ] Export/import configurations
- [ ] Per-page configurations (different homepage vs about page)
- [ ] Color scheme variants
- [ ] Layout density options (compact, normal, spacious)
- [ ] Responsive variants (mobile-specific)
- [ ] A/B testing support
- [ ] Analytics integration to track variant performance