@zombie-mermaid/svg-renderer 2.2.1

package/dist/index.d.cts

@@ -0,0 +1,524 @@
+import { ClassDiagram } from '@zombie-mermaid/mermaid-parser';
+import { ClassRenderOptions } from '@zombie-mermaid/core';
+import { CurveStyle } from '@zombie-mermaid/core';
+import { DiagramColors } from '@zombie-mermaid/core';
+import { Direction } from '@zombie-mermaid/core';
+import { ElkExtendedEdge } from 'elkjs';
+import { ElkLabel } from 'elkjs';
+import { ElkNode } from 'elkjs';
+import { ErDiagram } from '@zombie-mermaid/mermaid-parser';
+import { ErRenderOptions } from '@zombie-mermaid/core';
+import { FlowchartRenderOptions } from '@zombie-mermaid/core';
+import { LayoutCache } from '@zombie-mermaid/core';
+import { LayoutOptions } from 'elkjs';
+import { MermaidGraph } from '@zombie-mermaid/core';
+import { Point } from '@zombie-mermaid/core';
+import { PositionedClassDiagram } from '@zombie-mermaid/mermaid-parser';
+import { PositionedErDiagram } from '@zombie-mermaid/mermaid-parser';
+import { PositionedGraph } from '@zombie-mermaid/core';
+import { PositionedNode } from '@zombie-mermaid/core';
+import { PositionedSequenceDiagram } from '@zombie-mermaid/mermaid-parser';
+import { PositionedXYChart } from '@zombie-mermaid/mermaid-parser';
+import { SequenceDiagram } from '@zombie-mermaid/mermaid-parser';
+import { SequenceRenderOptions } from '@zombie-mermaid/core';
+import { SvgEmitOptions } from '@zombie-mermaid/core';
+import { XYChart } from '@zombie-mermaid/mermaid-parser';
+import { XyChartRenderOptions } from '@zombie-mermaid/core';
+
+/** Arrow head dimensions — matches spec: 8px wide × ~5px tall */
+export declare const ARROW_HEAD: {
+    readonly width: 8;
+    readonly height: 5;
+};
+
+/**
+ * The `elk.*` options every one of the three graph builders sets, with the
+ * values they all agree on. Callers spread the result and add their own
+ * diagram-specific options on top.
+ */
+export declare function baseElkLayoutOptions(spec: {
+    direction: ElkDirection;
+    nodeSpacing: number;
+    layerSpacing: number;
+    padding: number | ElkPaddingSides;
+}): LayoutOptions;
+
+/**
+ * Height of the label band at the top of a `box … end` group, in px — the
+ * label's font size plus vertical breathing room. Shared with the renderer
+ * so the label lands centred in the band the layout reserved for it.
+ */
+export declare function boxLabelHeight(labelFontSize: number): number;
+
+/**
+ * Build a single-source/single-target ELK edge, with a measured label when
+ * `label` is non-empty. An absent or empty label leaves `labels` off the
+ * edge entirely (rather than setting it to an empty array or `undefined`),
+ * matching what all three builders did by hand.
+ */
+export declare function buildElkEdge(spec: {
+    id: string;
+    source: string;
+    target: string;
+    label?: string;
+    labelStyle: ElkEdgeLabelStyle;
+}): ElkExtendedEdge;
+
+/**
+ * Measure an edge label and build ELK's label box for it.
+ *
+ * The `+8` / `+6` are the horizontal/vertical breathing room all three
+ * builders have always added around the measured text so ELK reserves a
+ * slightly larger channel than the glyphs strictly need.
+ */
+export declare function buildElkEdgeLabel(text: string, style: ElkEdgeLabelStyle): ElkLabel;
+
+/**
+ * Build a leaf ELK node.
+ *
+ * `label` is attached as an ELK label when supplied — the flowchart/state
+ * path does that (ELK reads it for nothing, but `from-elk.ts` reads it
+ * back); class and ER carry labels in their own side tables instead and
+ * omit it. An empty-string label is still a label, so the check is
+ * `undefined`, not truthiness.
+ */
+export declare function buildElkLeafNode(id: string, size: {
+    width: number;
+    height: number;
+}, label?: string): ElkNode;
+
+/**
+ * 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 declare function classNoteId(index: number): string;
+
+/**
+ * Clip an edge endpoint to the actual shape boundary of a node.
+ *
+ * @param points - The edge points array
+ * @param node - The node to clip to
+ * @param isStart - True if clipping the start point (source), false for end (target)
+ * @returns New points array with clipped endpoint
+ */
+export declare function clipEdgeToShape(points: Point[], node: PositionedNode, isStart: boolean): Point[];
+
+/** Layout constants for class diagrams */
+export declare const CLS: {
+    readonly padding: 40;
+    readonly boxPadX: 8;
+    readonly headerBaseHeight: 32;
+    readonly annotationHeight: 16;
+    readonly memberRowHeight: 20;
+    readonly sectionPadY: 8;
+    readonly emptySectionHeight: 8;
+    readonly minWidth: 120;
+    readonly memberFontSize: 11;
+    readonly memberFontWeight: 400;
+    readonly nodeSpacing: 40;
+    readonly layerSpacing: 60;
+    /** Horizontal / vertical padding inside a note box, around its text */
+    readonly notePadX: 10;
+    readonly notePadY: 6;
+};
+
+/**
+ * Convert MermaidGraph to ELK format (for benchmarking conversion overhead).
+ */
+export declare function convertToElkFormat(graph: MermaidGraph, options?: FlowchartRenderOptions): ElkNode;
+
+/**
+ * Create a new opt-in layout cache with a bounded size (default 20
+ * entries). Once full, the least-recently-used entry is evicted to make
+ * room for a new one.
+ *
+ * Pass the result to `elkLayoutSync()` directly, or via
+ * `RenderOptions.layoutCache` (threaded through by `layoutGraphSync()`,
+ * `layoutClassDiagramSync()`, and `layoutErDiagramSync()`) to memoize
+ * layout across repeated renders of the same diagram + options.
+ */
+export declare function createLayoutCache(maxSize?: number): LayoutCache;
+
+/**
+ * Convert a Mermaid `direction` to ELK's `elk.direction` value.
+ *
+ * `fallback` covers the no-`direction`-statement case only — every member
+ * of `Direction` has an explicit mapping. Pass the diagram type's entry
+ * from `ELK_DIRECTION_FALLBACK` rather than a bare string literal, so the
+ * per-type defaults stay documented in one place.
+ */
+export declare function directionToElk(dir: Direction | undefined, fallback: ElkDirection): ElkDirection;
+
+/**
+ * The `elk.direction` each diagram type falls back to when its source
+ * carries no `direction` statement.
+ *
+ * These genuinely differ per diagram type, and the difference is
+ * intentional rather than an accident of three separate implementations:
+ *
+ * - **flowchart / state** — `DOWN`. `MermaidGraph.direction` is a required
+ *   field the parser always fills in (defaulting to `TD`), so the fallback
+ *   is only a type-level backstop; the effective default is mermaid's own
+ *   top-down flowchart default.
+ * - **class** — `DOWN`. `ClassDiagram` has no direction concept at all (see
+ *   `ClassRenderOptions` in `packages/core/src/types.ts`: class diagrams
+ *   "have no `direction` or `curve` concept"), so this is the renderer's
+ *   single fixed orientation, matching Mermaid's own TB class rendering —
+ *   which `../class/layout.ts` relies on to put a `note for X` above its
+ *   class.
+ * - **ER** — `RIGHT`. An ER diagram's `direction` is optional
+ *   (`ErDiagram.direction?`), left `undefined` when the source has no
+ *   `direction` statement, and this renderer has always laid those out
+ *   left-to-right. `direction TB`/`LR`/`BT`/`RL` in the source (or
+ *   `RenderOptions.direction`, applied via `withDirectionOverride`) still
+ *   wins over it.
+ *
+ * The *mappings* were never in conflict — both hand-rolled
+ * `directionToElk()` implementations agreed on all five `Direction` values
+ * (`LR`→`RIGHT`, `RL`→`LEFT`, `BT`→`UP`, `TD`/`TB`→`DOWN`). Only the
+ * no-direction fallback differed, which is why it is a parameter here
+ * rather than something to reconcile away.
+ */
+export declare const ELK_DIRECTION_FALLBACK: {
+    readonly flowchart: "DOWN";
+    readonly state: "DOWN";
+    readonly class: "DOWN";
+    readonly er: "RIGHT";
+};
+
+/** The four values ELK's `elk.direction` option accepts in this codebase. */
+export declare type ElkDirection = 'DOWN' | 'UP' | 'LEFT' | 'RIGHT';
+
+/**
+ * How a caller wants its edge labels measured and placed. `fontSize` is
+ * the resolved `fontSizes.edgeLabel`; `layoutOptions`, when given, is
+ * attached to the ELK label itself.
+ */
+export declare interface ElkEdgeLabelStyle {
+    fontSize: number;
+    layoutOptions?: LayoutOptions;
+}
+
+/**
+ * Run ELK layout synchronously.
+ *
+ * Bypasses BOTH of ELK's setTimeout(0) wrappers:
+ *   - FakeWorker.postMessage wraps dispatch in setTimeout(0) — bypassed by
+ *     calling dispatcher.saveDispatch() directly
+ *   - PromisedWorker.onmessage wraps receive in setTimeout(0) — bypassed by
+ *     replacing rawWorker.onmessage with a direct interceptor
+ *
+ * @param cache - Optional opt-in layout cache (see `createLayoutCache()`).
+ *   When provided, a cache hit returns the previous result without running
+ *   ELK layout again. Omitted/undefined preserves the original
+ *   always-recompute behavior exactly.
+ */
+export declare function elkLayoutSync(graph: ElkNode, cache?: LayoutCache): ElkNode;
+
+/**
+ * Format ELK's `elk.padding` value. A single number applies to all four
+ * sides; an object sets them individually.
+ */
+export declare function elkPadding(padding: number | ElkPaddingSides): string;
+
+/** Per-side padding, for the asymmetric case (a subgraph's header gap). */
+export declare interface ElkPaddingSides {
+    top: number;
+    left: number;
+    bottom: number;
+    right: number;
+}
+
+/** Average character width in px for monospace fonts (uniform glyph width) */
+export declare function estimateMonoTextWidth(text: string, fontSize: number): number;
+
+/** Average character width in px at the given font size and weight (proportional font) */
+export declare function estimateTextWidth(text: string, fontSize: number, fontWeight: number): number;
+
+/**
+ * Evaluate one CSS value against a flat set of custom-property
+ * declarations — the expression engine behind `resolveCssColors`, exposed
+ * so it can be unit-tested (and reused) without building an SVG around it.
+ *
+ * @example
+ * evaluateCssColorValue('color-mix(in srgb, var(--fg) 50%, var(--bg))',
+ *   { '--fg': '#000000', '--bg': '#ffffff' }) // → '#808080'
+ */
+export declare function evaluateCssColorValue(value: string, declarations: Record<string, string>): string;
+
+/**
+ * Compute an edge label's center position from ELK's placed label box
+ * (`label.x/y` is the box's top-left corner).
+ *
+ * `offsetX`/`offsetY` translate into an ancestor's coordinate space, same
+ * as `extractEdgePoints`.
+ *
+ * Returns `undefined` if ELK didn't place a label (no label on the edge,
+ * or ELK left `x`/`y` unset).
+ */
+export declare function extractEdgeLabelPosition(elkEdge: ElkExtendedEdge, offsetX?: number, offsetY?: number): Point | undefined;
+
+/**
+ * Walk an ELK edge's first routed section into a flat point path:
+ * `startPoint → bendPoints → endPoint`.
+ *
+ * ELK can theoretically produce multiple sections per edge (for edges
+ * split across hierarchy boundaries via ports), but all three call sites
+ * only ever read `sections[0]` — hierarchical decomposition in this
+ * codebase is handled by emitting separate ELK edges (see
+ * `to-elk.ts`/`parseHopEdgeId` in `from-elk.ts`), not multi-section edges.
+ *
+ * `offsetX`/`offsetY` translate the section's coordinates into an
+ * ancestor's coordinate space, for callers walking a nested ELK result
+ * (`from-elk.ts`). Callers with a flat (non-hierarchical) ELK graph
+ * (`class/layout.ts`, `er/layout.ts`) can omit them.
+ *
+ * Returns an empty array if the edge has no routed sections.
+ */
+export declare function extractEdgePoints(elkEdge: ElkExtendedEdge, offsetX?: number, offsetY?: number): Point[];
+
+/** Default font sizes used in the renderer (in px). Overridable via `RenderOptions.fontSizes`. */
+export declare const FONT_SIZES: {
+    /** Node label text */
+    readonly nodeLabel: 13;
+    /** Edge label text */
+    readonly edgeLabel: 11;
+    /** Subgraph header text */
+    readonly groupHeader: 12;
+};
+
+/** Font weights used per element type */
+export declare const FONT_WEIGHTS: {
+    readonly nodeLabel: 500;
+    readonly edgeLabel: 400;
+    readonly groupHeader: 600;
+};
+
+/** Partial font-size overrides, as accepted by `RenderOptions.fontSizes`. */
+export declare type FontSizeOptions = Partial<FontSizes>;
+
+/** Resolved font-size set — same shape as {@link FONT_SIZES} but mutable numbers. */
+export declare type FontSizes = {
+    [K in keyof typeof FONT_SIZES]: number;
+};
+
+/** Vertical gap between a subgraph header band and the content area below it (px).
+ * Without this, nested subgraph headers sit flush against their parent's header band.
+ * Increased from 8 to 12 to provide more clearance for edges routing near headers. */
+export declare const GROUP_HEADER_CONTENT_PAD = 12;
+
+/**
+ * Per-label layout options the flowchart/state path sets on every edge
+ * label. Class and ER instead set `elk.edgeLabels.placement` once on the
+ * root graph, so they pass no per-label options.
+ */
+export declare const INLINE_CENTERED_EDGE_LABEL: LayoutOptions;
+
+export { LayoutCache }
+
+/**
+ * Lay out a parsed class diagram using ELK.js (synchronous).
+ */
+export declare function layoutClassDiagramSync(diagram: ClassDiagram, options?: ClassRenderOptions): PositionedClassDiagram;
+
+/**
+ * Lay out a parsed ER diagram using ELK.js (synchronous).
+ */
+export declare function layoutErDiagramSync(diagram: ErDiagram, options?: ErRenderOptions): PositionedErDiagram;
+
+/**
+ * Lay out a parsed MermaidGraph using ELK.js (synchronous).
+ * Returns a fully positioned graph ready for rendering.
+ */
+export declare function layoutGraphSync(graph: MermaidGraph, options?: FlowchartRenderOptions): PositionedGraph;
+
+/**
+ * Lay out a parsed sequence diagram.
+ * Returns a fully positioned diagram ready for SVG rendering.
+ */
+export declare function layoutSequenceDiagram(diagram: SequenceDiagram, options?: SequenceRenderOptions): PositionedSequenceDiagram;
+
+/**
+ * Lay out a parsed XY chart by computing pixel coordinates.
+ */
+export declare function layoutXYChart(chart: XYChart, _options?: XyChartRenderOptions): PositionedXYChart;
+
+/** Monospace font family used for code-like text (class members, types) */
+export declare const MONO_FONT: "'JetBrains Mono'";
+
+/** Full CSS fallback chain for monospace text */
+export declare const MONO_FONT_STACK: "'JetBrains Mono', 'SF Mono', 'Fira Code', ui-monospace, monospace";
+
+/** Padding inside node shapes */
+export declare const NODE_PADDING: {
+    /** Horizontal padding inside rectangles/rounded/stadium (increased from 16 for better label fit) */
+    readonly horizontal: 20;
+    /** Vertical padding inside rectangles/rounded/stadium */
+    readonly vertical: 10;
+    /** Extra padding for diamond shapes (they need more space due to rotation) */
+    readonly diamondExtra: 24;
+};
+
+/**
+ * Build the `d` attribute for an edge's routed points under `curve`.
+ *
+ * A path with fewer than two points cannot be drawn; the caller already skips
+ * those, but this degrades to an empty string rather than emitting `M`
+ * followed by nothing.
+ */
+export declare function pointsToPath(points: Point[], curve?: CurveStyle): string;
+
+/**
+ * Render a positioned class diagram as an SVG string.
+ *
+ * @param colors - DiagramColors with bg/fg and optional enrichment variables.
+ * @param transparent - If true, renders with transparent background.
+ * @param embedSource - Original diagram source to stamp onto the root `<svg>`
+ *                       as `data-src` (from `options.embedSource`). Omitted
+ *                       when the option is off.
+ * @param title - Accessible name (from `options.title`). See svgOpenTag() in
+ *                packages/core/src/theme.ts.
+ * @param decorative - Marks the SVG decorative (from `options.decorative`).
+ * @param linksEnabled - Whether `click`-based `<a href>` links and `<title>`
+ *                       tooltips render (from `options.interactivity !==
+ *                       'none'`, see `resolveLinksEnabled` in
+ *                       src/diagram-registry.ts).
+ *                       Default true — matches the flowchart/state renderer.
+ * @param emit - Strict-CSP controls (from `options.nonce` /
+ *               `options.styleAttribute`, see #216). Default: no nonce,
+ *               root `style` attribute on.
+ */
+export declare function renderClassSvg(diagram: PositionedClassDiagram, colors: DiagramColors, font?: string, transparent?: boolean, fontSizes?: FontSizes, embedSource?: string, title?: string, decorative?: boolean, linksEnabled?: boolean, emit?: SvgEmitOptions): string;
+
+/**
+ * Render a positioned ER diagram as an SVG string.
+ *
+ * @param colors - DiagramColors with bg/fg and optional enrichment variables.
+ * @param transparent - If true, renders with transparent background.
+ * @param embedSource - Original diagram source to stamp onto the root `<svg>`
+ *                       as `data-src` (from `options.embedSource`). Omitted
+ *                       when the option is off.
+ * @param title - Accessible name (from `options.title`). See svgOpenTag() in
+ *                packages/core/src/theme.ts.
+ * @param decorative - Marks the SVG decorative (from `options.decorative`).
+ * @param emit - Strict-CSP controls (from `options.nonce` /
+ *               `options.styleAttribute`, see #216). Default: no nonce,
+ *               root `style` attribute on.
+ */
+export declare function renderErSvg(diagram: PositionedErDiagram, colors: DiagramColors, font?: string, transparent?: boolean, fontSizes?: FontSizes, embedSource?: string, title?: string, decorative?: boolean, emit?: SvgEmitOptions): string;
+
+/**
+ * Render a positioned sequence diagram as an SVG string.
+ *
+ * @param colors - DiagramColors with bg/fg and optional enrichment variables.
+ * @param transparent - If true, renders with transparent background.
+ * @param embedSource - Original diagram source to stamp onto the root `<svg>`
+ *                       as `data-src` (from `options.embedSource`). Omitted
+ *                       when the option is off.
+ * @param title - Accessible name (from `options.title`). See svgOpenTag() in
+ *                packages/core/src/theme.ts.
+ * @param decorative - Marks the SVG decorative (from `options.decorative`).
+ * @param emit - Strict-CSP controls (from `options.nonce` /
+ *               `options.styleAttribute`, see #216). Default: no nonce,
+ *               root `style` attribute on.
+ */
+export declare function renderSequenceSvg(diagram: PositionedSequenceDiagram, colors: DiagramColors, font?: string, transparent?: boolean, fontSizes?: FontSizes, embedSource?: string, title?: string, decorative?: boolean, emit?: SvgEmitOptions): string;
+
+/**
+ * Render a positioned graph as an SVG string.
+ *
+ * @param colors - DiagramColors with bg/fg and optional enrichment variables.
+ *                 These are set as CSS custom properties on the <svg> tag.
+ *                 All element colors reference derived --_xxx variables.
+ * @param transparent - If true, renders with transparent background.
+ * @param embedSource - Original diagram source to stamp onto the root `<svg>`
+ *                       as `data-src` (from `options.embedSource`). Omitted
+ *                       when the option is off.
+ * @param animationEnabled - Whether `e1@{ animate: true }` edges actually
+ *                            animate (from `options.interactivity === 'full'`,
+ *                            see `resolveAnimationEnabled` in
+ *                            src/diagram-registry.ts).
+ *                            Default true — preserves the previously-ungated
+ *                            behavior for callers who don't pass it.
+ * @param linksEnabled - Whether `click`-based `<a href>` links and `<title>`
+ *                       tooltips render (from
+ *                       `options.interactivity !== 'none'`, see
+ *                       `resolveLinksEnabled` in src/diagram-registry.ts). Default true
+ *                       — preserves the previously-ungated behavior for
+ *                       callers who don't pass it.
+ * @param title - Accessible name (from `options.title`). See svgOpenTag() in
+ *                packages/core/src/theme.ts.
+ * @param decorative - Marks the SVG decorative (from `options.decorative`).
+ * @param emit - Strict-CSP controls (from `options.nonce` /
+ *               `options.styleAttribute`, see #216): a `nonce` for every
+ *               `<style>` element, and whether the root `style="…"`
+ *               attribute is emitted at all. Default: no nonce, attribute on.
+ */
+export declare function renderSvg(graph: PositionedGraph, colors: DiagramColors, font?: string, transparent?: boolean, fontSizes?: FontSizes, curve?: CurveStyle, embedSource?: string, animationEnabled?: boolean, linksEnabled?: boolean, title?: string, decorative?: boolean, emit?: SvgEmitOptions): string;
+
+/**
+ * Render a positioned XY chart as an SVG string.
+ *
+ * @param embedSource - Original diagram source to stamp onto the root
+ *                       `<svg>` as `data-src` (from `options.embedSource`).
+ *                       Omitted when the option is off.
+ * @param title - Accessible name (from `options.title`). See svgOpenTag() in
+ *                packages/core/src/theme.ts.
+ * @param decorative - Marks the SVG decorative (from `options.decorative`).
+ * @param emit - Strict-CSP controls (from `options.nonce` /
+ *               `options.styleAttribute`, see #216). Default: no nonce,
+ *               root `style` attribute on.
+ */
+export declare function renderXYChartSvg(chart: PositionedXYChart, colors: DiagramColors, font?: string, transparent?: boolean, interactive?: boolean, embedSource?: string, title?: string, decorative?: boolean, emit?: SvgEmitOptions): string;
+
+/**
+ * Replace every `var(--…)` and `color-mix(…)` in an SVG produced by this
+ * library's renderer with its computed sRGB value (`#rrggbb`, or
+ * `rgba(r, g, b, a)` when translucent).
+ *
+ * `colors` seeds the variable scope with the caller's palette; the SVG's
+ * own declarations (the root `style` attribute and any `<style>` block)
+ * are then read on top, so the derived `--_*` variables resolve through
+ * exactly the `color-mix()` rules `buildStyleBlock` emitted. See the
+ * module comment for what is and isn't rewritten.
+ */
+export declare function resolveCssColors(svg: string, colors: DiagramColors): string;
+
+/**
+ * Merge user-provided font-size overrides over the {@link FONT_SIZES} defaults.
+ * Any field left unspecified (or `undefined`) falls back to its default.
+ */
+export declare function resolveFontSizes(overrides?: FontSizeOptions): FontSizes;
+
+/** Stroke widths per element type (in px) */
+export declare const STROKE_WIDTHS: {
+    readonly outerBox: 1;
+    readonly innerBox: 0.75;
+    /** Edge connector stroke (increased from 0.75 for better visibility) */
+    readonly connector: 1;
+};
+
+/**
+ * Vertical shift applied to all text elements for font-agnostic centering.
+ *
+ * Instead of relying on `dominant-baseline="central"` (which each font interprets
+ * differently based on its own ascent/descent metrics), we use the default alphabetic
+ * baseline and shift down by 0.35em. This places the optical center of text at the
+ * y coordinate, regardless of font family (Inter, JetBrains Mono, system fallbacks).
+ *
+ * The 0.35em value approximates the distance from alphabetic baseline to visual
+ * center of Latin text. Using `em` units ensures it scales with font size.
+ */
+export declare const TEXT_BASELINE_SHIFT: "0.35em";
+
+/**
+ * Splice a `data-src` attribute (the original diagram source, escaped) onto
+ * an already-built root `<svg ...>` opening tag, e.g. from
+ * `embedSource: true`. Applied to the string `svgOpenTag()` returns rather
+ * than the diagram source's own markup, so it always lands on the root
+ * element regardless of diagram type. No-op when `source` is undefined.
+ */
+export declare function withDataSrc(svgTag: string, source: string | undefined): string;
+
+export { }