Render GFM Task Lists using emoji, not plain text (#9)

List starting with `[ ]` and `[x]` can be displayed nicer.

Author: ashb

crates/reviewq-app/src/config.default.toml

@@ -175,6 +175,11 @@ theme = "dark"
 # draw, or with "" to show the branch name on its own.
 #   [output.icons]
 #   branch = "->"
+#   gfm_task_checked = "✅"
+#   gfm_task_unchecked = "☐"
+# Task-list markers are padded to the wider marker's terminal-cell width so
+# their text aligns. Use alternatives such as "[x]" and "[ ]" if your font
+# displays the defaults at different widths.
 
 # The glyphs before a GFM alert's heading in a PR description — `> [!NOTE]`
 # and its four siblings. Each defaults to a Nerd Font codepoint, which a

crates/reviewq-app/src/config.rs

@@ -371,14 +371,18 @@ impl Marks {
 /// The glyphs that label a fact rather than a decision.
 ///
 /// Separate from [`Marks`], which says what *you* did to a PR; these say what
-/// the PR *is*. Configurable for the same reason: the default is a Nerd Font
-/// codepoint, and a terminal without a patched font draws a box. Set one to an
+/// the PR *is*. Some defaults are Nerd Font codepoints, and a terminal
+/// without a patched font draws a box. Set one to an
 /// empty string to drop the glyph and keep the value it labels.
 #[derive(Debug, Clone, PartialEq, Eq, Deserialize, Serialize)]
 #[serde(default)]
 pub struct Icons {
     /// Before the branch a PR would merge into.
     pub branch: String,
+    /// A checked GFM task-list item.
+    pub gfm_task_checked: String,
+    /// An unchecked GFM task-list item.
+    pub gfm_task_unchecked: String,
     /// Before a GFM alert's heading. `[output.icons.alert]` in TOML.
     pub alert: AlertIcons,
 }
@@ -388,6 +392,8 @@ impl Default for Icons {
         Self {
             // U+F419, Nerd Fonts' git-branch.
             branch: "\u{f419}".into(),
+            gfm_task_checked: "✅".into(),
+            gfm_task_unchecked: "☐".into(),
             alert: AlertIcons::default(),
         }
     }
@@ -939,6 +945,29 @@ mod tests {
         assert_eq!(none.output.icons.branch, "", "dropping it is allowed");
     }
 
+    #[test]
+    fn gfm_task_icons_can_be_overridden_independently() {
+        for (setting, checked, unchecked) in [
+            ("", "✅", "☐"),
+            ("gfm_task_checked = '[x]'", "[x]", "☐"),
+            ("gfm_task_unchecked = '[ ]'", "✅", "[ ]"),
+            ("gfm_task_checked = ''\ngfm_task_unchecked = ''", "", ""),
+        ] {
+            let config: Config =
+                toml::from_str(&minimal(&format!("[output.icons]\n{setting}"))).expect("parses");
+            assert_eq!(config.output.icons.gfm_task_checked, checked);
+            assert_eq!(config.output.icons.gfm_task_unchecked, unchecked);
+        }
+    }
+
+    #[test]
+    fn gfm_task_icons_reject_non_string_values() {
+        for key in ["gfm_task_checked", "gfm_task_unchecked"] {
+            let result = toml::from_str::<Config>(&minimal(&format!("[output.icons]\n{key} = 42")));
+            assert!(result.is_err(), "{key}");
+        }
+    }
+
     #[test]
     fn each_alert_icon_defaults_to_a_nerd_font_glyph_and_is_replaceable_alone() {
         let config: Config = toml::from_str(&minimal("")).expect("parses");

crates/reviewq-tui/src/ansi.rs

@@ -16,7 +16,7 @@
 //! needed is a handful of sequences, and the caller may be writing to a pipe, a
 //! file, or a string in a test rather than to a terminal at all.
 
-use ratatui::buffer::Buffer;
+use ratatui::buffer::{Buffer, Cell, CellWidth as _};
 use ratatui::layout::Rect;
 use ratatui::style::{Color, Modifier};
 use ratatui::text::Line;
@@ -32,8 +32,26 @@ use crate::theme::{Mode, Rgb, Theme};
 /// the tables, the bullets and the wrapping are in the characters, not in the
 /// styling.
 pub fn markdown(md: &str, mode: Mode, width: u16, colour: bool) -> String {
+    markdown_with_icons(
+        md,
+        mode,
+        width,
+        colour,
+        &reviewq_app::config::Icons::default(),
+    )
+}
+
+/// Render Markdown with the configured glyphs for GFM task lists.
+pub fn markdown_with_icons(
+    md: &str,
+    mode: Mode,
+    width: u16,
+    colour: bool,
+    icons: &reviewq_app::config::Icons,
+) -> String {
     let theme = Theme::new(mode);
-    let md = reflow_wide_tables(md, width.max(20));
+    let md = crate::gfm_task_list::render_markers(md, icons);
+    let md = reflow_wide_tables(&md, width.max(20));
     let lines: Vec<Line<'_>> = tui_markdown::from_str(&md)
         .lines
         .into_iter()
@@ -325,6 +343,19 @@ pub(crate) fn buffer(buffer: &Buffer, theme: &Theme, colour: bool) -> String {
     out
 }
 
+pub(crate) fn row_cells(buffer: &Buffer, row: u16) -> impl Iterator<Item = (u16, &Cell)> {
+    let mut col = 0;
+    std::iter::from_fn(move || {
+        if col >= buffer.area.width {
+            return None;
+        }
+        let cell = &buffer[(col, row)];
+        let current = col;
+        col += cell.cell_width().max(1);
+        Some((current, cell))
+    })
+}
+
 /// One row of the buffer, its trailing blank cells dropped — a terminal has no
 /// use for a line padded to the full width, and a reader copying the output has
 /// less.
@@ -336,8 +367,7 @@ fn push_row(out: &mut String, buffer: &Buffer, row: u16, theme: &Theme, colour:
         .map_or(0, |col| col + 1);
 
     let mut open: Option<Style> = None;
-    for col in 0..last {
-        let cell = &buffer[(col, row)];
+    for (_, cell) in row_cells(buffer, row).take_while(|(col, _)| *col < last) {
         let style = Style {
             fg: match cell.fg {
                 Color::Rgb(r, g, b) => Rgb { r, g, b },
@@ -505,6 +535,50 @@ mod tests {
         assert_eq!(rendered, "Short.\n");
     }
 
+    #[test]
+    fn wide_glyphs_preserve_spacing_in_plain_and_coloured_output() {
+        for input in ["✅done", "✅ done", "✅  done", "✅☐界done", "done✅"] {
+            for colour in [false, true] {
+                let rendered = markdown(input, Mode::Dark, 60, colour);
+                assert_eq!(strip_escapes(&rendered), format!("{input}\n"));
+            }
+        }
+    }
+
+    #[test]
+    fn configured_task_markers_align_the_item_text() {
+        for (checked, unchecked, expected) in [
+            ("✅", "☐", "- ✅ Done\n- ☐  Todo\n"),
+            ("✓", "界", "- ✓  Done\n- 界 Todo\n"),
+            ("[x]", "[ ]", "- [x] Done\n- [ ] Todo\n"),
+            ("", "", "- Done\n- Todo\n"),
+        ] {
+            let icons = reviewq_app::config::Icons {
+                gfm_task_checked: checked.into(),
+                gfm_task_unchecked: unchecked.into(),
+                ..Default::default()
+            };
+            for colour in [false, true] {
+                let rendered =
+                    markdown_with_icons("- [x] Done\n- [ ] Todo\n", Mode::Dark, 60, colour, &icons);
+                assert_eq!(strip_escapes(&rendered), expected);
+            }
+        }
+    }
+
+    #[test]
+    fn github_task_lists_render_as_status_glyphs() {
+        let input = "- [ ] Waiting\n- [x] Done lower\n- [X] Done upper\n- [x]ylophone\n\n```text\n- [x] literal\n```\n";
+
+        let rendered = markdown(input, Mode::Dark, 60, false);
+
+        assert!(rendered.contains("- ☐  Waiting"), "{rendered:?}");
+        assert!(rendered.contains("- ✅ Done lower"), "{rendered:?}");
+        assert!(rendered.contains("- ✅ Done upper"), "{rendered:?}");
+        assert!(rendered.contains("- [x]ylophone"), "{rendered:?}");
+        assert!(rendered.contains("- [x] literal"), "{rendered:?}");
+    }
+
     #[test]
     fn a_table_too_wide_for_the_page_becomes_a_list() {
         // 183 columns of two-cell prose is not a table anybody can read in a

crates/reviewq-tui/src/app.rs

@@ -3902,8 +3902,8 @@ mod loop_tests {
         let area = buffer.area();
         (0..area.height)
             .map(|y| {
-                (0..area.width)
-                    .map(|x| buffer[(x, y)].symbol())
+                crate::ansi::row_cells(buffer, y)
+                    .map(|(_, cell)| cell.symbol())
                     .collect::<String>()
                     .trim_end()
                     .to_string()

crates/reviewq-tui/src/docs.rs

@@ -77,8 +77,8 @@ mod tests {
             let (buffer, _) = draw(shot, WIDTH, Mode::Dark);
             println!("\n=== {} ===", shot.name);
             for y in 0..shot.height {
-                let row: String = (0..WIDTH)
-                    .map(|x| buffer[(x, y)].symbol())
+                let row: String = crate::ansi::row_cells(&buffer, y)
+                    .map(|(_, cell)| cell.symbol())
                     .collect::<String>()
                     .trim_end()
                     .to_string();

crates/reviewq-tui/src/gfm_task_list.rs

@@ -0,0 +1,76 @@
+use ratatui::buffer::CellWidth as _;
+use reviewq_app::config::Icons;
+
+pub(crate) fn render_markers(markdown: &str, icons: &Icons) -> String {
+    let mut rendered = String::with_capacity(markdown.len());
+    let mut fence = None;
+    let width = icons
+        .gfm_task_checked
+        .cell_width()
+        .max(icons.gfm_task_unchecked.cell_width());
+
+    for line in markdown.split_inclusive('\n') {
+        let trimmed = line.trim_start();
+        if let Some((character, length)) = fence {
+            rendered.push_str(line);
+            if closes_fence(trimmed, character, length) {
+                fence = None;
+            }
+            continue;
+        }
+
+        if let Some(opened) = opens_fence(trimmed) {
+            fence = Some(opened);
+            rendered.push_str(line);
+            continue;
+        }
+
+        let indent = line.len() - trimmed.len();
+        let remainder = trimmed.get(5..).unwrap_or_default();
+        let marker = if remainder.chars().next().is_none_or(char::is_whitespace) {
+            match trimmed.get(..5) {
+                Some("- [ ]") => Some(&icons.gfm_task_unchecked),
+                Some(candidate) if candidate.eq_ignore_ascii_case("- [x]") => {
+                    Some(&icons.gfm_task_checked)
+                }
+                _ => None,
+            }
+        } else {
+            None
+        };
+        if let Some(marker) = marker {
+            rendered.push_str(&line[..indent]);
+            rendered.push_str("- ");
+            rendered.push_str(marker);
+            rendered.extend(std::iter::repeat_n(
+                ' ',
+                usize::from(width - marker.cell_width()),
+            ));
+            rendered.push_str(&trimmed[5..]);
+        } else {
+            rendered.push_str(line);
+        }
+    }
+
+    rendered
+}
+
+fn opens_fence(line: &str) -> Option<(char, usize)> {
+    let character = line.chars().next()?;
+    if !matches!(character, '`' | '~') {
+        return None;
+    }
+    let length = line
+        .chars()
+        .take_while(|candidate| *candidate == character)
+        .count();
+    (length >= 3).then_some((character, length))
+}
+
+fn closes_fence(line: &str, character: char, opening_length: usize) -> bool {
+    let length = line
+        .chars()
+        .take_while(|candidate| *candidate == character)
+        .count();
+    length >= opening_length && line[length..].trim().is_empty()
+}

crates/reviewq-tui/src/lib.rs

@@ -14,6 +14,7 @@ mod app;
 #[cfg(test)]
 mod docs;
 mod fixture;
+mod gfm_task_list;
 mod mouse;
 mod svg;
 mod ui;
@@ -37,6 +38,7 @@ use ratatui::backend::CrosstermBackend;
 use reviewq_app::config::Config;
 
 pub use ansi::markdown as markdown_to_ansi;
+pub use ansi::markdown_with_icons as markdown_to_ansi_with_icons;
 
 /// Draw one of the documentation's screens, as text a terminal can print.
 ///

crates/reviewq-tui/src/snapshots/reviewq_tui__ui__tests__the_description_renders_as_markdown_with_template_comments_stripped.snap

@@ -21,8 +21,8 @@ reviewq  2 on the queue
 │                                           ││                                                     █
 │                                           ││ Adds a deferrable flag to S3KeySensor.              █
 │                                           ││                                                     █
-│                                           ││ - [x] Tests added                                   █
-│                                           ││ - [ ] Docs updated                                  █
+│                                           ││ - ✅ Tests added                                    █
+│                                           ││ - ☐  Docs updated                                   █
 │                                           ││                                                     █
 │                                           ││ ```python                                           █
 │                                           ││ sensor = S3KeySensor(deferrable=True)               █

crates/reviewq-tui/src/snapshots/reviewq_tui__ui__tests__the_detail_pane_shows_five_recent_activity_events.snap

@@ -1,5 +1,6 @@
 ---
 source: crates/reviewq-tui/src/ui.rs
+assertion_line: 2057
 expression: shown
 ---
 reviewq  9 on the queue
@@ -32,12 +33,12 @@ reviewq  9 on the queue
 │                                           ││ too, gated on the new flag rather than a second     █
 │                                           ││ operator class.                                     █
 │                                           ││                                                     █
-│                                           ││ - [x] Trigger and sensor share one poke             █
+│                                           ││ - ✅ Trigger and sensor share one poke              █
 │                                           ││ implementation                                      █
-│                                           ││ - [x] Tests for both modes                          █
-│                                           ││ - [x] Backport label added — this lands on 3.1 as   █
+│                                           ││ - ✅ Tests for both modes                           █
+│                                           ││ - ✅ Backport label added — this lands on 3.1 as    █
 │                                           ││ well as main                                        █
-│                                           ││ - [ ] Docs updated — waiting on #70344              █
+│                                           ││ - ☐  Docs updated — waiting on #70344               █
 │                                           ││                                                     █
 │                                           ││ Follow-up to the executor work in #69982.           █
 │                                           ││                                                     █

crates/reviewq-tui/src/snapshots/reviewq_tui__ui__tests__the_queue_and_the_selected_prs_detail_both_render.snap

@@ -21,6 +21,6 @@ reviewq  2 on the queue
 │                                           ││                                                     ║
 │                                           ││ Adds a deferrable flag to S3KeySensor.              ║
 │                                           ││                                                     ║
-│                                           ││ - [x] Tests added                                   ║
+│                                           ││ - ✅ Tests added                                    ║
 ╰───────────────────────────────────────────╯╰─────────────────────────────────────────────────────╯
 jk move   ⏎ review   d done   z snooze   ? / h keys   Esc quit