tix-tracker 0.4.0

use std::fmt::Write;

use crate::keybindings::{EffectiveBindings, InputContext, KeyBindings, TuiAction};

pub const MODE_BOARD: &str = "board";
pub const MODE_DETAIL: &str = "detail";
pub const MODE_HELP: &str = "help";
pub const MODE_COMMENT: &str = "comment";
pub const MODE_ASSET: &str = "asset";
pub const MODE_FILTER: &str = "filter";

const MAX_HINT_CHARS: usize = 80;

pub struct Cmd {
    pub key: &'static str,
    pub desc: &'static str,
    pub modes: &'static [&'static str],
    pub mode: &'static str,
}

pub const COMMANDS: &[Cmd] = &[
    Cmd {
        key: "j/k",
        desc: "move up/down",
        modes: &[MODE_BOARD],
        mode: MODE_BOARD,
    },
    Cmd {
        key: "n",
        desc: "new issue",
        modes: &[MODE_BOARD],
        mode: MODE_BOARD,
    },
    Cmd {
        key: "?",
        desc: "help",
        modes: &[MODE_BOARD, MODE_DETAIL],
        mode: "board/detail",
    },
    Cmd {
        key: "h/l",
        desc: "column",
        modes: &[MODE_BOARD],
        mode: MODE_BOARD,
    },
    Cmd {
        key: "enter",
        desc: "open",
        modes: &[MODE_BOARD],
        mode: MODE_BOARD,
    },
    Cmd {
        key: "d",
        desc: "delete",
        modes: &[MODE_BOARD],
        mode: MODE_BOARD,
    },
    Cmd {
        key: "< / >",
        desc: "move",
        modes: &[MODE_BOARD],
        mode: MODE_BOARD,
    },
    Cmd {
        key: "r",
        desc: "refresh",
        modes: &[MODE_BOARD],
        mode: MODE_BOARD,
    },
    Cmd {
        key: "/",
        desc: "filter",
        modes: &[MODE_BOARD],
        mode: MODE_BOARD,
    },
    Cmd {
        key: "f",
        desc: "criteria",
        modes: &[MODE_BOARD],
        mode: MODE_BOARD,
    },
    Cmd {
        key: "c",
        desc: "comment",
        modes: &[MODE_DETAIL],
        mode: MODE_DETAIL,
    },
    Cmd {
        key: "a",
        desc: "asset",
        modes: &[MODE_DETAIL],
        mode: MODE_DETAIL,
    },
];

fn actions(context: InputContext) -> &'static [TuiAction] {
    match context {
        InputContext::Board => &[
            TuiAction::NewIssue,
            TuiAction::Help,
            TuiAction::MoveUp,
            TuiAction::MoveDown,
            TuiAction::Planning,
            TuiAction::Quit,
        ],
        InputContext::Detail => &[
            TuiAction::Comment,
            TuiAction::Asset,
            // #1359: the three mutating relationship operations and the cursor that
            // names which edge `E` and `d` act on. A binding that exists but is not
            // in the footer is a binding nobody finds.
            TuiAction::NewRelationship,
            TuiAction::NextRelationship,
            TuiAction::PreviousRelationship,
            TuiAction::EditRelationship,
            TuiAction::RemoveRelationship,
            TuiAction::Edit,
            TuiAction::ScrollUp,
            TuiAction::ScrollDown,
            TuiAction::Help,
        ],
        _ => &[],
    }
}

pub fn hint_bar(active_modes: &[&str]) -> String {
    let bindings =
        KeyBindings::resolve(&KeyBindings::default()).expect("built-in bindings are valid");
    for mode in active_modes {
        if let Some(context) = match *mode {
            MODE_BOARD => Some(InputContext::Board),
            MODE_DETAIL => Some(InputContext::Detail),
            _ => None,
        } {
            return hint_bar_for(&bindings, context);
        }
    }
    String::new()
}

pub fn hint_bar_for(bindings: &EffectiveBindings, context: InputContext) -> String {
    if context == InputContext::Board
        && bindings.label(context, TuiAction::MoveUp) == "Up / k"
        && bindings.label(context, TuiAction::MoveDown) == "Down / j"
    {
        return truncate(
            &format!(
                "j/k nav · {} new issue · {} help",
                bindings.label(context, TuiAction::NewIssue),
                bindings.label(context, TuiAction::Help),
            ),
            MAX_HINT_CHARS,
        );
    }
    let mut text = String::new();
    for action in actions(context) {
        let _ = write!(
            text,
            "{} {} · ",
            bindings.label(context, *action),
            action.description()
        );
    }
    truncate(text.trim_end_matches(" · "), MAX_HINT_CHARS)
}

/// The contexts the keybindings overlay documents, in reading order.
///
/// One list, shared with the completeness guard in this module's tests: a context
/// added to the overlay but not to the guard (or the reverse) is how a whole surface
/// becomes invisible in the help without anyone noticing.
const HELP_CONTEXTS: [InputContext; 25] = [
    InputContext::Detail,
    InputContext::Board,
    InputContext::Rollover,
    InputContext::Form,
    InputContext::FormPicker,
    InputContext::ConfirmDelete,
    InputContext::MoveIntoDone,
    // WP04: the blocked-move prompt's keys belong in the help overlay too, or
    // a user who never guessed `y` has no way to learn it.
    InputContext::ConfirmBlockedMove,
    InputContext::Help,
    InputContext::HelpSearch,
    InputContext::ContextMenu,
    InputContext::Filter,
    InputContext::FilterModal,
    InputContext::Settings,
    InputContext::SettingsPrompt,
    InputContext::PlanningManagement,
    InputContext::PlanningConfirm,
    InputContext::PlanningForm,
    InputContext::DatePicker,
    InputContext::Comment,
    InputContext::Asset,
    InputContext::LinkPrompt,
    InputContext::EditWarning,
    // WP07: the batch surface's keys, for the same reason WP04 put the
    // blocked-move prompt's there — a key nobody can discover is a key nobody
    // uses, and the batch surface is entirely keyboard-driven.
    InputContext::BulkModal,
    // WP06: the triage inbox's keys, same reason. The `t` that opens it is
    // listed by the `board` rows below.
    InputContext::Triage,
];

pub fn help_overlay(bindings: &EffectiveBindings) -> Vec<(String, String, String)> {
    let mut rows = vec![
        (
            "mouse click".to_string(),
            "click".to_string(),
            "board".to_string(),
        ),
        (
            "mouse double".to_string(),
            "double-click".to_string(),
            "board".to_string(),
        ),
        (
            "mouse right".to_string(),
            "right-click".to_string(),
            "board".to_string(),
        ),
        (
            "mouse drag".to_string(),
            "drag".to_string(),
            "board".to_string(),
        ),
    ];
    for context in HELP_CONTEXTS {
        for action in all_actions(context) {
            rows.push((
                bindings.label(context, *action),
                action.description().to_string(),
                context.as_str().to_string(),
            ));
        }
    }
    rows
}

fn all_actions(context: InputContext) -> &'static [TuiAction] {
    match context {
        InputContext::Board => &[
            TuiAction::MoveUp,
            TuiAction::MoveDown,
            TuiAction::MoveLeft,
            TuiAction::MoveRight,
            TuiAction::NextBoard,
            TuiAction::PreviousBoard,
            TuiAction::Open,
            TuiAction::Edit,
            TuiAction::Agent,
            TuiAction::ToggleColumn,
            TuiAction::FilterModal,
            TuiAction::BulkModal,
            TuiAction::Triage,
            TuiAction::Mark,
            TuiAction::Unmark,
            TuiAction::MovePrevious,
            TuiAction::MoveNext,
            // The page keys (#1442): bound on the board, and until this guard existed
            // they were the only way to reach a card the column had scrolled past —
            // documented nowhere.
            TuiAction::ScrollUp,
            TuiAction::ScrollDown,
            TuiAction::NewIssue,
            // The two board keys added after this list was written: the overlay's list
            // is hand-written, so a binding it does not name is a key that works and
            // cannot be discovered. `every_bound_action_appears_in_the_overlay` is the
            // guard, and it is what found these.
            TuiAction::CloneIssue,
            TuiAction::ToggleArchived,
            TuiAction::Delete,
            TuiAction::Refresh,
            TuiAction::Settings,
            TuiAction::Planning,
            TuiAction::NewBoard,
            TuiAction::Help,
            TuiAction::Quit,
            TuiAction::TextFilter,
            TuiAction::ReorderUp,
            TuiAction::ReorderDown,
        ],
        InputContext::Detail => &[
            // The pane's own list, not the footer's: `close` is how you get back, and a
            // key that returns you is not one to leave out of the reference.
            TuiAction::Close,
            TuiAction::Edit,
            TuiAction::ScrollUp,
            TuiAction::ScrollDown,
            TuiAction::Help,
            TuiAction::Comment,
            TuiAction::Asset,
            TuiAction::NewRelationship,
            TuiAction::NextRelationship,
            TuiAction::PreviousRelationship,
            TuiAction::EditRelationship,
            TuiAction::RemoveRelationship,
        ],
        InputContext::Rollover => &[TuiAction::Submit, TuiAction::Previous, TuiAction::Cancel],
        InputContext::Form | InputContext::PlanningForm => &[
            TuiAction::Submit,
            TuiAction::Cancel,
            TuiAction::Next,
            TuiAction::Previous,
            TuiAction::OpenPicker,
        ],
        InputContext::FormPicker => &[
            TuiAction::Cancel,
            TuiAction::Next,
            TuiAction::Previous,
            TuiAction::Submit,
            TuiAction::Create,
        ],
        InputContext::ConfirmDelete
        | InputContext::PlanningConfirm
        | InputContext::ConfirmBlockedMove => &[TuiAction::Confirm, TuiAction::Cancel],
        InputContext::MoveIntoDone
        | InputContext::Filter
        | InputContext::Comment
        | InputContext::Asset
        | InputContext::LinkPrompt => &[TuiAction::Submit, TuiAction::Cancel],
        InputContext::Help => &[
            TuiAction::Cancel,
            TuiAction::Next,
            TuiAction::Previous,
            // #1496: the search key, so the overlay names the way to search it.
            TuiAction::TextFilter,
            // #1441/#1442: the overlay's page keys. These are the overlay's *rows*, not
            // a footer — the footer for this context is the hint bar `render_help` draws
            // underneath, which is the board's or the pane's.
            TuiAction::ScrollUp,
            TuiAction::ScrollDown,
            TuiAction::Submit,
        ],
        InputContext::ContextMenu => &[
            TuiAction::Cancel,
            TuiAction::Next,
            TuiAction::Previous,
            TuiAction::Submit,
        ],
        // Free text: `Esc` leaves the line (and clears it), `Enter` keeps the query.
        InputContext::HelpSearch => &[TuiAction::Cancel, TuiAction::Submit],
        InputContext::BulkModal => &[
            TuiAction::Next,
            TuiAction::Previous,
            TuiAction::Submit,
            TuiAction::Cancel,
        ],
        // WP06: only what the context actually binds. The inbox's decision keys
        // (`a`, `d`, `u`, `f`, `p`, `y`) are deliberately unbound so they stay
        // typeable in a reason field, so they cannot appear here as chords —
        // they are named by the modal's own footer instead, which is how the
        // batch surface names its unbound keys too.
        InputContext::Triage => &[
            TuiAction::MoveUp,
            TuiAction::MoveDown,
            TuiAction::Toggle,
            TuiAction::Submit,
            TuiAction::Cancel,
        ],
        InputContext::FilterModal => &[
            TuiAction::Next,
            TuiAction::Previous,
            TuiAction::Reset,
            TuiAction::Submit,
            TuiAction::Cancel,
            TuiAction::OpenPicker,
        ],
        InputContext::Settings => &[
            TuiAction::MoveUp,
            TuiAction::MoveDown,
            TuiAction::Next,
            TuiAction::Previous,
            TuiAction::Toggle,
            TuiAction::AddColumn,
            TuiAction::NewBoard,
            TuiAction::Delete,
            TuiAction::Close,
        ],
        InputContext::SettingsPrompt => &[TuiAction::Submit, TuiAction::Cancel],
        InputContext::PlanningManagement => &[
            TuiAction::MoveUp,
            TuiAction::MoveDown,
            TuiAction::Next,
            TuiAction::NewPlanningItem,
            TuiAction::EditPlanningItem,
            TuiAction::DeletePlanningItem,
            TuiAction::Close,
        ],
        InputContext::DatePicker => &[
            TuiAction::MoveUp,
            TuiAction::MoveDown,
            TuiAction::MoveLeft,
            TuiAction::MoveRight,
            TuiAction::PreviousMonth,
            TuiAction::NextMonth,
            TuiAction::PreviousYear,
            TuiAction::NextYear,
            TuiAction::Submit,
            TuiAction::Reset,
            TuiAction::Cancel,
        ],
        InputContext::EditWarning => &[TuiAction::Reedit, TuiAction::Ignore],
    }
}

fn truncate(value: &str, max_chars: usize) -> String {
    if max_chars == 0 || value.chars().count() <= max_chars {
        return value.to_string();
    }
    let take = max_chars.saturating_sub(1);
    let head: String = value.chars().take(take).collect();
    format!("{}…", head.trim_end())
}

#[cfg(test)]
mod tests {
    use super::*;

    /// Every action a documented context binds must appear in the overlay.
    ///
    /// `all_actions` is written by hand per context, so a binding can be added to the
    /// keymap and never appear in the help — the worst of both worlds, because the key
    /// works and nobody can discover it. It had already happened twice before this
    /// guard existed (`clone_issue` and `toggle_archived`, both added while this list
    /// was not).
    #[test]
    fn every_bound_action_appears_in_the_overlay() {
        let bindings =
            KeyBindings::resolve(&KeyBindings::default()).expect("built-in bindings are valid");
        let mut missing: Vec<String> = Vec::new();
        for context in HELP_CONTEXTS {
            let listed = all_actions(context);
            for action in bindings.bound_actions(context) {
                if !listed.contains(&action) {
                    missing.push(format!("{} — {}", context.as_str(), action.as_str()));
                }
            }
        }
        assert!(
            missing.is_empty(),
            "the overlay does not list these bound actions, so nothing in the help \
             would tell a user they exist:\n  {}",
            missing.join("\n  ")
        );
    }

    /// The guard is only as good as its context list: a context the overlay documents
    /// but the guard does not walk is a surface whose keys can go missing silently.
    #[test]
    fn the_overlay_and_its_guard_cover_the_same_contexts() {
        let bindings =
            KeyBindings::resolve(&KeyBindings::default()).expect("built-in bindings are valid");
        let drawn = help_overlay(&bindings);
        for context in HELP_CONTEXTS {
            let scope = context.as_str();
            assert!(
                drawn.iter().any(|(_, _, listed)| listed == scope),
                "`{scope}` is in HELP_CONTEXTS but contributes no rows to the overlay"
            );
        }
    }

    #[test]
    fn dynamic_hint_uses_effective_aliases() {
        let mut overrides = KeyBindings::default();
        overrides.board.new_issue = Some(vec!["ctrl+n".into(), "f4".into()]);
        overrides.board.help = Some(vec!["f1".into()]);
        let bindings = KeyBindings::resolve(&overrides).unwrap();
        let hint = hint_bar_for(&bindings, InputContext::Board);
        assert!(hint.contains("Ctrl+n / F4 new issue"), "got {hint:?}");
        assert!(hint.contains("F1 help"), "got {hint:?}");
    }

    #[test]
    fn help_covers_every_configured_action() {
        let bindings = KeyBindings::resolve(&KeyBindings::default()).unwrap();
        let rows = help_overlay(&bindings);
        for context in InputContext::ALL {
            for action in all_actions(*context) {
                assert!(
                    rows.iter()
                        .any(|(_, description, mode)| description == action.description()
                            && mode == context.as_str())
                );
            }
        }
    }
}