CandyLister
Tree / list view with box-drawing prefixes + cursor nav
Tree and flat list views with customizable box-drawing prefixes, cursor navigation, and word-wrap. Composeable with any bubbletea model.
Install
composer require sugarcraft/candy-listerQuickstart
use SugarCraft\Lister\{Model, StringItem, DefaultPrefixer};
// Fluent setters return NEW Models - rebind; instances are immutable.
$model = Model::new()->setWidth(80)->setHeight(24);
$model = $model->addItem(new StringItem('src/main.php'));
$model = $model->addItem(new StringItem('src/Model.php'));
$model = $model->addItem(new StringItem('tests/MainTest.php'));
$model = $model->setPrefixer(new DefaultPrefixer());
echo $model->view();
// Renders the list with ╭ ├ │ prefixes and > cursor markerWhat's in the box
Box-drawing prefixesCustomizable prefixers per depth level — lines, bullets, arrows.
Cursor navigationUp / Down / Home / End movement with viewport tracking.
Word-wrapAuto-wrap long items to terminal width.
Filter state machinewithFilterFn() / withoutFilter() with FilterState enum (unfiltered / filtering).
Fuzzy matchingSmith-Waterman local alignment scorer — scores and ranks candidates.
Source & demos
- Source on GitHub
- Full README
- Runnable examples
- Port of treilik/bubblelister (Go upstream)
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 |
| 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 list as ANSI string |
| Model | filterState() | Current FilterState (unfiltered / filtering) |
| FilterState | unfiltered | No filter active |
| FilterState | filtering | Filter function set and applied |
| FuzzyMatch | score(query, candidate) | Smith-Waterman alignment score (int, higher = better) |
| FuzzyMatch | match(query, list<\Stringable>) | Filter and rank items by score; returns list of [item, score] pairs |
| Item | value | The underlying \Stringable |
| StringItem | new(string) | Wrap a plain string as a list item |
