From d72851bf51a4ef5c23242d1d1eae7f5e9fa62eb8 Mon Sep 17 00:00:00 2001
From: nimec01 <24428341+nimec01@users.noreply.github.com>
Date: Sat, 2 Nov 2024 15:55:51 +0100
Subject: [PATCH] add history node

---
 .cspell/mermaid-terms.txt                     |  1 +
 .../rendering/stateDiagram-v2.spec.js         | 70 +++++++++++++++++++
 demos/state.html                              | 31 ++++++++
 docs/syntax/flowchart.md                      |  2 +
 docs/syntax/stateDiagram.md                   | 62 ++++++++++++++++
 packages/mermaid/scripts/docs.spec.ts         |  2 +
 .../diagrams/state/parser/stateDiagram.jison  | 14 ++++
 packages/mermaid/src/diagrams/state/styles.js |  5 ++
 .../mermaid/src/docs/syntax/stateDiagram.md   | 33 +++++++++
 .../rendering-elements/shapes.ts              | 17 +++++
 .../rendering-elements/shapes/history.ts      | 61 ++++++++++++++++
 11 files changed, 298 insertions(+)
 create mode 100644 packages/mermaid/src/rendering-util/rendering-elements/shapes/history.ts

diff --git a/.cspell/mermaid-terms.txt b/.cspell/mermaid-terms.txt
index cb6db41dec..2d7d48d326 100644
--- a/.cspell/mermaid-terms.txt
+++ b/.cspell/mermaid-terms.txt
@@ -6,6 +6,7 @@ braintree
 catmull
 compositTitleSize
 curv
+deephistory
 doublecircle
 elems
 gantt
diff --git a/cypress/integration/rendering/stateDiagram-v2.spec.js b/cypress/integration/rendering/stateDiagram-v2.spec.js
index 606a1a3f57..810e9533c7 100644
--- a/cypress/integration/rendering/stateDiagram-v2.spec.js
+++ b/cypress/integration/rendering/stateDiagram-v2.spec.js
@@ -330,6 +330,76 @@ describe('State diagram', () => {
       }
     );
   });
+  it('v2 it should be possible to use a (deep) history node', () => {
+    imgSnapshotTest(
+      `
+  stateDiagram-v2
+      state "A" as A {
+        state "B" as B
+        state "C" as C
+        state A_History [[history]]
+
+        B --> C
+        C --> B
+      }
+      state "D" as D {
+        state "E" as E {
+          state "F" as F
+          state "G" as G
+
+          F --> G
+          G --> F
+        }
+        state "I" as I
+        state D_History [[deephistory]]
+
+        E --> I
+        I --> E
+      }
+
+      G --> A_History
+      A --> D_History
+    `,
+      {
+        logLevel: 0,
+      }
+    );
+  });
+  it('v2 it should be possible to use a (deep) history node shorthand', () => {
+    imgSnapshotTest(
+      `
+  stateDiagram-v2
+      state "A" as A {
+        state "B" as B
+        state "C" as C
+        state A_History [[H]]
+
+        B --> C
+        C --> B
+      }
+      state "D" as D {
+        state "E" as E {
+          state "F" as F
+          state "G" as G
+
+          F --> G
+          G --> F
+        }
+        state "I" as I
+        state D_History [[H*]]
+
+        E --> I
+        I --> E
+      }
+
+      G --> A_History
+      A --> D_History
+    `,
+      {
+        logLevel: 0,
+      }
+    );
+  });
   it('v2 A compound state should be able to link to itself', () => {
     imgSnapshotTest(
       `
diff --git a/demos/state.html b/demos/state.html
index aaa8e0aa99..c6d012458d 100644
--- a/demos/state.html
+++ b/demos/state.html
@@ -218,6 +218,37 @@ <h2>You can add Notes</h2>
     </pre>
     <hr />
 
+    <h2>You can add History nodes</h2>
+    <pre class="mermaid">
+    stateDiagram-v2
+      state "A" as A {
+        state "B" as B
+        state "C" as C
+        state A_History [[H]]
+
+        B --> C
+        C --> B
+      }
+      state "D" as D {
+        state "E" as E {
+          state "F" as F
+          state "G" as G
+
+          F --> G
+          G --> F
+        }
+        state "I" as I
+        state D_History [[H*]]
+
+        E --> I
+        I --> E
+      }
+
+      G --> A_History
+      A --> D_History
+    </pre>
+    <hr />
+
     <script type="module">
       import mermaid from './mermaid.esm.mjs';
       mermaid.initialize({
diff --git a/docs/syntax/flowchart.md b/docs/syntax/flowchart.md
index 3837e77de6..c2b8286a22 100644
--- a/docs/syntax/flowchart.md
+++ b/docs/syntax/flowchart.md
@@ -328,6 +328,7 @@ Below is a comprehensive list of the newly introduced shapes and their correspon
 | Data Input/Output                 | Lean Left              | `lean-l`       | Represents output or input     | `lean-left`, `out-in`                                            |
 | Database                          | Cylinder               | `cyl`          | Database storage               | `cylinder`, `database`, `db`                                     |
 | Decision                          | Diamond                | `diam`         | Decision-making step           | `decision`, `diamond`, `question`                                |
+| Deep History                      | Circle with an H\*     | `deephistory`  | Deep history entrance          | `H*`                                                             |
 | Delay                             | Half-Rounded Rectangle | `delay`        | Represents a delay             | `half-rounded-rectangle`                                         |
 | Direct Access Storage             | Horizontal Cylinder    | `h-cyl`        | Direct access storage          | `das`, `horizontal-cylinder`                                     |
 | Disk Storage                      | Lined Cylinder         | `lin-cyl`      | Disk storage                   | `disk`, `lined-cylinder`                                         |
@@ -337,6 +338,7 @@ Below is a comprehensive list of the newly introduced shapes and their correspon
 | Event                             | Rounded Rectangle      | `rounded`      | Represents an event            | `event`                                                          |
 | Extract                           | Triangle               | `tri`          | Extraction process             | `extract`, `triangle`                                            |
 | Fork/Join                         | Filled Rectangle       | `fork`         | Fork or join in process flow   | `join`                                                           |
+| History                           | Circle with an H       | `history`      | History entrance               | `H`                                                              |
 | Internal Storage                  | Window Pane            | `win-pane`     | Internal storage               | `internal-storage`, `window-pane`                                |
 | Junction                          | Filled Circle          | `f-circ`       | Junction point                 | `filled-circle`, `junction`                                      |
 | Lined Document                    | Lined Document         | `lin-doc`      | Lined document                 | `lined-document`                                                 |
diff --git a/docs/syntax/stateDiagram.md b/docs/syntax/stateDiagram.md
index e532678f0a..0fae3e2828 100644
--- a/docs/syntax/stateDiagram.md
+++ b/docs/syntax/stateDiagram.md
@@ -334,6 +334,68 @@ It is possible to specify a fork in the diagram using <\<fork>> <\<join>>.
       State4 --> [*]
 ```
 
+## History (v\<MERMAID_RELEASE_VERSION>+)
+
+It is possible to add (deep) history nodes in the diagram using <\<history>> <\<deephistory>> or their respective shorthand <\<H>> <\<H\*>>.
+
+```mermaid-example
+   stateDiagram-v2
+      state "A" as A {
+        state "B" as B
+        state "C" as C
+        state A_History <<history>>
+
+        B --> C
+        C --> B
+      }
+      state "D" as D {
+        state "E" as E {
+          state "F" as F
+          state "G" as G
+
+          F --> G
+          G --> F
+        }
+        state "I" as I
+        state D_History <<deephistory>>
+
+        E --> I
+        I --> E
+      }
+
+      G --> A_History
+      A --> D_History
+```
+
+```mermaid
+   stateDiagram-v2
+      state "A" as A {
+        state "B" as B
+        state "C" as C
+        state A_History <<history>>
+
+        B --> C
+        C --> B
+      }
+      state "D" as D {
+        state "E" as E {
+          state "F" as F
+          state "G" as G
+
+          F --> G
+          G --> F
+        }
+        state "I" as I
+        state D_History <<deephistory>>
+
+        E --> I
+        I --> E
+      }
+
+      G --> A_History
+      A --> D_History
+```
+
 ## Notes
 
 Sometimes nothing says it better than a Post-it note. That is also the case in state diagrams.
diff --git a/packages/mermaid/scripts/docs.spec.ts b/packages/mermaid/scripts/docs.spec.ts
index 68677d4c9c..01aa4b0cd0 100644
--- a/packages/mermaid/scripts/docs.spec.ts
+++ b/packages/mermaid/scripts/docs.spec.ts
@@ -181,6 +181,7 @@ This Markdown should be kept.
         | Data Input/Output                 | Lean Left              | \`lean-l\`       | Represents output or input     | \`lean-left\`, \`out-in\`                                            |
         | Database                          | Cylinder               | \`cyl\`          | Database storage               | \`cylinder\`, \`database\`, \`db\`                                     |
         | Decision                          | Diamond                | \`diam\`         | Decision-making step           | \`decision\`, \`diamond\`, \`question\`                                |
+        | Deep History                      | Circle with an H\\*     | \`deephistory\`  | Deep history entrance          | \`H*\`                                                             |
         | Delay                             | Half-Rounded Rectangle | \`delay\`        | Represents a delay             | \`half-rounded-rectangle\`                                         |
         | Direct Access Storage             | Horizontal Cylinder    | \`h-cyl\`        | Direct access storage          | \`das\`, \`horizontal-cylinder\`                                     |
         | Disk Storage                      | Lined Cylinder         | \`lin-cyl\`      | Disk storage                   | \`disk\`, \`lined-cylinder\`                                         |
@@ -190,6 +191,7 @@ This Markdown should be kept.
         | Event                             | Rounded Rectangle      | \`rounded\`      | Represents an event            | \`event\`                                                          |
         | Extract                           | Triangle               | \`tri\`          | Extraction process             | \`extract\`, \`triangle\`                                            |
         | Fork/Join                         | Filled Rectangle       | \`fork\`         | Fork or join in process flow   | \`join\`                                                           |
+        | History                           | Circle with an H       | \`history\`      | History entrance               | \`H\`                                                              |
         | Internal Storage                  | Window Pane            | \`win-pane\`     | Internal storage               | \`internal-storage\`, \`window-pane\`                                |
         | Junction                          | Filled Circle          | \`f-circ\`       | Junction point                 | \`filled-circle\`, \`junction\`                                      |
         | Lined Document                    | Lined Document         | \`lin-doc\`      | Lined document                 | \`lined-document\`                                                 |
diff --git a/packages/mermaid/src/diagrams/state/parser/stateDiagram.jison b/packages/mermaid/src/diagrams/state/parser/stateDiagram.jison
index e3bc512352..9ec0acb17e 100644
--- a/packages/mermaid/src/diagrams/state/parser/stateDiagram.jison
+++ b/packages/mermaid/src/diagrams/state/parser/stateDiagram.jison
@@ -92,9 +92,17 @@ accDescr\s*"{"\s*                                { this.begin("acc_descr_multili
 
 <INITIAL,struct>"state"\s+  { /* console.log('Starting STATE '); */ this.pushState('STATE'); }
 
+<STATE>.*"<<H>>"                      {this.popState();yytext=yytext.slice(0,-5).trim(); /*console.warn('History: ',yytext);*/return 'HISTORY';}
+<STATE>.*"<<H*>>"                     {this.popState();yytext=yytext.slice(0,-6).trim(); /*console.warn('History: ',yytext);*/return 'DEEPHISTORY';}
+<STATE>.*"<<history>>"                {this.popState();yytext=yytext.slice(0,-11).trim(); /*console.warn('History: ',yytext);*/return 'HISTORY';}
+<STATE>.*"<<deephistory>>"            {this.popState();yytext=yytext.slice(0,-15).trim(); /*console.warn('Deep History: ',yytext);*/return 'DEEPHISTORY';}
 <STATE>.*"<<fork>>"                   {this.popState();yytext=yytext.slice(0,-8).trim(); /*console.warn('Fork Fork: ',yytext);*/return 'FORK';}
 <STATE>.*"<<join>>"                   {this.popState();yytext=yytext.slice(0,-8).trim();/*console.warn('Fork Join: ',yytext);*/return 'JOIN';}
 <STATE>.*"<<choice>>"                 {this.popState();yytext=yytext.slice(0,-10).trim();/*console.warn('Fork Join: ',yytext);*/return 'CHOICE';}
+<STATE>.*"[[H]]"                      {this.popState();yytext=yytext.slice(0,-5).trim(); /*console.warn('History: ',yytext);*/return 'HISTORY';}
+<STATE>.*"[[H*]]"                     {this.popState();yytext=yytext.slice(0,-6).trim(); /*console.warn('History: ',yytext);*/return 'DEEPHISTORY';}
+<STATE>.*"[[history]]"                {this.popState();yytext=yytext.slice(0,-11).trim(); /*console.warn('History: ',yytext);*/return 'HISTORY';}
+<STATE>.*"[[deephistory]]"            {this.popState();yytext=yytext.slice(0,-15).trim(); /*console.warn('Deep History: ',yytext);*/return 'DEEPHISTORY';}
 <STATE>.*"[[fork]]"                   {this.popState();yytext=yytext.slice(0,-8).trim();/*console.warn('Fork Fork: ',yytext);*/return 'FORK';}
 <STATE>.*"[[join]]"                   {this.popState();yytext=yytext.slice(0,-8).trim();/*console.warn('Fork Join: ',yytext);*/return 'JOIN';}
 <STATE>.*"[[choice]]"                 {this.popState();yytext=yytext.slice(0,-10).trim();/*console.warn('Fork Join: ',yytext);*/return 'CHOICE';}
@@ -237,6 +245,12 @@ statement
     | CONCURRENT {
         $$={ stmt: 'state', id: yy.getDividerId(), type: 'divider' }
     }
+    | HISTORY {
+        $$={ stmt: 'state', id: $1, type: 'history' }
+    }
+    | DEEPHISTORY {
+        $$={ stmt: 'state', id: $1, type: 'deephistory' }
+    }
     | note notePosition ID NOTE_TEXT
     {
         /* console.warn('got NOTE, position: ', $2.trim(), 'id = ', $3.trim(), 'note: ', $4);*/
diff --git a/packages/mermaid/src/diagrams/state/styles.js b/packages/mermaid/src/diagrams/state/styles.js
index 05d530ee36..ae0c91dfc4 100644
--- a/packages/mermaid/src/diagrams/state/styles.js
+++ b/packages/mermaid/src/diagrams/state/styles.js
@@ -103,6 +103,11 @@ g.stateGroup line {
   stroke: ${options.specialStateColor};
 }
 
+.node .history {
+  fill: ${options.background};
+  stroke: ${options.specialStateColor};
+}
+
 .node circle.state-end {
   fill: ${options.innerEndBackground};
   stroke: ${options.background};
diff --git a/packages/mermaid/src/docs/syntax/stateDiagram.md b/packages/mermaid/src/docs/syntax/stateDiagram.md
index 9d99ab93b9..c31510e86b 100644
--- a/packages/mermaid/src/docs/syntax/stateDiagram.md
+++ b/packages/mermaid/src/docs/syntax/stateDiagram.md
@@ -193,6 +193,39 @@ It is possible to specify a fork in the diagram using &lt;&lt;fork&gt;&gt; &lt;&
       State4 --> [*]
 ```
 
+## History (v<MERMAID_RELEASE_VERSION>+)
+
+It is possible to add (deep) history nodes in the diagram using &lt;&lt;history&gt;&gt; &lt;&lt;deephistory&gt;&gt; or their respective shorthand &lt;&lt;H&gt;&gt; &lt;&lt;H\*&gt;&gt;.
+
+```mermaid-example
+   stateDiagram-v2
+      state "A" as A {
+        state "B" as B
+        state "C" as C
+        state A_History <<history>>
+
+        B --> C
+        C --> B
+      }
+      state "D" as D {
+        state "E" as E {
+          state "F" as F
+          state "G" as G
+
+          F --> G
+          G --> F
+        }
+        state "I" as I
+        state D_History <<deephistory>>
+
+        E --> I
+        I --> E
+      }
+
+      G --> A_History
+      A --> D_History
+```
+
 ## Notes
 
 Sometimes nothing says it better than a Post-it note. That is also the case in state diagrams.
diff --git a/packages/mermaid/src/rendering-util/rendering-elements/shapes.ts b/packages/mermaid/src/rendering-util/rendering-elements/shapes.ts
index dbfc93677f..0821ff0166 100644
--- a/packages/mermaid/src/rendering-util/rendering-elements/shapes.ts
+++ b/packages/mermaid/src/rendering-util/rendering-elements/shapes.ts
@@ -59,6 +59,7 @@ import { waveRectangle } from './shapes/waveRectangle.js';
 import { windowPane } from './shapes/windowPane.js';
 import { classBox } from './shapes/classBox.js';
 import { kanbanItem } from './shapes/kanbanItem.js';
+import { history, deephistory } from './shapes/history.js';
 
 type ShapeHandler = <T extends SVGGraphicsElement>(
   parent: D3Selection<T>,
@@ -243,6 +244,22 @@ export const shapesDefs = [
     internalAliases: ['forkJoin'],
     handler: forkJoin,
   },
+  {
+    semanticName: 'History',
+    name: 'Circle with an H',
+    shortName: 'history',
+    description: 'History entrance',
+    aliases: ['H'],
+    handler: history,
+  },
+  {
+    semanticName: 'Deep History',
+    name: 'Circle with an H*',
+    shortName: 'deephistory',
+    description: 'Deep history entrance',
+    aliases: ['H*'],
+    handler: deephistory,
+  },
   {
     semanticName: 'Collate',
     name: 'Hourglass',
diff --git a/packages/mermaid/src/rendering-util/rendering-elements/shapes/history.ts b/packages/mermaid/src/rendering-util/rendering-elements/shapes/history.ts
new file mode 100644
index 0000000000..7e9e7a56aa
--- /dev/null
+++ b/packages/mermaid/src/rendering-util/rendering-elements/shapes/history.ts
@@ -0,0 +1,61 @@
+import { labelHelper, updateNodeBounds, getNodeClasses } from './util.js';
+import intersect from '../intersect/index.js';
+import type { Node } from '../../types.js';
+import { styles2String, userNodeOverrides } from './handDrawnShapeStyles.js';
+import rough from 'roughjs';
+import type { D3Selection } from '../../../types.js';
+import { handleUndefinedAttr } from '../../../utils.js';
+
+export async function historyBase<T extends SVGGraphicsElement>(
+  parent: D3Selection<T>,
+  node: Node
+) {
+  const { labelStyles, nodeStyles } = styles2String(node);
+  node.labelStyle = labelStyles;
+  const { shapeSvg } = await labelHelper(parent, node, getNodeClasses(node));
+
+  const radius = 16;
+  let circleElem;
+  const { cssStyles } = node;
+
+  if (node.look === 'handDrawn') {
+    // @ts-expect-error -- Passing a D3.Selection seems to work for some reason
+    const rc = rough.svg(shapeSvg);
+    const options = userNodeOverrides(node, {});
+    const roughNode = rc.circle(0, 0, radius * 2, options);
+
+    circleElem = shapeSvg.insert(() => roughNode, ':first-child');
+    circleElem
+      .attr('class', 'basic label-container history')
+      .attr('style', handleUndefinedAttr(cssStyles));
+  } else {
+    circleElem = shapeSvg
+      .insert('circle', ':first-child')
+      .attr('class', 'basic label-container history')
+      .attr('style', nodeStyles)
+      .attr('r', radius)
+      .attr('cx', 0)
+      .attr('cy', 0);
+  }
+
+  updateNodeBounds(node, circleElem);
+
+  node.intersect = function (point) {
+    return intersect.circle(node, radius, point);
+  };
+
+  return shapeSvg;
+}
+
+export async function history<T extends SVGGraphicsElement>(parent: D3Selection<T>, node: Node) {
+  node.label = 'H';
+  return await historyBase(parent, node);
+}
+
+export async function deephistory<T extends SVGGraphicsElement>(
+  parent: D3Selection<T>,
+  node: Node
+) {
+  node.label = 'H*';
+  return await historyBase(parent, node);
+}