svg

Type-safe SVG generation library for Kit

Files

Dependencies

None

Installation

kit add gitlab.com/kit-lang/packages/kit-svg.git

Usage

import Kit.SVG as SVG

# Create a simple SVG document
doc = SVG.new {width: 200.0, height: 200.0}
  |> SVG.add (SVG.rect {x: 10.0, y: 10.0, width: 80.0, height: 60.0, fill: "#3498db"})
  |> SVG.add (SVG.circle {cx: 150.0, cy: 100.0, r: 40.0, fill: "#e74c3c"})

output = SVG.render doc

Basic Shapes

# Rectangle with rounded corners
SVG.rect {x: 0.0, y: 0.0, width: 100.0, height: 50.0, rx: 5.0, fill: "blue"}

# Circle
SVG.circle {cx: 50.0, cy: 50.0, r: 25.0, stroke: "black", stroke-width: "2"}

# Ellipse
SVG.ellipse {cx: 50.0, cy: 50.0, rx: 40.0, ry: 20.0}

# Line
SVG.line {x1: 0.0, y1: 0.0, x2: 100.0, y2: 100.0, stroke: "red"}

# Polygon (closed shape)
SVG.polygon {points: [SVG.pt 50.0 0.0, SVG.pt 100.0 100.0, SVG.pt 0.0 100.0], fill: "green"}

Path DSL

# Build complex paths with the path DSL
path = SVG.path-new
  |> SVG.move-to 10.0 10.0
  |> SVG.line-to 90.0 10.0
  |> SVG.curve-to {x1: 100.0, y1: 50.0, x2: 90.0, y2: 90.0, x: 50.0, y: 90.0}
  |> SVG.close-path
  |> SVG.path-fill "purple"
  |> SVG.path-stroke "black"

Transforms

# Transform helper functions
translate-str = SVG.translate 50.0 100.0     # "translate(50 100)"
rotate-str = SVG.rotate 45.0                 # "rotate(45)"
scale-str = SVG.scale 2.0                    # "scale(2)"

# Apply to groups
g = SVG.group-new
  |> SVG.group-transform (SVG.translate 100.0 50.0)
  |> SVG.group-add (SVG.rect {x: 0.0, y: 0.0, width: 20.0, height: 20.0})

Gradients

# Create a linear gradient
grad = SVG.linear-gradient "myGrad"
  |> SVG.gradient-stop {offset: 0.0, color: "red"}
  |> SVG.gradient-stop {offset: 1.0, color: "blue"}

# Use in a shape
doc = SVG.new {width: 100.0, height: 100.0}
  |> SVG.add-def grad
  |> SVG.add (SVG.rect {x: 0.0, y: 0.0, width: 100.0, height: 100.0, fill: SVG.url "myGrad"})

Convenience Shapes

# Star shape
star = SVG.star {
  cx: 100.0, cy: 100.0, 
  points: 5, 
  outer-r: 50.0, inner-r: 25.0, 
  fill: "gold"
}

# Regular polygon (hexagon)
hexagon = SVG.regular-polygon {
  cx: 100.0, cy: 100.0, 
  sides: 6, 
  radius: 50.0, 
  fill: "blue"
}

# Arrow shape
arrow = SVG.arrow {
  start: {x: 0.0, y: 50.0}, 
  end: {x: 100.0, y: 50.0}, 
  head-size: 10.0, 
  stroke: "black"
}

# Rounded rectangle shorthand
rounded = SVG.rounded-rect {
  x: 10.0, y: 10.0, 
  width: 100.0, height: 50.0, 
  radius: 10.0, 
  fill: "blue"
}

Markers

# Create arrow marker for line endpoints
arrow-mark = SVG.arrow-marker {id: "arrow", size: 10.0, color: "black"}

# Create circle/dot marker
dot = SVG.circle-marker {id: "dot", radius: 3.0, fill: "red"}

# Square and diamond markers also available
square = SVG.square-marker {id: "square", size: 6.0, fill: "blue"}
diamond = SVG.diamond-marker {id: "diamond", size: 8.0, fill: "green"}

# Add markers to document
doc = SVG.new {width: 200.0, height: 100.0}
  |> SVG.add-def arrow-mark
  |> SVG.add (SVG.line {
    x1: 10.0, y1: 50.0, x2: 190.0, y2: 50.0, 
    stroke: "black", 
    marker-end: SVG.marker-url "arrow"
  })

Colors

The Colors module (import separately) provides a comprehensive color system:

import Kit.SVG.Colors as Color

# Create colors in different formats
red = Color.rgb 255 0 0
blue = Color.hex "#0000ff"
green = Color.hsl 120.0 1.0 0.5
semi-transparent = Color.rgba 255 0 0 0.5

# Convert between formats
hex-red = Color.to-hex red            # "#ff0000"
css-str = Color.to-css blue           # "#0000ff"
hsl-green = Color.to-hsl green        # HSL 120.0 1.0 0.5

# Manipulate colors
light-red = Color.lighten 0.2 red     # Make 20% lighter
dark-blue = Color.darken 0.2 blue     # Make 20% darker
vivid = Color.saturate 0.3 green      # Increase saturation
muted = Color.desaturate 0.3 green    # Decrease saturation

# Color operations
complement = Color.complement red      # Get complementary color
rotated = Color.rotate-hue 60.0 red   # Rotate hue by degrees
gray = Color.grayscale red            # Convert to grayscale
inverted = Color.invert red           # Invert color
mixed = Color.mix red blue 0.5        # Mix two colors
with-alpha = Color.with-alpha 0.5 red # Set opacity

Animation

The Animation module (import separately) provides SVG declarative animations:

import Kit.SVG.Animation as Animation

# Animate a single attribute
fade = Animation.animate {
  attribute: "opacity", 
  from : "0", to: "1", 
  dur: "2s", 
  fill-mode: "freeze"
}

# Transform animations (rotate, scale, translate)
spin = Animation.animate-transform {
  transform-type: "rotate", 
  values: "0 50 50;360 50 50", 
  dur: "3s", 
  repeat-count: "indefinite"
}

# Motion along a path
motion = Animation.animate-motion {
  path: "M0,0 C50,0 50,100 100,100", 
  dur: "4s", 
  rotate: "auto"
}

# Set a value at a specific time
show = Animation.set {
  attribute: "visibility", 
  to: "visible", 
  begin: "1s"
}

# Convenience functions
fade-in = Animation.fade-in "1s"
fade-out = Animation.fade-out "1s"
pulse = Animation.pulse "0.5s"
spinning = Animation.spin 50.0 50.0 "2s"
shake = Animation.shake "0.3s"
bounce = Animation.bounce "0.5s"
color-change = Animation.color-transition "blue" "red" "2s"
draw = Animation.draw-stroke "100" "2s"

# Render animation to XML
xml = Animation.render-animate fade

Filter Effects

The Filters module (import separately) provides SVG filter effects:

import Kit.SVG.Filters as Filters

# Basic effects
blur = Filters.gaussian-blur 5.0
offset = Filters.offset 3.0 3.0
saturate = Filters.saturate 0.5
hue-shift = Filters.hue-rotate 90.0
gray = Filters.grayscale()

# Create a simple blur filter
blur-filter = Filters.blur-filter "myBlur" 8.0

# Create a drop shadow
shadow = Filters.drop-shadow {
  id: "shadow", 
  dx: 3.0, dy: 3.0, 
  blur: 5.0, 
  color: "black", 
  opacity: 0.5
}

# Create a glow effect
glow = Filters.glow {
  id: "glow", 
  blur: 5.0, 
  color: "yellow"
}

# Inner shadow
inner = Filters.inner-shadow {
  id: "inner", 
  dx: 2.0, dy: 2.0, 
  blur: 3.0, 
  color: "black"
}

# Emboss and sharpen
emboss = Filters.emboss "embossed"
sharpen = Filters.sharpen "sharpened" 1.0

# Build custom filters with effects chain
custom = Filters.simple-filter "custom" [
  Filters.offset 2.0 2.0, 
  Filters.gaussian-blur 3.0, 
  Filters.merge ["SourceGraphic", "blur"]
]

# Apply filter to element
doc = SVG.new {width: 200.0, height: 200.0}
  |> SVG.add-def shadow
  |> SVG.add (SVG.rect {
    x: 50.0, y: 50.0, width: 100.0, height: 100.0, 
    fill: "blue", 
    filter: Filters.filter-url "shadow"
  })

Transform Matrix

The Matrix module (import separately) provides 2D transformation matrices:

import Kit.SVG.Matrix as Matrix

# Create transformation matrices
identity = Matrix.identity
t = Matrix.translate 10.0 20.0
s = Matrix.scale 2.0
r = Matrix.rotate 45.0
rx = Matrix.rotate-around 45.0 50.0 50.0  # Rotate around point

# Combine transformations
combined = Matrix.multiply s t
composed = Matrix.compose [t, s, r]

# Transform a point
p = Matrix.transform-point combined 5.0 10.0
# p.x and p.y contain transformed coordinates

# Matrix operations
det = Matrix.determinant combined
inv = Matrix.inverse combined  # Returns Option

# Extract components
translation = Matrix.get-translation combined
scale-factors = Matrix.get-scale combined
rotation = Matrix.get-rotation combined

# Convert to SVG string
str = Matrix.to-string combined            # "matrix(a b c d e f)"
transform = Matrix.to-transform-string t   # "translate(10 20)"

Bounding Box

The BBox module (import separately) provides geometry calculations:

import Kit.SVG.BBox as BBox

# Create bounding boxes from shapes
rect-bbox = BBox.from-rect 10.0 20.0 100.0 50.0
circle-bbox = BBox.from-circle 100.0 100.0 50.0
line-bbox = BBox.from-line 10.0 20.0 100.0 80.0
points-bbox = BBox.from-points [{x: 10.0, y: 20.0}, {x: 100.0, y: 80.0}]

# Get properties
x = BBox.get-x rect-bbox
y = BBox.get-y rect-bbox
width = BBox.get-width rect-bbox
height = BBox.get-height rect-bbox
center = BBox.center rect-bbox        # {x, y}
area = BBox.area rect-bbox
aspect = BBox.aspect-ratio rect-bbox

# Combine bounding boxes
merged = BBox.merge bbox1 bbox2
merged-all = BBox.merge-all [bbox1, bbox2, bbox3]
intersection = BBox.intersect bbox1 bbox2  # Returns Option

# Containment and overlap tests
inside = BBox.contains-point? 50.0 50.0 rect-bbox
contains = BBox.contains-box? outer inner
overlaps = BBox.overlaps? bbox1 bbox2

# Transform bounding boxes
expanded = BBox.expand 5.0 rect-bbox      # Grow by 5 on all sides
contracted = BBox.contract 5.0 rect-bbox  # Shrink by 5
translated = BBox.translate 10.0 20.0 rect-bbox
scaled = BBox.scale 2.0 rect-bbox         # Scale from center

# Convert to SVG viewBox
viewbox = BBox.to-viewbox rect-bbox       # "10 20 100 50"

Text Features

# Basic text
text = SVG.text {x: 50.0, y: 50.0, content: "Hello", fill: "black"}

# Multi-line text block (splits on newlines)
block = SVG.text-block {
  x: 10.0, y: 30.0, 
  content: "Line 1\nLine 2\nLine 3", 
  fill: "black", 
  line-height: 20.0
}

# Text along a path
text-path = SVG.text-path {
  content: "Curved text", 
  href: "myPath",  # Reference to a path element
  fill: "blue"
}

# Rich text with styled spans
rich = SVG.rich-text {
  x: 10.0, y: 50.0, 
  spans: [
    SVG.tspan-styled {text: "Bold", font-weight: "bold"}, 
    SVG.tspan {text: " and "}, 
    SVG.tspan-styled {text: "Red", fill: "red"}
  ]
}

Rendering

# Compact XML output (single line, no extra whitespace)
compact = SVG.render doc

# Pretty-printed XML with indentation
pretty = SVG.render-pretty doc

API Reference

Document

Elements

Path DSL

Groups

Transforms

Gradients

Markers

Shapes

License

MIT License - see LICENSE for details.

Exported Functions & Types

FilterEffect

Filter effect - represents a single filter primitive

Filter

Filter definition - a named filter containing effects

filter

Create a filter definition.

Config fields: - id: String - unique identifier for the filter - x: Float - x position (default: -10%) - y: Float - y position (default: -10%) - width: Float - width (default: 120%) - height: Float - height (default: 120%) - color-interpolation-filters: String - "sRGB" or "linearRGB"

{id: String, ...} -> [FilterEffect] -> Filter

simple-filter

Create a simple filter with just an ID and effects.

NonEmptyString -> [FilterEffect] -> Filter

gaussian-blur

Create a Gaussian blur effect.

PositiveFloat -> FilterEffect

gaussian-blur-io

Create a Gaussian blur with input/output.

PositiveFloat -> String -> String -> FilterEffect

offset

Create an offset effect.

Float -> Float -> FilterEffect

offset-io

Create an offset effect with input/output.

Float -> Float -> String -> String -> FilterEffect

blend

Create a blend effect.

Modes: normal, multiply, screen, darken, lighten, overlay, color-dodge, color-burn, hard-light, soft-light, difference, exclusion

String -> String -> String -> FilterEffect

blend-io

Create a blend effect with result.

String -> String -> String -> String -> FilterEffect

color-matrix

Create a color matrix effect.

Types: matrix, saturate, hueRotate, luminanceToAlpha

String -> String -> FilterEffect

color-matrix-io

Create a color matrix with input/output.

String -> String -> String -> String -> FilterEffect

saturate

Create a saturate effect (convenience for color-matrix saturate).

Float -> FilterEffect

hue-rotate

Create a hue-rotate effect (convenience for color-matrix hueRotate).

Float -> FilterEffect

grayscale

Create a grayscale effect (saturate 0).

() -> FilterEffect

flood

Create a flood (solid color) effect.

String -> Float -> FilterEffect

flood-io

Create a flood effect with result.

String -> Float -> String -> FilterEffect

morphology

Create a morphology effect (dilate or erode).

Operators: dilate, erode

String -> PositiveFloat -> FilterEffect

morphology-io

Create a morphology effect with input/output.

String -> PositiveFloat -> String -> String -> FilterEffect

dilate

Create a dilate effect (expand shapes).

PositiveFloat -> FilterEffect

erode

Create an erode effect (shrink shapes).

PositiveFloat -> FilterEffect

composite

Create a composite effect.

Operators: over, in, out, atop, xor, arithmetic

String -> String -> String -> FilterEffect

composite-arithmetic

Create a composite effect with arithmetic coefficients.

Float -> Float -> Float -> Float -> String -> String -> FilterEffect

merge

Create a merge effect combining multiple inputs.

[String] -> FilterEffect

merge-io

Create a merge effect with result.

[String] -> String -> FilterEffect

image

Create an image effect.

String -> FilterEffect

turbulence

Create a turbulence effect (noise).

Types: turbulence, fractalNoise

String -> Float -> Int -> FilterEffect

displacement-map

Create a displacement map effect.

Float -> String -> String -> String -> String -> FilterEffect

blur-filter

Create a simple blur filter.

NonEmptyString -> PositiveFloat -> Filter

drop-shadow

Create a drop shadow filter.

{id: String, dx: Float, dy: Float, blur: Float, color: String, opacity: Float} -> Filter

inner-shadow

Create an inner shadow filter.

{id: String, dx: Float, dy: Float, blur: Float, color: String} -> Filter

glow

Create a glow filter.

{id: String, blur: Float, color: String} -> Filter

emboss

Create an emboss filter.

NonEmptyString -> Filter

sharpen

Create a sharpen filter.

NonEmptyString -> PositiveFloat -> Filter

render-effect

Render a filter effect to XML string.

FilterEffect -> String

render-filter

Render a filter definition to XML string.

Filter -> String

filter-url

Generate a filter URL reference for use in style attributes.

NonEmptyString -> String

Color

Color type supporting multiple color spaces

to-rgb

Convert any color to RGB format.

Color -> Color

to-hsl

Convert any color to HSL format.

Color -> Color

to-hex

Convert any color to a hex string (e.g., "#ff0000").

Color -> String

to-css

Convert any color to a CSS-compatible string. Returns hex for RGB, rgba() for RGBA, hsl() for HSL, hsla() for HSLA.

Color -> String

lighten

Lighten a color by a given amount (0.0 to 1.0).

Float -> Color -> Color

darken

Darken a color by a given amount (0.0 to 1.0).

Float -> Color -> Color

saturate

Increase saturation by a given amount (0.0 to 1.0).

Float -> Color -> Color

desaturate

Decrease saturation by a given amount (0.0 to 1.0).

Float -> Color -> Color

complement

Get the complementary color (opposite on color wheel).

Color -> Color

rotate-hue

Rotate hue by a given number of degrees.

Float -> Color -> Color

with-alpha

Set the alpha (opacity) of a color.

Float -> Color -> Color

mix

Mix two colors together. weight is the amount of the first color (0.0 to 1.0).

Color -> Color -> Float -> Color

grayscale

Convert a color to grayscale.

Color -> Color

invert

Invert a color.

Color -> Color

rgb

Create an RGB color from values 0-255.

Int -> Int -> Int -> Color

rgba

Create an RGBA color from RGB values 0-255 and alpha 0.0-1.0.

Int -> Int -> Int -> Float -> Color

hsl

Create an HSL color from hue 0-360, saturation 0.0-1.0, lightness 0.0-1.0.

Float -> Float -> Float -> Color

hsla

Create an HSLA color.

Float -> Float -> Float -> Float -> Color

hex

Create a color from a hex string.

String -> Color

named

Create a named color.

String -> Color

star

Create a star shape.

Parameters:

• config - Record with cx, cy, points, outer-r, inner-r (required);
• fill, stroke, stroke-width, id, class (optional)

Returns: Element: A path element representing a star

{cx: Float, cy: Float, points: Int, outer-r: Float, inner-r: Float, ...} -> Element

SVG.star {cx: 100.0, cy: 100.0, points: 5, outer-r: 50.0, inner-r: 25.0, fill: "gold"}

regular-polygon

Create a regular polygon shape.

Parameters:

• config - Record with cx, cy, sides, radius (required);
• fill, stroke, stroke-width, id, class (optional)

Returns: Element: A path element representing a regular polygon

{cx: Float, cy: Float, sides: Int, radius: Float, ...} -> Element

SVG.regular-polygon {cx: 100.0, cy: 100.0, sides: 6, radius: 50.0, fill: "blue"}

arrow

Create an arrow shape (line with arrowhead).

Parameters:

• config - Record with start (Point or {x, y}), end (Point or {x, y}), head-size (required);
• stroke, stroke-width, id, class (optional)

Returns: Element: A path element representing an arrow

{start: {x: Float, y: Float}, end: {x: Float, y: Float}, head-size: Float, ...} -> Element

SVG.arrow {start: {x: 0.0, y: 0.0}, end: {x: 100.0, y: 100.0}, head-size: 10.0, stroke: "black"}

rounded-rect

Create a rounded rectangle with uniform corner radius.

Parameters:

• config - Record with x, y, width, height, radius (required);
• fill, stroke, stroke-width, opacity, id, class (optional)

Returns: Element: A rect element with uniform corner radius

{x: Float, y: Float, width: Float, height: Float, radius: Float, ...} -> Element

SVG.rounded-rect {x: 10.0, y: 10.0, width: 100.0, height: 50.0, radius: 10.0, fill: "blue"}

path-new

Create an empty path element.

Returns: Element: An empty path element

Unit -> Element

SVG.path-new
  |> SVG.move-to 0.0 0.0
  |> SVG.line-to 100.0 100.0
  |> SVG.close-path

move-to

Add a move-to command to a path.

Element -> Float -> Float -> Element

move-to-rel

Add a relative move-to command to a path.

Element -> Float -> Float -> Element

line-to

Add a line-to command to a path.

Element -> Float -> Float -> Element

line-to-rel

Add a relative line-to command to a path.

Element -> Float -> Float -> Element

horizontal-to

Add a horizontal line command to a path.

Element -> Float -> Element

horizontal-rel

Add a relative horizontal line command to a path.

Element -> Float -> Element

vertical-to

Add a vertical line command to a path.

Element -> Float -> Element

vertical-rel

Add a relative vertical line command to a path.

Element -> Float -> Element

curve-to

Add a cubic bezier curve command to a path.

Element -> {x1: Float, y1: Float, x2: Float, y2: Float, x: Float, y: Float} -> Element

curve-to-rel

Add a relative cubic bezier curve command to a path.

Element -> {dx1: Float, dy1: Float, dx2: Float, dy2: Float, dx: Float, dy: Float} -> Element

smooth-to

Add a smooth cubic bezier curve command to a path.

Element -> {x2: Float, y2: Float, x: Float, y: Float} -> Element

smooth-to-rel

Add a relative smooth cubic bezier curve command to a path.

Element -> {dx2: Float, dy2: Float, dx: Float, dy: Float} -> Element

quad-to

Add a quadratic bezier curve command to a path.

Element -> {x1: Float, y1: Float, x: Float, y: Float} -> Element

quad-to-rel

Add a relative quadratic bezier curve command to a path.

Element -> {dx1: Float, dy1: Float, dx: Float, dy: Float} -> Element

smooth-quad-to

Add a smooth quadratic bezier curve command to a path.

Element -> Float -> Float -> Element

smooth-quad-to-rel

Add a relative smooth quadratic bezier curve command to a path.

Element -> Float -> Float -> Element

arc-to

Add an arc command to a path.

Element -> {rx: Float, ry: Float, rotation: Float, large-arc: Bool, sweep: Bool, x: Float, y: Float} -> Element

arc-to-rel

Add a relative arc command to a path.

Element -> {rx: Float, ry: Float, rotation: Float, large-arc: Bool, sweep: Bool, dx: Float, dy: Float} -> Element

close-path

Close the current path.

Element -> Element

path-fill

Set fill on a path.

Element -> String -> Element

path-stroke

Set stroke on a path.

Element -> String -> Element

path-stroke-width

Set stroke-width on a path.

Element -> String -> Element

path-stroke-linecap

Set stroke-linecap on a path.

Element -> String -> Element

path-stroke-linejoin

Set stroke-linejoin on a path.

Element -> String -> Element

path-stroke-dasharray

Set stroke-dasharray on a path.

Element -> String -> Element

path-stroke-dashoffset

Set stroke-dashoffset on a path.

Element -> String -> Element

rect-path

Create a path element from rectangle coordinates. Returns a closed rectangular path.

Parameters:

• config - Record with x, y, width, height (required)

Returns: Element: A path element representing a rectangle

{x: Float, y: Float, width: Float, height: Float} -> Element

SVG.rect-path {x: 10.0, y: 10.0, width: 100.0, height: 50.0}
  |> SVG.path-fill "blue"

circle-path

Create a path element approximating a circle using bezier curves. Returns a closed circular path.

Parameters:

• config - Record with cx, cy, r (required)

Returns: Element: A path element approximating a circle

{cx: Float, cy: Float, r: Float} -> Element

SVG.circle-path {cx: 50.0, cy: 50.0, r: 25.0}
  |> SVG.path-fill "red"

arc-path

Create an arc path from start angle to end angle.

Parameters:

• config - Record with cx, cy, r, start, end (all in degrees; required)

Returns: Element: A path element representing an arc

{cx: Float, cy: Float, r: Float, start: Float, end: Float} -> Element

SVG.arc-path {cx: 50.0, cy: 50.0, r: 40.0, start: 0.0, end: 90.0}
  |> SVG.path-stroke "blue"
  |> SVG.path-fill "none"

pie-slice-path

Create a pie slice path (arc with lines to center).

Parameters:

• config - Record with cx, cy, r, start, end (all in degrees; required)

Returns: Element: A path element representing a pie slice

{cx: Float, cy: Float, r: Float, start: Float, end: Float} -> Element

SVG.pie-slice-path {cx: 100.0, cy: 100.0, r: 80.0, start: 0.0, end: 60.0}
  |> SVG.path-fill "orange"

new

Create a new SVG document with the given dimensions.

Parameters:

• config - Record with width and height (both required)

Returns: SvgDoc: A new SVG document

{width: Float, height: Float} -> SvgDoc

doc = SVG.new {width: 400, height: 300}

view-box

Set the viewBox attribute on an SVG document.

Parameters:

• doc - The SVG document
• box - Record with min-x, min-y, width, height

Returns: SvgDoc: Document with viewBox set

SvgDoc -> {min-x: Float, min-y: Float, width: Float, height: Float} -> SvgDoc

doc |> SVG.view-box {min-x: 0, min-y: 0, width: 100, height: 100}

add

Add an element to the SVG document.

Parameters:

• doc - The SVG document
• element - The element to add

Returns: SvgDoc: Document with element added

SvgDoc -> Element -> SvgDoc

doc |> SVG.add (SVG.rect {x: 0, y: 0, width: 100, height: 50})

add-all

Add multiple elements to the SVG document.

Parameters:

• doc - The SVG document
• elements - List of elements to add

Returns: SvgDoc: Document with elements added

SvgDoc -> [Element] -> SvgDoc

doc |> SVG.add-all [rect1, rect2, circle1]

add-def

Add a definition (gradient, pattern, marker, etc.) to the SVG document.

Parameters:

• doc - The SVG document
• def - The definition to add

Returns: SvgDoc: Document with definition added

SvgDoc -> Def -> SvgDoc

doc |> SVG.add-def gradient

arrow-marker

Create an arrow marker pointing right.

Parameters:

• config - Record with id, size (required); color (optional, defaults to "black")

Returns: Def: A marker definition with an arrow shape

{id: String, size: Float, ...} -> Def

arrow = SVG.arrow-marker {id: "arrow", size: 10.0}
doc |> SVG.add-def arrow

circle-marker

Create a circle marker.

Parameters:

• config - Record with id, radius (required); fill (optional, defaults to "black")

Returns: Def: A marker definition with a circle shape

{id: String, radius: Float, ...} -> Def

dot = SVG.circle-marker {id: "dot", radius: 3.0, fill: "red"}
doc |> SVG.add-def dot

square-marker

Create a square marker.

Parameters:

• config - Record with id, size (required); fill (optional, defaults to "black")

Returns: Def: A marker definition with a square shape

{id: String, size: Float, ...} -> Def

square = SVG.square-marker {id: "square", size: 6.0, fill: "blue"}
doc |> SVG.add-def square

diamond-marker

Create a diamond marker.

Parameters:

• config - Record with id, size (required); fill (optional, defaults to "black")

Returns: Def: A marker definition with a diamond shape

{id: String, size: Float, ...} -> Def

diamond = SVG.diamond-marker {id: "diamond", size: 8.0, fill: "green"}
doc |> SVG.add-def diamond

marker-url

Create a marker URL reference for use with marker-start, marker-mid, or marker-end.

String -> String

Animate

Animation element for animating a single attribute Fields: attribute-name, from, to, by, values, dur, begin, end, repeat-count, repeat-dur, fill-mode, calc-mode, key-times, key-splines, additive, accumulate

AnimateTransform

Transform animation element Fields: type, from, to, by, values, dur, begin, end, repeat-count, repeat-dur, fill-mode, calc-mode, key-times, key-splines, additive, accumulate

AnimateMotion

Motion animation element (animate along a path) Fields: path, mpath-href, rotate, dur, begin, end, repeat-count, repeat-dur, fill-mode, calc-mode, key-times, key-splines, key-points

Set

Set element (sets a value at a specific time) Fields: attribute-name, to, begin, end, dur

animate

Create an animate element to animate a single attribute.

Required config fields: - attribute: String - the attribute to animate (e.g., "cx", "opacity", "fill")

Optional config fields: - from: String - starting value - to: String - ending value - by: String - relative change - values: String - semicolon-separated keyframe values - dur: String - duration (e.g., "2s", "500ms") - begin: String - when to start (e.g., "0s", "click", "mouseover") - end: String - when to end - repeat-count: String - number of repetitions or "indefinite" - repeat-dur: String - total duration of repetitions - fill-mode: String - "freeze" or "remove" (what happens after) - calc-mode: String - "discrete", "linear", "paced", or "spline" - key-times: String - semicolon-separated time values (0 to 1) - key-splines: String - cubic bezier control points - additive: String - "replace" or "sum" - accumulate: String - "none" or "sum"

{attribute: String, ...} -> Animate

animate-transform

Create an animateTransform element for transform animations.

Required config fields: - type: String - transform type: "translate", "scale", "rotate", "skewX", "skewY"

Optional config fields: - from: String - starting transform values - to: String - ending transform values - by: String - relative change - values: String - semicolon-separated keyframe values - dur: String - duration - begin: String - when to start - end: String - when to end - repeat-count: String - repetitions or "indefinite" - repeat-dur: String - total duration - fill-mode: String - "freeze" or "remove" - calc-mode: String - interpolation mode - key-times: String - time values - key-splines: String - bezier control points - additive: String - "replace" or "sum" - accumulate: String - "none" or "sum"

{type: String, ...} -> AnimateTransform

animate-motion

Create an animateMotion element for path-based animation.

Optional config fields: - path: String - SVG path data for motion - mpath-href: String - reference to a path element by ID - rotate: String - "auto", "auto-reverse", or angle in degrees - dur: String - duration - begin: String - when to start - end: String - when to end - repeat-count: String - repetitions or "indefinite" - repeat-dur: String - total duration - fill-mode: String - "freeze" or "remove" - calc-mode: String - interpolation mode - key-times: String - time values - key-splines: String - bezier control points - key-points: String - points along the path

{...} -> AnimateMotion

set

Create a set element to set an attribute at a specific time.

Required config fields: - attribute: String - the attribute to set - to: String - the value to set

Optional config fields: - begin: String - when to set the value - end: String - when to revert (optional) - dur: String - how long to maintain the value

{attribute: String, to: String, ...} -> Set

fade-in

Create a simple fade-in animation.

String -> Animate

fade-out

Create a simple fade-out animation.

String -> Animate

pulse

Create a pulse animation (scale up and down).

String -> AnimateTransform

spin

Create a continuous rotation animation.

Float -> Float -> String -> AnimateTransform

shake

Create a horizontal shake animation.

String -> AnimateTransform

bounce

Create a bounce animation (vertical).

String -> AnimateTransform

color-transition

Create a color transition animation.

String -> String -> String -> Animate

draw-stroke

Create a stroke dash animation (drawing effect).

String -> String -> Animate

render-animate

Render an Animate element to XML string.

Animate -> String

render-animate-transform

Render an AnimateTransform element to XML string.

AnimateTransform -> String

render-animate-motion

Render an AnimateMotion element to XML string.

AnimateMotion -> String

render-set

Render a Set element to XML string.

Set -> String

Matrix

2D affine transformation matrix Fields: a, b, c, d, e, f (following SVG matrix notation)

identity

Create the identity matrix (no transformation).

Matrix

translate

Create a translation matrix.

Float -> Float -> Matrix

scale

Create a uniform scale matrix.

Float -> Matrix

scale-xy

Create a non-uniform scale matrix.

Float -> Float -> Matrix

rotate

Create a rotation matrix (angle in degrees).

Float -> Matrix

rotate-around

Create a rotation matrix around a point (angle in degrees).

Float -> Float -> Float -> Matrix

skew-x

Create a skewX matrix (angle in degrees).

Float -> Matrix

skew-y

Create a skewY matrix (angle in degrees).

Float -> Matrix

multiply

Multiply two matrices (compose transformations). The result applies m2 first, then m1.

Matrix -> Matrix -> Matrix

compose

Compose a list of matrices (left to right application). compose [m1, m2, m3] applies m1 first, then m2, then m3.

[Matrix] -> Matrix

determinant

Calculate the determinant of a matrix.

Matrix -> Float

inverse

Calculate the inverse of a matrix. Returns None if the matrix is not invertible (determinant is 0).

Matrix -> Option Matrix

transform-point

Apply a matrix transformation to a point.

Matrix -> Float -> Float -> {x: Float, y: Float}

is-identity?

Check if a matrix is the identity matrix.

Matrix -> Bool

to-string

Convert matrix to SVG matrix() transform string.

Matrix -> String

to-transform-string

Convert matrix to individual transform operations (if possible). This produces more readable output for simple transforms. Falls back to matrix() for complex transforms.

Matrix -> String

get-a

Get the a component (scale x / cos rotation).

Matrix -> Float

get-b

Get the b component (skew y / sin rotation).

Matrix -> Float

get-c

Get the c component (skew x / -sin rotation).

Matrix -> Float

get-d

Get the d component (scale y / cos rotation).

Matrix -> Float

get-e

Get the e component (translate x).

Matrix -> Float

get-f

Get the f component (translate y).

Matrix -> Float

get-translation

Extract translation components.

Matrix -> {x: Float, y: Float}

get-scale

Extract scale factors (approximate, assumes no skew).

Matrix -> {x: Float, y: Float}

get-rotation

Extract rotation angle in degrees (approximate, assumes no skew).

Matrix -> Float

BBox

Axis-aligned bounding box Fields: x (left), y (top), width, height

new

Create a bounding box from x, y, width, height.

Float -> Float -> Float -> Float -> BBox

from-rect

Create a bounding box from a rectangle.

Float -> Float -> Float -> Float -> BBox

from-circle

Create a bounding box from a circle.

Float -> Float -> Float -> BBox

from-ellipse

Create a bounding box from an ellipse.

Float -> Float -> Float -> Float -> BBox

from-line

Create a bounding box from a line.

Float -> Float -> Float -> Float -> BBox

from-points

Create a bounding box from a list of points. Each point is a record with x and y fields.

[{x: Float, y: Float}] -> BBox

from-extents

Create a bounding box from min/max coordinates.

Float -> Float -> Float -> Float -> BBox

empty

Create an empty bounding box (zero size at origin).

BBox

infinite

Create an "infinite" bounding box for initial merge operations. Use this as starting point when merging multiple boxes.

BBox

get-x

Get the x coordinate (left edge).

BBox -> Float

get-y

Get the y coordinate (top edge).

BBox -> Float

get-width

Get the width.

BBox -> Float

get-height

Get the height.

BBox -> Float

get-right

Get the right edge (x + width).

BBox -> Float

get-bottom

Get the bottom edge (y + height).

BBox -> Float

center

Get the center point.

BBox -> {x: Float, y: Float}

top-left

Get the top-left corner.

BBox -> {x: Float, y: Float}

top-right

Get the top-right corner.

BBox -> {x: Float, y: Float}

bottom-left

Get the bottom-left corner.

BBox -> {x: Float, y: Float}

bottom-right

Get the bottom-right corner.

BBox -> {x: Float, y: Float}

area

Get the area of the bounding box.

BBox -> Float

perimeter

Get the perimeter of the bounding box.

BBox -> Float

aspect-ratio

Get the aspect ratio (width / height).

BBox -> Float

merge

Merge two bounding boxes into one that contains both.

BBox -> BBox -> BBox

merge-all

Merge a list of bounding boxes.

[BBox] -> BBox

intersect

Intersect two bounding boxes. Returns None if they don't overlap.

BBox -> BBox -> Option BBox

contains-point?

Check if a point is inside the bounding box.

Float -> Float -> BBox -> Bool

contains-box?

Check if the first bounding box completely contains the second.

BBox -> BBox -> Bool

overlaps?

Check if two bounding boxes overlap.

BBox -> BBox -> Bool

expand

Expand a bounding box by a given amount on all sides.

Float -> BBox -> BBox

expand-sides

Expand a bounding box by different amounts on each side.

Float -> Float -> Float -> Float -> BBox -> BBox

contract

Contract a bounding box by a given amount on all sides. Will not create negative dimensions.

Float -> BBox -> BBox

translate

Translate a bounding box by dx, dy.

Float -> Float -> BBox -> BBox

scale

Scale a bounding box uniformly around its center.

Float -> BBox -> BBox

scale-from-origin

Scale a bounding box from origin (0, 0).

Float -> BBox -> BBox

is-empty?

Check if a bounding box is empty (zero or negative dimensions).

BBox -> Bool

is-valid?

Check if a bounding box is valid (positive dimensions).

BBox -> Bool

is-square?

Check if a bounding box is square (width equals height).

BBox -> Bool

to-viewbox

Convert to SVG viewBox attribute value.

BBox -> String

to-record

Convert to a record with named fields.

BBox -> {x: Float, y: Float, width: Float, height: Float}

to-string

Convert to a string representation.

BBox -> String

linear-gradient

Create a linear gradient definition.

NonEmptyString -> Def

gradient-direction

Set the direction of a linear gradient.

Def -> {x1: Float, y1: Float, x2: Float, y2: Float} -> Def

radial-gradient

Create a radial gradient definition.

NonEmptyString -> Def

gradient-stop

Add a stop to a gradient.

Def -> {offset: Float, color: String, ...} -> Def

url

Create a URL reference for use with fill/stroke.

NonEmptyString -> String

with-fill

Set the fill attribute on an element.

Element -> String -> Element

with-stroke

Set the stroke attribute on an element.

Element -> String -> Element

with-stroke-width

Set the stroke-width attribute on an element.

Element -> String -> Element

with-opacity

Set the opacity attribute on an element.

Element -> String -> Element

with-id

Set the id attribute on an element.

Element -> String -> Element

with-class

Set the class attribute on an element.

Element -> String -> Element

with-transform

Set the transform attribute on an element.

Element -> String -> Element

with-title

Add a title element to an SVG document.

SvgDoc -> String -> SvgDoc

with-desc

Add a desc element to an SVG document.

SvgDoc -> String -> SvgDoc

with-stroke-linecap

Set the stroke-linecap attribute on an element.

Element -> String -> Element

with-stroke-linejoin

Set the stroke-linejoin attribute on an element.

Element -> String -> Element

with-stroke-dasharray

Set the stroke-dasharray attribute on an element.

Element -> String -> Element

group-new

Create an empty group element.

Returns: Element: An empty group element

Unit -> Element

SVG.group-new
  |> SVG.group-add rect
  |> SVG.group-add circle

group-add

Add an element to a group.

Element -> Element -> Element

group-add-all

Add multiple elements to a group.

Element -> [Element] -> Element

group-id

Set the ID attribute on a group.

Element -> String -> Element

group-class

Set the class attribute on a group.

Element -> String -> Element

group-transform

Set the transform attribute on a group.

Element -> String -> Element

render

Render an SVG document to an XML string.

Parameters:

• doc - The SVG document to render

Returns: String: The SVG as an XML string

SvgDoc -> String

xml = SVG.render doc
File.write "output.svg" xml

render-pretty

Render an SVG document with pretty printing.

Parameters:

• doc - The SVG document to render
• indent - Number of spaces for indentation

Returns: String: The SVG as a pretty-printed XML string

SvgDoc -> PositiveInt -> String

format-num

Format a number for SVG output. Integers are rendered without decimal points.

Float -> String

translate

Create a translate transform string.

Float -> Float -> String

rotate

Create a rotate transform string.

Float -> String

rotate-around

Create a rotate transform string around a point.

Float -> Float -> Float -> String

scale

Create a scale transform string.

Float -> String

scale-xy

Create a scale transform string with separate x and y factors.

Float -> Float -> String

skew-x

Create a skewX transform string.

Float -> String

skew-y

Create a skewY transform string.

Float -> String

PathCommand

Path command for the Path DSL

GradientStop

Gradient stop: offset (0-1), color, opacity (0-1)

TSpan

Text span: dx, dy, content

RichSpan

Rich text span with styling options RichSpan: content, dx, dy, fill, font-family, font-size, font-weight, font-style, baseline-shift

Point

Point: x, y coordinates

Element

SVG element types

Def

Definition types (gradients, patterns, markers, etc.)

SvgDoc

SVG document: width, height, view-box, preserve-aspect-ratio, defs, children

rect

Create a rectangle element.

Parameters:

• config - Record with x, y, width, height (required); rx, ry, fill, stroke, etc. (optional)

Returns: Element: A rectangle element

{x: Float, y: Float, width: Float, height: Float, ...} -> Element

SVG.rect {x: 10.0, y: 10.0, width: 100.0, height: 50.0}
SVG.rect {x: 10.0, y: 10.0, width: 100.0, height: 50.0, rx: 5.0, fill: "#ff0000"}

circle

Create a circle element.

Parameters:

• config - Record with cx, cy, r (required)

Returns: Element: A circle element

{cx: Float, cy: Float, r: Float, ...} -> Element

SVG.circle {cx: 50.0, cy: 50.0, r: 25.0}
SVG.circle {cx: 50.0, cy: 50.0, r: 25.0, fill: "red"}

ellipse

Create an ellipse element.

Parameters:

• config - Record with cx, cy, rx, ry (required)

Returns: Element: An ellipse element

{cx: Float, cy: Float, rx: Float, ry: Float, ...} -> Element

SVG.ellipse {cx: 50.0, cy: 50.0, rx: 40.0, ry: 20.0}

line

Create a line element.

Parameters:

• config - Record with x1, y1, x2, y2 (required)

Returns: Element: A line element

{x1: Float, y1: Float, x2: Float, y2: Float, ...} -> Element

SVG.line {x1: 0.0, y1: 0.0, x2: 100.0, y2: 100.0}

polyline

Create a polyline element (open shape).

Parameters:

• config - Record with points (list of Point values)

Returns: Element: A polyline element

{points: [Point], ...} -> Element

SVG.polyline {points: [SVG.pt 0.0 0.0, SVG.pt 50.0 25.0, SVG.pt 100.0 0.0]}

polygon

Create a polygon element (closed shape).

Parameters:

• config - Record with points (list of Point values)

Returns: Element: A polygon element

{points: [Point], ...} -> Element

SVG.polygon {points: [SVG.pt 50.0 0.0, SVG.pt 100.0 100.0, SVG.pt 0.0 100.0]}  # Triangle

pt

Create a point for use with polyline and polygon.

Float -> Float -> Point

text

Create a text element.

Parameters:

• config - Record with x, y, content (required)

Returns: Element: A text element

{x: Float, y: Float, content: String, ...} -> Element

SVG.text {x: 50.0, y: 50.0, content: "Hello"}

image

Create an image element.

Parameters:

• config - Record with x, y, width, height, href (required)

Returns: Element: An image element

{x: Float, y: Float, width: Float, height: Float, href: String, ...} -> Element

SVG.image {x: 0.0, y: 0.0, width: 100.0, height: 100.0, href: "logo.png"}

use

Create a use element to reference a symbol.

Parameters:

• config - Record with href, x, y, width, height

Returns: Element: A use element

{href: String, x: Float, y: Float, width: Float, height: Float, ...} -> Element

SVG.use {href: "my-symbol", x: 0.0, y: 0.0, width: 50.0, height: 50.0}

raw

Create a raw XML element (for custom SVG content).

String -> Element

title

Create a title element for accessibility.

Parameters:

• content - The title text

Returns: Element: A title element

String -> Element

SVG.title "My Chart"

desc

Create a desc element for accessibility.

Parameters:

• content - The description text

Returns: Element: A desc element

String -> Element

SVG.desc "A bar chart showing quarterly sales"

style

Create a style element for embedded CSS.

Parameters:

• css - The CSS content

Returns: Element: A style element

String -> Element

SVG.style ".highlight { fill: yellow; }"

text-block

Create a text block with automatic line wrapping based on newlines.

The leading parameter controls line spacing as a multiplier of font-size. For example, leading: 1.5 with font-size: 16 results in 24px line spacing.

Parameters:

• config - Record with x, y, content (required); leading, font-size, fill, etc. (optional)

Returns: Element: A text element with tspan children for each line

{x: Float, y: Float, content: String, ...} -> Element

SVG.text-block {x: 10.0, y: 20.0, content: "Line 1\nLine 2\nLine 3", leading: 1.5, font-size: "16"}

text-path

Create a text-path element for text flowing along a path.

Parameters:

• config - Record with href (path id), content (required); start-offset, spacing, method, id, class (optional)

Returns: Element: A textPath element

{href: String, content: String, ...} -> Element

SVG.text-path {href: "curve", content: "Text along a curve", start-offset: "10%"}

tspan-styled

Create a rich text span with styling.

Parameters:

• config - Record with content (required); dx, dy, fill, font-family, font-size, font-weight, font-style, baseline-shift (optional)

Returns: RichSpan: A styled text span

{content: String, ...} -> RichSpan

SVG.tspan-styled {content: "bold text", font-weight: "bold"}
SVG.tspan-styled {content: "italic", font-style: "italic"}
SVG.tspan-styled {content: "subscript", baseline-shift: "sub", font-size: "smaller"}

tspan

Create a simple rich text span (just content, no styling).

Parameters:

• content - The text content

Returns: RichSpan: A plain text span

String -> RichSpan

SVG.tspan "plain text"

rich-text

Create a rich text element from a list of styled spans.

Parameters:

• config - Record with x, y (required); fill, font-family, font-size, font-weight, anchor, id, class (optional)
• spans - List of RichSpan values

Returns: Element: A text element with rich content

{x: Float, y: Float, ...} -> [RichSpan] -> Element

SVG.rich-text {x: 10.0, y: 20.0, font-size: "16"} [
  SVG.span "Normal text ",
  SVG.tspan-styled {content: "bold", font-weight: "bold"},
  SVG.span " and ",
  SVG.tspan-styled {content: "italic", font-style: "italic"}
]