@zombie-mermaid/svg-renderer 3.2.0 → 4.0.0

package/src/class/layout.ts

@@ -14,6 +14,7 @@ import type {
   ClassMember,
   PositionedClassDiagram,
   PositionedClassNode,
+  PositionedClassNamespace,
   PositionedClassNote,
   PositionedClassRelationship,
 } from '@zombie-mermaid/mermaid-parser'
@@ -36,6 +37,7 @@ import {
   buildElkEdge,
   buildElkLeafNode,
   directionToElk,
+  elkPadding,
 } from '../layout-engine/elk-graph-builder.ts'
 import { measureMultilineText, resolveNodeStyle } from '@zombie-mermaid/core'
 
@@ -56,6 +58,11 @@ export const CLS = {
   /** Horizontal / vertical padding inside a note box, around its text */
   notePadX: 10,
   notePadY: 6,
+  /** Space reserved above a namespace's classes for its title */
+  namespaceTitleHeight: 28,
+  /** Padding between a namespace frame and its classes (other three sides) */
+  namespacePad: 16,
+  namespaceTitleFontSize: 12,
 } as const
 
 /**
@@ -83,6 +90,41 @@ type ClassSizeMap = Map<
   }
 >
 
+/** Layout id for the i-th namespace; contains a space, so it can't match a class id. */
+function classNamespaceId(index: number): string {
+  return `namespace ${index}`
+}
+
+/** A namespace that has at least one member class, ready for layout. */
+interface LayoutNamespace {
+  id: string
+  name: string
+  classIds: string[]
+}
+
+/**
+ * Namespaces to draw: members that aren't classes of the diagram are dropped,
+ * a class claimed by two namespaces stays in the first (ELK nodes have one
+ * parent), and a namespace left with no members is skipped.
+ */
+function resolveNamespaces(diagram: ClassDiagram): LayoutNamespace[] {
+  const known = new Set(diagram.classes.map((c) => c.id))
+  const claimed = new Set<string>()
+  const out: LayoutNamespace[] = []
+  for (const [i, ns] of diagram.namespaces.entries()) {
+    const classIds: string[] = []
+    for (const id of ns.classIds) {
+      if (!known.has(id) || claimed.has(id)) continue
+      claimed.add(id)
+      classIds.push(id)
+    }
+    if (classIds.length > 0) {
+      out.push({ id: classNamespaceId(i), name: ns.name, classIds })
+    }
+  }
+  return out
+}
+
 /** Size of each note box, keyed by its layout id. */
 type NoteSizeMap = Map<string, { width: number; height: number }>
 
@@ -90,7 +132,12 @@ type NoteSizeMap = Map<string, { width: number; height: number }>
 function buildClassElkGraph(
   diagram: ClassDiagram,
   options: ClassRenderOptions,
-): { elkGraph: ElkNode; classSizes: ClassSizeMap; noteSizes: NoteSizeMap } {
+): {
+  elkGraph: ElkNode
+  classSizes: ClassSizeMap
+  noteSizes: NoteSizeMap
+  namespaces: LayoutNamespace[]
+} {
   const classSizes: ClassSizeMap = new Map()
   const noteSizes: NoteSizeMap = new Map()
   const fontSizes = resolveFontSizes(options.fontSizes)
@@ -137,9 +184,44 @@ function buildClassElkGraph(
   // 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 namespaces = resolveNamespaces(diagram)
+  const namespaceOf = new Map<string, string>()
+  for (const ns of namespaces) {
+    for (const id of ns.classIds) namespaceOf.set(id, ns.id)
+  }
+  const namespaceNodes = new Map<string, ElkNode>()
   const children: ElkNode[] = []
+  for (const ns of namespaces) {
+    // Wide enough for the title; ELK grows it to fit the classes inside.
+    const titleW =
+      estimateTextWidth(
+        ns.name,
+        CLS.namespaceTitleFontSize,
+        FONT_WEIGHTS.groupHeader,
+      ) +
+      CLS.namespacePad * 2
+    const node: ElkNode = {
+      id: ns.id,
+      children: [],
+      layoutOptions: {
+        'elk.padding': elkPadding({
+          top: CLS.namespaceTitleHeight + CLS.namespacePad / 2,
+          left: CLS.namespacePad,
+          bottom: CLS.namespacePad,
+          right: CLS.namespacePad,
+        }),
+        'elk.nodeSize.constraints': 'MINIMUM_SIZE',
+        'elk.nodeSize.minimum': `(${Math.ceil(titleW)}, 0)`,
+      },
+    }
+    namespaceNodes.set(ns.id, node)
+    children.push(node)
+  }
   for (const [id, size] of classSizes) {
-    children.push(buildElkLeafNode(id, size))
+    const leaf = buildElkLeafNode(id, size)
+    const parent = namespaceNodes.get(namespaceOf.get(id) ?? '')
+    if (parent?.children) parent.children.push(leaf)
+    else children.push(leaf)
   }
 
   // Class edge labels carry no per-label layout options — placement is set
@@ -203,12 +285,21 @@ function buildClassElkGraph(
         padding: CLS.padding,
       }),
       'elk.edgeLabels.placement': 'CENTER',
+      // Relationships are declared at the root and may cross namespace
+      // frames; INCLUDE_CHILDREN routes them in one pass through the nesting.
+      'elk.hierarchyHandling': 'INCLUDE_CHILDREN',
+      // Mermaid lays disconnected components out left to right in
+      // declaration order (#1249). ELK's default packs components by size
+      // into rows, which reorders them; laying them out as one graph with
+      // model order as the tie-break keeps source order.
+      'elk.separateConnectedComponents': 'false',
+      'elk.layered.considerModelOrder.strategy': 'NODES_AND_EDGES',
     },
     children,
     edges,
   }
 
-  return { elkGraph, classSizes, noteSizes }
+  return { elkGraph, classSizes, noteSizes, namespaces }
 }
 
 /** Extract positioned classes, relationships, and notes from ELK result. */
@@ -217,12 +308,56 @@ function extractClassLayout(
   diagram: ClassDiagram,
   classSizes: ClassSizeMap,
   noteSizes: NoteSizeMap,
+  namespaces: LayoutNamespace[],
 ): PositionedClassDiagram {
   const classLookup = new Map<string, ClassNode>()
   for (const cls of diagram.classes) classLookup.set(cls.id, cls)
 
-  const positionedClasses: PositionedClassNode[] = []
+  // ELK reports a nested node relative to its parent. Namespaces are one
+  // level deep, so flatten each member into diagram coordinates.
+  const namespaceIds = new Set(namespaces.map((ns) => ns.id))
+  const namespaceOffsets = new Map<string, { x: number; y: number }>()
+  const flatChildren: ElkNode[] = []
   for (const child of result.children ?? []) {
+    if (namespaceIds.has(child.id)) {
+      const ox = child.x ?? 0
+      const oy = child.y ?? 0
+      namespaceOffsets.set(child.id, { x: ox, y: oy })
+      for (const inner of child.children ?? []) {
+        flatChildren.push({
+          ...inner,
+          x: (inner.x ?? 0) + ox,
+          y: (inner.y ?? 0) + oy,
+        })
+      }
+    } else {
+      flatChildren.push(child)
+    }
+  }
+  // Under INCLUDE_CHILDREN an edge's points are relative to its container
+  // (the lowest common ancestor of its endpoints): a namespace for an edge
+  // inside one, the root otherwise.
+  const edgeOffset = (edge: ElkExtendedEdge): { x: number; y: number } => {
+    const container = (edge as { container?: string }).container
+    return (container && namespaceOffsets.get(container)) || { x: 0, y: 0 }
+  }
+
+  const positionedNamespaces: PositionedClassNamespace[] = []
+  for (const ns of namespaces) {
+    const node = (result.children ?? []).find((c) => c.id === ns.id)
+    if (!node) continue
+    positionedNamespaces.push({
+      name: ns.name,
+      classIds: ns.classIds,
+      x: node.x ?? 0,
+      y: node.y ?? 0,
+      width: node.width ?? 0,
+      height: node.height ?? 0,
+    })
+  }
+
+  const positionedClasses: PositionedClassNode[] = []
+  for (const child of flatChildren) {
     const cls = classLookup.get(child.id)
     if (cls) {
       const size = classSizes.get(cls.id)
@@ -269,8 +404,9 @@ function extractClassLayout(
       throw new Error(`Missing ELK edge for relationship ${i}`)
     }
 
-    const points = extractEdgePoints(elkEdge)
-    const labelPosition = extractEdgeLabelPosition(elkEdge)
+    const off = edgeOffset(elkEdge)
+    const points = extractEdgePoints(elkEdge, off.x, off.y)
+    const labelPosition = extractEdgeLabelPosition(elkEdge, off.x, off.y)
 
     relationships.push({
       from: rel.from,
@@ -292,7 +428,7 @@ function extractClassLayout(
     linkEdges.set(elkEdge.id, elkEdge)
   }
   const childById = new Map<string, ElkNode>()
-  for (const child of result.children ?? []) childById.set(child.id, child)
+  for (const child of flatChildren) childById.set(child.id, child)
 
   const notes: PositionedClassNote[] = []
   for (const [i, note] of diagram.notes.entries()) {
@@ -315,7 +451,15 @@ function extractClassLayout(
       y: child.y ?? 0,
       width: child.width ?? size.width,
       height: child.height ?? size.height,
-      ...(link ? { linkPoints: extractEdgePoints(link) } : {}),
+      ...(link
+        ? {
+            linkPoints: extractEdgePoints(
+              link,
+              edgeOffset(link).x,
+              edgeOffset(link).y,
+            ),
+          }
+        : {}),
     })
   }
 
@@ -325,6 +469,7 @@ function extractClassLayout(
     classes: positionedClasses,
     relationships,
     notes,
+    namespaces: positionedNamespaces,
   }
 }
 
@@ -336,15 +481,36 @@ export function layoutClassDiagramSync(
   options: ClassRenderOptions = {},
 ): PositionedClassDiagram {
   if (diagram.classes.length === 0 && diagram.notes.length === 0) {
-    return { width: 0, height: 0, classes: [], relationships: [], notes: [] }
+    return {
+      width: 0,
+      height: 0,
+      classes: [],
+      relationships: [],
+      notes: [],
+      namespaces: [],
+    }
   }
 
-  const { elkGraph, classSizes, noteSizes } = buildClassElkGraph(
+  const { elkGraph, classSizes, noteSizes, namespaces } = buildClassElkGraph(
     diagram,
     options,
   )
   const result = elkLayoutSync(elkGraph, options.layoutCache)
-  return extractClassLayout(result, diagram, classSizes, noteSizes)
+  return extractClassLayout(result, diagram, classSizes, noteSizes, namespaces)
+}
+
+/**
+ * Width of a member line sized for the worst-case glyph advance.
+ *
+ * The mono face advances 0.6em per glyph (6.6px at the 11px member size), but
+ * browsers that don't position glyphs at subpixel offsets (headless Chromium
+ * on Linux, notably) round each advance to a whole pixel, so a long member
+ * draws up to 0.4px per character wider than `estimateMonoTextWidth` says and
+ * ran into the box's right border (#1238). Rounding the advance up here keeps
+ * the full `CLS.boxPadX` of right padding whichever way the font is rasterized.
+ */
+function memberTextWidth(text: string): number {
+  return text.length * Math.ceil(estimateMonoTextWidth('M', CLS.memberFontSize))
 }
 
 /** Calculate the max width of a list of class members (uses mono metrics) */
@@ -352,8 +518,7 @@ 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)
+    const w = memberTextWidth(formatClassMember(m))
     if (w > maxW) maxW = w
   }
   return maxW

package/src/class/renderer.ts

@@ -1,5 +1,6 @@
 import type {
   PositionedClassDiagram,
+  PositionedClassNamespace,
   PositionedClassNode,
   PositionedClassNote,
   PositionedClassRelationship,
@@ -35,6 +36,7 @@ import { CLS } from './layout.ts'
 // All colors use CSS custom properties (var(--_xxx)) from the theme system.
 //
 // Render order:
+//   0. Namespace frames (behind everything)
 //   1. Relationship lines and note links (behind boxes)
 //   2. Class boxes (header + attributes + methods compartments)
 //   3. Notes (dog-eared boxes)
@@ -113,6 +115,11 @@ export function renderClassSvg(
   parts.push(relationshipMarkerDefs())
   parts.push('</defs>')
 
+  // 0. Namespace frames (behind everything else)
+  for (const ns of diagram.namespaces) {
+    parts.push(renderNamespace(ns))
+  }
+
   // 1. Relationship lines and note links (rendered behind boxes)
   for (const rel of diagram.relationships) {
     parts.push(renderRelationship(rel))
@@ -140,6 +147,24 @@ export function renderClassSvg(
   return parts.join('\n')
 }
 
+// ============================================================================
+// Namespace frames
+// ============================================================================
+
+/** A `namespace` block: a framed box with its name in a header band. */
+function renderNamespace(ns: PositionedClassNamespace): string {
+  const { x, y, width, height } = ns
+  const bandH = CLS.namespaceTitleHeight
+  const sw = STROKE_WIDTHS.outerBox
+  return [
+    f`<g class="class-namespace" data-id="${escapeAttr(ns.name)}" data-label="${escapeAttr(ns.name)}">`,
+    f`  <rect x="${x}" y="${y}" width="${width}" height="${height}" rx="0" ry="0" fill="var(--_group-fill)" stroke="var(--_node-stroke)" stroke-width="${sw}" />`,
+    f`  <rect x="${x}" y="${y}" width="${width}" height="${bandH}" rx="0" ry="0" fill="var(--_group-hdr)" stroke="var(--_node-stroke)" stroke-width="${sw}" />`,
+    f`  <text x="${x + CLS.namespacePad}" y="${y + bandH / 2}" dy="${TEXT_BASELINE_SHIFT}" font-size="${CLS.namespaceTitleFontSize}" font-weight="${FONT_WEIGHTS.groupHeader}" fill="var(--_text-sec)">${escapeXml(ns.name)}</text>`,
+    '</g>',
+  ].join('\n')
+}
+
 // ============================================================================
 // Marker definitions
 // ============================================================================
@@ -336,10 +361,14 @@ function renderClassBox(
   return parts.join('\n')
 }
 
+/** Heavier weight for the visibility marker so `~` stays distinct from `-` (#1237) */
+const VISIBILITY_MARKER_WEIGHT = 700
+
 /**
  * Render a single class member with syntax highlighting.
  * Uses <tspan> elements to color each part of the member differently:
- *   - visibility symbol (+/-/#/~) → textFaint
+ *   - visibility symbol (+/-/#/~) → textSecondary, bold (faint at weight 400
+ *     made `~` read like `-` at 1x, #1237)
  *   - member name (incl. parens for methods) → textSecondary
  *   - colon separator → textFaint
  *   - type annotation → textMuted
@@ -368,7 +397,7 @@ function renderMember(
 
   if (member.visibility) {
     spans.push(
-      f`<tspan fill="${faint}">${escapeXml(member.visibility)} </tspan>`,
+      f`<tspan fill="${secondary}" font-weight="${VISIBILITY_MARKER_WEIGHT}">${escapeXml(member.visibility)}</tspan><tspan fill="${faint}"> </tspan>`,
     )
   }
 

package/src/er/layout.ts

@@ -47,6 +47,19 @@ const ER = {
 type EntitySizeMap = Map<string, { width: number; height: number }>
 
 /** Build ELK graph and size map from an ER diagram. */
+/**
+ * Width of an attribute row sized for the worst-case glyph advance.
+ *
+ * The mono face advances 0.6em per glyph (6.6px at the 11px attribute size),
+ * but browsers that don't position glyphs at subpixel offsets (headless
+ * Chromium on Linux) round each advance to a whole pixel, so a long row draws
+ * wider than `estimateMonoTextWidth` says and the type runs into the
+ * right-aligned name (#1262, same cause as class members in #1238).
+ */
+function attrTextWidth(text: string): number {
+  return text.length * Math.ceil(estimateMonoTextWidth('M', ER.attrFontSize))
+}
+
 function buildErElkGraph(
   diagram: ErDiagram,
   options: ErRenderOptions,
@@ -63,7 +76,7 @@ function buildErElkGraph(
     let maxAttrW = 0
     for (const attr of entity.attributes) {
       const attrText = `${attr.type}  ${attr.name}${attr.keys.length > 0 ? '  ' + attr.keys.join(',') : ''}`
-      const w = estimateMonoTextWidth(attrText, ER.attrFontSize)
+      const w = attrTextWidth(attrText)
       if (w > maxAttrW) maxAttrW = w
     }
     const width = Math.max(
@@ -105,15 +118,18 @@ function buildErElkGraph(
     id: 'root',
     layoutOptions: {
       ...baseElkLayoutOptions({
-        // A source with no `direction` statement lays out left-to-right —
-        // ER's own default, unlike flowchart/class's DOWN. See
-        // ELK_DIRECTION_FALLBACK.
+        // A source with no `direction` statement lays out top-to-bottom,
+        // as official Mermaid does (#1250). See ELK_DIRECTION_FALLBACK.
         direction: directionToElk(diagram.direction, ELK_DIRECTION_FALLBACK.er),
         nodeSpacing: ER.nodeSpacing,
         layerSpacing: ER.layerSpacing,
         padding: ER.padding,
       }),
       'elk.edgeLabels.placement': 'CENTER',
+      // Keep declaration order as the crossing-minimization tie-break and
+      // center children under their parents, as official Mermaid does.
+      'elk.layered.considerModelOrder.strategy': 'NODES_AND_EDGES',
+      'elk.layered.nodePlacement.bk.fixedAlignment': 'BALANCED',
     },
     children,
     edges,

package/src/er/renderer.ts

@@ -38,6 +38,15 @@ import type { FontSizes } from '../styles.ts'
 //   4. Relationship labels
 // ============================================================================
 
+/**
+ * Relationship-label text: `--fg` mixed into `--bg` at this percentage.
+ * The shared `--_text-muted` (40%) is ~2.4:1 on the default white theme and
+ * `--_text-sec` (60%) is ~4.1:1, both under the WCAG AA 4.5:1 text minimum;
+ * 70% is ~5.6:1 while still reading as secondary to the entity names (#1244).
+ * Local to ER so other diagram types keep their tuned text hierarchy.
+ */
+const ER_EDGE_LABEL_FG_PERCENT = 70
+
 /** Font sizes specific to ER diagrams */
 const ER_FONT = {
   attrSize: 11,
@@ -320,7 +329,7 @@ function renderRelationshipLabel(
       mid.x,
       mid.y,
       fontSizes.edgeLabel,
-      f`text-anchor="middle" font-size="${fontSizes.edgeLabel}" font-weight="${FONT_WEIGHTS.edgeLabel}" fill="var(--_text-muted)"`,
+      f`text-anchor="middle" font-size="${fontSizes.edgeLabel}" font-weight="${FONT_WEIGHTS.edgeLabel}" fill="color-mix(in srgb, var(--fg) ${ER_EDGE_LABEL_FG_PERCENT}%, var(--bg))"`,
     )}`
   )
 }

package/src/layout-engine/back-edges.ts

@@ -0,0 +1,73 @@
+/**
+ * Which edges of a flowchart are "back edges", found the way mermaid.js finds
+ * them.
+ *
+ * mermaid lays a flowchart out with dagre, which makes the graph acyclic by a
+ * depth-first walk: starting from each node in order and following out-edges
+ * in source order, an edge that points at a node still on the walk's stack is
+ * reversed. Which edge of a cycle gets reversed decides the whole layout. In
+ * the CI/CD sample `D -.-> A` closes the cycle `A -> B -> D -> A`, and walking
+ * `A -> B -> C -> E -> F` reaches `D` through `F --> D` first, so `D -.-> A` is
+ * the back edge and `D` ("Fix & Retry") sits after `F`.
+ *
+ * ELK's own cycle breaking picks a different edge (`F --> D`), puts `D` early,
+ * and draws the long way round. It also treats a subgraph's contents
+ * separately from the rest of the graph, so no ELK setting reproduces the
+ * dagre result (#1239). Handing ELK these edges already reversed means it never
+ * has a cycle to break.
+ */
+
+import type { MermaidGraph } from '@zombie-mermaid/core'
+
+/**
+ * Indices into `graph.edges` of the edges a depth-first walk reverses.
+ * Self-loops are never back edges here; layout handles them on their own.
+ *
+ * `walkOrder` is the order the walk starts from; it defaults to the graph's
+ * node order, which is mermaid's (first appearance in the source).
+ */
+export function findBackEdgeIndexes(
+  graph: MermaidGraph,
+  walkOrder?: Iterable<string>,
+): Set<number> {
+  const outEdges = new Map<string, number[]>()
+  graph.edges.forEach((edge, index) => {
+    if (edge.source === edge.target) return
+    const list = outEdges.get(edge.source)
+    if (list) list.push(index)
+    else outEdges.set(edge.source, [index])
+  })
+
+  const back = new Set<number>()
+  const visited = new Set<string>()
+  const onStack = new Set<string>()
+
+  // Iterative, so a long chain can't overflow the call stack.
+  for (const root of walkOrder ?? graph.nodes.keys()) {
+    if (visited.has(root)) continue
+    const stack: Array<{ node: string; next: number }> = [
+      { node: root, next: 0 },
+    ]
+    visited.add(root)
+    onStack.add(root)
+    while (stack.length > 0) {
+      const frame = stack[stack.length - 1]!
+      const edges = outEdges.get(frame.node) ?? []
+      if (frame.next >= edges.length) {
+        onStack.delete(frame.node)
+        stack.pop()
+        continue
+      }
+      const index = edges[frame.next++]!
+      const target = graph.edges[index]!.target
+      if (onStack.has(target)) {
+        back.add(index)
+      } else if (!visited.has(target)) {
+        visited.add(target)
+        onStack.add(target)
+        stack.push({ node: target, next: 0 })
+      }
+    }
+  }
+  return back
+}