All 42 libraries

SugarFlexbox

FlexBox layout + delta Table + sticky Viewport + Scrollbar

design antecedent 76creates/stickers flexboxtablelayoutgrid

SugarFlexbox code coverage

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

FlexBoxRatio-based row / column layout. Align: Start, Center, End, Stretch (one value drives both axes — box height plus text placement in row mode, rendered width plus placement in column mode; no CSS justify-content counterpart).
TableSort by column (asc/desc toggle, with authored secondary tiebreakers via Column::sorted()), filter by case-folded text, cursor navigation guarded at its door, per-column style, hidden (width-0) columns, themeable ruler, and an over-wide disclosure: computeTotalWidth() is the whole grid's width and render() never wraps — compose in a Viewport to scroll it.
ViewportScrollable viewport composes the canonical sugar-forms Viewport. Keyboard nav (line/page/half-page), mouse wheel, smooth scroll, scrollbar. Sticky headers and footers via withStickyHeader()/withStickyFooter(); a document that fits renders the plain streaming face. withLinkedViewport() is a decorative partner marker only (scroll state never propagates).
ScrollbarScrollbar composes the canonical sugar-forms Scrollbar. Vertical/horizontal, configurable thumb/track chars.
ImmutabilityAll builders return new instances.

Source & demos

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.

Try the quickstart →

API

ClassMethodDescription
FlexBoxrow(...items)Create horizontal flexbox
FlexBoxcolumn(...items)Create vertical flexbox
FlexBoxwithGap(cells)Set gap between items
FlexBoxwithAlign(Align)Align enum case (Start/Center/End/Stretch) driving both axes — takes the enum, not a string
FlexItemnew(content)Create flex item
FlexItemwithRatio(n)Share of leftover main-axis space (0 = never grows, keeps its floor)
FlexItemwithBasis(cells)Fixed main-axis reservation before ratios share the rest
FlexItemwithWidth(cells)Deprecated alias of withBasis() retiring in 2.0.0 — in column mode the reserved axis is the HEIGHT; prefer withBasis
Tablenew()Create empty table
TablewithColumn(col)Add a column (addColumn() retires in 2.0.0)
TablewithRow(cells)Add a row; surplus values throw at the door (withRow is the canonical spelling)
TablewithSort(col, asc)Sort by column — the selection follows its row through the re-sort
TablesortByNext(col)Toggle asc/desc on a column (selection follows its row)
TablewithFilter(text)Rows containing the Unicode case-folded substring in any cell; a selection whose row is filtered away falls back to row 0
TablewithCursorStyle(style)SGR string for the cursor row (default '' marks nothing on screen)
TablewithCursorMarker(prefix)Non-color focus glyph inside the first column's width (screen readers still need a spoken cue — read cursor())
TablewithEmptyText(text)Row spanning the grid when a filter drops every row ('no matches' disclosure)
TablewithCursor(row)Move the cursor — the door settles the view and refuses indexes outside it
Tablecursor()Cursor index of the settled view (null only while the view holds no rows)
TablerawCurrentRow()Stored values of the cursor row, un-rendered (null when the view has no rows)
TablerawCurrentCell(col)Single stored cell under the cursor (currentRow()/currentCell() were renamed raw* and retire in 2.0.0)
Tablerender()Full frame (pure); use TableRenderer for deltas
TableRendererrender(table)First/resize frame full, then change-only delta
Columnnew(title, width)Create a column (width in cells; `make()` remains as its deprecated BC alias retiring in 2.0.0)
ColumnwithAlign(align)Align case (Start/Center/End) or legacy string via the shared alignOf() door; Stretch is FlexBox sizing language and refuses
ColumnwithStyle(style)SGR parameter string applied to every cell of the column (validated at the door; the cursor style paints over it)
ViewportfromContent(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)
ViewportwithStickyHeader/Footer(rows)Pin FIRST/LAST rows across scrolling; negatives throw at the door
ViewportshowScrollbar(bool)Toggle scrollbar display (withScrollbar() retires in 2.0.0)
ViewportwithSmoothScroll(bool)Reduced-motion switch: off, every scroll settles in one frame
ViewportlineUp/Down(n)Scroll by n lines
ViewportpageUp/Down(), halfPageUp/Down()Scroll by a page or half the viewport height
ViewportwithMouseWheelEnabled(bool)Accept mouse-wheel scroll messages
ViewportwithMouseWheelDelta(n)Lines the wheel turns per notch
ViewportgotoTop/Bottom()Jump to start/end
Scrollbarvertical()Vertical scrollbar
Scrollbarhorizontal()Horizontal scrollbar
Scrollbarview(state, height)Render scrollbar

Demos.

VHS-recorded GIFs of every example shipped with the library. Regenerated automatically on every push that touches the source.

Three panels: a ratio row, a stacked column, a centered row

FlexBox row + column

Ratio 1:2:1 row + column with gap=1.
Table frames with sort arrows, then a highlighted cursor row and a raw readout

Sort + cursor table

Sort flips on Name and the flag column, then cursor styling, movement and a rawCurrentRow()/rawCurrentCell() readout — no filter call.
Table frames sorted by column then narrowed to rows containing the letter e

Sort + filter table

Age-ascending and Score-descending sorts plus an "e" filter over per-column widths and right-aligned numerics.