blockworx/document/

mod.rs

//! The legacy document model: dormant since the flag day (F7), demolished in
//! phase 7.
//!
//! Nothing in the editor reads a legacy `Document` any more — the bridge
//! (`crate::schema::lower`) reads the *schema*, and everything downstream is
//! `blockworx_doc`. What survives here is what the schema parse half and the
//! tutorial embeds still compile against, plus the handful of value types the
//! editor kept (`GridPos`, `Lock`, `LinearDistance`). Being unplugged, most of
//! it has no caller, so `dead_code` is allowed module-wide rather than
//! decorated item by item — the lid comes off by deleting the module, not by
//! finding callers for it.
#![allow(dead_code)]

pub mod auto_route;
pub mod change;
pub mod coord;
pub mod decorations;
pub mod image;
pub mod label;
pub mod linear_distance;
pub mod model;
pub mod pin_side;
pub mod pin_type;
pub mod schema_convert;

pub use auto_route::AutoRoute;
pub use coord::{GridPos, GridRect, GridSize, GridVec};
pub use decorations::Decorations;
pub use image::{Asset, Image, ImageData};
pub use label::{BlockLabel, LabelSide};
pub use linear_distance::LinearDistance;
pub use model::Document;
pub use pin_side::PinSide;
pub use pin_type::PinType;

use serde::{Deserialize, Serialize};

use crate::presentation::store::{IdMap, IdSet};
use crate::store::{CommentId, ImageId, PinId, RectId, RouteId, TextId};

/// A node in the persistent document tree.
///
/// `pins` of a Block, when the Block is the one whose interior is being drawn,
/// are visualized as Ports on the canvas boundary. When the Block is a child
/// (in some other Block's `children`), it is visualized as a rect with its
/// pins on its edges.
#[derive(Clone, Debug, PartialEq)]
pub struct Block {
    pub inner: GridRect,
    /// The block's label decorations. `decorations.title.name` is the single
    /// source of truth for the block's name.
    pub decorations: Decorations,
    pub pins: IdMap<PinId, PinPort>,
    /// Ids of this block's children. The child `Block`s themselves live in the
    /// document-global [`Document::blocks`] map; this set only records which of
    /// them are this block's children and in what order (render z-order). Stored
    /// as an [`IdSet`] — insertion-ordered, so child z-order is stable.
    pub children: IdSet<RectId>,
    pub routes: IdMap<RouteId, AutoRoute>,
    /// Free-floating text annotations placed on this block's interior. They
    /// carry no pins and never participate in routing.
    pub texts: IdMap<TextId, TextBox>,
    /// Free-floating boundary [`Comment`]s placed on this block's interior. Like
    /// [`texts`](Self::texts) they carry no pins, never participate in routing,
    /// and are not part of the hierarchy (never listed in any block's
    /// `children`). They render on a layer above the blocks and routes.
    pub comments: IdMap<CommentId, Comment>,
    /// Free-floating background image annotations placed on this block's
    /// interior. Like [`texts`](Self::texts) and [`comments`](Self::comments)
    /// they carry no pins, never participate in routing, and are not part of the
    /// hierarchy. They paint behind everything (the background layer).
    pub images: IdMap<ImageId, Image>,
    /// This block's optional foreground icon: a [`Image`] centered on the block
    /// that travels with it. Unlike a background [`images`](Self::images) image
    /// it is only selectable while the block itself is selected.
    pub icon: Option<Image>,
    /// Optional accent index (`0..=7`) selecting the block's outline color via
    /// [`Accent0`](crate::theme::Role::Accent0)..[`Accent7`](crate::theme::Role::Accent7);
    /// `None` uses [`AccentDefault`](crate::theme::Role::AccentDefault).
    pub role: Option<u8>,
    /// Whether the block's pin/port interface is frozen. A locked block can still
    /// be moved, deleted, resized, recolored, and have its title/type edited, but
    /// its pins and ports are protected from material edits (rename, retype, tag
    /// text, add, delete).
    pub locked: bool,
}

/// Whether an interface is frozen against edits — the parameter form of a
/// `locked` flag, so a call site reads `Lock::Locked` instead of a bare `true`.
#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
pub enum Lock {
    Locked,
    Unlocked,
}

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

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

/// Whether a pin/port draws its tag. The parameter form of `tag_hidden`.
#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
pub enum TagVisibility {
    Shown,
    Hidden,
}

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

/// Whether a block's pin interface accepts edits. The parameter form of
/// `locked`.
#[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
        }
    }
}

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

/// A free-floating multi-line text annotation. Unlike a [`Block`] it has no
/// pins, title, tag, or bounding box — just text pinned at a single grid
/// `anchor`. It implements [`crate::shape::BaseShape`] so it can be
/// selected, moved, and deleted through the same machinery as blocks and ports
/// (but it is never resized — its extent is whatever the text needs).
#[derive(Clone, Debug, PartialEq)]
pub struct TextBox {
    /// The annotation's content. May contain `\n` for multiple lines; the user
    /// governs the layout, there is no wrapping.
    pub text: String,
    /// Top-left anchor (grid coordinate). Text flows right/down from here.
    /// The measured on-canvas extent is derived state
    /// ([`crate::presentation::TextExtents`]), not stored here.
    pub anchor: GridPos,
    /// Optional accent index (`0..=7`) selecting the outline color; `None`
    /// strokes with [`crate::theme::Role::TextBoxStroke`].
    pub role: Option<u8>,
}

/// A free-floating boundary annotation: a rectangle drawn as an outline only
/// (no fill) with a single repositionable [`BlockLabel`] title. Unlike a
/// [`Block`] it has no pins, tag, children, or routes and never participates in
/// the hierarchy — it exists purely to group components visually. It implements
/// [`crate::shape::BaseShape`] so it is selected, moved, resized, and renamed
/// through the same machinery as blocks, and it renders on a layer above the
/// blocks and routes.
#[derive(Clone, Debug, PartialEq)]
pub struct Comment {
    /// Position and size in grid coordinates (resizable, like a block).
    pub inner: GridRect,
    /// The comment's repositionable title. `title.name` is the comment's name.
    pub title: BlockLabel,
    /// Optional accent index (`0..=7`) selecting the outline color; `None`
    /// strokes with [`crate::theme::Role::CommentStroke`].
    pub role: Option<u8>,
}

/// Unified Pin/Port data structure. When the entry lives in a child block's
/// `pins` store it is acting as an inner pin and `rect` is unused (the
/// position is computed from the parent block's rect + `side`/`offset`).
/// When the entry lives in the current block's `pins` store it is rendered
/// as a Port and `rect` carries its on-canvas position.
#[derive(Clone, Debug, PartialEq)]
pub struct PinPort {
    /// The pin's primary label, a single line. (Legacy documents may carry a
    /// second line after a `\n`; it is ignored — the render/edit paths use only
    /// the first line.)
    pub name: String,
    /// The pin's secondary label — its "type" — drawn a little smaller, below the
    /// name. Single-line, like `name`. Written on disk as `type`. Distinct from
    /// [`PinType`] (`kind`), which is the I/O direction, not free text.
    pub type_label: String,
    /// A short user-editable label — the pin's "location" designator (e.g. "A1").
    /// Defaults to the pin's id (as a string) at creation.
    pub tag: String,
    /// Whether the `tag` label is hidden. Kept beside `tag` since it governs it.
    /// The user toggles it via the per-pin eye button shown when the pin's
    /// owning shape is selected. (There is deliberately no `name`-visibility
    /// flag: an unlabelled pin breaks the hierarchy, so to drop a label the user
    /// clears its text instead.)
    pub tag_hidden: bool,
    pub side: PinSide,
    pub offset: u32,
    pub rect: GridRect,
    /// Signal direction, stored from the pin's point of view. Flipped when
    /// this `PinPort` is rendered as a port. See [`PinType`].
    pub kind: PinType,
    /// The user-picked accent of this pin drawn as a boundary port. The
    /// stub accents that used to sit beside it (`pin_accent`,
    /// `port_pin_accent`) are propagated from route roles — derived
    /// state, computed in [`crate::presentation::PinAccents`], never stored
    /// here.
    pub port_accent: Option<u8>,
    /// Which way the stub faces when this `PinPort` is drawn as a boundary
    /// *port*, independent of `side` (which edge of the parent it occupies as a
    /// pin). `None` derives it as `side.flip()` — a port faces opposite the edge
    /// its pin sits on, so its interior stub points inward. The flip-L/R tool
    /// sets it explicitly (and a parent flip freezes it) so it stops tracking
    /// `side`. Ignored when this `PinPort` is drawn as a block's edge pin.
    /// Written on disk as `facing`.
    pub port_orientation: Option<PinSide>,
}

#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
pub struct Waypoint {
    pub pos: GridPos,
    pub locked: bool,
}

/// Absolute reference to a pin on either the current block (`Port`) or
/// a child block (`Pin`). Ordered so anchors can key an ordered set — the
/// order is arbitrary but stable, which is what a change set needs.
#[derive(Clone, Copy, Debug, PartialEq, Eq, PartialOrd, Ord, Hash)]
pub enum LineAnchor {
    Port(PinId),
    Pin { block: RectId, pin: PinId },
}

/// The on-disk spelling: `p2` for a port (relative to the block owning the
/// route) and `b3:p2` for a child block's pin.
impl std::fmt::Display for LineAnchor {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            LineAnchor::Port(p) => write!(f, "{p}"),
            LineAnchor::Pin { block, pin } => write!(f, "{block}:{pin}"),
        }
    }
}

/// Width (grid cells) a top block is born with. Deliberately small and fixed
/// rather than derived from what the block contains: the top is a block like any
/// other once a level is added above it, and a size the user drags to fit beats a
/// rect as large as the whole drawing.
pub const TOP_BLOCK_DEFAULT_WIDTH: u32 = 8;
/// Height (grid cells) a top block is born with. One of the valid block heights
/// (see [`crate::grid::snap_block_height_cells`]), leaving room for five pin
/// slots.
pub const TOP_BLOCK_DEFAULT_HEIGHT: u32 = 16;

/// The rect a top block is born with, at the world origin.
pub const TOP_BLOCK_DEFAULT_RECT: GridRect = GridRect::new(
    GridPos::new(0, 0),
    GridSize::new(TOP_BLOCK_DEFAULT_WIDTH, TOP_BLOCK_DEFAULT_HEIGHT),
);

impl Default for Block {
    fn default() -> Self {
        Self {
            inner: TOP_BLOCK_DEFAULT_RECT,
            decorations: Decorations {
                title: BlockLabel {
                    name: "top".to_string(),
                    ..BlockLabel::default()
                },
                ..Decorations::default()
            },
            pins: IdMap::default(),
            children: IdSet::default(),
            routes: IdMap::default(),
            texts: IdMap::default(),
            comments: IdMap::default(),
            images: IdMap::default(),
            icon: None,
            role: None,
            locked: false,
        }
    }
}