blockworx/tools/

new_pin.rs

//! Shared "new-pin target" primitives.
//!
//! 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 (within `NEW_PIN_ACTIVATION_RANGE`) animates into a blue
//! ring that grows out to `PORT_RADIUS`.
//!
//! The *resize* tool uses these markers as click/drag buttons to add a pin to
//! the selected block. The *route* tool reuses them (see
//! [`draw_route_new_pin_targets`]) to let an in-progress route terminate on a
//! pin that doesn't exist yet.

use std::time::Duration;

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

use crate::progress::Progress;
use crate::{
    grid::{GRID_SIZE, HIT_RADIUS, PIN_PITCH, PIN_TOP_MARGIN, PORT_RADIUS, ROUTE_HIT_MARGIN},
    shape::{BaseShape, BlockShape, PinLocation, pin::PinSide},
    theme::{Role, Style},
};
use blockworx_paint::{AnimKey, Canvas, Renderer};
// The grab-handle affordance itself — resting size, grow range, grow time —
// is the render layer's, which draws the resize handles to match.
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 `HIT_RADIUS`.
        GRID_SIZE.hypot(PIN_TOP_MARGIN) - HIT_RADIUS.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()),
    ]
}

/// How far the drag-to-route hint's ghost circle drifts from the marker per loop.
pub(crate) const HINT_DRIFT: f32 = 2.0 * GRID_SIZE;
/// Loop period of the drag-to-route hint.
pub(crate) const HINT_PERIOD: Duration = Duration::from_millis(900);
/// How far the pointer must pull outward off a pressed target — in the pin's own
/// direction — to commit to starting a route (rather than adding/selecting on
/// release). Deliberately more than a jittery hold so the hint stays visible.
pub(crate) const HINT_ROUTE_THRESHOLD: WorldPx = WorldPx::new(1.5 * GRID_SIZE);

/// The drag-to-route hint's free-running loop phase at frame clock `now` (see
/// [`Canvas::now`]). The caller must `request_repaint` each frame the hint is
/// shown to keep it moving.
pub(crate) fn route_hint_phase(now: Duration) -> Progress {
    Progress::new((now.as_secs_f64() / HINT_PERIOD.as_secs_f64()).rem_euclid(1.0) as f32)
}

/// Each free slot's location paired with the world point one grid cell outside the
/// block edge — where the new pin's connection point will sit.
pub(crate) fn new_pin_targets(block: &BlockShape<'_>) -> Vec<(PinLocation, Pos2)> {
    block
        .new_pin_locations()
        .into_iter()
        .filter_map(|loc| {
            let edge = block.pin_position(loc)?;
            let outward = match loc.side {
                PinSide::East => GRID_SIZE,
                PinSide::West => -GRID_SIZE,
            };
            Some((loc, edge + vec2(outward, 0.0)))
        })
        .collect()
}

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

/// A `+` glyph centered at `center`, sized to the marker radius.
pub(crate) 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),
    );
}

/// The ghost circle's offset from a pressed marker at loop `phase` (0..1): it
/// drifts outward along the pin's side, the way a drag would carry a new route.
pub(crate) fn hint_offset(side: PinSide, phase: f32) -> Vec2 {
    let outward = match side {
        PinSide::East => 1.0,
        PinSide::West => -1.0,
    };
    vec2(outward * phase * HINT_DRIFT, 0.0)
}

/// Number of ghost circles in the drag-to-route hint's outward stream.
const HINT_GHOSTS: usize = 3;

/// The drag-to-route discoverability hint, drawn at a *pressed* new-pin marker: a
/// steady stream of ghost circles flows away from the `+` (each fading in then out)
/// toward a static arrowhead pointing the way, colored as a route-start target so
/// it reads as "drag here to start a route". Staggering several circles keeps one
/// always mid-flight, so the motion reads as continuous. Purely visual.
pub(crate) fn draw_route_hint<C: Canvas>(
    center: Pos2,
    side: PinSide,
    phase: Progress,
    painter: &mut Style<'_, C>,
) {
    let outward = match side {
        PinSide::East => 1.0,
        PinSide::West => -1.0,
    };
    // A steady arrowhead at the drift end points the way.
    let tip = center + vec2(outward * (HINT_DRIFT + PORT_RADIUS.get()), 0.0);
    let barb = PORT_RADIUS.get() * 0.7;
    painter.line_segment(
        [tip, tip - vec2(outward * barb, barb)],
        (2.0, Role::RouteStartTarget),
    );
    painter.line_segment(
        [tip, tip - vec2(outward * barb, -barb)],
        (2.0, Role::RouteStartTarget),
    );
    // The flowing stream: circles evenly staggered along the loop, each drifting
    // out and fading as it goes.
    for k in 0..HINT_GHOSTS {
        let p = (phase.get() + k as f32 / HINT_GHOSTS as f32).fract();
        let ghost = center + hint_offset(side, p);
        let opacity = (p * std::f32::consts::PI).sin();
        painter.with_opacity(opacity, |painter| {
            painter.circle_filled(ghost, PORT_RADIUS * 0.55, Role::RouteStartTarget);
        });
    }
}

/// The animation key for one block's resize-tool marker, keyed by slot + side
/// so each marker animates independently.
pub(crate) fn target_anim_key(rid: BlockId, loc: PinLocation) -> AnimKey {
    let slot = (loc.offset / PIN_PITCH).round() as i32;
    AnimKey::of(("new_pin_target", rid, loc.side, slot))
}

/// The animation key for the route tool's marker. A distinct tag from
/// [`target_anim_key`] keeps the two tools' animations independent.
fn route_target_anim_key(rid: BlockId, loc: PinLocation) -> AnimKey {
    let slot = (loc.offset / PIN_PITCH).round() as i32;
    AnimKey::of(("route_new_pin_target", rid, loc.side, slot))
}

/// Draw `block`'s new-pin markers for the route tool and return the one currently
/// armed (grown to the full control), if any. A target's resting dot appears once
/// the pointer is within `NEW_PIN_ACTIVATION_RANGE`; the nearest target grows into
/// the ring + plus control once the pointer is within `NEW_PIN_GROW_RANGE`.
pub(crate) fn draw_route_new_pin_targets<C: Canvas>(
    rid: BlockId,
    targets: &[(PinLocation, Pos2)],
    pointer: Option<Pos2>,
    painter: &mut Style<'_, C>,
) -> Option<(PinLocation, Pos2)> {
    let nearest = pointer.and_then(|p| active_new_pin_target(targets, p));
    let mut armed = None;
    for (i, (loc, center)) in targets.iter().enumerate() {
        let dist = pointer.map(|p| p.distance(*center));
        if !dist.is_some_and(|d| d < NEW_PIN_ACTIVATION_RANGE.get()) {
            // Keep the animation settled while the dot is hidden so it doesn't
            // pop on re-approach.
            painter.animate(route_target_anim_key(rid, *loc), 0.0, NEW_PIN_ANIM_TIME);
            continue;
        }
        let active = nearest == Some(i) && dist.is_some_and(|d| d < NEW_PIN_GROW_RANGE.get());
        if active {
            armed = Some((*loc, *center));
        }
        let goal = if active { 1.0 } else { 0.0 };
        let t = painter.animate(route_target_anim_key(rid, *loc), goal, NEW_PIN_ANIM_TIME);
        // The resting dot fades out as the ring grows in, so it reads as the dot
        // expanding into the ring.
        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);
            });
        }
    }
    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, as the geometry layer sees it.
    fn block_300<'a>(drawing: &'a Drawing<'_>) -> BlockShape<'a> {
        drawing
            .block_shape(block_id(1))
            .expect("the block is in this scope")
    }

    /// R34, stated as 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 block = block_300(&drawing);
        let bbox = block.gui_rect();
        let grab = new_pin_grab().get();
        let east: Vec<Pos2> = new_pin_targets(&block)
            .into_iter()
            .filter(|(loc, _)| loc.side == PinSide::East)
            .map(|(_, at)| at)
            .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 + HIT_RADIUS.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 block = block_300(&drawing);
        let bbox = block.gui_rect();
        let targets = new_pin_targets(&block);
        assert!(!targets.is_empty());

        let (mut west, mut east) = (0, 0);
        for (loc, p) in &targets {
            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 active_new_pin_target_is_the_nearest_within_range_else_none() {
        let mut scene = scene_300();
        let drawing = scene.drawing();
        let targets = new_pin_targets(&block_300(&drawing));

        // A query right on a target activates exactly that target.
        let (_, first) = targets[0];
        assert_eq!(active_new_pin_target(&targets, first), Some(0));

        // Just inside the range of the first target (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_new_pin_target(&targets, near), Some(0));

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

    #[test]
    fn hint_offset_drifts_outward_along_the_pin_side() {
        // No drift at the loop start; the ghost begins on the marker.
        assert_eq!(hint_offset(PinSide::East, 0.0), vec2(0.0, 0.0));
        // East drifts right (+x), West drifts left (-x); always horizontal.
        assert!(hint_offset(PinSide::East, 0.5).x > 0.0);
        assert!(hint_offset(PinSide::West, 0.5).x < 0.0);
        assert_eq!(hint_offset(PinSide::East, 0.5).y, 0.0);
        // Magnitude grows with phase and is bounded by one full drift.
        assert!(hint_offset(PinSide::East, 0.9).x > hint_offset(PinSide::East, 0.4).x);
        assert_eq!(hint_offset(PinSide::East, 1.0).x, HINT_DRIFT);
        assert_eq!(hint_offset(PinSide::West, 1.0).x, -HINT_DRIFT);
    }
}