SugarFocus
Focus-ring state machine — ordered focusable regions with Tab/Shift-Tab traversal, accent paint gated on isEnabled()
A tiny, dependency-free focus ring for full-window terminal UIs: an ordered set of focusable regions with a single focused member and wrap-around Tab/Shift-Tab traversal. It is the "which panel has focus" state for a TUI layout — register each focusable region (sidebar, content grid, filter bar…), map Tab to next() and Shift-Tab to previous(), and give the region current() returns an accent border when you render. The ring carries no rendering or key decoding of its own, so it composes with any sugar-core model without pulling in dependencies. Original SugarCraft component.
Install
composer require sugarcraft/sugar-focus
Quickstart
use SugarCraft\Focus\FocusRing;
$ring = FocusRing::of('sidebar', 'grid', 'filter'); // 'sidebar' is focused
$ring = $ring->next(); // → 'grid'
$ring = $ring->next(); // → 'filter'
$ring = $ring->next(); // → 'sidebar' (wraps)
$ring = $ring->previous(); // → 'filter' (wraps the other way)
$ring = $ring->focus('grid'); // jump straight to a region
$ring->current(); // 'grid'
$ring->isFocused('grid'); // true
Wire it into a sugar-core model's update(), then let each region style itself in view():
use SugarCraft\Core\KeyType;
use SugarCraft\Core\Msg\KeyMsg;
// …in update():
if ($msg instanceof KeyMsg && $msg->type === KeyType::Tab
&& !$msg->ctrl && !$msg->alt) {
$ring = $msg->shift ? $this->ring->previous() : $this->ring->next();
return [$this->withRing($ring), null];
}
// …and in view():
$style = $ring->isFocused('sidebar') && $ring->isEnabled('sidebar')
? $accentBorder : $plainBorder;
On the wire, Shift+Tab arrives as Tab with shift: true — sugar-core's InputReader decodes ESC [ Z (CSI-Z, the literal "Backtab" sequence) into that shape. The ring leg is gated on !$msg->ctrl && !$msg->alt, so Ctrl+Tab and Ctrl+Shift+Tab stay free for other bindings — but only on terminals that report modifiers (kitty keyboard negotiation or an xterm modifyOtherKeys-style decoder); on legacy/basic terminals Ctrl+Tab is byte-identical to bare Tab and moves the ring like a plain Tab would. The isEnabled() conjunct in the paint matters: focus can legally park on a disabled region, so isFocused() alone can accent a dimmed panel.
Behavior
current() is null, index() is -1).next() / previous() wrap past the ends and are no-ops with fewer than two enabled regions — with one exception: focus parked on a disabled region beats the no-op and moves to the nearest enabled survivor in that direction.disable() keeps a region registered but makes traversal skip it; enable() puts it back. Disabling the focused region does not move focus — the next next() / previous() carries it to the nearest enabled region in that direction, even a sole enabled survivor. focus() refuses a disabled id (no-op) so it cannot teleport past that wall — snapshot restore focuses the id before re-applying its disabled flag. A region dropped while disabled comes back enabled.IteratorAggregate, Countable and JsonSerializable: foreach walks every registered id, count($ring) counts them, json_encode($ring) gives {"ids":[…],"focused":…,"index":n,"disabled":[…]}, and FocusRing::restore() rebuilds the ring — preferring the focused id over the positional leg, an unknown focused id landing on the first region, clamping stale indices on legacy positional-only snapshots, and dropping unknown disabled entries. Legacy positional-only snapshots carry no disabled key, so everything comes back enabled.nextOf() / previousOf() answer where traversal would land from an id without moving focus; focusFirst() / focusLast() jump to the first / last enabled region; enabledIndex() is the focused region's ordinal among enabled ids (null while parked or empty).FocusRing and leaves the receiver untouched, so it slots into the immutable Model–Update–View pattern. No-op calls return the same instance, so $new === $old cheaply detects "nothing changed".isFocused() when drawing. Composes with any sugar-core model.Use it for
- Full-window TUI layouts — track which panel (sidebar, content grid, filter bar) currently owns keyboard focus.
- Tab / Shift-Tab traversal — wrap-around movement across an ordered set of regions, decoupled from key decoding.
- Accent-border styling — read
isFocused()together withisEnabled()inview()to highlight the focused region. - Immutable models — drop the ring into your Model state; every mutator returns a fresh instance.
Source & demos
- Source on GitHub
- Full README
- Test suite
- Runnable example
- Original SugarCraft design — no 1:1 Go counterpart.

API
| Class | Method | Description |
|---|---|---|
| FocusRing | new(): self | An empty ring with nothing registered or focused |
| FocusRing | of(string ...$ids): self | A ring of regions (duplicates dropped), focusing the first |
| FocusRing | ofStrict(string ...$ids): self | Like of(), but throws InvalidArgumentException on a duplicate id |
| FocusRing | restore(array $snapshot): self | Inverse of jsonSerialize() — clamps stale indices on legacy positional-only snapshots, unknown focused ids land on the first region, drops unknown disabled entries, and legacy positional-only snapshots carry no disabled key so everything comes back enabled; takes a decoded array (guard json_decode with is_array) |
| FocusRing | register(string $id): self | Add an enabled region to the end of the traversal order |
| FocusRing | unregister(string $id): self | Remove a region, preserving focus where possible |
| FocusRing | reorder(string ...$ids): self | Replace the traversal order, keeping focus on the current id when it survives |
| FocusRing | focus(string $id): self | Focus a specific registered, enabled region (no-op for unknown, disabled or already-focused ids) |
| FocusRing | next(): self | Tab traversal — move to the next enabled region (wrapping) |
| FocusRing | previous(): self | Shift-Tab traversal — move to the previous enabled region (wrapping) |
| FocusRing | nextOf(string $id): ?string / previousOf(string $id): ?string | Pure query: the id traversal would land on if focus sat on $id (focus not moved; null for unregistered ids) |
| FocusRing | focusFirst(): self / focusLast(): self | Jump to the first / last enabled region (no-op when none is enabled) |
| FocusRing | disable(string $id): self / enable(string $id): self | Exclude a region from / restore it to traversal; no-ops for unknown ids or ids already in that state |
| FocusRing | isEnabled(string $id): bool | Whether $id is registered and not disabled (false conflates unregistered with disabled — use has() to tell them apart) |
| FocusRing | enabledIds(): list<string> / disabledIds(): list<string> | Enabled / disabled ids in traversal order |
| FocusRing | enabledCount(): int / disabledCount(): int | Enabled / disabled region counts |
| FocusRing | current(): ?string | The focused region id, or null when empty |
| FocusRing | isFocused(string $id): bool | Whether $id is the focused region (paint with && isEnabled($id)) |
| FocusRing | has(string $id): bool | Whether $id is registered |
| FocusRing | index(): int | Focused position into all registered ids, or -1 when empty (enabledIndex() for the "k of n" enabled ordinal) |
| FocusRing | enabledIndex(): ?int | Focused region's 0-based ordinal into enabledIds(), or null when the ring is empty or focus is parked on a disabled region |
| FocusRing | ids(): list<string> | Registered region ids in traversal order |
| FocusRing | count(): int | Number of registered regions (Countable, so count($ring) works too) |
| FocusRing | isEmpty(): bool | Whether the ring has no regions |
| FocusRing | getIterator(): Traversable<int, string> | foreach support — every registered id (disabled ones included) in traversal order |
| FocusRing | jsonSerialize(): array | ['ids' => …, 'focused' => …, 'index' => …, 'disabled' => …] snapshot for json_encode(); restore() reads it back |