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
}

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 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 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
}