SugarFlexbox
FlexBox layout + delta Table + sticky Viewport + Scrollbar
FlexBox layout engine for terminal grids — ratio-based item sizing, gap, align. Plus a simple table with sort, filter, cursor nav, and column styling. Viewport and Scrollbar compose the canonical sugar-forms classes.
Install
composer require sugarcraft/sugar-flexbox
Quickstart
use SugarCraft\Flexbox\Flex\{FlexBox, FlexItem};
use SugarCraft\Flexbox\Flex\Align;
use SugarCraft\Flexbox\Table\{Table, Column};
$flex = FlexBox::row(
FlexItem::new('LEFT')->withRatio(1),
FlexItem::new('RIGHT')->withRatio(2),
)->withGap(2);
$table = Table::new()
->withColumn(Column::new('Name', 20))
->withColumn(Column::new('Age', 5)->withAlign(Align::End))
->withRow(['Alice', '30'])
->withRow(['Bob', '25'])
->withSort(0);
echo $flex->render(40, 1), PHP_EOL;
echo $table->render(), PHP_EOL;
What's in the box
Source & demos
- Source on GitHub
- Full README
- Runnable examples
- Design antecedent: 76creates/stickers (PHP); SugarCraft is developed as a native PHP project.
Trust boundary
Table, Column and FlexBox treat everything they render as untrusted data: cell values and column titles pass through Sanitize::untrusted(), and at render time a line feed or a CRLF pair collapses to a single space, a tab becomes a single space, and a lone carriage return is DELETED (not replaced) — so no escape sequence can ride in through content. One asymmetry to know about: the FlexBox measures an item's raw content before the sweep, and only the tab skews the budget (it measures four cells and prints one space — over-allocation, never a truncation); every other swept byte measures zero cells on both sides. Style strings are gated to legal SGR parameter text (codes 0..255 separated by single ;, colon sub-parameters normalized at the door) or empty for no style; anything else throws InvalidArgumentException naming the refused property. Viewport and Scrollbar are trusted-input by design — the Viewport renders your setContent() / fromContent() lines as given and the Scrollbar emits your runes verbatim — so sanitize user input before feeding them.
Accessibility
Focus is never carried by color alone. The cursor row's default cue is its style; withCursorMarker() prepends a glyph inside the first column's width without moving frame dimensions. A screen reader announces neither color nor shape — pair the visual cue by reading cursor()/currentRow() on every change. Sort state is a glyph (▲/▼), not a color; a filtered-to-nothing table can say so with withEmptyText() over totalRowCount()/filterText().
Reduced motion has a real switch (withSmoothScroll(false)), keyboard is the primary path (every scroll verb answers update() with a KeyMsg; see examples/viewport-keys.php), and color policy stays the host's: the library never reads NO_COLOR/TERM — validated SGR you pass in is passed through deliberately.
API
| Class | Method | Description |
|---|---|---|
| FlexBox | row(...items) | Create horizontal flexbox |
| FlexBox | column(...items) | Create vertical flexbox |
| FlexBox | withGap(cells) | Set gap between items |
| FlexBox | withAlign(Align) | Align enum case (Start/Center/End/Stretch) driving both axes — takes the enum, not a string |
| FlexItem | new(content) | Create flex item |
| FlexItem | withRatio(n) | Share of leftover main-axis space (0 = never grows, keeps its floor) |
| FlexItem | withBasis(cells) | Fixed main-axis reservation before ratios share the rest |
| FlexItem | withWidth(cells) | Deprecated alias of withBasis() retiring in 2.0.0 — in column mode the reserved axis is the HEIGHT; prefer withBasis |
| Table | new() | Create empty table |
| Table | withColumn(col) | Add a column (addColumn() retires in 2.0.0) |
| Table | withRow(cells) | Add a row; surplus values throw at the door (withRow is the canonical spelling) |
| Table | withSort(col, asc) | Sort by column — the selection follows its row through the re-sort |
| Table | sortByNext(col) | Toggle asc/desc on a column (selection follows its row) |
| Table | withFilter(text) | Rows containing the Unicode case-folded substring in any cell; a selection whose row is filtered away falls back to row 0 |
| Table | withCursorStyle(style) | SGR string for the cursor row (default '' marks nothing on screen) |
| Table | withCursorMarker(prefix) | Non-color focus glyph inside the first column's width (screen readers still need a spoken cue — read cursor()) |
| Table | withEmptyText(text) | Row spanning the grid when a filter drops every row ('no matches' disclosure) |
| Table | withCursor(row) | Move the cursor — the door settles the view and refuses indexes outside it |
| Table | cursor() | Cursor index of the settled view (null only while the view holds no rows) |
| Table | rawCurrentRow() | Stored values of the cursor row, un-rendered (null when the view has no rows) |
| Table | rawCurrentCell(col) | Single stored cell under the cursor (currentRow()/currentCell() were renamed raw* and retire in 2.0.0) |
| Table | render() | Full frame (pure); use TableRenderer for deltas |
| TableRenderer | render(table) | First/resize frame full, then change-only delta |
| Column | new(title, width) | Create a column (width in cells; `make()` remains as its deprecated BC alias retiring in 2.0.0) |
| Column | withAlign(align) | Align case (Start/Center/End) or legacy string via the shared alignOf() door; Stretch is FlexBox sizing language and refuses |
| Column | withStyle(style) | SGR parameter string applied to every cell of the column (validated at the door; the cursor style paints over it) |
| Viewport | fromContent(str, w=80, h=24) | Create viewport from string content (withContent() was the old factory name — it impersonated a fluent setter and retires in 2.0.0) |
| Viewport | withStickyHeader/Footer(rows) | Pin FIRST/LAST rows across scrolling; negatives throw at the door |
| Viewport | showScrollbar(bool) | Toggle scrollbar display (withScrollbar() retires in 2.0.0) |
| Viewport | withSmoothScroll(bool) | Reduced-motion switch: off, every scroll settles in one frame |
| Viewport | lineUp/Down(n) | Scroll by n lines |
| Viewport | pageUp/Down(), halfPageUp/Down() | Scroll by a page or half the viewport height |
| Viewport | withMouseWheelEnabled(bool) | Accept mouse-wheel scroll messages |
| Viewport | withMouseWheelDelta(n) | Lines the wheel turns per notch |
| Viewport | gotoTop/Bottom() | Jump to start/end |
| Scrollbar | vertical() | Vertical scrollbar |
| Scrollbar | horizontal() | Horizontal scrollbar |
| Scrollbar | view(state, height) | Render scrollbar |
Demos.
VHS-recorded GIFs of every example shipped with the library. Regenerated automatically on every push that touches the source.
FlexBox row + column
Ratio 1:2:1 row + column with gap=1.
Sort + cursor table
Sort flips on Name and the flag column, then cursor styling, movement and a rawCurrentRow()/rawCurrentCell() readout — no filter call.