diff --git a/AGENTS.md b/AGENTS.md index b8f2e05..6e4efe5 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -87,6 +87,10 @@ front is the same two commands in a more useful order. - 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 +- **Columns scroll to keep the selected card in view.** `Board::offsets` holds one offset per column, parallel to `columns` and resized in step by `reload`, so a column you leave stays where it was. The keypress aligns the focused column via `follow_selection(screen)`, taking the screen size for the same reason `scroll_detail` does: the visible height belongs to the terminal, which only the caller measures between draws +- Card heights are measured on `card_lines`, never assumed, on both the keypress and the draw side (`card_height`, and the `starts` vec as the cards are built). An alignment that trusted a fixed card height would drift from the renderer the first time the card changed shape +- The draw aligns the focused column again on its own geometry, so a resize between keypress and frame cannot hide the selection, and caps every column against blank space past its last card. The stored value may go stale after a tick shrinks the column; that is fine, because what is drawn is corrected immediately and the next navigation writes the correction back +- Entering another column follows the selection rather than resetting to its top. The card index carries across columns, so a reset would open the column with the highlight below the fold whenever it was — the opposite of the detail view's reset-on-selection-move, where each ticket genuinely starts at its own top - **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 53d8993..deb925e 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -1494,7 +1494,7 @@ dependencies = [ [[package]] name = "worklane" -version = "0.7.1" +version = "0.7.2" dependencies = [ "anyhow", "assert_cmd", diff --git a/Cargo.toml b/Cargo.toml index e4a80c6..6999549 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "worklane" -version = "0.7.1" +version = "0.7.2" edition = "2024" [dependencies] diff --git a/src/main.rs b/src/main.rs index e00772f..01859d7 100644 --- a/src/main.rs +++ b/src/main.rs @@ -167,13 +167,13 @@ fn run_tui(start: &std::path::Path) -> Result<()> { None => board.should_quit = true, }, 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), + KeyCode::Left | KeyCode::Char('h') => board.select_column(-1, screen), + KeyCode::Right | KeyCode::Char('l') => board.select_column(1, screen), // 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::Up | KeyCode::Char('k') => board.select_card(-1, screen), + KeyCode::Down | KeyCode::Char('j') => board.select_card(1, screen), 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 5b768ff..32f7e40 100644 --- a/src/tui.rs +++ b/src/tui.rs @@ -35,6 +35,9 @@ pub struct Board { pub columns: Vec, pub column: usize, pub card: usize, + /// First visible line of each column, counted in card lines. Parallel to + /// `columns`, so a tick that reshapes the board resizes it in step. + pub offsets: Vec, /// 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. @@ -50,6 +53,7 @@ impl Board { columns: Vec::new(), column: 0, card: 0, + offsets: Vec::new(), detail: None, offset: 0, should_quit: false, @@ -86,6 +90,11 @@ impl Board { }) .collect(); + // One scroll position per column, kept by index. A tick that adds or removes + // columns is not a thing statuses do, but the resize keeps the two in step + // regardless; `resize` both pads and truncates. + self.offsets.resize(self.columns.len(), 0); + self.digest = digest(&self.worklane_dir); self.clamp(); @@ -123,7 +132,7 @@ impl Board { } /// Move between columns, keeping the card index where it can land. - pub fn select_column(&mut self, delta: isize) { + pub fn select_column(&mut self, delta: isize, screen: Size) { if self.columns.is_empty() { return; } @@ -132,10 +141,15 @@ impl Board { let next = (self.column as isize + delta).clamp(0, last); self.column = next as usize; self.clamp(); + // Entering a column shows the card the selection landed on rather than + // resetting to its top: the card index carries across columns, so a reset + // would open the column with the highlight below the fold whenever it was. + // The rest of the place the column was left in is kept. + self.follow_selection(screen); self.refresh_detail(); } - pub fn select_card(&mut self, delta: isize) { + pub fn select_card(&mut self, delta: isize, screen: Size) { let count = match self.columns.get(self.column) { Some(column) => column.tickets.len(), None => return, @@ -146,9 +160,42 @@ impl Board { let next = (self.card as isize + delta).clamp(0, count as isize - 1); self.card = next as usize; + self.follow_selection(screen); self.refresh_detail(); } + /// Move the focused column's offset so the selected card sits inside the view. + /// + /// Measured on the same card lines the draw renders, so the two cannot disagree + /// about how tall a card is. The screen comes in because the visible height + /// belongs to the terminal, which only the caller measures between draws — the + /// same reason `scroll_detail` takes it. The draw aligns the focused column again + /// on its own geometry, so a resize between this and the next frame is corrected + /// there; what is stored here is the place an unfocused column keeps. + fn follow_selection(&mut self, screen: Size) { + let Some(column) = self.columns.get(self.column) else { + return; + }; + let Some(slot) = self.offsets.get_mut(self.column) else { + return; + }; + + let start: u16 = column + .tickets + .get(..self.card) + .map(|before| before.iter().map(card_height).sum()) + .unwrap_or(0); + let end = start + + column + .tickets + .get(self.card) + .map(card_height) + .unwrap_or(0); + let total: u16 = column.tickets.iter().map(card_height).sum(); + + *slot = aligned_offset(*slot, start, end, column_text_height(screen), total); + } + /// 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; @@ -312,17 +359,75 @@ fn draw_columns(frame: &mut Frame, board: &Board, area: Rect) { Color::Grey.into() })); + // The cards go into one paragraph, and where each card starts is recorded as + // it is added: the scroll has to measure what is really drawn, not assume a + // card size the renderer has to agree with. let mut lines: Vec = Vec::new(); + let mut starts: Vec = Vec::new(); for (card, ticket) in column.tickets.iter().enumerate() { let selected = focused && card == board.card; + starts.push(lines.len() as u16); lines.extend(card_lines(ticket, selected)); } + let total = lines.len() as u16; + let text = areas[index].inner(Margin::new(1, 1)); + let stored = board.offsets.get(index).copied().unwrap_or(0); + + // The focused column follows its selection here as well as on the keypress: + // the terminal can be resized between the two, and a tick can shorten the + // column under a reader who is already at the end. An unfocused column keeps + // the place it was left in, capped so it cannot show blank space past its + // last card. + let offset = if focused { + let start = starts.get(board.card).copied().unwrap_or(total); + let end = starts.get(board.card + 1).copied().unwrap_or(total); + aligned_offset(stored, start, end, text.height, total) + } else { + stored.min(total.saturating_sub(text.height)) + }; // An empty status is an empty column, not a column that is not there. - frame.render_widget(Paragraph::new(lines).block(block), areas[index]); + frame.render_widget( + Paragraph::new(lines) + .block(block) + .scroll((offset, 0)), + areas[index], + ); } } +/// The lines one card occupies, measured the way `draw_columns` renders it. +fn card_height(ticket: &TicketItem) -> u16 { + card_lines(ticket, false).len() as u16 +} + +/// The rows a column's cards share: above the footer row and inside the border. +/// +/// Mirrors the vertical layout in `draw`: one footer row, then a border row on either +/// side of the text. The draw measures the real inner rectangle instead, so a terminal +/// too short for this arithmetic is corrected there. +fn column_text_height(screen: Size) -> u16 { + screen.height.saturating_sub(3) +} + +/// The offset that keeps the lines `start..end` in view, inside content `0..total`. +/// +/// A range below the view lands its last line on the bottom row; one above the view +/// puts its first line on the top row; inside, the offset stays where it was. Capped +/// against `total - inner` last, so neither path runs past the end of the content into +/// blank space — the same both-ends clamp `scroll_detail` applies to the overlay. +fn aligned_offset(offset: u16, start: u16, end: u16, inner: u16, total: u16) -> u16 { + let offset = if end > offset.saturating_add(inner) { + end.saturating_sub(inner) + } else if start < offset { + start + } else { + offset + }; + + offset.min(total.saturating_sub(inner)) +} + /// One card: the priority mark and short id, the title, then owner and due. fn card_lines(ticket: &TicketItem, selected: bool) -> Vec> { let (glyph, colour) = priority_mark(ticket.priority); @@ -635,23 +740,23 @@ mod tests { let mut board = Board::new(&dir).unwrap(); assert_eq!(board.selected().map(|t| t.title.clone()), Some("Alpha".to_string())); - board.select_card(1); + board.select_card(1, SCREEN); assert_eq!(board.selected().map(|t| t.title.clone()), Some("Beta".to_string())); // Clamped at both ends rather than wrapping - board.select_card(5); + board.select_card(5, SCREEN); assert_eq!(board.selected().map(|t| t.title.clone()), Some("Beta".to_string())); - board.select_card(-9); + board.select_card(-9, SCREEN); assert_eq!(board.selected().map(|t| t.title.clone()), Some("Alpha".to_string())); - board.select_column(1); + board.select_column(1, SCREEN); assert_eq!(board.selected().map(|t| t.title.clone()), Some("Gamma".to_string())); // reviewing is empty, so there is nothing selected there - board.select_column(1); + board.select_column(1, SCREEN); assert!(board.selected().is_none()); - board.select_column(-9); + board.select_column(-9, SCREEN); assert_eq!(board.column, 0); } @@ -666,13 +771,191 @@ mod tests { write_ticket(&dir, "committed", "44444444-0000-4000-8000-000000000000", "Delta", ""); let mut board = Board::new(&dir).unwrap(); - board.select_card(2); - board.select_column(1); + board.select_card(2, SCREEN); + board.select_column(1, SCREEN); assert_eq!(board.card, 0); assert_eq!(board.selected().map(|t| t.title.clone()), Some("Delta".to_string())); } + /// A column long enough that one window cannot hold it: twelve cards at four lines + /// each against seventeen visible rows on [`SCREEN`]. + fn fill_column(dir: &Path, status: &str, count: usize) { + for n in 1..=count { + write_ticket( + dir, + status, + &format!("{n:08}-0000-4000-8000-000000000000"), + &format!("Ticket {n:02}"), + "", + ); + } + } + + /// The reported bug: walking the selection down past the fold left the highlight on + /// a card the window could not see, so from the keyboard nothing appeared to move. + #[test] + fn selecting_down_past_the_fold_brings_the_selected_card_into_view() { + let dir = board_dir(); + fill_column(&dir, "backlog", 12); + + let mut board = Board::new(&dir).unwrap(); + + let top = render(&board, SCREEN.width, SCREEN.height).join("\n"); + assert!(top.contains("Ticket 01"), "{top}"); + assert!( + !top.contains("Ticket 12"), + "the fixture fits without scrolling:\n{top}" + ); + + board.select_card(11, SCREEN); + + let scrolled = render(&board, SCREEN.width, SCREEN.height).join("\n"); + assert!( + scrolled.contains("Ticket 12"), + "the selection fell below the fold:\n{scrolled}" + ); + assert!(!scrolled.contains("Ticket 01"), "nothing scrolled:\n{scrolled}"); + } + + /// And back up again: reaching the top returns the column to its head. + #[test] + fn selecting_up_scrolls_back_to_the_top() { + let dir = board_dir(); + fill_column(&dir, "backlog", 12); + + let mut board = Board::new(&dir).unwrap(); + board.select_card(11, SCREEN); + assert_eq!(board.offsets[0], 31); + + board.select_card(-99, SCREEN); + assert_eq!(board.offsets[0], 0, "the column stayed where the bottom left it"); + + let top = render(&board, SCREEN.width, SCREEN.height).join("\n"); + assert!(top.contains("Ticket 01"), "{top}"); + assert!(!top.contains("Ticket 12"), "{top}"); + } + + /// Down stops at the last card rather than running into blank space past it, and + /// the last card is what ends the view. + #[test] + fn the_column_scroll_stops_at_the_last_card() { + let dir = board_dir(); + fill_column(&dir, "backlog", 12); + + let mut board = Board::new(&dir).unwrap(); + // More downs than the column has, since the clamp and the cap are what stop it. + for _ in 0..30 { + board.select_card(1, SCREEN); + } + + assert_eq!(board.card, 11); + // Twelve cards at four lines, seventeen visible rows. + assert_eq!(board.offsets[0], 48 - 17); + + let end = render(&board, SCREEN.width, SCREEN.height).join("\n"); + assert!(end.contains("Ticket 12"), "the end is out of reach:\n{end}"); + assert!(!end.contains("Ticket 01"), "nothing scrolled:\n{end}"); + } + + /// A ticket moved elsewhere shortens the column under the reader; the draw has to + /// take that without waiting for a keypress, and the stored offset heals on the + /// next one rather than throwing the reader anywhere first. + #[test] + fn a_tick_that_shrinks_a_column_keeps_the_selection_in_view() { + let dir = board_dir(); + fill_column(&dir, "backlog", 12); + + let mut board = Board::new(&dir).unwrap(); + board.select_card(11, SCREEN); + + for n in 6..=12 { + let uuid = format!("{n:08}-0000-4000-8000-000000000000"); + let name = format!("{uuid}_ticket-{n:02}.md"); + std::fs::remove_file(dir.join("backlog").join(name)).unwrap(); + } + + assert!(board.tick().unwrap(), "the tick saw no change"); + assert_eq!(board.card, 4, "the selection was not clamped to the new end"); + + let shrunk = render(&board, SCREEN.width, SCREEN.height).join("\n"); + assert!(shrunk.contains("Ticket 05"), "the new end is out of reach:\n{shrunk}"); + assert!(!shrunk.contains("Ticket 06"), "{shrunk}"); + + // The stored value is stale until the next navigation, which is fine: the draw + // corrected what was shown, and this is what writes the correction back. + board.select_card(0, SCREEN); + assert_eq!(board.offsets[0], 3); + } + + /// Each column keeps its own place: leaving one must not snap it back to the top, + /// and entering one must show the card the selection landed on, not its head. + #[test] + fn each_column_keeps_its_place_and_entering_one_shows_the_selection() { + let dir = board_dir(); + fill_column(&dir, "backlog", 12); + for n in 1..=3 { + write_ticket( + &dir, + "committed", + &format!("{:08}-0000-4000-8000-000000000000", n + 20), + &format!("Other {n:02}"), + "", + ); + } + + let mut board = Board::new(&dir).unwrap(); + board.select_card(11, SCREEN); + + board.select_column(1, SCREEN); + // The card index carried over and clamps onto committed's last card. + assert_eq!(board.card, 2); + + let away = render(&board, SCREEN.width, SCREEN.height).join("\n"); + assert!( + away.contains("Ticket 12"), + "leaving snapped the column back to its top:\n{away}" + ); + assert!(away.contains("Other 03"), "{away}"); + + board.select_column(-1, SCREEN); + // Back in backlog the selection is card 2: the index is shared and it moved + // while we were away, so the column follows where it is now rather than + // holding a scroll position for a highlight it no longer has. + assert_eq!(board.card, 2); + let back = render(&board, SCREEN.width, SCREEN.height).join("\n"); + assert!( + back.contains("Ticket 03"), + "returning lost the selection:\n{back}" + ); + assert!(!back.contains("Ticket 12"), "{back}"); + } + + /// The terminal can shrink between the keypress and the draw; the draw measures the + /// real geometry, so the selection cannot be left above or below the fold. + #[test] + fn a_resize_between_the_keypress_and_the_draw_is_taken_at_draw_time() { + let dir = board_dir(); + fill_column(&dir, "backlog", 12); + + // Tall enough that every card fits, so the keypress stores no scroll at all. + let roomy = Size { + width: 120, + height: 60, + }; + + let mut board = Board::new(&dir).unwrap(); + board.select_card(11, roomy); + assert_eq!(board.offsets[0], 0); + + let shrunk = render(&board, SCREEN.width, SCREEN.height).join("\n"); + assert!( + shrunk.contains("Ticket 12"), + "the smaller window hid the selection:\n{shrunk}" + ); + assert!(!shrunk.contains("Ticket 01"), "{shrunk}"); + } + #[test] fn the_detail_view_shows_the_body_and_the_comments() { let dir = board_dir(); @@ -850,7 +1133,7 @@ mod tests { // the heading, so the detail text does not carry it. assert!(board.detail.clone().unwrap().contains("11111111"), "{:?}", board.detail); - board.select_card(1); + board.select_card(1, SCREEN); assert_eq!(board.selected().map(|t| t.title.clone()), Some("Beta".to_string())); assert!(board.detail.clone().unwrap().contains("22222222"), "{:?}", board.detail); } @@ -869,12 +1152,12 @@ mod tests { board.scroll_detail(1, SCREEN); assert!(board.offset > 0); - board.select_card(1); + board.select_card(1, SCREEN); assert_eq!(board.offset, 0, "the next card opened partway down"); board.scroll_detail(1, SCREEN); assert!(board.offset > 0); - board.select_column(1); + board.select_column(1, SCREEN); assert_eq!(board.offset, 0, "the next column opened partway down"); }