# MetaBuilder Migration Phases **Master Plan for UI Migration & Package Enhancement** **Created:** 2025-12-30 **Updated:** 2025-12-30 **Status:** Active - Phase 1 & 2 In Progress **Goal:** Complete migration to fakemui + Lua packages, eliminate dependencies --- ## Executive Summary | Goal | Current State | Target | |------|---------------|--------| | @mui/material | In use | ❌ Removed | | @mui/icons-material | ✅ Eliminated from source | ✅ Complete | | @phosphor-icons/react | In package.json | ❌ Removed | | fakemui icons | 357+ icons | 400+ icons | | fakemui components | ~155 (TreeView added) | 200+ (full MUI parity) | | Lua packages typed | 16+ packages | All packages | | Lua packages tested | 20+ packages | All packages | | TSX to Lua conversion | ~40% | 95% | ### Recent Progress (2025-12-30) - ✅ Created types.lua for: admin_dialog, form_builder, schema_editor, data_table, nav_menu, dashboard, workflow_editor, stats_grid - ✅ Added 25+ new fakemui icons (formatting, charts, communication, status) - ✅ Added TreeView component to fakemui/data-display - ✅ Updated fakemui/icons/index.ts with all new exports --- ## Phase Overview ``` ┌─────────────────────────────────────────────────────────────────┐ │ PHASE 1: Foundation Enhancement [Week 1] │ │ - Add missing fakemui icons │ │ - Add missing fakemui components │ │ - Create Monaco/Markdown fakemui components │ ├─────────────────────────────────────────────────────────────────┤ │ PHASE 2: Lua Package Types [Week 1-2] │ │ - Add LuaCATS annotations to all packages │ │ - Create types.lua for each package │ │ - Cross-reference with shared/types/ │ ├─────────────────────────────────────────────────────────────────┤ │ PHASE 3: Parameterized Tests [Week 2] │ │ - Add .test.lua and .cases.json to all packages │ │ - Use lua_test framework │ │ - Achieve 80%+ coverage │ ├─────────────────────────────────────────────────────────────────┤ │ PHASE 4: Package Validator Compliance [Week 2-3] │ │ - Run package_validator on all packages │ │ - Fix any validation errors │ │ - Update validator if needed │ ├─────────────────────────────────────────────────────────────────┤ │ PHASE 5: TSX to Lua Conversion [Week 3-4] │ │ - Convert hardcoded TSX components to Lua │ │ - Create new packages as needed │ │ - Remove MUI imports │ ├─────────────────────────────────────────────────────────────────┤ │ PHASE 6: Dependency Cleanup [Week 4] │ │ - Remove @mui/* from package.json │ │ - Remove @emotion/* from package.json │ │ - Remove @phosphor-icons/react │ │ - Verify app still renders │ ├─────────────────────────────────────────────────────────────────┤ │ PHASE 7: Permission System [Week 5] │ │ - Add database toggle to packages │ │ - Add component on/off switches │ │ - Implement minLevel enforcement │ ├─────────────────────────────────────────────────────────────────┤ │ PHASE 8: Style System [Week 5-6] │ │ - Create CSS designer Lua package │ │ - Enable style overlays via seed data │ │ - Theme customization via database │ ├─────────────────────────────────────────────────────────────────┤ │ PHASE 9: Multi-Frontend Support [Week 6-7] │ │ - QT6/QML powered by packages │ │ - CLI frontend integration │ │ - Abstract package rendering │ ├─────────────────────────────────────────────────────────────────┤ │ PHASE 10: Verification & Polish [Week 7-8] │ │ - Playwright E2E tests │ │ - Enable packages one at a time │ │ - Final cleanup and documentation │ └─────────────────────────────────────────────────────────────────┘ ``` --- ## Phase 1: Foundation Enhancement ### 1.1 Missing fakemui Icons Add icons that may still be needed: **Editor Icons:** - [ ] Spellcheck, FormatClear, FormatIndentIncrease, FormatIndentDecrease - [ ] FormatAlignCenter, FormatAlignRight, FormatAlignJustify - [ ] Superscript, Subscript, Strikethrough **Data/Chart Icons:** - [ ] TrendDown, TrendingFlat - [ ] DonutLarge, DonutSmall - [ ] StackedBarChart, StackedLineChart **Communication:** - [ ] Forum, Comment, CommentOutlined - [ ] Announcement, Campaign **Status/Progress:** - [ ] HourglassEmpty, HourglassFull - [ ] Pending, PendingActions - [ ] PublishedWithChanges ### 1.2 Missing fakemui Components **Layout:** - [ ] AspectRatio (maintains aspect ratio) - [ ] Center (centers content) - [ ] Spacer (flexible space) **Inputs:** - [ ] SearchInput (input with search icon) - [ ] PasswordInput (with visibility toggle) - [ ] TagInput (multiple tags) - [ ] Autocomplete (suggestions) **Data Display:** - [ ] DataList (definition lists) - [ ] Timeline (event timeline) - [ ] TreeView (hierarchical tree) - [ ] VirtualList (virtualized rendering) **Advanced:** - [ ] Monaco (code editor wrapper) - [ ] MarkdownRenderer (markdown display) - [ ] RichTextEditor (WYSIWYG editor) ### 1.3 Component Gaps Checklist | Component | fakemui | MUI Equivalent | Status | |-----------|---------|----------------|--------| | Autocomplete | ❌ | Autocomplete | Needed | | TreeView | ❌ | TreeView | Needed | | Stepper | ❌ | Stepper | Needed | | SpeedDial | ❌ | SpeedDial | Optional | | Backdrop | ❌ | Backdrop | Needed | | ClickAwayListener | ❌ | ClickAwayListener | Needed | | Popper | ❌ | Popper | Needed | | Transition | ✅ | Transition | Complete | --- ## Phase 2: Lua Package Type Annotations ### Packages Needing Types | Package | types.lua | Status | |---------|-----------|--------| | admin_dialog | ❌ | Needed | | arcade_lobby | ❌ | Needed | | audit_log | ✅ | Complete | | codegen_studio | ❌ | Needed | | code_editor | ✅ | Complete | | config_summary | ❌ | Needed | | dashboard | ❌ | Needed | | data_table | ❌ | Needed | | dbal_demo | ✅ | Complete | | form_builder | ❌ | Needed | | forum_forge | ✅ | Complete | | github_tools | ✅ | Complete | | irc_webchat | ✅ | Complete | | lua_test | ✅ | Complete | | media_center | ✅ | Complete | | nav_menu | ❌ | Needed | | notification_center | ✅ | Complete | | package_validator | ✅ | Complete | | quick_guide | ❌ | Needed | | role_editor | ❌ | Needed | | schema_editor | ❌ | Needed | | screenshot_analyzer | ✅ | Complete | | shared | ✅ | Complete | | smtp_config | ❌ | Needed | | social_hub | ✅ | Complete | | stats_grid | ❌ | Needed | | stream_cast | ✅ | Complete | | ui_* (all) | ✅ | Complete | | user_manager | ❌ | Needed | | workflow_editor | ❌ | Needed | --- ## Phase 3: Parameterized Tests ### Test Structure Pattern ``` package/seed/scripts/tests/ ├── {module}.test.lua # Test definitions └── {module}.cases.json # Test parameters ``` ### Example Test Pattern (from lua_test) ```lua ---@param case table Test case data ---@field input any Input value ---@field expected any Expected output local function testCase(case) local result = functionUnderTest(case.input) expect(result).toEqual(case.expected) end describe("Module Tests", function() it.each(testCases)("should handle $description", testCase) end) ``` ### Packages Needing Tests | Package | Test Files | Status | |---------|------------|--------| | admin_dialog | ❌ | Needed | | config_summary | ❌ | Needed | | dashboard | ❌ | Needed | | data_table | ❌ | Needed | | form_builder | ❌ | Needed | | nav_menu | ❌ | Needed | | quick_guide | ❌ | Needed | | role_editor | ❌ | Needed | | schema_editor | ❌ | Needed | | smtp_config | ❌ | Needed | | stats_grid | ❌ | Needed | | user_manager | ❌ | Needed | | workflow_editor | ❌ | Needed | --- ## Phase 4: Package Validator Compliance ### Validation Rules (from package_validator) 1. ✅ Valid metadata.json with required fields 2. ✅ components.json array structure 3. ✅ All exported scripts exist 4. ✅ All component types are valid 5. ✅ No circular dependencies 6. ✅ Version follows semver 7. ✅ minLevel in valid range (0-6) ### Run Command ```bash npm run package:validate -- --all ``` --- ## Phase 5: TSX to Lua Conversion ### Priority Order 1. **Viewers** - Read-only data display (easiest) 2. **Editors** - Form-based editing 3. **Complex** - Multi-step workflows ### Files to Convert See MUI_ELIMINATION_PLAN.md for full list (~160 files) --- ## Phase 6: Dependency Cleanup ### Dependencies to Remove ```json { "@emotion/react": "^11.14.0", "@emotion/styled": "^11.14.1", "@mui/icons-material": "^7.3.6", "@mui/material": "^7.3.6", "@mui/x-data-grid": "^8.23.0", "@mui/x-date-pickers": "^8.23.0", "@phosphor-icons/react": "^2.1.10" } ``` ### Estimated Savings - Bundle size: -2-3 MB - Install time: -30 seconds - Build time: -15% --- ## Phase 7: Permission System ### Package-Level Permissions ```json { "permissions": { "minLevel": 3, "requiresDatabase": true, "features": { "editing": { "minLevel": 4 }, "deleting": { "minLevel": 5 }, "admin": { "minLevel": 6 } } } } ``` ### Component Toggle System ```lua -- In package init.lua local enabled_components = config.get("enabled_components", {}) function is_enabled(component_id) return enabled_components[component_id] ~= false end ``` --- ## Phase 8: Style System ### CSS Designer Package ``` packages/css_designer/ ├── seed/ │ ├── metadata.json │ ├── components.json │ └── scripts/ │ ├── init.lua │ ├── theme_manager.lua │ ├── color_picker.lua │ ├── variable_editor.lua │ └── preview.lua ``` ### Theme Override Structure ```lua ---@class ThemeOverride ---@field primary_color string ---@field secondary_color string ---@field background_color string ---@field text_color string ---@field border_radius string ---@field font_family string ``` --- ## Phase 9: Multi-Frontend Support ### Package Rendering Abstraction ```lua ---@class RenderTarget ---@field type "react" | "qml" | "cli" ---@field capabilities table ---@param target RenderTarget ---@param component UIComponent ---@return string Rendered output function render(target, component) if target.type == "react" then return render_react(component) elseif target.type == "qml" then return render_qml(component) elseif target.type == "cli" then return render_cli(component) end end ``` --- ## Phase 10: Verification ### E2E Test Plan 1. Enable one package at a time 2. Run Playwright tests 3. Check for visual regressions 4. Verify functionality 5. Document any issues ### Success Criteria - [ ] All packages pass validation - [ ] All packages have types - [ ] All packages have tests - [ ] Zero MUI imports in codebase - [ ] App renders correctly - [ ] E2E tests pass --- ## Progress Tracking ### Weekly Updates - **Week 1:** Phase 1-2 - **Week 2:** Phase 2-4 - **Week 3:** Phase 4-5 - **Week 4:** Phase 5-6 - **Week 5:** Phase 6-7 - **Week 6:** Phase 7-8 - **Week 7:** Phase 8-9 - **Week 8:** Phase 9-10 ### Completion Notification When all phases complete, create `MIGRATION_COMPLETE.md` with: - Summary of changes - Performance metrics - Breaking changes - Upgrade guide