## `render_data_viz` usage guide

This tool renders data visualization resources. Use the `uri` field to specify the visualization type, and pass all parameters in the `data` object.

### Supported URIs:
- `ui://data-dashboard/metrics` — Metric card dashboard
- `ui://data-dashboard/chart` — Single chart (line, bar, pie, radar, scatter, gauge)
- `ui://data-dashboard/multi-chart` — Multiple charts in a grid layout

---

### 1. Metrics — `ui://data-dashboard/metrics`

When to use: KPIs, stats, numerical summaries, side-by-side comparisons.

```
render_data_viz(
  uri="ui://data-dashboard/metrics",
  data={
    "title": "Sales Overview",
    "metrics": [
      {"label": "Revenue", "value": "$12,345", "change": "+12.5%", "change_type": "up"},
      {"label": "Users", "value": "1,234", "change": "-3.2%", "change_type": "down"},
      {"label": "Conversion", "value": "4.5%", "change_type": "neutral"}
    ]
  }
)
```

---

### 2. Chart — `ui://data-dashboard/chart`

When to use: trends, comparisons, distributions, compositions, single metric gauges.

#### Line chart — trends over time
```
render_data_viz(
  uri="ui://data-dashboard/chart",
  data={
    "title": "Monthly Revenue",
    "chart_type": "line",
    "data": {
      "categories": ["Jan", "Feb", "Mar", "Apr", "May", "Jun"],
      "series": [
        {"name": "2024", "data": [820, 932, 901, 934, 1290, 1330]},
        {"name": "2025", "data": [620, 732, 801, 1034, 1190, 1530]}
      ]
    },
    "smooth": true
  }
)
```

#### Bar chart — comparisons
```
render_data_viz(
  uri="ui://data-dashboard/chart",
  data={
    "title": "Sales by Region",
    "chart_type": "bar",
    "data": {
      "categories": ["North", "South", "East", "West"],
      "series": [
        {"name": "Q1", "data": [320, 302, 341, 374]},
        {"name": "Q2", "data": [220, 182, 191, 234]}
      ]
    },
    "stacked": true,
    "show_label": true
  }
)
```

#### Pie chart — proportions
```
render_data_viz(
  uri="ui://data-dashboard/chart",
  data={
    "title": "Traffic Sources",
    "chart_type": "pie",
    "data": {
      "series": [{
        "name": "Sources",
        "data": [
          {"name": "Search", "value": 1048},
          {"name": "Direct", "value": 735},
          {"name": "Email", "value": 580},
          {"name": "Social", "value": 484}
        ]
      }]
    }
  }
)
```

#### Radar chart — multi-dimensional
```
render_data_viz(
  uri="ui://data-dashboard/chart",
  data={
    "title": "Skill Assessment",
    "chart_type": "radar",
    "data": {
      "categories": ["Sales", "Admin", "Tech", "Support", "Marketing"],
      "series": [
        {"name": "Alice", "data": [4200, 3000, 20000, 35000, 50000]},
        {"name": "Bob",   "data": [5000, 14000, 28000, 26000, 42000]}
      ]
    }
  }
)
```

#### Scatter chart — correlation
```
render_data_viz(
  uri="ui://data-dashboard/chart",
  data={
    "title": "Height vs Weight",
    "chart_type": "scatter",
    "data": {
      "series": [
        {"name": "Male",   "data": [[161, 51], [167, 59], [159, 49], [175, 73]]},
        {"name": "Female", "data": [[150, 45], [160, 55], [165, 60], [155, 50]]}
      ]
    }
  }
)
```

#### Gauge chart — single KPI
```
render_data_viz(
  uri="ui://data-dashboard/chart",
  data={
    "title": "CPU Usage",
    "chart_type": "gauge",
    "data": {"series": [{"name": "CPU", "data": [72.5]}]}
  }
)
```

#### Chart options (inside data):
- `width`: CSS width, default "100%"
- `height`: CSS height, default "400px"
- `theme`: "light" (default) or "dark"
- `stacked`: stack series (line/bar), default false
- `smooth`: smooth curves (line), default false
- `show_label`: show data labels, default false

---

### 3. Multi-chart — `ui://data-dashboard/multi-chart`

When to use: comprehensive overviews, multiple related charts, business reports.

```
render_data_viz(
  uri="ui://data-dashboard/multi-chart",
  data={
    "title": "Monthly Business Report",
    "columns": 2,
    "theme": "light",
    "charts": [
      {
        "title": "Revenue Trend",
        "chart_type": "line",
        "data": {
          "categories": ["Jan", "Feb", "Mar", "Apr", "May", "Jun"],
          "series": [{"name": "Revenue", "data": [820, 932, 901, 934, 1290, 1330]}]
        },
        "smooth": true
      },
      {
        "title": "Sales by Region",
        "chart_type": "bar",
        "data": {
          "categories": ["North", "South", "East", "West"],
          "series": [
            {"name": "Q1", "data": [320, 302, 341, 374]},
            {"name": "Q2", "data": [220, 182, 191, 234]}
          ]
        }
      },
      {
        "title": "Traffic Sources",
        "chart_type": "pie",
        "data": {
          "series": [{"name": "Sources", "data": [
            {"name": "Search", "value": 1048},
            {"name": "Direct", "value": 735},
            {"name": "Social", "value": 484}
          ]}]
        }
      },
      {
        "title": "Server Load",
        "chart_type": "gauge",
        "data": {"series": [{"name": "CPU", "data": [67]}]},
        "height": "300px"
      }
    ]
  }
)
```

### Tips:
- Always choose the most appropriate chart_type for the data
- Use line for time-series trends, bar for category comparisons
- Use pie for proportions (limit ~7 segments), radar for multi-dimensional scores
- Use scatter for correlation, gauge for single KPI (0-100)
- Set height: "400px" for most charts, "300px" for gauge
- Multi-chart: columns=2 for 2-4 charts, keep 4-6 max per call