Widgets

Widgets

Four kinds (kind column). Locked contract — don’t rename.

Kind	Renders	When to use
chart	Recharts visualization per spec.kind	Time-series, breakdowns, ratios
kpi	Big number + delta vs. prior period	Single-metric watch (“days in A/R”)
table	Sortable, paginated grid	Cohort lists, exception rows
markdown	Rendered Markdown	Section headers, methodology notes, links

Per-widget fields

id:              uuid
dashboard_id:    uuid
kind:            "chart" | "kpi" | "table" | "markdown"
title:           string
spec_json:       { ... }      # kind-specific
layout_json:     { i, x, y, w, h }
last_data_json:  { ... } | null
last_error:      string | null
last_refreshed_at: datetime | null

Chart spec kinds

For kind: "chart", the spec.kind selects the Recharts component:

spec.kind	Recharts
line	<LineChart> — single or multi-series time-series
area	<AreaChart> — stacked or absolute
bar	<BarChart> — category × metric
stacked-bar	<BarChart> with stackId per series
donut	<PieChart> with inner radius
scatter	<ScatterChart> for two-metric correlations
kpi	Numeric tile (same as widget kind: "kpi" but inside a chart widget; used by Workbench → BI shape inference)
table	Tabular preview (same as kind: "table")

Spec shape always includes {kind, x_field, y_fields[], series_field?, color?, decimals?}.

KPI widget

KPI = a single metric scalar with optional delta + prior-period context. Spec:

kind:           "kpi"
spec_json:
  metric_field: "first_pass_rate"
  unit:         "%"
  precision:    1
  delta_label:  "vs. last month"

The widget’s SQL must return one row with the metric_field column. Optionally a second column named prior_<metric_field> auto-renders as the delta.

Table widget

For when the question’s answer is a list of rows (“cohort of patients with X”). Spec:

kind:            "table"
spec_json:
  columns:       ["patient_id", "name", "days_overdue"]
  default_sort:  ["days_overdue", "desc"]
  page_size:     50

Markdown widget

For documentation in the canvas — section headers, methodology notes, links to the underlying SQL in Confluence, etc.

kind:        "markdown"
spec_json:
  body:      "## Methodology\nDays-in-A/R is calculated as..."

Creating a widget

Three paths:

1. Workbench → Send to BI — preferred for ad-hoc widgets. See Workbench → BI.
2. + Widget on the canvas — opens an editor for kind + connection + SQL + spec. For hand-authored widgets.
3. Ask AI about this widget — duplicate an existing widget and tweak the spec via a natural-language prompt. See Ask AI.