blockworx_export/

svg.rs

//! SVG export backend.
//!
//! [`SvgRenderer`] implements the [`Renderer`] trait, so the exact same render
//! path that draws the diagram on screen can be pointed at it to produce a
//! standalone `.svg`. Geometry has a single source of truth; this module only
//! translates the primitive calls into SVG nodes (built with the `svg` crate).
//! Like the on-screen painter it holds a [`Palette`] and resolves each
//! [`Swatch`] to a color at draw time — the canvas never sees an app-level role.
//!
//! Text layout comes from the host's [`TextLayout`] — the very engine that lays
//! the diagram out on screen — so the rows a run breaks into, and where each
//! row stands, are the screen's. Each row is written as a `<text>` in the
//! face's own family, with the face embedded, so the export's text is text: a
//! viewer can select it, a PDF made from it carries it, a search finds it. The
//! viewer shapes within a row; the row is ours.
//!
//! Coordinates are world space and written out directly (no zoom/pan); the
//! final `<svg viewBox>` frames whatever was drawn.

use std::cell::{Cell, RefCell};

use blockworx_doc::block_model::Asset;
use blockworx_geom::{Align2, Angle, Pos2, Rect, Vec2, WorldPx, grid::GRID_SIZE, vec2};
use blockworx_paint::text::{Layout, TextLayout, TextRow};
use blockworx_paint::{Color, Font};
use svg::Document;
use svg::node::element::{Circle, Image, Line, Polygon, Polyline, Rectangle, Style};
use svg::node::{Blob, Node};

use blockworx_paint::{Palette, PaletteStroke, Renderer, Swatch, extent::Bounds};

pub struct SvgRenderer<L: TextLayout> {
    palette: Palette,
    /// The host's text engine — the one the canvas draws through.
    layout: L,
    /// The document under construction; draw calls `append` nodes to it.
    doc: RefCell<Document>,
    /// Running world-space bounding box of everything drawn so far.
    bounds: Bounds,
    /// Whether any text was written, and so whether the face is embedded.
    wrote_text: Cell<bool>,
}

impl<L: TextLayout> SvgRenderer<L> {
    pub fn new(palette: Palette, layout: L) -> Self {
        Self {
            palette,
            layout,
            doc: RefCell::new(Document::new()),
            bounds: Bounds::default(),
            wrote_text: Cell::new(false),
        }
    }

    /// Resolve a [`Swatch`] to a concrete color through the palette.
    fn color(&self, swatch: impl Into<Swatch>) -> Color {
        self.palette.resolve(swatch.into())
    }

    /// Resolve a palette-based stroke to the width and color the SVG states.
    fn resolve_stroke(&self, stroke: impl Into<PaletteStroke>) -> Ink {
        let s = stroke.into();
        Ink {
            width: s.width,
            color: self.color(s.color),
        }
    }

    /// Finalize the `<svg>` root: set its `viewBox`/size to frame the content
    /// (with a small margin) and serialize it, with the viewBox rect — the
    /// exact world-space region the SVG depicts, for callers that place the
    /// output back into world coordinates (the PDF export's page fit).
    pub fn finish(self) -> (String, Rect) {
        let view = framed(self.bounds.get());
        let mut doc = self
            .doc
            .into_inner()
            .set(
                "viewBox",
                (view.min.x, view.min.y, view.width(), view.height()),
            )
            .set("width", view.width())
            .set("height", view.height());
        if self.wrote_text.get() {
            let typeface = self.layout.typeface();
            let family = crate::fonts::family(typeface);
            doc = doc
                .set("font-family", family.as_str())
                .set("xml:space", "preserve")
                .add(Style::new(font_face(&family, typeface.bytes())));
        }
        (doc.to_string(), view)
    }

    fn append(&self, node: impl Into<Box<dyn Node>>) {
        self.doc.borrow_mut().append(node);
    }

    /// Write each row of `laid`, anchored at world `pos` and turned by
    /// `angle` about it, as a `<text>` at the row's pen. Returns the unturned
    /// anchored rect.
    // Mirrors `Renderer::text(pos, anchor, text, font, color)`, extended with
    // the rotation this canvas needs. Grouping these into a struct would make
    // every call site diverge from the API it wraps.
    #[expect(clippy::too_many_arguments)]
    fn draw_rows(
        &self,
        pos: Pos2,
        anchor: Align2,
        laid: &Layout,
        font: &Font,
        color: Color,
        angle: Angle,
    ) -> Rect {
        let rows = laid.rows_at(pos, anchor, angle);
        if !rows.is_empty() {
            for row in &rows {
                self.append(text_element(row, font, color, angle));
            }
            self.wrote_text.set(true);
            self.bounds.rect(laid.bounds_at(pos, anchor, angle));
        }
        anchor.anchor_size(pos, laid.size)
    }
}

impl<L: TextLayout> Renderer for SvgRenderer<L> {
    fn rect(
        &self,
        rect: Rect,
        rounding: WorldPx,
        fill: impl Into<Swatch>,
        stroke: impl Into<PaletteStroke>,
    ) {
        let stroke = stroke.into();
        self.bounds.stroked(rect, &stroke);
        let stroke = self.resolve_stroke(stroke);
        let mut el = Rectangle::new()
            .set("x", rect.min.x)
            .set("y", rect.min.y)
            .set("width", rect.width())
            .set("height", rect.height())
            .set("rx", rounding.get());
        apply_fill(&mut el, self.color(fill));
        apply_stroke(&mut el, stroke);
        self.append(el);
    }

    fn line_segment(&self, points: [Pos2; 2], stroke: impl Into<PaletteStroke>) {
        let stroke = self.resolve_stroke(stroke);
        self.bounds.path(&points);
        let mut el = Line::new()
            .set("x1", points[0].x)
            .set("y1", points[0].y)
            .set("x2", points[1].x)
            .set("y2", points[1].y)
            .set("stroke-linecap", "round");
        apply_stroke(&mut el, stroke);
        self.append(el);
    }

    fn line(&self, points: Vec<Pos2>, stroke: impl Into<PaletteStroke>) {
        let stroke = self.resolve_stroke(stroke);
        self.bounds.path(&points);
        let mut el = Polyline::new()
            .set("points", point_list(&points))
            .set("fill", "none")
            .set("stroke-linecap", "round")
            .set("stroke-linejoin", "round");
        apply_stroke(&mut el, stroke);
        self.append(el);
    }

    fn circle(
        &self,
        center: Pos2,
        radius: WorldPx,
        fill: impl Into<Swatch>,
        stroke: impl Into<PaletteStroke>,
    ) {
        let stroke = stroke.into();
        self.bounds.disc(center, radius, &stroke);
        let stroke = self.resolve_stroke(stroke);
        let mut el = Circle::new()
            .set("cx", center.x)
            .set("cy", center.y)
            .set("r", radius.get());
        apply_fill(&mut el, self.color(fill));
        apply_stroke(&mut el, stroke);
        self.append(el);
    }

    fn add_convex_polygon(
        &self,
        points: Vec<Pos2>,
        fill: impl Into<Swatch>,
        stroke: impl Into<PaletteStroke>,
    ) {
        let stroke = self.resolve_stroke(stroke);
        self.bounds.path(&points);
        let mut el = Polygon::new().set("points", point_list(&points));
        apply_fill(&mut el, self.color(fill));
        apply_stroke(&mut el, stroke);
        self.append(el);
    }

    fn text(
        &self,
        pos: Pos2,
        anchor: Align2,
        text: impl ToString,
        font: &Font,
        color: impl Into<Swatch>,
    ) -> Rect {
        let color = self.color(color);
        let laid = self
            .layout
            .layout(&text.to_string(), font, WorldPx::UNBOUNDED);
        self.draw_rows(pos, anchor, &laid, font, color, Angle::ZERO)
    }

    fn rotated_text(
        &self,
        pos: Pos2,
        anchor: Align2,
        text: impl ToString,
        font: &Font,
        color: impl Into<Swatch>,
        angle: Angle,
    ) {
        let color = self.color(color);
        let laid = self
            .layout
            .layout(&text.to_string(), font, WorldPx::UNBOUNDED);
        self.draw_rows(pos, anchor, &laid, font, color, angle);
    }

    fn text_wrapped(
        &self,
        pos: Pos2,
        anchor: Align2,
        text: impl ToString,
        font: &Font,
        color: impl Into<Swatch>,
        max_width: WorldPx,
    ) -> Rect {
        let color = self.color(color);
        let laid = self.layout.layout(&text.to_string(), font, max_width);
        self.draw_rows(pos, anchor, &laid, font, color, Angle::ZERO)
    }

    fn text_size(&self, text: impl ToString, font: &Font) -> Vec2 {
        self.layout
            .layout(&text.to_string(), font, WorldPx::UNBOUNDED)
            .size
    }

    fn text_size_wrapped(&self, text: impl ToString, font: &Font, max_width: WorldPx) -> Vec2 {
        self.layout.layout(&text.to_string(), font, max_width).size
    }

    fn text_layout(&self, text: &str, font: &Font, max_width: WorldPx) -> Layout {
        self.layout.layout(text, font, max_width)
    }

    fn draw_image(&self, rect: Rect, image: &Asset) {
        use base64::Engine as _;
        self.bounds.rect(rect);
        // Embed the image as a base64 data URI so the export is self-contained,
        // with the MIME type matching the payload. `rect` is already
        // aspect-correct; `meet` keeps the image centered and undistorted within
        // it.
        let mime = match image {
            Asset::Svg(_) => "image/svg+xml",
            Asset::Png(_) => "image/png",
        };
        let href = format!(
            "data:{mime};base64,{}",
            base64::engine::general_purpose::STANDARD.encode(image.bytes())
        );
        let el = Image::new()
            .set("x", rect.min.x)
            .set("y", rect.min.y)
            .set("width", rect.width())
            .set("height", rect.height())
            .set("preserveAspectRatio", "xMidYMid meet")
            .set("href", href.as_str());
        self.append(el);
    }

    fn image_intrinsic_size(&self, image: &Asset) -> Option<Vec2> {
        blockworx_paint::image::image_intrinsic_size(image).ok()
    }
}

/// The world rect an export frames: everything `drawn`, and a cell's margin
/// around it — or a unit square for a level that drew nothing.
pub(crate) fn framed(drawn: Option<Rect>) -> Rect {
    drawn.map_or(Rect::from_min_size(Pos2::ZERO, vec2(1.0, 1.0)), |r| {
        r.expand(GRID_SIZE)
    })
}

/// The `@font-face` rule that embeds `bytes` under `family`, so a viewer
/// without the face installed sets the text in it.
fn font_face(family: &str, bytes: &[u8]) -> String {
    use base64::Engine as _;
    format!(
        "@font-face {{ font-family: '{family}'; src: url(data:font/ttf;base64,{}); }}",
        base64::engine::general_purpose::STANDARD.encode(bytes)
    )
}

/// Every `<text>` of an exported SVG, in draw order: its characters, and the
/// pen it starts at. Lives here so the exporter's own tests and the
/// end-to-end render-path tests read the output the same way; the exporter
/// never reads what it writes.
#[cfg(test)]
pub(crate) fn text_rows(svg: &str) -> Vec<(String, Pos2)> {
    let attribute = |tag: &str, name: &str| -> f32 {
        let at = tag
            .find(&format!(" {name}=\""))
            .expect("the attribute is written")
            + name.len()
            + 3;
        tag[at..tag[at..].find('"').map(|end| at + end).expect("closed")]
            .parse()
            .expect("a number")
    };
    svg.match_indices("<text ")
        .map(|(at, _)| {
            let rest = &svg[at..];
            let open = &rest[..rest.find('>').expect("the tag is closed")];
            let body = &rest[open.len() + 1..rest.find("</text>").expect("the element is closed")];
            let text = body
                .replace("&lt;", "<")
                .replace("&gt;", ">")
                .replace("&quot;", "\"")
                .replace("&#39;", "'")
                .replace("&amp;", "&");
            (text, Pos2::new(attribute(open, "x"), attribute(open, "y")))
        })
        .collect()
}

/// Build the `points` attribute value for a polyline/polygon. `Vec<(f32, f32)>`
/// serializes to `"x y x y …"`, which SVG accepts.
fn point_list(points: &[Pos2]) -> Vec<(f32, f32)> {
    points.iter().map(|p| (p.x, p.y)).collect()
}

fn color_hex(c: Color) -> String {
    let [r, g, b, _] = c.to_srgba_unmultiplied();
    format!("#{r:02x}{g:02x}{b:02x}")
}

/// `fill`/`fill-opacity`, or `fill="none"` when fully transparent.
fn fill(c: Color) -> Vec<(&'static str, String)> {
    let [.., a] = c.to_srgba_unmultiplied();
    match a {
        0 => vec![("fill", "none".to_owned())],
        255 => vec![("fill", color_hex(c))],
        _ => vec![
            ("fill", color_hex(c)),
            ("fill-opacity", (f32::from(a) / 255.0).to_string()),
        ],
    }
}

fn apply_fill(node: &mut impl Node, c: Color) {
    for (name, value) in fill(c) {
        node.assign(name, value);
    }
}

/// One row as a `<text>` at its pen, turned about it by `angle`. Written by
/// hand because the `svg` crate breaks an element's content onto lines of
/// its own, which `xml:space="preserve"` would set as spaces.
fn text_element(row: &TextRow, font: &Font, color: Color, angle: Angle) -> Blob {
    use std::fmt::Write as _;
    let (x, y) = (row.pen.x, row.pen.y);
    let mut tag = format!(r#"<text x="{x}" y="{y}" font-size="{}""#, font.size);
    if angle != Angle::ZERO {
        let _ = write!(tag, r#" transform="rotate({} {x} {y})""#, angle.degrees());
    }
    for (name, value) in fill(color) {
        let _ = write!(tag, r#" {name}="{value}""#);
    }
    let text = row
        .text
        .replace('&', "&amp;")
        .replace('<', "&lt;")
        .replace('>', "&gt;");
    Blob::new(format!("{tag}>{text}</text>"))
}

/// A palette stroke resolved to what the SVG states: a width and a color.
#[derive(Clone, Copy)]
struct Ink {
    width: WorldPx,
    color: Color,
}

/// Set `stroke`/`stroke-width`(+opacity); no-op when there's no visible stroke.
fn apply_stroke(node: &mut impl Node, ink: Ink) {
    let [.., a] = ink.color.to_srgba_unmultiplied();
    if ink.width == WorldPx::ZERO || a == 0 {
        return;
    }
    node.assign("stroke", color_hex(ink.color));
    node.assign("stroke-width", ink.width.get());
    if a != 255 {
        node.assign("stroke-opacity", a as f32 / 255.0);
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use blockworx_paint::{Base, FontChoice};
    use blockworx_text::Shaper;

    fn px(v: f32) -> WorldPx {
        WorldPx::new(v)
    }

    fn palette() -> Palette {
        Palette::tokyo_night_moon()
    }

    fn renderer() -> SvgRenderer<Shaper> {
        SvgRenderer::new(palette(), Shaper::new(FontChoice::Basic))
    }

    /// The family the canvas actually draws in.
    fn font() -> Font {
        Font::canvas(12.0)
    }

    /// A run is written as its characters, not as outlines, in the face the
    /// layout measured — named on the root and embedded for a viewer that
    /// lacks it — in the palette's resolved ink.
    #[test]
    fn a_run_is_written_as_text_in_the_embedded_face() {
        let r = renderer();
        let rect = r.text(Pos2::ZERO, Align2::LEFT_TOP, "Config", &font(), Base::B00);
        let (svg, _) = r.finish();
        let rows = text_rows(&svg);
        assert_eq!(rows.len(), 1, "one row: {rows:?}");
        assert_eq!(rows[0].0, "Config", "a ligature is the viewer's to shape");
        assert!(
            rows[0].1.y > 0.0 && rows[0].1.y < rect.height(),
            "the pen is on the baseline, inside the run: {rows:?} in {rect:?}"
        );
        assert!(!svg.contains("<path"), "no glyph outlines:\n{svg}");
        assert!(svg.contains(r#"font-family="Roboto""#), "{svg}");
        assert!(svg.contains("@font-face { font-family: 'Roboto'"));
        assert!(svg.contains(r##"fill="#222436""##), "resolved palette fill");
    }

    #[test]
    fn a_wrapped_run_writes_one_text_per_row() {
        let r = renderer();
        let line = "the quick brown fox jumps over the lazy dog";
        let max = r.text_size(line, &font()).x / 3.0;
        r.text_wrapped(
            Pos2::ZERO,
            Align2::LEFT_TOP,
            line,
            &font(),
            Base::B00,
            px(max),
        );
        let (svg, _) = r.finish();
        let rows = text_rows(&svg);
        assert!(
            rows.len() >= 3,
            "a third of the width takes three rows: {rows:?}"
        );
        let joined: String = rows.iter().map(|(text, _)| text.as_str()).collect();
        assert_eq!(
            joined.split_whitespace().collect::<Vec<_>>().join(" "),
            line
        );
        assert!(
            rows.windows(2)
                .all(|pair| pair[0].1.y < pair[1].1.y && pair[0].1.x == pair[1].1.x),
            "rows stack down one left edge: {rows:?}"
        );
    }

    #[test]
    fn a_turned_run_turns_each_row_about_its_pen() {
        let r = renderer();
        r.rotated_text(
            Pos2::new(50.0, 20.0),
            Align2::LEFT_TOP,
            "sig",
            &font(),
            Base::B00,
            Angle::QUARTER_TURN,
        );
        let (svg, _) = r.finish();
        let rows = text_rows(&svg);
        assert_eq!(rows.len(), 1);
        let (x, y) = (rows[0].1.x, rows[0].1.y);
        assert!(
            x < 50.0 && (y - 20.0).abs() < 1e-3,
            "a quarter turn puts the baseline left of the anchor: {rows:?}"
        );
        assert!(svg.contains(&format!("rotate(90 {x} {y})")), "{svg}");
    }

    #[test]
    fn markup_in_a_run_is_escaped() {
        let r = renderer();
        r.text(Pos2::ZERO, Align2::LEFT_TOP, "a<b & c", &font(), Base::B00);
        let (svg, _) = r.finish();
        assert!(svg.contains("a&lt;b &amp; c"), "{svg}");
        assert_eq!(text_rows(&svg)[0].0, "a<b & c");
    }

    #[test]
    fn multiline_text_stacks_lines() {
        let r = renderer();
        let font = font();
        // Two `\n`-separated lines measure two rows tall, one row wide.
        let one = r.text_size("aaaa", &font);
        let two = r.text_size("aa\naa", &font);
        assert!(
            (two.y - 2.0 * one.y).abs() < 0.001,
            "two lines should be twice as tall: {} vs {}",
            two.y,
            one.y
        );
        assert!(
            two.x < one.x + 0.001,
            "width is the widest line, not the sum: {} vs {}",
            two.x,
            one.x
        );
        // A trailing newline keeps an empty final row.
        assert!((r.text_size("aa\n", &font).y - two.y).abs() < 0.001);
    }

    #[test]
    fn wrapped_text_breaks_long_lines_within_the_width() {
        let r = renderer();
        let font = font();
        let line = "the quick brown fox jumps over the lazy dog";
        let unwrapped = r.text_size(line, &font);
        // Wrap to a third of the unwrapped width: it must take more rows, and no
        // row may exceed the wrap width.
        let max = unwrapped.x / 3.0;
        let wrapped = r.text_size_wrapped(line, &font, px(max));
        assert!(
            wrapped.y > unwrapped.y,
            "wrapping a long line adds rows: {} vs {}",
            wrapped.y,
            unwrapped.y
        );
        assert!(
            wrapped.x <= max + 0.001,
            "no wrapped row exceeds the wrap width: {} vs {}",
            wrapped.x,
            max
        );
        // An infinite width is a no-op (matches the no-wrap default).
        assert!(
            (r.text_size_wrapped(line, &font, WorldPx::UNBOUNDED).x - unwrapped.x).abs() < 0.001
        );
    }

    #[test]
    fn primitives_and_viewbox() {
        let r = renderer();
        r.rect(
            Rect::from_min_size(Pos2::new(10.0, 10.0), vec2(30.0, 20.0)),
            px(3.0),
            Base::B01,
            (1.0, Base::B0D),
        );
        r.line(
            vec![Pos2::new(0.0, 0.0), Pos2::new(40.0, 0.0)],
            (1.7, Base::B0B),
        );
        let (svg, _) = r.finish();
        assert!(svg.contains("<svg"));
        assert!(svg.contains("viewBox="));
        assert!(svg.contains("<rect"));
        assert!(svg.contains("<polyline"));
        assert!(svg.contains("</svg>"));
        assert!(
            !svg.contains("@font-face"),
            "a picture with no text embeds no face"
        );
    }

    #[test]
    fn image_embeds_as_data_uri() {
        let r = renderer();
        r.draw_image(
            Rect::from_min_size(Pos2::new(0.0, 0.0), vec2(10.0, 10.0)),
            &Asset::Svg(r#"<svg viewBox="0 0 1 1"/>"#.as_bytes().into()),
        );
        let (svg, _) = r.finish();
        assert!(
            svg.contains("<image"),
            "image exports as an <image>:\n{svg}"
        );
        assert!(
            svg.contains("data:image/svg+xml;base64,"),
            "image href is a base64 SVG data URI"
        );
        assert!(svg.contains(r#"preserveAspectRatio="xMidYMid meet""#));
    }

    #[test]
    fn png_image_embeds_as_png_data_uri() {
        let r = renderer();
        r.draw_image(
            Rect::from_min_size(Pos2::new(0.0, 0.0), vec2(10.0, 10.0)),
            &Asset::Png(vec![0x89, b'P', b'N', b'G', 1, 2, 3].into()),
        );
        let (svg, _) = r.finish();
        assert!(
            svg.contains("data:image/png;base64,"),
            "PNG image href is a base64 PNG data URI:\n{svg}"
        );
    }
}