blockworx/edit/

naming.rs

//! The naming and flag family (`docs/op-emitter-playbook.md`, 10a/10b):
//! one- or two-register updates on an existing entity.

use blockworx_doc::{
    block_model::{
        AreaUpdate, BlockUpdate, Label, LabelUpdate, Pin, PinUpdate, RouteUpdate, TextUpdate,
    },
    commit::CommitBuilder,
    document::Document,
    geometry::{FracVal, GridRect, GridSize},
    id::{AreaId, BlockId, PinId, RouteId, RouteLabelId, TextId},
    opcode::{Crud, OpCodes},
    values::{LabelSide, PinDir},
};

use blockworx_store::doc::Writability;

use crate::edit::lock::MaterialPin;
use crate::edit::lower::role_from_accent;

/// What a title rename lands on — the two entities carrying a title label.
#[derive(Clone, Copy, Debug)]
pub enum TitleTarget {
    Block(BlockId),
    Area(AreaId),
}

/// Inventory row "Rename Title": a block's or area's title label gets a
/// new name.
pub fn rename_title(doc: &Document, target: TitleTarget, name: &str, builder: &mut CommitBuilder) {
    match target {
        TitleTarget::Block(id) => {
            let Some(live) = doc.block(&id) else {
                return;
            };
            if live.title.name == name {
                return;
            }
            builder.push(OpCodes::Block(
                id,
                Crud::Update(BlockUpdate::Title(LabelUpdate::Name(name.into()))),
            ));
        }
        TitleTarget::Area(id) => {
            let Some(live) = doc.area(&id) else {
                return;
            };
            if live.title.name == name {
                return;
            }
            builder.push(OpCodes::Area(
                id,
                Crud::Update(AreaUpdate::Title(LabelUpdate::Name(name.into()))),
            ));
        }
    }
}

/// What an accent pick lands on — the five accent-bearing entities. A
/// port's accent is its own register (`PortAccent`); the stub and port-pin
/// accents are derived state, never in the log.
#[derive(Clone, Copy, Debug)]
pub enum AccentTarget {
    Block(BlockId),
    Route(RouteId),
    Area(AreaId),
    Text(TextId),
    Port(PinId),
}

/// Inventory row "Set Accent": recolor a block, wire, area, text, or
/// port. `accent` is the picker's vocabulary (`None` = plain).
pub fn set_accent(
    doc: &Document,
    target: AccentTarget,
    accent: Option<u8>,
    builder: &mut CommitBuilder,
) {
    let role = role_from_accent(accent);
    match target {
        AccentTarget::Block(id) => {
            let Some(live) = doc.block(&id) else {
                return;
            };
            if live.role == role {
                return;
            }
            builder.push(OpCodes::Block(id, Crud::Update(BlockUpdate::Role(role))));
        }
        AccentTarget::Route(id) => {
            let Some(live) = doc.route(&id) else {
                return;
            };
            if live.role == role {
                return;
            }
            builder.push(OpCodes::Route(id, Crud::Update(RouteUpdate::Role(role))));
        }
        AccentTarget::Area(id) => {
            let Some(live) = doc.area(&id) else {
                return;
            };
            if live.role == role {
                return;
            }
            builder.push(OpCodes::Area(id, Crud::Update(AreaUpdate::Role(role))));
        }
        AccentTarget::Text(id) => {
            let Some(live) = doc.text(&id) else {
                return;
            };
            if live.role == role {
                return;
            }
            builder.push(OpCodes::Text(id, Crud::Update(TextUpdate::Role(role))));
        }
        AccentTarget::Port(id) => {
            let Some(live) = doc.pin(&id) else {
                return;
            };
            if live.port_accent == role {
                return;
            }
            builder.push(OpCodes::Pin(id, Crud::Update(PinUpdate::PortAccent(role))));
        }
    }
}

/// Inventory row "Rename Block Type": a block's type label gets a new name.
pub fn rename_type(doc: &Document, block: BlockId, name: &str, builder: &mut CommitBuilder) {
    let Some(live) = doc.block(&block) else {
        return;
    };
    if live.type_label.name == name {
        return;
    }
    builder.push(OpCodes::Block(
        block,
        Crud::Update(BlockUpdate::TypeLabel(LabelUpdate::Name(name.into()))),
    ));
}

/// The width, in grid cells, that fits a pin's labels — the gesture's text
/// measurement, which the emitter cannot make for itself.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub struct LabelFitWidth(u32);

impl LabelFitWidth {
    pub fn new(cells: u32) -> Self {
        Self(cells)
    }
}

impl From<LabelFitWidth> for u32 {
    fn from(width: LabelFitWidth) -> u32 {
        width.0
    }
}

/// The rename/retype rider: the port body grows to fit its labels and never
/// narrows, so a body the user widened keeps its width.
fn widened(pin: &Pin, fit: LabelFitWidth) -> Option<GridRect> {
    let rect = pin.rect;
    let fit = u32::from(fit);
    (fit > rect.size.w).then_some(GridRect {
        size: GridSize {
            w: fit,
            ..rect.size
        },
        ..rect
    })
}

/// Inventory row "Rename Pin": a pin's name, widening the port body to fit.
pub fn rename_pin(
    doc: &Document,
    target: MaterialPin,
    name: &str,
    fit: LabelFitWidth,
    builder: &mut CommitBuilder,
) {
    let pin = target.id();
    let Some(live) = doc.pin(&pin) else {
        return;
    };
    if live.name != name {
        builder.push(OpCodes::Pin(
            pin,
            Crud::Update(PinUpdate::Name(name.into())),
        ));
    }
    if let Some(rect) = widened(live, fit) {
        builder.push(OpCodes::Pin(pin, Crud::Update(PinUpdate::Rect(rect))));
    }
}

/// Inventory row "Set Pin Tag": a pin's location designator. Tags extend
/// outward over the stub, so there is no widening rider.
pub fn set_tag(doc: &Document, target: MaterialPin, tag: &str, builder: &mut CommitBuilder) {
    let pin = target.id();
    let Some(live) = doc.pin(&pin) else {
        return;
    };
    if live.tag == tag {
        return;
    }
    builder.push(OpCodes::Pin(pin, Crud::Update(PinUpdate::Tag(tag.into()))));
}

/// Inventory row "Retype Pin": a pin's type line, widening the port body to
/// fit.
pub fn retype_pin(
    doc: &Document,
    target: MaterialPin,
    type_name: &str,
    fit: LabelFitWidth,
    builder: &mut CommitBuilder,
) {
    let pin = target.id();
    let Some(live) = doc.pin(&pin) else {
        return;
    };
    if live.type_name != type_name {
        builder.push(OpCodes::Pin(
            pin,
            Crud::Update(PinUpdate::TypeName(type_name.into())),
        ));
    }
    if let Some(rect) = widened(live, fit) {
        builder.push(OpCodes::Pin(pin, Crud::Update(PinUpdate::Rect(rect))));
    }
}

/// `InOut` → Input → Output → `InOut`.
fn cycled(dir: PinDir) -> PinDir {
    match dir {
        PinDir::InOut => PinDir::Input,
        PinDir::Input => PinDir::Output,
        PinDir::Output => PinDir::InOut,
    }
}

/// Inventory row "Cycle Pin Direction": clicking the selected pin's stub
/// advances its signal direction.
pub fn cycle_dir(doc: &Document, target: MaterialPin, builder: &mut CommitBuilder) {
    let pin = target.id();
    let Some(live) = doc.pin(&pin) else {
        return;
    };
    builder.push(OpCodes::Pin(
        pin,
        Crud::Update(PinUpdate::Dir(cycled(live.dir))),
    ));
}

/// Inventory row "Set Pin Direction (bulk)": one direction across a pin
/// selection, leaving locked owners' interfaces frozen.
pub fn set_dirs(doc: &Document, pins: &[MaterialPin], dir: PinDir, builder: &mut CommitBuilder) {
    for target in pins {
        let id = target.id();
        let Some(live) = doc.pin(&id) else {
            continue;
        };
        if live.dir == dir {
            continue;
        }
        builder.push(OpCodes::Pin(id, Crud::Update(PinUpdate::Dir(dir))));
    }
}

/// Whether a pin draws its location tag — the parameter form of the pin's
/// `TagHidden` register.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum TagVisibility {
    Shown,
    Hidden,
}

impl TagVisibility {
    pub fn is_hidden(self) -> bool {
        self == TagVisibility::Hidden
    }
}

impl From<bool> for TagVisibility {
    fn from(hidden: bool) -> Self {
        if hidden {
            TagVisibility::Hidden
        } else {
            TagVisibility::Shown
        }
    }
}

/// Inventory row "Show/Hide Pin Tags": tag visibility across a pin
/// selection.
pub fn set_tag_visibility(
    doc: &Document,
    pins: &[PinId],
    visibility: TagVisibility,
    builder: &mut CommitBuilder,
) {
    let hidden = visibility.is_hidden();
    for id in pins {
        let Some(live) = doc.pin(id) else {
            continue;
        };
        if live.tag_hidden == hidden {
            continue;
        }
        builder.push(OpCodes::Pin(
            *id,
            Crud::Update(PinUpdate::TagHidden(hidden)),
        ));
    }
}

/// Whether a block's pin interface accepts edits — the parameter form of
/// the block's `Locked` register.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum InterfaceLock {
    Locked,
    Unlocked,
}

impl InterfaceLock {
    pub fn is_locked(self) -> bool {
        self == InterfaceLock::Locked
    }
}

impl From<bool> for InterfaceLock {
    fn from(locked: bool) -> Self {
        if locked {
            InterfaceLock::Locked
        } else {
            InterfaceLock::Unlocked
        }
    }
}

/// Whether the affordances that *add* something are offered: the faint
/// "Add name"/"Add type" prompts, the free-slot pin dots, the route-start
/// targets, a wire's waypoint handles and text anchors — and, with them,
/// the gestures those affordances begin.
///
/// One value for two questions that have always had the same answer. A
/// locked block already withheld its prompts because its interface is
/// frozen; a read-only session freezes everything, so it withholds them on
/// the same terms. Folding both here is what keeps the paint layer and the
/// gesture layer from disagreeing about whether a thing is editable.
#[derive(Clone, Copy, PartialEq, Eq, Debug)]
pub enum Authoring {
    Offered,
    Withheld,
}

impl Authoring {
    /// What a session of this [`Writability`] offers on a shape under this
    /// [`InterfaceLock`] — the whole rule, in one place.
    pub fn of(writability: Writability, lock: InterfaceLock) -> Self {
        match (writability, lock.is_locked()) {
            (Writability::Writable, false) => Authoring::Offered,
            _ => Authoring::Withheld,
        }
    }

    pub fn is_withheld(self) -> bool {
        self == Authoring::Withheld
    }
}

impl From<Writability> for Authoring {
    fn from(writability: Writability) -> Self {
        Authoring::of(writability, InterfaceLock::Unlocked)
    }
}

/// Inventory row "Lock/Unlock Block": freeze or thaw a block's pin
/// interface.
pub fn set_locked(
    doc: &Document,
    block: BlockId,
    lock: InterfaceLock,
    builder: &mut CommitBuilder,
) {
    let Some(live) = doc.block(&block) else {
        return;
    };
    let locked = lock.is_locked();
    if live.locked == locked {
        return;
    }
    builder.push(OpCodes::Block(
        block,
        Crud::Update(BlockUpdate::Locked(locked)),
    ));
}

/// Inventory row "Rename Route": name a wire. A blank name is the wire
/// label's deletion instead ([`clear_wire_label`]), never a name write.
pub fn rename_route(doc: &Document, route: RouteId, name: &str, builder: &mut CommitBuilder) {
    if name.trim().is_empty() {
        return;
    }
    let Some(live) = doc.route(&route) else {
        return;
    };
    if live.name == name {
        return;
    }
    builder.push(OpCodes::Route(
        route,
        Crud::Update(RouteUpdate::Name(name.into())),
    ));
}

/// What a label drag lands on — the three placeable labels.
#[derive(Clone, Copy, Debug)]
pub enum LabelTarget {
    BlockTitle(BlockId),
    BlockType(BlockId),
    AreaTitle(AreaId),
}

/// A committed label drag: the offset the gesture resolved, and the side
/// the release height chose, when it chose one.
#[derive(Clone, Copy, Debug)]
pub struct LabelPlacement {
    pub offset: FracVal,
    pub side: Option<LabelSide>,
}

/// The two placement registers filter independently: a drag along one side
/// writes no side, and a side change at the same offset writes no offset.
fn placement_updates(label: &Label, placement: LabelPlacement) -> Vec<LabelUpdate> {
    let mut updates = Vec::new();
    if label.offset != placement.offset {
        updates.push(LabelUpdate::Offset(placement.offset));
    }
    if let Some(side) = placement.side.filter(|side| *side != label.side) {
        updates.push(LabelUpdate::Side(side));
    }
    updates
}

/// Inventory row "Move Title / Type Label": reposition a block's or
/// area's title, or a block's type label.
pub fn place_label(
    doc: &Document,
    target: LabelTarget,
    placement: LabelPlacement,
    builder: &mut CommitBuilder,
) {
    match target {
        LabelTarget::BlockTitle(id) => {
            let Some(live) = doc.block(&id) else {
                return;
            };
            builder.extend(
                placement_updates(&live.title, placement)
                    .into_iter()
                    .map(|update| OpCodes::Block(id, Crud::Update(BlockUpdate::Title(update)))),
            );
        }
        LabelTarget::BlockType(id) => {
            let Some(live) = doc.block(&id) else {
                return;
            };
            builder.extend(
                placement_updates(&live.type_label, placement)
                    .into_iter()
                    .map(|update| OpCodes::Block(id, Crud::Update(BlockUpdate::TypeLabel(update)))),
            );
        }
        LabelTarget::AreaTitle(id) => {
            let Some(live) = doc.area(&id) else {
                return;
            };
            builder.extend(
                placement_updates(&live.title, placement)
                    .into_iter()
                    .map(|update| OpCodes::Area(id, Crud::Update(AreaUpdate::Title(update)))),
            );
        }
    }
}

/// Inventory rows "Edit Text Box" and "Delete Text Box (emptied)": a text
/// box commits its content, or is discarded when that content is blank
/// rather than left invisible.
pub fn edit_text(doc: &Document, text: TextId, content: &str, builder: &mut CommitBuilder) {
    let Some(live) = doc.text(&text) else {
        return;
    };
    if content.trim().is_empty() {
        builder.push(OpCodes::Text(text, Crud::Delete));
        return;
    }
    if live.text == content {
        return;
    }
    builder.push(OpCodes::Text(
        text,
        Crud::Update(TextUpdate::Text(content.into())),
    ));
}

/// Inventory row "Delete Wire Label (empty rename)": clearing a wire
/// label's text drops the label and unnames the wire it labelled.
pub fn clear_wire_label(doc: &Document, label: RouteLabelId, builder: &mut CommitBuilder) {
    let Some(live) = doc.route_label(&label) else {
        return;
    };
    let route = live.owner;
    builder.push(OpCodes::RouteLabel(label, Crud::Delete));
    if doc.route(&route).is_some_and(|r| !r.name.is_empty()) {
        builder.push(OpCodes::Route(
            route,
            Crud::Update(RouteUpdate::Name(String::new())),
        ));
    }
}

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

    /// The capability a material edit takes, for a test whose pin is
    /// unlocked. A locked one is `MaterialPin::of(...) == None`, which is
    /// the point of the type and is asserted where it matters.
    fn material(doc: &Document, n: u32) -> MaterialPin {
        MaterialPin::of(doc, pin_id(n)).expect("the pin's owner is unlocked")
    }
    use crate::edit::harness::{fold, route_label_create, seals_to_nothing, wired};
    use blockworx_doc::fixtures::{area_id, block_id, pin_id, route_id, route_label_id, text_id};
    use blockworx_doc::values::Role;

    #[test]
    fn rename_title_lands_on_a_block_and_an_area() {
        let doc = wired();
        assert_eq!(
            doc.block(&block_id(1)).unwrap().title.name,
            "b1",
            "precondition: the scene's block starts under its fixture name"
        );

        let mut builder = CommitBuilder::new("Renamed a block");
        rename_title(&doc, TitleTarget::Block(block_id(1)), "ALU", &mut builder);
        let doc = fold(builder, &doc);
        assert_eq!(doc.block(&block_id(1)).unwrap().title.name, "ALU");

        let mut builder = CommitBuilder::new("Renamed an area");
        rename_title(&doc, TitleTarget::Area(area_id(8)), "notes", &mut builder);
        let doc = fold(builder, &doc);
        assert_eq!(doc.area(&area_id(8)).unwrap().title.name, "notes");
    }

    #[test]
    fn renaming_to_the_same_name_seals_to_nothing() {
        let doc = wired();
        let mut builder = CommitBuilder::new("Renamed a block");
        rename_title(&doc, TitleTarget::Block(block_id(1)), "b1", &mut builder);
        seals_to_nothing(builder);
    }

    #[test]
    fn an_absent_target_pushes_nothing() {
        let doc = wired();
        let mut builder = CommitBuilder::new("Renamed a ghost");
        rename_title(&doc, TitleTarget::Block(block_id(99)), "x", &mut builder);
        seals_to_nothing(builder);
    }

    #[test]
    fn set_accent_recolors_every_target_kind() {
        let doc = wired();
        let mut builder = CommitBuilder::new("Recolored the scene");
        set_accent(
            &doc,
            AccentTarget::Block(block_id(1)),
            Some(0),
            &mut builder,
        );
        set_accent(
            &doc,
            AccentTarget::Route(route_id(5)),
            Some(3),
            &mut builder,
        );
        set_accent(&doc, AccentTarget::Port(pin_id(3)), Some(7), &mut builder);
        let doc = fold(builder, &doc);
        assert_eq!(doc.block(&block_id(1)).unwrap().role, Role::Accent1);
        assert_eq!(doc.route(&route_id(5)).unwrap().role, Role::Accent4);
        assert_eq!(doc.pin(&pin_id(3)).unwrap().port_accent, Role::Accent8);

        // Clearing back to plain is an edit; clearing an already-plain
        // element is not.
        let mut builder = CommitBuilder::new("Cleared an accent");
        set_accent(&doc, AccentTarget::Block(block_id(1)), None, &mut builder);
        let doc = fold(builder, &doc);
        assert_eq!(doc.block(&block_id(1)).unwrap().role, Role::Accent0);
        let mut builder = CommitBuilder::new("Cleared it again");
        set_accent(&doc, AccentTarget::Block(block_id(1)), None, &mut builder);
        seals_to_nothing(builder);
    }

    fn pin(doc: &Document, id: u32) -> &Pin {
        doc.pin(&pin_id(id)).expect("the scene's pin exists")
    }

    fn body_width(doc: &Document, id: u32) -> u32 {
        pin(doc, id).rect.size.w
    }

    /// The scene with its pins' owner frozen — the arm every material pin
    /// edit must decline.
    fn locked_scene() -> Document {
        let doc = wired();
        let mut builder = CommitBuilder::new("Locked a block");
        set_locked(&doc, block_id(1), InterfaceLock::Locked, &mut builder);
        let doc = fold(builder, &doc);
        assert!(
            doc.block(&block_id(1))
                .expect("the scene's block exists")
                .locked,
            "precondition: the owner is locked"
        );
        assert_eq!(
            pin(&doc, 3).owner,
            block_id(1),
            "precondition: pin 3 belongs to the locked block"
        );
        doc
    }

    #[test]
    fn rename_type_writes_the_type_label_and_leaves_the_title() {
        let doc = wired();
        assert_eq!(
            doc.block(&block_id(1))
                .expect("the scene's block exists")
                .type_label
                .name,
            "",
            "precondition: the scene's block carries no type label"
        );

        let mut builder = CommitBuilder::new("Retyped a block");
        rename_type(&doc, block_id(1), "ALU", &mut builder);
        let doc = fold(builder, &doc);
        let block = doc.block(&block_id(1)).expect("the scene's block exists");
        assert_eq!(block.type_label.name, "ALU");
        assert_eq!(block.title.name, "b1", "the twin label is untouched");

        let mut builder = CommitBuilder::new("Retyped it the same");
        rename_type(&doc, block_id(1), "ALU", &mut builder);
        seals_to_nothing(builder);
    }

    #[test]
    fn rename_pin_writes_the_name_and_widens_the_body() {
        let doc = wired();
        assert_eq!(
            body_width(&doc, 3),
            0,
            "precondition: the fixture pin's body starts unsized"
        );

        let mut builder = CommitBuilder::new("Renamed a pin");
        rename_pin(
            &doc,
            material(&doc, 3),
            "clk",
            LabelFitWidth::new(5),
            &mut builder,
        );
        let doc = fold(builder, &doc);
        assert_eq!(pin(&doc, 3).name, "clk");
        assert_eq!(body_width(&doc, 3), 5);

        let mut builder = CommitBuilder::new("Renamed it shorter");
        rename_pin(
            &doc,
            material(&doc, 3),
            "d0",
            LabelFitWidth::new(3),
            &mut builder,
        );
        let doc = fold(builder, &doc);
        assert_eq!(pin(&doc, 3).name, "d0");
        assert_eq!(body_width(&doc, 3), 5, "a widened body is never narrowed");

        // The two registers filter independently: the same name still
        // widens.
        let mut builder = CommitBuilder::new("Remeasured the same name");
        rename_pin(
            &doc,
            material(&doc, 3),
            "d0",
            LabelFitWidth::new(7),
            &mut builder,
        );
        let doc = fold(builder, &doc);
        assert_eq!(pin(&doc, 3).name, "d0");
        assert_eq!(body_width(&doc, 3), 7);

        let mut builder = CommitBuilder::new("Renamed it to itself");
        rename_pin(
            &doc,
            material(&doc, 3),
            "d0",
            LabelFitWidth::new(7),
            &mut builder,
        );
        seals_to_nothing(builder);
    }

    #[test]
    fn retype_pin_writes_the_type_line_and_widens_the_body() {
        let doc = wired();
        assert_eq!(
            pin(&doc, 3).type_name,
            "",
            "precondition: the fixture pin carries no type line"
        );

        let mut builder = CommitBuilder::new("Retyped a pin");
        retype_pin(
            &doc,
            material(&doc, 3),
            "clock",
            LabelFitWidth::new(6),
            &mut builder,
        );
        let doc = fold(builder, &doc);
        assert_eq!(pin(&doc, 3).type_name, "clock");
        assert_eq!(body_width(&doc, 3), 6);

        let mut builder = CommitBuilder::new("Retyped it the same");
        retype_pin(
            &doc,
            material(&doc, 3),
            "clock",
            LabelFitWidth::new(6),
            &mut builder,
        );
        seals_to_nothing(builder);
    }

    #[test]
    fn set_tag_writes_the_location_designator() {
        let doc = wired();
        assert_eq!(
            pin(&doc, 3).tag,
            "",
            "precondition: the fixture pin is untagged"
        );

        let mut builder = CommitBuilder::new("Tagged a pin");
        set_tag(&doc, material(&doc, 3), "U3", &mut builder);
        let doc = fold(builder, &doc);
        assert_eq!(pin(&doc, 3).tag, "U3");
        assert_eq!(
            body_width(&doc, 3),
            0,
            "tags extend over the stub, so the body is not widened"
        );

        let mut builder = CommitBuilder::new("Tagged it the same");
        set_tag(&doc, material(&doc, 3), "U3", &mut builder);
        seals_to_nothing(builder);
    }

    /// A locked owner freezes its interface by refusing the capability, so a
    /// material emitter cannot be *called* against its pins rather than
    /// declining inside: a new emitter that forgot the check does not compile.
    #[test]
    fn a_locked_owner_refuses_the_capability_material_edits_need() {
        let doc = locked_scene();
        for n in [3u32, 4] {
            assert_eq!(
                MaterialPin::of(&doc, pin_id(n)),
                None,
                "pin {n} belongs to a locked block, so no material edit can name it",
            );
        }
        assert!(
            MaterialPin::all(&doc, &[pin_id(3), pin_id(4)]).is_empty(),
            "and a group of them is an empty set, not a refused edit",
        );

        // The bulk emitter, handed that empty set, writes nothing — the only
        // shape in which a material emitter still sees a locked pin at all.
        let mut builder = CommitBuilder::new("Redirected frozen pins");
        set_dirs(
            &doc,
            &MaterialPin::all(&doc, &[pin_id(3), pin_id(4)]),
            PinDir::Output,
            &mut builder,
        );
        seals_to_nothing(builder);
    }

    /// The other half of the same rule: a lock says nothing about
    /// presentation, so hiding a locked block's tags goes through. The
    /// emitter takes plain ids and is offered no capability, which is how the
    /// signature says so.
    #[test]
    fn a_locked_owner_still_takes_presentation_edits() {
        let doc = locked_scene();
        let mut builder = CommitBuilder::new("Hid a frozen block's tags");
        set_tag_visibility(
            &doc,
            &[pin_id(3), pin_id(4)],
            TagVisibility::Hidden,
            &mut builder,
        );
        assert!(
            builder.seal().is_some(),
            "tag visibility is presentation, and a lock does not reach it",
        );
    }

    #[test]
    fn cycle_dir_visits_every_direction_and_returns() {
        let mut doc = wired();
        assert_eq!(
            pin(&doc, 3).dir,
            PinDir::Input,
            "precondition: the fixture pin starts at the zero direction"
        );

        for expected in [PinDir::Output, PinDir::InOut, PinDir::Input] {
            let mut builder = CommitBuilder::new("Cycled a pin");
            cycle_dir(&doc, material(&doc, 3), &mut builder);
            doc = fold(builder, &doc);
            assert_eq!(pin(&doc, 3).dir, expected);
        }
    }

    /// A pin the document does not hold has no capability to hand out, so
    /// the emitter is unreachable rather than merely uneventful.
    #[test]
    fn an_absent_pin_has_no_capability_to_cycle() {
        let doc = wired();
        assert_eq!(MaterialPin::of(&doc, pin_id(99)), None);
    }

    #[test]
    fn set_dirs_writes_the_group_and_skips_the_pins_already_facing_that_way() {
        let doc = wired();
        assert_eq!(
            pin(&doc, 4).dir,
            PinDir::Input,
            "precondition: both scene pins start at the zero direction"
        );

        let mut builder = CommitBuilder::new("Redirected a group");
        set_dirs(
            &doc,
            &MaterialPin::all(&doc, &[pin_id(3), pin_id(4)]),
            PinDir::Output,
            &mut builder,
        );
        let doc = fold(builder, &doc);
        assert_eq!(pin(&doc, 3).dir, PinDir::Output);
        assert_eq!(pin(&doc, 4).dir, PinDir::Output);

        let mut builder = CommitBuilder::new("Redirected them again");
        set_dirs(
            &doc,
            &MaterialPin::all(&doc, &[pin_id(3), pin_id(4)]),
            PinDir::Output,
            &mut builder,
        );
        seals_to_nothing(builder);
    }

    #[test]
    fn set_tag_visibility_hides_a_group_and_a_locked_owner_does_not_stop_it() {
        let doc = locked_scene();
        assert!(
            !pin(&doc, 3).tag_hidden,
            "precondition: the fixture pins draw their tags"
        );

        let mut builder = CommitBuilder::new("Hid the tags");
        set_tag_visibility(
            &doc,
            &[pin_id(3), pin_id(4)],
            TagVisibility::Hidden,
            &mut builder,
        );
        let doc = fold(builder, &doc);
        assert!(pin(&doc, 3).tag_hidden);
        assert!(pin(&doc, 4).tag_hidden);

        let mut builder = CommitBuilder::new("Hid them again");
        set_tag_visibility(
            &doc,
            &[pin_id(3), pin_id(4)],
            TagVisibility::Hidden,
            &mut builder,
        );
        seals_to_nothing(builder);

        let mut builder = CommitBuilder::new("Showed the tags");
        set_tag_visibility(&doc, &[pin_id(3)], TagVisibility::Shown, &mut builder);
        let doc = fold(builder, &doc);
        assert!(!pin(&doc, 3).tag_hidden);
        assert!(
            pin(&doc, 4).tag_hidden,
            "the pin outside the group is untouched"
        );
    }

    #[test]
    fn set_locked_flips_the_flag_once() {
        let doc = locked_scene();

        let mut builder = CommitBuilder::new("Locked it again");
        set_locked(&doc, block_id(1), InterfaceLock::Locked, &mut builder);
        seals_to_nothing(builder);

        let mut builder = CommitBuilder::new("Unlocked the block");
        set_locked(&doc, block_id(1), InterfaceLock::Unlocked, &mut builder);
        let doc = fold(builder, &doc);
        assert!(
            !doc.block(&block_id(1))
                .expect("the scene's block exists")
                .locked
        );

        let mut builder = CommitBuilder::new("Renamed a thawed pin");
        rename_pin(
            &doc,
            material(&doc, 3),
            "clk",
            LabelFitWidth::new(5),
            &mut builder,
        );
        let doc = fold(builder, &doc);
        assert_eq!(
            pin(&doc, 3).name,
            "clk",
            "thawing restores the pin interface"
        );
    }

    #[test]
    fn rename_route_writes_only_a_non_empty_name() {
        let doc = wired();
        assert_eq!(
            doc.route(&route_id(5))
                .expect("the scene's route exists")
                .name,
            "r5",
            "precondition: the scene's wire starts under its fixture name"
        );

        let mut builder = CommitBuilder::new("Named a wire");
        rename_route(&doc, route_id(5), "clk_net", &mut builder);
        let doc = fold(builder, &doc);
        assert_eq!(
            doc.route(&route_id(5))
                .expect("the scene's route exists")
                .name,
            "clk_net"
        );

        for blank in ["", "   "] {
            let mut builder = CommitBuilder::new("Blanked a wire name");
            rename_route(&doc, route_id(5), blank, &mut builder);
            seals_to_nothing(builder);
        }

        let mut builder = CommitBuilder::new("Named it the same");
        rename_route(&doc, route_id(5), "clk_net", &mut builder);
        seals_to_nothing(builder);
    }

    #[test]
    fn place_label_repositions_all_three_labels() {
        let doc = wired();
        let placement = LabelPlacement {
            offset: FracVal::from(2.5),
            side: Some(LabelSide::Bottom),
        };
        assert_eq!(
            doc.block(&block_id(1))
                .expect("the scene's block exists")
                .title
                .side,
            LabelSide::Top,
            "precondition: labels start at the zero placement"
        );

        let mut builder = CommitBuilder::new("Placed the labels");
        place_label(
            &doc,
            LabelTarget::BlockTitle(block_id(1)),
            placement,
            &mut builder,
        );
        place_label(
            &doc,
            LabelTarget::BlockType(block_id(1)),
            placement,
            &mut builder,
        );
        place_label(
            &doc,
            LabelTarget::AreaTitle(area_id(8)),
            placement,
            &mut builder,
        );
        let doc = fold(builder, &doc);

        let block = doc.block(&block_id(1)).expect("the scene's block exists");
        for label in [&block.title, &block.type_label] {
            assert_eq!(label.offset, FracVal::from(2.5));
            assert_eq!(label.side, LabelSide::Bottom);
        }
        let area_title = &doc
            .area(&area_id(8))
            .expect("the scene's area exists")
            .title;
        assert_eq!(area_title.offset, FracVal::from(2.5));
        assert_eq!(area_title.side, LabelSide::Bottom);

        let mut builder = CommitBuilder::new("Placed it where it already was");
        place_label(
            &doc,
            LabelTarget::BlockTitle(block_id(1)),
            placement,
            &mut builder,
        );
        seals_to_nothing(builder);
    }

    #[test]
    fn a_placement_writes_only_the_register_that_moved() {
        let doc = wired();

        let mut builder = CommitBuilder::new("Slid a title along its side");
        place_label(
            &doc,
            LabelTarget::BlockTitle(block_id(1)),
            LabelPlacement {
                offset: FracVal::from(1.0),
                side: None,
            },
            &mut builder,
        );
        let doc = fold(builder, &doc);
        let title = &doc
            .block(&block_id(1))
            .expect("the scene's block exists")
            .title;
        assert_eq!(title.offset, FracVal::from(1.0));
        assert_eq!(
            title.side,
            LabelSide::Top,
            "a drag that chose no side leaves the side alone"
        );

        let mut builder = CommitBuilder::new("Dropped it on another side");
        place_label(
            &doc,
            LabelTarget::BlockTitle(block_id(1)),
            LabelPlacement {
                offset: FracVal::from(1.0),
                side: Some(LabelSide::Center),
            },
            &mut builder,
        );
        let commit = builder.seal().expect("the side moved");
        assert_eq!(
            commit.ops().len(),
            1,
            "an unmoved offset takes no write of its own"
        );
        let doc = doc
            .try_apply(&commit)
            .expect("the fold accepts the gesture");
        assert_eq!(
            doc.block(&block_id(1))
                .expect("the scene's block exists")
                .title
                .side,
            LabelSide::Center
        );
    }

    #[test]
    fn edit_text_writes_content_and_discards_an_emptied_box() {
        let doc = wired();
        assert!(
            doc.text(&text_id(7)).is_some(),
            "precondition: the scene holds the text box"
        );

        let mut builder = CommitBuilder::new("Edited a text box");
        edit_text(&doc, text_id(7), "two\nlines", &mut builder);
        let doc = fold(builder, &doc);
        assert_eq!(
            doc.text(&text_id(7)).expect("the scene's text exists").text,
            "two\nlines"
        );

        let mut builder = CommitBuilder::new("Edited it to the same content");
        edit_text(&doc, text_id(7), "two\nlines", &mut builder);
        seals_to_nothing(builder);

        let mut builder = CommitBuilder::new("Emptied a text box");
        edit_text(&doc, text_id(7), "  \n ", &mut builder);
        let doc = fold(builder, &doc);
        assert!(
            doc.text(&text_id(7)).is_none(),
            "an emptied box is discarded, not left invisible"
        );

        let mut builder = CommitBuilder::new("Emptied it again");
        edit_text(&doc, text_id(7), "", &mut builder);
        seals_to_nothing(builder);
    }

    #[test]
    fn clearing_a_wire_label_deletes_it_and_unnames_the_wire() {
        let doc = wired();
        let mut builder = CommitBuilder::new("Labelled a wire");
        builder.push(route_label_create(6, 5));
        builder.push(route_label_create(9, 5));
        let doc = fold(builder, &doc);
        assert_eq!(
            doc.route_label(&route_label_id(6))
                .expect("the label exists")
                .owner,
            route_id(5),
            "precondition: the label belongs to the scene's named wire"
        );

        let mut builder = CommitBuilder::new("Cleared a wire label");
        clear_wire_label(&doc, route_label_id(6), &mut builder);
        let doc = fold(builder, &doc);
        assert!(doc.route_label(&route_label_id(6)).is_none());
        assert_eq!(
            doc.route(&route_id(5))
                .expect("the scene's route exists")
                .name,
            "",
            "the wire goes back to unlabelled rather than carrying a blank slot"
        );

        let mut builder = CommitBuilder::new("Cleared the second label");
        clear_wire_label(&doc, route_label_id(9), &mut builder);
        let commit = builder.seal().expect("the label is deleted");
        assert_eq!(
            commit.ops().len(),
            1,
            "an already-unnamed wire takes no name write"
        );

        let doc = doc
            .try_apply(&commit)
            .expect("the fold accepts the gesture");
        let mut builder = CommitBuilder::new("Cleared a ghost label");
        clear_wire_label(&doc, route_label_id(9), &mut builder);
        seals_to_nothing(builder);
    }
}