README

A comprehensive TUI component library for PHP 8.3+, ported from the Charmbracelet ecosystem (bubbletea, bubble-grid, lipgloss). Provides 200+ components organized into 13 namespaces for building rich terminal user interfaces.

Installation

composer require sugarcraft/sugar-dash

Namespace Structure (13 Namespaces)

Namespace	Description
`Foundation\`	Pure interfaces + low-level primitives (Item, Sizer, Style, Theme, Color, Rect, Drawable, Buffer, Cell)
`Layout\`	Layout primitives (Stack, VStack, HStack, ZStack, FlexLayout, GridLayout, Frame, Panel, Split, Spacer, Window, etc.)
`Components\`	UI components (Modal, Select, Toast, Tabs, StatusBar, Form, Feedback, Nav, Card, Calendar, Tree, Table, etc.)
`Plot\`	Charts and plotting (Chart, Sparkline, Gauge, Donut, Heatmap, RadarChart, TreeViz, Graph, etc.)
`Module\`	Module interface + base implementations
`Registry\`	Registry pattern for modules
`Plugin\`	Plugin system with JSON protocol
`Modules\`	Built-in modules (Clock, System, Weather, etc.)
`Events\`	Input/event plumbing (Event, KeyEvent, MouseEvent, FocusEvent, etc.)
`Keys\`	Key registry and mappings
`Position\`	ANSI-aware geometry helpers
`Output\`	Extracted helpers (truncate, render bar)
`State\`	State management

Foundation Namespace

Interfaces & Contracts

Type	Description	Key Methods
`Item`	Anything that can be rendered as a string	`render(): string`
`Sizer`	An Item that knows its own dimensions (extends Item)	`setSize(int $width, int $height): Sizer`, `render(): string`
`Drawable`	Universal draw contract with GetRect/SetRect/Draw	`getRect(): Rect`, `setRect(Rect): void`, `draw(Buffer): void`

Configuration Classes

Type	Description	Key Properties
`Options`	Grid-level configuration options	`$fitScreen: bool` (default: true)
`ItemOptions`	Per-item placement options within StackedGrid	`$column: int` (0-based), `$expandVertical: bool`
`ItemWithOptions`	Internal pairing of Item + ItemOptions	`$item: Item`, `$options: ItemOptions`

Low-Level Primitives

Type	Description	Key Methods
`Cell`	Single terminal cell (rune + style)
`Buffer`	Cell grid buffer for drawing	`getCell(x,y)`, `setCell(x,y,Cell)`, `fill(rect,Cell)`
`Rect`	Rectangle geometry	`contains()`, `intersect()`, `dx()`, `dy()`
`Style`	Terminal styling (colors, attributes)	`fg()`, `bg()`, `bold()`, etc.
`StyleParser`	ParseStyles inline syntax `[text](fg:red,bg:blue)`
`Color`	Color representation
`Theme`	Pre-defined theme palettes	`dark()`, `dracula()`, `oneDark()`, `githubDark()`, `light()`

Layout Namespace

Layout Enums

Type	Values
`LayoutDirection`	`Horizontal`, `Vertical`
`SplitDirection`	`Horizontal`, `Vertical`
`AlignItems`	`Start`, `End`, `FlexStart`, `FlexEnd`, `Center`, `Stretch`, `Baseline`
`FlexDirection`	`Row`, `Column`, `RowReverse`, `ColumnReverse`
`FlexWrap`	`NoWrap`, `Wrap`, `WrapReverse`
`HAlign`	`Left`, `Right`, `Center`
`VAlign`	`Top`, `Middle`, `Bottom`
`JustifyContent`	`Start`, `End`, `FlexStart`, `FlexEnd`, `Center`, `SpaceBetween`, `SpaceAround`, `SpaceEvenly`

Layout Containers

Type	Description	Key Methods/Factories
`StackedGrid`	Multi-column stacked grid layout with items in columns	`addItem(Item, ItemOptions)`, `new(Options)`
`GridLayout`	CSS Grid-style layout with rows/columns/gaps	`columns(int, items)`, `rows(int, items)`, `withGap()`, `withItem()`
`FlexLayout`	Flexbox-style layout with direction/wrap/justify	`row()`, `column()`, `withJustify()`, `withAlignItems()`, `withGap()`
`VStack`	Vertical stack with alignment and spacing	`new(...items)`, `spaced(int, ...items)`, `centered(...items)`, `right(...items)`
`HStack`	Horizontal stack with spacing and alignment	`new(...items)`, `spaced(int, ...items)`, `centered(...items)`
`ZStack`	Layered stack (items on top of each other)	`new(...items)`, `left(...items)`, `right(...items)`, `top(...items)`, `bottom(...items)`
`Stack`	Basic vertical stack	`new(...items)`, `spaced(int, ...items)`
`Split`	Split view with two panes	`new(...items)`, `horizontal()`, `vertical()`

Border & Frame Components

Type	Description	Key Methods/Factories	GIF
`Frame`	Bordered frame wrapping any Item with title/padding	`new(Item)`, `withBorder()`, `withBorderColor()`, `withPadding()`, `withTitle()`
`Panel`	Panel with header/content/footer sections	`new(Item	string)`,` titled(Item
`BoxDrawing`	Unicode box-drawing frame generator	`new(?string)`, `titled(string)`, `double()`, `rounded()`, `bold()`, `withStyle()`, `withBorderColor()`, `withBgColor()`
`BorderText`	Text with ASCII-art border characters	`new(Item	string)`,` withBorders(Item
`Divider`	Horizontal or vertical divider line	`new(?string)`, `h(?string)`, `v(?string)`, `withStyle()`, `withLabel()`, `withColor()`

Spacing & Layout Helpers

Type	Description	Key Methods/Factories
`Spacer`	Empty space filler with optional fill character	`new(int $width, int $height)`, `dotted(int)`, `dashed(int)`, `vertical(int, int)`
`LayoutItem`	Item with flex properties for layouts	`flex(Item, int)`, `fixed(Item)`
`Shadow`	Drop shadow effect wrapping any Item	`new(Item)`, `withStyle()`, `withColor()`, `withOffset()`, `withHeavy()`, `withNoShadow()`
`Segment`	7-segment digital display	`new(string)`, `withDigitWidth()`, `withOnColor()`, `withOffColor()`
`Window`	Window frame with title bar
`Screen`	Terminal screen container
`Viewport`	Scrollable viewport
`Sidebar`	Sidebar navigation panel
`Pad`	Padding wrapper (formerly Boxer)

Plot Namespace (Charts & Visualization)

Chart Components

Type	Description	Key Methods/Factories
`Plot`	Line/scatter chart with braille plotting	`new(dataPoints, type)`, `withDataPoints()`, `withType()`, `withColor()`, `withGrid()`
`Chart`	Bar/line chart with axes, labels, grid	`new(dataPoints, type)`, `withDataPoints()`, `withType()`, `withColor()`, `withGrid()`, `withShowValues()`
`AreaChart`	Area chart for time series data	`new(series)`, `withShowGrid()`, `withShowLegend()`, `withMaxValue()`, `withStacked()`
`Area`	Stacked area chart with gradient fills	`new(dataPoints)`, `sample(int)`, `withDataPoints()`, `withStacked()`, `withShowLegend()`
`AreaPoint`	Area chart data point: `label: string`, `value: float`, `y0: float	null`
`Bar`	Horizontal status bar with colors	`new(string)`, `withContent()`, `withForeground()`, `withBackground()`, `withAlign()`, `withBorders()`
`CandlestickChart`	Financial candlestick chart	`new()`, `withCandle()`, `addCandle()`, `withShowGrid()`, `withShowVolume()`
`Candlestick`	Single OHLC candlestick: `label`, `open`, `high`, `low`, `close`	`bullish()`, `bearish()`, `isBullish()`
`Donut`	Donut chart with proportional segments	`new(data)`, `mocha(data)`, `withSize()`, `withCenterLabel()`, `withShowPercentage()`
`Gauge`	Horizontal progress bar / gauge	`new(float $ratio)`, `withWidth()`, `withFilledColor()`, `withEmptyColor()`, `withPercentage()`
`GaugeChart`	Circular gauge chart
`GaugeCircle`	Circular gauge visualization
`HeatMapChart`	2D heatmap with color gradient	`new(data)`, `sample()`, `withRowLabels()`, `withColumnLabels()`, `withLowColor()`, `withHighColor()`
`Heatmap`	Heat map visualization with legend	`new(data)`, `sample()`, `withLegend()`, `withValues()`, `withLowColor()`, `withHighColor()`
`HeatmapCalendar`	GitHub-style calendar heatmap	`new(data)`, `sample()`, `withLowColor()`, `withHighColor()`, `withEmptyChar()`
`RadarChart`	Radar/spider chart for multi-axis data	`new(labels, series)`, `withSize()`, `withGridLines()`, `withShowLabels()`
`Sparkline`	Inline sparkline chart	`new(data)`, `withData()`, `withWidth()`, `withHeight()`, `withDataPoints()`, `withFill()`
`SparklineBar`	Bar-style sparkline
`SparklineArea`	Area-style sparkline
`SparkArea`	Spark area chart
`FunnelChart`	Funnel chart visualization
`Funnel`	Funnel visualization component
`Bullet`	Bullet chart
`Meter`	Meter/gauge component
`Rating`	Star rating display
`OHLC`	Open-High-Low-Close data
`OHLCPoint`	OHLC data point
`Waterfall`	Waterfall chart
`WaterfallItem`	Waterfall bar item
`MetricsGrid`	Grid of metric displays

Graph & Network Visualization

Type	Description	Key Methods/Factories
`Sankey`	Sankey diagram for flow visualization	`new()`, `addNode()`, `addFlow()`, `withHorizontal()`, `withShowLabels()`
`SankeyNode`	Node in Sankey diagram: `id`, `label`, `value`, `color`
`SankeyFlow`	Flow connection: `source`, `target`, `value`, `color`
`Sunburst`	Sunburst chart visualization
`Treemap`	Treemap chart visualization
`TreemapLeaf`	Leaf node in treemap
`TreeViz`	Tree visualization
`Network`	Network diagram
`NetworkNode`	Node in network
`NetworkShape`	`Circle`, `Square`, `Diamond`, `Hexagon`, `Star`
`MindMap`	Mind map visualization
`OrgChart`	Organization chart
`ClassDiagram`	UML class diagram
`Flowchart`	Flowchart diagram
`FlowchartNode`	Node in flowchart
`FlowchartNodeType`	`Process`, `Decision`, `StartEnd`, `InputOutput`, `Connector`, `Data`
`Dendrogram`	Dendrogram/tree diagram
`DendrogramNode`	Node in dendrogram
`Gantt`	Gantt chart
`PERT`	PERT chart
`Timeline`	Timeline display
`TimelineViz`	Timeline visualization
`TimelineNode`	Node in timeline
`Sequence`	Sequence diagram
`Graph`	Graph visualization
`Bubble`	Bubble chart
`BubblePoint`	Bubble chart point
`Leaderboard`	Leaderboard display
`WordCloud`	Word cloud visualization
`DotMatrix`	Dot matrix display
`Pictogram`	Pictogram display
`Partition`	Partition chart
`PartitionSegment`	Partition segment
`Diff`	Diff view
`Ladder`	Ladder diagram
`Canvas`	Drawing canvas
`Scrollbar`	Custom scrollbar

Components Namespace

Components\Form (Form & Input)

Type	Description	Key Methods/Factories
`Input`	Text input field	`new(?string)`, `labeled()`, `password()`, `withValue()`, `withPlaceholder()`, `withLabel()`, `withError()`, `withBorderColor()`
`Textarea`	Multi-line text area
`Checkbox`	Checkbox group with single/multi-select	`new(options)`, `withSelectedIndex()`, `withOptionChecked()`, `withMultiSelect()`, `withCheckedColor()`
`Radio`	Radio button
`Toggle`	Toggle switch
`SwitchComponent`	Switch component
`Slider`	Slider control
`Select`	Dropdown select component	`new(options)`, `withSelectedIndex()`, `withOptions()`, `withSelectedColor()`
`ComboBox`	Combo box
`Dropdown`	Dropdown menu
`DatePicker`	Date picker
`ColorPicker`	Color picker
`Label`	Form label
`Chip`	Chip/tag component
`ChipGroup`	Group of chips
`Editor`	Text editor
`CommandPalette`	Command palette
`Cursor`	Terminal cursor

Components\Feedback (Non-Modal Feedback)

Type	Description	Key Methods/Factories
`Alert`	Alert/message box (info, warning, error, success)	`new(string)`, `info()`, `warning()`, `error()`, `success()`, `withMessage()`, `withTitle()`, `withBorderColor()`
`Badge`	Badge/tag component	`new(string)`, `success()`, `warning()`, `error()`, `info()`, `withStyle()`, `withSize()`, `withIcon()`
`BadgeGroup`	Group of badges
`LoadingText`	Animated loading text
`Skeleton`	Loading skeleton
`Spinner`	Loading spinner
`Toast`	Toast message
`Tooltip`	Tooltip popup
`Popover`	Popover content
`NProgress`	npm-style progress bar
`Marquee`	Scrolling marquee text
`EmptyState`	Empty state placeholder

Components\Modal (Modal Dialogs)

Type	Description	Key Methods/Factories	GIF
`Modal`	Modal dialog
`Notification`	Toast notification
`Progress`	Progress indicator
`ProgressBar`	Progress bar
`ProgressRing`	Circular progress indicator
`Drawer`	Drawer panel
`Wizard`	Multi-step wizard
`WizardStep`	Wizard step

Components\Nav (Navigation)

Type	Description	Key Methods/Factories
`Tabs`	Tabbed interface	`new(tabs)`, `withSelectedIndex()`, `withActiveColor()`, `withTabs()`
`TabsVertical`	Vertical tab navigation
`Breadcrumb`	Breadcrumb navigation	`new(items)`, `fromPath()`, `withItems()`, `withSeparator()`, `withActiveIndex()`
`Pagination`	Pagination controls
`PaginationSimple`	Simple pagination
`Stepper`	Step progress indicator
`Navbar`	Navigation bar
`Menu`	Menu component
`Ladder`	Ladder diagram
`Sequence`	Sequence diagram
`Scrollbar`	Custom scrollbar

Components\StatusBar (Status Bar)

Type	Description	Key Methods/Factories	GIF
`StatusBar`	Status bar with left/right zones	`new()`, `withLeft()`, `withRight()`, `withSeparator()`
`StatusIndicator`	Status indicator dot

Components\Card (Card & Content Components)

Type	Description	Key Methods/Factories	GIF
`Card`	Card container component
`Header`	Page header
`Footer`	Page footer
`Cover`	Cover layout
`Jumbotron`	Jumbotron hero section
`CTA`	Call-to-action component
`Profile`	User profile card
`Testimonial`	Testimonial quote
`Pricing`	Pricing table
`Features`	Feature grid
`Accordion`	Accordion/collapsible
`Comment`	Comment component
`ActivityFeed`	Activity feed
`Leaderboard`	Leaderboard display

Components\Media (Media Components)

Type	Description	Key Methods/Factories	GIF
`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
`FigletText`	ASCII art text (FIGlet style)
`ASCIIBanner`	ASCII banner text
`Emoji`	Emoji display
`Marquee`	Scrolling marquee text

Components\Calendar (Calendar & Date Components)

Type	Description	Key Methods/Factories	GIF
`Calendar`	Calendar view
`ListComponent`	List renderer

Components\System (System/Console Components)

Type	Description	Key Methods/Factories	GIF
`Console`	Terminal console
`Terminal`	Terminal emulator
`Log`	Log entry
`LogViewer`	Log file viewer
`HexDump`	Hex dump viewer
`Clock`	Digital clock
`Timer`	Countdown timer
`Stopwatch`	Stopwatch

Components\Tree (Tree Structure Components)

Type	Description	Key Methods/Factories	GIF
`Tree`	Tree structure
`TreeNode`	Tree node

Components\Table (Table Components)

Type	Description	Key Methods/Factories	GIF
`TableChart`	Table-based chart
`TableBordered`	Bordered table
`TableZebra`	Zebra-striped table
`Stat`	Single stat display
`Stats`	Statistics display
`Metric`	Metric display
`ProgressList`	List of progress items

Components\Text (Text Components)

Type	Description	Key Methods/Factories
`Text`	Word-wrapped text content	`new(string)`, `withMaxWidth()`, `withTrim()`, `withHorizontalAlign()`
`Paragraph`	Paragraph text
`Code`	Code block with syntax highlighting
`Kbd`	Keyboard key display
`Markdown`	Markdown rendering
`Highlight`	Syntax highlighted code
`Diff`	Diff view

Events Namespace (Input/Event Plumbing)

Type	Description	Key Properties
`Event`	Base event class
`EventHandler`	Event handler callback
`EventDispatcher`	Event dispatcher
`FocusEvent`	Focus event
`KeyEvent`	Keyboard event
`MouseEvent`	Mouse event
`PasteEvent`	Paste event
`ResizeEvent`	Resize event
`Focus`	Focus state management

Keys Namespace (Key Registry)

Type	Description	Key Properties
`Key`	Key representation
`KeyAction`	Key action
`KeyMap`	Key mapping

State Namespace (State Management)

Type	Description	Key Properties
`State`	Application state

Position Namespace (ANSI-Aware Geometry)

Type	Description	Key Methods
`Center`	Calculate centered position
`HAlign`	`Left`, `Right`, `Center`
`VAlign`	`Top`, `Middle`, `Bottom`

Output Namespace (Extracted Helpers)

Type	Description	Key Methods
`Truncate`	String truncation with ANSI awareness
`RenderBar`	Bar rendering helper
`WrapCells`	Cell-aware text wrapping

Module Namespace (Module Interface)

Type	Description	Key Methods
`Module`	Elm-arch interface aligned with `Core\Model`: `init(): ?Closure`, `update(Msg): array{0:Module,1:?Cmd}`, `view(): string`, plus `name(): string`, `minSize(): array{0:int,1:int}`
`BaseModule`	Abstract helper — `withState(array): static` for immutable state, default `update()` returns `[self,null]`
`LegacyModule`	Deprecated array-state interface — superseded by `Module`
`LegacyModuleAdapter`	`@internal` wrapper that adapts `LegacyModule` to the `Module` contract
`ModuleConfig`	Module configuration
`ImagePlacer`	Optional interface for image placements
`ImagePlacement`	Image placement data
`TickEpoch`	Focus-regain epoch counter

Registry Namespace (Module Registry)

Type	Description	Key Methods
`Registry`	Static register/get/list/reset for modules; auto-wraps `LegacyModule` via `LegacyModuleAdapter`

Plugin Namespace (Plugin System)

Type	Description	Key Methods
`Request`	Plugin request DTO
`Response`	Plugin response DTO
`PluginSdk`	Plugin runner loop
`ExternalModule`	Wraps binary into Module interface
`Discovery`	Plugin discovery from filesystem

Modules Namespace (Built-in Modules)

All built-in modules extend BaseModule and use withState() for immutable state updates.

Type	Description
`Clock\ClockModule`	Single-line clock
`System\SystemModule`	CPU/mem/disk stats
`Uptime\UptimeModule`	System uptime
`Greeting\GreetingModule`	Time-of-day greeting
`Generic\GenericModule`	Arbitrary shell command runner

Usage Example

use SugarCraft\Dash\Layout\{Frame, VStack, Panel};
use SugarCraft\Dash\Layout\{StackedGrid, Options, ItemOptions};
use SugarCraft\Dash\Components\Text;

// Create a stacked grid layout
$grid = new StackedGrid(new Options(fitScreen: true));

// Add items to columns
$grid->addItem(
    Frame::new(
        VStack::centered(
            Text::new('Welcome to SugarDash'),
            Text::new('Build beautiful TUIs')
        )
    )->withPadding(1),
    new ItemOptions(column: 0, expandVertical: true)
);

// Add a panel to the second column
$grid->addItem(
    Panel::titled(
        Text::new('This is a panel'),
        'Dashboard'
    ),
    new ItemOptions(column: 1)
);

// Set size and render
$grid->setSize(80, 24);
echo $grid->render();

Testing

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

GIF Demos

Demo	Description
	Layout containers demo
	Charts demo
	Form demo
	Navigation demo
	Status indicators demo
	Text components demo
	Time components demo
	UI components demo
	Complex layout demo
	Data display demo
	Devtools demo
	Interactive components demo
	Media components demo
	Metrics display demo

Example Demos

The examples/ directory contains standalone demo files that showcase individual components and combinations:

Demo	Description
`dashboard-showcase.php`	Multi-component server dashboard with gauges, charts, timeline, breadcrumb, avatar group
`dashboard-complex.php`	Full-featured analytics dashboard with charts, stats, funnel, sparkline
`dashboard-interactive.php`	Accordion and timeline components
`dashboard-metrics.php`	Key statistics and status indicators
`dashboard-status.php`	Spinners, progress bars, gauges, alerts
`dashboard-charts.php`	Chart components including area, donut, radar, heatmap
`dashboard-form.php`	Form components demo
`dashboard-ui.php`	UI components demo
`dashboard-nav.php`	Navigation components demo
`dashboard-text.php`	Text components demo
`dashboard-time.php`	Time components demo
`dashboard-media.php`	Media components demo
`dashboard-data.php`	Data display components demo
`dashboard-devtools.php`	Devtools components demo
`dashboard-layout.php`	Layout containers demo

License

MIT License - See LICENSE file for details.

sugarcraft / sugar-dash

Maintainers

Package info

Statistics

Security