Grid Canvas System - Professional Layout Builder

Simple, powerful grid/flexbox layout builder with Flutter export

🎨 Grid Canvas System

The most professional, intuitive grid/flexbox builder for GoGrab Space.

🎯 Overview

The Grid Canvas System is a complete rewrite of the layout builder, designed to be:

Removed: ❌ Complex Divider System

Added: ✅ Simple Grid Controls + Flutter Export

📁 File Structure

libs/libs-structural/modular-universe/
├── src/lib/
│   ├── components/
│   │   └── grid-canvas/
│   │       ├── grid-canvas.component.ts      # Main canvas logic
│   │       ├── grid-canvas.component.html    # Template
│   │       └── grid-canvas.component.scss    # Styles
│   ├── services/
│   │   └── flutter-export.service.ts         # Flutter code generation
│   └── models/
│       ├── layout-types.ts                   # Layout interfaces
│       └── canvas-mode.types.ts              # Canvas modes

🎮 Canvas Modes

1. Select Mode (Default)

2. Add Mode

3. Resize Mode

4. Reorder Mode

5. Grid Edit Mode 🆕

6. Export Mode 🆕

🧩 Grid Edit Mode - How It Works

Adding Rows/Columns

// User clicks "Add Row"
addGridRow() {
  // 1. Add new row track (1fr)
  config.grid.rows.push('1fr');
  
  // 2. Create sections for new row (one per column)
  for (col = 1; col <= colCount; col++) {
    createGridSection(newRowIndex, col);
  }
  
  // 3. Save to storage
  saveLayoutConfiguration();
}

Result: Instant visual update, new sections ready for content.

Removing Rows/Columns

// User clicks "Remove Row"
removeGridRow() {
  // 1. Remove last row track
  config.grid.rows.pop();
  
  // 2. Remove sections in that row
  config.sections = config.sections.filter(
    section => section.grid.row !== removedRowIndex
  );
  
  // 3. Save to storage
  saveLayoutConfiguration();
}

Safety: Can't remove if only 1 row/column remains.

🚀 Flutter Export System

Usage

// User clicks "Export to Flutter"
const flutterCode = flutterExport.exportLayout(layoutConfig);

// Output:
GridView.count(
  crossAxisCount: 3,
  crossAxisSpacing: 16,
  mainAxisSpacing: 16,
  children: [
    Container(
      decoration: BoxDecoration(
        color: Colors.grey[200],
        borderRadius: BorderRadius.circular(8.0),
      ),
      padding: EdgeInsets.all(16.0),
      child: Text('Section 1'),
    ),
    // ... more sections
  ],
)

Supported Features

Export Flow

  1. User clicks "Export to Flutter"
  2. FlutterExportService generates Dart code
  3. Code copied to clipboard automatically
  4. Alert confirms "Flutter code copied!"

🎨 Layout Types

Flexbox (Default)

{
  type: 'flexbox',
  flexbox: {
    direction: 'column',
    wrap: 'nowrap',
    justifyContent: 'flex-start',
    alignItems: 'stretch',
    gap: '16px'
  },
  sections: [...]
}

Use Cases:

CSS Grid

{
  type: 'grid',
  grid: {
    rows: ['1fr', '2fr', '1fr'],
    columns: ['250px', '1fr', '1fr'],
    gap: '16px'
  },
  sections: [...]
}

Use Cases:

💾 Storage System

Auto-Save

Storage Key Pattern

const key = `modular-universe/layout/${universeId}/${moduleType}`;
// Example: "modular-universe/layout/main-universe/universe"

Event System

// Listen for cross-tab updates
this.storage.onEvent((event) => {
  if (event.type === 'put' && event.key === layoutKey) {
    // Reload layout from storage
    this.layoutConfig.set(updatedConfig);
  }
});

🛡️ Prevents Loops: Ignores own save events with isSaving flag.

🧪 Testing Guide

Manual Testing Checklist

Grid Mode

Export

Storage

🔄 Migration Notes

Removed Files

Added Files

Updated Files

🎯 Future Enhancements

Phase 1 (Pending)

Phase 2 (Future)

📚 Code Examples

Creating a Simple 2x2 Grid

// User switches to Grid mode
switchLayoutType('grid');

// System auto-generates 2x2 grid
{
  type: 'grid',
  grid: {
    rows: ['1fr', '1fr'],
    columns: ['1fr', '1fr'],
    gap: '16px'
  },
  sections: [
    { id: '1', grid: { row: 1, col: 1, rowSpan: 1, colSpan: 1 } },
    { id: '2', grid: { row: 1, col: 2, rowSpan: 1, colSpan: 1 } },
    { id: '3', grid: { row: 2, col: 1, rowSpan: 1, colSpan: 1 } },
    { id: '4', grid: { row: 2, col: 2, rowSpan: 1, colSpan: 1 } }
  ]
}

Adding a Third Column

// User clicks "Add Column" in Grid Edit mode
addGridColumn();

// System adds column and creates 2 new sections (for 2 rows)
{
  grid: {
    columns: ['1fr', '1fr', '1fr']  // Added '1fr'
  },
  sections: [
    // ... existing 4 sections
    { id: '5', grid: { row: 1, col: 3, rowSpan: 1, colSpan: 1 } },
    { id: '6', grid: { row: 2, col: 3, rowSpan: 1, colSpan: 1 } }
  ]
}

🐛 Troubleshooting

Grid sections not appearing

Cause: Sections array empty
Solution: Switch to Grid mode to auto-generate default sections

Export button not copying

Cause: Browser clipboard permissions
Solution: Check console for code output, copy manually

Layout not persisting

Cause: universeId not set
Solution: Verify universeId input is provided to component

Cross-tab sync not working

Cause: Storage event listener not registered
Solution: Check console logs for event listener setup

🎓 Learning Resources

Key Concepts

  1. OnPush Change Detection: Use cdr.markForCheck() after mutations
  2. Signals: Reactive state with signal() and computed()
  3. Storage System: Flash persistence + real-time sync
  4. Immutability: Always structuredClone() before mutations

Related Documentation

🎉 Success Criteria

This system is successful when:

Built with ❤️ for GoGrab Space
The most professional platform builder in the universe.