blockworx_geom/

grid.rs

//! The grid: the pitch, the snapping ladder, the screen-mapping constants every
//! shape is measured against, and the bridge to the document's own integer
//! geometry.
//!
//! This module is the scalar half — one axis at a time, no document type
//! involved. The typed half converts whole points, vectors and rects; it is
//! re-exported here so a call site reads one namespace.

mod bridge;

pub use bridge::{
    artwork_rect, grid_point, grid_rect, grid_size_ceil, grid_vec, px_point, px_rect, px_vec,
    screen_rect,
};

use crate::{Pos2, Rect, Vec2, WorldPx, pos2};

pub const GRID_SIZE: f32 = 15.0;

/// Maximum length of a short on-canvas label (pin name and its two lines, block
/// or area title, pin/block tag, route label). The rename editors enforce
/// this so an accidental paste of a long string can't break the canvas layout.
pub const MAX_LABEL_CHARS: usize = 32;
/// Maximum length of a pin's short "location" designator (its `tag`, e.g. "A1").
/// Tighter than [`MAX_LABEL_CHARS`] since it's a compact label drawn above the stub.
pub const MAX_LOCATION_CHARS: usize = 8;
/// Maximum length of a free-floating text box. Much larger than a label since a
/// text box is a paragraph annotation, but still bounded so an accidental paste
/// of a huge string can't blow up the layout.
pub const MAX_TEXT_BOX_CHARS: usize = 2000;
pub const SHIM: f32 = GRID_SIZE * 0.7;
/// Padding between a multi-selection's contents and the group frame drawn around
/// them, so the frame sits clear of the shapes' own edges rather than hugging them.
pub const GROUP_SELECTION_PAD: f32 = GRID_SIZE * 1.5;
pub const RESIZE_SHIM: f32 = GRID_SIZE / 4.0;
pub const MOVE_HOVER_DISTANCE: f32 = GRID_SIZE * 0.8;
pub const PORT_RADIUS: WorldPx = WorldPx::new(GRID_SIZE * 0.3);
/// Larger radius used for hit-testing interactive control points (ports,
/// waypoints, resize handles). Intentionally bigger than `PORT_RADIUS` so
/// targets are easier to click without changing how they look.
pub const HIT_RADIUS: WorldPx = WorldPx::new(GRID_SIZE * 0.6);
/// Generous margin for snapping a route to a pin: the cursor registers anywhere
/// near the pin's stub or its end, not just on the connection point. Kept just
/// under half a [`PIN_PITCH`] so adjacent pins stay distinct.
pub const ROUTE_HIT_MARGIN: WorldPx = WorldPx::new(GRID_SIZE * 0.9);
pub const LINE_RADIUS: f32 = GRID_SIZE * 0.7;
pub const TITLE_TEXT_SIZE: f32 = GRID_SIZE * 1.0;
/// A block's type label, drawn slightly smaller than its title.
pub const BLOCK_TYPE_TEXT_SIZE: f32 = GRID_SIZE * 0.85;
pub const PORT_TEXT_SIZE: f32 = GRID_SIZE * 0.9;
pub const ROUTE_TEXT_SIZE: f32 = GRID_SIZE * 0.8;
pub const TAG_TEXT_SIZE: f32 = GRID_SIZE * 0.75;
/// Subtitle (second line) of a pin/port name. Slightly smaller than the name.
pub const PORT_SUBTITLE_TEXT_SIZE: f32 = GRID_SIZE * 0.6;
/// Horizontal gap between a block/port edge and the start of its tag label.
pub const TAG_SHIM: f32 = GRID_SIZE * 0.25;
/// Vertical nudge applied to the pin's type label, which is otherwise centered
/// one [`GRID_SIZE`] below the name. Zero keeps it centered exactly a grid cell
/// below the stub; the wider pin pitch leaves room for the full gap.
pub const TYPE_SHIM_Y: f32 = 0.0;
pub const PORT_RENDER_HEIGHT: f32 = GRID_SIZE * 2.2;

/// Side length of the passive "locked" padlock hint drawn in a selected locked
/// block's upper-right corner. Grid-relative and small so it reads as a hint.
pub const LOCK_HINT_SIZE: f32 = GRID_SIZE * 0.8;

/// Stroke width of a block/port outline, in world units. The single source of
/// truth shared by the frame (`draw_block_frame`) and the pins that butt against
/// it: a pin stub stops half this width outside the bbox edge so it meets the
/// outline's outer face instead of crossing into it.
pub const BLOCK_STROKE_WIDTH: f32 = 1.0;

/// Vertical space a pin slot occupies, in grid units. Adjacent integer offsets
/// are this many grid units apart.
pub const PIN_PITCH_GRID: i32 = 3;

/// On-screen distance between consecutive pin slots.
pub const PIN_PITCH: f32 = GRID_SIZE * PIN_PITCH_GRID as f32;

/// Vertical margin from a block's top edge to its first pin slot, and the
/// matching clearance kept below the lowest slot. A whole number of grid cells,
/// kept independent of [`PIN_PITCH`] so the pitch may be odd: the first pin sits
/// this far down and pins are a full [`PIN_PITCH`] apart.
pub const PIN_TOP_MARGIN: f32 = GRID_SIZE * 2.0;

/// When a block is expanded into its own view, its boundary ports are laid out
/// to mirror the parent's pin arrangement, magnified by this factor so there is
/// room to place interior child blocks between them.
pub const DEFAULT_SCALE_FOR_NEW_VIEW: i32 = 4;

/// A grid cell in the `x,y` spelling scripts use: the cell nearest a world
/// position.
#[derive(Clone, Copy, PartialEq, Eq, Debug, serde::Serialize, serde::Deserialize)]
pub struct GridCell {
    pub x: i32,
    pub y: i32,
}

impl GridCell {
    pub fn at(world: Pos2) -> Self {
        Self {
            x: (world.x / GRID_SIZE).round() as i32,
            y: (world.y / GRID_SIZE).round() as i32,
        }
    }
}

impl std::fmt::Display for GridCell {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        write!(f, "{},{}", self.x, self.y)
    }
}

pub fn snap_to_grid(pos: Pos2) -> Pos2 {
    Pos2::new(round_to_grid(pos.x), round_to_grid(pos.y))
}

/// Grid-snap a translation `delta` (the vector form of [`snap_to_grid`]), used to
/// round a drag offset to whole grid steps.
pub fn snap_offset(delta: Vec2) -> Vec2 {
    snap_to_grid(delta.to_pos2()).to_vec2()
}

pub fn round_to_grid(value: f32) -> f32 {
    (value / GRID_SIZE).round() * GRID_SIZE
}

/// Screen y of pin slot `offset` within a shape whose top edge is at `top`.
/// `offset` is a plain contiguous integer index; the pitch lives here, not in
/// the stored value. The first slot sits a [`PIN_TOP_MARGIN`] below the top edge;
/// each further slot is one [`PIN_PITCH`] down.
pub fn pin_offset_y(top: f32, offset: u32) -> f32 {
    top + PIN_TOP_MARGIN + PIN_PITCH * offset as f32
}

/// [`pin_offset_y`] in whole grid cells: the row slot `offset` sits on in a
/// shape whose top edge is at cell `top`. The document's own geometry is
/// integer, so a reader that stays in grid space never crosses through
/// pixels to place a pin.
pub fn pin_slot_row(top: i32, offset: u32) -> i32 {
    top + grid_i32(pin_offset_y(0.0, offset))
}

/// Round a pixel offset to the nearest pin slot, in pixels.
pub fn round_to_pitch(value: f32) -> f32 {
    (value / PIN_PITCH).round() * PIN_PITCH
}

/// Pixel offset (`slot * PIN_PITCH`) → slot index.
pub fn pin_slot(px: f32) -> u32 {
    (px / PIN_PITCH).round().max(0.0) as u32
}

/// The largest pin slot that fits within a shape of the given `height` while
/// keeping at least a [`PIN_TOP_MARGIN`] of clearance below it. Slot `s` sits at
/// [`pin_offset_y`] = `top + PIN_TOP_MARGIN + PIN_PITCH * s`, so the lowest slot
/// leaving a `PIN_TOP_MARGIN` above the bottom edge is `floor((height - 2 *
/// PIN_TOP_MARGIN) / PIN_PITCH)`. This is the bound that bounds-checks pin
/// placement (see `Block::new_pin_locations`).
pub fn max_pin_slot(height: f32) -> u32 {
    (((height - 2.0 * PIN_TOP_MARGIN) / PIN_PITCH).floor() as i32).max(0) as u32
}

/// A block's height is constrained to `2 * PIN_TOP_MARGIN + h * PIN_PITCH` for an
/// unsigned `h`: a [`PIN_TOP_MARGIN`] above the top pin slot and below the bottom
/// one, plus one [`PIN_PITCH`] per added slot. So a height-`h` block holds `h + 1`
/// pins, at offsets `0..=h` (and `max_pin_slot` of this height is exactly `h`).
/// This rounds a raw pixel height to the nearest such valid height, floored at the
/// `h = 0` minimum of `2 * PIN_TOP_MARGIN`.
pub fn snap_block_height(height_px: f32) -> f32 {
    let slots = ((height_px - 2.0 * PIN_TOP_MARGIN) / PIN_PITCH)
        .round()
        .max(0.0);
    2.0 * PIN_TOP_MARGIN + slots * PIN_PITCH
}

/// [`snap_block_height`] expressed in whole grid cells — the form a block's
/// `inner.size.h` stores. The minimum is 4 cells (`2 * PIN_TOP_MARGIN`) and each
/// added slot adds [`PIN_PITCH_GRID`] cells: one of `4, 7, 10, …`.
pub fn snap_block_height_cells(cells: u32) -> u32 {
    (snap_block_height(cells as f32 * GRID_SIZE) / GRID_SIZE).round() as u32
}

/// The smallest whole grid width that still holds `width_px`. A resize floor has
/// to be expressed on the lattice the drop snaps to, or the snap rounds back
/// through it.
pub fn ceil_to_grid(width_px: f32) -> f32 {
    (width_px / GRID_SIZE).ceil().max(0.0) * GRID_SIZE
}

/// The smallest valid block height (see [`snap_block_height`]) that still holds
/// `height_px` — the height counterpart of [`ceil_to_grid`].
pub fn ceil_block_height(height_px: f32) -> f32 {
    let slots = ((height_px - 2.0 * PIN_TOP_MARGIN) / PIN_PITCH)
        .ceil()
        .max(0.0);
    2.0 * PIN_TOP_MARGIN + slots * PIN_PITCH
}

/// A world-space rect with both corners snapped to the grid.
pub fn snap_rect(rect: Rect) -> Rect {
    Rect::from_min_max(
        snap_to_grid(pos2(rect.min.x, rect.min.y)),
        snap_to_grid(pos2(rect.max.x, rect.max.y)),
    )
}

// --- Cell ↔ pixel scalars -----------------------------------------------------

pub fn px(grid: i32) -> f32 {
    grid as f32 * GRID_SIZE
}

/// The world-space position of a grid cell's corner, for the places that
/// author canvas coordinates in whole cells.
pub fn grid_pos(x: i32, y: i32) -> Pos2 {
    pos2(px(x), px(y))
}

pub fn px_u(grid: u32) -> f32 {
    grid as f32 * GRID_SIZE
}

pub fn grid_i32(px: f32) -> i32 {
    (px / GRID_SIZE).round() as i32
}

pub fn grid_u32(px: f32) -> u32 {
    (px / GRID_SIZE).round().max(0.0) as u32
}

/// A world-space extent in whole grid cells, rounded *up* so the cell count
/// always fully encloses the extent, and clamped to at least one cell per
/// axis.
pub fn grid_u32_ceil(px: f32) -> u32 {
    (px / GRID_SIZE).ceil().max(1.0) as u32
}

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

    #[test]
    fn round_to_pitch_snaps_to_nearest_slot() {
        assert_eq!(round_to_pitch(0.0), 0.0);
        assert_eq!(round_to_pitch(PIN_PITCH * 0.4), 0.0); // < half a pitch
        assert_eq!(round_to_pitch(PIN_PITCH * 0.6), PIN_PITCH); // > half a pitch
        assert_eq!(round_to_pitch(PIN_PITCH * 3.0 + 2.0), PIN_PITCH * 3.0);
    }

    #[test]
    fn pin_slot_inverts_the_pitch_mapping() {
        assert_eq!(pin_slot(0.0), 0);
        assert_eq!(pin_slot(PIN_PITCH), 1);
        assert_eq!(pin_slot(PIN_PITCH * 4.0), 4);
        assert_eq!(pin_slot(-5.0), 0); // clamped
    }

    #[test]
    fn max_pin_slot_reserves_a_top_margin_below_the_lowest_slot() {
        // floor((height - 2 * PIN_TOP_MARGIN) / PIN_PITCH).
        let h = |slots: f32| 2.0 * PIN_TOP_MARGIN + slots * PIN_PITCH;
        assert_eq!(max_pin_slot(h(9.0)), 9); // floor(9.0)
        assert_eq!(max_pin_slot(h(1.5)), 1); // floor(1.5)
        assert_eq!(max_pin_slot(h(0.0)), 0); // floor(0)
        assert_eq!(max_pin_slot(h(-0.5)), 0); // clamped, never negative

        // The lowest offered slot keeps at least a PIN_TOP_MARGIN above the bottom.
        let height = h(9.0);
        let lowest_pin_y = pin_offset_y(0.0, max_pin_slot(height));
        assert!(height - lowest_pin_y >= PIN_TOP_MARGIN);
    }

    #[test]
    fn snap_block_height_rounds_to_a_valid_block_height() {
        // Valid heights are 2 * PIN_TOP_MARGIN + h * PIN_PITCH (h >= 0).
        let h = |slots: f32| 2.0 * PIN_TOP_MARGIN + slots * PIN_PITCH;
        assert_eq!(snap_block_height(h(0.0)), h(0.0)); // h = 0, the floor
        assert_eq!(snap_block_height(h(0.4)), h(0.0)); // rounds down
        assert_eq!(snap_block_height(h(0.6)), h(1.0)); // rounds up
        assert_eq!(snap_block_height(0.0), h(0.0)); // floored at the minimum
        assert_eq!(snap_block_height_cells(1), 4); // 4 grid cells minimum
        assert_eq!(snap_block_height_cells(5), 4); // nearest valid (75px -> 60px)
        assert_eq!(snap_block_height_cells(19), 19); // already valid (285px)
        // The ceilings never round *through* their input, unlike the snaps above.
        assert_eq!(ceil_to_grid(GRID_SIZE * 2.0), GRID_SIZE * 2.0);
        assert_eq!(ceil_to_grid(GRID_SIZE * 2.0 + 0.1), GRID_SIZE * 3.0);
        assert_eq!(ceil_block_height(h(1.0)), h(1.0));
        assert_eq!(ceil_block_height(h(1.0) + 0.1), h(2.0));
        assert_eq!(ceil_block_height(0.0), h(0.0));
    }

    #[test]
    fn a_height_h_block_holds_h_plus_one_pins() {
        // height 2 * PIN_TOP_MARGIN + h * PIN_PITCH => max_pin_slot == h => pins 0..=h.
        for h in 0..6u32 {
            let height = 2.0 * PIN_TOP_MARGIN + h as f32 * PIN_PITCH;
            assert_eq!(
                snap_block_height(height),
                height,
                "h={h} not a valid height"
            );
            assert_eq!(max_pin_slot(height), h, "h={h} wrong capacity");
        }
    }

    #[test]
    fn pin_offset_y_uses_the_pitch() {
        // top + PIN_TOP_MARGIN + PIN_PITCH * offset: a leading top margin.
        assert_eq!(pin_offset_y(0.0, 0), PIN_TOP_MARGIN);
        assert_eq!(pin_offset_y(0.0, 1), PIN_TOP_MARGIN + PIN_PITCH);
        assert_eq!(
            pin_offset_y(100.0, 2),
            100.0 + PIN_TOP_MARGIN + 2.0 * PIN_PITCH
        );
    }

    #[test]
    fn the_slot_row_is_the_pixel_offset_in_cells() {
        assert_eq!(pin_slot_row(0, 0), grid_i32(PIN_TOP_MARGIN));
        assert_eq!(pin_slot_row(0, 1), grid_i32(PIN_TOP_MARGIN + PIN_PITCH));
        assert_eq!(pin_slot_row(7, 2), 7 + grid_i32(pin_offset_y(0.0, 2)));
    }
}