# JSON Input Formats

Reference for the JSON data format expected by each of the 15 chart types.
These formats apply to both the CLI (`textcharts <type>`) and the MCP server
(`textcharts_<type>` tools).

All examples below can be piped directly to the CLI:

```bash
echo '<json>' | textcharts <type> --no-color
```

---

## bar

Horizontal bar chart for comparing values across categories.

**Format:** list of objects

| Field     | Type    | Required | Description              |
|-----------|---------|----------|--------------------------|
| label     | string  | yes      | Category label           |
| value     | number  | yes      | Numeric value            |
| group     | string  | no       | Optional grouping key    |
| error     | number  | no       | Optional error margin    |
| is_best   | boolean | no       | Mark as best performer   |
| is_worst  | boolean | no       | Mark as worst performer  |

```json
[
  {"label": "Fiction", "value": 18.4, "is_best": true},
  {"label": "Children", "value": 14.2},
  {"label": "Comics", "value": 9.8},
  {"label": "Stationery", "value": 6.1, "is_worst": true}
]
```

**Chart params:** `metric_label` (string), `sort_by` (value | label | none)

---

## histogram

Vertical bar histogram for frequency distribution.

**Format:** list of objects

| Field    | Type    | Required | Description                |
|----------|---------|----------|----------------------------|
| label    | string  | yes      | Item identifier            |
| value    | number  | yes      | Numeric value              |
| platform | string  | no       | Optional platform name     |
| error    | number  | no       | Optional error margin      |
| is_best  | boolean | no       | Mark as best performer     |
| is_worst | boolean | no       | Mark as worst performer    |

```json
[
  {"label": "Q1", "value": 120.5},
  {"label": "Q2", "value": 85.3, "is_best": true},
  {"label": "Q3", "value": 210.7, "is_worst": true}
]
```

**Chart params:** `y_label` (string), `sort_by` (label | value),
`max_per_chart` (integer), `show_mean_line` (boolean)

---

## heatmap

Matrix heatmap with color intensity showing value magnitude.

**Format:** single object

| Field      | Type  | Required | Description                              |
|------------|-------|----------|------------------------------------------|
| matrix     | array | yes      | 2D array of numbers (rows x cols); null for missing |
| row_labels | array | yes      | Labels for each row                      |
| col_labels | array | yes      | Labels for each column                   |

```json
{
  "matrix": [
    [1.2, 3.4, 2.1],
    [4.5, null, 1.8],
    [2.3, 3.1, 5.0]
  ],
  "row_labels": ["Row A", "Row B", "Row C"],
  "col_labels": ["Col 1", "Col 2", "Col 3"]
}
```

**Chart params:** `value_label` (string), `x_label` (string),
`show_values` (boolean), `color_scheme` (diverging | sequential)

---

## boxplot

Box plot showing distribution with quartiles, whiskers, and outliers.

**Format:** list of objects

| Field  | Type   | Required | Description              |
|--------|--------|----------|--------------------------|
| name   | string | yes      | Series name              |
| values | array  | yes      | Array of numeric values  |

```json
[
  {"name": "Server A", "values": [12, 15, 14, 18, 22, 13, 16, 45]},
  {"name": "Server B", "values": [8, 9, 11, 10, 12, 9, 10, 11]}
]
```

**Chart params:** `y_label` (string), `show_stats` (boolean),
`show_mean` (boolean)

---

## line

Line chart for time series or trend visualization.

**Format:** list of objects

| Field  | Type   | Required | Description                    |
|--------|--------|----------|--------------------------------|
| series | string | yes      | Series name for grouping       |
| x      | number | yes      | X-axis value (numeric or string) |
| y      | number | yes      | Y-axis value                   |
| label  | string | no       | Optional point label           |

```json
[
  {"series": "Sales", "x": 1, "y": 100},
  {"series": "Sales", "x": 2, "y": 140},
  {"series": "Sales", "x": 3, "y": 120},
  {"series": "Costs", "x": 1, "y": 80},
  {"series": "Costs", "x": 2, "y": 90},
  {"series": "Costs", "x": 3, "y": 85}
]
```

**Chart params:** `x_label` (string), `y_label` (string),
`show_trend` (boolean)

---

## scatter

Scatter plot for comparing two dimensions with optional Pareto frontier.

**Format:** list of objects

| Field     | Type    | Required | Description               |
|-----------|---------|----------|---------------------------|
| name      | string  | yes      | Point label               |
| x         | number  | yes      | X-axis value              |
| y         | number  | yes      | Y-axis value              |
| is_pareto | boolean | no       | Mark as Pareto-optimal    |

```json
[
  {"name": "Alpha", "x": 10, "y": 95, "is_pareto": true},
  {"name": "Beta", "x": 25, "y": 88},
  {"name": "Gamma", "x": 15, "y": 92, "is_pareto": true},
  {"name": "Delta", "x": 40, "y": 70}
]
```

**Chart params:** `x_label` (string), `y_label` (string),
`show_pareto` (boolean)

---

## comparison

Side-by-side paired bar chart comparing baseline vs. comparison values.

**Format:** list of objects

| Field            | Type   | Required | Description                |
|------------------|--------|----------|----------------------------|
| label            | string | yes      | Item label                 |
| baseline_value   | number | yes      | Baseline measurement       |
| comparison_value | number | yes      | Comparison measurement     |
| baseline_name    | string | no       | Name for baseline series   |
| comparison_name  | string | no       | Name for comparison series |

```json
[
  {"label": "Query 1", "baseline_value": 120, "comparison_value": 95},
  {"label": "Query 2", "baseline_value": 200, "comparison_value": 180},
  {"label": "Query 3", "baseline_value": 80, "comparison_value": 110}
]
```

**Chart params:** `metric_label` (string)

---

## diverging

Centered diverging bar chart showing percentage change.

**Format:** list of objects

| Field      | Type   | Required | Description                                       |
|------------|--------|----------|---------------------------------------------------|
| label      | string | yes      | Item label                                        |
| pct_change | number | yes      | Percentage change (negative = improvement)        |

```json
[
  {"label": "Query 1", "pct_change": -25.3},
  {"label": "Query 2", "pct_change": 12.8},
  {"label": "Query 3", "pct_change": -8.1},
  {"label": "Query 4", "pct_change": 45.0}
]
```

**Chart params:** `clip_pct` (number, default 200.0)

---

## summary

Bordered summary box with aggregate statistics.

**Format:** single object

| Field                | Type    | Required | Description                                  |
|----------------------|---------|----------|----------------------------------------------|
| title                | string  | no       | Summary box title                            |
| primary_value        | number  | no       | Primary aggregate value (e.g. geometric mean)|
| secondary_value      | number  | no       | Secondary aggregate value (e.g. median)      |
| total_value          | number  | no       | Total aggregate value                        |
| primary_baseline     | number  | no       | Baseline primary value                       |
| primary_comparison   | number  | no       | Comparison primary value                     |
| total_baseline       | number  | no       | Baseline total value                         |
| total_comparison     | number  | no       | Comparison total value                       |
| primary_label        | string  | no       | Label for primary value (default: "Geo Mean")|
| secondary_label      | string  | no       | Label for secondary value (default: "Median")|
| total_label          | string  | no       | Label for total value (default: "Total")     |
| count_label          | string  | no       | Label for item count (default: "Queries")    |
| baseline_name        | string  | no       | Baseline label                               |
| comparison_name      | string  | no       | Comparison label                             |
| num_items            | integer | no       | Number of items                              |
| num_improved         | integer | no       | Count of improved items                      |
| num_stable           | integer | no       | Count of stable items                        |
| num_regressed        | integer | no       | Count of regressed items                     |
| best_items           | array   | no       | List of [name, value] pairs for best items   |
| worst_items          | array   | no       | List of [name, value] pairs for worst items  |
| environment          | object  | no       | Environment info dict                        |
| platform_config      | object  | no       | Platform config dict                         |
| metric_label         | string  | no       | Unit label for values (default: "ms")        |

```json
{
  "title": "Performance Summary",
  "primary_value": 142.5,
  "secondary_value": 128.0,
  "num_items": 10,
  "num_improved": 6,
  "num_stable": 2,
  "num_regressed": 2,
  "best_items": [["Q3", 45.2], ["Q7", 52.1]],
  "worst_items": [["Q1", 312.5]]
}
```

---

## percentile

Layered percentile bands showing P50/P90/P95/P99 distribution.

**Format:** list of objects

| Field | Type   | Required | Description              |
|-------|--------|----------|--------------------------|
| name  | string | yes      | Series name              |
| p50   | number | yes      | 50th percentile value    |
| p90   | number | yes      | 90th percentile value    |
| p95   | number | yes      | 95th percentile value    |
| p99   | number | yes      | 99th percentile value    |

```json
[
  {"name": "API v1", "p50": 45, "p90": 120, "p95": 200, "p99": 450},
  {"name": "API v2", "p50": 30, "p90": 85, "p95": 140, "p99": 310}
]
```

**Chart params:** `metric_label` (string)

---

## speedup

Log-scale normalized speedup chart relative to a baseline.

**Format:** list of objects

| Field       | Type    | Required | Description                                    |
|-------------|---------|----------|------------------------------------------------|
| name        | string  | yes      | Platform or variant name                       |
| ratio       | number  | yes      | Speedup ratio (2.0 = 2x faster)               |
| is_baseline | boolean | no       | Mark as baseline (ratio=1.0)                   |

```json
[
  {"name": "Baseline", "ratio": 1.0, "is_baseline": true},
  {"name": "Optimized", "ratio": 2.4},
  {"name": "Experimental", "ratio": 0.8}
]
```

**Chart params:** `baseline_name` (string)

---

## stacked

Stacked horizontal bar chart showing component breakdown.

**Format:** list of objects

| Field    | Type   | Required | Description                                    |
|----------|--------|----------|------------------------------------------------|
| label    | string | yes      | Bar label                                      |
| segments | array  | yes      | List of `{phase_name, value, color?}` segments |
| total    | number | no       | Override total (auto-computed if omitted)       |

```json
[
  {
    "label": "Server A",
    "segments": [
      {"phase_name": "Parse", "value": 30},
      {"phase_name": "Execute", "value": 85},
      {"phase_name": "Serialize", "value": 15}
    ]
  },
  {
    "label": "Server B",
    "segments": [
      {"phase_name": "Parse", "value": 25},
      {"phase_name": "Execute", "value": 60},
      {"phase_name": "Serialize", "value": 20}
    ]
  }
]
```

**Chart params:** `metric_label` (string, default "ms")

---

## sparkline

Compact table with inline sparkline mini-charts.

**Format:** single object

| Field     | Type  | Required | Description                                             |
|-----------|-------|----------|---------------------------------------------------------|
| rows      | array | yes      | List of row names                                       |
| columns   | array | yes      | List of `{name, values: {row: number}, higher_is_better?}` |

```json
{
  "rows": ["PostgreSQL", "MySQL", "SQLite"],
  "columns": [
    {
      "name": "Throughput",
      "values": {"PostgreSQL": 1200, "MySQL": 950, "SQLite": 400},
      "higher_is_better": true
    },
    {
      "name": "Latency (ms)",
      "values": {"PostgreSQL": 12, "MySQL": 18, "SQLite": 5}
    }
  ]
}
```

---

## cdf

Cumulative distribution function chart for comparing distributions.

**Format:** list of objects

| Field  | Type   | Required | Description              |
|--------|--------|----------|--------------------------|
| name   | string | yes      | Series name              |
| values | array  | yes      | Array of numeric values  |

```json
[
  {"name": "Before", "values": [10, 15, 12, 18, 22, 30, 45, 50]},
  {"name": "After", "values": [8, 10, 11, 13, 14, 16, 20, 22]}
]
```

**Chart params:** `x_label` (string), `y_label` (string),
`height` (integer)

---

## rank

Competitive ranking table with win counts across items.

**Format:** single object

| Field  | Type   | Required | Description                                      |
|--------|--------|----------|--------------------------------------------------|
| items  | array  | yes      | List of item names                               |
| groups | array  | yes      | List of group names                              |
| values | object | yes      | Mapping of `"group,item"` keys to numeric values |

```json
{
  "items": ["Q1", "Q2", "Q3"],
  "groups": ["Postgres", "MySQL"],
  "values": {
    "Postgres,Q1": 120,
    "Postgres,Q2": 85,
    "Postgres,Q3": 200,
    "MySQL,Q1": 130,
    "MySQL,Q2": 90,
    "MySQL,Q3": 180
  }
}
```

---

## Common Options

These options apply to all chart types and can be passed as CLI flags or
top-level keys in MCP tool calls:

| Option      | Type    | Default | Description                          |
|-------------|---------|---------|--------------------------------------|
| title       | string  | —       | Chart title                          |
| subtitle    | string  | —       | Subtitle line displayed below title  |
| width       | integer | auto    | Chart width in characters            |
| height      | integer | auto    | Chart height in rows                 |
| use_color   | boolean | true    | Enable ANSI color output             |
| use_unicode | boolean | true    | Enable Unicode box-drawing           |
| theme       | string  | light   | Color theme (light or dark)          |
| show_legend | boolean | true    | Show chart legend                    |
| show_values | boolean | true    | Show numeric values on chart         |

CLI flags use `--no-color` / `--no-unicode` to disable.
