Compare commits

..
1 Commits
Author SHA1 Message Date
Ansho ReiandClaude Opus 5 88918b2f8a (c628759) Show a page indicator on the detail overlay's border, and bump to 0.16.1
The overlay has scrolled since 1b78a24 and nothing said where you were: a long
ticket opened looking exactly like a short one, so the only way to learn there
was more below was to press pgdn and watch whether anything moved.

`pg 2/8` now sits on the bottom right of the border, through
`Block::title_bottom` with a right-aligned line, which spends no text row. That
is the trade the title already makes on the top border, and the two cannot
crowd each other because they are on opposite borders.

Both of the things this had to get right are arithmetic. `wrapped_height` is
now the one measurement: `last_offset` is it less the viewport and
`page_indicator` takes the same two numbers, so the clamp and the indicator
cannot disagree. A second `line_count` call would be a number free to drift,
and an indicator claiming there is more to read where the scroll refuses to
move is worse than none.

The furthest offset is the last page by definition rather than by division. The
clamp stops at the wrapped height less the viewport, which is not a page
boundary, so the final screenful is partial and dividing reads `pg 2/3` at the
bottom of the ticket. The pages are counted in `scroll_step`, a screenful less
the overlap line, because that is the step the keys take: counting whole
screenfuls names a page pgdn cannot land on, and puts a 30 row ticket in a 10
row viewport at `pg 3/3` two rows short of its end.

Grey, the colour the footer keys and a rendered checkbox take, since this says
where you are in the ticket rather than anything about the ticket. Dropped
whole on an overlay too narrow for it and absent entirely when nothing scrolls,
the rules a corner and the tags row already follow.

`page_indicator` is four numbers in and an `Option<String>` out, so the
arithmetic is pinned without a terminal. The drawn tests answer the two things
it cannot: which border it landed on and what colour it reached the screen in.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-22 17:22:41 +02:00
5 changed files with 337 additions and 16 deletions
+7
View File
@@ -145,6 +145,12 @@ and this file is for what someone changing worklane's own code needs.
- 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 overlay carries a page indicator on the bottom right of its border**, `pg 2/8`, so a long ticket does not open looking exactly like a short one. `Block::title_bottom` with a right-aligned `Line`, which spends no text row, the trade the title already makes on the top border. The two cannot crowd each other: they are on opposite borders
- **`wrapped_height` is the one measurement.** `last_offset` is it less the viewport and `page_indicator` takes the same two numbers, so the clamp and the indicator cannot disagree. A second `line_count` call, or a count of the raw lines, is a number free to drift, and an indicator that says there is more to read where the scroll refuses to move is worse than none
- **The furthest offset is the last page by definition, not by division.** The clamp stops at the wrapped height less the viewport, which is not a page boundary, so the final screenful is partial: `offset / step + 1` reads `pg 2/3` at the bottom of a 25 row ticket in a 10 row viewport and claims there is more below
- **The pages are counted in `scroll_step`, a screenful less the overlap line, not in whole screenfuls.** The step is what the keys take, so counting in it names only pages `pgdn` can land on. Counting by screenfuls puts a 30 row ticket in a 10 row viewport at `pg 3/3` two rows short of its end, since three presses are what it takes to get there
- The indicator is dropped whole on an overlay too narrow for it, the rule a corner and the tags row already follow, and absent entirely when nothing scrolls, the way an untagged card spends no row on tags
- `page_indicator` takes four numbers and returns an `Option<String>`, so every case above is pinned without a terminal. The drawn tests exist for the two things arithmetic cannot answer: which border it landed on and what colour it reached the screen in
- **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
@@ -280,6 +286,7 @@ and this file is for what someone changing worklane's own code needs.
- Priority ramp → brightred (1), red (2), orange (3), cyan (4), grey (5). Green is deliberately absent: it means title
- Relation kind mark → brightred `×` blocked by and blocks, cyan `→` relates to, orange `←` regression of and regressed by. A small ramp inside one column, the way the priority meter is: the mark says which kind of edge the row is, so none of these three is a colour standing in for the uuid or the title beside it. Brightred on the cross rather than red, because the id one cell to its right is red and the two would blend. It is the colour and the glyph a held-up card already carries, which is the point: one vocabulary for blocking
- Relation status mark → grey `○` backlog, orange `◐` committed, cyan `◐` reviewing, green `●` done, grey `?` for a target the board does not hold. The second ramp in that column: the shape says how far the target has got and the colour tells the two middle stages apart, since both are half circles. **Green is here and deliberately absent from the priority ramp**, where it would sit on a whole line and read as a title; on a one-cell mark with no title behind it, it is the obvious colour for finished and nothing else wants it. Orange keeps the meaning it already has, Status, and grey keeps unset for the one row with no status to show
- Chrome → grey. The footer's key names, a rendered `[ ]`, and the overlay's page indicator. Not a new slot: grey already means "what a reader skips", which is the other half of the unset-value meaning, and none of these is a value. The indicator in orange would read as the title it faces across the overlay, in cyan as a timestamp, and in the priority ramp's colours as a level
- **The palette splits in two: seven colours that each mean one thing, and `TAG_COLORS`, the eight a tag may be drawn in.** A tag in red would read as a uuid, in green as a title, in grey as an unset value, so the tag slots are reserved as a list rather than picked at the call site. Do not assign a new meaning to a colour in `TAG_COLORS`, and do not draw a tag in one outside it
- `tag_color()` is a pure function of the tag string, so the same tag is the same colour on every card, in every view and on every board, with nothing stored. Case sensitive, because `Bug` and `bug` are two different tags to the field and to every search
- **The hash is FNV-1a written out here, not `DefaultHasher`.** std does not promise its output is stable across releases, and a board that repaints itself on a toolchain upgrade has lost the only property the mapping is for. `the_tag_mapping_is_pinned` fails on any change to it, so a repaint is a decision rather than a surprise
Generated
+1 -1
View File
@@ -1494,7 +1494,7 @@ dependencies = [
[[package]]
name = "worklane"
version = "0.16.0"
version = "0.16.1"
dependencies = [
"anyhow",
"assert_cmd",
+1 -1
View File
@@ -1,6 +1,6 @@
[package]
name = "worklane"
version = "0.16.0"
version = "0.16.1"
edition = "2024"
[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 [path...]` | Opens the board: four status columns, redrawn when the tree changes. Read only. Opens on backlog, committed and reviewing; `d` shows or hides done, whose count stays in the footer either way. Arrows or `hjkl` to move, `enter` for detail, `pgup`/`pgdn` to scroll an open ticket, `/` to jump to the first ticket whose id or title matches, `y` to copy the selected ticket's short id to the clipboard, `q` to quit. Each path opens the first `.worklane` at or above it, the working directory by default. Several paths are monitored together, as a tab per project plus an `all` tab that merges them, with `tab` and `shift+tab` between them |
| `worklane` or `worklane tui [path...]` | Opens the board: four status columns, redrawn when the tree changes. Read only. Opens on backlog, committed and reviewing; `d` shows or hides done, whose count stays in the footer either way. Arrows or `hjkl` to move, `enter` for detail, `pgup`/`pgdn` to scroll an open ticket, whose border carries a page indicator while there is more of it than fits, `/` to jump to the first ticket whose id or title matches, `y` to copy the selected ticket's short id to the clipboard, `q` to quit. Each path opens the first `.worklane` at or above it, the working directory by default. Several paths are monitored together, as a tab per project plus an `all` tab that merges them, with `tab` and `shift+tab` between them |
| `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. `--due` takes `YYYY-MM-DD` and refuses anything else at parse time |
| `worklane ls [status]` | Lists tickets, sorted by priority then title. Optional positional status, and `--priority <1-5>`, `--tag <tag>` and `--campaign <campaign>`, which compose in any combination. `--tag` matches a whole value of the comma-separated Tags field, case sensitively, so `--tag bug` does not list a ticket tagged `bugfix` or one tagged `Bug` |
+327 -13
View File
@@ -1643,29 +1643,87 @@ 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.
/// How tall the detail body is once wrapped to `width`.
///
/// 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: &Text<'static>, text: Rect) -> u16 {
/// Measured by the widget rather than counted by hand, since it wraps on words. A count
/// of the raw lines would stop short of the end on a wrapped ticket, and one that
/// ignored the wrapping the other way would run past it into blank space.
///
/// The one place the number comes from. The scroll clamp and the page indicator are both
/// derived from it, and two measurements are two numbers free to disagree: an indicator
/// saying there is more to read where the scroll refuses to move is worse than no
/// indicator at all.
fn wrapped_height(detail: &Text<'static>, width: u16) -> u16 {
let wrapped = Paragraph::new(detail.clone())
.wrap(Wrap { trim: false })
.line_count(text.width);
.line_count(width);
u16::try_from(wrapped)
.unwrap_or(u16::MAX)
.saturating_sub(text.height)
u16::try_from(wrapped).unwrap_or(u16::MAX)
}
/// The furthest the detail view can scroll: the last screenful, and no further.
fn last_offset(detail: &Text<'static>, text: Rect) -> u16 {
wrapped_height(detail, text.width).saturating_sub(text.height)
}
/// The step `scroll_detail` takes, a screenful less the line kept for overlap.
///
/// The page numbers are counted in it rather than in whole screenfuls, so the pages the
/// indicator names are the ones the keys can actually land on. Counting by screenfuls
/// would put a 30 line ticket in a 10 line viewport at `pg 3/3` two rows short of its
/// end, since three presses are what it takes to get there.
fn scroll_step(height: u16) -> u16 {
height.saturating_sub(1).max(1)
}
/// Where the reader is, as `pg 2/5`, or `None` when there is nothing to say or no room
/// to say it in.
///
/// `offset` has to be clamped already and `last` is what it was clamped against, so this
/// is arithmetic on the one wrapped measurement rather than a second look at the text.
///
/// **The furthest offset is the last page by definition, not by division.** The clamp
/// stops at `last`, which is the wrapped height less the viewport and not a page
/// boundary, so the final screenful is partial: dividing there reads `pg 2/3` at the
/// bottom of the ticket and claims there is more to read.
fn page_indicator(offset: u16, last: u16, height: u16, overlay_width: u16) -> Option<String> {
// Nothing scrolls, so there are no pages to be on. A ticket that fits spends no
// indicator, the way an untagged card spends no row on tags.
if last == 0 {
return None;
}
let step = scroll_step(height);
let total = last.div_ceil(step).saturating_add(1);
let page = match offset >= last {
true => total,
false => offset / step + 1,
};
let indicator = format!(" pg {page}/{total} ");
// Dropped whole rather than cut, the rule a card's corner follows: half a page number
// reads as a different one. Measured against the inner width, since the two border
// columns are not the indicator's to write on. The title cannot be crowded by this
// however narrow the overlay gets, because the two sit on opposite borders.
match indicator.chars().count() <= overlay_width.saturating_sub(2) as usize {
true => Some(indicator),
false => None,
}
}
fn draw_detail(frame: &mut Frame, detail: &Detail, offset: u16, area: Rect) {
let overlay = detail_overlay(area);
let text = detail_text_area(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.body, detail_text_area(area)));
// One measurement, two derivations. 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. Which is also what repages the indicator, since the wrapped
// count and the viewport both move with the width.
let last = wrapped_height(&detail.body, text.width).saturating_sub(text.height);
let offset = offset.min(last);
let block = Block::default()
let mut block = Block::default()
.borders(Borders::ALL)
.border_style(Style::default().fg(Color::Cyan.into()))
.title(Span::styled(
@@ -1673,6 +1731,20 @@ fn draw_detail(frame: &mut Frame, detail: &Detail, offset: u16, area: Rect) {
Style::default().fg(Color::Orange.into()),
));
// On the bottom border, so it costs no text row, which is the trade the title already
// makes on the top one. Grey because it is chrome: it says where you are in the
// ticket rather than anything about the ticket, so it takes the colour the footer
// keys and a rendered checkbox take, and does not compete with the orange title.
if let Some(indicator) = page_indicator(offset, last, text.height, overlay.width) {
block = block.title_bottom(
Line::from(Span::styled(
indicator,
Style::default().fg(Color::Grey.into()),
))
.right_aligned(),
);
}
frame.render_widget(Clear, overlay);
frame.render_widget(
Paragraph::new(detail.body.clone())
@@ -1846,6 +1918,31 @@ mod tests {
.collect()
}
/// The overlay's bottom border row, where the page indicator sits.
fn overlay_bottom_row(lines: &[String], width: u16, height: u16) -> String {
let overlay = detail_overlay(Rect::new(0, 0, width, height));
lines[(overlay.y + overlay.height - 1) as usize]
.chars()
.skip(overlay.x as usize)
.take(overlay.width as usize)
.collect()
}
/// A board with one ticket long enough to scroll, opened on it.
fn scrolling_board(dir: &Path, lines: usize) -> Board {
write_ticket(
dir,
"backlog",
"11111111-0000-4000-8000-000000000000",
"A long one",
&long_section(lines),
);
let mut board = one_board(dir);
board.toggle_detail();
board
}
#[test]
fn the_board_draws_the_four_statuses_as_columns_once_done_is_shown() {
let dir = board_dir();
@@ -4471,4 +4568,221 @@ mod tests {
let text = &board.detail.as_ref().expect("no detail").plain();
assert!(text.contains("A description."), "the body was lost: {text:?}");
}
/// The overlay scrolls and nothing said where you were: a long ticket opened looking
/// exactly like a short one.
#[test]
fn a_scrollable_ticket_shows_a_page_indicator_on_the_bottom_border() {
let dir = board_dir();
let board = scrolling_board(&dir, 60);
let screen = render(&board, SCREEN.width, SCREEN.height);
let row = overlay_bottom_row(&screen, SCREEN.width, SCREEN.height);
assert!(row.contains("pg 1/"), "no indicator on the bottom border:\n{row}");
// On the border, not on a text row: the row it is drawn on is the one carrying
// the corners, so no line of the ticket was spent on it.
assert!(row.starts_with('└'), "not the bottom border row:\n{row}");
assert!(row.ends_with('┘'), "not the bottom border row:\n{row}");
// Bottom right, so it is in the corner the eye goes to for a number and not
// adrift in the middle of the border.
let at = row.chars().position(|c| c == 'p').expect("no indicator");
let width = row.chars().count();
assert!(
at > width - 12,
"the indicator is not in the right-hand corner of a {width} cell border:\n{row}"
);
// And the top border still carries the title alone.
let title = overlay_title_row(&screen, SCREEN.width, SCREEN.height);
assert!(title.contains("A long one"), "{title}");
assert!(!title.contains("pg "), "the indicator landed on the title row:\n{title}");
std::fs::remove_dir_all(&dir).ok();
}
/// At the top of a scrollable ticket, page one.
#[test]
fn the_indicator_opens_on_page_one() {
let dir = board_dir();
let board = scrolling_board(&dir, 60);
let screen = render(&board, SCREEN.width, SCREEN.height);
let row = overlay_bottom_row(&screen, SCREEN.width, SCREEN.height);
assert!(row.contains("pg 1/"), "{row}");
std::fs::remove_dir_all(&dir).ok();
}
/// The one the arithmetic is for: the clamp stops at the wrapped height less the
/// viewport, not on a page boundary, so the last screenful is partial and dividing
/// would claim there is more to read.
#[test]
fn the_furthest_scroll_reads_the_last_page() {
let dir = board_dir();
let mut board = scrolling_board(&dir, 60);
// Far past the end, so the clamp is what stops it.
for _ in 0..40 {
board.scroll_detail(1, SCREEN);
}
let text = detail_text_area(Rect::new(0, 0, SCREEN.width, SCREEN.height));
let last = last_offset(&board.detail.as_ref().unwrap().body, text);
assert_eq!(board.offset, last, "the fixture did not reach the end");
let screen = render(&board, SCREEN.width, SCREEN.height);
let row = overlay_bottom_row(&screen, SCREEN.width, SCREEN.height);
let indicator = row
.split_whitespace()
.find(|word| word.contains('/'))
.unwrap_or_else(|| panic!("no indicator on:\n{row}"))
.to_string();
let (page, total) = indicator.split_once('/').expect("no separator");
assert_eq!(page, total, "the last page reads as the second to last: {indicator}");
std::fs::remove_dir_all(&dir).ok();
}
/// A ticket that fits spends no indicator, the way an untagged card spends no row on
/// tags.
///
/// On a taller screen than the other overlay tests use: `write_ticket`'s own body is
/// twenty-odd rows and scrolls in a twenty row terminal, so the fixture has to be
/// given a terminal it fits in for the absence to mean anything.
#[test]
fn a_ticket_that_fits_shows_no_indicator() {
let (width, height) = (120, 60);
let dir = board_dir();
write_ticket(&dir, "backlog", "11111111-0000-4000-8000-000000000000", "A short one", "");
let mut board = one_board(&dir);
board.toggle_detail();
let text = detail_text_area(Rect::new(0, 0, width, height));
assert_eq!(
last_offset(&board.detail.as_ref().unwrap().body, text),
0,
"the fixture scrolls, so it proves nothing"
);
let screen = render(&board, width, height);
assert!(
!screen.join("\n").contains("pg "),
"a ticket that fits drew an indicator:\n{}",
screen.join("\n")
);
std::fs::remove_dir_all(&dir).ok();
}
/// The wrapped count and the viewport both move with the terminal, so the total has
/// to move with them. Narrower and shorter means more pages of the same ticket.
#[test]
fn a_resize_repages_the_indicator() {
let dir = board_dir();
let board = scrolling_board(&dir, 60);
let total = |width: u16, height: u16| -> String {
let screen = render(&board, width, height);
let row = overlay_bottom_row(&screen, width, height);
row.split_whitespace()
.find(|word| word.contains('/'))
.unwrap_or_else(|| panic!("no indicator at {width}x{height} on:\n{row}"))
.split_once('/')
.expect("no separator")
.1
.to_string()
};
let wide = total(120, 40);
let narrow = total(60, 20);
assert_ne!(wide, narrow, "the same total on two terminal sizes");
std::fs::remove_dir_all(&dir).ok();
}
/// An overlay too narrow for the indicator drops it whole rather than cutting it, the
/// rule a card's corner follows: half a page number reads as a different one.
#[test]
fn an_overlay_too_narrow_for_the_indicator_drops_it_whole() {
// Six pages in a two cell overlay, so there is plenty to say and no room for it.
assert_eq!(page_indicator(0, 50, 10, 2), None);
assert_eq!(page_indicator(0, 50, 10, 8), None);
// ` pg 1/7 ` is eight characters, so it needs ten cells of overlay.
assert_eq!(page_indicator(0, 50, 10, 10).as_deref(), Some(" pg 1/7 "));
}
/// The arithmetic on its own, so the cases that need no terminal are pinned where
/// they can be read.
#[test]
fn the_page_numbers_count_in_the_step_the_keys_take() {
// A 25 line ticket in a 10 line viewport: the step is nine, so the offsets the
// keys reach are 0, 9 and 15, the last of them clamped.
let (last, height) = (15, 10);
assert_eq!(page_indicator(0, last, height, 40).as_deref(), Some(" pg 1/3 "));
assert_eq!(page_indicator(9, last, height, 40).as_deref(), Some(" pg 2/3 "));
assert_eq!(page_indicator(15, last, height, 40).as_deref(), Some(" pg 3/3 "));
// Nothing to scroll, nothing to say.
assert_eq!(page_indicator(0, 0, height, 40), None);
// One line over the viewport is two pages, and the second of them is one row.
assert_eq!(page_indicator(0, 1, height, 40).as_deref(), Some(" pg 1/2 "));
assert_eq!(page_indicator(1, 1, height, 40).as_deref(), Some(" pg 2/2 "));
}
/// The colour the indicator actually reached the screen in.
///
/// Located on the bottom border row rather than by searching the buffer for a glyph:
/// `p` and `g` are all over the board, and `drawn_color` would answer about whichever
/// card holds the first one.
fn indicator_color(
board: &Board,
width: u16,
height: u16,
) -> Option<ratatui::style::Color> {
let mut terminal = Terminal::new(TestBackend::new(width, height)).unwrap();
terminal.draw(|frame| draw(frame, board)).unwrap();
let buffer = terminal.backend().buffer().clone();
let overlay = detail_overlay(Rect::new(0, 0, width, height));
let row = overlay.y + overlay.height - 1;
(overlay.x..overlay.x + overlay.width - 1)
.find(|x| {
buffer[(*x, row)].symbol() == "p" && buffer[(x + 1, row)].symbol() == "g"
})
.map(|x| buffer[(x, row)].fg)
}
/// Chrome, not a value: the guideline gives grey to what a reader skips, and the
/// title on the opposite border keeps orange.
#[test]
fn the_indicator_is_drawn_as_chrome() {
let dir = board_dir();
let board = scrolling_board(&dir, 60);
assert_eq!(
indicator_color(&board, SCREEN.width, SCREEN.height),
Some(Color::Grey.into()),
"the indicator was drawn in something other than the chrome colour"
);
// Not the same colour as the title on the opposite border, or it would read as
// part of the ticket's identity rather than as chrome.
assert_ne!(
indicator_color(&board, SCREEN.width, SCREEN.height),
Some(Color::Orange.into()),
"the indicator took the title's colour"
);
std::fs::remove_dir_all(&dir).ok();
}
}