SugarDashboard
Dashboard TUI library — column grid, constraint layout, ratio grid, data grid, tree, modal, status bar, tabs, plot/canvas, and a module/plugin system
Build dashboard-style terminal UIs with a column grid, constraint layout, ratio grid, data grid, tree views, modals, status bars, tabs, and plot/canvas rendering. Compose complex layouts from reusable components, and extend the whole system through the module/plugin layer. All motion is frame-driven — the library renders synchronously and the host supplies every frame, so a reduced-motion presentation is always reachable by holding the frames still.
Install
composer require sugarcraft/sugar-dashboard
Quickstart
use SugarCraft\Dashboard\Layout\Grid\{StackedGrid, Options, ItemOptions};
use SugarCraft\Dashboard\Components\Card\{Card, Text};
$grid = (new StackedGrid(new Options(fitScreen: true)))
->withItem(Card::titled(Text::new('CPU 42%'), 'Load'), new ItemOptions(column: 0))
->withItem(Card::titled(Text::new('3 alerts'), 'Alerts'), new ItemOptions(column: 1, expandVertical: true));
// Every with*() / setSize() returns a sized COPY — keep the result.
$grid = $grid->setSize(100, 24);
echo $grid->render(); // two bordered cards side by side; below 90 columns they stack
What's in the box
graph_symbols table, in braille / block / block2 / tty families, with invert, no-zero, max-value scaling, gradient coloring and the graph_bg underlay.Meter::withGradient($stops, positionWise: true) renders btop's one-row ■ bar — each cell colored at its own position on a 101-stop ramp, meter_bg tail, invert, memoized per shape.Gradient101::expand() (btop's integer ramp law), GradientStore named ramps (at('cpu', 73)), and value-driven BrailleCanvas::withGradient().ProcRowComposer renders a btop process-list row (pid … mem, 5×1 cpu mini-graph on graph_bg, cpu%) with DistanceFade shading; ProcGraphTracker manages per-pid graphs.btop-style graphs & meters
Ported from aristocratos/btop for candy-top; color and quantization laws are byte-faithful to btop. Run php examples/dual-sample-graph.php for every family.
use SugarCraft\Core\Util\Color;
use SugarCraft\Dashboard\Plot\Braille\DualSampleGraph;
use SugarCraft\Dashboard\Plot\Chart\Meter;
$stops = [Color::hex('#80d0a3'), Color::hex('#dcd179'), Color::hex('#d45454')];
echo DualSampleGraph::new(12, 3)
->withGradient($stops)
->withData(5, 12, 30, 55, 80, 95, 70, 45, 20, 10, 35, 60)
->render(), "\n";
echo Meter::new(0.62)->withWidth(20)->withGradient($stops, positionWise: true)->render(), "\n";
Showcase examples
View gif →
Source & demos
- Source on GitHub
- Full README
- Runnable examples
- Originally inspired by the Go Charm ecosystem; SugarCraft is developed as a native PHP project.
API
| Class | Method | Description |
|---|---|---|
| Layout\Grid\StackedGrid | __construct(Options = new Options()) | Column grid; columns stack vertically below the narrow breakpoint (90 cells) |
| Layout\Grid\StackedGrid | addItem(Item, ItemOptions = new ItemOptions()) | Add an item to a column |
| Layout\Grid\StackedGrid | setSize(width, height) / render() / withTheme(Theme) | Size, render to an ANSI string, theme |
| Layout\Grid\Options / ItemOptions | new Options(fitScreen: bool) / new ItemOptions(column: int, expandVertical: bool) | Grid and per-item options |
| Components\Card\Card | static titled(Item|string, string $title) | Bordered card with a title |
| Layout\Frame | static new(Item) / withTitle() / withBorder() / withPadding() | Framed panel |
| Plot\Gradient101 | static expand(list<Color> $stops) | btop's 101-entry ramp (index = percent), truncating integer law |
| Plot\Braille\BrailleCanvas | withGradient(stops, ?scale) / withValue(v) / withoutGradient() / gradient() / value() | Null-color dots take the ramp color at the current value |
| Plot\Braille\DualSampleGraph | static new(width, height, family, invert, noZero, maxValue, offset) | btop Draw::Graph; families FAMILY_BRAILLE / FAMILY_BLOCK / FAMILY_BLOCK2 / FAMILY_TTY |
| Plot\Braille\DualSampleGraph | push(...$v) / withData(...$v) / withGradient(stops) / withUnderlay(Color) / render(?profile) | Append or replace history, color, underlay, render |
| Plot\Braille\DualSampleGraph | static underlay(family, cells, Color) | Bare btop graph_bg strip (⣀ ▄ 🬭 ░) |
| Plot\Chart\Meter | withGradient(stops, positionWise) / withGlyph() / withInvert() / withMeterBg() | btop Draw::Meter position-colored bar; memoStats() / resetMemo() |
| Foundation\NetAutoScale | static new(sync) / offer(down, up) / downloadMax() / uploadMax() / maxFor(dir) / counters(dir) / forceRescale() / rescaleNow() / rescalePending() | btop net-graph ceiling hysteresis; the $sync / $rescaled result flags are public readonly |
| Foundation\GradientStore | static fromStops(array) / static ramp(start, ?mid, ?end) / withGradient(name, start, ?mid, ?end) / at(name, percent) / gradient(name) / has(name) / names() | Named 101-entry ramps (btop Theme::g) |
| Plot\DistanceFade | ramp() / distance() / fadeIndex() / fadeColor() / metricPosition() / metricColor() / flatMetricColor() / metricValues() | btop proc-list distance fade |
| Plot\ProcRow\ProcRowComposer | static new(width) / withColumns() / withPalette() / withProcColors() / withProcGradient() / withFamily() / row(ProcRow, row, selected, selectMax, ?graph, followed, ?profile) | One btop process-list row; ProcRow, ProcColumns, ProcRowPalette, ProcGraphTracker supply data, layout, colors and mini-graphs |
Demos.
VHS-recorded GIFs for the library's examples. Regenerated automatically on every push that touches the source.
Layout & Structure
StackedGrid
Multi-column stacked grid layout.
GridLayout
CSS Grid-style layout.
FlexLayout
Flexbox-style layout.
VStack
Vertical stack with alignment.
HStack
Horizontal stack with spacing.
ZStack
Layered stack.
Stack
Basic vertical stack.
Frame
Bordered frame with title.
Panel
Panel with header/footer.
Card
Card container component.
Divider
Horizontal or vertical divider.
BoxDrawing
Unicode box-drawing frame.
BorderText
Text with ASCII border.
Spacer
Empty space filler.
Split
Split layout.
Center
Centered content.
Cover
Cover layout.
Header
Page header.
Footer
Page footer.
Window
Window frame.
Drawer
Drawer panel.Charts
Chart
Bar/line chart with axes.
AreaChart
Area chart for time series.
Bar
Horizontal status bar.
Donut
Donut chart.
Gauge
Horizontal gauge.
GaugeChart
Circular gauge chart.
GaugeCircle
Circular gauge visualization.
Heatmap
Heat map visualization.
RadarChart
Radar/spider chart.
Bubble
Bubble chart.
Bullet
Bullet chart.
Sparkline
Inline sparkline chart.
SparklineBar
Bar-style sparkline.
SparklineArea
Area-style sparkline.
SparkArea
Spark area chart.
FunnelChart
Funnel chart.Form & Input
Input
Text input field.
Textarea
Multi-line text area.
Select
Dropdown select.
Checkbox
Checkbox group.
Radio
Radio button.
Slider
Slider control.
Toggle
Toggle switch.
Switch
Switch component.
Chip
Chip/tag component.
ChipGroup
Group of chips.
Label
Form label.
ComboBox
Combo box.
DatePicker
Date picker.Navigation
Tabs
Tabbed interface.
TabsVertical
Vertical tab navigation.
Navbar
Navigation bar.
Sidebar
Sidebar navigation.
Breadcrumb
Breadcrumb navigation.
Menu
Menu component.Feedback
Alert
Alert/message box.
Toast
Toast message.
Notification
Toast notification.
Spinner
Loading spinner.
Progress
Progress indicator.
ProgressBar
Progress bar.
ProgressRing
Circular progress indicator.
NProgress
npm-style progress bar.
LoadingText
Animated loading text.Data Display
TableBordered
Bordered table.
TableZebra
Zebra-striped table.
List
List renderer.
Tree
Tree structure.
Metric
Metric display.
Stat
Single stat display.
Stats
Statistics display.
MetricsGrid
Grid of metrics.Media
Image
Image display.
Picture
Picture frame.Avatar
User avatar.AvatarGroup
Group of avatars.Icon
Icon display.
QRCode
QR code.
Barcode
Barcode.
Video
Video player.
Audio
Audio player.Text
Text
Word-wrapped text.
Paragraph
Paragraph text.
Code
Code block.
Kbd
Keyboard key display.
Emoji
Emoji display.
FigletText
ASCII art text.
ASCIIBanner
ASCII banner text.
Highlight
Syntax highlighted code.
HexDump
Hex dump viewer.
DotMatrix
Dot matrix display.
Pictogram
Pictogram display.
Boxer
Tree-based layout splitting — a region subdivided by ratio down to content leaves.Status
Clock
Digital clock.
Timer
Countdown timer.
Stopwatch
Stopwatch.
Calendar
Calendar view.
Terminal
Terminal emulator.
LogViewer
Log file viewer.
Log
Log entry.
Console
Terminal console.
State
Application state.
Focus
Focus state management.Advanced
Accordion
Accordion/collapsible.
ActivityFeed
Activity feed.
Badge
Badge/tag component.
Testimonial
Testimonial quote.
Profile
User profile card.
CTA
Call-to-action.
Jumbotron
Jumbotron hero section.
EmptyState
Empty state placeholder.
Skeleton
Loading skeleton.
Marquee
Scrolling marquee text.
Scrollbar
Custom scrollbar.
Tooltip
Tooltip popup.
Popover
Popover content.
Hint
Hint component.
Tag
Tag component.
Rating
Star rating display.
Leaderboard
Leaderboard display.
Diff
Diff view.
Editor
Text editor.
CommandPalette
Command palette.
Modal
Modal dialog.
WordCloud
Word cloud visualization.Dashboard Examples
Dashboard Layout
Layout containers demo.
Dashboard Charts
Charts demo.
Dashboard Form
Form demo.
Dashboard Nav
Navigation demo.
Dashboard Status
Status indicators demo.
Dashboard Text
Text components demo.
Dashboard Time
Time components demo.
Dashboard UI
UI components demo.
Dashboard Complex
Complex layout demo.
Dashboard Data
Data display demo.
Dashboard Devtools
Devtools demo.
Dashboard Accordion Timeline
Accordion and timeline components.
Dashboard Media
Media components demo.