PLATFORM AGNOSTIC LAYOUT

Documentation for Plans

🌍 Platform-Agnostic Layout System - Design Document

🎯 Problem Statement

Current Issue: CSS Grid is web-specific and doesn't translate to Flutter, React Native, or other platforms.

User's Concern:

"Our platform-builder is supposed to generate platform-agnostic content, including for Flutter. We might be shooting ourselves in the foot if we allow CSS Grid."

Solution: Flexbox-only approach with smart layout presets that work everywhere.

✅ Why Flexbox?

Cross-Platform Support:

CSS Grid Limitations:

🎨 Layout System Design

1. Core Concepts (Flexbox-Only)

Every section uses Flexbox with:

Additional Properties:

2. Smart Layout Presets

Instead of CSS Grid, we provide 8 powerful presets:

Preset 1: Stack (Vertical) 📚

Container (Column, Center)
├─ Child 1 (100% width)
├─ Child 2 (100% width)
└─ Child 3 (100% width)

Use Case: Default stacking layout
Flutter Equivalent: Column(children: [...])

Preset 2: Sidebar (Fixed + Flexible) 📐

Container (Row)
├─ Sidebar (width: 250px, fixed)
└─ Content (flex: 1, scrollable)

Use Case: Admin panels, dashboards
Flutter Equivalent: 

Row(children: [
  Container(width: 250, child: Sidebar()),
  Expanded(child: Content())
])

Preset 3: Split View (50/50 or 30/70) ⚖️

Container (Row)
├─ Left (flex: 1)
└─ Right (flex: 1)

Use Case: Comparison views, dual panels
Flutter Equivalent: 

Row(children: [
  Expanded(flex: 1, child: Left()),
  Expanded(flex: 1, child: Right())
])

Preset 4: Card Grid (Wrap) 🎴

Container (Row, Wrap)
├─ Card (width: 30%, margin: 1%)
├─ Card (width: 30%, margin: 1%)
├─ Card (width: 30%, margin: 1%)
└─ (wraps to next row...)

Use Case: Product grids, gallery
Flutter Equivalent: Wrap(children: [...])

Preset 5: Header/Content/Footer 📄

Container (Column)
├─ Header (height: auto)
├─ Content (flex: 1, scrollable)
└─ Footer (height: auto)

Use Case: Classic page layout
Flutter Equivalent: 

Column(children: [
  Header(),
  Expanded(child: Content()),
  Footer()
])

Preset 6: Center (Absolute Center) 🎯

Container (Column, Center, Center)
└─ Child (centered both axes)

Use Case: Hero sections, modals
Flutter Equivalent: Center(child: ...)

Preset 7: Toolbar (Icons Row) 🔧

Container (Row, Center, Space Between)
├─ Icon 1
├─ Icon 2
└─ Icon 3

Use Case: Action bars, button groups
Flutter Equivalent: 

Row(
  mainAxisAlignment: MainAxisAlignment.spaceBetween,
  children: [Icon1(), Icon2(), Icon3()]
)

Preset 8: Stack/Overlay (Absolute Positioning) 🗂️

Container (position: relative)
├─ Background Layer (z: 0)
├─ Content Layer (z: 1)
└─ Overlay Layer (z: 2)

Use Case: Modals, tooltips, overlays
Flutter Equivalent: Stack(children: [...])

🧩 Module Integration Strategy

Module Placement Metadata

Based on GoGrab-modules architecture, add to ModuleManifest:

interface ModuleManifest {
  id: string;
  name: string;
  // ... existing fields
  
  // NEW: Placement preferences
  placementPreferences?: {
    preferredLayout: 'stack' | 'sidebar' | 'split' | 'cards' | 'header-content-footer' | 'center' | 'toolbar' | 'stack-overlay';
    preferredWidth?: string; // '100%', '300px', '30%'
    preferredHeight?: string; // 'auto', '200px', '100vh'
    flexGrow?: number; // 0 = fixed, 1 = flexible
    canNest?: boolean; // Can contain other modules?
    suggestedPosition?: 'header' | 'sidebar' | 'main' | 'footer'; // Hint for auto-placement
  };
}

Example Module Definitions

// Structural Module: Sidebar Navigation
{
  id: 'module-sidenav',
  name: 'Side Navigation',
  type: 'structural',
  placementPreferences: {
    preferredLayout: 'sidebar',
    preferredWidth: '250px',
    flexGrow: 0, // Fixed width
    canNest: true,
    suggestedPosition: 'sidebar'
  }
}

// Content Module: User Profile Widget
{
  id: 'module-user-profile',
  name: 'User Profile',
  type: 'content',
  placementPreferences: {
    preferredWidth: '30%',
    preferredHeight: '400px',
    flexGrow: 0,
    canNest: false,
    suggestedPosition: 'main'
  }
}

// Structural Module: Dashboard Container
{
  id: 'module-dashboard',
  name: 'Dashboard',
  type: 'structural',
  placementPreferences: {
    preferredLayout: 'cards',
    canNest: true,
    suggestedPosition: 'main'
  }
}

🎯 Auto-Placement Intelligence

When user drops a module on canvas:

  1. Check Module Type:

    • Structural → Suggest creating new section
    • Content → Place in nearest section

  2. Apply Preferences:

    • Read placementPreferences.preferredWidth/Height
    • Set section flex properties
    • Apply suggested layout preset

  3. Smart Positioning:

    • suggestedPosition: 'sidebar' → Add to left/right
    • suggestedPosition: 'header' → Add to top
    • suggestedPosition: 'footer' → Add to bottom
    • suggestedPosition: 'main' → Add to center content

  4. Validate Nesting:

    • If canNest: true → Allow dropping modules inside
    • If canNest: false → Block nested drops

🔧 Implementation Plan

Phase 1: Remove CSS Grid ✅

Phase 2: Add Layout Presets 🎨

Phase 3: Module Placement Metadata 🧩

Phase 4: Auto-Placement Logic 🤖

📚 References

Design Inspiration

GoGrab-Modules Integration

✅ Success Criteria

  1. ✅ No CSS Grid - Flexbox-only approach
  2. ✅ 8 Layout Presets - Cover 90% of use cases
  3. ✅ Module Metadata - Placement preferences in manifests
  4. ✅ Smart Auto-Placement - Modules know where they belong
  5. ✅ Flutter-Compatible - All layouts translate to Flutter
  6. ✅ Intuitive UX - Visual preset selector
  7. ✅ Reusable - Modules inside modules (nesting)

Status: 📋 In Design
Next Step: Implement Phase 1 (Remove CSS Grid)
Goal: Platform-agnostic, intuitive, powerful layout system