`5475c02`

Add contextual help modal

Authored by

espadonne 2 weeks ago

SHA: 5475c027352bb09cf6ac22bf2aad2e312f92d546
Parents: 9cb416e
Tree: 66b16ff

4 changed files

Status	File	+	-
M	`README.md`	1	0
M	`src/app.rs`	91	1
M	`src/cli.rs`	9	2
M	`src/tui.rs`	200	6

README.mdmodified

  ## Controls
  - Arrow keys move the selected date.
 +- `?` opens contextual help.
  - `+` opens the Create event modal.
  - In day view, `d` opens the Delete confirmation for the selected local event.
  - `Enter` opens the focused day view.

src/app.rsmodified

      create_form: Option<CreateEventForm>,
      recurrence_choice: Option<RecurrenceEditChoice>,
      delete_choice: Option<EventDeleteChoice>,
 +    help_open: bool,
      selected_day_event_id: Option<String>,
      should_quit: bool,
+ }
              create_form: None,
              recurrence_choice: None,
              delete_choice: None,
 +            help_open: false,
              selected_day_event_id: None,
              should_quit: false,
+         }
          self.delete_choice.is_some()
+     }
 +    pub const fn is_showing_help(&self) -> bool {
 +        self.help_open
 +    }
++
      pub fn close_create_form(&mut self) {
          self.create_form = None;
+     }
          self.delete_choice = None;
+     }
 +    pub fn close_help(&mut self) {
 +        self.help_open = false;
 +    }
++
      pub fn set_delete_error(&mut self, message: impl Into<String>) {
          if let Some(choice) = &mut self.delete_choice {
              choice.error = Some(message.into());
+         }
+     }
 +    pub fn handle_help_key(&mut self, key: KeyEvent) -> HelpInputResult {
 +        if key.kind == KeyEventKind::Release {
 +            return HelpInputResult::Continue;
 +        }
++
 +        match key.code {
 +            KeyCode::Esc | KeyCode::Enter | KeyCode::Char('?') => {
 +                self.close_help();
 +                HelpInputResult::Close
 +            }
 +            KeyCode::Char(value) if value.eq_ignore_ascii_case(&'q') => {
 +                self.should_quit = true;
 +                HelpInputResult::Continue
 +            }
 +            KeyCode::Char(value) if ctrl_c(value, key.modifiers) => {
 +                self.should_quit = true;
 +                HelpInputResult::Continue
 +            }
 +            _ => HelpInputResult::Continue,
 +        }
 +    }
++
      pub fn calendar_month(&self) -> CalendarMonth {
          CalendarMonth::from_dates(self.selected_date, self.today)
+     }
          match action {
              AppAction::Noop => {}
              AppAction::Quit => self.should_quit = true,
 +            AppAction::OpenHelp
 +                if self.create_form.is_none()
 +                    && self.recurrence_choice.is_none()
 +                    && self.delete_choice.is_none() =>
 +            {
 +                self.help_open = true;
 +            }
 +            _ if self.help_open => {}
              AppAction::OpenDay if self.view_mode == ViewMode::Day => {
                  if let Some(source) = source {
                      self.open_selected_event_for_edit(source);
                  self.selected_day_event_id = None;
                  self.recurrence_choice = None;
                  self.delete_choice = None;
 +                self.help_open = false;
+             }
              AppAction::OpenCreate => {
                  if self.create_form.is_none()
                      && self.recurrence_choice.is_none()
                      && self.delete_choice.is_none()
 +                    && !self.help_open
+                 {
                      let context = match self.view_mode {
                          ViewMode::Month => CreateEventContext::EditableDate,
                  if self.create_form.is_none()
                      && self.recurrence_choice.is_none()
                      && self.delete_choice.is_none()
 +                    && !self.help_open
                      && let Some(source) = source
+                 {
                      self.open_selected_event_for_delete(source);
              | AppAction::SelectDate(_)
              | AppAction::JumpToDay(_)
              | AppAction::JumpToWeekday(_)
 -            | AppAction::OpenDelete => {}
 +            | AppAction::OpenDelete
 +            | AppAction::OpenHelp => {}
+         }
+     }
      CloseDay,
      OpenCreate,
      OpenDelete,
 +    OpenHelp,
      Quit,
+ }
      Submit(EventDeleteSubmission),
+ }
 +#[derive(Debug, Clone, PartialEq, Eq)]
 +pub enum HelpInputResult {
 +    Continue,
 +    Close,
 +}
++
  #[derive(Debug, Clone, PartialEq, Eq)]
  pub struct CreateEventForm {
      mode: EventFormMode,
              return AppAction::OpenCreate;
+         }
 +        if value == '?' {
 +            self.clear();
 +            return AppAction::OpenHelp;
 +        }
++
          if value.eq_ignore_ascii_case(&'d') {
              self.clear();
              return AppAction::OpenDelete;
          );
+     }
 +    #[test]
 +    fn question_mark_opens_help_and_esc_closes_it() {
 +        let day = date(2026, Month::April, 23);
 +        let mut app = AppState::new(day);
 +        let mut input = KeyboardInput::default();
++
 +        app.apply(input.translate(char_key('?')));
++
 +        assert!(app.is_showing_help());
 +        assert_eq!(
 +            app.handle_help_key(key(KeyCode::Esc)),
 +            HelpInputResult::Close
 +        );
 +        assert!(!app.is_showing_help());
 +        assert_eq!(app.selected_date(), day);
 +    }
++
 +    #[test]
 +    fn help_modal_blocks_calendar_navigation_until_closed() {
 +        let day = date(2026, Month::April, 23);
 +        let mut app = AppState::new(day);
 +        let mut input = KeyboardInput::default();
++
 +        app.apply(input.translate(char_key('?')));
 +        app.apply(input.translate(key(KeyCode::Right)));
++
 +        assert!(app.is_showing_help());
 +        assert_eq!(app.selected_date(), day);
++
 +        assert_eq!(app.handle_help_key(char_key('?')), HelpInputResult::Close);
 +        app.apply(input.translate(key(KeyCode::Right)));
 +        assert_eq!(app.selected_date(), date(2026, Month::April, 24));
 +    }
++
      #[test]
      fn create_form_text_input_does_not_move_selection() {
          let day = date(2026, Month::April, 23);

src/cli.rsmodified

      agenda::{ConfiguredAgendaSource, HolidayProvider, LocalEventStoreError, default_events_file},
      app::{
          AppState, CreateEventInputResult, EventDeleteInputResult, EventDeleteSubmission,
 -        EventFormMode, KeyboardInput, MouseInput, RecurrenceChoiceInputResult,
 +        EventFormMode, HelpInputResult, KeyboardInput, MouseInput, RecurrenceChoiceInputResult,
      },
      calendar::CalendarDate,
      tui::{
      "  -V, --version                       Show version.\n\n",
      "Keys:\n",
      "  Arrow keys move selection; Enter opens day view; Esc returns to month; q exits.\n",
 +    "  ? opens contextual help.\n",
      "  + opens the Create event modal.\n",
      "  In day view, d opens the Delete confirmation for the selected local event.\n",
      "  In day view, Left/Right move to the previous or next day.\n",
          let event = if !app.is_creating_event()
              && !app.is_choosing_recurring_edit()
              && !app.is_confirming_delete()
 +            && !app.is_showing_help()
              && keyboard.is_waiting_for_digit()
+         {
              if event::poll(DIGIT_JUMP_TIMEOUT)? {
          match event {
              Event::Key(key) => {
                  mouse.clear();
 -                if app.is_confirming_delete() {
 +                if app.is_showing_help() {
 +                    match app.handle_help_key(key) {
 +                        HelpInputResult::Continue | HelpInputResult::Close => {}
 +                    }
 +                } else if app.is_confirming_delete() {
                      match app.handle_delete_choice_key(key) {
                          EventDeleteInputResult::Continue => {}
                          EventDeleteInputResult::Cancel => app.close_delete_choice(),
                  if app.is_creating_event()
                      || app.is_choosing_recurring_edit()
                      || app.is_confirming_delete()
 +                    || app.is_showing_help()
+                 {
                      continue;
+                 }

src/tui.rsmodified

  const HEADER_HEIGHT: u16 = 2;
  const VERTICAL_GRID_LINES: u16 = DAYS_PER_WEEK as u16 + 1;
  const HORIZONTAL_GRID_LINES: u16 = MONTH_GRID_WEEKS as u16 + 1;
 +const HELP_HINT: &str = "?: Help";
  static EMPTY_AGENDA_SOURCE: EmptyAgendaSource = EmptyAgendaSource;
  #[derive(Clone, Copy)]
          if let Some(choice) = self.app.delete_choice() {
              render_delete_choice_modal(choice, area, buf, CreateModalStyles::new());
+         }
 +        if self.app.is_showing_help() {
 +            render_help_modal(self.app.view_mode(), area, buf, CreateModalStyles::new());
 +        }
+     }
+ }
      in_month_border: Style,
      preview: Style,
      preview_summary: Style,
 +    help_hint: Style,
      filler: Style,
      filler_border: Style,
+ }
              in_month_border: Style::new().fg(Color::DarkGray).add_modifier(Modifier::DIM),
              preview: Style::new().fg(Color::Gray),
              preview_summary: Style::new().fg(Color::Cyan).add_modifier(Modifier::DIM),
 +            help_hint: Style::new().fg(Color::DarkGray),
              filler: Style::new().fg(Color::DarkGray).add_modifier(Modifier::DIM),
              filler_border: Style::new().fg(Color::DarkGray).add_modifier(Modifier::DIM),
+         }
      holiday: Style,
      event: Style,
      selected_event: Style,
 +    help_hint: Style,
+ }
  impl DayViewStyles {
                  .fg(Color::White)
                  .bg(Color::Blue)
                  .add_modifier(Modifier::BOLD),
 +            help_hint: Style::new().fg(Color::DarkGray),
+         }
+     }
+ }
      buf: &mut Buffer,
      styles: DayViewStyles,
  ) {
 +    let title = day_title(agenda.date);
      write_centered(
          buf,
          layout.title_y,
          layout.area.x,
          layout.area.width,
 -        &day_title(agenda.date),
 +        &title,
          styles.title,
      );
 +    render_title_hint(
 +        buf,
 +        layout.title_y,
 +        layout.area.x,
 +        layout.area.width,
 +        &title,
 +        styles.help_hint,
 +    );
      let Some(summary_y) = layout.summary_y else {
          return;
      );
+ }
 +fn render_help_modal(view_mode: ViewMode, area: Rect, buf: &mut Buffer, styles: CreateModalStyles) {
 +    if area.width == 0 || area.height == 0 {
 +        return;
 +    }
++
 +    let rows = help_rows(view_mode);
 +    let modal = help_modal_area(area, rows.len());
 +    fill_rect(buf, modal, styles.panel);
 +    draw_border(buf, modal, styles.border, BorderCharacters::normal());
++
 +    let content = inset_rect(modal);
 +    if content.width == 0 || content.height == 0 {
 +        return;
 +    }
++
 +    write_centered(
 +        buf,
 +        content.y,
 +        content.x,
 +        content.width,
 +        help_heading(view_mode),
 +        styles.title,
 +    );
++
 +    let key_width = 13.min(content.width.saturating_sub(2));
 +    let description_x = content.x.saturating_add(key_width).saturating_add(2);
 +    let description_width = content.right().saturating_sub(description_x);
 +    let mut y = content.y.saturating_add(2);
 +    for (key, description) in rows {
 +        if y >= content.bottom().saturating_sub(2) {
 +            break;
 +        }
 +        write_padded_left(buf, y, content.x, key_width, key, styles.checkbox);
 +        write_left(
 +            buf,
 +            y,
 +            description_x,
 +            description_width,
 +            description,
 +            styles.value,
 +        );
 +        y = y.saturating_add(1);
 +    }
++
 +    write_centered(
 +        buf,
 +        content.bottom().saturating_sub(1),
 +        content.x,
 +        content.width,
 +        "Esc / ? close",
 +        styles.footer,
 +    );
 +}
++
  fn create_modal_area(area: Rect, form: &CreateEventForm) -> Rect {
      if area.width < 52 || area.height < 16 {
          return area;
+     )
+ }
 +fn help_modal_area(area: Rect, row_count: usize) -> Rect {
 +    if area.width < 48 || area.height < 12 {
 +        return area;
 +    }
++
 +    let width = area.width.saturating_sub(4).min(66);
 +    let desired_height = u16::try_from(row_count)
 +        .unwrap_or(u16::MAX)
 +        .saturating_add(5);
 +    let height = desired_height.min(area.height.saturating_sub(4)).max(10);
 +    Rect::new(
 +        area.x + area.width.saturating_sub(width) / 2,
 +        area.y + area.height.saturating_sub(height) / 2,
 +        width,
 +        height,
 +    )
 +}
++
 +fn help_heading(view_mode: ViewMode) -> &'static str {
 +    match view_mode {
 +        ViewMode::Month => "Month / Week keys",
 +        ViewMode::Day => "Day keys",
 +    }
 +}
++
 +fn help_rows(view_mode: ViewMode) -> &'static [(&'static str, &'static str)] {
 +    match view_mode {
 +        ViewMode::Month => &[
 +            ("Arrows", "Move the selected date"),
 +            ("Digits", "Jump to a day, with quick two-digit refinement"),
 +            ("Weekdays", "Jump within the selected week"),
 +            ("Enter", "Open the focused day view"),
 +            ("+", "Create an event on the selected date"),
 +            ("Mouse", "Select a date; click it again to open"),
 +            ("?", "Close this help"),
 +            ("q", "Quit"),
 +        ],
 +        ViewMode::Day => &[
 +            ("Left/Right", "Move to the previous or next day"),
 +            ("Up/Down", "Select a local event"),
 +            ("Enter", "Edit the selected local event"),
 +            ("d", "Delete the selected local event"),
 +            ("+", "Create an event on this day"),
 +            ("Esc", "Return to month view"),
 +            ("?", "Close this help"),
 +            ("q", "Quit"),
 +        ],
 +    }
 +}
++
  fn recurrence_choice_modal_area(area: Rect) -> Rect {
      if area.width < 36 || area.height < 9 {
          return area;
          &title,
          styles.title,
      );
 +    render_title_hint(
 +        buf,
 +        layout.title_y,
 +        layout.area.x,
 +        layout.area.width,
 +        &title,
 +        styles.help_hint,
 +    );
+ }
  fn render_weekdays(layout: &MonthGridLayout, buf: &mut Buffer, styles: MonthGridStyles) {
          &title,
          styles.title,
      );
 +    render_title_hint(
 +        buf,
 +        layout.title_y,
 +        layout.area.x,
 +        layout.area.width,
 +        &title,
 +        styles.help_hint,
 +    );
+ }
  fn render_cell(
      buf.set_stringn(start, y, text, usize::from(width), style);
+ }
 +fn render_title_hint(buf: &mut Buffer, y: u16, x: u16, width: u16, title: &str, style: Style) {
 +    let hint_width = u16::try_from(HELP_HINT.len()).unwrap_or(u16::MAX);
 +    let title_width = u16::try_from(title.len()).unwrap_or(u16::MAX);
 +    if width <= hint_width.saturating_add(1) || title_width >= width {
 +        return;
 +    }
++
 +    let title_start = x + width.saturating_sub(title_width) / 2;
 +    let title_end = title_start.saturating_add(title_width);
 +    let hint_x = x + width.saturating_sub(hint_width).saturating_sub(1);
 +    if hint_x <= title_end.saturating_add(3) {
 +        return;
 +    }
++
 +    write_left(buf, y, hint_x, hint_width, HELP_HINT, style);
 +}
++
  fn write_left(buf: &mut Buffer, y: u16, x: u16, width: u16, text: &str, style: Style) {
      if width == 0 || !buf.area.contains((x, y).into()) {
          return;
          format!("{}{}{}", " ".repeat(left), text, " ".repeat(right))
+     }
 +    fn assert_line_has_centered_title(line: &str, width: usize, title: &str) {
 +        let start = width.saturating_sub(title.len()) / 2;
 +        assert_eq!(&line[start..start + title.len()], title);
 +    }
++
      fn source_metadata() -> SourceMetadata {
          SourceMetadata::fixture()
+     }
          let lines = buffer_lines(&buffer);
          assert_eq!(lines.len(), 20);
 -        assert_eq!(
 -            lines[0],
 -            "                   April 2026                    "
 -        );
 +        assert_line_has_centered_title(&lines[0], 49, "April 2026");
 +        assert!(lines[0].contains("?: Help"));
          assert_eq!(
              lines[1],
              "  Sun    Mon    Tue    Wed    Thu    Fri    Sat  "
          assert!(rendered.contains("30"));
+     }
 +    #[test]
 +    fn title_hint_renders_without_moving_month_title() {
 +        let app = AppState::new(date(2026, Month::April, 23));
 +        let rendered = render_app_to_string(&app, 84, 26);
 +        let lines = rendered.lines().collect::<Vec<_>>();
++
 +        assert_line_has_centered_title(lines[0], 84, "April 2026");
 +        assert!(lines[0].contains("?: Help"));
 +    }
++
      #[test]
      fn create_modal_renders_over_month_view() {
          let mut app = AppState::new(date(2026, Month::April, 23));
          assert!(rendered.contains("Enter select"));
+     }
 +    #[test]
 +    fn help_modal_shows_month_week_keys_in_month_mode() {
 +        let mut app = AppState::new(date(2026, Month::April, 23));
 +        app.apply(AppAction::OpenHelp);
++
 +        let rendered = render_app_to_string(&app, 84, 26);
++
 +        assert!(rendered.contains("Month / Week keys"));
 +        assert!(rendered.contains("Open the focused day view"));
 +        assert!(rendered.contains("Esc / ? close"));
 +        assert!(!rendered.contains("Delete the selected local event"));
 +    }
++
 +    #[test]
 +    fn help_modal_shows_day_keys_in_day_mode() {
 +        let mut app = AppState::new(date(2026, Month::April, 23));
 +        app.apply(AppAction::OpenDay);
 +        app.apply(AppAction::OpenHelp);
++
 +        let rendered = render_app_to_string(&app, 84, 26);
++
 +        assert!(rendered.contains("Day keys"));
 +        assert!(rendered.contains("Delete the selected local event"));
 +        assert!(rendered.contains("Move to the previous or next day"));
 +    }
++
      #[test]
      fn recurring_instances_render_without_repeat_marker() {
          let day = date(2026, Month::April, 23);
          let rendered = render_app_to_string(&app, 84, 14);
          let lines: Vec<_> = rendered.lines().collect();
 -        assert_eq!(lines[0], centered(84, "Thursday, April 23, 2026"));
 +        assert_line_has_centered_title(lines[0], 84, "Thursday, April 23, 2026");
 +        assert!(lines[0].contains("?: Help"));
          assert_eq!(
              lines[1],
              centered(84, "0 holidays | 0 events | Esc returns to month")