SugarPanels
H/V panels with flex/natural sizing, borders, nesting, and stateful delta rendering
Compose terminal layouts with horizontal and vertical panels. Attach borders, hint minimum and maximum sizes, let flex children fill the rest, and nest arbitrarily deep.
Install
composer require sugarcraft/sugar-panels
Quickstart
use SugarCraft\Panels\SugarPanels;
$panels = SugarPanels::new();
$layout = $panels->vertical(
$panels->horizontal(
$panels->leaf("Left panel"),
$panels->leaf("Right panel"),
)->withBorder(false)->withGrow(),
$panels->leaf("Bottom bar")->withBorder(false),
)->withBorder(false);
echo $panels->render($layout, 60, 7);
Every node is bordered by default — a plain nested layout paints a doubled frame at each level. Containers are usually scaffolding, so turn their frames off with withBorder(false) (or wrap a subtree in noBorder(), which suppresses every frame and every divider below it), and give the viewport enough rows to hold what you asked for. That prints (protocol and styling stripped):
╭────────────────────────────╮╭────────────────────────────╮
│Left panel ││Right panel │
│ ││ │
│ ││ │
│ ││ │
╰────────────────────────────╯╰────────────────────────────╯
Bottom bar
The horizontal row carries withGrow(), so it flexes to six of the seven rows while Bottom bar — the fixed child — claims its measured natural single row at the bottom. Every row the renderer emits is padded to the viewport width, Bottom bar's included.
What's in the box
Styled content stays trusted input — escape sequences ride through by design; see the README's Trust boundary section.
Where it fits
There are no in-repo consumers yet — sugar-panels ships as the ecosystem's pane composer for your application. When a sibling does a similar-looking job: the raw CSS flexbox computation (solve, don't paint) is sugar-flexbox; modal foregrounds over existing content with dimming and zone hit-testing are sugar-overlay; tabular data grids with a row cursor are sugar-table. Nested horizontal/vertical panes with borders, titles and flex weights, painted as plain ANSI strings — that is sugar-panels.
Source & demos
- Source on GitHub
- Full README
- Runnable examples
- Originally inspired by treilik/bubbleboxer (Go); SugarCraft is developed as a native PHP project.
API
| Class | Method | Description |
|---|---|---|
| SugarPanels | new() | Create a panels instance |
| SugarPanels | leaf(string) | Leaf node with string content |
| SugarPanels | horizontal(Node ...) | Horizontal (row) layout |
| SugarPanels | vertical(Node ...) | Vertical (column) layout |
| SugarPanels | noBorder(Node) | Suppresses every frame and every divider through the whole subtree — adjacent panels render touching |
| SugarPanels | render(Node, int $width, int $height) | Paint one frame to an ANSI string; throws InvalidArgumentException on a viewport outside the documented ranges |
| SugarPanels | resetPreviousFrame() | Drop the frame cache — the next render() repaints full, without erasing |
| SugarPanels | MAX_VIEWPORT_DIMENSION | 4096 cells — largest viewport side accepted |
| SugarPanels | MAX_VIEWPORT_CELLS | 1 000 000 cells — largest viewport area accepted (printed as 1000000 in the exception message) |
| Node | leaf(string) | Static leaf constructor |
| Node | horizontal(Node ...) | Static horizontal constructor |
| Node | vertical(Node ...) | Static vertical constructor |
| Node | noBorder(Node) | Static no-border wrapper — suppresses every frame and every divider through the whole subtree |
| Node | totalWidth() / totalHeight() | Footprint the node claims: natural content, floored by min*, capped by max*, plus padding, frame and margin |
| Node | withMinWidth(int) | Floor for the natural width. That floor enters the flex path through fixed children's bases; a grown child gets only its weighted share, its min* is not applied, and totalWidth() over-claims for grown children; in the legacy equal-split fallback, a min* acts as a proportional weight, not a floor |
| Node | withMaxWidth(int) | Cap on the node's painted footprint (frame + padding + content) — what a flex basis claims. 0 means no cap; margin rides outside the cap, matching totalWidth() |
| Node | withMinHeight(int) | Floor for the natural height. That floor enters the flex path through fixed children's bases; a grown child gets only its weighted share, its min* is not applied, and totalHeight() over-claims for grown children; in the legacy equal-split fallback, a min* acts as a proportional weight, not a floor |
| Node | withMaxHeight(int) | Cap on the node's painted footprint (frame + padding + content) — what a flex basis claims. 0 means no cap; margin rides outside the cap, matching totalHeight() |
| Node | withPadding(int) | Inner padding (cells) |
| Node | withBorder(bool) | Show/hide box border |
| Node | withSpacing(int) | Gap between children (cells) |
| Node | withContent(string) | Replace leaf content (new node) |
| Node | withFlex(int) | Fill leftover space by weight (0 = fixed, natural size) |
| Node | withGrow() | Shorthand for withFlex(1) |
| Node | withBorderStyle(?Border) | Border char set from sugar-style |
| Node | withStyle(?Style) | Style (color, attributes) from sugar-style |
| Node | withTitle(string) | Box title text |
| Node | withMargin(int $top, ...) | Outer margin (top/right/bottom/left) |
| Node | withAlignH(?Align) | Horizontal text alignment (null clears) |
| Node | withAlignV(?VAlign) | Vertical text alignment (null clears) |
Demos.
VHS-recorded GIFs of three of the five examples shipped with the library. Regenerated automatically on every push that touches the source.
Border styles
Every named Border::catalog() preset, side by side with its name.
Basic compose
Horizontal + vertical panels with weighted sizing.