@zombie-mermaid/core 2.2.1

package/src/index.ts

@@ -0,0 +1,34 @@
+// ============================================================================
+// @zombie-mermaid/core — the module set both renderers import
+//
+// Every file re-exported below was grep-verified (zombie-mermaid#625,
+// umbrella #620) as reachable from BOTH front doors — `src/index.ts` (SVG)
+// and `src/ascii/index.ts` (ASCII) — either directly or through
+// `src/parser.ts`, which both call. Nothing here imports anything outside
+// this package, so `core` is a sink in the workspace graph: the ASCII
+// renderer can depend on it without dragging in `elkjs` or any SVG
+// emission code.
+//
+// The one external reference is a type-only `import type { ElkNode }` in
+// `types.ts` (for `RenderOptions.layoutCache`), erased before bundling.
+//
+// A barrel rather than per-file subpath exports: `#620`'s recommendation 4
+// has the umbrella's three entries eventually become thin re-exports of
+// real packages, which needs a real package API. `sideEffects: false` plus
+// this package's total absence of module-level side effects is what keeps
+// the barrel from widening any bundle — verified against the pre-split
+// `dist/` byte-for-byte.
+// ============================================================================
+
+export * from './click-directive.ts'
+export * from './color-utils.ts'
+export * from './diagram-type.ts'
+export * from './direction.ts'
+export * from './direction-override.ts'
+export * from './init-directive.ts'
+export * from './multiline-utils.ts'
+export * from './statements.ts'
+export * from './style-directives.ts'
+export * from './text-metrics.ts'
+export * from './theme.ts'
+export * from './types.ts'

package/src/init-directive.ts

@@ -0,0 +1,248 @@
+// ============================================================================
+// zombie-mermaid — %%{init: ...}%% configuration directives
+//
+// Mermaid lets a diagram carry its own configuration inline:
+//
+//   %%{init: {"theme": "dark", "flowchart": {"curve": "basis"}}}%%
+//   flowchart TD
+//     A --> B
+//
+// The payload is JSON-ish: Mermaid accepts unquoted keys and single quotes,
+// which strict JSON.parse rejects, so it is normalized before parsing.
+//
+// A directive only ever *supplies defaults*. Explicit render options passed
+// by the caller win, because the caller is closer to the user's intent than
+// text embedded in a diagram — and because a diagram from an untrusted source
+// should not be able to override the host application's rendering choices.
+// ============================================================================
+
+import type { RenderOptions } from './types.ts'
+
+/** How an edge path is interpolated between its routed points. */
+export type CurveStyle =
+  'linear' | 'basis' | 'natural' | 'step' | 'stepBefore' | 'stepAfter'
+
+const CURVE_STYLES = new Set<CurveStyle>([
+  'linear',
+  'basis',
+  'natural',
+  'step',
+  'stepBefore',
+  'stepAfter',
+])
+
+/** Configuration a diagram can set for itself via `%%{init: ...}%%`. */
+export interface InitConfig {
+  theme?: string
+  /** Flowchart edge interpolation. */
+  curve?: CurveStyle
+  /** Recognized but not acted on — see `IGNORED_KEYS`. */
+  ignored: string[]
+}
+
+/**
+ * Directive keys that are parsed and deliberately not acted on, with the
+ * reason. Reported on the result so a caller can surface them rather than
+ * having the setting vanish silently.
+ */
+const IGNORED_KEYS: Record<string, string> = {
+  theme:
+    "colors come from the caller's bg/fg render options, which are usually CSS variables so a diagram inherits the host page's light/dark. A diagram-supplied theme would hard-code colors that fight it. Mermaid's theme names (default/dark/forest/neutral) also have no equivalent in this renderer's palettes — pass `bg`/`fg`, or a THEMES entry, instead",
+  securitylevel:
+    'this renderer emits static SVG and never executes diagram-supplied script, so there is no sandbox to configure',
+  defaultrenderer:
+    'ELK is the only layout engine; dagre/elk selection has no effect',
+  fontfamily: 'use the `font` render option instead',
+  htmllabels:
+    'labels are always rendered as SVG text; there is no HTML label mode',
+  maxtextsize: 'no text-size limit is enforced',
+  startonload: 'not a browser auto-render integration',
+}
+
+/**
+ * Matches a `%%{init: ... }%%` or `%%{initialize: ... }%%` directive.
+ *
+ * The body is captured lazily up to the closing `}%%` so a directive sharing
+ * a line with other content does not swallow it.
+ */
+const INIT_DIRECTIVE = /^\s*%%\{\s*(?:init|initialize)\s*:\s*([\s\S]*?)\}%%/i
+
+/** True if `line` is an init directive. */
+export function isInitDirective(line: string): boolean {
+  return INIT_DIRECTIVE.test(line)
+}
+
+/**
+ * Turn Mermaid's relaxed JSON into strict JSON.
+ *
+ * Mermaid accepts `{theme: 'dark'}`; JSON.parse does not. Quoting is applied
+ * only outside string literals so a value containing a colon, a brace, or an
+ * apostrophe survives intact.
+ */
+function normalizeRelaxedJson(text: string): string {
+  let out = ''
+  let quote: '"' | "'" | null = null
+
+  for (let i = 0; i < text.length; i++) {
+    const ch = text[i]!
+
+    if (quote !== null) {
+      if (ch === '\\' && i + 1 < text.length) {
+        /*
+         * Consume the escape and its target together. Without this, the
+         * backslash is emitted bare and the quote it protects reads as the
+         * end of the string — so strict, valid JSON like {"theme": "a\"b"}
+         * re-emits unbalanced and the whole directive is dropped.
+         *
+         * JSON has no \' escape, so a single-quoted string's \' becomes a
+         * bare apostrophe. Every other escape passes through untouched.
+         */
+        const next = text[i + 1]!
+        out += next === "'" ? "'" : `\\${next}`
+        i++
+      } else if (ch === quote) {
+        quote = null
+        out += '"'
+      } else if (ch === '"') {
+        // A double quote inside a single-quoted string must be escaped once
+        // the string is re-emitted with double quotes.
+        out += '\\"'
+      } else {
+        out += ch
+      }
+      continue
+    }
+
+    if (ch === '"' || ch === "'") {
+      quote = ch
+      out += '"'
+      continue
+    }
+
+    // Bare key: an identifier run followed (after spaces) by a colon.
+    if (/[A-Za-z_$]/.test(ch)) {
+      let j = i
+      while (j < text.length && /[\w$-]/.test(text[j]!)) j++
+      const word = text.slice(i, j)
+      let k = j
+      while (k < text.length && /\s/.test(text[k]!)) k++
+
+      if (text[k] === ':') {
+        out += `"${word}"`
+        i = j - 1
+        continue
+      }
+
+      // A bare word in value position — `true`, `false`, `null` are already
+      // valid JSON; anything else is quoted so it parses as a string.
+      out += /^(true|false|null)$/i.test(word)
+        ? word.toLowerCase()
+        : `"${word}"`
+      i = j - 1
+      continue
+    }
+
+    out += ch
+  }
+
+  return out
+}
+
+/**
+ * Parse an init directive's payload.
+ *
+ * Returns `undefined` when the line is not a directive or its payload cannot
+ * be parsed. A malformed directive is ignored rather than fatal: Mermaid
+ * treats config as advisory, and failing an entire diagram over a stray brace
+ * in a comment-like construct would be a poor trade.
+ */
+export function parseInitDirective(line: string): InitConfig | undefined {
+  const match = line.match(INIT_DIRECTIVE)
+  if (!match) return undefined
+
+  let payload: unknown
+  try {
+    payload = JSON.parse(normalizeRelaxedJson(match[1]!))
+  } catch {
+    return undefined
+  }
+
+  if (typeof payload !== 'object' || payload === null) return undefined
+
+  const config: InitConfig = { ignored: [] }
+  const record: Record<string, unknown> = { ...payload }
+
+  for (const [key, value] of Object.entries(record)) {
+    const lower = key.toLowerCase()
+
+    if (lower === 'theme' && typeof value === 'string') {
+      /*
+       * Kept on the result as metadata for a caller that wants to act on it,
+       * but listed as ignored: it is parsed and deliberately not applied. See
+       * IGNORED_KEYS for why.
+       */
+      config.theme = value
+      config.ignored.push(key)
+      continue
+    }
+
+    if (lower === 'flowchart' && typeof value === 'object' && value !== null) {
+      const flowchart: Record<string, unknown> = { ...value }
+      for (const [fk, fv] of Object.entries(flowchart)) {
+        if (fk.toLowerCase() === 'curve' && typeof fv === 'string') {
+          if (CURVE_STYLES.has(fv as CurveStyle)) {
+            config.curve = fv as CurveStyle
+          }
+          continue
+        }
+        if (fk.toLowerCase() in IGNORED_KEYS) config.ignored.push(fk)
+      }
+      continue
+    }
+
+    if (lower in IGNORED_KEYS) config.ignored.push(key)
+  }
+
+  return config
+}
+
+/**
+ * Scan a whole diagram for init directives and merge them.
+ *
+ * Later directives win over earlier ones, matching Mermaid, where a second
+ * directive overrides the first.
+ */
+export function extractInitConfig(lines: string[]): InitConfig {
+  const merged: InitConfig = { ignored: [] }
+
+  for (const line of lines) {
+    const config = parseInitDirective(line)
+    if (!config) continue
+    if (config.theme !== undefined) merged.theme = config.theme
+    if (config.curve !== undefined) merged.curve = config.curve
+    merged.ignored.push(...config.ignored)
+  }
+
+  return merged
+}
+
+/**
+ * Fold an init config into render options.
+ *
+ * Caller-supplied options always win: a directive supplies a default, never
+ * an override. See the module header for why.
+ */
+export function applyInitConfig(
+  options: RenderOptions,
+  config: InitConfig,
+): RenderOptions {
+  if (config.curve === undefined || options.curve !== undefined) return options
+  return { ...options, curve: config.curve }
+}
+
+/** Human-readable note about directive keys that were parsed but not applied. */
+export function describeIgnored(config: InitConfig): string[] {
+  return [...new Set(config.ignored)].map(
+    (key) => `${key}: ${IGNORED_KEYS[key.toLowerCase()] ?? 'not supported'}`,
+  )
+}

package/src/multiline-utils.ts

@@ -0,0 +1,275 @@
+// ============================================================================
+// Multi-line Text Rendering Utilities
+//
+// Shared utilities for rendering multi-line text in SVG using <tspan> elements.
+// Supports inline formatting: <b>, <i>, <u>, <s> mapped to SVG attributes.
+// Used across all diagram types (flowcharts, state, sequence, class, ER).
+// ============================================================================
+
+import { LINE_HEIGHT_RATIO } from './text-metrics.ts'
+
+/**
+ * Normalize label text: strip surrounding quotes, convert <br> tags and
+ * literal \n sequences to newline characters. Strips unsupported HTML tags
+ * but preserves formatting tags (<b>, <i>, <u>, <s>) for SVG rendering.
+ */
+export function normalizeBrTags(label: string): string {
+  // Strip surrounding double quotes (Mermaid uses them for special chars in labels)
+  const unquoted =
+    label.startsWith('"') && label.endsWith('"') ? label.slice(1, -1) : label
+
+  /*
+   * Mermaid's markdown-string form wraps the label in backticks —
+   * `A["` + '`**bold**`' + `"]`. The markdown conversion below already runs
+   * unconditionally, so the backticks only need removing; left in place they
+   * rendered as literal characters in the label.
+   */
+  const unfenced =
+    unquoted.length >= 2 && unquoted.startsWith('`') && unquoted.endsWith('`')
+      ? unquoted.slice(1, -1)
+      : unquoted
+
+  return (
+    unfenced
+      .replace(/<br\s*\/?>/gi, '\n')
+      .replace(/\\n/g, '\n')
+      .replace(/<\/?(?:sub|sup|small|mark)\s*>/gi, '')
+      // Markdown formatting → HTML tags (order matters: ** before *)
+      .replace(/\*\*(.+?)\*\*/g, '<b>$1</b>')
+      .replace(/(?<!\*)\*([^\s*](?:[^*]*[^\s*])?)\*(?!\*)/g, '<i>$1</i>')
+      .replace(/~~(.+?)~~/g, '<s>$1</s>')
+  )
+}
+
+/**
+ * Strip all inline formatting tags from text, keeping only plain text.
+ * Used for text measurement where tag characters shouldn't affect width.
+ */
+export function stripFormattingTags(text: string): string {
+  return text.replace(/<\/?(?:b|strong|i|em|u|s|del)\s*>/gi, '')
+}
+
+/**
+ * Escape special XML characters in text content.
+ */
+export function escapeXml(text: string): string {
+  return text
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#39;')
+}
+
+/**
+ * Escape a string for use as an XML/HTML attribute value.
+ * Escapes quotes and ampersands to prevent attribute injection.
+ *
+ * Deliberately distinct from `escapeXml()` above: attribute values in this
+ * codebase are always double-quoted, so single quotes don't need escaping —
+ * `escapeXml()` escapes them too (for safe embedding in either quote style),
+ * which would change output if reused here.
+ */
+export function escapeAttr(value: string): string {
+  return value
+    .replace(/&/g, '&amp;')
+    .replace(/"/g, '&quot;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+}
+
+// ============================================================================
+// Inline formatting: <b>, <i>, <u>, <s> → SVG tspan attributes
+// ============================================================================
+
+interface StyledSegment {
+  text: string
+  bold: boolean
+  italic: boolean
+  underline: boolean
+  strikethrough: boolean
+}
+
+/** Regex to match opening/closing formatting tags */
+const FORMAT_TAG_REGEX = /<(\/)?(?:(b|strong)|(i|em)|(u)|(s|del))\s*>/gi
+
+/**
+ * Parse a line of text into styled segments based on inline formatting tags.
+ * Supports nesting: `<b>bold <i>both</i> bold</b>`.
+ */
+function parseInlineFormatting(line: string): StyledSegment[] {
+  const segments: StyledSegment[] = []
+  let bold = false,
+    italic = false,
+    underline = false,
+    strikethrough = false
+  let lastIndex = 0
+
+  // Reset lastIndex for global regex
+  FORMAT_TAG_REGEX.lastIndex = 0
+
+  let match: RegExpExecArray | null
+  while ((match = FORMAT_TAG_REGEX.exec(line)) !== null) {
+    // Capture text before this tag
+    if (match.index > lastIndex) {
+      segments.push({
+        text: line.slice(lastIndex, match.index),
+        bold,
+        italic,
+        underline,
+        strikethrough,
+      })
+    }
+    lastIndex = match.index + match[0].length
+
+    const isClosing = Boolean(match[1])
+    // match[2] = b|strong, match[3] = i|em, match[4] = u, match[5] = s|del
+    if (match[2]) bold = !isClosing
+    else if (match[3]) italic = !isClosing
+    else if (match[4]) underline = !isClosing
+    else if (match[5]) strikethrough = !isClosing
+  }
+
+  // Remaining text after last tag
+  if (lastIndex < line.length) {
+    segments.push({
+      text: line.slice(lastIndex),
+      bold,
+      italic,
+      underline,
+      strikethrough,
+    })
+  }
+
+  return segments
+}
+
+/** Check if a line contains any formatting tags */
+const HAS_FORMAT_TAGS = /<\/?(?:b|strong|i|em|u|s|del)\s*>/i
+
+/**
+ * Render a line's content as SVG, with inline formatting applied as tspan attributes.
+ * Returns raw SVG content (no wrapping tspan — caller provides positioning).
+ */
+function renderLineContent(line: string): string {
+  // Fast path: no formatting tags
+  if (!HAS_FORMAT_TAGS.test(line)) return escapeXml(line)
+
+  const segments = parseInlineFormatting(line)
+  if (segments.length === 0) return ''
+
+  // If all segments are unstyled, just escape
+  const allPlain = segments.every(
+    (s) => !s.bold && !s.italic && !s.underline && !s.strikethrough,
+  )
+  if (allPlain) return segments.map((s) => escapeXml(s.text)).join('')
+
+  return segments
+    .map((seg) => {
+      const escaped = escapeXml(seg.text)
+      if (!seg.bold && !seg.italic && !seg.underline && !seg.strikethrough)
+        return escaped
+
+      const attrs: string[] = []
+      if (seg.bold) attrs.push('font-weight="bold"')
+      if (seg.italic) attrs.push('font-style="italic"')
+      // SVG text-decoration can combine values
+      const deco: string[] = []
+      if (seg.underline) deco.push('underline')
+      if (seg.strikethrough) deco.push('line-through')
+      if (deco.length) attrs.push(`text-decoration="${deco.join(' ')}"`)
+
+      return `<tspan ${attrs.join(' ')}>${escaped}</tspan>`
+    })
+    .join('')
+}
+
+// ============================================================================
+// Multi-line text rendering
+// ============================================================================
+
+/**
+ * Render a multi-line text element with proper vertical centering.
+ *
+ * For single-line text, returns a simple <text> element.
+ * For multi-line text (containing \n), returns <text> with <tspan> children.
+ * Inline formatting tags (<b>, <i>, <u>, <s>) are rendered as SVG attributes.
+ *
+ * @param text - The text to render (may contain \n and formatting tags)
+ * @param cx - Center x coordinate
+ * @param cy - Center y coordinate
+ * @param fontSize - Font size in pixels
+ * @param attrs - Additional SVG attributes (e.g., 'text-anchor="middle" fill="var(--_text)"')
+ * @param baselineShift - Baseline shift for vertical alignment (default 0.35)
+ * @returns SVG text element string
+ */
+export function renderMultilineText(
+  text: string,
+  cx: number,
+  cy: number,
+  fontSize: number,
+  attrs: string,
+  baselineShift: number = 0.35,
+): string {
+  const lines = text.split('\n')
+
+  // Single line — simple text element
+  if (lines.length === 1) {
+    const dy = fontSize * baselineShift
+    return `<text x="${cx}" y="${cy}" ${attrs} dy="${dy}">${renderLineContent(text)}</text>`
+  }
+
+  // Multi-line — use tspan elements with vertical centering
+  const lineHeight = fontSize * LINE_HEIGHT_RATIO
+  // First line dy: shift up by (n-1)/2 line heights, then add baseline shift
+  const firstDy =
+    -((lines.length - 1) / 2) * lineHeight + fontSize * baselineShift
+
+  const tspans = lines
+    .map((line, i) => {
+      const dy = i === 0 ? firstDy : lineHeight
+      return `<tspan x="${cx}" dy="${dy}">${renderLineContent(line)}</tspan>`
+    })
+    .join('')
+
+  return `<text x="${cx}" y="${cy}" ${attrs}>${tspans}</text>`
+}
+
+/**
+ * Render a multi-line text element with a background rectangle (pill).
+ *
+ * Used for edge labels that need a background for readability.
+ *
+ * @param text - The text to render (may contain \n)
+ * @param cx - Center x coordinate
+ * @param cy - Center y coordinate
+ * @param textWidth - Pre-calculated text width (max line width)
+ * @param textHeight - Pre-calculated text height (lines × lineHeight)
+ * @param fontSize - Font size in pixels
+ * @param padding - Padding around text
+ * @param textAttrs - SVG attributes for the text element
+ * @param bgAttrs - SVG attributes for the background rect
+ * @returns SVG elements string (rect + text)
+ */
+export function renderMultilineTextWithBackground(
+  text: string,
+  cx: number,
+  cy: number,
+  textWidth: number,
+  textHeight: number,
+  fontSize: number,
+  padding: number,
+  textAttrs: string,
+  bgAttrs: string,
+): string {
+  const bgWidth = textWidth + padding * 2
+  const bgHeight = textHeight + padding * 2
+
+  const rect =
+    `<rect x="${cx - bgWidth / 2}" y="${cy - bgHeight / 2}" ` +
+    `width="${bgWidth}" height="${bgHeight}" ${bgAttrs} />`
+
+  const textEl = renderMultilineText(text, cx, cy, fontSize, textAttrs)
+
+  return `${rect}\n${textEl}`
+}