metabuilder/frontends/codegen/docs/COMPONENT_CONVERSION_ANALYSIS.md

Component Conversion Analysis

Analysis of 68 React Components

After analyzing all 68 organism and molecule components, here's what can be converted to JSON:

Categories

✅ Fully Convertible to JSON (48 components)

These are presentational components with props, conditional rendering, and simple event handlers:

Molecules (35):

1. LabelWithBadge - ✅ Converted
2. LoadingState - ✅ Converted
3. SaveIndicator - ✅ Converted (computed sources replace hook)
4. SearchInput - ✅ Converted
5. AppBranding - Props + conditionals
6. ActionBar - Layout + buttons
7. Breadcrumb - ✅ Already converted
8. DataCard - ✅ Already converted
9. EmptyState - ✅ Already converted
10. EmptyEditorState - ✅ Already converted
11. FileTabs - ✅ Already converted
12. NavigationGroupHeader - Collapse trigger + state
13. NavigationItem - Button with active state
14. PageHeaderContent - Layout composition
15. ToolbarButton - Tooltip + IconButton
16. TreeListHeader - Buttons with events
17. ComponentTreeEmptyState - Config + icon lookup
18. ComponentTreeHeader - Counts + expand/collapse
19. PropertyEditorEmptyState - Config + icon lookup
20. PropertyEditorHeader - Title + count
21. PropertyEditorSection - Collapsible section
22. DataSourceIdField - Input with validation display
23. KvSourceFields - Form fields
24. StaticSourceFields - Form fields
25. ComputedSourceFields - Form fields
26. GitHubBuildStatus - Status display + polling
27. LoadingFallback - Spinner + message
28. MonacoEditorPanel - Layout wrapper (not editor itself)
29. SearchBar - SearchInput wrapper
30. SeedDataManager - Form + buttons (logic in parent)
31. StorageSettings - Form fields
32. TreeCard - Card + tree display
33. TreeFormDialog - Dialog with form (validation in parent)
34. EditorActions - Button group
35. EditorToolbar - Toolbar layout

Organisms (13):

1. AppHeader - ✅ Already converted
2. EmptyCanvasState - ✅ Already converted
3. NavigationMenu - ✅ Already converted
4. PageHeader - ✅ Already converted
5. SchemaEditorLayout - ✅ Already converted
6. SchemaEditorSidebar - ✅ Already converted
7. SchemaEditorCanvas - ✅ Already converted
8. SchemaEditorPropertiesPanel - ✅ Already converted
9. SchemaEditorStatusBar - Status display
10. SchemaEditorToolbar - Toolbar with actions
11. ToolbarActions - Action buttons
12. SchemaCodeViewer - Tabs + code display
13. TreeListPanel - List display

⚠️ Needs Wrapper (Complex Hooks) (12 components)

These use hooks but the hook logic can be extracted to data sources or remain in a thin wrapper:

Molecules (10):

1. BindingEditor - Form with useForm hook → Extract to form state
2. ComponentBindingDialog - Dialog with useForm → Extract to form state
3. DataSourceEditorDialog - Complex form + validation → Wrapper + JSON form
4. PropertyEditor - Dynamic form generation → Computed source for fields
5. ComponentPalette - Search + filter → Computed source
6. CanvasRenderer - Recursive rendering → Could be JSON with loop support
7. ComponentTree - Tree state + drag/drop → State machine in JSON
8. ComponentTreeNodes - Recursive nodes → Loop construct
9. CodeExplanationDialog - Dialog + API call → Dialog JSON + API action
10. DataSourceCard - Card with actions + state → Separate state, JSON layout

Organisms (2):

1. DataSourceManager - Complex CRUD + hook → Extract useDataSourceManager logic
2. JSONUIShowcase - Examples display → Convert examples to JSON schema

❌ Must Stay React (8 components)

These have imperative APIs, complex recursion, or third-party integration:

Molecules (6):

1. LazyMonacoEditor - Monaco integration (refs, imperative API)
2. LazyInlineMonacoEditor - Monaco integration
3. MonacoEditorPanel - Monaco wrapper
4. LazyBarChart - Recharts integration
5. LazyLineChart - Recharts integration
6. LazyD3BarChart - D3.js integration (imperative DOM manipulation)

Organisms (2):

1. SchemaEditor - Complex editor with drag-drop, undo/redo state machine
2. DataBindingDesigner - Visual flow editor with canvas manipulation

Conversion Statistics

Category	Count	Percentage
✅ Fully Convertible	48	71%
⚠️ Needs Wrapper	12	18%
❌ Must Stay React	8	11%
Total	68	100%

Key Insights

1. Most Components Are Presentational

71% of components are pure presentation + simple logic that JSON can handle with:

• Data binding
• Computed sources
• Conditional rendering
• Event actions
• Loops (for lists)

2. Hooks Aren't a Blocker

Even components with hooks like useSaveIndicator can be converted:

• Time-based logic → Computed sources with polling
• Form state → Form data sources
• Local UI state → Page-level state

3. True Blockers

Only 8 components (11%) genuinely need React:

• Third-party library integrations (Monaco, D3, Recharts)
• Complex state machines (drag-drop, undo/redo)
• Imperative DOM manipulation
• Recursive algorithms (though loops might handle some)

4. Wrapper Pattern

The 12 "needs wrapper" components can have thin React wrappers that:

• Extract hooks to data source utilities
• Convert to JSON-configurable components
• Keep complex logic centralized

Example:

// Thin wrapper
export function FormDialogWrapper({ schema, onSubmit }) {
  const form = useForm()
  return <JSONDialog schema={schema} formState={form} onSubmit={onSubmit} />
}

// JSON configures it
{
  "type": "FormDialogWrapper",
  "props": {
    "schema": { "$ref": "./schemas/user-form.json" }
  }
}

Recommended Conversion Priority

Phase 1: Low-Hanging Fruit (35 molecules)

Convert all presentational molecules that are just composition:

• AppBranding, ActionBar, ToolbarButton, etc.
• Impact: Eliminate 51% of React components

Phase 2: Organisms (13)

Convert layout organisms:

• TreeListPanel, SchemaCodeViewer, etc.
• Impact: Eliminate 70% of React components

Phase 3: Extract Hooks (10 molecules)

Create data source utilities and convert:

• BindingEditor, ComponentPalette, etc.
• Impact: Eliminate 85% of React components

Phase 4: Wrappers (2 organisms)

Create thin wrappers for complex components:

• DataSourceManager, JSONUIShowcase
• Impact: 89% conversion

Final State

• 8 React components (third-party integrations + complex editors)
• 60 JSON components (89% of current React code)
• 100% JSON page definitions (already achieved)

Implementation Patterns

Pattern 1: Simple Conversion

// React
export function LabelWithBadge({ label, badge }) {
  return (
    <Flex>
      <Text>{label}</Text>
      {badge && <Badge>{badge}</Badge>}
    </Flex>
  )
}

// JSON
{
  "type": "div",
  "className": "flex gap-2",
  "children": [
    { "type": "Text", "dataBinding": { "children": { "source": "label" } } },
    {
      "type": "Badge",
      "conditional": { "source": "badge", "operator": "truthy" },
      "dataBinding": { "children": { "source": "badge" } }
    }
  ]
}

Pattern 2: Hook Extraction

// React (before)
export function SaveIndicator({ lastSaved }) {
  const { timeAgo, isRecent } = useSaveIndicator(lastSaved)
  return <div>{isRecent ? 'Saved' : timeAgo}</div>
}

// JSON (after) - hook logic → computed source
{
  "dataSources": [
    {
      "id": "isRecent",
      "type": "computed",
      "compute": "(data) => Date.now() - data.lastSaved < 3000"
    }
  ],
  "type": "div",
  "dataBinding": {
    "children": {
      "source": "isRecent",
      "transform": "(isRecent, data) => isRecent ? 'Saved' : data.timeAgo"
    }
  }
}

Pattern 3: Wrapper for Complex Logic

// Thin React wrapper
export function DataSourceManagerWrapper(props) {
  const manager = useDataSourceManager(props.dataSources)
  return <JSONComponent schema={schema} data={manager} />
}

Next Steps

1. ✅ Convert 35 simple molecules to JSON
2. ✅ Convert 13 layout organisms to JSON
3. ⚠️ Extract hooks to utilities for 10 components
4. ⚠️ Create wrappers for 2 complex organisms
5. ❌ Keep 8 third-party integrations as React

Target: 60/68 components in JSON (89% conversion)