@jarenjs/mermaid 0.34.0

package/src/ast.js

@@ -0,0 +1,252 @@
+//@ts-check
+/**
+ * @file The Mermaid AST vocabulary: node constructors and walkers.
+ *
+ * Every node is a plain JSON object born from a constructor so that all
+ * nodes of a type share one hidden class — property access stays
+ * monomorphic and the structural hash is deterministic (MERMAID-FORMAT
+ * §4). The AST is deliberately **geometry-free**:
+ * layout is a separate pass, so the AST is a faithful, lossless
+ * semantic model of the diagram's *meaning* — a directed graph
+ * (flowchart), an ordered interaction (sequence), a finite state machine
+ * (state) — that other engines project via JSLT without ever seeing a
+ * coordinate.
+ *
+ * Member order is fixed per constructor; keep it stable so the FNV-1a
+ * hash of `JSON.stringify` is reproducible and the round-trip printer
+ * (`to-mermaid.js`) is a fixed point.
+ */
+
+/** The diagram-document format version this package produces. */
+export const MERMAID_VERSION = '0.1';
+
+//#region envelope --------------------------------------------------
+
+/**
+ * @typedef {object} DiagramDocument
+ * @property {string} $mermaid format version
+ * @property {string} diagram diagram type (`flowchart`, `sequence`, …)
+ * @property {any} config plain-JSON config (theme, per-type options)
+ * @property {any} ast the type-specific, geometry-free AST
+ * @property {{ hash: string, direction: string|null, title: string|null }} meta
+ */
+
+/**
+ * Assemble the shared DiagramDocument envelope. Fresh per parse,
+ * never mutated after return — share-friendly for JSLT/patch.
+ * @param {string} diagram
+ * @param {any} config
+ * @param {any} ast
+ * @param {{ hash: string, direction: string|null, title: string|null }} meta
+ * @returns {DiagramDocument}
+ */
+export function diagramDocument(diagram, config, ast, meta) {
+  return { $mermaid: MERMAID_VERSION, diagram, config, ast, meta };
+}
+
+//#endregion
+//#region flowchart -------------------------------------------------
+
+/**
+ * @typedef {'rect'|'round'|'stadium'|'subroutine'|'cylinder'|'circle'
+ *   |'doublecircle'|'diamond'|'hexagon'|'parallelogram'|'parallelogram_alt'
+ *   |'trapezoid'|'trapezoid_alt'|'asymmetric'} FlowShape
+ */
+
+/**
+ * A flowchart vertex.
+ * @param {string} id
+ * @param {string} label
+ * @param {FlowShape} shape
+ * @returns {{ id: string, label: string, shape: FlowShape }}
+ */
+export function flowNode(id, label, shape) {
+  return { id, label, shape };
+}
+
+/**
+ * A flowchart edge (link). `stroke` is the line style, `head`/`tail`
+ * the endpoint markers, `length` the dash count (preserved so the
+ * canonical printer is a fixed point), `label` the optional edge text.
+ * @param {string} from
+ * @param {string} to
+ * @param {'solid'|'thick'|'dotted'} stroke
+ * @param {'none'|'arrow'|'circle'|'cross'} head
+ * @param {'none'|'arrow'|'circle'|'cross'} tail
+ * @param {number} length
+ * @param {string|null} label
+ * @returns {object}
+ */
+export function flowEdge(from, to, stroke, head, tail, length, label) {
+  return { from, to, stroke, head, tail, length, label };
+}
+
+/**
+ * A subgraph grouping.
+ * @param {string} id
+ * @param {string} label
+ * @param {string|null} direction
+ * @param {string[]} nodes ids of member nodes
+ * @returns {object}
+ */
+export function flowSubgraph(id, label, direction, nodes) {
+  return { id, label, direction, nodes };
+}
+
+/**
+ * A `classDef` style class.
+ * @param {string} name
+ * @param {string} styles semicolon-separated CSS declarations
+ * @returns {object}
+ */
+export function flowClassDef(name, styles) {
+  return { name, styles };
+}
+
+/**
+ * A `class`/`:::` assignment of a style class to a node.
+ * @param {string} node
+ * @param {string} name
+ * @returns {object}
+ */
+export function flowClass(node, name) {
+  return { node, name };
+}
+
+/**
+ * A `style` inline-style assignment to a node.
+ * @param {string} node
+ * @param {string} styles
+ * @returns {object}
+ */
+export function flowStyle(node, styles) {
+  return { node, styles };
+}
+
+/**
+ * The flowchart AST root.
+ * @param {string} direction
+ * @param {object[]} nodes
+ * @param {object[]} edges
+ * @param {object[]} subgraphs
+ * @param {object[]} classDefs
+ * @param {object[]} classes
+ * @param {object[]} styles
+ * @returns {object}
+ */
+export function flowchartAst(direction, nodes, edges, subgraphs, classDefs, classes, styles) {
+  return { direction, nodes, edges, subgraphs, classDefs, classes, styles };
+}
+
+//#endregion
+//#region sequence --------------------------------------------------
+
+/**
+ * A declared participant/actor.
+ * @param {string} id
+ * @param {string} label
+ * @param {'participant'|'actor'} kind
+ * @returns {object}
+ */
+export function seqParticipant(id, label, kind) {
+  return { id, label, kind };
+}
+
+/**
+ * A message statement.
+ * @param {string} from
+ * @param {string} to
+ * @param {string} text
+ * @param {'solid'|'dotted'} line
+ * @param {'arrow'|'open'|'cross'|'point'} head
+ * @param {'activate'|'deactivate'|null} activation `+`/`-` shorthand
+ * @returns {object}
+ */
+export function seqMessage(from, to, text, line, head, activation) {
+  return { kind: 'message', from, to, text, line, head, activation };
+}
+
+/**
+ * A note statement.
+ * @param {'left of'|'right of'|'over'} placement
+ * @param {string[]} actors
+ * @param {string} text
+ * @returns {object}
+ */
+export function seqNote(placement, actors, text) {
+  return { kind: 'note', placement, actors, text };
+}
+
+/**
+ * An explicit activate/deactivate statement.
+ * @param {'activate'|'deactivate'} kind
+ * @param {string} actor
+ * @returns {object}
+ */
+export function seqActivation(kind, actor) {
+  return { kind, actor };
+}
+
+/**
+ * A block statement (loop/opt/alt/par/critical/break). Single-branch
+ * blocks (loop/opt/critical/break) carry one branch; alt/par carry one
+ * per `else`/`and` section. `branches` is always present so the shape
+ * is monomorphic.
+ * @param {'loop'|'opt'|'alt'|'par'|'critical'|'break'} blockType
+ * @param {{ label: string, statements: object[] }[]} branches
+ * @returns {object}
+ */
+export function seqBlock(blockType, branches) {
+  return { kind: 'block', blockType, branches };
+}
+
+/**
+ * The sequence AST root.
+ * @param {object[]} participants explicitly declared participants
+ * @param {object[]} statements ordered interaction statements
+ * @param {boolean} autonumber
+ * @returns {object}
+ */
+export function sequenceAst(participants, statements, autonumber) {
+  return { participants, statements, autonumber };
+}
+
+//#endregion
+//#region generic AST for secondary/placeholder diagrams ------------
+
+/**
+ * A geometry-free "lines" AST for diagram types that parse-accept but
+ * are not yet laid out (the secondary types). Preserves the raw body
+ * lines so `toMermaid` round-trips and the coverage scorecard can be
+ * honest.
+ * @param {string} diagram
+ * @param {string[]} lines
+ * @returns {object}
+ */
+export function rawAst(diagram, lines) {
+  return { diagram, lines };
+}
+
+//#endregion
+//#region walkers ---------------------------------------------------
+
+/**
+ * Walk the ordered statements of a sequence AST (descending into block
+ * branches), calling `visitor(stmt)` pre-order.
+ * @param {object[]} statements
+ * @param {(stmt: any) => void} visitor
+ */
+export function walkSequence(statements, visitor) {
+  for (let i = 0; i < statements.length; i++) {
+    const stmt = statements[i];
+    visitor(stmt);
+    if (/** @type {any} */ (stmt).kind === 'block') {
+      const branches = /** @type {any} */ (stmt).branches;
+      for (let b = 0; b < branches.length; b++) {
+        walkSequence(branches[b].statements, visitor);
+      }
+    }
+  }
+}
+
+//#endregion

package/src/component/index.js

@@ -0,0 +1,109 @@
+//@ts-check
+/**
+ * @file The Mermaid VISUAL COMPONENT — part two of the package.
+ *
+ * Everything below this line is presentation glue; the engine
+ * (`@jarenjs/mermaid`) neither knows nor needs any of it. Mirrors
+ * `@jarenjs/md`'s `createMdComponent` field-for-field:
+ *
+ *  - `createMermaidComponent()` — a memoized `view()` projection for
+ *    `@jarenjs/app` viewModels (reference-stable, so an unchanged source
+ *    patches in O(1) — the O(change) contract), `effects` entries for
+ *    the app effect registry (`mermaid-render`, `mermaid-load`), and a
+ *    `hydrate()` pass kept for API symmetry (a no-op in v1: the render is
+ *    already complete);
+ *  - `styles/mermaid.css` — the component stylesheet.
+ *
+ * The boundary is one-way: the component imports the engine, never the
+ * reverse.
+ */
+
+import { createProjectionMemo } from '@jarenjs/view/helpers';
+import { compileMermaid, diagramToVnode } from '../index.js';
+
+/**
+ * @typedef {object} MermaidComponentOptions
+ * @property {any} [theme] theme name or override object
+ * @property {number} [memoLimit] LRU size for the source-string memo (default 32)
+ * @property {string | URL} [base] base URL for `mermaid-load`
+ * @property {typeof globalThis.fetch} [fetch] fetch implementation for `mermaid-load`
+ * @property {(err: any) => void} [onHydrateError]
+ */
+/**
+ * @typedef {object} MermaidComponent
+ * @property {(source: string) => any} compile memoized compile
+ * @property {(sourceOrDoc: any) => any} view memoized vnode projection
+ * @property {Record<string, (props: any, dispatch: any) => any>} effects
+ * @property {(container: any) => void} hydrate no-op in v1
+ */
+
+/**
+ * Create the Mermaid component.
+ *
+ * @example
+ * const mermaid = createMermaidComponent();
+ * createApp(appDoc, {
+ *   effects: { ...mermaid.effects },
+ *   viewModel: (state) => ({ ...state, diagram: mermaid.view(state.source) }),
+ * });
+ *
+ * @param {MermaidComponentOptions} [options]
+ * @returns {MermaidComponent}
+ */
+export function createMermaidComponent(options = {}) {
+  const compileOptions = { theme: options.theme };
+
+  const { compile, view } = createProjectionMemo({
+    memoLimit: options.memoLimit ?? 32,
+    compile: (source) => compileMermaid(source, compileOptions),
+    toVnode: (compiled) => compiled.toVnode(),
+    docToVnode: (doc) => diagramToVnode(doc, compileOptions),
+  });
+
+  return {
+    compile,
+
+    view,
+
+    effects: {
+      /**
+       * Render an in-state source to an SVG vnode and dispatch it:
+       * `{ run: 'mermaid-render', with: { source, done } }`.
+       */
+      'mermaid-render': (props, dispatch) => {
+        dispatch(props.done, compile(String(props.source ?? '')).toVnode());
+      },
+
+      /**
+       * Fetch a `.mmd`/`.mermaid` URL and dispatch the DiagramDocument:
+       * `{ run: 'mermaid-load', with: { url, done, error? } }`.
+       */
+      'mermaid-load': (props, dispatch) => {
+        const f = options.fetch ?? globalThis.fetch;
+        const url = options.base ? new URL(String(props.url), options.base).href : String(props.url);
+        return f(url).then(
+          (res) => {
+            if (!res.ok) throw new Error(`HTTP ${res.status} for ${url}`);
+            return res.text();
+          },
+        ).then(
+          (text) => dispatch(props.done, compile(text).doc),
+          (err) => {
+            if (props.error !== undefined) {
+              dispatch(props.error, { url, message: String(err?.message ?? err) });
+            }
+            else {
+              throw err;
+            }
+          },
+        );
+      },
+    },
+
+    // Render is complete; hydrate is reserved for optional
+    // client-only enhancements (pan/zoom) that are out of scope for v1.
+    hydrate() {
+      /* no-op */
+    },
+  };
+}

package/src/errors.js

@@ -0,0 +1,35 @@
+//@ts-check
+/**
+ * @file The engine's one error type. Parsers raise it with a 1-based
+ * `line`/`column`; the render path (`diagramToVnode`/`renderMermaid`)
+ * catches it and emits a clear error vnode instead of throwing, so
+ * rendering is always total.
+ */
+
+export class MermaidParseError extends Error {
+  /**
+   * @param {string} message
+   * @param {number} [line] 1-based line number
+   * @param {number} [column] 1-based column number
+   */
+  constructor(message, line = 0, column = 0) {
+    super(message);
+    this.name = 'MermaidParseError';
+    /** @type {number} */
+    this.line = line;
+    /** @type {number} */
+    this.column = column;
+  }
+}
+
+/**
+ * The `fail(message, position)` idiom from `packages/json/src/path.js`,
+ * adapted to line/column. Throws; never returns.
+ * @param {string} message
+ * @param {number} line
+ * @param {number} [column]
+ * @returns {never}
+ */
+export function fail(message, line, column = 0) {
+  throw new MermaidParseError(message, line, column);
+}

package/src/index.js

@@ -0,0 +1,155 @@
+//@ts-check
+/**
+ * @file `@jarenjs/mermaid` — a native, headless Mermaid clone. This is
+ * the **engine** (part one): pure functions over data — text ⇄ AST ⇄
+ * pure-vnode SVG — that know only the `@jarenjs/view` vnode shape. It
+ * imports nothing from the component, `@jarenjs/app`, the DOM or
+ * `@jarenjs/md` (the two-layer rule).
+ *
+ * The pipeline mirrors `@jarenjs/md`:
+ *
+ *   source ──parseMermaid──▶ DiagramDocument (geometry-free JSON AST)
+ *                              │
+ *            ┌─────────────────┼───────────────────┐
+ *            ▼                 ▼                   ▼
+ *       toMermaid()      layoutDiagram()      JSLT / query
+ *       (canonical        → diagramToVnode()  (the AST is an
+ *        round-trip)       (pure-vnode SVG)    ordinary document)
+ */
+
+import { renderToString, createDomRenderer } from '@jarenjs/view';
+import { parseMermaid } from './parser/index.js';
+import { toMermaid } from './to-mermaid.js';
+import { diagramToVnode, layoutDiagram } from './render/index.js';
+import { hashContent } from './utils.js';
+
+export { parseMermaid } from './parser/index.js';
+export { toMermaid } from './to-mermaid.js';
+export { parseMermaidConfig } from './parser/config.js';
+export { layoutDiagram, diagramToVnode } from './render/index.js';
+export { createTheme, THEMES, HOST_VARS } from './theme.js';
+export { sanitizeHref } from '@jarenjs/view/helpers';
+export { MermaidParseError } from './errors.js';
+export { hashContent } from './utils.js';
+export {
+  MERMAID_VERSION, diagramDocument, walkSequence,
+  flowNode, flowEdge, sequenceAst, flowchartAst,
+} from './ast.js';
+
+/**
+ * Convenience: parse → layout → render, error-safe, in one call.
+ * @param {string} source
+ * @param {{ theme?: any }} [options]
+ * @returns {any} an SVG vnode
+ */
+export function renderMermaid(source, options = {}) {
+  return diagramToVnode(source, options);
+}
+
+/**
+ * @typedef {object} CompiledMermaid
+ * @property {import('./ast.js').DiagramDocument} doc the parsed document
+ * @property {() => any} toVnode cached pure-vnode SVG
+ * @property {() => string} toSvgString cached standalone SVG string (SSR)
+ * @property {() => string} toText canonical Mermaid text (`toMermaid`)
+ * @property {(visitor: (stmt: any) => void) => void} walk walk the AST
+ */
+
+/**
+ * Parse once and return a bundle of cached projections.
+ * `toVnode`/`toSvgString`/`toText` each compute at most once; the
+ * vnode is returned by reference on repeat calls, so an unchanged
+ * document patches in O(1) through the view reconciler.
+ *
+ * @param {string} source
+ * @param {{ theme?: any, [k: string]: any }} [options]
+ * @returns {CompiledMermaid}
+ */
+export function compileMermaid(source, options = {}) {
+  let doc = null;
+  let parseError = null;
+  try {
+    doc = parseMermaid(source, options);
+  }
+  catch (err) {
+    parseError = err;
+  }
+  let vnode;
+  let svg;
+  let text;
+  let layout;
+  return {
+    doc,
+    parseError,
+    toVnode() {
+      // Error-safe: a parse failure renders the error vnode, which
+      // `diagramToVnode` produces when handed the original source.
+      if (vnode === undefined) vnode = diagramToVnode(doc ?? source, options);
+      return vnode;
+    },
+    toSvgString() {
+      if (svg === undefined) svg = renderToString(this.toVnode());
+      return svg;
+    },
+    toText() {
+      if (text === undefined) text = doc !== null ? toMermaid(doc) : source;
+      return text;
+    },
+    toLayout() {
+      // The editor's hit-testing substrate: the pure PositionedDiagram
+      // (nodes with x/y/w/h, edges with routed points), cached like the
+      // other projections — same compiled document, reference-equal
+      // scene. Null for types without a geometric layout, and for
+      // documents that failed to parse.
+      if (layout === undefined) layout = doc !== null ? layoutDiagram(doc) : null;
+      return layout;
+    },
+    walk(visitor) {
+      if (doc !== null) walkDoc(doc, visitor);
+    },
+  };
+}
+
+/**
+ * A host-DOM renderer (mirrors `@jarenjs/md`'s `createMdRenderer`).
+ * Owns a `@jarenjs/view` DOM renderer over `container` and patches the
+ * rendered SVG on each `render(docOrSource)` call. `createDomRenderer`
+ * touches no DOM until it is handed a container, so importing it keeps
+ * the engine host-agnostic.
+ *
+ * @param {{ container: any, document?: any, theme?: any, [k: string]: any }} config
+ * @returns {(docOrSource: any) => void}
+ */
+export function createMermaidRenderer(config) {
+  const render = createDomRenderer(config.container, { document: config.document });
+  return (docOrSource) => {
+    render(diagramToVnode(docOrSource, config));
+  };
+}
+
+/**
+ * Walk a document's AST statements (sequence blocks descend).
+ * @param {import('./ast.js').DiagramDocument} doc
+ * @param {(stmt: any) => void} visitor
+ */
+function walkDoc(doc, visitor) {
+  const ast = doc.ast;
+  if (doc.diagram === 'sequence') {
+    const walk = (stmts) => {
+      for (const s of stmts) {
+        visitor(s);
+        if (s.kind === 'block') for (const b of s.branches) walk(b.statements);
+      }
+    };
+    walk(ast.statements);
+  }
+  else if (doc.diagram === 'flowchart') {
+    for (const n of ast.nodes) visitor(n);
+    for (const e of ast.edges) visitor(e);
+  }
+  else {
+    visitor(ast);
+  }
+}
+
+export { hashContent as contentHash };