@jarenjs/mermaid 0.72.3 → 0.73.0

package/README.md

@@ -360,7 +360,9 @@ Every subpath a consumer can import, derived from the manifest by
 | `@jarenjs/mermaid/schemas/jaren-workflow.schema.json` | schema | — |
 | `@jarenjs/mermaid/stylesheets/dag-to-flowchart.jslt.json` | asset | — |
 | `@jarenjs/mermaid/stylesheets/flowchart-to-dag.jslt.json` | asset | — |
+| `@jarenjs/mermaid/stylesheets/state-to-statechart.jslt.json` | asset | — |
 | `@jarenjs/mermaid/stylesheets/state-to-workflow.jslt.json` | asset | — |
+| `@jarenjs/mermaid/stylesheets/statechart-to-state.jslt.json` | asset | — |
 | `@jarenjs/mermaid/stylesheets/workflow-to-state.jslt.json` | asset | — |
 | `@jarenjs/mermaid/package.json` | metadata | — |
 <!--/fact-->

package/dist/types/parser/state.d.ts

@@ -11,9 +11,8 @@
  * fits no UML pattern reads whole as the event, so plain labels keep
  * their historical meaning byte for byte.
  *
- * Composite states (`state Foo { … }`) are flattened one level: the
- * inner transitions are captured with their parent recorded, keeping the
- * AST geometry-free.
+ * Composite states (`state Foo { … }`) stay in a flat table with parent
+ * ids on both states and transitions, at arbitrary nesting depth.
  */
 /**
  * @param {string[]} lines

package/docs/MERMAID-FORMAT.md

@@ -261,7 +261,7 @@ primitive.
 
 ### 5.1 Semantic projections
 
-The geometry-free AST doubles as a domain model, and four JSLT
+The geometry-free AST doubles as a domain model, and six JSLT
 stylesheets in [`stylesheets/`](../stylesheets/) project it both ways —
 plain data documents, no code:
 
@@ -269,6 +269,8 @@ plain data documents, no code:
 |---|---|
 | `state-to-workflow.jslt.json` | state DiagramDocument → executable machine (`@jarenjs/flow`'s jaren-fsm superset shape) |
 | `workflow-to-state.jslt.json` | machine document → state AST (print with `toMermaid`) |
+| `state-to-statechart.jslt.json` | compound state DiagramDocument → jaren-fsm 0.2 (`compileStatechart`) |
+| `statechart-to-state.jslt.json` | statechart document → state AST, preserving compound parents, initials and finals |
 | `flowchart-to-dag.jslt.json` | flowchart DiagramDocument → jaren-dag **skeleton** (every node a `task` stub named by its id; edge labels become `port`s verbatim) |
 | `dag-to-flowchart.jslt.json` | jaren-dag document → flowchart AST |
 
@@ -278,6 +280,19 @@ The forward state projection maps the parsed UML parts: `event` and
 registry name by convention. The reverse composes the label from the
 machine's parts and stays consistent with the parser by construction.
 
+The compound projection uses `parent` on states as well as transitions;
+the parser records arbitrary nesting depth and the printer retains transition
+order while reopening compound scopes when necessary. A scope's unlabelled
+`[*]` entry supplies its `initial`; an unlabelled edge to `[*]` declares its
+source terminal. Missing or ambiguous initials, a terminal with other outgoing
+transitions, or labelled pseudo-state edges refuse at statechart compilation.
+The 0.1 projection keeps its original flat behavior. Statechart history,
+parallel types, internal/external distinctions, delays, completion/eventless
+triggers and state entry/exit effects have no lossless spelling in this
+projection: author and retain those in JSON. The reverse is a display
+projection outside the compound/initial/final subset, not a serialization
+format for a full statechart.
+
 The dag projection renders each node kind as a fixed flowchart shape:
 
 | kind | shape |

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@jarenjs/mermaid",
   "private": false,
-  "version": "0.72.3",
+  "version": "0.73.0",
   "type": "module",
   "main": "./src/index.js",
   "types": "./dist/types/index.d.ts",
@@ -77,8 +77,8 @@
     "prepack": "npm run build:types"
   },
   "dependencies": {
-    "@jarenjs/charts": "^0.72.3",
-    "@jarenjs/core": "^0.72.3",
-    "@jarenjs/view": "^0.72.3"
+    "@jarenjs/charts": "^0.73.0",
+    "@jarenjs/core": "^0.73.0",
+    "@jarenjs/view": "^0.73.0"
   }
 }

package/src/parser/state.js

@@ -12,9 +12,8 @@
  * fits no UML pattern reads whole as the event, so plain labels keep
  * their historical meaning byte for byte.
  *
- * Composite states (`state Foo { … }`) are flattened one level: the
- * inner transitions are captured with their parent recorded, keeping the
- * AST geometry-free.
+ * Composite states (`state Foo { … }`) stay in a flat table with parent
+ * ids on both states and transitions, at arbitrary nesting depth.
  */
 
 /** `A --> B` / `A --> B : label`. */
@@ -79,17 +78,19 @@ export function parseState(lines) {
   /** @type {string[]} */
   const parentStack = [];
 
-  const ensure = (id, label) => {
+  const ensure = (id, label, declaration = false) => {
     if (id === '[*]') return;
     let st = stateMap.get(id);
     if (st === undefined) {
-      st = { id, label: label ?? id };
+      st = { id, label: label ?? id,
+        ...(parentStack.length ? { parent: parentStack.at(-1) } : {}) };
       stateMap.set(id, st);
       order.push(id);
     }
     else if (label != null) {
       st.label = label;
     }
+    if (declaration && parentStack.length) st.parent = parentStack.at(-1);
   };
 
   for (let li = 0; li < lines.length; li++) {
@@ -101,13 +102,13 @@ export function parseState(lines) {
     if (line.startsWith('state ') && line.endsWith('{')) {
       const inner = line.slice('state '.length, -1).trim();
       const id = inner.split(/\s+/)[0];
-      ensure(id, id);
+      ensure(id, null, true);
       parentStack.push(id);
       continue;
     }
 
     const sa = RE_STATE_AS.exec(line);
-    if (sa !== null) { ensure(sa[2], sa[1]); continue; }
+    if (sa !== null) { ensure(sa[2], sa[1], true); continue; }
 
     const tr = RE_TRANSITION.exec(line);
     if (tr !== null) {
@@ -127,7 +128,7 @@ export function parseState(lines) {
       continue;
     }
 
-    if (line.startsWith('state ')) { ensure(line.slice('state '.length).trim(), null); continue; }
+    if (line.startsWith('state ')) { ensure(line.slice('state '.length).trim(), null, true); continue; }
 
     const sd = RE_STATE_DESC.exec(line);
     if (sd !== null && sd[1] !== '[*]') { ensure(sd[1], sd[2].trim()); continue; }

package/src/to-mermaid.js

@@ -253,6 +253,34 @@ function printClass(ast) {
  */
 function printState(ast) {
   const out = ['stateDiagram-v2'];
+  if (ast.states.some((s) => s.parent != null) || ast.transitions.some((t) => t.parent != null)) {
+    const states = new Map(ast.states.map((s) => [s.id, s]));
+    let opened = [];
+    const scope = (parent) => {
+      const target = [];
+      for (let id = parent; id != null; id = states.get(id)?.parent) {
+        if (target.includes(id)) throw new TypeError('cyclic state-diagram parent');
+        target.unshift(id);
+      }
+      let shared = 0;
+      while (shared < opened.length && opened[shared] === target[shared]) shared++;
+      for (let i = opened.length; i > shared; i--) out.push('  '.repeat(i - 1) + '}');
+      for (let i = shared; i < target.length; i++) out.push('  '.repeat(i) + `state ${target[i]} {`);
+      opened = target;
+    };
+    // Declare every id first, then retain transition document order even
+    // when that requires reopening a compound scope. Priority survives print.
+    for (const s of ast.states) {
+      scope(s.parent);
+      out.push('  '.repeat(opened.length) + (s.label !== s.id ? `${s.id} : ${s.label}` : `state ${s.id}`));
+    }
+    for (const t of ast.transitions) {
+      scope(t.parent);
+      out.push('  '.repeat(opened.length) + `${t.from} --> ${t.to}${t.label ? ' : ' + t.label : ''}`);
+    }
+    scope(null);
+    return out.join('\n') + '\n';
+  }
   // an id-only state no transition mentions must still be DECLARED, or
   // the canonical round trip silently drops it (`state x` is the
   // parser's own spelling for exactly that)

package/stylesheets/state-to-statechart.jslt.json

@@ -0,0 +1,168 @@
+{
+  "$jslt": "0.1",
+  "rules": [
+    {
+      "match": "$",
+      "body": {
+        "$map": [
+          [
+            "$$fsm",
+            "0.2"
+          ],
+          [
+            "initial",
+            {
+              "$for": {
+                "t": "$.ast.transitions[*]"
+              },
+              "$where": {
+                "$and": [
+                  {
+                    "$eq": [
+                      "$t.from",
+                      "[*]"
+                    ]
+                  },
+                  {
+                    "$eq": [
+                      "$t.parent",
+                      null
+                    ]
+                  }
+                ]
+              },
+              "$return": "$t.to"
+            }
+          ],
+          [
+            "states",
+            [
+              {
+                "$for": {
+                  "s": "$.ast.states[*]"
+                },
+                "$return": {
+                  "id": "$s.id",
+                  "parent": {
+                    "$if": [
+                      "$s.parent",
+                      "$s.parent"
+                    ]
+                  },
+                  "initial": {
+                    "$for": {
+                      "t": "$.ast.transitions[*]"
+                    },
+                    "$where": {
+                      "$and": [
+                        {
+                          "$eq": [
+                            "$t.from",
+                            "[*]"
+                          ]
+                        },
+                        {
+                          "$eq": [
+                            "$t.parent",
+                            "$s.id"
+                          ]
+                        }
+                      ]
+                    },
+                    "$return": "$t.to"
+                  },
+                  "final": {
+                    "$if": [
+                      {
+                        "$exists": {
+                          "$for": {
+                            "t": "$.ast.transitions[*]"
+                          },
+                          "$where": {
+                            "$and": [
+                              {
+                                "$eq": [
+                                  "$t.to",
+                                  "[*]"
+                                ]
+                              },
+                              {
+                                "$eq": [
+                                  "$t.from",
+                                  "$s.id"
+                                ]
+                              }
+                            ]
+                          },
+                          "$return": "$t.from"
+                        }
+                      },
+                      true
+                    ]
+                  }
+                }
+              }
+            ]
+          ],
+          [
+            "transitions",
+            [
+              {
+                "$for": {
+                  "t": "$.ast.transitions[*]"
+                },
+                "$return": {
+                  "from": "$t.from",
+                  "event": "$t.event",
+                  "guard": {
+                    "$if": [
+                      "$t.guard",
+                      "$t.guard"
+                    ]
+                  },
+                  "to": "$t.to",
+                  "effects": {
+                    "$if": [
+                      "$t.effect",
+                      [
+                        {
+                          "run": "$t.effect"
+                        }
+                      ]
+                    ]
+                  }
+                },
+                "$where": {
+                  "$or": [
+                    {
+                      "$and": [
+                        {
+                          "$ne": [
+                            "$t.from",
+                            "[*]"
+                          ]
+                        },
+                        {
+                          "$ne": [
+                            "$t.to",
+                            "[*]"
+                          ]
+                        }
+                      ]
+                    },
+                    {
+                      "$ne": [
+                        "$t.label",
+                        null
+                      ]
+                    }
+                  ]
+                }
+              }
+            ]
+          ]
+        ]
+      }
+    }
+  ]
+}

package/stylesheets/statechart-to-state.jslt.json

@@ -0,0 +1,240 @@
+{
+  "$jslt": "0.1",
+  "rules": [
+    {
+      "match": "$",
+      "body": {
+        "states": [
+          {
+            "$for": {
+              "s": "$.states[*]"
+            },
+            "$return": {
+              "id": {
+                "$if": [
+                  {
+                    "$is-string": "$s"
+                  },
+                  "$s",
+                  "$s.id"
+                ]
+              },
+              "label": {
+                "$if": [
+                  {
+                    "$is-string": "$s"
+                  },
+                  "$s",
+                  "$s.id"
+                ]
+              },
+              "parent": {
+                "$if": [
+                  "$s.parent",
+                  "$s.parent"
+                ]
+              }
+            }
+          }
+        ],
+        "transitions": [
+          {
+            "$if": [
+              "$.initial",
+              {
+                "from": "[*]",
+                "to": "$.initial",
+                "label": null,
+                "event": null,
+                "guard": null,
+                "effect": null,
+                "parent": null
+              }
+            ]
+          },
+          {
+            "$for": {
+              "s": "$.states[*]"
+            },
+            "$where": {
+              "$exists": "$s.initial"
+            },
+            "$return": {
+              "from": "[*]",
+              "to": "$s.initial",
+              "label": null,
+              "event": null,
+              "guard": null,
+              "effect": null,
+              "parent": "$s.id"
+            }
+          },
+          {
+            "$for": {
+              "t": "$.transitions[*]"
+            },
+            "$return": {
+              "$let": {
+                "guardText": {
+                  "$if": [
+                    "$t.guard",
+                    {
+                      "$concat": [
+                        "[",
+                        {
+                          "$if": [
+                            {
+                              "$is-string": "$t.guard"
+                            },
+                            "$t.guard",
+                            "…"
+                          ]
+                        },
+                        "]"
+                      ]
+                    }
+                  ]
+                },
+                "effectText": {
+                  "$if": [
+                    {
+                      "$exists": "$t.effects[*]"
+                    },
+                    {
+                      "$concat": [
+                        "/ ",
+                        {
+                          "$string-join": [
+                            "$t.effects[*].run",
+                            ", "
+                          ]
+                        }
+                      ]
+                    }
+                  ]
+                }
+              },
+              "$return": {
+                "$let": {
+                  "pieces": {
+                    "$seq": [
+                      {
+                        "$if": [
+                          "$t.event",
+                          "$t.event"
+                        ]
+                      },
+                      "$guardText",
+                      "$effectText"
+                    ]
+                  }
+                },
+                "$return": {
+                  "from": "$t.from",
+                  "to": "$t.to",
+                  "label": {
+                    "$coalesce": [
+                      {
+                        "$if": [
+                          {
+                            "$exists": "$pieces"
+                          },
+                          {
+                            "$string-join": [
+                              "$pieces",
+                              " "
+                            ]
+                          }
+                        ]
+                      },
+                      null
+                    ]
+                  },
+                  "event": {
+                    "$coalesce": [
+                      "$t.event",
+                      null
+                    ]
+                  },
+                  "guard": {
+                    "$coalesce": [
+                      {
+                        "$if": [
+                          "$t.guard",
+                          {
+                            "$if": [
+                              {
+                                "$is-string": "$t.guard"
+                              },
+                              "$t.guard",
+                              "…"
+                            ]
+                          }
+                        ]
+                      },
+                      null
+                    ]
+                  },
+                  "effect": {
+                    "$coalesce": [
+                      {
+                        "$if": [
+                          {
+                            "$exists": "$t.effects[*]"
+                          },
+                          {
+                            "$string-join": [
+                              "$t.effects[*].run",
+                              ", "
+                            ]
+                          }
+                        ]
+                      },
+                      null
+                    ]
+                  },
+                  "parent": null
+                }
+              }
+            }
+          },
+          {
+            "$for": {
+              "s": "$.states[*]"
+            },
+            "$where": {
+              "$or": [
+                {
+                  "$eq": [
+                    "$s.final",
+                    true
+                  ]
+                },
+                {
+                  "$eq": [
+                    "$s.type",
+                    "final"
+                  ]
+                }
+              ]
+            },
+            "$return": {
+              "from": "$s.id",
+              "to": "[*]",
+              "label": null,
+              "event": null,
+              "guard": null,
+              "effect": null,
+              "parent": {
+                "$coalesce": [
+                  "$s.parent",
+                  null
+                ]
+              }
+            }
+          }
+        ]
+      }
+    }
+  ]
+}