reports

type Bind struct {
	Target string
	From   string
	To     string
}

type ChartSpec = viz.ChartSpec

type ColumnSpec = viz.ColumnSpec

type Control struct {
	Label string `json:"label"`
	// Kind is one of ControlKinds; empty means inferred from the bound
	// leaf's GraphQL type where it is known.
	Kind     string `json:"control,omitempty"`
	Bind     Bind   `json:"bind"`
	Required bool   `json:"required,omitempty"`
	// Template wraps the raw input for the QUERIES — the placeholder is
	// {value}, so "%{value}%" turns a search box into an ilike argument.
	// Applied server-side at bind time; the echoed variables stay raw, so
	// the panel always shows what the user typed.
	Template string   `json:"template,omitempty"`
	Min      *float64 `json:"min,omitempty"`
	Max      *float64 `json:"max,omitempty"`
	// Options (static) and OptionsQuery (resolved by a data query) are
	// mutually exclusive; an enum-typed bind needs neither — its options
	// come from the schema.
	Options      []Option      `json:"options,omitempty"`
	OptionsQuery *OptionsQuery `json:"options_query,omitempty"`
}

type ControlOptions struct {
	Label   string   `json:"label"`
	Options []Option `json:"options,omitempty"`
	Error   string   `json:"error,omitempty"`
}

type Option struct {
	Value any    `json:"value"`
	Label string `json:"label,omitempty"`
}

type OptionsQuery struct {
	Query string `json:"query"`
	JQ    string `json:"jq,omitempty"`
}

type ReportData struct {
	Variables map[string]any   `json:"variables"`
	Controls  []ControlOptions `json:"controls,omitempty"`
	Sections  []SectionData    `json:"sections,omitempty"`
}

type RunOptions struct {
	// QueryTTL is the cache hint for every query this run executes
	// (MCP_QUERY_TTL) — a re-render with unchanged variables becomes cache
	// reads.
	QueryTTL time.Duration
	// MaxTimeout caps the spec's requested deadline; 0 means the built-in
	// 5-minute ceiling.
	MaxTimeout time.Duration
	// OptionsOnly resolves the control option lists and skips the sections —
	// the light mode a changed parent variable needs to refresh dependent
	// lists without re-running the whole report.
	OptionsOnly bool
}

type Section struct {
	Kind        string `json:"kind"`
	Title       string `json:"title,omitempty"`
	Description string `json:"description,omitempty"`
	// Width is the human layout word (full | two_thirds | half | third |
	// quarter); Span is the fine-grained 1..12 alternative. At most one.
	Width string `json:"width,omitempty"`
	Span  int    `json:"span,omitempty"`
	// PageBreak "before" forces a page break in print.
	PageBreak string `json:"page_break,omitempty"`

	Query    string       `json:"query,omitempty"`
	JQ       string       `json:"jq,omitempty"`
	Chart    *ChartSpec   `json:"chart,omitempty"`
	Columns  []ColumnSpec `json:"columns,omitempty"`
	Markdown string       `json:"markdown,omitempty"`
}

type SectionData struct {
	Kind      string           `json:"kind"`
	Rows      []map[string]any `json:"rows,omitempty"`
	Kpis      []viz.KPI        `json:"kpis,omitempty"`
	RowCount  int              `json:"row_count,omitempty"`
	Truncated bool             `json:"truncated,omitempty"`
	AtLimit   bool             `json:"at_limit,omitempty"`
	// RowsSampled is set only on the wire copy the model (and the first
	// widget render) receives; the view pulls the full rows itself.
	RowsSampled bool   `json:"rows_sampled,omitempty"`
	Error       string `json:"error,omitempty"`
}

type Spec struct {
	Title       string     `json:"title"`
	Description string     `json:"description,omitempty"`
	Variables   []Variable `json:"variables,omitempty"`
	Controls    []Control  `json:"controls,omitempty"`
	Sections    []Section  `json:"sections"`
	// TimeoutSec overrides the shared run deadline (default 60), capped by
	// the server's own limit at run time.
	TimeoutSec int `json:"timeout_seconds,omitempty"`
}

type Variable struct {
	Name string `json:"name"`
	Type string `json:"type"`
	// Default applies when no value is submitted at all; an explicit null
	// stays null (that is how a filter is cleared).
	Default  any  `json:"default,omitempty"`
	Required bool `json:"required,omitempty"`
}