Files
worklane/docs/tui-board.md
T

51 KiB
Raw Blame History

The TUI

The TUI: the columns, the cards, the frame, the pickers and the footer.

The Board View

  • The board is for a person, and only for a person. Scripts and agents drive worklane through the CLI, which is what assets/SKILL.md teaches and what the integration tests pin. Nothing parses the drawn frame, so its layout is free to change: a new row on a card, a moved corner, a different colour or a hidden column breaks no caller. Judge a change here on whether it reads well, not on what it might break, and do not preserve a layout for compatibility's sake. What the CLI prints is the opposite case and is not covered by this
  • worklane with no subcommand and worklane tui both open it, the way a bare frig does. Cli::command is therefore an Option
  • The worklane directory is looked for before the terminal, so running outside one gives the usual "No .worklane directory found" rather than a complaint about the tty. Both errors stay reachable and both are testable without a pty
  • A missing tty is refused with a message naming a subcommand. Raw mode on a pipe fails with a bare "No such device or address (os error 6)", which explains nothing
  • The watch looks at files, not directories. A directory's mtime only moves on create and rename, so a ticket edited in place would be missed. digest() hashes every ticket and comment file's path, length and mtime. Comment files are in it because a comment added elsewhere has to reach the detail view
  • The digest guards the rescan, not the draw. ratatui diffs its buffer, so drawing every iteration is free; reading the tree every iteration is not
  • notify is deliberately not a dependency. Polling a tree of tens of small files on the 250ms tick is enough, and the reason is recorded on f6af387
  • Cards come from collect_ticket_items, the same source ls uses, so there is no second parser. TicketItem::path exists for the detail view
  • The detail view scrolls on pgup and pgdn, not on up and down. Up and down stay on the selection with the modal open, so a whole column can be read without closing it, and the modal follows. That is worth more than the two keys, which is why the scroll went elsewhere rather than taking them
  • The 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
  • 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
  • Entering another column follows the selection rather than resetting to its top. The card index carries across columns, so a reset would open the column with the highlight below the fold whenever it was — the opposite of the detail view's reset-on-selection-move, where each ticket genuinely starts at its own top. The index is shared and clamps permanently when a shorter column pulls it down, so a column you return to follows the selection to where it now sits rather than holding your old place
  • The footer names only keys that work. It read ↑↓ scroll when nothing scrolled at all, which sends the reader looking for their own mistake. A UI that misdescribes itself is worse than one that is merely incomplete
  • A hint is a key and what pressing it does, and key_hint is the only thing that draws one. The key is cyan and bold, the description takes the terminal's default foreground, and the row keeps its three-space gaps. Everything that names a key goes through it: the three footer states, the prompt's two keys, the picker's row and the q board on the frame's border, so a reader learns the shape once. Same division in frig and pantop, each in its own accent colour, cyan here and magenta there — the three tools are read side by side and used to look like three programs
  • A key that is its description's first letter is merged into it, so the board draws quit, campaign and tag with the letter coloured and no letter in front, while y copy id, ctrl-c quit, d show done (2) and every arrow row stay split. Two cells back on a row already at its width naming eight keys, and the coloured letter is the key either way. The prefix test in key_hint is case sensitive for exactly that reason: a row naming both r and R would otherwise draw one word for the two of them, and the merged form can only say which key it is while the letter on screen is that key. It also means the row carries both forms at once, which is the cost of the two cells
  • What the row is cannot be read off its text any more, so the tests read its cells. footer_cells, footer_at, keys_on and footer_style in the test module: keys_on(.., "quit") is Some(1) where q quits and Some(0) on a row whose only quit is the tail of ctrl-c quit. A contains("q quit") cannot tell those apart, and three of the guards that keep 1b78a24 out were written that way
  • q and esc are one key: close what is open, quit when there is nothing left to close. q used to set should_quit outright, so a reader who pressed it to put a ticket away lost the board instead, which is not what q does anywhere else that lays a document over a list. One match arm in main.rs, not two: two arms carrying one rule is how a later edit changes it for one key and not the other
  • The rule is Board::dismiss, not the match arm. The dispatch in main.rs is not reachable from a test, so anything decided there is undecidable by the suite. The arm is the line that names the keys and nothing else. the_dispatch_gives_q_and_esc_one_arm_and_leaves_ctrl_c_quitting scans main.rs for what the arm cannot say for itself, over whitespace-collapsed source so rustfmt cannot fail it
  • The footer's last slot always answers how to get out, and with a ticket open the honest answer is ctrl-c, the only key left that quits in one press. Going on drawing the merged quit there would be 1b78a24 in the other direction: a footer describing a key by what it used to do. ctrl-c quit is split by the same rule that merges the other, being no word's first letter
  • The overlay names its ticket on the border, not at the head of the paragraph. Board::detail is a Detail carrying the title, the id and the text, because the name has to travel beside the body rather than inside it: content_trim drops the # heading on purpose, since cmd_show prints it, and anything in the paragraph scrolls away
  • detail_title cuts the string itself instead of leaving it to ratatui, which truncates an overlong block title at whatever cell it reaches and would take the id with it. Cut against the inner width, so the id survives whole and the name ends in an ellipsis. The id goes first because that is how every other view addresses a ticket
  • The detail view renders from cells, never from painted strings: ratatui draws styled spans, so an escape sequence in a paragraph would be printed as literal bytes. content_trim and format_history_with take the colour decision for the CLI's side of the same layouts
  • Read only. Moving a card by keypress is a follow-up, deliberately kept out until the watch and render loop were solid
  • A card is four corners with the title between them: mark and short id top left, due top right, owner bottom left, comment count then criteria count bottom right. The numbers are in corners because that is where the eye goes for one, and they were invisible at the end of a line of prose
  • The title takes one row or two, wrapped on spaces, with an ellipsis when even two are not enough. One row when one is enough: a second, blank row on every short ticket spends the column's height on nothing
  • A card's height therefore depends on the column's width, so card_lines and card_height both take it. column_areas is shared between the draw and follow_selection for the same reason: Ratio hands the remainder column to whichever slot it likes, and reproducing that arithmetic by hand is how the measurement and the draw come to disagree about where a card starts
  • A corner that will not fit is dropped whole, never truncated or wrapped: half a date reads as a different date, and a card that reflows in a narrow column changes height, which the scroll would then have to chase. The left corner is the ticket's identity and always stays
  • corner_line's right side is a group, single-spaced, and it gives up its items from the front. The item nearest the edge is what the corner is about; anything to its left has been added beside it. So the bottom row loses its comment count before its criteria count, and the top row, with one item, behaves exactly as it did when the parameter was an Option. The spacing between the items lives in corner_line with the gap arithmetic rather than in a caller, for the reason column_areas is shared: geometry reproduced by hand drifts from the draw. due_span returns a Span and not an Option<Span> now, since the Option only ever existed to satisfy the old signature and the function cannot fail
  • The criteria count is a field on TicketItem, filled in collect_ticket_items where the file is already being read, and counted through criteria() so a checkbox in a description is not counted here or numbered by show. Do not count per card: that re-reads every ticket body on every draw instead of on the tick that changed something. None rather than [0/0] for a ticket with no criteria
  • The comment count is the same field discipline and the one entry on that pass that costs a directory listing. The history lives outside the ticket file, so count_comments is a read_dir rather than a parse: .md only, the filter read_history applies, and no body is read, because a count needs none of them. It counts comments and not entries, off the kind in the filename, so a card still says how many things somebody said: a ticket that has moved three times has not been talked about, and counting the moves would put a number on every card on the board. collect_ticket_items derives the board from status_path.parent() instead of taking it as a second argument, so a status directory from one board cannot arrive with the history of another. history_dir spells the path once for the writer, the reader and the counter, the way campaigns_dir does. Zero draws nothing, not a 0 and not a blank: an uncommented card is the row it has always been, which a_card_with_no_comments_spends_nothing_on_the_corner pins to the exact spacing
  • The count is cyan and the mark is COMMENT_MARK, U+275E, a Dingbat. It is the only coloured thing on a row whose owner and criteria count are grey, because two counts side by side otherwise read as one number in brackets and another that lost its brackets. Not U+1F4AC SPEECH BALLOON: emoji presentation and East Asian Width Wide, so it draws two cells where spans_width counts one character and every corner on the card lands a cell out. Not U+1F5E8 LEFT SPEECH BUBBLE either: text presentation and Neutral, but in a pictograph block most terminal fonts leave as tofu. Check both properties before swapping the glyph
  • the_count_is_read_when_the_items_are_collected_and_not_per_draw takes the history directory away after the board is built, and is paired with a_comment_added_after_the_board_was_built_reaches_the_card_on_reload, because a count that never asks the filesystem again would pass the first test by never changing. The digest already moves when a comment lands, so the reload is what recounts
  • A card names its campaign on the label row, before the tags, in bold. labels_line draws both, CAMPAIGN_MARK (~) for the campaign and # for a tag, and the campaign takes the row's width first: two cards in one campaign is what a reader looking for a campaign is looking for, and the tags are the context around it. So a row too narrow for both drops the tags whole and keeps the campaign, the order corner_line and project_label already follow, and a campaign the row will not hold at all goes whole too. A ticket in neither spends no row, so a ticket in no campaign renders exactly as it did before campaigns reached the card
  • Card::campaign is a resolved Cell, not a uuid, settled at reload the way project and blocked are. TicketItem::campaign already carries the uuid off the pass that builds the card; the name is in another directory, so columns_of reads CampaignIndex once per project and hands it to every card. Never per draw, the rule criteria and tags already hold. The merge carries the resolved cell rather than looking it up again, for the reason it carries blocked: a campaign is addressed inside one .worklane, so a merged lookup could answer one project's uuid with another project's campaign
  • A campaign the board does not hold labels nothing, the answer mark_blocked gives a dangling blocker. campaign_cells 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 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, column_count and the copy key all keep working unchanged
  • A campaign filter is a uuid on the tab, not on the Board. Tab::filter is a Filter, and 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 has two heights, and Chrome is what every measurement takes. Chrome::frame is an Option<FrameSize>, not a bool: None for a tab showing the whole board, and Collapsed or Expanded for one filtered to a campaign or a tag, because both heights have to be measured the same way by everything that measures the board. screen_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, FRAME_ROW, BOARD_ROW, FOOTER_ROW), since an index written out by hand goes on meaning what it used to. Nothing in the geometry is named after campaigns, because the slot is the tag filter's too: Chrome::frame says how tall the frame is and never which filter filled it, so a measurement of the board never has to ask
  • 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
  • FRAME_PROSE_ROWS is the collapsed height, and it is a constant rather than 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 expanded height is a share, not a second constant: half of what the frame and the columns divide. That is the screen less the tab row and the footer, so the split is even between the two of them rather than even against rows neither gets all of. Half rather than most of it for the same reason the frame is not an overlay: the columns below are the campaign's members, and a reader inspecting the campaign has to go on seeing what it is made of. Floored, so the odd row goes to the cards. Chrome::frame_rows takes the height because of this, and screen_rows is where it is called, since that is the one place that already has an area to take a share of — which is what keeps Chrome itself pure and copyable from Board::chrome with no screen to hand
  • The share is bounded at both ends, and COLUMN_MIN_ROWS is why. Constraint::Min(COLUMN_MIN_ROWS) would take rows back from a frame that asked for too many, silently, and the frame's own measurement would then disagree with what is drawn — the fault Chrome exists to prevent. So the share is capped at what leaves the columns those rows, and floored at FRAME_ROWS, since expanding must never shrink the frame. On a board too short to divide, enter gives the collapsed height back rather than a height nothing measured. the_expanded_share_is_bounded_at_both_ends sweeps every height from 4 to 60, tabbed and not, because one screen that happens to work says nothing about the arithmetic
  • 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 slot is shared between the filters, not doubled. One filter is on at a time, per Filter, so a tag frame is the campaign frame with its three slots filled differently: #tag in tag_color on the top border where the campaign's identity goes, how many tickets carry it on the bottom right where the standing goes, and the annotation in the prose rows. FrameContent is what they are told apart into, and frame_content is the one place they are told apart at all — the borders, the colour, q board, the page indicator, the scroll and the focus are all the campaign frame's, and a second match on the filter below that is how the frames come to behave differently in a way nobody decided
  • A tag frame draws the annotation, which is the payoff for declaring a tag. Whoever is browsing a tag is deciding whether the next ticket belongs in it, and the sentence saying when the tag is appropriate is then on the screen at that moment rather than in tags.md, which they would have to know to open. An undeclared tag draws NO_ANNOTATION in grey, which is also the frame saying the word was never agreed on — the vocabulary file's own placeholder rather than the description section's, so the frame and the file say the same thing about the same tag. A tag declared with nothing said about it draws the same, since here the two have the same nothing to show; the picker's sections are where the difference is actionable
  • A tag has no id, so y on its frame copies the word. A tag is its name, matched whole by ls --tag, so there are no seven characters to shorten and the # the border draws is not part of it — --tag "#bug" matches nothing. The footer says y copy tag there for the same reason: naming it an id would send the reader looking for a short id on a border that prints a word
  • The count on a tag frame is every column's, drawn or not, the rule the standing holds. With the filter on, those columns are the tickets carrying the tag, so it counts what is below it without counting it a second way. The noun is spelled out and pluralised, because a bare number on a border says nothing about what was counted, and there is no derived state beside it: a tag is a word and not a piece of work, so there is no [open] to be in
  • 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 either filter on 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 filter is on is the one state that must never exist — select_filter and reload are what keep it from arising, off Filter::is_whole rather than off which filter it is, since either draws a frame to hold it
  • Tab::selected hands back nothing while the frame holds the selection. Every key that acts on a card has to answer for the frame. ←→ 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
  • enter routes on the focus through Board::toggle_focused: the frame's height on the frame, the overlay on a card. It used to be inert on the frame for free, because Tab::selected hands back nothing and toggle_detail therefore had nothing to open. That is no longer an answer, and the routing is in Board rather than in the main.rs arm for the reason dismiss and scroll_page are
  • q does not gain a layer for the expanded frame, and up and down do not take it back. The expanded frame is the frame at its other height, not a thing laid over the board, so q goes on taking the campaign filter off from either height and enter is the only key that undoes what enter did. The height outlives the selection for the same reason: it is a view of the campaign the reader chose, so the columns stay short with the selection on a card. Tab::expanded sits beside the filter and resets where select_campaign and reload reset the focus and the offset — a different campaign opens collapsed and at the top of its own description
  • The toggle re-clamps the frame offset, through scroll_frame(0, screen). A taller viewport has a smaller last offset than a shorter one, so where the reader was can end up past the end of the frame they just asked for. The draw clamps on its own geometry either way, but the stored value has to be clamped too or the next pgup counts down from a number the frame never showed. A scroll of no pages is that clamp and nothing else, which keeps it in the one place it lives
  • 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, and measured over its spans rather than one string since it is a key hint like any other. Drawn through key_hint and not as grey chrome: it is the one key on the board named anywhere but the footer, and a reader who has learnt to look for the cyan letter should not need a second convention to find it. The indicator beside it stays grey, having no key in it
  • c and t are named in the footer only on a closed board with nothing filtered, which is where a reader has to find them. Over an open ticket and on a filtered board they are left out: the frame's border then says how to put the filter away, and the row has no cells to spare. The tag used to be drawn on that row in its own colour, for want of a frame to draw it in, and 2a83bd4 took that away rather than saying it twice. 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, ↵ expand or ↵ collapse, the two scroll keys and y copy id — y copy tag on a tag frame — and leaves out ←→ because they do nothing there. It has to say which way ↵ goes, since the key is a toggle and the frame is always at one of its two heights. ↑ 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. Nor is the way to collapse an expanded frame named from the cards, which is the same trade again — the frame is right there and ↑ reaches it
  • picker: Option<Picker> 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
  • t opens the same picker over the tags instead, and taking a tag filters every column to the cards carrying it. Every tag the board declares or carries, matched whole and case sensitively the way ls --tag matches — the box completes the filter, so offering what the filter would refuse is the one bug it must not have. It opens on the tag already applied, the courtesy c pays a campaign-filtered board, and a board carrying no tag gets the same Notice a board with no campaigns gets
  • A picker row draws a real codename only. The row opens with the short id, so the card's ~<id> fallback would print it twice and say nothing the second time
  • One picker serves both lists, and PickerRow::key is what keeps it one. A second picker would have been a second keyboard, query and highlight to keep in step with the first; instead PickerKind decides only which list is built, and everything between the keypress and the filter runs once against the key — which since the pile arrived is a PickerKey enum rather than a bare string, because one of the answers filters on an absence and carries no string to hand back. take_picked reads the kind off the answer rather than off which list was open. Picking any of them clears the others without either setter remembering to, because select_filter replaces one Filter: one field, which is the same reason the frame slot is shared
  • The campaign picker opens with a row for the tickets in no campaign, above both sections and never truncated: the pile is the one question about a board of campaigns that no single campaign answers, and on a board whose completed tail is being kept back it would be pushed off the box if it listed among them. It draws its count where a campaign row draws its standing, so picking an empty pile is seen coming; under a query it answers "no campaign" and "none" and hides like any other row. It selects Filter::NoCampaign, its own variant — retain_campaign compares the field to the uuid it is given, so the absence case is a different predicate beside it (retain_no_campaign) and not a different value in it, and a magic uuid meaning none is exactly the thing that later matches a real one. A dangling uuid is set wrongly and stays out of the view, as it draws _missing_ on its card rather than nothing at all
  • The pile crosses boards where a campaign cannot, so it is pickable on the merge tab. An unset field means the same thing in every .worklane, the property that lets a tag filter travel there; the count adds across boards, taken at reload off the unfiltered columns like the standings are (Tab::no_campaign), never per draw and never off the filtered columns, which would answer zero about themselves
  • The opening highlight still lands on the first campaign, not on the pile. Campaigns are what this list opens for; the row sits above the list without claiming it — one step up reaches it, it holds the highlight whenever it was the row selected, and only when every campaign is hidden does it take the opening one
  • The frame speaks for the pile in its own words, because the frame question stays is_whole(). Exempting one variant from either half of that rule would be a state where the selection rests on a frame that is not drawn — the one thing Focus exists to make unrepresentable. So the title is grey no campaign (no id to shorten and no mark, which keeps ~ meaning a campaign and # a tag), the standing corner takes the count, and the prose is one grey sentence the board owns, since no file holds words for an absence
  • y has nothing to copy from the pile's frame — no id to shorten and no word a command line takes, ls --campaign being unable to say none — so the footer leaves the key out rather than naming it into a notice, and pressing it anyway still answers "nothing to copy"
  • The picker draws two sections, open campaigns above completed, and truncates the completed tail. One flat list by title put the finished campaigns among the open ones forever, and the tail only grows, so on a board that has run for a while the campaigns worth picking were pushed towards the bottom of the box and eventually off it. Open keeps the index's order, which is by title; completed is by Created At newest first, because what a reader recognises about a finished campaign is that it was finished recently. COMPLETED_SHOWN of them survive, behind a grey line naming how many older ones are being kept back — rows that are simply gone read as a board that never held them. An unstamped campaign sinks below every stamped one, the rule by_status_order holds for a column
  • The tag sections are declared above undeclared, and truncate neither. The same two-section shape with the opposite reason for the second: a completed campaign is finished with, so its tail is kept back before it pushes the pickable campaigns off the box, while an undeclared tag — a word somebody typed onto a ticket that the board never agreed on — is the row a reader most wants to see. A declared tag no ticket carries stays a row too: tags.md is what the board intends, and the vocabulary the listing reports is the one the picker offers. campaign and campaigns would have sat one under the other here, in different sections, the day the second was invented
  • picker_list is the one place that decides what a picker row is, and Picker::row counts drawn rows. The sections reorder the campaigns and add rows of their own, so Tab::campaigns and the drawn list agree about no number past the first heading, and a row number that meant one thing to the draw and another to a keypress is how a highlight comes to name a campaign nobody chose. The list is derived on every draw and every keypress and never held, which is what keeps a campaign filed elsewhere reaching an open picker on the next tick
  • A heading is drawn only over rows that exist, the bargain an untagged card's label row already makes, and it says which kind its rows are for as long as they are there — which is what a query filtering down to completed campaigns alone has to go on saying
  • open and completed, not open and done. The split is taken from Standing::state, so the section a campaign lands in and the state the frame draws cannot come to disagree about what finished means, but the word is the section's own: a campaign sits in no status directory, so it is not in done the way a ticket under that heading is. A campaign with no members is neither, per that method, and lists as open — completed means every member is done, and it holds none to be done
  • Headings and the truncation line take no number: the highlight moves over campaigns only. stepped_picker_row walks past the chrome rather than stopping on it, since a highlight resting on a heading gives enter nothing to do, and a step that runs out of campaigns is no move at all, the way a card at the end of a column clamps rather than cycling
  • / in the picker is the key it already is on the board, and picker_key can take it because printable keys used to fall through _ => {}. Typing filters case insensitively against the short id, the codename and the title — the three things the row draws and the three a campaign is chosen by. Not the summary: a query that matched prose would answer disk with every campaign whose description mentions one. A tag answers by itself or by its annotation, which is a reader who cannot remember the word finding it by what it was for — case insensitive here though --tag is not, because matching a tag is the filter and searching for one is a reader typing. An empty query matches everything, the opposite of first_match's answer and right for the opposite reason: a jump with nothing typed has nowhere to go, while a filter with nothing typed is not filtering, and pressing / must not empty the list
  • A query turns the truncation off, which is the point of having one: the campaign a reader is searching for is exactly the one the truncation hid
  • The query is a layer, and esc takes it off before it takes the picker off, the order dismiss closes the board's own layers in. So the list is whole again after that press, not still filtered with nothing on screen saying why. Movement and enter stay live under an open query, because a filtered list nothing can move in is a list nothing can be chosen from; every printable key goes into the buffer, so q types and so does j
  • The highlight follows its row, not its row number. place_picker takes a key — whichever answer PickerRow::key hands back, the same shape Tab::filter holds for any of them: typing, clearing the query and a tick that finishes a campaign all reshape the list, and a number kept across that names whichever campaign now sits at it. One the list no longer holds drops the highlight to the first row that does, which is where an incremental filter puts it. reload reads the highlighted key before the lists are rebuilt and puts it back after
  • Both ends bring the highlight into the window. Opening aligns against the screen the dispatch hands open_picker, and the draw follows the highlight again through aligned_offset on the geometry it is actually drawing — a resize between that keypress and the frame, or a tick that put the highlight back without touching the scroll, cannot leave it below the fold until some later keypress fixes it. The stored offset is left alone, the way a column's is: what is drawn is corrected immediately and the next navigation writes the correction back
  • A miss is a row in the box, no match in brightred, where the search prompt puts its own, and enter on it leaves the picker and the query exactly as they are so the query can be corrected in place. An empty box says nothing about why it is empty
  • The picker's footer becomes its query, the trade draw_search makes: with every printable key going into a buffer, a list of keys describes nothing that works. / search is named only on the closed query, and the open one names what esc does to it rather than what it does to the picker
  • The title says both counts while a query is open, campaigns (2 of 6). The bare total is what the box is, but over a list a query has cut down it is a lie about what is on screen
  • Every campaign's standing is settled at reload, in one pass over the cards. standings_of counts the cards naming each uuid off the columns the reload is already holding, which is what Standing::of builds for campaign ls without the walk of the status directories that one pays per campaign. A keypress must not pay that, and the picker needs every campaign's standing rather than just the selected one's, since the split is what it decides. Counted before the campaign filter is applied: how far a campaign has got is not a question about what the tab is showing
  • Tab::standing is gone with it. The frame's standing is the row's, because two counts of one number are two numbers free to drift — the rule wrapped_height holds for the scroll. the_standings_are_read_when_the_cards_are_and_not_per_draw takes the status directories away after the board is built, paired with a_member_finished_after_the_board_was_built_completes_its_campaign for the reason the comment count's two tests are paired: a standing that never asked the filesystem again would pass the first by never changing
  • q takes off one layer at a time, in the order they were put on: the overlay, then the campaign filter, then the board. Board::dismiss holds all three, and it takes the screen now because clearing the filter reloads and has to follow the selection. Selecting a campaign closes an open ticket, the answer hiding the done column already gives: the ticket may not be on the filtered board at all, and swapping it for a different one without saying so is how a person acts on the wrong ticket
  • digest watches the campaigns directory as well as the statuses and the history. A campaign filed elsewhere has to reach the picker and a codename edited by hand has to reach every card that names it, and a directory's own mtime would miss the edit
  • The tags go under the title, dimmed, each prefixed with #. The field was invisible on the board: nothing said a ticket was tagged bug without opening it. The marker is what stops the row reading as a third line of the title, since a tag is an ordinary word and the title sits directly above it. The row is dropped whole when the column will not hold it, the rule a corner follows, and an untagged ticket spends no row at all, the way a short title spends no second one
  • tags is a field on TicketItem, filled in collect_ticket_items through parse_tags, for the reason the criteria count is. parse_tags splits the comma-separated field into whole trimmed values, so a caller asking for bug is not answered by bugfix, and reads absent, _None_ and empty as the same answer
  • A held-up card carries BLOCKED_MARK, ×, after its id, in brightred. The constant lives in util.rs and the relations block draws the same one, since both say the same word. A ticket waiting on an open blocker looked exactly like one that is ready, and the board is where the next thing to pick up is chosen. Not a fourth circle from Geometric Shapes: those belong to the priority meter two cells away and would read as part of that ramp. The multiplication sign is Latin-1, like the middle dot the unset priority draws, so it renders wherever the meter does
  • The mark goes after the id, not before it. Ahead of the id it would push every id in the column out of line whenever one card was blocked, which costs more than one card's state is worth. It is measured before the project label and the due date, so both give way to it: those are context for a ticket somebody can start, and this is the one thing on a card that says not to. Dropped whole when the row cannot hold the identity and the mark together, the rule a corner follows
  • blocked is on Card, not on TicketItem. The answer lives on two tickets at once, so no card can reach it alone, and it is settled at reload the way project is. What collect_ticket_items fills is the ticket's own uuid and its blockers, both read off the file it is already holding; mark_blocked then walks the columns once for a uuid-to-status map and once to answer every card. No file is read twice and nothing is asked per draw
  • A blocker the board does not hold marks nothing, the answer mv already gives a dangling uuid. A Relations section that cannot be parsed reads as no blockers, the exception detail_of makes for the same reason: show and mv are where a hand-edited file is reported, and a board that will not draw because one ticket is malformed is the worse failure
  • The merge carries the flag rather than recomputing it. relate resolves its target inside one .worklane, so a blocker in another project is not a relation anything can record; resolving over the merged columns would let one project's uuid match another project's ticket. That is b8ce18c's fourth plan step and the answer is no
  • project_label takes the width the row has already spent, measured off the spans, rather than adding up the widths those spans are supposed to have. The hand-written version left out the space after the priority mark, so a cut label was handed one cell more than the column had; the_project_label_leaves_the_row_inside_the_column pins it
  • due_date cuts a due value back to its date only when it has one. The field is not validated (daa0e79), so it can hold a time or free text, and taking the first word regardless would turn "next friday" into "next"
  • The terminal columns are hidden until d asks for them, one step at a time. Not a new opinion: ls already counts both in its summary and leaves them out of the listing. Done only grows, so a quarter of the width was going to the column least often read, and discarded arriving made it two. So d rotates three states — hide both, show done, show both, and back around — through the Visibility enum on Board, discarded last in the rotation because it is the least likely thing to be looking for. The footer names what the next press does and carries the count of the column still hidden, which is the board's version of that summary line. Hiding is a prefix of the columns: done and discarded are the last two in what the board draws, so revealing either appends it and the columns before keep their indices
  • Hiding is a change to what is drawn, never to what is read. reload still scans the done and discarded directories and digest still watches them, so the footer counts are right and revealing either column needs no rescan. Do not "optimise" that into a conditional scan
  • visible() returns a prefix of columns, not a filter, which is what keeps column and offsets valid as indices into either. It is derived from where DONE and DISCARDED actually sit rather than assuming positions, and the_terminal_columns_are_last_in_the_order_drawn pins the assumption. A status inserted after discarded would otherwise hide two columns in silence
  • Hiding the column under the selection moves the selection to the last drawn column and closes an open detail view. The alternative, refreshing the modal onto whichever ticket the selection landed on, swaps what someone is reading without saying so, which is how a person acts on the wrong ticket. Showing another column is a no-op for the selection, since a column is appended rather than inserted
  • The choice is not remembered between runs. worklane has no config file and one flag is not a reason to start one; if it should persist, that is its own ticket
  • Assert a column heading against the top border row, not the whole screen. The footer names done too, so screen.contains("done (0)") passes on the footer whether the column is drawn or not. Three tests went vacuous that way the moment done was hidden; headings() and footer() exist so the next one does not. headings() locates the row through board_area() rather than taking row zero, since the tab row sits above it when more than one board is monitored

Monitoring Several Boards

  • worklane tui <path>... takes any number of paths, each resolved through find_worklane_dir the way the working directory is: the first .worklane at or above it. No path is the working directory, so a bare worklane and worklane tui are unchanged
  • The failure names the path that had no board, since with several arguments "No .worklane directory found" does not say which one was wrong. Only when a path was given: a bare worklane has no path to name and keeps the message every other command gives, which is what its integration test asserts
  • Two paths inside one project resolve to the same .worklane and are monitored once. projects() dedupes on the resolved directory, not on the argument
  • Tab owns the selection, column, card and offsets, not Board. Sharing them across projects would point the selection at whatever unrelated ticket sat at the same place in the tab you switched to. Board::current() is the tab in view, and visibility stays on the board because it is a preference about the flow rather than about a project
  • The tabs are fixed for the run: a project cannot be added or dropped without restarting, so Board::new builds the tab list once and reload only refills each tab's columns. reload clamps every tab, and select_tab clamps again on arrival, because done may have been hidden while another tab was in view
  • The merge tab goes first and is where the view opens: it is the reason to monitor several boards at once. It is materialised in reload, from the cards already read, rather than computed per draw — the same reason the criteria count is filled in collect_ticket_items
  • The merge is sorted, through by_priority_then_title in util.rs, not concatenated. An overview whose order depended on the order of the arguments would bury one project's p1 under another's p5. It keeps priority then title where every other column takes by_status_order: the merge spans statuses, so no single date governs it
  • Card wraps a TicketItem with the project it came from, Some only on the merge tab. Decided at reload rather than passed down to card_lines as a "which tab is this" flag. TicketItem is therefore Clone: the merge holds a second copy rather than re-reading every tree
  • The project follows the id, on the card and on the overlay border. Across boards the id is not an address: two projects can hold the same title, and seven characters do not say where they live. project_label takes what the row has left after the mark and the id and ends in an ellipsis, and it is measured before the due date, so on the merge the project wins the narrow column and the date is what corner_line drops
  • tab and shift+tab cycle rather than clamp, unlike the cards and columns: a row of tabs is a ring, and there is no end of a list to run off. Both were free of every other binding — the columns took hjkl and the arrows
  • The tab row is drawn only when there is more than one board, so a single board is the view it has always been. screen_rows() gives it Length(0) otherwise, which keeps the row indices the same for both cases and is shared with card_width and column_text_height for the reason column_areas is: geometry reproduced by hand drifts from the draw
  • digest_of hashes each board's digest into one value, so a change in any of them redraws. Do not watch only the first