blockworx/tools/

title_block.rs

//! The drawing's title block: what a printed sheet states about the drawing
//! it carries, and how that statement is arranged.
//!
//! It says what a reader needs in order to know what they are looking at: what
//! the document is, which revision, who wrote it and when, and which level of
//! it is on the sheet.
//!
//! This is **content, not chrome** (spec §8): the block belongs to the sheet,
//! inside the drawing border, because it prints. The editor used to paint one
//! in the canvas's lower-right corner as well; that copy dissolved into the
//! frame (playbook R2) — the name reads in the document bar, the path in the
//! status strip's breadcrumb, and the rev, author and date in the history
//! panel's own rows. The canvas is clear (invariant 1).

use blockworx_doc::rev::Rev;

use blockworx_store::projection::Provenance;

use crate::{theme::Theme, tools::content_path};

/// What a title block states about a drawing. The strings are owned: the
/// session hands the block a stamp rather than a borrow of itself, so the same
/// stamp can be built where the document index is borrowed — and asked for by
/// a test, or carried into an export.
pub struct TitleBlock {
    /// What the document calls itself — the name in the window title, and the
    /// one the printed sheet's block carries.
    pub name: String,
    /// The name this session's commits are attributed to.
    pub author: String,
    /// The revision on the canvas — the current one, or the one the time
    /// machine is showing.
    pub rev: Rev,
    /// The date [`Self::rev`] was written, read off the log rather than off a
    /// clock, so an export of a rev says the same thing every time it is
    /// taken. `None` for a scratch session, whose log carries no wall times —
    /// and then the block simply has no Date row.
    pub date: Option<String>,
    /// Where this session's document came from, when it was opened from an
    /// export rather than authored here (D19). Advisory and session-only: it
    /// is never written into the log.
    pub from: Option<Provenance>,
}

/// What a cell's value is worth, for the painter that has to color it: the
/// document's own name is the one line a sheet sets apart from the rest.
#[derive(Clone, Copy, PartialEq, Eq, Debug)]
pub enum Emphasis {
    Title,
    Body,
}

/// What a cell says. A path is kept as its segments rather than as the joined
/// string because the printed sheet links each ancestor segment to that
/// ancestor's page, which means knowing where one name ends and the next
/// begins.
#[derive(Clone, PartialEq, Eq, Debug)]
pub enum Value {
    Text(String),
    Path(Vec<String>),
}

impl Value {
    /// The value as one run of text — what both painters set.
    pub fn text(&self) -> String {
        match self {
            Value::Text(text) => text.clone(),
            Value::Path(segments) => content_path::join(segments),
        }
    }
}

/// One cell of the block: its caption, what it says, how it is set, and what
/// it has no room for.
#[derive(Clone, PartialEq, Eq, Debug)]
pub struct Cell {
    pub caption: &'static str,
    pub value: Value,
    pub emphasis: Emphasis,
}

impl Cell {
    fn new(caption: &'static str, text: String) -> Cell {
        Cell {
            caption,
            value: Value::Text(text),
            emphasis: Emphasis::Body,
        }
    }
}

/// The block's arrangement: an ECAD-style two-column head — what the drawing
/// *is* on the left, which revision of it on the right — over lines wide
/// enough for a path to run across without squeezing the head.
///
/// A column is a list, so a column with nothing more to say simply ends; a
/// hole in the middle of one is not representable.
#[derive(Clone, PartialEq, Eq, Debug)]
pub struct Grid {
    pub left: Vec<Cell>,
    pub right: Vec<Cell>,
    pub wide: Vec<Cell>,
}

impl Grid {
    /// How many lines the head takes.
    pub fn head_rows(&self) -> usize {
        self.left.len().max(self.right.len())
    }

    /// Every cell in reading order — the whole of what the block says, for a
    /// reader that does not care which column it was in.
    #[cfg_attr(not(test), allow(dead_code))]
    pub fn cells(&self) -> impl Iterator<Item = &Cell> {
        (0..self.head_rows())
            .flat_map(|row| [self.left.get(row), self.right.get(row)])
            .flatten()
            .chain(self.wide.iter())
    }
}

impl TitleBlock {
    /// The block's cells for the level at `path`, named outermost first (see
    /// [`content_path::segments`]). The document root names no level, so an
    /// empty path draws no Path line rather than an empty one.
    pub fn grid(&self, path: &[String]) -> Grid {
        let mut right = vec![Cell::new(REV_CAPTION, self.rev.get().to_string())];
        if let Some(date) = &self.date {
            right.push(Cell::new("Date:", date.clone()));
        }
        let mut wide = Vec::new();
        if !path.is_empty() {
            wide.push(Cell {
                caption: "Path:",
                value: Value::Path(path.to_vec()),
                emphasis: Emphasis::Body,
            });
        }
        if let Some(from) = &self.from {
            wide.push(Cell {
                caption: "From:",
                value: Value::Text(from.line()),
                emphasis: Emphasis::Body,
            });
        }
        Grid {
            left: vec![
                Cell {
                    caption: "Diagram:",
                    value: Value::Text(self.name.clone()),
                    emphasis: Emphasis::Title,
                },
                Cell::new("Author:", self.author.clone()),
            ],
            right,
            wide,
        }
    }
}

/// The one size the block sets everything in, captions and values alike: the
/// canvas's own block-title size, so the block reads as part of the drawing
/// rather than as chrome bolted beside it. The printed sheet takes the same
/// size at the document scale.
pub fn text_size(theme: &Theme) -> f32 {
    theme.font_sizes().title
}

/// The cell the rev is stated in.
const REV_CAPTION: &str = "Rev:";

#[cfg(test)]
mod tests {
    use super::*;
    use blockworx_doc::fixtures::rev;

    pub(crate) fn block(rev: Rev) -> TitleBlock {
        TitleBlock {
            name: "motor-controller".to_owned(),
            author: "ada".to_owned(),
            rev,
            date: Some("2026-08-30".to_owned()),
            from: None,
        }
    }

    /// The path `drawn` shows, as its own segments.
    pub(crate) fn path_names() -> Vec<String> {
        ["top", "Thing 1", "Core"]
            .map(str::to_owned)
            .into_iter()
            .collect()
    }

    fn cell(caption: &'static str, text: &str) -> Cell {
        Cell::new(caption, text.to_owned())
    }

    /// The whole of what a title block says, and how it is arranged: what the
    /// drawing *is* down the left, which revision of it down the right, the
    /// level it shows across the bottom. Both painters are handed this — the
    /// two used to be written separately, and said different things.
    #[test]
    fn the_grid_names_the_document_its_revision_and_the_level_drawn() {
        assert_eq!(
            block(rev(41)).grid(&path_names()),
            Grid {
                left: vec![
                    Cell {
                        caption: "Diagram:",
                        value: Value::Text("motor-controller".to_owned()),
                        emphasis: Emphasis::Title,
                    },
                    cell("Author:", "ada"),
                ],
                right: vec![cell(REV_CAPTION, "41"), cell("Date:", "2026-08-30")],
                wide: vec![Cell {
                    caption: "Path:",
                    value: Value::Path(path_names()),
                    emphasis: Emphasis::Body,
                }],
            },
        );
    }

    /// A scratch session's log carries no wall times, so there is no date to
    /// state — and the layout simply has one line fewer rather than a row
    /// saying nothing. The document root names no level, and draws no Path.
    #[test]
    fn a_missing_date_and_an_empty_path_take_their_lines_with_them() {
        let mut block = block(rev(3));
        block.date = None;
        let grid = block.grid(&[]);
        assert_eq!(grid.right.len(), 1, "{:?}", grid.right);
        assert_eq!(grid.right[0].caption, REV_CAPTION);
        assert!(grid.wide.is_empty(), "{:?}", grid.wide);
        assert_eq!(
            grid.head_rows(),
            2,
            "the head is as tall as its longer column",
        );
    }

    /// D19: a session opened from an export says so, in the spelling the
    /// decision spells.
    #[test]
    fn a_document_opened_from_an_export_names_where_it_came_from() {
        let mut block = block(rev(1));
        block.from = Some(Provenance {
            document: "motor-controller".to_owned(),
            rev: rev(23),
            author: "ada".to_owned(),
            tags: vec!["Initial Draft".to_owned()],
        });
        let grid = block.grid(&path_names());
        let from = grid.wide.last().expect("the block has wide lines");
        assert_eq!(from.caption, "From:");
        assert_eq!(from.value.text(), "Rev 23 of motor-controller");
        assert_eq!(
            grid.right[0].value.text(),
            "1",
            "the Rev cell still names the rev on the canvas, not the source's",
        );
    }
}