@mermaid-js/mermaid-cli 9.1.6 → 9.2.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mermaid-js/mermaid-cli",
-  "version": "9.1.6",
+  "version": "9.2.2",
   "description": "Command-line interface for mermaid",
   "license": "MIT",
   "repository": "git@github.com:mermaid-js/mermaid-cli.git",
@@ -14,9 +14,8 @@
   },
   "exports": "./src/index.js",
   "scripts": {
-    "upgrade": "yarn-upgrade-all && sh copy_modules.sh",
-    "prepare": "sh copy_modules.sh",
-    "prepack": "sh copy_modules.sh",
+    "prepare": "vite build",
+    "prepack": "vite build",
     "test": "standard && yarn node --experimental-vm-modules $(yarn bin jest)",
     "lint": "standard",
     "lint-fix": "standard --fix"
@@ -24,20 +23,22 @@
   "dependencies": {
     "chalk": "^5.0.1",
     "commander": "^9.0.0",
-    "puppeteer": "^16.1.0"
+    "puppeteer": "^19.0.0"
   },
   "devDependencies": {
     "@fortawesome/fontawesome-free-webfonts": "^1.0.9",
-    "mermaid": "^9.1.2",
-    "jest": "^28.1.2",
+    "@mermaid-js/mermaid-mindmap": "^9.2.2",
+    "mermaid": "^9.2.2",
+    "jest": "^29.0.1",
     "standard": "^17.0.0",
+    "vite": "^3.2.3",
+    "vite-plugin-singlefile": "^0.13.1",
+    "vite-svg-loader": "^3.6.0",
     "yarn-upgrade-all": "^0.7.0"
   },
   "files": [
     "src/",
-    "mermaid.min.js",
-    "index.html",
-    "fontawesome/*"
+    "dist/"
   ],
   "jest": {
     "moduleNameMapper": {
@@ -46,7 +47,7 @@
   },
   "standard": {
     "ignore": [
-      "mermaid.min.js"
+      "/dist/"
     ]
   }
 }

package/src/index.js

@@ -60,13 +60,7 @@ const getInputData = async inputFile => new Promise((resolve, reject) => {
   })
 })
 
-const convertToValidXML = html => {
-  // <br> tags in valid HTML (from innerHTML) look like <br>, but they must look like <br/> to be valid XML (such as SVG)
-  return html.replace(/<br>/gi, '<br/>')
-}
-
 async function cli () {
-// TODO: This is currently unindented to make `git diff` easier for PR reviewers.
   const commander = new Command()
   commander
     .version(pkg.version)
@@ -75,6 +69,7 @@ async function cli () {
     .option('-H, --height [height]', 'Height of the page. Optional. Default: 600', /^\d+$/, '600')
     .option('-i, --input <input>', 'Input mermaid file. Files ending in .md will be treated as Markdown and all charts (e.g. ```mermaid (...)```) will be extracted and generated. Required.')
     .option('-o, --output [output]', 'Output file. It should be either md, svg, png or pdf. Optional. Default: input + ".svg"')
+    .option('-e, --outputFormat <format>', 'Output format for the generated image. It should be either svg, png or pdf. Optional. Default: output file extension')
     .option('-b, --backgroundColor [backgroundColor]', 'Background color for pngs/svgs (not pdfs). Example: transparent, red, \'#F0F0F0\'. Optional. Default: white')
     .option('-c, --configFile [configFile]', 'JSON configuration file for mermaid. Optional')
     .option('-C, --cssFile [cssFile]', 'CSS file for the page. Optional')
@@ -86,7 +81,7 @@ async function cli () {
 
   const options = commander.opts()
 
-  let { theme, width, height, input, output, backgroundColor, configFile, cssFile, puppeteerConfigFile, scale, pdfFit, quiet } = options
+  let { theme, width, height, input, output, outputFormat, backgroundColor, configFile, cssFile, puppeteerConfigFile, scale, pdfFit, quiet } = options
 
   // check input file
   if (!(input || inputPipedFromStdin())) {
@@ -103,7 +98,11 @@ async function cli () {
   // if an input file is defined, it should take precedence, otherwise, input is
   // coming from stdin and just name the file out.svg, if it hasn't been
   // specified with the '-o' option
-    output = input ? (input + '.svg') : 'out.svg'
+    if (outputFormat) {
+      output = input ? (`${input}.${outputFormat}`) : `out.${outputFormat}`
+    } else {
+      output = input ? (`${input}.svg`) : 'out.svg'
+    }
   }
   if (!/\.(?:svg|png|pdf|md)$/.test(output)) {
     error('Output file must end with ".md", ".svg", ".png" or ".pdf"')
@@ -144,6 +143,7 @@ async function cli () {
     input, output, {
       puppeteerConfig,
       quiet,
+      outputFormat,
       parseMMDOptions: {
         mermaidConfig, backgroundColor, myCSS, pdfFit, viewport: { width, height, deviceScaleFactor }
       }
@@ -163,84 +163,172 @@ async function cli () {
 /**
  * Parse and render a mermaid diagram.
  *
+ * @deprecated Prefer {@link renderMermaid}, as it also returns useful metadata.
+ *
  * @param {puppeteer.Browser} browser - Puppeteer Browser
  * @param {string} definition - Mermaid diagram definition
  * @param {"svg" | "png" | "pdf"} outputFormat - Mermaid output format.
  * @param {ParseMDDOptions} [opt] - Options, see {@link ParseMDDOptions} for details.
+ *
  * @returns {Promise<Buffer>} The output file in bytes.
  */
-async function parseMMD (browser, definition, outputFormat, { viewport, backgroundColor = 'white', mermaidConfig = {}, myCSS, pdfFit } = {}) {
+async function parseMMD (...args) {
+  const { data } = await renderMermaid(...args)
+  return data
+}
+
+/**
+ * Render a mermaid diagram.
+ *
+ * @param {puppeteer.Browser} browser - Puppeteer Browser
+ * @param {string} definition - Mermaid diagram definition
+ * @param {"svg" | "png" | "pdf"} outputFormat - Mermaid output format.
+ * @param {ParseMDDOptions} [opt] - Options, see {@link ParseMDDOptions} for details.
+ * @returns {Promise<{title?: string, desc?: string, data: Buffer}>} The output file in bytes,
+ * with optional metadata.
+ */
+async function renderMermaid (browser, definition, outputFormat, { viewport, backgroundColor = 'white', mermaidConfig = {}, myCSS, pdfFit } = {}) {
   const page = await browser.newPage()
-  if (viewport) {
-    await page.setViewport(viewport)
-  }
-  const mermaidHTMLPath = path.join(__dirname, '..', 'index.html')
-  await page.goto(url.pathToFileURL(mermaidHTMLPath))
-  await page.$eval('body', (body, backgroundColor) => {
-    body.style.background = backgroundColor
-  }, backgroundColor)
-  await page.$eval('#container', (container, definition, mermaidConfig, myCSS, backgroundColor) => {
-    container.textContent = definition
-    window.mermaid.initialize(mermaidConfig)
-    // should throw an error if mmd diagram is invalid
-    try {
-      window.mermaid.initThrowsErrors(undefined, container)
-    } catch (error) {
-      if (error instanceof Error) {
-        // mermaid-js doesn't currently throws JS Errors, but let's leave this
-        // here in case it does in the future
-        throw error
+  page.on('console', (msg) => {
+    console.log(msg.text())
+  })
+  try {
+    if (viewport) {
+      await page.setViewport(viewport)
+    }
+    const mermaidHTMLPath = path.join(__dirname, '..', 'dist', 'index.html')
+    await page.goto(url.pathToFileURL(mermaidHTMLPath))
+    await page.$eval('body', (body, backgroundColor) => {
+      body.style.background = backgroundColor
+    }, backgroundColor)
+    const metadata = await page.$eval('#container', async (container, definition, mermaidConfig, myCSS, backgroundColor) => {
+      container.textContent = definition
+
+      /** @type {import("mermaid")} Already imported mermaid instance */
+      const mermaid = globalThis.mermaid
+      /** @type {import("@mermaid-js/mermaid-mindmap")} */
+      const mermaidMindmap = globalThis.mermaidMindmap
+
+      await mermaid.registerExternalDiagrams([mermaidMindmap])
+
+      mermaid.initialize(mermaidConfig)
+      // should throw an error if mmd diagram is invalid
+      try {
+        await mermaid.initThrowsErrorsAsync(undefined, container)
+      } catch (error) {
+        if (error instanceof Error) {
+          // mermaid-js doesn't currently throws JS Errors, but let's leave this
+          // here in case it does in the future
+          throw error
+        } else {
+          throw new Error(error?.message ?? 'Unknown mermaid render error')
+        }
+      }
+
+      const svg = container.getElementsByTagName?.('svg')?.[0]
+      if (svg?.style) {
+        svg.style.backgroundColor = backgroundColor
       } else {
-        throw new Error(error?.message ?? 'Unknown mermaid render error')
+        warn('svg not found. Not applying background color.')
+      }
+      if (myCSS) {
+        // add CSS as a <svg>...<style>... element
+        // see https://developer.mozilla.org/en-US/docs/Web/API/SVGStyleElement
+        const style = document.createElementNS('http://www.w3.org/2000/svg', 'style')
+        style.appendChild(document.createTextNode(myCSS))
+        svg.appendChild(style)
       }
-    }
 
-    const svg = container.getElementsByTagName?.('svg')?.[0]
-    if (svg?.style) {
-      svg.style.backgroundColor = backgroundColor
-    } else {
-      warn('svg not found. Not applying background color.')
-      return
-    }
-    if (myCSS) {
-      // add CSS as a <svg>...<style>... element
-      // see https://developer.mozilla.org/en-US/docs/Web/API/SVGStyleElement
-      const style = document.createElementNS('http://www.w3.org/2000/svg', 'style')
-      style.appendChild(document.createTextNode(myCSS))
-      svg.appendChild(style)
-    }
-  }, definition, mermaidConfig, myCSS, backgroundColor)
+      // Finds SVG metadata for accessibility purposes
+      /** SVG title */
+      let title = null
+      // If <title> exists, it must be the first child Node,
+      // see https://www.w3.org/TR/SVG11/struct.html#DescriptionAndTitleElements
+      /* global SVGTitleElement, SVGDescElement */ // These exist in browser-based code
+      if (svg.firstChild instanceof SVGTitleElement) {
+        title = svg.firstChild.textContent
+      }
+      /** SVG description. According to SVG spec, we should use the first one we find */
+      let desc = null
+      for (const svgNode of svg.children) {
+        if (svgNode instanceof SVGDescElement) {
+          desc = svgNode.textContent
+        }
+      }
+      return {
+        title, desc
+      }
+    }, definition, mermaidConfig, myCSS, backgroundColor)
 
-  if (outputFormat === 'svg') {
-    const svg = await page.$eval('#container', (container) => {
-      return container.innerHTML
-    })
-    const svgXML = convertToValidXML(svg)
-    return Buffer.from(svgXML, 'utf8')
-  } else if (outputFormat === 'png') {
-    const clip = await page.$eval('svg', svg => {
-      const react = svg.getBoundingClientRect()
-      return { x: Math.floor(react.left), y: Math.floor(react.top), width: Math.ceil(react.width), height: Math.ceil(react.height) }
-    })
-    await page.setViewport({ ...viewport, width: clip.x + clip.width, height: clip.y + clip.height })
-    return await page.screenshot({ clip, omitBackground: backgroundColor === 'transparent' })
-  } else { // pdf
-    if (pdfFit) {
+    if (outputFormat === 'svg') {
+      const svgXML = await page.$eval('svg', (svg) => {
+        // SVG might have HTML <foreignObject> that are not valid XML
+        // E.g. <br> must be replaced with <br/>
+        // Luckily the DOM Web API has the XMLSerializer for this
+        // eslint-disable-next-line no-undef
+        const xmlSerializer = new XMLSerializer()
+        return xmlSerializer.serializeToString(svg)
+      })
+      return {
+        ...metadata,
+        data: Buffer.from(svgXML, 'utf8')
+      }
+    } else if (outputFormat === 'png') {
       const clip = await page.$eval('svg', svg => {
         const react = svg.getBoundingClientRect()
-        return { x: react.left, y: react.top, width: react.width, height: react.height }
-      })
-      return await page.pdf({
-        omitBackground: backgroundColor === 'transparent',
-        width: (Math.ceil(clip.width) + clip.x * 2) + 'px',
-        height: (Math.ceil(clip.height) + clip.y * 2) + 'px',
-        pageRanges: '1-1'
-      })
-    } else {
-      return await page.pdf({
-        omitBackground: backgroundColor === 'transparent'
+        return { x: Math.floor(react.left), y: Math.floor(react.top), width: Math.ceil(react.width), height: Math.ceil(react.height) }
       })
+      await page.setViewport({ ...viewport, width: clip.x + clip.width, height: clip.y + clip.height })
+      return {
+        ...metadata,
+        data: await page.screenshot({ clip, omitBackground: backgroundColor === 'transparent' })
+      }
+    } else { // pdf
+      if (pdfFit) {
+        const clip = await page.$eval('svg', svg => {
+          const react = svg.getBoundingClientRect()
+          return { x: react.left, y: react.top, width: react.width, height: react.height }
+        })
+        return {
+          ...metadata,
+          data: await page.pdf({
+            omitBackground: backgroundColor === 'transparent',
+            width: (Math.ceil(clip.width) + clip.x * 2) + 'px',
+            height: (Math.ceil(clip.height) + clip.y * 2) + 'px',
+            pageRanges: '1-1'
+          })
+        }
+      } else {
+        return {
+          ...metadata,
+          data: await page.pdf({
+            omitBackground: backgroundColor === 'transparent'
+          })
+        }
+      }
     }
+  } finally {
+    await page.close()
+  }
+}
+
+/**
+ * Creates a markdown image syntax.
+ *
+ * @param {object} params - Parameters.
+ * @param {string} params.url - Path to image.
+ * @param {string} params.alt - Image alt text, required.
+ * @param {string} [params.title] - Image title text.
+ * @returns {`![${string}](${string})`} The markdown image text.
+ */
+function markdownImage ({ url, title, alt }) {
+  // we can't use String.prototype.replaceAll since it's not supported in Node v14
+  const altEscaped = alt.replace(/[[\]\\]/g, '\\$&')
+  if (title) {
+    const titleEscaped = title.replace(/["\\]/g, '\\$&')
+    return `![${altEscaped}](${url} "${titleEscaped}")`
+  } else {
+    return `![${altEscaped}](${url})`
   }
 }
 
@@ -254,57 +342,80 @@ async function parseMMD (browser, definition, outputFormat, { viewport, backgrou
  * @param {Object} [opts] - Options
  * @param {puppeteer.LaunchOptions} [opts.puppeteerConfig] - Puppeteer launch options.
  * @param {boolean} [opts.quiet] - If set, suppress log output.
+ * @param {"svg" | "png" | "pdf"} [opts.outputFormat] - Mermaid output format.
+ * Defaults to `output` extension. Overrides `output` extension if set.
  * @param {ParseMDDOptions} [opts.parseMMDOptions] - Options to pass to {@link parseMMDOptions}.
  */
-async function run (input, output, { puppeteerConfig = {}, quiet = false, parseMMDOptions } = {}) {
+async function run (input, output, { puppeteerConfig = {}, quiet = false, outputFormat, parseMMDOptions } = {}) {
   const info = message => {
     if (!quiet) {
       console.info(message)
     }
   }
 
-  const mermaidChartsInMarkdown = /^```(?:mermaid)(\r?\n([\s\S]*?))```$/
+  const mermaidChartsInMarkdown = /^\s*```(?:mermaid)(\r?\n([\s\S]*?))```\s*$/
   const mermaidChartsInMarkdownRegexGlobal = new RegExp(mermaidChartsInMarkdown, 'gm')
-  const mermaidChartsInMarkdownRegex = new RegExp(mermaidChartsInMarkdown)
   const browser = await puppeteer.launch(puppeteerConfig)
   try {
-  // TODO: indent this (currently unindented to make `git diff` smaller)
+    if (!outputFormat) {
+      outputFormat = path.extname(output).replace('.', '')
+    }
+    if (outputFormat === 'md') {
+      // fallback to svg in case no outputFormat is given and output file is MD
+      outputFormat = 'svg'
+    }
+    if (!/(?:svg|png|pdf)$/.test(outputFormat)) {
+      throw new Error('Output format must be one of "svg", "png" or "pdf"')
+    }
+
     const definition = await getInputData(input)
     if (/\.md$/.test(input)) {
-      const diagrams = []
-      const outDefinition = definition.replace(mermaidChartsInMarkdownRegexGlobal, (mermaidMd) => {
-        const md = mermaidChartsInMarkdownRegex.exec(mermaidMd)[1]
+      const imagePromises = []
+      for (const mermaidCodeblockMatch of definition.matchAll(mermaidChartsInMarkdownRegexGlobal)) {
+        const mermaidDefinition = mermaidCodeblockMatch[1]
 
         // Output can be either a template image file, or a `.md` output file.
         //   If it is a template image file, use that to created numbered diagrams
         //     I.e. if "out.png", use "out-1.png", "out-2.png", etc
         //   If it is an output `.md` file, use that to base .svg numbered diagrams on
         //     I.e. if "out.md". use "out-1.svg", "out-2.svg", etc
-        const outputFile = output.replace(/(\.(md|png|svg|pdf))$/, `-${diagrams.length + 1}$1`).replace(/(\.md)$/, '.svg')
+        const outputFile = output.replace(/(\.(md|png|svg|pdf))$/, `-${imagePromises.length + 1}$1`).replace(/(\.md)$/, `.${outputFormat}`)
         const outputFileRelative = `./${path.relative(path.dirname(path.resolve(output)), path.resolve(outputFile))}`
-        diagrams.push([outputFile, md])
-        return `![diagram](${outputFileRelative})`
-      })
 
-      if (diagrams.length) {
-        info(`Found ${diagrams.length} mermaid charts in Markdown input`)
-        await Promise.all(diagrams.map(async ([imgFile, md]) => {
-          const data = await parseMMD(browser, md, path.extname(imgFile).replace('.', ''), parseMMDOptions)
-          await fs.promises.writeFile(imgFile, data)
-          info(` ✅ ${imgFile}`)
-        })
-        )
+        const imagePromise = (async () => {
+          const { title, desc, data } = await renderMermaid(browser, mermaidDefinition, outputFormat, parseMMDOptions)
+          await fs.promises.writeFile(outputFile, data)
+          info(` ✅ ${outputFileRelative}`)
+
+          return {
+            url: outputFileRelative,
+            title,
+            alt: desc
+          }
+        })()
+        imagePromises.push(imagePromise)
+      }
+
+      if (imagePromises.length) {
+        info(`Found ${imagePromises.length} mermaid charts in Markdown input`)
       } else {
         info('No mermaid charts found in Markdown input')
       }
 
+      const images = await Promise.all(imagePromises)
+
       if (/\.md$/.test(output)) {
+        const outDefinition = definition.replace(mermaidChartsInMarkdownRegexGlobal, (_mermaidMd) => {
+          // pop first image from front of array
+          const { url, title, alt } = images.shift()
+          return markdownImage({ url, title, alt: alt || 'diagram' })
+        })
         await fs.promises.writeFile(output, outDefinition, 'utf-8')
         info(` ✅ ${output}`)
       }
     } else {
       info('Generating single mermaid chart')
-      const data = await parseMMD(browser, definition, path.extname(output).replace('.', ''), parseMMDOptions)
+      const data = await parseMMD(browser, definition, outputFormat, parseMMDOptions)
       await fs.promises.writeFile(output, data)
     }
   } finally {
@@ -312,4 +423,4 @@ async function run (input, output, { puppeteerConfig = {}, quiet = false, parseM
   }
 }
 
-export { run, parseMMD, cli, error }
+export { run, renderMermaid, parseMMD, cli, error }

package/fontawesome/css/fa-brands.css

@@ -1,9 +0,0 @@
-@font-face {
-  font-family: 'Font Awesome 5 Brands';
-  font-style: normal;
-  font-weight: normal;
-  src: url("../webfonts/fa-brands-400.eot");
-  src: url("../webfonts/fa-brands-400.eot?#iefix") format("embedded-opentype"), url("../webfonts/fa-brands-400.woff2") format("woff2"), url("../webfonts/fa-brands-400.woff") format("woff"), url("../webfonts/fa-brands-400.ttf") format("truetype"), url("../webfonts/fa-brands-400.svg#fontawesome") format("svg"); }
-
-.fab {
-  font-family: 'Font Awesome 5 Brands'; }

package/fontawesome/css/fa-regular.css

@@ -1,10 +0,0 @@
-@font-face {
-  font-family: 'Font Awesome 5 Free';
-  font-style: normal;
-  font-weight: 400;
-  src: url("../webfonts/fa-regular-400.eot");
-  src: url("../webfonts/fa-regular-400.eot?#iefix") format("embedded-opentype"), url("../webfonts/fa-regular-400.woff2") format("woff2"), url("../webfonts/fa-regular-400.woff") format("woff"), url("../webfonts/fa-regular-400.ttf") format("truetype"), url("../webfonts/fa-regular-400.svg#fontawesome") format("svg"); }
-
-.far {
-  font-family: 'Font Awesome 5 Free';
-  font-weight: 400; }

package/fontawesome/css/fa-solid.css

@@ -1,11 +0,0 @@
-@font-face {
-  font-family: 'Font Awesome 5 Free';
-  font-style: normal;
-  font-weight: 900;
-  src: url("../webfonts/fa-solid-900.eot");
-  src: url("../webfonts/fa-solid-900.eot?#iefix") format("embedded-opentype"), url("../webfonts/fa-solid-900.woff2") format("woff2"), url("../webfonts/fa-solid-900.woff") format("woff"), url("../webfonts/fa-solid-900.ttf") format("truetype"), url("../webfonts/fa-solid-900.svg#fontawesome") format("svg"); }
-
-.fa,
-.fas {
-  font-family: 'Font Awesome 5 Free';
-  font-weight: 900; }