SugarCrumbs

PHP port of KevM/bubbleo — NavStack (navigation stack) and Breadcrumb components for terminal UIs.

Features

• NavStack — hierarchical navigation state with push/pop/peek operations
• Breadcrumb renderer — renders the current navigation path as a clickable-looking breadcrumb string
• Shell — combines NavStack + Breadcrumb into a single component
• Pure renderer — breadcrumb output is just strings; works with any TUI framework
• No external dependencies — pure PHP 8.1+

Install

composer require sugarcraft/sugar-crumbs

NavStack Quick Start

use SugarCraft\Crumbs\NavStack;

$stack = new NavStack();

// Push navigation items (each has a title + optional data)
$stack->push('Home');
$stack->push('Settings');
$stack->push('Display');

// Current item
echo $stack->current()->title;   // "Display"
echo $stack->depth();            // 3

// Pop back
$popped = $stack->pop();
echo $popped->title;             // "Display"
echo $stack->current()->title;   // "Settings"

Breadcrumb Rendering

use SugarCraft\Crumbs\Breadcrumb;

$bc = new Breadcrumb();
$bc->setSeparator(' › ');        // default " › "
$bc->setMaxWidth(60);            // truncate if needed

// Render from NavStack
$stack = new NavStack();
$stack->push('Home');
$stack->push('Settings');
$stack->push('Display');

echo $bc->render($stack);  // "Home › Settings › Display"

Click-Region Tracking

Attach a self-contained Scanner from sugarcraft/candy-mouse for mouse-click zone routing:

use SugarCraft\Crumbs\Breadcrumb;
use SugarCraft\Mouse\Scanner;

$bc = (new Breadcrumb())->withScanner(Scanner::new());

$output = $bc->render($stack);
// Each crumb is wrapped in a named zone marker: "crumb-0", "crumb-1", …

$bc->scan($output);
$zone = $bc->hit($col, $row); // returns Zone for clicked crumb-N or null

if ($zone !== null && \preg_match('/crumb-(\d+)/', $zone->id, $m)) {
    $index = (int) $m[1];
    // route click on crumb-$index to the appropriate handler
}

Shared foundations

Mouse hit-testing is self-contained via candy-mouse. The Scanner class handles zone registration and hit testing locally — no external zone-manager wiring is needed.

License

MIT