blockworx_tools/

tool.rs

use blockworx_geom::Pos2;
use enum_dispatch::enum_dispatch;

use crate::edit::naming::Authoring;
use crate::{
    AddPin, AddPort, AddRouteLabel, AddText, EditRoute, EditTextBox, MoveBlock, MoveBlockType,
    MoveLabel, MovePin, MoveTitle, NewArea, NewBlock, RenameBlockType, RenamePin, RenameRoute,
    RenameTitle, RetypePin, RouteTool, SelectTool,
    block_edit::EditTarget,
    edit::naming::{InterfaceLock, TagVisibility},
    move_multi_pin::MoveMultiPin,
    multi_pin_select::MultiPinSelect,
    multi_select::MultiSelect,
    names::ToolName,
    resize_block::ResizeBlock,
    select_pin::SelectPin,
    shape::ShapeId,
    theme::Style,
    widget::drawing::Drawing,
};
use blockworx_doc::{
    block_model::Asset,
    id::{BlockId, PinId, RouteId},
    values::PinDir,
};
use blockworx_paint::{Canvas, Interaction};

// The selection vocabulary and the preview phase are the editor's — a
// `Deletable` is a set of shapes and `PreviewPhase` gates its preview writers —
// and every tool reaches them through this module.
pub use crate::shape::{Deletable, RoleTarget};
pub use crate::widget::PreviewPhase;

#[enum_dispatch(Tool)]
pub trait ToolTrait {
    fn name(&self) -> ToolName;
    /// Advance this frame's drag state and preview the geometry it implies.
    /// Runs before [`Self::widget`] paints, on every frame of a drag —
    /// including one carrying no event at all, which is what a repaint
    /// mid-drag looks like.
    fn preview<C: Canvas>(
        &mut self,
        _data: &mut Drawing<'_>,
        _interaction: &Interaction,
        _painter: &mut Style<'_, C>,
        _phase: &PreviewPhase,
    ) {
    }
    fn widget<C: Canvas>(
        &mut self,
        data: &mut Drawing<'_>,
        interaction: &Interaction,
        painter: &mut Style<'_, C>,
    ) -> Option<Transition>;
    /// The item this tool currently has selected that can be deleted, if any.
    /// Used to drive the delete button overlay.
    fn selection(&self) -> Option<Deletable> {
        None
    }
    /// A world-space point the selection overlay should anchor to, overriding the
    /// selection's bounding box. A route spans a wide bbox but is picked at one
    /// spot, so its overlay anchors at the click instead of the whole polyline.
    fn overlay_anchor(&self) -> Option<Pos2> {
        None
    }
}

/// One frame of a tool: preview, then act. The drivers call this and never
/// [`ToolTrait::widget`] directly, which is what makes the order structural —
/// a tool has no way to reach the preview writers from `widget`, because the
/// [`PreviewPhase`] they require is minted here and handed only to `preview`.
pub fn frame<C: Canvas>(
    tool: &mut Tool,
    data: &mut Drawing<'_>,
    interaction: &Interaction,
    painter: &mut Style<'_, C>,
) -> Option<Transition> {
    // Measurement first: a text box whose text changed under it — an undo, a
    // restore — carries a stale extent until something measures it, and
    // everything below this line reads extents. Only stale entries cost
    // anything, so an ordinary frame pays a comparison per box.
    data.refresh_text_extents(painter);
    let interaction = &offered_gestures(interaction, data.authoring());
    let name = tool.name();
    {
        let _s = tracing::info_span!("preview", label = ?name).entered();
        tool.preview(data, interaction, painter, &PreviewPhase::frame());
    }
    let _s = tracing::info_span!("widget", label = ?name).entered();
    tool.widget(data, interaction, painter)
}

/// The interaction a frame hands its tool. A read-only session keeps the
/// pointer — selecting and navigating are free — but loses the two channels
/// that exist only to author: the held press every add-affordance arms from
/// (the new-pin markers, the route-start targets) and the Delete key. Taken
/// away here rather than in each of the tools that read them, so a new tool
/// cannot forget.
fn offered_gestures(interaction: &Interaction, authoring: Authoring) -> Interaction {
    match authoring {
        Authoring::Offered => interaction.clone(),
        Authoring::Withheld => Interaction {
            press: None,
            delete_pressed: false,
            ..interaction.clone()
        },
    }
}

#[enum_dispatch]
pub enum Tool {
    NewBlock(NewBlock),
    NewArea(NewArea),
    AddPin(AddPin),
    AddPort(AddPort),
    AddText(AddText),
    EditTextBox(EditTextBox),
    MovePin(MovePin),
    RenamePin(RenamePin),
    RetypePin(RetypePin),
    MoveTitle(MoveTitle),
    MoveBlockType(MoveBlockType),
    RenameTitle(RenameTitle),
    RenameBlockType(RenameBlockType),
    Route(RouteTool),
    MoveBlock(MoveBlock),
    ResizeBlock(ResizeBlock),
    EditRoute(EditRoute),
    AddRouteLabel(AddRouteLabel),
    RenameRoute(RenameRoute),
    MoveLabel(MoveLabel),
    Select(SelectTool),
    SelectPin(SelectPin),
    MultiSelect(MultiSelect),
    MultiPinSelect(MultiPinSelect),
    MoveMultiPin(MoveMultiPin),
}

impl Tool {
    /// The fresh (idle) tool a toolbar press on `name` arms. Tools that are
    /// never armed from the toolbar — armed instead from a selection overlay
    /// (`AddRouteLabel`), a marquee drag (`MultiSelect`), a text box
    /// (`EditTextBox`), and the rest of the selection family — fall back to
    /// `Select`. Shared by the toolbar and the headless tool suites so
    /// there is exactly one `ToolName → Tool` mapping.
    pub fn from_name(name: ToolName) -> Tool {
        match name {
            ToolName::NewBlock => Tool::NewBlock(NewBlock::Idle),
            ToolName::NewArea => Tool::NewArea(NewArea::Idle),
            ToolName::AddPin => Tool::AddPin(AddPin),
            ToolName::AddPort => Tool::AddPort(AddPort),
            ToolName::AddText => Tool::AddText(AddText),
            ToolName::MovePin => Tool::MovePin(MovePin::Idle),
            ToolName::RenamePin => Tool::RenamePin(RenamePin::Idle),
            ToolName::MoveTitle => Tool::MoveTitle(MoveTitle::Idle),
            ToolName::RenameTitle => Tool::RenameTitle(RenameTitle::Idle),
            ToolName::Route => Tool::Route(RouteTool::default()),
            ToolName::MoveBlock => Tool::MoveBlock(MoveBlock::Idle),
            ToolName::ResizeBlock => Tool::ResizeBlock(ResizeBlock::Idle),
            ToolName::EditRoute => Tool::EditRoute(EditRoute::Idle),
            ToolName::RenameRoute => Tool::RenameRoute(RenameRoute::Idle),
            ToolName::MoveLabel => Tool::MoveLabel(MoveLabel::Idle),
            ToolName::Select
            | ToolName::Icon
            | ToolName::NewImage
            | ToolName::AddRouteLabel
            | ToolName::RetypePin
            | ToolName::MoveBlockType
            | ToolName::RenameBlockType
            | ToolName::MultiSelect
            | ToolName::MultiPinSelect
            | ToolName::MoveMultiPin
            | ToolName::EditTextBox
            | ToolName::SelectPin => Tool::Select(SelectTool),
        }
    }
}

/// What a tool's frame asks for: the next tool, seeded with whatever state
/// the hand-off carries — installed inside the same call and never sent
/// anywhere — or an action on the same terms a front end sends one.
pub enum Transition {
    SwitchTool(Tool),
    Action(Action),
}

impl Default for Transition {
    fn default() -> Self {
        Transition::SwitchTool(SelectTool.into())
    }
}

impl From<Action> for Transition {
    fn from(action: Action) -> Self {
        Transition::Action(action)
    }
}

impl Transition {
    /// What the gesture this transition opens is called; see
    /// [`Action::label`].
    pub fn label(&self) -> &'static str {
        match self {
            Transition::SwitchTool(_) => SWITCH_TOOL,
            Transition::Action(action) => action.label(),
        }
    }
}

const SWITCH_TOOL: &str = "switch tool";

/// What the core executes, as a front end or a tool says it. Holds no
/// [`Tool`]: a tool the front end asks for is named — by its [`ToolName`],
/// the route it labels, the field it edits — and built against the drawing
/// as it stands when the action is applied.
#[derive(PartialEq, serde::Serialize, serde::Deserialize)]
pub enum Action {
    /// Arm the fresh tool [`Tool::from_name`] gives for this name.
    Arm(ToolName),
    /// Toggle the author's diagnostic overlay.
    ToggleDiagnostic,
    /// Toggle the frame-rate readout the front end shows.
    ToggleFrameRate,
    /// Arm the label tool on this route.
    ArmAddRouteLabel(RouteId),
    /// Open the in-place editor on this field. A field that is no longer
    /// there, or no longer editable, opens nothing.
    OpenEditor(EditTarget),
    /// Stamp `tool`'s default thing at the world point `at` — what a cell
    /// dragged off the tool cluster and dropped on the canvas comes to
    /// (`crate::stamp`). Arming and stamping are the cell's two
    /// gestures, and this is the one that does not arm.
    StampTool {
        tool: ToolName,
        at: Pos2,
    },
    Delete(Deletable),
    /// Copy the given shapes (and the routes among them) to the clipboard.
    Copy(Vec<ShapeId>),
    /// Copy a group of child-block pins to the clipboard (as a pin payload).
    CopyPins(Vec<PinId>),
    /// Copy the given shapes to the clipboard, then delete them (one undo step).
    Cut(Vec<ShapeId>),
    /// Copy a group of child-block pins to the clipboard, then delete them.
    CutPins(Vec<PinId>),
    /// Set every listed pin's tag to `tags`.
    SetPinTags {
        pins: Vec<PinId>,
        tags: TagVisibility,
    },
    /// Set a selected shape's own label — a child block's tag, or a port's pin
    /// tag — to `tags`.
    SetShapeTagHidden {
        shape: ShapeId,
        tags: TagVisibility,
    },
    /// Flip a selected shape's pins to the opposite edge — a port's single pin,
    /// or all of a child block's pins — and re-route.
    FlipShapePins(ShapeId),
    /// Vertically mirror a selected child block's pins — a pin near the top moves
    /// to the bottom and vice versa, each keeping its East/West side — and
    /// re-route. Scoped to blocks (ports carry a single pin, nothing to mirror).
    FlipBlockVertical(BlockId),
    /// Lock or unlock a child block: a locked block keeps its pin/port interface
    /// frozen (no rename/retype/tag/add/delete of pins or ports) while still
    /// allowing whole-block moves, deletes, resizes, and aesthetic edits.
    SetBlockLocked {
        block: BlockId,
        lock: InterfaceLock,
    },
    /// Paste a clipboard JSON payload into the current level.
    Paste(String),
    ExpandBlock(BlockId),
    /// Step the zoom in or out about the pointer — the keyboard's zoom, where
    /// the wheel zooms about the cursor continuously.
    Zoom(blockworx_paint::ZoomStep),
    /// Navigate to a level by its whole path — the palette's `go <path>`,
    /// which parses a content-path string (see [`crate::content_path`]).
    GoToPath(crate::path::BlockPath),
    /// Accent `target` — what the picker reports, rather than what it writes.
    /// A popup that wrote the document itself was the only mutation in the
    /// app reachable by no other route, and so the only one no test could
    /// drive; as an action it dispatches like every other write and a script
    /// can ask for it by name.
    SetRole {
        target: RoleTarget,
        /// The accent index the picker reports; `None` is "no accent", the
        /// target's own un-accented stroke.
        role: Option<u8>,
    },
    /// Set the I/O direction of every listed pin — the pin-type picker's
    /// report, on the same terms as [`Action::SetRole`].
    SetPinsKind {
        pins: Vec<PinId>,
        kind: PinDir,
    },
    GoUp,
    /// The user is done with one of the session's failure notices, named by
    /// its position among them.
    AcknowledgeFailure(usize),
    /// Frame this world rect — the palette's `camera <x> <y> <w> <h>`, the
    /// same framing a scripted `camera` step applies.
    FrameRect(blockworx_geom::Rect),
    /// Select a block chosen in the navigation dialog: replace the selection (or,
    /// with `extend`, toggle it into the current selection like a canvas
    /// shift-click), then pan/zoom the canvas to frame that block.
    NavSelect {
        block: BlockId,
        extend: bool,
    },
    /// Restore the previous document/navigation snapshot.
    Undo,
    /// Re-apply a snapshot undone by [`Action::Undo`].
    Redo,
    /// Arrow-key move of the current selection: shapes shift by `(dx, dy)` grid
    /// cells; a pin selection shifts by `dy` slots (`dx` ignored).
    Nudge {
        dx: i32,
        dy: i32,
    },
    /// Reset zoom/pan so the whole document fits in the viewport.
    ResetView,
    /// Export what is on the canvas in `format` — or, when `selection` names
    /// shapes, those shapes as a standalone diagram. What comes of it is bytes
    /// and a name, handed back through the session's one hand-off slot; which
    /// file they are written to is the host's own business.
    Export {
        format: crate::commands::ExportFormat,
        selection: Option<Vec<ShapeId>>,
    },
    /// Wear this artwork as the block's foreground icon.
    SetIcon {
        block: BlockId,
        asset: Asset,
    },
    /// Draw this artwork as an image of its own. Where it goes is the
    /// session's to say — the picker the shell ran knows nothing about the
    /// canvas — so it lands centred on the point a paste lands on, at the
    /// artwork's own aspect.
    PlaceImage {
        asset: Asset,
    },
    /// Rip up a route and autoroute it fresh with no waypoints.
    Reroute(RouteId),
    /// Rip up and autoroute every route with an endpoint on this block.
    RerouteBlock(BlockId),
    /// Put a past rev on the canvas, read-only — the time machine.
    ViewRev(blockworx_doc::rev::Rev),
    /// Leave the past for the writable head.
    ViewHead,
    /// Paint the drawing in this palette from now on — the front end's
    /// theme, told. Not an edit: it spends no rev, the undo stack does not
    /// move, and a read-only session takes it.
    SetPalette(blockworx_paint::Palette),
    /// Put a name on a rev, or take one off. Not an edit: it spends no rev
    /// and the undo stack does not move.
    TagRev {
        at: blockworx_doc::rev::Rev,
        name: String,
        how: blockworx_store::tags::Tagging,
    },
}

impl Action {
    /// What the commit this action produces is called — the stable command
    /// name where a named command triggered it, so the log, undo, and review
    /// all read the same word for the same gesture. Actions that write
    /// nothing still carry one: the gesture opens before the dispatcher
    /// knows which arm will take it.
    pub fn label(&self) -> &'static str {
        match self {
            Action::Arm(_)
            | Action::ArmAddRouteLabel(_)
            | Action::OpenEditor(_)
            | Action::ToggleDiagnostic
            | Action::ToggleFrameRate => SWITCH_TOOL,
            // Labelled by the tool that made it, exactly as the canvas
            // labels the same tool's drawn gesture — one word for one kind
            // of thing, however it was created.
            Action::StampTool { tool, .. } => tool.verb(),
            Action::Delete(_) => "delete",
            Action::SetRole { .. } => "accent",
            Action::SetPinsKind { .. } => "io",
            Action::Copy(_) | Action::CopyPins(_) => "copy",
            Action::Cut(_) | Action::CutPins(_) => "cut",
            Action::SetPinTags {
                tags: TagVisibility::Hidden,
                ..
            }
            | Action::SetShapeTagHidden {
                tags: TagVisibility::Hidden,
                ..
            } => "hide-tags",
            Action::SetPinTags {
                tags: TagVisibility::Shown,
                ..
            }
            | Action::SetShapeTagHidden {
                tags: TagVisibility::Shown,
                ..
            } => "show-tags",
            Action::FlipShapePins(_) => "flip-lr",
            Action::FlipBlockVertical(_) => "flip-ud",
            Action::SetBlockLocked {
                lock: InterfaceLock::Locked,
                ..
            } => "lock",
            Action::SetBlockLocked {
                lock: InterfaceLock::Unlocked,
                ..
            } => "unlock",
            Action::Paste(_) => "paste",
            // The one arm here that writes: a restore is an ordinary
            // forward commit, and the log should say which rev it went
            // back to rather than merely "restore".
            Action::Reroute(_) => "reroute",
            Action::RerouteBlock(_) => "reroute-block",
            Action::GoUp => "up",
            Action::AcknowledgeFailure(_) => "acknowledge",
            Action::FrameRect(_) => "camera",
            Action::Nudge { .. } => "nudge",
            // The picked image writes under the verb of the tool that asked
            // for it, so a drawn image and an attached icon read in the log
            // exactly as they did when the tool wrote them itself.
            Action::PlaceImage { .. } => ToolName::NewImage.verb(),
            Action::SetIcon { .. } => ToolName::Icon.verb(),
            // Navigation, the view, the palette, the exports and the history
            // stack author nothing.
            Action::ExpandBlock(_)
            | Action::Export { .. }
            | Action::Zoom(_)
            | Action::GoToPath(_)
            | Action::NavSelect { .. }
            | Action::Undo
            | Action::Redo
            | Action::ResetView
            | Action::ViewRev(_)
            | Action::ViewHead
            | Action::TagRev { .. }
            | Action::SetPalette(_) => "edit",
        }
    }
}

/// The selection tool a freshly renamed/moved pin should return to, so the pin
/// stays the standing target for further edits. A block pin returns to the
/// per-pin [`SelectPin`] selection; a port returns to its block-style
/// [`ResizeBlock`] selection.
pub fn select_tool_for_anchor(data: &Drawing<'_>, anchor: PinId) -> Tool {
    match data.pin_shape(anchor) {
        Some(shape @ ShapeId::Port(_)) => ResizeBlock::Selected { shape }.into(),
        _ => SelectPin::Selected { anchor }.into(),
    }
}

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

    /// Every tool is stored inline in `Tool`, which is moved on each tool switch
    /// and carried by value inside `Transition`, so one wide tool taxes the whole
    /// layer. The route tool's cross-frame preview cache — 312 bytes of router
    /// and fixed legs, far more than any other tool holds — is boxed for exactly
    /// that reason; this fails if the next wide field lands inline instead.
    #[test]
    fn a_tool_switch_stays_cheap_to_move() {
        let tool = size_of::<Tool>();
        assert!(tool <= 256, "Tool grew to {tool} bytes");
        // `Transition::SwitchTool` carries a whole `Tool`, so it tracks that budget.
        assert!(size_of::<Transition>() <= tool + 16);
    }

    /// A mis-wired arm in [`Tool::from_name`] (arming `MoveTitle` for
    /// `ToolName::MovePin`, say) is invisible until a script or toolbar press
    /// runs the wrong tool.
    #[test]
    fn from_name_arms_the_named_tool_or_falls_back_to_select() {
        for name in crate::names::ALL_TOOLS {
            let armed = Tool::from_name(name).name();
            assert!(
                armed == name || armed == ToolName::Select,
                "from_name({name:?}) armed {armed:?}"
            );
        }
    }

    /// The toolbar's own tools have no fallback: pressing a toolbar button
    /// must arm exactly that tool. The image cell is not one of them — it
    /// picks artwork rather than arming anything — so it is the one band cell
    /// `from_name` answers with `Select`.
    #[test]
    fn toolbar_tools_round_trip_through_from_name() {
        for name in crate::names::band_tools() {
            let armed = Tool::from_name(name).name();
            if name == ToolName::NewImage {
                assert_eq!(armed, ToolName::Select);
                continue;
            }
            assert_eq!(armed, name);
        }
    }
}