Merge branch 'develop' into fix/maps

.gitignore

@@ -48,6 +48,7 @@ demos/dev/**
 !/demos/dev/example.html
 !/demos/dev/reload.js
 tsx-0/**
+vite.config.ts.timestamp-*
 
 # autogenereated by langium-cli
 generated/

docs/config/math.md

@@ -84,3 +84,13 @@ Example with legacy mode enabled (the latest version of KaTeX's stylesheet can b
   </body>
 </html>
 ```
+
+## Handling Rendering Differences
+
+Due to differences between default fonts across operating systems and browser's MathML implementations, inconsistent results can be seen across platforms. If having consistent results are important, or the most optimal rendered results are desired, `forceLegacyMathML` can be enabled in the config.
+
+This option will always use KaTeX's stylesheet instead of only when MathML is not supported (as with `legacyMathML`). Note that only `forceLegacyMathML` needs to be set.
+
+If including KaTeX's stylesheet is not a concern, enabling this option is recommended to avoid scenarios where no MathML implementation within a browser provides the desired output (as seen below).
+
+![Image showing differences between Browsers](img/mathMLDifferences.png)

docs/ecosystem/integrations-community.md

@@ -240,6 +240,8 @@ Communication tools and platforms
 
 ### Other
 
+- [Astro](https://astro.build/)
+  - [Adding diagrams to your Astro site with MermaidJS and Playwright](https://agramont.net/blog/diagraming-with-mermaidjs-astro/)
 - [Bisheng](https://www.npmjs.com/package/bisheng)
   - [bisheng-plugin-mermaid](https://github.com/yct21/bisheng-plugin-mermaid)
 - [Blazorade Mermaid: Render Mermaid diagrams in Blazor applications](https://github.com/Blazorade/Blazorade-Mermaid/wiki)
@@ -249,6 +251,7 @@ Communication tools and platforms
 - [Jekyll](https://jekyllrb.com/)
   - [jekyll-mermaid](https://rubygems.org/gems/jekyll-mermaid)
   - [jekyll-mermaid-diagrams](https://github.com/fuzhibo/jekyll-mermaid-diagrams)
+- [MarkChart: Preview Mermaid diagrams on macOS](https://markchart.app/)
 - [mermaid-isomorphic](https://github.com/remcohaszing/mermaid-isomorphic)
 - [mermaid-server: Generate diagrams using a HTTP request](https://github.com/TomWright/mermaid-server)
 - [NiceGUI: Let any browser be the frontend of your Python code](https://nicegui.io) ✅

package.json

@@ -4,7 +4,7 @@
   "version": "10.2.4",
   "description": "Markdownish syntax for generating flowcharts, sequence diagrams, class diagrams, gantt charts and git graphs.",
   "type": "module",
-  "packageManager": "pnpm@8.15.7",
+  "packageManager": "pnpm@8.15.8",
   "keywords": [
     "diagram",
     "markdown",
@@ -19,7 +19,7 @@
     "build:esbuild": "pnpm run -r clean && tsx .esbuild/build.ts",
     "build:mermaid": "pnpm build:esbuild --mermaid",
     "build:viz": "pnpm build:esbuild --visualize",
-    "build:types": "tsx .build/types.ts",
+    "build:types": "pnpm --filter mermaid types:build-config && tsx .build/types.ts",
     "build:types:watch": "tsc -p ./packages/mermaid/tsconfig.json --emitDeclarationOnly --watch",
     "dev": "tsx .esbuild/server.ts",
     "dev:vite": "tsx .vite/server.ts",
@@ -107,7 +107,7 @@
     "jison": "^0.4.18",
     "js-yaml": "^4.1.0",
     "jsdom": "^24.0.0",
-    "langium-cli": "3.0.1",
+    "langium-cli": "3.0.3",
     "lint-staged": "^15.2.2",
     "markdown-table": "^3.0.3",
     "nyc": "^15.1.0",

packages/mermaid/scripts/create-types-from-json-schema.mts

@@ -10,18 +10,16 @@
 
 /* eslint-disable no-console */
 
-import { readFile, writeFile } from 'node:fs/promises';
-import { join } from 'node:path';
+import _Ajv2019, { type JSONSchemaType } from 'ajv/dist/2019.js';
+import { JSON_SCHEMA, load } from 'js-yaml';
+import { compile, type JSONSchema } from 'json-schema-to-typescript';
 import assert from 'node:assert';
 import { execFile } from 'node:child_process';
+import { readFile, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
 import { promisify } from 'node:util';
-
-import { load, JSON_SCHEMA } from 'js-yaml';
-import { compile, type JSONSchema } from 'json-schema-to-typescript';
 import prettier from 'prettier';
 
-import _Ajv2019, { type JSONSchemaType } from 'ajv/dist/2019.js';
-
 // Workaround for wrong AJV types, see
 // https://github.com/ajv-validator/ajv/issues/2132#issuecomment-1290409907
 const Ajv2019 = _Ajv2019 as unknown as typeof _Ajv2019.default;
@@ -34,28 +32,6 @@ const verifyOnly = process.argv.includes('--verify');
 /** If `true`, automatically `git add` any changes (i.e. during `pnpm run pre-commit`)*/
 const git = process.argv.includes('--git');
 
-/**
- * All of the keys in the mermaid config that have a mermaid diagram config.
- */
-const MERMAID_CONFIG_DIAGRAM_KEYS = [
-  'flowchart',
-  'sequence',
-  'gantt',
-  'journey',
-  'class',
-  'state',
-  'er',
-  'pie',
-  'quadrantChart',
-  'xyChart',
-  'requirement',
-  'mindmap',
-  'timeline',
-  'gitGraph',
-  'c4',
-  'sankey',
-];
-
 /**
  * Loads the MermaidConfig JSON schema YAML file.
  *
@@ -148,53 +124,9 @@ async function generateTypescript(mermaidConfigSchema: JSONSchemaType<MermaidCon
     return { ...schema, required: [] };
   }
 
-  /**
-   * This is a temporary hack to control the order the types are generated in.
-   *
-   * By default, json-schema-to-typescript outputs the $defs in the order they
-   * are used, then any unused schemas at the end.
-   *
-   * **The only purpose of this function is to make the `git diff` simpler**
-   * **We should remove this later to simplify the code**
-   *
-   * @todo TODO: Remove this function in a future PR.
-   * @param schema - The input schema.
-   * @returns The schema with all `$ref`s removed.
-   */
-  function unrefSubschemas(schema: JSONSchemaType<Record<string, any>>) {
-    return {
-      ...schema,
-      properties: Object.fromEntries(
-        Object.entries(schema.properties).map(([key, propertySchema]) => {
-          if (MERMAID_CONFIG_DIAGRAM_KEYS.includes(key)) {
-            const { $ref, ...propertySchemaWithoutRef } = propertySchema as JSONSchemaType<unknown>;
-            if ($ref === undefined) {
-              throw Error(
-                `subSchema ${key} is in MERMAID_CONFIG_DIAGRAM_KEYS but does not have a $ref field`
-              );
-            }
-            const [
-              _root, // eslint-disable-line @typescript-eslint/no-unused-vars
-              _defs, // eslint-disable-line @typescript-eslint/no-unused-vars
-              defName,
-            ] = $ref.split('/');
-            return [
-              key,
-              {
-                ...propertySchemaWithoutRef,
-                tsType: defName,
-              },
-            ];
-          }
-          return [key, propertySchema];
-        })
-      ),
-    };
-  }
-
   assert.ok(mermaidConfigSchema.$defs);
   const modifiedSchema = {
-    ...unrefSubschemas(removeRequired(mermaidConfigSchema)),
+    ...removeRequired(mermaidConfigSchema),
 
     $defs: Object.fromEntries(
       Object.entries(mermaidConfigSchema.$defs).map(([key, subSchema]) => {

packages/mermaid/src/diagrams/class/classRenderer-v2.ts

@@ -4,7 +4,7 @@ import * as graphlib from 'dagre-d3-es/src/graphlib/index.js';
 import { log } from '../../logger.js';
 import { getConfig } from '../../diagram-api/diagramAPI.js';
 import { render } from '../../dagre-wrapper/index.js';
-import utils from '../../utils.js';
+import utils, { getEdgeId } from '../../utils.js';
 import { interpolateToCurve, getStylesFromArray } from '../../utils.js';
 import { setupGraphViewbox } from '../../setupGraphViewbox.js';
 import common from '../common/common.js';
@@ -231,7 +231,10 @@ export const addRelations = function (relations: ClassRelation[], g: graphlib.Gr
       //Set relationship style and line type
       classes: 'relation',
       pattern: edge.relation.lineType == 1 ? 'dashed' : 'solid',
-      id: `id_${edge.id1}_${edge.id2}_${cnt}`,
+      id: getEdgeId(edge.id1, edge.id2, {
+        prefix: 'id',
+        counter: cnt,
+      }),
       // Set link type for rendering
       arrowhead: edge.type === 'arrow_open' ? 'none' : 'normal',
       //Set edge extra labels

packages/mermaid/src/diagrams/common/common.ts

@@ -337,18 +337,20 @@ export const renderKatex = async (text: string, config: MermaidConfig): Promise<
     return text;
   }
 
-  if (!isMathMLSupported() && !config.legacyMathML) {
+  if (!(isMathMLSupported() || config.legacyMathML || config.forceLegacyMathML)) {
     return text.replace(katexRegex, 'MathML is unsupported in this environment.');
   }
 
   const { default: katex } = await import('katex');
+  const outputMode =
+    config.forceLegacyMathML || (!isMathMLSupported() && config.legacyMathML)
+      ? 'htmlAndMathml'
+      : 'mathml';
   return text
     .split(lineBreakRegex)
     .map((line) =>
       hasKatex(line)
-        ? `<div style="display: flex; align-items: center; justify-content: center; white-space: nowrap;">
-              ${line}
-            </div>`
+        ? `<div style="display: flex; align-items: center; justify-content: center; white-space: nowrap;">${line}</div>`
         : `<div>${line}</div>`
     )
     .join('')
@@ -357,7 +359,7 @@ export const renderKatex = async (text: string, config: MermaidConfig): Promise<
         .renderToString(c, {
           throwOnError: true,
           displayMode: true,
-          output: isMathMLSupported() ? 'mathml' : 'htmlAndMathml',
+          output: outputMode,
         })
         .replace(/\n/g, ' ')
         .replace(/<annotation.*<\/annotation>/g, '')

packages/mermaid/src/diagrams/flowchart/flowRenderer-v2.js

@@ -1,7 +1,7 @@
 import * as graphlib from 'dagre-d3-es/src/graphlib/index.js';
 import { select, curveLinear, selectAll } from 'd3';
 import { getConfig } from '../../diagram-api/diagramAPI.js';
-import utils from '../../utils.js';
+import utils, { getEdgeId } from '../../utils.js';
 import { render } from '../../dagre-wrapper/index.js';
 import { addHtmlLabel } from 'dagre-d3-es/src/dagre-js/label/add-html-label.js';
 import { log } from '../../logger.js';
@@ -210,7 +210,11 @@ export const addEdges = async function (edges, g, diagObj) {
     cnt++;
 
     // Identify Link
-    const linkIdBase = 'L-' + edge.start + '-' + edge.end;
+    const linkIdBase = getEdgeId(edge.start, edge.end, {
+      counter: cnt,
+      prefix: 'L',
+    });
+
     // count the links from+to the same node to give unique id
     if (linkIdCnt[linkIdBase] === undefined) {
       linkIdCnt[linkIdBase] = 0;
@@ -219,7 +223,8 @@ export const addEdges = async function (edges, g, diagObj) {
       linkIdCnt[linkIdBase]++;
       log.info('abc78 new entry', linkIdBase, linkIdCnt[linkIdBase]);
     }
-    let linkId = linkIdBase + '-' + linkIdCnt[linkIdBase];
+    let linkId = `${linkIdBase}_${linkIdCnt[linkIdBase]}`;
+
     log.info('abc78 new link id to be used is', linkIdBase, linkId, linkIdCnt[linkIdBase]);
     const linkNameStart = 'LS-' + edge.start;
     const linkNameEnd = 'LE-' + edge.end;

packages/mermaid/src/diagrams/flowchart/flowRenderer.js

@@ -6,7 +6,7 @@ import { applyStyle } from 'dagre-d3-es/src/dagre-js/util.js';
 import { addHtmlLabel } from 'dagre-d3-es/src/dagre-js/label/add-html-label.js';
 import { log } from '../../logger.js';
 import common, { evaluate, renderKatex } from '../common/common.js';
-import { interpolateToCurve, getStylesFromArray } from '../../utils.js';
+import { interpolateToCurve, getStylesFromArray, getEdgeId } from '../../utils.js';
 import { setupGraphViewbox } from '../../setupGraphViewbox.js';
 import flowChartShapes from './flowChartShapes.js';
 import { replaceIconSubstring } from '../../rendering-util/createText.js';
@@ -175,7 +175,10 @@ export const addEdges = async function (edges, g, diagObj) {
     cnt++;
 
     // Identify Link
-    const linkId = 'L-' + edge.start + '-' + edge.end;
+    const linkId = getEdgeId(edge.start, edge.end, {
+      counter: cnt,
+      prefix: 'L',
+    });
     const linkNameStart = 'LS-' + edge.start;
     const linkNameEnd = 'LE-' + edge.end;
 

packages/mermaid/src/diagrams/state/stateRenderer-v2.js

@@ -5,7 +5,7 @@ import { render } from '../../dagre-wrapper/index.js';
 import { log } from '../../logger.js';
 import { configureSvgSize } from '../../setupGraphViewbox.js';
 import common from '../common/common.js';
-import utils from '../../utils.js';
+import utils, { getEdgeId } from '../../utils.js';
 
 import {
   DEFAULT_DIAGRAM_DIRECTION,
@@ -252,7 +252,6 @@ const setupNode = (g, parent, parsedItem, diagramStates, diagramDb, altFlag) =>
         type: 'group',
         padding: 0, //getConfig().flowchart.padding
       };
-      graphItemCount++;
 
       const parentNodeId = itemId + PARENT_ID;
       g.setNode(parentNodeId, groupData);
@@ -270,17 +269,23 @@ const setupNode = (g, parent, parsedItem, diagramStates, diagramDb, altFlag) =>
         from = noteData.id;
         to = itemId;
       }
+
       g.setEdge(from, to, {
         arrowhead: 'none',
         arrowType: '',
         style: G_EDGE_STYLE,
         labelStyle: '',
+        id: getEdgeId(from, to, {
+          counter: graphItemCount,
+        }),
         classes: CSS_EDGE_NOTE_EDGE,
         arrowheadStyle: G_EDGE_ARROWHEADSTYLE,
         labelpos: G_EDGE_LABELPOS,
         labelType: G_EDGE_LABELTYPE,
         thickness: G_EDGE_THICKNESS,
       });
+
+      graphItemCount++;
     } else {
       g.setNode(itemId, nodeData);
     }
@@ -324,7 +329,9 @@ const setupDoc = (g, parentParsedItem, doc, diagramStates, diagramDb, altFlag) =
           setupNode(g, parentParsedItem, item.state1, diagramStates, diagramDb, altFlag);
           setupNode(g, parentParsedItem, item.state2, diagramStates, diagramDb, altFlag);
           const edgeData = {
-            id: 'edge' + graphItemCount,
+            id: getEdgeId(item.state1.id, item.state2.id, {
+              counter: graphItemCount,
+            }),
             arrowhead: 'normal',
             arrowTypeEnd: 'arrow_barb',
             style: G_EDGE_STYLE,

packages/mermaid/src/docs/config/math.md

@@ -60,3 +60,13 @@ Example with legacy mode enabled (the latest version of KaTeX's stylesheet can b
   </body>
 </html>
 ```
+
+## Handling Rendering Differences
+
+Due to differences between default fonts across operating systems and browser's MathML implementations, inconsistent results can be seen across platforms. If having consistent results are important, or the most optimal rendered results are desired, `forceLegacyMathML` can be enabled in the config.
+
+This option will always use KaTeX's stylesheet instead of only when MathML is not supported (as with `legacyMathML`). Note that only `forceLegacyMathML` needs to be set.
+
+If including KaTeX's stylesheet is not a concern, enabling this option is recommended to avoid scenarios where no MathML implementation within a browser provides the desired output (as seen below).
+
+![Image showing differences between Browsers](img/mathMLDifferences.png)

packages/mermaid/src/docs/ecosystem/integrations-community.md

@@ -235,6 +235,8 @@ Communication tools and platforms
 
 ### Other
 
+- [Astro](https://astro.build/)
+  - [Adding diagrams to your Astro site with MermaidJS and Playwright](https://agramont.net/blog/diagraming-with-mermaidjs-astro/)
 - [Bisheng](https://www.npmjs.com/package/bisheng)
   - [bisheng-plugin-mermaid](https://github.com/yct21/bisheng-plugin-mermaid)
 - [Blazorade Mermaid: Render Mermaid diagrams in Blazor applications](https://github.com/Blazorade/Blazorade-Mermaid/wiki)
@@ -244,6 +246,7 @@ Communication tools and platforms
 - [Jekyll](https://jekyllrb.com/)
   - [jekyll-mermaid](https://rubygems.org/gems/jekyll-mermaid)
   - [jekyll-mermaid-diagrams](https://github.com/fuzhibo/jekyll-mermaid-diagrams)
+- [MarkChart: Preview Mermaid diagrams on macOS](https://markchart.app/)
 - [mermaid-isomorphic](https://github.com/remcohaszing/mermaid-isomorphic)
 - [mermaid-server: Generate diagrams using a HTTP request](https://github.com/TomWright/mermaid-server)
 - [NiceGUI: Let any browser be the frontend of your Python code](https://nicegui.io) ✅

packages/mermaid/src/docs/package.json

@@ -34,7 +34,7 @@
     "unplugin-vue-components": "^0.26.0",
     "vite": "^5.0.0",
     "vite-plugin-pwa": "^0.19.7",
-    "vitepress": "1.1.0",
+    "vitepress": "1.1.4",
     "workbox-window": "^7.0.0"
   }
 }

packages/mermaid/src/schemas/config.schema.yaml

@@ -180,6 +180,13 @@ properties:
       fall back to legacy rendering for KaTeX.
     type: boolean
     default: false
+  forceLegacyMathML:
+    description: |
+      This option forces Mermaid to rely on KaTeX's own stylesheet for rendering MathML. Due to differences between OS 
+      fonts and browser's MathML implementation, this option is recommended if consistent rendering is important.
+      If set to true, ignores legacyMathML.
+    type: boolean
+    default: false
   deterministicIds:
     description: |
       This option controls if the generated ids of nodes in the SVG are

packages/mermaid/src/utils.ts

@@ -929,3 +929,19 @@ export const decodeEntities = function (text: string): string {
 export const isString = (value: unknown): value is string => {
   return typeof value === 'string';
 };
+
+export const getEdgeId = (
+  from: string,
+  to: string,
+  {
+    counter = 0,
+    prefix,
+    suffix,
+  }: {
+    counter?: number;
+    prefix?: string;
+    suffix?: string;
+  }
+) => {
+  return `${prefix ? `${prefix}_` : ''}${from}_${to}_${counter}${suffix ? `_${suffix}` : ''}`;
+};