@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/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Wesley Cormier
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in
|
|
13
|
+
all copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.fr.md
ADDED
|
@@ -0,0 +1,438 @@
|
|
|
1
|
+
# StandarGraph
|
|
2
|
+
|
|
3
|
+
[](https://github.com/miralabs-tech/standargraph/actions/workflows/ci.yml) [](https://www.npmjs.com/package/@standarx/graph) [](./LICENSE) [](https://nodejs.org)
|
|
4
|
+
|
|
5
|
+
> "Diagrammes déclaratifs à partir de JSON (graphes, séquences, machines à états, entité-relation et arbres), rendus en SVG, HTML interactif, PNG et PDF, avec WebGL au-delà de 2000 nœuds de graphe."
|
|
6
|
+
|
|
7
|
+
📖 [English](./README.md) · Français
|
|
8
|
+
|
|
9
|
+
[Démarrage rapide](#-démarrage-rapide) · [Installation](#-installation) · [Fonctionnalités](#-fonctionnalités) · [Types de diagrammes](#-types-de-diagrammes) · [Thèmes](./docs/theming.md) · [Limites](#-limites) · [Cœur headless](./docs/headless.md) · [Benchmark](./docs/bench.md) · [Changelog](./CHANGELOG.md)
|
|
10
|
+
|
|
11
|
+
[](./docs/assets/architecture.html)
|
|
12
|
+
|
|
13
|
+
[](./docs/assets/protocol.html)
|
|
14
|
+
|
|
15
|
+
Les deux images ci-dessus sont produites par la CLI (`examples/architecture.json` et `examples/protocol.json`). Chacune renvoie vers un visualiseur interactif autonome : téléchargez le fichier `.html` et ouvrez-le dans un navigateur.
|
|
16
|
+
|
|
17
|
+
**Démo en ligne** : le [playground](https://miralabs-tech.github.io/standargraph/) affiche la syntaxe texte ou le JSON pendant la frappe, hors ligne une fois chargé, et chaque exemple a une page interactive : [architecture](https://miralabs-tech.github.io/standargraph/examples/architecture.html), [protocol](https://miralabs-tech.github.io/standargraph/examples/protocol.html).
|
|
18
|
+
|
|
19
|
+
---
|
|
20
|
+
|
|
21
|
+
## 🧠 Qu'est-ce que StandarGraph ?
|
|
22
|
+
|
|
23
|
+
Vous décrivez un diagramme dans un document JSON (`version: 1`, `kind` parmi `"graph"`, `"sequence"`, `"state"`, `"er"` ou `"tree"`), et StandarGraph le met en page et le rend. Les nœuds, arêtes et groupes peuvent porter des métadonnées facultatives : provenance (source, confiance, outil), couverture et fraîcheur, pour qu'un diagramme produit par un outil ou un agent dise à quel point on peut s'y fier.
|
|
24
|
+
|
|
25
|
+
La mise en page et la vue (caméra, hit testing, culling, niveau de détail, survol, sélection, recherche) forment un cœur headless qui ne touche jamais au DOM. Des adaptateurs se posent dessus : un rendu SVG, une page HTML interactive, et un rendu WebGL basé sur [Sigma.js](https://www.sigmajs.org) pour les grands graphes.
|
|
26
|
+
|
|
27
|
+
Les sorties sont le SVG, une page HTML en un seul fichier qui fonctionne hors ligne (polices et runtime embarqués, aucun accès réseau), le PNG et le PDF. Le PNG et le PDF sont rendus sans navigateur.
|
|
28
|
+
|
|
29
|
+
**Statut : 1.1.0.**
|
|
30
|
+
|
|
31
|
+
---
|
|
32
|
+
|
|
33
|
+
## 🚀 Démarrage rapide
|
|
34
|
+
|
|
35
|
+
Un document de graphe minimal, `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 et graph.html à côté du fichier d'entrée
|
|
55
|
+
standargraph export graph.json --format svg,html,png,pdf --out out --theme dark
|
|
56
|
+
standargraph export graph.json --renderer webgl # force la page WebGL
|
|
57
|
+
standargraph export graph.json --markdown # affiche aussi un extrait Markdown d'aperçu
|
|
58
|
+
standargraph export graph.json --format mermaid # graph.mmd, pour le Markdown de GitHub (voir docs/mermaid.md)
|
|
59
|
+
standargraph layout graph.json # graph.positioned.json : chaque nœud reçoit sa position calculée
|
|
60
|
+
standargraph convert graph.json # graph.sg, le même document en syntaxe texte
|
|
61
|
+
standargraph convert graph.sg --to json --out out/graph.json
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
Chaque commande lit du JSON ou la [syntaxe texte](#syntaxe-texte) : le format est détecté par le contenu, jamais par l'extension du fichier. `validate` sort avec le code 0 quand le document est valide, 1 avec une ligne `chemin: message` par erreur JSON (ou une ligne `fichier:ligne:col: message [code]` par erreur de texte) sinon, 2 quand le fichier n'est pas lisible. `layout` écrit toujours du JSON. `convert` écrit l'autre format que celui de l'entrée, sauf si `--to json|text` en décide autrement, et sort avec le code 2 et `Output would overwrite the input` quand la sortie est le fichier d'entrée.
|
|
65
|
+
|
|
66
|
+
| Option | Rôle |
|
|
67
|
+
| --- | --- |
|
|
68
|
+
| `--format <liste>` | Liste séparée par des virgules : `svg`, `html`, `png`, `pdf`, `mermaid` (défaut `svg,html`) ; `mermaid` écrit `<base>.mmd` et affiche ses avertissements sur stderr |
|
|
69
|
+
| `--out <dir>` | Dossier de sortie (défaut : le dossier du fichier d'entrée) |
|
|
70
|
+
| `--name <base>` | Nom de base des sorties (défaut : le nom du fichier d'entrée sans `.json` ni `.sg`) |
|
|
71
|
+
| `--theme <thème>` | `auto` (défaut), un nom de palette (`light`, `dark`, `nord`, `solarized-light`, `solarized-dark`, `high-contrast`) ou un fichier de thème `.json`, voir [docs/theming.md](./docs/theming.md) |
|
|
72
|
+
| `--no-palette` | Coupe la couleur automatique par `type` d'élément |
|
|
73
|
+
| `--scale <n>` | Facteur d'échelle du PNG (défaut 2) |
|
|
74
|
+
| `--renderer <nom>` | Rendu HTML : `auto`, `svg` ou `webgl` (défaut `auto`) |
|
|
75
|
+
| `--markdown` | Affiche `[](base.html)`, un extrait Markdown qui lie l'aperçu SVG à la page HTML ; avec `mermaid` dans `--format`, un bloc de code `mermaid` suit |
|
|
76
|
+
|
|
77
|
+
### JavaScript
|
|
78
|
+
|
|
79
|
+
Chaque sous-chemin est un point d'entrée distinct de `@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
|
+
Tous les formats en un appel, depuis `/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 est une chaîne, out.png et out.pdf sont des Uint8Array
|
|
102
|
+
```
|
|
103
|
+
|
|
104
|
+
Du texte Mermaid pour le Markdown de GitHub, depuis `/mermaid` (`formats: ["mermaid"]` dans `exportDocument()` renvoie le même texte sous forme de chaîne, sans les avertissements) :
|
|
105
|
+
|
|
106
|
+
```ts
|
|
107
|
+
import { toMermaid } from "@standarx/graph/mermaid";
|
|
108
|
+
|
|
109
|
+
const { text, warnings } = toMermaid(graphDocument);
|
|
110
|
+
```
|
|
111
|
+
|
|
112
|
+
Monter un graphe interactif dans une page (`mount(container, document, { theme, title, renderer })`). Quand chaque nœud a une `position`, ELK est ignoré ; sinon la mise en page tourne dans un Web Worker et le thread principal reste libre. Plusieurs instances peuvent coexister sur une 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
|
+
Pipelines Markdown, avec le plugin remark (il transforme les blocs de code ` ```standargraph ` et ` ```sg ` contenant un document JSON ou la syntaxe texte en SVG en ligne, lié à une page HTML autonome quand `outDir` est défini) :
|
|
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
|
+
Le cœur headless, pour votre propre rendu (voir [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
|
+
Les fonctions d'éditeur de la syntaxe texte, sans dépendance à un serveur de langage (voir [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
|
+
## 🧩 Types de diagrammes
|
|
155
|
+
|
|
156
|
+
Chaque document porte `version: 1` et un `kind`. Les fichiers de [examples](./examples) sont des documents complets pour chaque type.
|
|
157
|
+
|
|
158
|
+
### `graph` et `sequence`
|
|
159
|
+
|
|
160
|
+
`graph` contient des `nodes`, des `edges` et des `groups` imbriqués ; `sequence` contient des `participants` et des `messages`. Voir le démarrage rapide plus haut, ainsi que `examples/architecture.json` et `examples/protocol.json`.
|
|
161
|
+
|
|
162
|
+
### `state`
|
|
163
|
+
|
|
164
|
+
Des états, des pseudo-états facultatifs (`initial`, `final`, `choice`, `fork`, `join`, `history`), des états composites par `parent`, et des transitions avec `event`, `guard` et `action`. Extrait de `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
|
+
Des entités à attributs (`keys` : `pk`, `fk`, `uk` ; `nullable` ; `note`) et des relations dessinées avec des cardinalités en pattes de corbeau (`one`, `zero-or-one`, `one-or-more`, `zero-or-more`). Extrait de `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
|
+
Une liste plate de nœuds liés par `parent`, mise en page en arbre « tidy » (`"layout": "tree"`, par défaut, avec une `direction`) ou en mindmap à deux côtés autour de la racine (`"layout": "mindmap"`). Extrait de `examples/repo-tree.json` et `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
|
+
### Formes
|
|
239
|
+
|
|
240
|
+
`shape` sur un nœud `graph` ou `tree` vaut `box` (par défaut), `rect`, `pill`, `diamond`, `circle`, `ellipse`, `hexagon`, `parallelogram`, `cylinder`, `document` ou `subroutine`. Les arêtes s'arrêtent sur le contour de la forme : un flowchart est donc un `graph` avec des formes (`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
|
+
Les formes sont dans le document ; les couleurs n'y sont jamais. Elles viennent du thème.
|
|
260
|
+
|
|
261
|
+
### Syntaxe texte
|
|
262
|
+
|
|
263
|
+
Chaque type se laisse aussi écrire en texte brut, dans des fichiers nommés `.sg` par convention. Un graphe en forme à symboles :
|
|
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
|
+
Le même graphe en forme à mots, où `to`, `with`, `async`, `reply` et `via` remplacent les opérateurs et `do` ... `end` remplace les accolades :
|
|
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
|
+
Les deux formes se lisent comme le même document. `examples/` contient un jumeau `.sg` de chaque exemple JSON. Le sous-chemin `/text` exporte `parse`, `print`, `canonicalize`, `sniff` et `loadSource` ; une chaîne passée à `mount()` ou à `exportDocument()` passe par `loadSource`, et `standargraph convert` transforme un format en l'autre. Dans un Markdown, un bloc ` ```sg ` (ou ` ```standargraph `) contient l'un ou l'autre format :
|
|
294
|
+
|
|
295
|
+
````md
|
|
296
|
+
```sg
|
|
297
|
+
graph "Release flow"
|
|
298
|
+
|
|
299
|
+
build -> check
|
|
300
|
+
```
|
|
301
|
+
````
|
|
302
|
+
|
|
303
|
+
#### Coloration syntaxique
|
|
304
|
+
|
|
305
|
+
Le paquet livre une grammaire TextMate (`@standarx/graph/grammars/standargraph.tmLanguage.json`, scope `source.standargraph`), un `language-configuration.json` et `highlight(source)` dans le sous-chemin `/text`, qui renvoie des jetons typés avec les types de jetons sémantiques du LSP. La démo en ligne colore son éditeur avec `highlight()`. Une extension VS Code les consommera depuis son propre dépôt. Voir [docs/syntax-highlighting.md](./docs/syntax-highlighting.md) (en anglais).
|
|
306
|
+
|
|
307
|
+
### Thèmes
|
|
308
|
+
|
|
309
|
+
Un thème est un ensemble de jetons de couleur plus des couleurs facultatives par `type` de nœud, donné par `--theme <fichier.json>` dans la CLI ou par l'option `theme` de l'API. Six palettes sont prêtes à l'emploi, en `theme: "nord"` ou `--theme nord` : `light`, `dark`, `nord`, `solarized-light`, `solarized-dark` et `high-contrast`, chacune avec un contraste d'au moins 4,5:1 pour son texte.
|
|
310
|
+
|
|
311
|
+
- Un élément typé sans couleur propre en reçoit une de la palette du thème, choisie par un hachage stable de son `type`. `palette: false` dans le thème, ou `--no-palette`, la coupe, et une entrée de `types` l'emporte toujours.
|
|
312
|
+
- Avec `"auto"` ou une paire `{ light, dark }`, la page interactive et `mount()` affichent dans la barre d'outils un bouton qui fait défiler `auto`, `light` et `dark`, gardé dans `localStorage`.
|
|
313
|
+
- La démo en ligne a un panneau de thème : une palette, les jetons, une couleur par type, et un `theme.json` à télécharger pour `--theme`.
|
|
314
|
+
|
|
315
|
+
Voir [docs/theming.md](./docs/theming.md) (en anglais).
|
|
316
|
+
|
|
317
|
+
### GitHub Action
|
|
318
|
+
|
|
319
|
+
L'action composite à la racine du dépôt rend vos fichiers `.sg` avec la CLI publiée. Elle ne commite ni ne pousse jamais.
|
|
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
|
+
| Entrée | Défaut | Rôle |
|
|
330
|
+
| --- | --- | --- |
|
|
331
|
+
| `files` | `**/*.sg` | Fichiers à rendre |
|
|
332
|
+
| `formats` | `svg` | Formats d'export |
|
|
333
|
+
| `theme` | `light` | Thème du rendu |
|
|
334
|
+
| `out` | vide (à côté du source) | Dossier de sortie |
|
|
335
|
+
| `version` | la version du paquet de la ref de l'action | Version npm de `@standarx/graph` lancée |
|
|
336
|
+
| `mode` | `write` | `write` rend ; `check` rend puis échoue, en listant les fichiers, si une sortie diffère de l'arbre de travail ou manque |
|
|
337
|
+
| `cli-path` | vide | Chemin d'un `dist/cli.js` construit localement, utilisé à la place du paquet npm (CI de ce dépôt) |
|
|
338
|
+
|
|
339
|
+
[docs/diagrams-workflow.yml](./docs/diagrams-workflow.yml) est un workflow d'exemple qui rend à chaque push et commite le résultat avec de simples commandes `git`. Copiez-le dans `.github/workflows/diagrams.yml`.
|
|
340
|
+
|
|
341
|
+
---
|
|
342
|
+
|
|
343
|
+
## 📦 Installation
|
|
344
|
+
|
|
345
|
+
```sh
|
|
346
|
+
npm install @standarx/graph
|
|
347
|
+
bun add @standarx/graph
|
|
348
|
+
```
|
|
349
|
+
|
|
350
|
+
Node >= 20. La CLI est le binaire `standargraph`. Une fois le paquet installé, `npx standargraph` ou `bunx standargraph` la lance ; sans installation, nommez le paquet :
|
|
351
|
+
|
|
352
|
+
```sh
|
|
353
|
+
npx @standarx/graph export graph.json
|
|
354
|
+
bunx @standarx/graph export graph.json
|
|
355
|
+
npm install -g @standarx/graph # puis : standargraph export graph.json
|
|
356
|
+
```
|
|
357
|
+
|
|
358
|
+
---
|
|
359
|
+
|
|
360
|
+
## ✨ Fonctionnalités
|
|
361
|
+
|
|
362
|
+
- **Format v1** : documents JSON de cinq types, `graph` (nœuds, arêtes, groupes imbriqués, `position` fixe facultative), `sequence` (participants, messages), `state`, `er` et `tree` (voir [Types de diagrammes](#-types-de-diagrammes)), validés par un [JSON Schema](./schema/graph-document.v1.json) publié, avec un `validate()` qui renvoie une erreur par problème et son chemin.
|
|
363
|
+
- **Métadonnées** : provenance (`confirmed`, `inferred`, `unknown`), couverture et fraîcheur sur les documents, nœuds, arêtes et groupes ; les éléments à faible confiance sont dessinés atténués.
|
|
364
|
+
- **Mise en page** : layout ELK en couches pour les graphes, les groupes, les machines à états et les diagrammes entité-relation, layout dédié aux diagrammes de séquence, layout arbre ou mindmap pour les arbres, texte mesuré avec les métriques d'Inter embarquées pour que SVG et HTML s'accordent.
|
|
365
|
+
- **Formes** : 11 formes de nœud sur les nœuds `graph` et `tree`, dessinées en SVG et coupées au contour par les arêtes (voir [Formes](#formes)).
|
|
366
|
+
- **Thèmes** : six palettes nommées, une couleur automatique par `type` de nœud, un sélecteur clair, sombre et auto, des jetons de couleur et des couleurs par `type` de nœud, un seul objet pour le SVG, le HTML, le PNG et le PDF, option `--theme <nom|fichier.json>` (voir [docs/theming.md](./docs/theming.md), en anglais).
|
|
367
|
+
- **Rendus** : SVG, HTML interactif (déplacement, zoom, survol, sélection, recherche, panneau, clavier, thèmes clair et sombre), et WebGL via Sigma.js.
|
|
368
|
+
- **WebGL au-delà de 2000 nœuds** : l'export HTML d'un `graph` bascule automatiquement en WebGL au-delà de 2000 nœuds (`--renderer` force le choix). Sur la porte v1, 10 000 nœuds en WebGL tiennent une médiane de 303 FPS (p5 285,7) plafonnée par le rafraîchissement de l'écran, et une médiane de 58,1 FPS (p5 54,3) sans plafond, sur un Intel Core i7-14700KF avec une NVIDIA GeForce RTX 4070 Ti SUPER dans Microsoft Edge 157. Détails dans [docs/bench.md](./docs/bench.md).
|
|
369
|
+
- **HTML hors ligne en un fichier** : polices et runtime embarqués, rien n'est téléchargé.
|
|
370
|
+
- **Export** : SVG, HTML, PNG et PDF depuis la CLI ou `exportDocument()`, PNG et PDF sans navigateur (resvg WASM et PDFKit).
|
|
371
|
+
- **Cœur headless** : contrôleur de vue avec caméra, hit testing, culling, niveau de détail et surbrillance, utilisable dans Node, Bun, un worker ou un navigateur.
|
|
372
|
+
- **Syntaxe texte** : chaque type en texte brut (`.sg`), en forme à symboles ou à mots, avec des erreurs en ligne et colonne, `print()` pour revenir au texte et `standargraph convert` entre les deux formats (voir [Syntaxe texte](#syntaxe-texte)).
|
|
373
|
+
- **Export Mermaid** : chaque type en texte Mermaid avec `toMermaid()` ou `--format mermaid`, les pertes étant signalées par des avertissements (voir [docs/mermaid.md](./docs/mermaid.md), en anglais).
|
|
374
|
+
- **Intégration** : `mount()` pour les applications, avec un worker de mise en page à la demande, et un plugin remark pour le Markdown.
|
|
375
|
+
|
|
376
|
+
---
|
|
377
|
+
|
|
378
|
+
## 🚧 Limites
|
|
379
|
+
|
|
380
|
+
- **La mise en page des grands graphes est lente.** ELK met en page 10 000 nœuds en environ 44 s (5 000 nœuds : 13 s, 2 000 : 3,7 s ; voir [docs/bench.md](./docs/bench.md)). Le rendu n'est pas le goulot. Une mise en page plus rapide pour les grands graphes arrive bientôt.
|
|
381
|
+
- **Précalculez les positions des grands graphes.** Dès que chaque nœud a une `position`, ELK est ignoré par `layout()`, `mount()` et les exports. `standargraph export` calcule la mise en page une fois et la page HTML qu'il écrit porte le résultat : l'ouvrir ne remet jamais rien en page. Pour garder les positions dans vos documents, lancez `standargraph layout graph.json` (ou `--out <fichier>`) : la commande écrit le même document avec une `position` sur chaque nœud, qui s'affiche ensuite sans ELK.
|
|
382
|
+
|
|
383
|
+
- La sortie du plugin remark ne s'affiche pas sur GitHub. Dans un README, utilisez le SVG écrit par la CLI, lié à sa page HTML (`--markdown` affiche l'extrait).
|
|
384
|
+
- Le rendu WebGL ne dessine ni les légendes de type de nœud, ni les libellés d'arêtes, ni les pointes de flèche, et les diagrammes `sequence`, `state`, `er` et `tree` sont toujours dessinés en SVG.
|
|
385
|
+
|
|
386
|
+
---
|
|
387
|
+
|
|
388
|
+
## 📚 Documentation
|
|
389
|
+
|
|
390
|
+
- [Cœur headless et adaptateurs](./docs/headless.md) (anglais)
|
|
391
|
+
- [Thèmes](./docs/theming.md) (anglais)
|
|
392
|
+
- [Coloration syntaxique de `.sg`](./docs/syntax-highlighting.md) (anglais)
|
|
393
|
+
- [Service de langage pour `.sg`](./docs/language-service.md) (anglais)
|
|
394
|
+
- [Export Mermaid](./docs/mermaid.md) (anglais)
|
|
395
|
+
- [Benchmark et temps de mise en page](./docs/bench.md) (anglais)
|
|
396
|
+
- [JSON Schema du format v1](./schema/graph-document.v1.json)
|
|
397
|
+
- [Exemples](./examples)
|
|
398
|
+
- [Changelog](./CHANGELOG.md) (anglais)
|
|
399
|
+
|
|
400
|
+
---
|
|
401
|
+
|
|
402
|
+
## 🛠️ Build et tests
|
|
403
|
+
|
|
404
|
+
```sh
|
|
405
|
+
bun install
|
|
406
|
+
bun run typecheck
|
|
407
|
+
bun test
|
|
408
|
+
bun run build
|
|
409
|
+
bun run smoke # le paquet empaqueté, sous Node
|
|
410
|
+
STANDARGRAPH_BROWSER_CHANNEL=msedge bun run test:browser # Playwright, indiquez le canal d'un navigateur installé
|
|
411
|
+
bun run bench # benchmark (Microsoft Edge, avec fenêtre)
|
|
412
|
+
bun run runtime # régénère les runtimes HTML et WebGL embarqués
|
|
413
|
+
bun run site # construit le site GitHub Pages dans site-dist/
|
|
414
|
+
```
|
|
415
|
+
|
|
416
|
+
La CI épingle bun 1.4.2 pour que les bundles générés correspondent à ceux versionnés ; utilisez la même version avant de lancer `bun run runtime`.
|
|
417
|
+
|
|
418
|
+
---
|
|
419
|
+
|
|
420
|
+
## 🤝 Contribuer
|
|
421
|
+
|
|
422
|
+
Les issues et pull requests sont les bienvenues sur [github.com/miralabs-tech/standargraph](https://github.com/miralabs-tech/standargraph). Lancez typecheck, tests, build et smoke test avant d'ouvrir une pull request.
|
|
423
|
+
|
|
424
|
+
---
|
|
425
|
+
|
|
426
|
+
## ❤️ Soutien
|
|
427
|
+
|
|
428
|
+
Si StandarGraph vous aide :
|
|
429
|
+
|
|
430
|
+
👉 [Mettre une étoile](https://github.com/miralabs-tech/standargraph) · [Ouvrir une issue](https://github.com/miralabs-tech/standargraph/issues)
|
|
431
|
+
|
|
432
|
+
---
|
|
433
|
+
|
|
434
|
+
## 📜 Licence
|
|
435
|
+
|
|
436
|
+
[MIT](./LICENSE) - Copyright (c) 2026 Wesley Cormier.
|
|
437
|
+
|
|
438
|
+
Les composants tiers gardent leurs propres licences : voir [THIRD_PARTY_NOTICES.md](./THIRD_PARTY_NOTICES.md) et les textes dans [licenses/](./licenses) (elkjs est EPL-2.0 OU GPL-3.0-or-later, resvg est MPL-2.0, Inter est SIL OFL 1.1).
|