@zombie-mermaid/svg-renderer 3.0.0 → 3.2.0

package/src/c4/metrics.ts

@@ -0,0 +1,235 @@
+import type { C4Element } from '@zombie-mermaid/mermaid-parser'
+import { estimateTextWidth } from '../styles.ts'
+
+// ============================================================================
+// C4 SVG geometry, shared by the layout (which sizes and places shapes) and
+// the renderer (which draws text and glyphs inside them), so the two can't
+// drift.
+//
+// The numbers follow Mermaid 11.17's C4 renderer: its default `c4` config for
+// spacing, and sizes fitted to what it draws for each shape (a fixed 216px
+// width, 20px padding, a 14px name, a 0.75em type line and a 0.82em
+// description). Text is measured with this package's own width estimate
+// instead of the browser, so sizes agree with Mermaid's to within a few pixels.
+// ============================================================================
+
+export const C4 = {
+  // Mermaid's default `c4` config.
+  width: 216,
+  diagramMarginX: 50,
+  diagramMarginY: 10,
+  shapeMargin: 50,
+  shapePadding: 20,
+  shapeInRow: 4,
+  boundaryInRow: 2,
+  nextLinePaddingX: 0,
+  /**
+   * Mermaid limits a row to the browser's `screen.availWidth`, which a server
+   * cannot know; a common desktop width keeps the output stable.
+   */
+  screenWidth: 1440,
+  // Text.
+  nameSize: 14,
+  typeSize: 10.5,
+  descrSize: 11.5,
+  messageSize: 12,
+  boundarySize: 14,
+  // Line heights fitted to Mermaid: one more name line adds 15.35px, and a
+  // name plus its type line make 31.07px; each description line adds 17.1px.
+  nameLine: 15.35,
+  typeLine: 15.72,
+  descrLine: 17.1,
+  /** Each wrapped description line after the first (one `1.1em` row). */
+  descrExtraLine: 12.48,
+  /**
+   * Mermaid's text is about 8% narrower than this package's width estimate
+   * (its font is Open Sans, this package's is Inter); fitted on a measured
+   * name.
+   */
+  textScale: 0.922,
+  // Heights Mermaid measures for a boundary's heading text (fitted): the
+  // title at 16px bold, the `[type]` at 14px, a description at 12px.
+  boundaryLabelHeight: 18,
+  boundaryTypeHeight: 16.1,
+  boundaryDescrHeight: 14.4,
+  /** Height Mermaid reserves for the unnamed root boundary's heading. */
+  rootHeadingHeight: 47,
+  /** Extra height added to a diagram with a title (Mermaid's `extraVertForTitle`). */
+  titleExtra: 60,
+  // Shapes.
+  cornerRadius: 12,
+  strokeWidth: 2,
+  /**
+   * Person proportions at the standard width (Mermaid scales the pill's
+   * corners and head with the width, and the head's rise a little faster).
+   */
+  personRx: 38.232,
+  personHeadRadius: 49.68,
+  /** Distance from the top of a person to the top of its pill (under the head). */
+  personPillTop: 85.946,
+  personPillTopPerExtraWidth: 0.4,
+  /** Cylinder height lost where its text block meets the lower ellipse. */
+  dbTrim: 3.91,
+  /** Queue height over its text block. */
+  queueExtra: 10,
+} as const
+
+/**
+ * Width the text of an element wraps to. Fitted to Mermaid: a 173px name
+ * stays on one line and a 231px one wraps, and a 188px name stays on one.
+ */
+export const C4_TEXT_WIDTH = C4.width - C4.shapePadding
+
+/** Greedy word wrap by estimated pixel width. */
+export function wrapToWidth(
+  text: string,
+  maxWidth: number,
+  fontSize: number,
+  weight: number,
+): string[] {
+  const lines: string[] = []
+  for (const paragraph of text.split('\n')) {
+    let cur = ''
+    for (const word of paragraph.split(/\s+/).filter(Boolean)) {
+      const next = cur ? `${cur} ${word}` : word
+      if (
+        cur &&
+        estimateTextWidth(next, fontSize, weight) * C4.textScale > maxWidth
+      ) {
+        lines.push(cur)
+        cur = word
+      } else {
+        cur = next
+      }
+    }
+    lines.push(cur)
+  }
+  return lines
+}
+
+/** A person's pill corner, head radius and pill top for a box of this width. */
+export function c4PersonGeometry(width: number): {
+  rx: number
+  headRadius: number
+  pillTop: number
+} {
+  const scale = width / C4.width
+  return {
+    rx: C4.personRx * scale,
+    headRadius: C4.personHeadRadius * scale,
+    pillTop:
+      C4.personPillTop + C4.personPillTopPerExtraWidth * (width - C4.width),
+  }
+}
+
+export interface C4ShapeSize {
+  width: number
+  height: number
+  /** Height of the text block (name, type, description lines). */
+  textHeight: number
+}
+
+/** Height of an element's text block for its wrapped lines. */
+export function c4TextBlockHeight(
+  nameLines: number,
+  descriptionLines: number,
+): number {
+  return (
+    nameLines * C4.nameLine +
+    C4.typeLine +
+    c4DescriptionHeight(descriptionLines)
+  )
+}
+
+/** Height of a description wrapped to this many lines. */
+export function c4DescriptionHeight(lines: number): number {
+  return lines === 0 ? 0 : C4.descrLine + (lines - 1) * C4.descrExtraLine
+}
+
+/** Cylinder cap radii for a box of this width: `rx` across, `ry` down. */
+export function c4CylinderCap(width: number): { rx: number; ry: number } {
+  const rx = width / 2
+  return { rx, ry: rx / (2.5 + width / 50) }
+}
+
+/** Queue cap radii for a pipe of this height: `rx` across, `ry` down. */
+export function c4QueueCap(height: number): { rx: number; ry: number } {
+  const ry = height / 2
+  return { rx: ry / (2.5 + height / 50), ry }
+}
+
+/** Estimated width of a text line as Mermaid would measure it. */
+export function c4TextWidth(
+  text: string,
+  fontSize: number,
+  weight: number,
+): number {
+  return estimateTextWidth(text, fontSize, weight) * C4.textScale
+}
+
+/**
+ * The size Mermaid gives an element: the standard width unless its text is
+ * wider (then the text plus padding both sides), and a height that follows
+ * its wrapped text lines.
+ */
+export function c4ShapeSize(
+  el: Pick<C4Element, 'kind' | 'shape'>,
+  nameLines: number,
+  descriptionLines: number,
+  textWidth: number,
+): C4ShapeSize {
+  const textHeight = c4TextBlockHeight(nameLines, descriptionLines)
+  const boxHeight = textHeight + 2 * C4.shapePadding
+  const width = Math.max(C4.width, textWidth + 2 * C4.shapePadding)
+  if (el.kind === 'person') {
+    return {
+      width,
+      // The head rises above the pill, which is as tall as the text needs.
+      height: c4PersonGeometry(width).pillTop + boxHeight,
+      textHeight,
+    }
+  }
+  if (el.shape === 'db') {
+    const { ry } = c4CylinderCap(width)
+    return { width, height: boxHeight + 2 * ry - C4.dbTrim, textHeight }
+  }
+  if (el.shape === 'queue') {
+    const height = textHeight + C4.queueExtra
+    const { rx } = c4QueueCap(height)
+    return { width: width + 3 * rx, height, textHeight }
+  }
+  return { width, height: boxHeight, textHeight }
+}
+
+/** Mermaid's C4 colours by kind and externality. */
+export interface C4Palette {
+  fill: string
+  stroke: string
+  text: string
+}
+
+export function c4Palette(el: Pick<C4Element, 'kind' | 'external'>): C4Palette {
+  const text = '#ffffff'
+  if (el.external) {
+    switch (el.kind) {
+      case 'person':
+        return { fill: '#686868', stroke: '#8a8a8a', text }
+      case 'system':
+        return { fill: '#999999', stroke: '#8a8a8a', text }
+      case 'container':
+        return { fill: '#b3b3b3', stroke: '#a6a6a6', text }
+      case 'component':
+        return { fill: '#cccccc', stroke: '#bfbfbf', text }
+    }
+  }
+  switch (el.kind) {
+    case 'person':
+      return { fill: '#08427b', stroke: '#073b6f', text }
+    case 'system':
+      return { fill: '#1168bd', stroke: '#3c7fc0', text }
+    case 'container':
+      return { fill: '#438dd5', stroke: '#3c7fc0', text }
+    case 'component':
+      return { fill: '#85bbf0', stroke: '#78a8d8', text }
+  }
+}

package/src/c4/renderer.ts

@@ -0,0 +1,366 @@
+import type {
+  PositionedC4Boundary,
+  PositionedC4Diagram,
+  PositionedC4Element,
+  PositionedC4Relationship,
+} from '@zombie-mermaid/mermaid-parser'
+import {
+  c4BoundaryTypeLine,
+  c4RelLabelLines,
+  c4TypeLine,
+} from '@zombie-mermaid/mermaid-parser'
+import type { DiagramColors, Point, SvgEmitOptions } from '@zombie-mermaid/core'
+import {
+  svgOpenTag,
+  buildStyleBlock,
+  escapeXml,
+  escapeAttr,
+  f,
+} from '@zombie-mermaid/core'
+import { withDataSrc } from '../renderer.ts'
+import { FONT_SIZES, TEXT_BASELINE_SHIFT } from '../styles.ts'
+import type { FontSizes } from '../styles.ts'
+import {
+  C4,
+  c4CylinderCap,
+  c4DescriptionHeight,
+  c4Palette,
+  c4PersonGeometry,
+  c4QueueCap,
+  c4TextBlockHeight,
+} from './metrics.ts'
+import type { C4Palette } from './metrics.ts'
+
+// ============================================================================
+// C4 diagram SVG renderer, drawn the way Mermaid draws C4.
+//
+// Render order (as in Mermaid): boundaries, elements, then relationships,
+// each with its label on top. Elements use Mermaid's C4 colours and stay
+// fixed across themes, as C4 colours carry meaning; boundaries, lines and
+// labels follow the theme's CSS variables.
+// ============================================================================
+
+/**
+ * Render a positioned C4 diagram as an SVG string. Parameters mirror
+ * `renderErSvg`; see there for the `embedSource` / `title` / `decorative` /
+ * `emit` contract.
+ */
+export function renderC4Svg(
+  diagram: PositionedC4Diagram,
+  colors: DiagramColors,
+  font: string = 'Inter',
+  transparent: boolean = false,
+  _fontSizes: FontSizes = FONT_SIZES,
+  embedSource?: string,
+  title?: string,
+  decorative?: boolean,
+  emit: SvgEmitOptions = {},
+): string {
+  const parts: string[] = []
+  parts.push(
+    withDataSrc(
+      svgOpenTag(
+        diagram.width,
+        diagram.height,
+        colors,
+        transparent,
+        title ?? diagram.title,
+        decorative,
+        undefined,
+        emit.styleAttribute,
+      ),
+      embedSource,
+    ),
+  )
+  parts.push(buildStyleBlock(font, false, emit.nonce))
+
+  if (diagram.title && diagram.titlePosition) {
+    // Mermaid sets the title as plain text at its start point.
+    parts.push(
+      f`<text class="c4-title" x="${diagram.titlePosition.x}" y="${diagram.titlePosition.y}" dy="${TEXT_BASELINE_SHIFT}" ` +
+        f`font-size="16" fill="var(--_text)">${escapeXml(diagram.title)}</text>`,
+    )
+  }
+
+  for (const b of diagram.boundaries) parts.push(renderBoundary(b))
+  for (const el of diagram.elements) parts.push(renderElement(el))
+  for (const r of diagram.relationships) {
+    parts.push(renderRelationshipLine(r))
+    parts.push(renderRelationshipLabel(r))
+  }
+
+  parts.push('</svg>')
+  return parts.filter(Boolean).join('\n')
+}
+
+// ---------------------------------------------------------------------------
+// Boundaries
+// ---------------------------------------------------------------------------
+
+/** One centred line of text. */
+function centred(
+  text: string,
+  x: number,
+  y: number,
+  size: number,
+  extra: string,
+): string {
+  return (
+    f`  <text x="${x}" y="${y}" text-anchor="middle" dy="${TEXT_BASELINE_SHIFT}" font-size="${size}" ` +
+    f`${extra}>${escapeXml(text)}</text>`
+  )
+}
+
+function renderBoundary(b: PositionedC4Boundary): string {
+  const parts: string[] = []
+  parts.push(
+    f`<g class="c4-boundary" data-id="${escapeAttr(b.alias)}" data-label="${escapeAttr(b.label)}" data-depth="${b.depth}">`,
+  )
+  // A dashed square-cornered frame with no fill, as Mermaid draws it.
+  parts.push(
+    f`  <rect x="${b.x}" y="${b.y}" width="${b.width}" height="${b.height}" rx="2.5" ry="2.5" ` +
+      `fill="none" stroke="var(--_text)" stroke-width="1" stroke-dasharray="7,7" />`,
+  )
+  const cx = b.x + b.width / 2
+  parts.push(
+    centred(
+      b.label,
+      cx,
+      b.y + (b.labelY ?? 8),
+      C4.boundarySize + 2,
+      'font-weight="700" fill="var(--_text)"',
+    ),
+  )
+  const typeLine = c4BoundaryTypeLine({
+    alias: b.alias,
+    label: b.label,
+    ...(b.type ? { type: b.type } : {}),
+    elementAliases: [],
+    children: [],
+  })
+  if (typeLine && b.typeY !== undefined) {
+    parts.push(
+      centred(
+        typeLine,
+        cx,
+        b.y + b.typeY,
+        C4.boundarySize,
+        'fill="var(--_text)"',
+      ),
+    )
+  }
+  if (b.description && b.descrY !== undefined) {
+    parts.push(
+      centred(
+        b.description,
+        cx,
+        b.y + b.descrY,
+        C4.boundarySize - 2,
+        'fill="var(--_text)"',
+      ),
+    )
+  }
+  parts.push('</g>')
+  return parts.join('\n')
+}
+
+// ---------------------------------------------------------------------------
+// Elements
+// ---------------------------------------------------------------------------
+
+function renderElement(el: PositionedC4Element): string {
+  const pal = c4Palette(el)
+  const { x, y, width: w, height: h } = el
+  const cx = x + w / 2
+  const textH = c4TextBlockHeight(
+    el.nameLines.length,
+    el.descriptionLines.length,
+  )
+  const parts: string[] = []
+  parts.push(
+    f`<g class="c4-element" data-id="${escapeAttr(el.alias)}" data-kind="${el.kind}" data-shape="${el.shape}" ` +
+      f`data-external="${el.external}" data-label="${escapeAttr(el.label)}">`,
+  )
+
+  // Where the text block starts, and the x it is centred on.
+  let top: number
+  let textCx = cx
+  if (el.kind === 'person') {
+    parts.push(...personShape(el, pal))
+    const g = c4PersonGeometry(w)
+    top = y + g.pillTop + C4.shapePadding
+  } else if (el.shape === 'db') {
+    parts.push(...cylinderShape(el, pal))
+    const { ry } = c4CylinderCap(w)
+    // Centred in the body below the upper ellipse.
+    top = y + (2 * ry + h) / 2 - textH / 2
+  } else if (el.shape === 'queue') {
+    parts.push(...queueShape(el, pal))
+    const { rx } = c4QueueCap(h)
+    // Mermaid centres the text one cap radius left of the pipe's centre.
+    textCx = cx - rx
+    top = y + h / 2 - textH / 2
+  } else {
+    parts.push(
+      f`  <rect x="${x}" y="${y}" width="${w}" height="${h}" rx="${C4.cornerRadius}" ry="${C4.cornerRadius}" ` +
+        f`fill="${pal.fill}" stroke="${pal.stroke}" stroke-width="${C4.strokeWidth}" />`,
+    )
+    top = y + C4.shapePadding
+  }
+
+  let cursor = top
+  for (const line of el.nameLines) {
+    parts.push(
+      centred(
+        line,
+        textCx,
+        cursor + C4.nameLine / 2,
+        C4.nameSize,
+        f`font-weight="700" fill="${pal.text}"`,
+      ),
+    )
+    cursor += C4.nameLine
+  }
+  parts.push(
+    centred(
+      c4TypeLine(el),
+      textCx,
+      cursor + C4.typeLine / 2,
+      C4.typeSize,
+      f`fill="${pal.text}"`,
+    ),
+  )
+  cursor += C4.typeLine
+  el.descriptionLines.forEach((line, i) => {
+    // The first line is as tall as Mermaid measures a one-line text; each
+    // wrapped line after it is one `1.1em` row.
+    parts.push(
+      centred(
+        line,
+        textCx,
+        cursor + C4.descrLine / 2 + i * C4.descrExtraLine,
+        C4.descrSize,
+        f`fill="${pal.text}"`,
+      ),
+    )
+  })
+  cursor += c4DescriptionHeight(el.descriptionLines.length)
+  parts.push('</g>')
+  return parts.join('\n')
+}
+
+/** A rounded pill with a round head rising out of its top, as Mermaid draws a person. */
+function personShape(el: PositionedC4Element, pal: C4Palette): string[] {
+  const { x, width: w } = el
+  const { rx, headRadius, pillTop: rise } = c4PersonGeometry(w)
+  const y = el.y
+  const cx = x + w / 2
+  const pillTop = y + rise
+  const pillHeight = el.y + el.height - pillTop
+  const style = f`fill="${pal.fill}" stroke="${pal.stroke}" stroke-width="${C4.strokeWidth}"`
+  return [
+    f`  <rect x="${x}" y="${pillTop}" width="${w}" height="${pillHeight}" rx="${rx}" ry="${rx}" ${style} />`,
+    f`  <circle cx="${cx}" cy="${y + headRadius}" r="${headRadius}" ${style} />`,
+  ]
+}
+
+function cylinderShape(el: PositionedC4Element, pal: C4Palette): string[] {
+  const { x, y, width: w, height: h } = el
+  const { rx, ry } = c4CylinderCap(w)
+  const style = f`fill="${pal.fill}" stroke="${pal.stroke}" stroke-width="${C4.strokeWidth}"`
+  return [
+    f`  <path d="M ${x} ${y + ry} L ${x} ${y + h - ry} A ${rx} ${ry} 0 0 0 ${x + w} ${y + h - ry} L ${x + w} ${y + ry} Z" ${style} />`,
+    f`  <ellipse cx="${x + rx}" cy="${y + ry}" rx="${rx}" ry="${ry}" ${style} />`,
+  ]
+}
+
+/**
+ * A pipe on its side, as Mermaid draws it: rounded at the left, with the
+ * ellipse face showing at the right end.
+ */
+function queueShape(el: PositionedC4Element, pal: C4Palette): string[] {
+  const { x, y, width: w, height: h } = el
+  const { rx, ry } = c4QueueCap(h)
+  const style = f`fill="${pal.fill}" stroke="${pal.stroke}" stroke-width="${C4.strokeWidth}"`
+  return [
+    f`  <path d="M ${x + w - rx} ${y} H ${x + rx} A ${rx} ${ry} 0 0 0 ${x + rx} ${y + h} H ${x + w - rx} Z" ${style} />`,
+    f`  <ellipse cx="${x + w - rx}" cy="${y + ry}" rx="${rx}" ry="${ry}" ${style} />`,
+  ]
+}
+
+// ---------------------------------------------------------------------------
+// Relationships
+// ---------------------------------------------------------------------------
+
+/** Mermaid's arrowhead: a 10 by 10 triangle whose tip sits on the line's end. */
+function arrowHead(tip: Point, from: Point): string {
+  const dx = tip.x - from.x
+  const dy = tip.y - from.y
+  const len = Math.hypot(dx, dy)
+  if (len === 0) return ''
+  const ux = dx / len
+  const uy = dy / len
+  const L = 10
+  const W = 5
+  const bx = tip.x - ux * L
+  const by = tip.y - uy * L
+  return (
+    f`<polygon class="c4-arrowhead" points="${tip.x},${tip.y} ${bx - uy * W},${by + ux * W} ${bx + uy * W},${by - ux * W}" ` +
+    `fill="var(--_text)" />`
+  )
+}
+
+function renderRelationshipLine(rel: PositionedC4Relationship): string {
+  const [start, end] = [rel.points[0], rel.points[rel.points.length - 1]]
+  if (!start || !end || start === end) return ''
+  const attrs = [
+    'class="c4-relationship"',
+    f`data-from="${escapeAttr(rel.from)}"`,
+    f`data-to="${escapeAttr(rel.to)}"`,
+  ]
+  if (rel.label) attrs.push(f`data-label="${escapeAttr(rel.label)}"`)
+  if (rel.technology) {
+    attrs.push(f`data-technology="${escapeAttr(rel.technology)}"`)
+  }
+  const d = rel.curve
+    ? f`M ${start.x},${start.y} Q ${rel.curve.x},${rel.curve.y} ${end.x},${end.y}`
+    : f`M ${start.x},${start.y} L ${end.x},${end.y}`
+  const line = f`<path ${attrs.join(' ')} d="${d}" fill="none" stroke="var(--_text)" stroke-width="1" />`
+  // A curve leaves and arrives along its control point.
+  const beforeEnd = rel.curve ?? start
+  const afterStart = rel.curve ?? end
+  const endHead = arrowHead(end, beforeEnd)
+  const startHead = arrowHead(start, afterStart)
+  const heads = rel.bidirectional
+    ? [endHead, startHead]
+    : [rel.reversed ? startHead : endHead]
+  return [line, ...heads].filter(Boolean).join('\n')
+}
+
+/** Plain text at the middle of the chord: the label, then `[technology]` below. */
+function renderRelationshipLabel(rel: PositionedC4Relationship): string {
+  const lines = c4RelLabelLines(rel)
+  if (lines.length === 0 || !rel.labelPosition) return ''
+  const { x, y } = rel.labelPosition
+  const parts = [
+    f`<g class="c4-relationship-label" data-from="${escapeAttr(rel.from)}" data-to="${escapeAttr(rel.to)}">`,
+  ]
+  lines.forEach((line, i) => {
+    const isTech = rel.technology !== undefined && i === lines.length - 1
+    // Mermaid puts the technology one font size plus 5px below the label.
+    const cy = y + (i === 0 ? 0 : C4.messageSize + 5)
+    parts.push(
+      centred(
+        line,
+        isTech && rel.technologyX !== undefined ? rel.technologyX : x,
+        cy,
+        C4.messageSize,
+        isTech
+          ? 'font-style="italic" fill="var(--_text)"'
+          : 'fill="var(--_text)"',
+      ),
+    )
+  })
+  parts.push('</g>')
+  return parts.join('\n')
+}