mermaid-text 0.41.0

//! Renderer for [`BlockDiagram`]. Produces a fixed-width grid of Unicode boxes
//! with a text edge summary below.
//!
//! ## Layout
//!
//! Blocks are laid out in a grid. Each column is sized to the widest block
//! label that falls into it (a spanning block's label is spread across its
//! columns). The grid is rendered with Unicode box-drawing corners and
//! horizontal/vertical rules.
//!
//! Example for `columns 3`, blocks A, B (span 2), C:
//!
//! ```text
//! ┌───┐ ┌───────┐ ┌───┐
//! │ A │ │   B   │ │ C │
//! └───┘ └───────┘ └───┘
//! ```
//!
//! Edges are listed as a text summary below the grid:
//!
//! ```text
//! Edges:
//!   A ──► B
//!   B ──► C
//! ```
//!
//! ## max_width
//!
//! When `max_width` is `Some(n)`, block label text is truncated with `…` so
//! that the total grid width does not exceed the budget. The edge summary is
//! not truncated.
//!
//! ## Phase 1 limitations
//!
//! - Only rectangle-shaped blocks are rendered; all shape variants are normalised
//!   to plain rectangular boxes.
//! - Nested blocks are not rendered (they are ignored by the parser).
//! - Vertical spanning (multi-row blocks) is not supported.
//! - Edge labels appear in the text summary only — no inline arrow decoration
//!   on the grid itself.
//! - Close-together points in the grid are separated by a single space column;
//!   very long labels may slightly exceed `max_width` when `max_width` is tight.

use unicode_width::UnicodeWidthStr;

use crate::block_diagram::{Block, BlockDiagram, BlockEdge};

/// Number of spaces between adjacent column boxes.
const COL_GAP: usize = 1;

/// Minimum inner width (characters) for a single column cell.
const MIN_CELL_INNER: usize = 1;

/// Render a [`BlockDiagram`] to a Unicode string.
///
/// # Arguments
///
/// * `diag`      — the parsed diagram
/// * `max_width` — optional column budget; block labels are truncated with `…`
///   when the natural grid exceeds this budget
///
/// # Returns
///
/// A multi-line string ready for printing. The grid uses Unicode box-drawing
/// characters (`┌ ─ ┐ │ └ ┘`) with blocks separated by single-space gaps.
/// Spanning blocks merge their column widths and the gap between them.
/// A directed-edge summary is appended below the grid when edges are present.
pub fn render(diag: &BlockDiagram, max_width: Option<usize>) -> String {
    // Edge case: no blocks — emit just the edge summary (if any).
    if diag.blocks.is_empty() {
        return render_edge_summary(&diag.edges);
    }

    let cols = diag.columns.max(1);

    // Assign each block to grid cells (row, col_start, col_end).
    let grid_placements = compute_placements(&diag.blocks, cols);

    // Compute the natural inner width of each column.
    let col_inner_widths = compute_col_widths(&diag.blocks, &grid_placements, cols);

    // Apply max_width budget by truncating column widths if necessary.
    let col_inner_widths = apply_max_width(col_inner_widths, max_width, cols);

    // Determine how many rows the grid has.
    let row_count = grid_placements.iter().map(|p| p.row + 1).max().unwrap_or(0);

    let mut out = String::new();

    // Render each row.
    for row in 0..row_count {
        // Collect the blocks that belong to this row, in column order.
        let mut row_blocks: Vec<(usize, usize, usize, &Block)> = grid_placements
            .iter()
            .filter(|p| p.row == row)
            .map(|p| {
                (
                    p.col_start,
                    p.col_end,
                    p.block_idx,
                    &diag.blocks[p.block_idx],
                )
            })
            .collect();
        row_blocks.sort_by_key(|&(col_start, _, _, _)| col_start);

        // ---- Top border line ----
        let mut top = String::new();
        let mut col_cursor = 0usize;
        for (col_start, col_end, _, _block) in &row_blocks {
            // Gap between previous block and this one.
            if *col_start > col_cursor {
                for _ in 0..((*col_start - col_cursor) * (MIN_CELL_INNER + 2 + COL_GAP)) {
                    top.push(' ');
                }
            }
            // Inner width = sum of spanned columns' inner widths + gaps between them.
            let inner_w = spanned_inner_width(&col_inner_widths, *col_start, *col_end);
            top.push('\u{250C}'); // ┌
            for _ in 0..inner_w + 2 {
                top.push('\u{2500}'); // ─
            }
            top.push('\u{2510}'); // ┐
            col_cursor = *col_end;
            // Add gap after block (unless it's the last block in the row).
            top.push_str(&" ".repeat(COL_GAP));
        }
        out.push_str(top.trim_end());
        out.push('\n');

        // ---- Content line ----
        let mut mid = String::new();
        col_cursor = 0;
        for (col_start, col_end, _, block) in &row_blocks {
            if *col_start > col_cursor {
                for _ in 0..((*col_start - col_cursor) * (MIN_CELL_INNER + 2 + COL_GAP)) {
                    mid.push(' ');
                }
            }
            let inner_w = spanned_inner_width(&col_inner_widths, *col_start, *col_end);
            let label = block.display_text();
            let label_w = UnicodeWidthStr::width(label);
            let label = if label_w > inner_w {
                truncate_to_width(label, inner_w)
            } else {
                label.to_string()
            };
            let label_w = UnicodeWidthStr::width(label.as_str());
            // Pad: 1 space left, then label centred, then fill to inner_w, 1 space right.
            let total_pad = inner_w.saturating_sub(label_w);
            let left_pad = total_pad / 2;
            let right_pad = total_pad - left_pad;
            mid.push('\u{2502}'); // │
            mid.push(' ');
            for _ in 0..left_pad {
                mid.push(' ');
            }
            mid.push_str(&label);
            for _ in 0..right_pad {
                mid.push(' ');
            }
            mid.push(' ');
            mid.push('\u{2502}'); // │
            col_cursor = *col_end;
            mid.push_str(&" ".repeat(COL_GAP));
        }
        out.push_str(mid.trim_end());
        out.push('\n');

        // ---- Bottom border line ----
        let mut bot = String::new();
        col_cursor = 0;
        for (col_start, col_end, _, _block) in &row_blocks {
            if *col_start > col_cursor {
                for _ in 0..((*col_start - col_cursor) * (MIN_CELL_INNER + 2 + COL_GAP)) {
                    bot.push(' ');
                }
            }
            let inner_w = spanned_inner_width(&col_inner_widths, *col_start, *col_end);
            bot.push('\u{2514}'); // └
            for _ in 0..inner_w + 2 {
                bot.push('\u{2500}'); // ─
            }
            bot.push('\u{2518}'); // ┘
            col_cursor = *col_end;
            bot.push_str(&" ".repeat(COL_GAP));
        }
        out.push_str(bot.trim_end());
        out.push('\n');

        // Blank line between rows for readability.
        if row + 1 < row_count {
            out.push('\n');
        }
    }

    // Append edge summary.
    let edge_part = render_edge_summary(&diag.edges);
    if !edge_part.is_empty() {
        out.push('\n');
        out.push_str(&edge_part);
    }

    // Trim trailing newlines.
    while out.ends_with('\n') {
        out.pop();
    }
    out
}

// ---------------------------------------------------------------------------
// Placement helpers
// ---------------------------------------------------------------------------

/// Grid placement for a single block.
#[derive(Debug)]
struct Placement {
    block_idx: usize,
    row: usize,
    col_start: usize, // inclusive, 0-based
    col_end: usize,   // exclusive
}

/// Assign each block its (row, col_start, col_end) in the grid.
///
/// Blocks fill left-to-right; when a block's span would exceed the current
/// row's remaining capacity it is moved to the next row.
fn compute_placements(blocks: &[Block], cols: usize) -> Vec<Placement> {
    let mut placements = Vec::with_capacity(blocks.len());
    let mut row = 0usize;
    let mut col = 0usize; // next free column in the current row

    for (idx, block) in blocks.iter().enumerate() {
        let span = block.col_span.min(cols).max(1);

        // If the block doesn't fit in the remaining columns of this row, wrap.
        if col + span > cols && col > 0 {
            row += 1;
            col = 0;
        }

        placements.push(Placement {
            block_idx: idx,
            row,
            col_start: col,
            col_end: col + span,
        });

        col += span;
        // If the row is now full, advance to the next.
        if col >= cols {
            row += 1;
            col = 0;
        }
    }

    placements
}

/// Compute the natural inner width for each column based on block label widths.
///
/// For a block spanning multiple columns the label width is distributed evenly
/// across its columns (with any remainder in the last column). Single-column
/// blocks set the minimum width for that column directly.
fn compute_col_widths(blocks: &[Block], placements: &[Placement], cols: usize) -> Vec<usize> {
    let mut col_widths = vec![MIN_CELL_INNER; cols];

    for p in placements {
        let block = &blocks[p.block_idx];
        let label = block.display_text();
        let lw = UnicodeWidthStr::width(label);
        let span = p.col_end - p.col_start;

        if span == 1 {
            col_widths[p.col_start] = col_widths[p.col_start].max(lw);
        } else {
            // The spanned inner width = sum of column widths + (span-1) gaps
            // (each gap = COL_GAP + 2 for the two `│` walls that disappear).
            // We need: sum(col_widths[col_start..col_end]) + (span-1)*(COL_GAP+2) >= lw
            // So minimum per column = (lw - (span-1)*(COL_GAP+2)) / span, at least MIN_CELL_INNER.
            let gap_absorbed = (span - 1) * (COL_GAP + 2);
            let needed_per_col = lw.saturating_sub(gap_absorbed).div_ceil(span);
            let needed_per_col = needed_per_col.max(MIN_CELL_INNER);
            for col_w in col_widths.iter_mut().take(p.col_end).skip(p.col_start) {
                *col_w = (*col_w).max(needed_per_col);
            }
        }
    }

    col_widths
}

/// Shrink column widths so the total grid width fits within `max_width`.
///
/// The total rendered grid width is:
///   sum(inner_w + 2) for each col + (cols - 1) * COL_GAP
///
/// We reduce column widths proportionally, with a floor of `MIN_CELL_INNER`.
fn apply_max_width(
    mut col_widths: Vec<usize>,
    max_width: Option<usize>,
    cols: usize,
) -> Vec<usize> {
    let Some(budget) = max_width else {
        return col_widths;
    };

    let natural = grid_natural_width(&col_widths, cols);
    if natural <= budget {
        return col_widths;
    }

    // Compute how many characters we need to shed.
    let overhead = budget.saturating_sub(grid_overhead(cols));
    // Distribute available width proportionally, respecting floor.
    let total_inner: usize = col_widths.iter().sum();
    if total_inner == 0 {
        return col_widths;
    }

    // Iteratively reduce the widest columns until we fit.
    for _ in 0..100 {
        let current = grid_natural_width(&col_widths, cols);
        if current <= budget {
            break;
        }
        // Find the widest column and reduce it by 1.
        let max_w = *col_widths.iter().max().unwrap_or(&MIN_CELL_INNER);
        if max_w <= MIN_CELL_INNER {
            break;
        }
        // Suppress the unused variable warning — `overhead` may not be used in loop.
        let _ = overhead;
        for w in &mut col_widths {
            if *w == max_w {
                *w -= 1;
                break;
            }
        }
    }

    col_widths
}

/// The total outer width of the rendered grid, in characters.
fn grid_natural_width(col_widths: &[usize], cols: usize) -> usize {
    grid_overhead(cols) + col_widths.iter().take(cols).sum::<usize>()
}

/// The non-content overhead: sum of `2` (walls) per column + gaps between columns.
fn grid_overhead(cols: usize) -> usize {
    if cols == 0 {
        return 0;
    }
    cols * 2 + (cols - 1) * COL_GAP
}

/// The inner width of a spanning block across columns `col_start..col_end`.
///
/// Absorbs the gap and walls between merged columns so the label has room.
fn spanned_inner_width(col_widths: &[usize], col_start: usize, col_end: usize) -> usize {
    let span = col_end - col_start;
    let base: usize = col_widths[col_start..col_end.min(col_widths.len())]
        .iter()
        .sum();
    if span <= 1 {
        base
    } else {
        // Each absorbed gap between columns: COL_GAP + 2 borders.
        base + (span - 1) * (COL_GAP + 2)
    }
}

/// Truncate `s` so its display width is ≤ `max_w`, appending `…` if truncated.
fn truncate_to_width(s: &str, max_w: usize) -> String {
    if max_w == 0 {
        return String::new();
    }
    let w = UnicodeWidthStr::width(s);
    if w <= max_w {
        return s.to_string();
    }
    // Reserve 1 column for the ellipsis character.
    let target = max_w.saturating_sub(1);
    let mut result = String::new();
    let mut used = 0usize;
    for ch in s.chars() {
        let cw = unicode_width::UnicodeWidthChar::width(ch).unwrap_or(1);
        if used + cw > target {
            break;
        }
        result.push(ch);
        used += cw;
    }
    result.push('\u{2026}'); // …
    result
}

// ---------------------------------------------------------------------------
// Edge summary
// ---------------------------------------------------------------------------

/// Render the directed-edge summary as text lines.
///
/// Returns an empty string when `edges` is empty.
fn render_edge_summary(edges: &[BlockEdge]) -> String {
    if edges.is_empty() {
        return String::new();
    }
    let mut out = String::from("Edges:\n");
    for edge in edges {
        if let Some(label) = &edge.label {
            out.push_str(&format!(
                "  {} \u{2500}\u{2500}\u{25BA} {} [{}]\n",
                edge.source, edge.target, label
            ));
        } else {
            out.push_str(&format!(
                "  {} \u{2500}\u{2500}\u{25BA} {}\n",
                edge.source, edge.target
            ));
        }
    }
    // Trim trailing newline.
    while out.ends_with('\n') {
        out.pop();
    }
    out
}

// ---------------------------------------------------------------------------
// Tests
// ---------------------------------------------------------------------------

#[cfg(test)]
mod tests {
    use super::*;
    use crate::parser::block_diagram::parse;

    fn parsed(src: &str) -> BlockDiagram {
        parse(src).expect("parse should succeed")
    }

    #[test]
    fn renders_single_block() {
        let diag = parsed("block-beta\n    A");
        let out = render(&diag, None);
        assert!(
            out.contains('A'),
            "block label 'A' must appear in output:\n{out}"
        );
        assert!(
            out.contains('\u{250C}'),
            "top-left corner ┌ must appear:\n{out}"
        );
        assert!(
            out.contains('\u{2518}'),
            "bottom-right corner ┘ must appear:\n{out}"
        );
    }

    #[test]
    fn renders_blocks_with_text_labels() {
        let diag = parsed("block-beta\n    columns 2\n    a[\"Alpha\"] b[\"Beta\"]");
        let out = render(&diag, None);
        assert!(out.contains("Alpha"), "Alpha label missing:\n{out}");
        assert!(out.contains("Beta"), "Beta label missing:\n{out}");
    }

    #[test]
    fn renders_edge_summary() {
        let diag = parsed("block-beta\n    A\n    B\n    A --> B");
        let out = render(&diag, None);
        assert!(out.contains("Edges:"), "Edges: header missing:\n{out}");
        assert!(
            out.contains('A') && out.contains('B'),
            "edge endpoints missing:\n{out}"
        );
        assert!(out.contains('\u{25BA}'), "arrow glyph ► missing:\n{out}");
    }

    #[test]
    fn empty_diagram_renders_without_panic() {
        let diag = BlockDiagram::default();
        let out = render(&diag, None);
        // An empty diagram has no blocks; output is either empty or edge-only.
        assert!(
            !out.contains('\u{250C}'),
            "no box should be drawn for empty diagram"
        );
    }

    #[test]
    fn max_width_truncates_long_labels() {
        // A very long label that would naturally exceed 20 columns.
        let diag = parsed("block-beta\n    a[\"This is a very long label that overflows\"]");
        let out = render(&diag, Some(20));
        // Every line must be at most 20 display columns wide.
        for line in out.lines() {
            let w = UnicodeWidthStr::width(line);
            assert!(
                w <= 22, // slight tolerance for box borders
                "line width {w} exceeds budget: {line:?}"
            );
        }
    }

    #[test]
    fn spanning_block_renders_wider_box() {
        // Row 1: a(1) b:2(2) = fills 3 cols (a and b:2 share row 1).
        // Row 2: c d e f (all in row 2 of a 3-column grid).
        // The spanning block `b:2` should have a wider box than `a`.
        let diag = parsed("block-beta\n    columns 3\n    a b:2 c\n    d e f");
        let out = render(&diag, None);
        // All block ids must appear somewhere in the output.
        for id in &["a", "b", "c", "d", "e", "f"] {
            assert!(out.contains(id), "block {id} missing from output:\n{out}");
        }
        // The first rendered row has exactly 2 boxes: `a` and `b:2`.
        // Row 2 has c, d, e, f = 4 boxes. Both rows together have ≥6 ┌ corners total.
        let total_corners: usize = out
            .lines()
            .map(|l| l.chars().filter(|&c| c == '\u{250C}').count())
            .sum();
        assert!(
            total_corners >= 6,
            "expected ≥6 ┌ corners across all rows, got {total_corners}:\n{out}"
        );
        // The b:2 spanning box line should be wider than the a box line.
        // We verify this by checking that the content line contains a `│` that
        // spans across more cells — checking the b label is present is sufficient
        // since the renderer only places it in a wide-enough box.
        assert!(
            out.contains("b "),
            "b label with trailing space missing:\n{out}"
        );
    }

    #[test]
    fn labelled_edge_appears_in_summary() {
        let diag = parsed("block-beta\n    A B\n    A -->|calls| B");
        let out = render(&diag, None);
        assert!(
            out.contains("calls"),
            "edge label 'calls' missing from summary:\n{out}"
        );
    }

    #[test]
    fn multi_row_grid_has_blank_line_separator() {
        let diag = parsed("block-beta\n    columns 1\n    A\n    B\n    C");
        let out = render(&diag, None);
        // Three single-column blocks in a 1-column grid render as 3 rows.
        // Between rows there should be blank lines.
        let blank_lines = out.lines().filter(|l| l.trim().is_empty()).count();
        assert!(
            blank_lines >= 2,
            "expected ≥2 blank separator lines, got {blank_lines}:\n{out}"
        );
    }
}