All 42 libraries

SugarNavstack

Navigation breadcrumbs for terminal UIs

inspired by KevM/bubbleo navigationbreadcrumbrouting

SugarNavstack code coverage

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

Try the quickstart →

API

ClassMethodDescription
NavStacknew()Create navigation stack
NavStackpush(string $title, mixed $data = null): selfPush a navigation item (mutates; returns the stack). Refuses titles empty after trimming and sanitizing, and growth past MAX_STACK_DEPTH.
NavStackpop(): ?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
NavStacksafeTitle(string): stringPublic static facade over the display sweep — sanitize untrusted titles before pushing them
NavStackview(string $separator = ' › '): stringPlain-text crumb trail; titles sanitized and the separator control-gated (CR/LF and terminal escapes throw; zone sentinels stripped; empty is legal here)
NavStackviewHtml(?callable $href = null, string $label = 'Breadcrumb', ?array $allowSchemes = null): stringAccessible 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.
NavStackfiltered(string $term): selfNew 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.
ShellwithDirectory(string $cwd): self / withBreadcrumb(Breadcrumb)New Shell per navigation mutation (derived Shells get their own breadcrumb); withBreadcrumb opts into deliberate sharing
Urlderive(NavStack): string / deriveTo(NavStack, int $index): stringPercent-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
BreadcrumbwithScanner(?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.
Breadcrumbscan(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
BreadcrumbsetSeparator(string)Set separator between crumbs
BreadcrumbsetMaxWidth(int)Cap trail width; oldest crumbs elide first. 0 (default) disables the cap; negative throws.
BreadcrumbsetTruncator(string $ellipsis)Glyph marking elided crumbs (default …); forged zone-sentinel bytes are stripped, multi-line throws
BreadcrumbsetItemRenderer(\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.
BreadcrumbsetEmptyLabel(string)Depth-0 opt-in: paints a label through the same width pipeline; never a clickable zone
BreadcrumbsetFocusedIndex(?int) / focusedIndex(): ?intHands the item renderer a third bool $focused; focus is intent — off-visible indices clamp to null and the accessor reports what the render reflected
BreadcrumbelisionSpan(): ?array[start, end, row] of the painted … marker after scan(), or null; treat hits there as an expansion gesture, not navigation
BreadcrumbsetZonePrefix(string)Rename crumb- zone ids (alphabet [A-Za-z0-9._:-]); keeps merged dispatch tables of independent widgets unambiguous
BreadcrumbvisibleIndices(): arrayStack indices that survived the last render's truncation — the map from display position to zone id
BreadcrumbrenderTitles(array $titles): stringRender a pre-trimmed title list (host-owned filtering) instead of a NavStack; each title is byte-capped like a constructed item
Breadcrumbscanner(): ?ScannerRead back the owned (copied-in) sugar-mouse scanner, or null when click zones are off
Breadcrumbrender(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.

Terminal recording: a scripted back-navigation walk — Home, Settings, and Display pushed, then popped one by one while the trail shrinks.

Push / pop / back

NavStack push / pop / back through nested screens.
Terminal recording: the Home Settings Display trail rendered plain, with a custom greater-than separator, and elided to a width-20 cap.

Basic crumb trail

Render a Home › Settings › Display crumb trail — default and custom separators, and width-capped left-elision.