TermMosaic v1.0.0

v1.0.0 is the first release that makes a stability promise: the public API freezes here and Semantic Versioning applies in earnest — with one documented exception: widgets/widgettest is excluded from that promise, because it must evolve with the framework. Read the limitations before you rely on anything here.

Widgets widgets/viz

Sparkline

A series of numbers drawn as Braille or block elements, scaled to its own range.

A series of numbers drawn as Braille or block elements, scaled to its own range.

Package widgets/viz. API reference: pkg.go.dev/widgets/viz.

Sparkline is a series of values drawn in one row — or one column — with sub-cell resolution.

Rendered output

Sparkline rendered by cmd/capture through widgettest.Capture: colour at 3 widths (40, 80, 120 columns), and the exact plain-text cell grid at the widest of them.

MinSize() returns 5 × 3 cells. That is the whole widget including its own chrome, and it is the widget's assertion about itself — below it, Draw clips rather than blanks, and what to do about that is the application's decision.

40 columns × 3 rows

╭ frame time (ms) ─────────────────────╮
│⠁⠁⠑⠙⠙⠙⠙⠙⠙⠙⠁⠁⠁⠁⠁⠁⠁⠑⠙⠙⠙⠙⠉⠁⠁⠁⠁⠁⠁⠁⠁⠁⠁⠁⠁⠙⠛⠛│
╰──────────────────────────────────────╯

80 columns × 3 rows

╭ frame time (ms) ─────────────────────────────────────────────────────────────╮
│⠁⠁⠑⠙⠙⠙⠙⠙⠙⠙⠁⠁⠁⠁⠁⠁⠁⠑⠙⠙⠙⠙⠉⠁⠁⠁⠁⠁⠁⠁⠁⠁⠁⠁⠁⠙⠛⠛⠛⠛⠛⠙⠉⠁⠁⠁⠁⠁⠁⠁⠁⠁⠁⠑⠙⠙⠙⠙⠙⠉⠁⠁⠁⠁⠁⠁⠁⠁⠁⠁⠁⠁⠁⠁⠁⠁⠁⠁│
╰──────────────────────────────────────────────────────────────────────────────╯

120 columns × 3 rows

╭ frame time (ms) ─────────────────────────────────────────────────────────────────────────────────────────────────────╮
│⠁⠁⠑⠙⠙⠙⠙⠙⠙⠙⠁⠁⠁⠁⠁⠁⠁⠑⠙⠙⠙⠙⠉⠁⠁⠁⠁⠁⠁⠁⠁⠁⠁⠁⠁⠙⠛⠛⠛⠛⠛⠙⠉⠁⠁⠁⠁⠁⠁⠁⠁⠁⠁⠑⠙⠙⠙⠙⠙⠉⠁⠁⠁⠁⠁⠁⠁⠁⠁⠁⠁⠁⠁⠁⠁⠁⠁⠁⠁⠁⠁⠁⠁⠁⠁⠁⠁⠁⠁⠁⠁⠁⠁⠁⠁⠁⠁⠁⠁⠁⠁⠁⠁⠁⠁⠑⠙⠙⠉⠁⠁⠁⠁⠁⠁⠁⠁⠁│
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯

Plain text — the exact cell grid, trimmed per line. This is the honest form: Braille and block-element glyphs can take a different advance width in a web font than a terminal gives them, which breaks the alignment they depend on.

# Sparkline — A series of numbers drawn as Braille or block elements, scaled to its own range.
# package: widgets/viz
# constructor: viz.NewSparkline(r buffer.Rect) *viz.Sparkline
# 120 columns x 3 rows, rendered through widgettest.Capture

╭ frame time (ms) ─────────────────────────────────────────────────────────────────────────────────────────────────────╮
│⠁⠁⠑⠙⠙⠙⠙⠙⠙⠙⠁⠁⠁⠁⠁⠁⠁⠑⠙⠙⠙⠙⠉⠁⠁⠁⠁⠁⠁⠁⠁⠁⠁⠁⠁⠙⠛⠛⠛⠛⠛⠙⠉⠁⠁⠁⠁⠁⠁⠁⠁⠁⠁⠑⠙⠙⠙⠙⠙⠉⠁⠁⠁⠁⠁⠁⠁⠁⠁⠁⠁⠁⠁⠁⠁⠁⠁⠁⠁⠁⠁⠁⠁⠁⠁⠁⠁⠁⠁⠁⠁⠁⠁⠁⠁⠁⠁⠁⠁⠁⠁⠁⠁⠁⠁⠑⠙⠙⠉⠁⠁⠁⠁⠁⠁⠁⠁⠁│
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯

What you are looking at. This is the cell grid the renderer produced, in a web page. It is not a screenshot of a terminal, and it cannot show interaction, resize or animation — a capture is one settled frame after N frames of settling. Braille and Block Elements can take a different advance width in your browser's font than in a terminal, so if a gauge or a sparkline above looks wrong, the plain-text form below it is the exact output and the colour one is the decoration. The colour frames are at 40, 80, 120 columns; the plain-text frame is at 120. More on this.

About this capture. Braille encoding, two samples per cell, so the series holds twice the values the width can show. The threshold defaults to reverse video, which is an attribute rather than a colour.

Package context

Package viz provides the catalog’s measurement and display widgets: ProgressBar, Gauge, Meter, Sparkline and BarChart.

  • Its space is Bounds(), never buf.Size() (ADR 0007 §1 rule 1).
  • It repaints its whole Bounds() before drawing content (rule 3), by composing widgets/block.Block, whose Draw fills the rect in Background before anything else. No widget here draws a border, a corner or a title itself.
  • Its Draw is allocation-free (ADR 0008 §4). Everything derived from the size — which regions survived the budget, where the axis labels go, the glyph ramp for a sparkline — is computed in the size-change check, cached against the rect, and only read in Draw.

Constructing it

viz.NewSparkline(r buffer.Rect) *viz.Sparkline

NewSparkline takes a rect; Values is the series.

  • Values — []float64 — the series. Braille encodes two samples per cell, so the series holds twice the values the width can show.
  • Braille — bool — on by default. Off gives block elements, which is the degradation path for a terminal or font that cannot hold Braille.
  • Vertical — bool — draw the series as a column rather than a row.
  • Auto — bool — scale to the series’ own range. Off means you set Min/Max, which is what you want when several sparklines must be comparable.
  • LastStyle — buffer.Style — the most recent sample, which is what a reader looks for first.

More on accessibility

The threshold defaults to reverse video, which is an attribute rather than a colour, and the last sample is marked distinctly. Colour is never the only signal, and for a terminal with NO_COLOR set the distinction survives.

When not to use it

Do not use it to read exact values. Braille gives sub-cell resolution, not numeric precision. A sparkline answers “did it go up, and by roughly how much”; if the answer needs to be a number, print the number.

Do not use it when the series is shorter than about eight samples. Sub-cell encoding needs samples to spend. Three points render as three nearly identical columns and the shape is noise.

Do not use it with Auto on when two sparklines sit next to each other. Auto-scales to each series’ own range, so two sparklines of very different magnitudes look identical. Set Min/Max explicitly for anything meant to be compared.

Do not use it for a single current value. That is Gauge or Meter.

Do not use it expecting a legible result in a web font. Braille in a browser is exactly the case the plain-text capture on this site exists for.

Instead: Gauge for one value, BarChart for categories rather than time.