blockworx_kernel/

chrome.rs

//! The chrome model: what a front end shows around the canvas, as values
//! the session builds and a [`View`](crate::View) carries.
//!
//! Every type here is owned and toolkit-free. The bar's words, the status
//! line's fields, the history's rows, the navigator's tree, the selection
//! bar's swatch and the notices are all facts about the session, so they
//! are read off it in one place each; what a widget adds — which panel is
//! open, where the pointer is over the chrome, a rename box's draft — stays
//! with the widget.

use std::borrow::Cow;

use blockworx_doc::{
    id::BlockId,
    rev::Rev,
    values::{PinDir, Role as AccentRole},
};
use blockworx_editor::{
    content_path,
    edit::lower::accent_from_role,
    path::{BlockPath, Scope, child_blocks, tree_root},
    shape::{ShapeId, ShapeRef},
    widget::drawing::Drawing,
};
use blockworx_geom::{Rect, grid::GridCell};
use blockworx_paint::{
    Color, Zoom,
    theme::{Role, accent_role},
};
use blockworx_store::{
    doc::{Attachment, Doc, Renaming, Viewing, Writability},
    history::Row,
    record::WallTime,
};
use blockworx_tools::{
    commands::{Act, CommandId, CommandSet, Effect},
    names::{ToolName, displayed_tool, instruction},
    tool::{RoleTarget, ToolTrait},
};

use crate::session::{Consequences, Session, viewed};

/// Everything the top bar says: the breadcrumb's root and its levels, the
/// undo and redo buttons' entries, the lens, and the liveness dot.
#[derive(Clone, Debug, PartialEq, serde::Serialize, serde::Deserialize)]
pub struct TopBar {
    /// What the document calls itself — the breadcrumb's root segment.
    pub name: String,
    pub scope: ScopePath,
    pub steps: Consequences,
    pub lens: Lens,
    pub liveness: Liveness,
    /// Whether the name can be typed over: only a container has a name to
    /// change.
    pub renaming: Renaming,
}

/// Where the canvas is standing: the levels that reach it, outermost first,
/// and the path that names them.
#[derive(Clone, Debug, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
pub struct ScopePath {
    pub path: BlockPath,
    pub names: Vec<String>,
}

/// Past this many levels the breadcrumb collapses from the middle.
const MAX_SEGMENTS: usize = 4;
/// How many levels above the current one survive the collapse.
const TAIL_SEGMENTS: usize = 2;

/// One thing a breadcrumb draws.
#[derive(Clone, PartialEq, Eq, Debug)]
pub enum Crumb {
    Root,
    /// A level, by how many levels down from the root it stands.
    Level(usize),
    /// The middle the collapse hid, by the same measure.
    Elided(Vec<usize>),
}

impl ScopePath {
    /// How many levels stand between the document and the canvas.
    pub fn here(&self) -> usize {
        self.names.len()
    }

    /// Which segments a breadcrumb of these levels actually draws.
    ///
    /// It collapses from the middle — the root and the level the canvas is
    /// standing on are never hidden. Past four levels the run between them
    /// goes behind one ellipsis that lists it.
    pub fn collapsed(&self) -> Vec<Crumb> {
        let here = self.here();
        let depths = 1..=here;
        if here < MAX_SEGMENTS {
            return std::iter::once(Crumb::Root)
                .chain(depths.map(Crumb::Level))
                .collect();
        }
        let tail = here.saturating_sub(TAIL_SEGMENTS - 1);
        vec![
            Crumb::Root,
            Crumb::Elided((1..tail).collect()),
            Crumb::Level(tail),
            Crumb::Level(here),
        ]
    }

    /// What a click on the segment standing `depth` levels down from the
    /// document asks for. The immediate parent is a rise; anything further
    /// out names the whole path, since going up twice would take two frames.
    pub fn up_to(&self, depth: usize) -> blockworx_tools::tool::Action {
        if depth + 1 == self.path.segments().len() {
            return blockworx_tools::tool::Action::GoUp;
        }
        let mut to = BlockPath::empty();
        for &id in &self.path.segments()[..depth] {
            to.push(id);
        }
        blockworx_tools::tool::Action::GoToPath(to)
    }
}

/// What the lens is showing, and what the bar says about it.
#[derive(Clone, Debug, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
pub struct Lens {
    pub viewing: Viewing,
    /// The newest rev in the log — the far end the stepper walks toward.
    pub head: Rev,
    /// How long ago the viewed rev was written, in words. Empty for a scratch
    /// session, which keeps no clock to measure against, and the bar then
    /// says nothing rather than guessing.
    pub age: String,
}

/// What the document's own state is, as the dot beside its name reports it.
///
/// The user's reading, adopted whole: *"I expect it to be green (all is
/// good), red (no editing allowed), and yellow (update to the disk
/// representation in flight). But I also get gray."* The grey is the fourth
/// state they had not been told about — a session with no file behind it —
/// which keeps its colour and gains its words.
#[derive(Clone, Copy, PartialEq, Eq, Debug, serde::Serialize, serde::Deserialize)]
pub enum Liveness {
    /// Everything the log holds is on disk.
    Recorded,
    /// Nothing may be written, for the reason it names.
    ReadOnly(Locked),
    /// No container at all: the log lives and dies with the process.
    Scratch,
}

/// Why a document may not be written.
#[derive(Clone, Copy, PartialEq, Eq, Debug, serde::Serialize, serde::Deserialize)]
pub enum Locked {
    /// A past rev is on the canvas.
    Lens,
    /// The container itself is read-only.
    Container,
}

impl Liveness {
    /// The one resolver, so the dot and the words under it cannot disagree
    /// — and neither can any other surface that comes to ask.
    ///
    /// The lens outranks everything: what is on the canvas cannot be edited,
    /// whatever stands behind it.
    ///
    /// A rev is written as it is committed, so an attached document this
    /// session may write is recorded by the time anyone asks. Where a host
    /// writes through a queue — the browser's journal — how much it still
    /// owes is the journal's own count, not this.
    pub fn of(viewing: Viewing, writability: Writability, attachment: Attachment) -> Self {
        if matches!(viewing, Viewing::Past(_)) {
            return Liveness::ReadOnly(Locked::Lens);
        }
        if writability == Writability::ReadOnly {
            return Liveness::ReadOnly(Locked::Container);
        }
        match attachment {
            Attachment::Scratch => Liveness::Scratch,
            Attachment::Attached => Liveness::Recorded,
        }
    }
}

/// Everything the status line could say, before its priority picks one.
#[derive(Clone, Debug, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
pub struct Reading {
    /// How to use the armed tool, while one is armed.
    pub tool: Option<Cow<'static, str>>,
    /// The path to what is selected, while something is.
    pub selection: Option<String>,
    pub zoom: Zoom,
    /// The grid cell under the pointer, while it is over the canvas.
    pub cursor: Option<GridCell>,
    pub title: TitleBlock,
}

/// The status line's second line: *"the text in the lower left corner
/// (let's consider that the title block) should also indicate on a second
/// line, the author, current rev, and date/time of that rev."*
///
/// The rev is the one **on the canvas**, not the one at the head of the log:
/// a title block describes the drawing being looked at, and under the lens
/// that is an earlier rev.
#[derive(Clone, PartialEq, Eq, Debug, serde::Serialize, serde::Deserialize)]
pub struct TitleBlock {
    /// Who this session attributes its work to.
    pub author: String,
    pub rev: Rev,
    /// When `rev` was written, as its own record stamped it. Empty for a
    /// scratch session, which keeps no records and so no clock — and the
    /// line then says nothing rather than guessing at one.
    pub written: String,
}

/// The navigator's tree: every block the document holds under its top,
/// nested as the document nests them, beside where the canvas is standing
/// and what is selected on it.
#[derive(Clone, Debug, PartialEq, Eq, Default, serde::Serialize, serde::Deserialize)]
pub struct NavTree {
    /// What the tree hangs from. The top block is never a row of its own —
    /// its children are the first rows — so a path from the document root
    /// passes through it by name here.
    pub hung: Hung,
    pub nodes: Vec<NavNode>,
    pub path: BlockPath,
    pub selected: Vec<BlockId>,
}

/// Where a tree hangs from: the document's own root, or its designated top.
#[derive(Clone, Debug, PartialEq, Eq, Default, serde::Serialize, serde::Deserialize)]
pub enum Hung {
    #[default]
    FromRoot,
    FromTop {
        id: BlockId,
        /// The top's name, as a content path spells it.
        name: String,
    },
}

impl Hung {
    pub fn scope(&self) -> Scope {
        match self {
            Hung::FromRoot => Scope::Root,
            Hung::FromTop { id, .. } => Scope::Block(*id),
        }
    }
}

/// One block as the tree lists it, with the blocks it holds beneath it in
/// the document's one draw order.
#[derive(Clone, Debug, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
pub struct NavNode {
    pub id: BlockId,
    /// The block's name as a content path spells it: its title, or its id
    /// where it has none.
    pub name: String,
    /// The block's display label: its name, then its type, joined with a
    /// slash.
    pub label: String,
    /// The block's own accent index, or `None` where it has taken none.
    pub accent: Option<u8>,
    pub children: Vec<NavNode>,
}

impl NavNode {
    /// Whether the tree hangs a disclosure triangle on this row — the same
    /// answer the canvas's double border and the PDF's page cut give.
    pub fn opens_a_scope(&self) -> bool {
        !self.children.is_empty()
    }

    /// How many leaves this subtree holds — what a closed branch prints so
    /// its size is legible without opening it. A leaf counts itself.
    pub fn leaves(&self) -> usize {
        if self.children.is_empty() {
            return 1;
        }
        self.children.iter().map(NavNode::leaves).sum()
    }
}

impl NavTree {
    /// The tree over `document`, under its top block: every block the
    /// document holds, nested as the document nests them.
    pub fn of(
        document: &blockworx_doc::document::IndexedDocument<'_>,
        path: BlockPath,
        selected: Vec<BlockId>,
    ) -> Self {
        fn nodes(
            document: &blockworx_doc::document::IndexedDocument<'_>,
            scope: Scope,
        ) -> Vec<NavNode> {
            child_blocks(document, scope)
                .into_iter()
                .map(|id| NavNode {
                    id,
                    name: content_path::name_of(document, id),
                    label: block_label(document, id),
                    accent: document
                        .doc
                        .block(&id)
                        .and_then(|block| accent_from_role(block.role)),
                    children: nodes(document, Scope::Block(id)),
                })
                .collect()
        }
        let root = tree_root(document);
        NavTree {
            hung: match root {
                Scope::Root => Hung::FromRoot,
                Scope::Block(id) => Hung::FromTop {
                    id,
                    name: content_path::name_of(document, id),
                },
            },
            nodes: nodes(document, root),
            path,
            selected,
        }
    }

    /// Resolve a path string back to a [`BlockPath`], matching names down
    /// from the document root — through the top, where one is designated —
    /// case-insensitively after trimming; the first sibling that matches
    /// wins. `None` if any name names nothing the tree holds.
    pub fn path_of(&self, text: &str) -> Option<BlockPath> {
        let mut names = text
            .split(content_path::SEPARATOR)
            .map(str::trim)
            .filter(|name| !name.is_empty())
            .peekable();
        let mut path = BlockPath::empty();
        if let Hung::FromTop { id, name } = &self.hung {
            let first = names.next()?;
            if !name.eq_ignore_ascii_case(first) {
                return None;
            }
            path.push(*id);
        }
        let mut level = self.nodes.as_slice();
        for name in names {
            let node = level
                .iter()
                .find(|node| node.name.eq_ignore_ascii_case(name))?;
            path.push(node.id);
            level = &node.children;
        }
        Some(path)
    }

    /// Every block the tree holds with its display label, depth first — the
    /// palette's search space for `find`.
    pub fn all_blocks(&self) -> Vec<(BlockId, String)> {
        self.walk()
            .map(|(node, _)| (node.id, node.label.clone()))
            .collect()
    }

    /// The blocks on the level the canvas is standing on, with their display
    /// labels — the palette's `expand <block>` targets, since only a direct
    /// child can be descended into.
    pub fn level_blocks(&self) -> Vec<(BlockId, String)> {
        self.children_of(self.path.scope())
            .iter()
            .map(|node| (node.id, node.label.clone()))
            .collect()
    }

    /// Every node, depth first, each with the ids of its ancestors between
    /// the tree's root and it, outermost first.
    pub fn walk(&self) -> impl Iterator<Item = (&NavNode, Vec<BlockId>)> {
        fn descend<'a>(
            nodes: &'a [NavNode],
            above: &mut Vec<BlockId>,
            out: &mut Vec<(&'a NavNode, Vec<BlockId>)>,
        ) {
            for node in nodes {
                out.push((node, above.clone()));
                above.push(node.id);
                descend(&node.children, above, out);
                above.pop();
            }
        }
        let mut out = Vec::new();
        descend(&self.nodes, &mut Vec::new(), &mut out);
        out.into_iter()
    }

    /// The node for `id`, wherever it is in the tree.
    pub fn node(&self, id: BlockId) -> Option<&NavNode> {
        self.walk().map(|(node, _)| node).find(|node| node.id == id)
    }

    /// The blocks a scope holds: the tree's own rows for [`Scope::Root`] —
    /// the root a walk over the tree hangs from — and for the scope the
    /// tree hangs from in the document, which names the same rows for a
    /// path standing inside the top; a node's children for a block within.
    pub fn children_of(&self, scope: Scope) -> &[NavNode] {
        if scope == Scope::Root || scope == self.hung.scope() {
            return &self.nodes;
        }
        match scope {
            Scope::Root => &[],
            Scope::Block(id) => self.node(id).map_or(&[], |node| node.children.as_slice()),
        }
    }
}

/// A block's display label: its name, then its type, joined as `name/type`,
/// skipping an empty type. The name falls back to the block's id (`b3`)
/// when unnamed, so the label is never empty — and so a block that has
/// left the document still names a row.
pub fn block_label(document: &blockworx_doc::document::IndexedDocument<'_>, id: BlockId) -> String {
    let Some(block) = document.doc.block(&id) else {
        return id.to_string();
    };
    let name = block.title.name.trim();
    let head = if name.is_empty() {
        id.to_string()
    } else {
        name.to_owned()
    };
    let kind = block.type_label.name.trim();
    if kind.is_empty() {
        head
    } else {
        format!("{head}/{kind}")
    }
}

/// The selection bar's contents: the selection it stands over, and the
/// readings of the document its controls and pickers show — the accent
/// swatch's colour, the accent index behind it, and the direction the I/O
/// toggle reports.
#[derive(Clone, Debug, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
pub struct Overlay {
    pub selection: Selection,
    /// The colour the accent swatch shows, where an accent command is
    /// offered: the selection's own accent, or its un-accented stroke.
    pub swatch: Option<Color>,
    /// The accent index the selection carries, where an accent command is
    /// offered — `None` for no accent, which the picker shows as the
    /// target's own un-accented stroke.
    pub accent: Option<u8>,
    /// The one direction every pin the I/O command stands over is facing,
    /// where one is offered and they agree.
    pub pin_dir: Option<PinDir>,
}

/// The selection the bar is drawn for: where it sits on screen, and how
/// many things it holds.
#[derive(Clone, Copy, Debug, PartialEq, serde::Serialize, serde::Deserialize)]
pub struct Selection {
    pub screen: Rect,
    pub count: usize,
}

// The overlay's own `PartialEq` is by value; `Rect` is floats, so `Eq` is
// not derivable and the overlay states it explicitly.
impl Eq for Selection {}

impl Overlay {
    /// The bar's contents for `selection`, read off the drawing the commands
    /// were offered against: the accent swatch's colour where an accent
    /// command is offered, and the I/O toggle's direction where one is.
    pub fn of(
        drawing: &Drawing<'_>,
        theme: &blockworx_paint::theme::Theme,
        selection: Selection,
        commands: &CommandSet,
    ) -> Self {
        // The drawn commands, the withheld ones included: the bar draws
        // those dead rather than leaving a hole, so the swatch still shows
        // its colour on a read-only canvas.
        let accent = commands
            .iter_drawn()
            .find_map(|cmd| match (cmd.id, &cmd.act) {
                (CommandId::Accent, Act::Effect(Effect::Accent(target))) => Some(*target),
                _ => None,
            });
        let pins = commands
            .iter_drawn()
            .find_map(|cmd| match (cmd.id, &cmd.act) {
                (CommandId::PinType, Act::Effect(Effect::PinType(pins))) => Some(pins.as_slice()),
                _ => None,
            });
        let current = accent.map(|target| (target, current_accent(drawing, target)));
        Overlay {
            selection,
            swatch: current
                .map(|(target, index)| theme.resolve(accent_display_role(target, index))),
            accent: current.and_then(|(_, index)| index),
            pin_dir: pins.and_then(|pins| shared_dir(drawing, pins)),
        }
    }
}

/// What the session has to tell the user about its document: why the canvas
/// is read-only, what will be overwritten by the next save, and the load
/// that did not work.
///
/// Two kinds, because they end differently. A standing fact stands until the
/// fact does — dismissing "read-only" would not make the container writable.
/// A failure happened once, so it carries an acknowledgement and is gone for
/// the rest of the session once it is given.
#[derive(Clone, Debug, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
pub enum Notice {
    /// A failure that happened once — a container that would not open, a file
    /// that would not be written.
    Failure(String),
    /// A standing fact about the document, true until it stops being true.
    Standing(String),
}

/// What this session has owned up to and the user has not yet acknowledged:
/// an error nobody can dismiss makes the editor unusable
/// (docs/ui-issues.md). Dropped with the document it was about.
#[derive(Default, Debug)]
pub struct Notices(Vec<String>);

impl Notices {
    /// What the startup could not do, already said where it happened — so it
    /// is seeded rather than reported.
    pub fn opening(failure: Option<String>) -> Self {
        Self(failure.into_iter().collect())
    }

    /// Say on the canvas — and on the console — that something did not work.
    /// It stands until the user acknowledges it, or until the document it was
    /// about is replaced.
    pub fn report(&mut self, failure: String) {
        tracing::error!("{failure}");
        self.0.push(failure);
    }

    /// Drop them all, because the document they were about has gone.
    pub fn forget(&mut self) {
        self.0.clear();
    }

    pub fn acknowledge(&mut self, Acknowledged(failure): Acknowledged) {
        if failure < self.0.len() {
            self.0.remove(failure);
        }
    }

    pub fn failures(&self) -> &[String] {
        &self.0
    }
}

/// The failure the user acknowledged, by its position among the failures.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub struct Acknowledged(pub usize);

impl Session {
    /// The top bar's words, read off the session once so the breadcrumb, the
    /// lens and the dot cannot disagree with the document.
    pub fn top_bar(&mut self) -> TopBar {
        let viewing = self.viewing();
        // The rev's own row, so the bar's age is the history panel's, read
        // the same way from the same rows.
        let age = match viewing {
            Viewing::Head => None,
            Viewing::Past(at) => self
                .history_rows()
                .iter()
                .find(|row| row.rev == at)
                .map(|row| row.since(blockworx_store::history::now())),
        };
        TopBar {
            name: self.sheet.name.clone(),
            scope: ScopePath {
                path: self.path.clone(),
                names: self.scope_names(),
            },
            steps: self.consequences(),
            lens: Lens {
                viewing,
                head: self.doc.repo().rev(),
                age: age.unwrap_or_default(),
            },
            liveness: Liveness::of(viewing, self.doc.writability(), self.doc.attachment()),
            renaming: self.doc.renaming(),
        }
    }

    /// The colours under the diagram: the canvas ground and the grid over
    /// it, resolved through the same palette the diagram is — so the
    /// read-only drain cannot reach one and miss the other.
    pub fn ground(&self) -> Ground {
        Ground {
            background: self.chrome_color(Role::CanvasBackground),
            grid: self.chrome_color(Role::GridLine),
        }
    }

    /// What a frame wrote, where the log moved from `stood`: the confirmation
    /// the status line shows. Read off the log rather than off what did it,
    /// so the confirmation and the history row word one edit the same way,
    /// and a frame that turned out to write nothing says nothing.
    pub fn landed(&self, stood: Rev) -> Option<String> {
        let now = self.doc.repo().rev();
        if now == stood {
            return None;
        }
        let take_back = self.doc.trail().next_undo();
        Some(match crate::session::step_label(&self.doc, take_back) {
            Some(label) => format!("{label} \u{2014} rev {}", now.get()),
            None => format!("Rev {}", now.get()),
        })
    }

    /// The document's history as its readers see it, oldest first.
    pub fn history_rows(&self) -> Vec<Row> {
        blockworx_store::history::rows(self.doc.journal(), self.doc.tags())
    }

    /// The tool the rail shows armed.
    pub fn displayed_tool(&self) -> ToolName {
        displayed_tool(self.tool.name())
    }

    /// Everything the status line could say this frame.
    pub fn reading(&mut self) -> Reading {
        let cursor = self
            .pointer_screen()
            .and(self.hovered_world())
            .map(GridCell::at);
        Reading {
            tool: instruction(self.displayed_tool()).map(Cow::Borrowed),
            selection: self.selection_path(),
            zoom: self.vantage().zoom,
            cursor,
            title: self.title_block(),
        }
    }

    /// What is selected, as a path — the ephemeral half of the status line,
    /// which is why it cannot live in the bar's own breadcrumb.
    ///
    /// One shape is named where the document names it; several are counted,
    /// since a list of names is not a path and would not fit on a line.
    fn selection_path(&mut self) -> Option<String> {
        let count = self.tool.selection().map_or(0, |sel| sel.count());
        if count == 0 {
            return None;
        }
        let named = (count == 1)
            .then(|| {
                let shape = self.tool.selection()?.shapes()?.into_iter().next()?;
                let title = self.drawing().shape(shape)?.title()?.name.to_owned();
                let mut path = self.scope_names();
                path.push(title);
                Some(path.join(&format!(" {SELECTION_SEPARATOR} ")))
            })
            .flatten();
        Some(named.unwrap_or_else(|| format!("{count} selected")))
    }

    /// The status line's title block: who this session attributes its work
    /// to, the rev **on the canvas**, and when that rev was written. Under
    /// the lens that is the rev being looked at, because a title block
    /// describes the drawing in front of the reader.
    fn title_block(&self) -> TitleBlock {
        let rev = self.viewed_repo().rev();
        TitleBlock {
            author: self.identity.name.clone(),
            rev,
            written: self
                .written_at(rev)
                .map(blockworx_store::history::written_at)
                .unwrap_or_default(),
        }
    }

    /// When `rev` was written, where this session keeps rows. A scratch
    /// session keeps none, and answers `None` rather than the wall clock —
    /// which would make two readings of one rev differ.
    pub fn written_at(&self, rev: Rev) -> Option<WallTime> {
        match &self.doc {
            Doc::Scratch { .. } => None,
            Doc::Attached { store, .. } => store.row(rev).map(|row| row.wall_time),
        }
    }

    /// The navigator's tree over the document on the canvas.
    pub fn nav_tree(&mut self) -> NavTree {
        let selected = self
            .tool
            .selection()
            .and_then(|d| d.shapes())
            .unwrap_or_default()
            .into_iter()
            .filter_map(ShapeId::block)
            .collect();
        let document = self
            .doc_index
            .view(viewed(&self.doc, self.time_machine.as_ref()).document());
        NavTree::of(&document, self.path.clone(), selected)
    }

    /// The selection bar's contents, for the selection whose on-screen
    /// bounds the canvas pass measured — `None` while nothing is selected.
    /// `commands` is the frame's registry: the swatch and the I/O toggle
    /// read the targets of the commands it offers.
    pub fn overlay(&mut self, bounds: Option<Rect>, commands: &CommandSet) -> Option<Overlay> {
        let count = self.tool.selection()?.count();
        let screen = bounds?;
        let Session {
            doc,
            time_machine,
            doc_index,
            presentation,
            gesture,
            path,
            theme,
            ..
        } = self;
        let document = viewed(doc, time_machine.as_ref()).document();
        let drawing = Drawing::new(doc_index.view(document), path, presentation, gesture);
        Some(Overlay::of(
            &drawing,
            theme,
            Selection { screen, count },
            commands,
        ))
    }

    /// What this session has to tell the user: its failures first, since a
    /// failure is news, then the standing facts about its files.
    pub fn notices(&self) -> Vec<Notice> {
        self.failures
            .failures()
            .iter()
            .map(|failure| Notice::Failure(failure.clone()))
            .chain(self.file_notices().into_iter().map(Notice::Standing))
            .collect()
    }

    /// The standing facts about the files under this document. A session
    /// with no container has none, so it has nothing to say.
    fn file_notices(&self) -> Vec<String> {
        let mut notices = Vec::new();
        if let Some(reason) = self.doc.read_only_reason() {
            notices.push(format!("Read-only \u{2014} {reason}"));
        }
        notices
    }
}

/// What separates the levels of a selection path in the status line — the
/// mockup's own `join(" / ")`.
const SELECTION_SEPARATOR: &str = "/";

/// The colours under the diagram.
#[derive(Clone, Copy, Debug, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
pub struct Ground {
    pub background: Color,
    pub grid: Color,
}

/// The accent index `target` carries now, or `None` when it has none.
fn current_accent(data: &Drawing<'_>, target: RoleTarget) -> Option<u8> {
    let accent = |role: AccentRole| accent_from_role(role);
    match target {
        RoleTarget::Block(rid) => data.block(rid).and_then(|b| accent(b.role)),
        RoleTarget::Port(pid) => match data.shape(ShapeId::Port(pid)) {
            Some(ShapeRef::Port(port)) => accent(port.pin.port_accent),
            _ => None,
        },
        RoleTarget::Route(rid) => data.auto_route(rid).and_then(|w| accent(w.route.role)),
        RoleTarget::Area(cid) => match data.shape(ShapeId::Area(cid)) {
            Some(ShapeRef::Area(area)) => accent(area.role),
            _ => None,
        },
        RoleTarget::Text(tid) => match data.shape(ShapeId::Text(tid)) {
            Some(ShapeRef::Text(text)) => accent(text.text.role),
            _ => None,
        },
    }
}

/// The [`Role`] the accent swatch displays for `target` given its current
/// accent index `current`: the mapped accent role, or — when unset — the
/// target's own un-accented stroke.
pub fn accent_display_role(target: RoleTarget, current: Option<u8>) -> Role {
    let default_role = match target {
        RoleTarget::Area(_) => Role::AreaStroke,
        RoleTarget::Text(_) => Role::TextBoxStroke,
        RoleTarget::Block(_) | RoleTarget::Port(_) | RoleTarget::Route(_) => Role::AccentDefault,
    };
    accent_role(current).unwrap_or(default_role)
}

/// The one direction every pin in `pins` is facing, or `None` where they
/// disagree or the selection has gone.
fn shared_dir(data: &Drawing<'_>, pins: &[blockworx_doc::id::PinId]) -> Option<PinDir> {
    let mut dirs = pins
        .iter()
        .map(|&pin| data.pin_on_shape(pin).map(|(_, pin)| pin.dir));
    let first = dirs.next()??;
    dirs.all(|dir| dir == Some(first)).then_some(first)
}

#[cfg(test)]
mod tests {
    use super::*;
    use blockworx_doc::fixtures::block_id;
    use blockworx_editor::widget::test_fixtures::{self as fx, Scene};
    use blockworx_geom::{Rect, pos2};

    fn levels_deep(levels: usize) -> ScopePath {
        let path = (1..=levels).fold(BlockPath::empty(), |mut path, at| {
            path.push(block_id(at as u32));
            path
        });
        ScopePath {
            names: (1..=levels).map(|at| format!("Level {at}")).collect(),
            path,
        }
    }

    /// The breadcrumb collapses from the middle: the root and the level the
    /// canvas is standing on are never hidden, and what falls out between
    /// them is exactly the middle.
    #[test]
    fn a_deep_path_collapses_from_the_middle_and_keeps_its_ends() {
        assert_eq!(
            levels_deep(2).collapsed(),
            vec![Crumb::Root, Crumb::Level(1), Crumb::Level(2)],
            "a path that fits was collapsed anyway",
        );
        let deep = levels_deep(5).collapsed();
        assert_eq!(
            deep,
            vec![
                Crumb::Root,
                Crumb::Elided(vec![1, 2, 3]),
                Crumb::Level(4),
                Crumb::Level(5),
            ],
        );
        assert_eq!(deep.first(), Some(&Crumb::Root), "the root was hidden");
        assert_eq!(
            deep.last(),
            Some(&Crumb::Level(5)),
            "the current level was hidden",
        );
    }

    /// The immediate parent is exactly what "go up a level" means, so it is
    /// dispatched as that rather than as a second spelling of the same move;
    /// anything further out names the whole path.
    #[test]
    fn a_click_on_the_parent_rises_and_a_click_further_out_names_the_path() {
        let scope = levels_deep(3);
        assert!(matches!(
            scope.up_to(2),
            blockworx_tools::tool::Action::GoUp
        ));
        let blockworx_tools::tool::Action::GoToPath(to) = scope.up_to(1) else {
            panic!("a jump past the parent is a whole path");
        };
        assert_eq!(to.segments(), &[block_id(1)]);
        let blockworx_tools::tool::Action::GoToPath(root) = scope.up_to(0) else {
            panic!("the document's own segment is the root");
        };
        assert!(root.segments().is_empty());
    }

    fn body() -> Rect {
        Rect::from_min_max(pos2(0.0, 0.0), pos2(60.0, 60.0))
    }

    /// `top → Thing 1 → Core`, returning the ids in path order.
    fn nested() -> (Scene, Vec<BlockId>) {
        let scene = Scene::new(vec![
            fx::block_in(1, Scope::Root, body()),
            fx::titled(1, "top"),
            fx::block_in(2, Scope::Block(block_id(1)), body()),
            fx::titled(2, "Thing 1"),
            fx::block_in(3, Scope::Block(block_id(2)), body()),
            fx::titled(3, "Core"),
        ]);
        (scene, vec![block_id(1), block_id(2), block_id(3)])
    }

    fn path_of(ids: &[BlockId]) -> BlockPath {
        let mut path = BlockPath::empty();
        for &id in ids {
            path.push(id);
        }
        path
    }

    fn tree_of(scene: &mut Scene) -> NavTree {
        NavTree::of(&scene.indexed(), BlockPath::empty(), Vec::new())
    }

    /// What the display shows round-trips back to the path it came from —
    /// the whole point of copying the string out.
    #[test]
    fn a_displayed_path_parses_back_to_itself() {
        let (mut scene, ids) = nested();
        let text = content_path::to_string(&scene.indexed(), &path_of(&ids));
        let tree = tree_of(&mut scene);
        let path = path_of(&ids);
        assert_eq!(tree.path_of(&text), Some(path.clone()));
        // Spacing and case are forgiven.
        assert_eq!(tree.path_of(" top / thing 1 / core "), Some(path));
        assert_eq!(tree.path_of("top"), Some(path_of(&ids[..1])));
        assert_eq!(tree.path_of("top/Thing 1/Nope"), None);
        assert_eq!(tree.path_of("Core"), None, "names resolve level by level");
    }

    /// An untitled block still names a level: its id stands in, so the
    /// string never has an empty segment to parse back.
    #[test]
    fn an_untitled_block_falls_back_to_its_id() {
        let id = block_id(1);
        let mut scene = Scene::new(vec![
            fx::block_in(1, Scope::Root, body()),
            fx::titled(1, ""),
        ]);
        let tree = tree_of(&mut scene);
        assert_eq!(tree.path_of(&id.to_string()), Some(path_of(&[id])));
    }

    /// A designated top is the tree's invisible root: a path passes through
    /// it by name, and the level under it is the tree's first rows.
    #[test]
    fn a_path_passes_through_the_designated_top() {
        let (mut scene, ids) = nested();
        scene.apply(vec![fx::top(1)]);
        let tree = tree_of(&mut scene);
        assert!(matches!(tree.hung, Hung::FromTop { .. }));
        assert_eq!(tree.path_of("top/Thing 1"), Some(path_of(&ids[..2])));
        assert_eq!(tree.path_of("Thing 1"), None, "the top is not skipped");
        assert_eq!(
            tree.children_of(Scope::Block(ids[0]))
                .iter()
                .map(|node| node.id)
                .collect::<Vec<_>>(),
            vec![ids[1]],
        );
    }
}