@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 +63 -2
- package/index.mjs +10 -0
- package/package.json +2 -2
- package/src/diagrams/index.mjs +17 -0
- package/src/diagrams/state/assets.mjs +22 -0
- package/src/diagrams/state/docs/coverage_examples.mjs +77 -0
- package/src/diagrams/state/docs.mjs +27 -0
- package/src/diagrams/state/layout.mjs +30 -0
- package/src/diagrams/state/module.mjs +99 -0
- package/src/diagrams/state/parser.mjs +74 -0
- package/src/diagrams/state/plugins/syntax.mjs +291 -0
- package/src/diagrams/state/render.mjs +22 -0
- package/src/diagrams/state/security.mjs +18 -0
- package/src/diagrams/state/tests/output.mjs +24 -0
- package/src/diagrams/state/tests/state_components.test.mjs +147 -0
- package/src/diagrams/state/tests.mjs +20 -0
- package/src/general/layout/sizing.mjs +42 -0
- package/src/general/model/diagram.mjs +8 -0
- package/src/general/render/excalidraw.mjs +177 -0
- package/src/main/builtin.mjs +10 -0
- package/src/main/parser.mjs +7 -0
package/README.md
CHANGED
|
@@ -7,7 +7,7 @@
|
|
|
7
7
|
[](https://nodejs.org)
|
|
8
8
|
[](./LICENSE)
|
|
9
9
|
|
|
10
|
-
> PlantUML → ELK layout → Excalidraw renderer with a plugin-based parser. · **v0.
|
|
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 **
|
|
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.
|
|
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",
|
package/src/diagrams/index.mjs
CHANGED
|
@@ -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);
|
|
@@ -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
|
package/src/main/builtin.mjs
CHANGED
|
@@ -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,
|
package/src/main/parser.mjs
CHANGED
|
@@ -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
|
/**
|