Widget System Sync Plan

Plan to sync the new widget-system library from gograb-space to editor monorepo

🔄 Widget System Sync Plan

Date: October 31, 2025
Status: 🎯 READY TO EXECUTE
Priority: 🔥 CRITICAL - Blocks Phase 4 completion

📊 Executive Summary

The gograb-space team has created a revolutionary new widget system (@gograb-space/widget-system) with 7,000+ lines of production-ready code. This library needs to be synced to the editor monorepo to:

Enable Phase 4 (Widget System Enhancement) completion
Unify widget implementation across both monorepos
Provide foundation for AI-generated modules
Support dynamic widget composition in canvases

🎯 What's Being Synced

From gograb-space Monorepo

libs/core/widget-system/
├── src/
│   ├── lib/
│   │   ├── base/
│   │   │   └── base-widget.component.ts (259 lines)
│   │   ├── components/
│   │   │   ├── widget-container/ (118 lines + templates)
│   │   │   ├── widget-error/ (42 lines + templates)
│   │   │   ├── widget-grid/ (233 lines + templates)
│   │   │   └── widget-placeholder/ (24 lines + templates)
│   │   ├── models/
│   │   │   ├── grid-config.interface.ts
│   │   │   ├── widget-lifecycle.interface.ts
│   │   │   ├── widget-state.interface.ts
│   │   │   └── widget-event.ts
│   │   └── services/
│   │       ├── widget-communication.service.ts (207 lines)
│   │       └── widget-layout.service.ts (221 lines)
│   └── index.ts (barrel exports)
├── tests/
│   ├── base-widget.component.test.ts (653 lines)
│   ├── widget-container.component.test.ts (585 lines)
│   ├── widget-grid.component.test.ts (467 lines)
│   ├── widget-layout.service.test.ts (572 lines)
│   └── widget-system-integration.test.ts (687 lines)
├── project.json
├── package.json
├── tsconfig.json
├── tsconfig.lib.json
├── tsconfig.spec.json
├── vite.config.mts
├── ng-package.json
└── README.md (716 lines)

Total: ~7,000 lines of code, tests, and documentation

✅ Pre-Sync Checklist

Required Before Sync

Editor monorepo is clean (no uncommitted changes)
All existing builds are passing
Gograb-space commits identified (b776ba9 → 6bfd437)
Understanding of widget system architecture
Backup of current widgets library (optional)

Dependencies Verified

@libs-core/module-base exists
@libs-core/log-system exists
@angular/core ^20.x
rxjs workspace:*

🚀 Sync Steps

Step 1: Copy Widget System Library (15 minutes)

# Navigate to editor monorepo
cd /Users/fguijarro/developer/repos/editor

# Create widget-system directory
mkdir -p libs/core/widget-system

# Copy from gograb-space (adjust path as needed)
cp -r /Users/fguijarro/developer/repos/gograb-space/libs/core/widget-system/* \
      libs/core/widget-system/

# Verify files copied
ls -la libs/core/widget-system/

Expected Result: All files present in libs/core/widget-system/

Step 2: Update Import Paths (10 minutes)

All imports need to change from @gograb-space/* to @libs-core/*:

# Find all imports to update
cd libs/core/widget-system
grep -r "@gograb-space" src/

# Replace imports (or do manually)
find src/ -name "*.ts" -exec sed -i '' 's/@gograb-space/@libs-core/g' {} \;

Files to Check:

src/lib/base/base-widget.component.ts
src/lib/services/widget-communication.service.ts
src/lib/services/widget-layout.service.ts
All test files

Example Changes:

// Before
import { LoggerService } from '@gograb-space/log-system';
import { ModuleParameterMetadata } from '@gograb-space/module-base';

// After
import { LoggerService } from '@libs-core/log-system';
import { ModuleParameterMetadata } from '@libs-core/module-base';

Step 3: Update tsconfig.base.json (5 minutes)

Add path mapping for the new library:

{
  "compilerOptions": {
    "paths": {
      // ... existing paths ...
      "@libs-core/widget-system": ["libs/core/widget-system/src/index"],
      "@libs-core/widget-system/*": ["libs/core/widget-system/src/*"]
    }
  }
}

File: editor/tsconfig.base.json

Step 4: Update Library Configuration (10 minutes)

package.json

Update peer dependencies if needed:

{
  "peerDependencies": {
    "@angular/common": "^20.1.0",
    "@angular/core": "^20.1.0",
    "@libs-core/module-base": "workspace:*",
    "@libs-core/log-system": "workspace:*",
    "rxjs": "workspace:*"
  }
}

project.json

Verify build configuration is compatible with editor monorepo standards.

tsconfig.lib.json

May need to update to match editor's TypeScript configuration patterns.

Step 5: Build Widget System (5 minutes)

# Build the widget-system library
npx nx build widget-system

# Expected: Successful build with no errors

If Errors Occur:

Check import paths are correct
Verify dependencies are built (module-base, log-system)
Check TypeScript configuration

Step 6: Run Tests (10 minutes)

# Run widget-system tests
npx nx test widget-system

# Expected: All tests pass (or skip if tests need adjustment)

Note: Tests may need import path updates or adjustment to work in editor monorepo.

Step 7: Update Existing Widgets Library (20 minutes)

Update libs/widgets to use the new widget-system:

// libs/widgets/src/lib/base/widget-module-base.ts

// Add import
import { BaseWidget } from '@libs-core/widget-system';

// Update widgets to extend BaseWidget where appropriate

Files to Update:

libs/widgets/src/lib/base/widget-module-base.ts
Individual widget components that can benefit from BaseWidget
Widget factory implementations

Step 8: Verification (10 minutes)

Build Verification

# Build all affected libraries
npx nx run-many -t build --projects=widget-system,widgets,demos-lib

# Expected: All builds successful

Import Verification

# Test importing from new library
cd libs/widgets/src
grep -r "@libs-core/widget-system" .

# Expected: Imports work correctly

Linter Verification

# Run linter
npx nx lint widget-system
npx nx lint widgets

# Expected: No linter errors

🧪 Testing Plan

Unit Tests

Run npx nx test widget-system
Verify all widget-system tests pass
Run npx nx test widgets
Verify existing widget tests still pass

Integration Tests

Test BaseWidget in a simple component
Test widget-container with existing widgets
Test widget-grid layout
Test widget communication between widgets

Manual Tests

Load widgets in Editor canvas
Verify widget lifecycle hooks work
Test widget events and communication
Test widget grid layout

📚 Documentation Updates

Documents to Create

libs/core/widget-system/README.md - Already exists (716 lines)
Widget system architecture guide
Widget migration guide for existing widgets
Widget best practices guide

Documents to Update

progress-tracking.md - Updated with widget system status
phase-4-widget-system.md - Update with sync details
Main Lambo Builder plan - Reflect accelerated progress

🚨 Potential Issues & Solutions

Issue 1: Import Path Mismatches

Problem: Some imports may not resolve correctly
Solution: Use find/replace to systematically update all imports
Command: find src/ -name "*.ts" -exec sed -i '' 's/@gograb-space/@libs-core/g' {} \;

Issue 2: Dependency Version Mismatches

Problem: Widget system may expect different versions
Solution: Check package.json and align versions with editor standards

Issue 3: TypeScript Configuration Differences

Problem: TypeScript compiler options may differ
Solution: Update tsconfig.lib.json to match editor's patterns

Issue 4: Test Framework Differences

Problem: Tests may use different testing utilities
Solution: Update test imports or adapt tests to editor's testing setup

Issue 5: Build System Differences

Problem: Nx configuration may differ
Solution: Update project.json to match editor's build patterns

✅ Completion Checklist

Code Sync

All files copied from gograb-space
All import paths updated to @libs-core
tsconfig.base.json updated with path mappings
package.json peer dependencies correct
project.json build configuration verified

Build & Test

npx nx build widget-system passes
npx nx test widget-system passes (or adapted)
npx nx lint widget-system passes
Existing widgets library still builds
Integration tests pass

Integration

Existing widgets can import from widget-system
BaseWidget works with widget components
Widget services accessible
Widget models accessible

Documentation

README.md verified
Widget system guide created
Migration guide created
Progress tracker updated

📊 Success Metrics

Quantitative

✅ Zero build errors
✅ Zero linter errors
✅ All tests passing (or adapted)
✅ 100% of imports resolved

Qualitative

✅ Widget system architecture understood
✅ Clear migration path for existing widgets
✅ Team confident in using new system
✅ Documentation clear and comprehensive

🎯 Post-Sync Actions

Immediate (Same Day)

Update progress tracker with sync results
Document any issues encountered
Create migration guide for widgets

Short-term (1-2 Days)

Migrate 1-2 existing widgets to new system as proof of concept
Test integrated widgets in Editor canvas
Update widget documentation

Medium-term (3-7 Days)

Migrate remaining widgets to new system
Update Modularity tool to use widget-system
Enable widget selection in module packager
Connect canvases to widget-system

💡 Tips & Best Practices

During Sync

Copy entire directory first, then make changes
Commit after each major step (copy, imports, build)
Test frequently - don't wait until the end
Document issues as they arise

After Sync

Create examples showing how to use new system
Communicate changes to team
Monitor for issues in existing functionality
Iterate quickly on problems

📞 Support & Resources

Documentation

gograb-space widget-system README: 716 lines of comprehensive docs
gograb-space design.md: 1,606 lines of architecture details
gograb-space requirements.md: 427 lines of specifications
gograb-space tasks.md: 1,036 lines of implementation tasks

Code References

gograb-space commits: b776ba9 → 6bfd437
Widget system location: gograb-space/libs/core/widget-system
Editor location: editor/libs/core/widget-system (after sync)

🏁 Ready to Execute?

Estimated Total Time: 1.5 - 2 hours
Complexity: Medium
Risk Level: Low (new library, doesn't break existing code)
Rollback: Easy (just delete libs/core/widget-system)

Status: ✅ READY - All prerequisites met, plan is clear!

Next Step: Execute Step 1 (Copy Widget System Library)

"Let's bring the widget revolution to the editor monorepo!" 🚀