From f63708c003fca4f59af81e39ef39d04238cabfab Mon Sep 17 00:00:00 2001
From: nimec01 <24428341+nimec01@users.noreply.github.com>
Date: Wed, 7 Aug 2024 21:54:46 +0200
Subject: [PATCH] feat: add history nodes to state diagram

---
 .cspell/mermaid-terms.txt                     |  1 +
 .../rendering/stateDiagram-v2.spec.js         | 35 +++++++++++
 demos/state.html                              | 31 ++++++++++
 docs/syntax/stateDiagram.md                   | 62 +++++++++++++++++++
 packages/mermaid/src/dagre-wrapper/nodes.js   | 43 +++++++++++++
 .../diagrams/state/parser/stateDiagram.jison  | 10 +++
 packages/mermaid/src/diagrams/state/styles.js |  6 ++
 .../mermaid/src/docs/syntax/stateDiagram.md   | 33 ++++++++++
 8 files changed, 221 insertions(+)

diff --git a/.cspell/mermaid-terms.txt b/.cspell/mermaid-terms.txt
index 3fa5eff2699..b64714e94e8 100644
--- a/.cspell/mermaid-terms.txt
+++ b/.cspell/mermaid-terms.txt
@@ -4,6 +4,7 @@ bmatrix
 braintree
 catmull
 compositTitleSize
+deephistory
 doublecircle
 elems
 gantt
diff --git a/cypress/integration/rendering/stateDiagram-v2.spec.js b/cypress/integration/rendering/stateDiagram-v2.spec.js
index cb40aa8dc0d..83d857a53bf 100644
--- a/cypress/integration/rendering/stateDiagram-v2.spec.js
+++ b/cypress/integration/rendering/stateDiagram-v2.spec.js
@@ -330,6 +330,41 @@ 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 A compound state should be able to link to itself', () => {
     imgSnapshotTest(
       `
diff --git a/demos/state.html b/demos/state.html
index aaa8e0aa990..9cdcbf720f2 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 [[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
+    </pre>
+    <hr />
+
     <script type="module">
       import mermaid from './mermaid.esm.mjs';
       mermaid.initialize({
diff --git a/docs/syntax/stateDiagram.md b/docs/syntax/stateDiagram.md
index e532678f0a9..ce66e72bbf2 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 (v11.0.0+)
+
+It is possible to add (deep) history nodes in the diagram using <\<history>> <\<deephistory>>.
+
+```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/src/dagre-wrapper/nodes.js b/packages/mermaid/src/dagre-wrapper/nodes.js
index 611cc5b6eed..7964a08569d 100644
--- a/packages/mermaid/src/dagre-wrapper/nodes.js
+++ b/packages/mermaid/src/dagre-wrapper/nodes.js
@@ -87,6 +87,47 @@ const choice = (parent, node) => {
   return shapeSvg;
 };
 
+const historyBase = async (parent, node) => {
+  const { shapeSvg, bbox, halfPadding } = await labelHelper(
+    parent,
+    node,
+    getClassesFromNode(node, undefined),
+    true
+  );
+  const circle = shapeSvg.insert('circle', ':first-child');
+
+  // center the circle around its coordinate
+  circle
+    .attr('class', 'history')
+    .attr('style', node.style)
+    .attr('rx', node.rx)
+    .attr('ry', node.ry)
+    .attr('r', 16)
+    .attr('width', 34)
+    .attr('height', 34);
+
+  log.info('History main');
+
+  updateNodeBounds(node, circle);
+
+  node.intersect = function (point) {
+    log.info('History intersect', node, bbox.width / 2 + halfPadding, point);
+    return intersect.circle(node, bbox.width / 2 + halfPadding, point);
+  };
+
+  return shapeSvg;
+};
+
+const history = async (parent, node) => {
+  node.labelText = 'H';
+  return await historyBase(parent, node);
+};
+
+const deephistory = async (parent, node) => {
+  node.labelText = 'H*';
+  return await historyBase(parent, node);
+};
+
 const hexagon = async (parent, node) => {
   const { shapeSvg, bbox } = await labelHelper(
     parent,
@@ -1125,6 +1166,8 @@ const shapes = {
   subroutine,
   fork: forkJoin,
   join: forkJoin,
+  history,
+  deephistory,
   class_box,
 };
 
diff --git a/packages/mermaid/src/diagrams/state/parser/stateDiagram.jison b/packages/mermaid/src/diagrams/state/parser/stateDiagram.jison
index 44235ecd406..715a6553b65 100644
--- a/packages/mermaid/src/diagrams/state/parser/stateDiagram.jison
+++ b/packages/mermaid/src/diagrams/state/parser/stateDiagram.jison
@@ -81,9 +81,13 @@ accDescr\s*"{"\s*                                { this.begin("acc_descr_multili
 
 <INITIAL,struct>"state"\s+  { /* console.log('Starting STATE '); */ this.pushState('STATE'); }
 
+<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>.*"[[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';}
@@ -225,6 +229,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 fe3d7078b1f..7110f1b3445 100644
--- a/packages/mermaid/src/diagrams/state/styles.js
+++ b/packages/mermaid/src/diagrams/state/styles.js
@@ -96,6 +96,12 @@ g.stateGroup line {
   stroke: ${options.background};
   stroke-width: 1.5
 }
+
+.node .history {
+  fill: #fff;
+  stroke: #000;
+}
+
 .end-state-inner {
   fill: ${options.compositeBackground || options.background};
   // stroke: ${options.background};
diff --git a/packages/mermaid/src/docs/syntax/stateDiagram.md b/packages/mermaid/src/docs/syntax/stateDiagram.md
index 9d99ab93b96..307a3ab7e41 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 (v11.0.0+)
+
+It is possible to add (deep) history nodes in the diagram using &lt;&lt;history&gt;&gt; &lt;&lt;deephistory&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.