Widget vs Module Taxonomy - Decision Matrix

Comprehensive guidelines for classifying components as widgets or modules

🏷️ Widget vs Module Taxonomy - Decision Matrix

Last Updated: November 14, 2025
Status: 🎯 ACTIVE GUIDELINES
Purpose: Clear, actionable criteria for component classification

🎯 CORE PRINCIPLE

Widget (Pure UI + I/O Contract) + Functionality (Flows/Logic/State) = Module (Reusable System)

Philosophy: Start simple (widget), promote when complexity requires it (module).

📊 DECISION MATRIX

Quick Reference Table

Component	Start As	Promote When	Example Progression
Input Field	Widget	+ Validation flow	`gg-input` → `validated-input-module`
Select Dropdown	Widget	+ Data source API	`gg-select` → `data-select-module`
Button	Widget	+ Multi-step flow	`gg-button` → `action-button-module`
Card	Widget	+ Contains modules	`gg-card` → `module-card-container`
Badge	Widget	Never (pure UI)	`gg-badge` (stays widget)
Icon	Widget	Never (pure UI)	`gg-icon` (stays widget)
Modal	Module	Always	`modal-module` (immediate)
Sidebar	Module	Always	`sidebar-nav-module` (immediate)
Navigation	Module	Always	`top-nav-module` (immediate)
Data Grid	Module	Always	`data-grid-module` (immediate)
Form (simple)	Widget	+ Validation logic	`gg-form` → `smart-form-module`
Form (multi-step)	Module	Always	`wizard-form-module` (immediate)
Chart	Widget	+ Live data source	`gg-chart` → `live-chart-module`
Calendar	Widget	+ Event management	`gg-calendar` → `event-calendar-module`

🔍 CLASSIFICATION CRITERIA

Widget Definition

A widget is:

✅ Pure presentational component
✅ Has @Input/@Output for data binding
✅ No complex internal state
✅ No routing or navigation
✅ No direct API calls
✅ No lifecycle business logic
✅ Reusable across multiple contexts
✅ Can be embedded anywhere

Widget Characteristics:

@Component({
  selector: 'gg-input',
  standalone: true,
  template: '<input [value]="value" (input)="valueChange.emit($event.target.value)" />',
  inputs: ['value', 'placeholder', 'disabled', 'type'],
  outputs: ['valueChange', 'blur', 'focus']
})
export class GgInputWidget {
  // Pure UI logic only
  // No business logic
  // No API calls
  // No complex state
}

Module Definition

A module is:

✅ Self-contained functional unit
✅ Has manifest describing capabilities
✅ May have complex internal state
✅ May have routing
✅ May make API calls
✅ May contain other modules
✅ Has lifecycle management
✅ Registered with ModuleRegistry

Module Characteristics:

@Component({
  selector: 'lib-validated-input',
  standalone: true,
  template: `
    <gg-input [value]="value()" (valueChange)="onChange($event)"></gg-input>
    <div *ngIf="error()">{{ error() }}</div>
  `
})
export class ValidatedInputModule implements BrowserModuleContract {
  readonly manifest: ModuleManifest = {
    id: 'validated-input',
    name: 'Validated Input',
    type: 'feature',
    actions: ['validate', 'reset', 'getValue'],
    flows: ['validation-flow']
  };
  
  // Business logic
  async validate(): Promise<boolean> { /* ... */ }
  
  // Flow integration
  private attachedFlows: string[] = [];
  
  // Complex state
  private validationState = signal<ValidationState>({ /* ... */ });
}

🚦 PROMOTION TRIGGERS

Automatic Promotion (Any of these → Module)

Singularity Integration ⚡

// Widget with attached flow = Module
if (component.hasAttachedFlows) {
  classify = 'module';
}

Routing 🗺️

// Component with routes = Module
if (component.hasRoutes) {
  classify = 'module';
}

Child Modules 🧩

// Component containing modules = Module
if (component.containsModules) {
  classify = 'module';
}

Backend Integration 🌐

// Component making API calls = Module
if (component.hasApiCalls) {
  classify = 'module';
}

Complex State 💾

// Component with persistence/sync = Module
if (component.usesStorage || component.hasFlashState) {
  classify = 'module';
}

Lifecycle Logic 🔄

// Component with business logic in lifecycle = Module
if (component.hasBusinessLogicInLifecycle) {
  classify = 'module';
}

Manual Promotion (Architectural Decision)

Strategic Importance - Core platform capability
Reusability Across Universes - Used in multiple projects
Marketplace Potential - Could be sold/shared
Team Collaboration - Multiple developers need to extend

📁 STORAGE STRUCTURE

Widget Storage

Location: libs/libs-ui/ or libs/widgets/

libs/
├── libs-ui/
│   ├── gg-input/
│   ├── gg-button/
│   ├── gg-select/
│   ├── gg-card/
│   └── gg-badge/
│
└── widgets/
    ├── chart-widget/
    ├── calendar-widget/
    └── table-widget/

Characteristics:

Simple folder structure
No manifest file
Export from index.ts
Used via direct import

Module Storage

Location: libs/libs-structural/ or libs/libs-module-features/

libs/
├── libs-structural/
│   ├── sidebar-nav-lib/
│   │   ├── src/
│   │   └── sidebar-nav.manifest.ts  ← Has manifest
│   │
│   ├── modal-system-lib/
│   │   ├── src/
│   │   └── modal.manifest.ts
│   │
│   └── data-grid-lib/
│       ├── src/
│       └── data-grid.manifest.ts
│
└── libs-module-features/
    ├── validated-input-lib/
    │   ├── src/
    │   └── validated-input.manifest.ts
    │
    └── smart-form-lib/
        ├── src/
        └── smart-form.manifest.ts

Characteristics:

NX library with manifest
Registered with ModuleRegistry
Appears in module-browser
Can be assigned to sections

🔄 PROMOTION WORKFLOW

Step 1: Identify Promotion Need

// Widget starts simple
@Component({
  selector: 'gg-input'
})
export class GgInputWidget { }

// Developer adds validation logic
this.validationService.validate(value);

// 🚨 PROMOTION TRIGGER: Business logic added!

Step 2: Create Module Version

# Create new NX library
nx generate @nx/angular:library validated-input-lib \
  --directory=libs/libs-module-features \
  --standalone

# Move widget code
# Add manifest
# Add business logic
# Register with ModuleRegistry

Step 3: Implement Module Contract

@Component({
  selector: 'lib-validated-input',
  standalone: true
})
export class ValidatedInputModule implements BrowserModuleContract {
  
  // Required: Module ID
  readonly moduleId = 'validated-input';
  
  // Required: Manifest
  readonly manifest: ModuleManifest = {
    id: 'validated-input',
    name: 'Validated Input Field',
    type: 'feature',
    category: 'Form Components',
    version: '1.0.0',
    author: 'GoGrab Team',
    
    // What this module can do
    actions: [
      'validate',
      'getValue',
      'setValue',
      'reset'
    ],
    
    // Attached flows
    flows: ['validation-flow'],
    
    // Access control
    access: {
      visibility: 'public',
      audience: 'space-builder',
      showInBrowser: true,
      showInSelector: true
    }
  };
  
  // Lifecycle methods
  async initialize(): Promise<void> { }
  async start(): Promise<void> { }
  async stop(): Promise<void> { }
  async destroy(): Promise<void> { }
  
  // Public actions
  async validate(): Promise<boolean> { }
  async getValue(): Promise<any> { }
  async setValue(value: any): Promise<void> { }
  async reset(): Promise<void> { }
}

Step 4: Register Module

// In manifest file or module decorator
@ModuleDecorator({
  id: 'validated-input',
  name: 'Validated Input',
  type: 'feature'
})
export class ValidatedInputModule { }

// Auto-registers with ModuleRegistry on app init

Step 5: Deprecate Widget (Optional)

// Mark widget as deprecated
@Component({
  selector: 'gg-input',
  /**
   * @deprecated Use ValidatedInputModule instead
   * @see libs/libs-module-features/validated-input-lib
   */
})
export class GgInputWidget { }

📋 CLASSIFICATION EXAMPLES

Example 1: Input Field Progression

Stage 1: Simple Widget

@Component({ selector: 'gg-input' })
export class GgInputWidget {
  @Input() value: string = '';
  @Input() placeholder: string = '';
  @Output() valueChange = new EventEmitter<string>();
}
// Classification: WIDGET ✅

Stage 2: With Validation (Promotion Trigger)

export class GgInputWidget {
  @Input() value: string = '';
  @Input() validators: ValidatorFn[] = [];
  
  validate() {
    // Business logic added!
    return this.validators.every(v => v(this.value));
  }
}
// Classification: Should be MODULE ⚠️

Stage 3: As Module

@Component({ selector: 'lib-validated-input' })
export class ValidatedInputModule implements BrowserModuleContract {
  manifest: ModuleManifest = { /* ... */ };
  
  async validate(): Promise<boolean> {
    // Use singularity flow
    return await this.flowExecutor.execute('validation-flow', { value });
  }
}
// Classification: MODULE ✅

Example 2: Data Grid

Always a Module (Complex state + API + Pagination)

@Component({ selector: 'lib-data-grid' })
export class DataGridModule implements BrowserModuleContract {
  manifest: ModuleManifest = {
    id: 'data-grid',
    type: 'feature',
    actions: ['load', 'sort', 'filter', 'export']
  };
  
  // API integration
  async loadData(endpoint: string) { }
  
  // State management
  private dataState = signal<GridState>({ /* ... */ });
  
  // Pagination logic
  async changePage(page: number) { }
}
// Classification: MODULE ✅ (Always)

Example 3: Modal System

Always a Module (Lifecycle + Overlay + State)

@Component({ selector: 'lib-modal' })
export class ModalModule implements BrowserModuleContract {
  manifest: ModuleManifest = {
    id: 'modal-system',
    type: 'layout',
    actions: ['open', 'close', 'confirm']
  };
  
  // Lifecycle management
  async open() { }
  async close() { }
  
  // Complex interactions
  async confirm(): Promise<boolean> { }
}
// Classification: MODULE ✅ (Always)

🎨 UI LIBRARY AUDIT

Current libs/libs-ui/ Inventory

Pure Widgets (Keep as Widgets):

✅ gg-button - Pure UI
✅ gg-input - Pure UI
✅ gg-select - Pure UI
✅ gg-badge - Pure UI
✅ gg-chip - Pure UI
✅ gg-icon - Pure UI
✅ gg-avatar - Pure UI
✅ gg-spinner - Pure UI
✅ gg-tooltip - Pure UI
✅ gg-divider - Pure UI

Candidates for Promotion:

⚠️ gg-form → smart-form-module (if validation added)
⚠️ gg-table → data-grid-module (if pagination/sort added)
⚠️ gg-chart → live-chart-module (if live data added)
⚠️ gg-calendar → event-calendar-module (if events added)
⚠️ gg-dropdown-menu → menu-module (if navigation added)
⚠️ gg-tab-group → tab-module (if routing added)

Already Modules (Move to libs-structural):

🔄 gg-modal → modal-system-lib
🔄 gg-sidebar → sidebar-nav-lib (already done ✅)
🔄 gg-navigation → navigation-module-lib
🔄 gg-panel → panel-module-lib

🚀 IMPLEMENTATION STRATEGY

Phase 1: Classification (Week 1)

Audit all components in libs/libs-ui/
Classify each as widget/module/candidate
Document promotion triggers hit
Create promotion backlog

Phase 2: Promote Critical Components (Week 2)

Modal → modal-system-lib
Navigation → navigation-module-lib
Data Grid → data-grid-lib
Panel → panel-module-lib

Phase 3: Create Widget-Builder (Week 3)

Tool to create simple widgets
Tool to promote widgets to modules
Automatic manifest generation
ModuleRegistry integration

Phase 4: Documentation (Week 4)

Widget creation guide
Module promotion guide
Decision matrix poster
Training materials

📊 SUCCESS METRICS

Classification Clarity

100% of components classified
Zero ambiguity in decision matrix
Clear promotion triggers documented
Team aligned on philosophy

Technical Implementation

All modules registered with ModuleRegistry
All modules appear in module-browser
Widget-builder operational
Promotion workflow automated

Developer Experience

Widget creation: < 5 minutes
Module promotion: < 30 minutes
Clear guidelines: No confusion
Automated tooling: Minimal manual work

📚 RELATED DOCUMENTS

Decisions: DECISIONS-REFRESHED-NOV-2025.md
Foundation Review: FOUNDATION-REVIEW-NOV-2025.md
Module System: BREAKTHROUGH-MODULES-ARE-STRUCTURE.md
Master Plan: ULTIMATE-PLATFORM-BUILDER-MASTER-PLAN.md

Status: ✅ GUIDELINES COMPLETE
Next Action: Begin component classification audit
Owner: Development Team + UX Team
Last Updated: November 14, 2025