blockworx/edit/

lock.rs

//! What a block's lock protects, as a capability rather than a check.
//!
//! A locked block freezes its **interface**: which pins exist, what signal
//! each carries, what each is called. It does not freeze **presentation**:
//! where a pin sits on the edge, which way the block's pins face, whether a
//! tag is shown. The split is by what the edit *means*, not by what it
//! touches — moving a pin from slot 2 to slot 5 changes a drawing, changing
//! it from Input to Output changes a definition.
//!
//! | Material — a lock refuses | Presentation — a lock allows |
//! |---|---|
//! | add a pin, add a port | move a pin to another slot or edge |
//! | delete a pin or port | nudge or relocate a pin group |
//! | set the I/O direction | flip pins left/right or top/bottom |
//! | rename a pin | show or hide a tag |
//! | edit a pin's type line | recolor, resize, retitle the block |
//! | edit a pin's tag text | move or delete the whole block |
//!
//! Stated as types because a rule spread across call sites is a rule that
//! drifts, and this one had: the guard reached the presentation edits it
//! should have left alone, and missed `cycle_dir`, the one edit that most
//! obviously changes a pin's meaning. Both errors were invisible because
//! each site decided for itself.
//!
//! Now a material emitter takes a proof and there is no other way to name
//! its target, so the rule is checked where it is minted and nowhere else.
//! A presentation emitter takes a plain id and is offered no proof, which is
//! how the table above reads in the signatures.

use blockworx_doc::{
    document::{Document, IndexedDocument},
    id::PinId,
};

use crate::path::{Resolved, Scope, resolve};

/// A pin whose owner accepts material edits to its interface.
///
/// Minted only by [`MaterialPin::of`], so every emitter that changes what a
/// pin *is* asks the same question of the same rule.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub struct MaterialPin(PinId);

impl MaterialPin {
    /// `None` for a pin the document does not hold, or one whose owning
    /// block is locked.
    pub fn of(doc: &Document, pin: PinId) -> Option<Self> {
        let live = doc.pin(&pin)?;
        let owner = live.owner;
        // The document root has no block and therefore no lock: a port on
        // the root is as editable as the root is, which is always.
        let locked = doc.block(&owner).is_some_and(|block| block.locked);
        (!locked).then_some(Self(pin))
    }

    /// Every pin of `pins` whose owner accepts material edits, in order. A
    /// locked owner drops its pins from the set rather than refusing the
    /// whole edit, which is how a mixed selection behaves everywhere else.
    pub fn all(doc: &Document, pins: &[PinId]) -> Vec<Self> {
        pins.iter().filter_map(|&id| Self::of(doc, id)).collect()
    }

    pub fn id(self) -> PinId {
        self.0
    }
}

/// A scope that accepts material interface edits — the document root, which
/// has no lock to carry, or an unlocked block.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub struct UnlockedScope(Scope);

impl UnlockedScope {
    /// `None` for a locked block, or for a scope the document does not hold
    /// — which takes no edits at all, material or otherwise.
    pub fn of(indexed: &IndexedDocument<'_>, owner: Scope) -> Option<Self> {
        match resolve(indexed, owner) {
            Resolved::Root => Some(Self(owner)),
            Resolved::Block(block) => (!block.locked).then_some(Self(owner)),
            Resolved::Absent => None,
        }
    }

    pub fn scope(self) -> Scope {
        self.0
    }
}