@cardenelabs/dragon 0.12.0 → 0.14.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 +86 -58
- package/dist/index.cjs +10485 -6260
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +945 -4
- package/dist/index.d.ts +945 -4
- package/dist/index.js +10486 -6261
- package/dist/index.js.map +1 -1
- package/package.json +1 -1
- package/src/color.ts +31 -6
- package/src/compile.ts +724 -196
- package/src/input-size.ts +21 -1
- package/src/json-parser.ts +695 -2
- package/src/schemas/diagram.json +1341 -3
- package/src/types.ts +130 -1
- package/src/v05/input-table.generated.ts +136 -0
- package/src/v05/parser-types.ts +21 -0
- package/src/v05/parser.ts +1237 -26
- package/src/v05/readout-table.generated.ts +1088 -0
package/README.md
CHANGED
|
@@ -49,20 +49,27 @@ flow:
|
|
|
49
49
|
### 最上位のブロック
|
|
50
50
|
|
|
51
51
|
<!-- notation:top-level:start -->
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
|
55
|
-
| `
|
|
56
|
-
| `
|
|
57
|
-
| `
|
|
58
|
-
| `
|
|
59
|
-
| `
|
|
60
|
-
| `
|
|
61
|
-
| `
|
|
62
|
-
| `
|
|
63
|
-
| `
|
|
64
|
-
| `
|
|
65
|
-
| `
|
|
52
|
+
|
|
53
|
+
| 欄 | 何を書くか |
|
|
54
|
+
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
55
|
+
| `title` | 図の題 |
|
|
56
|
+
| `type` | 図種 (`sequence` / `flow` / `swimlane` / `er` / `state` / `topology` / `gantt` / `class` / `mind` / `tree` / `c4` / `solidity` / 図表各種) |
|
|
57
|
+
| `actors` | 箱 |
|
|
58
|
+
| `flow` | 矢印 |
|
|
59
|
+
| `states` | 状態の初期値 |
|
|
60
|
+
| `values` | 他の状態から決まる値 (式) |
|
|
61
|
+
| `animation` | 段 |
|
|
62
|
+
| `viewport` | 図全体の大きさと間隔 |
|
|
63
|
+
| `lanes` | 縦列の見出しと幅 |
|
|
64
|
+
| `groups` | 縦列を束ねる枠 |
|
|
65
|
+
| `eyebrow` | 図全体を 1 箱にする図種で、その箱の上に出す小見出し |
|
|
66
|
+
| `axes` | 2 軸で仕分ける図の軸の名前 |
|
|
67
|
+
| `readouts` | 値を見せる部品 (割合の輪 / 数え上げ / 目盛り) |
|
|
68
|
+
| `inputs` | 読む人が動かすつまみ (すべり / 選び / 入り切り など 14 種) |
|
|
69
|
+
| `formulas` | つまみの値から決まる値 (式。 `values` は段が動かす状態を読み、こちらはつまみを読む) |
|
|
70
|
+
| `events` | 押下などの出来事で動く仕掛け (相手は名前で指す) |
|
|
71
|
+
| `scrolls` | 巻き上げに応じて進む値 (画面を巻き上げた量から 0 から 1 を作る) |
|
|
72
|
+
|
|
66
73
|
<!-- notation:top-level:end -->
|
|
67
74
|
|
|
68
75
|
### 箱に書ける欄
|
|
@@ -70,28 +77,38 @@ flow:
|
|
|
70
77
|
`- 名前: { 欄: 値, ... }` の形で書く。
|
|
71
78
|
|
|
72
79
|
<!-- notation:actor:start -->
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
|
76
|
-
| `
|
|
77
|
-
| `
|
|
78
|
-
| `
|
|
79
|
-
| `
|
|
80
|
-
| `
|
|
81
|
-
| `
|
|
82
|
-
| `
|
|
83
|
-
| `
|
|
84
|
-
| `
|
|
85
|
-
| `
|
|
86
|
-
| `
|
|
87
|
-
| `
|
|
88
|
-
| `
|
|
89
|
-
| `
|
|
90
|
-
| `
|
|
91
|
-
| `
|
|
92
|
-
| `
|
|
93
|
-
| `
|
|
94
|
-
| `
|
|
80
|
+
|
|
81
|
+
| 欄 | 何を書くか |
|
|
82
|
+
| --------------- | ------------------------------------------------------------------------------ |
|
|
83
|
+
| `kind` | 見た目の種別 (`card` / `storage` / `service` / `person` 等、`種類` とも書ける) |
|
|
84
|
+
| `subtitle` | 題の下の補足 (`補足` とも書ける) |
|
|
85
|
+
| `eyebrow` | 題の上の小見出し |
|
|
86
|
+
| `value` | 箱に出す値 (`値` とも書ける) |
|
|
87
|
+
| `rows` | 箱の中に並べる行 (`行` とも書ける) |
|
|
88
|
+
| `lane` | どの縦列に置くか |
|
|
89
|
+
| `stack` | 縦列の中の何段目に置くか |
|
|
90
|
+
| `initial` | 状態遷移図で始まりの状態か |
|
|
91
|
+
| `final` | 状態遷移図で終わりの状態か |
|
|
92
|
+
| `tone` | 色 |
|
|
93
|
+
| `nodes` | 見本 (parts) の中の箱を差し替える |
|
|
94
|
+
| `touchpoint` | 体験の道筋で、利用者が触れる場所 |
|
|
95
|
+
| `opportunity` | 体験の道筋で、改善の余地 |
|
|
96
|
+
| `owner` | 工程の並びで、担当 |
|
|
97
|
+
| `end` | 工程の並びで、終わりの位置 |
|
|
98
|
+
| `posX` | 置く場所の横位置 |
|
|
99
|
+
| `posY` | 置く場所の縦位置 |
|
|
100
|
+
| `posW` | 箱の幅 |
|
|
101
|
+
| `posH` | 箱の高さ |
|
|
102
|
+
| `scale` | 見本 (parts) の倍率 (`倍率` とも書ける) |
|
|
103
|
+
| `shape` | 箱の中に描く図形 (水位 / 角度 / 半径を状態で動かす、`図形` とも書ける) |
|
|
104
|
+
| `visibleIf` | その箱を出すかどうかの条件 (`出す条件` とも書ける) |
|
|
105
|
+
| `title` | 箱に出す題。 書かなければ名前がそのまま題になる (`題` とも書ける) |
|
|
106
|
+
| `wBind` | 箱の幅を値に追随させる (状態の名前を `{名前}` の形で書く) |
|
|
107
|
+
| `hBind` | 箱の高さを値に追随させる (`wBind` と同じ読み方) |
|
|
108
|
+
| `opacity` | 箱の濃さ (0 から 1 の数か、状態の名前) |
|
|
109
|
+
| `renderOffsetX` | 描く時だけ箱を横へずらす量 (配置と矢印はずらす前の位置を使う) |
|
|
110
|
+
| `renderOffsetY` | 描く時だけ箱を縦へずらす量 (`renderOffsetX` と同じ読み方) |
|
|
111
|
+
|
|
95
112
|
<!-- notation:actor:end -->
|
|
96
113
|
|
|
97
114
|
### 矢印に書ける欄
|
|
@@ -99,14 +116,20 @@ flow:
|
|
|
99
116
|
`- A -> B: "説明" (色, 線種) { 欄: 値, ... }` の形で書く。
|
|
100
117
|
|
|
101
118
|
<!-- notation:flow:start -->
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
|
105
|
-
| `
|
|
106
|
-
| `
|
|
107
|
-
| `
|
|
108
|
-
| `
|
|
109
|
-
| `
|
|
119
|
+
|
|
120
|
+
| 欄 | 何を書くか |
|
|
121
|
+
| ---------------- | ------------------------------------------------------------------- |
|
|
122
|
+
| `sub` | 説明の下の補足 |
|
|
123
|
+
| `guard` | 状態遷移の条件 |
|
|
124
|
+
| `cardinality` | 関係の多重度 (`1:N` 等) |
|
|
125
|
+
| `widthBind` | 線の太さを値に追随させる (状態やつまみの名前を `{名前}` の形で書く) |
|
|
126
|
+
| `strokeBind` | 線の色を値に追随させる (`widthBind` と同じ読み方) |
|
|
127
|
+
| `dashOffsetBind` | 破線の位置を値に追随させる (流れているように見せる) |
|
|
128
|
+
| `side` | 矢印がどの辺から出るか (`top` / `right` / `bottom` / `left`) |
|
|
129
|
+
| `labelOffsetX` | 説明文の位置を横にずらす |
|
|
130
|
+
| `labelOffsetY` | 説明文の位置を縦にずらす |
|
|
131
|
+
| `overlay` | `true` で説明文を線の上に重ねる (分岐図の条件ラベル用) |
|
|
132
|
+
|
|
110
133
|
<!-- notation:flow:end -->
|
|
111
134
|
|
|
112
135
|
## 記法の癖
|
|
@@ -145,8 +168,8 @@ type: flow
|
|
|
145
168
|
actors: [A, B, C]
|
|
146
169
|
|
|
147
170
|
flow:
|
|
148
|
-
- A -> C: "x"
|
|
149
|
-
- C -> B: "y"
|
|
171
|
+
- A -> C: "x" # 出来るのは A -> B
|
|
172
|
+
- C -> B: "y" # 出来るのは B -> C
|
|
150
173
|
```
|
|
151
174
|
|
|
152
175
|
書いた端どおりに繋ぎたい時は箱に `lane:` を書く。 縦列を書いた形は別の組み立てを通り、
|
|
@@ -155,16 +178,19 @@ flow:
|
|
|
155
178
|
## API
|
|
156
179
|
|
|
157
180
|
**Text DSL (人向け YAML)**
|
|
181
|
+
|
|
158
182
|
- `textDslToDiagram(src: string): CdlDiagram` ... 一発変換 (v0.4 / v0.5 auto-detect、 recommended entry)
|
|
159
183
|
- `parseTextDslV05(src: string): V05ParseResult` ... v0.5 parser を直接呼出 (error 詳細取得)
|
|
160
184
|
- `compileToCdl(doc: DslDocument): CdlDiagram` ... AST → CdlDiagram
|
|
161
185
|
|
|
162
186
|
**JSON DSL (LLM 向け)**
|
|
187
|
+
|
|
163
188
|
- `jsonToDiagram(json: unknown): CdlDiagram` ... JSON DSL → CdlDiagram、 validation error は throw
|
|
164
189
|
- `validateDragonJson(json: unknown): { ok, data | errors }` ... compile なしで validation のみ
|
|
165
190
|
- `diagramJsonSchema` ... JSON Schema (Draft 7)、 LLM の tool schema にそのまま注入可能
|
|
166
191
|
|
|
167
192
|
**Deprecated (2026-12-31 削除予定)**
|
|
193
|
+
|
|
168
194
|
- `parseTextDsl(src: string): ParseResult` ... v0.4 parser、 `textDslToDiagram` に移行推奨
|
|
169
195
|
|
|
170
196
|
## LLM 向け JSON DSL
|
|
@@ -211,11 +237,13 @@ async function generateDiagramFromLLM(userRequest: string, maxRetry = 3) {
|
|
|
211
237
|
const res = await client.messages.create({
|
|
212
238
|
model: "claude-sonnet-5",
|
|
213
239
|
max_tokens: 4096,
|
|
214
|
-
tools: [
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
|
|
240
|
+
tools: [
|
|
241
|
+
{
|
|
242
|
+
name: "create_diagram",
|
|
243
|
+
description: "Create an animated diagram from user's request using Dragon DSL.",
|
|
244
|
+
input_schema: diagramJsonSchema,
|
|
245
|
+
},
|
|
246
|
+
],
|
|
219
247
|
tool_choice: { type: "tool", name: "create_diagram" },
|
|
220
248
|
messages,
|
|
221
249
|
});
|
|
@@ -238,7 +266,7 @@ async function generateDiagramFromLLM(userRequest: string, maxRetry = 3) {
|
|
|
238
266
|
|
|
239
267
|
// 使用例
|
|
240
268
|
const diagram = await generateDiagramFromLLM(
|
|
241
|
-
"ユーザーが API 経由で DB に検索をかけて結果を受け取るシーケンス図を作って"
|
|
269
|
+
"ユーザーが API 経由で DB に検索をかけて結果を受け取るシーケンス図を作って",
|
|
242
270
|
);
|
|
243
271
|
```
|
|
244
272
|
|
|
@@ -271,13 +299,13 @@ const diagram = jsonToDiagram(json);
|
|
|
271
299
|
|
|
272
300
|
同じ図を両方の記法で書ける。 人 → YAML、 LLM → JSON が推奨だが、 混在可能。
|
|
273
301
|
|
|
274
|
-
| YAML
|
|
275
|
-
|
|
276
|
-
| `title: "..."`
|
|
302
|
+
| YAML | JSON |
|
|
303
|
+
| ---------------------- | ------------------------------------------------------- |
|
|
304
|
+
| `title: "..."` | `{title: "..."}` |
|
|
277
305
|
| `actors: [A, B: kind]` | `{actors: [{name: "A"}, {name: "B", kind: "storage"}]}` |
|
|
278
|
-
| `- A -> B: "label"`
|
|
279
|
-
| `step: "..." 1.4s`
|
|
280
|
-
| `focus: [A, B]`
|
|
306
|
+
| `- A -> B: "label"` | `{from: "A", to: "B", label: "label"}` |
|
|
307
|
+
| `step: "..." 1.4s` | `{step: "...", duration: 1.4}` |
|
|
308
|
+
| `focus: [A, B]` | `{focus: ["A", "B"]}` |
|
|
281
309
|
|
|
282
310
|
箱に書ける項目 (`tone` / `owner` / `posX` 等) は両方の記法で同じ。 一覧は実装
|
|
283
311
|
(`INLINE_ACTOR_KEYS`) が持ち、`packages/dragon/test/json-actor-fields.test.ts` が
|