blockworx/panels/

history_panel.rs

//! The time machine's panel: the document's revs, newest first, with the
//! one on the canvas expanded. Rationale: `docs/single-author-playbook.md`.
//!
//! The History segment of the [navigator](crate::shell::navigator) — the
//! navigator's sibling: one walks the document's structure, the other its
//! past. Picking a row puts that rev on the same canvas, read-only; the
//! `Current` row at the top is the way back to the live document.
//!
//! A history of hundreds of homogeneous items is **rows, not cards**, dense
//! enough to scan — so the one rev being viewed is the only one that
//! expands, and it expands *in place* into the card that shows every field
//! and hosts the tag editor. Ordering follows what people scan for: what
//! changed, then where, then what it was called; who and when trail behind,
//! and the rev number is the smallest thing on the row because it is an
//! identifier rather than something anybody looks for.
//!
//! Filtering is one search field, not facets: text search over a generated
//! description is not what a reader remembers, while scope and tags are.
//! The prefixes (`tag:`, `by:`, `in:`, `#`) are how a reader says which of
//! those they mean.
//!
//! Thin on purpose. What a row *says* is [`blockworx_store::history::Row`],
//! shared with `blockworx log`, and what a search *admits* is
//! [`Query`] beside it, so this file decides nothing another surface
//! could disagree with.

use crate::canvas::convert::IntoEgui as _;
use blockworx_doc::rev::Rev;
use blockworx_store::doc::Viewing;
use blockworx_store::history::{Day, Query, Row, tag_query};
use blockworx_store::record::WallTime;
use blockworx_store::tags::Tagging;

use crate::{
    theme::{Role, Theme},
    tools::commands::Act,
    tools::tool::Action,
};

/// What the panel lists and which row is on the canvas.
#[derive(Clone, Copy)]
pub struct HistoryScene<'a> {
    /// Oldest first, as the manifest holds them; the panel shows them
    /// reversed.
    pub rows: &'a [Row],
    pub viewing: Viewing,
    /// The head rev — whichever row carries it is the writable present, so
    /// a click on it returns rather than opening a lens on what is already
    /// on the canvas.
    pub head: Rev,
    /// What the rows' days are measured against.
    pub now: WallTime,
    /// Resolves the badge and avatar roles — the two things the panel
    /// paints that the surrounding egui chrome has no color for.
    pub theme: &'a Theme,
}

/// The panel body and the state it carries between frames: what the reader
/// has narrowed the history down to, which must survive the panel being
/// collapsed and reopened.
pub struct HistoryPanel<'a> {
    pub scene: HistoryScene<'a>,
    pub search: &'a mut String,
}

/// The panel's body, drawn into whatever `ui` the workspace gives it: the
/// sticky search field over the rows, grouped by day. What the panel is
/// called and how it is collapsed are the frame's business, not this
/// file's.
pub fn body(ui: &mut egui::Ui, panel: HistoryPanel<'_>) -> Option<Act> {
    let HistoryPanel { scene, search } = panel;
    let query = Query::parse(search);
    let shown = scene.rows.iter().filter(|row| query.admits(row)).count();
    let mut action = None;
    search_field(ui, search, &query, shown, scene.rows.len());
    let reveal = reveal(ui.ctx(), scene.viewing);
    egui::ScrollArea::vertical()
        .auto_shrink([false, false])
        // The user: *"Hide the scroll bar on the history list."* The rows
        // are one column and the bar was the only vertical line in the
        // panel; the wheel and the drag are untouched.
        .scroll_bar_visibility(egui::scroll_area::ScrollBarVisibility::AlwaysHidden)
        .show(ui, |ui| {
            action = list(ui, &scene, &query, reveal);
        });
    if let Some(Picked::Tag(name)) = &action {
        *search = tag_query(name);
    }
    match action {
        Some(Picked::Act(action)) => Some(action),
        _ => None,
    }
}

/// What a click in the list asked for. A tag chip does nothing to the
/// document and nothing to a dialog — it narrows the list — so it cannot be
/// an [`Act`], and making it one variant of what a click returns keeps the
/// list's rows answering one question instead of two.
enum Picked {
    Act(Act),
    Tag(String),
}

/// The search field: sticky at the top, with the count reading "N of M"
/// while a query is active.
fn search_field(ui: &mut egui::Ui, search: &mut String, query: &Query, shown: usize, total: usize) {
    let count = if query.narrows() {
        format!("{shown} of {total}")
    } else {
        total.to_string()
    };
    sides(ui).show(
        ui,
        |ui| {
            ui.add(
                egui::TextEdit::singleline(search)
                    .hint_text("Search history")
                    .desired_width(f32::INFINITY),
            );
        },
        |ui| {
            ui.label(egui::RichText::new(count).small().weak());
        },
    );
    ui.add_space(SEARCH_AIR);
}

/// Whether this frame drags the viewed rev's row into view.
#[derive(Clone, Copy, PartialEq, Eq, Debug)]
enum Reveal {
    Now,
    LeaveTheScroll,
}

/// The panel opens wherever the canvas is standing, which is no use if
/// the row it is standing on is a hundred revs down the list. Scroll to it
/// on the frame the panel appears, and again whenever the canvas moves to
/// another rev under it — but not on every frame, or the list could never
/// be scrolled by hand.
fn reveal(ctx: &egui::Context, viewing: Viewing) -> Reveal {
    let id = panel_id().with("last-drawn");
    let now = ctx.cumulative_pass_nr();
    let before: Option<(u64, Viewing)> = ctx.data(|d| d.get_temp(id));
    ctx.data_mut(|d| d.insert_temp(id, (now, viewing)));
    match before {
        // A gap in the passes means the panel was not up: it is opening.
        Some((pass, seen)) if pass + 1 == now && seen == viewing => Reveal::LeaveTheScroll,
        _ => Reveal::Now,
    }
}

/// The rows, newest first, grouped under the day they were written, with
/// the `Current` row above them. `reveal` scrolls whichever row the canvas
/// is standing on into view — the frame the panel opens, and whenever the
/// canvas moves under it.
fn list(
    ui: &mut egui::Ui,
    scene: &HistoryScene<'_>,
    query: &Query,
    reveal: Reveal,
) -> Option<Picked> {
    let HistoryScene {
        rows,
        viewing,
        head,
        now,
        theme,
    } = *scene;
    let mut picked = None;
    // The `Current` row is the head's representation, not a filter result;
    // a narrowed list is a list of matches, so it stands down.
    if !query.narrows() {
        picked = current_row(ui, viewing, rows.iter().find(|row| row.rev == head));
    }
    let mut shown = 0;
    // A session with no clock has no days to group under, so its rows run
    // on unheaded rather than under one invented heading.
    let mut heading_shown: Option<Day> = None;
    // The head has no row of its own. The user: *"With a 'Current' at the
    // top of the history view, the previous entry in the list is redundant
    // (clicking r10 does nothing since it's considered the 'Current'
    // revision - so hide r10 from the list."* It was inert by construction,
    // which is exactly what makes it a row that says nothing.
    for row in rows
        .iter()
        .rev()
        .filter(|row| row.rev != head)
        .filter(|row| query.admits(row))
    {
        shown += 1;
        if let Some(day) = row.day()
            && heading_shown != Some(day)
        {
            heading_shown = Some(day);
            crate::panels::overlay::group_heading(ui, &day.label(now));
        }
        let response = if marked(viewing, row.rev) == OnCanvas::Yes {
            let (response, act) = rev_card(ui, row, rows, theme);
            picked = act.or(picked);
            response
        } else {
            let (response, act) = rev_row(ui, row, rows, theme);
            if response.clicked() {
                picked = Some(Picked::Act(Action::ViewRev(row.rev).into()));
            }
            // A chip narrows the list rather than visiting the rev, so it
            // answers after the row it sits on.
            picked = act.or(picked);
            response
        };
        if reveal == Reveal::Now && marked(viewing, row.rev) == OnCanvas::Yes {
            response.scroll_to_me(Some(egui::Align::Center));
        }
    }
    if shown == 0 && query.narrows() {
        nothing_matches(ui);
    }
    picked
}

/// The empty result, which names the prefixes rather than only reporting
/// the emptiness: the reader who typed a word that matched nothing is the
/// reader who has not met `tag:` yet.
fn nothing_matches(ui: &mut egui::Ui) {
    ui.add_space(SEARCH_AIR);
    ui.label(
        egui::RichText::new("Nothing matches. Try tag:, by:, in:, or # for a rev number.")
            .small()
            .weak(),
    );
}

/// The `Current` row: the live document, at the top of the list and above
/// the newest rev's own day. It is where the lens is let go of — the same
/// return the viewing pill offers, in the list a reader is already reading.
fn current_row(ui: &mut egui::Ui, viewing: Viewing, head: Option<&Row>) -> Option<Picked> {
    let live = OnCanvas::from(viewing == Viewing::Head);
    let (response, ()) = clickable(ui, live, |ui| {
        sides(ui).show(
            ui,
            |ui| {
                let (rect, _) =
                    ui.allocate_exact_size(egui::Vec2::splat(AVATAR), egui::Sense::hover());
                ui.painter().circle_filled(
                    rect.center(),
                    LIVE_DOT,
                    ui.visuals().selection.stroke.color,
                );
                ui.label("Current");
            },
            |ui| {
                ui.label(
                    egui::RichText::new(match live {
                        OnCanvas::Yes => "editing",
                        OnCanvas::No => "return",
                    })
                    .small()
                    .weak(),
                );
            },
        );
    });
    let _ = head;
    (response.clicked() && live == OnCanvas::No).then_some(Picked::Act(Action::ViewHead.into()))
}

/// Whether a row is the one the list marks — the mockup's `aria-current`.
#[derive(Clone, Copy, PartialEq, Eq)]
enum OnCanvas {
    Yes,
    No,
}

/// Which row wears the mark: a rev's row only while the lens is on that rev,
/// so at head the `Current` row wears it alone and the newest rev is not a
/// second answer to the same question.
fn marked(viewing: Viewing, rev: Rev) -> OnCanvas {
    OnCanvas::from(matches!(viewing, Viewing::Past(at) if at == rev))
}

impl From<bool> for OnCanvas {
    fn from(here: bool) -> Self {
        if here { OnCanvas::Yes } else { OnCanvas::No }
    }
}

/// One unexpanded rev: the author's initials, then what changed over
/// where it changed over what it is called, with the time and the rev
/// number trailing.
fn rev_row(
    ui: &mut egui::Ui,
    row: &Row,
    rows: &[Row],
    theme: &Theme,
) -> (egui::Response, Option<Picked>) {
    let mut picked = None;
    let (response, ()) = clickable(ui, OnCanvas::No, |ui| {
        sides(ui).show(
            ui,
            |ui| {
                avatar(ui, row, theme);
                ui.vertical(|ui| {
                    ui.add(description(ui, row, rows));
                    scope_line(ui, row);
                    picked = tag_chips(ui, row, theme);
                });
            },
            |ui| meta(ui, row),
        );
    });
    (response, picked)
}

/// The rev being viewed, expanded in place: every field in full, and the
/// tag editor.
///
/// The card is where the per-rev affordances live now. A `…` on every row
/// was a control that said nothing about the row it sat on, and the one
/// rev a reader is looking at is the one they act on.
fn rev_card(
    ui: &mut egui::Ui,
    row: &Row,
    rows: &[Row],
    theme: &Theme,
) -> (egui::Response, Option<Picked>) {
    let mut picked = None;
    let tint = ui.visuals().selection.bg_fill;
    let frame = egui::Frame::new()
        .fill(tint)
        .corner_radius(CARD_RADIUS)
        .inner_margin(CARD_PAD)
        .show(ui, |ui| {
            ui.horizontal(|ui| {
                avatar(ui, row, theme);
                let by = row.author();
                if !by.is_empty() {
                    ui.label(egui::RichText::new(by).strong());
                }
                ui.label(egui::RichText::new(row.full_when()).small().weak());
                ui.with_layout(egui::Layout::right_to_left(egui::Align::Center), |ui| {
                    ui.label(rev_number(row.rev));
                });
            });
            ui.add_space(CARD_GAP);
            ui.add(egui::Label::new(
                egui::RichText::new(blockworx_store::history::said(row, rows)).size(CARD_TITLE),
            ));
            let names = row.scope_names();
            if !names.is_empty() {
                ui.label(
                    egui::RichText::new(names.join(SEPARATOR))
                        .small()
                        .color(ui.visuals().text_color()),
                );
            }
            ui.add_space(CARD_GAP);
            picked = tag_editor(ui, row, rows, theme);
        });
    (frame.response, picked)
}

/// The author's initials on a disc, in one of five accent roles picked by
/// hashing their name, so the same hand keeps the same colour down the list.
fn avatar(ui: &mut egui::Ui, row: &Row, theme: &Theme) {
    let (rect, response) = ui.allocate_exact_size(egui::Vec2::splat(AVATAR), egui::Sense::hover());
    let by = row.author();
    if by.is_empty() {
        return;
    }
    ui.painter().circle_filled(
        rect.center(),
        AVATAR / 2.0,
        theme
            .resolve(blockworx_paint::theme::avatar_role(by))
            .egui(),
    );
    ui.painter().text(
        rect.center(),
        egui::Align2::CENTER_CENTER,
        row.initials(),
        small(ui),
        theme.resolve(Role::AuthorAvatarText).egui(),
    );
    response.on_hover_text(by);
}

/// The row's primary line. An inverse rev names what it took back —
/// `Undo — <original>` — and is drawn muted and italic so a reader
/// scanning for when a thing changed reads past it.
fn description(ui: &egui::Ui, row: &Row, rows: &[Row]) -> egui::Label {
    let text = egui::RichText::new(blockworx_store::history::said(row, rows));
    egui::Label::new(if row.is_inverse() {
        text.italics().color(ui.visuals().weak_text_color())
    } else {
        text
    })
    .wrap()
}

/// The scope line, elided **from the left** so the leaf — the thing the
/// act actually happened to — is the part that survives a narrow panel.
fn scope_line(ui: &mut egui::Ui, row: &Row) {
    let names = row.scope_names();
    if names.is_empty() {
        return;
    }
    let whole = names.join(SEPARATOR);
    let shown = fits_from_the_left(ui, names, ui.available_width());
    ui.label(egui::RichText::new(shown).small().weak())
        .on_hover_text(whole);
}

/// The deepest run of `names` that fits in `room`, with a leading ellipsis
/// where anything was dropped. egui elides from the right, which would
/// take the leaf and leave the root — the wrong half.
fn fits_from_the_left(ui: &egui::Ui, names: &[String], room: f32) -> String {
    for start in 0..names.len() {
        let kept = names[start..].join(SEPARATOR);
        let text = if start == 0 {
            kept
        } else {
            format!("\u{2026}{SEPARATOR}{kept}")
        };
        if measure(ui, &text) <= room || start + 1 == names.len() {
            return text;
        }
    }
    String::new()
}

/// The row's tags as chips. Clicking one narrows the list to it, which is
/// the whole of what a tag is for on an unexpanded row.
fn tag_chips(ui: &mut egui::Ui, row: &Row, theme: &Theme) -> Option<Picked> {
    if row.tags.is_empty() {
        return None;
    }
    let mut picked = None;
    ui.horizontal_wrapped(|ui| {
        for tag in &row.tags {
            if chip(ui, tag, theme).clicked() {
                picked = Some(Picked::Tag(tag.clone()));
            }
        }
    });
    picked
}

fn chip(ui: &mut egui::Ui, tag: &str, theme: &Theme) -> egui::Response {
    ui.add(
        egui::Button::new(
            egui::RichText::new(tag)
                .small()
                .color(theme.resolve(Role::TagBadgeText).egui()),
        )
        .fill(theme.resolve(Role::TagBadge).egui())
        .corner_radius(CHIP_RADIUS),
    )
}

/// The card's tag editor: the rev's own names as removable chips, and a
/// field that offers the document's existing vocabulary as it is typed, so
/// that a diagram tagged in one set of words stays searchable and five
/// spellings of one word do not accumulate.
///
/// The draft lives in egui's own transient store keyed by the rev, so a
/// half-typed name survives a frame without the editor holding state for
/// it.
fn tag_editor(ui: &mut egui::Ui, row: &Row, rows: &[Row], theme: &Theme) -> Option<Picked> {
    let mut picked = None;
    let id = panel_id().with(("tag", row.rev.get()));
    let mut draft: String = ui.data(|d| d.get_temp(id)).unwrap_or_default();
    ui.horizontal_wrapped(|ui| {
        for tag in &row.tags {
            if chip(ui, tag, theme).clicked() {
                picked = Some(Picked::Tag(tag.clone()));
            }
            if ui
                .add(egui::Button::new("\u{d7}").frame(false))
                .on_hover_text("Remove this tag")
                .clicked()
            {
                picked = Some(Picked::Act(
                    Action::TagRev {
                        at: row.rev,
                        name: tag.clone(),
                        how: Tagging::Removed,
                    }
                    .into(),
                ));
            }
        }
        let edit = ui.add(
            egui::TextEdit::singleline(&mut draft)
                .hint_text("Add tag")
                .desired_width(TAG_FIELD),
        );
        // `lost_focus`, not `has_focus`: a single-line `TextEdit` takes the
        // Enter for itself and gives up focus on it, so the key never
        // reaches a frame where the field still has focus.
        let entered = edit.lost_focus() && ui.input(|i| i.key_pressed(egui::Key::Enter));
        if entered && !draft.trim().is_empty() {
            picked = Some(Picked::Act(
                Action::TagRev {
                    at: row.rev,
                    name: draft.clone(),
                    how: Tagging::Added,
                }
                .into(),
            ));
            draft.clear();
        }
    });
    for name in suggestions(&draft, row, rows) {
        if ui.add(egui::Button::new(&name).frame(false)).clicked() {
            picked = Some(Picked::Act(
                Action::TagRev {
                    at: row.rev,
                    name,
                    how: Tagging::Added,
                }
                .into(),
            ));
            draft.clear();
        }
    }
    ui.data_mut(|d| d.insert_temp(id, draft));
    picked
}

/// The vocabulary this document already uses, minus what the rev already
/// carries, narrowed by what has been typed so far.
fn suggestions(draft: &str, row: &Row, rows: &[Row]) -> Vec<String> {
    let typed = draft.trim().to_lowercase();
    let mut seen: Vec<String> = Vec::new();
    for tag in rows.iter().flat_map(|row| &row.tags) {
        if row.tags.contains(tag) || seen.contains(tag) {
            continue;
        }
        if typed.is_empty() || tag.contains(&typed) {
            seen.push(tag.clone());
        }
    }
    seen.sort();
    seen.truncate(SUGGESTIONS);
    seen
}

/// A whole row as one click target — a rev is visited by clicking anywhere
/// along it, not by finding its label — with the tint behind it drawn from
/// the response, so hover and current are the one shape.
fn clickable<R>(
    ui: &mut egui::Ui,
    here: OnCanvas,
    contents: impl FnOnce(&mut egui::Ui) -> R,
) -> (egui::Response, R) {
    let backdrop = ui.painter().add(egui::Shape::Noop);
    let inner = ui.scope_builder(egui::UiBuilder::new().sense(egui::Sense::click()), |ui| {
        // The row is the target, so the text on it is not: egui makes a
        // label selectable by default, and a selectable label senses the
        // click before the row underneath it does.
        ui.style_mut().interaction.selectable_labels = false;
        contents(ui)
    });
    let fill = match (here, inner.response.hovered()) {
        (OnCanvas::Yes, _) => ui.visuals().selection.bg_fill,
        (OnCanvas::No, true) => ui.visuals().widgets.hovered.weak_bg_fill,
        (OnCanvas::No, false) => egui::Color32::TRANSPARENT,
    };
    ui.painter().set(
        backdrop,
        egui::epaint::RectShape::filled(inner.response.rect.expand(ROW_AIR), ROW_RADIUS, fill),
    );
    (inner.response, inner.inner)
}

/// A row's trailing cluster: when it happened over which rev it is.
fn meta(ui: &mut egui::Ui, row: &Row) {
    ui.with_layout(egui::Layout::top_down(egui::Align::Max), |ui| {
        // A session with no clock has no time to stamp its rows with, and
        // an empty label would still take the line the number wants.
        let when = row.time();
        if !when.is_empty() {
            ui.label(egui::RichText::new(when).small().weak())
                .on_hover_text(row.full_when());
        }
        ui.label(rev_number(row.rev));
    });
}

/// The panel's one row shape: a trailing cluster that takes the width it
/// needs and a leading side that takes the rest, truncating rather than
/// pushing its neighbour off the edge.
///
/// `shrink_left` is the whole of it. Reserving the room by measuring the
/// trailing text and subtracting — which this file did until the layout
/// was reviewed — is the same rule written twice and rounded differently
/// each time.
fn sides(ui: &egui::Ui) -> egui::containers::Sides {
    egui::containers::Sides::new()
        .shrink_left()
        .spacing(ui.spacing().item_spacing.x)
}

/// The rev number, the smallest thing on the row: an identifier rather
/// than something anybody scans for.
fn rev_number(rev: Rev) -> egui::RichText {
    egui::RichText::new(format!("#{}", rev.get()))
        .small()
        .weak()
}

/// How wide `text` reads at the small style — the one measurement the
/// panel still makes, for the one thing no layout gives it: eliding a path
/// from the left.
fn measure(ui: &egui::Ui, text: &str) -> f32 {
    ui.painter()
        .layout_no_wrap(text.to_owned(), small(ui), egui::Color32::PLACEHOLDER)
        .rect
        .width()
}

fn small(ui: &egui::Ui) -> egui::FontId {
    egui::TextStyle::Small.resolve(ui.style())
}

fn panel_id() -> egui::Id {
    egui::Id::new("history_panel")
}

/// What separates two names on the scope line, in the spelling the content
/// path along the canvas bottom uses.
const SEPARATOR: &str = " / ";

/// The avatar, and the live dot the `Current` row wears in its place.
const AVATAR: f32 = 26.0;
const LIVE_DOT: f32 = 4.5;

/// The air a row's tint is drawn out into around its content, and the
/// inner radius it is drawn with.
const ROW_AIR: f32 = 4.0;
const ROW_RADIUS: u8 = 12;

/// The expanded card: its corner, its padding, the air between its
/// stacked fields, and the 15px description.
const CARD_RADIUS: u8 = 14;
const CARD_PAD: i8 = 12;
const CARD_GAP: f32 = 8.0;
const CARD_TITLE: f32 = 15.0;

/// A tag chip's corner — small enough to read as a chip rather than a
/// button.
const CHIP_RADIUS: u8 = 6;

/// The tag field, and how many of the vocabulary it offers at once. Four,
/// as the mockup has it: a suggestion list long enough to scroll is a
/// second list to read.
const TAG_FIELD: f32 = 82.0;
const SUGGESTIONS: usize = 4;

/// The air under the search field, before the first day heading.
const SEARCH_AIR: f32 = 6.0;

#[cfg(test)]
mod tests {
    use super::*;
    use crate::canvas::convert::IntoGeom as _;
    use blockworx_doc::repo::Repo;
    use blockworx_geom::{Rect, pos2, vec2};
    use blockworx_store::history::{self, Journal};
    use blockworx_store::manifest::{Row as Written, RowKind};
    use blockworx_store::record::{Camera, Digest, Identity, ScopePath};
    use blockworx_store::tags::Tags;

    /// What the panel reads: a container's rows, or — with none — the
    /// commits a session with no files holds.
    fn journal<'a>(repo: &'a Repo, written: &'a [Written]) -> Journal<'a> {
        if written.is_empty() {
            Journal::Session(repo.log())
        } else {
            Journal::Recorded(written)
        }
    }

    /// The panel, driven through real frames by what it actually painted —
    /// so a row that laid out but never drew, or that moved out from under
    /// the pointer, fails here.
    struct Panel {
        chrome: crate::panels::painted::Chrome,
        session: Session,
    }

    struct Session {
        repo: Repo,
        /// The rows a container wrote beside the commits — empty for a
        /// scratch session, which has neither clock nor author.
        written: Vec<Written>,
        tags: Tags,
        now: WallTime,
        search: String,
        viewing: Viewing,
        fired: Option<Act>,
    }

    impl Session {
        fn frame(&mut self, ui: &mut egui::Ui) {
            let theme = crate::theme::Theme::default();
            let rows = history::rows(journal(&self.repo, &self.written), &self.tags);
            let mut panel = ui.new_child(
                egui::UiBuilder::new()
                    .id(egui::Id::new("history_body"))
                    .max_rect(egui::Rect::from_min_size(
                        egui::pos2(20.0, 40.0),
                        egui::vec2(312.0, 640.0),
                    ))
                    .layout(egui::Layout::top_down(egui::Align::Min)),
            );
            let fired = body(
                &mut panel,
                HistoryPanel {
                    scene: HistoryScene {
                        rows: &rows,
                        viewing: self.viewing,
                        head: self.repo.rev(),
                        now: self.now,
                        theme: &theme,
                    },
                    search: &mut self.search,
                },
            );
            if fired.is_some() {
                self.fired = fired;
            }
        }
    }

    impl Panel {
        fn over(repo: Repo, written: Vec<Written>, tags: Tags, now: WallTime) -> Self {
            let mut panel = Panel {
                chrome: crate::panels::painted::Chrome::new(Rect::from_min_size(
                    pos2(0.0, 0.0),
                    vec2(1000.0, 800.0),
                )),
                session: Session {
                    repo,
                    written,
                    tags,
                    now,
                    search: String::new(),
                    viewing: Viewing::Head,
                    fired: None,
                },
            };
            panel.settle();
            panel
        }

        fn settle(&mut self) {
            let Self { chrome, session } = self;
            chrome.settle(|ui| session.frame(ui));
        }

        fn click_at(&mut self, at: egui::Pos2) {
            let Self { chrome, session } = self;
            chrome.click_at(at.geom(), |ui| session.frame(ui));
        }

        fn click_on(&mut self, text: &str) {
            let Self { chrome, session } = self;
            chrome.click_on(text, |ui| session.frame(ui));
        }

        fn type_text(&mut self, text: &str) {
            let Self { chrome, session } = self;
            chrome.type_text(text, |ui| session.frame(ui));
        }

        fn press(&mut self, key: egui::Key) {
            let Self { chrome, session } = self;
            chrome.press(key, |ui| session.frame(ui));
        }

        /// Put the caret in the search box and type — the box is the only
        /// text field on an unexpanded list.
        fn search_for(&mut self, text: &str) {
            self.click_on("Search history");
            self.type_text(text);
            self.settle();
        }

        fn viewing(&mut self, at: Viewing) {
            self.session.viewing = at;
            self.settle();
        }
    }

    /// What the panel asked for, named — neither an `Act` nor an `Action` is
    /// `Debug`, and a failure that cannot say what fired instead is a failure
    /// you have to re-run under a debugger.
    fn fired(panel: &Panel) -> String {
        match &panel.session.fired {
            None => "nothing".to_owned(),
            Some(Act::Edit(Action::ViewHead)) => "ViewHead".to_owned(),
            Some(Act::Edit(Action::ViewRev(at))) => format!("ViewRev(r{})", at.get()),
            Some(Act::Edit(Action::TagRev { at, name, how })) => {
                format!("TagRev(r{}, {name:?}, {how:?})", at.get())
            }
            Some(_) => "another act".to_owned(),
        }
    }

    const TODAY: u64 = 1_756_000_000_000;
    const A_DAY: u64 = 86_400_000;

    /// One manifest row, unchained — the panel reads rows, never the links
    /// between them.
    fn row(n: u64, at: u64, kind: RowKind, by: &str) -> Written {
        Written {
            rev: blockworx_doc::fixtures::rev(n),
            kind,
            wall_time: WallTime::from_unix_millis(at),
            author: Identity::new(by),
            label: label_of(n),
            scope: ScopePath::default(),
            scope_names: vec!["engine".to_owned(), "left motor mount".to_owned()],
            camera: Camera::UNSEEN,
            touched: vec![blockworx_doc::id::EntityRef::Block(
                blockworx_doc::fixtures::block_id(n as u32),
            )],
            truncated: false,
            hash: Digest::of(format!("rev {n}").as_bytes()),
            parent: Digest::genesis(),
        }
    }

    fn label_of(n: u64) -> String {
        match n {
            1 => "Added Adder",
            2 => "Undo Added Adder",
            3 => "Added Mux",
            _ => "Added Register",
        }
        .to_owned()
    }

    fn recorded() -> Panel {
        recorded_with(Tags::default())
    }

    fn recorded_with(tags: Tags) -> Panel {
        let repo = Repo::folding(&[
            blockworx_store::fixture::commit(
                "Added Adder",
                vec![blockworx_store::fixture::block_create(1, "Adder")],
            ),
            blockworx_store::fixture::commit(
                "Undo Added Adder",
                vec![blockworx_store::fixture::block_create(2, "Summer")],
            ),
            blockworx_store::fixture::commit(
                "Added Mux",
                vec![blockworx_store::fixture::block_create(3, "Mux")],
            ),
            // The head, which the list does not draw — so every row the
            // tests below read is one the panel really shows.
            blockworx_store::fixture::commit(
                "Added Register",
                vec![blockworx_store::fixture::block_create(4, "Register")],
            ),
        ])
        .expect("the fixture commits fold");
        let written = vec![
            row(1, TODAY - 2 * A_DAY, RowKind::Edit, "ada lovelace"),
            row(
                2,
                TODAY,
                RowKind::Undo {
                    of: blockworx_doc::fixtures::rev(1),
                },
                "ada lovelace",
            ),
            row(3, TODAY, RowKind::Edit, "grace hopper"),
            row(4, TODAY, RowKind::Edit, "grace hopper"),
        ];
        Panel::over(repo, written, tags, WallTime::from_unix_millis(TODAY))
    }

    /// A row, field by field: the author's initials on the avatar, the
    /// description, the scope under it, and the rev number trailing.
    #[test]
    fn a_row_carries_its_author_its_description_its_scope_and_its_number() {
        let panel = recorded();
        for expected in ["AL", "Added Mux", "engine / left motor mount", "#3"] {
            assert!(
                panel.chrome.says(expected),
                "a row does not show {expected:?}: {:?}",
                panel.chrome.texts(),
            );
        }
    }

    /// The scope is truncated from the *left*, so the leaf — the thing the
    /// act actually happened to — is the half that survives a narrow panel.
    #[test]
    fn the_scope_line_keeps_its_leaf_and_drops_its_root() {
        let ctx = egui::Context::default();
        let names: Vec<String> = ["engine", "left motor mount", "base plate"]
            .iter()
            .map(|name| (*name).to_owned())
            .collect();
        let mut shown = String::new();
        ctx.run_ui(egui::RawInput::default(), |ui| {
            let whole = fits_from_the_left(ui, &names, 4_000.0);
            assert_eq!(
                whole, "engine / left motor mount / base plate",
                "a line with room to spare was elided anyway",
            );
            shown = fits_from_the_left(ui, &names, 60.0);
        })
        .drop_without_applying_deltas();
        assert!(
            shown.ends_with("base plate"),
            "the leaf was elided away: {shown:?}",
        );
        assert!(
            shown.starts_with('\u{2026}'),
            "an elided line does not say so: {shown:?}",
        );
    }

    /// An inverse rev names what it took back, and is muted and italic
    /// where its neighbours are neither, so a reader scanning the log can
    /// read past it.
    #[test]
    fn an_undo_rev_names_what_it_took_back_and_is_muted_and_italic() {
        let panel = recorded();
        let undone = panel
            .chrome
            .format_of("Undo \u{2014} Added Adder")
            .expect("the undo row does not name the rev it took back");
        let plain = panel
            .chrome
            .format_of("Added Mux")
            .expect("an ordinary row painted its label");
        assert!(!plain.italics, "an ordinary rev is already italic");
        assert!(undone.italics, "the inverse rev is not italic");
        assert_ne!(
            undone.color, plain.color,
            "the inverse rev is not muted from its neighbours",
        );
    }

    /// The rows fall under the day they were written, and the last two days
    /// are named rather than dated.
    #[test]
    fn the_rows_group_under_the_day_they_were_written() {
        let panel = recorded();
        assert!(
            panel.chrome.says("Today"),
            "no day heading: {:?}",
            panel.chrome.texts(),
        );
        assert!(
            panel
                .chrome
                .texts()
                .iter()
                .any(|text| *text != "Today" && text.contains('-') && text.starts_with("20")),
            "the older day was not dated: {:?}",
            panel.chrome.texts(),
        );
    }

    /// A session with no container has no clock, so it invents neither a day
    /// to group under nor a time to stamp its rows with.
    #[test]
    fn a_session_with_no_clock_shows_no_day_headings() {
        let repo =
            Repo::folding(&blockworx_store::fixture::edits(3)).expect("the fixture commits fold");
        let panel = Panel::over(repo, Vec::new(), Tags::default(), history::now());
        assert!(
            !panel.chrome.says("Today"),
            "a session with no clock invented a day: {:?}",
            panel.chrome.texts(),
        );
    }

    /// The count reads the whole history until a query narrows it, then
    /// how much of it survived.
    #[test]
    fn the_count_reads_n_of_m_only_while_a_query_narrows() {
        let mut panel = recorded();
        assert!(
            panel.chrome.says("4"),
            "the unnarrowed count is not the whole history: {:?}",
            panel.chrome.texts(),
        );
        panel.search_for("Mux");
        assert!(
            panel.chrome.says("1 of 4"),
            "a narrowed list does not say how much it kept: {:?}",
            panel.chrome.texts(),
        );
    }

    /// The `Current` row is the head's representation, not a match — so a
    /// narrowed list, which is a list of matches, does not carry it.
    #[test]
    fn the_current_row_stands_down_while_a_query_narrows_the_list() {
        let mut panel = recorded();
        assert!(panel.chrome.says("Current"));
        panel.search_for("Mux");
        assert!(
            !panel.chrome.says("Current"),
            "the Current row survived a filter it is not a match for",
        );
    }

    /// An empty result teaches the prefixes rather than only reporting
    /// the emptiness.
    #[test]
    fn an_empty_result_names_the_prefixes() {
        let mut panel = recorded();
        panel.search_for("nothing whatsoever");
        assert!(
            panel
                .chrome
                .says("Nothing matches. Try tag:, by:, in:, or # for a rev number."),
            "an empty result said nothing useful: {:?}",
            panel.chrome.texts(),
        );
    }

    /// The prefixes narrow to one column: `by:` reaches an author whose name
    /// appears in no description.
    #[test]
    fn a_by_prefix_narrows_to_the_author() {
        let mut panel = recorded();
        panel.search_for("by:grace");
        assert!(
            panel.chrome.says("Added Mux"),
            "grace's row was filtered out: {:?}",
            panel.chrome.texts(),
        );
        assert!(
            !panel.chrome.says("Added Adder"),
            "ada's row survived a search for grace: {:?}",
            panel.chrome.texts(),
        );
    }

    /// Clicking a tag chip anywhere in the list sets `tag:<name>`, which
    /// is the whole of what a tag does on an unexpanded row.
    #[test]
    fn clicking_a_tag_chip_narrows_the_list_to_that_tag() {
        let mut tags = Tags::default();
        tags.add(blockworx_doc::fixtures::rev(3), "vendor");
        let mut panel = recorded_with(tags);
        assert!(
            panel.chrome.says("vendor"),
            "the tag chip was not drawn: {:?}",
            panel.chrome.texts(),
        );
        panel.click_on("vendor");
        panel.settle();
        assert_eq!(panel.session.search, "tag:vendor");
        assert!(
            panel.chrome.says("Added Mux") && !panel.chrome.says("Added Adder"),
            "the chip did not narrow the list: {:?}",
            panel.chrome.texts(),
        );
    }

    /// The rev on the canvas expands in place into the card: every field
    /// in full, where the row had only what fits.
    #[test]
    fn the_viewed_rev_expands_into_a_card_carrying_every_field() {
        let mut panel = recorded();
        panel.viewing(Viewing::Past(blockworx_doc::fixtures::rev(3)));
        for expected in ["grace hopper", "Added Mux", "#3"] {
            assert!(
                panel.chrome.says(expected),
                "the card does not show {expected:?}: {:?}",
                panel.chrome.texts(),
            );
        }
        assert!(
            panel
                .chrome
                .texts()
                .iter()
                .any(|text| text.contains("2025") && text.contains(':')),
            "the card does not carry the full timestamp: {:?}",
            panel.chrome.texts(),
        );
    }

    /// The card's tag editor puts a name on the rev it shows.
    #[test]
    fn the_cards_tag_field_names_the_rev_it_shows() {
        let mut panel = recorded();
        let at = blockworx_doc::fixtures::rev(3);
        panel.viewing(Viewing::Past(at));
        panel.click_on("Add tag");
        panel.type_text("released");
        panel.press(egui::Key::Enter);
        assert!(
            matches!(
                &panel.session.fired,
                Some(Act::Edit(Action::TagRev { at: fired, name, how }))
                    if *fired == at && name == "released" && *how == Tagging::Added,
            ),
            "the tag field did not name the rev: {}",
            fired(&panel),
        );
    }

    /// The card takes a name back off, naming which one — the whole reason
    /// an untag is its own row kind now that a rev holds a set.
    #[test]
    fn the_cards_chip_takes_one_name_back_off() {
        let at = blockworx_doc::fixtures::rev(3);
        let mut tags = Tags::default();
        tags.add(at, "released");
        tags.add(at, "vendor");
        let mut panel = recorded_with(tags);
        panel.viewing(Viewing::Past(at));
        // The two chips each carry a remove button; the first is
        // "released", since a rev's names read alphabetically.
        let remove = panel
            .chrome
            .rects("\u{d7}")
            .first()
            .copied()
            .expect("the card drew no remove button");
        panel.click_at(remove.center().egui());
        assert!(
            matches!(
                &panel.session.fired,
                Some(Act::Edit(Action::TagRev { at: fired, name, how }))
                    if *fired == at && name == "released" && *how == Tagging::Removed,
            ),
            "the chip did not take its own name off: {}",
            fired(&panel),
        );
    }

    /// The panel opens on the rev the canvas is standing on, wherever that
    /// row has scrolled to — but it must not drag the list back every frame,
    /// or it could never be scrolled by hand.
    #[test]
    fn the_viewed_row_is_revealed_on_opening_and_on_moving_but_not_after() {
        let ctx = egui::Context::default();
        let at = Viewing::Past(blockworx_doc::fixtures::rev(2));
        let mut seen = Vec::new();
        let mut look = |viewing: Option<Viewing>| {
            ctx.clone()
                .run_ui(egui::RawInput::default(), |ui| {
                    if let Some(viewing) = viewing {
                        seen.push(reveal(ui.ctx(), viewing));
                    }
                })
                .drop_without_applying_deltas();
        };
        // Two consecutive passes at one rev, a third after the canvas moved,
        // then a gap (the panel closed) and one more.
        look(Some(at));
        look(Some(at));
        look(Some(Viewing::Head));
        look(None);
        look(Some(Viewing::Head));
        assert_eq!(
            seen,
            vec![
                Reveal::Now,
                Reveal::LeaveTheScroll,
                Reveal::Now,
                Reveal::Now
            ],
        );
    }

    /// The `Current` row is the way back, and it is the only thing in the
    /// list that offers one.
    #[test]
    fn the_current_row_returns_to_the_live_document() {
        let mut panel = recorded();
        panel.viewing(Viewing::Past(blockworx_doc::fixtures::rev(1)));
        panel.click_on("Current");
        assert!(
            matches!(panel.session.fired, Some(Act::Edit(Action::ViewHead))),
            "the Current row did not return to the present: {}",
            fired(&panel),
        );
    }

    /// Nothing in the list dispatches a return while the present is already
    /// on the canvas — there is nowhere to return from.
    #[test]
    fn nothing_returns_to_a_present_already_shown() {
        let mut panel = recorded();
        panel.click_on("Current");
        assert!(
            panel.session.fired.is_none(),
            "a return fired where the present is already shown: {}",
            fired(&panel),
        );
    }

    /// A click on a row puts that rev on the canvas; the head has no row of
    /// its own to click.
    #[test]
    fn clicking_a_row_visits_its_rev_and_the_head_has_no_row() {
        let mut panel = recorded();
        assert!(
            !panel.chrome.says("Added Register"),
            "the head still draws a row of its own: {:?}",
            panel.chrome.texts(),
        );
        panel.click_on("Added Mux");
        assert!(
            matches!(
                panel.session.fired,
                Some(Act::Edit(Action::ViewRev(at))) if at == blockworx_doc::fixtures::rev(3),
            ),
            "a click on r3's row did not visit r3: {}",
            fired(&panel),
        );
    }
}