@standarx/graph 0.0.0-stage โ 1.1.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/LICENSE +21 -0
- package/README.fr.md +438 -0
- package/README.md +437 -2
- package/THIRD_PARTY_NOTICES.md +22 -0
- package/assets/fonts/Inter-Regular.ttf +0 -0
- package/assets/fonts/Inter-SemiBold.ttf +0 -0
- package/assets/fonts/OFL.txt +92 -0
- package/dist/adapter-0bggwh8x.js +393 -0
- package/dist/cli-4m00785g.js +20 -0
- package/dist/cli-5v9761s9.js +330 -0
- package/dist/cli-9f1pdw5q.js +462 -0
- package/dist/cli-a4ax1vkc.js +172 -0
- package/dist/cli-abzdy8pn.js +1144 -0
- package/dist/cli-gh5166k6.js +1565 -0
- package/dist/cli-m29a3wgx.js +579 -0
- package/dist/cli-mzmjkk5v.js +11 -0
- package/dist/cli-nhmh6yxk.js +2485 -0
- package/dist/cli-nyckgf1t.js +4 -0
- package/dist/cli-sfdqkbd1.js +433 -0
- package/dist/cli-txrzzr2q.js +0 -0
- package/dist/cli-vecew2na.js +709 -0
- package/dist/cli-wt9dmbhm.js +560 -0
- package/dist/cli-ywgtv1cg.js +39 -0
- package/dist/cli-z3ccx2y4.js +141 -0
- package/dist/cli.d.ts +2 -0
- package/dist/cli.js +413 -0
- package/dist/core/index.d.ts +6 -0
- package/dist/core/index.js +91 -0
- package/dist/core/spatial.d.ts +16 -0
- package/dist/core/threshold.d.ts +1 -0
- package/dist/core/view.d.ts +80 -0
- package/dist/export/index.d.ts +18 -0
- package/dist/export/index.js +170 -0
- package/dist/export/pdf.d.ts +5 -0
- package/dist/export/png.d.ts +4 -0
- package/dist/format/index.d.ts +4 -0
- package/dist/format/index.js +69 -0
- package/dist/format/json-schema.d.ts +2 -0
- package/dist/format/schema.d.ts +787 -0
- package/dist/format/semantic/er.d.ts +3 -0
- package/dist/format/semantic/graph.d.ts +3 -0
- package/dist/format/semantic/sequence.d.ts +3 -0
- package/dist/format/semantic/shared.d.ts +14 -0
- package/dist/format/semantic/state.d.ts +3 -0
- package/dist/format/semantic/tree.d.ts +3 -0
- package/dist/format/transition-label.d.ts +2 -0
- package/dist/format/validate.d.ts +11 -0
- package/dist/html/index.d.ts +3 -0
- package/dist/html/index.js +125 -0
- package/dist/html/layout-worker.d.ts +1 -0
- package/dist/html/layout-worker.generated.d.ts +1 -0
- package/dist/html/mount.d.ts +12 -0
- package/dist/html/page.d.ts +14 -0
- package/dist/html/render.d.ts +7 -0
- package/dist/html/runtime.d.ts +1 -0
- package/dist/html/runtime.generated.d.ts +1 -0
- package/dist/html/shell.d.ts +10 -0
- package/dist/html/svg-adapter.d.ts +8 -0
- package/dist/html/ui.d.ts +34 -0
- package/dist/language/actions.d.ts +3 -0
- package/dist/language/analysis.d.ts +38 -0
- package/dist/language/complete.d.ts +3 -0
- package/dist/language/diagnostics.d.ts +14 -0
- package/dist/language/docs.d.ts +11 -0
- package/dist/language/format.d.ts +17 -0
- package/dist/language/hover.d.ts +3 -0
- package/dist/language/index.d.ts +8 -0
- package/dist/language/index.js +1560 -0
- package/dist/language/navigation.d.ts +9 -0
- package/dist/language/positions.d.ts +7 -0
- package/dist/language/symbols.d.ts +3 -0
- package/dist/language/types.d.ts +46 -0
- package/dist/layout/elk.d.ts +35 -0
- package/dist/layout/er.d.ts +3 -0
- package/dist/layout/font-metrics.d.ts +9 -0
- package/dist/layout/graph.d.ts +3 -0
- package/dist/layout/index.d.ts +5 -0
- package/dist/layout/index.js +16 -0
- package/dist/layout/measure.d.ts +10 -0
- package/dist/layout/sequence.d.ts +3 -0
- package/dist/layout/shapes.d.ts +16 -0
- package/dist/layout/shared.d.ts +31 -0
- package/dist/layout/state.d.ts +3 -0
- package/dist/layout/tree.d.ts +3 -0
- package/dist/layout/types.d.ts +198 -0
- package/dist/layout-worker.generated-xsmtzrfj.js +34 -0
- package/dist/mermaid/common.d.ts +36 -0
- package/dist/mermaid/er.d.ts +3 -0
- package/dist/mermaid/graph.d.ts +4 -0
- package/dist/mermaid/index.d.ts +6 -0
- package/dist/mermaid/index.js +6 -0
- package/dist/mermaid/mindmap.d.ts +3 -0
- package/dist/mermaid/sequence.d.ts +3 -0
- package/dist/mermaid/state.d.ts +3 -0
- package/dist/remark/index.d.ts +9 -0
- package/dist/remark/index.js +102 -0
- package/dist/shared/errors.d.ts +6 -0
- package/dist/shared/package-root.d.ts +5 -0
- package/dist/svg/escape.d.ts +1 -0
- package/dist/svg/index.d.ts +3 -0
- package/dist/svg/index.js +25 -0
- package/dist/svg/render.d.ts +9 -0
- package/dist/svg/theme.d.ts +62 -0
- package/dist/svg-adapter-gq5vmp6q.js +227 -0
- package/dist/text/build.d.ts +10 -0
- package/dist/text/canonical.d.ts +10 -0
- package/dist/text/errors.d.ts +33 -0
- package/dist/text/highlight.d.ts +13 -0
- package/dist/text/index.d.ts +33 -0
- package/dist/text/index.js +25 -0
- package/dist/text/lexer.d.ts +29 -0
- package/dist/text/parser.d.ts +160 -0
- package/dist/text/print.d.ts +6 -0
- package/dist/text/slug.d.ts +1 -0
- package/dist/text/syntax.d.ts +8 -0
- package/dist/version.d.ts +1 -0
- package/dist/webgl/adapter.d.ts +4 -0
- package/dist/webgl/index.d.ts +7 -0
- package/dist/webgl/index.js +15 -0
- package/dist/webgl/runtime.d.ts +1 -0
- package/dist/webgl/runtime.generated.d.ts +1 -0
- package/grammars/standargraph.tmLanguage.json +599 -0
- package/language-configuration.json +35 -0
- package/licenses/EPL-2.0.txt +277 -0
- package/licenses/MPL-2.0.txt +373 -0
- package/package.json +133 -4
- package/schema/graph-document.v1.json +1737 -0
package/README.md
CHANGED
|
@@ -1,3 +1,438 @@
|
|
|
1
|
-
#
|
|
1
|
+
# StandarGraph
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
[](https://github.com/miralabs-tech/standargraph/actions/workflows/ci.yml) [](https://www.npmjs.com/package/@standarx/graph) [](./LICENSE) [](https://nodejs.org)
|
|
4
|
+
|
|
5
|
+
> "Declarative diagrams from JSON (graphs, sequences, state machines, entity-relation and trees), rendered to SVG, interactive HTML, PNG and PDF, with WebGL beyond 2000 graph nodes."
|
|
6
|
+
|
|
7
|
+
๐ English ยท [Franรงais](./README.fr.md)
|
|
8
|
+
|
|
9
|
+
[Quickstart](#-quickstart) ยท [Install](#-install) ยท [Features](#-features) ยท [Diagram kinds](#-diagram-kinds) ยท [Theming](./docs/theming.md) ยท [Limits](#-limits) ยท [Headless core](./docs/headless.md) ยท [Benchmark](./docs/bench.md) ยท [Changelog](./CHANGELOG.md)
|
|
10
|
+
|
|
11
|
+
[](./docs/assets/architecture.html)
|
|
12
|
+
|
|
13
|
+
[](./docs/assets/protocol.html)
|
|
14
|
+
|
|
15
|
+
Both images above come from the CLI (`examples/architecture.json` and `examples/protocol.json`). Each links to a self-contained interactive viewer: download the `.html` file and open it in a browser.
|
|
16
|
+
|
|
17
|
+
**Live demo**: the [playground](https://miralabs-tech.github.io/standargraph/) renders the text syntax or JSON as you type, offline once loaded, and every example has an interactive page: [architecture](https://miralabs-tech.github.io/standargraph/examples/architecture.html), [protocol](https://miralabs-tech.github.io/standargraph/examples/protocol.html).
|
|
18
|
+
|
|
19
|
+
---
|
|
20
|
+
|
|
21
|
+
## ๐ง What is StandarGraph?
|
|
22
|
+
|
|
23
|
+
You describe a diagram in a JSON document (`version: 1`, `kind` one of `"graph"`, `"sequence"`, `"state"`, `"er"` or `"tree"`), and StandarGraph lays it out and renders it. Nodes, edges and groups can carry optional metadata: provenance (source, confidence, tool), coverage and freshness, so a diagram produced by a tool or an agent says how far it can be trusted.
|
|
24
|
+
|
|
25
|
+
The layout and the view (camera, hit testing, culling, level of detail, hover, selection, search) form a headless core that never touches the DOM. Adapters sit on top of it: an SVG renderer, an interactive HTML page, and a WebGL renderer built on [Sigma.js](https://www.sigmajs.org) for large graphs.
|
|
26
|
+
|
|
27
|
+
Outputs are SVG, a single-file HTML page that works offline (fonts and runtime embedded, no network), PNG and PDF. PNG and PDF are rendered without a browser.
|
|
28
|
+
|
|
29
|
+
**Status: 1.1.0.**
|
|
30
|
+
|
|
31
|
+
---
|
|
32
|
+
|
|
33
|
+
## ๐ Quickstart
|
|
34
|
+
|
|
35
|
+
A minimal graph document, `graph.json`:
|
|
36
|
+
|
|
37
|
+
```json
|
|
38
|
+
{
|
|
39
|
+
"version": 1,
|
|
40
|
+
"kind": "graph",
|
|
41
|
+
"title": "Hello",
|
|
42
|
+
"nodes": [
|
|
43
|
+
{ "id": "a", "label": "Client" },
|
|
44
|
+
{ "id": "b", "label": "Server" }
|
|
45
|
+
],
|
|
46
|
+
"edges": [{ "from": "a", "to": "b", "label": "requests", "directed": true }]
|
|
47
|
+
}
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
### CLI
|
|
51
|
+
|
|
52
|
+
```sh
|
|
53
|
+
standargraph validate graph.json
|
|
54
|
+
standargraph export graph.json # graph.svg and graph.html next to the input
|
|
55
|
+
standargraph export graph.json --format svg,html,png,pdf --out out --theme dark
|
|
56
|
+
standargraph export graph.json --renderer webgl # force the WebGL page
|
|
57
|
+
standargraph export graph.json --markdown # also print a Markdown preview snippet
|
|
58
|
+
standargraph export graph.json --format mermaid # graph.mmd, for GitHub Markdown (see docs/mermaid.md)
|
|
59
|
+
standargraph layout graph.json # graph.positioned.json: every node gets its computed position
|
|
60
|
+
standargraph convert graph.json # graph.sg, the same document in the text syntax
|
|
61
|
+
standargraph convert graph.sg --to json --out out/graph.json
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
Every command reads JSON or the [text syntax](#text-syntax): the format is detected from the content, never from the file extension. `validate` exits 0 when the document is valid, 1 with one `path: message` line per JSON error (or one `file:line:col: message [code]` line per text error) otherwise, 2 when the file cannot be read. `layout` always writes JSON. `convert` writes the other format than the input unless `--to json|text` says otherwise, and exits 2 with `Output would overwrite the input` when the output is the input file.
|
|
65
|
+
|
|
66
|
+
| Option | Meaning |
|
|
67
|
+
| --- | --- |
|
|
68
|
+
| `--format <list>` | Comma-separated: `svg`, `html`, `png`, `pdf`, `mermaid` (default `svg,html`); `mermaid` writes `<base>.mmd` and prints its warnings on stderr |
|
|
69
|
+
| `--out <dir>` | Output directory (default: the input file directory) |
|
|
70
|
+
| `--name <base>` | Output base name (default: the input file name without `.json` or `.sg`) |
|
|
71
|
+
| `--theme <theme>` | `auto` (default), a palette name (`light`, `dark`, `nord`, `solarized-light`, `solarized-dark`, `high-contrast`) or a `.json` theme file, see [docs/theming.md](./docs/theming.md) |
|
|
72
|
+
| `--no-palette` | Turn off the automatic color per item `type` |
|
|
73
|
+
| `--scale <n>` | PNG scale factor (default 2) |
|
|
74
|
+
| `--renderer <name>` | HTML renderer: `auto`, `svg` or `webgl` (default `auto`) |
|
|
75
|
+
| `--markdown` | Print `[](base.html)`, a Markdown snippet linking the SVG preview to the HTML page; with `mermaid` in `--format`, a fenced `mermaid` code block follows |
|
|
76
|
+
|
|
77
|
+
### JavaScript
|
|
78
|
+
|
|
79
|
+
Every subpath is a separate entry point of `@standarx/graph`.
|
|
80
|
+
|
|
81
|
+
```ts
|
|
82
|
+
import { validate } from "@standarx/graph/format";
|
|
83
|
+
import { layout } from "@standarx/graph/layout";
|
|
84
|
+
import { renderSvg } from "@standarx/graph/svg";
|
|
85
|
+
import { renderHtml } from "@standarx/graph/html";
|
|
86
|
+
|
|
87
|
+
const result = validate(JSON.parse(text));
|
|
88
|
+
if (!result.ok) throw new Error(result.errors.map((e) => `${e.path}: ${e.message}`).join("\n"));
|
|
89
|
+
|
|
90
|
+
const scene = await layout(result.document);
|
|
91
|
+
const svg = renderSvg(scene, { theme: "light" });
|
|
92
|
+
const html = renderHtml(result.document, scene, { theme: "auto", renderer: "auto" });
|
|
93
|
+
```
|
|
94
|
+
|
|
95
|
+
All formats in one call, from `/export`:
|
|
96
|
+
|
|
97
|
+
```ts
|
|
98
|
+
import { exportDocument } from "@standarx/graph/export";
|
|
99
|
+
|
|
100
|
+
const out = await exportDocument(graphDocument, { formats: ["svg", "png", "pdf"], theme: "light", scale: 2 });
|
|
101
|
+
// out.svg is a string, out.png and out.pdf are Uint8Array
|
|
102
|
+
```
|
|
103
|
+
|
|
104
|
+
Mermaid text for GitHub Markdown, from `/mermaid` (`formats: ["mermaid"]` in `exportDocument()` returns the same text as a string, without the warnings):
|
|
105
|
+
|
|
106
|
+
```ts
|
|
107
|
+
import { toMermaid } from "@standarx/graph/mermaid";
|
|
108
|
+
|
|
109
|
+
const { text, warnings } = toMermaid(graphDocument);
|
|
110
|
+
```
|
|
111
|
+
|
|
112
|
+
Mount an interactive graph in a page (`mount(container, document, { theme, title, renderer })`). When every node has a `position`, ELK is skipped; otherwise the layout runs in a Web Worker and the main thread stays free. Several instances can live on one page:
|
|
113
|
+
|
|
114
|
+
```ts
|
|
115
|
+
import { mount } from "@standarx/graph/html";
|
|
116
|
+
|
|
117
|
+
const { view, destroy } = await mount(document.getElementById("graph")!, graphDocument, { renderer: "auto" });
|
|
118
|
+
```
|
|
119
|
+
|
|
120
|
+
Markdown pipelines, with the remark plugin (it turns ` ```standargraph ` and ` ```sg ` code blocks holding a JSON document or the text syntax into an inline SVG, linked to a standalone HTML page when `outDir` is set):
|
|
121
|
+
|
|
122
|
+
```ts
|
|
123
|
+
import { unified } from "unified";
|
|
124
|
+
import remarkParse from "remark-parse";
|
|
125
|
+
import { remarkStandargraph } from "@standarx/graph/remark";
|
|
126
|
+
|
|
127
|
+
unified().use(remarkParse).use(remarkStandargraph, { outDir: "public/diagrams", publicPath: "/diagrams", theme: "auto" });
|
|
128
|
+
```
|
|
129
|
+
|
|
130
|
+
The headless core, for your own renderer (see [docs/headless.md](./docs/headless.md)):
|
|
131
|
+
|
|
132
|
+
```ts
|
|
133
|
+
import { createView, layout } from "@standarx/graph/core";
|
|
134
|
+
|
|
135
|
+
const view = createView(await layout(graphDocument));
|
|
136
|
+
view.setViewport(1280, 800);
|
|
137
|
+
view.fit();
|
|
138
|
+
view.subscribe(() => draw(view));
|
|
139
|
+
```
|
|
140
|
+
|
|
141
|
+
The editor features of the text syntax, with no language server dependency (see [docs/language-service.md](./docs/language-service.md)):
|
|
142
|
+
|
|
143
|
+
```ts
|
|
144
|
+
import { codeActions, complete, diagnostics, format } from "@standarx/graph/language";
|
|
145
|
+
|
|
146
|
+
const items = complete(source, { line: 2, character: 3 });
|
|
147
|
+
const edits = format(source);
|
|
148
|
+
const problems = diagnostics(source);
|
|
149
|
+
const fixes = codeActions(source, problems[0].range);
|
|
150
|
+
```
|
|
151
|
+
|
|
152
|
+
---
|
|
153
|
+
|
|
154
|
+
## ๐งฉ Diagram kinds
|
|
155
|
+
|
|
156
|
+
Every document has `version: 1` and a `kind`. The files in [examples](./examples) are complete documents for each kind.
|
|
157
|
+
|
|
158
|
+
### `graph` and `sequence`
|
|
159
|
+
|
|
160
|
+
`graph` holds `nodes`, `edges` and nested `groups`; `sequence` holds `participants` and `messages`. See the quickstart above and `examples/architecture.json` and `examples/protocol.json`.
|
|
161
|
+
|
|
162
|
+
### `state`
|
|
163
|
+
|
|
164
|
+
States, optional pseudo-states (`initial`, `final`, `choice`, `fork`, `join`, `history`), composite states through `parent`, and transitions with `event`, `guard` and `action`. From `examples/order-state.json`:
|
|
165
|
+
|
|
166
|
+
```json
|
|
167
|
+
{
|
|
168
|
+
"version": 1,
|
|
169
|
+
"kind": "state",
|
|
170
|
+
"title": "Order lifecycle",
|
|
171
|
+
"direction": "right",
|
|
172
|
+
"states": [
|
|
173
|
+
{ "id": "__initial", "pseudo": "initial" },
|
|
174
|
+
{ "id": "pending", "label": "Pending", "actions": ["entry / reserve stock"] },
|
|
175
|
+
{ "id": "paid", "label": "Paid" },
|
|
176
|
+
{ "id": "__final", "pseudo": "final" }
|
|
177
|
+
],
|
|
178
|
+
"transitions": [
|
|
179
|
+
{ "from": "__initial", "to": "pending" },
|
|
180
|
+
{ "from": "pending", "to": "paid", "event": "payment received" },
|
|
181
|
+
{ "from": "paid", "to": "__final" }
|
|
182
|
+
]
|
|
183
|
+
}
|
|
184
|
+
```
|
|
185
|
+
|
|
186
|
+
### `er`
|
|
187
|
+
|
|
188
|
+
Entities with attributes (`keys`: `pk`, `fk`, `uk`; `nullable`; `note`) and relations drawn with crow's foot cardinalities (`one`, `zero-or-one`, `one-or-more`, `zero-or-more`). From `examples/shop-er.json`:
|
|
189
|
+
|
|
190
|
+
```json
|
|
191
|
+
{
|
|
192
|
+
"version": 1,
|
|
193
|
+
"kind": "er",
|
|
194
|
+
"title": "Shop orders",
|
|
195
|
+
"entities": [
|
|
196
|
+
{
|
|
197
|
+
"id": "customer",
|
|
198
|
+
"label": "Customer",
|
|
199
|
+
"attributes": [
|
|
200
|
+
{ "name": "id", "type": "uuid", "keys": ["pk"] },
|
|
201
|
+
{ "name": "email", "type": "varchar(255)", "keys": ["uk"] }
|
|
202
|
+
]
|
|
203
|
+
},
|
|
204
|
+
{
|
|
205
|
+
"id": "order",
|
|
206
|
+
"label": "Order",
|
|
207
|
+
"attributes": [
|
|
208
|
+
{ "name": "id", "type": "uuid", "keys": ["pk"] },
|
|
209
|
+
{ "name": "customer_id", "type": "uuid", "keys": ["fk"] }
|
|
210
|
+
]
|
|
211
|
+
}
|
|
212
|
+
],
|
|
213
|
+
"relations": [
|
|
214
|
+
{ "from": "customer", "to": "order", "fromCardinality": "one", "toCardinality": "zero-or-more", "label": "places" }
|
|
215
|
+
]
|
|
216
|
+
}
|
|
217
|
+
```
|
|
218
|
+
|
|
219
|
+
### `tree`
|
|
220
|
+
|
|
221
|
+
A flat list of nodes linked by `parent`, laid out as a tidy tree (`"layout": "tree"`, the default, with a `direction`) or as a two-sided mindmap around the root (`"layout": "mindmap"`). From `examples/repo-tree.json` and `examples/roadmap-mindmap.json`:
|
|
222
|
+
|
|
223
|
+
```json
|
|
224
|
+
{
|
|
225
|
+
"version": 1,
|
|
226
|
+
"kind": "tree",
|
|
227
|
+
"title": "Repository layout",
|
|
228
|
+
"layout": "mindmap",
|
|
229
|
+
"nodes": [
|
|
230
|
+
{ "id": "repo", "label": "standargraph", "shape": "pill" },
|
|
231
|
+
{ "id": "src", "label": "src", "parent": "repo" },
|
|
232
|
+
{ "id": "format", "label": "format", "parent": "src" },
|
|
233
|
+
{ "id": "tests", "label": "tests", "parent": "repo" }
|
|
234
|
+
]
|
|
235
|
+
}
|
|
236
|
+
```
|
|
237
|
+
|
|
238
|
+
### Shapes
|
|
239
|
+
|
|
240
|
+
`shape` on a `graph` or `tree` node is one of `box` (the default), `rect`, `pill`, `diamond`, `circle`, `ellipse`, `hexagon`, `parallelogram`, `cylinder`, `document` and `subroutine`. Edges end on the outline of the shape, so a flowchart is a `graph` with shapes (`examples/deploy-flowchart.json`):
|
|
241
|
+
|
|
242
|
+
```json
|
|
243
|
+
{
|
|
244
|
+
"version": 1,
|
|
245
|
+
"kind": "graph",
|
|
246
|
+
"direction": "down",
|
|
247
|
+
"nodes": [
|
|
248
|
+
{ "id": "build", "label": "Build image", "shape": "rect" },
|
|
249
|
+
{ "id": "green", "label": "Green?", "shape": "diamond" },
|
|
250
|
+
{ "id": "done", "label": "Live", "shape": "pill" }
|
|
251
|
+
],
|
|
252
|
+
"edges": [
|
|
253
|
+
{ "from": "build", "to": "green", "directed": true },
|
|
254
|
+
{ "from": "green", "to": "done", "label": "yes", "directed": true }
|
|
255
|
+
]
|
|
256
|
+
}
|
|
257
|
+
```
|
|
258
|
+
|
|
259
|
+
Shapes live in the document; colors never do. They come from the theme.
|
|
260
|
+
|
|
261
|
+
### Text syntax
|
|
262
|
+
|
|
263
|
+
Every kind can also be written as plain text, in files conventionally named `.sg`. A graph in the symbol form:
|
|
264
|
+
|
|
265
|
+
```
|
|
266
|
+
graph "Release flow" [direction=right]
|
|
267
|
+
|
|
268
|
+
live "Live" [shape=pill]
|
|
269
|
+
group ci "CI" {
|
|
270
|
+
build "Build image" [shape=rect]
|
|
271
|
+
check "Green?" [shape=diamond]
|
|
272
|
+
}
|
|
273
|
+
|
|
274
|
+
build -> check
|
|
275
|
+
check -> live "yes"
|
|
276
|
+
```
|
|
277
|
+
|
|
278
|
+
The same graph in the word form, where `to`, `with`, `async`, `reply` and `via` replace the operators and `do` ... `end` replaces the braces:
|
|
279
|
+
|
|
280
|
+
```
|
|
281
|
+
graph "Release flow" [direction=right]
|
|
282
|
+
|
|
283
|
+
live "Live" [shape=pill]
|
|
284
|
+
group ci "CI" do
|
|
285
|
+
build "Build image" [shape=rect]
|
|
286
|
+
check "Green?" [shape=diamond]
|
|
287
|
+
end
|
|
288
|
+
|
|
289
|
+
build to check
|
|
290
|
+
check to live "yes"
|
|
291
|
+
```
|
|
292
|
+
|
|
293
|
+
Both forms read to the same document. `examples/` holds a `.sg` twin of every JSON example. The `/text` subpath exports `parse`, `print`, `canonicalize`, `sniff` and `loadSource`; a string passed to `mount()` or `exportDocument()` goes through `loadSource`, and `standargraph convert` turns one format into the other. In Markdown, a ` ```sg ` fence (or ` ```standargraph `) holds either format:
|
|
294
|
+
|
|
295
|
+
````md
|
|
296
|
+
```sg
|
|
297
|
+
graph "Release flow"
|
|
298
|
+
|
|
299
|
+
build -> check
|
|
300
|
+
```
|
|
301
|
+
````
|
|
302
|
+
|
|
303
|
+
#### Syntax highlighting
|
|
304
|
+
|
|
305
|
+
The package ships a TextMate grammar (`@standarx/graph/grammars/standargraph.tmLanguage.json`, scope `source.standargraph`), a `language-configuration.json` and `highlight(source)` in the `/text` subpath, which returns tokens typed with the LSP semantic token types. The online demo colors its editor with `highlight()`. A VS Code extension will consume these files from its own repository. See [docs/syntax-highlighting.md](./docs/syntax-highlighting.md).
|
|
306
|
+
|
|
307
|
+
### Theming
|
|
308
|
+
|
|
309
|
+
A theme is a set of color tokens plus optional colors per node `type`, given as `--theme <file.json>` on the CLI or as the `theme` option of the API. Six palettes come ready to use, as `theme: "nord"` or `--theme nord`: `light`, `dark`, `nord`, `solarized-light`, `solarized-dark` and `high-contrast`, each with a contrast of at least 4.5:1 for its text.
|
|
310
|
+
|
|
311
|
+
- A typed item with no color of its own gets one from the palette of the theme, chosen by a stable hash of its `type`. `palette: false` in the theme, or `--no-palette`, turns it off, and a `types` entry always wins.
|
|
312
|
+
- With `"auto"` or a `{ light, dark }` pair, the interactive page and `mount()` show a toolbar button that cycles `auto`, `light` and `dark`, kept in `localStorage`.
|
|
313
|
+
- The online demo has a theme panel: a palette, the tokens, a color per type, and a `theme.json` to download for `--theme`.
|
|
314
|
+
|
|
315
|
+
See [docs/theming.md](./docs/theming.md).
|
|
316
|
+
|
|
317
|
+
### GitHub Action
|
|
318
|
+
|
|
319
|
+
The composite action at the root of the repository renders your `.sg` files with the published CLI and never commits or pushes.
|
|
320
|
+
|
|
321
|
+
```yaml
|
|
322
|
+
- uses: actions/checkout@v4
|
|
323
|
+
- uses: miralabs-tech/standargraph@v1
|
|
324
|
+
with:
|
|
325
|
+
files: "docs/**/*.sg"
|
|
326
|
+
mode: check
|
|
327
|
+
```
|
|
328
|
+
|
|
329
|
+
| Input | Default | Meaning |
|
|
330
|
+
| --- | --- | --- |
|
|
331
|
+
| `files` | `**/*.sg` | Files to render |
|
|
332
|
+
| `formats` | `svg` | Export formats |
|
|
333
|
+
| `theme` | `light` | Theme of the render |
|
|
334
|
+
| `out` | empty (next to the source) | Output directory |
|
|
335
|
+
| `version` | the package version of the action ref | npm version of `@standarx/graph` to run |
|
|
336
|
+
| `mode` | `write` | `write` renders; `check` renders and fails, listing the files, when an output differs from the working tree or is missing |
|
|
337
|
+
| `cli-path` | empty | Path of a locally built `dist/cli.js`, used instead of the npm package (CI of this repository) |
|
|
338
|
+
|
|
339
|
+
[docs/diagrams-workflow.yml](./docs/diagrams-workflow.yml) is an example workflow that renders on push and commits the result with plain `git` commands. Copy it to `.github/workflows/diagrams.yml`.
|
|
340
|
+
|
|
341
|
+
---
|
|
342
|
+
|
|
343
|
+
## ๐ฆ Install
|
|
344
|
+
|
|
345
|
+
```sh
|
|
346
|
+
npm install @standarx/graph
|
|
347
|
+
bun add @standarx/graph
|
|
348
|
+
```
|
|
349
|
+
|
|
350
|
+
Node >= 20. The CLI is the `standargraph` binary. Once the package is installed, `npx standargraph` or `bunx standargraph` runs it; without installing, name the package:
|
|
351
|
+
|
|
352
|
+
```sh
|
|
353
|
+
npx @standarx/graph export graph.json
|
|
354
|
+
bunx @standarx/graph export graph.json
|
|
355
|
+
npm install -g @standarx/graph # then: standargraph export graph.json
|
|
356
|
+
```
|
|
357
|
+
|
|
358
|
+
---
|
|
359
|
+
|
|
360
|
+
## โจ Features
|
|
361
|
+
|
|
362
|
+
- **Format v1**: JSON documents of five kinds, `graph` (nodes, edges, nested groups, optional fixed `position`), `sequence` (participants, messages), `state`, `er` and `tree` (see [Diagram kinds](#-diagram-kinds)), validated against a published [JSON Schema](./schema/graph-document.v1.json), with a `validate()` that returns one error per problem and its path.
|
|
363
|
+
- **Metadata**: provenance (`confirmed`, `inferred`, `unknown`), coverage and freshness on documents, nodes, edges and groups; low-confidence items are drawn muted.
|
|
364
|
+
- **Layout**: ELK layered layout for graphs, groups, state machines and entity-relation diagrams, a dedicated layout for sequence diagrams, a tidy or mindmap layout for trees, text measured with embedded Inter metrics so SVG and HTML agree.
|
|
365
|
+
- **Shapes**: 11 node shapes on `graph` and `tree` nodes, drawn in SVG and cut at the outline by the edges (see [Shapes](#shapes)).
|
|
366
|
+
- **Theming**: six named palettes, an automatic color per node `type`, a light, dark and auto switch, color tokens and colors per node `type`, one object for SVG, HTML, PNG and PDF, a `--theme <name|file.json>` option (see [docs/theming.md](./docs/theming.md)).
|
|
367
|
+
- **Renderers**: SVG, interactive HTML (pan, zoom, hover, selection, search, panel, keyboard, light and dark themes), and WebGL through Sigma.js.
|
|
368
|
+
- **WebGL above 2000 nodes**: the HTML export of a `graph` switches to WebGL automatically past 2000 nodes (`--renderer` overrides it). On the v1 gate, 10 000 nodes in WebGL hold a median of 303 FPS (p5 285.7) with the display refresh as the cap, and a median of 58.1 FPS (p5 54.3) uncapped, on an Intel Core i7-14700KF with an NVIDIA GeForce RTX 4070 Ti SUPER in Microsoft Edge 157. Details in [docs/bench.md](./docs/bench.md).
|
|
369
|
+
- **Offline single-file HTML**: fonts and runtime are embedded, nothing is fetched.
|
|
370
|
+
- **Export**: SVG, HTML, PNG and PDF from the CLI or `exportDocument()`, PNG and PDF without a browser (resvg WASM and PDFKit).
|
|
371
|
+
- **Headless core**: view controller with camera, hit testing, culling, level of detail and highlight, usable in Node, Bun, a worker or a browser.
|
|
372
|
+
- **Text syntax**: every kind as plain text (`.sg`), in a symbol or a word form, with line and column errors, `print()` back to text and `standargraph convert` between the two formats (see [Text syntax](#text-syntax)).
|
|
373
|
+
- **Mermaid export**: every kind as Mermaid text with `toMermaid()` or `--format mermaid`, with the losses reported as warnings (see [docs/mermaid.md](./docs/mermaid.md)).
|
|
374
|
+
- **Embedding**: `mount()` for applications, with an on-demand layout worker, and a remark plugin for Markdown.
|
|
375
|
+
|
|
376
|
+
---
|
|
377
|
+
|
|
378
|
+
## ๐ง Limits
|
|
379
|
+
|
|
380
|
+
- **Layout of large graphs is slow.** ELK lays out 10 000 nodes in about 44 s (5 000 nodes: 13 s, 2 000: 3.7 s; see [docs/bench.md](./docs/bench.md)). Rendering is not the bottleneck. A faster layout for large graphs is coming soon.
|
|
381
|
+
- **Precompute positions for large graphs.** Once every node has a `position`, ELK is skipped by `layout()`, `mount()` and the exports. `standargraph export` runs the layout once and the HTML page it writes carries the result: opening it never lays anything out again. To keep positions in your documents, run `standargraph layout graph.json` (or `--out <file>`): it writes the same document with a `position` on every node, which then renders without ELK.
|
|
382
|
+
|
|
383
|
+
- The remark plugin output does not render on GitHub. In a README, use the SVG written by the CLI, linked to its HTML page (`--markdown` prints the snippet).
|
|
384
|
+
- Node type captions, edge labels and arrowheads are not drawn by the WebGL renderer, and `sequence`, `state`, `er` and `tree` diagrams are always drawn as SVG.
|
|
385
|
+
|
|
386
|
+
---
|
|
387
|
+
|
|
388
|
+
## ๐ Documentation
|
|
389
|
+
|
|
390
|
+
- [Headless core and adapters](./docs/headless.md)
|
|
391
|
+
- [Theming](./docs/theming.md)
|
|
392
|
+
- [Syntax highlighting for `.sg`](./docs/syntax-highlighting.md)
|
|
393
|
+
- [Language service for `.sg`](./docs/language-service.md)
|
|
394
|
+
- [Mermaid export](./docs/mermaid.md)
|
|
395
|
+
- [Benchmark and layout times](./docs/bench.md)
|
|
396
|
+
- [JSON Schema of the format v1](./schema/graph-document.v1.json)
|
|
397
|
+
- [Examples](./examples)
|
|
398
|
+
- [Changelog](./CHANGELOG.md)
|
|
399
|
+
|
|
400
|
+
---
|
|
401
|
+
|
|
402
|
+
## ๐ ๏ธ Build & tests
|
|
403
|
+
|
|
404
|
+
```sh
|
|
405
|
+
bun install
|
|
406
|
+
bun run typecheck
|
|
407
|
+
bun test
|
|
408
|
+
bun run build
|
|
409
|
+
bun run smoke # the packed package, under Node
|
|
410
|
+
STANDARGRAPH_BROWSER_CHANNEL=msedge bun run test:browser # Playwright, set the channel of an installed browser
|
|
411
|
+
bun run bench # benchmark (Microsoft Edge, headed)
|
|
412
|
+
bun run runtime # regenerate the embedded HTML and WebGL runtimes
|
|
413
|
+
bun run site # build the GitHub Pages site into site-dist/
|
|
414
|
+
```
|
|
415
|
+
|
|
416
|
+
CI pins bun 1.4.2 so that the generated bundles match the committed ones; use the same version before running `bun run runtime`.
|
|
417
|
+
|
|
418
|
+
---
|
|
419
|
+
|
|
420
|
+
## ๐ค Contributing
|
|
421
|
+
|
|
422
|
+
Issues and pull requests are welcome at [github.com/miralabs-tech/standargraph](https://github.com/miralabs-tech/standargraph). Run typecheck, tests, build and smoke test before opening a pull request.
|
|
423
|
+
|
|
424
|
+
---
|
|
425
|
+
|
|
426
|
+
## โค๏ธ Support
|
|
427
|
+
|
|
428
|
+
If StandarGraph helps you:
|
|
429
|
+
|
|
430
|
+
๐ [Star the repo](https://github.com/miralabs-tech/standargraph) ยท [Open an issue](https://github.com/miralabs-tech/standargraph/issues)
|
|
431
|
+
|
|
432
|
+
---
|
|
433
|
+
|
|
434
|
+
## ๐ License
|
|
435
|
+
|
|
436
|
+
[MIT](./LICENSE) - Copyright (c) 2026 Wesley Cormier.
|
|
437
|
+
|
|
438
|
+
Third-party components keep their own licenses: see [THIRD_PARTY_NOTICES.md](./THIRD_PARTY_NOTICES.md) and the texts in [licenses/](./licenses) (elkjs is EPL-2.0 OR GPL-3.0-or-later, resvg is MPL-2.0, Inter is SIL OFL 1.1).
|
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
# Third-party notices
|
|
2
|
+
|
|
3
|
+
Runtime dependencies and bundled assets, with the license each package declares.
|
|
4
|
+
|
|
5
|
+
| Component | Version | License |
|
|
6
|
+
| --- | --- | --- |
|
|
7
|
+
| elkjs | 0.12.1 | EPL-2.0 OR GPL-3.0-or-later (`licenses/EPL-2.0.txt`) |
|
|
8
|
+
| @sinclair/typebox | 0.34.52 | MIT |
|
|
9
|
+
| @resvg/resvg-wasm | 2.6.2 | MPL-2.0 (`licenses/MPL-2.0.txt`) |
|
|
10
|
+
| pdfkit | 0.20.2 | MIT |
|
|
11
|
+
| svg-to-pdfkit | 0.1.8 | MIT |
|
|
12
|
+
| sigma | 4.0.6 | MIT |
|
|
13
|
+
| graphology | 0.26.0 | MIT |
|
|
14
|
+
| graphology-utils (via sigma) | 2.5.2 | MIT |
|
|
15
|
+
| events (via sigma and graphology) | 3.3.0 | MIT |
|
|
16
|
+
| Inter (`assets/fonts/`) | โ | SIL OFL 1.1 (`assets/fonts/OFL.txt`) |
|
|
17
|
+
|
|
18
|
+
## Where each component ends up
|
|
19
|
+
|
|
20
|
+
- The self-contained HTML pages written by the CLI embed sigma, graphology and their MIT dependencies in the WebGL page only (`--renderer webgl`, or `auto` above the node threshold), and Inter in every page. They never embed ELK: positions are computed by the CLI before the page is written, so the pages carry no ELK notice.
|
|
21
|
+
- `mount` (`@standarx/graph/html`) runs the layout of a document without positions in a Web Worker. The worker source is an inline bundle of the layout code and elkjs, shipped inside the `mount` module and loaded from a Blob URL. Applications that bundle `mount` therefore ship elkjs (EPL-2.0 OR GPL-3.0-or-later) in their own bundle and take on its notice, as they do with any use of `@standarx/graph/layout`.
|
|
22
|
+
- playwright-core 1.65.1 (Apache-2.0) is a development dependency of the benchmark in `bench/` and is not part of the published package.
|
|
Binary file
|
|
Binary file
|
|
@@ -0,0 +1,92 @@
|
|
|
1
|
+
Copyright (c) 2016 The Inter Project Authors (https://github.com/rsms/inter)
|
|
2
|
+
|
|
3
|
+
This Font Software is licensed under the SIL Open Font License, Version 1.1.
|
|
4
|
+
This license is copied below, and is also available with a FAQ at:
|
|
5
|
+
http://scripts.sil.org/OFL
|
|
6
|
+
|
|
7
|
+
-----------------------------------------------------------
|
|
8
|
+
SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
|
|
9
|
+
-----------------------------------------------------------
|
|
10
|
+
|
|
11
|
+
PREAMBLE
|
|
12
|
+
The goals of the Open Font License (OFL) are to stimulate worldwide
|
|
13
|
+
development of collaborative font projects, to support the font creation
|
|
14
|
+
efforts of academic and linguistic communities, and to provide a free and
|
|
15
|
+
open framework in which fonts may be shared and improved in partnership
|
|
16
|
+
with others.
|
|
17
|
+
|
|
18
|
+
The OFL allows the licensed fonts to be used, studied, modified and
|
|
19
|
+
redistributed freely as long as they are not sold by themselves. The
|
|
20
|
+
fonts, including any derivative works, can be bundled, embedded,
|
|
21
|
+
redistributed and/or sold with any software provided that any reserved
|
|
22
|
+
names are not used by derivative works. The fonts and derivatives,
|
|
23
|
+
however, cannot be released under any other type of license. The
|
|
24
|
+
requirement for fonts to remain under this license does not apply
|
|
25
|
+
to any document created using the fonts or their derivatives.
|
|
26
|
+
|
|
27
|
+
DEFINITIONS
|
|
28
|
+
"Font Software" refers to the set of files released by the Copyright
|
|
29
|
+
Holder(s) under this license and clearly marked as such. This may
|
|
30
|
+
include source files, build scripts and documentation.
|
|
31
|
+
|
|
32
|
+
"Reserved Font Name" refers to any names specified as such after the
|
|
33
|
+
copyright statement(s).
|
|
34
|
+
|
|
35
|
+
"Original Version" refers to the collection of Font Software components as
|
|
36
|
+
distributed by the Copyright Holder(s).
|
|
37
|
+
|
|
38
|
+
"Modified Version" refers to any derivative made by adding to, deleting,
|
|
39
|
+
or substituting -- in part or in whole -- any of the components of the
|
|
40
|
+
Original Version, by changing formats or by porting the Font Software to a
|
|
41
|
+
new environment.
|
|
42
|
+
|
|
43
|
+
"Author" refers to any designer, engineer, programmer, technical
|
|
44
|
+
writer or other person who contributed to the Font Software.
|
|
45
|
+
|
|
46
|
+
PERMISSION AND CONDITIONS
|
|
47
|
+
Permission is hereby granted, free of charge, to any person obtaining
|
|
48
|
+
a copy of the Font Software, to use, study, copy, merge, embed, modify,
|
|
49
|
+
redistribute, and sell modified and unmodified copies of the Font
|
|
50
|
+
Software, subject to the following conditions:
|
|
51
|
+
|
|
52
|
+
1) Neither the Font Software nor any of its individual components,
|
|
53
|
+
in Original or Modified Versions, may be sold by itself.
|
|
54
|
+
|
|
55
|
+
2) Original or Modified Versions of the Font Software may be bundled,
|
|
56
|
+
redistributed and/or sold with any software, provided that each copy
|
|
57
|
+
contains the above copyright notice and this license. These can be
|
|
58
|
+
included either as stand-alone text files, human-readable headers or
|
|
59
|
+
in the appropriate machine-readable metadata fields within text or
|
|
60
|
+
binary files as long as those fields can be easily viewed by the user.
|
|
61
|
+
|
|
62
|
+
3) No Modified Version of the Font Software may use the Reserved Font
|
|
63
|
+
Name(s) unless explicit written permission is granted by the corresponding
|
|
64
|
+
Copyright Holder. This restriction only applies to the primary font name as
|
|
65
|
+
presented to the users.
|
|
66
|
+
|
|
67
|
+
4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
|
|
68
|
+
Software shall not be used to promote, endorse or advertise any
|
|
69
|
+
Modified Version, except to acknowledge the contribution(s) of the
|
|
70
|
+
Copyright Holder(s) and the Author(s) or with their explicit written
|
|
71
|
+
permission.
|
|
72
|
+
|
|
73
|
+
5) The Font Software, modified or unmodified, in part or in whole,
|
|
74
|
+
must be distributed entirely under this license, and must not be
|
|
75
|
+
distributed under any other license. The requirement for fonts to
|
|
76
|
+
remain under this license does not apply to any document created
|
|
77
|
+
using the Font Software.
|
|
78
|
+
|
|
79
|
+
TERMINATION
|
|
80
|
+
This license becomes null and void if any of the above conditions are
|
|
81
|
+
not met.
|
|
82
|
+
|
|
83
|
+
DISCLAIMER
|
|
84
|
+
THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
|
|
85
|
+
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
|
|
86
|
+
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
|
|
87
|
+
OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
|
|
88
|
+
COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
|
|
89
|
+
INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
|
|
90
|
+
DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
|
|
91
|
+
FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
|
|
92
|
+
OTHER DEALINGS IN THE FONT SOFTWARE.
|