theme

type Option func(*Theme)

type Theme struct {
	Name string

	// Surfaces.
	Background ir.Color // outside the plot area
	PlotFill   ir.Color // inside the plot area

	// Text.
	FontFamily string
	TitleSize  float64
	LabelSize  float64
	TickSize   float64
	TitleColor ir.Color
	LabelColor ir.Color
	TickColor  ir.Color

	// Axes and grid.
	AxisColor     ir.Color
	AxisWidth     float32
	GridColor     ir.Color
	GridWidth     float32
	GridDash      []float32
	TickLength    float32
	TickLabelPad  float32
	AxisTitlePad  float32
	ShowGridX     bool
	ShowGridY     bool
	ShowAxisLineX bool
	ShowAxisLineY bool
	// ShowTicksX and ShowTicksY turn each axis's tick marks and tick labels on
	// or off. They are the third of the three furniture switches, and the one
	// a chart drawn in a coordinate system that does not want an axis reaches
	// for: a pie has no radial quantity to label, and the numbers a linear
	// scale puts round the outside of one are noise about a slot rather than
	// information about the data.
	ShowTicksX     bool
	ShowTicksY     bool
	TickCountHintX int
	TickCountHintY int

	// Legend.
	LegendSwatch  float32
	LegendPad     float32
	LegendGap     float32
	LegendColor   ir.Color
	LegendBG      ir.Color
	LegendBorder  ir.Color
	LegendPadding float32

	// Guides. A chart can carry more than one — a legend for the layers that
	// have a colour each, a colourbar for a layer whose colour comes from a
	// continuous scale — and they stack in one column beside the plot.
	GuideGap float32 // vertical gap between stacked guides

	// Colourbar.
	ColorbarThickness float32 // across the bar
	ColorbarFraction  float64 // of the plot height, before clamping
	ColorbarBorder    ir.Color
	ColorbarTickCount int

	// Size key: the ladder of sample marks a size channel is read off.
	// BubbleSize is the diameter of the largest mark a size scale draws, and
	// therefore the widest sample the key shows; SizeKeyCount is how many
	// samples it shows.
	BubbleSize   float32
	SizeKeyCount int

	// Annotations: reference lines, bands and labels that are not data.
	AnnotationColor   ir.Color
	AnnotationWidth   float32
	AnnotationDash    []float32
	AnnotationOpacity float64 // fill alpha for a shaded band

	// Panels: subplots and facets.
	PanelGap    float32 // between adjacent panels
	StripBG     ir.Color
	StripColor  ir.Color
	StripSize   float64
	StripPad    float32
	StripBorder ir.Color

	// Spacing.
	Margin float32 // outer margin on all four sides

	// Series colours, and the ramps a colour scale falls back to.
	Palette    palette.Qualitative
	Sequential palette.Ramp
	Diverging  palette.Ramp

	// SeriesDashes and SeriesMarkers are the redundant encoding: a second and
	// a third channel a layer is told apart by, so that colour is not the only
	// one. A layer that set neither [github.com/timzifer/figure/geom.Dash]
	// nor [github.com/timzifer/figure/geom.Shape] takes the entry at its own
	// index, the same way it takes its colour from Palette.
	//
	// Both are empty by default, which draws exactly what figure has always
	// drawn. [Redundant] fills them in. See docs/adr/0024.
	SeriesDashes  [][]float32
	SeriesMarkers []ir.Marker

	// A projected scene. A flat chart needs none of this; a three-dimensional
	// one needs to know which way the light falls and what a face turned
	// toward it and away from it are mixed toward. There is one directional
	// light and no model beyond it: no specular, no shadows, no ambient
	// occlusion, no textures — see docs/adr/0056-three-dimensional-charts.md.
	//
	// DepthTop and DepthSide are ADR 0055's two shades under ADR 0055's
	// names: a mark extruded by an oblique coord and a face of a surface are
	// both a colour seen in depth, and one ladder is right for both.
	LightDir   [3]float32 // unit direction the light comes from, in scene space
	LightFloor float64    // how lit the least-lit face still is, in [0, 1]
	DepthTop   ir.Color   // a face turned toward the light mixes toward this
	DepthSide  ir.Color   // one turned away mixes toward this
	CubeFill   ir.Color   // the three faces a projected cube shows
	CubeEdge   ir.Color   // its edges
	CubeGrid   ir.Color   // the grid drawn on those faces

	// Default geometry weights.
	LineWidth  float32
	MarkerSize float32
}

type Tokens struct {
	// Name identifies the theme, and is the key it registers under.
	Name string

	// Background is the canvas outside the plot area; Panel is the fill
	// inside it, normally transparent so the background shows through; Strip
	// is the band a facet's label sits in.
	Background ir.Color
	Panel      ir.Color
	Strip      ir.Color

	// Ink runs from the strongest text to the faintest: a title, a label, a
	// tick. Three levels is enough to build a hierarchy and few enough that a
	// second theme has to answer only three questions.
	Ink       ir.Color
	InkMuted  ir.Color
	InkSubtle ir.Color

	// Line is the axis; LineSubtle is the grid behind the data.
	Line       ir.Color
	LineSubtle ir.Color

	// FontFamily is the logical family; "" means the backend's default sans.
	FontFamily string

	// FontSize is the label size in device units. The title and tick sizes
	// derive from it — see [Build].
	FontSize float64

	// Space is the spacing unit every padding and gap is a multiple of.
	Space float64

	// Palette colours the layers of a chart; Sequential and Diverging are the
	// ramps a colour scale falls back to when it is given none.
	Palette    palette.Qualitative
	Sequential palette.Ramp
	Diverging  palette.Ramp
}