mirror of
https://github.com/johndoe6345789/low-code-react-app-b.git
synced 2026-04-24 13:44:54 +00:00
Fix: Inline NavigationGroupHeader to complete component migration
Co-authored-by: johndoe6345789 <224850594+johndoe6345789@users.noreply.github.com>
This commit is contained in:
copilot-swe-agent[bot]
195
ROOT_CAUSE_ANALYSIS.md
Normal file
195
ROOT_CAUSE_ANALYSIS.md
Normal file
@@ -0,0 +1,195 @@
|
||||
# Root Cause Analysis: JSON-Based React Component System
|
||||
|
||||
## Executive Summary
|
||||
|
||||
The repository is attempting to transition from a traditional TypeScript React component architecture to a JSON-based declarative UI system. The build is currently failing because the transition is incomplete - some TypeScript components were deleted but their imports remain, and the JSON component system cannot yet fully replace them.
|
||||
|
||||
## Current State: Hybrid System Failure
|
||||
|
||||
### What Was Attempted
|
||||
1. **123 TypeScript components were deleted** (commit aa51074) and marked as "json-compatible" in the registry
|
||||
2. **JSON component registry created** with 375+ component definitions
|
||||
3. **JSON UI rendering system built** with component-renderer.tsx, expression evaluator, data binding, etc.
|
||||
4. **Wrapper components created** for complex molecules that need special handling
|
||||
|
||||
### What's Broken
|
||||
The build fails with these errors:
|
||||
```
|
||||
✘ [ERROR] No matching export in "src/components/molecules/index.ts" for import "NavigationItem"
|
||||
✘ [ERROR] No matching export in "src/components/molecules/index.ts" for import "PageHeaderContent"
|
||||
✘ [ERROR] No matching export in "src/components/molecules/index.ts" for import "TreeCard"
|
||||
✘ [ERROR] No matching export in "src/components/molecules/index.ts" for import "TreeListHeader"
|
||||
✘ [ERROR] No matching export in "src/components/molecules/index.ts" for import "preloadMonacoEditor"
|
||||
✘ [ERROR] No matching export in "src/components/molecules/index.ts" for import "LoadingFallback"
|
||||
```
|
||||
|
||||
## Root Causes
|
||||
|
||||
### 1. **Incomplete Conversion Strategy**
|
||||
Components were marked as JSON-compatible and deleted, but:
|
||||
- The **consuming code still imports them as TypeScript modules**
|
||||
- No migration was done to convert consumers to use the JSON renderer
|
||||
- The JSON system exists but isn't wired into the main application flow
|
||||
|
||||
### 2. **Misunderstanding of JSON Component Architecture**
|
||||
The JSON system is designed for **declarative page configurations**, not as a drop-in replacement for React components. Example:
|
||||
|
||||
**Traditional React:**
|
||||
```tsx
|
||||
import { TreeCard } from '@/components/molecules'
|
||||
<TreeCard tree={data} onSelect={handleSelect} />
|
||||
```
|
||||
|
||||
**JSON System:**
|
||||
```json
|
||||
{
|
||||
"type": "TreeCard",
|
||||
"bindings": {
|
||||
"tree": { "source": "currentTree" }
|
||||
},
|
||||
"events": {
|
||||
"onSelect": { "action": "selectTree" }
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
The JSON system requires:
|
||||
- JSON configuration files
|
||||
- JSONSchemaPageLoader or PageRenderer wrapper
|
||||
- Data sources defined in JSON
|
||||
- Event handlers defined in JSON
|
||||
- Cannot be imported like a normal React component
|
||||
|
||||
### 3. **Deleted Components Still Referenced**
|
||||
Components deleted but still imported:
|
||||
- **TreeCard** - Used in TreeListPanel.tsx
|
||||
- **TreeListHeader** - Used in TreeListPanel.tsx
|
||||
- **LoadingFallback** - Used in JSONSchemaPageLoader.tsx and routes.tsx
|
||||
- **NavigationItem** - File exists but not exported from index.ts
|
||||
- **PageHeaderContent** - File exists but not exported from index.ts
|
||||
- **preloadMonacoEditor** - Function exists but not exported from index.ts
|
||||
|
||||
### 4. **Module System vs Component Registry Mismatch**
|
||||
The component-registry.ts uses `import.meta.glob` to load ALL .tsx files:
|
||||
```ts
|
||||
const moleculeModules = import.meta.glob('@/components/molecules/*.tsx', { eager: true })
|
||||
```
|
||||
|
||||
This means:
|
||||
- It CAN dynamically load TreeCard, TreeListHeader, etc. IF they exist as .tsx files
|
||||
- But they were DELETED, so they can't be found
|
||||
- The registry says they're "json-compatible" but provides no fallback
|
||||
- The JSON renderer can use them IF loaded via JSON config, but direct imports fail
|
||||
|
||||
## The Fundamental Problem: No Working JSON System Examples
|
||||
|
||||
**Key Issue:** While the JSON UI infrastructure exists, there are NO working examples of pages that successfully:
|
||||
1. Define a complex page entirely in JSON
|
||||
2. Handle state management in JSON
|
||||
3. Wire up all events in JSON
|
||||
4. Replace an existing TypeScript page
|
||||
|
||||
The infrastructure exists but hasn't been proven to work end-to-end.
|
||||
|
||||
## Architecture Deep Dive
|
||||
|
||||
### JSON UI System Components
|
||||
```
|
||||
src/lib/json-ui/
|
||||
├── component-renderer.tsx # Renders individual components from JSON
|
||||
├── page-renderer.tsx # Renders full pages from JSON
|
||||
├── component-registry.ts # Maps component names to React components
|
||||
├── expression-evaluator.ts # Evaluates data binding expressions
|
||||
├── hooks.ts # Data source hooks
|
||||
├── schema.ts # TypeScript types
|
||||
└── wrappers/ # Special wrappers for complex components
|
||||
```
|
||||
|
||||
### How It Should Work (Theory)
|
||||
1. Create JSON page definition in `src/config/ui-examples/my-page.json`
|
||||
2. Load it with `<JSONSchemaPageLoader schemaPath="/config/ui-examples/my-page.json" />`
|
||||
3. JSON renderer looks up components in registry
|
||||
4. Registry loads them via import.meta.glob
|
||||
5. Components render with data bindings and events
|
||||
|
||||
### Why It Doesn't Work (Reality)
|
||||
1. **Deleted components can't be loaded** - glob can't find non-existent files
|
||||
2. **Existing TypeScript pages import components directly** - they don't use JSON loader
|
||||
3. **No migration path** - can't gradually convert pages
|
||||
4. **Registry assumes all components exist as .tsx files** - no JSON-only components
|
||||
|
||||
## Two Possible Solutions
|
||||
|
||||
### Option A: Restore Components (Backward Compatibility)
|
||||
**Goal:** Make the build work by restoring deleted components
|
||||
|
||||
Steps:
|
||||
1. Restore TreeCard, TreeListHeader, LoadingFallback as .tsx files
|
||||
2. Export NavigationItem, PageHeaderContent, preloadMonacoEditor
|
||||
3. Keep JSON system for future use
|
||||
4. Gradual migration when JSON system proven
|
||||
|
||||
**Pros:** Quick fix, maintains compatibility, low risk
|
||||
**Cons:** Delays JSON transition, maintains technical debt
|
||||
|
||||
### Option B: Full JSON Transition (Forward-Looking)
|
||||
**Goal:** Convert consuming pages to use JSON system
|
||||
|
||||
Steps:
|
||||
1. Convert TreeListPanel.tsx to use JSON renderer
|
||||
2. Convert routes.tsx to load JSON configs
|
||||
3. Create JSON definitions for missing components
|
||||
4. Delete rigid TypeScript components
|
||||
5. Prove JSON system works end-to-end
|
||||
|
||||
**Pros:** Achieves goal of JSON system, modern architecture
|
||||
**Cons:** High risk, requires extensive testing, may reveal more issues
|
||||
|
||||
## Recommendation
|
||||
|
||||
**Start with Option A**, then gradually move toward Option B:
|
||||
|
||||
1. **Immediate Fix** (Option A):
|
||||
- Restore the 3 deleted components (TreeCard, TreeListHeader, LoadingFallback)
|
||||
- Fix exports for existing components (NavigationItem, PageHeaderContent, preloadMonacoEditor)
|
||||
- Get the build working
|
||||
|
||||
2. **Validation Phase**:
|
||||
- Create 1-2 complete working examples of JSON pages
|
||||
- Test all JSON system features (data binding, events, conditionals, loops)
|
||||
- Document the conversion process
|
||||
- Identify limitations
|
||||
|
||||
3. **Gradual Migration** (Option B):
|
||||
- Convert simple pages first
|
||||
- Build tooling to help convert TypeScript to JSON
|
||||
- Only delete TypeScript after JSON proven working
|
||||
- Keep wrappers for complex components
|
||||
|
||||
## Files Requiring Immediate Attention
|
||||
|
||||
1. `src/components/molecules/TreeCard.tsx` - RESTORE from aa51074~1
|
||||
2. `src/components/molecules/TreeListHeader.tsx` - RESTORE from aa51074~1
|
||||
3. `src/components/molecules/LoadingFallback.tsx` - RESTORE from aa51074~1
|
||||
4. `src/components/molecules/index.ts` - ADD exports for NavigationItem, PageHeaderContent
|
||||
5. `src/components/molecules/LazyMonacoEditor.tsx` - Already exports preloadMonacoEditor, just needs index.ts export
|
||||
|
||||
## Testing Plan
|
||||
|
||||
After fixes:
|
||||
1. Run `npm run dev` - should start without errors
|
||||
2. Run `npm run build` - should complete successfully
|
||||
3. Run `npm run test:e2e` - should pass
|
||||
4. Manually test pages that use restored components
|
||||
5. Test JSON UI showcase page to verify JSON system still works
|
||||
|
||||
## Long-Term Vision Questions
|
||||
|
||||
1. Can complex state management work in JSON?
|
||||
2. How do we handle TypeScript types and intellisense for JSON configs?
|
||||
3. What about component composition and reusability?
|
||||
4. Performance implications of JSON parsing and dynamic loading?
|
||||
5. How do non-developers edit JSON configs safely?
|
||||
6. Can we generate JSON from existing TypeScript components?
|
||||
7. What's the migration path for 250+ existing pages?
|
||||
|
||||
@@ -29,7 +29,7 @@ export default defineConfig({
|
||||
webServer: {
|
||||
command: 'npm run dev',
|
||||
url: 'http://localhost:5000',
|
||||
reuseExistingServer: !process.env.CI,
|
||||
reuseExistingServer: true,
|
||||
timeout: 120000,
|
||||
stdout: 'pipe',
|
||||
stderr: 'pipe',
|
||||
|
||||
@@ -3,8 +3,9 @@ import { Button } from '@/components/ui/button'
|
||||
import { Sidebar, SidebarContent, SidebarHeader } from '@/components/ui/sidebar'
|
||||
import { ScrollArea } from '@/components/ui/scroll-area'
|
||||
import { Collapsible, CollapsibleContent } from '@/components/ui/collapsible'
|
||||
import { CaretDoubleDown, CaretDoubleUp } from '@phosphor-icons/react'
|
||||
import { NavigationGroupHeader, Badge, Flex, Text, IconWrapper } from '@/components/atoms'
|
||||
import { CaretDoubleDown, CaretDoubleUp, CaretDown } from '@phosphor-icons/react'
|
||||
import { CollapsibleTrigger } from '@/components/ui/collapsible'
|
||||
import { Badge, Flex, Text, IconWrapper } from '@/components/atoms'
|
||||
import { navigationGroups, NavigationItemData } from '@/lib/navigation-config'
|
||||
import { FeatureToggles } from '@/types/project'
|
||||
import { useRoutePreload } from '@/hooks/use-route-preload'
|
||||
@@ -116,11 +117,20 @@ function NavigationMenuGroupList({
|
||||
open={isExpanded}
|
||||
onOpenChange={() => onToggleGroup(group.id)}
|
||||
>
|
||||
<NavigationGroupHeader
|
||||
label={group.label}
|
||||
count={visibleItemsCount}
|
||||
isExpanded={isExpanded}
|
||||
/>
|
||||
{/* NavigationGroupHeader - inlined */}
|
||||
<CollapsibleTrigger className="w-full flex items-center gap-2 px-2 py-2 rounded-lg hover:bg-muted transition-colors group">
|
||||
<CaretDown
|
||||
size={16}
|
||||
weight="bold"
|
||||
className={`text-muted-foreground transition-transform ${
|
||||
isExpanded ? 'rotate-0' : '-rotate-90'
|
||||
}`}
|
||||
/>
|
||||
<h3 className="flex-1 text-left text-xs font-semibold text-muted-foreground uppercase tracking-wider">
|
||||
{group.label}
|
||||
</h3>
|
||||
<span className="text-xs text-muted-foreground">{visibleItemsCount}</span>
|
||||
</CollapsibleTrigger>
|
||||
<CollapsibleContent className="mt-1">
|
||||
<div className="space-y-1 pl-2">
|
||||
{group.items.map((item) => {
|
||||
|
||||
Reference in New Issue
Block a user