upload

DOCS/MYUIBRIX_GRID_LAYOUT_FEATURE.md

@@ -0,0 +1,160 @@
+# MyUIbrix Grid Layout Feature
+
+## Overview
+Enhanced the MyUIbrix Editor with comprehensive **Grid Layout Controls** that allow admins to split sections into different grid configurations with visual templates and fine-grained control.
+
+## New Features Added
+
+### 1. Grid Layout Tab in VisualStylePanel
+A new dedicated **Grid** tab has been added to the left sidebar style panel with:
+
+#### Quick Templates (One-Click Layouts)
+- 📱 **Single Column** - `1fr`
+- ⚖️ **Two Equal** (50% / 50%) - `1fr 1fr`
+- 📊 **Left Larger** (66% / 33%) - `2fr 1fr`
+- 📊 **Right Larger** (33% / 66%) - `1fr 2fr`
+- 🎯 **Three Equal** (33% / 33% / 33%) - `1fr 1fr 1fr`
+- 📰 **Featured + Two** (50% / 25% / 25%) - `2fr 1fr 1fr`
+- 🔲 **Four Equal** (25% each) - `repeat(4, 1fr)`
+- 📋 **Main + Sidebar** (75% / 25%) - `3fr 1fr`
+
+#### Advanced Grid Controls
+- **Grid Template Columns**: Custom input for precise control (e.g., `300px 1fr`, `2fr 1fr 1fr`)
+- **Grid Template Rows**: Control row sizing
+- **Column Gap**: 0-100px slider
+- **Row Gap**: 0-100px slider
+- **Auto Flow**: Row, Column, Row Dense, Column Dense
+- **Align Items**: Vertical alignment (stretch, start, center, end, baseline)
+- **Justify Items**: Horizontal alignment (stretch, start, center, end)
+
+### 2. Real-Time Style Application
+- Styles are applied **instantly** in preview mode
+- Uses CSS Grid with proper `grid-template-columns`, `column-gap`, `row-gap`
+- Automatic camelCase to kebab-case conversion
+- Smart unit handling (px for numeric values)
+
+### 3. Style Persistence
+- Grid styles are stored in state
+- Applied to DOM elements via `data-element` attribute
+- Works seamlessly with existing variant system
+
+## How to Use
+
+### Step 1: Activate MyUIbrix Editor
+1. Navigate to the homepage as an **admin**
+2. Click the **purple edit button** (bottom-left corner)
+3. Or add `?myuibrix=edit` to the URL
+
+### Step 2: Select an Element
+1. Click on any element you want to configure (e.g., hero, news, gallery)
+2. The element will be highlighted with a blue border
+3. The VisualStylePanel will appear on the left
+
+### Step 3: Configure Grid Layout
+1. Click the **Grid** tab in the VisualStylePanel
+2. Toggle **"Enable Grid Layout"** switch to ON
+3. Choose a quick template or customize:
+   - Click a template button for instant layouts
+   - OR manually enter `grid-template-columns` values
+   - Adjust gaps with sliders
+   - Fine-tune alignment options
+
+### Step 4: Preview & Publish
+1. Changes apply **instantly in preview** (only visible to you)
+2. Click **"Publikovat"** (Publish) in the top bar to save
+3. Page reloads and changes go live for all users
+
+## Examples
+
+### Example 1: Blog Post Layout (Left Content + Right Sidebar)
+```
+grid-template-columns: 2fr 1fr
+column-gap: 32px
+```
+Creates a 66%/33% split - perfect for main content with a sidebar.
+
+### Example 2: Photo Gallery (Three Equal Columns)
+```
+grid-template-columns: 1fr 1fr 1fr
+column-gap: 16px
+row-gap: 16px
+```
+Creates a 3-column equal-width grid with spacing.
+
+### Example 3: Hero Section (Featured + Two)
+```
+grid-template-columns: 2fr 1fr 1fr
+column-gap: 24px
+```
+Creates a 50%/25%/25% split - large featured item with two smaller items.
+
+### Example 4: Custom Fixed + Flexible
+```
+grid-template-columns: 300px 1fr
+column-gap: 40px
+```
+Fixed 300px sidebar + flexible main content.
+
+## Technical Details
+
+### Files Modified
+1. **`frontend/src/components/editor/VisualStylePanel.tsx`**
+   - Added Grid tab with templates and controls
+   - Imported `FiGrid` icon and `Button` component
+   - Added grid-related state variables
+
+2. **`frontend/src/hooks/usePageElementConfig.ts`**
+   - Added `styles` state management
+   - Added `handleMyUIbrixStyleChange` event listener
+   - Added `getStyles()` function
+   - Real-time DOM style application
+
+### Event System
+- **Event**: `myuibrix-style-change`
+- **Detail**: `{ elementName, styles, previewMode }`
+- **Flow**: VisualStylePanel → MyUIbrixEditor → usePageElementConfig → DOM
+
+### CSS Properties Supported
+- `display: grid`
+- `grid-template-columns`
+- `grid-template-rows`
+- `grid-column-gap` / `column-gap`
+- `grid-row-gap` / `row-gap`
+- `grid-auto-flow`
+- `align-items`
+- `justify-items`
+- All standard CSS properties (padding, margin, colors, typography, etc.)
+
+## Browser Compatibility
+- CSS Grid is supported in all modern browsers
+- IE11 requires fallbacks (not implemented)
+
+## Future Enhancements
+- [ ] Responsive grid templates (mobile/tablet breakpoints)
+- [ ] Grid area naming and placement
+- [ ] Visual grid template builder (drag-and-drop)
+- [ ] Save/load custom grid templates
+- [ ] Export grid as reusable component
+
+## Troubleshooting
+
+### Styles Not Applying?
+1. Ensure element has `data-element="elementName"` attribute
+2. Check browser console for errors
+3. Verify grid is enabled (toggle switch ON)
+
+### Changes Not Saving?
+1. Click **Publikovat** button to save
+2. Check for error toasts
+3. Verify admin authentication
+
+### Preview Mode vs Production
+- In **preview mode** (editing): Changes visible only to you
+- After **publishing**: Changes visible to all users
+- Use this to test layouts before going live
+
+---
+
+**Created**: 2025-01-15  
+**Version**: 1.0  
+**Author**: MyUIbrix Development Team