Started railroad diagrams

2025-10-31 10:54:15 +01:00 · 2023-08-03 17:27:41 +03:00
14 changed files with 230 additions and 2 deletions
--- a/mocks/railroadRenderer.js
+++ b/mocks/railroadRenderer.js
@@ -0,0 +1,13 @@
+/**
+ * Mocked Railroad diagram renderer
+ */
+
+import { vi } from 'vitest';
+
+export const draw = vi.fn().mockImplementation(() => {
+  return '';
+});
+
+export default {
+  draw,
+};
--- a/cypress/integration/rendering/railroad.spec.ts
+++ b/cypress/integration/rendering/railroad.spec.ts
--- a/demos/index.html
+++ b/demos/index.html
@@ -7,7 +7,6 @@
    <link rel="icon" type="image/png" href="data:image/png;base64,iVBORw0KGgo=" />
    <style>
      div.mermaid {
-        /* font-family: 'trebuchet ms', verdana, arial; */
        font-family: 'Courier New', Courier, monospace !important;
      }
    </style>
@@ -78,6 +77,9 @@
      <li>
        <h2><a href="./sankey.html">Sankey</a></h2>
      </li>
+      <li>
+        <h2><a href="./railroad.html">Railroad</a></h2>
+      </li>
    </ul>
  </body>
 </html>
--- a/demos/railroad.html
+++ b/demos/railroad.html
@@ -0,0 +1,32 @@
+<!DOCTYPE html>
+<html lang="en" xmlns="http://www.w3.org/1999/html">
+  <head>
+    <meta charset="utf-8" />
+    <meta http-equiv="X-UA-Compatible" content="IE=edge" />
+    <title>Railroad Mermaid Quick Test Page</title>
+    <link rel="icon" type="image/png" href="data:image/png;base64,iVBORw0KGgo=" />
+    <style>
+      div.mermaid {
+        font-family: 'Courier New', Courier, monospace !important;
+      }
+    </style>
+  </head>
+
+  <body>
+    <h1>Railroad diagram demos</h1>
+    <h2>Example</h2>
+    <pre class="mermaid">
+      railroad-beta
+    </pre>
+
+    <script type="module">
+      import mermaid from './mermaid.esm.mjs';
+      mermaid.initialize({
+        theme: 'default',
+        logLevel: 3,
+        securityLevel: 'loose',
+        railroad: {},
+      });
+    </script>
+  </body>
+</html>
--- a/packages/mermaid/src/diagram-api/diagram-orchestration.ts
+++ b/packages/mermaid/src/diagram-api/diagram-orchestration.ts
@@ -21,6 +21,7 @@ import mindmap from '../diagrams/mindmap/detector.js';
 import sankey from '../diagrams/sankey/sankeyDetector.js';
 import { registerLazyLoadedDiagrams } from './detectType.js';
 import { registerDiagram } from './diagramAPI.js';
+import { railroad } from '../diagrams/railroad/railroadDetector.js';

 let hasLoadedDiagrams = false;
 export const addDiagrams = () => {
@@ -81,6 +82,7 @@ export const addDiagrams = () => {
    state,
    journey,
    quadrantChart,
-    sankey
+    sankey,
+    railroad
  );
 };
--- a/packages/mermaid/src/diagrams/railroad/railroadDB.ts
+++ b/packages/mermaid/src/diagrams/railroad/railroadDB.ts
@@ -0,0 +1,13 @@
+import type { RailroadDB } from './railroadTypes.js';
+
+import {
+  clear as commonClear,
+} from '../../commonDb.js';
+
+const clear = (): void => {
+  commonClear();
+};
+
+export const db: RailroadDB = {
+  clear,
+};
--- a/packages/mermaid/src/diagrams/railroad/railroadDetector.ts
+++ b/packages/mermaid/src/diagrams/railroad/railroadDetector.ts
@@ -0,0 +1,22 @@
+import type {
+  DiagramDetector,
+  DiagramLoader,
+  ExternalDiagramDefinition,
+} from '../../diagram-api/types.js';
+
+const id = 'railroad';
+
+const detector: DiagramDetector = (txt) => {
+  return /^\s*railroad-beta/.test(txt);
+};
+
+const loader: DiagramLoader = async () => {
+  const { diagram } = await import('./railroadDiagram.js');
+  return { id, diagram };
+};
+
+export const railroad: ExternalDiagramDefinition = {
+  id,
+  detector,
+  loader,
+};
--- a/packages/mermaid/src/diagrams/railroad/railroadDiagram.ts
+++ b/packages/mermaid/src/diagrams/railroad/railroadDiagram.ts
@@ -0,0 +1,15 @@
+import { DiagramDefinition } from '../../diagram-api/types.js';
+// @ts-ignore: jison doesn't export types
+import parser from './railroadParser.jison';
+import { db } from './railroadDB.js';
+import renderer from './railroadRenderer.js';
+// import { prepareTextForParsing } from './railroadUtils.js';
+
+// const originalParse = parser.parse.bind(parser);
+// parser.parse = (text: string) => originalParse(prepareTextForParsing(text));
+
+export const diagram: DiagramDefinition = {
+  parser,
+  db,
+  renderer,
+};
--- a/packages/mermaid/src/diagrams/railroad/railroadParser.jison
+++ b/packages/mermaid/src/diagrams/railroad/railroadParser.jison
@@ -0,0 +1,46 @@
+/*
+  Mermaid
+  https://mermaid.js.org/
+  MIT license.
+*/
+
+//------------------
+// Lexical analysis
+//------------------
+
+%lex
+
+// Pre lexer steps
+
+%{
+%}
+
+// Start conditions
+%x diagram
+
+// Definitions
+DIAGRAM_KEYWORD "railroad-beta"
+
+%%
+
+// Tokenization
+<INITIAL>DIAGRAM_KEYWORD       { this.pushState('diagram'); return 'DIAGRAM_KEYWORD'; }
+<INITIAL,diagram>\s+           {}
+<INITIAL,diagram><<EOF>>       { return 'EOF' } // match end of file
+
+/lex
+
+//-----------------
+// Syntax analysis
+//-----------------
+
+// Configuration
+
+%start start
+
+%%
+
+// Grammar
+
+start: DIAGRAM_KEYWORD EOF;
+
--- a/packages/mermaid/src/diagrams/railroad/railroadRenderer.ts
+++ b/packages/mermaid/src/diagrams/railroad/railroadRenderer.ts
@@ -0,0 +1,52 @@
+import { Diagram } from '../../Diagram.js';
+import * as configApi from '../../config.js';
+import type { DrawDefinition, HTML, SVG } from '../../diagram-api/types.js';
+import { select } from 'd3';
+// import { configureSvgSize } from '../../setupGraphViewbox.js';
+// import { Uid } from '../../rendering-util/uid.js';
+
+const fetchSVGElement = (id: string): SVG => {
+  // Get config
+  const { securityLevel } = configApi.getConfig();
+
+  // Handle root and document for when rendering in sandbox mode
+  let sandboxElement: HTML | undefined;
+  let document: Document | null | undefined;
+  if (securityLevel === 'sandbox') {
+    sandboxElement = select('#i' + id);
+    document = sandboxElement.nodes()[0].contentDocument;
+  }
+
+  // @ts-ignore - figure out how to assign HTML to document type
+  const root: HTML = (sandboxElement && document) ? select(document) : select('body');
+  const svg: SVG = root.select('#' + id);
+  return svg;
+}
+
+/**
+ * Draws Railroad diagram.
+ *
+ * @param text - The text of the diagram
+ * @param id - The id of the diagram which will be used as a DOM element id¨
+ * @param _version - Mermaid version from package.json
+ * @param diagObj - A standard diagram containing the db and the text and type etc of the diagram
+ */
+export const draw: DrawDefinition = (text: string, id: string, _version: string, diagObj: Diagram): void => {
+  const svg: SVG = fetchSVGElement(id);
+  
+  // const defaultRailroadConfig = configApi!.defaultConfig!.railroad!;
+  // Establish svg dimensions and get width and height
+  //
+  // const width = conf?.width || defaultRailroadConfig.width!;
+  // const height = conf?.height || defaultRailroadConfig.width!;
+  // const useMaxWidth = conf?.useMaxWidth || defaultRailroadConfig.useMaxWidth!;
+
+  // configureSvgSize(svg, height, width, useMaxWidth);
+
+  // Compute layout
+  // 
+};
+
+export default {
+  draw,
+};
--- a/packages/mermaid/src/diagrams/railroad/railroadTests.spec.ts
+++ b/packages/mermaid/src/diagrams/railroad/railroadTests.spec.ts
@@ -0,0 +1,25 @@
+// @ts-ignore: jison doesn't export types
+import railroad from './railroad.jison';
+// import { prepareTextForParsing } from '../railroadUtils.js';
+import * as fs from 'fs';
+import * as path from 'path';
+import { cleanupComments } from '../../diagram-api/comments.js';
+import { db } from './railroadDB.js';
+
+describe('Railroad diagram', function () {
+  describe('when parsing an info graph it', function () {
+    beforeEach(function () {
+      railroad.parser.yy = db;
+      railroad.parser.yy.clear();
+    });
+
+    it('parses csv', async () => {
+      const csv = path.resolve(__dirname, './energy.csv');
+      const data = fs.readFileSync(csv, 'utf8');
+      // const graphDefinition = prepareTextForParsing(cleanupComments('railroad-beta\n\n ' + data));
+      const graphDefinition = cleanupComments('railroad-beta\n\n ' + data);
+
+      railroad.parser.parse(graphDefinition);
+    });
+  });
+});
--- a/packages/mermaid/src/diagrams/railroad/railroadTypes.ts
+++ b/packages/mermaid/src/diagrams/railroad/railroadTypes.ts
@@ -0,0 +1,5 @@
+import type { DiagramDB } from '../../diagram-api/types.js';
+
+export interface RailroadDB extends DiagramDB {
+  clear: () => void;
+}
--- a/packages/mermaid/src/docs/.vitepress/config.ts
+++ b/packages/mermaid/src/docs/.vitepress/config.ts
@@ -144,6 +144,7 @@ function sidebarSyntax() {
        { text: 'Timeline 🔥', link: '/syntax/timeline' },
        { text: 'Zenuml 🔥', link: '/syntax/zenuml' },
        { text: 'Sankey 🔥', link: '/syntax/sankey' },
+        { text: 'Railroad 🔥', link: '/syntax/railroad' },
        { text: 'Other Examples', link: '/syntax/examples' },
      ],
    },
--- a/packages/mermaid/src/docs/syntax/railroad.md
+++ b/packages/mermaid/src/docs/syntax/railroad.md