diff --git a/AGENTS.md b/AGENTS.md index db93d52..1ee572a 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -199,6 +199,7 @@ and this file is for what someone changing worklane's own code needs. - `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 campaign frame scrolls on the same two keys, and `Board::scroll_page` is where the precedence lives.** An open ticket wins, whatever holds the selection behind it; the frame takes them only when there is no overlay to take them first. In `Board` rather than in the `main.rs` arm for the reason `dismiss` is: a layering rule written into that dispatch is a rule nothing can check - 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 @@ -234,11 +235,18 @@ and this file is for what someone changing worklane's own code needs. - **A campaign the board does not hold labels nothing**, the answer `mark_blocked` gives a dangling blocker. `campaign_cell` renders that case as `_missing_` because a metadata table is a place to report a dangling reference; a card is not - **`c` opens the campaign picker, and taking a campaign filters the tab's columns to its members.** Not a fifth tab: a campaign groups across the flow, so the shape of the answer is the four statuses with fewer cards in them, which is what `campaign show` already answers the question in. Every column is kept, empty ones included. The filter is applied in `reload`, where the columns are built, so nothing downstream has to ask whether a campaign is selected — the board simply holds fewer cards, and `first_match`, `done_count` and the copy key all keep working unchanged - **`Tab::campaign` is a uuid on the tab, not on the `Board`.** A campaign belongs to one `.worklane`, so a filter carried onto another project's tab would empty it and say nothing about why. It is looked up by uuid rather than held as an index, and a selection whose campaign has left the board is cleared by `reload` rather than left filtering the board to nothing -- **The frame above the columns is three rows, and `Chrome` is what every measurement takes.** `frame_rows` grew a row, so the two bools that decide the geometry became one `Chrome`, copied from `Board::chrome`: adjacent same-typed parameters are what the Rust Style rule warns about, and the draw and `follow_selection` have to measure one answer or a keypress scrolls against a board the next frame does not draw. The row indices are named (`TAB_ROW`, `CAMPAIGN_ROW`, `BOARD_ROW`, `FOOTER_ROW`), since an index written out by hand goes on meaning what it used to -- **The frame says the rest of what it has to say on its borders**, the trade the detail overlay makes with its title and its page indicator: `(id) ~codename · Name` on the top one, the standing on the bottom right, and `q board` on the bottom left. One text row, the opening line of the description. Every row spent here is a row of cards +- **The frame above the columns is `Chrome::CAMPAIGN_ROWS` rows, and `Chrome` is what every measurement takes.** `frame_rows` grew a row, so the two bools that decide the geometry became one `Chrome`, copied from `Board::chrome`: adjacent same-typed parameters are what the Rust Style rule warns about, and the draw and `follow_selection` have to measure one answer or a keypress scrolls against a board the next frame does not draw. The row indices are named (`TAB_ROW`, `CAMPAIGN_ROW`, `BOARD_ROW`, `FOOTER_ROW`), since an index written out by hand goes on meaning what it used to +- **The whole description is carried off the one read, and the cut is on the view.** `section_prose` replaced `section_opening`, which cut to the opening line at read time: the campaign file is only in hand while the campaigns directory is being read, so what that read has to carry is everything a view might want, and `CampaignRow::summary` takes the one line the picker draws back off it. Two fields, one cut from the other, are two strings free to come from different reads of the same file +- **`CAMPAIGN_PROSE_ROWS` is a constant, not a height fitted to the description.** Three rows of prose plus a border either side. A frame that grew and shrank with the campaign would resize every column whenever the filter changed, and a reader would look for a card where the previous campaign's description had put it. It does not have to be right for the longest description, because scrolling is what covers the rest — which is also why three was affordable where one row was not +- **The frame says the rest of what it has to say on its borders**, the trade the detail overlay makes with its title and its page indicator: `(id) ~codename · Name` on the top one, the standing on the bottom right, and `q board` then the page indicator on the bottom left. Every row spent here is a row of cards +- **The frame's page indicator goes on the bottom border beside `q board`, not on the top beside the title.** The title is cut against the border it sits on, so an indicator up there would shorten a long campaign name the moment its description grew past three rows; and the bottom right is the standing's, which is what the frame is *about* where the indicator is only where the reader has got to in it. Dropped before `q board` when the two cannot both fit, since with a campaign selected the footer's last slot names `ctrl-c quit` and the border is the only place that says `q` gives the board back +- **`Focus` is the third place the selection can be, and `Tab` is what holds it.** The board had a column and a card and `select_card` clamped at zero; up from the top card now reaches the frame and down returns to the column it left, since the column index is never what changed. Per tab beside the filter and the offset, so switching away and back returns to where the tab was left. `Focus::Frame` while no campaign is selected is the one state that must never exist — `select_campaign` and `reload` are what keep it from arising +- **`Tab::selected` hands back nothing while the frame holds the selection.** Every key that acts on a card has to answer for the frame, and the answer for `enter` falls out of this rather than being written into the dispatch. `←→` are inert, because the frame spans the width of the board and moving the column underneath would change nothing on screen. `y` is the exception that earns its place: it copies the campaign's short id, so `y copy id` means the id of the selected thing in every state the selection can be in. No card is drawn reversed there either, since that highlight is what says which ticket a key is about +- **The frame is out of reach from under an open ticket.** With the overlay open, up and down step through the tickets and it follows, so a selection that reached the frame would have to either close it on an arrow key or leave it showing a ticket nothing is selecting. `an_open_ticket_keeps_the_scroll_keys_from_the_frame` builds that state by hand for exactly this reason: the precedence has to hold whether or not a keypress can reach it - **The standing comes from the columns, not from a walk of the tree.** While a campaign is selected the columns *are* its members, done included, so `Tab::standing` counts what is already in hand rather than paying what `campaign ls` pays per campaign. Counted over every column, drawn or not: hiding done is a change to what is drawn and never to what is counted - **The way out is on the frame's own border, not in the footer.** `q board` sits on the thing it takes away, and the footer row was already at its width naming eight keys. Dropped whole when it and the standing would meet, the rule the page indicator follows - **`c` is named in the footer only on a closed board with nothing selected**, which is where a reader has to find it. Over an open ticket and on a filtered board it is left out: the frame's border then says how to put the campaign away, and the row has no cells to spare. Incomplete rather than wrong, which is the trade this row is allowed to make — what it must never do is name a key by what it used to do +- **The footer has three states, because the selection has three places to be.** An open ticket, the frame, and the cards. On the frame it names `↓ board`, the two scroll keys and `y copy id`, and leaves out `enter` and `←→` because they do nothing there. `↑ frame` is not named on the board, on the same trade `c` is dropped on: the frame is drawn directly above the columns and up is the key that reaches it - **`picker: Option` is the whole mode**, the shape `search` and `detail` use, and `Board::picker_key` runs beside `search_key` ahead of the action arms for the same reason: an open list owns the keyboard, so `d` must not toggle done and `q` must not quit while a campaign is being chosen. `ctrl-c` is the one key it declines and every other control combination is swallowed, or `ctrl-d` would reach the arm bound to `d` - **The picker's rows are `Tab::campaigns`, not a copy taken when it opened**, so a campaign filed elsewhere appears in an open picker on the next tick. It opens on the campaign already selected, so `c` on a filtered board says where you are as well as offering somewhere to go, and a board with no campaigns gets a `Notice` rather than an empty box that has to be dismissed to learn it was empty - **A picker row draws a real codename only.** The row opens with the short id, so the card's `~` fallback would print it twice and say nothing the second time diff --git a/Cargo.lock b/Cargo.lock index 0fc0813..5e67090 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -1503,7 +1503,7 @@ dependencies = [ [[package]] name = "worklane" -version = "0.26.1" +version = "0.26.2" dependencies = [ "anyhow", "assert_cmd", diff --git a/Cargo.toml b/Cargo.toml index 0bce50f..568f880 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "worklane" -version = "0.26.1" +version = "0.26.2" edition = "2024" [dependencies] diff --git a/README.md b/README.md index 0676e3f..bf878d3 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 [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, `c` to pick a campaign and filter the columns to its members, `q` to close whatever is open and then to quit. A card carries its campaign beside its tags, marked `~` and bold, and a comment count in its bottom right corner, the number then `❞` in cyan, before the criteria count and absent entirely when nobody has commented; while one is selected a frame above the columns names it and says how far it has got, and `q` on its border gives the whole board back. 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 or the campaign frame, whichever the selection is on, with a page indicator on its border 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, `c` to pick a campaign and filter the columns to its members, `q` to close whatever is open and then to quit. A card carries its campaign beside its tags, marked `~` and bold, and a comment count in its bottom right corner, the number then `❞` in cyan, before the criteria count and absent entirely when nobody has commented; while one is selected a frame above the columns names it, shows three rows of its description and says how far it has got, and `q` on its border gives the whole board back; up from the top card of a column moves the selection to that frame, where the scroll keys page through the description and down returns to the column it came from. 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 ` and `--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`. `--ids` prints one ticket per line as its short id, a tab and its title, unstyled, done included, for a script or a completion | diff --git a/src/main.rs b/src/main.rs index 2bfb4ab..5bd8a8f 100644 --- a/src/main.rs +++ b/src/main.rs @@ -215,11 +215,15 @@ fn run_tui(paths: &[std::path::PathBuf], start: &std::path::Path) -> Result<()> 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. + // open ticket is a page at a time, and so is scrolling the campaign + // frame that up reaches from the top card of a column. 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), + // The open ticket first and the campaign frame behind it, which is + // `Board::scroll_page` rather than a condition written here: the arms in + // this dispatch are not reachable from a test. + KeyCode::PageUp => board.scroll_page(-1, screen), + KeyCode::PageDown => board.scroll_page(1, screen), // Tabs cycle rather than clamp, the way tabs everywhere do, and are // a no-op with a single board. Free of every other binding: the // columns took hjkl and the arrows. diff --git a/src/tui.rs b/src/tui.rs index 43c0b6e..eb6ce75 100644 --- a/src/tui.rs +++ b/src/tui.rs @@ -49,13 +49,28 @@ pub struct Chrome { } impl Chrome { - /// The rows the campaign frame takes: a border either side of one row of prose. + /// The rows of prose the campaign frame holds. /// - /// Three rather than four, because the frame says the rest of what it has to say on - /// its borders: the identity on the top one and the standing on the bottom, the trade - /// the detail overlay already makes with its title and its page indicator. Every row + /// A constant rather than a height fitted to the description it is drawing. Every + /// measurement of the board goes through `frame_rows`, so a frame that grew and shrank + /// with the campaign would resize the columns whenever the filter changed, and a reader + /// would look for a card where the previous campaign's description had put it. + /// + /// Three, up from the one row the frame opened with. A line and a half of prose was the + /// wrong amount for the place the question it answers gets asked, and the two extra rows + /// cost two rows of cards: on a 24 row terminal the columns go from 20 rows to 18, which + /// is a card and a half of the four or five rows a card takes. Scrolling is what covers + /// a description longer than this, which is why the constant does not have to be right + /// for the longest one. + const CAMPAIGN_PROSE_ROWS: u16 = 3; + + /// The rows the campaign frame takes: a border either side of its prose. + /// + /// The frame says the rest of what it has to say on its borders: the identity on the top + /// one, and the standing, the way out and the page indicator on the bottom, the trade + /// the detail overlay already makes with its title and its own indicator. Every row /// spent here is a row of cards. - const CAMPAIGN_ROWS: u16 = 3; + const CAMPAIGN_ROWS: u16 = Self::CAMPAIGN_PROSE_ROWS + 2; fn campaign_rows(self) -> u16 { match self.campaign { @@ -65,6 +80,24 @@ impl Chrome { } } +/// Where a tab's selection is: among its cards, or on the campaign frame above them. +/// +/// The board had no focus beyond a column and a card, and `select_card` clamped at zero. A +/// frame that can hold the selection is a third place focus can be, so it is named rather +/// than left as a bool beside the card index: every key that acts on a card has to answer +/// for it, and a `match` on two variants is what makes an unanswered key something the +/// reader can be told about instead of whatever the clamp happened to do. +#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)] +pub enum Focus { + /// A card in a column, which is where the board opens and where every jump lands. + #[default] + Cards, + /// The campaign frame. Only ever set while the tab is filtered to a campaign, which + /// `select_campaign` and `reload` are what keep true: a frame that is not drawn must + /// never be holding the selection. + Frame, +} + /// One monitored board: where it lives, and what to call it. #[derive(Debug)] pub struct Project { @@ -166,8 +199,10 @@ pub struct Column { /// A campaign as the board holds it: what the picker lists and what the frame draws. /// /// Read at reload from the one pass over the campaigns directory, the same pass that names -/// the campaign on each card. The description is cut to its opening line here rather than -/// at draw time, because the file is only in hand while the directory is being read. +/// the campaign on each card. The whole description is carried off that read rather than +/// the opening line it used to be cut to, because the file is only in hand while the +/// directory is being read and the frame now pages through the rest of it. The cut lives on +/// [`CampaignRow::summary`], for the caller that still wants one line. /// /// The standing is counted here too, off the cards the reload is already holding rather /// than by the walk of the status directories per campaign that `campaign ls` pays. A @@ -178,8 +213,8 @@ pub struct CampaignRow { pub uuid: String, pub title: String, pub codename: Option, - /// The opening line of the description, or empty for a campaign with none. - pub summary: String, + /// The description as the file spells it, or empty for a campaign with none. + pub description: String, /// When it was filed, as the file spells it. What the completed section is ordered by, /// so the couple that survive the truncation are the ones just finished. Compared as a /// string: `%Y-%m-%d %H:%M:%S` is lexicographic in chronological order, the property @@ -199,6 +234,15 @@ impl CampaignRow { campaign_label(&self.uuid, self.codename.as_deref()) } + /// The opening line of the description, or empty for a campaign with none. + /// + /// For the picker, which has one row per campaign and no room for the rest. Taken off + /// the description rather than held beside it: two fields, one cut from the other, are + /// two strings free to come from different reads of the same file. + pub fn summary(&self) -> &str { + self.description.lines().next().unwrap_or_default() + } + /// Whether every member is done, which is what puts the row under `completed`. /// /// Off `Standing::state`, so the section a campaign lands in and the state the frame @@ -232,6 +276,19 @@ pub struct Tab { /// one `.worklane`, so a filter carried across to another project's tab would empty it /// and say nothing about why. pub campaign: Option, + /// Whether the selection is on a card or on the campaign frame above the columns. + /// + /// Per tab like the rest of the selection, so switching away and back returns to where + /// the tab was left. A tab showing the whole board has no frame to hold it, which is + /// the invariant `select_campaign` and `reload` keep. + pub focus: Focus, + /// First visible line of the frame's prose, counted in wrapped lines the way + /// `Board::offset` counts the overlay's. + /// + /// Per tab beside the filter, since the filter is per tab: the frame draws the campaign + /// this tab is showing, so how far into its description the reader has got is a fact + /// about this tab and not about the board. + pub frame_offset: u16, } impl Tab { @@ -244,6 +301,8 @@ impl Tab { offsets: Vec::new(), campaigns: Vec::new(), campaign: None, + focus: Focus::default(), + frame_offset: 0, } } @@ -294,7 +353,22 @@ impl Tab { }; } + /// The selected card, or nothing while the frame holds the selection. + /// + /// Nothing rather than the card the selection was last on. That card draws no highlight + /// while the frame is focused, so handing it back here would leave `y` copying and + /// `enter` opening a ticket the reader can no longer see picked out — a stale card, and + /// the one thing a third focus must not introduce. `enter` being inert on the frame + /// falls out of this rather than being written into the dispatch. + /// + /// It is also what closes an open overlay when a tab whose selection is on its frame is + /// switched to: `refresh_detail` follows the selection, and there is no ticket there to + /// follow. fn selected(&self) -> Option<&Card> { + if self.focus == Focus::Frame { + return None; + } + self.columns .get(self.column) .and_then(|column| column.cards.get(self.card)) @@ -672,6 +746,12 @@ impl Board { // tickets. if tab.selected_campaign().is_none() { tab.campaign = None; + // And the frame goes with it, both the focus and the place its prose was + // scrolled to: a frame that is no longer drawn must not be holding the + // selection, and the next campaign selected starts at the top of its own + // description rather than partway down the last one's. + tab.focus = Focus::Cards; + tab.frame_offset = 0; } tab.columns = retain_campaign(columns, tab.campaign.as_deref()); // One scroll position per column, kept by index. A tick that adds or removes @@ -765,7 +845,16 @@ impl Board { } /// Move between columns, keeping the card index where it can land. + /// + /// Inert while the frame holds the selection. The frame spans the width of the board, so + /// there is nothing beside it to move to, and moving the column underneath would change + /// nothing on screen until the selection came back down — a keypress that quietly + /// relocates where `↓` returns to is worse than one that does nothing. pub fn select_column(&mut self, delta: isize, screen: Size) { + if self.current().focus == Focus::Frame { + return; + } + let visible = self.visible_count(); if visible == 0 { return; @@ -785,12 +874,41 @@ impl Board { self.refresh_detail(); } + /// Move up and down the focused column, and on and off the frame above it. + /// + /// A step up from the top card reaches the campaign frame, and a step down from the + /// frame comes back to the column the selection left, since the column index is never + /// what changed. An empty column reaches it too: a column with no card to stand on must + /// not be a column the reader is stuck in. + /// + /// Not from under an open ticket. There, up and down step through the tickets and the + /// overlay follows, so a selection that reached the frame would have to either close the + /// overlay on an arrow key or leave it showing a ticket nothing is selecting. The clamp + /// at the top card is what it has always been while a ticket is open, and the frame is + /// one `q` away. pub fn select_card(&mut self, delta: isize, screen: Size) { - let tab = self.current_mut(); - let count = match tab.columns.get(tab.column) { - Some(column) => column.cards.len(), - None => return, + if self.current().focus == Focus::Frame { + // Up has nowhere further to go, the answer the top card of a column gives. + if delta > 0 { + self.current_mut().focus = Focus::Cards; + self.follow_selection(screen); + self.refresh_detail(); + } + return; + } + + let open = self.detail.is_some(); + let tab = self.current(); + let Some(column) = tab.columns.get(tab.column) else { + return; }; + let count = column.cards.len(); + + if delta < 0 && tab.card == 0 && tab.campaign.is_some() && !open { + self.current_mut().focus = Focus::Frame; + return; + } + if count == 0 { return; } @@ -811,6 +929,10 @@ impl Board { let tab = self.current_mut(); tab.column = column; tab.card = card; + // A jump lands on a card, so it takes the selection off the frame: `/` reaching a + // ticket the frame still held would leave the highlight where none of the keys that + // act on a ticket do anything. + tab.focus = Focus::Cards; self.follow_selection(screen); self.refresh_detail(); } @@ -1105,6 +1227,11 @@ impl Board { tab.column = 0; tab.card = 0; tab.offsets.iter_mut().for_each(|offset| *offset = 0); + // The frame is a different campaign's now, or gone, so the selection comes back to + // the cards and its prose starts at the top — the answer `refresh_detail` gives the + // overlay when the ticket under it changes. + tab.focus = Focus::Cards; + tab.frame_offset = 0; // Swallowed for the reason the tick's is not: there is nobody above a keypress to // handle a failed read, and the board goes on being drawn either way. @@ -1241,6 +1368,17 @@ impl Board { /// `None` on an empty column, so nothing is sent rather than an empty string put on /// the clipboard over whatever the reader had there. pub fn copy_text(&self) -> Option { + // On the frame it is the campaign's id, since that is what the selection is on and + // what the frame's own top border prints. `y copy id` means the id of the selected + // thing in every state the selection can be in, rather than a key that stops + // working one row above the cards. Seven characters like a card's, and every command + // that takes a campaign resolves them. + if self.current().focus == Focus::Frame { + return self + .campaign() + .map(|campaign| short_id(&campaign.uuid).to_string()); + } + self.selected().map(|card| card.ticket.id.clone()) } @@ -1300,6 +1438,55 @@ impl Board { self.offset = (self.offset as isize + pages.saturating_mul(step)).clamp(0, last) as u16; } + /// Scroll whatever `pgup` and `pgdn` belong to: the open ticket, or the campaign frame. + /// + /// The precedence is here rather than in the dispatch, the rule `dismiss` follows: the + /// match arms in `main.rs` are not reachable from a test, so a layering rule written + /// into one of them is a rule nothing can check. + /// + /// An open ticket wins, whatever holds the selection behind it. It is the thing the + /// reader put on and the thing they are reading, and it has had these two keys since + /// 1b78a24; the frame takes them only when there is no overlay to take them first. With + /// neither open they do nothing, which is what they did on the board before the frame + /// could be scrolled. + pub fn scroll_page(&mut self, pages: isize, screen: Size) { + if self.detail.is_some() { + self.scroll_detail(pages, screen); + return; + } + + if self.current().focus == Focus::Frame { + self.scroll_frame(pages, screen); + } + } + + /// Scroll the campaign frame's description by whole screenfuls, one line kept for + /// overlap. + /// + /// The overlay's arithmetic, deliberately: `scroll_step` decides the step and + /// `last_offset` the clamp there, and prose wrapped into a viewport is prose wrapped + /// into a viewport. Two sets of rules is how the same two keys come to move different + /// distances in the two places a reader presses them. + /// + /// Inert on a description that fits, since `last` is zero and the clamp leaves the + /// offset where it is — which is what leaves a short description's frame selectable + /// rather than making it a place the keys had to be kept away from. The screen comes in + /// for the reason `scroll_detail` takes it. + pub fn scroll_frame(&mut self, pages: isize, screen: Size) { + let chrome = self.chrome(); + let Some(campaign) = self.campaign() else { + return; + }; + + let text = frame_text_area(screen, chrome); + let step = scroll_step(text.height) as isize; + let last = last_offset(&frame_prose(campaign), text) as isize; + + let tab = self.current_mut(); + let at = tab.frame_offset as isize + pages.saturating_mul(step); + tab.frame_offset = at.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. @@ -1459,7 +1646,7 @@ fn campaign_rows( uuid: campaign.uuid.clone(), title: campaign.title.clone(), codename: campaign.codename.clone(), - summary: section_opening(&campaign.content, &DESCRIPTION).unwrap_or_default(), + description: section_prose(&campaign.content, &DESCRIPTION).unwrap_or_default(), created_at: parse_ticket_field(&campaign.content, "Created At"), standing: standings .get(campaign.uuid.as_str()) @@ -1711,8 +1898,8 @@ pub fn draw(frame: &mut Frame, board: &Board) { if chrome.tabbed { draw_tabs(frame, board, rows[TAB_ROW]); } - if let Some(campaign) = board.campaign() { - draw_campaign(frame, campaign, rows[CAMPAIGN_ROW]); + if chrome.campaign { + draw_campaign(frame, board.current(), rows[CAMPAIGN_ROW]); } draw_columns(frame, board, rows[BOARD_ROW]); draw_footer(frame, board, rows[FOOTER_ROW]); @@ -1781,19 +1968,47 @@ fn draw_tabs(frame: &mut Frame, board: &Board, area: Rect) { /// it has got. /// /// The columns below are its members, so this is the row that says whose members they are. -/// Three rows for it, of which one is prose: the identity goes on the top border and the -/// standing on the bottom one, the trade the detail overlay already makes with its title -/// and its page indicator, and every row taken here is a row of cards. +/// [`Chrome::CAMPAIGN_ROWS`] rows for it, of which [`Chrome::CAMPAIGN_PROSE_ROWS`] are +/// prose: the identity goes on the top border and the standing, the way out and the page +/// indicator on the bottom one, the trade the detail overlay already makes with its title +/// and its own indicator, and every row taken here is a row of cards. +/// +/// The tab comes in rather than the campaign alone, because the frame draws three of the +/// tab's facts and not one: which campaign it is filtered to, how far into that campaign's +/// description the reader has scrolled, and whether the selection is on the frame or on a +/// card below it. Cyan when it holds the selection, the colour the focused column's border +/// and the overlay's already take. /// /// The title carries the id in red, the codename in its own colour and bold, and the name /// in green, which is the colour guideline applied rather than a decision of its own. Cut /// by hand, like `detail_title`, because ratatui truncates a block title at whatever cell /// it reaches and would take the id with it. -fn draw_campaign(frame: &mut Frame, campaign: &CampaignRow, area: Rect) { +fn draw_campaign(frame: &mut Frame, tab: &Tab, area: Rect) { + let Some(campaign) = tab.selected_campaign() else { + return; + }; + let focused = tab.focus == Focus::Frame; + + // The same rectangle `frame_text_area` reaches from the screen size for the keypress, + // measured here off the area the draw was actually given: the relationship + // `column_text_height` has with `draw_columns`, so a resize between a keypress and the + // frame that follows it is corrected in the frame. + let text = area.inner(Margin::new(1, 1)); + let prose = frame_prose(campaign); + // One measurement, three derivations, the rule `wrapped_height` holds for the overlay. + // Clamped here as well as on the keypress for the same two reasons: the terminal may + // have been resized since, and a tick can put a shorter description in front of a reader + // who was at the end of the old one. + let last = last_offset(&prose, text); + let offset = tab.frame_offset.min(last); + let standing = &campaign.standing; let mut block = Block::default() .borders(Borders::ALL) - .border_style(Style::default().fg(Color::Grey.into())) + .border_style(Style::default().fg(match focused { + true => Color::Cyan.into(), + false => Color::Grey.into(), + })) .title(Line::from(campaign_title(campaign, area.width))); // Right-aligned on the bottom border, where the overlay already puts the one number it @@ -1813,27 +2028,63 @@ fn draw_campaign(frame: &mut Frame, campaign: &CampaignRow, area: Rect) { // frame anyway: it is what takes the frame away. Grey because it is chrome, the colour // the footer's own key names and the overlay's page indicator take. // - // Dropped whole when the two would meet, the rule the page indicator follows: half of - // either reads as something else, and the footer still answers how to leave the board. + // The page indicator follows it on the same border rather than going up beside the + // title where the overlay's sits. The title is cut against the border it is on, so an + // indicator up there would shorten a long campaign name the moment its description grew + // past three rows, and the bottom right is the standing's — which is what the frame is + // about, where this is only where the reader has got to in it. let hint = " q board "; + let indicator = page_indicator(offset, last, text.height, area.width).unwrap_or_default(); let room = area.width.saturating_sub(2) as usize; - if hint.chars().count() + spans_width(&standing_spans) <= room { + let taken = spans_width(&standing_spans); + + // Dropped whole rather than cut, the rule the indicator follows on the overlay: half of + // either reads as something else. The indicator goes first when the two cannot both fit, + // because with a campaign selected the footer's last slot names `ctrl-c quit` and this + // is the only place on the board that says `q` gives it back. + let both = format!("{hint}{indicator}"); + let left = [both.as_str(), hint, ""] + .into_iter() + .find(|left| left.chars().count() + taken <= room) + .unwrap_or_default(); + if !left.is_empty() { block = block - .title_bottom(Line::from(Span::styled(hint, Style::default().fg(Color::Grey.into())))); + .title_bottom(Line::from(Span::styled(left, Style::default().fg(Color::Grey.into())))); } block = block.title_bottom(Line::from(standing_spans).right_aligned()); - // The description's opening line, or the placeholder in grey for a campaign that has - // none: the row is spent either way, and a blank one reads as a frame that failed to - // draw. Wrapped off, so a long line is cut at the border rather than pushing the frame - // taller than the geometry says it is. - let summary = match campaign.summary.is_empty() { - true => Span::styled(DESCRIPTION.placeholder, Style::default().fg(Color::Grey.into())), - false => Span::raw(campaign.summary.clone()), - }; + // Wrapped and scrolled, where the one row it opened with was cut at the border: with + // three rows a description has somewhere to go, and `pgup` and `pgdn` reach whatever is + // past them. `Wrap` cannot push the frame taller than the geometry says it is — the rows + // past the bottom are simply not drawn, which is what the offset is for. + frame.render_widget( + Paragraph::new(prose) + .block(block) + .wrap(Wrap { trim: false }) + .scroll((offset, 0)), + area, + ); +} - frame.render_widget(Paragraph::new(Line::from(summary)).block(block), area); +/// The campaign's description as the frame draws it, or the placeholder for a campaign with +/// none. +/// +/// The placeholder rather than a blank row, the bargain the one-row frame already took: the +/// rows are spent either way, and an empty frame reads as one that failed to draw. Grey, +/// because it is the absence of prose rather than prose. +/// +/// One place, for the reason `wrapped_height` is one place: the draw, the scroll clamp and +/// the page indicator all measure this, and prose measured twice is two heights free to +/// disagree about where the end of it is. +fn frame_prose(campaign: &CampaignRow) -> Text<'static> { + match campaign.description.is_empty() { + true => Text::from(Line::from(Span::styled( + DESCRIPTION.placeholder, + Style::default().fg(Color::Grey.into()), + ))), + false => Text::from(campaign.description.clone()), + } } /// The campaign frame's title: `(id) ~codename · Name`, cut to the border it sits on. @@ -1889,6 +2140,13 @@ fn draw_columns(frame: &mut Frame, board: &Board, area: Rect) { let columns = board.visible(); let areas = column_areas(area, columns.len()); + // Whether a card can be picked out at all. While the frame above holds the selection no + // card is selected, so none is drawn reversed — that highlight is what `y` and `enter` + // act on, and one left up there would be pointing at a ticket neither key would touch. + // The focused column keeps its cyan border regardless, because it is where `↓` comes + // back to, and that is the one thing about the columns still worth saying. + let on_cards = board.current().focus == Focus::Cards; + for (index, column) in columns.iter().enumerate() { let focused = index == board.current().column; let title = format!(" {} ({}) ", column.status, column.cards.len()); @@ -1918,7 +2176,7 @@ fn draw_columns(frame: &mut Frame, board: &Board, area: Rect) { let mut lines: Vec = Vec::new(); let mut starts: Vec = Vec::new(); for (at, card) in column.cards.iter().enumerate() { - let selected = focused && at == board.current().card; + let selected = focused && on_cards && at == board.current().card; starts.push(lines.len() as u16); lines.extend(card_lines(card, selected, text.width)); } @@ -1990,6 +2248,19 @@ fn board_area(screen: Size, chrome: Chrome) -> Rect { frame_rows(Rect::new(0, 0, screen.width, screen.height), chrome)[BOARD_ROW] } +/// The rows of the campaign frame that hold prose: inside its border. +/// +/// Through `frame_rows` rather than by arithmetic on [`Chrome::CAMPAIGN_PROSE_ROWS`], for +/// the reason `board_area` is: geometry reproduced by hand is geometry that comes to +/// disagree with the draw. What `scroll_frame` measures its step and its clamp against, +/// which is why it takes the screen — the same relationship `column_text_height` has with +/// `draw_columns`. Zero-height with no campaign selected, which is why `scroll_frame` asks +/// for one before it measures. +fn frame_text_area(screen: Size, chrome: Chrome) -> Rect { + frame_rows(Rect::new(0, 0, screen.width, screen.height), chrome)[CAMPAIGN_ROW] + .inner(Margin::new(1, 1)) +} + /// 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 @@ -2414,11 +2685,25 @@ fn draw_footer(frame: &mut Frame, board: &Board, area: Rect) { false => "c campaign ", }; - let keys = match board.detail { - Some(_) => format!( + // Three states, because the frame is a third place the selection can be and the row + // must describe the keys that work where it is. An open ticket wins over both, which is + // what owning `pgup` and `pgdn` means. + // + // On the frame, `↓` is the way back to the cards and the two scroll keys are the + // frame's; `y` is named because it still copies an id, the campaign's. `enter` and `←→` + // are left out because they do nothing there. Incomplete rather than wrong, the trade + // this row is allowed to make — what it must never do is name a key by what it used to + // do. `↑ frame` is not named on the board for the same reason `c` is dropped from a + // filtered board: the frame is drawn right above the columns and up is the key that + // reaches it, and the row has no cells to spend saying so. + let keys = match (board.detail.is_some(), board.current().focus) { + (true, _) => format!( " {tabs}←→↑↓ select pgup/pgdn scroll / search y copy id enter/q close {done} {quit} " ), - None => format!( + (false, Focus::Frame) => { + format!(" {tabs}↓ board pgup/pgdn scroll / search y copy id {done} {quit} ") + } + (false, Focus::Cards) => format!( " {tabs}←→ column ↑↓ card / search {campaign}y copy id enter detail {done} {quit} " ), }; @@ -2705,9 +2990,9 @@ fn picker_line(campaign: &CampaignRow, selected: bool, width: u16) -> Line<'stat // What the campaign is *called* takes the row first, and the prose takes what is left. // Under three characters there is nothing left to say, the bargain `project_label` makes. let used = spans_width(&spans); - let summary = match campaign.summary.is_empty() { + let summary = match campaign.summary().is_empty() { true => campaign.title.as_str(), - false => campaign.summary.as_str(), + false => campaign.summary(), }; if let Some(room) = (width as usize).checked_sub(used + 2).filter(|room| *room >= 3) { let cut = match summary.chars().count() <= room { @@ -2787,7 +3072,13 @@ fn scroll_step(height: u16) -> u16 { /// 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 { +/// +/// Shared by the detail overlay and the campaign frame, which is why the width is the +/// border's and not one view's: a reader who learns what `pg 2/3` means on a ticket reads +/// it the same way above the columns. It says only whether the indicator fits the border at +/// all; a caller with something else on that border checks against that itself, which the +/// frame does and the overlay has no need to. +fn page_indicator(offset: u16, last: u16, height: u16, border_width: u16) -> Option { // 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 { @@ -2805,9 +3096,8 @@ fn page_indicator(offset: u16, last: u16, height: u16, overlay_width: u16) -> Op // 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 { + // columns are not the indicator's to write on. + match indicator.chars().count() <= border_width.saturating_sub(2) as usize { true => Some(indicator), false => None, } @@ -2995,6 +3285,18 @@ mod tests { render(board, width, height).remove(top) } + /// The campaign frame's rows, cut out of the drawn buffer by its own geometry. + /// + /// Through `frame_rows` for the reason `headings` goes through the layout: the frame sits + /// a row lower when a tab row is drawn above it, and it grew from three rows to five when + /// its prose became scrollable. A test counting rows by hand goes on measuring whichever + /// rows used to be the frame. + fn frame_lines(board: &Board, width: u16, height: u16) -> Vec { + let area = frame_rows(Rect::new(0, 0, width, height), board.chrome())[CAMPAIGN_ROW]; + let lines = render(board, width, height); + lines[area.y as usize..(area.y + area.height) as usize].to_vec() + } + /// The tab row, which is the top row whenever it is drawn at all. fn tab_row(board: &Board, width: u16, height: u16) -> String { render(board, width, height).remove(0) @@ -6582,19 +6884,26 @@ mod tests { let mut board = campaign_board(&dir); board.select_campaign(Some(V1.to_string()), SCREEN); - let rows = render(&board, 100, 24); + let rows = frame_lines(&board, 100, 24); + assert_eq!( + rows.len(), + Chrome::CAMPAIGN_ROWS as usize, + "the frame is a different height" + ); + + let bottom = rows.len() - 1; assert!(rows[0].contains(short_id(V1)), "no id on the frame: {:?}", rows[0]); assert!(rows[0].contains("~v1"), "no codename on the frame: {:?}", rows[0]); assert!(rows[0].contains("First public release"), "no name: {:?}", rows[0]); assert!( rows[1].contains("Everything for a public tag."), - "no summary: {:?}", + "no description: {:?}", rows[1] ); - assert!(rows[2].contains("0/2 done"), "no standing: {:?}", rows[2]); - assert!(rows[2].contains("[open]"), "no derived state: {:?}", rows[2]); + assert!(rows[bottom].contains("0/2 done"), "no standing: {:?}", rows[bottom]); + assert!(rows[bottom].contains("[open]"), "no derived state: {:?}", rows[bottom]); // The way out, on the border of the thing it undoes. - assert!(rows[2].contains("q board"), "no way out named: {:?}", rows[2]); + assert!(rows[bottom].contains("q board"), "no way out named: {:?}", rows[bottom]); std::fs::remove_dir_all(&dir).ok(); } @@ -6653,6 +6962,529 @@ mod tests { std::fs::remove_dir_all(&dir).ok(); } + // ------------------------------------------------------- the frame's own prose -- + + /// A description of numbered lines, so a test can say which of them is on screen. + /// + /// `long_section` for a campaign, and longer than the frame at any width these tests + /// draw, which is true of every campaign description filed in this repo. + fn long_description(lines: usize) -> String { + (1..=lines).map(|n| format!("Line {n:03}\n")).collect() + } + + /// `campaign_board` filtered to v1, with a description that has somewhere to scroll. + /// + /// The same tickets as every other campaign test reasons about, and `write_campaign` + /// again over the same uuid and title, which is the same file: the columns are the + /// fixture's and only the prose above them is this one's. + fn frame_board(dir: &Path, lines: usize) -> Board { + campaign_board(dir); + write_campaign(dir, V1, "First public release", "v1", &long_description(lines)); + + let mut board = one_board(dir); + board.select_campaign(Some(V1.to_string()), SCREEN); + board + } + + /// Whether any card is drawn picked out, which is what the reversed modifier does. + /// + /// Read off the buffer rather than off `card_lines`, because the question is what the + /// reader can see: the highlight is the only thing that says which ticket `y` and + /// `enter` are about, and while the frame holds the selection they are about none. + fn a_card_is_highlighted(board: &Board, width: u16, height: u16) -> bool { + let mut terminal = Terminal::new(TestBackend::new(width, height)).unwrap(); + terminal.draw(|frame| draw(frame, board)).unwrap(); + let buffer = terminal.backend().buffer().clone(); + let area = board_area(Size { width, height }, board.chrome()); + + (area.y..area.y + area.height) + .flat_map(|y| (area.x..area.x + area.width).map(move |x| (x, y))) + .any(|(x, y)| buffer[(x, y)].modifier.contains(Modifier::REVERSED)) + } + + /// The frame spends its prose rows on prose, which is the whole point of taking them: + /// a line and a half of a description was the wrong amount for the place the question + /// it answers gets asked. + #[test] + fn the_frame_draws_a_row_of_the_description_for_every_row_it_takes() { + let dir = board_dir(); + let board = frame_board(&dir, 40); + + let rows = frame_lines(&board, 120, 20); + assert_eq!( + rows.len(), + Chrome::CAMPAIGN_ROWS as usize, + "the frame is a different height" + ); + + // The prose rows are the frame's rows less the border either side of them. + let prose = &rows[1..rows.len() - 1]; + assert_eq!( + prose.len(), + Chrome::CAMPAIGN_PROSE_ROWS as usize, + "not all of them are prose" + ); + + for (at, drawn) in prose.iter().enumerate() { + let wanted = format!("Line {:03}", at + 1); + assert!(drawn.contains(&wanted), "no {wanted} on the frame: {drawn:?}"); + } + + std::fs::remove_dir_all(&dir).ok(); + } + + /// Up past the top card reaches the frame, and down comes back to the column it was + /// left in rather than to the first one: the column index is never what changed. + #[test] + fn up_from_the_top_card_reaches_the_frame_and_down_returns_to_the_column() { + let dir = board_dir(); + let mut board = frame_board(&dir, 40); + + board.select_column(1, SCREEN); + assert_eq!( + selected_title(&board).as_deref(), + Some("Also in v1"), + "the fixture changed" + ); + + board.select_card(-1, SCREEN); + assert_eq!(board.current().focus, Focus::Frame, "up from the top card stayed put"); + + // And no further up: the frame is the top of the board, the answer the top card of + // a column already gives. + board.select_card(-1, SCREEN); + assert_eq!(board.current().focus, Focus::Frame, "up from the frame went somewhere"); + + board.select_card(1, SCREEN); + assert_eq!(board.current().focus, Focus::Cards, "down did not leave the frame"); + assert_eq!(board.current().column, 1, "down landed in a different column"); + assert_eq!(selected_title(&board).as_deref(), Some("Also in v1")); + + std::fs::remove_dir_all(&dir).ok(); + } + + /// An empty column reaches it too. A column with no card to stand on must not be a + /// column the reader is stuck in, which is what the old clamp made of it. + #[test] + fn an_empty_column_still_reaches_the_frame() { + let dir = board_dir(); + let mut board = frame_board(&dir, 40); + + board.select_column(2, SCREEN); + assert!(board.selected().is_none(), "the fixture's third column is not empty"); + + board.select_card(-1, SCREEN); + assert_eq!( + board.current().focus, + Focus::Frame, + "an empty column trapped the selection" + ); + + board.select_card(1, SCREEN); + assert_eq!(board.current().column, 2, "down landed somewhere else"); + + std::fs::remove_dir_all(&dir).ok(); + } + + /// The two keys the overlay reads a ticket with read the frame's description, clamped + /// at both ends off the same wrapped measurement the draw uses. + #[test] + fn the_scroll_keys_page_through_the_frame_while_it_holds_the_selection() { + let dir = board_dir(); + let mut board = frame_board(&dir, 40); + board.select_card(-1, SCREEN); + + board.scroll_page(1, SCREEN); + let one = board.current().frame_offset; + assert!(one > 0, "the frame did not move"); + + board.scroll_page(1, SCREEN); + assert!(board.current().frame_offset > one, "the second page did not move"); + + // Both ends, the clamp the overlay applies: the last page ends with the prose + // rather than running on into blank rows, and the top is zero. + board.scroll_page(40, SCREEN); + let text = frame_text_area(SCREEN, board.chrome()); + let last = last_offset(&frame_prose(board.campaign().expect("no campaign")), text); + assert_eq!(board.current().frame_offset, last, "the scroll ran past the description"); + + board.scroll_page(-40, SCREEN); + assert_eq!(board.current().frame_offset, 0, "the scroll ran off the top"); + + std::fs::remove_dir_all(&dir).ok(); + } + + /// And only while it holds the selection. On the cards the keys are what they were + /// before the frame could scroll, which is nothing. + #[test] + fn the_scroll_keys_leave_the_frame_alone_from_the_cards() { + let dir = board_dir(); + let mut board = frame_board(&dir, 40); + assert_eq!(board.current().focus, Focus::Cards, "the board opened on the frame"); + + board.scroll_page(1, SCREEN); + assert_eq!(board.current().frame_offset, 0, "the frame scrolled from the cards"); + + std::fs::remove_dir_all(&dir).ok(); + } + + /// An open ticket keeps both keys whatever holds the selection behind it. It is the + /// thing the reader put on and the thing they are reading, and it has had them since + /// 1b78a24. + /// + /// The state is built by hand because no keypress produces it: up stops at the top card + /// while a ticket is open, which the next test is. The precedence is what has to be + /// written down, and it holds whether or not there is a way to reach the state. + #[test] + fn an_open_ticket_keeps_the_scroll_keys_from_the_frame() { + let dir = board_dir(); + write_campaign(&dir, V1, "First public release", "v1", &long_description(40)); + let mut extra = campaign_field(V1); + extra.push_str(&long_section(60)); + write_ticket( + &dir, + "backlog", + "11111111-0000-4000-8000-000000000000", + "A long one", + &extra, + ); + + let mut board = one_board(&dir); + board.select_campaign(Some(V1.to_string()), SCREEN); + board.toggle_detail(); + assert!(board.detail.is_some(), "nothing opened"); + + let tab = board.tab; + board.tabs[tab].focus = Focus::Frame; + board.scroll_page(1, SCREEN); + + assert!(board.offset > 0, "the open ticket lost the scroll keys"); + assert_eq!(board.current().frame_offset, 0, "the frame took them from under it"); + + std::fs::remove_dir_all(&dir).ok(); + } + + /// And the frame is out of reach from under an open ticket. Up and down step through + /// the tickets there and the overlay follows, so a selection that reached the frame + /// would have to either close the overlay on an arrow key or leave it showing a ticket + /// nothing is selecting. + #[test] + fn the_frame_is_out_of_reach_from_under_an_open_ticket() { + let dir = board_dir(); + let mut board = frame_board(&dir, 40); + board.toggle_detail(); + assert!(board.detail.is_some(), "nothing opened"); + + board.select_card(-1, SCREEN); + assert_eq!(board.current().focus, Focus::Cards, "the frame took the selection"); + assert!(board.detail.is_some(), "the overlay closed on an arrow key"); + + std::fs::remove_dir_all(&dir).ok(); + } + + /// The frame says there is more of it than fits, in the words the overlay says it in: + /// a reader who has learned what `pg 2/3` means on a ticket reads it the same way here. + #[test] + fn the_frame_says_there_is_more_of_it_than_fits() { + let dir = board_dir(); + let mut board = frame_board(&dir, 40); + board.select_card(-1, SCREEN); + + let bottom = |board: &Board| { + let rows = frame_lines(board, 120, 20); + rows[rows.len() - 1].clone() + }; + + let first = bottom(&board); + assert!(first.contains("pg 1/"), "no indicator on a scrollable frame: {first:?}"); + // Beside the way out and clear of the standing, which is the frame's own corner. + assert!(first.contains("q board"), "the indicator took the way out: {first:?}"); + assert!(first.contains("0/2 done"), "the indicator took the standing: {first:?}"); + + board.scroll_page(1, SCREEN); + let second = bottom(&board); + assert!( + second.contains("pg 2/"), + "the indicator did not follow the scroll: {second:?}" + ); + + std::fs::remove_dir_all(&dir).ok(); + } + + /// A description that fits leaves the frame selectable and the keys inert. Making the + /// frame unreachable instead would be a key that works on one campaign and not the + /// next, which is worse than a key that sometimes has nothing to scroll. + #[test] + fn a_description_that_fits_leaves_the_frame_selectable_and_the_keys_inert() { + let dir = board_dir(); + let mut board = campaign_board(&dir); + board.select_campaign(Some(V1.to_string()), SCREEN); + + board.select_card(-1, SCREEN); + assert_eq!(board.current().focus, Focus::Frame, "the short frame was unreachable"); + + board.scroll_page(1, SCREEN); + assert_eq!(board.current().frame_offset, 0, "a description that fits scrolled"); + + let rows = frame_lines(&board, 120, 20); + let bottom = &rows[rows.len() - 1]; + assert!( + !bottom.contains("pg "), + "an indicator over a description that fits: {bottom:?}" + ); + + std::fs::remove_dir_all(&dir).ok(); + } + + /// A campaign with no description is reachable and spends its rows on the placeholder. + /// The rows are taken either way, and an empty frame reads as one that failed to draw. + #[test] + fn a_campaign_with_no_description_is_reachable_and_shows_its_placeholder() { + let dir = board_dir(); + write_campaign(&dir, V1, "First public release", "v1", ""); + write_ticket( + &dir, + "backlog", + "11111111-0000-4000-8000-000000000000", + "In v1", + &campaign_field(V1), + ); + + let mut board = one_board(&dir); + board.select_campaign(Some(V1.to_string()), SCREEN); + + let rows = frame_lines(&board, 120, 20); + assert!( + rows[1].contains(DESCRIPTION.placeholder), + "no placeholder on an empty frame: {:?}", + rows[1] + ); + + board.select_card(-1, SCREEN); + assert_eq!(board.current().focus, Focus::Frame, "an empty frame was unreachable"); + + std::fs::remove_dir_all(&dir).ok(); + } + + /// The footer describes the keys that work where the selection is, which on the frame + /// is a different list. What it must never do is name a key by what it used to do. + #[test] + fn the_footer_names_the_keys_that_work_on_the_frame() { + let dir = board_dir(); + let mut board = frame_board(&dir, 40); + board.select_card(-1, SCREEN); + + let row = footer(&board, 120, 20); + assert!(row.contains("↓ board"), "no way back to the cards named:\n{row}"); + assert!(row.contains("pgup/pgdn scroll"), "the scroll keys are not named:\n{row}"); + assert!(row.contains("y copy id"), "the copy key is not named:\n{row}"); + // Both do nothing here, so neither is offered. + assert!(!row.contains("enter detail"), "enter is named and does nothing:\n{row}"); + assert!( + !row.contains("←→ column"), + "the column keys are named and do nothing:\n{row}" + ); + // And the last slot still answers how to get out, which from here is `ctrl-c`. + assert!(row.contains("ctrl-c quit"), "nothing says what quits from here:\n{row}"); + + std::fs::remove_dir_all(&dir).ok(); + } + + /// No card is selected while the frame holds the selection, and none is drawn as if it + /// were: that highlight is what says which ticket `enter` is about. + #[test] + fn no_card_is_selected_while_the_frame_holds_the_selection() { + let dir = board_dir(); + let mut board = frame_board(&dir, 40); + assert!( + a_card_is_highlighted(&board, 120, 20), + "nothing was picked out to begin with" + ); + + board.select_card(-1, SCREEN); + assert!(board.selected().is_none(), "a card was handed back from the frame"); + assert!(!a_card_is_highlighted(&board, 120, 20), "a card is still drawn picked out"); + + board.toggle_detail(); + assert!(board.detail.is_none(), "enter opened a ticket nothing was selecting"); + + board.select_card(1, SCREEN); + assert!(a_card_is_highlighted(&board, 120, 20), "the highlight did not come back"); + + std::fs::remove_dir_all(&dir).ok(); + } + + /// `y` copies the id of what is selected in every state the selection can be in, and on + /// the frame that is the campaign whose id the top border prints. + #[test] + fn the_copy_key_takes_the_campaigns_id_from_the_frame() { + let dir = board_dir(); + let mut board = frame_board(&dir, 40); + board.select_card(-1, SCREEN); + + assert_eq!(board.copy_text().as_deref(), Some(short_id(V1)), "not the campaign's id"); + + board.select_card(1, SCREEN); + assert_eq!( + board.copy_text().as_deref(), + Some(short_id("11111111-0000-4000-8000-000000000000")), + "back on the cards it is not the ticket's id" + ); + + std::fs::remove_dir_all(&dir).ok(); + } + + /// Left and right do nothing on the frame. It spans the width of the board, so there is + /// nothing beside it, and moving the column underneath would change nothing on screen + /// until the selection came back down. + #[test] + fn the_column_keys_are_inert_while_the_frame_holds_the_selection() { + let dir = board_dir(); + let mut board = frame_board(&dir, 40); + board.select_column(1, SCREEN); + board.select_card(-1, SCREEN); + + board.select_column(1, SCREEN); + assert_eq!(board.current().focus, Focus::Frame, "a column key left the frame"); + assert_eq!(board.current().column, 1, "a column key moved where down comes back to"); + + std::fs::remove_dir_all(&dir).ok(); + } + + /// `q` gives the whole board back from the frame, as it does from the columns: the + /// frame is the campaign filter drawn, so taking it off is taking the filter off. + #[test] + fn q_gives_the_whole_board_back_from_the_frame() { + let dir = board_dir(); + let mut board = frame_board(&dir, 40); + board.select_card(-1, SCREEN); + + board.dismiss(SCREEN); + assert_eq!(board.current().campaign, None, "the campaign is still selected"); + assert_eq!( + board.current().focus, + Focus::Cards, + "the selection is on a frame nothing draws" + ); + assert!(!board.should_quit, "the board quit out from under the frame"); + + let all: usize = board.current().columns.iter().map(|c| c.cards.len()).sum(); + assert_eq!(all, 4, "the whole board did not come back"); + + std::fs::remove_dir_all(&dir).ok(); + } + + /// A jump lands on a card, so it takes the selection off the frame: `/` reaching a + /// ticket the frame still held would leave the highlight where none of the keys that + /// act on a ticket do anything. + #[test] + fn a_jump_takes_the_selection_off_the_frame() { + let dir = board_dir(); + let mut board = frame_board(&dir, 40); + board.select_card(-1, SCREEN); + + board.open_search(); + for c in "Also".chars() { + board.search_key(letter(c), SCREEN); + } + board.search_key(typed(KeyCode::Enter), SCREEN); + + assert_eq!( + board.current().focus, + Focus::Cards, + "the jump left the selection on the frame" + ); + assert_eq!(selected_title(&board).as_deref(), Some("Also in v1")); + + std::fs::remove_dir_all(&dir).ok(); + } + + /// The offset is the tab's, beside the filter, since the filter is per tab: how far into + /// a description a reader has got is a fact about the tab drawing it. + #[test] + fn the_frame_offset_is_the_tabs_own() { + let one = board_dir(); + let two = board_dir(); + write_campaign(&one, V1, "First public release", "v1", &long_description(40)); + write_ticket( + &one, + "backlog", + "11111111-0000-4000-8000-000000000000", + "In v1", + &campaign_field(V1), + ); + write_ticket(&two, "backlog", "77777777-0000-4000-8000-000000000000", "Elsewhere", ""); + + let mut board = boards(&[("one", &one), ("two", &two)]); + board.select_campaign(Some(V1.to_string()), SCREEN); + board.select_card(-1, SCREEN); + board.scroll_page(1, SCREEN); + + let at = board.current().frame_offset; + assert!(at > 0, "the merge tab's frame did not scroll"); + + board.select_tab(2, SCREEN); + assert_eq!(board.current().frame_offset, 0, "the offset came across to another tab"); + assert_eq!(board.current().focus, Focus::Cards, "so did the focus"); + + board.select_tab(-2, SCREEN); + assert_eq!(board.current().frame_offset, at, "the tab did not keep its place"); + assert_eq!(board.current().focus, Focus::Frame, "the tab did not keep its focus"); + + std::fs::remove_dir_all(&one).ok(); + std::fs::remove_dir_all(&two).ok(); + } + + /// Changing the filter puts the frame back at the top, the answer `refresh_detail` + /// gives the overlay when the ticket under it changes: it is a different campaign's + /// description, and a reader opening on line 20 of it is reading nothing. + #[test] + fn changing_the_filter_puts_the_frame_back_at_the_top() { + let dir = board_dir(); + let mut board = frame_board(&dir, 40); + board.select_card(-1, SCREEN); + board.scroll_page(1, SCREEN); + assert!(board.current().frame_offset > 0, "nothing scrolled"); + + board.select_campaign(Some(BEAVER.to_string()), SCREEN); + assert_eq!(board.current().frame_offset, 0, "the new campaign opened partway down"); + assert_eq!(board.current().focus, Focus::Cards, "the selection stayed on the frame"); + + std::fs::remove_dir_all(&dir).ok(); + } + + /// A campaign that leaves the board takes the frame with it, focus and offset both: the + /// filter goes back to the whole board, and a frame nothing draws must not be holding + /// the selection. + #[test] + fn a_campaign_that_leaves_the_board_takes_the_frame_with_it() { + let dir = board_dir(); + let mut board = frame_board(&dir, 40); + board.select_card(-1, SCREEN); + board.scroll_page(1, SCREEN); + + std::fs::remove_file(dir.join(CAMPAIGNS_DIR).join(format!( + "{}_{}.md", + V1, + slug("First public release") + ))) + .unwrap(); + assert!( + board.tick().expect("the reload failed"), + "the campaign file is not watched" + ); + + assert_eq!(board.current().campaign, None, "the filter survived its campaign"); + assert_eq!( + board.current().focus, + Focus::Cards, + "the selection is on a frame nothing draws" + ); + assert_eq!(board.current().frame_offset, 0, "the offset outlived the description"); + + std::fs::remove_dir_all(&dir).ok(); + } + /// `q` takes off one layer at a time, in the order they were put on: the overlay, then /// the campaign, then the board. Quitting out from under a filter is what `q` used to /// do to an open ticket. diff --git a/src/util.rs b/src/util.rs index e090f48..86052b1 100644 --- a/src/util.rs +++ b/src/util.rs @@ -1776,23 +1776,38 @@ fn section_body(lines: &[&str], heading: &str) -> Option> Some(after..section_end(lines, after)) } -/// The first line of a section's body, or nothing when the section is absent or holds -/// only its placeholder. +/// A section's body as prose, or nothing when the section is absent or holds only its +/// placeholder. /// -/// For a view with one row to spend on prose: the board's campaign frame and its picker -/// both want the opening line of a description and have no room for the rest. Through -/// [`section_body`] rather than a scan of its own, so what counts as the section is +/// The whole of it, the blank lines between paragraphs included, for a view that can page +/// through what it cannot fit: the board's campaign frame gives a description three rows +/// and scrolls the rest, and the one line the picker draws is the first line of this. +/// +/// It replaced `section_opening`, which did the cut here. The cut belongs to the view that +/// wants one line, not to the read: the file is only in hand while the campaigns directory +/// is being read, so what that read has to carry is everything a view might want, and +/// `CampaignRow::summary` is where the one line comes off it again. +/// +/// Through [`section_body`] rather than a scan of its own, so what counts as the section is /// decided in one place, and the placeholder reads as nothing here the way it does to -/// `append`. -pub fn section_opening(content: &str, section: &Section) -> Option { +/// `append`. Only the ends are trimmed: those blanks separate the body from its heading and +/// from whatever follows, and a view that kept them would open on empty rows and scroll +/// past empty ones at the end. Indentation inside a line survives, since a nested list is +/// part of the prose. +pub fn section_prose(content: &str, section: &Section) -> Option { let lines: Vec<&str> = content.lines().collect(); let body = section_body(&lines, section.heading)?; - lines[body] + let kept: Vec<&str> = lines[body] .iter() - .map(|line| line.trim()) - .find(|line| !line.is_empty() && *line != section.placeholder) - .map(|line| line.to_string()) + .map(|line| line.trim_end()) + .filter(|line| *line != section.placeholder) + .collect(); + + let start = kept.iter().position(|line| !line.is_empty())?; + let end = kept.iter().rposition(|line| !line.is_empty())?; + + Some(kept[start..=end].join("\n")) } /// Where the body's content ends, ignoring the blank lines that separate it from