53 KiB
53 KiB
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.mdteaches 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 worklanewith no subcommand andworklane tuiboth open it, the way a barefrigdoes.Cli::commandis therefore anOption- 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
notifyis 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 sourcelsuses, so there is no second parser.TicketItem::pathexists for the detail view - The detail view scrolls on
pgupandpgdn, 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_pageis 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. InBoardrather than in themain.rsarm for the reasondismissis: 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 whyratatuicarries theunstable-rendered-line-infofeature. 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_bottomwith a right-alignedLine, 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_heightis the one measurement.last_offsetis it less the viewport andpage_indicatortakes the same two numbers, so the clamp and the indicator cannot disagree. A secondline_countcall, 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 + 1readspg 2/3at 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 pagespgdncan land on. Counting by screenfuls puts a 30 row ticket in a 10 row viewport atpg 3/3two 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 follows, and absent entirely when nothing scrolls, the way an untagged card spends no row on tags
page_indicatortakes four numbers and returns anOption<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::offsetsholds one offset per column, parallel tocolumnsand resized in step byreload, so a column you leave stays where it was. The keypress aligns the focused column viafollow_selection(screen), taking the screen size for the same reasonscroll_detaildoes: 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 thestartsvec 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
↑↓ scrollwhen 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_hintis 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 theq boardon 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,campaignandtagwith the letter coloured and no letter in front, whiley 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 inkey_hintis case sensitive for exactly that reason: a row naming bothrandRwould 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_onandfooter_stylein the test module:keys_on(.., "quit")isSome(1)whereqquits andSome(0)on a row whose onlyquitis the tail ofctrl-c quit. Acontains("q quit")cannot tell those apart, and three of the guards that keep 1b78a24 out were written that way qandescare one key: close what is open, quit when there is nothing left to close.qused to setshould_quitoutright, so a reader who pressed it to put a ticket away lost the board instead, which is not whatqdoes anywhere else that lays a document over a list. One match arm inmain.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 inmain.rsis 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_quittingscansmain.rsfor 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 mergedquitthere would be 1b78a24 in the other direction: a footer describing a key by what it used to do.ctrl-c quitis 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::detailis aDetailcarrying the title, the id and the text, because the name has to travel beside the body rather than inside it:content_trimdrops the#heading on purpose, sincecmd_showprints it, and anything in the paragraph scrolls away detail_titlecuts 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_trimandformat_history_withtake 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_linesandcard_heightboth take it.column_areasis shared between the draw andfollow_selectionfor the same reason:Ratiohands 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 anOption. The spacing between the items lives incorner_linewith the gap arithmetic rather than in a caller, for the reasoncolumn_areasis shared: geometry reproduced by hand drifts from the draw.due_spanreturns aSpanand not anOption<Span>now, since theOptiononly ever existed to satisfy the old signature and the function cannot fail- The criteria count is a field on
TicketItem, filled incollect_ticket_itemswhere the file is already being read, and counted throughcriteria()so a checkbox in a description is not counted here or numbered byshow. Do not count per card: that re-reads every ticket body on every draw instead of on the tick that changed something.Nonerather 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_commentsis aread_dirrather than a parse:.mdonly, the filterread_historyapplies, 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_itemsderives the board fromstatus_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_dirspells the path once for the writer, the reader and the counter, the waycampaigns_dirdoes. Zero draws nothing, not a0and not a blank: an uncommented card is the row it has always been, whicha_card_with_no_comments_spends_nothing_on_the_cornerpins 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 wherespans_widthcounts 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_drawtakes the history directory away after the board is built, and is paired witha_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_linedraws 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 gives up tags until the two fit and keeps the campaign, the ordercorner_lineandproject_labelalready 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::campaignis a resolvedCell, not a uuid, settled at reload the wayprojectandblockedare.TicketItem::campaignalready carries the uuid off the pass that builds the card; the name is in another directory, socolumns_ofreadsCampaignIndexonce per project and hands it to every card. Never per draw, the rulecriteriaandtagsalready hold. The merge carries the resolved cell rather than looking it up again, for the reason it carriesblocked: 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_blockedgives a dangling blocker.campaign_cellsrenders that case as_missing_because a metadata table is a place to report a dangling reference; a card is not copens 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 whatcampaign showalready answers the question in. Every column is kept, empty ones included. The filter is applied inreload, where the columns are built, so nothing downstream has to ask whether a campaign is selected — the board simply holds fewer cards, andfirst_match,column_countand the copy key all keep working unchanged- A campaign filter is a uuid on the tab, not on the
Board.Tab::filteris aFilter, 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 byreloadrather than left filtering the board to nothing - The frame above the columns has two heights, and
Chromeis what every measurement takes.Chrome::frameis anOption<FrameSize>, not a bool:Nonefor a tab showing the whole board, andCollapsedorExpandedfor 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_rowsgrew a row, so the two bools that decide the geometry became oneChrome, copied fromBoard::chrome: adjacent same-typed parameters are what the Rust Style rule warns about, and the draw andfollow_selectionhave 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::framesays 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_prosereplacedsection_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, andCampaignRow::summarytakes 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_ROWSis 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_rowstakes the height because of this, andscreen_rowsis where it is called, since that is the one place that already has an area to take a share of — which is what keepsChromeitself pure and copyable fromBoard::chromewith no screen to hand - The share is bounded at both ends, and
COLUMN_MIN_ROWSis 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 faultChromeexists to prevent. So the share is capped at what leaves the columns those rows, and floored atFRAME_ROWS, since expanding must never shrink the frame. On a board too short to divide,entergives the collapsed height back rather than a height nothing measured.the_expanded_share_is_bounded_at_both_endssweeps 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 · Nameon the top one, the standing on the bottom right, andq boardthen 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:#tagintag_coloron 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.FrameContentis what they are told apart into, andframe_contentis 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 secondmatchon 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 drawsNO_ANNOTATIONin 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
yon its frame copies the word. A tag is its name, matched whole byls --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 saysy copy tagthere 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 beforeq boardwhen the two cannot both fit, since with either filter on the footer's last slot namesctrl-c quitand the border is the only place that saysqgives the board back Focusis the third place the selection can be, andTabis what holds it. The board had a column and a card andselect_cardclamped 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::Framewhile no filter is on is the one state that must never exist —select_filterandreloadare what keep it from arising, offFilter::is_wholerather than off which filter it is, since either draws a frame to hold itTab::selectedhands 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.yis the exception that earns its place: it copies the campaign's short id, soy copy idmeans 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 aboutenterroutes on the focus throughBoard::toggle_focused: the frame's height on the frame, the overlay on a card. It used to be inert on the frame for free, becauseTab::selectedhands back nothing andtoggle_detailtherefore had nothing to open. That is no longer an answer, and the routing is inBoardrather than in themain.rsarm for the reasondismissandscroll_pageareqdoes 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, soqgoes on taking the campaign filter off from either height andenteris the only key that undoes whatenterdid. 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::expandedsits beside the filter and resets whereselect_campaignandreloadreset 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 nextpgupcounts 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_framebuilds 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::standingcounts what is already in hand rather than paying whatcampaign lspays 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 boardsits 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 throughkey_hintand 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 candtare 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,↵ expandor↵ collapse, the two scroll keys andy copy id—y copy tagon 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.↑ frameis not named on the board, on the same tradecis 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 shapesearchanddetailuse, andBoard::picker_keyruns besidesearch_keyahead of the action arms for the same reason: an open list owns the keyboard, sodmust not toggle done andqmust not quit while a campaign is being chosen.ctrl-cis the one key it declines and every other control combination is swallowed, orctrl-dwould reach the arm bound tod- 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, socon a filtered board says where you are as well as offering somewhere to go, and a board with no campaigns gets aNoticerather than an empty box that has to be dismissed to learn it was empty topens 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 wayls --tagmatches — 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 courtesycpays a campaign-filtered board, and a board carrying no tag gets the sameNoticea 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::keyis what keeps it one. A second picker would have been a second keyboard, query and highlight to keep in step with the first; insteadPickerKinddecides only which list is built, and everything between the keypress and the filter runs once against the key — which since the pile arrived is aPickerKeyenum rather than a bare string, because one of the answers filters on an absence and carries no string to hand back.take_pickedreads the kind off the answer rather than off which list was open. Picking any of them clears the others without either setter remembering to, becauseselect_filterreplaces oneFilter: 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_campaigncompares 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 thingFocusexists to make unrepresentable. So the title is greyno 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 yhas nothing to copy from the pile's frame — no id to shorten and no word a command line takes,ls --campaignbeing 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 Atnewest first, because what a reader recognises about a finished campaign is that it was finished recently.COMPLETED_SHOWNof 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 ruleby_status_orderholds 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.mdis what the board intends, and the vocabulary the listing reports is the one the picker offers.campaignandcampaignswould have sat one under the other here, in different sections, the day the second was invented - A tag with nothing open sinks to a third section,
nothing open, below both. Every carrier done or discarded, or none at all, whether it is declared or not. A reader opens the picker to find work, and a tag with nothing to pick up is the row in the way of that, the reason completed campaigns sit below open ones. Not truncated, for the reason the other two are not. Each tag row trailsdone/totalthe way a campaign row does, off aStandingcounted intag_rowsthroughis_open, so finished means the same in both lists; a tag nothing carries draws no standing, as a campaign with no members does. The tag frame keeps its plain ticket count offstanding.total picker_listis the one place that decides what a picker row is, andPicker::rowcounts drawn rows. The sections reorder the campaigns and add rows of their own, soTab::campaignsand 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
openandcompleted, notopenanddone. The split is taken fromStanding::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_rowwalks past the chrome rather than stopping on it, since a highlight resting on a heading givesenternothing 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, andpicker_keycan 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 answerdiskwith 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--tagis not, because matching a tag is the filter and searching for one is a reader typing. An empty query matches everything, the opposite offirst_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
esctakes it off before it takes the picker off, the orderdismisscloses 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 andenterstay 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, soqtypes and so doesj - The highlight follows its row, not its row number.
place_pickertakes a key — whichever answerPickerRow::keyhands back, the same shapeTab::filterholds 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.reloadreads 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 throughaligned_offseton 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 matchin brightred, where the search prompt puts its own, andenteron 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_searchmakes: with every printable key going into a buffer, a list of keys describes nothing that works./ searchis named only on the closed query, and the open one names whatescdoes 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_ofcounts the cards naming each uuid off the columns the reload is already holding, which is whatStanding::ofbuilds forcampaign lswithout 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::standingis gone with it. The frame's standing is the row's, because two counts of one number are two numbers free to drift — the rulewrapped_heightholds for the scroll.the_standings_are_read_when_the_cards_are_and_not_per_drawtakes the status directories away after the board is built, paired witha_member_finished_after_the_board_was_built_completes_its_campaignfor the reason the comment count's two tests are paired: a standing that never asked the filesystem again would pass the first by never changingqtakes off one layer at a time, in the order they were put on: the overlay, then the campaign filter, then the board.Board::dismissholds 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 ticketdigestwatches 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 taggedbugwithout 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. An untagged ticket spends no row at all, the way a short title spends no second one - A row the column will not hold draws the tags that fit and ends in
(+n), the count of the ones it left out. Whole tags only, the rule a corner follows:bugandbugfixcut to the same width say the same thing. What changed in 39be95b2 is the other half of that rule — the row used to go whole, so a narrow column, which is exactly where a reader is scanning cards for a tag, showed no tags at all. A short row is allowed as long as it says it is short, and the indicator is the entire difference between a cut list and one that reads as the ticket's whole list. So a row with no room for one tag beside the count is still dropped whole:(+3)alone tells nobody anything, and a tag drawn without the count would lie.tags_that_fitmeasures the indicator as part of the row it counts rather than reserving it up front, because(+9)and(+10)are different widths and a list of under ten should not pay for the tenth - The count is grey and parenthesised, not a colour of its own and not bracketed: it is a fact about the row rather than another tag on it, and
[n/m]two rows below is the criteria count tagsis a field onTicketItem, filled incollect_ticket_itemsthroughparse_tags, for the reason the criteria count is.parse_tagssplits the comma-separated field into whole trimmed values, so a caller asking forbugis not answered bybugfix, 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 inutil.rsand the relations block draws the same one, since both say the same word. A ticket its blocker has not moved out of the way of looked exactly like one that is ready, and the board is where the next thing to pick up is chosen. The mark ismv's own rule asked one column ahead, so it says this cannot advance rather than that a dependency was ever recorded: a card in committed whose blocker is in reviewing is unmarked, because reviewing is where it may go, and the same card is marked once it sits in reviewing and only done is left. The two terminal columns have no next stage and nothing in them is drawn blocked. 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
blockedis onCard, not onTicketItem. The answer lives on two tickets at once, so no card can reach it alone, and it is settled at reload the wayprojectis. Whatcollect_ticket_itemsfills is the ticket's ownuuidand itsblockers, both read off the file it is already holding;mark_blockedthen 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
mvalready gives a dangling uuid. A Relations section that cannot be parsed reads as no blockers, the exceptiondetail_ofmakes for the same reason:showandmvare 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.
relateresolves 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_labeltakes 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_columnpins itdue_datecuts 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
dasks for them, one step at a time. Not a new opinion:lsalready 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. Sodrotates three states — hide both, show done, show both, and back around — through theVisibilityenum onBoard, 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.
reloadstill scans the done and discarded directories anddigeststill 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 ofcolumns, not a filter, which is what keepscolumnandoffsetsvalid as indices into either. It is derived from whereDONEandDISCARDEDactually sit rather than assuming positions, andthe_terminal_columns_are_last_in_the_order_drawnpins 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()andfooter()exist so the next one does not.headings()locates the row throughboard_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 throughfind_worklane_dirthe way the working directory is: the first.worklaneat or above it. No path is the working directory, so a bareworklaneandworklane tuiare 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
worklanehas 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
.worklaneand are monitored once.projects()dedupes on the resolved directory, not on the argument Tabowns the selection,column,cardandoffsets, notBoard. 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, andvisibilitystays 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::newbuilds the tab list once andreloadonly refills each tab's columns.reloadclamps every tab, andselect_tabclamps 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 incollect_ticket_items - The merge is sorted, through
by_priority_then_titleinutil.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 takesby_status_order: the merge spans statuses, so no single date governs it Cardwraps aTicketItemwith the project it came from,Someonly on the merge tab. Decided at reload rather than passed down tocard_linesas a "which tab is this" flag.TicketItemis thereforeClone: 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_labeltakes 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 whatcorner_linedrops tabandshift+tabcycle 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 tookhjkland 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 itLength(0)otherwise, which keeps the row indices the same for both cases and is shared withcard_widthandcolumn_text_heightfor the reasoncolumn_areasis: geometry reproduced by hand drifts from the draw digest_ofhashes each board'sdigestinto one value, so a change in any of them redraws. Do not watch only the first