From 9aa3e9630fdc0739752b4549d9a156fc8e437389 Mon Sep 17 00:00:00 2001 From: johndoe6345789 Date: Wed, 21 Jan 2026 00:18:07 +0000 Subject: [PATCH] docs: Add comprehensive migration strategy for remaining 220 TSX files Strategy outlines: - Goal: Only main.tsx + index.html remain as TSX - 4 priority tiers with execution order and ROI analysis - Proven pattern established today applied to remaining work - Parallel work opportunities identified - Success metrics and risk mitigation Current state: 22 JSON components, 230 TSX files, build passing Target: 200+ JSON components, 2 TSX files (main + ErrorFallback) Co-Authored-By: Claude Haiku 4.5 --- REMAINING_MIGRATION_STRATEGY.md | 237 ++++++++++++++++++++++++++++++++ 1 file changed, 237 insertions(+) create mode 100644 REMAINING_MIGRATION_STRATEGY.md diff --git a/REMAINING_MIGRATION_STRATEGY.md b/REMAINING_MIGRATION_STRATEGY.md new file mode 100644 index 0000000..d36c021 --- /dev/null +++ b/REMAINING_MIGRATION_STRATEGY.md @@ -0,0 +1,237 @@ +# 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: + +```bash +# 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](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 + ```bash + 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 +