@zombie-mermaid/svg-renderer 2.2.6 → 3.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zombie-mermaid/svg-renderer",
-  "version": "2.2.6",
+  "version": "3.0.0",
   "license": "MIT",
   "description": "SVG rendering primitives and the ELK-backed layout engine behind zombie-mermaid's SVG output.",
   "repository": {
@@ -36,7 +36,8 @@
   ],
   "dependencies": {
     "elkjs": "^0.11.0",
-    "@zombie-mermaid/core": "2.2.6",
-    "@zombie-mermaid/mermaid-parser": "2.2.6"
+    "entities": "^7.0.1",
+    "@zombie-mermaid/core": "3.0.0",
+    "@zombie-mermaid/mermaid-parser": "3.0.0"
   }
 }

package/src/__tests__/render-mermaid-svg.test.ts

@@ -0,0 +1,64 @@
+/**
+ * Smoke tests for `renderMermaidSVG` — the "Mermaid text in, SVG out" front
+ * door moved into this package under #1111, for parity with
+ * `@zombie-mermaid/ascii-renderer`'s `renderMermaidASCII`. The umbrella's own
+ * extensive `src/__tests__/*` suite already exercises this function
+ * end-to-end (through the re-export in `src/index.ts`), so this file only
+ * checks what's specific to *this* package: every registered diagram type
+ * dispatches to real SVG output through `./registry.ts`'s `diagramRegistry`
+ * when called directly from `@zombie-mermaid/svg-renderer`, not just via the
+ * umbrella.
+ */
+import { describe, it, expect } from 'vitest'
+import {
+  renderMermaidSVG,
+  renderMermaidSVGAsync,
+  renderMermaidSync,
+  renderMermaid,
+  themeCssVariables,
+} from '@zombie-mermaid/svg-renderer'
+
+describe('renderMermaidSVG', () => {
+  it.each([
+    ['flowchart', 'graph TD\n  A --> B'],
+    ['state', 'stateDiagram-v2\n  [*] --> A'],
+    ['sequence', 'sequenceDiagram\n  A->>B: hi'],
+    ['class', 'classDiagram\n  Animal <|-- Dog'],
+    ['er', 'erDiagram\n  A ||--o{ B : has'],
+    ['xychart', 'xychart-beta\n  line [1, 2, 3]'],
+  ])('renders a %s diagram to an SVG string', (_label, source) => {
+    const svg = renderMermaidSVG(source)
+    expect(svg).toContain('<svg')
+    expect(svg).toContain('</svg>')
+  })
+
+  it('embeds the original source when embedSource is set', () => {
+    const svg = renderMermaidSVG('graph TD\n  A --> B', { embedSource: true })
+    expect(svg).toContain('data-src=')
+  })
+})
+
+describe('renderMermaidSVGAsync', () => {
+  it('resolves to the same output as the sync render', async () => {
+    const source = 'graph TD\n  A --> B'
+    expect(await renderMermaidSVGAsync(source)).toBe(renderMermaidSVG(source))
+  })
+})
+
+describe('themeCssVariables', () => {
+  it('includes the resolved --bg/--fg custom properties', () => {
+    const css = themeCssVariables({ bg: '#111111', fg: '#eeeeee' })
+    expect(css).toContain('--bg:#111111')
+    expect(css).toContain('--fg:#eeeeee')
+  })
+})
+
+describe('deprecated aliases', () => {
+  it('renderMermaidSync matches renderMermaidSVG', () => {
+    expect(renderMermaidSync).toBe(renderMermaidSVG)
+  })
+
+  it('renderMermaid matches renderMermaidSVGAsync', () => {
+    expect(renderMermaid).toBe(renderMermaidSVGAsync)
+  })
+})

package/src/index.ts

@@ -23,10 +23,9 @@
 // #624) call its primitives directly (zombie-mermaid#616), so it is part
 // of the public API alongside `elk-adapter-utils.ts`.
 //
-// `layout.ts` re-exports `layoutGraphSync` from `layout-engine.ts`, so the
-// two star-exports below resolve to one and the same binding — legal, and
-// not an ambiguous re-export. It stays a module of its own (rather than
-// being folded away here) because #625 is a move, not a redesign.
+// `layout.ts` used to be a thin re-export of `layoutGraphSync` from
+// `layout-engine.ts`; it was folded into `layout-engine.ts` directly
+// (#1109), so `layoutGraphSync` now comes from the one star-export below.
 //
 // `class/`, `er/`, `sequence/`, `xychart/` hold each diagram type's
 // renderer half (`layout.ts` + `renderer.ts`) — the other half
@@ -35,11 +34,18 @@
 // `@zombie-mermaid/mermaid-parser` under the same issue (#624), per the
 // scoping doc's finding 1: each per-type directory used to mix both halves
 // in one place, and the split point already existed at the file level.
+//
+// `renderMermaidSVG` (below) is the single "Mermaid text in, SVG out" front
+// door — moved here from the umbrella's `src/index.ts` under issue #1111,
+// for parity with `@zombie-mermaid/ascii-renderer`'s `renderMermaidASCII`.
+// `./registry.ts` (not re-exported — same as ascii-renderer's own
+// `registry.ts` — it's this front door's internal dispatch table, not part
+// of the public API) drives per-diagram-type dispatch; see that file's
+// header for why it's a separate module from the ASCII side's table.
 // ============================================================================
 
 export * from './edge-curves.ts'
 export * from './elk-instance.ts'
-export * from './layout.ts'
 export * from './layout-engine.ts'
 export * from './layout-engine/elk-adapter-utils.ts'
 export * from './layout-engine/elk-graph-builder.ts'
@@ -56,3 +62,214 @@ export * from './sequence/layout.ts'
 export * from './sequence/renderer.ts'
 export * from './xychart/layout.ts'
 export * from './xychart/renderer.ts'
+
+import { decodeXML } from 'entities'
+import type {
+  RenderOptions,
+  DiagramColors,
+  SvgEmitOptions,
+  DiagramType,
+} from '@zombie-mermaid/core'
+import {
+  DEFAULTS,
+  themeStyleDeclarations,
+  isMonospaceFont,
+  setMonospaceMetrics,
+  detectDiagramType,
+  splitStatements,
+} from '@zombie-mermaid/core'
+import { resolveCssColors } from './resolve-colors.ts'
+import { resolveFontSizes } from './styles.ts'
+import { diagramRegistry } from './registry.ts'
+import type { SvgRenderContext } from './registry.ts'
+
+/**
+ * Build a DiagramColors object from render options.
+ * Uses DEFAULTS for bg/fg when not provided, and passes through
+ * optional enrichment colors (line, accent, muted, surface, border).
+ */
+function buildColors(options: RenderOptions): DiagramColors {
+  return {
+    bg: options.bg ?? DEFAULTS.bg,
+    fg: options.fg ?? DEFAULTS.fg,
+    line: options.line,
+    accent: options.accent,
+    muted: options.muted,
+    surface: options.surface,
+    border: options.border,
+  }
+}
+
+/**
+ * The exact CSS declaration list the root `<svg style="…">` attribute would
+ * carry for these options — `--bg`, `--fg`, whichever enrichment colours
+ * were given, and (unless `transparent`) `background: var(--bg)`.
+ *
+ * For hosts with a strict `Content-Security-Policy`: a `style=` attribute
+ * can't be nonced, so a `style-src` without `'unsafe-inline'` drops it and
+ * the diagram loses its colours. Render with `styleAttribute: false` and
+ * put this string in your own stylesheet on the SVG (or any ancestor —
+ * custom properties inherit) instead. Pass the same options object to both
+ * calls so the declarations match what the render expects. See
+ * `RenderOptions.styleAttribute` / `RenderOptions.nonce` and issue #216.
+ *
+ * Built by the same function that fills the attribute in normal renders,
+ * so there is one variable list to keep in sync. The string is compact
+ * (`--bg:#fff;--fg:#000;background:var(--bg)`) — valid inside any rule
+ * block — and the colour values are yours, unescaped, exactly as the
+ * attribute has always carried them.
+ *
+ * @example
+ * ```ts
+ * const opts = { bg: '#1a1b26', fg: '#a9b1d6', nonce, styleAttribute: false }
+ * const svg = renderMermaidSVG('graph TD\n  A --> B', opts)
+ * const css = `.diagram svg { ${themeCssVariables(opts)} }`
+ * ```
+ */
+export function themeCssVariables(options: RenderOptions = {}): string {
+  return themeStyleDeclarations(buildColors(options), options.transparent)
+}
+
+/**
+ * Resolve the effective strict-CSP emission controls from the public
+ * options. Kept as one object so every renderer takes it as a single
+ * trailing parameter — see `SvgEmitOptions` in packages/core/src/theme.ts.
+ */
+function resolveSvgEmit(options: RenderOptions): SvgEmitOptions {
+  return {
+    nonce: options.nonce,
+    styleAttribute: options.styleAttribute,
+  }
+}
+
+// Interactivity-derived render gates — whether xychart hover tooltips
+// render, whether flowchart/state edge animation (`e1@{ animate: true }`)
+// plays, and whether `click`-based links/`<title>` tooltips render — all
+// now live next to their diagram type's registry entry in ./registry.ts
+// (`resolveAnimationEnabled`/`resolveLinksEnabled` there, duplicated rather
+// than imported since that module is imported BY this file — see those
+// functions' own comments for why), since every diagram type's SVG dispatch
+// is fully handled by the registry lookup below and there is no remaining
+// switch case here for them to serve.
+
+/**
+ * Render Mermaid diagram text to an SVG string — synchronously.
+ *
+ * Uses elk.bundled.js with a direct FakeWorker bypass (no setTimeout(0) delay).
+ * The ELK singleton is created lazily on first use and cached forever.
+ *
+ * Use this in React components with useMemo() to avoid flash:
+ *   const svg = useMemo(() => renderMermaidSVG(code, opts), [code])
+ *
+ * @param text - Mermaid source text
+ * @param options - Rendering options (colors, font, spacing)
+ * @returns A self-contained SVG string
+ *
+ * @example
+ * ```ts
+ * const svg = renderMermaidSVG('graph TD\n  A --> B')
+ *
+ * // With theme
+ * const svg = renderMermaidSVG('graph TD\n  A --> B', {
+ *   bg: '#1a1b26', fg: '#a9b1d6'
+ * })
+ *
+ * // With CSS variables (for live theme switching)
+ * const svg = renderMermaidSVG('graph TD\n  A --> B', {
+ *   bg: 'var(--background)', fg: 'var(--foreground)', transparent: true
+ * })
+ *
+ * // With the original source stamped onto the root <svg> as data-src —
+ * // handy for a "copy source" button or an "open in Mermaid Live" link
+ * // without re-attaching it via string surgery on the output.
+ * const svg = renderMermaidSVG('graph TD\n  A --> B', { embedSource: true })
+ *
+ * // With an accessible name — role="img" + aria-labelledby pointing at a
+ * // <title> child, so assistive tech announces the diagram instead of
+ * // reading every node label individually (see issue #215).
+ * const svg = renderMermaidSVG('graph TD\n  A --> B', {
+ *   title: 'Flowchart: Build → Test → Ship'
+ * })
+ *
+ * // Decorative diagram — already described in surrounding prose, so it's
+ * // hidden from assistive tech (aria-hidden="true") instead of named.
+ * const svg = renderMermaidSVG('graph TD\n  A --> B', { decorative: true })
+ * ```
+ */
+export function renderMermaidSVG(
+  text: string,
+  options: RenderOptions = {},
+): string {
+  const svg = renderMermaidSVGRaw(text, options)
+  return options.resolveColors
+    ? resolveCssColors(svg, buildColors(options))
+    : svg
+}
+
+/** The renderer proper — `renderMermaidSVG` minus the optional `resolveColors` post-pass. */
+function renderMermaidSVGRaw(text: string, options: RenderOptions): string {
+  // Decode XML entities that may leak from markdown parsers (e.g. rehype-raw).
+  // Without this, escapeXml() double-encodes them: &lt; → &amp;lt; → literal "&lt;" in SVG.
+  // `text` itself is left untouched so `embedSource` below stamps the exact
+  // string the caller passed in, not this entity-decoded copy used
+  // internally for parsing.
+  const decoded = decodeXML(text)
+
+  const colors = buildColors(options)
+  const font = options.font ?? 'Inter'
+  // Box sizing depends on the metrics model, so pick it before any layout runs.
+  setMonospaceMetrics(isMonospaceFont(font))
+  const transparent = options.transparent ?? false
+  const fontSizes = resolveFontSizes(options.fontSizes)
+  const diagramType: DiagramType = detectDiagramType(decoded)
+  const embedSource = options.embedSource ? text : undefined
+  const title = options.title
+  const decorative = options.decorative
+  const emit = resolveSvgEmit(options)
+
+  const lines = splitStatements(decoded)
+
+  // Registry dispatch (see ./registry.ts): every diagram type, including
+  // 'flowchart' (and the 'state' pipeline it shares), is registered there.
+  // `parse` takes both `lines` (what every already-registered type's parser
+  // wants) and `decoded` (the raw text flowchart/state's parser needs
+  // instead — see the `parse` doc comment on `DiagramModule` in
+  // ./registry.ts).
+  const registered = diagramRegistry[diagramType]
+  const diagram = registered.parse(lines, decoded)
+  const positioned = registered.layoutForSvg(diagram, options)
+  const ctx: SvgRenderContext = {
+    colors,
+    font,
+    transparent,
+    fontSizes,
+    embedSource,
+    title,
+    decorative,
+    emit,
+  }
+  return registered.renderSvg(positioned, ctx, options)
+}
+
+/**
+ * Render Mermaid diagram text to an SVG string — async.
+ *
+ * Same result as renderMermaidSVG() but returns a Promise.
+ * Useful in async contexts (server handlers, data loaders, etc.)
+ */
+export async function renderMermaidSVGAsync(
+  text: string,
+  options: RenderOptions = {},
+): Promise<string> {
+  return renderMermaidSVG(text, options)
+}
+
+// ---------------------------------------------------------------------------
+// Backward-compatible aliases
+// ---------------------------------------------------------------------------
+
+/** @deprecated Use `renderMermaidSVG` */
+export const renderMermaidSync = renderMermaidSVG
+
+/** @deprecated Use `renderMermaidSVGAsync` */
+export const renderMermaid = renderMermaidSVGAsync

package/src/layout-engine/from-elk.ts

@@ -7,7 +7,7 @@
  * up ELK's raw output.
  */
 
-import type { ElkNode } from 'elkjs'
+import type { ElkNode, ElkExtendedEdge } from 'elkjs'
 import type {
   MermaidGraph,
   MermaidSubgraph,
@@ -432,9 +432,27 @@ function extractEdgesRecursively(
   offsetY: number,
   margins?: MarginInfo,
 ): void {
-  // First pass: collect all edge segments
+  // First pass: collect all edge segments.
+  //
+  // Under `hierarchyHandling: INCLUDE_CHILDREN` (see to-elk.ts — used when no
+  // subgraph has a direction override), ELK is free to leave a
+  // cross-hierarchy edge in an *ancestor* node's `edges` array while
+  // reporting its sections/labels in the coordinate space of the deeper
+  // container named by the edge's own (untyped-in-elkjs) `container`
+  // property. `collectEdgeSegments`'s tree walk assumes an edge's
+  // coordinates match the array it was found in, which breaks for exactly
+  // this case — the edge lands at the *ancestor's* offset instead of the
+  // declared container's, shifting nested-subgraph edges/labels off their
+  // node boundaries toward the root. Pre-computing every container's
+  // accumulated root offset here lets `collectEdgeSegments` prefer the
+  // edge's declared container when present, falling back to the owning
+  // array's offset (the previous behavior) otherwise — see
+  // zombie-mermaid#1145, ported from a fix by Galen Suen in
+  // lukilabs/beautiful-mermaid#152.
+  const containerOffsets = new Map<string, Point>()
+  collectContainerOffsets(elkNode, containerOffsets, 0, 0)
   const segments = new Map<number, EdgeSegmentGroup>()
-  collectEdgeSegments(elkNode, segments, 0, 0)
+  collectEdgeSegments(elkNode, segments, 0, 0, containerOffsets)
 
   // Track margin-routed edge count for spacing offsets
   let marginEdgeIndex = 0
@@ -518,6 +536,35 @@ function extractEdgesRecursively(
   }
 }
 
+/**
+ * Build a map from every ELK node's own id to its accumulated root-relative
+ * offset, by walking the same `elkNode.children` tree `collectEdgeSegments`
+ * walks. Used to resolve a cross-hierarchy edge's declared `container`
+ * (an ELK output property not modeled in elkjs's types) to the offset of
+ * the container ELK actually reported its coordinates in, rather than the
+ * offset of whichever ancestor array the edge object happened to be left
+ * in — see the comment on `extractEdgesRecursively`'s call site.
+ */
+function collectContainerOffsets(
+  elkNode: ElkNode,
+  offsets: Map<string, Point>,
+  offsetX: number,
+  offsetY: number,
+): void {
+  offsets.set(elkNode.id, { x: offsetX, y: offsetY })
+  for (const child of elkNode.children ?? []) {
+    // `x`/`y` are optional in elkjs's types, but ELK always assigns both to
+    // every laid-out child node — the `?? 0` fallback mirrors the same
+    // defensive pattern already used for this walk in `collectEdgeSegments`
+    // below, and is equally unreachable from real ELK output.
+    /* v8 ignore next */
+    const childX = child.x ?? 0
+    /* v8 ignore next */
+    const childY = child.y ?? 0
+    collectContainerOffsets(child, offsets, offsetX + childX, offsetY + childY)
+  }
+}
+
 /**
  * Post-process edge points to ensure all segments are purely orthogonal.
  *
@@ -596,6 +643,7 @@ function collectEdgeSegments(
   segments: Map<number, EdgeSegmentGroup>,
   offsetX: number,
   offsetY: number,
+  containerOffsets: Map<string, Point>,
 ): void {
   if (elkNode.edges) {
     for (const elkEdge of elkNode.edges) {
@@ -605,9 +653,35 @@ function collectEdgeSegments(
       if (!parsed) continue
       const { edgeIndex } = parsed
 
+      // Prefer the edge's declared container offset (see
+      // `collectContainerOffsets`'s comment) over the owning array's
+      // offset. `container` and `containerOffsets.get(container)` were
+      // verified (by direct instrumentation against real elk.bundled.js
+      // output, across both flat and multiply-nested subgraphs) to always
+      // be defined in practice — ELK tags every edge with its container,
+      // even at the root, and `collectContainerOffsets` walks the same
+      // tree so every container id it can name is already in the map. The
+      // `container?`/`?? offset{X,Y}` fallbacks below exist only because
+      // `container` is untyped in elkjs and `Map.get` is typed to allow a
+      // miss; kept as defensive narrowing rather than assumed impossible.
+      const container = (elkEdge as ElkExtendedEdge & { container?: string })
+        .container
+      /* v8 ignore next */
+      const containerOffset = container
+        ? containerOffsets.get(container)
+        : undefined
+      /* v8 ignore next */
+      const edgeOffsetX = containerOffset?.x ?? offsetX
+      /* v8 ignore next */
+      const edgeOffsetY = containerOffset?.y ?? offsetY
+
       // Extract points and label position
-      const points = extractEdgePoints(elkEdge, offsetX, offsetY)
-      const labelPosition = extractEdgeLabelPosition(elkEdge, offsetX, offsetY)
+      const points = extractEdgePoints(elkEdge, edgeOffsetX, edgeOffsetY)
+      const labelPosition = extractEdgeLabelPosition(
+        elkEdge,
+        edgeOffsetX,
+        edgeOffsetY,
+      )
 
       // Store segment
       const seg: EdgeSegmentGroup = segments.get(edgeIndex) ?? {
@@ -635,6 +709,7 @@ function collectEdgeSegments(
         segments,
         offsetX + (child.x ?? 0),
         offsetY + (child.y ?? 0),
+        containerOffsets,
       )
     }
   }