selection

Documentation

Overview

Package selection defines the canonical structured selection event emitted by every Prism rendering context (Go-native, WASM/browser, Twirp /prism/scene). The same Event shape travels the wire in every environment so a single consumer handler works against any binding.

Mark-type uniformity: every selection — point, interval, lasso — and every mark type (bar, line, point, rule + text combos, …) emits the same Event struct. The selection kind, populated fields, and extent pointers tell consumers what kind of gesture produced the event; the structure itself is invariant.

Data-space coordinates are the canonical form. Pixel-space extent is optional and exists for UI overlays (brushes, tooltips) — for any downstream protocol the data-space extent is what matters because it survives re-renders at different sizes.

Stable instance keys: InstanceKey is derived from the (layer_id, row_id) pair, not from render-time ordering. Re-rendering the same spec with the same data produces identical instance keys.

Index

• func InstanceKey(layerID string, rowID int64) string
• type AxisExtent
• type BuildInput
• type DataExtent
• type DataRowRef
• type Event
  • func Build(in BuildInput, doc *scene.SceneDoc, sp *spec.Spec) (Event, error)
• type Kind
• type PixelExtent
• type PixelRange
• type PointHit
• type SelectedMark

Functions

func InstanceKey

func InstanceKey(layerID string, rowID int64) string

InstanceKey returns the canonical instance-key string for a (layer, row) pair. Exposed for callers building events manually.

Types

type AxisExtent

type AxisExtent struct {
	Min        *float64 `json:"min,omitempty"`
	Max        *float64 `json:"max,omitempty"`
	Categories []string `json:"categories,omitempty"`
}

AxisExtent is one axis's worth of selection bounds. Numeric ranges use Min/Max; categorical brushes populate Categories.

type BuildInput

type BuildInput struct {
	SceneID     string
	SelectionID string
	Kind        Kind
	Timestamp   int64 // 0 → now (ms since epoch)

	// Point gestures populate Points; interval / lasso gestures
	// populate Range / Categories + optional Pixel*.
	Points []PointHit

	// Range is the value-space brush extent for interval gestures.
	Range *DataExtent

	// PixelExtent is optional UI-overlay info.
	PixelExtent *PixelExtent
}

BuildInput is the raw selection state from a gesture (DOM hit-test, brush release, server selection apply). Build resolves it against a SceneDoc to produce a structured Event.

type DataExtent

type DataExtent struct {
	X *AxisExtent `json:"x,omitempty"`
	Y *AxisExtent `json:"y,omitempty"`
}

DataExtent carries the value-space bounds of an interval / lasso selection. For non-numeric (categorical) brushes, X/Y carry the stringified domain values via the optional Categories list.

type DataRowRef

type DataRowRef struct {
	DatasetName string `json:"dataset_name"`
	RowIndex    int    `json:"row_index"`
	RowID       string `json:"row_id,omitempty"`
}

DataRowRef points back into a named dataset. DatasetName is the scene-layer Source (the spec's data.source / dataset name). RowIndex is the table position; RowID is the dataset's id-column value when present.

type Event

type Event struct {
	SceneID     string         `json:"scene_id"`
	SelectionID string         `json:"selection_id"`
	Kind        Kind           `json:"kind"`
	Timestamp   int64          `json:"timestamp"`
	Marks       []SelectedMark `json:"marks"`
	DataRows    []DataRowRef   `json:"data_rows"`
	DataExtent  *DataExtent    `json:"data_extent,omitempty"`
	PixelExtent *PixelExtent   `json:"pixel_extent,omitempty"`
	SpecPath    string         `json:"spec_path"`
}

Event is the structured selection emission. It is the contract between Prism and downstream consumers (UI handlers, Twirp clients, MCP agents). JSON shape uses snake_case keys per Prism's wire conventions; field ordering in the struct mirrors the upgrade spec.

func Build

func Build(in BuildInput, doc *scene.SceneDoc, sp *spec.Spec) (Event, error)

Build resolves the raw input against the SceneDoc + Spec to produce the canonical Event. doc is the scene the gesture happened on; sp is the spec the scene was compiled from (used to map selection IDs to their JSON Pointer in the spec). doc must be non-nil; sp may be nil — when nil, SpecPath is computed structurally as "/selection/<id>".

type Kind

type Kind string

Kind discriminates between the three selection gesture families.

const (
	KindPoint    Kind = "point"
	KindInterval Kind = "interval"
	KindLasso    Kind = "lasso"
)

type PixelExtent

type PixelExtent struct {
	X *PixelRange `json:"x,omitempty"`
	Y *PixelRange `json:"y,omitempty"`
}

PixelExtent carries pixel-space bounds of an interval / lasso brush. Optional — populated when the renderer has pixel info to share; consumers should not assume presence.

type PixelRange

type PixelRange struct {
	Min float64 `json:"min"`
	Max float64 `json:"max"`
}

PixelRange is one axis's pixel bounds.

type PointHit

type PointHit struct {
	LayerID string
	RowID   int64
}

PointHit is the DOM-side hit-test result for one mark instance.

type SelectedMark

type SelectedMark struct {
	MarkIndex   int    `json:"mark_index"`
	InstanceKey string `json:"instance_key"`
}

SelectedMark identifies one selected mark instance. MarkIndex is the layer index in the spec (Prism has one mark per layer; for an unlayered single-mark spec, MarkIndex is 0). InstanceKey is stable across re-renders.