charting library Charting

Terminal chart painters and chart data primitives.

Classes

AreaChartProps
Props for filled area charts.
AxisOptions
Axis display options.
BarChartProps
Props for bar charts.
BaseChartProps
Shared props for full-frame charts.
Block
Block-drawing characters.
Braille
Braille base and bit layout.
BrailleCanvas
A 2x4 sub-cell braille canvas for plotting terminal-native 2D graphics.
CanvasCircle
An outlined circle in world coordinates.
CanvasLine
A line between two world-coordinate points.
CanvasPainter
Projects world coordinates onto a high-resolution braille canvas.
CanvasPoint
A point in a canvas's world-coordinate system.
CanvasPoints
A collection of independently projected world-coordinate points.
CanvasRange
A finite range used to project world coordinates onto a terminal canvas.
CanvasRectangle
An outlined rectangle positioned from its bottom-left corner.
CanvasShape
Something that can draw itself through a CanvasPainter.
ChartCanvas
A convenience canvas for rendering charts into UV buffers.
ChartLegendEntry
A single entry in a chart legend.
ChartMargins
Chart content margins in terminal cells.
ChartRamp
Discrete color ramp for mapping normalized 0..1 values to colors.
DataPoint
A labeled numeric data point.
DataSeries
A named series of Y values for multi-series charts.
GaugeChartProps
Props for semicircular gauges.
GaugeThreshold
A gauge threshold stop.
GridOptions
Grid line options.
HeatmapCell
A heatmap cell coordinate (optional convenience type).
HeatmapChartProps
Props for heatmaps.
LegendOptions
Legend options.
LineChars
Box-drawing and marker characters.
LineChartProps
Props for multi-series line charts.
MultiSeriesBuffer
Manages multiple named TimeSeriesBuffers with a shared window.
NiceScale
Result of computeNiceScale.
PieChartProps
Props for pie / donut charts.
PieSlice
A labeled slice for pie charts.
QuadrantCanvas
2×2 sub-pixel quadrant-block canvas for smooth solid lines.
ScatterChartProps
Props for scatter charts.
ScatterPoint
An (x, y) point for scatter charts.
SequenceActivation
Activation/deactivation bar marker.
SequenceDiagramOptions
Rendering options.
SequenceDiagramTheme
Theming configuration for sequence diagram rendering.
SequenceFragment
A fragment block (alt/else/loop/end).
SequenceMessage
A message between participants.
SequenceNote
A note displayed over participants.
SequenceParticipant
Immutable participant definition.
SequenceParticipantGroup
A group/box of participants.
SequenceRect
A rect region wrapping messages with a background color.
SequenceStep
A single step in the diagram timeline.
SequenceStepActivation
SequenceStepFragment
SequenceStepMessage
SequenceStepNote
SparklineProps
Props for compact sparklines.
StackedBarChartProps
Props for stacked bar charts.
TimeSeriesBuffer
Sliding-window buffer of timestamped numeric samples.
TimeSeriesBufferOptions
Options for TimeSeriesBuffer / MultiSeriesBuffer.

Enums

ChartBorderStyle
Optional border style for chart containers (UI chrome).
ChartOrientation
Bar / stacked-bar orientation.
GridStyle
Grid line stroke style.
LegendPosition
Legend placement relative to the plot.
LineStyle
Line interpolation style for line charts.
SequenceArrowHead
Arrow head shape.
SequenceFragmentKind
Fragment/loop/alt block kind with default style.
SequenceMessageStyle
Message arrow style with default UV style and arrow character.
SequenceNotePosition
Placement of a sequence note.
SparklineStyle
Compact sparkline rendering style.

Constants

defaultColors → const List<String>
Default multi-series color palette (hex).
defaultMargins → const ChartMargins
Default chart margins.
pieChars → const List<String>
Alternate pie fill characters.

Functions

clamp01(double value) → double
Clamps value to the range 0..1, treating NaN as 0.
computeNiceScale(double dataMin, double dataMax, [int maxTicks = 10, int? plotHeight]) → NiceScale
Computes a "nice" axis scale with evenly spaced ticks.
createAreaChart(AreaChartProps props) → String
Creates an area chart and returns it rendered as a multi-line string.
createBarChart(BarChartProps props) → String
Creates a bar chart and returns it rendered as a multi-line string.
createGaugeChart(GaugeChartProps props) → String
Creates a gauge chart and returns it rendered as a multi-line string.
createHeatmapChart(HeatmapChartProps props) → String
Creates a heatmap chart and returns it rendered as a multi-line string.
createLineChart(LineChartProps props) → String
Creates a line chart and returns it rendered as a multi-line string.
createPieChart(PieChartProps props) → String
Creates a pie chart and returns it rendered as a multi-line string.
createScatterChart(ScatterChartProps props) → String
Creates a scatter chart and returns it rendered as a multi-line string.
createSparkline(SparklineProps props) → String
Alias for createSparklineChart matching the legacy opentui-charts name.
createSparklineChart(SparklineProps props) → String
Creates a sparkline chart and returns it rendered as a multi-line string.
createStackedBarChart(StackedBarChartProps props) → String
Creates a stacked bar chart and returns it rendered as a multi-line string.
dimFg(String hex, [double factor = 0.4]) → UvStyle
Dims a hex color by factor (0..1) and returns a foreground style.
drawAxes(Screen screen, Rectangle area, int plotX, int plotY, int plotW, int plotH, NiceScale scale, List<String>? labels, UvStyle bg, UvStyle axisColor, AxisOptions? xAxisOpts, AxisOptions? yAxisOpts, GridOptions? gridOpts) → void
Draws axes, ticks, grid, and optional X labels on screen.
drawAxisLabels(Screen screen, Rectangle area, {List<String>? xLabels, List<String>? yLabels, UvStyle style = const UvStyle()}) → void
Draws axis labels along the X and/or Y edges of area.
drawCanvasShapes(Screen screen, Rectangle area, Iterable<CanvasShape> shapes, {CanvasRange xBounds = const CanvasRange(0, 100), CanvasRange yBounds = const CanvasRange(0, 100), UvStyle fallbackStyle = const UvStyle()}) → void
Draws shapes into screen using a braille sub-cell canvas.
drawCrosshair(Screen screen, Rectangle area, int x, int y, {UvStyle style = const UvStyle(), String hChar = '─', String vChar = '│', String intersectionChar = '┼', bool drawOnEmpty = true}) → void
Draws a crosshair overlay at (x, y) within area.
drawGrid(Screen screen, Rectangle area, {int rows = 3, int cols = 3, UvStyle style = const UvStyle(), String hChar = '┄', String vChar = '┆', String intersectionChar = '┼', bool preserveBackground = false}) → void
Draws a grid of horizontal and vertical guide lines within area.
drawGroupedHistogram(Screen screen, Rectangle area, List<List<double>> seriesList, {List<UvStyle> styles = const [UvStyle()], UvStyle axisStyle = const UvStyle(), UvStyle gridStyle = const UvStyle(), UvStyle labelStyle = const UvStyle(), bool showAxis = true, bool showGrid = false, int gridRows = 3, int gridCols = 0, List<String>? xLabels, List<String>? yLabels, String barChar = BlockShades.full, int barGap = 1, int groupGap = 1, int? barWidth, bool drawAxisLine = true}) → void
Draws a grouped (side-by-side) multi-series vertical bar chart.
drawHeatmap(Screen screen, Rectangle area, List<List<double>> grid, {ChartRamp? ramp, bool useBackground = true, String glyph = ' ', bool showGrid = false, int gridRows = 3, int gridCols = 3, UvStyle gridStyle = const UvStyle(), List<String>? xLabels, List<String>? yLabels, UvStyle labelStyle = const UvStyle()}) → void
Draws a heatmap of the 2-D grid values into area on screen.
drawHistogram(Screen screen, Rectangle area, List<double> values, {UvStyle barStyle = const UvStyle(), UvStyle axisStyle = const UvStyle(), UvStyle gridStyle = const UvStyle(), UvStyle labelStyle = const UvStyle(), bool showAxis = true, bool showGrid = false, int gridRows = 3, int gridCols = 0, List<String>? xLabels, List<String>? yLabels, String barChar = BlockShades.full, int barGap = 1, int? barWidth, bool drawAxisLine = true}) → void
Draws a vertical bar histogram of values into area on screen.
drawHLine(Screen screen, Rectangle area, int x1, int x2, int y, UvStyle fg, UvStyle bg, [String char = LineChars.horizontal]) → void
Draws a horizontal line on screen.
drawHorizontalGroupedHistogram(Screen screen, Rectangle area, List<List<double>> seriesList, {List<UvStyle> styles = const [UvStyle()], UvStyle axisStyle = const UvStyle(), UvStyle gridStyle = const UvStyle(), UvStyle labelStyle = const UvStyle(), bool showAxis = true, bool showGrid = false, int gridRows = 0, int gridCols = 3, List<String>? yLabels, String barChar = BlockShades.full, int barGap = 1, int groupGap = 1, int? barWidth, bool drawAxisLine = true}) → void
Draws a grouped multi-series horizontal bar chart.
drawHorizontalStackedHistogram(Screen screen, Rectangle area, List<List<double>> seriesList, {List<UvStyle> styles = const [UvStyle()], UvStyle axisStyle = const UvStyle(), UvStyle gridStyle = const UvStyle(), UvStyle labelStyle = const UvStyle(), bool showAxis = true, bool showGrid = false, int gridRows = 0, int gridCols = 3, List<String>? yLabels, String barChar = BlockShades.full, int barGap = 1, int groupGap = 1, int? barWidth, bool drawAxisLine = true}) → void
Draws a stacked multi-series horizontal bar chart.
drawLegend(Screen screen, Rectangle area, List<ChartLegendEntry> entries, {int columns = 1, int rowGap = 0}) → void
Draws a legend for the given entries within area.
drawLine(Screen screen, Rectangle area, int x0, int y0, int x1, int y1, UvStyle fg, UvStyle bg, [String char = '']) → void
Bresenham line with optional fixed char (else directional box-draw glyphs).
drawLineChart(Screen screen, Rectangle area, List<double> values, {UvStyle lineStyle = const UvStyle(), UvStyle gridStyle = const UvStyle(), UvStyle labelStyle = const UvStyle(), bool showGrid = false, int gridRows = 3, int gridCols = 3, bool showMarkers = false, String markerChar = Circles.filled, String lineChar = DotChars.bullet, List<String>? xLabels, List<String>? yLabels, double? minValue, double? maxValue}) → void
Draws a line chart of values into area on screen.
drawMultiSeriesLineChart(Screen screen, Rectangle area, List<List<double>> seriesList, {List<UvStyle> styles = const [UvStyle()], UvStyle gridStyle = const UvStyle(), UvStyle labelStyle = const UvStyle(), bool showGrid = false, int gridRows = 3, int gridCols = 3, bool showMarkers = false, String markerChar = Circles.filled, List<String>? xLabels, List<String>? yLabels, double? minValue, double? maxValue}) → void
Draws a multi-series line chart into area on screen.
drawPieChart(Screen screen, Rectangle area, List<double> values, {List<UvStyle>? styles, bool useBackground = true, bool donut = false, double innerRadiusRatio = 0.45, double cellAspect = 2.0, String glyph = ' ', int subSamples = 4}) → void
Draws a pie (or donut) chart of values into area on screen.
drawRibbonChart(Screen screen, Rectangle area, List<List<double>> series, {List<UvStyle>? styles, bool normalizeTotals = true, String fillChar = BlockShades.full, bool showGrid = false, int gridRows = 3, int gridCols = 0, UvStyle gridStyle = const UvStyle()}) → void
Draws a stacked ribbon chart of multiple series into area on screen.
drawSequenceDiagram(Canvas canvas, Rectangle area, SequenceDiagram diagram, {SequenceDiagramTheme theme = SequenceDiagramTheme.defaultTheme, SequenceDiagramOptions? options}) → void
Renders a parsed sequence diagram onto a UV Canvas.
drawSparkline(Screen screen, Rectangle area, List<double> values, {UvStyle style = const UvStyle(), bool showGrid = false, UvStyle gridStyle = const UvStyle(), double baseline = 0.0, double? minValue, double? maxValue, UvStyle? gradientLow, UvStyle? gradientHigh}) → void
Draws a compact sparkline of values into area on screen.
drawStackedHistogram(Screen screen, Rectangle area, List<List<double>> seriesList, {List<UvStyle> styles = const [UvStyle()], UvStyle axisStyle = const UvStyle(), UvStyle gridStyle = const UvStyle(), UvStyle labelStyle = const UvStyle(), bool showAxis = true, bool showGrid = false, int gridRows = 3, int gridCols = 0, List<String>? xLabels, List<String>? yLabels, String barChar = BlockShades.full, int barGap = 1, int groupGap = 1, int? barWidth, bool drawAxisLine = true}) → void
Draws a stacked multi-series vertical bar chart.
drawVLine(Screen screen, Rectangle area, int x, int y1, int y2, UvStyle fg, UvStyle bg, [String char = LineChars.vertical]) → void
Draws a vertical line on screen.
fg(String hex) → UvStyle
Foreground UvStyle for a hex color.
fillAreaUnderPolyline(Screen screen, Rectangle area, List<(int, int)> points, int baseY, int plotX, int plotY, int plotW, int plotH, UvStyle fillStyle, UvStyle bg, {String fillChar = Block.shadeMedium, List<int>? baselineYs}) → void
Continuous vertical fill under a polyline using shade glyphs.
fillRect(Screen screen, Rectangle area, int x, int y, int w, int h, UvStyle style) → void
Fills a rectangular region on screen with style as the background.
formatNumber(double n) → String
Formats a number for axis labels.
isSequenceDiagram(String content) → bool
Returns true if the content starts with sequenceDiagram.
layoutSequenceDiagram(SequenceDiagram diagram, {SequenceDiagramOptions? options}) → LayoutResult
Renders a parsed diagram to text lines.
lerpFg(String a, String b, double t) → UvStyle
Linearly interpolates between two hex colors; returns a foreground style.
mergeStyle(UvStyle fg, UvStyle bg) → UvStyle
Merges foreground and background UvStyles into a combined style.
normalize(double value, double min, double max) → double
Normalizes value into the 0..1 range between min and max.
parseHexColor(String hex, {UvColor fallback = const UvColor.rgb(170, 170, 170)}) → UvColor
Parses a hex color (#RRGGBB or RRGGBB) into a UvColor.
parseMermaidColor(String value) → UvColor?
Parses a Mermaid color token (CSS name, hex, rgb, rgba) into UvColor.
parseSequenceDiagram(String content) → SequenceDiagram?
Parses Mermaid sequence diagram content into a SequenceDiagram record. Returns null if content does not start with sequenceDiagram.
putText(Screen screen, Rectangle area, int x, int y, String text, UvStyle style) → void
renderAreaChart(Screen screen, Rectangle area, AreaChartProps props) → void
Renders an area chart onto screen within area.
renderBarChart(Screen screen, Rectangle area, BarChartProps props) → void
Renders a bar chart onto screen within area.
renderChart(int width, int height, ChartPainter painter) → String
Renders a chart using painter at the given width and height, returning the result as a single String with embedded newlines.
renderChartLines(int width, int height, ChartPainter painter) → List<String>
Renders a chart into a list of lines.
renderGaugeChart(Screen screen, Rectangle area, GaugeChartProps props) → void
Renders a gauge chart onto screen within area.
renderHeatmapChart(Screen screen, Rectangle area, HeatmapChartProps props) → void
Renders a heatmap chart onto screen within area.
renderLineChart(Screen screen, Rectangle area, LineChartProps props) → void
Renders a line chart onto screen within area.
renderPieChart(Screen screen, Rectangle area, PieChartProps props) → void
Renders a pie chart onto screen within area.
renderScatterChart(Screen screen, Rectangle area, ScatterChartProps props) → void
Renders a scatter chart onto screen within area.
renderSequenceDiagram(String content, {SequenceDiagramOptions? options, SequenceDiagramTheme? theme, int? maxWidth}) → String
Convenience: renders a Mermaid sequence diagram string to text.
renderSparklineChart(Screen screen, Rectangle area, SparklineProps props) → void
Renders a sparkline chart onto screen within area.
renderStackedBarChart(Screen screen, Rectangle area, StackedBarChartProps props) → void
Renders a stacked bar chart onto screen within area.
resolveMargins(ChartMargins? partial) → ChartMargins
Merges partial margins with defaultMargins.
sampleSeries(List<double> values, int width) → List<double>
Down-samples or up-samples values to fit the given width.
uvColorFromHex(String hex, {UvColor fallback = const UvBasic16(7)}) → UvColor
Parses a hex color string (e.g. '#ff0000') into a UvColor.
uvStyleFromHex(String hex, {String? backgroundHex, int attrs = 0}) → UvStyle
Creates a UvStyle from hex color strings for foreground and optional background.

Typedefs

ChartPainter = void Function(Screen screen, Rectangle area)
Signature for chart painters.
LayoutResult = ({int height, List<String> lines, int width})
Layout result with text lines and dimensions.
SequenceDiagram = ({Map<String, UvStyle> actorStyles, List<SequenceParticipantGroup> groups, List<SequenceMessage> messages, List<SequenceParticipant> participants, List<SequenceRect> rects, List<SequenceStep> steps})
Parsed sequence diagram data.