blockworx/tools/

palette.rs

//! The command palette: a Ctrl+K popup that fuzzy-searches the frame's
//! [`CommandSet`], plus a `find <block>` row per document block, an
//! `expand <block>` row per block on the current level, a `rev N` row per
//! commit in the log, and a `go <path>` row for a typed content
//! path — so every registered operation (and canvas navigation) is reachable
//! by typing its name or label. Matching and ranking come from `nucleo-matcher` (the
//! Helix editor's scorer); rows dispatch the same resolved [`Action`]s the
//! overlay buttons do.
//!
//! Results are typed and grouped by their [`Source`] (spec §6): what a row
//! *is* decides which run it joins, so a block named like a command cannot
//! be mistaken for one. Numeric queries ("everything wider than 8 cells")
//! are the spec's own open question and are not answered here.

use nucleo_matcher::{
    Config, Matcher, Utf32Str,
    pattern::{CaseMatching, Normalization, Pattern},
};

use crate::{
    path::BlockPath,
    tools::{
        commands::{CommandId, CommandSet},
        nav_tree,
        tool::Action,
    },
};
use blockworx_doc::{document::IndexedDocument, id::BlockId};
use blockworx_geom::Rect;

type Doc<'a> = IndexedDocument<'a>;

/// The verb that turns the rest of a query into a content path.
const GO_VERB: &str = "go ";

/// The verb that turns the rest of a query into a camera rect.
const CAMERA_VERB: &str = "camera ";

/// Bounds on a typed camera's size, in grid cells. A zero or negative extent
/// has no framing at all, and a huge one zooms so far out the diagram vanishes
/// — both are typos, not intentions.
const CAMERA_MIN_CELLS: i32 = 1;
const CAMERA_MAX_CELLS: i32 = 5_000;

/// Parse `camera <x> <y> <w> <h>` (grid cells) into the world rect it frames.
/// `None` unless all four numbers are present and the size is within
/// [`CAMERA_MIN_CELLS`]..=[`CAMERA_MAX_CELLS`], so a half-typed or nonsense
/// camera simply offers no row to pick.
fn parse_camera(rest: &str) -> Option<Rect> {
    let values: Vec<i32> = rest
        .split_whitespace()
        .map(str::parse::<i32>)
        .collect::<Result<_, _>>()
        .ok()?;
    let [x, y, w, h] = values[..] else {
        return None;
    };
    let sane = |v: i32| (CAMERA_MIN_CELLS..=CAMERA_MAX_CELLS).contains(&v);
    if !sane(w) || !sane(h) {
        return None;
    }
    Some(Rect::from_min_size(
        crate::grid::grid_pos(x, y),
        crate::grid::grid_pos(w, h).to_vec2(),
    ))
}

const PALETTE_WIDTH: f32 = 420.0;
const LIST_MAX_HEIGHT: f32 = 280.0;
/// Ranked rows shown for a non-empty query; the tail is cut, an empty query
/// lists every available command instead.
const MAX_MATCHES: usize = 12;

/// What the palette searches besides the command set: the document (every
/// block, for `find`), the current path (this level's blocks, for `expand`)
/// and the log (every commit, for `rev`).
#[derive(Clone, Copy)]
pub struct PaletteScope<'a> {
    pub document: &'a Doc<'a>,
    pub path: &'a BlockPath,
    pub revs: &'a [blockworx_store::history::Row<'a>],
}

/// The open palette's state: the query text and the highlighted row.
pub struct Palette {
    query: String,
    selected: usize,
}

/// What the palette's frame asks the app to do. The action is boxed so the
/// stay-open/close cases don't carry `Action`'s footprint.
pub enum PaletteOutcome {
    /// Stay open.
    Open,
    /// Close without dispatching (Escape, click-away).
    Close,
    /// Dispatch the picked row's action and close.
    Dispatch(Box<Action>),
}

/// What a row dispatches when picked: a registry command, navigation to a
/// block found by name, descending into a block on the current level,
/// jumping to a typed content path, or putting a past rev on the canvas.
#[derive(Clone, PartialEq, Debug)]
enum RowId {
    Command(CommandId),
    Block(BlockId),
    Expand(BlockId),
    GoToPath(BlockPath),
    Camera(Rect),
    Rev(blockworx_doc::rev::Rev),
}

/// Where a result came from (spec §6). Read off the row's own id rather than
/// carried beside it, so a row cannot be filed under a source it does not
/// belong to.
///
/// The declaration order is the order the groups are listed in: a query that
/// parses as a typed verb named its target exactly and everything else is a
/// guess, so those lead; then what the session can *do*, then what the
/// document holds, then what it has been.
#[derive(Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Debug)]
enum Source {
    Typed,
    Command,
    Block,
    Rev,
}

impl Source {
    fn heading(self) -> &'static str {
        match self {
            Source::Typed => "Go to",
            Source::Command => "Commands",
            Source::Block => "Blocks",
            Source::Rev => "History",
        }
    }
}

impl RowId {
    fn source(&self) -> Source {
        match self {
            RowId::Command(_) => Source::Command,
            RowId::Block(_) | RowId::Expand(_) => Source::Block,
            RowId::GoToPath(_) | RowId::Camera(_) => Source::Typed,
            RowId::Rev(_) => Source::Rev,
        }
    }
}

struct Row {
    id: RowId,
    /// The command label, or `find`/`expand` plus a block label.
    text: String,
    /// The command's stable name, shown dimmed as the typeable spelling.
    name: Option<&'static str>,
    score: u32,
}

impl Palette {
    pub fn new() -> Self {
        Self {
            query: String::new(),
            selected: 0,
        }
    }

    /// Show the palette for one frame. Keyboard: Up/Down move the highlight,
    /// Enter picks it, Escape closes — consumed here so nothing else sees
    /// them (the canvas already ignores keys while the palette's text field
    /// holds focus).
    pub fn show(
        &mut self,
        ctx: &egui::Context,
        commands: &mut CommandSet,
        scope: PaletteScope<'_>,
        viewport: egui::Rect,
    ) -> PaletteOutcome {
        use egui::{Key, Modifiers};
        let (up, down, enter, escape) = ctx.input_mut(|i| {
            (
                i.consume_key(Modifiers::NONE, Key::ArrowUp),
                i.consume_key(Modifiers::NONE, Key::ArrowDown),
                i.consume_key(Modifiers::NONE, Key::Enter),
                i.consume_key(Modifiers::NONE, Key::Escape),
            )
        });
        if escape {
            return PaletteOutcome::Close;
        }
        let blocks = nav_tree::all_blocks(scope.document);
        let level = nav_tree::level_blocks(scope.document, scope.path);
        let rows = rows(&self.query, commands, &blocks, &level, scope);
        if down {
            self.selected += 1;
        }
        if up {
            self.selected = self.selected.saturating_sub(1);
        }
        self.selected = self.selected.min(rows.len().saturating_sub(1));
        // Scroll only on an actual move: an unconditional per-frame
        // `scroll_to_me` restarts a scroll animation every frame, which pins
        // the repaint delay at zero and keeps the list shimmering.
        let scroll_to_selected = up || down;
        let mut picked: Option<RowId> = None;
        if enter {
            picked = rows.get(self.selected).map(|r| r.id.clone());
        }
        let pos = egui::pos2(
            viewport.center().x - PALETTE_WIDTH / 2.0,
            viewport.top() + 0.1 * viewport.height(),
        );
        let area = egui::Area::new(egui::Id::new("command_palette"))
            .order(egui::Order::Foreground)
            .fixed_pos(pos)
            .show(ctx, |ui| {
                egui::Frame::popup(ui.style()).show(ui, |ui| {
                    ui.set_width(PALETTE_WIDTH);
                    let edit = ui.add(
                        egui::TextEdit::singleline(&mut self.query)
                            .hint_text("Type a command or block name…")
                            .desired_width(f32::INFINITY),
                    );
                    edit.request_focus();
                    if edit.changed() {
                        self.selected = 0;
                    }
                    ui.separator();
                    egui::ScrollArea::vertical()
                        .max_height(LIST_MAX_HEIGHT)
                        .show(ui, |ui| {
                            // Each row: the label as the clickable body, the
                            // command's typeable name dimmed on the right,
                            // under the heading of the source it came from.
                            let mut heading_shown: Option<Source> = None;
                            for (i, row) in rows.iter().enumerate() {
                                let source = row.id.source();
                                if heading_shown != Some(source) {
                                    heading_shown = Some(source);
                                    crate::tools::overlay::group_heading(ui, source.heading());
                                }
                                let selected = i == self.selected;
                                ui.horizontal(|ui| {
                                    let response = ui.selectable_label(selected, &row.text);
                                    if selected && scroll_to_selected {
                                        response.scroll_to_me(None);
                                    }
                                    if response.clicked() {
                                        picked = Some(row.id.clone());
                                    }
                                    if let Some(name) = row.name {
                                        let annotation = match row.id {
                                            RowId::Command(cid) => {
                                                match crate::tools::commands::binding(cid) {
                                                    Some(chord) => format!(
                                                        "{name} · {}",
                                                        ui.ctx().format_shortcut(chord)
                                                    ),
                                                    None => name.to_string(),
                                                }
                                            }
                                            _ => name.to_string(),
                                        };
                                        ui.with_layout(
                                            egui::Layout::right_to_left(egui::Align::Center),
                                            |ui| ui.weak(annotation),
                                        );
                                    }
                                });
                            }
                            if rows.is_empty() {
                                ui.weak("No matching command or block");
                            }
                        });
                });
            });
        if let Some(id) = picked {
            let action = match id {
                RowId::Command(cid) => commands.take(cid),
                RowId::Block(rid) => Some(Action::NavSelect {
                    block: rid,
                    extend: false,
                }),
                RowId::Expand(rid) => Some(Action::ExpandBlock(rid)),
                RowId::GoToPath(path) => Some(Action::GoToPath(path)),
                RowId::Camera(rect) => Some(Action::Camera(rect)),
                RowId::Rev(rev) => Some(Action::ViewRev(rev)),
            };
            return match action {
                Some(action) => PaletteOutcome::Dispatch(Box::new(action)),
                None => PaletteOutcome::Close,
            };
        }
        if area.response.clicked_elsewhere() {
            return PaletteOutcome::Close;
        }
        PaletteOutcome::Open
    }
}

/// The rows a query yields: every available command on an empty query
/// (registry order), otherwise commands, `expand <block>` entries for the
/// current level, `find <block>` entries for the whole document and `rev`
/// entries for the log, scored against label + name and ranked best-first
/// (ties keep registry order).
///
/// Ranking picks *which* rows survive; [`Source`] decides the order they are
/// listed in (§6). Grouping after the cut rather than before is what keeps
/// the two from fighting: the results are the same twelve either way, and no
/// group can crowd another out of the list.
fn rows(
    query: &str,
    commands: &CommandSet,
    blocks: &[(BlockId, String)],
    level: &[(BlockId, String)],
    scope: PaletteScope<'_>,
) -> Vec<Row> {
    let query = query.trim();
    if query.is_empty() {
        return commands
            .iter()
            .map(|c| Row {
                id: RowId::Command(c.id),
                text: c.label.to_string(),
                name: Some(c.id.name()),
                score: 0,
            })
            .collect();
    }
    let mut matcher = Matcher::new(Config::DEFAULT);
    let pattern = Pattern::parse(query, CaseMatching::Ignore, Normalization::Smart);
    let mut buf = Vec::new();
    let mut score = |text: &str| pattern.score(Utf32Str::new(text, &mut buf), &mut matcher);
    let mut rows: Vec<Row> = Vec::new();
    // `go <path>` is typed, not picked from a list: whatever follows the verb
    // is parsed as a content path, so a path copied off the canvas navigates
    // straight back to that level. Only a path that resolves offers a row.
    if let Some(target) = query
        .strip_prefix(GO_VERB)
        .and_then(|rest| crate::tools::content_path::parse(scope.document, rest))
    {
        rows.push(Row {
            id: RowId::GoToPath(target),
            text: query.to_owned(),
            name: None,
            score: u32::MAX,
        });
    }
    if let Some(rect) = query.strip_prefix(CAMERA_VERB).and_then(parse_camera) {
        rows.push(Row {
            id: RowId::Camera(rect),
            text: query.to_owned(),
            name: None,
            score: u32::MAX,
        });
    }
    for c in commands.iter() {
        let name = c.id.name();
        if let Some(score) = score(&format!("{} {name}", c.label)) {
            rows.push(Row {
                id: RowId::Command(c.id),
                text: c.label.to_string(),
                name: Some(name),
                score,
            });
        }
    }
    for (rid, label) in level {
        let text = format!("expand {label}");
        if let Some(score) = score(&text) {
            rows.push(Row {
                id: RowId::Expand(*rid),
                text,
                name: None,
                score,
            });
        }
    }
    for (rid, label) in blocks {
        let text = format!("find {label}");
        if let Some(score) = score(&text) {
            rows.push(Row {
                id: RowId::Block(*rid),
                text,
                name: None,
                score,
            });
        }
    }
    for rev in scope.revs {
        let text = rev_row(rev);
        if let Some(score) = score(&text) {
            rows.push(Row {
                id: RowId::Rev(rev.rev),
                text,
                name: None,
                score,
            });
        }
    }
    rows.sort_by_key(|row| std::cmp::Reverse(row.score));
    rows.truncate(MAX_MATCHES);
    // Stable, so ranking still orders the rows within each run.
    rows.sort_by_key(|row| row.id.source());
    rows
}

/// How a commit reads in the palette: the number a reader types and the
/// label the history panel gives the same rev, so one commit is not named
/// two ways across two surfaces.
fn rev_row(row: &blockworx_store::history::Row<'_>) -> String {
    format!("rev {} \u{2014} {}", row.rev.get(), row.label)
}

#[cfg(all(test, feature = "kittest"))]
mod kittest_visual {
    use super::*;
    use crate::path::Scope;
    use crate::shell::picture::{Width, at_every_width, dress};
    use crate::tools::commands::{CommandContext, History};
    use crate::widget::test_fixtures::{self as fx, Scene};
    use egui::vec2;
    use egui_kittest::Harness;

    /// One query reaching three sources (§6): the commands the session can
    /// run, the blocks the document holds, and the revs it has been —
    /// each run under the heading that says what it is, so a row's kind is
    /// read off the list rather than guessed from its wording.
    #[test]
    fn shell_palette() {
        at_every_width("shell_palette", picture);
    }

    #[expect(
        clippy::expect_used,
        reason = "a fixture that will not fold has no picture to take"
    )]
    fn picture(width: Width) -> Harness<'static> {
        let mut scene = Scene::new(vec![
            fx::block_in(
                1,
                Scope::Root,
                Rect::from_min_max(
                    blockworx_geom::pos2(0.0, 0.0),
                    blockworx_geom::pos2(80.0, 80.0),
                ),
            ),
            fx::titled(1, "adder"),
        ]);
        let repo = blockworx_doc::repo::Repo::folding(&blockworx_store::fixture::edits(2))
            .expect("the edits fold");
        let tags = blockworx_store::tags::Tags::default();
        let mut palette = Palette::new();
        "add".clone_into(&mut palette.query);
        let size = vec2(width.points(), 460.0);
        let viewport = egui::Rect::from_min_size(egui::pos2(0.0, 0.0), size);
        Harness::builder().with_size(size).build_ui(move |ui| {
            let ctx = ui.ctx().clone();
            dress(&ctx);
            let tool: crate::tools::tool::Tool = crate::tools::SelectTool.into();
            let mut commands = {
                let drawing = scene.drawing();
                CommandSet::available(&CommandContext {
                    tool: &tool,
                    data: &drawing,
                    history: History {
                        undo: Some(crate::history::Kind::Doc),
                        redo: None,
                    },
                    current_lock: crate::edit::naming::InterfaceLock::Unlocked,
                    writability: blockworx_store::doc::Writability::Writable,
                    saving: blockworx_store::doc::Saving::Withheld,
                    viewing: blockworx_store::doc::Viewing::Head,
                })
            };
            let indexed = scene.indexed();
            let revs = blockworx_store::history::rows(
                blockworx_store::history::Journal::Session(repo.log()),
                &tags,
            );
            let here = BlockPath::empty();
            let _ = palette.show(
                &ctx,
                &mut commands,
                PaletteScope {
                    document: &indexed,
                    path: &here,
                    revs: &revs,
                },
                viewport,
            );
        })
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::canvas::convert::IntoEgui as _;
    use crate::edit::naming::InterfaceLock;
    use crate::path::Scope;
    use crate::tools::commands::{CommandContext, CommandSet, History};
    use crate::tools::resize_block::ResizeBlock;
    use crate::tools::tool::Tool;
    use crate::widget::test_fixtures::{self as fx, Scene};
    use blockworx_doc::fixtures::block_id;
    use blockworx_geom::{Rect, pos2, vec2};

    /// Blocks paired with their palette labels.
    type Labeled = Vec<(BlockId, String)>;

    /// A palette's whole input: the frame's commands plus the row sources.
    struct Fixture {
        set: CommandSet,
        scene: Scene,
        blocks: Labeled,
        level: Labeled,
        /// The log the `rev` rows are read out of, and the names hung on it.
        repo: blockworx_doc::repo::Repo,
        tags: blockworx_store::tags::Tags,
    }

    impl Fixture {
        fn rows(&mut self, query: &str) -> Vec<Row> {
            let Self {
                set,
                scene,
                blocks,
                level,
                repo,
                tags,
            } = self;
            let indexed = scene.indexed();
            let revs = blockworx_store::history::rows(
                blockworx_store::history::Journal::Session(repo.log()),
                tags,
            );
            let here = BlockPath::empty();
            rows(
                query,
                set,
                blocks,
                level,
                PaletteScope {
                    document: &indexed,
                    path: &here,
                    revs: &revs,
                },
            )
        }
    }

    /// Three commits, each labelled differently, so a query can name one.
    fn logged() -> blockworx_doc::repo::Repo {
        let commits: Vec<blockworx_doc::commit::Commit> = ["Drew a block", "Moved the adder"]
            .iter()
            .enumerate()
            .map(|(ndx, label)| {
                blockworx_store::fixture::commit(
                    label,
                    vec![blockworx_store::fixture::block_create(
                        u32::try_from(ndx).expect("two commits") + 10,
                        &format!("p{ndx}"),
                    )],
                )
            })
            .collect();
        blockworx_doc::repo::Repo::folding(&commits).expect("the fixture commits fold")
    }

    /// A document whose root holds `adder`, which in turn holds `carry`: one
    /// block on the current level and one a level deeper.
    fn block_selected_set() -> Fixture {
        let b = block_id(1);
        let mut scene = Scene::new(vec![
            fx::block_in(
                1,
                Scope::Root,
                Rect::from_min_max(pos2(0.0, 0.0), pos2(80.0, 80.0)),
            ),
            fx::titled(1, "adder"),
            fx::block_in(
                2,
                Scope::Block(b),
                Rect::from_min_max(pos2(0.0, 0.0), pos2(40.0, 40.0)),
            ),
            fx::titled(2, "carry"),
        ]);
        let tool: Tool = ResizeBlock::Selected {
            shape: crate::shape::ShapeId::Rect(b),
        }
        .into();
        let set = {
            let drawing = scene.drawing();
            CommandSet::available(&CommandContext {
                tool: &tool,
                data: &drawing,
                history: History::empty(),
                current_lock: InterfaceLock::Unlocked,
                writability: blockworx_store::doc::Writability::Writable,
                saving: blockworx_store::doc::Saving::Withheld,
                viewing: blockworx_store::doc::Viewing::Head,
            })
        };
        let path = BlockPath::empty();
        let (blocks, level) = {
            let indexed = scene.indexed();
            (
                nav_tree::all_blocks(&indexed),
                nav_tree::level_blocks(&indexed, &path),
            )
        };
        Fixture {
            set,
            scene,
            blocks,
            level,
            repo: logged(),
            tags: blockworx_store::tags::Tags::default(),
        }
    }

    fn top_row_id(query: &str) -> RowId {
        let mut fixture = block_selected_set();
        let rows = fixture.rows(query);
        assert!(
            !rows.is_empty(),
            "{query:?} should match at least one row of {} commands / {} blocks",
            fixture.set.iter().count(),
            fixture.blocks.len()
        );
        rows[0].id.clone()
    }

    /// An open, untouched palette must settle (see [`crate::canvas::settle`]).
    /// A per-frame `scroll_to_me` once pinned the repaint delay at zero,
    /// restarting a scroll animation every frame — the palette shimmered and
    /// the app repainted continuously.
    #[test]
    fn an_idle_palette_settles() {
        let mut palette = Palette::new();
        let repo = logged();
        let tags = blockworx_store::tags::Tags::default();
        let mut scene = Scene::new(vec![
            fx::block_in(
                1,
                Scope::Root,
                Rect::from_min_max(pos2(0.0, 0.0), pos2(80.0, 80.0)),
            ),
            fx::titled(1, "adder"),
        ]);
        let viewport = egui::Rect::from_min_size(egui::pos2(0.0, 0.0), egui::vec2(1000.0, 800.0));
        let settle = crate::canvas::settle::probe(30, |ui| {
            let tool: Tool = crate::tools::SelectTool.into();
            let path = BlockPath::empty();
            let mut set = {
                let drawing = scene.drawing();
                CommandSet::available(&CommandContext {
                    tool: &tool,
                    data: &drawing,
                    history: History::empty(),
                    current_lock: InterfaceLock::Unlocked,
                    writability: blockworx_store::doc::Writability::Writable,
                    saving: blockworx_store::doc::Saving::Withheld,
                    viewing: blockworx_store::doc::Viewing::Head,
                })
            };
            let indexed = scene.indexed();
            let revs = blockworx_store::history::rows(
                blockworx_store::history::Journal::Session(repo.log()),
                &tags,
            );
            let scope = PaletteScope {
                document: &indexed,
                path: &path,
                revs: &revs,
            };
            let _ = palette.show(ui.ctx(), &mut set, scope, viewport);
        });
        crate::canvas::settle::assert_settles(&settle, 3);
    }

    #[test]
    fn an_empty_query_lists_every_command_in_registry_order() {
        let mut fixture = block_selected_set();
        let rows = fixture.rows("");
        let ids: Vec<RowId> = rows.iter().map(|r| r.id.clone()).collect();
        let expected: Vec<RowId> = fixture.set.iter().map(|c| RowId::Command(c.id)).collect();
        assert_eq!(ids, expected);
    }

    /// `camera x y w h` frames a rect typed in grid cells — the same numbers
    /// the authoring footer prints for a level script.
    #[test]
    fn a_typed_camera_offers_a_row_and_rejects_nonsense() {
        let mut fixture = block_selected_set();
        let mut framed = |q: &str| {
            fixture.rows(q).into_iter().find_map(|r| match r.id {
                RowId::Camera(rect) => Some(rect),
                _ => None,
            })
        };
        assert_eq!(
            framed("camera 0 0 28 20"),
            Some(Rect::from_min_size(
                crate::grid::grid_pos(0, 0),
                crate::grid::grid_pos(28, 20).to_vec2(),
            ))
        );
        // Negative origins are fine — the canvas extends both ways.
        assert!(framed("camera -12 -4 10 10").is_some());
        // A size that frames nothing, or so much that the diagram vanishes.
        assert_eq!(framed("camera 0 0 0 20"), None, "zero width");
        assert_eq!(framed("camera 0 0 28 -20"), None, "negative height");
        assert_eq!(framed("camera 0 0 28 999999"), None, "absurd height");
        // Half-typed or misspelled: no row rather than a wrong framing.
        assert_eq!(framed("camera 0 0 28"), None, "too few values");
        assert_eq!(framed("camera 0 0 28 20 4"), None, "too many values");
        assert_eq!(framed("camera a b c d"), None, "not numbers");
    }

    /// `go <path>` parses whatever follows the verb, so a content path copied
    /// off the canvas navigates straight back — and leads the ranking.
    #[test]
    fn a_typed_content_path_offers_a_go_row() {
        let mut fixture = block_selected_set();
        let expected = {
            let indexed = fixture.scene.indexed();
            crate::tools::content_path::parse(&indexed, "adder")
                .expect("adder is a child of the root scope")
        };
        assert_eq!(
            fixture.rows("go adder").first().map(|r| r.id.clone()),
            Some(RowId::GoToPath(expected))
        );
        // A path that resolves to nothing offers no row to pick.
        assert!(
            !fixture
                .rows("go nowhere")
                .iter()
                .any(|r| matches!(r.id, RowId::GoToPath(_)))
        );
    }

    #[test]
    fn typeable_names_rank_their_command_first() {
        assert_eq!(top_row_id("fliplr"), RowId::Command(CommandId::FlipLr));
        assert_eq!(top_row_id("lock"), RowId::Command(CommandId::Lock));
        assert_eq!(
            top_row_id("route"),
            RowId::Command(CommandId::Arm(crate::tools::names::ToolName::Route))
        );
    }

    #[test]
    fn a_block_name_yields_a_find_row() {
        let mut fixture = block_selected_set();
        let matched = fixture.rows("adder");
        assert!(
            matched
                .iter()
                .any(|r| matches!(r.id, RowId::Block(_)) && r.text == "find adder"),
            "no find row for the adder block"
        );
        // The word `find` itself reaches the block rows too.
        let via_verb = fixture.rows("find add");
        assert!(via_verb.iter().any(|r| matches!(r.id, RowId::Block(_))));
    }

    /// A block on the current level can be descended into, so it gets an
    /// `expand` row; a block a level deeper is reachable by `find` only.
    #[test]
    fn only_blocks_on_the_current_level_get_an_expand_row() {
        let mut fixture = block_selected_set();
        // Precondition: `carry` is in the document but not on this level.
        assert!(fixture.blocks.iter().any(|(_, l)| l == "carry"));
        assert!(!fixture.level.iter().any(|(_, l)| l == "carry"));

        let matched = fixture.rows("expand");
        let expanded: Vec<&str> = matched
            .iter()
            .filter(|r| matches!(r.id, RowId::Expand(_)))
            .map(|r| r.text.as_str())
            .collect();
        assert_eq!(expanded, ["expand adder"]);
    }

    /// A commit is a result like any other: found by its number or by the
    /// words the history panel gives it, and picked to put that rev on the
    /// canvas.
    #[test]
    fn a_rev_is_found_by_its_number_and_by_its_label() {
        let mut fixture = block_selected_set();
        let picked = |rows: Vec<Row>| {
            rows.into_iter()
                .find_map(|row| match row.id {
                    RowId::Rev(rev) => Some(rev),
                    _ => None,
                })
                .map(|rev| rev.get())
        };
        assert_eq!(picked(fixture.rows("rev 2")), Some(2));
        assert_eq!(picked(fixture.rows("Moved the adder")), Some(2));
        assert_eq!(
            picked(fixture.rows("camera 0 0 8 8")),
            None,
            "a typed camera dragged the whole log in behind it",
        );
    }

    /// §6: the results are grouped by source, and ranking orders the rows
    /// inside each run rather than across the list. One query reaching three
    /// sources proves both halves at once.
    #[test]
    fn results_are_listed_in_source_order() {
        let mut fixture = block_selected_set();
        let rows = fixture.rows("add");
        let sources: Vec<Source> = rows.iter().map(|row| row.id.source()).collect();
        for source in [Source::Command, Source::Block, Source::Rev] {
            assert!(
                sources.contains(&source),
                "precondition: {source:?} answered nothing: {sources:?}",
            );
        }
        assert!(
            sources.is_sorted(),
            "the sources are interleaved: {sources:?}",
        );
        let scores: Vec<u32> = rows
            .iter()
            .filter(|row| row.id.source() == Source::Command)
            .map(|row| row.score)
            .collect();
        assert!(
            scores.windows(2).all(|pair| pair[0] >= pair[1]),
            "ranking stopped ordering the commands: {scores:?}",
        );
    }

    /// The headings are drawn, in order, above the rows they name — through
    /// real frames, so a heading that laid out but never painted fails here.
    #[test]
    fn every_run_of_rows_is_drawn_under_its_own_heading() {
        let mut fixture = block_selected_set();
        let mut palette = Palette::new();
        palette.query = "add".to_owned();
        let screen = Rect::from_min_size(pos2(0.0, 0.0), vec2(1000.0, 800.0));
        let mut chrome = crate::tools::painted::Chrome::new(screen);
        chrome.settle(|ui| {
            // `show` finds the blocks itself; the fixture's own lists are
            // for `rows`.
            let Fixture {
                set,
                scene,
                repo,
                tags,
                ..
            } = &mut fixture;
            let indexed = scene.indexed();
            let revs = blockworx_store::history::rows(
                blockworx_store::history::Journal::Session(repo.log()),
                tags,
            );
            let here = BlockPath::empty();
            let _ = palette.show(
                ui.ctx(),
                set,
                PaletteScope {
                    document: &indexed,
                    path: &here,
                    revs: &revs,
                },
                screen.egui(),
            );
        });
        let mut headings = Vec::new();
        for source in [Source::Command, Source::Block, Source::Rev] {
            let at = chrome.rect(source.heading()).unwrap_or_else(|| {
                panic!(
                    "the palette never drew the {:?} heading: {:?}",
                    source,
                    chrome.texts(),
                )
            });
            headings.push((source, at));
        }
        assert!(
            headings
                .windows(2)
                .all(|pair| pair[0].1.top() < pair[1].1.top()),
            "the headings are out of source order: {headings:?}",
        );
        let found = chrome
            .rect("find adder")
            .expect("the adder's find row never drew");
        let (_, blocks) = headings[1];
        let (_, revs) = headings[2];
        assert!(
            found.top() > blocks.top() && found.top() < revs.top(),
            "the find row at {found:?} is not under the Blocks heading at {blocks:?}",
        );
    }
}