From 1ebe3baa91e882c7052408814ddfa6c87255dce9 Mon Sep 17 00:00:00 2001 From: Richard Ward Date: Tue, 30 Dec 2025 14:43:38 +0000 Subject: [PATCH] docs: phases,migration (1 files) --- MIGRATION_PHASES.md | 400 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 400 insertions(+) create mode 100644 MIGRATION_PHASES.md diff --git a/MIGRATION_PHASES.md b/MIGRATION_PHASES.md new file mode 100644 index 000000000..5cd4d05b7 --- /dev/null +++ b/MIGRATION_PHASES.md @@ -0,0 +1,400 @@ +# MetaBuilder Migration Phases +**Master Plan for UI Migration & Package Enhancement** + +**Created:** 2025-12-30 +**Status:** Active +**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 | 332+ icons | 400+ icons | +| fakemui components | ~150 | 200+ (full MUI parity) | +| Lua packages typed | ~8 | All packages | +| Lua packages tested | ~8 | All packages | +| TSX to Lua conversion | ~40% | 95% | + +--- + +## 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