SugarBits

composer require sugarcraft/sugar-bits

Components

Vim mode

Msg routing cheat-sheet

Quickstart — TextInput with autocomplete

use SugarCraft\Bits\TextInput\TextInput;
use SugarCraft\Core\{Cmd, Model, Msg, Program};
use SugarCraft\Core\Msg\KeyMsg;
use SugarCraft\Core\KeyType;
final class Search implements Model
{
 public function __construct(public readonly TextInput $ti) {}
 public function init(): ?\Closure { return null; }
 public function update(Msg $msg): array
 {
 if ($msg instanceof KeyMsg && $msg->type === KeyType::Enter) {
 return [$this, Cmd::quit()];
 }
 if ($msg instanceof KeyMsg && $msg->type === KeyType::Tab) {
 return [new self($this->ti->acceptSuggestion()), null];
 }
 [$ti, $cmd] = $this->ti->update($msg);
 return [new self($ti), $cmd];
 }
 public function view(): string
 {
 $body = $this->ti->view();
 if (($s = $this->ti->currentSuggestion()) !== null) {
 $body .= "\n → $s";
 }
 return $body;
 }
}
[$ti, $cmd] = TextInput::new()
 ->withSuggestions(['apple', 'apricot', 'banana', 'cherry'])
 ->showSuggestions()
 ->withValidator(fn(string $v) => strlen($v) >= 2 ? null : 'too short')
 ->focus();
(new Program(new Search($ti)))->run();

Quickstart — animated progress bar

use SugarCraft\Bits\Progress\AnimatedProgress;
$bar = AnimatedProgress::new()
 ->withWidth(40)
 ->withDefaultGradient();
[$bar, $cmd] = $bar->setPercent(0.75);
// dispatch $cmd via the Program — ticks re-fire from inside update()
// until the bar settles within 5e-4 of the target.

Quickstart — TextInput with placeholder styling and prefix/suffix

use SugarCraft\Bits\TextInput\TextInput;
use SugarCraft\Sprinkles\Style;
use SugarCraft\Core\Util\Color;
$ti = TextInput::new()
 ->withPlaceholder('Enter command...')
 ->withPlaceholderStyle(Style::new()->faint()) // default: dim
 ->withPrefix('$ ') // fixed prefix
 ->withSuffix(' <'); // fixed suffix
echo $ti->view();
// $ Enter command... <

TextInput — ValidateOn and restrict

ValidateOn timing control

use SugarCraft\Bits\TextInput\{TextInput, ValidateOn};
$ti = TextInput::new()
 ->withValidateOn(ValidateOn::Blur); // validate when focus leaves

Keystroke filter (restrict)

use SugarCraft\Bits\TextInput\TextInput;
// Accept only digits
$numeric = TextInput::new()->withRestrict('[0-9]');
// Accept alphanumeric only
$alphanum = TextInput::new()->withRestrict('[a-zA-Z0-9]');

TextInput notable builders

Table — multi-column sort

use SugarCraft\Bits\Table\{Table, SortDirection, SortState};
// Primary sort by Name ascending
$t = $table->withSort('Name');
// Tiebreaker: Age descending
$t = $table->thenSortBy('Age', SortDirection::Desc);
// Reset to insertion order
$t = $table->clearSort();
// Inspect current sort criteria
$state = $t->getSortState(); // SortState
foreach ($state->criteria as [$colIndex, $dir]) {
 // $colIndex is an int, $dir is SortDirection::Asc or SortDirection::Desc
}

SortDirection enum

SortState DTO

Table sort builders

Table — filtering

use SugarCraft\Bits\Table\Table;
// Enable the filter feature (opt-in)
$t = $table->withFilterable(true);
// Set a query string — default: case-insensitive substring match across all visible columns
$t = $table->withFilter('foo');
// Custom filter: receives a row (list<string>), returns true to keep
$t = $table->withFilterPredicate(fn(array $row): bool =>
 str_contains(strtolower(implode("\t", $row)), 'foo')
);
// Inspect current filter state
$isFilterable = $t->getFilterable(); // bool
$query = $t->getFilter(); // string
$predicate = $t->getFilterPredicate(); // ?Closure(list<string>): bool

Table filter builders

Table — pagination

use SugarCraft\Bits\Table\Table;
// Enable pagination: 10 rows per page
$t = $table->withPageSize(10);
// Navigate pages
$t = $t->withPage(1); // zero-based — go to page 1 (second page)
$t = $t->nextPage();
$t = $t->prevPage();
$t = $t->pageFirst();
$t = $t->pageLast();
// Inspect pagination state
$pageSize = $t->getPageSize(); // int — rows per page (0 = pagination disabled)
$current = $t->getCurrentPage(); // int — zero-based current page
$totalPages = $t->getTotalPages(); // int — 1 when pagination is disabled
// Wire a Paginator to the table for UI rendering
$paginator = $t->getPaginator(); // Paginator instance

Table pagination builders

Snapshot tests

UPDATE_GOLDENS=1 vendor/bin/phpunit

Test

cd sugar-bits && composer install && vendor/bin/phpunit

Demos

Cursor

File picker

Help

Item list

Paginator

Progress

Spinners

Stopwatch

Tabs

Table

Text area

Text input

Text input (enhanced)

Timer

Tree

Viewport

Related