Documentation
¶
Index ¶
- Variables
- type BrailleRenderer
- type Chart
- type Event
- type LinesRenderer
- type Model
- func (m *Model) AddEvent(ev Event)
- func (m *Model) AddEventAt(offset int, ev Event)
- func (m *Model) AxisStyle() lipgloss.Style
- func (m *Model) ClearEvents()
- func (m *Model) EventsBox() string
- func (m *Model) Fill() bool
- func (m *Model) Grid() bool
- func (m *Model) Height() int
- func (m *Model) Inverted() bool
- func (m *Model) Last(name string) (float64, bool)
- func (m *Model) Legend() string
- func (m *Model) LegendBox() string
- func (m *Model) Len() int
- func (m *Model) LenSeries(name string) int
- func (m *Model) LineStyle() lipgloss.Style
- func (m *Model) LineWidth() int
- func (m *Model) Max() float64
- func (m *Model) Min() float64
- func (m *Model) Mode() RenderMode
- func (m *Model) NegativeStyle() lipgloss.Style
- func (m *Model) Push(v float64)
- func (m *Model) PushSeries(name string, v float64)
- func (m *Model) Renderer() Renderer
- func (m *Model) SeriesData(name string) []float64
- func (m *Model) SeriesInverted(name string) bool
- func (m *Model) SeriesNames() []string
- func (m *Model) SeriesNegativeStyle(name string) lipgloss.Style
- func (m *Model) SeriesStyle(name string) lipgloss.Style
- func (m *Model) SetAxisStyle(s lipgloss.Style)
- func (m *Model) SetFill(on bool)
- func (m *Model) SetGrid(on bool)
- func (m *Model) SetInverted(inverted bool)
- func (m *Model) SetLabelFormatter(fn func(float64) string)
- func (m *Model) SetLabelWidth(w int)
- func (m *Model) SetLineStyle(s lipgloss.Style)
- func (m *Model) SetLineWidth(w int)
- func (m *Model) SetMode(mode RenderMode)
- func (m *Model) SetNegativeStyle(s lipgloss.Style)
- func (m *Model) SetRange(min, max float64)
- func (m *Model) SetRenderer(r Renderer)
- func (m *Model) SetSeriesInverted(name string, inverted bool)
- func (m *Model) SetSeriesNegativeStyle(name string, s lipgloss.Style)
- func (m *Model) SetSeriesStyle(name string, s lipgloss.Style)
- func (m *Model) SetSmooth(on bool)
- func (m *Model) SetSolidFill(on bool)
- func (m *Model) SetSymmetric(on bool)
- func (m *Model) SetTicks(ticks ...float64)
- func (m *Model) SetTintColor(c color.Color)
- func (m *Model) SetTintedFill(on bool)
- func (m *Model) SetXAxis(label func(age int) string)
- func (m *Model) SetXAxisAt(label func(age int) string)
- func (m *Model) SetZeroBaseline(on bool)
- func (m *Model) Smooth() bool
- func (m *Model) SolidFill() bool
- func (m *Model) String() string
- func (m *Model) Symmetric() bool
- func (m *Model) TintColor() color.Color
- func (m *Model) TintedFill() bool
- func (m *Model) ToggleRenderMode()
- func (m *Model) View() string
- func (m *Model) VisibleEvents() []VisibleEvent
- func (m *Model) Width() int
- func (m *Model) ZeroBaseline() bool
- type Option
- func WithAxisStyle(s lipgloss.Style) Option
- func WithEvent(offset int, ev Event) Option
- func WithFill(on bool) Option
- func WithGrid(on bool) Option
- func WithInverted(inverted bool) Option
- func WithLabelFormatter(fn func(float64) string) Option
- func WithLabelWidth(w int) Option
- func WithLineStyle(s lipgloss.Style) Option
- func WithLineWidth(w int) Option
- func WithMode(mode RenderMode) Option
- func WithNegativeStyle(s lipgloss.Style) Option
- func WithRange(min, max float64) Option
- func WithRenderer(r Renderer) Option
- func WithSeriesInverted(name string, inverted bool) Option
- func WithSeriesNegativeStyle(name string, s lipgloss.Style) Option
- func WithSeriesStyle(name string, s lipgloss.Style) Option
- func WithSmooth(on bool) Option
- func WithSolidFill(on bool) Option
- func WithSymmetric(on bool) Option
- func WithTicks(ticks ...float64) Option
- func WithTintColor(c color.Color) Option
- func WithTintedFill(on bool) Option
- func WithXAxis(label func(age int) string) Option
- func WithXAxisAt(label func(age int) string) Option
- func WithZeroBaseline(on bool) Option
- type RenderContext
- type RenderMode
- type Renderer
- type VisibleEvent
Constants ¶
This section is empty.
Variables ¶
var DefaultEventColor color.Color = lipgloss.Color("#7dcfff")
DefaultEventColor is the default foreground color for timeline event pins and guidelines (#7dcfff).
var DefaultTintColor color.Color = lipgloss.Color("#1f2335")
DefaultTintColor is the default background tint used when TintedFill is active and no custom tint color or style background is specified. Defaults to Tokyo Night slate (#1f2335).
Functions ¶
This section is empty.
Types ¶
type BrailleRenderer ¶ added in v0.3.0
type BrailleRenderer struct{}
BrailleRenderer renders 2x4 dot Braille patterns.
func (BrailleRenderer) Render ¶ added in v0.3.0
func (BrailleRenderer) Render(c Chart, ctx RenderContext) string
Render implements Renderer for BrailleRenderer.
type Chart ¶ added in v0.4.0
type Chart interface {
Width() int
Height() int
Min() float64
Max() float64
Fill() bool
TintedFill() bool
SolidFill() bool
TintColor() color.Color
Grid() bool
Smooth() bool
LineWidth() int
AxisStyle() lipgloss.Style
LineStyle() lipgloss.Style
SeriesStyle(name string) lipgloss.Style
SeriesNames() []string
// SeriesData returns raw values, including NaN and Inf for missing points.
SeriesData(name string) []float64
VisibleEvents() []VisibleEvent
ZeroBaseline() bool
Symmetric() bool
NegativeStyle() lipgloss.Style
SeriesNegativeStyle(name string) lipgloss.Style
SeriesInverted(name string) bool
}
Chart provides the read-only contract for inspecting chart dimensions, data, and styles.
type Event ¶ added in v0.4.1
type Event struct {
ID string // Optional identifier for programmatic lookup or removal
Label string // Human-readable description (e.g. "Deploy v1.4.2")
Glyph string // Marker glyph (e.g. "▼", "🚀", "▲", "◆", "!", "⚠️"). Defaults to "▼".
Style lipgloss.Style // Style for the marker glyph and vertical guideline
NoLine bool // If true, omits the vertical guideline across the chart
}
Event represents a discrete timeline annotation or event marker.
type LinesRenderer ¶ added in v0.3.0
type LinesRenderer struct{}
LinesRenderer renders smooth box-drawing lines with optional area fill.
func (LinesRenderer) Render ¶ added in v0.3.0
func (LinesRenderer) Render(c Chart, ctx RenderContext) string
Render implements Renderer for LinesRenderer.
type Model ¶
type Model struct {
// contains filtered or unexported fields
}
Model is a streaming terminal line chart.
func (*Model) AddEvent ¶ added in v0.4.1
AddEvent records an event at the current newest point on the timeline. As new points are pushed, the event moves left across the window.
func (*Model) AddEventAt ¶ added in v0.4.1
AddEventAt records an event at a historical offset (0 = newest point, 10 = 10 points ago).
func (*Model) ClearEvents ¶ added in v0.4.1
func (m *Model) ClearEvents()
ClearEvents removes all timeline events from the chart.
func (*Model) EventsBox ¶ added in v0.4.1
EventsBox returns a boxed card listing all currently visible timeline events. Returns an empty string if there are no visible events.
func (*Model) Height ¶ added in v0.3.0
Height returns the chart plot height in terminal cells. With an X axis, View returns Height()+2 lines.
func (*Model) Inverted ¶ added in v0.5.0
Inverted returns whether value inversion is enabled for the default series.
func (*Model) Last ¶
Last returns the most recent finite value of a named series. Trailing gaps (NaN, +Inf, -Inf) are skipped.
func (*Model) Legend ¶
Legend returns a formatted legend for named series, or empty string if none exist.
func (*Model) LegendBox ¶
LegendBox returns a boxed legend with borders, swatches, series names, and recent values.
func (*Model) LenSeries ¶
LenSeries returns the number of points in the named series within the window.
func (*Model) Mode ¶
func (m *Model) Mode() RenderMode
Mode returns the current rendering mode derived from the active renderer.
func (*Model) NegativeStyle ¶ added in v0.5.0
NegativeStyle returns the negative line style for the default series, or default line style.
func (*Model) Push ¶
Push adds a data point to the default series. Maintains a sliding window of width w. NaN, +Inf and -Inf are kept as given and drawn as gaps.
func (*Model) PushSeries ¶
PushSeries adds a data point to a named series. NaN, +Inf and -Inf are kept as given and drawn as gaps.
func (*Model) SeriesData ¶ added in v0.3.0
SeriesData returns a copy of data points for a series. Missing points are returned raw (NaN, +Inf, -Inf), so custom renderers see them.
func (*Model) SeriesInverted ¶ added in v0.5.0
SeriesInverted returns whether value inversion is enabled for a named series.
func (*Model) SeriesNames ¶ added in v0.3.0
SeriesNames returns registered series names in order.
func (*Model) SeriesNegativeStyle ¶ added in v0.5.0
SeriesNegativeStyle returns the negative style for a named series.
func (*Model) SeriesStyle ¶ added in v0.4.0
SeriesStyle returns the style for a named series, or default line style.
func (*Model) SetAxisStyle ¶
SetAxisStyle dynamically updates the axis style.
func (*Model) SetInverted ¶ added in v0.5.0
SetInverted enables or disables value inversion for the default series.
func (*Model) SetLabelFormatter ¶ added in v0.2.0
SetLabelFormatter dynamically updates the Y-axis label formatter.
func (*Model) SetLabelWidth ¶ added in v0.2.0
SetLabelWidth dynamically updates the Y-axis label column width.
func (*Model) SetLineStyle ¶
SetLineStyle dynamically updates the line style.
func (*Model) SetLineWidth ¶
SetLineWidth sets the line width: 1 for thin, 2 for bold.
func (*Model) SetMode ¶
func (m *Model) SetMode(mode RenderMode)
SetMode sets the rendering mode (ModeLines or ModeBraille). ModeCustom cannot be set: install the renderer with SetRenderer instead.
func (*Model) SetNegativeStyle ¶ added in v0.5.0
SetNegativeStyle dynamically sets the negative line style for the default series.
func (*Model) SetRenderer ¶ added in v0.3.0
SetRenderer dynamically updates the chart renderer and synchronizes Mode(). A nil renderer falls back to LinesRenderer.
func (*Model) SetSeriesInverted ¶ added in v0.5.0
SetSeriesInverted enables or disables value inversion for a named series.
func (*Model) SetSeriesNegativeStyle ¶ added in v0.5.0
SetSeriesNegativeStyle dynamically sets the negative style for a named series.
func (*Model) SetSeriesStyle ¶
SetSeriesStyle dynamically sets the style for a named series.
func (*Model) SetSolidFill ¶ added in v0.4.0
SetSolidFill enables or disables solid background fill dynamically.
func (*Model) SetSymmetric ¶ added in v0.5.0
SetSymmetric enables or disables symmetric Y range normalization around zero ([-max, +max]).
func (*Model) SetTicks ¶
SetTicks dynamically sets explicit tick values for the Y axis. Ticks are copied, sorted ascending, and deduplicated.
func (*Model) SetTintColor ¶ added in v0.4.0
SetTintColor dynamically updates the chart background tint color.
func (*Model) SetTintedFill ¶ added in v0.4.0
SetTintedFill enables or disables tinted background fill dynamically.
func (*Model) SetXAxis ¶ added in v0.7.0
SetXAxis sets the X axis label function; nil turns the axis off. See WithXAxis.
func (*Model) SetXAxisAt ¶ added in v0.7.0
SetXAxisAt sets the X axis label function asked for every column; nil turns the axis off. See WithXAxisAt.
func (*Model) SetZeroBaseline ¶ added in v0.5.0
SetZeroBaseline enables or disables explicit zero baseline rendering.
func (*Model) SolidFill ¶ added in v0.4.0
SolidFill returns whether solid background fill is enabled.
func (*Model) String ¶ added in v0.3.0
String implements fmt.Stringer, returning the rendered chart View().
func (*Model) Symmetric ¶ added in v0.5.0
Symmetric returns whether symmetric Y range normalization is enabled.
func (*Model) TintColor ¶ added in v0.4.0
TintColor returns the custom background tint color, or nil if using default.
func (*Model) TintedFill ¶ added in v0.4.0
TintedFill returns whether tinted area fill is enabled.
func (*Model) ToggleRenderMode ¶
func (m *Model) ToggleRenderMode()
ToggleRenderMode switches between ModeLines and ModeBraille.
func (*Model) View ¶
View renders the chart: Y-axis labels + axis border + plot area, then the X axis and label rows when WithXAxis is set.
func (*Model) VisibleEvents ¶ added in v0.4.1
func (m *Model) VisibleEvents() []VisibleEvent
VisibleEvents returns all timeline events currently visible within the chart window.
func (*Model) ZeroBaseline ¶ added in v0.5.0
ZeroBaseline returns whether explicit zero baseline rendering is enabled.
type Option ¶
type Option func(*Model)
Option configures a Model.
func WithAxisStyle ¶
WithAxisStyle sets the axes and labels style.
func WithEvent ¶ added in v0.4.1
WithEvent registers an initial timeline event marker at a historical offset (0 = newest point).
func WithInverted ¶ added in v0.5.0
WithInverted configures the default series to invert its values when plotted (v -> -v).
func WithLabelFormatter ¶ added in v0.2.0
WithLabelFormatter sets a custom formatter for Y-axis tick values.
func WithLabelWidth ¶ added in v0.2.0
WithLabelWidth sets an explicit width for Y-axis labels.
func WithLineStyle ¶
WithLineStyle sets the default line style.
func WithLineWidth ¶
WithLineWidth sets line width: 1 thin, 2 bold.
func WithMode ¶
func WithMode(mode RenderMode) Option
WithMode sets rendering mode (ModeLines or ModeBraille).
func WithNegativeStyle ¶ added in v0.5.0
WithNegativeStyle sets the style for negative values (< 0) of the default series.
func WithRenderer ¶ added in v0.3.0
WithRenderer sets a custom chart renderer.
func WithSeriesInverted ¶ added in v0.5.0
WithSeriesInverted configures a named series to invert its values when plotted (v -> -v).
func WithSeriesNegativeStyle ¶ added in v0.5.0
WithSeriesNegativeStyle sets the style for negative values (< 0) of a named series.
func WithSeriesStyle ¶
WithSeriesStyle sets the style for a named series.
func WithSmooth ¶
WithSmooth enables or disables line smoothing (rounded corners or spline).
func WithSolidFill ¶ added in v0.4.0
WithSolidFill enables or disables solid background fill (spaces with background color) instead of stippled glyphs (░).
func WithSymmetric ¶ added in v0.5.0
WithSymmetric normalizes the Y range to be symmetric around zero ([-max, +max]), ensuring the zero baseline remains anchored directly in the center of the chart.
func WithTicks ¶
WithTicks sets explicit Y-axis tick values (e.g. 0, 25, 50, 75, 100 or 0, 50, 100).
func WithTintColor ¶ added in v0.4.0
WithTintColor sets a custom background tint color for tinted fill mode. If nil, DefaultTintColor (#1f2335) is used.
func WithTintedFill ¶ added in v0.4.0
WithTintedFill enables or disables tinted background fill under the line, seamlessly bridging the gap between box-drawing characters and area fill.
func WithXAxis ¶ added in v0.7.0
WithXAxis draws an axis row and a label row under the plot. label returns the text for the point age steps before the newest (age 0 is the newest point). With the axis on, View returns Height()+2 lines.
func WithXAxisAt ¶ added in v0.7.0
WithXAxisAt draws the X axis like WithXAxis, with labels at the columns you choose. label is asked for every column (age 0 to width-1); a non-empty text proposes a label there. The right edge goes first, then the other columns from right to left; a label that runs past an edge or touches a placed one is dropped. Vertical grid lines follow the placed middle labels.
func WithZeroBaseline ¶ added in v0.5.0
WithZeroBaseline enables or disables explicit zero baseline rendering (├ on Y-axis and baseline ruling at Y=0).
type RenderContext ¶ added in v0.3.0
type RenderContext struct {
LabelWidth int
LabelStyle lipgloss.Style
RowLabel map[int]string
HGrid []bool
VGrid []bool
Names []string
Styles []lipgloss.Style
NegativeStyles []lipgloss.Style
HasNegStyles []bool
SeriesData [][]float64
GridStyle lipgloss.Style
ZeroRow int
}
RenderContext contains prepared axis, tick, label, and style metadata passed to a Renderer.
type RenderMode ¶
type RenderMode int
RenderMode defines how line curves are rendered on the chart.
const ( // ModeLines renders smooth continuous lines (box-drawing ╭, ╮, ╯, ╰, ─, │) with Grafana-style area fill ░. ModeLines RenderMode = iota // ModeBraille renders using a 2x4 dot braille matrix (Unicode Braille Patterns). ModeBraille // ModeCustom represents a custom user-supplied Renderer. ModeCustom )
type Renderer ¶ added in v0.3.0
type Renderer interface {
Render(c Chart, ctx RenderContext) string
}
Renderer defines how chart series data and axes are rendered into a string. Custom renderers only need the Chart contract: build one with New and Push in tests, no mocks required.
type VisibleEvent ¶ added in v0.4.1
type VisibleEvent struct {
Col int // Column index in current plot area (0 to Width()-1)
Age int // How many time steps ago this event occurred
Event Event // The event metadata
}
VisibleEvent pairs an Event with its current visible column in the chart window.