contracts

type ChartData struct {
	// Series is the chart's named series; at least one is expected. An
	// empty Series drives the App's empty state.
	Series []ChartSeries `json:"series"`
	// Categories are the shared-axis category labels (e.g. months on a
	// bar chart's x-axis). Optional for chart types that do not use them
	// (pie, radar, scatter).
	Categories []string `json:"categories,omitempty"`
}

type ChartSeries struct {
	// Name is the series label rendered in the legend.
	Name string `json:"name"`
	// Values is the series' numeric values. For scatter and radar the
	// app expects paired values; for the rest, one value per category.
	Values []float64 `json:"values"`
}

type ChartType string

type CreateChartInput struct {
	// Type is the chart kind: bar | line | area | pie | scatter | radar.
	Type ChartType `json:"type"`
	// Data is the chart payload: one or more named series, plus optional
	// category labels for the shared axis.
	Data ChartData `json:"data"`
	// Title is an optional chart title rendered above the chart.
	Title string `json:"title,omitempty"`
	// Options is an optional passthrough of ECharts option overrides. The
	// App merges them over the sensible defaults Dockyard derives from
	// Type + Data, so a developer can override colors, axis ticks, legend
	// placement, etc. Renderer-agnostic in framing — the field is opaque
	// in the contract — but its V1 keys mirror the ECharts schema.
	Options map[string]any `json:"options,omitempty"`
	// Theme is the per-call theme override. "auto" (default) honours the
	// host theme propagated via `hostContext.styles.variables`.
	Theme ThemeMode `json:"theme,omitempty"`
}

type CreateChartOutput struct {
	// Kind is always "chart" for a create_chart output. The dispatcher
	// reads it to route to the chart renderer.
	Kind string `json:"kind"`
	// Type is the chart kind, passed through from the input.
	Type ChartType `json:"type"`
	// Data is the chart payload, passed through.
	Data ChartData `json:"data"`
	// Title is the chart title, passed through (empty when not set).
	Title string `json:"title,omitempty"`
	// Options is the ECharts option override, passed through.
	Options map[string]any `json:"options,omitempty"`
	// Theme is the resolved theme: never "auto" — the handler resolves
	// "auto" against the host context.
	Theme ThemeMode `json:"theme"`
	// State is the UI state the App enters: "ready" | "empty" |
	// "error" | "permission" | "loading". Fixtures drive each value to
	// exercise the four-state PageState in the inspector switcher.
	State WidgetState `json:"state"`
	// Message is the human-readable message rendered in the non-ready
	// states (e.g. "No revenue this period.", "Not authorized to view
	// this chart.", "Loading…"). Empty in the ready state.
	Message string `json:"message,omitempty"`
}

type CreateMetricCardInput struct {
	// Label is the metric name (e.g. "Customer health").
	Label string `json:"label"`
	// Value is the metric's primary value. JSON-numeric or string; the
	// renderer prints it verbatim. Required.
	Value any `json:"value"`
	// Unit is the optional value suffix ("$", "%", "ms", …).
	Unit string `json:"unit,omitempty"`
	// Delta is the optional period-over-period change.
	Delta *MetricDelta `json:"delta,omitempty"`
	// Series is the optional sparkline series — when present the App
	// renders the shared web/ui Sparkline next to the value.
	Series []float64 `json:"series,omitempty"`
	// Breakdowns are optional sub-rows (top contributors / segments). An
	// empty Breakdowns is rendered as "no breakdown for this metric".
	Breakdowns []MetricBreakdown `json:"breakdowns,omitempty"`
	// Theme is the per-call theme override.
	Theme ThemeMode `json:"theme,omitempty"`
}

type CreateMetricCardOutput struct {
	// Kind is always "metric_card" — dispatcher reads it.
	Kind string `json:"kind"`
	// Label, Value, Unit, Delta, Series, Breakdowns are passed through.
	Label      string            `json:"label"`
	Value      any               `json:"value"`
	Unit       string            `json:"unit,omitempty"`
	Delta      *MetricDelta      `json:"delta,omitempty"`
	Series     []float64         `json:"series,omitempty"`
	Breakdowns []MetricBreakdown `json:"breakdowns,omitempty"`
	// Theme is the resolved theme.
	Theme ThemeMode `json:"theme"`
	// State is the UI state ("ready" | "empty" | "error" | "permission"
	// | "loading").
	State WidgetState `json:"state"`
	// Message is the human-readable message for non-ready states.
	Message string `json:"message,omitempty"`
}

type CreateTableInput struct {
	// Columns is the table's column definitions.
	Columns []TableColumn `json:"columns"`
	// Rows is the table's row set. An empty Rows drives the empty state.
	Rows []map[string]any `json:"rows"`
	// Sort is the requested sort. Optional — the App's DataTable allows
	// client-side re-sort.
	Sort *TableSort `json:"sort,omitempty"`
	// Theme is the per-call theme override. "auto" honours the host.
	Theme ThemeMode `json:"theme,omitempty"`
}

type CreateTableOutput struct {
	// Kind is always "table" — dispatcher reads it.
	Kind string `json:"kind"`
	// Columns is the column set, passed through.
	Columns []TableColumn `json:"columns"`
	// Rows is the row set, passed through.
	Rows []map[string]any `json:"rows"`
	// Sort is the resolved sort.
	Sort *TableSort `json:"sort,omitempty"`
	// Theme is the resolved theme (never "auto").
	Theme ThemeMode `json:"theme"`
	// State is the UI state ("ready" | "empty" | "error" | "permission"
	// | "loading").
	State WidgetState `json:"state"`
	// Message is the human-readable message for non-ready states.
	Message string `json:"message,omitempty"`
}

type MetricBreakdown struct {
	// Label is the breakdown row's name.
	Label string `json:"label"`
	// Value is the breakdown row's value (printed verbatim).
	Value any `json:"value"`
	// Share is the optional percentage share of the total (0..1). When
	// present the App renders it as a small percentage chip.
	Share float64 `json:"share,omitempty"`
}

type MetricDelta struct {
	// Value is the delta text rendered next to the value (e.g. "+12%",
	// "-3").
	Value string `json:"value"`
	// Tone colors the delta: "ok" (green-ish) | "warn" (amber) | "error"
	// (red).
	Tone MetricDeltaTone `json:"tone"`
}

type MetricDeltaTone string

type TableColumn struct {
	// Key is the row map key whose value lands in this column.
	Key string `json:"key"`
	// Label is the human-facing column header.
	Label string `json:"label"`
	// Type is the column's value type ("string", "number", "currency",
	// "percent", "date", "status"). The renderer formats accordingly.
	Type TableColumnType `json:"type"`
	// Sortable opts the column into client-side sorting.
	Sortable bool `json:"sortable,omitempty"`
}

type TableColumnType string

type TableSort struct {
	// Column is the column Key the table is sorted by.
	Column string `json:"column"`
	// Dir is "asc" or "desc".
	Dir string `json:"dir"`
}

type ThemeMode string

type WidgetState string