blockworx/tools/

tool.rs

use blockworx_geom::{Pos2, Rect};
use enum_dispatch::enum_dispatch;

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

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

#[enum_dispatch(Tool)]
pub trait ToolTrait {
    fn name(&self) -> ToolName;
    /// Advance this frame's drag state and suppose 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 suppose<C: Canvas>(
        &mut self,
        _data: &mut Drawing<'_>,
        _interaction: &Interaction,
        _painter: &mut Style<'_, C>,
        _phase: &Supposing,
    ) {
    }
    fn widget<C: Canvas>(
        &mut self,
        data: &mut Drawing<'_>,
        interaction: &Interaction,
        painter: &mut Style<'_, C>,
    ) -> Option<Action>;
    /// 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: suppose, 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
/// [`Supposing`] they require is minted here and handed only to `suppose`.
pub fn frame<C: Canvas>(
    tool: &mut Tool,
    data: &mut Drawing<'_>,
    interaction: &Interaction,
    painter: &mut Style<'_, C>,
) -> Option<Action> {
    // 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());
    tool.suppose(data, interaction, painter, &Supposing::frame());
    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,
        Authoring::Withheld => Interaction {
            press: None,
            delete_pressed: false,
            ..*interaction
        },
    }
}

#[enum_dispatch]
pub enum Tool {
    NewBlock(NewBlock),
    NewArea(NewArea),
    AddPort(AddPort),
    NewImage(NewImage),
    AddText(AddText),
    EditTextBox(EditTextBox),
    MovePin(MovePin),
    RenamePin(RenamePin),
    RetypePin(RetypePin),
    MoveTitle(MoveTitle),
    MoveBlockType(MoveBlockType),
    RenameTitle(RenameTitle),
    RenameBlockType(RenameBlockType),
    Route(RouteTool),
    MoveBlock(MoveBlock),
    ResizeBlock(ResizeBlock),
    Icon(IconTool),
    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 selection overlays
    /// (`Icon`, `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::AddPort => Tool::AddPort(AddPort::Idle),
            ToolName::NewImage => Tool::NewImage(NewImage::Idle),
            ToolName::AddText => Tool::AddText(AddText::Idle),
            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::AddRouteLabel
            | ToolName::RetypePin
            | ToolName::MoveBlockType
            | ToolName::RenameBlockType
            | ToolName::MultiSelect
            | ToolName::MultiPinSelect
            | ToolName::MoveMultiPin
            | ToolName::EditTextBox
            | ToolName::SelectPin => Tool::Select(SelectTool),
        }
    }
}

/// Where an export goes. The history row offers a rev both ways, and the
/// payload is the same either way — this is the whole difference between
/// "Copy" and "Save…".
#[derive(Clone, Copy, PartialEq, Eq, Debug)]
pub enum ExportTo {
    Clipboard,
    File,
}

pub enum Action {
    SwitchTool(Tool),
    /// 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::tools::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),
    /// Frame this world rect — the palette's `camera <x> <y> <w> <h>`, the same
    /// framing a scripted `camera` step applies.
    Camera(Rect),
    /// 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::tools::content_path`]).
    GoToPath(crate::path::BlockPath),
    /// Open the accent-color (role) picker for the selected block, port, route,
    /// area, or text box. The popup anchors itself above the selection
    /// overlay, so no screen position is carried here.
    OpenRolePicker {
        target: RoleTarget,
    },
    /// 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. Spelled as the setter spells it —
        /// naming this index is queued with the rest of the nomenclature
        /// sweep, and it reaches the legacy layer phase 7 deletes.
        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,
    },

    /// Open the pin-type (I/O style) picker for the current pin/port selection.
    /// Carries the anchors of every pin the picker will retype. Like
    /// [`Action::OpenRolePicker`], the popup anchors itself above the selection
    /// overlay, so no screen position is carried here.
    OpenPinTypePicker {
        pins: Vec<PinId>,
    },
    GoUp,
    /// 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 in the chosen format via a save dialog / download. `selection` is
    /// the shapes to export as a standalone diagram (`None` = the current view).
    Export {
        format: crate::export::ExportFormat,
        selection: Option<Vec<ShapeId>>,
    },
    /// Open the import dialog (JSON / PNG / SVG). A diagram lands as one
    /// new block in the active scope (D19); a PNG/SVG is added as a plain
    /// image.
    Import,
    /// Write the flattened document at a rev — the history row's Copy and
    /// Save… (D19). The rev's fold is the only thing that separates this from
    /// [`Action::Export`] of the current view.
    ExportRev {
        at: blockworx_doc::rev::Rev,
        to: ExportTo,
    },
    /// Close whatever is open and start a fresh unsaved session. With
    /// append-on-commit there is nothing to prompt about: a container already
    /// holds everything that was committed to it.
    #[cfg(not(target_arch = "wasm32"))]
    NewDocument,
    /// Open the File menu's dialog for `request`; the pick comes back
    /// through [`crate::file::PickReceiver`].
    #[cfg(not(target_arch = "wasm32"))]
    PickFile(crate::file::FileRequest),
    /// Reopen a remembered container.
    #[cfg(not(target_arch = "wasm32"))]
    OpenRecent(std::path::PathBuf),
    /// Call this document something else, which renames its container: the
    /// directory's name *is* the document's name (D20). Carries the name
    /// the user typed, unvalidated — [`crate::file::renamed_beside`] is
    /// what says whether it is one.
    #[cfg(not(target_arch = "wasm32"))]
    RenameDocument(String),
    /// Rewrite the attached container's `document.json` from the head fold.
    /// The commits are already durable; this refreshes the readable view of
    /// them (D11). Unlike its File-menu neighbours this variant exists on
    /// every target, because the *registry* offers it — and the registry is
    /// one list, compiled everywhere. The browser simply never has a
    /// container for [`Saving`](blockworx_store::doc::Saving) to offer it on.
    SaveProjection,
    /// 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 (F7).
    ViewRev(blockworx_doc::rev::Rev),
    /// Leave the past for the writable head.
    ViewHead,
    /// Put one of §8.1's names on a rev, or take one off (D18). 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 Default for Action {
    fn default() -> Self {
        Action::SwitchTool(SelectTool.into())
    }
}

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::SwitchTool(_) => "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::Nudge { .. } => "nudge",
            Action::Import => "import",
            // The File flow writes through the store rather than through a
            // gesture, so the gesture it opens seals to nothing.
            Action::SaveProjection => "file",
            #[cfg(not(target_arch = "wasm32"))]
            Action::NewDocument
            | Action::PickFile(_)
            | Action::OpenRecent(_)
            | Action::RenameDocument(_) => "file",
            // Navigation, view, dialogs and the history stack author nothing.
            Action::ExpandBlock(_)
            | Action::Camera(_)
            | Action::Zoom(_)
            | Action::GoToPath(_)
            | Action::OpenRolePicker { .. }
            | Action::OpenPinTypePicker { .. }
            | Action::NavSelect { .. }
            | Action::Undo
            | Action::Redo
            | Action::ResetView
            | Action::Export { .. }
            | Action::ExportRev { .. }
            | Action::ViewRev(_)
            | Action::ViewHead
            | Action::TagRev { .. } => "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 `Action`, 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");
        // `Action::SwitchTool` carries a whole `Tool`, so it tracks that budget.
        assert!(size_of::<Action>() <= 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::tools::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.
    #[test]
    fn toolbar_tools_round_trip_through_from_name() {
        for name in crate::tools::names::band_tools() {
            assert_eq!(Tool::from_name(name).name(), name);
        }
    }
}