All 42 libraries

SugarPanels

H/V panels with flex/natural sizing, borders, nesting, and stateful delta rendering

inspired by treilik/bubbleboxer layoutboxborderuipaneltui

SugarPanels code coverage

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

H/V panelsRow and column composition with weighted sizing.
BordersPreset or custom border styles per panel.
Nested layoutsArbitrarily deep nesting — grids within grids.
Word-wrapText reflows inside the region at render time.
ANSI-awareStyled content is placed by visible columns; a clipped or unbalanced span is auto-reset so color stays inside its box.
Diff renderingSelf-positioning delta frames repaint only the cells that changed — light SSH payloads, no full-screen flicker.
Trust boundaryHostile text is repaired, not rejected: UTF-8 mended, zone sentinels stripped, stray controls normalized at the paint choke.
Flex / growwithFlex/withGrow children fill leftover space — fixed headers and status bars, a content pane that fills.

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

Try the quickstart →

API

ClassMethodDescription
SugarPanelsnew()Create a panels instance
SugarPanelsleaf(string)Leaf node with string content
SugarPanelshorizontal(Node ...)Horizontal (row) layout
SugarPanelsvertical(Node ...)Vertical (column) layout
SugarPanelsnoBorder(Node)Suppresses every frame and every divider through the whole subtree — adjacent panels render touching
SugarPanelsrender(Node, int $width, int $height)Paint one frame to an ANSI string; throws InvalidArgumentException on a viewport outside the documented ranges
SugarPanelsresetPreviousFrame()Drop the frame cache — the next render() repaints full, without erasing
SugarPanelsMAX_VIEWPORT_DIMENSION4096 cells — largest viewport side accepted
SugarPanelsMAX_VIEWPORT_CELLS1 000 000 cells — largest viewport area accepted (printed as 1000000 in the exception message)
Nodeleaf(string)Static leaf constructor
Nodehorizontal(Node ...)Static horizontal constructor
Nodevertical(Node ...)Static vertical constructor
NodenoBorder(Node)Static no-border wrapper — suppresses every frame and every divider through the whole subtree
NodetotalWidth() / totalHeight()Footprint the node claims: natural content, floored by min*, capped by max*, plus padding, frame and margin
NodewithMinWidth(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
NodewithMaxWidth(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()
NodewithMinHeight(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
NodewithMaxHeight(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()
NodewithPadding(int)Inner padding (cells)
NodewithBorder(bool)Show/hide box border
NodewithSpacing(int)Gap between children (cells)
NodewithContent(string)Replace leaf content (new node)
NodewithFlex(int)Fill leftover space by weight (0 = fixed, natural size)
NodewithGrow()Shorthand for withFlex(1)
NodewithBorderStyle(?Border)Border char set from sugar-style
NodewithStyle(?Style)Style (color, attributes) from sugar-style
NodewithTitle(string)Box title text
NodewithMargin(int $top, ...)Outer margin (top/right/bottom/left)
NodewithAlignH(?Align)Horizontal text alignment (null clears)
NodewithAlignV(?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

Border styles

Every named Border::catalog() preset, side by side with its name.
Basic compose

Basic compose

Horizontal + vertical panels with weighted sizing.
Nested grids

Nested grids

A grid-of-grids — header / body / footer with sidebars.