kimun_notes/components/dialogs/

help_dialog.rs

use std::collections::BTreeMap;

use ratatui::Frame;
use ratatui::crossterm::event::{KeyCode, MouseEvent, MouseEventKind};
use ratatui::layout::{Constraint, Direction, Layout, Rect};
use ratatui::style::{Modifier, Style};
use ratatui::widgets::Paragraph;

use super::ModalShell;
use crate::components::Component;
use crate::components::event_state::EventState;
use crate::components::events::{AppEvent, AppTx, InputEvent};
use crate::components::hint_row::HintRow;
use crate::components::panel::{ModalSpec, modal_chrome};
use crate::keys::KeyBindings;
use crate::keys::action_shortcuts::ShortcutCategory;
use crate::settings::themes::Theme;

// ---------------------------------------------------------------------------
// HelpRow
// ---------------------------------------------------------------------------

pub enum HelpRow {
    Header(String),
    Separator,
    Binding { keys: String, label: String },
    Blank,
}

// ---------------------------------------------------------------------------
// HelpDialog
// ---------------------------------------------------------------------------

pub struct HelpDialog {
    pub rows: Vec<HelpRow>,
    /// Window title — distinguishes the flat F1 help from the leader-tree
    /// cheatsheet, which share this widget.
    title: &'static str,
    scroll: usize,
    /// Cached body height from last render, used for PageUp/PageDown page size.
    last_body_height: u16,
    /// Dismiss-on-outside-press and hint-chip clicks (see [`ModalShell`]).
    shell: ModalShell,
    footer: HintRow,
}

impl HelpDialog {
    pub fn new(key_bindings: &KeyBindings, tree: &crate::keys::leader::LeaderNode) -> Self {
        use crate::keys::action_shortcuts::ActionShortcuts;
        use crate::keys::leader::{LeaderAction, LeaderNode};

        let mut by_category: BTreeMap<ShortcutCategory, Vec<(String, String)>> = BTreeMap::new();

        let map = key_bindings.to_hashmap();
        let mut entries: Vec<_> = map.into_iter().collect();
        entries.sort_by_key(|(action, _)| action.to_string());

        for (action, mut combos) in entries {
            combos.sort();
            let keys = combos
                .iter()
                .map(|c| c.to_string())
                .collect::<Vec<_>>()
                .join(" / ");
            let label = action.label();
            by_category
                .entry(action.category())
                .or_default()
                .push((keys, label));
        }

        // Formatting carries no default chord — it lives on the leader's
        // `+text` group, because `Ctrl+I` is Tab's byte outside the kitty
        // keyboard protocol. This list is built from the binding map, so with
        // nothing bound the whole section would vanish and formatting would
        // read as removed rather than moved. Name the route, and read it off
        // the tree the cheatsheet renders from, so a rebound or relabelled
        // group is described as it is. Listed beside any chord the user
        // bound: the leader is the route that always works.
        //
        // Both conditions matter. With the gateway unbound there is no
        // `<leader> t` to reach, so there is nothing truthful to say — which
        // is why the gateway is read as an Option rather than defaulted to a
        // placeholder. And a tree with no group holding `TextBold` (an
        // override removed it) has no route to name.
        let text_group = tree.children().iter().find(|(_, node)| {
            node.children().iter().any(|(_, leaf)| {
                matches!(
                    leaf,
                    LeaderNode::Leaf {
                        action: LeaderAction::TextBold,
                        ..
                    }
                )
            })
        });
        if let Some(leader) = key_bindings.first_combo_for(&ActionShortcuts::Leader)
            && let Some((key, group)) = text_group
        {
            let leaves = group
                .children()
                .iter()
                .map(|(_, leaf)| leaf.label())
                .collect::<Vec<_>>()
                .join(" / ");
            by_category
                .entry(ShortcutCategory::TextEditing)
                .or_default()
                .push((
                    format!("{leader} {key}"),
                    format!("{leaves} ({})", group.label()),
                ));
        }

        let mut rows: Vec<HelpRow> = Vec::new();
        for (category, bindings) in by_category {
            if bindings.is_empty() {
                continue;
            }
            rows.push(HelpRow::Blank);
            rows.push(HelpRow::Header(category.to_string()));
            rows.push(HelpRow::Separator);
            for (keys, label) in bindings {
                rows.push(HelpRow::Binding { keys, label });
            }
        }
        rows.push(HelpRow::Blank);

        Self {
            rows,
            title: " Keyboard Shortcuts ",
            scroll: 0,
            last_body_height: 20,
            shell: ModalShell::default(),
            footer: footer_hints(),
        }
    }

    /// The full leader-tree cheatsheet (leader `?`): every sequence in the
    /// tree as `gateway keys → description`, grouped per top-level group,
    /// followed by the flat Tier-0 bindings. Built from the same
    /// `leader_tree()` the engine and the which-key overlay walk — one
    /// source, three surfaces.
    pub fn cheatsheet(settings: &crate::settings::AppSettings) -> Self {
        use crate::keys::action_shortcuts::ActionShortcuts;
        use crate::keys::leader::LeaderNode;

        let key_bindings = &settings.key_bindings;
        let gateway = key_bindings
            .first_combo_for(&ActionShortcuts::Leader)
            .unwrap_or_else(|| "leader".to_string());

        fn walk(node: &LeaderNode, prefix: &str, rows: &mut Vec<HelpRow>) {
            for (key, child) in node.children() {
                let keys = format!("{prefix} {key}");
                match child {
                    LeaderNode::Leaf { label, .. } => rows.push(HelpRow::Binding {
                        keys,
                        label: (*label).to_string(),
                    }),
                    LeaderNode::Group { .. } => walk(child, &keys, rows),
                }
            }
        }

        let tree = settings.leader_tree();
        let mut rows: Vec<HelpRow> = Vec::new();
        // Current configuration up top (surfaces the theme and keys).
        rows.push(HelpRow::Header("Configuration".to_string()));
        rows.push(HelpRow::Separator);
        rows.push(HelpRow::Binding {
            keys: settings.get_theme().name,
            label: "active theme (leader v c to switch)".to_string(),
        });
        rows.push(HelpRow::Binding {
            keys: gateway.clone(),
            label: "leader gateway".to_string(),
        });
        rows.push(HelpRow::Binding {
            keys: format!("{} ms", settings.leader_timeout_ms),
            label: "which-key reveal timeout".to_string(),
        });
        rows.push(HelpRow::Binding {
            keys: "F1 in Find".to_string(),
            label: "search query syntax".to_string(),
        });
        for row in tree.display_children() {
            if row.is_group {
                // Group: find the child node by its single key and walk it.
                let key = row.keys.chars().next().expect("group keys are one char");
                let child = tree.child(key).expect("display row names a real child");
                rows.push(HelpRow::Blank);
                rows.push(HelpRow::Header(format!("{gateway} {key}  {}", row.label)));
                rows.push(HelpRow::Separator);
                walk(child, &format!("{gateway} {key}"), &mut rows);
            } else {
                rows.push(HelpRow::Blank);
                rows.push(HelpRow::Binding {
                    keys: format!("{gateway} {}", row.keys),
                    label: row.label,
                });
            }
        }

        // Tier-0: the flat always-on bindings, from the same help builder.
        let flat = Self::new(key_bindings, &tree);
        rows.push(HelpRow::Blank);
        rows.push(HelpRow::Header("Always-on shortcuts".to_string()));
        rows.push(HelpRow::Separator);
        rows.extend(
            flat.rows
                .into_iter()
                .filter(|r| matches!(r, HelpRow::Binding { .. })),
        );
        rows.push(HelpRow::Blank);

        Self {
            rows,
            title: " Cheatsheet — leader keys ",
            scroll: 0,
            last_body_height: 20,
            shell: ModalShell::default(),
            footer: footer_hints(),
        }
    }

    /// Reference card for the search query language (F1 over the Find drawer
    /// view). Operators, modifiers, and a few worked examples — mirrors the
    /// canonical table in `docs/.../search.md`, condensed to the
    /// keys|label shape the help widget already renders. The full prose guide
    /// lives on the docs site, not here.
    pub fn query_syntax() -> Self {
        // (short / long, meaning) — sourced from search.md's operator table.
        const OPERATORS: &[(&str, &str)] = &[
            ("(type text)", "full-text body search"),
            ("= / name:", "by note name"),
            ("@ / in:", "by section heading"),
            ("/ / pt:", "by path / folder"),
            ("# / lb:", "by label (tag)"),
            ("< / lk:", "links TO it (backlinks)"),
            ("> / fwd:", "it links to (forward)"),
            ("% / prop:", "by property (%due, %k=v)"),
            ("^ / or:", "sort results (-^ = desc)"),
        ];
        const MODIFIERS: &[(&str, &str)] = &[
            ("- prefix", "exclude (e.g. -#draft)"),
            ("*", "wildcard prefix (screen*)"),
            ("\" \"", "quote values with spaces"),
        ];
        const EXAMPLES: &[(&str, &str)] = &[
            ("#finance report", "labelled finance + text"),
            ("@work -cancelled", "Work section, not cancelled"),
            ("<kimun #project", "kimun backlinks + label"),
            ("%status=done ^%due", "done, sorted by due"),
        ];

        fn section(rows: &mut Vec<HelpRow>, header: &str, entries: &[(&str, &str)]) {
            rows.push(HelpRow::Header(header.to_string()));
            rows.push(HelpRow::Separator);
            for (keys, label) in entries {
                rows.push(HelpRow::Binding {
                    keys: (*keys).to_string(),
                    label: (*label).to_string(),
                });
            }
            rows.push(HelpRow::Blank);
        }

        let mut rows: Vec<HelpRow> = Vec::new();
        section(&mut rows, "Operators", OPERATORS);
        section(&mut rows, "Modifiers", MODIFIERS);
        section(&mut rows, "Examples", EXAMPLES);

        Self {
            rows,
            title: " Search Query Syntax ",
            scroll: 0,
            last_body_height: 20,
            shell: ModalShell::default(),
            footer: footer_hints(),
        }
    }

    fn scroll_up(&mut self) {
        self.scroll = self.scroll.saturating_sub(1);
    }

    fn scroll_down(&mut self) {
        // Clamped to rows.len() so render's slice is always valid even if called
        // between renders.
        self.scroll = self
            .scroll
            .saturating_add(1)
            .min(self.rows.len().saturating_sub(1));
    }

    fn page_up(&mut self) {
        let page = (self.last_body_height as usize).max(1);
        self.scroll = self.scroll.saturating_sub(page);
    }

    fn page_down(&mut self) {
        let page = (self.last_body_height as usize).max(1);
        self.scroll = self
            .scroll
            .saturating_add(page)
            .min(self.rows.len().saturating_sub(1));
    }

    #[cfg(test)]
    pub(crate) fn scroll(&self) -> usize {
        self.scroll
    }

    /// The wheel scrolls, `[Esc] Close` and a press outside the popup close
    /// it. Modal: every mouse event is consumed.
    pub fn handle_mouse(&mut self, m: &MouseEvent, tx: &AppTx) -> EventState {
        if let Some(key) = self.shell.pointer_key(m, &[&self.footer]) {
            return self.handle_key(key, tx);
        }
        match m.kind {
            MouseEventKind::ScrollUp => (0..WHEEL_ROWS).for_each(|_| self.scroll_up()),
            MouseEventKind::ScrollDown => (0..WHEEL_ROWS).for_each(|_| self.scroll_down()),
            _ => {}
        }
        EventState::Consumed
    }

    /// Key handler — mirrors the `handle_key` pattern used by all other dialog types.
    pub fn handle_key(
        &mut self,
        key: ratatui::crossterm::event::KeyEvent,
        tx: &AppTx,
    ) -> EventState {
        match key.code {
            KeyCode::Esc => {
                tx.send(AppEvent::CloseOverlay).ok();
            }
            KeyCode::Up => self.scroll_up(),
            KeyCode::Down => self.scroll_down(),
            KeyCode::PageUp => self.page_up(),
            KeyCode::PageDown => self.page_down(),
            _ => {}
        }
        EventState::Consumed
    }
}

const OUTER_WIDTH: u16 = 50;
/// Rows one wheel notch scrolls.
const WHEEL_ROWS: usize = 3;

/// The footer: an informational scroll chip, then `[Esc] Close`.
fn footer_hints() -> HintRow {
    HintRow::new(&[
        (KeyCode::Null, "↑↓ PgUp/PgDn", "Scroll"),
        (KeyCode::Esc, "Esc", "Close"),
    ])
    .with_gap(3)
}
const KEYS_COL_WIDTH: u16 = 18;

impl Component for HelpDialog {
    fn handle_input(&mut self, event: &InputEvent, tx: &AppTx) -> EventState {
        let InputEvent::Key(key) = event else {
            return EventState::NotConsumed;
        };
        self.handle_key(*key, tx)
    }

    fn render(&mut self, f: &mut Frame, rect: Rect, theme: &Theme, _focused: bool) {
        let content_rows = self.rows.len() as u16;
        let desired_height = content_rows + 4; // borders(2) + footer(1) + bottom blank(1)
        let max_height = (rect.height * 60 / 100).max(10);
        let outer_height = desired_height.min(max_height);

        let popup_area = super::fixed_centered_rect(OUTER_WIDTH, outer_height, rect);
        self.shell.set(popup_area);
        let inner = modal_chrome(
            f,
            popup_area,
            theme,
            ModalSpec {
                title: Some(self.title),
                border: Some(Style::default().fg(theme.fg.to_ratatui())),
                ..Default::default()
            },
        );

        if inner.height < 2 {
            return;
        }

        let chunks = Layout::default()
            .direction(Direction::Vertical)
            .constraints([Constraint::Min(1), Constraint::Length(1)])
            .split(inner);

        let body_area = chunks[0];
        let footer_area = chunks[1];

        let bg = theme.bg_panel.to_ratatui();
        let fg = theme.fg.to_ratatui();
        let gray = theme.gray.to_ratatui();
        let fg_accent = theme.selection_fg.to_ratatui();

        // Cache for PageUp/PageDown.
        self.last_body_height = body_area.height;

        // Clamp scroll.
        let body_height = body_area.height as usize;
        let max_scroll = self.rows.len().saturating_sub(body_height);
        self.scroll = self.scroll.min(max_scroll);

        // Render visible rows.
        let visible = &self.rows[self.scroll..];
        for (y, row) in (body_area.y..).zip(visible.iter()) {
            if y >= body_area.y + body_area.height {
                break;
            }
            let row_rect = Rect {
                x: body_area.x,
                y,
                width: body_area.width,
                height: 1,
            };
            match row {
                HelpRow::Blank => {}
                HelpRow::Header(title) => {
                    f.render_widget(
                        Paragraph::new(format!("  {title}")).style(
                            Style::default()
                                .fg(fg_accent)
                                .bg(bg)
                                .add_modifier(Modifier::BOLD),
                        ),
                        row_rect,
                    );
                }
                HelpRow::Separator => {
                    super::render_separator(f, row_rect, gray, bg);
                }
                HelpRow::Binding { keys, label } => {
                    let cols = Layout::default()
                        .direction(Direction::Horizontal)
                        .constraints([
                            Constraint::Length(2),
                            Constraint::Length(KEYS_COL_WIDTH),
                            Constraint::Min(1),
                        ])
                        .split(row_rect);
                    f.render_widget(
                        Paragraph::new(keys.as_str()).style(Style::default().fg(fg_accent).bg(bg)),
                        cols[1],
                    );
                    f.render_widget(
                        Paragraph::new(label.as_str()).style(Style::default().fg(fg).bg(bg)),
                        cols[2],
                    );
                }
            }
        }

        let hint_style = Style::default().fg(gray).bg(bg);
        self.footer.render(f, footer_area, hint_style, theme);
    }
}

impl_dialog!(HelpDialog);

#[cfg(test)]
mod tests {
    use super::*;
    use crate::keys::KeyBindings;
    use crate::keys::action_shortcuts::{ActionShortcuts, TextAction};
    use crate::keys::key_strike::KeyStrike;

    fn bindings_with_bold_and_quit() -> KeyBindings {
        let mut kb = KeyBindings::empty();
        kb.batch_add()
            .with_ctrl()
            .add(KeyStrike::KeyB, ActionShortcuts::Text(TextAction::Bold))
            .add(KeyStrike::KeyQ, ActionShortcuts::Quit);
        kb
    }

    /// Formatting moved to the leader, so F1 has no chord to list for it.
    /// It must still say where formatting went — a missing section reads as a
    /// removed feature.
    #[test]
    fn f1_names_the_leader_route_when_no_formatting_chord_is_bound() {
        let dialog = HelpDialog::new(
            &crate::settings::AppSettings::default().key_bindings,
            &crate::keys::leader::leader_tree(),
        );
        let row = dialog.rows.iter().find_map(|r| match r {
            HelpRow::Binding { keys, label } if label.contains("bold") => {
                Some((keys.clone(), label.clone()))
            }
            _ => None,
        });
        let (keys, label) = row.expect("F1 must point at the formatting route");
        assert!(keys.ends_with(" t"), "should name the +text group: {keys}");
        assert!(
            keys.starts_with("ctrl&B"),
            "prefixed by the gateway: {keys}"
        );
        assert_eq!(label, "bold / italic / strikethrough (+text)");
    }

    /// The leader route is the primary way to format, so it is listed even
    /// beside a chord the user bound — a lone `TextEditor-Underline` chord is
    /// a no-op, and hiding the three leaves that work behind it was the bug.
    #[test]
    fn f1_lists_the_leader_route_beside_a_real_formatting_chord() {
        let mut kb = bindings_with_bold_and_quit();
        kb.batch_add()
            .with_ctrl()
            .add(KeyStrike::KeyG, ActionShortcuts::Leader);
        let dialog = HelpDialog::new(&kb, &crate::keys::leader::leader_tree());
        let labels: Vec<&str> = dialog
            .rows
            .iter()
            .filter_map(|r| match r {
                HelpRow::Binding { label, .. } => Some(label.as_str()),
                _ => None,
            })
            .collect();
        assert!(labels.contains(&"Bold"), "{labels:?}");
        assert!(
            labels.iter().any(|l| l.contains("+text")),
            "the leader route must stand beside the chord: {labels:?}"
        );
    }

    /// The row is read off the tree, so a rebound or relabelled `+text`
    /// group shows up as it really is rather than as the shipped default.
    #[test]
    fn f1_formatting_hint_follows_the_tree() {
        use crate::keys::leader::{LeaderAction, LeaderNode};
        let tree = LeaderNode::Group {
            label: "leader".into(),
            children: vec![(
                'x',
                LeaderNode::Group {
                    label: "+fmt".into(),
                    children: vec![
                        (
                            'b',
                            LeaderNode::Leaf {
                                label: "bold",
                                action: LeaderAction::TextBold,
                            },
                        ),
                        (
                            'i',
                            LeaderNode::Leaf {
                                label: "italic",
                                action: LeaderAction::TextItalic,
                            },
                        ),
                    ],
                },
            )],
        };
        let dialog = HelpDialog::new(&crate::settings::AppSettings::default().key_bindings, &tree);
        let row = dialog.rows.iter().find_map(|r| match r {
            HelpRow::Binding { keys, label } if label.contains("+fmt") => {
                Some((keys.clone(), label.clone()))
            }
            _ => None,
        });
        let (keys, label) = row.expect("the hint must be built from the tree");
        assert_eq!(keys, "ctrl&B x");
        assert_eq!(label, "bold / italic (+fmt)");
    }

    #[test]
    fn rows_contain_both_categories() {
        let dialog = HelpDialog::new(
            &bindings_with_bold_and_quit(),
            &crate::keys::leader::leader_tree(),
        );
        let headers: Vec<String> = dialog
            .rows
            .iter()
            .filter_map(|r| {
                if let HelpRow::Header(s) = r {
                    Some(s.clone())
                } else {
                    None
                }
            })
            .collect();
        assert!(headers.contains(&"Text Editing".to_string()));
        assert!(headers.contains(&"Other".to_string()));
        assert!(!headers.contains(&"Navigation".to_string()));
        assert!(!headers.contains(&"Notes".to_string()));
    }

    #[test]
    fn binding_row_has_correct_keys_and_label() {
        let dialog = HelpDialog::new(
            &bindings_with_bold_and_quit(),
            &crate::keys::leader::leader_tree(),
        );
        let binding = dialog.rows.iter().find_map(|r| {
            if let HelpRow::Binding { keys, label } = r
                && label == "Bold"
            {
                return Some(keys.clone());
            }
            None
        });
        assert!(binding.is_some(), "expected a Bold binding row");
        assert_eq!(binding.unwrap(), "ctrl&B");
    }

    #[test]
    fn empty_keybindings_produces_no_rows() {
        let dialog = HelpDialog::new(&KeyBindings::empty(), &crate::keys::leader::leader_tree());
        assert!(
            !dialog
                .rows
                .iter()
                .any(|r| matches!(r, HelpRow::Binding { .. }))
        );
        assert!(!dialog.rows.iter().any(|r| matches!(r, HelpRow::Header(_))));
    }
}