blockworx_tools/

new_pin.rs

//! The free-slot markers: where a pin can be added to a block.
//!
//! Every free pin slot on a block is offered as a small blue dot one grid cell
//! outside the block edge — where the pin's connection point will land. The
//! dot nearest the cursor animates into a blue ring that grows out to
//! `PORT_RADIUS`.
//!
//! Three tools offer them: a selected block offers its own (the "(+)"), the
//! add-pin tool offers every block's in scope, and the route tool offers the
//! nearest block's so a route can end on a pin that does not exist yet. Which
//! blocks offer, where a marker sits, which one a press lands on and how one
//! is drawn are decided here, once.

use blockworx_doc::id::BlockId;
use blockworx_geom::WorldPx;
use blockworx_geom::{Pos2, vec2};

use crate::{
    edit::naming::Authoring,
    grid::{GRID_SIZE, PIN_PITCH, PIN_TOP_MARGIN, PORT_RADIUS, ROUTE_HIT_MARGIN},
    rename_pin::{Field, RenamePin},
    shape::{BaseShape, PinLocation, ShapeId, pin::PinSide},
    theme::{Role, Style},
    tool::Transition,
    widget::drawing::Drawing,
};
use blockworx_paint::{AnimKey, Canvas, Event, Interaction, Renderer};
// The grab-handle affordance itself — resting size, grow range, grow time —
// is the render layer's, which draws the resize handles to match.
use crate::render::HANDLE_GRAB;
pub(crate) use crate::render::{NEW_PIN_ANIM_TIME, NEW_PIN_GROW_RANGE, NEW_PIN_INACTIVE_SCALE};

/// How near the cursor must be for a marker's resting dot to appear.
pub(crate) const NEW_PIN_ACTIVATION_RANGE: WorldPx = WorldPx::new(3.0 * GRID_SIZE);
/// How near the pointer must come to a free slot's marker for a press to
/// place a pin there.
///
/// The user asked for it as wide as it will go: *"Increase the hit radius on
/// the 'add pin' affordance around the blocks. Make it as large as possible
/// without overlapping other affordances (I assume that it should be at
/// least 1 grid unit in radius)."* So it is not a number written down here —
/// it is the smallest clearance the neighbouring affordances leave, computed
/// from *their* own constants. Move a neighbour closer and this shrinks to
/// suit rather than silently starting to overlap it.
pub(crate) fn new_pin_grab() -> WorldPx {
    WorldPx::new(clearances().into_iter().fold(f32::INFINITY, f32::min))
}

/// What each affordance around a free slot's marker leaves it: how big the
/// marker's disc may grow before it touches that neighbour's own.
fn clearances() -> [f32; 5] {
    [
        // The block body, which takes a press with no padding at all and is
        // exactly one grid cell in from the marker.
        GRID_SIZE,
        // The next free slot along the same edge carries a disc of this same
        // size, so the two meet half way.
        PIN_PITCH * 0.5,
        // The nearest resize handle sits on the corner — `PIN_TOP_MARGIN`
        // along the edge from the outermost slot, and `GRID_SIZE` in from
        // the marker — and grabs from `HANDLE_GRAB`.
        GRID_SIZE.hypot(PIN_TOP_MARGIN) - HANDLE_GRAB.get(),
        // An occupied neighbour a pitch away: the route-start ring, at the
        // radius a fingertip gets.
        PIN_PITCH - NEW_PIN_GROW_RANGE.get(),
        // and the region that neighbour's stub answers a route drag from.
        PIN_PITCH - (GRID_SIZE / 3.0 + ROUTE_HIT_MARGIN.get()),
    ]
}

/// One free slot's marker: the block a pin would be added to, the slot, and
/// the world point the new pin's connection will sit at.
#[derive(Clone, Copy, Debug)]
pub struct SlotMarker {
    pub block: BlockId,
    pub loc: PinLocation,
    pub center: Pos2,
}

/// Every free slot's marker on `block`, whether or not the block offers them.
pub fn markers_on(data: &Drawing, block: BlockId) -> Vec<SlotMarker> {
    let Some(shape) = data.block_shape(block) else {
        return Vec::new();
    };
    shape
        .new_pin_locations()
        .into_iter()
        .filter_map(|loc| {
            let edge = shape.pin_position(loc)?;
            let outward = match loc.side {
                PinSide::East => GRID_SIZE,
                PinSide::West => -GRID_SIZE,
            };
            Some(SlotMarker {
                block,
                loc,
                center: edge + vec2(outward, 0.0),
            })
        })
        .collect()
}

/// The markers `blocks` offer. A block offers none when nothing may be added
/// to it — a locked interface and a read-only session both mean that.
pub fn offered_markers(
    data: &Drawing,
    blocks: impl IntoIterator<Item = BlockId>,
) -> Vec<SlotMarker> {
    blocks
        .into_iter()
        .filter(|block| data.authoring_of(ShapeId::Rect(*block)) == Authoring::Offered)
        .flat_map(|block| markers_on(data, block))
        .collect()
}

/// The markers every block in the current scope offers.
pub fn markers_in_scope(data: &Drawing) -> Vec<SlotMarker> {
    offered_markers(data, data.current_blocks().map(|(block, _)| block))
}

/// The marker nearest `pos` within `NEW_PIN_ACTIVATION_RANGE`, if any. At most
/// one is ever active, so the markers never fight over the cursor.
fn active_marker(markers: &[SlotMarker], pos: Pos2) -> Option<usize> {
    markers
        .iter()
        .enumerate()
        .map(|(i, marker)| (i, marker.center.distance(pos)))
        .filter(|(_, d)| *d < NEW_PIN_ACTIVATION_RANGE.get())
        .min_by(|a, b| a.1.total_cmp(&b.1))
        .map(|(i, _)| i)
}

/// The marker a press at `pos` lands on: the active one, within the widest
/// grab its neighbours leave it — wider than the ring draws at, like every
/// other target on the canvas.
pub fn marker_at(markers: &[SlotMarker], pos: Pos2) -> Option<SlotMarker> {
    let marker = markers[active_marker(markers, pos)?];
    (pos.distance(marker.center) < new_pin_grab().get()).then_some(marker)
}

/// Add the pin `marker` offers and open its name for editing. `None` when the
/// block declines it, as a block locked since the marker was drawn does.
pub(crate) fn add_pin(data: &mut Drawing, marker: SlotMarker) -> Option<Transition> {
    let pin = data.add_named_pin(marker.block, marker.loc)?;
    Some(RenamePin::action(data, pin, Field::Name))
}

/// A `+` glyph centered at `center`, sized to the marker radius.
fn draw_plus<R: Renderer>(center: Pos2, radius: WorldPx, role: Role, painter: &mut Style<'_, R>) {
    let arm = radius.get() * 0.6;
    painter.line_segment(
        [center - vec2(arm, 0.0), center + vec2(arm, 0.0)],
        (2.0, role),
    );
    painter.line_segment(
        [center - vec2(0.0, arm), center + vec2(0.0, arm)],
        (2.0, role),
    );
}

/// One marker `t` of the way through growing: the resting dot fades out as
/// the ring and its `+` grow in, so it reads as the dot expanding into the
/// ring.
fn draw_marker<C: Canvas>(center: Pos2, t: f32, painter: &mut Style<'_, C>) {
    if t < 1.0 {
        painter.with_opacity(1.0 - t, |p| {
            p.circle_filled(
                center,
                PORT_RADIUS * NEW_PIN_INACTIVE_SCALE,
                Role::NewPinPreviewFill,
            );
        });
    }
    if t > 0.0 {
        let radius = PORT_RADIUS * (NEW_PIN_INACTIVE_SCALE + (1.0 - NEW_PIN_INACTIVE_SCALE) * t);
        painter.circle(
            center,
            radius,
            Role::Transparent,
            (2.0, Role::NewPinPreviewFill),
        );
        painter.with_opacity(t, |p| {
            draw_plus(center, PORT_RADIUS, Role::NewPinPreviewFill, p);
        });
    }
}

/// The animation key for one marker, keyed by block, side and slot so each
/// marker animates independently. `tag` keeps one tool's animation apart from
/// another's.
fn anim_key(tag: &'static str, marker: &SlotMarker) -> AnimKey {
    let slot = (marker.loc.offset / PIN_PITCH).round() as i32;
    AnimKey::of((tag, marker.block, marker.loc.side, slot))
}

/// Draw `markers` as buttons: the one nearest the hover grows its ring, and
/// the one a press holds down is drawn inverted — a filled disk with a light
/// `+` — and locks out the hover.
pub(crate) fn draw_markers<C: Canvas>(
    markers: &[SlotMarker],
    interaction: &Interaction,
    painter: &mut Style<'_, C>,
) {
    let held = interaction
        .press
        .and_then(|press| marker_at(markers, press.origin))
        .map(|marker| marker.center);
    let active = match (held, interaction.event) {
        (None, Some(Event::HoverAt(pos))) => active_marker(markers, pos),
        _ => None,
    };
    for (i, marker) in markers.iter().enumerate() {
        if Some(marker.center) == held {
            painter.circle_filled(marker.center, PORT_RADIUS, Role::NewPinPreviewFill);
            draw_plus(
                marker.center,
                PORT_RADIUS,
                Role::NewPinPreviewStroke,
                painter,
            );
            continue;
        }
        let goal = if active == Some(i) { 1.0 } else { 0.0 };
        let t = painter.animate(anim_key("new_pin_target", marker), goal, NEW_PIN_ANIM_TIME);
        draw_marker(marker.center, t, painter);
    }
}

/// The block whose markers the route tool shows with the pointer at `pos`:
/// the one owning the nearest marker in range, so the cursor is never crowded
/// by several blocks' markers.
pub(crate) fn nearest_block_markers(markers: &[SlotMarker], pos: Pos2) -> Vec<SlotMarker> {
    let Some(nearest) = active_marker(markers, pos) else {
        return Vec::new();
    };
    let block = markers[nearest].block;
    markers
        .iter()
        .filter(|marker| marker.block == block)
        .copied()
        .collect()
}

/// Draw the route tool's markers and return the one armed — grown to the
/// full control — if any. A marker's resting dot appears once the pointer is
/// within `NEW_PIN_ACTIVATION_RANGE`; the nearest grows into the ring once the
/// pointer is within `NEW_PIN_GROW_RANGE`.
pub(crate) fn draw_route_markers<C: Canvas>(
    markers: &[SlotMarker],
    pointer: Pos2,
    painter: &mut Style<'_, C>,
) -> Option<SlotMarker> {
    let nearest = active_marker(markers, pointer);
    let mut armed = None;
    for (i, marker) in markers.iter().enumerate() {
        let key = anim_key("route_new_pin_target", marker);
        let dist = pointer.distance(marker.center);
        if dist >= NEW_PIN_ACTIVATION_RANGE.get() {
            // Keep the animation settled while the dot is hidden so it doesn't
            // pop on re-approach.
            painter.animate(key, 0.0, NEW_PIN_ANIM_TIME);
            continue;
        }
        let active = nearest == Some(i) && dist < NEW_PIN_GROW_RANGE.get();
        if active {
            armed = Some(*marker);
        }
        let t = painter.animate(key, if active { 1.0 } else { 0.0 }, NEW_PIN_ANIM_TIME);
        draw_marker(marker.center, t, painter);
    }
    armed
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::path::Scope;
    use crate::widget::{
        drawing::Drawing,
        test_fixtures::{self as fx, Scene},
    };
    use blockworx_doc::fixtures::block_id;
    use blockworx_geom::{Rect, pos2};

    /// A bare 300×300 block: every slot on both of its edges is free.
    fn scene_300() -> Scene {
        Scene::new(vec![
            fx::block_in(
                1,
                Scope::Root,
                Rect::from_min_max(pos2(0.0, 0.0), pos2(300.0, 300.0)),
            ),
            fx::titled(1, "b"),
        ])
    }

    /// The scene's lone block's outline and markers.
    fn block_300(drawing: &Drawing<'_>) -> (Rect, Vec<SlotMarker>) {
        let bbox = drawing
            .block_shape(block_id(1))
            .expect("the block is in this scope")
            .gui_rect();
        (bbox, markers_on(drawing, block_id(1)))
    }

    /// The property the user asked for: as large as it can be without
    /// overlapping a neighbour, and at least one grid unit.
    #[test]
    fn the_add_pin_grab_is_the_widest_radius_its_neighbours_leave_it() {
        let grab = new_pin_grab().get();
        assert!(
            grab >= GRID_SIZE,
            "the grab is under a grid unit: {grab} against {GRID_SIZE}",
        );
        assert!(
            grab > PORT_RADIUS.get(),
            "precondition: the grab is wider than the ring it draws \
             ({grab} against {})",
            PORT_RADIUS.get(),
        );
        for (n, clearance) in clearances().into_iter().enumerate() {
            assert!(
                grab <= clearance,
                "the grab of {grab} overlaps neighbour {n}, which leaves {clearance}",
            );
        }
        assert!(
            clearances().into_iter().any(|room| room == grab),
            "the grab is smaller than every clearance, so it is not maximal: \
             {grab} against {:?}",
            clearances(),
        );
    }

    /// The same property against real geometry rather than against the
    /// arithmetic that produced it: on a laid-out block, the outermost
    /// marker's grab reaches neither the corner handle beside it, nor the
    /// next slot's, nor inside the block.
    #[test]
    fn the_add_pin_grab_touches_nothing_on_a_real_block() {
        let mut scene = scene_300();
        let drawing = scene.drawing();
        let (bbox, markers) = block_300(&drawing);
        let grab = new_pin_grab().get();
        let east: Vec<Pos2> = markers
            .into_iter()
            .filter(|marker| marker.loc.side == PinSide::East)
            .map(|marker| marker.center)
            .collect();
        assert!(
            east.len() >= 2,
            "precondition: the block has two free slots to crowd each other",
        );

        for at in &east {
            assert!(
                at.x - grab >= bbox.right() - 1e-3,
                "the marker's grab reaches inside the block: {at:?} against {bbox:?}",
            );
            for corner in [bbox.right_top(), bbox.right_bottom()] {
                assert!(
                    at.distance(corner) >= grab + HANDLE_GRAB.get() - 1e-3,
                    "the marker at {at:?} overlaps the resize handle at {corner:?}",
                );
            }
        }
        for pair in east.windows(2) {
            assert!(
                pair[0].distance(pair[1]) >= 2.0 * grab - 1e-3,
                "two markers' grabs overlap: {:?} and {:?}",
                pair[0],
                pair[1],
            );
        }
    }

    #[test]
    fn new_pin_targets_sit_one_grid_cell_outside_each_edge() {
        let mut scene = scene_300();
        let drawing = scene.drawing();
        let (bbox, markers) = block_300(&drawing);
        assert!(!markers.is_empty());

        let (mut west, mut east) = (0, 0);
        for SlotMarker { loc, center: p, .. } in &markers {
            match loc.side {
                PinSide::West => {
                    assert!((p.x - (bbox.left() - GRID_SIZE)).abs() < 1e-3);
                    west += 1;
                }
                PinSide::East => {
                    assert!((p.x - (bbox.right() + GRID_SIZE)).abs() < 1e-3);
                    east += 1;
                }
            }
        }
        // A fresh block has free slots on both sides.
        assert!(west > 0 && east > 0);
    }

    #[test]
    fn the_active_marker_is_the_nearest_within_range_else_none() {
        let mut scene = scene_300();
        let drawing = scene.drawing();
        let (_, markers) = block_300(&drawing);

        // A query right on a marker activates exactly that marker.
        let first = markers[0].center;
        assert_eq!(active_marker(&markers, first), Some(0));

        // Just inside the range of the first marker (but nearer to it than any
        // other) still selects it.
        let near = first + vec2(NEW_PIN_ACTIVATION_RANGE.get() * 0.5, 0.0);
        assert_eq!(active_marker(&markers, near), Some(0));

        // Far beyond every marker's activation range → nothing is active.
        let far = pos2(10_000.0, 10_000.0);
        assert_eq!(active_marker(&markers, far), None);
    }

    /// A locked block keeps its pin interface frozen, so it offers no
    /// markers even though its slots are free.
    #[test]
    fn a_locked_block_offers_no_markers() {
        let mut scene = scene_300();
        assert!(
            !offered_markers(&scene.drawing(), [block_id(1)]).is_empty(),
            "precondition: the unlocked block offers markers",
        );
        scene.apply(vec![fx::locked(1)]);
        let drawing = scene.drawing();
        assert!(
            !markers_on(&drawing, block_id(1)).is_empty(),
            "precondition: the locked block still has free slots",
        );
        assert!(offered_markers(&drawing, [block_id(1)]).is_empty());
        assert!(markers_in_scope(&drawing).is_empty());
    }
}