# Charts

Reference for the `chart` tool — native PowerPoint charts (not images of charts), backed by an
embedded chart data sheet.

## Actions

| Tool | Action | Parameters | Notes |
|------|--------|------------|-------|
| `chart` | `add-chart` | `presentation_session_id`, `slide_index`, `chart_type`, `left`, `top`, `width`, `height`, `categories` (string array), `series_name` (string), `values` (double array) | Creates a native chart shape with **one** data series. |
| `chart` | `get-chart-data` | `presentation_session_id`, `slide_index`, `shape_index` | Returns `categoryCount` and `seriesCount` of an existing chart — dimensions only, not the raw values. |
| `chart` | `add-series` | `presentation_session_id`, `slide_index`, `shape_index`, `series_name`, `values` (double array) | Adds one more data series to an existing chart. `values` length must match the chart's existing category count. Call repeatedly to build an N-series chart. |
| `chart` | `replace-chart-data` | `presentation_session_id`, `slide_index`, `shape_index`, `categories` (string array), `series_names` (string array), `series_values` (double array, **series-major flat**) | Replaces ALL of an existing chart's categories/series/values in one call — including changing the category count. See "Replacing Chart Data" below for the flat layout. |
| `chart` | `set-chart-title` | `presentation_session_id`, `slide_index`, `shape_index`, `title` | Sets/shows the chart's title text. |
| `chart` | `get-chart-title` | `presentation_session_id`, `slide_index`, `shape_index` | Returns `hasTitle` and, if present, `title`. |
| `chart` | `set-axis-title` | `presentation_session_id`, `slide_index`, `shape_index`, `axis_type` (`"category"` or `"value"`), `title` | Sets the title of the category (X) or value (Y) axis. |
| `chart` | `get-axis-title` | `presentation_session_id`, `slide_index`, `shape_index`, `axis_type` (`"category"` or `"value"`) | Returns the axis title text. |
| `chart` | `set-legend-visibility` | `presentation_session_id`, `slide_index`, `shape_index`, `visible` (bool) | Shows/hides the chart's legend. |
| `chart` | `get-legend-visibility` | `presentation_session_id`, `slide_index`, `shape_index` | Returns `legendVisible`. |
| `chart` | `set-style` | `presentation_session_id`, `slide_index`, `shape_index`, `style` (integer, 1-48) | Applies a built-in chart layout/style and returns `chartStyle`. |
| `chart` | `get-style` | `presentation_session_id`, `slide_index`, `shape_index` | Returns the current `chartStyle`. |
| `chart` | `set-color-style` | `presentation_session_id`, `slide_index`, `shape_index`, `color_style` (integer, 1-26) | Applies a built-in chart color palette and returns `colorStyle`. |
| `chart` | `get-color-style` | `presentation_session_id`, `slide_index`, `shape_index` | Returns the current `colorStyle`. |
| `chart` | `set-data-table` | `presentation_session_id`, `slide_index`, `shape_index`, `visible` (bool) | Shows or hides the chart's data table and returns `hasDataTable`. |
| `chart` | `get-data-table` | `presentation_session_id`, `slide_index`, `shape_index` | Returns `hasDataTable`. |

## Supported Chart Types

`chart_type` is a plain string: `"bar"`, `"line"`, or `"pie"`. There is no doughnut, scatter, area,
or 3D variant in this tool surface — pick the closest of the three:

| Need | Use |
|------|-----|
| Comparing categories side by side | `"bar"` |
| Trend over time | `"line"` |
| Part-of-whole (few categories) | `"pie"` |

## Multi-Series Charts

`chart(action: "add-chart", ...)` always creates the chart with exactly one series. To add more
series (e.g., "Revenue" and "Cost" side by side), call `chart(action: "add-series", ...)` once per
additional series against the shape returned by `add-chart`:

```
chart(action: "add-chart", presentation_session_id: ..., slide_index: ..., chart_type: "bar",
  left: 60, top: 120, width: 500, height: 300,
  categories: ["Q1", "Q2", "Q3", "Q4"],
  series_name: "Revenue",
  values: [120.0, 150.0, 170.0, 210.0])
# → shapeIndex from the result above

chart(action: "add-series", presentation_session_id: ..., slide_index: ..., shape_index: <shapeIndex>,
  series_name: "Cost", values: [80.0, 95.0, 110.0, 130.0])
```

Each `add-series` call's `values` array length must match the chart's existing category count
(from the original `add-chart` call) — a mismatch returns `Success=false` without throwing.

## Replacing Chart Data

Unlike `add-series` (which appends one more series to the existing category count),
`chart(action: "replace-chart-data", ...)` wholesale-replaces an existing chart's categories, series
names, and values in a single call — including changing the number of categories. This avoids the
delete-shape-and-recreate workaround mentioned above.

`series_values` is a **flat, series-major** array: all values for `series_names[0]` first, then all
values for `series_names[1]`, etc. Its length must equal `categories.length * series_names.length`.

```
chart(action: "replace-chart-data", presentation_session_id: ..., slide_index: ..., shape_index: <shapeIndex>,
  categories: ["Jan", "Feb", "Mar", "Apr"],
  series_names: ["Revenue", "Cost"],
  # Revenue: 100, 200, 300, 400 — then Cost: 50, 60, 70, 80
  series_values: [100.0, 200.0, 300.0, 400.0, 50.0, 60.0, 70.0, 80.0])
```

A mismatched `series_values` length or an invalid/non-chart `shape_index` returns `Success=false`
without throwing.

## Pie Charts

For `"pie"`, `categories` become the slice labels and `values` the slice sizes — keep to 6 or
fewer categories so labels stay legible once rendered. `add-series` is rarely useful on a pie
chart (pie charts render only their first series).

## Titles and Legend

Use `set-chart-title`/`set-axis-title` to label the chart and its axes directly, instead of (or in
addition to) a nearby text-box callout:

```
chart(action: "set-chart-title", presentation_session_id: ..., slide_index: ..., shape_index: ..., title: "Quarterly Revenue")
chart(action: "set-axis-title", presentation_session_id: ..., slide_index: ..., shape_index: ..., axis_type: "category", title: "Quarter")
chart(action: "set-axis-title", presentation_session_id: ..., slide_index: ..., shape_index: ..., axis_type: "value", title: "USD (thousands)")
chart(action: "set-legend-visibility", presentation_session_id: ..., slide_index: ..., shape_index: ..., visible: true)
```

`set-legend-visibility` with `visible: true` is recommended whenever a chart has more than one
series — without a visible legend, a multi-series chart's colors are unlabeled.

## Quick Formatting

Use the paired style, color-style, and data-table actions to make a chart visually consistent and
then verify the saved state:

```
chart(action: "set-style", presentation_session_id: ..., slide_index: ..., shape_index: ..., style: 10)
chart(action: "get-style", presentation_session_id: ..., slide_index: ..., shape_index: ...)
chart(action: "set-color-style", presentation_session_id: ..., slide_index: ..., shape_index: ..., color_style: 4)
chart(action: "get-color-style", presentation_session_id: ..., slide_index: ..., shape_index: ...)
chart(action: "set-data-table", presentation_session_id: ..., slide_index: ..., shape_index: ..., visible: true)
chart(action: "get-data-table", presentation_session_id: ..., slide_index: ..., shape_index: ...)
```

Direct PIA characterization tests verify that installed PowerPoint accepts style 48 and color style
26, then rejects the first following values (49 and 27) without changing the chart. Range tests
exercise every accepted value. Commands return `Success=false` before PowerPoint is called for
values outside those observed ranges, so invalid input does not change the chart or destabilize the
presentation session.

## Sizing and Placement

- Keep charts within the slide's safe area (see `deck-builder.md` positioning reference).
- Leave room beside or below the chart for a text-box callout describing the key takeaway, unless
  you've already used `set-chart-title`/`set-axis-title` to label it directly.
- Minimum practical size: `width ≥ 300, height ≥ 200` — smaller charts render illegibly once
  exported.

## Reading Back Chart Data

`chart(action: "get-chart-data", ...)` only reports `categoryCount`/`seriesCount` — it does not
return the actual category labels or values. Use it to confirm a chart was created with the
expected shape (e.g., 4 categories, 1 series) after `add-chart`, not to recover the original data
for editing. To change the category labels or values, use `replace-chart-data` (see "Replacing
Chart Data" above) rather than deleting and recreating the shape.

## Verify Visually

Charts are the highest-value target for `export(action: "export-slide-to-image", ...)` —
data-entry mistakes (wrong values, mismatched category count) are invisible from a
`get-chart-data` call alone but obvious in the rendered image. Always export and inspect after
`add-chart`/`add-series` (see `export-and-verify.md`).