@grethel-labs/excaliplant 0.10.0 → 0.11.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -7,7 +7,7 @@
7
7
  [![node](https://img.shields.io/node/v/@grethel-labs/excaliplant.svg)](https://nodejs.org)
8
8
  [![license](https://img.shields.io/npm/l/@grethel-labs/excaliplant.svg)](./LICENSE)
9
9
 
10
- > PlantUML → ELK layout → Excalidraw renderer with a plugin-based parser.  ·  **v0.10.0**  ·  200 tests  ·  MIT
10
+ > PlantUML → ELK layout → Excalidraw renderer with a plugin-based parser.  ·  **v0.11.0**  ·  210 tests  ·  MIT
11
11
 
12
12
  `@grethel-labs/excaliplant` takes PlantUML source, runs it through a plugin-based
13
13
  parser, lays it out with [ELK](https://github.com/kieler/elkjs), and
@@ -131,7 +131,7 @@ See the full [Sequence Diagram Component Coverage](./docs/sequence-components.md
131
131
  npm test
132
132
  ```
133
133
 
134
- Ships with **200 tests** across functional, edge-case,
134
+ Ships with **210 tests** across functional, edge-case,
135
135
  security (XSS / ReDoS / prototype-pollution), and self-introspection
136
136
  suites.
137
137
 
@@ -342,6 +342,18 @@ excaliplant
342
342
  │ │ │ ├── graph_context.mjs
343
343
  │ │ │ ├── graph_parser.mjs
344
344
  │ │ │ └── graph_runtime.mjs
345
+ │ │ ├── state
346
+ │ │ │ ├── docs
347
+ │ │ │ ├── plugins
348
+ │ │ │ ├── tests
349
+ │ │ │ ├── assets.mjs
350
+ │ │ │ ├── docs.mjs
351
+ │ │ │ ├── layout.mjs
352
+ │ │ │ ├── module.mjs
353
+ │ │ │ ├── parser.mjs
354
+ │ │ │ ├── render.mjs
355
+ │ │ │ ├── security.mjs
356
+ │ │ │ └── tests.mjs
345
357
  │ │ ├── use-case
346
358
  │ │ │ ├── plugins
347
359
  │ │ │ ├── tests
@@ -403,6 +415,7 @@ excaliplant
403
415
  │ ├── security.test.mjs
404
416
  │ ├── self_introspection.test.mjs
405
417
  │ ├── sequence_components.test.mjs
418
+ │ ├── state_components.test.mjs
406
419
  │ ├── style.test.mjs
407
420
  │ └── usecase_components.test.mjs
408
421
  ├── AGENTS.md
@@ -665,6 +678,54 @@ generated by the same command from JSDoc.
665
678
 
666
679
 
667
680
 
681
+ ### diagrams/state/assets
682
+
683
+
684
+
685
+ ### diagrams/state/docs
686
+
687
+
688
+
689
+ ### diagrams/state/docs/coverage_examples
690
+
691
+
692
+
693
+ ### diagrams/state/layout
694
+
695
+
696
+
697
+ ### diagrams/state/module
698
+
699
+
700
+
701
+ ### diagrams/state/parser
702
+
703
+
704
+
705
+ ### diagrams/state/plugins/syntax
706
+
707
+
708
+
709
+ ### diagrams/state/render
710
+
711
+
712
+
713
+ ### diagrams/state/security
714
+
715
+
716
+
717
+ ### diagrams/state/tests
718
+
719
+
720
+
721
+ ### diagrams/state/tests/output
722
+
723
+
724
+
725
+ ### diagrams/state/tests/state_components
726
+
727
+
728
+
668
729
  ### diagrams/use-case/assets
669
730
 
670
731
 
package/index.mjs CHANGED
@@ -109,6 +109,7 @@ export {
109
109
  DEFAULT_DEPLOYMENT_PLUGINS,
110
110
  DEFAULT_OBJECT_PLUGINS,
111
111
  DEFAULT_SEQUENCE_PLUGINS,
112
+ DEFAULT_STATE_PLUGINS,
112
113
  DEFAULT_USE_CASE_PLUGINS,
113
114
  defaultDiagramModuleRegistry,
114
115
  DeploymentDiagramAssets,
@@ -129,6 +130,15 @@ export {
129
130
  ObjectDiagramSecurity,
130
131
  ObjectDiagramTests,
131
132
  objectDiagramModule,
133
+ StateDiagramAssets,
134
+ StateDiagramDocs,
135
+ StateDiagramLayout,
136
+ StateDiagramModule,
137
+ StateDiagramParser,
138
+ StateDiagramRenderer,
139
+ StateDiagramSecurity,
140
+ StateDiagramTests,
141
+ stateDiagramModule,
132
142
  SequenceDiagramAssets,
133
143
  SequenceDiagramDocs,
134
144
  SequenceDiagramLayout,
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@grethel-labs/excaliplant",
3
- "version": "0.10.0",
3
+ "version": "0.11.0",
4
4
  "description": "PlantUML → ELK layout → Excalidraw renderer with a plugin-based parser.",
5
5
  "type": "module",
6
6
  "main": "index.mjs",
@@ -51,7 +51,7 @@
51
51
  },
52
52
  "scripts": {
53
53
  "pretest": "node scripts/clean-test-output.mjs",
54
- "test": "node --test tests/edge_cases.test.mjs tests/functional_more.test.mjs tests/merge_driver.test.mjs tests/modular_architecture.test.mjs tests/plantuml.test.mjs tests/security.test.mjs tests/self_introspection.test.mjs tests/sequence_components.test.mjs tests/class_components.test.mjs tests/component_components.test.mjs tests/deployment_components.test.mjs tests/usecase_components.test.mjs tests/object_components.test.mjs tests/style.test.mjs",
54
+ "test": "node --test tests/edge_cases.test.mjs tests/functional_more.test.mjs tests/merge_driver.test.mjs tests/modular_architecture.test.mjs tests/plantuml.test.mjs tests/security.test.mjs tests/self_introspection.test.mjs tests/sequence_components.test.mjs tests/class_components.test.mjs tests/component_components.test.mjs tests/deployment_components.test.mjs tests/usecase_components.test.mjs tests/object_components.test.mjs tests/state_components.test.mjs tests/style.test.mjs",
55
55
  "typecheck": "tsc -p tsconfig.json",
56
56
  "build:docs": "node docs/scripts/build-docs.mjs",
57
57
  "build:api": "node docs/scripts/build-docs.mjs",
@@ -125,6 +125,21 @@ export {
125
125
  } from "./object/render.mjs";
126
126
  export { ObjectDiagramSecurity, objectDiagramSecurity } from "./object/security.mjs";
127
127
  export { ObjectDiagramTests, objectDiagramTests } from "./object/tests.mjs";
128
+ export { StateDiagramModule, stateDiagramModule } from "./state/module.mjs";
129
+ export { StateDiagramAssets, stateDiagramAssets } from "./state/assets.mjs";
130
+ export { StateDiagramDocs, stateDiagramDocs } from "./state/docs.mjs";
131
+ export { StateDiagramLayout, layoutStateDiagram, stateDiagramLayout } from "./state/layout.mjs";
132
+ export {
133
+ StateDiagramParser,
134
+ DEFAULT_STATE_PLUGINS,
135
+ createStateParseContext,
136
+ detectStateDiagram,
137
+ prepareStateLines,
138
+ stateDiagramParser,
139
+ } from "./state/parser.mjs";
140
+ export { STATE_RENDERERS, StateDiagramRenderer, stateDiagramRenderer } from "./state/render.mjs";
141
+ export { StateDiagramSecurity, stateDiagramSecurity } from "./state/security.mjs";
142
+ export { StateDiagramTests, stateDiagramTests } from "./state/tests.mjs";
128
143
 
129
144
  import { sequenceDiagramModule } from "./sequence/module.mjs";
130
145
  import { classDiagramModule } from "./class/module.mjs";
@@ -132,6 +147,7 @@ import { componentDiagramModule } from "./component/module.mjs";
132
147
  import { deploymentDiagramModule } from "./deployment/module.mjs";
133
148
  import { useCaseDiagramModule } from "./use-case/module.mjs";
134
149
  import { objectDiagramModule } from "./object/module.mjs";
150
+ import { stateDiagramModule } from "./state/module.mjs";
135
151
 
136
152
  /** @public */
137
153
  export const BUILTIN_DIAGRAM_MODULES = Object.freeze([
@@ -141,4 +157,5 @@ export const BUILTIN_DIAGRAM_MODULES = Object.freeze([
141
157
  deploymentDiagramModule,
142
158
  useCaseDiagramModule,
143
159
  objectDiagramModule,
160
+ stateDiagramModule,
144
161
  ]);
@@ -0,0 +1,22 @@
1
+ /**
2
+ * State diagram asset manifest.
3
+ * @module diagrams/state/assets
4
+ */
5
+
6
+ import { BaseModuleAssets } from "../base/assets.mjs";
7
+
8
+ /** @public */
9
+ export class StateDiagramAssets extends BaseModuleAssets {
10
+ constructor() {
11
+ super({
12
+ fonts: ["Excalifont"],
13
+ sprites: [],
14
+ icons: [],
15
+ fixtures: [],
16
+ allowsRemoteAssets: false,
17
+ });
18
+ }
19
+ }
20
+
21
+ /** @public */
22
+ export const stateDiagramAssets = new StateDiagramAssets();
@@ -0,0 +1,77 @@
1
+ /**
2
+ * State diagram coverage examples.
3
+ * @module diagrams/state/docs/coverage_examples
4
+ */
5
+
6
+ /** @public */
7
+ export const STATE_COVERAGE_EXAMPLES = {
8
+ "simple-states": `
9
+ @startuml
10
+ [*] --> State1
11
+ State1 : this is a string
12
+ State1 --> State2 : event / action
13
+ State2 --> [*]
14
+ hide empty description
15
+ @enduml
16
+ `,
17
+
18
+ pseudostates: `
19
+ @startuml
20
+ state start1 <<start>>
21
+ state choice1 <<choice>>
22
+ state fork1 <<fork>>
23
+ state join1 <<join>>
24
+ state h <<history>>
25
+ state hd <<history*>>
26
+ [*] --> choice1
27
+ choice1 --> fork1 : yes
28
+ fork1 --> StateA
29
+ fork1 --> StateB
30
+ StateA --> join1
31
+ StateB --> join1
32
+ join1 --> [*]
33
+ @enduml
34
+ `,
35
+
36
+ "composite-states": `
37
+ @startuml
38
+ state Active {
39
+ [*] --> Idle
40
+ Idle --> Configuring : EvConfig
41
+ state Configuring {
42
+ [*] --> NewValue
43
+ }
44
+ }
45
+ Active --> [*]
46
+ @enduml
47
+ `,
48
+
49
+ "concurrent-regions": `
50
+ @startuml
51
+ state Active {
52
+ [*] -> NumLockOff
53
+ NumLockOff --> NumLockOn
54
+ --
55
+ [*] -> CapsLockOff
56
+ CapsLockOff --> CapsLockOn
57
+ }
58
+ @enduml
59
+ `,
60
+
61
+ transitions: `
62
+ @startuml
63
+ State1 -[#red,dashed]-> State2
64
+ State2 x->o State3
65
+ State3 --> State4 : event [guard] / action
66
+ @enduml
67
+ `,
68
+
69
+ notes: `
70
+ @startuml
71
+ state CurrentSite #pink {
72
+ state HardwareSetup #lightblue
73
+ }
74
+ note right of CurrentSite : composite note
75
+ @enduml
76
+ `,
77
+ };
@@ -0,0 +1,27 @@
1
+ /**
2
+ * State diagram documentation manifest.
3
+ * @module diagrams/state/docs
4
+ */
5
+
6
+ import { BaseModuleDocs } from "../base/docs.mjs";
7
+
8
+ /** @public */
9
+ export class StateDiagramDocs extends BaseModuleDocs {
10
+ constructor() {
11
+ super({
12
+ examples: [
13
+ "simple-states",
14
+ "pseudostates",
15
+ "composite-states",
16
+ "concurrent-regions",
17
+ "transitions",
18
+ "notes",
19
+ ],
20
+ generatedPages: [],
21
+ knownGaps: ["entry-exit-points", "expansion-regions", "sdl-notation"],
22
+ });
23
+ }
24
+ }
25
+
26
+ /** @public */
27
+ export const stateDiagramDocs = new StateDiagramDocs();
@@ -0,0 +1,30 @@
1
+ /**
2
+ * State diagram layout contract.
3
+ * @module diagrams/state/layout
4
+ */
5
+
6
+ import { BaseModuleLayout } from "../base/layout.mjs";
7
+ import { layoutDiagram } from "../../general/layout/elk_layout.mjs";
8
+
9
+ /**
10
+ * @param {object} model
11
+ * @param {object} _context
12
+ * @returns {Promise<void>}
13
+ * @public
14
+ */
15
+ export async function layoutStateDiagram(model, _context) {
16
+ await layoutDiagram(/** @type {import("../../general/model/diagram.mjs").Diagram} */ (model));
17
+ }
18
+
19
+ /** @public */
20
+ export class StateDiagramLayout extends BaseModuleLayout {
21
+ constructor() {
22
+ super({
23
+ layoutStrategy: "elkGraph",
24
+ layout: layoutStateDiagram,
25
+ });
26
+ }
27
+ }
28
+
29
+ /** @public */
30
+ export const stateDiagramLayout = new StateDiagramLayout();
@@ -0,0 +1,99 @@
1
+ /**
2
+ * Built-in state diagram module.
3
+ * @module diagrams/state/module
4
+ */
5
+
6
+ import { GraphModuleBase } from "../base/module.mjs";
7
+ import { stateDiagramAssets } from "./assets.mjs";
8
+ import { stateDiagramDocs } from "./docs.mjs";
9
+ import { stateDiagramLayout } from "./layout.mjs";
10
+ import { stateDiagramParser } from "./parser.mjs";
11
+ import { stateDiagramRenderer } from "./render.mjs";
12
+ import { stateDiagramSecurity } from "./security.mjs";
13
+ import { stateDiagramTests } from "./tests.mjs";
14
+
15
+ /** @public */
16
+ export class StateDiagramModule extends GraphModuleBase {
17
+ constructor() {
18
+ super({
19
+ kind: "state",
20
+ artifactRoot: "src/diagrams/state",
21
+ ownedArtifacts: {
22
+ parser: [
23
+ "src/diagrams/state/parser.mjs",
24
+ "src/diagrams/state/plugins/syntax.mjs",
25
+ "src/diagrams/shared/graph_parser.mjs",
26
+ "src/diagrams/shared/graph_plugins/connections.mjs",
27
+ "src/diagrams/shared/graph_plugins/containers.mjs",
28
+ "src/diagrams/shared/graph_plugins/filters.mjs",
29
+ "src/diagrams/shared/graph_plugins/notes.mjs",
30
+ "src/diagrams/shared/graph_plugins/ports.mjs",
31
+ "src/diagrams/shared/graph_plugins/preamble.mjs",
32
+ "src/diagrams/shared/graph_plugins/shapes.mjs",
33
+ ],
34
+ model: ["src/diagrams/shared/graph_context.mjs", "src/general/model/diagram.mjs"],
35
+ style: [],
36
+ layout: ["src/diagrams/state/layout.mjs"],
37
+ render: ["src/diagrams/state/render.mjs", "src/general/render/excalidraw.mjs"],
38
+ security: ["src/diagrams/state/security.mjs"],
39
+ assets: ["src/diagrams/state/assets.mjs"],
40
+ docs: ["src/diagrams/state/docs.mjs", "src/diagrams/state/docs/coverage_examples.mjs"],
41
+ tests: [
42
+ "src/diagrams/state/tests.mjs",
43
+ "src/diagrams/state/tests/state_components.test.mjs",
44
+ "src/diagrams/state/tests/output.mjs",
45
+ "tests/state_components.test.mjs",
46
+ ],
47
+ },
48
+ startDirectives: ["@startstate"],
49
+ parser: stateDiagramParser,
50
+ layout: stateDiagramLayout,
51
+ renderer: stateDiagramRenderer,
52
+ docs: stateDiagramDocs,
53
+ tests: stateDiagramTests,
54
+ security: stateDiagramSecurity,
55
+ assets: stateDiagramAssets,
56
+ dependencies: [
57
+ {
58
+ kind: "security-base",
59
+ versionRange: "^1.0.0",
60
+ capabilities: ["sanitize", "limits"],
61
+ optional: false,
62
+ },
63
+ {
64
+ kind: "style-base",
65
+ versionRange: "^1.0.0",
66
+ capabilities: ["style-cascade"],
67
+ optional: false,
68
+ },
69
+ {
70
+ kind: "text-base",
71
+ versionRange: "^1.0.0",
72
+ capabilities: ["inline-text"],
73
+ optional: false,
74
+ },
75
+ {
76
+ kind: "arrow-base",
77
+ versionRange: "^1.0.0",
78
+ capabilities: ["diagram-arrow"],
79
+ optional: false,
80
+ },
81
+ {
82
+ kind: "asset-base",
83
+ versionRange: "^1.0.0",
84
+ capabilities: ["packaged-assets"],
85
+ optional: false,
86
+ },
87
+ {
88
+ kind: "graph-structure",
89
+ versionRange: "^1.0.0",
90
+ capabilities: ["boxes", "containers", "connections"],
91
+ optional: false,
92
+ },
93
+ ],
94
+ });
95
+ }
96
+ }
97
+
98
+ /** @public */
99
+ export const stateDiagramModule = new StateDiagramModule();
@@ -0,0 +1,74 @@
1
+ /**
2
+ * State diagram parser contract.
3
+ * @module diagrams/state/parser
4
+ */
5
+
6
+ import { explodeBraces, stripComment } from "../../util/plantuml_utils.mjs";
7
+ import { BaseModuleParser } from "../base/parser.mjs";
8
+ import { DEFAULT_GRAPH_PLUGINS, createGraphParseContext } from "../shared/graph_parser.mjs";
9
+ import { connectionPlugin } from "../shared/graph_plugins/connections.mjs";
10
+ import {
11
+ stateDeclarationPlugin,
12
+ pseudostateDeclarationPlugin,
13
+ compositeStatePlugin,
14
+ stateDescriptionPlugin,
15
+ concurrentRegionPlugin,
16
+ } from "./plugins/syntax.mjs";
17
+
18
+ const graphPluginsBeforeConnections = DEFAULT_GRAPH_PLUGINS.filter(
19
+ (plugin) => plugin.name !== connectionPlugin.name,
20
+ );
21
+
22
+ /** @public */
23
+ export const DEFAULT_STATE_PLUGINS = Object.freeze([
24
+ ...graphPluginsBeforeConnections,
25
+ stateDeclarationPlugin,
26
+ pseudostateDeclarationPlugin,
27
+ compositeStatePlugin,
28
+ stateDescriptionPlugin,
29
+ concurrentRegionPlugin,
30
+ connectionPlugin,
31
+ ]);
32
+
33
+ /** @public */
34
+ export const createStateParseContext = createGraphParseContext;
35
+
36
+ /**
37
+ * @param {string[]} lines Raw PlantUML lines.
38
+ * @returns {string[]} Lines prepared for state-diagram parsing.
39
+ * @public
40
+ */
41
+ export function prepareStateLines(lines) {
42
+ return explodeBraces(lines).filter((line) => !/^@(start|end)state\b/i.test(line.trim()));
43
+ }
44
+
45
+ /** @public */
46
+ export class StateDiagramParser extends BaseModuleParser {
47
+ constructor() {
48
+ super({
49
+ plugins: DEFAULT_STATE_PLUGINS,
50
+ createParseContext: createStateParseContext,
51
+ prepareLines: prepareStateLines,
52
+ detect: detectStateDiagram,
53
+ });
54
+ }
55
+ }
56
+
57
+ /** @public */
58
+ export const stateDiagramParser = new StateDiagramParser();
59
+
60
+ /**
61
+ * @param {string} text Raw PlantUML source.
62
+ * @returns {boolean}
63
+ */
64
+ export function detectStateDiagram(text) {
65
+ for (const raw of text.split(/\r?\n/)) {
66
+ const line = stripComment(raw).trim();
67
+ if (!line) continue;
68
+ if (/^skinparam\s+state\b/i.test(line)) return true;
69
+ if (/^\[\*\]\s*-->?\s*/.test(line)) return true;
70
+ if (/^state\s+/.test(line)) return true;
71
+ if (/^hide\s+empty\s+description\b/i.test(line)) return true;
72
+ }
73
+ return false;
74
+ }
@@ -0,0 +1,291 @@
1
+ /**
2
+ * State-diagram specific syntax plugins.
3
+ * @module diagrams/state/plugins/syntax
4
+ */
5
+
6
+ import { slug, stripQuotes, STEREOTYPE } from "../../../util/plantuml_utils.mjs";
7
+
8
+ const STATE_HEADER = /^state\s+(.+?)(?:\s+as\s+([A-Za-z_][\w.-]*))?(\s*\{)?$/i;
9
+ const STATE_DESCRIPTION = /^([A-Za-z_][\w.-]*)\s*:\s*(.+)$/;
10
+ const PSEUDOSTATE_PATTERN = /^\[\*\]|^\[H\]|^\[H\*\]/i;
11
+ const CONCURRENT_SEPARATOR = /^\s*(--|\|\|)\s*$/;
12
+
13
+ /**
14
+ * @typedef {{id:string,title:string,kind:string,stereotype:string}} ParsedState
15
+ */
16
+
17
+ /**
18
+ * Parse a state declaration.
19
+ * @param {string} raw Raw declaration body after the keyword.
20
+ * @returns {ParsedState|null}
21
+ */
22
+ function parseStateDeclaration(raw) {
23
+ let body = raw.replace(/\s*\{\s*$/, "").trim();
24
+ if (!body) return null;
25
+
26
+ let stereotype = "";
27
+ const stereotypeMatch = body.match(STEREOTYPE);
28
+ if (stereotypeMatch) {
29
+ stereotype = stereotypeMatch[1].trim();
30
+ body = body.replace(stereotypeMatch[0], "").trim();
31
+ }
32
+
33
+ // Check for pseudostate stereotypes
34
+ let kind = "state";
35
+ if (stereotype) {
36
+ const lower = stereotype.toLowerCase();
37
+ if (
38
+ [
39
+ "start",
40
+ "end",
41
+ "choice",
42
+ "fork",
43
+ "join",
44
+ "history",
45
+ "history*",
46
+ "entrypoint",
47
+ "exitpoint",
48
+ "inputpin",
49
+ "outputpin",
50
+ ].includes(lower)
51
+ ) {
52
+ kind = lower.replace("*", "_deep");
53
+ }
54
+ }
55
+
56
+ const aliasMatch = body.match(/^("[^"]+"|.+?)\s+as\s+([A-Za-z_][\w.-]*)$/i);
57
+ if (aliasMatch) {
58
+ const title = stripQuotes(aliasMatch[1].trim());
59
+ return { id: aliasMatch[2], title, kind, stereotype };
60
+ }
61
+
62
+ const title = stripQuotes(body);
63
+ const id = body.startsWith('"') ? slug(title) : body.split(/\s+/)[0];
64
+ return { id, title, kind, stereotype };
65
+ }
66
+
67
+ /**
68
+ * State declaration plugin.
69
+ * Handles: state Name, state "Long Name" as alias, state Name { ... }
70
+ * @public
71
+ */
72
+ export const stateDeclarationPlugin = {
73
+ name: "state.declaration",
74
+ /**
75
+ * @param {string} line
76
+ * @param {Record<string, any>} ctx
77
+ * @returns {boolean}
78
+ */
79
+ tryLine(line, ctx) {
80
+ const match = line.match(STATE_HEADER);
81
+ if (!match) return false;
82
+
83
+ const parsed = parseStateDeclaration(match[1]);
84
+ if (!parsed) return false;
85
+
86
+ const id = match[2] || parsed.id;
87
+ const isBlock = !!match[3];
88
+
89
+ ctx.addBox({
90
+ id,
91
+ title: parsed.title,
92
+ shape: parsed.kind,
93
+ stereotype: parsed.stereotype,
94
+ });
95
+
96
+ if (isBlock) {
97
+ ctx.enterBlock(id, {
98
+ onLine: (/** @type {string} */ innerLine, /** @type {Record<string, any>} */ innerCtx) => {
99
+ // Handle state body content
100
+ if (innerLine.trim() === "}") return { endBlock: true };
101
+
102
+ // Handle state descriptions inside block
103
+ const descMatch = innerLine.match(STATE_DESCRIPTION);
104
+ if (descMatch && descMatch[1] === id) {
105
+ const box = innerCtx.boxes.get(id);
106
+ if (box) {
107
+ if (!box.members) box.members = [];
108
+ box.members.push(descMatch[2]);
109
+ }
110
+ return true;
111
+ }
112
+
113
+ // Handle nested states
114
+ const nestedMatch = innerLine.match(STATE_HEADER);
115
+ if (nestedMatch) {
116
+ const nestedParsed = parseStateDeclaration(nestedMatch[1]);
117
+ if (nestedParsed) {
118
+ const nestedId = nestedMatch[2] || nestedParsed.id;
119
+ innerCtx.addBox({
120
+ id: nestedId,
121
+ title: nestedParsed.title,
122
+ shape: nestedParsed.kind,
123
+ stereotype: nestedParsed.stereotype,
124
+ parent: id,
125
+ });
126
+ }
127
+ return true;
128
+ }
129
+
130
+ return false;
131
+ },
132
+ tryEnd: (/** @type {string} */ endLine) => endLine.trim() === "}",
133
+ });
134
+ }
135
+
136
+ return true;
137
+ },
138
+ };
139
+
140
+ /**
141
+ * Pseudostate declaration plugin.
142
+ * Handles: [*], [H], [H*] and their shorthand forms
143
+ * @public
144
+ */
145
+ export const pseudostateDeclarationPlugin = {
146
+ name: "state.pseudostate",
147
+ /**
148
+ * @param {string} line
149
+ * @param {Record<string, any>} ctx
150
+ * @returns {boolean}
151
+ */
152
+ tryLine(line, ctx) {
153
+ // Handle [*] as start/end state
154
+ if (line.trim() === "[*]") {
155
+ // [*] is typically used in transitions, not as standalone declaration
156
+ // But we can create an implicit start state if needed
157
+ return false;
158
+ }
159
+
160
+ // Handle [H] and [H*] history states
161
+ const historyMatch = line.match(/^\[H\*?\]\s*$/i);
162
+ if (historyMatch) {
163
+ const isDeep = line.includes("H*");
164
+ ctx.addBox({
165
+ id: `history_${ctx.boxes.size}`,
166
+ title: isDeep ? "H*" : "H",
167
+ shape: isDeep ? "history_deep" : "history",
168
+ });
169
+ return true;
170
+ }
171
+
172
+ return false;
173
+ },
174
+ };
175
+
176
+ /**
177
+ * Composite state plugin.
178
+ * Handles nested state blocks and concurrent regions.
179
+ * @public
180
+ */
181
+ export const compositeStatePlugin = {
182
+ name: "state.composite",
183
+ /**
184
+ * @param {string} line
185
+ * @param {Record<string, any>} ctx
186
+ * @returns {boolean|object}
187
+ */
188
+ tryStart(line, ctx) {
189
+ const match = line.match(STATE_HEADER);
190
+ if (!match || !match[3]) return false;
191
+
192
+ const parsed = parseStateDeclaration(match[1]);
193
+ if (!parsed) return false;
194
+
195
+ const id = match[2] || parsed.id;
196
+
197
+ ctx.addBox({
198
+ id,
199
+ title: parsed.title,
200
+ shape: parsed.kind,
201
+ stereotype: parsed.stereotype,
202
+ isContainer: true,
203
+ });
204
+
205
+ return {
206
+ onLine: (/** @type {string} */ innerLine, /** @type {Record<string, any>} */ innerCtx) => {
207
+ const trimmed = innerLine.trim();
208
+ if (trimmed === "}") return { endBlock: true };
209
+
210
+ // Handle concurrent region separator
211
+ if (CONCURRENT_SEPARATOR.test(trimmed)) {
212
+ const box = innerCtx.boxes.get(id);
213
+ if (box) {
214
+ if (!box.regions) box.regions = [];
215
+ box.regions.push({ separator: trimmed });
216
+ }
217
+ return true;
218
+ }
219
+
220
+ // Handle state descriptions
221
+ const descMatch = innerLine.match(STATE_DESCRIPTION);
222
+ if (descMatch) {
223
+ const targetId = descMatch[1];
224
+ const box = innerCtx.boxes.get(targetId);
225
+ if (box) {
226
+ if (!box.members) box.members = [];
227
+ box.members.push(descMatch[2]);
228
+ }
229
+ return true;
230
+ }
231
+
232
+ return false;
233
+ },
234
+ tryEnd: (/** @type {string} */ endLine) => endLine.trim() === "}",
235
+ };
236
+ },
237
+ };
238
+
239
+ /**
240
+ * State description plugin.
241
+ * Handles: StateName : description text
242
+ * @public
243
+ */
244
+ export const stateDescriptionPlugin = {
245
+ name: "state.description",
246
+ /**
247
+ * @param {string} line
248
+ * @param {Record<string, any>} ctx
249
+ * @returns {boolean}
250
+ */
251
+ tryLine(line, ctx) {
252
+ const match = line.match(STATE_DESCRIPTION);
253
+ if (!match) return false;
254
+
255
+ const id = match[1];
256
+ const box = ctx.boxes.get(id);
257
+ if (!box) return false;
258
+
259
+ if (!box.members) box.members = [];
260
+ box.members.push(match[2]);
261
+ return true;
262
+ },
263
+ };
264
+
265
+ /**
266
+ * Concurrent region plugin.
267
+ * Handles -- and || separators within composite states.
268
+ * @public
269
+ */
270
+ export const concurrentRegionPlugin = {
271
+ name: "state.concurrent",
272
+ /**
273
+ * @param {string} line
274
+ * @param {Record<string, any>} ctx
275
+ * @returns {boolean}
276
+ */
277
+ tryLine(line, ctx) {
278
+ if (!CONCURRENT_SEPARATOR.test(line.trim())) return false;
279
+
280
+ // Mark current container as having concurrent regions
281
+ const currentContainer = ctx.currentContainer;
282
+ if (currentContainer) {
283
+ const box = ctx.boxes.get(currentContainer);
284
+ if (box) {
285
+ box.hasConcurrentRegions = true;
286
+ }
287
+ }
288
+
289
+ return true;
290
+ },
291
+ };
@@ -0,0 +1,22 @@
1
+ /**
2
+ * State diagram renderer contract.
3
+ * @module diagrams/state/render
4
+ */
5
+
6
+ import { BaseModuleRenderer } from "../base/renderer.mjs";
7
+ import { GRAPH_RENDERERS } from "../shared/graph_runtime.mjs";
8
+
9
+ /** @public */
10
+ export const STATE_RENDERERS = GRAPH_RENDERERS;
11
+
12
+ /** @public */
13
+ export class StateDiagramRenderer extends BaseModuleRenderer {
14
+ constructor() {
15
+ super({
16
+ renderers: STATE_RENDERERS,
17
+ });
18
+ }
19
+ }
20
+
21
+ /** @public */
22
+ export const stateDiagramRenderer = new StateDiagramRenderer();
@@ -0,0 +1,18 @@
1
+ /**
2
+ * State diagram security profile.
3
+ * @module diagrams/state/security
4
+ */
5
+
6
+ import { BaseModuleSecurity } from "../base/security.mjs";
7
+
8
+ /** @public */
9
+ export class StateDiagramSecurity extends BaseModuleSecurity {
10
+ constructor() {
11
+ super({
12
+ capabilities: ["sanitize", "limits", "inline-text", "diagram-arrow"],
13
+ });
14
+ }
15
+ }
16
+
17
+ /** @public */
18
+ export const stateDiagramSecurity = new StateDiagramSecurity();
@@ -0,0 +1,24 @@
1
+ /**
2
+ * State diagram test output utilities.
3
+ * @module diagrams/state/tests/output
4
+ */
5
+
6
+ import { mkdirSync, writeFileSync } from "node:fs";
7
+ import { dirname, join } from "node:path";
8
+ import { fileURLToPath } from "node:url";
9
+
10
+ const __dirname = dirname(fileURLToPath(import.meta.url));
11
+
12
+ /** @public */
13
+ export const STATE_TEST_OUTPUT_DIR = join(__dirname, "output");
14
+
15
+ /**
16
+ * @param {string} filename
17
+ * @param {string} content
18
+ * @public
19
+ */
20
+ export function writeStateOutput(filename, content) {
21
+ const path = join(STATE_TEST_OUTPUT_DIR, filename);
22
+ mkdirSync(dirname(path), { recursive: true });
23
+ writeFileSync(path, content, "utf-8");
24
+ }
@@ -0,0 +1,147 @@
1
+ /**
2
+ * State diagram component tests.
3
+ * @module diagrams/state/tests/state_components
4
+ */
5
+
6
+ import { describe, it } from "node:test";
7
+ import { strict as assert } from "node:assert";
8
+ import { parsePlantUml } from "../../../../index.mjs";
9
+
10
+ const BASIC_STATE = `
11
+ @startuml
12
+ [*] --> State1
13
+ State1 : this is a string
14
+ State1 --> State2 : event / action
15
+ State2 --> [*]
16
+ hide empty description
17
+ @enduml
18
+ `;
19
+
20
+ describe("State diagram examples", () => {
21
+ it("parses basic state diagram", async () => {
22
+ const parsed = await parsePlantUml(BASIC_STATE);
23
+ assert.ok(parsed, "Should parse successfully");
24
+ });
25
+ });
26
+
27
+ describe("State declarations", () => {
28
+ it("parses state declarations", async () => {
29
+ const puml = `
30
+ @startuml
31
+ state Idle
32
+ state Running : active process
33
+ state Stopped : final state
34
+ @enduml
35
+ `;
36
+ const parsed = await parsePlantUml(puml);
37
+ assert.ok(parsed, "Should parse");
38
+ // Just verify parsing succeeds - detailed box inspection depends on model structure
39
+ assert.ok(parsed.planes || parsed.boxes, "Should have planes or boxes");
40
+ });
41
+
42
+ it("handles aliases", async () => {
43
+ const puml = `
44
+ @startuml
45
+ state "My Complex State" as complex
46
+ @enduml
47
+ `;
48
+ const parsed = await parsePlantUml(puml);
49
+ assert.ok(parsed, "Should parse with aliases");
50
+ });
51
+ });
52
+
53
+ describe("Pseudostates", () => {
54
+ it("recognizes start and end states", async () => {
55
+ const puml = `
56
+ @startuml
57
+ state start1 <<start>>
58
+ state end1 <<end>>
59
+ [*] --> start1
60
+ start1 --> end1
61
+ end1 --> [*]
62
+ @enduml
63
+ `;
64
+ const parsed = await parsePlantUml(puml);
65
+ assert.ok(parsed, "Should parse pseudostates");
66
+ });
67
+
68
+ it("recognizes choice, fork, join", async () => {
69
+ const puml = `
70
+ @startuml
71
+ state choice1 <<choice>>
72
+ state fork1 <<fork>>
73
+ state join1 <<join>>
74
+ [*] --> choice1
75
+ @enduml
76
+ `;
77
+ const parsed = await parsePlantUml(puml);
78
+ assert.ok(parsed, "Should parse choice/fork/join");
79
+ });
80
+
81
+ it("recognizes history states", async () => {
82
+ const puml = `
83
+ @startuml
84
+ state h <<history>>
85
+ state hd <<history*>>
86
+ @enduml
87
+ `;
88
+ const parsed = await parsePlantUml(puml);
89
+ assert.ok(parsed, "Should parse history states");
90
+ });
91
+ });
92
+
93
+ describe("Composite states", () => {
94
+ it("handles nested states", async () => {
95
+ const puml = `
96
+ @startuml
97
+ state Active {
98
+ [*] --> Idle
99
+ Idle --> Configuring : EvConfig
100
+ }
101
+ @enduml
102
+ `;
103
+ const parsed = await parsePlantUml(puml);
104
+ assert.ok(parsed, "Should parse composite states");
105
+ });
106
+
107
+ it("handles deeply nested states", async () => {
108
+ const puml = `
109
+ @startuml
110
+ state Outer {
111
+ state Inner {
112
+ [*] --> Deep
113
+ state Deep {
114
+ [*] --> Deepest
115
+ }
116
+ }
117
+ }
118
+ @enduml
119
+ `;
120
+ const parsed = await parsePlantUml(puml);
121
+ assert.ok(parsed, "Should parse deeply nested states");
122
+ });
123
+ });
124
+
125
+ describe("Transitions", () => {
126
+ it("handles basic transitions", async () => {
127
+ const puml = `
128
+ @startuml
129
+ State1 --> State2 : event
130
+ State2 --> State3 : event [guard] / action
131
+ @enduml
132
+ `;
133
+ const parsed = await parsePlantUml(puml);
134
+ assert.ok(parsed, "Should parse transitions");
135
+ });
136
+
137
+ it("handles transitions to/from [*]", async () => {
138
+ const puml = `
139
+ @startuml
140
+ [*] --> State1
141
+ State1 --> [*]
142
+ @enduml
143
+ `;
144
+ const parsed = await parsePlantUml(puml);
145
+ assert.ok(parsed, "Should parse transitions to/from [*]");
146
+ });
147
+ });
@@ -0,0 +1,20 @@
1
+ /**
2
+ * State diagram test manifest.
3
+ * @module diagrams/state/tests
4
+ */
5
+
6
+ import { BaseModuleTests } from "../base/tests.mjs";
7
+
8
+ /** @public */
9
+ export class StateDiagramTests extends BaseModuleTests {
10
+ constructor() {
11
+ super({
12
+ unit: ["src/diagrams/state/tests/state_components.test.mjs"],
13
+ integration: ["tests/state_components.test.mjs", "tests/plantuml.test.mjs"],
14
+ security: ["tests/security.test.mjs"],
15
+ });
16
+ }
17
+ }
18
+
19
+ /** @public */
20
+ export const stateDiagramTests = new StateDiagramTests();
@@ -265,6 +265,48 @@ function sizeBox(box, width) {
265
265
  case "note":
266
266
  shapeMin = Math.max(shapeMin, 50);
267
267
  break;
268
+ case "state":
269
+ // State diagrams use similar sizing to class/object
270
+ if (box.members && box.members.length) {
271
+ const wrappedMembers = [];
272
+ let totalLines = 0;
273
+ for (const member of box.members) {
274
+ const segments = String(member).split("\n");
275
+ const lines = [];
276
+ for (const seg of segments) {
277
+ const w = wrapMemberSignature(seg, FONT.sizeDescription, innerWidth);
278
+ if (w.lines.length === 0) lines.push("");
279
+ else lines.push(...w.lines);
280
+ }
281
+ wrappedMembers.push(lines);
282
+ totalLines += Math.max(1, lines.length);
283
+ }
284
+ box._wrappedMembers = wrappedMembers;
285
+ shapeMin = Math.max(
286
+ shapeMin,
287
+ textHeight + totalLines * FONT.sizeDescription * FONT.lineHeight + 12,
288
+ );
289
+ }
290
+ break;
291
+ case "start":
292
+ case "end":
293
+ // Start/end pseudostates are small circles
294
+ shapeMin = Math.max(shapeMin, 40);
295
+ break;
296
+ case "choice":
297
+ // Choice pseudostate is a diamond
298
+ shapeMin = Math.max(shapeMin, 60);
299
+ break;
300
+ case "fork":
301
+ case "join":
302
+ // Fork/join are bars
303
+ shapeMin = Math.max(shapeMin, 20);
304
+ break;
305
+ case "history":
306
+ case "history_deep":
307
+ // History states are small circles with H
308
+ shapeMin = Math.max(shapeMin, 48);
309
+ break;
268
310
  }
269
311
 
270
312
  box.height = Math.max(shapeMin, textHeight, connectionsHeight);
@@ -42,6 +42,14 @@ export const SHAPES = [
42
42
  "map",
43
43
  "diamond",
44
44
  "note",
45
+ "state",
46
+ "start",
47
+ "end",
48
+ "choice",
49
+ "fork",
50
+ "join",
51
+ "history",
52
+ "history_deep",
45
53
  ];
46
54
 
47
55
  /**
@@ -745,6 +745,24 @@ function renderBox(box, parentColor, elements) {
745
745
  case "note":
746
746
  renderNote(box, elements);
747
747
  break;
748
+ case "state":
749
+ renderStateShape(box, color, elements);
750
+ break;
751
+ case "start":
752
+ case "end":
753
+ renderStartEndShape(box, color, elements);
754
+ break;
755
+ case "choice":
756
+ renderChoiceShape(box, color, elements);
757
+ break;
758
+ case "fork":
759
+ case "join":
760
+ renderForkJoinShape(box, color, elements);
761
+ break;
762
+ case "history":
763
+ case "history_deep":
764
+ renderHistoryShape(box, color, elements);
765
+ break;
748
766
  default:
749
767
  renderRectangleShape(box, color, elements);
750
768
  break;
@@ -898,6 +916,165 @@ function renderDiamondShape(box, color, elements) {
898
916
  renderBoxText(box, color, elements);
899
917
  }
900
918
 
919
+ /**
920
+ * Render a UML state shape (rounded rectangle with optional compartments).
921
+ * @param {Box} box Box (shape == `state`).
922
+ * @param {{ stroke: string, fill: string, titleFill: string }} color
923
+ * @param {ExcalElement[]} elements
924
+ * @internal
925
+ */
926
+ function renderStateShape(box, color, elements) {
927
+ // State is rendered as a rounded rectangle
928
+ const r = rect({
929
+ x: box.x,
930
+ y: box.y,
931
+ width: box.width,
932
+ height: box.height,
933
+ strokeColor: color.stroke,
934
+ backgroundColor: color.fill,
935
+ });
936
+ r.roundness = { type: ROUNDNESS.proportional, value: 0.2 };
937
+ elements.push(r);
938
+ renderBoxText(box, color, elements);
939
+ }
940
+
941
+ /**
942
+ * Render start/end pseudostate (filled circle for start, bullseye for end).
943
+ * @param {Box} box Box (shape == `start` or `end`).
944
+ * @param {{ stroke: string, fill: string }} color
945
+ * @param {object[]} elements
946
+ * @internal
947
+ */
948
+ function renderStartEndShape(box, color, elements) {
949
+ const cx = box.x + box.width / 2;
950
+ const cy = box.y + box.height / 2;
951
+ const radius = Math.min(box.width, box.height) / 2 - 2;
952
+
953
+ if (box.shape === "start") {
954
+ // Start state: filled black circle
955
+ elements.push(
956
+ ellipse({
957
+ x: cx - radius,
958
+ y: cy - radius,
959
+ width: radius * 2,
960
+ height: radius * 2,
961
+ strokeColor: color.stroke,
962
+ backgroundColor: "#000000",
963
+ }),
964
+ );
965
+ } else {
966
+ // End state: bullseye (outer circle + inner filled circle)
967
+ elements.push(
968
+ ellipse({
969
+ x: cx - radius,
970
+ y: cy - radius,
971
+ width: radius * 2,
972
+ height: radius * 2,
973
+ strokeColor: color.stroke,
974
+ backgroundColor: "#ffffff",
975
+ }),
976
+ );
977
+ const innerRadius = radius * 0.5;
978
+ elements.push(
979
+ ellipse({
980
+ x: cx - innerRadius,
981
+ y: cy - innerRadius,
982
+ width: innerRadius * 2,
983
+ height: innerRadius * 2,
984
+ strokeColor: color.stroke,
985
+ backgroundColor: "#000000",
986
+ }),
987
+ );
988
+ }
989
+ }
990
+
991
+ /**
992
+ * Render choice pseudostate (small diamond).
993
+ * @param {Box} box Box (shape == `choice`).
994
+ * @param {{ stroke: string, fill: string }} color
995
+ * @param {object[]} elements
996
+ * @internal
997
+ */
998
+ function renderChoiceShape(box, color, elements) {
999
+ const cx = box.x + box.width / 2;
1000
+ const cy = box.y + box.height / 2;
1001
+ const size = Math.min(box.width, box.height) / 2 - 2;
1002
+
1003
+ elements.push(
1004
+ line({
1005
+ points: [
1006
+ { x: cx, y: cy - size },
1007
+ { x: cx + size, y: cy },
1008
+ { x: cx, y: cy + size },
1009
+ { x: cx - size, y: cy },
1010
+ { x: cx, y: cy - size },
1011
+ ],
1012
+ strokeColor: color.stroke,
1013
+ }),
1014
+ );
1015
+ }
1016
+
1017
+ /**
1018
+ * Render fork/join pseudostate (horizontal or vertical bar).
1019
+ * @param {Box} box Box (shape == `fork` or `join`).
1020
+ * @param {{ stroke: string, fill: string }} color
1021
+ * @param {object[]} elements
1022
+ * @internal
1023
+ */
1024
+ function renderForkJoinShape(box, color, elements) {
1025
+ // Fork/join are rendered as thick bars
1026
+ const r = rect({
1027
+ x: box.x,
1028
+ y: box.y,
1029
+ width: box.width,
1030
+ height: box.height,
1031
+ strokeColor: color.stroke,
1032
+ backgroundColor: "#000000",
1033
+ });
1034
+ r.strokeWidth = 3;
1035
+ elements.push(r);
1036
+ }
1037
+
1038
+ /**
1039
+ * Render history pseudostate (circle with H).
1040
+ * @param {Box} box Box (shape == `history` or `history_deep`).
1041
+ * @param {{ stroke: string, fill: string }} color
1042
+ * @param {object[]} elements
1043
+ * @internal
1044
+ */
1045
+ function renderHistoryShape(box, color, elements) {
1046
+ const cx = box.x + box.width / 2;
1047
+ const cy = box.y + box.height / 2;
1048
+ const radius = Math.min(box.width, box.height) / 2 - 2;
1049
+
1050
+ // Outer circle
1051
+ elements.push(
1052
+ ellipse({
1053
+ x: cx - radius,
1054
+ y: cy - radius,
1055
+ width: radius * 2,
1056
+ height: radius * 2,
1057
+ strokeColor: color.stroke,
1058
+ backgroundColor: "#ffffff",
1059
+ }),
1060
+ );
1061
+
1062
+ // H or H* text
1063
+ const label = box.shape === "history_deep" ? "H*" : "H";
1064
+ elements.push(
1065
+ text({
1066
+ x: box.x + 4,
1067
+ y: box.y + 4,
1068
+ width: box.width - 8,
1069
+ height: box.height - 8,
1070
+ value: label,
1071
+ fontSize: FONT.sizeDescription,
1072
+ color: color.stroke,
1073
+ align: "center",
1074
+ }),
1075
+ );
1076
+ }
1077
+
901
1078
  /**
902
1079
  * @param {Box} box
903
1080
  * @param {{ stroke: string, fill: string, titleFill: string }} color
@@ -34,6 +34,7 @@ export {
34
34
  DEFAULT_DEPLOYMENT_PLUGINS,
35
35
  DEFAULT_OBJECT_PLUGINS,
36
36
  DEFAULT_SEQUENCE_PLUGINS,
37
+ DEFAULT_STATE_PLUGINS,
37
38
  DEFAULT_USE_CASE_PLUGINS,
38
39
  DeploymentDiagramAssets,
39
40
  DeploymentDiagramDocs,
@@ -53,6 +54,15 @@ export {
53
54
  ObjectDiagramSecurity,
54
55
  ObjectDiagramTests,
55
56
  objectDiagramModule,
57
+ StateDiagramAssets,
58
+ StateDiagramDocs,
59
+ StateDiagramLayout,
60
+ StateDiagramModule,
61
+ StateDiagramParser,
62
+ StateDiagramRenderer,
63
+ StateDiagramSecurity,
64
+ StateDiagramTests,
65
+ stateDiagramModule,
56
66
  SequenceDiagramAssets,
57
67
  SequenceDiagramDocs,
58
68
  SequenceDiagramLayout,
@@ -36,6 +36,7 @@ import {
36
36
  DEFAULT_COMPONENT_PLUGINS,
37
37
  DEFAULT_OBJECT_PLUGINS,
38
38
  DEFAULT_SEQUENCE_PLUGINS,
39
+ DEFAULT_STATE_PLUGINS,
39
40
  DEFAULT_USE_CASE_PLUGINS,
40
41
  defaultDiagramModuleRegistry,
41
42
  } from "./builtin.mjs";
@@ -81,6 +82,12 @@ export { DEFAULT_USE_CASE_PLUGINS } from "./builtin.mjs";
81
82
  */
82
83
  export { DEFAULT_SEQUENCE_PLUGINS } from "./builtin.mjs";
83
84
 
85
+ /**
86
+ * Default plugin pipeline for state diagrams.
87
+ * @public
88
+ */
89
+ export { DEFAULT_STATE_PLUGINS } from "./builtin.mjs";
90
+
84
91
  const PARSE_SECURITY_BASE = createSecurityBase();
85
92
 
86
93
  /**