Compare commits

...
3 Commits
Author SHA1 Message Date
Ansho Rei 220789efea (6b8f4d13) Scroll the tui board columns with the selection, and bump to 0.7.2 2026-08-21 14:24:19 +02:00
Ansho ReiandClaude Opus 5 c1137f29cf (1b78a24) Scroll the tui detail view on pgup and pgdn, and bump to 0.7.1
The detail view had no scrolling at all: no offset on Board, nothing passed
to Paragraph::scroll, so anything past the height of the overlay was
unreachable. Every ticket in this repo is longer than that. The footer read
"↑↓ scroll" while up and down moved the selection, so it named a key that did
nothing and sent the reader looking for their own mistake.

The scroll goes on pgup and pgdn rather than taking 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 the selection. That is worth more
than the two keys.

The offset is clamped against the wrapped line count from
Paragraph::line_count, which is why ratatui now 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 run past it into blank space,
and 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,
since the terminal can be resized between them 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.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-21 12:38:54 +02:00
Ansho ReiandClaude Opus 5 77bf2d9e2a Say when to move a ticket, not just how
Both AGENTS.md and the kanban skill listed the statuses and the mv command
without ever saying at what point to run it, so a ticket could sit in backlog
until the work was finished and the board said nothing while it was in progress.
That is what happened to f6af387.

The rule is now in both places, and in both for a reason: the skill is what an
agent loads to work tickets in any repo, and AGENTS.md is what an agent working
on worklane itself reads, possibly without ever loading the skill. The skill's
Workflow section also becomes a sequence for working one ticket rather than an
unordered list of commands, with the command list kept separately.

Worth stating because it is self-enforcing: only one stage forward is allowed at
a time, so a ticket left in backlog cannot go straight to reviewing and has to
be walked through committed regardless. Moving it up front is the same two
commands in a more useful order.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-21 11:54:23 +02:00
7 changed files with 656 additions and 35 deletions
+25 -8
View File
@@ -176,12 +176,29 @@ worklane comment "My Ticket" "Needs changes to the UI"
worklane comment a1b2c3d4 "LGTM, approved"
```
## Workflow
## Working a ticket
1. Use `worklane add` to create tickets with all relevant details
2. Use `worklane ls [status]` to view tickets by status
3. Use `worklane show <id>` to view full ticket details
4. Use `worklane mv <id> --status <target>` to move tickets through the workflow
5. Use `worklane set <ticket>` to correct a field, or `worklane append <ticket>` to add to a section
6. Use `worklane check <ticket> <n>` to tick a criterion as it is met
7. Use `worklane comment <ticket> <body>` to add notes to tickets
Move the ticket as you work it, not afterwards. The board should say what is happening
now, not only what already landed.
1. `worklane show <id>` to read it
2. **`worklane mv <id> --status committed` before writing any code.** This is what marks
the ticket as being worked on, so it belongs at the start
3. Do the work. `worklane check <id> <n>` as each criterion is met
4. `worklane comment <id> <body>` with anything worth recording: a decision, a rejected
acceptance criterion, something the ticket got wrong
5. **`worklane mv <id> --status reviewing` once it is done and the tests pass**
Only one stage forward is allowed at a time, so a ticket left in `backlog` until the end
cannot go straight to `reviewing`. It has to be walked through `committed` anyway, which
makes moving it up front the same two commands in a more useful order.
## Commands
- `worklane add` creates tickets with all relevant details
- `worklane ls [status]` views tickets by status
- `worklane show <id>` views full ticket details
- `worklane mv <id> --status <target>` moves tickets through the workflow
- `worklane set <ticket>` corrects a field, `worklane append <ticket>` adds to a section
- `worklane check <ticket> <n>` ticks a criterion as it is met
- `worklane comment <ticket> <body>` adds notes to tickets
+18
View File
@@ -20,6 +20,15 @@
## Status Workflow
`backlog` → `committed` → `reviewing` → `done`
**Move the ticket as you work it, not afterwards.** `mv <id> --status committed` before
writing any code, and `mv <id> --status reviewing` once it is done and the tests pass.
The board is then true while the work is in progress, not only after it lands, which is
the whole point of having a `committed` column.
Only one stage at a time is allowed, so a ticket left in `backlog` until the end cannot
go straight to `reviewing` and has to be walked through `committed` anyway. Doing it up
front is the same two commands in a more useful order.
## Testing
- Run: `cargo test`
- Tests use `assert_cmd` and `assert_fs` for CLI testing
@@ -74,6 +83,15 @@
- 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
- **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
Generated
+1 -1
View File
@@ -1494,7 +1494,7 @@ dependencies = [
[[package]]
name = "worklane"
version = "0.7.0"
version = "0.7.2"
dependencies = [
"anyhow",
"assert_cmd",
+5 -2
View File
@@ -1,6 +1,6 @@
[package]
name = "worklane"
version = "0.7.0"
version = "0.7.2"
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]
+1 -1
View File
@@ -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>` |
+12 -4
View File
@@ -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;
@@ -164,10 +167,15 @@ 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::Up | KeyCode::Char('k') => board.select_card(-1),
KeyCode::Down | KeyCode::Char('j') => board.select_card(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, 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),
_ => {}
}
}
+594 -19
View File
@@ -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};
@@ -35,8 +35,13 @@ pub struct Board {
pub columns: Vec<Column>,
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<u16>,
/// The body and comments of the selected ticket, when the detail view is open.
pub detail: Option<String>,
/// First visible line of the detail view, counted in wrapped lines.
pub offset: u16,
pub should_quit: bool,
worklane_dir: PathBuf,
digest: u64,
@@ -48,7 +53,9 @@ impl Board {
columns: Vec::new(),
column: 0,
card: 0,
offsets: Vec::new(),
detail: None,
offset: 0,
should_quit: false,
worklane_dir: worklane_dir.to_path_buf(),
digest: 0,
@@ -83,10 +90,18 @@ 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();
// 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);
}
@@ -117,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;
}
@@ -126,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,
@@ -140,18 +160,76 @@ 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;
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 +321,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);
}
}
@@ -281,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<Line> = Vec::new();
let mut starts: Vec<u16> = 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<Line<'static>> {
let (glyph, colour) = priority_mark(ticket.priority);
@@ -329,7 +465,7 @@ fn card_lines(ticket: &TicketItem, selected: bool) -> Vec<Line<'static>> {
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 +475,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 +529,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 +565,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<String> {
let mut terminal = Terminal::new(TestBackend::new(width, height)).unwrap();
@@ -556,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);
}
@@ -587,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();
@@ -658,6 +1020,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, SCREEN);
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, 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, SCREEN);
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.