SugarNavstack
Navigation breadcrumbs for terminal UIs
Push / pop navigation items to build breadcrumbs. Track a stack of visited locations — useful for file explorers, menu trees, and cwd-tracked directory trails. Rendered trails carry click zones (sugar-mouse) and an accessible HTML shape (aria-label nav + aria-current).
Install
composer require sugarcraft/sugar-navstack
Packagist currently serves this package from dev-master only (no tagged release yet): require it with a root minimum-stability: "dev" plus an exact sugarcraft/sugar-navstack: "dev-master".
Quickstart
use SugarCraft\NavStack\NavStack;
// NavStack is a mutable stack: push() returns the same stack for chaining.
$nav = NavStack::new()
->push('Home', '/') // title, then any payload
->push('Settings', '/settings')
->push('Display', '/settings/display');
echo $nav->view(); // Home › Settings › Display
echo $nav->view(' / '); // Home / Settings / Display
$top = $nav->pop(); // NavigationItem: title 'Display', data '/settings/display'
$nav->depth(); // 2
What's in the box
NavStackPush / pop navigation stack (mutable, chainable push) with depth, parent and truncation helpers.
Directory stacks (Shell)Explicit cwd-tracked trails — your host detects a directory change and calls withDirectory() (pushDirectory() remains as a deprecated forwarder); nothing auto-pushes, and `.`/`..` follow the documented no-downward-walk rule.
FilterUnicode case-folded substring filtering over titles and payload data (arrays matched by value up to 64 nesting levels — deeper payloads throw).
Accessible HTMLviewHtml() emits the recommended nav[aria-label] > ol shape with aria-current="page" on the live crumb — screen-reader-ready without host markup work.
Breadcrumb rendererTheme-aware plain-text rendering with width-capped left-elision, custom separators/ellipses, per-item renderer closures, and stack-indexed mouse zones that survive truncation.
Source & demos
- Source on GitHub
- Full README
- Runnable examples
- Originally inspired by KevM/bubbleo (Go); SugarCraft is developed as a native PHP project.
API
| Class | Method | Description |
|---|---|---|
| NavStack | new() | Create navigation stack |
| NavStack | push(string $title, mixed $data = null): self | Push a navigation item (mutates; returns the stack). Refuses titles empty after trimming and sanitizing, and growth past MAX_STACK_DEPTH. |
| NavStack | pop(): ?NavigationItem / popTo(int) / popToRoot() / current() / parent() / depth() | Pop and inspect the stack; generation(): int stamps the mutation counter so cross-generation breadcrumb dispatch is refused |
| NavStack | safeTitle(string): string | Public static facade over the display sweep — sanitize untrusted titles before pushing them |
| NavStack | view(string $separator = ' › '): string | Plain-text crumb trail; titles sanitized and the separator control-gated (CR/LF and terminal escapes throw; zone sentinels stripped; empty is legal here) |
| NavStack | viewHtml(?callable $href = null, string $label = 'Breadcrumb', ?array $allowSchemes = null): string | Accessible HTML: nav[aria-label="…"] around an ol, last item aria-current="page". $href receives (item, stack index); a string answer links that crumb, null leaves it plain text (an unlinked ancestor). $allowSchemes gates returned URLs by scheme (case-insensitive; '/' admits scheme-less paths) — rejected URLs render as plain text. $label names the landmark via aria-label. |
| NavStack | filtered(string $term): self | New stack with items whose title or scalar/Stringable payload (array values up to 64 levels) contains $term — Unicode (mb_stripos) case fold; result indices renumber. filter() is a deprecated forwarder. |
| Shell | withDirectory(string $cwd): self / withBreadcrumb(Breadcrumb) | New Shell per navigation mutation (derived Shells get their own breadcrumb); withBreadcrumb opts into deliberate sharing |
| Url | derive(NavStack): string / deriveTo(NavStack, int $index): string | Percent-encoded path from the trail (sanitize-then-encode); deriveTo() yields the ancestor prefix up to and including $index — every prefix is a byte-identical segment slice of the full path |
| NavigationItem | __construct(string $title, mixed $data = null) / title() | One stack entry; the constructor refuses titles empty after trim+sanitize and over 64 KiB raw |
| Breadcrumb | withScanner(?Scanner) | Attach mouse-click zones per crumb (sugar-mouse Scanner; copied in, never aliased — read it back via scanner()). Zone ids carry the STACK index, so click routing survives truncation. |
| Breadcrumb | scan(string $rendered, int $viewportWidth, int $row = 1) / hit(col, row) / hitItem(stack, col, row) | Feed the rendered string to the owned scanner, clamped to the REQUIRED viewport width (for a row other than 1), then resolve which crumb a terminal cell falls in — hitItem() is the one-call dispatcher returning the clicked NavigationItem; failure shapes follow the scan()/hit() rule table |
| Breadcrumb | setSeparator(string) | Set separator between crumbs |
| Breadcrumb | setMaxWidth(int) | Cap trail width; oldest crumbs elide first. 0 (default) disables the cap; negative throws. |
| Breadcrumb | setTruncator(string $ellipsis) | Glyph marking elided crumbs (default …); forged zone-sentinel bytes are stripped, multi-line throws |
| Breadcrumb | setItemRenderer(\Closure $fn) | Per-item custom rendering fn(item, index, focused): ?string — null falls back to the default; returned strings emit RAW. A smoke call at assignment refuses non-string answers; contract errors otherwise throw at render(). 2-arg closures keep working. |
| Breadcrumb | setEmptyLabel(string) | Depth-0 opt-in: paints a label through the same width pipeline; never a clickable zone |
| Breadcrumb | setFocusedIndex(?int) / focusedIndex(): ?int | Hands the item renderer a third bool $focused; focus is intent — off-visible indices clamp to null and the accessor reports what the render reflected |
| Breadcrumb | elisionSpan(): ?array | [start, end, row] of the painted … marker after scan(), or null; treat hits there as an expansion gesture, not navigation |
| Breadcrumb | setZonePrefix(string) | Rename crumb- zone ids (alphabet [A-Za-z0-9._:-]); keeps merged dispatch tables of independent widgets unambiguous |
| Breadcrumb | visibleIndices(): array | Stack indices that survived the last render's truncation — the map from display position to zone id |
| Breadcrumb | renderTitles(array $titles): string | Render a pre-trimmed title list (host-owned filtering) instead of a NavStack; each title is byte-capped like a constructed item |
| Breadcrumb | scanner(): ?Scanner | Read back the owned (copied-in) sugar-mouse scanner, or null when click zones are off |
| Breadcrumb | render(NavStack) | Render NavStack as breadcrumb string |
Demos.
VHS-recorded GIFs of every example shipped with the library. Regenerated automatically on every push that touches the source.
Push / pop / back
NavStack push / pop / back through nested screens.
Basic crumb trail
Render aHome › Settings › Display crumb trail — default and custom separators, and width-capped left-elision.