metabuilder/codegen/docs/COMPONENT_TREE_JSON_LOADING.md

Component Tree JSON Loading System

Overview

This system loads molecule and organism component trees from JSON files into the application's KV store on startup. Component trees define the hierarchical structure of reusable UI components with their props, children, and metadata.

File Structure

src/
├── config/
│   └── component-trees/
│       ├── index.ts           # Exports and utility functions
│       ├── molecules.json     # Molecule component trees
│       └── organisms.json     # Organism component trees
├── hooks/
│   └── use-component-tree-loader.ts  # Hook for loading and managing trees
└── components/
    ├── ComponentTreeViewer.tsx        # UI for viewing component trees
    └── ComponentTreeDemoPage.tsx      # Demo page

Component Tree Structure

Each component tree follows this schema:

interface ComponentTree {
  id: string                    // Unique identifier
  name: string                  // Display name
  description: string           // Description of the component
  category: 'molecule' | 'organism'  // Component category
  rootNodes: ComponentNode[]    // Root component nodes
  createdAt: number            // Timestamp
  updatedAt: number            // Timestamp
}

interface ComponentNode {
  id: string                    // Unique node ID
  type: string                  // Component type (Button, Card, etc.)
  name: string                  // Node name
  props: Record<string, any>   // Component props
  children: ComponentNode[]    // Child nodes
}

JSON Files

molecules.json

Contains component trees for molecule-level components:

• SearchInput
• DataCard
• StatCard
• ActionBar
• EmptyState
• FileTabs

organisms.json

Contains component trees for organism-level components:

• AppHeader
• NavigationMenu
• SchemaEditorCanvas
• TreeListPanel
• DataTable
• SchemaEditorSidebar

Usage

Loading Component Trees

Component trees are automatically loaded on application startup via the App.tsx initialization:

const { loadComponentTrees } = useComponentTreeLoader()

useEffect(() => {
  loadSeedData()
    .then(() => loadComponentTrees())
    .then(() => console.log('Trees loaded'))
}, [])

Using the Hook

import { useComponentTreeLoader } from '@/hooks/use-component-tree-loader'

function MyComponent() {
  const {
    isLoaded,
    isLoading,
    error,
    moleculeTrees,
    organismTrees,
    allTrees,
    getComponentTreeById,
    getComponentTreeByName,
    getComponentTreesByCategory,
    reloadFromJSON,
  } = useComponentTreeLoader()

  // Access trees from memory
  const molecules = moleculeTrees

  // Get tree from KV store
  const tree = await getComponentTreeById('mol-tree-1')

  // Reload from JSON files
  await reloadFromJSON()
}

Viewing Component Trees

Use the ComponentTreeViewer component to visualize and explore loaded trees:

import { ComponentTreeViewer } from '@/components/ComponentTreeViewer'

function MyPage() {
  return <ComponentTreeViewer />
}

API Reference

useComponentTreeLoader()

Returns an object with:

• isLoaded: boolean - Whether trees have been loaded
• isLoading: boolean - Whether loading is in progress
• error: Error | null - Any loading error
• moleculeTrees: ComponentTree[] - Array of molecule trees
• organismTrees: ComponentTree[] - Array of organism trees
• allTrees: ComponentTree[] - All trees combined
• loadComponentTrees() - Load trees from JSON to KV store
• getComponentTrees() - Get all trees from KV store
• getComponentTreesByCategory(category) - Get trees by category
• getComponentTreeById(id) - Get tree by ID
• getComponentTreeByName(name) - Get tree by name
• reloadFromJSON() - Force reload from JSON files

Config Functions

From @/config/component-trees:

import componentTreesData from '@/config/component-trees'

// Access trees
const molecules = componentTreesData.molecules
const organisms = componentTreesData.organisms
const all = componentTreesData.all

// Utility functions
const tree = componentTreesData.getById('mol-tree-1')
const tree = componentTreesData.getByName('SearchInput')
const trees = componentTreesData.getByCategory('molecule')

Adding New Component Trees

1. Edit molecules.json or organisms.json:

{
  "molecules": [
    {
      "id": "mol-tree-new",
      "name": "NewComponent",
      "description": "Description of the component",
      "category": "molecule",
      "rootNodes": [
        {
          "id": "root-1",
          "type": "div",
          "name": "Container",
          "props": {
            "className": "flex gap-2"
          },
          "children": []
        }
      ],
      "createdAt": 1704067200000,
      "updatedAt": 1704067200000
    }
  ]
}

2. Reload in the application:

const { reloadFromJSON } = useComponentTreeLoader()
await reloadFromJSON()

Or restart the application for automatic loading.

Features

• Automatic Loading: Trees are loaded on app startup
• Merge Strategy: New trees are merged with existing trees, preserving user modifications
• Category Filtering: Filter trees by molecule/organism category
• Type Safety: Full TypeScript support
• Error Handling: Graceful error handling with user feedback
• Hot Reload: Reload from JSON without restarting the app
• Visual Explorer: Built-in UI for viewing tree structures

Benefits

1. Separation of Concerns: Component structures defined in JSON, separate from implementation
2. Reusability: Trees can be referenced and reused across the application
3. Documentation: JSON serves as living documentation of component hierarchy
4. Version Control: Easy to track changes to component structures
5. Tooling: Can be generated or validated by external tools

Integration with Existing System

The component tree system integrates with:

• Project State: Trees stored in KV store alongside other project data
• Seed Data: Loaded automatically with seed data on startup
• Component Trees Feature: Used by existing component tree builder/manager
• Atomic Design: Follows atomic design principles (molecules, organisms)

Future Enhancements

Potential improvements:

• JSON schema validation
• Component tree code generation
• Visual tree editor with drag-and-drop
• Tree composition (combining multiple trees)
• Tree versioning and history
• Export trees to React code
• Import trees from existing React components