@zombie-mermaid/svg-renderer 2.2.1

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@zombie-mermaid/svg-renderer",
+  "version": "2.2.1",
+  "license": "MIT",
+  "description": "SVG rendering primitives and the ELK-backed layout engine behind zombie-mermaid's SVG output.",
+  "type": "module",
+  "sideEffects": false,
+  "main": "dist/index.cjs",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "files": [
+    "src/",
+    "dist/",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "@zombie-mermaid/core": "workspace:*",
+    "@zombie-mermaid/mermaid-parser": "workspace:*",
+    "elkjs": "^0.11.0"
+  }
+}

package/src/__tests__/elk-adapter-utils.test.ts

@@ -0,0 +1,166 @@
+/**
+ * Unit tests for the shared ELK edge-geometry extraction helpers
+ * (`extractEdgePoints` / `extractEdgeLabelPosition`).
+ *
+ * `from-elk.ts`, `class/layout.ts`, and `er/layout.ts` all exercise this
+ * module indirectly through full-diagram integration tests, but those
+ * only ever hit the "happy path" (an edge with sections and, sometimes,
+ * a placed label). These tests cover the defensive branches directly —
+ * missing/empty sections, missing/empty labels, an unplaced label, and
+ * missing bend points/label dimensions — so every branch has direct
+ * coverage rather than relying on an integration test to happen to hit it.
+ */
+import { describe, it, expect } from 'vitest'
+import type { ElkExtendedEdge } from 'elkjs'
+import {
+  extractEdgePoints,
+  extractEdgeLabelPosition,
+} from '@zombie-mermaid/svg-renderer'
+
+function edge(partial: Partial<ElkExtendedEdge>): ElkExtendedEdge {
+  return { id: 'e0', sources: ['a'], targets: ['b'], ...partial }
+}
+
+describe('extractEdgePoints', () => {
+  it('returns an empty array when the edge has no sections property', () => {
+    expect(extractEdgePoints(edge({}))).toEqual([])
+  })
+
+  it('returns an empty array when sections is an empty array', () => {
+    expect(extractEdgePoints(edge({ sections: [] }))).toEqual([])
+  })
+
+  it('walks start -> end with no bend points', () => {
+    const e = edge({
+      sections: [
+        {
+          id: 's0',
+          startPoint: { x: 10, y: 20 },
+          endPoint: { x: 30, y: 40 },
+        },
+      ],
+    })
+    expect(extractEdgePoints(e)).toEqual([
+      { x: 10, y: 20 },
+      { x: 30, y: 40 },
+    ])
+  })
+
+  it('walks start -> bendPoints -> end when bend points are present', () => {
+    const e = edge({
+      sections: [
+        {
+          id: 's0',
+          startPoint: { x: 0, y: 0 },
+          endPoint: { x: 100, y: 0 },
+          bendPoints: [
+            { x: 25, y: 50 },
+            { x: 75, y: 50 },
+          ],
+        },
+      ],
+    })
+    expect(extractEdgePoints(e)).toEqual([
+      { x: 0, y: 0 },
+      { x: 25, y: 50 },
+      { x: 75, y: 50 },
+      { x: 100, y: 0 },
+    ])
+  })
+
+  it('translates every point by offsetX/offsetY when provided', () => {
+    const e = edge({
+      sections: [
+        {
+          id: 's0',
+          startPoint: { x: 0, y: 0 },
+          endPoint: { x: 10, y: 10 },
+          bendPoints: [{ x: 5, y: 5 }],
+        },
+      ],
+    })
+    expect(extractEdgePoints(e, 100, 200)).toEqual([
+      { x: 100, y: 200 },
+      { x: 105, y: 205 },
+      { x: 110, y: 210 },
+    ])
+  })
+
+  it('only reads the first section when multiple are present', () => {
+    const e = edge({
+      sections: [
+        { id: 's0', startPoint: { x: 0, y: 0 }, endPoint: { x: 1, y: 1 } },
+        { id: 's1', startPoint: { x: 9, y: 9 }, endPoint: { x: 8, y: 8 } },
+      ],
+    })
+    expect(extractEdgePoints(e)).toEqual([
+      { x: 0, y: 0 },
+      { x: 1, y: 1 },
+    ])
+  })
+})
+
+describe('extractEdgeLabelPosition', () => {
+  it('returns undefined when the edge has no labels property', () => {
+    expect(extractEdgeLabelPosition(edge({}))).toBeUndefined()
+  })
+
+  it('returns undefined when labels is an empty array', () => {
+    expect(extractEdgeLabelPosition(edge({ labels: [] }))).toBeUndefined()
+  })
+
+  it('returns undefined when the label has no x/y (ELK left it unplaced)', () => {
+    expect(
+      extractEdgeLabelPosition(edge({ labels: [{ text: 'foo' }] })),
+    ).toBeUndefined()
+  })
+
+  it('returns undefined when only x is set (y still unplaced)', () => {
+    expect(
+      extractEdgeLabelPosition(edge({ labels: [{ text: 'foo', x: 5 }] })),
+    ).toBeUndefined()
+  })
+
+  it('computes the label center, defaulting missing width/height to 0', () => {
+    expect(
+      extractEdgeLabelPosition(
+        edge({ labels: [{ text: 'foo', x: 10, y: 20 }] }),
+      ),
+    ).toEqual({ x: 10, y: 20 })
+  })
+
+  it('computes the label center from x/y/width/height', () => {
+    expect(
+      extractEdgeLabelPosition(
+        edge({
+          labels: [{ text: 'foo', x: 10, y: 20, width: 40, height: 10 }],
+        }),
+      ),
+    ).toEqual({ x: 30, y: 25 })
+  })
+
+  it('translates the computed center by offsetX/offsetY when provided', () => {
+    expect(
+      extractEdgeLabelPosition(
+        edge({
+          labels: [{ text: 'foo', x: 10, y: 20, width: 40, height: 10 }],
+        }),
+        100,
+        200,
+      ),
+    ).toEqual({ x: 130, y: 225 })
+  })
+
+  it('only reads the first label when multiple are present', () => {
+    expect(
+      extractEdgeLabelPosition(
+        edge({
+          labels: [
+            { text: 'first', x: 0, y: 0 },
+            { text: 'second', x: 100, y: 100 },
+          ],
+        }),
+      ),
+    ).toEqual({ x: 0, y: 0 })
+  })
+})

package/src/class/layout.ts

@@ -0,0 +1,360 @@
+/**
+ * Class diagram layout engine (ELK.js).
+ *
+ * Each class box has 3 compartments:
+ *   1. Header (class name + optional annotation)
+ *   2. Attributes section
+ *   3. Methods section
+ */
+
+import type { ElkNode, ElkExtendedEdge } from 'elkjs'
+import type {
+  ClassDiagram,
+  ClassNode,
+  ClassMember,
+  PositionedClassDiagram,
+  PositionedClassNode,
+  PositionedClassNote,
+  PositionedClassRelationship,
+} from '@zombie-mermaid/mermaid-parser'
+import { formatClassMember } from '@zombie-mermaid/mermaid-parser'
+import type { ClassRenderOptions } from '@zombie-mermaid/core'
+import {
+  estimateTextWidth,
+  estimateMonoTextWidth,
+  FONT_WEIGHTS,
+  resolveFontSizes,
+} from '../styles.ts'
+import { elkLayoutSync } from '../elk-instance.ts'
+import {
+  extractEdgePoints,
+  extractEdgeLabelPosition,
+} from '../layout-engine/elk-adapter-utils.ts'
+import {
+  ELK_DIRECTION_FALLBACK,
+  baseElkLayoutOptions,
+  buildElkEdge,
+  buildElkLeafNode,
+  directionToElk,
+} from '../layout-engine/elk-graph-builder.ts'
+import { measureMultilineText, resolveNodeStyle } from '@zombie-mermaid/core'
+
+/** Layout constants for class diagrams */
+export const CLS = {
+  padding: 40,
+  boxPadX: 8,
+  headerBaseHeight: 32,
+  annotationHeight: 16,
+  memberRowHeight: 20,
+  sectionPadY: 8,
+  emptySectionHeight: 8,
+  minWidth: 120,
+  memberFontSize: 11,
+  memberFontWeight: 400,
+  nodeSpacing: 40,
+  layerSpacing: 60,
+  /** Horizontal / vertical padding inside a note box, around its text */
+  notePadX: 10,
+  notePadY: 6,
+} as const
+
+/**
+ * Layout id for the i-th note. A class id is a run of non-whitespace
+ * (`\S+` in the parser), so an id containing a space can never collide
+ * with one; ELK treats ids as opaque strings.
+ */
+export function classNoteId(index: number): string {
+  return `note ${index}`
+}
+
+/** Layout id for the dotted link joining note `noteId` to its class. */
+function classNoteLinkId(noteId: string): string {
+  return `${noteId} link`
+}
+
+type ClassSizeMap = Map<
+  string,
+  {
+    width: number
+    height: number
+    headerHeight: number
+    attrHeight: number
+    methodHeight: number
+  }
+>
+
+/** Size of each note box, keyed by its layout id. */
+type NoteSizeMap = Map<string, { width: number; height: number }>
+
+/** Build ELK graph and size map from a class diagram. */
+function buildClassElkGraph(
+  diagram: ClassDiagram,
+  options: ClassRenderOptions,
+): { elkGraph: ElkNode; classSizes: ClassSizeMap; noteSizes: NoteSizeMap } {
+  const classSizes: ClassSizeMap = new Map()
+  const noteSizes: NoteSizeMap = new Map()
+  const fontSizes = resolveFontSizes(options.fontSizes)
+
+  for (const cls of diagram.classes) {
+    const headerHeight = cls.annotation
+      ? CLS.headerBaseHeight + CLS.annotationHeight
+      : CLS.headerBaseHeight
+
+    const attrHeight =
+      cls.attributes.length > 0
+        ? cls.attributes.length * CLS.memberRowHeight + CLS.sectionPadY
+        : CLS.emptySectionHeight
+
+    const methodHeight =
+      cls.methods.length > 0
+        ? cls.methods.length * CLS.memberRowHeight + CLS.sectionPadY
+        : CLS.emptySectionHeight
+
+    const headerTextW = estimateTextWidth(
+      cls.label,
+      fontSizes.nodeLabel,
+      FONT_WEIGHTS.nodeLabel,
+    )
+    const maxAttrW = maxMemberWidth(cls.attributes)
+    const maxMethodW = maxMemberWidth(cls.methods)
+    const width = Math.max(
+      CLS.minWidth,
+      headerTextW + CLS.boxPadX * 2,
+      maxAttrW + CLS.boxPadX * 2,
+      maxMethodW + CLS.boxPadX * 2,
+    )
+    const height = headerHeight + attrHeight + methodHeight
+
+    classSizes.set(cls.id, {
+      width,
+      height,
+      headerHeight,
+      attrHeight,
+      methodHeight,
+    })
+  }
+
+  // Iterate classSizes directly (populated above, in diagram.classes order)
+  // rather than looking each class back up by id — sidesteps needing an
+  // assertion or invariant check for a lookup that can't actually miss.
+  const children: ElkNode[] = []
+  for (const [id, size] of classSizes) {
+    children.push(buildElkLeafNode(id, size))
+  }
+
+  // Class edge labels carry no per-label layout options — placement is set
+  // once on the root graph below (`elk.edgeLabels.placement: CENTER`).
+  const labelStyle = { fontSize: fontSizes.edgeLabel }
+
+  const edges: ElkExtendedEdge[] = []
+  for (const [i, rel] of diagram.relationships.entries()) {
+    edges.push(
+      buildElkEdge({
+        id: `e${i}`,
+        source: rel.from,
+        target: rel.to,
+        label: rel.label,
+        labelStyle,
+      }),
+    )
+  }
+
+  // Notes. Mirrors Mermaid's classDb.getData(): every note is a node of its
+  // own, and `note for X` adds an arrowless dotted edge note→class so the
+  // layout keeps the two adjacent (with a DOWN layout the note lands above
+  // its class, as it does in Mermaid's TB rendering). The link edges go
+  // after the relationship edges so relationship indices stay positional.
+  const classIds = new Set(classSizes.keys())
+  for (const [i, note] of diagram.notes.entries()) {
+    const id = classNoteId(i)
+    const metrics = measureMultilineText(
+      note.text,
+      fontSizes.edgeLabel,
+      FONT_WEIGHTS.edgeLabel,
+    )
+    const size = {
+      width: metrics.width + CLS.notePadX * 2,
+      height: metrics.height + CLS.notePadY * 2,
+    }
+    noteSizes.set(id, size)
+    children.push(buildElkLeafNode(id, size))
+    if (note.forClass !== undefined && classIds.has(note.forClass)) {
+      edges.push(
+        buildElkEdge({
+          id: classNoteLinkId(id),
+          source: id,
+          target: note.forClass,
+          labelStyle,
+        }),
+      )
+    }
+  }
+
+  const elkGraph: ElkNode = {
+    id: 'root',
+    layoutOptions: {
+      ...baseElkLayoutOptions({
+        // Class diagrams have no `direction` concept — they always lay out
+        // top-down. See ELK_DIRECTION_FALLBACK for why that default is
+        // per-diagram-type rather than shared with ER's.
+        direction: directionToElk(undefined, ELK_DIRECTION_FALLBACK.class),
+        nodeSpacing: CLS.nodeSpacing,
+        layerSpacing: CLS.layerSpacing,
+        padding: CLS.padding,
+      }),
+      'elk.edgeLabels.placement': 'CENTER',
+    },
+    children,
+    edges,
+  }
+
+  return { elkGraph, classSizes, noteSizes }
+}
+
+/** Extract positioned classes, relationships, and notes from ELK result. */
+function extractClassLayout(
+  result: ElkNode,
+  diagram: ClassDiagram,
+  classSizes: ClassSizeMap,
+  noteSizes: NoteSizeMap,
+): PositionedClassDiagram {
+  const classLookup = new Map<string, ClassNode>()
+  for (const cls of diagram.classes) classLookup.set(cls.id, cls)
+
+  const positionedClasses: PositionedClassNode[] = []
+  for (const child of result.children ?? []) {
+    const cls = classLookup.get(child.id)
+    if (cls) {
+      const size = classSizes.get(cls.id)
+      if (!size) {
+        // Unreachable — classSizes is populated for every diagram.classes
+        // entry, and classLookup/cls.id come from that same list.
+        /* v8 ignore next */
+        throw new Error(`Missing computed size for class "${cls.id}"`)
+      }
+      positionedClasses.push({
+        id: cls.id,
+        label: cls.label,
+        annotation: cls.annotation,
+        attributes: cls.attributes,
+        methods: cls.methods,
+        x: child.x ?? 0,
+        y: child.y ?? 0,
+        width: child.width ?? size.width,
+        height: child.height ?? size.height,
+        headerHeight: size.headerHeight,
+        attrHeight: size.attrHeight,
+        methodHeight: size.methodHeight,
+        interaction: diagram.interactions.get(cls.id),
+        // Same cascade the flowchart layout applies (src/layout-engine/
+        // from-elk.ts): classDef default → assigned class → `style`.
+        inlineStyle: resolveNodeStyle(cls.id, diagram),
+        // Kept separately from inlineStyle so the class name still reaches
+        // the SVG `class` attribute when it has no matching classDef.
+        className: diagram.classAssignments.get(cls.id),
+      })
+    }
+  }
+
+  const relationships: PositionedClassRelationship[] = []
+  const elkEdges = result.edges ?? []
+  // The first diagram.relationships.length edges are the relationships, in
+  // order — buildClassElkGraph creates exactly one ELK edge per relationship
+  // before appending any note links.
+  for (const [i, rel] of diagram.relationships.entries()) {
+    const elkEdge = elkEdges[i]
+    if (!elkEdge) {
+      // Unreachable — ELK returns every edge it was given.
+      /* v8 ignore next */
+      throw new Error(`Missing ELK edge for relationship ${i}`)
+    }
+
+    const points = extractEdgePoints(elkEdge)
+    const labelPosition = extractEdgeLabelPosition(elkEdge)
+
+    relationships.push({
+      from: rel.from,
+      to: rel.to,
+      type: rel.type,
+      markerAt: rel.markerAt,
+      label: rel.label,
+      fromCardinality: rel.fromCardinality,
+      toCardinality: rel.toCardinality,
+      points,
+      labelPosition,
+    })
+  }
+
+  // Note links are matched by id rather than position — only notes whose
+  // class exists got an edge, so their count isn't derivable from the note list.
+  const linkEdges = new Map<string, ElkExtendedEdge>()
+  for (const elkEdge of elkEdges.slice(diagram.relationships.length)) {
+    linkEdges.set(elkEdge.id, elkEdge)
+  }
+  const childById = new Map<string, ElkNode>()
+  for (const child of result.children ?? []) childById.set(child.id, child)
+
+  const notes: PositionedClassNote[] = []
+  for (const [i, note] of diagram.notes.entries()) {
+    const id = classNoteId(i)
+    const child = childById.get(id)
+    const size = noteSizes.get(id)
+    if (!child || !size) {
+      // Unreachable — a child and a size are recorded for every note.
+      /* v8 ignore next */
+      throw new Error(`Missing layout for note ${i}`)
+    }
+    const link = linkEdges.get(classNoteLinkId(id))
+    notes.push({
+      id,
+      text: note.text,
+      ...(link && note.forClass !== undefined
+        ? { forClass: note.forClass }
+        : {}),
+      x: child.x ?? 0,
+      y: child.y ?? 0,
+      width: child.width ?? size.width,
+      height: child.height ?? size.height,
+      ...(link ? { linkPoints: extractEdgePoints(link) } : {}),
+    })
+  }
+
+  return {
+    width: result.width ?? 600,
+    height: result.height ?? 400,
+    classes: positionedClasses,
+    relationships,
+    notes,
+  }
+}
+
+/**
+ * Lay out a parsed class diagram using ELK.js (synchronous).
+ */
+export function layoutClassDiagramSync(
+  diagram: ClassDiagram,
+  options: ClassRenderOptions = {},
+): PositionedClassDiagram {
+  if (diagram.classes.length === 0 && diagram.notes.length === 0) {
+    return { width: 0, height: 0, classes: [], relationships: [], notes: [] }
+  }
+
+  const { elkGraph, classSizes, noteSizes } = buildClassElkGraph(
+    diagram,
+    options,
+  )
+  const result = elkLayoutSync(elkGraph, options.layoutCache)
+  return extractClassLayout(result, diagram, classSizes, noteSizes)
+}
+
+/** Calculate the max width of a list of class members (uses mono metrics) */
+function maxMemberWidth(members: ClassMember[]): number {
+  if (members.length === 0) return 0
+  let maxW = 0
+  for (const m of members) {
+    const text = formatClassMember(m)
+    const w = estimateMonoTextWidth(text, CLS.memberFontSize)
+    if (w > maxW) maxW = w
+  }
+  return maxW
+}