metabuilder/docs/MIGRATION_PHASES.md

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)

---@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

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

{
  "@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

{
  "permissions": {
    "minLevel": 3,
    "requiresDatabase": true,
    "features": {
      "editing": { "minLevel": 4 },
      "deleting": { "minLevel": 5 },
      "admin": { "minLevel": 6 }
    }
  }
}

Component Toggle System

-- 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

---@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

---@class RenderTarget
---@field type "react" | "qml" | "cli"
---@field capabilities table<string, boolean>

---@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