rdbms-playground/docs/adr/0051-context-state-aware-keybinding-strip.md

ADR-0051: Bottom keybinding strip — context- and state-aware

Status

Accepted 2026-06-13 (issue #27). Closes Gitea #27. All forks below were escalated to the user and user-chosen before any code was written; to be implemented test-first. Builds on ADR-0046 (nav focus), ADR-0003 (input modes), ADR-0049 (the #29 readline keys this strip now advertises), and ADR-0022 (the Tab-completion memo).

Context

The bottom status line (render_status_bar, ui.rs) mixed keystrokes with typed-command words: Enter submit · : advanced once · mode advanced switch · Ctrl-C quit. That is redundant — the hint panel already teaches help and Enter when the input is empty — and it is static apart from a three-way mode branch, so it never reflects what the user can actually do right now (navigating the sidebar, cycling a completion, browsing history, editing a line).

Issue #27: repurpose the line as a keybindings-only strip that is context-sensitive to nav focus and state-aware of the current transient interaction, and move mode discovery into the empty-input hint.

Decision

1. The strip is keybindings-only and state-selected

A single pure function status_bar_bindings(app) -> Vec<Binding> computes the strip from app state; render_status_bar is a thin renderer over it (so the binding sets are unit-testable without a Frame). history_cursor is private to App, so a small pub fn is_browsing_history(&self) -> bool accessor exposes the history-navigation predicate; mode / nav_focus / last_completion are already pub and effective_mode() is a pub method. The state is chosen by priority — first match wins:

Priority	State (predicate)	Strip
1	Sidebar focus (nav_focus in a sidebar)	Ctrl-O next pane · ↑↓/PgUp/PgDn scroll · Esc input
2	Completion memo live (last_completion.is_some())	Tab/Shift-Tab cycle · Esc cancel · Enter run
3	History navigation (history_cursor.is_some())	↑↓ browse · Esc clear · Enter run
4	Editing (Input focus, input non-empty)	Esc clear · Ctrl-A/E home/end · Ctrl-W del word · Enter run
5	Default (Input focus, input empty)	Ctrl-O sidebar · Tab complete · ↑ history · Enter run

Priority order matters: a completion memo or history navigation is a non-empty-input situation, so states 2 and 3 must precede state 4. The sidebar overlay occludes the input entirely (ADR-0046), so state 1 wins outright.

2. Mode discovery moves off the strip, into the empty-input hint

The typed-command advertisements (mode advanced / mode simple switch, the : one-shot) leave the strip — they are not keystrokes. Mode discovery moves to the empty-input hint (resolve_hint_lines's (None, None) arm), in simple mode only:

• Simple: … · \mode advanced` for SQL`
• Advanced (persistent): no pointer.

The pointer omits the verb "type" — the surrounding prompt already implies it (we don't say "type help" either). Advanced mode shows no pointer (user decision, post-trial): a user who switched into advanced mode knows how they got there, and help covers the way back — a "switch back" pointer only reads naturally in the moment right after switching, so it earns its space poorly.

The one-shot advanced state's old Backspace cancel one-shot label is subsumed by the editing state (the input is non-empty in one-shot; Esc-clear and Backspace both cancel it). No behaviour is lost — only the dedicated label.

3. Width: no drop machinery; a budget test instead

The longest strip (state 4, editing) is ≈ 65 display columns, which fits every supported width (90-col screencasts, 80-col terminals) with margin — so the priority-drop / abbreviation machinery considered would never trigger and is not built (user-confirmed). Ratatui's existing clip-at-edge is the trivial fallback for pathologically narrow (< 65-col) terminals. Instead, a width-budget unit test pins the longest rendered strip within an 80-col budget, keeping the strip lean by construction — a future over-long strip fails the test rather than silently clipping in a cast.

Forks (all user-chosen)

• Editing state — yes: when the input has text, surface the #29 readline keys (Esc-clear, Ctrl-A/E, Ctrl-W); the strip stays lean (nav/complete/history) when empty. (vs not advertising the #29 keys.)
• Ctrl-C quit — omitted from the strip (vs always shown): quit is a near-universal convention; omitting it keeps the strips lean and matches the issue's sketch.
• Width — budget test, no drop logic (vs graceful priority-drop / abbreviation): the strips fit at supported widths, so the machinery would be dead weight (user's own observation).

Consequences

• The strip now teaches the keys for the current situation; learners see Tab/Shift-Tab cycle exactly while cycling, the editing keys exactly while editing, etc.
• The #29 readline keys (ADR-0049) gain their on-screen advertisement, closing that ADR's deferred item.
• 15 existing full-panel insta snapshots churn (the bottom line — and, on empty-input views, the hint pointer — changes in every one, including the rebuild-confirm modal view, whose modal box is itself unchanged); each diff was reviewed, not blind-accepted.
• requirements.md is unaffected (an ADR-tracked UI refinement); the change is cross-referenced from the commit + this ADR.

Tests

• Tier-1 (ui.rs unit): status_bar_bindings returns the expected key set for each of the five states (sidebar, completion-live, history-nav, editing, default) — the completion/history states driven through real key events (update) so the predicate transitions are exercised, the others by setting App fields; plus the width-budget assertion across states. (Per-state coverage is these unit tests, not snapshots — a one-line strip is asserted more precisely by its exact key list than by a full-panel snapshot.)
• Tier-1: the empty-input hint appends the correct mode pointer in Simple vs Advanced, and does not append it when an ambient hint is showing (non-empty input).
• Tier-3 (walking_skeleton): the old status_bar_lists_quit_and_ submit_in_all_modes (which asserted the pre-ADR strip) is rewritten + renamed to assert the keystroke-only, state-aware strip end-to-end through the real render path (default → editing transition).
• Tier-2 (insta): the 15 full-panel snapshots re-accepted (each diff reviewed — strip line and/or hint pointer only).

Out of scope

• Modal-aware strip. While a modal is open (load picker, rebuild / undo confirm) it owns the keyboard and carries its own in-box key hints; the bottom strip under a modal computes from input state exactly as it does today (modals render over the status bar). This issue does not redesign the modal case — pre-existing behaviour, unchanged and not worsened.
• A persistent/togglable help overlay listing all keys (the strip is a contextual subset, not a cheatsheet).
• Per-key colour theming beyond the existing key/label/separator styles.
• Localisation of the new label strings beyond adding catalog entries.
• The remaining I1b kill keys' (Ctrl-K/Ctrl-U) advertisement — the editing strip shows the highest-value subset (Esc/Ctrl-A/E/Ctrl-W) to stay within the width budget; Ctrl-K/U remain unadvertised muscle memory.