render

type Chart struct {
	Width, Height int
	DPR           float64
	Theme         theme.Theme

	Title  string
	XTitle string
	YTitle string
	// Y2Title labels the secondary vertical axis, down the right-hand side,
	// and X2Title the secondary horizontal one, along the top.
	Y2Title string
	X2Title string

	X, Y scale.Scale

	// Y2 is the chart's secondary vertical axis, drawn down the right-hand
	// side, and X2 its secondary horizontal one, drawn along the top. Each is
	// read by the layers that asked for it with
	// [github.com/timzifer/refract/geom.OnY2] or OnX2, and each is nil for a
	// chart with one axis in that direction — which is every chart written
	// before there were two.
	//
	// They are the chart's rather than a panel's for the reason the coord is:
	// the panels of a facet are one plot over different rows, and a second
	// axis that meant different things in different panels would be a
	// different chart. A grid of subplots gives each panel its own through
	// [Panel.Y2] and [Panel.X2].
	Y2 scale.Scale
	X2 scale.Scale

	// Coord is the stage between the scales and the IR: what the interval a
	// scale maps into means. Nil is [coord.Cartesian], which is the identity,
	// so a chart that names no coord draws exactly what it always drew.
	//
	// It belongs to the chart rather than to a panel: the panels of a facet are
	// the same plot over different rows, and one of them in a different
	// coordinate system would be a different chart.
	Coord coord.Coord

	Layers []geom.Geom

	// ShowLegend requests a legend. Entries come from the layers.
	ShowLegend bool

	// Description is what the chart says about itself in words, for a backend
	// that can carry it — see [ir.Semantics]. It is announced before anything
	// is drawn and never affects what is.
	Description ir.Description

	// Math typesets the notation in this chart's labels. It is nil for a chart
	// whose labels are text, which is the default and costs nothing: the
	// backend is wrapped only when there is a typesetter to wrap it with.
	Math mathtext.Typesetter

	// Panels, Rows and Cols describe a multi-panel chart: subplots, or the
	// facets of one plot. When Panels is empty the chart is the single panel
	// described by X, Y and Layers.
	Panels     []Panel
	Rows, Cols int

	// RowHeights fixes the height of a grid row in device units, leaving the
	// solver to size any row whose entry is zero or absent. It is how a track
	// is given the height it was asked for, and how a subplot grid is told
	// that one of its rows is a strip rather than a panel.
	RowHeights []float32

	// ColWidths fixes the width of a grid column in device units, leaving the
	// solver to size any column whose entry is zero or absent. It is
	// RowHeights turned a quarter turn, and it is what a left or right track
	// is given its width by.
	ColWidths []float32

	// Serial draws the panels one at a time. The zero value builds them
	// concurrently where that is possible and worth it — see [drawData] — and
	// produces the same output either way.
	Serial bool

	// Observer is told which panel and which layer is drawing, so that a
	// caller watching the backend can attribute a mark to the layer that made
	// it. It is nil for an ordinary render, and setting it forces the serial
	// path: the observer is told things in order, and two panels drawing at
	// once have no order to be told in.
	Observer Observer

	// RowSink, when non-nil, collects which source row is behind each mark. It
	// is separate from Observer because it is a separate cost: a layer does
	// the bookkeeping only when someone is listening, so this is what turns it
	// on. See [geom.Rows].
	//
	// It is not called Rows because that name is already the facet grid's.
	RowSink geom.Rows

	// Hidden turns individual layers off by index, without removing them: a
	// hidden layer is not drawn, still trains its scales, and still appears in
	// the legend — dimmed, so that a reader can see what they have put away
	// and bring it back.
	//
	// It is indexed by the layer's position among the chart's layers, which is
	// the index an [Observer] is told and the one [interact.Hit] reports. A
	// shorter slice than there are layers hides none of the rest, and nil
	// hides nothing at all.
	//
	// The scales are trained from hidden layers on purpose. A legend toggle is
	// a reading aid — let me see this one without that one on top — and an
	// axis that moved every time one was clicked would make the two readings
	// incomparable, which is the thing the toggle was for. A caller who wants
	// the axes to follow what is left removes the layer instead, with
	// [Plot.SetLayers], which is a different statement about the chart.
	Hidden []bool

	// Overlay paints over the finished chart — a crosshair, a tooltip, a brush
	// rectangle. It is nil for an ordinary chart and costs nothing then.
	//
	// It is drawn last, after the guides, and is not announced to Observer:
	// what an overlay draws is not a mark and must not be hit-testable. See
	// [Overlay].
	Overlay Overlay
}

type ColorbarEntry interface {
	// ColorbarEntry reports a colourbar, or one band of a classed one.
	//
	// cs is the scale the bar was painted from, so that a caller can ask what
	// value the ramp reaches at a point of it — which is the ramp's answer
	// rather than the axis's, and the two disagree wherever the ramp is
	// compressed.
	//
	// class is the band's index and lo and hi its interval; class is -1 for a
	// continuous bar, and lo and hi are then the scale's whole domain.
	ColorbarEntry(cs scale.ColorScale, class int, lo, hi float64, area ir.Rect)
}

type EndData interface {
	// EndData reports that the data pass is over and everything after it is
	// furniture. It is called once per render, after the last layer of the
	// last panel, and is not called at all by a render with no layers.
	EndData()
}

type LayerAxes interface {
	// LayerAxes names the scales the next layer opened by [Observer.Layer] is
	// drawn against. It is called immediately before it, and both are ranged
	// for the panel already announced.
	LayerAxes(x, y scale.Scale)
}

type LegendEntry interface {
	// LegendEntry reports one row of the legend: which layer it stands for,
	// what it is labelled, the rectangle it occupies, and whether that layer
	// is currently hidden.
	//
	// layer is -1 for a row no layer can be attributed to. The rectangle spans
	// the legend's width, so the gap between a swatch and its label is part of
	// the same target — a reader aiming at a word should not have to hit the
	// word.
	LegendEntry(layer int, label string, area ir.Rect, hidden bool)
}

type Observer interface {
	// Panel opens a panel: its index in the chart, the rectangle it occupies,
	// the scales that place values in it, and the coord that turns a pair of
	// mapped positions into a point there. The scales are ranged for this
	// panel and must not be modified; the coord is framed for it and is what
	// turns a device position back into a pair — which is the only way a
	// tooltip over a pie slice names a value rather than a pixel.
	Panel(i int, area ir.Rect, x, y scale.Scale, cd coord.Coord)

	// Layer opens a layer within the panel just announced: its index among
	// that panel's layers, and its legend label if it has one.
	Layer(i int, label string)
}

type Overlay interface {
	// DrawOverlay paints over the finished chart.
	DrawOverlay(b ir.Backend, f OverlayFrame)
}

type OverlayFrame struct {
	// Canvas is the whole drawing, in device space.
	Canvas ir.Rect
	// Panels are the chart's panels, in chart order.
	Panels []OverlayPanel
	// Theme is the chart's theme, so that an overlay drawn over a dark chart
	// is legible on it.
	Theme theme.Theme
}

type OverlayPanel struct {
	// Index is the panel's position in the chart, matching the index an
	// [Observer] was told and the one [interact.Hit] reports.
	Index int
	// Area is the panel's plot rectangle in device space.
	Area ir.Rect
	// X and Y are the panel's scales, ranged to Area. An overlay reads them
	// to turn a value into a place — a crosshair at a threshold, a band
	// between two dates — and must not modify them.
	X, Y scale.Scale
	// Y2 and X2 are the panel's secondary axes, or nil where it has none.
	Y2, X2 scale.Scale
	// Coord is the coordinate system the panel was drawn in, framed to Area.
	// It is what turns a mapped pair into a point, and is [coord.Cartesian]
	// for a chart that named no coord — reach for [OverlayPanel.Coords].
	Coord coord.Coord
}

type Panel struct {
	// Row and Col place the panel in the grid.
	Row, Col int
	// Strip and RightStrip are the labels naming the panel, above it and
	// beside it.
	Strip, RightStrip string

	// X and Y are this panel's scales. Panels sharing an axis share the scale
	// object, which is what makes the axis shared rather than merely similar.
	X, Y scale.Scale

	// Y2 and X2 are this panel's secondary vertical and horizontal axes, or
	// nil for a panel with one in that direction. The layers that read them
	// are the ones that answer
	// [github.com/timzifer/refract/geom.OnSecondaryY] and OnSecondaryX.
	Y2 scale.Scale
	X2 scale.Scale

	// Coord overrides the chart's coordinate system for this panel, and is nil
	// for the panels that use it — which is every panel of a facet, because
	// the panels of a facet are one plot over different rows and one of them
	// in a different coordinate system would be a different chart.
	//
	// A grid of subplots is the case that needs it: those panels are separate
	// plots that happen to share a canvas, each with its own scales and its
	// own axes, so a pie beside a bar chart is two coords beside each other.
	Coord coord.Coord
	// Layers are this panel's marks.
	Layers []geom.Geom

	// ShowX and ShowY report whether this panel writes its own tick labels. A
	// panel that shares an axis with its neighbour leaves the labels to the
	// edge of the grid. ShowY2 and ShowX2 are the same question for the
	// secondary axes, answered at the right-hand and top edges of the grid
	// rather than the left and bottom ones.
	ShowX, ShowY, ShowY2, ShowX2 bool

	// HideGrid suppresses this panel's grid lines while leaving its fill, its
	// axes and its tick marks alone. A track — a band on the panel's own X,
	// whose rows are lanes rather than a quantity — is what it is for: a grid
	// line through a gantt strip is a rule drawn across a solid bar.
	HideGrid bool
}

type SizeKeyEntry interface {
	// SizeKeyEntry reports one row of a size key: the value its sample is
	// drawn for, how that value is spelled, and the rectangle the row
	// occupies.
	SizeKeyEntry(value float64, label string, area ir.Rect)
}