@hecto/svg

Typed procedural SVG nodes, paths, transforms, paint, filters, definition hoisting, and rendering.

pnpm add @hecto/svg

import { pipe } from '@hecto/fp'
import { rgb } from '@hecto/color'
import { circle, fill, render, translate, viewBox } from '@hecto/svg'

const base = circle(32)
const moved = translate(base, 50, 50)
const painted = fill(moved, rgb(1, 0, 0))
const directBadge = viewBox(painted, 0, 0, 100, 100)

const pipedBadge = pipe(base, translate(50, 50), fill(rgb(1, 0, 0)), viewBox(0, 0, 100, 100))

const markup = render(directBadge)
const sameMarkup = pipe(pipedBadge, render)

Data-taking operators support direct data-first and curried data-last calls under the same name. XML escaping, generated identifiers, and shared <defs> are owned by the renderer.

Resource identity across roots

Use a distinct stable idPrefix for each SVG that shares a document:

const leftMarkup = render(directBadge, { idPrefix: 'dashboard:left' })
const rightMarkup = render(pipedBadge, { idPrefix: 'dashboard:right' })

Pass the same prefix for the same root during server rendering and hydration. Prefixes are encoded without randomness or process-wide counters. Generated resources share one allocator that reserves authored attrs.id values throughout the render tree, including pattern, clip, mask and symbol contents. Repeated references to one resource object still share one definition.

Omitting idPrefix retains the standalone _g0/_s0 naming convention. It does not provide uniqueness across separate render calls. Authored IDs are preserved; callers must also keep their authored IDs unique across roots in one document. Separate calls cannot discover IDs authored in other roots. If authored IDs can fall inside another root's generated namespace, provide those IDs through reservedIds on every affected render:

const authoredDocumentIds = new Set(['svg-00720069006700680074-g0'])
const safeMarkup = render(directBadge, {
  idPrefix: 'right',
  reservedIds: authoredDocumentIds,
})

The renderer copies these reservations and does not mutate the caller's set. Alternatively, keep authored IDs in a distinct naming scheme from generated IDs.

Hit-test limits

hitTest from @hecto/svg/la does not implement path or line containment. These nodes return no hit even when the point appears inside a painted path. Text uses only its baseline, font size and starting x coordinate; it does not measure glyph width, so a point far to the right can still match. Use a measured rectangle for text interaction bounds or a browser geometry API when exact path or text hit testing is required. Existing transforms continue to use LA affine operations; these limits do not change rendering or matrix behavior.

Dual operation reference

toClip(node)                         / toClip()(node)
toMask(node)                         / toMask()(node)
fill(node, paint)                    / fill(paint)(node)
stroke(node, paint, width, options?) / stroke(paint, width, options?)(node)
opacity(node, alpha)                 / opacity(alpha)(node)
translate(node, dx, dy)              / translate(dx, dy)(node)
rotate(node, degrees, cx?, cy?)      / rotate(degrees, cx?, cy?)(node)
scale(node, sx, sy?)                 / scale(sx, sy?)(node)
skewX(node, degrees)                 / skewX(degrees)(node)
skewY(node, degrees)                 / skewY(degrees)(node)
clip(node, clipPath)                 / clip(clipPath)(node)
mask(node, maskValue)                / mask(maskValue)(node)
filter(node, filterValue)            / filter(filterValue)(node)
viewBox(node, x, y, width, height)   / viewBox(x, y, width, height)(node)

path.lineTo(pathValue, x, y)                         / path.lineTo(x, y)(pathValue)
path.curveTo(pathValue, x1, y1, x2, y2, x, y)       / path.curveTo(x1, y1, x2, y2, x, y)(pathValue)
path.quadTo(pathValue, x1, y1, x, y)                 / path.quadTo(x1, y1, x, y)(pathValue)
path.arcTo(pathValue, rx, ry, large, sweep, x, y)    / path.arcTo(rx, ry, large, sweep, x, y)(pathValue)
path.close(pathValue)                                / path.close()(pathValue)
path.toNode(pathValue)                               / path.toNode()(pathValue)

mul(a, b)                            / mul(b)(a)
render(node, options?)

lerpTransform(a, b, t)               / lerpTransform(b, t)(a)
toQuad(node, corners)                / toQuad(corners)(node)
hitTest(root, point)                 / hitTest(point)(root)
fitBezier(points)                    / fitBezier()(points)
alignToPrincipalAxis(node, points)   / alignToPrincipalAxis(points)(node)
symmetry(node, count, step)          / symmetry(count, step)(node)

Documentation