From f37e16fa7de4cbd688a8bad06282d5e054954215 Mon Sep 17 00:00:00 2001 From: Dandaedre Date: Thu, 15 Oct 2026 23:00:29 +0200 Subject: [PATCH] feat: add detailed keyboard help Open orientation-aware keyboard help with h or ?, move fader hiding to Shift+H, and update footer reminders and documentation. Tests: cargo fmt --all -- --check; cargo check --workspace --all-targets --all-features; cargo test --workspace --all-targets --all-features; cargo test --workspace --doc --all-features; cargo clippy --workspace --all-targets --all-features -- -D warnings; cargo build --workspace --release --all-features; cargo check --workspace; cargo check --workspace --no-default-features; cargo check -p midi --no-default-features --features midir; cargo check -p volume_lib --no-default-features --features pulse --- README.md | 5 ++- architecture.md | 3 ++ task.md | 3 +- tui/src/lib.rs | 100 +++++++++++++++++++++++++++++++++++++++++++++--- 4 files changed, 103 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index 4352614..ffeb3ac 100644 --- a/README.md +++ b/README.md @@ -57,8 +57,9 @@ The mixer arrow keys follow its orientation. In Vertical mode, use Up/Down to select a configured fader or separator and Left/Right to change its volume. In Horizontal mode, use Left/Right to select and Up/Down to change volume. J/K remain selection aliases in either mode, and Shift plus the selection arrows -reorders an entry. M toggles mute, T cycles the profile's theme draft, and Q -opens the quit confirmation. Escape cancels the active editor or dialog and +reorders an entry. M toggles mute, Shift+H hides the selected fader, and `h` or +`?` opens detailed keyboard help. T cycles the profile's theme draft, and Q opens +the quit confirmation. Escape cancels the active editor or dialog and does not quit from the main screen. Pass `--theme dracula`, `nord`, `gruvbox-dark`, `catppuccin-mocha`, or `solarized-dark` to choose an initial session theme. Save from Config to persist a theme selected with T. Offline diff --git a/architecture.md b/architecture.md index a57ad1a..37c6792 100644 --- a/architecture.md +++ b/architecture.md @@ -442,6 +442,9 @@ with Up/Down and changes volume with Left/Right, while horizontal mode selects with Left/Right and changes volume with Up/Down. Holding Shift reorders entries along the active selection axis; J/K remain orientation-independent selection aliases. +Lowercase `h` and `?` open an orientation-aware keyboard-help popup with mixer, +configuration, and global controls. Hiding is deliberately assigned to Shift+H +so the common help key does not perform a destructive presentation edit. The selected main-list entry can be moved directly, and separators can be added, renamed, moved, or removed. Adding or renaming a separator uses a diff --git a/task.md b/task.md index 5c59c2c..cf54b61 100644 --- a/task.md +++ b/task.md @@ -420,7 +420,8 @@ Dependencies: M8, M2, M1. state. Hidden restoration uses one settings action that opens a popup listing every hidden fader rather than expanding the settings page with one row per fader. MIDI-device status rows are selectable and open a details popup where - the profile's default-controller assignment can be set or cleared. + the profile's default-controller assignment can be set or cleared. `h` and `?` + open detailed keyboard help; Shift+H hides the selected mixer fader. Keep this item open until any remaining required object-creation workflow is available from the mixer and its small-terminal acceptance passes. diff --git a/tui/src/lib.rs b/tui/src/lib.rs index d82c092..fca4165 100644 --- a/tui/src/lib.rs +++ b/tui/src/lib.rs @@ -814,6 +814,7 @@ pub struct LiveTui { theme_override: bool, exit: bool, quit_confirmation: bool, + show_help: bool, client_error: Option, tab: Tab, editor: Option, @@ -995,6 +996,7 @@ impl LiveTui { theme_override, exit: false, quit_confirmation: false, + show_help: false, client_error: None, tab: Tab::Mixer, editor: None, @@ -1119,6 +1121,12 @@ impl LiveTui { } return; } + if self.show_help { + if matches!(key_event.code, KeyCode::Esc | KeyCode::Char('h' | '?')) { + self.show_help = false; + } + return; + } if self.snapshot.configuration.learning.is_some() { if matches!(key_event.code, KeyCode::Esc | KeyCode::Char('c')) { self.cancel_midi_learn(); @@ -1154,6 +1162,7 @@ impl LiveTui { return; } match key_event.code { + KeyCode::Char('h' | '?') => self.show_help = true, KeyCode::Char('t') => self.change_theme(self.theme.next()), KeyCode::Tab => { self.tab = match self.tab { @@ -1196,6 +1205,7 @@ impl LiveTui { self.snapshot.configuration.mixer_orientation == MixerOrientation::Horizontal; if key_event.modifiers.contains(KeyModifiers::SHIFT) { match (horizontal, key_event.code) { + (_, KeyCode::Char('H' | 'h')) => self.toggle_selected_visibility(), (true, KeyCode::Left) | (false, KeyCode::Up) => { self.move_selected_layout(-1); } @@ -1237,7 +1247,7 @@ impl LiveTui { KeyCode::Home => self.set_selected_volume(0.0), KeyCode::End => self.set_selected_volume(1.0), KeyCode::Char('m') => self.toggle_selected_mute(), - KeyCode::Char('h') => self.toggle_selected_visibility(), + KeyCode::Char('H') => self.toggle_selected_visibility(), KeyCode::Char('a') => self.start_separator_editor(), KeyCode::Char('e') => self.edit_selected_entry(), KeyCode::Char('d') => self.remove_selected_separator(), @@ -2205,8 +2215,10 @@ impl Widget for &LiveTui { "move".fg(theme.secondary), " A/E/D ".fg(theme.foreground), "separator".fg(theme.secondary), - " h ".fg(theme.foreground), + " ⇧H ".fg(theme.foreground), "hide".fg(theme.secondary), + " h/? ".fg(theme.foreground), + "help".fg(theme.secondary), ]), (Tab::Mixer, MixerOrientation::Vertical) => Line::from(vec![ " ↑↓/jk ".fg(theme.foreground), @@ -2227,8 +2239,10 @@ impl Widget for &LiveTui { "move".fg(theme.secondary), " A/E/D ".fg(theme.foreground), "separator".fg(theme.secondary), - " h ".fg(theme.foreground), + " ⇧H ".fg(theme.foreground), "hide".fg(theme.secondary), + " h/? ".fg(theme.foreground), + "help".fg(theme.secondary), ]), (Tab::Configuration, _) => Line::from(vec![ " ↑↓ ".fg(theme.foreground), @@ -2243,6 +2257,8 @@ impl Widget for &LiveTui { "theme".fg(theme.secondary), " Q ".fg(theme.foreground), "quit".fg(theme.secondary), + " h/? ".fg(theme.foreground), + "help".fg(theme.secondary), ]), }; Paragraph::new(footer_line) @@ -2278,6 +2294,9 @@ impl Widget for &LiveTui { if self.snapshot.configuration.learning.is_some() { self.render_midi_learn_waiting(area, buf); } + if self.show_help { + self.render_help(area, buf); + } if self.quit_confirmation { let width = area.width.min(46); let height = area.height.min(5); @@ -2787,6 +2806,47 @@ impl LiveTui { .render(popup, buf); } + fn render_help(&self, area: Rect, buf: &mut Buffer) { + let theme = self.theme.palette(); + let (selection, volume, movement) = match self.snapshot.configuration.mixer_orientation { + MixerOrientation::Horizontal => ("Left/Right", "Up/Down", "Shift+Left/Right"), + MixerOrientation::Vertical => ("Up/Down", "Left/Right", "Shift+Up/Down"), + }; + let popup = centered_rect(area, 78, 22); + Clear.render(popup, buf); + Paragraph::new(Text::from(vec![ + Line::from("Mixer").fg(theme.accent).bold(), + Line::from(format!(" {selection:<18} Select a fader or separator")), + Line::from(format!(" {volume:<18} Change the selected fader volume")), + Line::from(format!(" {movement:<18} Reorder the selected entry")), + Line::from(" J/K Select next/previous in either orientation"), + Line::from(" M Toggle mute"), + Line::from(" Shift+H Hide the selected fader"), + Line::from(" E Edit the selected fader or separator"), + Line::from(" A Add a separator after the selection"), + Line::from(" D Remove the selected separator"), + Line::from(""), + Line::from("Configuration").fg(theme.accent).bold(), + Line::from(" Up/Down or J/K Select a setting or MIDI device"), + Line::from(" Left/Right/Enter Change a setting or open its popup"), + Line::from(" S Save the configuration"), + Line::from(""), + Line::from("Global").fg(theme.accent).bold(), + Line::from(" 1 / 2 / Tab Switch Mixer and Config views"), + Line::from(" T Cycle theme Q Confirm quit"), + ])) + .wrap(Wrap { trim: false }) + .block( + Block::bordered() + .title(" Keyboard help ".fg(theme.accent).bold()) + .title_bottom(" Esc / h / ? close ".fg(theme.muted)) + .border_set(border::DOUBLE) + .border_style(Style::default().fg(theme.accent)) + .style(Style::default().bg(theme.background)), + ) + .render(popup, buf); + } + fn render_configuration(&self, area: Rect, buf: &mut Buffer) { let theme = self.theme.palette(); let config = &self.snapshot.configuration; @@ -3669,6 +3729,37 @@ mod tests { assert!(app.exit); } + #[test] + fn help_keys_open_detailed_keyboard_help_without_hiding() { + let mut app = LiveTui::new(DemoClient::default()).unwrap(); + app.handle_key_event(press(KeyCode::Char('h'))); + + let area = Rect::new(0, 0, 100, 24); + let mut buffer = Buffer::empty(area); + (&app).render(area, &mut buffer); + let rendered = buffer + .content + .iter() + .map(|cell| cell.symbol()) + .collect::(); + assert!(rendered.contains("Keyboard help")); + assert!(rendered.contains("Shift+H")); + assert!(rendered.contains("Add a separator")); + assert!(rendered.contains("Save the configuration")); + + app.handle_key_event(press(KeyCode::Esc)); + assert!(!app.exit); + app.handle_key_event(press(KeyCode::Char('?'))); + let mut question_buffer = Buffer::empty(area); + (&app).render(area, &mut question_buffer); + let question_rendered = question_buffer + .content + .iter() + .map(|cell| cell.symbol()) + .collect::(); + assert!(question_rendered.contains("Keyboard help")); + } + #[test] fn separator_name_is_edited_in_a_centered_popup() { let mut app = LiveTui::new(DemoClient::default()).unwrap(); @@ -3882,8 +3973,7 @@ mod tests { app.handle_key_event(shift(KeyCode::Down)); app.handle_key_event(press(KeyCode::Up)); - app.handle_key_event(press(KeyCode::Char('h'))); - app.handle_key_event(press(KeyCode::Char('H'))); + app.handle_key_event(shift(KeyCode::Char('H'))); app.handle_key_event(press(KeyCode::Tab)); let mut hidden_buffer = Buffer::empty(area); (&app).render(area, &mut hidden_buffer);