Phase 0 Analysis - Current State & Requirements

Comprehensive analysis of existing canvas-v2 implementation and required enhancements

Phase 0 Analysis: Current State & Requirements

🎯 Analysis Summary

The canvas-v2 implementation is already quite advanced with excellent foundations in place. This analysis documents what exists, what's missing, and what needs enhancement.

✅ What EXISTS (Excellent Foundation)

1. Type System (`canvas-v2.types.ts`)

Status: ✅ COMPLETE and comprehensive (700+ lines)

Highlights:

Complete CanvasState interface with all required fields
Section interface with responsive overrides already included ✓
AIMetadata interface for training data ✓
ContentConfig for module/widget/page assignment ✓
All layout engines: Flex, Grid, Stack, Absolute ✓
ResponsiveOverrides type defined ✓
DeviceType for breakpoints (mobile, tablet, desktop) ✓

Structure:

export interface Section {
  // ... core fields ...
  content?: ContentConfig;      // ✓ Already supports modules
  responsive: ResponsiveOverrides;  // ✓ Already has responsive!
  ai: AIMetadata;              // ✓ Already has AI metadata!
  // ...
}

export interface ResponsiveOverrides {
  mobile?: Partial<{
    sizing?: Partial<SizingConfig>;
    spacing?: Partial<SpacingConfig>;
    appearance?: Partial<AppearanceConfig>;
    // ... other overrides
  }>;
  tablet?: Partial<{
    // ... same structure
  }>;
}

What's MISSING:

Module placement metadata extension (need to extend ModuleManifest from @libs-core/module-base)

2. CanvasStateService (`canvas-state.service.ts`)

Status: ✅ EXCELLENT - 898 lines, comprehensive

Highlights:

viewMode signal (desktop, tablet, mobile) ✓
canvasMode signal (edit, preview, ai) ✓
selectedSectionId and hoveredSectionId signals ✓
Action history for undo/redo ✓
Auto-save with debouncing (500ms) ✓
Real-time sync with GgStorage ✓
Cross-tab sync detection ✓
Comprehensive CRUD operations ✓

Key Methods:

- loadCanvas(canvasId: string): Promise<void>
- initializeNewCanvas(name: string, type: CanvasType): void
- selectSection(sectionId: string | null): void
- hoverSection(sectionId: string | null): void
- setMode(mode: 'edit' | 'preview' | 'ai'): void
- setViewMode(mode: DeviceType): void
- addSection(parentId: string | null, section: Partial<Section>): string
- updateSection(sectionId: string, updates: Partial<Section>): void
- removeSection(sectionId: string): void
- undo(): void
- redo(): void

What's MISSING:

Responsive-aware update method - Need updateSectionResponsive() that checks viewMode
Module-specific helpers - Methods for module placement and configuration

3. Components

canvas-root.component.ts

Status: ✅ GOOD - Main orchestrator (394 lines)

Highlights:

Uses CanvasStateService ✓
Keyboard shortcuts (Ctrl+Z undo, Ctrl+Shift+Z redo, Delete, Escape) ✓
Exposes all necessary signals ✓
CDK DragDrop already imported ✓

canvas-section.component.ts

Status: ✅ GOOD - Recursive renderer (496 lines)

Highlights:

Recursive section rendering ✓
OnPush change detection ✓
Selection and hover states ✓
Click handling ✓

What's MISSING:

Drop zone capability (cdkDropList)
Module/widget rendering
Mobile-first action toolbar

canvas-toolbar.component.ts

Status: ✅ EXISTS (need to verify features)

canvas-config-panel.component.ts

Status: ✅ EXISTS (need to verify if it's the tabbed version or needs replacement)

4. Services

canvas-actions.service.ts

Status: ✅ EXISTS (need to analyze)

canvas-export.service.ts

Status: ✅ EXISTS (platform export service)

❌ What's MISSING (Needs Implementation)

1. ModulePlacementService ⭐ CRITICAL NEW

Purpose: Intelligent module placement with AI suggestions

Required Methods:

@Injectable({ providedIn: 'root' })
export class ModulePlacementService {
  getSuggestedPlacement(moduleId: string, canvas: CanvasState): PlacementSuggestion[];
  autoPlaceModule(moduleId: string, targetSection?: string): Section;
  validatePlacement(moduleId: string, sectionId: string): PlacementValidation;
  getModulePlacementMetadata(moduleId: string): ModulePlacementMetadata | null;
}

Status: 🔴 NOT IMPLEMENTED

2. Module Placement Metadata Types ⭐ CRITICAL

Need to extend: @libs-core/module-base ModuleManifest

Approach: Create augmentation file

// libs/libs-structural/modular-universe/src/lib/canvas-v2/models/module-placement.types.ts

declare module '@libs-core/module-base' {
  interface ModuleManifest {
    placement?: ModulePlacementMetadata;
  }
}

export interface ModulePlacementMetadata {
  preferredLocation?: 'header' | 'sidebar' | 'content' | 'footer' | 'floating';
  defaultGridArea?: { row: string; column: string; };
  autoSize?: boolean;
  minWidth?: string;
  minHeight?: string;
  maxWidth?: string;
  maxHeight?: string;
  responsive?: {
    mobile?: Partial<ModulePlacementMetadata>;
    tablet?: Partial<ModulePlacementMetadata>;
  };
}

Status: 🔴 NOT IMPLEMENTED

3. ModulePaletteComponent ⭐ CRITICAL NEW

Purpose: Categorized, searchable module browser sidebar

Features Needed:

Load modules from ModuleRegistryService
Category grouping (Structural, Content, Feature)
Search/filter
Drag source (cdkDrag)
Module preview/description

Status: 🔴 NOT IMPLEMENTED

4. Drag-Drop Integration

Current State:

CDK DragDrop imported in canvas-root ✓
NOT implemented in canvas-section

Need to Add:

cdkDropList on canvas-section
cdkDrag on module palette items
Drop event handling
Drag preview/ghost element

Status: 🟡 PARTIAL (imported but not used)

5. CanvasPersistenceService

Analysis: OPTIONAL - May not be needed!

The CanvasStateService already has:

Auto-save with debouncing ✓
Real-time sync ✓
Cross-tab sync ✓
GgStorage integration ✓

Decision: Keep persistence logic in CanvasStateService, add helper methods if needed.

Status: ✅ NOT NEEDED (already in CanvasStateService)

🔧 What Needs ENHANCEMENT

1. CanvasStateService

Add responsive-aware update method:

/**
 * Update section with responsive mode awareness
 * If desktop: updates root properties
 * If mobile/tablet: updates responsive overrides
 */
updateSectionResponsive(
  sectionId: string,
  updates: Partial<Section>,
  viewport?: DeviceType
): void {
  const currentViewport = viewport ?? this.viewMode();
  
  if (currentViewport === 'desktop') {
    // Update root properties
    this.updateSection(sectionId, updates);
  } else {
    // Update responsive overrides
    const section = this.canvasState()?.sectionsMap[sectionId];
    if (!section) return;
    
    const responsiveKey = currentViewport; // 'mobile' or 'tablet'
    const currentOverrides = section.responsive[responsiveKey] || {};
    
    this.updateSection(sectionId, {
      responsive: {
        ...section.responsive,
        [responsiveKey]: {
          ...currentOverrides,
          ...updates
        }
      }
    });
  }
}

2. CanvasSectionComponent

Add:

Drop zone (cdkDropList)
Module rendering (if content.type === 'module')
Mobile-first action toolbar
Drop event handling

Template Enhancement:

<div class="section-container"
     cdkDropList
     [cdkDropListData]="section()"
     (cdkDropListDropped)="onDrop($event)">
  
  <!-- Existing content -->
  
  <!-- NEW: Module rendering -->
  @if (section().content?.type === 'module') {
    <div class="module-container">
      <!-- Render module component here -->
    </div>
  }
  
  <!-- NEW: Mobile-first toolbar -->
  @if (isSelected()) {
    <div class="mobile-toolbar">
      <button (click)="splitHorizontal()">Split H</button>
      <button (click)="splitVertical()">Split V</button>
      <button (click)="addModule()">Add Module</button>
      <button (click)="configure()">Configure</button>
    </div>
  }
</div>

3. canvas-config-panel.component.ts

Need to verify:

Is it the tabbed version from grid-section?
Does it have responsive mode toggle?
Does it have module-specific configuration?

If NOT, replace with section-config-panel from grid-section

📊 Implementation Priority

Phase 1: Critical Foundation (Week 1)

✅ Analyze existing code (THIS DOCUMENT)
🔴 Create module placement types
🔴 Create ModulePlacementService
🔴 Add responsive-aware methods to CanvasStateService

Phase 2: Core Components (Week 2)

🔴 Create ModulePaletteComponent
🔴 Enhance CanvasSectionComponent with drop zones
🔴 Integrate/replace CanvasConfigPanelComponent
🔴 Wire up drag-drop system

Phase 3: Integration & Testing (Week 3)

🔴 Test module placement workflow
🔴 Test responsive editing
🔴 Test persistence
🔴 Add mobile-first toolbars

💡 Key Insights

Excellent Foundations

The canvas-v2 implementation is production-grade quality:

Type system is comprehensive
State management is excellent (signals, undo/redo, persistence)
Component architecture is solid
Integration with storage system is complete

Smart Reuse Strategy

We DON'T need to rebuild everything. We need to:

ADD: ModulePlacementService, ModulePaletteComponent
ENHANCE: CanvasSectionComponent (drop zones), CanvasStateService (responsive methods)
INTEGRATE: Existing components from grid-section where better
WIRE UP: Drag-drop system that's already imported

Low Risk

Because the foundation is solid, the implementation risk is LOW. We're adding features, not rebuilding.

🎯 Next Steps

✅ Complete this analysis document
🔄 Design ModulePlacementService architecture
🔄 Design module placement metadata types
🔄 Update master plan with precise file locations
🔄 Begin Phase 1 implementation

📝 Files to Create

New Files (Priority Order)

libs/libs-structural/modular-universe/src/lib/canvas-v2/models/module-placement.types.ts
libs/libs-structural/modular-universe/src/lib/canvas-v2/services/module-placement.service.ts
libs/libs-structural/modular-universe/src/lib/canvas-v2/components/module-palette/module-palette.component.ts
libs/libs-structural/modular-universe/src/lib/canvas-v2/components/module-palette/module-palette.component.html
libs/libs-structural/modular-universe/src/lib/canvas-v2/components/module-palette/module-palette.component.scss

Files to Modify

libs/libs-structural/modular-universe/src/lib/canvas-v2/services/canvas-state.service.ts - Add responsive-aware methods
libs/libs-structural/modular-universe/src/lib/canvas-v2/components/canvas-section/canvas-section.component.ts - Add drop zones, module rendering
libs/libs-structural/modular-universe/src/lib/canvas-v2/components/canvas-section/canvas-section.component.html - Add drop zone markup
libs/libs-structural/modular-universe/src/lib/canvas-v2/services/index.ts - Export new service
libs/libs-structural/modular-universe/src/lib/canvas-v2/models/index.ts - Export new types
libs/libs-structural/modular-universe/src/lib/canvas-v2/components/index.ts - Export new component

Status: ✅ Phase 0 Analysis Complete
Next: Design detailed service architecture
Confidence: 🔥 VERY HIGH (excellent foundation exists)

Phase 0 Analysis: Current State & Requirements

🎯 Analysis Summary

✅ What EXISTS (Excellent Foundation)

1. Type System (canvas-v2.types.ts)

2. CanvasStateService (canvas-state.service.ts)

3. Components

canvas-root.component.ts

canvas-section.component.ts

canvas-toolbar.component.ts

canvas-config-panel.component.ts

4. Services

canvas-actions.service.ts

canvas-export.service.ts

❌ What's MISSING (Needs Implementation)

1. ModulePlacementService ⭐ CRITICAL NEW

2. Module Placement Metadata Types ⭐ CRITICAL

3. ModulePaletteComponent ⭐ CRITICAL NEW

4. Drag-Drop Integration

5. CanvasPersistenceService

🔧 What Needs ENHANCEMENT

1. CanvasStateService

2. CanvasSectionComponent

3. canvas-config-panel.component.ts

📊 Implementation Priority

Phase 1: Critical Foundation (Week 1)

Phase 2: Core Components (Week 2)

Phase 3: Integration & Testing (Week 3)

💡 Key Insights

Excellent Foundations

Smart Reuse Strategy

Low Risk

🎯 Next Steps

📝 Files to Create

New Files (Priority Order)

Files to Modify

1. Type System (`canvas-v2.types.ts`)

2. CanvasStateService (`canvas-state.service.ts`)