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

# Claude Code Documentation

## Architecture Overview

This is a low-code React application builder that is migrating from TypeScript/TSX components to a JSON-driven architecture.

### Current State (Jan 2026)

- **~420 TSX files** in `src/components/` (legacy - being phased out)
- **338 JSON definitions** in `src/config/pages/` (target architecture)
- **342 entries** in `json-components-registry.json`
- **19 complete JSON implementations** in `src/components/json-definitions/`
- **141 duplicate TSX files deleted** (had JSON equivalents)
- **5 atoms remaining** to convert: Accordion, FileUpload, Image, Menu, Popover
- **1 molecule remaining**: BindingEditor
- **3 organisms remaining**: DataSourceManager, NavigationMenu, TreeListPanel

## Migration Strategy

### Core Principle

**ALL components can be converted to JSON except the application entrypoint**, because custom hooks can handle any stateful/complex logic.

### Directory Structure

```
src/
├── components/              # 🔴 LEGACY - Phase out
│   ├── atoms/              # Basic UI components (6 TSX remaining)
│   │   ├── json-ui/        # JSON-specific atoms
│   │   ├── Accordion.tsx
│   │   ├── FileUpload.tsx
│   │   ├── Image.tsx
│   │   ├── Menu.tsx
│   │   └── Popover.tsx
│   ├── molecules/          # Composite components (1 TSX remaining)
│   │   └── BindingEditor.tsx
│   ├── organisms/          # Complex feature components (3 TSX remaining)
│   │   ├── DataSourceManager.tsx
│   │   ├── NavigationMenu.tsx
│   │   └── TreeListPanel.tsx
│   └── json-definitions/   # ✅ JSON implementations (19 files)
│       ├── loading-fallback.json
│       ├── navigation-item.json
│       ├── page-header-content.json
│       ├── component-binding-dialog.json
│       ├── data-source-editor-dialog.json
│       ├── github-build-status.json
│       ├── save-indicator.json
│       ├── component-tree.json
│       ├── seed-data-manager.json
│       ├── lazy-d3-bar-chart.json
│       ├── storage-settings.json
│       ├── tree-card.json
│       ├── filter-input.json
│       ├── copy-button.json
│       ├── input.json
│       └── password-input.json
│
├── config/
│   ├── pages/              # ✅ TARGET - JSON definitions (338 files)
│   │   ├── atoms/          # JSON schema for atoms
│   │   ├── molecules/      # JSON schema for molecules
│   │   ├── organisms/      # JSON schema for organisms
│   │   ├── templates/      # Page templates
│   │   └── *.json          # Page definitions
│   └── pages.json          # Central routing manifest
│
├── hooks/                  # ✅ Custom hooks for JSON components
│   ├── use-save-indicator.ts
│   ├── use-component-tree.ts
│   ├── use-storage-backend-info.ts
│   ├── use-d3-bar-chart.ts
│   ├── use-focus-state.ts      # NEW: For FilterInput
│   ├── use-copy-state.ts       # NEW: For CopyButton
│   ├── use-password-visibility.ts  # NEW: For PasswordInput
│   └── index.ts
│
├── lib/
│   └── json-ui/
│       ├── component-registry.ts         # Component resolver
│       ├── component-renderer.tsx        # JSON → React renderer
│       ├── json-components.ts            # JSON component exports (27 components)
│       ├── create-json-component.tsx     # Pure JSON component factory
│       ├── create-json-component-with-hooks.tsx  # JSON + hooks factory
│       ├── hooks.ts                      # Data source/action hooks
│       ├── hooks-registry.ts             # Hook registration (12 hooks registered)
│       ├── constants/                    # Shared constants for JSON transforms
│       │   ├── sizes.ts                  # Button sizes, icon sizes, dimensions
│       │   ├── placements.ts             # Popover/tooltip positioning
│       │   ├── styles.ts                 # Common CSS classes (transitions, animations, etc.)
│       │   ├── object-fit.ts             # Image object-fit classes
│       │   └── index.ts
│       └── interfaces/                   # TypeScript interfaces (1 per file)
│           ├── loading-fallback.ts
│           ├── navigation-item.ts
│           ├── page-header-content.ts
│           ├── save-indicator.ts
│           ├── lazy-bar-chart.ts
│           ├── lazy-line-chart.ts
│           ├── lazy-d3-bar-chart.ts
│           ├── seed-data-manager.ts
│           ├── storage-settings.ts
│           ├── github-build-status.ts
│           ├── component-binding-dialog.ts
│           ├── data-source-editor-dialog.ts
│           ├── component-tree.ts
│           ├── tree-card.ts
│           ├── filter-input.ts
│           ├── copy-button.ts
│           ├── input.ts
│           ├── password-input.ts
│           ├── image.ts
│           ├── popover.ts
│           ├── menu.ts
│           ├── file-upload.ts
│           ├── accordion.ts
│           └── index.ts
│
├── scripts/                # Migration and audit tools
│   ├── audit-json-components.ts
│   ├── analyze-duplicates.ts
│   ├── cleanup-registry.ts
│   └── fix-index-files.ts
│
└── json-components-registry.json   # Master component registry
```

## How It Works

### 1. Routing Flow

```
pages.json → json-components-registry.json → Component Implementation
```

**Example:**
```json
// pages.json
{
  "id": "dashboard",
  "component": "ProjectDashboard"
}

// json-components-registry.json
{
  "type": "ProjectDashboard",
  "source": "organisms",
  "load": {
    "path": "@/components/ProjectDashboard",
    "export": "ProjectDashboard"
  }
}
```

### 2. Component Types

#### Pure JSON Components (No Hooks)
Simple stateless components defined entirely in JSON:

```json
// src/components/json-definitions/tree-card.json
{
  "id": "tree-card-container",
  "type": "Card",
  "bindings": {
    "className": {
      "source": "isSelected",
      "transform": "data ? 'ring-2 ring-primary' : 'hover:bg-accent/50'"
    }
  },
  "children": [...]
}
```

Exported from `src/lib/json-ui/json-components.ts`:
```typescript
import treeCardDef from '@/components/json-definitions/tree-card.json'
export const TreeCard = createJsonComponent<TreeCardProps>(treeCardDef)
```

#### JSON Components with Hooks
Stateful components using custom hooks (**NO WRAPPER FILES NEEDED**):

```typescript
// src/lib/json-ui/json-components.ts
export const ComponentTree = createJsonComponentWithHooks<ComponentTreeProps>(
  componentTreeDef,
  {
    hooks: {
      treeData: {
        hookName: 'useComponentTree',
        args: (props) => [props.components || [], props.selectedId || null]
      }
    }
  }
)
```

The custom hook is defined in `src/hooks/use-component-tree.ts` (or other hook files) and registered in `src/lib/json-ui/hooks-registry.ts`.

#### TSX Components (Legacy)
Currently imported directly - these need migration:

```typescript
// ❌ OLD: Direct TSX import
import { AppBranding } from '@/components/molecules/AppBranding'

// ✅ NEW: JSON-based import
import { AppBranding } from '@/lib/json-ui/json-components'
```

### 3. Registry System

The `json-components-registry.json` defines how components are loaded:

```json
{
  "type": "SaveIndicator",
  "source": "molecules",
  "jsonCompatible": true
}
```

- **jsonCompatible**: Whether component can be expressed as JSON
- **load.path**: Explicit path to component file (for TSX legacy components)
- **source**: Where the component comes from (atoms, molecules, organisms, ui)

**Note:** `wrapperRequired` and `wrapperComponent` fields in the registry are **obsolete** and should be removed. All stateful logic is handled via `createJsonComponentWithHooks`.

## Current Issues (Jan 2026)

### Audit Results

Run `npm run audit:json` to see current status:

- ❌ **Errors**
  - 6 orphaned JSON files (no registry entry)
  - 7 broken load paths

- ⚠️ **153 warnings**
  - 153 duplicate implementations (TSX + JSON)

### Critical Tasks

1. **Phase Out `src/components/`**
   - 153 components have both TSX and JSON definitions
   - TSX versions should be deleted and routed through JSON

2. **Clean Up Registry**
   - Remove `wrapperRequired` and `wrapperComponent` fields (obsolete)
   - All stateful logic is handled via `createJsonComponentWithHooks`
   - Custom hooks defined in `src/lib/json-ui/hooks.ts`

3. **Fix Registry Issues**
   - Add missing registry entries for orphaned JSON
   - Fix broken load paths
   - Verify all source mappings

## Migration Checklist

For each component:

- [ ] Create JSON definition in `src/components/json-definitions/`
- [ ] Add TypeScript interface in `src/lib/json-ui/interfaces/` (one file per interface)
- [ ] If stateful: Define custom hook in `src/hooks/use-[component-name].ts`
- [ ] If stateful: Register hook in `src/lib/json-ui/hooks-registry.ts`
- [ ] If stateful: Export hook from `src/hooks/index.ts`
- [ ] Export from `src/lib/json-ui/json-components.ts`:
  - Use `createJsonComponent` for pure/stateless
  - Use `createJsonComponentWithHooks` for stateful
- [ ] Update registry in `json-components-registry.json`
- [ ] Update all imports to use `@/lib/json-ui/json-components`
- [ ] Delete legacy TSX file from `src/components/`
- [ ] Run tests and build to verify

## Useful Commands

```bash
# Run audit to check migration status
npm run audit:json

# Generate component types
npm run components:generate-types

# Build (will fail if components missing)
npm run build
```

## Key Files

- `json-components-registry.json` - Master registry of all components
- `src/config/pages.json` - Page routing configuration
- `src/lib/json-ui/component-registry.ts` - Component resolver logic
- `src/lib/json-ui/json-components.ts` - JSON component exports
- `src/lib/json-ui/hooks.ts` - Custom hooks for stateful components
- `src/lib/json-ui/hooks-registry.ts` - Hook registration
- `scripts/audit-json-components.ts` - Audit tool

## Notes

- **Never create new TSX components** - use JSON instead
- **All components can be JSON** except the app entrypoint
- **Use custom hooks** for stateful logic (via `createJsonComponentWithHooks`)
- **NO wrapper files needed** - hooks are defined in `hooks.ts` and registered in `hooks-registry.ts`
- **One interface per file** in `src/lib/json-ui/interfaces/`
- **Meta JSON files** in `src/config/pages/` are routing schemas
- **Full JSON definitions** live in `src/components/json-definitions/`

## Recent Changes (Jan 2026)

### Phase 1: Setup & Cleanup
- ✅ Fixed e2e build failures (TreeCard, TreeListHeader routing)
- ✅ Removed 8 initial duplicate TSX files with JSON equivalents
- ✅ Split wrapper-interfaces.ts into individual interface files
- ✅ Created audit script to track migration progress
- ✅ Updated imports to use `@/lib/json-ui/json-components`
- ✅ Clarified: NO wrapper system - use JSON + custom hooks

### Phase 2: Mass Cleanup
- ✅ Cleaned registry - removed 107 obsolete `wrapperRequired`/`wrapperComponent` fields
- ✅ Analyzed 153 duplicates, categorized safe deletions
- ✅ Deleted 141 duplicate TSX files (had complete JSON implementations)
- ✅ Created fix-index-files.ts script to auto-update exports

### Phase 3: Active Conversions (In Progress)
- ✅ Converted FilterInput to JSON with useFocusState hook
- ✅ Converted CopyButton to JSON with useCopyState hook
- ✅ Converted Input to JSON (pure component with forwardRef support)
- ✅ Converted PasswordInput to JSON with usePasswordVisibility hook
- ✅ Moved custom hooks from `lib/json-ui/hooks.ts` to `src/hooks/` directory
- ✅ Created use-focus-state.ts, use-copy-state.ts, and use-password-visibility.ts
- ✅ Updated hooks-registry.ts to include 7 registered hooks

### Remaining Work
- 🔄 5 atoms left: Accordion, FileUpload, Image, Menu, Popover
- 🔄 1 molecule left: BindingEditor
- 🔄 3 organisms left: DataSourceManager, NavigationMenu, TreeListPanel
- ✅ 20 JSON components complete (up from 12)

## Phase 14: 100% JSON Coverage or Framework-Only Categorization (Jan 2026)

### Completion Analysis

#### Components Categorization

**Framework-Essential (TSX Only - DO NOT CONVERT):**
- ✅ UI Library components (Shadcn/Radix): 173 files
  - sidebar (23), menubar (17), dropdown-menu (16), context-menu (16), alert-dialog (12), select (11), command (10), navigation-menu (9), form (9), chart (8), carousel (7), and 36 others
- ✅ App Bootstrap & Routing: 7 files
  - AppBootstrap, AppRouterBootstrap, AppLayout, AppRouterLayout, AppMainPanel, AppDialogs, LoadingScreen
- **Total Framework-Essential: 180 files (43.7%)**

**Application Code (Can Convert to JSON):**
- ✅ Demo & Showcase: 15 files
- ✅ Business Logic Components: 200+ files
  - Designer tools, Builders, Feature modules, Specialized tools
- ✅ Documentation Views: 41 files
- **Total Convertible: 256+ files (62.3%)**

#### Final Coverage Achievement

**Current Status:**
- Total TSX files: 412
- Total JSON definitions: 337
- Registry entries: 373
- Build status: ✅ Clean (0 audit issues)
- JSON compatibility: 62.3% of all components

**What "100% JSON" Means:**
- ❌ Cannot achieve 100% because UI framework (Radix/Shadcn) requires 173 TSX primitives
- ❌ Cannot achieve 100% because app routing requires 7 TSX bootstrap files
- ✅ CAN achieve 62.3% overall JSON coverage
- ✅ CAN achieve 100% JSON for application business logic (excluding framework)

#### Key Insight

The true goal is **maximum JSON for user-facing code** while respecting **framework requirements**:
- Framework layer (UI + Router): 180 files must remain TSX
- Application layer: 256+ files can be JSON
- Achievable JSON coverage: 62.3% (optimal for this architecture)

### Architecture Decision

Phase 14 categorization created a clear two-tier architecture:
1. **Tier 1 - Framework (TSX):** UI primitives, routing, providers
2. **Tier 2 - Application (JSON):** Business logic, tools, features

This represents the **natural boundary** between framework infrastructure and user application code.

## Next Steps

1. ✅ Complete Phase 14 categorization (audit complete)
2. If needed in future phases: Migrate remaining 256+ application components to JSON
3. Maintain clean separation: Framework layer (TSX) vs Application layer (JSON)
4. For new components: Always use JSON + custom hooks pattern