@zombie-mermaid/svg-renderer 2.2.1 → 3.0.0

package/dist/index.d.cts

@@ -19,6 +19,7 @@ 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 { RenderOptions } from '@zombie-mermaid/core';
 import { SequenceDiagram } from '@zombie-mermaid/mermaid-parser';
 import { SequenceRenderOptions } from '@zombie-mermaid/core';
 import { SvgEmitOptions } from '@zombie-mermaid/core';
@@ -408,6 +409,66 @@ export declare function renderClassSvg(diagram: PositionedClassDiagram, colors:
  */
 export declare function renderErSvg(diagram: PositionedErDiagram, colors: DiagramColors, font?: string, transparent?: boolean, fontSizes?: FontSizes, embedSource?: string, title?: string, decorative?: boolean, emit?: SvgEmitOptions): string;
 
+/** @deprecated Use `renderMermaidSVGAsync` */
+export declare const renderMermaid: typeof renderMermaidSVGAsync;
+
+/**
+ * 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 declare function renderMermaidSVG(text: string, options?: RenderOptions): string;
+
+/**
+ * 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 declare function renderMermaidSVGAsync(text: string, options?: RenderOptions): Promise<string>;
+
+/** @deprecated Use `renderMermaidSVG` */
+export declare const renderMermaidSync: typeof renderMermaidSVG;
+
 /**
  * Render a positioned sequence diagram as an SVG string.
  *
@@ -512,6 +573,34 @@ export declare const STROKE_WIDTHS: {
  */
 export declare const TEXT_BASELINE_SHIFT: "0.35em";
 
+/**
+ * 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 declare function themeCssVariables(options?: RenderOptions): string;
+
 /**
  * Splice a `data-src` attribute (the original diagram source, escaped) onto
  * an already-built root `<svg ...>` opening tag, e.g. from

package/dist/index.d.ts

@@ -19,6 +19,7 @@ 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 { RenderOptions } from '@zombie-mermaid/core';
 import { SequenceDiagram } from '@zombie-mermaid/mermaid-parser';
 import { SequenceRenderOptions } from '@zombie-mermaid/core';
 import { SvgEmitOptions } from '@zombie-mermaid/core';
@@ -408,6 +409,66 @@ export declare function renderClassSvg(diagram: PositionedClassDiagram, colors:
  */
 export declare function renderErSvg(diagram: PositionedErDiagram, colors: DiagramColors, font?: string, transparent?: boolean, fontSizes?: FontSizes, embedSource?: string, title?: string, decorative?: boolean, emit?: SvgEmitOptions): string;
 
+/** @deprecated Use `renderMermaidSVGAsync` */
+export declare const renderMermaid: typeof renderMermaidSVGAsync;
+
+/**
+ * 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 declare function renderMermaidSVG(text: string, options?: RenderOptions): string;
+
+/**
+ * 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 declare function renderMermaidSVGAsync(text: string, options?: RenderOptions): Promise<string>;
+
+/** @deprecated Use `renderMermaidSVG` */
+export declare const renderMermaidSync: typeof renderMermaidSVG;
+
 /**
  * Render a positioned sequence diagram as an SVG string.
  *
@@ -512,6 +573,34 @@ export declare const STROKE_WIDTHS: {
  */
 export declare const TEXT_BASELINE_SHIFT: "0.35em";
 
+/**
+ * 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 declare function themeCssVariables(options?: RenderOptions): string;
+
 /**
  * Splice a `data-src` attribute (the original diagram source, escaped) onto
  * an already-built root `<svg ...>` opening tag, e.g. from