Charts¶

Actions¶

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:

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", 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", 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", 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", session_id: ..., slide_index: ..., shape_index: ..., title: "Quarterly Revenue")
chart(action: "set-axis-title", session_id: ..., slide_index: ..., shape_index: ..., axis_type: "category", title: "Quarter")
chart(action: "set-axis-title", session_id: ..., slide_index: ..., shape_index: ..., axis_type: "value", title: "USD (thousands)")
chart(action: "set-legend-visibility", 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.

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).