feat(tui): standardize picker navigation keys (#22347)

## Why

Picker-style UI in the TUI has accumulated a mix of hardcoded navigation
keys. Some lists supported page movement, some did not; some accepted
Vim-like keys, while others only accepted arrows; and tabbed or
horizontally adjustable pickers had no shared keymap action for
left/right movement.

This PR makes picker/list navigation consistent and configurable so
users can rely on the same defaults across the TUI.

## What Changed

- Adds shared list keymap actions for:
  - vertical movement: `move_up`, `move_down`
  - horizontal movement: `move_left`, `move_right`
  - paging and jumps: `page_up`, `page_down`, `jump_top`, `jump_bottom`
- Adds defaults:
- Up/down: arrows, `Ctrl+P/N`, `Ctrl+K/J`, and plain `k/j` where text
input is not active
  - Page up/down: `PageUp/PageDown` and `Ctrl+B/F`
  - First/last: `Home/End`
  - Left/right: `Left/Right` and `Ctrl+H/L`
- Wires the shared list keymap through picker and list surfaces
including session resume, multi-select, tabbed selection lists,
settings-style lists, app-link selection, MCP elicitation,
request-user-input, and the OSS selection wizard.
- Keeps search behavior intact by reserving printable characters for
query text in searchable pickers.
- Updates keymap setup actions, config schema, snapshots, and focused
coverage for the new list actions.

## How to Test

1. Start Codex from this branch and open the session picker, for example
with an existing session history.
2. In the session list, verify that `Ctrl+J/K` moves the selection
down/up.
3. Verify that `Ctrl+F/B` pages down/up and `Home/End` jumps to the
first/last visible session.
4. Type printable search text such as `j` or `k` and confirm it updates
the query instead of navigating.
5. Focus a picker control that changes values horizontally, such as a
session picker toolbar control, and verify `Ctrl+H/L` changes the
focused value like left/right arrows.

Targeted tests run:

- `cargo test -p codex-tui keymap::tests::`
- `cargo test -p codex-tui keymap_setup::tests::`
- `cargo test -p codex-tui horizontal_list_keys`
- `cargo test -p codex-tui page_and_jump_navigation_use_list_keymap`
- `cargo test -p codex-tui ctrl_h_l_move_provider_selection`
- `cargo test -p codex-tui scroll_state::tests`
- `cargo test -p codex-tui
switching_tabs_changes_visible_items_and_clears_search`
- `cargo test -p codex-tui toggle_sort_key_reloads_with_new_sort`

Also ran `just write-config-schema`, `just fmt`, `just fix -p
codex-tui`, `just argument-comment-lint`, and `git diff --check`.

Note: `cargo test -p codex-tui` was attempted and still aborts in the
pre-existing
`tests::fork_last_filters_latest_session_by_cwd_unless_show_all` stack
overflow, which is unrelated to this branch.
This commit is contained in:
Felipe Coury authored and GitHub committed 2026-05-13 15:33:27 +00:00
1 parent 441c2f818f
commit 3d517fbd00
37 files changed
+1635 -426

No files matched your search

@@ -29,6 +29,8 @@ use crate::app_event_sender::AppEventSender;
use crate::hooks_rpc::HookTrustUpdate;
use crate::hooks_rpc::hook_needs_review;
use crate::key_hint;
use crate::key_hint::KeyBindingListExt;
use crate::keymap::ListKeymap;
use crate::line_truncation::truncate_line_with_ellipsis_if_overflow;
use crate::render::renderable::Renderable;
use crate::status::format_directory_display;
@@ -50,6 +52,7 @@ pub(crate) struct HooksBrowserView {
state: ScrollState,
complete: bool,
app_event_tx: AppEventSender,
keymap: ListKeymap,
}
impl HooksBrowserView {
@@ -68,10 +71,15 @@ impl HooksBrowserView {
errors,
},
app_event_tx,
crate::keymap::RuntimeKeymap::defaults().list,
)
}
pub(crate) fn from_entry(mut entry: HooksListEntry, app_event_tx: AppEventSender) -> Self {
pub(crate) fn from_entry(
mut entry: HooksListEntry,
app_event_tx: AppEventSender,
keymap: ListKeymap,
) -> Self {
entry.hooks.sort_by_key(|hook| hook.display_order);
let mut view = Self {
entry,
@@ -79,6 +87,7 @@ impl HooksBrowserView {
state: ScrollState::new(),
complete: false,
app_event_tx,
keymap,
};
if view.page_len() > 0 {
view.state.selected_idx = Some(
@@ -165,6 +174,26 @@ impl HooksBrowserView {
self.state.ensure_visible(len, self.max_visible_rows());
}
fn page_up(&mut self) {
let len = self.page_len();
self.state.page_up_clamped(len, self.max_visible_rows());
}
fn page_down(&mut self) {
let len = self.page_len();
self.state.page_down_clamped(len, self.max_visible_rows());
}
fn jump_top(&mut self) {
let len = self.page_len();
self.state.jump_top(len, self.max_visible_rows());
}
fn jump_bottom(&mut self) {
let len = self.page_len();
self.state.jump_bottom(len, self.max_visible_rows());
}
fn page_len(&self) -> usize {
match self.page {
HooksBrowserPage::Events => codex_protocol::protocol::HookEventName::iter().count(),
@@ -533,33 +562,18 @@ impl HooksBrowserView {
impl BottomPaneView for HooksBrowserView {
fn handle_key_event(&mut self, key_event: KeyEvent) {
match key_event {
KeyEvent {
code: KeyCode::Up, ..
_ if self.keymap.move_up.is_pressed(key_event) => self.move_up(),
_ if self.keymap.move_down.is_pressed(key_event) => self.move_down(),
_ if self.keymap.page_up.is_pressed(key_event) => self.page_up(),
_ if self.keymap.page_down.is_pressed(key_event) => self.page_down(),
_ if self.keymap.jump_top.is_pressed(key_event) => self.jump_top(),
_ if self.keymap.jump_bottom.is_pressed(key_event) => self.jump_bottom(),
_ if self.keymap.accept.is_pressed(key_event)
&& self.page == HooksBrowserPage::Events =>
{
self.open_selected_event()
}
| KeyEvent {
code: KeyCode::Char('p'),
modifiers: KeyModifiers::CONTROL,
..
} => self.move_up(),
KeyEvent {
code: KeyCode::Down,
..
}
| KeyEvent {
code: KeyCode::Char('n'),
modifiers: KeyModifiers::CONTROL,
..
} => self.move_down(),
KeyEvent {
code: KeyCode::Enter,
modifiers: KeyModifiers::NONE,
..
} if self.page == HooksBrowserPage::Events => self.open_selected_event(),
KeyEvent {
code: KeyCode::Enter,
modifiers: KeyModifiers::NONE,
..
} => {
_ if self.keymap.accept.is_pressed(key_event) => {
if let HooksBrowserPage::Handlers(event_name) = self.page {
self.toggle_selected_hook(event_name);
}
@@ -581,9 +595,7 @@ impl BottomPaneView for HooksBrowserView {
HooksBrowserPage::Events => self.trust_all_hooks(),
HooksBrowserPage::Handlers(event_name) => self.trust_selected_hook(event_name),
},
KeyEvent {
code: KeyCode::Esc, ..
} => match self.page {
_ if self.keymap.cancel.is_pressed(key_event) => match self.page {
HooksBrowserPage::Events => self.close(),
HooksBrowserPage::Handlers(_) => self.return_to_events(),
},