@cardenelabs/dragon 0.46.0 → 0.46.1

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.ja.md ADDED
@@ -0,0 +1,331 @@
1
+ # @cardenelabs/dragon
2
+
3
+ 動く図を、人は dragon記法で、AI は JSON で書くための package。
4
+
5
+ [English](README.md)
6
+
7
+ dragon は、短い文の file から段ごとに動く図を描く。
8
+ 見本帳 (全ての種類の図と、書くとその場で動く編集画面) は <https://cardene777.github.io/dragon/> にある。
9
+
10
+ ## 入れ方
11
+
12
+ ```sh
13
+ npm install @cardenelabs/dragon
14
+ ```
15
+
16
+ この package は次の 4 つを持つ。
17
+
18
+ | 持つ物 | 形 |
19
+ |---|---|
20
+ | 原本 | 共通の骨格と図の種類ごとの欄を持つ JSON。版を持ち、古い版は読む時に変換する |
21
+ | 記法 | 行の頭の英語の語で行の種類が決まる dragon記法 (下の節)。JSON と行き来でき、名前と文は日本語でも書ける ([書き方](https://github.com/cardene777/dragon/blob/main/packages/dragon/examples/quick-start.md)、[英語の書き方](https://github.com/cardene777/dragon/blob/main/packages/dragon/examples/quick-start.en.md)) |
22
+ | 描く部品 | 原本を頁に描き、段ごとに動かす部品。時系列図、構成図、状態遷移図、枝分かれの図、時間軸の図、木の図を描く |
23
+ | 書き出し | 同じ原本から mp4、GIF、HTML、PNG を書き出す命令 `dragon export` |
24
+
25
+ 前の版から上げる時に書き直す所は [`CHANGELOG.md`](https://github.com/cardene777/dragon/blob/main/CHANGELOG.md) にある。
26
+
27
+ ## 最初の図
28
+
29
+ ```dragon
30
+ sequence ログインを頼む
31
+
32
+ box ブラウザ as 利用者のブラウザ [note: 利用者が操作する]
33
+ box アプリ [note: ログインを頼む側]
34
+
35
+ step ログインを押す
36
+ say 利用者がアプリのログインを押す。
37
+ ブラウザ -> アプリ: GET /login
38
+ ```
39
+
40
+ 見本帳の編集画面に貼るとその場で動き、次の節の書き方で自分の頁にも置ける。
41
+
42
+ ## 頁に置く
43
+
44
+ 頁で 1 度だけ字の入口 `@cardenelabs/dragon/fonts` を import し、記法を読んだ原本を `mountDiagram` に渡す。
45
+
46
+ ```ts
47
+ import "@cardenelabs/dragon/fonts";
48
+ import { mountDiagram, parseNotation } from "@cardenelabs/dragon";
49
+
50
+ const source = await (await fetch("login.dragon")).text();
51
+ const parsed = parseNotation(source);
52
+ if (!parsed.ok) throw new Error(parsed.errors.map((e) => `${e.line}: ${e.message}`).join("\n"));
53
+
54
+ const host = document.getElementById("figure");
55
+ if (host === null) throw new Error("#figure not found");
56
+ const player = mountDiagram(host, parsed.diagram);
57
+ ```
58
+
59
+ 字の入口は、同梱の 2 つの字 (Noto Sans JP と JetBrains Mono) の CSS を読み込むだけで、何も出さない。
60
+ 図は同梱の字で測った字の幅で組むため、読み込まないと端末の字で描かれ、札から字がはみ出すことがある。
61
+ CSS と字の file は、束ねる道具 (Vite など) が頁へ運ぶ。
62
+ この入口は Node の組み込みの module を読まないため、Next.js の Turbopack のように頁を束ねる道具でもそのまま読める。
63
+ 原本の file を今の版へ移す `migrateFile` は、Node でだけ動く入口 `@cardenelabs/dragon/node` から引く。
64
+
65
+ `mountDiagram` が返す `player` で段を動かす (`next`、`prev`、`play`、`pause`、`destroy`)。
66
+ 3 つめの引数には色味や段が替わった時に呼ぶ関数などの設定 (`PlayerOptions`) を渡す。
67
+ 置いた時に流さず決めた段の止め絵で止めて置くには `pausedAt` に段の番号 (0 から) を、1 度だけ流して最後の段で止めるには `playOnce: true` を渡す。
68
+ `still: true` を渡すと、最後の段の止め絵に全ての段の線の名前と箱の中の処理を最後の段と同じ濃さで出し、動かさない読者にも流れ全体を 1 枚で見せる。
69
+ `still` は `renderDiagram` にも渡せる。
70
+ どれも渡さなければ、置いた時から全ての段を繰り返し流す。
71
+
72
+ 色味は名前 (`palette`) で選び、`colors` に色の変数の名前と値を渡すと、渡した色だけを描く明暗 (`theme`) の色として上書きする。
73
+ 鍵は色味が持つ名前 (`bg`、`surf`、`ink`、`line`、`c-green`、`t-green` など。型は `ColorName`) で、渡さない色は名前で選んだ色味の値のまま残る。
74
+ 置いた図、寄って追う時の全体図、釦と段の帯のどれも同じ色で塗る。`renderDiagram` も同じ `colors` を受ける。
75
+
76
+ ```ts
77
+ mountDiagram(host, parsed.diagram, {
78
+ palette: "night",
79
+ colors: { bg: "#0a0f0a", surf: "#101810", ink: "#39ff14", line: "#1f9a0b", "c-green": "#39ff14" },
80
+ });
81
+ ```
82
+
83
+ 色味に無い名前と、`;`、`"`、`<` などを含む色として読めない値を渡すと、その名前を挙げて描かずに断る。
84
+
85
+ ## 図の種類の部品を後から読む
86
+
87
+ 頁が最初に読む量を抑えたい時は、`@cardenelabs/dragon/light` から読む。
88
+ 既定の入口と同じ部品を出すが、`git`、`lineup`、`state`、`time`、`tree` の描く部品を持たず、`loadKind` を待った時に読む。
89
+ 読んだ後は既定の入口と同じ関数で、待たずに同じ図を描く。
90
+
91
+ ```ts
92
+ import { loadKind, mountDiagram, parseNotation } from "@cardenelabs/dragon/light";
93
+
94
+ const parsed = parseNotation(text);
95
+ if (parsed.ok) {
96
+ await loadKind(parsed.diagram.kind);
97
+ mountDiagram(host, parsed.diagram);
98
+ }
99
+ ```
100
+
101
+ 読んでいない種類を描くと、その種類の名前を含む誤りで止まる。
102
+ 読み込みが落ちると `loadKind` が拒否され、次に呼ぶと読み直す。
103
+ `sequence` と `architecture` は初めから持つので、`loadKind` を呼ばなくても描ける。
104
+ 1 つの頁で既定の入口と混ぜると、全ての種類の部品が頁に入る。
105
+
106
+ ## dragon記法
107
+
108
+ どの行も次の決まり 4 つに従う。
109
+
110
+ 1. 行の種類は行の頭の英語の語で決まる。矢印の行だけは箱の名札から始まる
111
+ 2. 鍵と値はコロンで区切り、属性は `[ ]` の中に `,` で並べる
112
+ 3. 空白を含む名前と文は、行末か `[` の前に置く。`,` か `]` を含む値と、`[` を含む名前だけを `"` で囲む
113
+ 4. 入れ子は `group … end` だけ。段は次の `step` までで、字下げは読みやすさのために付ける。`say` の続きの行だけは `say` より深く字下げする
114
+
115
+ 行の頭の語は `sequence` `architecture` `state` `git` `time` `tree` `group` `end` `box` `branch` `scale` `period` `row` `point` `zoom` `strip` `step` `say` `code` `source` `commit` `mark` `span` `leaf` `node` `act` `note` `set` で、線の行は `名札 -> 名札` と書く。
116
+ 箱の行の属性 `link` に飛び先を書くと、描いた図でその箱が飛び先への link になる。
117
+ 段の中の `source <名前> [url: <URL>]` の行は段の出典になり、1 つの段に何行でも書け、読み上げの段の一覧に名前の link で出る。
118
+ 飛び先と出典の URL には、`/` で始まる path か、`http://` か `https://` で始まる URL だけを書ける。
119
+
120
+ ```dragon
121
+ architecture 注文を倉庫へ回す
122
+
123
+ group 店側 as 店 [note: 注文を受ける側, color: blue, icon: cart]
124
+ box 受付 [note: 注文を受ける, icon: app]
125
+ end
126
+
127
+ group 倉庫側 as 倉庫 [note: 品物を送る側, color: green, icon: box]
128
+ box 出荷 [note: 品物を送る, icon: truck]
129
+ end
130
+
131
+ step 出荷に回す
132
+ say
133
+ 受付が注文の番号を 2 つまとめて出荷に回す。
134
+ 出荷は届いた番号の順に品物を送る。
135
+ 受付 -> 出荷: 送ってよい [tag: "#42, #43"]
136
+ ```
137
+
138
+ `parseNotation` は記法を原本の JSON に、`printNotation` は原本の JSON を記法に直す。
139
+ 誤りの文の言葉は `parseNotation(text, { lang: "en" })` のように渡した言葉で決まり、渡さなければ日本語になる。
140
+ 前の形の記法 (`時系列図` か `構成図` で始まる形) は読まず、その行の新しい形を示す誤りで止まる。
141
+ 前の形と新しい形の対応表は [`CHANGELOG.md`](https://github.com/cardene777/dragon/blob/main/CHANGELOG.md) にある。
142
+
143
+ ### 状態遷移図
144
+
145
+ `state` で始めると、1 つの物が状態を移る様子を段ごとに追う状態遷移図になる。箱が状態で、線は状態から状態への移り変わり。
146
+ 線の送る側に `start` を書くと始まりの印から出る線に、受ける側に `finish` を書くと終わりの印へ入る線になる。
147
+ 最初の `step` より前に書いた線は、移れるが今回は通らない道として点線で引く。
148
+
149
+ ```dragon
150
+ state 注文が届くまでの状態
151
+
152
+ box 支払い待ち [note: 入金を待つ, color: amber, icon: clock]
153
+ box 発送済み [note: 業者が運ぶ, color: violet, icon: truck]
154
+ box 配達完了 [note: 受け取られた, color: green, icon: check]
155
+ box キャンセル [note: 払った分は返す, color: rose, icon: x]
156
+
157
+ 支払い待ち -> キャンセル: 取り消す
158
+ キャンセル -> finish
159
+
160
+ step 注文する
161
+ say 注文を確定すると、支払い待ちから始まる。
162
+ start -> 支払い待ち: 注文を確定 [tag: #1042]
163
+
164
+ step 発送する
165
+ say 入金を確かめて品物を送り、発送済みに移る。
166
+ 支払い待ち -> 発送済み: 発送 [tag: #1042]
167
+
168
+ step 届く
169
+ say 品物が届いて配達完了に移り、注文を閉じる。
170
+ 発送済み -> 配達完了: 受け取り [tag: #1042]
171
+ 配達完了 -> finish: 注文を閉じる [tag: #1042]
172
+ ```
173
+
174
+ ### 枝分かれの図
175
+
176
+ `git` で始めると、git の枝に commit を積み、取り込むまでを段ごとに追う枝分かれの図になる。枝は `branch` の行で上から順に宣言し、枝ごとに帯が並ぶ。
177
+ 段の中では `commit <名札> on <枝>` で枝の先に commit を積み、`copy <元>` で当て直しの commit を、`merge <枝>` で merge commit を作る。`hash` と `note` で丸の外に hash と一言を添える。
178
+ `<枝> from <commit>` で枝を切り、`<札> -> <commit>` で commit を作らずに枝の札か `HEAD` を動かす。どの札からも辿れなくなった commit は点線の丸に変わる。
179
+
180
+ ```dragon
181
+ git fix は merge commit で、feature は当て直して取り込む
182
+
183
+ branch main [note: 取り込む先]
184
+ branch feature [note: 作業の枝]
185
+ branch fix [note: 直しの枝]
186
+
187
+ step 枝を切る
188
+ say main の A から fix と feature を切り、それぞれに commit を積む。
189
+ commit A on main [hash: 3fa0c19, note: 最初の形]
190
+ fix from A
191
+ commit F on fix [hash: 9b2e4d1, note: 誤字を直す]
192
+ feature from A
193
+ commit C on feature [hash: c41d0e5, note: 検索を足す]
194
+
195
+ step merge commit で取り込む
196
+ say fix を merge commit M で main へ取り込む。M は A と F の 2 つを親に持つ。
197
+ commit M on main merge fix [hash: 7d3a5e2, note: fix を取り込む]
198
+
199
+ step 当て直す
200
+ say HEAD を M へ動かして枝から離し、C を M の先へ写して C' を作る。
201
+ HEAD -> M
202
+ commit C' on main copy C [hash: a90c6b4, note: 検索を足す]
203
+
204
+ step 早送りする
205
+ say feature を C' へ動かし、main も C' まで進める。元の C はどの枝からも辿れなくなる。
206
+ feature -> C'
207
+ main -> C'
208
+ ```
209
+
210
+ ### 時間軸の図
211
+
212
+ `time` で始めると、決まった間隔で進む時間の上で、出来事がどの目盛りで起きたかを段ごとに追う時間軸の図になる。`scale <単位> <長さ> <数>` で目盛りを宣言し、`period` で区切りを、`row` で印の列を、`point` で軸の下の節目を、`zoom <範囲>` で上の帯に拡大する目盛りを宣言する。
213
+ 段の中では `now -> <目盛り>` で針を進める。針は目盛り 1 つを決まった速さで進み、過ぎた目盛りの印がその時に出る。`mark` で印の色を変え、`span` で軸の下に範囲の括弧か、印の列を囲む枠を出す。
214
+ 中身の帯の欄に `[meter: <割合>]` を付けると物差しになり、`set` で書いた割合まで針と一緒に満ちる。
215
+
216
+ ```dragon
217
+ time ブロックが確定して戻せなくなるまで
218
+
219
+ scale slot 12s 64
220
+ period epoch 32
221
+ row ブロック [color: blue, empty: 5]
222
+ point C0 at 0
223
+ point C1 at 32
224
+ zoom 0-1
225
+
226
+ box 提案者 [color: blue, icon: user]
227
+ box ブロック [color: blue, icon: box]
228
+
229
+ strip 確定の進み: 経過, 今の epoch の票 [meter: 2/3]
230
+
231
+ step ブロックを出す
232
+ say slot ごとに提案者が 1 人選ばれ、ブロックを 1 つ出す。上の帯は最初の 2 slot を拡大した所。
233
+ 提案者 -> ブロック [at: 0]
234
+ 提案者 -> ブロック [at: 1]
235
+ now -> 1
236
+ set 経過: 24 秒
237
+
238
+ step 1 epoch 分の票を集める
239
+ say 32 slot で 1 epoch。針が過ぎた slot にブロックの印が出て、提案者が応答しなかった slot は空きの印になる。
240
+ note C0: 提案済み [color: blue]
241
+ span 0-31: 1 epoch = 6.4 分 [color: slate]
242
+ now -> 31
243
+ set 経過: 6 分 24 秒
244
+ set 今の epoch の票: 97%
245
+
246
+ step 次の epoch へ進む
247
+ say C0 への票が全体の 2/3 を超えたので、C0 は正当化される。次の epoch では C1 へ票が集まる。
248
+ note C0: 正当化 [color: violet]
249
+ note C1: 提案済み [color: blue]
250
+ now -> 63
251
+ set 経過: 12 分 48 秒
252
+ set 今の epoch の票: 97%
253
+
254
+ step C0 が確定する
255
+ say C1 も正当化されると、続けて正当化された 2 つのうち前の C0 が確定する。確定したブロックは戻せない。
256
+ C0 -> C1: 2/3 を超えた [carry: none]
257
+ note C1: 正当化 [color: violet]
258
+ note C0: 確定 [color: green]
259
+ mark ブロック 0-31 [color: green]
260
+ span 0-31: 確定して戻せない [shape: box, color: rose]
261
+ ```
262
+
263
+ ### 木の図
264
+
265
+ `tree` で始めると、葉の値を親へ畳み上げて1つの根にまとめる構造を段ごとに追う木の図になる。段の中の `leaf <名札> [hash: <値>]` で葉を、`node <名札> of <子>, <子> [hash: <値>]` で親を書くと、書いた段で箱が現れる。
266
+ 葉は書いた順に左から並び、親は子の真ん中の上に置かれ、どの親にも組まれなかった箱が根になる。
267
+ 親子の箱どうしの線の運ぶ物は木の線の上を走り、通った木の線はその色で残る。木の線を運ぶ物が通った段から後は、運ぶ物を送るか受けた箱だけを濃く出す。
268
+
269
+ ```dragon
270
+ tree 取引が含まれることを確かめる
271
+
272
+ step 取引ごとに値を出す
273
+ say 4件の取引それぞれから値を出す。この値が木の葉になる。
274
+ leaf 取引1 [hash: 3fa0]
275
+ leaf 取引2 [hash: 8b04]
276
+ leaf 取引3 [hash: c41d]
277
+ leaf 取引4 [hash: e5f8]
278
+
279
+ step 2つずつ組む
280
+ say 隣どうしの値を2つずつつないで、もう1度値を出す。親が2つできる。
281
+ node 1と2 of 取引1, 取引2 [hash: 7a21]
282
+ node 3と4 of 取引3, 取引4 [hash: b9e4]
283
+
284
+ step 根ができる
285
+ say 残った2つを組むと、全ての取引の値をまとめた根が1つできる。
286
+ node 根 of 1と2, 3と4 [hash: e71c]
287
+
288
+ step 取引3から根まで上る
289
+ say 隣の値を受け取りながら親へ上る。取引1と取引2を読まなくても、根の値が出る。
290
+ 取引3 -> 3と4 [tag: c41d]
291
+ 取引4 -> 3と4 [tag: e5f8]
292
+ 3と4 -> 根 [tag: b9e4]
293
+ 1と2 -> 根 [tag: 7a21]
294
+ ```
295
+
296
+ ## 書き出し
297
+
298
+ 書き出しは画面なしの Chromium で、頁と同じ描画を時刻を止めて 1 コマずつ撮る。
299
+ 撮ったコマは同じ Chromium の中で mp4 と GIF に詰めるので、ffmpeg は要らない。
300
+ Chromium を動かす `playwright-core` は、書き出しを使う時だけ入れる。
301
+
302
+ ```sh
303
+ pnpm add -D playwright-core
304
+ pnpm exec playwright-core install chromium
305
+ ```
306
+
307
+ 原本の JSON (`.json`) か記法 (`.dragon`) を渡すと、同じ名前の 4 つの file を書き出す。
308
+
309
+ ```sh
310
+ dragon export ccip.json --out out
311
+ ```
312
+
313
+ | 設定 | 意味 |
314
+ |---|---|
315
+ | `--out <dir>` | 書き出す先。無ければ作る (既定は今の dir) |
316
+ | `--width <px>` | 枠の幅。見せ方 (全体を止める / 寄って追う) を選び、寄って追う窓の幅になる |
317
+ | `--palette <名前>` | 色味 (`clear` / `paper` / `night`、既定は `paper`) |
318
+ | `--theme <明暗>` | `light` か `dark` |
319
+ | `--lang <言葉>` | 図の中の字 (全体図の札、HTML の読み上げの名前、描けない時の断りの文) と、命令が出す使い方の文と誤りの文の言葉 (`ja` か `en`)。記法の file でも JSON の原本でも、既定は `ja` |
320
+ | `--fps <数>` | mp4 の 1 秒のコマの数 (既定 30) |
321
+ | `--gif-fps <数>` | GIF の 1 秒のコマの数 (既定 10) |
322
+ | `--format <形>` | 書き出す形を `,` で区切る (既定 `mp4,gif,html,png`) |
323
+
324
+ PNG は最後の段の止め絵を、全体を止めた見せ方で撮る。
325
+ 図の中で字が重なる段がある時は、書き出したうえで重なりを段と文で 1 件 1 行ずつ標準エラーに出す (例 `段 5: 段の番号 1 と段の番号 5 が重なる`)。終わり方は 0 のまま変えない。
326
+ HTML は図で描く字だけに削った字の file を埋めた 1 file で、外へ何も取りに行かない。
327
+ node から呼ぶ時は `@cardenelabs/dragon/export` の `exportDiagram` を使う。
328
+
329
+ ## license
330
+
331
+ MIT