TUI Stage 4.5a: focus system (tree, manager, traversal, key routing) - #36
Merged
Conversation
Specs the focus tree, FocusManager, Focus/FocusScope widgets, traversal policies, and key-event routing — the first half of the interactivity stage. The Actions/Intents/Shortcuts layer is deferred to Stage 4.5b. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
An interactive demo exercising the whole focus system — Tab/arrow traversal, per-card onKeyEvent handling, focus-chain bubbling, and hasFocus-driven highlighting. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds a focus system to the Flutter-style terminal-UI framework in
app/lib/src/tui/— the first half of the "interactivity" stage, and the prerequisite for a real interactive TUI app.FocusNode/FocusScopeNoderunning parallel to the element tree; a hand-rolled minimal listenable (noChangeNotifier, preserving the zero-pub-dependency rule).FocusManager— owned byTuiBinding; holds the primary focus, applies pending focus changes at the top of each frame (beforebuildScope), and routes key events down the focus chain.Focus/FocusScopewidgets — own/adopt focus nodes, attach them via a_FocusMarkerInheritedWidget, and re-exposehasFocusso descendants rebuild on focus change through the existing Stage 4 machinery.ReadingOrderTraversalPolicy(Tab order by post-layout geometry),DirectionalFocusTraversalPolicy(arrow keys),FocusTraversalGroup.runApppumpsterminal.keysintoFocusManager.handleKeyEvent; unhandled Tab/Shift-Tab/arrows hit a built-in traversal fallback. That fallback is the deliberate seam Stage 4.5b will replace with declarativeShortcuts/Actions.RenderObject.globalOffset— a read-only geometry helper for traversal.focus_demo.dart(2x2 grid + nestedFocusScope) andfocus_playground.dart(2x3 counter-card grid exercising traversal, per-cardonKeyEvent, focus-chain bubbling).Design spec:
docs/superpowers/specs/2026-05-16-tui-stage4.5a-focus-system-design.mdImplementation plan:
docs/superpowers/plans/2026-05-16-tui-stage4.5a-focus-system.mdBuilt TDD-style in 13 reviewed increments. The
Actions/Intents/Shortcutsdeclarative key-binding layer is intentionally deferred to Stage 4.5b.Test plan
cd app && flutter test— 363/363 pass (5 new focus suites +global_offset_test.dart, no regressions)cd app && flutter analyze— cleandart tool/prepare_submit.dart— no diffcd app && dart run examples/tui/focus_playground.dart— Tab/Shift-Tab cycle focus, arrows navigate the grid,+/-/spaceadjust the focused card,qquits cleanlycd app && dart run examples/tui/focus_demo.dart🤖 Generated with Claude Code