candycore/sugar-charts

PHP port of NimbleMarkets/ntcharts — terminal charts (canvas, sparkline, bar, line, heatmap, scatter, time-series, OHLC, streamline, waveline) for SugarCraft.

v0.2.0 2026-05-07 02:01 UTC

Requires

• php: ^8.1
• sugarcraft/candy-core: @dev
• sugarcraft/candy-sprinkles: @dev

Requires (Dev)

• phpunit/phpunit: ^10.5

MIT

• Joe Huss

• charts
• terminal
• graphs
• heatmap
• sparkline
• time-series
• scatter
• bar-chart
• line-chart
• tui
• candlestick
• ntcharts
• ohlc
• sugarcraft

README

SugarCharts

composer require sugarcraft/sugar-charts

PHP port of NimbleMarkets/ntcharts — terminal charts for SugarCraft. v0 ships the canvas foundation plus three self-contained chart types.

use SugarCraft\Charts\Sparkline\Sparkline;
use SugarCraft\Charts\BarChart\BarChart;
use SugarCraft\Charts\LineChart\LineChart;

echo Sparkline::new([1, 3, 2, 8, 5, 4, 7, 6], 8)->view() . PHP_EOL;
// ▁▃▂█▅▄▇▆

echo BarChart::new([['cpu', 0.7], ['mem', 0.4], ['disk', 0.9]], 20, 5)->view() . PHP_EOL;
// 0.9 ┤   ▏  █
// 0.7 ┤█  ▏  █
// 0.4 ┤█  █  █
//     └────────
//      cpu mem disk

echo LineChart::new([1, 4, 2, 8, 6, 3, 7], 30, 6)->view() . PHP_EOL;

Charts also expose short-form aliases on the most-used setters: data / size / min / max / point / xRange / yRange / colors / palette / bars / barWidth / showLabels / showAxis, etc. The upstream-mirroring with* long forms still work; pick the form that reads best at the call site.

Components

Component	Role	Notable knobs
Charts\Canvas\Canvas	Fixed-size cell grid; each cell holds a rune + optional Sprinkles Style.	setCell / setLines / setString / setRunes / fill / fillLine / shiftUp / shiftDown / shiftLeft / shiftRight / setCellStyle / getCellStyle
Charts\Canvas\BrailleGrid	Sub-cell scratch buffer (2 cols × 4 rows of dots per cell). Paint dots, then copy to a Canvas.	set / unset / toggle / isSet / rune / paint(Canvas, x0, y0, ?Style) / clear
Charts\Canvas\Graph	Drawing primitives over a Canvas.	drawHLine / drawVLine / drawXYAxis / drawXYAxisLabel / drawString / drawLine / drawLinePoints / fillRect / drawColumn / drawColumns / drawRows / drawCandlestick / drawBrailleRune / drawBraillePatterns / drawVerticalLineUp / drawVerticalLineDown / drawHorizontalLineLeft / drawHorizontalLineRight / getCirclePoints / getCirclePointsWithLimit / getFullCirclePoints / getFullCirclePointsWithLimit / getLinePointsWithLimit
Charts\Sparkline\Sparkline	Single-row series renderer using the 8 Unicode bar glyphs.	push / pushAll / clear / withMin / withMax / withStyle(?Style) / withNoAutoMaxValue(bool) / withWidth
Charts\BarChart\BarChart	Labeled vertical bars; auto-scales to a configurable min / max.	withBarWidth / withBarGap / withNoAutoBarWidth / push(Bar|array) / pushAll(iterable) / clear
Charts\LineChart\LineChart	Single-series ASCII plot drawn onto a Canvas with configurable axes.	withYRange / withXRange / withXYRange / autoAdjustRange / withXLabelFormatter / withYLabelFormatter / withAxes / withXLabels / withYLabels
Charts\LineChart\TimeSeries	LineChart variant accepting [\DateTimeImmutable, value] tuples.	push / withPoints / withTimeFormat / withXLabelCount / withTimeRange(?start, ?end) / getTimeRange()
Charts\LineChart\Streamline	Single-row streaming line — auto-windowed to width.	push / pushAll / clear / withSize / withMin / withMax / withYRange
Charts\LineChart\Wavelinechart	XY scatter / wave plot driven by (x, y) pairs.	push / pushAll / clear / withSize / withXRange / withYRange / withXYRange / withPoint
Charts\Heatmap\Heatmap	2D grid coloured by value with optional palette / legend.	withSize / withMin / withMax / withPalette / withLegend / withColors(cold, hot) / withColorProfile / withCellStyle(?Style) / withAutoValueRange(bool) / pushPoint(HeatPoint) / pushAll
Charts\OHLC\OHLC	Candlestick chart for (high, open, close, low) rows.	withSize / withCandleStyle / withWickStyle
Charts\Scatter\Scatter	XY scatter plot.	push / pushAll / withSize / withMin / withMax
Charts\Picture\Picture	Inline image renderer (Sixel today; Kitty / iTerm2 protocols pending).	withFromFile / withDimensions / view

Graph primitives at a glance

Graph is a static-method utility — every draw call takes a Canvas plus coordinates in canvas (cell) space (top-left origin). Pair with BrailleGrid for sub-cell precision:

use SugarCraft\Charts\Canvas\{Canvas, BrailleGrid, Graph};

$canvas = new Canvas(40, 8);
Graph::drawXYAxis($canvas, 1, 6, 38);
Graph::drawString($canvas, 4, 0, 'Demo');

// Sub-cell line via BrailleGrid.
$grid = new BrailleGrid(38, 6);
foreach (Graph::getLinePointsWithLimit(0, 0, 75, 23, limit: 200) as [$x, $y]) {
    $grid->set($x, $y);
}
$grid->paint($canvas, 1, 0);
echo $canvas->view();

Palette / colour profile

Heatmap::withPalette([Color, …]) interpolates between an arbitrary number of stops (≥ 2). withColors(Color $cold, Color $hot) is the two-stop shortcut. withColorProfile(ColorProfile) overrides the auto-detected output profile when piping to non-tty / Sixel-capable sinks. Heatmap::withCellStyle(Style) overlays additional attributes (bold / background / etc.) on top of every cell's foreground gradient.

Demos

Bar chart

Heatmap

Line chart

OHLC (candlestick)

Picture (Sixel)

Scatter

Sparkline

Time series

Status

Component	State
Canvas, BrailleGrid, Graph primitives	🟢 v1
Sparkline	🟢 v1
BarChart	🟢 v1 (multi-bar grouped datasets pending)
LineChart	🟢 v1 (zoom/pan + dataset styles pending)
TimeSeries	🟢 v1 (multi-dataset + update-handler variants pending)
Streamline, Wavelinechart	🟢 v1
Heatmap	🟢 v1 (default-color-scale getter/setter pending)
OHLC	🟡 candlestick rendering only — volume sub-pane + multi-series pending
Scatter	🟡 single-dataset only — per-point rune/style sets pending
Picture	🟡 Sixel renderer only — Kitty graphics protocol + iTerm2 inline + half-block fallback pending

Test

cd sugar-charts && composer install && vendor/bin/phpunit