interact

type Event struct {
	// Kind is what happened. Every event has one.
	Kind EventKind

	// Point is where the pointer was, in device space. Hover, Click, Zoom and
	// Pan all have one; Leave carries the last position.
	Point ir.Point

	// Panel is which panel Point is in, or -1 for a point outside every panel.
	Panel int

	// Hit is the mark under the pointer, and Found whether there was one.
	// They are set on Hover and Click.
	Hit   Hit
	Found bool

	// Key identifies the row under the pointer: the value its layer's key
	// column holds at [Hit.Row], from
	// [github.com/timzifer/figure/geom.KeyBy].
	//
	// It is what a caller linking two charts sends across. A row number is an
	// index into a table as it stands this frame, so it names a different
	// measurement after an append, a filter or a window; a key is a value the
	// data carries, so it survives all three and means the same thing in
	// another chart drawn from another table.
	//
	// It is empty when the layer named no key column, when row tracking is off,
	// and when the mark has no row behind it. Those are three different reasons
	// for the same answer, and [Hit.Row] tells them apart when it matters.
	//
	// It is on the event rather than on [Hit] because reading it means reading
	// the data, and this package does not: an Index knows where marks are and
	// which layer drew them, not what the layer holds. The root package fills
	// it in, where the plot's layers and their sources are both in scope.
	Key string

	// Rect is the region a rubber-band zoom selected, in device space. It is
	// set on Zoom when the zoom came from a selection rather than a wheel;
	// [ir.Rect.Empty] reports which.
	Rect ir.Rect

	// Factor is a wheel zoom's scale factor: below 1 zooms in, above 1 zooms
	// out. It is set on Zoom when Rect is empty.
	Factor float64

	// Delta is how far a Pan moved the view, in device units.
	Delta ir.Point

	// Rows are the source rows a Select covered, in the layer named by
	// [Hit.Layer] of the panel named by Panel.
	//
	// A selection is reported one layer at a time, so a list of rows never has
	// to say which layer's rows they are: a rectangle over two crossing series
	// fires twice, and a handler that cares about one of them ignores the
	// other by its layer rather than by unpicking a mixed list.
	//
	// The rows are the positions the *layer reported*, not the ink it drew,
	// so a half-covered bar is a question about where its value is rather than
	// about where its corner is. They need row tracking — see
	// [Index.TrackRows] — and are empty without it.
	//
	// The slice is the event's own and is not reused between events, so a
	// handler may keep it.
	Rows []int
}

type EventKind uint8

type Hit struct {
	// Panel is which panel the mark is in, and Layer which layer of it.
	Panel, Layer int
	// Series is the layer's legend label, empty for a layer that has none.
	Series string
	// Kind is what sort of mark this is.
	Kind Kind
	// At is the mark's position in device space.
	At ir.Point
	// X and Y are the data values at At, read back through the panel's
	// scales. On a categorical axis the value is the category index — pass it
	// to [scale.Categorical.Labels] to name it.
	X, Y float64
	// Distance is how far At is from the point that was asked about, in
	// device units. It is zero for a point inside an area.
	Distance float32

	// Hidden reports whether the series this hit's layer is currently turned
	// off, and is only meaningful when Kind is [LegendRow]. It is what lets a
	// handler say "show" or "hide" rather than having to ask the chart.
	Hidden bool

	// Value is the quantity a guide hit stands for: the value a colourbar's
	// ramp reaches under the pointer, or the value a size key's sample is
	// drawn for. It is meaningless for every other kind, which report their
	// position through X and Y instead.
	//
	// A colourbar reads its value through the *ramp* rather than through the
	// axis beside it. The two disagree wherever the ramp is compressed — a log
	// ramp, a diverging one centred off zero — and the ramp is the thing the
	// reader is pointing at.
	Value float64

	// Area is the rectangle of the guide that was hit — a legend row, a
	// colourbar band, a whole continuous bar, a size key row. It is the empty
	// rectangle for a hit on a mark, which has no target to speak of.
	//
	// It is what a caller anchors to: a tooltip beside a legend row, or the
	// band a drag along a colourbar is painted in.
	Area ir.Rect

	// Class is which band of a classed colourbar was hit, or -1 for a hit on a
	// continuous ramp and for every kind that is not a colourbar.
	//
	// Lo and Hi are that band's interval. They are what a filter is written
	// against: a reader clicking the third band of a quantile scale means the
	// rows between those two numbers, not the single value under their finger.
	Class  int
	Lo, Hi float64

	// Row is the source row behind the mark, or -1 when it is not known.
	//
	// It is -1 unless row tracking was on for the render — see
	// [Index.TrackRows] — and it stays -1 for a mark that no row is behind: a
	// boxplot's box aggregates many rows, a density raster is not a mark, an
	// interpolated point across a gap was never measured, and a third-party
	// geom that does not report its rows has none to report.
	Row int
}

type Index struct {
	// contains filtered or unexported fields
}

type Kind uint8

type Panel struct {
	// Area is the panel's plot rectangle in device space.
	Area ir.Rect
	// X and Y are the panel's scales, ranged to Area.
	//
	// Both are nil for a panel with no screen axes — a projected scene, whose
	// marks were placed by a camera rather than by a pair of intervals. A
	// caller inverting a device position checks first, as [Index.At] does, and
	// reads the value out of [Hit.Row] instead.
	X, Y scale.Scale
	// Z is the panel's depth scale, non-nil only for a panel announced by
	// [github.com/timzifer/figure/three]. ADR 0056 is the record.
	Z scale.Scale
	// Y2 and X2 are the panel's secondary vertical and horizontal axes, when a
	// layer in it was drawn against one, and nil otherwise.
	//
	// They are discovered from the layers rather than announced with the
	// panel: [render.Observer.Panel] carries the two scales a panel has always
	// had and never gains more, so a second axis arrives through
	// [Index.Layer] with the layer that reads it. A caller steering the
	// chart needs them — a zoom that moved one axis and left the other in the
	// same direction would slide the two series apart.
	Y2 scale.Scale
	X2 scale.Scale
	// Coord is the coordinate system the panel was drawn in, framed to Area.
	// It is what turns a device position back into the pair the scales speak
	// in — without it a pointer over a pie slice would be inverted as though
	// the wedge were a rectangle, and would report a value nothing was drawn
	// at. It is [coord.Cartesian] for a chart that named no coord.
	Coord coord.Coord
}

type RowRef struct {
	// Panel is which panel the row was drawn in, and Layer which layer of it.
	Panel, Layer int
	// Series is the layer's legend label, empty for a layer that has none.
	Series string
	// Row is the source row, in the table that was handed in.
	Row int
	// At is where the row landed, in device space.
	At ir.Point
}