{
  "name": "json-render-ui",
  "version": "1.0.0",
  "components": {
    "Card": {
      "description": "Container with optional header",
      "hasChildren": true,
      "props": {
        "title": { "type": "string", "required": false },
        "description": { "type": "string", "required": false },
        "padding": { "type": "enum", "values": ["sm", "md", "lg"], "default": "md" }
      }
    },
    "Grid": {
      "description": "CSS grid layout",
      "hasChildren": true,
      "props": {
        "columns": { "type": "number", "min": 1, "max": 4, "default": 2 },
        "gap": { "type": "enum", "values": ["sm", "md", "lg"], "default": "md" }
      }
    },
    "Stack": {
      "description": "Flexbox stack for layouts",
      "hasChildren": true,
      "props": {
        "direction": { "type": "enum", "values": ["horizontal", "vertical"], "default": "vertical" },
        "gap": { "type": "enum", "values": ["sm", "md", "lg"], "default": "md" },
        "align": { "type": "enum", "values": ["start", "center", "end", "stretch"], "default": "stretch" }
      }
    },
    "Metric": {
      "description": "Single KPI display with optional trend",
      "hasChildren": false,
      "props": {
        "label": { "type": "string", "required": true },
        "valuePath": { "type": "string", "required": true, "description": "JSON Pointer to data value" },
        "format": { "type": "enum", "values": ["number", "currency", "percent"], "default": "number" },
        "trend": { "type": "enum", "values": ["up", "down", "neutral"], "required": false },
        "trendValue": { "type": "string", "required": false }
      }
    },
    "Chart": {
      "description": "Data visualization from array data",
      "hasChildren": false,
      "props": {
        "type": { "type": "enum", "values": ["bar", "line", "pie", "area"], "required": true },
        "dataPath": { "type": "string", "required": true, "description": "JSON Pointer to array of {label, value} or {x, y}" },
        "title": { "type": "string", "required": false },
        "height": { "type": "number", "default": 200 }
      }
    },
    "Table": {
      "description": "Tabular data display",
      "hasChildren": false,
      "props": {
        "dataPath": { "type": "string", "required": true },
        "columns": {
          "type": "array",
          "required": true,
          "items": {
            "type": "object",
            "properties": {
              "key": { "type": "string", "required": true },
              "label": { "type": "string", "required": true },
              "format": { "type": "enum", "values": ["text", "currency", "date", "badge"], "default": "text" }
            }
          }
        }
      }
    },
    "List": {
      "description": "Rendered list from array data",
      "hasChildren": true,
      "props": {
        "dataPath": { "type": "string", "required": true },
        "emptyMessage": { "type": "string", "default": "No items" }
      }
    },
    "Button": {
      "description": "Clickable action button",
      "hasChildren": false,
      "props": {
        "label": { "type": "string", "required": true },
        "action": { "type": "string", "required": true, "description": "Action identifier passed to onAction handler" },
        "variant": { "type": "enum", "values": ["primary", "secondary", "danger", "ghost"], "default": "primary" },
        "size": { "type": "enum", "values": ["sm", "md", "lg"], "default": "md" },
        "disabled": { "type": "boolean", "default": false }
      }
    },
    "Select": {
      "description": "Dropdown select input with two-way binding",
      "hasChildren": false,
      "props": {
        "label": { "type": "string", "required": false },
        "bindPath": { "type": "string", "required": true, "description": "JSON Pointer for two-way data binding" },
        "options": {
          "type": "array",
          "required": true,
          "items": {
            "type": "object",
            "properties": {
              "value": { "type": "string", "required": true },
              "label": { "type": "string", "required": true }
            }
          }
        },
        "placeholder": { "type": "string", "required": false }
      }
    },
    "DatePicker": {
      "description": "Date input with two-way binding",
      "hasChildren": false,
      "props": {
        "label": { "type": "string", "required": false },
        "bindPath": { "type": "string", "required": true },
        "placeholder": { "type": "string", "required": false }
      }
    },
    "Heading": {
      "description": "Section heading",
      "hasChildren": false,
      "props": {
        "text": { "type": "string", "required": true },
        "level": { "type": "enum", "values": ["h1", "h2", "h3", "h4"], "default": "h2" }
      }
    },
    "Text": {
      "description": "Text paragraph",
      "hasChildren": false,
      "props": {
        "content": { "type": "string", "required": true },
        "variant": { "type": "enum", "values": ["body", "caption", "label"], "default": "body" },
        "color": { "type": "enum", "values": ["default", "muted", "success", "warning", "danger"], "default": "default" }
      }
    },
    "Badge": {
      "description": "Small status indicator",
      "hasChildren": false,
      "props": {
        "text": { "type": "string", "required": true },
        "variant": { "type": "enum", "values": ["default", "success", "warning", "danger", "info"], "default": "default" }
      }
    },
    "Alert": {
      "description": "Notification banner",
      "hasChildren": false,
      "props": {
        "type": { "type": "enum", "values": ["info", "success", "warning", "error"], "required": true },
        "title": { "type": "string", "required": true },
        "message": { "type": "string", "required": false },
        "dismissible": { "type": "boolean", "default": false }
      }
    },
    "Divider": {
      "description": "Visual separator",
      "hasChildren": false,
      "props": {
        "label": { "type": "string", "required": false }
      }
    },
    "Empty": {
      "description": "Empty state placeholder",
      "hasChildren": false,
      "props": {
        "title": { "type": "string", "required": true },
        "description": { "type": "string", "required": false },
        "action": { "type": "string", "required": false, "description": "Action identifier for CTA button" },
        "actionLabel": { "type": "string", "required": false, "description": "Label for CTA button" }
      }
    }
  },
  "actions": {
    "description": "Actions are string identifiers passed to the onAction handler. Define handlers in your app.",
    "examples": ["export_report", "refresh_data", "view_details", "apply_filter", "delete_item"]
  }
}

# UITree Format Specification

## Overview

UITree is a flat JSON structure representing a component hierarchy. It's designed for LLM generation—flat structure avoids deep nesting issues with streaming and parsing.

## Structure

```typescript
interface UITree {
  root: string;                    // Key of root element
  elements: Record<string, UIElement>;  // Flat map of all elements
  data?: Record<string, unknown>;  // Data model for bindings
}

interface UIElement {
  key: string;                     // Unique identifier
  type: string;                    // Component type from catalog
  props: Record<string, unknown>;  // Component props
  children?: string[];             // Keys of child elements
  visible?: VisibilityCondition;   // Optional visibility rule
}
```

## Key Generation

Keys must be unique within the tree. Conventions:
- Use descriptive names: `"revenueMetric"`, `"headerCard"`, `"userTable"`
- For repeated items, use suffixes: `"metric1"`, `"metric2"`
- Avoid generic names like `"div1"`, `"component3"`

## Parent-Child Relationships

Children are referenced by key, not embedded:

```json
{
  "root": "container",
  "elements": {
    "container": {
      "key": "container",
      "type": "Card",
      "props": { "title": "My Card" },
      "children": ["child1", "child2"]
    },
    "child1": {
      "key": "child1",
      "type": "Text",
      "props": { "content": "First child" }
    },
    "child2": {
      "key": "child2",
      "type": "Text",
      "props": { "content": "Second child" }
    }
  }
}
```

## Data Binding

### Value Paths

Props ending in `Path` reference the data model using JSON Pointer syntax:

| Path | Resolves to |
|------|-------------|
| `/revenue` | `data.revenue` |
| `/users/0/name` | `data.users[0].name` |
| `/settings/theme` | `data.settings.theme` |

### Read-Only Binding (valuePath, dataPath)

Used for display components. Data flows one way (data → UI):

```json
{
  "type": "Metric",
  "props": {
    "label": "Revenue",
    "valuePath": "/revenue"
  }
}
```

### Two-Way Binding (bindPath)

Used for input components. Data flows both ways:

```json
{
  "type": "Select",
  "props": {
    "label": "Status",
    "bindPath": "/filters/status",
    "options": [
      { "value": "active", "label": "Active" },
      { "value": "inactive", "label": "Inactive" }
    ]
  }
}
```

## Visibility Conditions

Control when elements render:

### Static

```json
{ "visible": true }   // Always visible (default)
{ "visible": false }  // Never visible
```

### Path-Based (Truthy Check)

```json
{ "visible": { "path": "/hasError" } }
```

### Boolean Logic

```json
// AND - all must be true
{ "visible": { "and": [{ "path": "/isAdmin" }, { "path": "/hasAccess" }] } }

// OR - any must be true
{ "visible": { "or": [{ "path": "/isOwner" }, { "path": "/isAdmin" }] } }

// NOT - negation
{ "visible": { "not": { "path": "/isHidden" } } }
```

### Comparisons

```json
// Equality
{ "visible": { "eq": [{ "path": "/status" }, "active"] } }

// Not equal
{ "visible": { "neq": [{ "path": "/count" }, 0] } }

// Numeric comparisons
{ "visible": { "gt": [{ "path": "/items" }, 5] } }
{ "visible": { "gte": [{ "path": "/items" }, 5] } }
{ "visible": { "lt": [{ "path": "/items" }, 10] } }
{ "visible": { "lte": [{ "path": "/items" }, 10] } }
```

### Complex Example

```json
{
  "visible": {
    "and": [
      { "path": "/user/isLoggedIn" },
      { "or": [
        { "eq": [{ "path": "/user/role" }, "admin"] },
        { "gt": [{ "path": "/user/level" }, 5] }
      ]}
    ]
  }
}
```

## Data Model

The `data` property provides values for bindings:

```json
{
  "root": "dashboard",
  "elements": { ... },
  "data": {
    "revenue": 125000,
    "growth": 0.15,
    "users": [
      { "name": "Alice", "status": "active" },
      { "name": "Bob", "status": "pending" }
    ],
    "filters": {
      "status": "all",
      "dateRange": "30d"
    }
  }
}
```

## Best Practices

### Keep Trees Flat

Avoid deep nesting. Prefer:
```
Grid → [Card, Card, Card]  (depth 2)
```

Over:
```
Grid → Card → Stack → Card → Text  (depth 5)
```

### Use Semantic Components

- **Metrics** for KPIs, not Text with styled numbers
- **Table** for tabular data, not nested Stacks
- **Chart** for visualizations, not custom SVG

### Provide Realistic Data

Always include sample data that matches the expected schema:

```json
{
  "type": "Chart",
  "props": {
    "type": "line",
    "dataPath": "/monthlyData"
  }
}
// data should include:
{
  "monthlyData": [
    { "month": "Jan", "value": 1000 },
    { "month": "Feb", "value": 1200 }
  ]
}
```

### Validate Keys

- Every `children` entry must exist in `elements`
- `root` must exist in `elements`
- No circular references