All 42 libraries

SugarTreelist

List view with box-drawing prefixes, cursor navigation, word-wrap, and live filtering

port of charmbracelet/bubbles/list treelistviewnavigation

SugarTreelist code coverage

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

Box-drawing prefixesSwap in your own prefixer; the shipped one picks its glyph by item position (first / middle / last), not by nesting depth.
Cursor navigationUp / Down / Home / End movement with viewport tracking.
Word-wrapLong items wrap at the configured viewport width (setWidth) — the terminal is never auto-detected.
Filter state machinewithFilterFn() / withoutFilter() with FilterState enum (unfiltered / filtering).
Fuzzy matchingFuzzyMatch delegates scoring to sugar-fuzzy's SmithWatermanMatcher (SSOT).
Per-row delta repaintview() 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

Try the quickstart →

API

Public API surface of sugar-treelist
ClassMethodDescription
Modelnew()Create model with defaults
ModelwithFilterFn(\Closure)Filter items; returns new Model; filterState → filtering
ModelwithoutFilter()Clear filter; restore original items; filterState → unfiltered (identity return - $this, no clone - when no filter was active)
ModeladdItem(\Stringable)Append a list item
ModelsetWidth(int)Set viewport width in cells
ModelsetHeight(int)Set viewport height in lines
ModelsetPrefixer(Prefixer)Attach a prefixer instance
ModelsetSuffixer(Suffixer)Attach a suffixer instance
Modellines()Return visible lines as array
Modelview()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
ModelresetPreviousFrame()Drop the delta memo so the next view() repaints the full frame (void; mutates this instance)
ModelfilterState()Current ?FilterState — null until the first withFilterFn()/withoutFilter() call, then unfiltered / filtering
ModelsetViewport(width, height)Set both dimensions at once
ModelsetCursor(int) / cursorUp(int) / cursorDown(int)Jump to, or step the cursor (default 1 row); clamped to the item range
ModelcursorPageUp(int) / cursorPageDown(int)Jump by whole viewport pages (default 1)
ModelcursorToStart() / cursorToEnd()Jump to the first / last item
ModelcursorIndex() / cursorItem() / tryCursorItem()Read the cursor: index; its \Stringable (throws on an empty list); the same, or null
ModelsetCursorOffset(int) / setWrap(int)Pin the cursor's row within the viewport; cap an item to N wrapped lines (0 = no cap)
FilterStateunfilteredNo filter active
FilterStatefilteringFilter function set and applied
FuzzyMatchscore(query, candidate)Smith-Waterman alignment score via the sugar-fuzzy SSOT (int, higher = better)
FuzzyMatchmatch(query, list<\Stringable>)Filter and rank items by score; returns list of [item, score] pairs
ScoringProfilecanonical() / 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
ItemvalueThe 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

Cursor navigation

Box-drawing gutter with cursor movement, repainted as a full frame after resetPreviousFrame().
Custom styling

Custom styling

Hand-written ★ Prefixer and ◉ Suffixer plugged into the same list.