graphein-mcp 0.12.0 → 0.14.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "graphein-mcp",
-  "version": "0.12.0",
+  "version": "0.14.0",
   "type": "module",
   "description": "Model Context Protocol server for Graphein — wraps generate → validate → repair → render → critique into one tool call, and serves Graphein's schema + agent guide as resources so a model that never saw the API can still build correct charts.",
   "license": "MIT",
@@ -61,9 +61,9 @@
     "prepack": "tsup"
   },
   "dependencies": {
-    "@graphein/node": "^0.12.0",
+    "@graphein/node": "^0.14.0",
     "@modelcontextprotocol/sdk": "^1.20.0",
-    "graphein": "^0.12.0",
+    "graphein": "^0.14.0",
     "zod": "^3.23.0"
   }
 }

package/resources/agent-guide.md

@@ -111,7 +111,7 @@ reference: [spec-reference → Transforms](./spec-reference.md#transforms).
 | Running total / bridge | `waterfall` | `stage`, `value` (signed deltas) |
 | Before / after by series | `slope` | `x`, `y`, `series` |
 | Gap between two groups | `dumbbell` | `category`, `value`, `group` |
-| Headline metric | `kpi` | `value`, `delta`, `sparkline` |
+| Single number / headline metric | `kpi` | `value` (+ `label`, `delta`, `sparkline`, `comparisons`) |
 | Raw/detail records | `table` | `columns` (+ optional totals, groups, bars/icons/rules) |
 | Aggregated cross‑tab | `matrix` | `rows`, `columns`, `values` (+ `showAs` percentages) |
 | Slice/filter a field | `dropdown` · `list` · `search` · `range` · `dateRange` | `field` (+ `param?`) |
@@ -354,20 +354,32 @@ Don't pre-bin or pre-count — feed one row per observation and let `bin` do the
 }
 ```
 
-**KPI with delta + sparkline**
+**KPI — scorecard (delta + sparkline + comparison rows)**
+
+The `kpi` is the only single-number visual. With just a `value` (+ `label`) it degrades to
+a clean centered **card**; add any of `delta`, `sparkline`, or `comparisons` and it becomes
+a full scorecard (label + value + ▲/▼ delta, an inline trend with min/max/last markers, and
+a divider over comparison rows).
 
 ```jsonc
 {
   "type": "kpi",
-  "label": "Total sales",
-  "value": { "field": "sales", "aggregate": "sum" },
-  "delta": 0.124,           // +12.4%, drives the up indicator
-  "format": "$,.0f",
-  "sparkline": true,
-  "data": [/* rows with a `sales` column */]
+  "label": "Total Costs AC",
+  "value": { "field": "cost", "aggregate": "sum" },
+  "format": ",.0f",
+  "sparkline": { "field": "cost", "markers": true }, // min→red, max→green, last→ring
+  "comparisons": [                                   // each row: sign drives ▲/▼ + color
+    { "label": "BU",  "delta": -0.02, "amount": -268 }, // ▼ -2% : -268  (red)
+    { "label": "PY",  "delta":  0.02, "amount":  295 }, // ▲ 2%  : 295   (green)
+    { "label": "MoM", "delta":  0.01, "amount":   96 }  // ▲ 1%  : 96    (green)
+  ],
+  "data": [/* rows with a `cost` column */]
 }
 ```
 
+A minimal card is just `{ "type": "kpi", "value": { "field": "revenue", "aggregate": "last" }, "label": "Revenue", "unit": "B" }`.
+
+
 **Table with conditional formatting**
 
 ```jsonc

package/resources/chart-spec.schema.json

@@ -2492,6 +2492,16 @@
             "$ref": "#/$defs/DashboardResponsiveSpan"
           },
           "description": "Per-view responsive span overrides; smallest matching maxWidth wins."
+        },
+        "interact": {
+          "type": "string",
+          "enum": [
+            "auto",
+            "none",
+            "source",
+            "target"
+          ],
+          "description": "This view's role in `interactions: 'auto'` cross-interaction. Default: full participation (it both drives and reacts).\n- 'none': inert — never filters/highlights others and never reacts.\n- 'source': can drive filters/highlights but is never filtered or dimmed.\n- 'target': reacts to others but never drives (e.g. a read-only detail chart). Ignored when `interactions` is `'none'` or an explicit InteractionLink array."
         }
       },
       "required": [
@@ -3729,14 +3739,8 @@
           "description": "Accessible description (alt text) for the chart. Used verbatim as the chart's `aria-label`; when omitted, a concise label is synthesized from the type, title, and data. Agents should set this to convey the chart's intent."
         },
         "legend": {
-          "anyOf": [
-            {
-              "$ref": "#/$defs/LegendConfig"
-            },
-            {
-              "type": "boolean"
-            }
-          ]
+          "type": "boolean",
+          "description": "Show a legend naming the value / comparison / track arcs (top-right). Defaults to shown when `compare` is set; otherwise hidden."
         },
         "tooltip": {
           "anyOf": [
@@ -3826,7 +3830,11 @@
         },
         "target": {
           "$ref": "#/$defs/ValueRef",
-          "description": "Optional target/threshold marker drawn as a needle/tick."
+          "description": "Optional target/threshold marker drawn as a subtle tick across the arc."
+        },
+        "compare": {
+          "$ref": "#/$defs/ValueRef",
+          "description": "Optional comparison value (e.g. a prior period) drawn as a thinner concentric arc just inside the main track."
         },
         "label": {
           "type": "string",
@@ -3834,7 +3842,7 @@
         },
         "format": {
           "type": "string",
-          "description": "Number format for the value + scale ticks (e.g. ',.0f', '.0%')."
+          "description": "Number format for the value readout (e.g. ',.0f', '.0%')."
         },
         "bands": {
           "type": "array",
@@ -3853,7 +3861,19 @@
             ],
             "additionalProperties": false
           },
-          "description": "Qualitative arc bands, each filling the scale up to `to`."
+          "description": "Qualitative arc bands — recolor the fill by the zone the value lands in."
+        },
+        "valueLabel": {
+          "type": "string",
+          "description": "Legend label for the value (fill) arc. Default 'Actual'."
+        },
+        "compareLabel": {
+          "type": "string",
+          "description": "Legend label for the comparison arc. Default 'Prior period'."
+        },
+        "trackLabel": {
+          "type": "string",
+          "description": "Legend label for the full-scale track. Default 'Target'."
         }
       },
       "required": [
@@ -3862,7 +3882,7 @@
         "max"
       ],
       "additionalProperties": false,
-      "description": "Gauge — a radial dial showing a single value against a `[min, max]` scale, with an optional `target` needle and qualitative background `bands`. The value is a literal or a field (optionally aggregated, like KpiSpec )."
+      "description": "Gauge — a clean semicircular radial-progress dial showing one value against a `[min, max]` scale. The full track is the scale (\"Target\"); an accent arc fills from the start to `value` (\"Actual\"); an optional `compare` value (e.g. a prior period) draws as a thinner concentric inner arc. A big value readout sits in the middle with `label` beneath it, and an optional `legend` names the arcs. `value`/`target`/`compare` are literals or fields (optionally aggregated, like KpiSpec ). Qualitative `bands` recolor the fill by the zone the value lands in, and `target` draws a subtle threshold tick."
     },
     "GeoFeature": {
       "type": "object",
@@ -4537,6 +4557,41 @@
       "additionalProperties": false,
       "description": "Explicit cross-interaction from one view to others (overrides auto-wiring)."
     },
+    "KpiComparison": {
+      "type": "object",
+      "properties": {
+        "label": {
+          "type": "string",
+          "description": "Short caption shown before the indicator (e.g. 'BU', 'PY', 'MoM')."
+        },
+        "delta": {
+          "$ref": "#/$defs/ValueRef",
+          "description": "The change — its sign drives the ▲/▼ indicator and green/red color."
+        },
+        "amount": {
+          "$ref": "#/$defs/ValueRef",
+          "description": "Absolute amount shown after the percentage (e.g. `: -268`)."
+        },
+        "format": {
+          "type": "string",
+          "description": "Format for `delta` (default: signed percent, e.g. `-0.02` → `-2%`)."
+        },
+        "amountFormat": {
+          "type": "string",
+          "description": "Format for `amount` (default: the KPI's `format`, else a plain integer)."
+        },
+        "invert": {
+          "type": "boolean",
+          "description": "Flip the color semantics so a *decrease* reads as good (green ▼)."
+        }
+      },
+      "required": [
+        "label",
+        "delta"
+      ],
+      "additionalProperties": false,
+      "description": "A named comparison row on a KpiSpec (e.g. vs. budget, prior year, month-over-month). The sign of `delta` drives the ▲/▼ indicator and its positive/negative color; an optional `amount` shows the absolute change after the percentage (`BU ▼ -2%: -268`)."
+    },
     "KpiSpec": {
       "type": "object",
       "properties": {
@@ -4678,14 +4733,16 @@
           "description": "Literal value or a field (optionally aggregated over data)."
         },
         "label": {
-          "type": "string"
+          "type": "string",
+          "description": "Caption shown with the value."
+        },
+        "format": {
+          "type": "string",
+          "description": "d3-format string for the value (e.g. ',.0f', '$,.2f', '.1%')."
         },
         "delta": {
           "$ref": "#/$defs/ValueRef",
-          "description": "Delta vs. a comparison, drives the up/down indicator."
-        },
-        "format": {
-          "type": "string"
+          "description": "Primary delta vs. a comparison — drives an ▲/▼ indicator under the value."
         },
         "sparkline": {
           "anyOf": [
@@ -4697,22 +4754,55 @@
               "properties": {
                 "field": {
                   "type": "string"
+                },
+                "markers": {
+                  "type": "boolean"
                 }
               },
-              "required": [
-                "field"
-              ],
               "additionalProperties": false
             }
           ],
-          "description": "Inline sparkline from a numeric field."
+          "description": "Inline trend from a numeric field. `true` uses the value's field; an object names the `field` and can toggle the min/max/last `markers` (default true)."
+        },
+        "comparisons": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/KpiComparison"
+          },
+          "description": "Named comparison rows (vs. budget, prior year, MoM …) beneath the value."
+        },
+        "align": {
+          "type": "string",
+          "enum": [
+            "start",
+            "center",
+            "end"
+          ],
+          "description": "Horizontal alignment of the value + label block. Default 'center'."
+        },
+        "labelPosition": {
+          "type": "string",
+          "enum": [
+            "above",
+            "below"
+          ],
+          "description": "Where the label sits relative to the value. Defaults to 'above' when the KPI has a delta/sparkline/comparisons, otherwise 'below' (the plain-card look)."
+        },
+        "unit": {
+          "type": "string",
+          "description": "Optional unit/suffix drawn after the value (e.g. '%', 'ms', 'MB')."
+        },
+        "color": {
+          "type": "string",
+          "description": "Value color override (defaults to the theme text color)."
         }
       },
       "required": [
         "type",
         "value"
       ],
-      "additionalProperties": false
+      "additionalProperties": false,
+      "description": "KPI — the value tile, and the *only* single-number visual. At its simplest it is one big number with an optional caption (a \"card\"); add a `delta`, a `sparkline`, and/or `comparisons` and it grows into a full scorecard. It supports horizontal `align`, a `label` placed `above`/`below`, a `unit` suffix, and a value `color`."
     },
     "LegendConfig": {
       "type": "object",

package/resources/spec-reference.md

@@ -595,15 +595,34 @@ Dense category × category grid colored by a measure.
 
 ### kpi
 
-A single stat card: big value, label, delta indicator, and inline sparkline.
+The value tile — and the **only** single-number visual. At its simplest it degrades to a
+plain **card**: one big centered number with an optional caption. Add a `delta`, a
+`sparkline`, and/or `comparisons` and it grows into a full **scorecard** — a header (label
++ value + ▲/▼ delta), an inline trend with min/max/last markers, and a divider over a
+stack of comparison rows (`BU ▼ -2% : -268`).
 
 | Field | Type | Notes |
 | --- | --- | --- |
-| `value` | `number \| { field, aggregate? }` | A literal, or a field aggregated over `data`. |
-| `label` | `string` | Caption under/above the value. |
-| `delta` | `number \| { field, aggregate? }` | Drives the up/down indicator (e.g. `0.124` → +12.4%). |
+| `value` | `number \| { field, aggregate? }` | **Required.** A literal, or a field aggregated over `data`. |
+| `label` | `string` | Caption shown with the value. |
 | `format` | `string` | [Format hint](#format-mini-language) for the value. |
-| `sparkline` | `boolean \| { field }` | Inline trend from a numeric field. |
+| `delta` | `number \| { field, aggregate? }` | Drives the primary ▲/▼ indicator under the value (e.g. `0.124` → +12.4%). |
+| `sparkline` | `boolean \| { field?, markers? }` | Inline trend from a numeric field (`true` uses the value's field). `markers` toggles the min/max/last dots (default `true`). |
+| `comparisons` | `KpiComparison[]` | Named comparison rows beneath a divider (vs. budget, prior year, MoM …). See below. |
+| `align` | `'start' \| 'center' \| 'end'` | Horizontal alignment of value + label. Default `'center'`. |
+| `labelPosition` | `'above' \| 'below'` | Where the label sits relative to the value. Defaults to `'above'` when rich (delta/sparkline/comparisons), else `'below'` (the plain-card look). |
+| `unit` | `string` | Optional suffix drawn after the value (e.g. `'%'`, `'B'`, `'ms'`). |
+| `color` | `string` | Value color override (defaults to the theme text color). |
+
+**`KpiComparison`** — one row: `{ label, delta, amount?, format?, amountFormat?, invert? }`.
+The sign of `delta` drives the ▲/▼ glyph and its green/red color; `amount` shows the
+absolute change after the percentage (`BU ▼ -2% : -268`). `format`/`amountFormat` are
+[format hints](#format-mini-language) (default: signed percent, then the KPI's `format`);
+`invert: true` flips the color so a *decrease* reads as good.
+
+> **Degrades to a card:** with only a `value` (+ optional `label`), the KPI renders as a
+> clean centered number — reach for this when you want *just the headline metric*. A field
+> value may be aggregated (e.g. `aggregate: 'last'` shows the most recent row).
 
 → [`examples/kpi.json`](./examples/kpi.json)
 
@@ -754,19 +773,28 @@ tiles, each with a header label.
 
 ### gauge
 
-A radial dial showing one value against a `[min, max]` scale, with an optional `target`
-tick and qualitative background `bands`. Like [`kpi`](#kpi), the value is a literal
-**or** a field (optionally aggregated over `data`). Renders to canvas (headless‑safe).
+A clean **semicircular radial‑progress dial** showing one value against a `[min, max]`
+scale. The full rounded track is the scale (**"Target"**); an accent arc fills from the
+start to `value` (**"Actual"**); an optional `compare` value (e.g. a prior period) draws
+as a thinner concentric inner arc (**"Prior period"**). A big value readout sits in the
+middle with `label` beneath it, and an optional `legend` (top‑right) names the arcs. Like
+[`kpi`](#kpi), `value`/`target`/`compare` are literals **or** fields (optionally aggregated
+over `data`). Renders to canvas (headless‑safe).
 
 | Field | Type | Notes |
 | --- | --- | --- |
 | `value` | `ValueRef` | The measured value: a literal number, or `{ field, aggregate? }` summarized over `data`. |
 | `max` | `number` | **Required.** Scale end (full‑scale). |
 | `min` | `number` | Scale start (default `0`). |
-| `target` | `ValueRef` | Optional threshold drawn as a needle/tick. |
-| `bands` | `{ to: number, color? }[]` | Qualitative arc bands, each filling the scale up to `to`. |
+| `target` | `ValueRef` | Optional threshold drawn as a subtle tick across the arc. |
+| `compare` | `ValueRef` | Optional comparison value (e.g. a prior period) drawn as a thinner concentric inner arc. |
+| `bands` | `{ to: number, color? }[]` | Qualitative bands — recolor the value fill by the zone the value lands in. |
 | `label` | `string` | Caption under the value (defaults to the title or value field). |
-| `format` | `string` | Number format for the value + scale ticks (e.g. `,.0f`, `.0%`). |
+| `format` | `string` | Number format for the value readout (e.g. `,.0f`, `.0%`). |
+| `legend` | `boolean` | Show a legend naming the arcs (top‑right). Defaults to shown when `compare` is set. |
+| `valueLabel` | `string` | Legend label for the value (fill) arc. Default `'Actual'`. |
+| `compareLabel` | `string` | Legend label for the comparison arc. Default `'Prior period'`. |
+| `trackLabel` | `string` | Legend label for the full‑scale track. Default `'Target'`. |
 
 → [`examples/gauge.json`](./examples/gauge.json)
 
@@ -1029,7 +1057,7 @@ views out on a responsive grid, and **auto‑wires** cross‑interaction. Valida
 | `background` | `string` | transparent | Header band tint. |
 | `collapsed` | `boolean` | `false` | Start with the body hidden behind a clickable header. |
 
-**`DashboardView`** — `{ id, spec, x?, y?, w?, h?, title?, subtitle?, frame?, background?, accent?, padding?, responsive? }`.
+**`DashboardView`** — `{ id, spec, x?, y?, w?, h?, title?, subtitle?, frame?, background?, accent?, padding?, responsive?, interact? }`.
 `id` is unique within the dashboard (used for layout + link references). `spec` is any
 chart or slicer spec (inherits the dashboard's `data` when it has none). `x`/`y` are
 1‑based grid placement (omit to auto‑flow); `w`/`h` are column/row spans (sensible
@@ -1043,6 +1071,7 @@ per‑type defaults).
 | `accent` | `string` | — | Solid left accent bar color. |
 | `padding` | `'none' \| 'standard'` | `'standard'` | Use `'none'` for flush tables/maps. |
 | `responsive` | `{ maxWidth, w?, h?, hidden? }[]` | — | Per-view span overrides at section/dashboard widths; smallest matching `maxWidth` wins. |
+| `interact` | `'auto' \| 'none' \| 'source' \| 'target'` | `'auto'` | Role in auto cross-interaction. `'none'` = inert (never drives or reacts); `'source'` = drives filters but is never filtered/dimmed itself; `'target'` = reacts to others but never drives. |
 
 **`interactions: 'auto'`** (Power BI semantics):
 
@@ -1338,12 +1367,19 @@ mirror this surface.
 ### Animation
 
 Charts play a brief **entrance animation** the first time they render; **resizes**
-are always instant (no re‑animation, no jank while dragging):
-
-- **Cartesian charts** (line/area/bar/scatter/box/heatmap) sweep their marks in
-  left‑to‑right with a short fade — the axes, gridlines, and labels are drawn
-  immediately so only the data "draws on".
-- **Pie, funnel, KPI, sankey, choropleth, tables** fade and rise in subtly.
+are always instant (no re‑animation, no jank while dragging). Each family uses the
+motion that best fits its marks — and every entrance's **final frame is
+pixel‑identical to a static draw**:
+
+- **Line / area / scatter / box** sweep their marks in left‑to‑right with a short
+  fade — axes, gridlines, and labels draw immediately so only the data "draws on".
+- **Bars grow out of the value baseline** (both grouped and stacked; horizontal bars
+  grow from the left).
+- **Pie / donut / gauge arcs sweep in** radially (the gauge fill arc and readout climb
+  from the minimum to the value).
+- **KPI numbers count up** from 0 to the value (the box is sized from the final
+  number, so the layout never reflows mid‑count).
+- **Funnel, sankey, choropleth, heatmap, treemap, tables** fade and rise in subtly.
 
 On **`update()`** (new data or config), canvas‑mark charts
 (line/area/bar/scatter/box/pie/heatmap/sankey/choropleth) **cross‑fade** the marks
@@ -1352,6 +1388,11 @@ pixel‑identical to an instant redraw. DOM charts (`kpi`/`table`/`matrix`) upda
 instantly, and a simultaneous size change snaps (that's a resize, not a data
 morph) to avoid a stretched bitmap.
 
+> All entrance styles are automatic per chart type — there's no per‑motion spec field
+> to set. *Future work:* tweening the dim/highlight on a selection change and rolling
+> `kpi` numbers from the previous value on `update()` (today they snap; the
+> entrance count‑up covers first render, reloads, and remounts).
+
 Tuning via the `animation` field:
 
 ```jsonc