upload

DOCS/ELEMENTOR_STYLE_EDITOR.md

@@ -0,0 +1,335 @@
+# Elementor-Style Visual Editor
+
+## 🎨 Overview
+
+The Elementor-Style Visual Editor brings WordPress Elementor-like page building capabilities to your football club website. Edit your homepage visually with live element highlighting, drag-free controls, and professional styling options.
+
+## ✨ Key Features
+
+### Visual Editing Mode
+- **Live Element Highlighting**: Hover over any element to see it highlighted with a blue dashed border
+- **Element Badges**: Click on element badges to instantly open their settings
+- **Selected Element**: Active element shows a solid blue border with semi-transparent overlay
+- **No Page Reload**: Changes preview live (refresh to see final result)
+
+### Professional Controls
+- **Left Control Panel**: Quick access toolbar with edit mode toggle, undo/redo, device preview, and save
+- **Right Settings Drawer**: Comprehensive element configuration panel
+- **Search Elements**: Quickly find the element you want to edit
+- **Template Import/Export**: Save and reuse your configurations
+
+### Advanced Features
+- **Undo/Redo History**: Full editing history with navigation
+- **Device Preview**: Switch between Desktop, Tablet, and Mobile views
+- **Template Management**: Export configurations as JSON and import them later
+- **Batch Save**: All changes saved in one operation
+
+## 🚀 How to Use
+
+### Entering Edit Mode
+
+1. **Login** as administrator
+2. **Navigate** to the homepage
+3. **Click** the purple edit button in the bottom-left control panel
+4. **Watch** as all editable elements get highlighted with badges
+
+### Editing Elements
+
+**Method 1: Click Element Badge**
+- Hover over any element (header, hero, news, etc.)
+- Click the element name badge that appears
+- Settings drawer opens automatically
+
+**Method 2: Use Settings Panel**
+- Click the settings (gear) icon in the left control panel
+- Browse or search for elements in the "Elements" tab
+- Click on an element to expand its settings
+
+### Configuring Variants
+
+1. **Select Element**: Click on the element or find it in the panel
+2. **Choose Variant**: Select from available style variants in dropdown
+3. **View Description**: Each variant shows a description below
+4. **See Changes**: Element updates immediately in the preview
+
+### Saving Changes
+
+1. **Make Changes**: Edit multiple elements as needed
+2. **Review**: Check the orange "unsaved changes" badge
+3. **Click Save**: Green save button in left panel or settings tab
+4. **Wait**: Page automatically refreshes to apply changes
+
+## 📐 Control Panel Breakdown
+
+### Left Floating Panel (Bottom-Left)
+
+```
+┌────────────┐
+│  👁️ / ✏️   │ ← Edit Mode Toggle
+├────────────┤
+│    ⚙️      │ ← Settings Drawer
+│    ↶      │ ← Undo
+│    ↷      │ ← Redo
+├────────────┤
+│   🖥️ / 📱  │ ← Device Preview
+├────────────┤
+│    💾      │ ← Save Changes
+└────────────┘
+```
+
+### Right Settings Drawer
+
+**Elements Tab**:
+- Search bar for quick element finding
+- Accordion list of all editable elements
+- Current variant shown below element name
+- Expand to see variant selector and description
+
+**Settings Tab**:
+- Page information
+- History controls (undo/redo with count)
+- Save button with change indicator
+- Template export/import buttons
+
+## 🎯 Available Elements & Variants
+
+### Header
+Visual style of the top header/logo area
+
+- **Unified**: Classic horizontal header with logo and text
+- **Edge**: Modern centered header with gradient background
+- **Minimal**: Clean minimal centered header
+- **Modern**: Bold header with accent colors and shadow
+
+### Hero
+Main featured content section
+
+- **Grid**: 3-column grid (1 large + 2 small cards)
+- **Swiper**: Swipeable carousel slider
+- **Swiper Full**: Full-width hero carousel
+- **Edge**: Dramatic full-screen hero from Edge style
+
+### News
+Article/blog listing section
+
+- **Grid**: Card grid layout
+- **Scroller**: Horizontal scrolling cards
+- **List**: Traditional vertical list
+- **Magazine**: Magazine-style with categories
+
+### Matches
+Match display section
+
+- **Compact**: Minimal match cards
+- **Expanded**: Detailed match information with stats
+- **Timeline**: Timeline view of fixtures
+
+### Sponsors
+Sponsor logos section
+
+- **Grid**: Grid with title sponsor
+- **Slider**: Infinite scrolling slider
+- **Scroller**: Horizontal scroller
+- **Pyramid**: Pyramid/tiered layout
+
+## ⌨️ Keyboard Shortcuts
+
+| Shortcut | Action |
+|----------|--------|
+| `Ctrl/Cmd + Z` | Undo |
+| `Ctrl/Cmd + Y` | Redo |
+| `Ctrl/Cmd + S` | Save Changes |
+| `Esc` | Close Settings Drawer |
+
+## 💡 Pro Tips
+
+### Fast Editing Workflow
+
+1. **Enter edit mode** once
+2. **Click element badges** directly (faster than using panel)
+3. **Make all changes** before saving
+4. **Export template** for backup before major changes
+5. **Save once** to apply all changes
+
+### Best Practices
+
+- **Preview Before Save**: Check all changes in different device views
+- **Use Undo/Redo**: Don't hesitate to experiment, you can always undo
+- **Export Templates**: Save successful configurations as templates
+- **Test Mobile**: Always check mobile device preview before saving
+- **Batch Changes**: Edit multiple elements in one session for efficiency
+
+### Element Selection Tips
+
+- **Header**: First impression matters - choose based on brand identity
+- **Hero**: Drive engagement - swiper for content variety, grid for stability
+- **News**: Match visitor behavior - grid for scanning, scroller for browsing
+- **Matches**: Consider info density - compact for many matches, expanded for detail
+- **Sponsors**: Balance visibility - grid for fewer sponsors, slider for many
+
+## 🔧 Advanced Usage
+
+### Template Management
+
+**Export Template**:
+1. Configure all elements as desired
+2. Click "Export" button in drawer header
+3. JSON file downloads with all configurations
+4. Save for backup or sharing
+
+**Import Template**:
+1. Click "Import" button in drawer header
+2. Select previously exported JSON file
+3. All configurations apply immediately
+4. Review and save to persist
+
+### History Management
+
+- **View Count**: Settings tab shows "X / Y changes"
+- **Navigate**: Use undo/redo buttons or keyboard
+- **Limit**: Last 50 changes stored
+- **Reset**: Save to clear history
+
+### Device Preview
+
+**Desktop View** (default):
+- Full-width preview
+- All elements visible
+- No overlay
+
+**Tablet View**:
+- 768px viewport simulation
+- Dark overlay on sides
+- Restricted width preview
+
+**Mobile View**:
+- 375px viewport simulation
+- Dark overlay on sides
+- Mobile-optimized preview
+
+## 🐛 Troubleshooting
+
+### Element Not Highlighting
+
+**Problem**: Element doesn't show border/badge on hover
+
+**Solutions**:
+- Ensure edit mode is ON (purple button pressed)
+- Check element has `data-element` attribute
+- Refresh page if overlays disappeared
+
+### Changes Not Saving
+
+**Problem**: Save button doesn't work or changes lost
+
+**Solutions**:
+- Check browser console for errors
+- Verify you're logged in as admin
+- Try saving one element at a time
+- Export template as backup, then try again
+
+### Preview Not Updating
+
+**Problem**: Changes don't show in preview
+
+**Solutions**:
+- Some changes need page refresh to see
+- Try toggling device preview
+- Click save to apply changes permanently
+
+### Can't Find Element
+
+**Problem**: Element not in the list
+
+**Solutions**:
+- Use search bar to filter
+- Check if element is wrapped with `EditableElement`
+- Verify element name in `ELEMENT_VARIANTS`
+
+## 🎓 For Developers
+
+### Adding Editable Elements
+
+Wrap any section with `EditableElement`:
+
+```tsx
+import EditableElement from '../components/editor/EditableElement';
+
+<EditableElement elementName="myElement">
+  <div>Your content here</div>
+</EditableElement>
+```
+
+### Defining Variants
+
+Add to `services/pageElements.ts`:
+
+```typescript
+export const ELEMENT_VARIANTS: Record<string, ElementVariant[]> = {
+  myElement: [
+    { 
+      value: 'variant1', 
+      label: 'Variant 1', 
+      description: 'Clean and simple layout' 
+    },
+    { 
+      value: 'variant2', 
+      label: 'Variant 2', 
+      description: 'Bold and colorful design' 
+    },
+  ],
+};
+```
+
+### Using Variant in Component
+
+```tsx
+const { getVariant } = useAllPageElementConfigs('homepage');
+const myVariant = getVariant('myElement', 'variant1');
+
+// Render based on variant
+{myVariant === 'variant1' && <Variant1Component />}
+{myVariant === 'variant2' && <Variant2Component />}
+```
+
+## 🎉 Comparison with WordPress Elementor
+
+| Feature | Elementor | Our Editor | Notes |
+|---------|-----------|------------|-------|
+| Visual Editing | ✅ | ✅ | Live element highlighting |
+| Drag & Drop | ✅ | ❌ | Not needed for variant switching |
+| Live Preview | ✅ | ⚠️ | Needs refresh for full preview |
+| Undo/Redo | ✅ | ✅ | Full history support |
+| Device Preview | ✅ | ✅ | Desktop/Tablet/Mobile |
+| Template Library | ✅ | ✅ | Export/Import JSON |
+| Advanced Styling | ✅ | 🔄 | Coming soon with AdvancedStyleControls |
+| Widget Library | ✅ | ⚠️ | Predefined variants instead |
+| Responsive Editing | ✅ | 🔄 | Per-device settings planned |
+| Custom CSS | ✅ | 🔄 | Planned feature |
+
+✅ = Fully implemented  
+⚠️ = Partially implemented  
+❌ = Not implemented  
+🔄 = Planned
+
+## 📚 Related Documentation
+
+- `VISUAL_ELEMENT_EDITOR.md` - Technical implementation details
+- `QUICK_START_VISUAL_EDITOR.md` - Quick start guide
+- `NAVIGATION_SYSTEM.md` - Navigation configuration
+- `README.md` - General documentation
+
+## 🆘 Support
+
+For issues or questions:
+1. Check this documentation
+2. Review browser console for errors
+3. Test in different browser
+4. Check `page_element_configs` database table
+5. Review component source code
+
+---
+
+**Version**: 2.0  
+**Last Updated**: 2025-01-13  
+**Compatibility**: React 18+, Chakra UI 2+