Add elk layout support to mermaid (#36486)

Fixes: https://github.com/go-gitea/gitea/issues/34769

This allows the user to opt-in to using `elk` layouts using either YAML
frontmatter or `%%{ init` directives inside the markup code block. The
default layout is not changed.

---------

Signed-off-by: silverwind <me@silverwind.io>
Co-authored-by: wxiaoguang <wxiaoguang@gmail.com>

package.json

@@ -15,6 +15,7 @@
     "@github/relative-time-element": "5.0.0",
     "@github/text-expander-element": "2.9.4",
     "@mcaptcha/vanilla-glue": "0.1.0-alpha-3",
+    "@mermaid-js/layout-elk": "0.2.0",
     "@primer/octicons": "19.21.2",
     "@resvg/resvg-wasm": "2.6.2",
     "@silverwind/vue3-calendar-heatmap": "2.1.1",

pnpm-lock.yaml

@@ -53,6 +53,9 @@ importers:
       '@mcaptcha/vanilla-glue':
         specifier: 0.1.0-alpha-3
         version: 0.1.0-alpha-3
+      '@mermaid-js/layout-elk':
+        specifier: 0.2.0
+        version: 0.2.0(mermaid@11.12.2)
       '@primer/octicons':
         specifier: 19.21.2
         version: 19.21.2
@@ -805,6 +808,11 @@ packages:
   '@mcaptcha/vanilla-glue@0.1.0-alpha-3':
     resolution: {integrity: sha512-GT6TJBgmViGXcXiT5VOr+h/6iOnThSlZuCoOWncubyTZU9R3cgU5vWPkF7G6Ob6ee2CBe3yqBxxk24CFVGTVXw==}
 
+  '@mermaid-js/layout-elk@0.2.0':
+    resolution: {integrity: sha512-vjjYGnCCjYlIA/rR7M//eFi0rHM6dsMyN1JQKfckpt30DTC/esrw36hcrvA2FNPHaqh3Q/SyBWzddyaky8EtUQ==}
+    peerDependencies:
+      mermaid: ^11.0.2
+
   '@mermaid-js/parser@0.6.3':
     resolution: {integrity: sha512-lnjOhe7zyHjc+If7yT4zoedx2vo4sHaTmtkl1+or8BRTnCtDmcTpAjpzDSfCZrshM5bCoz0GyidzadJAH1xobA==}
 
@@ -2257,6 +2265,9 @@ packages:
   electron-to-chromium@1.5.283:
     resolution: {integrity: sha512-3vifjt1HgrGW/h76UEeny+adYApveS9dH2h3p57JYzBSXJIKUJAvtmIytDKjcSCt9xHfrNCFJ7gts6vkhuq++w==}
 
+  elkjs@0.9.3:
+    resolution: {integrity: sha512-f/ZeWvW/BCXbhGEf1Ujp29EASo/lk1FDnETgNKwJrsVvGZhUWCZyg3xLJjAsxfOmt8KjswHmI5EwCQcPMpOYhQ==}
+
   emoji-regex@10.6.0:
     resolution: {integrity: sha512-toUI84YS5YmxW219erniWD0CIVOo46xGKColeNQRgOzDorgBi1v4D71/OFzgD9GO2UGKIv1C3Sp8DAn0+j5w7A==}
 
@@ -4744,6 +4755,12 @@ snapshots:
     dependencies:
       '@mcaptcha/core-glue': 0.1.0-alpha-5
 
+  '@mermaid-js/layout-elk@0.2.0(mermaid@11.12.2)':
+    dependencies:
+      d3: 7.9.0
+      elkjs: 0.9.3
+      mermaid: 11.12.2
+
   '@mermaid-js/parser@0.6.3':
     dependencies:
       langium: 3.3.1
@@ -6172,6 +6189,8 @@ snapshots:
 
   electron-to-chromium@1.5.283: {}
 
+  elkjs@0.9.3: {}
+
   emoji-regex@10.6.0: {}
 
   emoji-regex@8.0.0: {}

web_src/js/markup/mermaid.test.ts

@@ -0,0 +1,59 @@
+import {sourcesContainElk} from './mermaid.ts';
+import {dedent} from '../utils/testhelper.ts';
+
+test('sourcesContainElk', () => {
+  expect(sourcesContainElk([dedent(`
+    flowchart TB
+      elk --> B
+  `)])).toEqual(false);
+
+  expect(sourcesContainElk([dedent(`
+    ---
+    config:
+      layout : elk
+    ---
+    flowchart TB
+      A --> B
+  `)])).toEqual(true);
+
+  expect(sourcesContainElk([dedent(`
+    ---
+    config:
+      layout: elk.layered
+    ---
+    flowchart TB
+      A --> B
+  `)])).toEqual(true);
+
+  expect(sourcesContainElk([`
+    %%{ init : { "flowchart": { "defaultRenderer": "elk" } } }%%
+    flowchart TB
+      A --> B
+  `])).toEqual(true);
+
+  expect(sourcesContainElk([`
+    ---
+    config:
+      layout: 123
+    ---
+    %%{ init : { "class": { "defaultRenderer": "elk.any" } } }%%
+    flowchart TB
+      A --> B
+  `])).toEqual(true);
+
+  expect(sourcesContainElk([`
+    %%{init:{
+        "layout" : "elk.layered"
+    }}%%
+    flowchart TB
+      A --> B
+  `])).toEqual(true);
+
+  expect(sourcesContainElk([`
+    %%{ initialize: {
+        'layout' : 'elk.layered'
+    }}%%
+    flowchart TB
+      A --> B
+  `])).toEqual(true);
+});

web_src/js/markup/mermaid.ts

@@ -3,6 +3,8 @@ import {makeCodeCopyButton} from './codecopy.ts';
 import {displayError} from './common.ts';
 import {queryElems} from '../utils/dom.ts';
 import {html, htmlRaw} from '../utils/html.ts';
+import {load as loadYaml} from 'js-yaml';
+import type {MermaidConfig} from 'mermaid';
 
 const {mermaidMaxSourceCharacters} = window.config;
 
@@ -10,23 +12,111 @@ const iframeCss = `:root {color-scheme: normal}
 body {margin: 0; padding: 0; overflow: hidden}
 #mermaid {display: block; margin: 0 auto}`;
 
+function isSourceTooLarge(source: string) {
+  return mermaidMaxSourceCharacters >= 0 && source.length > mermaidMaxSourceCharacters;
+}
+
+function parseYamlInitConfig(source: string): MermaidConfig | null {
+  // ref: https://github.com/mermaid-js/mermaid/blob/develop/packages/mermaid/src/diagram-api/regexes.ts
+  const yamlFrontMatterRegex = /^---\s*[\n\r](.*?)[\n\r]---\s*[\n\r]+/s;
+  const frontmatter = (yamlFrontMatterRegex.exec(source) || [])[1];
+  if (!frontmatter) return null;
+  try {
+    return (loadYaml(frontmatter) as {config: MermaidConfig})?.config;
+  } catch {
+    console.error('invalid or unsupported mermaid init YAML config', frontmatter);
+  }
+  return null;
+}
+
+function parseJsonInitConfig(source: string): MermaidConfig | null {
+  // https://mermaid.js.org/config/directives.html#declaring-directives
+  // Do as dirty as mermaid does: https://github.com/mermaid-js/mermaid/blob/develop/packages/mermaid/src/utils.ts
+  // It can even accept invalid JSON string like:
+  // %%{initialize: { 'logLevel': 'fatal', "theme":'dark', 'startOnLoad': true } }%%
+  const jsonInitConfigRegex = /%%\{\s*(init|initialize)\s*:\s*(.*?)\}%%/s;
+  const jsonInitText = (jsonInitConfigRegex.exec(source) || [])[2];
+  if (!jsonInitText) return null;
+  try {
+    const processed = jsonInitText.trim().replace(/'/g, '"');
+    return JSON.parse(processed);
+  } catch {
+    console.error('invalid or unsupported mermaid init JSON config', jsonInitText);
+  }
+  return null;
+}
+
+function configValueIsElk(layoutOrRenderer: string | undefined) {
+  if (typeof layoutOrRenderer !== 'string') return false;
+  return layoutOrRenderer === 'elk' || layoutOrRenderer.startsWith('elk.');
+}
+
+function configContainsElk(config: MermaidConfig | null) {
+  if (!config) return false;
+  // Check the layout from the following properties:
+  // * config.layout
+  // * config.{any-diagram-config}.defaultRenderer
+  //   Although only a few diagram types like "flowchart" support "defaultRenderer",
+  //   as long as there is no side effect, here do a general check for all properties of "config", for ease of maintenance
+  return configValueIsElk(config.layout) || Object.values(config).some((value) => configValueIsElk(value?.defaultRenderer));
+}
+
+/** detect whether mermaid sources contain elk layout configuration */
+export function sourcesContainElk(sources: Array<string>) {
+  for (const source of sources) {
+    if (isSourceTooLarge(source)) continue;
+
+    const yamlConfig = parseYamlInitConfig(source);
+    if (configContainsElk(yamlConfig)) return true;
+
+    const jsonConfig = parseJsonInitConfig(source);
+    if (configContainsElk(jsonConfig)) return true;
+  }
+
+  return false;
+}
+
+async function loadMermaid(sources: Array<string>) {
+  const mermaidPromise = import(/* webpackChunkName: "mermaid" */'mermaid');
+  const elkPromise = sourcesContainElk(sources) ?
+    import(/* webpackChunkName: "mermaid-layout-elk" */'@mermaid-js/layout-elk') : null;
+
+  const results = await Promise.all([mermaidPromise, elkPromise]);
+  return {
+    mermaid: results[0].default,
+    elkLayouts: results[1]?.default,
+  };
+}
+
+let elkLayoutsRegistered = false;
+
 export async function initMarkupCodeMermaid(elMarkup: HTMLElement): Promise<void> {
   // .markup code.language-mermaid
-  queryElems(elMarkup, 'code.language-mermaid', async (el) => {
-    const {default: mermaid} = await import(/* webpackChunkName: "mermaid" */'mermaid');
+  const els = Array.from(queryElems(elMarkup, 'code.language-mermaid'));
+  if (!els.length) return;
+  const sources = Array.from(els, (el) => el.textContent ?? '');
+  const {mermaid, elkLayouts} = await loadMermaid(sources);
 
-    mermaid.initialize({
-      startOnLoad: false,
-      theme: isDarkTheme() ? 'dark' : 'neutral',
-      securityLevel: 'strict',
-      suppressErrorRendering: true,
-    });
+  if (elkLayouts && !elkLayoutsRegistered) {
+    mermaid.registerLayoutLoaders(elkLayouts);
+    elkLayoutsRegistered = true;
+  }
+  mermaid.initialize({
+    startOnLoad: false,
+    theme: isDarkTheme() ? 'dark' : 'neutral',
+    securityLevel: 'strict',
+    suppressErrorRendering: true,
+  });
 
+  await Promise.all(els.map(async (el, index) => {
+    const source = sources[index];
     const pre = el.closest('pre');
-    if (!pre || pre.hasAttribute('data-render-done')) return;
 
-    const source = el.textContent;
-    if (mermaidMaxSourceCharacters >= 0 && source.length > mermaidMaxSourceCharacters) {
+    if (!pre || pre.hasAttribute('data-render-done')) {
+      return;
+    }
+
+    if (isSourceTooLarge(source)) {
       displayError(pre, new Error(`Mermaid source of ${source.length} characters exceeds the maximum allowed length of ${mermaidMaxSourceCharacters}.`));
       return;
     }
@@ -83,5 +173,5 @@ export async function initMarkupCodeMermaid(elMarkup: HTMLElement): Promise<void
     } catch (err) {
       displayError(pre, err);
     }
-  });
+  }));
 }

web_src/js/utils/testhelper.ts

@@ -4,3 +4,19 @@
 export function isInFrontendUnitTest() {
   return import.meta.env.TEST === 'true';
 }
+
+/** strip common indentation from a string and trim it */
+export function dedent(str: string) {
+  const match = str.match(/^[ \t]*(?=\S)/gm);
+  if (!match) return str;
+
+  let minIndent = Number.POSITIVE_INFINITY;
+  for (const indent of match) {
+    minIndent = Math.min(minIndent, indent.length);
+  }
+  if (minIndent === 0 || minIndent === Number.POSITIVE_INFINITY) {
+    return str;
+  }
+
+  return str.replace(new RegExp(`^[ \\t]{${minIndent}}`, 'gm'), '').trim();
+}