diff --git a/Cargo.lock b/Cargo.lock index aa4cc7a..9daba37 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -1563,7 +1563,7 @@ dependencies = [ [[package]] name = "worklane" -version = "0.33.6" +version = "0.33.7" dependencies = [ "anyhow", "assert_cmd", diff --git a/Cargo.toml b/Cargo.toml index 2d25e22..3347d75 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "worklane" -version = "0.33.6" +version = "0.33.7" edition = "2024" [dependencies] diff --git a/docs/tui-prompts.md b/docs/tui-prompts.md index 861d9b9..c4c8df2 100644 --- a/docs/tui-prompts.md +++ b/docs/tui-prompts.md @@ -33,6 +33,10 @@ The three input modes on the board and the key that copies an id off it. - **The selection is restored by uuid across that reload, never by index.** `mv` puts the card in another column, `set --title` renames its file, and a filter can drop it out of view entirely, so the slot is not the ticket. `Board::reselect` has three answers: the card is in a drawn column and the selection goes to it; it is on the board but in a column the rotation is hiding, which is where `--status done` lands by default, so the notice says where it went and which key shows it; or the filter no longer holds it, which is said too, since a card vanishing from under the highlight reads as a bug in the board - **The merge tab is refused, for now.** It is the one tab that is not a board — its cards came from several `.worklane` directories and it is none of them — so `Board::current_project` answers `None` there and the command is refused rather than landing on whichever project came first. Routing by the card a command names is ebc5755. The project is resolved by index and not by the tab's name, which is a label two projects can share: e1d79c3 is exactly that, and a write routed by name would be that bug with a file changing at the end of it - **`Notice` holds as many lines as the command used, and `Board::notice_on_row` decides where they go.** One line with nothing else holding the row draws on the footer, where a copy's notice has always drawn. Anything else — several lines, or any answer at all while the prompt is still open on an error — draws as a box at the foot of the columns, cut to what the columns leave with the dropped count on its last row. A box rather than more rows of footer, and that is the whole reason it is an overlay: a footer that grew and shrank as notices came and went would reflow the columns on every keypress, moving every card the reader is looking at. `draw` and `draw_footer` both ask `notice_on_row`, so the two cannot come to disagree and draw the message twice or not at all +- **The command's own usage line takes the keys' slot as soon as the verb resolves.** The reader knows the grammar approximately — that `mv` takes a status, not whether it is a positional or a flag, and that `set` has a flag per section, not whether the criteria one is `--acceptance` or `--criteria` — which is what a shell answers as the line is typed and the board answered with nothing. `usage_of` walks the typed verb against the clap definition and renders *its* usage, so a flag added to a command is described here the day it is added; a table of synopses kept beside it would be a second grammar going stale silently, since nothing but a reader typing that verb would see the two disagree. The `Usage: ` label is dropped, being a block name in a help page of several where this is one line beside the line it describes +- **`esc` and `enter` are what the row gives up for it.** Two keys a reader learns once, against a synopsis that is different for every verb. A refusal still wins over both while it is up, being what was just said about the line that is still on the row, and `refusal` is the half that says what is *wrong* where this says what would have been right +- **A verb that resolves to nothing draws nothing, and complains about nothing.** The line is half typed most of the time the row is looked at, so an error about `com` is noise where a reader is still typing. A group's child is walked when the second word names one, so `campaign set` describes `set`; while that second word is half typed the group's own `campaign ` stands, which is what has been typed so far +- **Grey, and cut with an ellipsis rather than wrapped.** Grey is the chrome colour and says the same thing the suggestion's does: this is not in your line. The footer is one row, and a second one would reflow the columns every time a verb resolved — the reason a notice of several lines is a box. There is always at least the keys' width to cut into, because that width comes off the row before the line is windowed, so the usage never takes a cell from what is being typed - **What a refused line shows is clap's own message with the usage block cut off**, which is also what drops the `--help` line after it. `--help` is the exception: it parses as an error of the kind that means *print this* and what it would print is a page, so it is caught and answered in a row's worth of words, or clap's help lands on the alternate screen the way an unsunk `println!` would. `--version` goes through the ordinary path, because what it prints is one line by construction. `ColorChoice::Never` on the command, so nothing that reaches the row carries an escape - **The keys' width comes off the row before the line is windowed**, so a long command does not push them off the end; a message takes the row from the keys instead, since the reader has just been told something and `esc` and `enter` still do what they did. `prompt_window` anchors the window on the cursor's right edge, which costs the text *after* the cursor on a long line: keeping both ends needs a scroll offset in state, and the draw is where the width is known and the state is not writable - `: command` is named in every footer state, because the key works in every one of them, and the prompt's own key is drawn as `↵ run` diff --git a/src/tui.rs b/src/tui.rs index 165d15c..dc8ea32 100644 --- a/src/tui.rs +++ b/src/tui.rs @@ -980,12 +980,57 @@ fn command_name(matches: &clap::ArgMatches) -> Option { }) } +/// The usage line clap renders for the command the typed line names, or nothing while the +/// verb names none. +/// +/// **Clap's own rendering, off the definition the parse uses**, so a flag added to a +/// command is described here the day it is added. A table of synopses kept beside it would +/// be a second grammar, and it would go stale silently: nothing but a reader typing that +/// verb would ever see the two disagree. +/// +/// A verb that resolves to nothing answers `None`. The line is half typed most of the time +/// it is looked at, and a complaint about `com` is noise on a row the reader is typing on; +/// `refusal` is where a line that was actually entered is answered. +/// +/// A group's child is walked when the second word names one, so `campaign set` describes +/// `set` and not `campaign`. While that second word is still half typed the group's own +/// usage stands, which is the honest answer: `campaign ` is what has been typed +/// so far. +/// +/// The `Usage: ` label is dropped and the rest is kept verbatim. The label names the block +/// in a help page of several; this row is one line beside the line it describes, and the +/// cells are worth more than the word. +fn usage_of(args: &[String]) -> Option { + // Colour off for the same reason the parse turns it off: what this row draws is a + // ratatui span, and an escape inside one is printed rather than obeyed. + let cli = ::command().color(clap::ColorChoice::Never); + let command = cli.find_subcommand(args.first()?)?; + + // The child by exact name, which is what clap will resolve too. A half-typed one + // matches nothing and leaves the group's usage on the row. + let command = match args.get(1).and_then(|word| command.find_subcommand(word)) { + Some(child) => child, + None => command, + }; + + let usage = command.clone().render_usage().to_string(); + Some( + usage + .strip_prefix("Usage: ") + .unwrap_or(&usage) + .trim() + .to_string(), + ) +} + /// The one line the row carries for a line clap would not take. /// /// Clap's own message, because the grammar is clap's: a complaint written here would /// describe a rule this file does not own. What is dropped is the usage block and the -/// `--help` line after it, which are a paragraph — the synopsis is d7e493e's, and until -/// then the row says what is wrong rather than what would have been right. +/// `--help` line after it, which are a paragraph: this row says what is wrong, and +/// `usage_of` is what says what would have been right, on the same row for as long as the +/// verb resolves. A refusal wins the slot while it is up, being what was just said about +/// the line that is still there. /// /// `--help` is the exception. It parses as an error of the kind that means *print this*, /// and what it would print is a page: caught here, or clap's help lands on the alternate @@ -2520,6 +2565,19 @@ impl Board { .map(str::to_string) } + /// The usage line of the command the prompt's line names, for the row to draw in place + /// of the keys. + /// + /// Derived on every draw and held nowhere, the way `completion` is: what is on the row + /// is a function of what is in the line, so the two cannot come to disagree and there + /// is no state to clear when the line is edited. The walk is over the clap definition + /// alone and reads nothing off the board, since a keypress must not go to disk. + fn usage(&self) -> Option { + let prompt = self.prompt.as_ref()?; + let split = split_line(&prompt.line, prompt.cursor); + usage_of(&split.args) + } + /// `tab`: take what every candidate agrees on, and then step through them one press at /// a time. /// @@ -4766,7 +4824,13 @@ fn draw_footer(frame: &mut Frame, board: &Board, area: Rect) { // and is asked first: an input cannot be covered, and it is the newest of the three // things that can hold the row. Only one of the two prompts can be open at a time. if let Some(prompt) = &board.prompt { - draw_prompt(frame, prompt, board.suggestion().as_deref(), area); + draw_prompt( + frame, + prompt, + board.suggestion().as_deref(), + board.usage().as_deref(), + area, + ); return; } @@ -4979,7 +5043,26 @@ const PROMPT_OPENING: &str = " :"; /// of the field rather than a field of its own, so a long command loses the offer instead /// of pushing the keys off the row. The terminal cursor sits on its first cell, which is /// where the cursor already was: what is under a cursor is still what will be typed over. -fn draw_prompt(frame: &mut Frame, prompt: &Prompt, suggestion: Option<&str>, area: Rect) { +/// +/// **The usage line takes the keys' slot as soon as the verb resolves.** The reader knows +/// the grammar approximately — that `mv` takes a status, not whether it is a positional or +/// a flag — and in a shell fish answers that as the line is typed. `esc` and `enter` are +/// what the row gives up for it: they are two keys a reader learns once, and the synopsis +/// is the thing that is different for every verb. A refusal still wins over both, being +/// what was just said about the line that is still on the row. +/// +/// It is grey, the chrome colour: it is not in the line, nothing here is a value, and the +/// reader has to tell it from what they typed at a glance. Cut to what the row leaves with +/// an ellipsis, never wrapped: the footer is one line, and a second row would reflow the +/// columns every time a verb resolved. There is always at least the keys' width for it, +/// since that width was taken off the row before the line was windowed. +fn draw_prompt( + frame: &mut Frame, + prompt: &Prompt, + suggestion: Option<&str>, + usage: Option<&str>, + area: Rect, +) { let keys = key_hints(&[("↵", "run"), ("esc", "cancel")]); let spent: usize = PROMPT_OPENING.chars().count() + KEY_GAP.chars().count() @@ -4994,6 +5077,7 @@ fn draw_prompt(frame: &mut Frame, prompt: &Prompt, suggestion: Option<&str>, are let (visible, at) = prompt_window(&prompt.line, prompt.cursor, room); let mut spans = vec![Span::raw(format!("{PROMPT_OPENING}{visible}"))]; + let mut drawn = PROMPT_OPENING.chars().count() + visible.chars().count(); // Only ever drawn where the cursor is at the end of the line, which is what `visible` // then ends at, so this follows the cursor rather than landing in front of the tail of @@ -5002,16 +5086,30 @@ fn draw_prompt(frame: &mut Frame, prompt: &Prompt, suggestion: Option<&str>, are let left = room.saturating_sub(visible.chars().count()); let shown: String = rest.chars().take(left).collect(); if !shown.is_empty() { + drawn += shown.chars().count(); spans.push(Span::styled(shown, Style::default().fg(Color::Grey.into()))); } } - match &prompt.refused { - Some(message) => spans.push(Span::styled( + match (&prompt.refused, usage) { + (Some(message), _) => spans.push(Span::styled( format!("{KEY_GAP}{message}"), Style::default().fg(Color::BrightRed.into()), )), - None => { + (None, Some(usage)) => { + // What the row leaves after the line and the gap. Nothing at all on a terminal + // too narrow to hold a cell of it, the bargain the suggestion already takes. + let left = (area.width as usize).saturating_sub(drawn + KEY_GAP.chars().count()); + if left > 0 { + let shown = match usage.chars().count() <= left { + true => usage.to_string(), + false => with_ellipsis(usage, left), + }; + spans.push(Span::raw(KEY_GAP)); + spans.push(Span::styled(shown, Style::default().fg(Color::Grey.into()))); + } + } + (None, None) => { spans.push(Span::raw(KEY_GAP)); spans.extend(keys); } @@ -8199,6 +8297,132 @@ approach"; assert_eq!(at.y, SCREEN.height - 1, "the cursor left the prompt row"); } + /// The grammar, where the key list was, as soon as the verb resolves: the reader knows + /// `mv` takes a status and not whether it is a positional or a flag, which is what a + /// shell answers as the line is typed and the board answered with nothing. + #[test] + fn the_row_shows_the_usage_of_the_command_being_typed() { + let dir = searchable(); + let mut board = one_board(&dir); + board.open_prompt(); + + // Nothing typed yet, so there is no command to describe and the keys have the slot. + let row = footer(&board, SCREEN.width, SCREEN.height); + assert!(row.contains("esc cancel"), "{row}"); + + type_line(&mut board, "mv "); + let row = footer(&board, SCREEN.width, SCREEN.height); + assert!( + row.contains("mv [OPTIONS] --status "), + "the usage is not on the row: {row}" + ); + assert!( + !row.contains("esc cancel"), + "the keys and the usage both took the slot: {row}" + ); + + // And it is the grammar of the verb in the line, not of the one typed before it. + type_line(&mut board, "1111111"); + board.prompt_key(ctrl('w'), SCREEN); + for _ in 0.."mv ".len() { + board.prompt_key(typed(KeyCode::Backspace), SCREEN); + } + type_line(&mut board, "comment "); + let row = footer(&board, SCREEN.width, SCREEN.height); + assert!(row.contains("comment"), "{row}"); + assert!(!row.contains("--status"), "the previous verb's usage stayed: {row}"); + + // Closing the prompt gives the board's own key list back. + board.prompt_key(typed(KeyCode::Esc), SCREEN); + let row = footer(&board, SCREEN.width, SCREEN.height); + assert!(row.contains("quit"), "the key list did not come back: {row}"); + assert!(!row.contains("--status"), "the usage outlived the prompt: {row}"); + } + + /// The resolve step on its own: what a verb names, what a group's child names, and what + /// a word that names nothing yet does. + /// + /// The values are clap's own rendering off the definition the parse uses, which is why + /// this asserts on flags rather than on a synopsis written out here: a table of those + /// kept beside the command would go stale the first time a flag was added, and silently, + /// since nothing but a reader typing that verb would ever see the two disagree. + #[test] + fn a_usage_is_clap_s_own_and_a_nested_command_describes_itself() { + let usage = |line: &str| { + let words: Vec = line.split_whitespace().map(str::to_string).collect(); + usage_of(&words) + }; + + let mv = usage("mv").expect("mv names a command"); + assert!(mv.starts_with("mv "), "the label survived: {mv}"); + assert!(mv.contains("--status "), "{mv}"); + assert!(mv.contains(""), "{mv}"); + + // The question the ticket is about: which flag the criteria section is under. + assert!(usage("set").is_some_and(|set| set.contains("--acceptance"))); + + // A group's child describes itself rather than its parent, once both words are + // there. `campaign set` takes a campaign; `campaign` alone takes a command. + let group = usage("campaign").expect("campaign names a command"); + assert!(group.contains(""), "{group}"); + let child = usage("campaign set").expect("campaign set names a command"); + assert!(child.contains(""), "{child}"); + assert!(!child.contains(""), "the parent's usage was drawn: {child}"); + + // A second word that names no child leaves the group's own usage up, which is what + // has been typed so far. + assert_eq!(usage("campaign se"), Some(group.clone())); + + // And a verb that names nothing has nothing to say about it. + assert_eq!(usage("com"), None); + assert_eq!(usage(""), None); + assert_eq!(usage_of(&[]), None); + } + + /// A line half typed is the state the row is looked at in, so a verb that resolves to + /// nothing draws nothing and complains about nothing. + #[test] + fn a_half_typed_verb_shows_no_usage_and_no_complaint() { + let dir = searchable(); + let mut board = one_board(&dir); + board.open_prompt(); + type_line(&mut board, "com"); + + let row = footer(&board, SCREEN.width, SCREEN.height); + assert!(row.contains("esc cancel"), "the keys lost the slot: {row}"); + assert!(refused(&board).is_none(), "a half typed verb was refused"); + assert!(!row.contains("Usage"), "a label reached the row: {row}"); + } + + /// The footer is one row, whatever the usage is: a second row would reflow the columns + /// every time a verb resolved, which is the same reason a notice of several lines is a + /// box rather than more footer. + #[test] + fn a_usage_wider_than_the_row_is_cut_and_leaves_the_columns_alone() { + let dir = searchable(); + let mut board = one_board(&dir); + + // `set` has the longest synopsis in the tool, a flag per section and one per scalar. + let narrow = 60; + let before = render(&board, narrow, SCREEN.height); + + board.open_prompt(); + type_line(&mut board, "set "); + let after = render(&board, narrow, SCREEN.height); + + assert_eq!(before.len(), after.len(), "the row count changed"); + assert_eq!( + before[..before.len() - 1], + after[..after.len() - 1], + "the columns moved to make room for the usage" + ); + + let row = after.last().expect("no rows rendered"); + assert!(row.chars().count() <= narrow as usize, "the row ran over: {row}"); + assert!(row.contains('…'), "a usage too wide for the row was not cut: {row}"); + assert!(row.contains(" :set "), "the line lost its cells to the usage: {row}"); + } + /// The line is edited where the cursor is, not at its end, which is the difference /// between a command line and the search prompt's append-only query. #[test] @@ -8969,8 +9193,21 @@ approach"; let row = footer(&board, SCREEN.width, SCREEN.height); assert!(!row.contains(":mv"), "the head of the line held the row: {row}"); + // The slot at the end of the row keeps its width whatever is typed into the line, + // which is what taking it off the row before windowing is for. `mv` resolves, so + // what holds it is the usage; a verb that resolves to nothing leaves the keys. + assert!(row.contains("mv [OPTIONS]"), "a long line pushed the usage off: {row}"); + + board.dismiss(SCREEN); + board.open_prompt(); + type_line(&mut board, &format!("nosuchverb {}", "a".repeat(200))); + let row = footer(&board, SCREEN.width, SCREEN.height); assert!(row.contains("esc cancel"), "a long line pushed the keys off: {row}"); + board.dismiss(SCREEN); + board.open_prompt(); + type_line(&mut board, &format!("mv {}", "a".repeat(200))); + let mut terminal = Terminal::new(TestBackend::new(SCREEN.width, SCREEN.height)).unwrap(); terminal.draw(|frame| draw(frame, &board)).unwrap(); assert!(