diff --git a/AGENTS.md b/AGENTS.md index 187f1fb..b8f2e05 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -83,6 +83,11 @@ front is the same two commands in a more useful order. - The digest guards the *rescan*, not the draw. ratatui diffs its buffer, so drawing every iteration is free; reading the tree every iteration is not - `notify` is deliberately not a dependency. Polling a tree of tens of small files on the 250ms tick is enough, and the reason is recorded on f6af387 - Cards come from `collect_ticket_items`, the same source `ls` uses, so there is no second parser. `TicketItem::path` exists for the detail view +- **The detail view scrolls on `pgup` and `pgdn`, not on up and down.** Up and down stay on the selection with the modal open, so a whole column can be read without closing it, and the modal follows. That is worth more than the two keys, which is why the scroll went elsewhere rather than taking them +- The scroll offset is clamped against the *wrapped* line count, from `Paragraph::line_count`, which is why `ratatui` carries the `unstable-rendered-line-info` feature. The paragraph wraps on words, so a clamp on the raw lines would stop short of the end or scroll past it into blank space. Counting the wrapping by hand would only agree with the widget until one of the two changed +- The clamp runs on the keypress and again in the draw. The terminal can be resized between the two, and a tick can shorten the ticket under a reader who is already at the end +- The offset resets when the selection moves and when the modal is closed, so a ticket opens at its top. It deliberately does *not* reset on a tick: an edit elsewhere in the tree must not throw the reader back to the top of what they are reading +- **The footer names only keys that work.** It read `↑↓ scroll` when nothing scrolled at all, which sends the reader looking for their own mistake. A UI that misdescribes itself is worse than one that is merely incomplete - The detail view renders with colour off. ratatui draws styled spans, so an escape sequence in a paragraph would be printed as literal bytes. `content_trim` and `format_comments_with` take the colour decision for that reason - Read only. Moving a card by keypress is a follow-up, deliberately kept out until the watch and render loop were solid diff --git a/Cargo.lock b/Cargo.lock index 6a7e0fb..53d8993 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -1494,7 +1494,7 @@ dependencies = [ [[package]] name = "worklane" -version = "0.7.0" +version = "0.7.1" dependencies = [ "anyhow", "assert_cmd", diff --git a/Cargo.toml b/Cargo.toml index 70dd649..e4a80c6 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "worklane" -version = "0.7.0" +version = "0.7.1" edition = "2024" [dependencies] @@ -9,7 +9,10 @@ anyhow = "1" uuid = { version = "1", features = ["v4"] } chrono = { version = "0.4", features = ["serde"] } libc = "0.2" -ratatui = "0.29" +# unstable-rendered-line-info for Paragraph::line_count, which is how the detail view +# knows where its text ends. Counting the wrapping by hand would only agree with the +# widget until one of us changed. +ratatui = { version = "0.29", features = ["unstable-rendered-line-info"] } crossterm = "0.28" [dev-dependencies] diff --git a/README.md b/README.md index 9aa74c6..7155fc5 100644 --- a/README.md +++ b/README.md @@ -5,7 +5,7 @@ Worklane is a local Kanban flow for agentic software development. ## Commands | Command | Description | |---------|-------------| -| `worklane` or `worklane tui` | Opens the board: four status columns, redrawn when the tree changes. Read only. Arrows or `hjkl` to move, `enter` for detail, `q` to quit | +| `worklane` or `worklane tui` | Opens the board: four status columns, redrawn when the tree changes. Read only. Arrows or `hjkl` to move, `enter` for detail, `pgup`/`pgdn` to scroll an open ticket, `q` to quit | | `worklane init` | Creates `.worklane/` with backlog, committed, reviewing, done directories | | `worklane add` | Creates a ticket in backlog with `--title`, `--description`, `--acceptance`, `--plan`, `--tags`, `--due`, `--owner`, `--priority` flags | | `worklane ls [status]` | Lists tickets, sorted by priority then title. Optional positional status, and `--priority <1-5>` | diff --git a/src/main.rs b/src/main.rs index 598d0a7..e00772f 100644 --- a/src/main.rs +++ b/src/main.rs @@ -141,6 +141,9 @@ fn run_tui(start: &std::path::Path) -> Result<()> { board.tick()?; terminal.draw(|frame| tui::draw(frame, &board))?; + // Taken after the draw, so a scroll measures the overlay that is on screen. + let screen = terminal.size()?; + // Bounded, so the tick still runs when nobody is typing. if !event::poll(tui::POLL)? { continue; @@ -166,8 +169,13 @@ fn run_tui(start: &std::path::Path) -> Result<()> { KeyCode::Enter | KeyCode::Char(' ') => board.toggle_detail(), KeyCode::Left | KeyCode::Char('h') => board.select_column(-1), KeyCode::Right | KeyCode::Char('l') => board.select_column(1), + // Up and down stay on the selection, open detail view or not, so a + // column can be read through without closing the modal. Scrolling the + // open ticket is a page at a time. KeyCode::Up | KeyCode::Char('k') => board.select_card(-1), KeyCode::Down | KeyCode::Char('j') => board.select_card(1), + KeyCode::PageUp => board.scroll_detail(-1, screen), + KeyCode::PageDown => board.scroll_detail(1, screen), _ => {} } } diff --git a/src/tui.rs b/src/tui.rs index 6254bf6..5b768ff 100644 --- a/src/tui.rs +++ b/src/tui.rs @@ -12,7 +12,7 @@ use std::path::{Path, PathBuf}; use std::time::{Duration, SystemTime}; use anyhow::Result; -use ratatui::layout::{Constraint, Direction, Layout, Rect}; +use ratatui::layout::{Constraint, Direction, Layout, Margin, Rect, Size}; use ratatui::style::{Modifier, Style}; use ratatui::text::{Line, Span}; use ratatui::widgets::{Block, Borders, Clear, Paragraph, Wrap}; @@ -37,6 +37,8 @@ pub struct Board { pub card: usize, /// The body and comments of the selected ticket, when the detail view is open. pub detail: Option, + /// First visible line of the detail view, counted in wrapped lines. + pub offset: u16, pub should_quit: bool, worklane_dir: PathBuf, digest: u64, @@ -49,6 +51,7 @@ impl Board { column: 0, card: 0, detail: None, + offset: 0, should_quit: false, worklane_dir: worklane_dir.to_path_buf(), digest: 0, @@ -87,6 +90,9 @@ impl Board { self.clamp(); // The selected ticket may have moved or gone, so the open detail follows it. + // The scroll offset stays where the reader put it: an edit elsewhere in the tree + // should not throw them back to the top of what they are reading. A ticket that + // got shorter is caught by the clamp in the draw. if self.detail.is_some() { self.detail = self.selected().map(detail_of); } @@ -145,13 +151,38 @@ impl Board { /// Open the detail view on the selected card, or close it if it is already open. pub fn toggle_detail(&mut self) { + self.offset = 0; self.detail = match self.detail { Some(_) => None, None => self.selected().map(detail_of), }; } + /// Scroll the open detail view by whole screenfuls, one line kept for overlap. + /// + /// Up and down move the selection, so the scroll is on PageUp and PageDown. That is + /// worth keeping either way: with the modal open, up and down step through the + /// tickets and the modal follows, so a column can be read without closing it. + /// + /// Clamped against the wrapped text rather than the raw lines, so the last page ends + /// with the ticket instead of running on into blank space, and against zero at the + /// top. The screen is asked for because both ends belong to the overlay, which only + /// the draw otherwise measures. + pub fn scroll_detail(&mut self, pages: isize, screen: Size) { + let Some(detail) = &self.detail else { return }; + + let text = detail_text_area(Rect::new(0, 0, screen.width, screen.height)); + // A screenful less a line, so the eye has something to land on after the jump. + let step = text.height.saturating_sub(1).max(1) as isize; + let last = last_offset(detail, text) as isize; + + self.offset = (self.offset as isize + pages.saturating_mul(step)).clamp(0, last) as u16; + } + fn refresh_detail(&mut self) { + // A newly selected ticket starts at its top, not partway down where the last one + // was left. + self.offset = 0; if self.detail.is_some() { self.detail = self.selected().map(detail_of); } @@ -243,7 +274,7 @@ pub fn draw(frame: &mut Frame, board: &Board) { draw_footer(frame, board, rows[1]); if let Some(detail) = &board.detail { - draw_detail(frame, detail, area); + draw_detail(frame, detail, board.offset, area); } } @@ -329,7 +360,7 @@ fn card_lines(ticket: &TicketItem, selected: bool) -> Vec> { fn draw_footer(frame: &mut Frame, board: &Board, area: Rect) { let keys = match board.detail { - Some(_) => " ↑↓ scroll enter close q quit ", + Some(_) => " ←→↑↓ select pgup/pgdn scroll enter close q quit ", None => " ←→ column ↑↓ card enter detail q quit ", }; @@ -339,16 +370,47 @@ fn draw_footer(frame: &mut Frame, board: &Board, area: Rect) { ); } -fn draw_detail(frame: &mut Frame, detail: &str, area: Rect) { - // Inset, so the board stays visible around the edges and the overlay reads as one. +/// Where the detail overlay sits in the frame. +/// +/// Inset, so the board stays visible around the edges and the overlay reads as one. +fn detail_overlay(area: Rect) -> Rect { let width = area.width.saturating_sub(area.width / 5).max(20); let height = area.height.saturating_sub(area.height / 6).max(6); - let overlay = Rect { + Rect { x: area.x + (area.width.saturating_sub(width)) / 2, y: area.y + (area.height.saturating_sub(height)) / 2, width: width.min(area.width), height: height.min(area.height), - }; + } +} + +/// The part of the overlay that holds text: the border takes a row and a column on +/// either side, and the title sits on the top border rather than below it. +fn detail_text_area(area: Rect) -> Rect { + detail_overlay(area).inner(Margin::new(1, 1)) +} + +/// The furthest the detail view can scroll: the last screenful, and no further. +/// +/// Measured by the widget rather than counted by hand, since it wraps on words. A clamp +/// on the raw lines would stop short of the end on a wrapped ticket, and one that +/// ignored the wrapping the other way would scroll past it into blank space. +fn last_offset(detail: &str, text: Rect) -> u16 { + let wrapped = Paragraph::new(detail) + .wrap(Wrap { trim: false }) + .line_count(text.width); + + u16::try_from(wrapped) + .unwrap_or(u16::MAX) + .saturating_sub(text.height) +} + +fn draw_detail(frame: &mut Frame, detail: &str, offset: u16, area: Rect) { + let overlay = detail_overlay(area); + + // Clamped here as well as on the keypress: the terminal may have been resized since, + // and a ticket read to its end can grow shorter under a tick. + let offset = offset.min(last_offset(detail, detail_text_area(area))); let block = Block::default() .borders(Borders::ALL) @@ -362,7 +424,8 @@ fn draw_detail(frame: &mut Frame, detail: &str, area: Rect) { frame.render_widget( Paragraph::new(detail.to_string()) .block(block) - .wrap(Wrap { trim: false }), + .wrap(Wrap { trim: false }) + .scroll((offset, 0)), overlay, ); } @@ -397,6 +460,22 @@ mod tests { path } + /// A section of numbered lines, so a test can say which of them is on screen. + /// + /// Long enough not to fit any overlay the tests draw, which is true of every real + /// ticket in the repo as well. + fn long_section(lines: usize) -> String { + let body: String = (1..=lines).map(|n| format!("Line {n:03}\n")).collect(); + format!("\n## Notes\n{body}") + } + + /// The screen the scrolling tests draw on, so the keypress and the draw measure the + /// same overlay. + const SCREEN: Size = Size { + width: 120, + height: 20, + }; + /// The rendered buffer as lines of text, escapes and styling dropped. fn render(board: &Board, width: u16, height: u16) -> Vec { let mut terminal = Terminal::new(TestBackend::new(width, height)).unwrap(); @@ -658,6 +737,219 @@ mod tests { assert!(!board.tick().unwrap()); } + /// The reported bug: a ticket longer than the overlay had no way to be read past its + /// first screenful, comments included. + #[test] + fn paging_down_reaches_the_end_of_a_long_ticket() { + let dir = board_dir(); + let uuid = "11111111-0000-4000-8000-000000000000"; + write_ticket(&dir, "backlog", uuid, "First one", &long_section(60)); + + let comments = dir.join("comments").join(uuid); + std::fs::create_dir_all(&comments).unwrap(); + std::fs::write( + comments.join("20260821_120000_000000.md"), + "**Comment**\nThe last word.\n\n**Author**: bob\n**Time**: 2026-08-21 12:00:00\n", + ) + .unwrap(); + + let mut board = Board::new(&dir).unwrap(); + board.toggle_detail(); + + let top = render(&board, SCREEN.width, SCREEN.height).join("\n"); + assert!(top.contains("A description."), "not at the top:\n{top}"); + assert!(!top.contains("Line 060"), "the fixture is too short:\n{top}"); + + // More pages than the ticket has, since the clamp is what stops it. + for _ in 0..20 { + board.scroll_detail(1, SCREEN); + } + + let end = render(&board, SCREEN.width, SCREEN.height).join("\n"); + assert!(end.contains("Line 060"), "the end is out of reach:\n{end}"); + assert!(end.contains("The last word."), "the comments are out of reach:\n{end}"); + assert!(!end.contains("A description."), "nothing scrolled:\n{end}"); + } + + /// The end of the scroll is the end of the text, not blank space past it, and the top + /// of it is the top of the ticket. + #[test] + fn the_scroll_offset_stops_at_both_ends() { + let dir = board_dir(); + write_ticket( + &dir, + "backlog", + "11111111-0000-4000-8000-000000000000", + "First one", + &long_section(60), + ); + + let mut board = Board::new(&dir).unwrap(); + board.toggle_detail(); + + for _ in 0..20 { + board.scroll_detail(1, SCREEN); + } + let settled = board.offset; + assert!(settled > 0, "a long ticket did not scroll at all"); + + board.scroll_detail(1, SCREEN); + assert_eq!(board.offset, settled, "the offset ran past the end"); + + // The last screenful is full: text on the bottom row of the overlay, not the + // blank space a clamp on the raw lines would have left there. + let lines = render(&board, SCREEN.width, SCREEN.height); + let text = detail_text_area(Rect::new(0, 0, SCREEN.width, SCREEN.height)); + let bottom: String = lines[(text.bottom() - 1) as usize] + .chars() + .skip(text.x as usize) + .take(text.width as usize) + .collect(); + assert!( + !bottom.trim().is_empty(), + "the last page ran into blank space:\n{}", + lines.join("\n") + ); + + board.scroll_detail(-40, SCREEN); + assert_eq!(board.offset, 0, "the offset went above the top"); + } + + /// A ticket that fits has nothing to scroll, so the keys do nothing to it. + #[test] + fn a_ticket_shorter_than_the_overlay_does_not_scroll() { + let dir = board_dir(); + write_ticket(&dir, "backlog", "11111111-0000-4000-8000-000000000000", "First one", ""); + + // Tall enough that the whole ticket is on screen at once. + let roomy = Size { + width: 120, + height: 60, + }; + + let mut board = Board::new(&dir).unwrap(); + board.toggle_detail(); + let before = render(&board, roomy.width, roomy.height); + + board.scroll_detail(1, roomy); + assert_eq!(board.offset, 0); + assert_eq!(render(&board, roomy.width, roomy.height), before); + } + + /// Up and down still move the selection with the detail view open, and the modal + /// follows, which is the reason the scroll went on pgup and pgdn in the first place. + #[test] + fn the_selection_still_moves_under_an_open_detail_view() { + let dir = board_dir(); + write_ticket(&dir, "backlog", "11111111-0000-4000-8000-000000000000", "Alpha", ""); + write_ticket(&dir, "backlog", "22222222-0000-4000-8000-000000000000", "Beta", ""); + + let mut board = Board::new(&dir).unwrap(); + board.toggle_detail(); + // By id rather than title: the body leaves the title to the caller that prints + // the heading, so the detail text does not carry it. + assert!(board.detail.clone().unwrap().contains("11111111"), "{:?}", board.detail); + + board.select_card(1); + assert_eq!(board.selected().map(|t| t.title.clone()), Some("Beta".to_string())); + assert!(board.detail.clone().unwrap().contains("22222222"), "{:?}", board.detail); + } + + /// A newly selected ticket starts at its own top, not where the last one was left. + #[test] + fn the_scroll_offset_resets_when_the_selection_moves() { + let dir = board_dir(); + let long = long_section(60); + write_ticket(&dir, "backlog", "11111111-0000-4000-8000-000000000000", "Alpha", &long); + write_ticket(&dir, "backlog", "22222222-0000-4000-8000-000000000000", "Beta", &long); + write_ticket(&dir, "committed", "33333333-0000-4000-8000-000000000000", "Gamma", &long); + + let mut board = Board::new(&dir).unwrap(); + board.toggle_detail(); + + board.scroll_detail(1, SCREEN); + assert!(board.offset > 0); + board.select_card(1); + assert_eq!(board.offset, 0, "the next card opened partway down"); + + board.scroll_detail(1, SCREEN); + assert!(board.offset > 0); + board.select_column(1); + assert_eq!(board.offset, 0, "the next column opened partway down"); + } + + #[test] + fn the_scroll_offset_resets_when_the_detail_view_is_reopened() { + let dir = board_dir(); + write_ticket( + &dir, + "backlog", + "11111111-0000-4000-8000-000000000000", + "First one", + &long_section(60), + ); + + let mut board = Board::new(&dir).unwrap(); + board.toggle_detail(); + board.scroll_detail(1, SCREEN); + assert!(board.offset > 0); + + board.toggle_detail(); + board.toggle_detail(); + assert_eq!(board.offset, 0, "the ticket reopened where it was left"); + } + + /// An edit elsewhere in the tree must not throw the reader back to the top. + #[test] + fn a_tick_leaves_the_scroll_where_the_reader_put_it() { + let dir = board_dir(); + let uuid = "11111111-0000-4000-8000-000000000000"; + write_ticket(&dir, "backlog", uuid, "First one", &long_section(60)); + + let mut board = Board::new(&dir).unwrap(); + board.toggle_detail(); + board.scroll_detail(1, SCREEN); + let offset = board.offset; + + let comments = dir.join("comments").join(uuid); + std::fs::create_dir_all(&comments).unwrap(); + std::fs::write( + comments.join("20260821_120000_000000.md"), + "**Comment**\nA late note.\n\n**Author**: bob\n**Time**: 2026-08-21 12:00:00\n", + ) + .unwrap(); + + assert!(board.tick().unwrap(), "the tick saw no change"); + assert_eq!(board.offset, offset); + } + + /// The footer is what sent the reporter looking for their own mistake, so it has to + /// name the keys that exist and only those. + #[test] + fn the_footer_names_the_keys_that_work() { + let dir = board_dir(); + write_ticket( + &dir, + "backlog", + "11111111-0000-4000-8000-000000000000", + "First one", + &long_section(60), + ); + + let mut board = Board::new(&dir).unwrap(); + + let closed = render(&board, SCREEN.width, SCREEN.height).join("\n"); + assert!(closed.contains("↑↓ card"), "{closed}"); + assert!(closed.contains("enter detail"), "{closed}"); + assert!(!closed.contains("scroll"), "a scroll offered with nothing open:\n{closed}"); + + board.toggle_detail(); + let open = render(&board, SCREEN.width, SCREEN.height).join("\n"); + assert!(open.contains("pgup/pgdn scroll"), "{open}"); + assert!(open.contains("select"), "{open}"); + assert!(open.contains("enter close"), "{open}"); + } + /// The board and the listing draw from the same palette, so a colour cannot exist /// for one and not the other. The enum makes that a compile error; this pins the /// mapping itself.