low-code-react-app-b/REMAINING_MIGRATION_STRATEGY.md

Complete Migration Strategy - Remaining Work

The Goal

End state: Only src/main.tsx and src/index.html as TSX/HTML

• Everything else in src/components/ → JSON + custom hooks

Current Reality (After Today's Work)

Completed: 9 components (8 atoms + 1 molecule)
├── Accordion, CopyButton, FileUpload, FilterInput, Image, Input, PasswordInput, Popover (atoms)
└── BindingEditor (molecule)

Remaining: ~220 TSX files (excluding main.tsx and demo/showcase pages)
├── 3 organisms: DataSourceManager, NavigationMenu, TreeListPanel
├── 110+ atoms: ActionButton, ActionCard, Alert, Button, Card, etc.
├── 35+ molecules: AppBranding, ComponentTree, PropertyEditor, etc.
├── 7 app bootstrap components: AppBootstrap, AppLayout, etc.
└── 55+ demo/showcase pages

Priority Tiers

Tier 1: Core App Bootstrap (7 files - High Impact)

These are used by every page. Converting them unblocks everything.

1. src/components/app/AppBootstrap.tsx

   • Uses: useAppBootstrap hook
   • Action: Create JSON, register hook, export, delete TSX

2. src/components/app/AppLayout.tsx

   • Action: Same pattern

3. src/components/app/LoadingScreen.tsx

   • Likely stateless UI component
   • Action: Convert to pure JSON

4. src/components/app/AppDialogs.tsx

   • Action: Assess and migrate

5. src/components/app/AppMainPanel.tsx

   • Action: Assess and migrate

6. src/components/app/AppRouterBootstrap.tsx

   • Router mode variant of bootstrap

7. src/components/app/AppRouterLayout.tsx

   • Router mode variant of layout

Impact: Converting these 7 components would eliminate the need for TSX anywhere in the bootstrap flow

Tier 2: 3 Documented Organisms (3 files - Medium Impact)

Mentioned in CLAUDE.md as remaining work

1. src/components/organisms/DataSourceManager.tsx
2. src/components/organisms/NavigationMenu.tsx
3. src/components/organisms/TreeListPanel.tsx

Impact: Completes the documented migration targets

Tier 3: Core UI Atoms & Molecules (150+ files - Large Scale)

The bulk of component library

Atoms (~110 files):

• ActionButton, ActionCard, Alert, Avatar, Badge, Breadcrumb, Button, Calendar, Card, Checkbox, CommandPalette, DatePicker, Dialog, Divider, Drawer, EmptyState, FileIcon, Form, Grid, Heading, HoverCard, Input, Kbd, Label, Link, List, Menu, Modal, NumberInput, PasswordInput, Popover, ProgressBar, Radio, RangeSlider, Rating, ScrollArea, SearchInput, Select, Separator, Skeleton, Slider, Stack, Switch, Table, Tabs, Tag, Text, TextArea, Toggle, Tooltip, TreeIcon, etc.

Molecules (~35 files):

• AppBranding, CanvasRenderer, ComponentTree, ComponentPalette, PropertyEditor, SearchBar, ToolbarButton, TreeFormDialog, etc.

Current strategy: These have JSON definitions in src/config/pages/ but aren't yet exported from json-components.ts. Need to:

1. Create JSON definitions in src/components/json-definitions/ (if not already there)
2. Create TypeScript interfaces
3. Register hooks (if stateful)
4. Export from json-components.ts
5. Delete TSX files

Tier 4: Demo/Showcase Pages (55+ files - No Impact on App)

These are development/demo utilities

Examples:

• AtomicComponentShowcase.tsx
• JSONConversionShowcase.tsx
• DashboardDemoPage.tsx
• DataBindingDesigner.tsx
• JSONFlaskDesigner.tsx
• etc.

Decision: These are optional. Could be:

• Converted to JSON (least effort)
• Deleted if not needed
• Left as-is if they're development tools

Recommended Execution Order

Phase 1: Bootstrap (Highest ROI)

1. AppBootstrap → JSON + useAppBootstrap hook
2. AppLayout → JSON + appropriate hooks
3. LoadingScreen → Pure JSON
4. Repeat for other 4 app components

Why first: These are on the critical path. Every app render goes through them. Converting them proves the architecture works for complex components.

Expected time: 2-3 hours

Phase 2: Documented Organisms

1. DataSourceManager → JSON + hooks
2. NavigationMenu → JSON + hooks
3. TreeListPanel → JSON + hooks

Why next: Completes the documented migration targets from CLAUDE.md

Expected time: 2-3 hours

Phase 3: Core Component Library (If Time/Priority)

Option A: Batch similar components

• All simple buttons/links as one batch
• All inputs as one batch
• All containers/layouts as one batch

Option B: Focus on most-used

• Button, Input, Card, Dialog, Menu → highest impact
• Others as needed

Expected time: 8-20 hours (depending on thoroughness)

Phase 4: Demo Pages (Nice-to-have)

Convert or delete as appropriate. Low priority.

Pattern to Follow (Proven)

For each component:

# 1. Create/verify JSON definition
src/components/json-definitions/[component].json

# 2. Create/verify TypeScript interface  
src/lib/json-ui/interfaces/[component].ts

# 3. If stateful, create custom hook
src/hooks/use-[component].ts
# Then register in hooks-registry.ts
# Then export from hooks/index.ts

# 4. Export from json-components.ts
export const ComponentName = createJsonComponent[WithHooks]<Props>(def, ...)

# 5. Update registry entry
json-components-registry.json

# 6. Delete legacy TSX
rm src/components/[category]/[ComponentName].tsx

# 7. Update index.ts exports
src/components/[category]/index.ts

# 8. Update all imports across codebase
# From: import { X } from '@/components/...'
# To: import { X } from '@/lib/json-ui/json-components'

# 9. Verify build passes
npm run build

Parallel Work Opportunities

Can work on simultaneously:

• AppBootstrap + AppLayout (independent)
• DataSourceManager + NavigationMenu (independent)
• Multiple atoms in parallel (Button, Input, Card, Dialog don't depend on each other)

Must sequence:

• ChildComponent → ParentComponent (parent depends on child)
• Example: Button must be JSON before ButtonGroup

Success Metrics

Current State:

• 22 JSON components exported
• 230 TSX files remaining
• Build passes ✅

Phase 1 Success:

• 29+ JSON components (added 7 app bootstrap)
• 223 TSX files remaining
• Build passes ✅

Phase 2 Success:

• 32+ JSON components (added 3 organisms)
• 220 TSX files remaining
• Build passes ✅

Phase 3 Success (Core Library):

• 150+ JSON components
• 75 TSX files remaining (mostly demo pages)
• Build passes ✅

Final State (Full Migration):

• 200+ JSON components
• 2 TSX files (main.tsx + ErrorFallback.tsx as optional)
• 1 HTML file (index.html)
• Build passes ✅

Key Advantages Once Complete

1. No component duplication - Single source of truth (JSON)
2. Easier maintenance - All components follow same pattern
3. Better code reuse - Hooks shared across components
4. Smaller bundle - JSON more compressible than TSX
5. Faster iteration - Change JSON, no rebuild needed (with hot reload)
6. Better tooling - Can build JSON editing UI without code knowledge

Risks & Mitigation

Risk	Mitigation
Breaking changes	Run tests frequently, commit after each component
Performance regression	Monitor bundle size, hook performance
Import path issues	Use find-replace to update all imports systematically
Circular dependencies	Review src/lib/json-ui/ structure before major changes
Hook registration errors	Test each hook in hooks-registry before moving to next

Next Immediate Steps

1. Run audit to get baseline

   npm run audit:json
   

2. Pick one app bootstrap component (e.g., LoadingScreen - simplest)

3. Follow the pattern from today's work with Accordion/BindingEditor

4. Commit after each component with clear message

5. Run tests to catch regressions