SugarTreelist
List view with box-drawing prefixes, cursor navigation, word-wrap, and live filtering
List view with box-drawing prefixes, cursor navigation, word-wrap, and live filtering (host-driven). It is a plain final class, not a TEA Model - render it from your host program's view() and feed it input there.
Install
composer require sugarcraft/sugar-treelist
Quickstart
use SugarCraft\TreeList\Model;
// Fluent setters return NEW Models - rebind. Data is immutable; view()
// mutates the delta-render memo in place, and withoutFilter() with no filter
// active is an identity return ($this, no clone).
// Model::tree() = new() + the Default prefixer/suffixer pair; plain new()
// stays deliberately undecorated, and withPrefixer()/withSuffixer() attach
// one half at a time (the set* spellings are deprecated aliases).
$model = Model::tree()
->withWidth(80)
->withHeight(24)
->withItemsFromArray(['src/main.php', 'src/Model.php', 'tests/MainTest.php']);
echo $model->view();
// Renders the list with a ╭ ├ ╰ box-drawing gutter chosen by item position
// (│ appears only as a wrap-continuation glyph), 1-based line numbers, and
// the cursor line decorated with the > … < marker pair
What's in the box
view() emits a full frame, then only changed rows as CUP + EL fragments; assistive hosts want lines() instead, or resetPreviousFrame() before every paint.Accessibility
Guide the cursor with text, not color alone: keep a marker glyph ($currentMarker, or your suffixer's) so position survives monochrome terminals and screen readers — relying on withCurrentStyle()'s color by itself is a WCAG 1.4.1 (use of color) warning. withLineStyle('') + withCurrentStyle('') + lines() is the full plain-text mode: lines() never styles and never deltas, which makes it the right reader for assistive and scripted-output hosts.
The library emits no color of its own — every style is caller-supplied, so pass empty style strings to emit none; sugar-treelist neither reads nor acts on NO_COLOR. Item text all renders through the frame choke (Model::sweepForFrame), so content can forge neither a frame nor a click zone.
Source & demos
- Source on GitHub
- Full README
- Runnable examples
- Primary design source charmbracelet/bubbles/list (Go) — the ported cursor/filter/render surface; naming and tree-gutter context from treilik/bubblelister. SugarCraft is developed as a native PHP project.
API
| Class | Method | Description |
|---|---|---|
| Model | new() | Create model with defaults |
| Model | withFilterFn(\Closure) | Filter items; returns new Model; filterState → filtering |
| Model | withoutFilter() | Clear filter; restore original items; filterState → unfiltered (identity return - $this, no clone - when no filter was active) |
| Model | addItem(\Stringable) | Append a list item |
| Model | setWidth(int) | Set viewport width in cells |
| Model | setHeight(int) | Set viewport height in lines |
| Model | setPrefixer(Prefixer) | Attach a prefixer instance |
| Model | setSuffixer(Suffixer) | Attach a suffixer instance |
| Model | lines() | Return visible lines as array |
| Model | view() | Render the list as an ANSI string: a full frame after resetPreviousFrame() (or on first render), then only changed rows as CUP + row + EL delta fragments |
| Model | resetPreviousFrame() | Drop the delta memo so the next view() repaints the full frame (void; mutates this instance) |
| Model | filterState() | Current ?FilterState — null until the first withFilterFn()/withoutFilter() call, then unfiltered / filtering |
| Model | setViewport(width, height) | Set both dimensions at once |
| Model | setCursor(int) / cursorUp(int) / cursorDown(int) | Jump to, or step the cursor (default 1 row); clamped to the item range |
| Model | cursorPageUp(int) / cursorPageDown(int) | Jump by whole viewport pages (default 1) |
| Model | cursorToStart() / cursorToEnd() | Jump to the first / last item |
| Model | cursorIndex() / cursorItem() / tryCursorItem() | Read the cursor: index; its \Stringable (throws on an empty list); the same, or null |
| Model | setCursorOffset(int) / setWrap(int) | Pin the cursor's row within the viewport; cap an item to N wrapped lines (0 = no cap) |
| FilterState | unfiltered | No filter active |
| FilterState | filtering | Filter function set and applied |
| FuzzyMatch | score(query, candidate) | Smith-Waterman alignment score via the sugar-fuzzy SSOT (int, higher = better) |
| FuzzyMatch | match(query, list<\Stringable>) | Filter and rank items by score; returns list of [item, score] pairs |
| ScoringProfile | canonical() / strict() / lenient() | @deprecated class_alias of SugarCraft\Fuzzy\ScoringProfile (sugar-fuzzy is the SSOT); FuzzyMatch keeps a ?ScoringProfile constructor parameter and withProfile() for migration only - new code depends on sugar-fuzzy directly |
| Item | value | The underlying \Stringable |
| StringItem | __construct(string) | Wrap a plain string as a list item |
Demos.
VHS-recorded GIFs regenerated automatically from the tapes under .vhs/ on every push that touches the source.
Cursor navigation
Box-drawing gutter with cursor movement, repainted as a full frame after resetPreviousFrame().