Widget System Architecture - Master Plan

Comprehensive architecture defining Core UI Widgets vs Custom Widgets and Widget-to-Module conversion

🏗️ Widget System Architecture - Master Plan

Last Updated: November 17, 2025
Status: 🎯 MASTER PLAN
Purpose: Define widget system architecture and widget-to-module conversion strategy

🎯 EXECUTIVE SUMMARY

The Core Question

"How do widgets and modules work together in our platform?"

The Answer

Widgets and modules serve different but complementary purposes:

🧩 MODULES (Building Blocks) = Complete Features with Logic + State + Routing
├── Contain multiple widgets
├── Have their own state management
├── Can communicate via ActionRegistry
├── Follow BrowserModuleContract
└── Example: sidebar-nav, top-nav, footer modules

🎨 WIDGETS (UI Components) = Pure Presentation + Basic Interaction
├── Reusable UI elements
├── No business logic (only presentation)
├── Configured via inputs/outputs
├── Live inside modules
└── Example: button, input, card, panel

📊 ARCHITECTURAL HIERARCHY

The Complete Stack

🌌 UNIVERSE (Top Level)
  └── Has Grid System (modular-universe)
      └── Each Section = Module Slot
          ├── 🧩 STRUCTURAL MODULES (navigation, layout containers)
          │   ├── Sidebar Navigation Module
          │   ├── Top Navigation Module  
          │   └── Footer Module
          │
          ├── 🧩 FEATURE MODULES (complete functionality)
          │   ├── User Management Module
          │   ├── E-commerce Cart Module
          │   └── Content Management Module
          │
          └── 🧩 PAGE MODULES (content pages built with editor-web-lib)
              └── Contains Custom Widgets
                  ├── 🎨 CUSTOM WIDGETS (built in widget-builder)
                  │   ├── User Profile Card
                  │   ├── Product Showcase
                  │   └── Feature Section
                  │   └── Built from → CORE UI WIDGETS ↓
                  │
                  └── 🎨 CORE UI WIDGETS (from ux-ui-* libraries)
                      ├── ux-ui-core: button, input, card, chip
                      ├── ux-ui-extended: menu, panel, portal
                      ├── ux-ui-feedback: toast, dialog, modal
                      └── ux-ui-forms: checkbox, select, range

🎨 WIDGET SYSTEM ARCHITECTURE

1. Core UI Widgets (Foundation Layer)

Purpose: Atomic, reusable UI components with NO business logic

Location: libs/libs-ui/ux-ui-* libraries

Characteristics:

✅ Pure presentation components
✅ Highly configurable via inputs
✅ Multiple variants (themes, sizes, states)
✅ Zero business logic
✅ Standalone Angular components
❌ NO state management (StateLESS)
❌ NO routing
❌ NO data fetching

Example - Button Widget:

@Component({
  selector: 'ux-button',
  standalone: true,
  template: `<button [class]="buttonClasses()">{{ label() }}</button>`
})
export class UxButtonComponent {
  label = input<string>('Click me');
  variant = input<'primary' | 'secondary' | 'ghost'>('primary');
  size = input<'sm' | 'md' | 'lg'>('md');
  disabled = input<boolean>(false);
  
  onClick = output<MouseEvent>();
  
  // Computed styles based on inputs
  buttonClasses = computed(() => {
    return `btn btn-${this.variant()} btn-${this.size()}`;
  });
}

Core UI Widget Libraries:

libs/libs-ui/
├── ux-ui-core/         # Buttons, inputs, cards, chips, icons
├── ux-ui-extended/     # Menus, panels, portals, context-menu
├── ux-ui-feedback/     # Toasts, dialogs, modals, alerts
└── ux-ui-forms/        # Checkboxes, selects, ranges, switches

2. Custom Widgets (Composition Layer)

Purpose: Composed widgets combining Core UI Widgets for specific use cases

Location: Created in widget-builder, stored in widgets-manager

Characteristics:

✅ Composition of Core UI Widgets
✅ Specific use case (e.g., "Hero Section", "User Profile Card")
✅ Has visual designer (grid-based layout)
✅ Property Groups for configuration
✅ Variants for different contexts
✅ Can include Singularity flows for interactivity
❌ Still NO complex business logic
❌ NO state management (receives data via inputs)

Example - User Profile Card Widget:

// Generated by widget-builder
@Component({
  selector: 'custom-user-profile-card',
  standalone: true,
  imports: [UxButtonComponent, UxChipComponent, UxCardComponent],
  template: `
    <ux-card variant="elevated">
      <img [src]="avatarUrl()" />
      <h3>{{ userName() }}</h3>
      <p>{{ userBio() }}</p>
      <ux-chip [label]="userRole()" />
      <ux-button 
        label="View Profile" 
        (onClick)="onViewProfile.emit($event)" />
    </ux-card>
  `
})
export class CustomUserProfileCardWidget {
  // Properties from property groups
  avatarUrl = input.required<string>();
  userName = input.required<string>();
  userBio = input<string>('');
  userRole = input<string>('User');
  
  // Events
  onViewProfile = output<void>();
}

Custom Widget Structure:

Custom Widget
├── Grid Layout (defined in visual designer)
├── Core UI Widgets (placed in grid)
├── Property Groups (configuration interface)
├── Variants (different styles/configurations)
└── Singularity Flows (optional interactivity)

🧩 MODULE SYSTEM ARCHITECTURE

What is a Module?

A module = Complete feature with logic, state, and UI

Key Difference from Widgets:

WIDGET:  Data In → Render UI → Events Out
MODULE:  Complete Feature + State + Logic + Routes + API

Module Characteristics

✅ Implements BrowserModuleContract
✅ Has manifest (ModuleManifest)
✅ Can have routes
✅ Has state management (uses storage-system)
✅ Can communicate via ActionRegistry
✅ Contains multiple widgets
✅ Has business logic
✅ Can fetch data

Module Types

type ModuleType = 
  // STRUCTURAL MODULES (layout/navigation)
  | 'navigation'   // TopNav, Sidebar, Footer
  | 'layout'       // Grid containers, sections
  
  // FEATURE MODULES (complete functionality)
  | 'feature'      // Cart, Auth, Search, CRM
  | 'data'         // Data providers, API integrations
  
  // CONTENT MODULES
  | 'page'         // Content pages (built with editor-web-lib)
  
  // LOGIC MODULES
  | 'flow'         // Singularity logic flows
  
  // WIDGET MODULES
  | 'widget';      // ⚠️ When widgets need to become modules

🔄 WIDGET-TO-MODULE CONVERSION STRATEGY

When Should a Widget Become a Module?

Keep as Widget if:

✅ Pure presentation
✅ No state management needed
✅ No routing needed
✅ No complex business logic
✅ Just needs data in/events out

Convert to Module if:

⚠️ Needs internal state management
⚠️ Needs to communicate with other modules
⚠️ Needs routing
⚠️ Needs to fetch data
⚠️ Has complex business logic
⚠️ Needs to be discoverable in module registry

Conversion Process

Step 1: Identify the Need

User creates "Shopping Cart" widget
→ Realizes it needs to:
  - Store cart state
  - Sync with backend
  - Communicate with checkout module
  - Have its own routes (/cart, /cart/checkout)
→ Time to convert to module!

Step 2: Conversion Tool (Widget-to-Module Generator)

Location: libs/libs-widgets/widget-builder (new feature)

Process:

User clicks "Convert to Module" in widget-builder

System generates:

modules/custom-modules/<widget-name>/
├── src/
│   ├── lib/
│   │   ├── components/
│   │   │   └── <widget-name>.component.ts  # Original widget
│   │   ├── services/
│   │   │   └── <widget-name>.service.ts     # State management
│   │   ├── <widget-name>.manifest.ts
│   │   └── <widget-name>.module.ts          # Module wrapper
│   └── index.ts
├── project.json
├── tsconfig.json
└── README.md

Module manifest includes:

{
  id: 'custom-<widget-name>',
  type: 'widget', // Indicates it's a widget-based module
  embeddableComponents: [
    {
      id: '<widget-name>',
      componentType: WidgetComponent,
      category: 'widget'
    }
  ],
  publicActions: {
    // Generated from widget events
  }
}

Step 3: Module Registration

Module registers with ModuleRegistryService
Becomes discoverable in modular-universe
Can be placed in grid sections
Can communicate via ActionRegistry

🎯 REVISED WIDGET SYSTEM COMPONENTS

1. Widget Gallery (widget-showcase/widget-gallery)

Purpose: Browse and demo CUSTOM widgets only

URL: /widgets/gallery

Features:

✅ Browse user-created custom widgets
✅ Filter by category/tags
✅ Preview functionality
✅ Quick access to edit in widget-builder
❌ Does NOT show Core UI Widgets (those are in Widget Guide)

2. Widget Guide (widget-showcase/widget-guide)

Purpose: Documentation and variant creation for CORE UI WIDGETS

URL: /widgets/guide

Features:

✅ Browse all Core UI Widgets (from ux-ui-* libraries)
✅ Interactive demos for each widget
✅ Variant Creator (key feature!)
✅ Usage examples and API reference
✅ Copy code snippets

Variant Creator Flow:

User selects Core UI Widget (e.g., button)
Opens variant creator (widget-demo component)
Adjusts properties (size, color, style)
Names variant (e.g., "CTA Button - Blue")

System generates variant config:

{
  id: 'cta-button-blue-v1',
  baseWidget: 'ux-button',
  properties: {
    variant: 'primary',
    size: 'lg',
    styles: { background: '#3b82f6' }
  }
}

Variant saved to storage-system
Variant appears in widget-builder component palette

3. Widget Builder (widget-builder)

Purpose: Create custom widgets using Core UI Widgets

URL: /widgets/builder

Redesigned Architecture:

A. Three-Panel Layout

┌──────────────┬──────────────────────┬──────────────┐
│              │                      │              │
│   SIDEBAR    │   MAIN CANVAS        │  LIVE PANEL  │
│              │                      │              │
│  (Compact)   │   (Grid Designer)    │  (Preview +  │
│              │                      │   Config)    │
│              │                      │              │
│  - Navigator │   Modes:             │  - Live      │
│  - Component │   • Design           │    Preview   │
│    Palette   │   • Property Bind    │  - Property  │
│  - Quick     │   • Flow Attach      │    Editor    │
│    Stats     │   • Preview          │  - Variants  │
│              │                      │  - Code Gen  │
│              │                      │              │
│  Collapsible │                      │  Collapsible │
└──────────────┴──────────────────────┴──────────────┘

B. Mode-Based Canvas (Inspired by modular-universe)

type WidgetBuilderMode =
  | 'design'          // Grid-based visual designer
  | 'property-bind'   // Connect properties to components
  | 'flow-attach'     // Attach Singularity flows
  | 'preview';        // Live preview with test data

Design Mode:

Empty canvas with grid overlay
Drag Core UI Widgets from palette
Position in grid cells
Resize and align
Similar to modular-universe grid-canvas

Property Bind Mode:

Select widget in canvas
Map property groups to widget inputs
Create computed properties
Set default values

Flow Attach Mode:

Select widget in canvas
Attach Singularity flows to events
Configure flow parameters
Test flows

Preview Mode:

Live widget preview
Test with sample data
Responsive breakpoints
Variant switching

C. Component Palette (Enhanced Sidebar)

Structure:

┌─────────────────────┐
│ 🧩 WIDGET BUILDER   │
│─────────────────────│
│ 📊 Quick Stats      │
│ • 9 Property Groups │
│ • 3 Variants        │
│ • 2 Flows Attached  │
│─────────────────────│
│ 🎨 Component Palette│
│                     │
│ 📦 Core UI Widgets  │
│  ├─ Basics          │
│  │  ├─ Button (5)   │ ← Shows variant count
│  │  ├─ Input (3)    │
│  │  └─ Card (4)     │
│  ├─ Forms           │
│  │  ├─ Checkbox     │
│  │  └─ Select       │
│  └─ Feedback        │
│     ├─ Toast        │
│     └─ Dialog       │
│                     │
│ 🏗️ Custom Widgets   │
│  └─ My Widgets (3)  │
│                     │
│ ⚡ Singularity       │
│  └─ Available Flows │
│─────────────────────│
│ 🧭 Quick Navigation │
│ • Properties →      │
│ • Variants →        │
│ • Flows →           │
│ • Code →            │
└─────────────────────┘

Key Improvements:

✅ Grouped by category
✅ Shows variant count
✅ Quick navigation to tabs
✅ Collapsible sections
✅ Search/filter
✅ Drag-and-drop to canvas

D. Live Panel (Always Visible)

Combines preview + configuration

┌──────────────────────┐
│ 🎬 LIVE PREVIEW      │
│──────────────────────│
│ ┌──────────────────┐ │
│ │                  │ │
│ │  Widget renders  │ │
│ │  here in         │ │
│ │  real-time       │ │
│ │                  │ │
│ └──────────────────┘ │
│ Breakpoint: 📱 💻 🖥️  │
│──────────────────────│
│ ⚙️ CONFIGURATION     │
│──────────────────────│
│ Tabs: [Props][Vars]  │
│                      │
│ Active Property:     │
│ • Name: User Name    │
│ • Type: string       │
│ • Default: ""        │
│ • Required: ✓        │
│──────────────────────│
│ 📋 Quick Info        │
│ • Total Props: 9     │
│ • Total Variants: 3  │
│ • Last Saved: 2m ago │
└──────────────────────┘

Benefits:

✅ No need for separate preview tab
✅ See changes in real-time
✅ Configure while previewing
✅ Context-aware (shows selected component's properties)

💾 FLASH PERSISTENCE STRATEGY

Complete State to Persist

interface WidgetBuilderWorkspaceState {
  // Widget definition
  widgetId: string;
  widgetName: string;
  widgetType: CoreWidgetType;
  widgetDescription: string;
  
  // Design
  gridLayout: GridLayout;
  components: DesignElement[];
  
  // Configuration
  propertyGroups: PropertyGroup[];
  propertyValues: WidgetPropertyValues;
  variants: WidgetVariant[];
  flows: FlowBinding[];
  
  // UI State (CRITICAL - currently missing!)
  uiState: {
    activePanel: 'design' | 'properties' | 'variants' | 'code' | 'preview';
    activeMode: WidgetBuilderMode;
    sidebarCollapsed: boolean;
    livePanelCollapsed: boolean;
    expandedSections: string[];
    selectedComponentId: string | null;
    activeVariantId: string | null;
    codeViewMode: 'component' | 'template' | 'styles' | 'all';
    previewBreakpoint: 'mobile' | 'tablet' | 'desktop';
  };
  
  // Metadata
  lastSaved: number;
  lastModified: number;
  autoSaveEnabled: boolean;
}

Storage Keys

// Current widget workspace
`widget-builder:workspace:${widgetId}`

// UI preferences (global)
`widget-builder:ui-preferences:${userId}`

// Recent widgets
`widget-builder:recent-widgets:${userId}`

// Auto-save backup
`widget-builder:autosave:${widgetId}`

Flash Persistence Implementation

// In widget-builder-workspace.component.ts
import { GgStorage } from '@storage-system';

export class WidgetBuilderWorkspaceComponent {
  private storage = inject(GgStorage);
  
  // Auto-save effect
  private autoSaveEffect = effect(() => {
    const state: WidgetBuilderWorkspaceState = {
      widgetId: this.widgetId(),
      widgetName: this.widgetName(),
      // ... all state
      uiState: {
        activePanel: this.activePanel(),
        activeMode: this.canvasMode(),
        // ... all UI state
      },
      lastSaved: Date.now()
    };
    
    // Flash persistence - saves immediately
    this.storage.set(`widget-builder:workspace:${this.widgetId()}`, state);
  });
  
  // Load state on init
  async ngOnInit() {
    const widgetId = this.route.snapshot.params['widgetId'];
    if (widgetId) {
      const state = await this.storage.get<WidgetBuilderWorkspaceState>(
        `widget-builder:workspace:${widgetId}`
      );
      
      if (state) {
        // Restore complete state
        this.widgetName.set(state.widgetName);
        this.activePanel.set(state.uiState.activePanel); // ← RESTORE UI STATE!
        this.canvasMode.set(state.uiState.activeMode);
        // ... restore everything
      }
    }
  }
}

🎯 IMPLEMENTATION ROADMAP

Phase 1: Core UI Widget Separation (Week 1)

Move Core UI Widget demos to Widget Guide
Remove Core UI Widgets from Widget Gallery
Implement variant creator in widget-demo
Connect variants to storage-system

Phase 2: Widget Builder Redesign (Week 2-3)

Implement three-panel layout
Add mode-based canvas system
Create grid-based visual designer
Redesign sidebar with component palette
Implement live panel (preview + config)

Phase 3: Flash Persistence (Week 3)

Add complete UI state to persistence
Implement auto-save with UI state
Add restore functionality
Test cross-tab synchronization

Phase 4: Widget-to-Module Conversion (Week 4)

Design conversion UI
Implement module generator
Create module scaffold
Add to module registry
Document workflow

Phase 5: Integration & Polish (Week 5)

Integrate with modular-universe
Test end-to-end workflow
Performance optimization
Documentation
Training materials

🎨 KEY DESIGN PRINCIPLES

1. Separation of Concerns

Core UI Widgets → Basic building blocks (ux-ui-*)
Custom Widgets  → Composed for specific use cases (widget-builder)
Modules         → Complete features with logic (modules/)

2. Progressive Enhancement

Start Simple  → Use Core UI Widget variants
Need More     → Create Custom Widget in builder
Complex Logic → Convert to Module

3. Reusability First

Everything is reusable at every level:
- Core UI Widgets have variants
- Custom Widgets are templates
- Modules are self-contained

4. AI-Trainable Architecture

Clear patterns at every level make AI training effective:
- Core UI Widgets: Learn from existing components
- Custom Widgets: Learn from user creations
- Modules: Learn from module manifests

📚 RELATED DOCUMENTATION

Status: 🎯 Ready for Implementation
Next Steps: Begin Phase 1 - Core UI Widget Separation