@zombie-mermaid/svg-renderer 4.2.2 → 5.0.0

package/src/c4/metrics.ts

@@ -1,261 +0,0 @@
-import type { C4Element } from '@zombie-mermaid/mermaid-parser'
-import { estimateTextWidth } from '../styles.ts'
-import { arialAdvance } from './arial-widths.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 by summing Arial advances instead of in the
-// browser, which matches the recorded Mermaid diagrams to a fraction of a pixel.
-// ============================================================================
-
-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,
-  /**
-   * For text outside printable ASCII, which has no Arial advance table:
-   * Arial is about 8% narrower than this package's width estimate (Inter).
-   */
-  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, from Mermaid's person shape: the pill's corner is
-   * 17.7% of the width (at most 45% of the pill's height), the head's radius
-   * is 23% of the width clamped to 16..56, and the head overlaps the pill by
-   * 27% of its radius.
-   */
-  personRx: 0.177,
-  personRxMaxOfHeight: 0.45,
-  personHeadRatio: 0.23,
-  personHeadMin: 16,
-  personHeadMax: 56,
-  personHeadOverlap: 0.27,
-  /** 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: the shape's width less its padding
- * on both sides (Mermaid's `c4LabelHelper`).
- */
-export const C4_TEXT_WIDTH = C4.width - 2 * C4.shapePadding
-
-/**
- * Greedy word wrap by estimated pixel width. Mermaid decides where to break
- * with the text at regular weight and draws a name in bold afterwards, so a
- * bold name can come out wider than the limit.
- */
-export function wrapToWidth(
-  text: string,
-  maxWidth: number,
-  fontSize: 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 && c4TextWidth(next, fontSize, 400) > 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
- * (and, when known, this height: a short pill gets smaller corners).
- */
-export function c4PersonGeometry(
-  width: number,
-  height?: number,
-): {
-  rx: number
-  headRadius: number
-  pillTop: number
-} {
-  const headRadius = Math.min(
-    Math.max(width * C4.personHeadRatio, C4.personHeadMin),
-    C4.personHeadMax,
-  )
-  // The head's diameter less the part that overlaps the pill.
-  const pillTop = headRadius * (2 - C4.personHeadOverlap)
-  const pillHeight = height === undefined ? Infinity : height - pillTop
-  return {
-    rx: Math.min(width * C4.personRx, pillHeight * C4.personRxMaxOfHeight),
-    headRadius,
-    pillTop,
-  }
-}
-
-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: sans-serif
- * advances for printable ASCII, this package's own estimate (scaled to match)
- * for anything else.
- */
-export function c4TextWidth(
-  text: string,
-  fontSize: number,
-  weight: number,
-): number {
-  let width = 0
-  for (const ch of text) {
-    const em = arialAdvance(ch, weight >= 600)
-    width +=
-      em === undefined
-        ? estimateTextWidth(ch, fontSize, weight) * C4.textScale
-        : em * fontSize
-  }
-  return width
-}
-
-/**
- * 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

@@ -1,366 +0,0 @@
-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, el.height)
-  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')
-}