@cardenelabs/dragon 0.27.0 → 0.30.0

package/README.md

@@ -65,12 +65,13 @@ flow:
 | `eyebrow`   | 図全体を 1 箱にする図種で、その箱の上に出す小見出し                                                                                        |
 | `axes`      | 2 軸で仕分ける図の軸の名前                                                                                                                 |
 | `readouts`  | 値を見せる部品 (割合の輪 / 数え上げ / 目盛り)                                                                                              |
-| `inputs`    | 読む人が動かすつまみ (すべり / 選び / 入り切り など 14 種)                                                                                 |
-| `formulas`  | つまみの値から決まる値 (式。 `values` は段が動かす状態を読み、こちらはつまみを読む)                                                        |
+| `inputs`    | 読む人が動かすつまみ (すべり / 選び / 入り切り など。 書ける種類は、知らない種類を書いた時の知らせが `使える種類 = ...` の形で全て並べる。 選択肢を `{ value, label }` の組で、入り切りを `onLabel` / `offLabel` で書くと、値は綴りのまま名前で描く) |
+| `formulas`  | つまみの値から決まる値 (式。 `values` は段が動かす状態を読み、こちらはつまみを読む。 `{ expression, label }` の組で書くと操作部に名札を出す) |
 | `events`    | 押下などの出来事で動く仕掛け (相手は名前で指す)                                                                                            |
 | `scrolls`   | 巻き上げに応じて進む値 (画面を巻き上げた量から 0 から 1 を作る)                                                                            |
 | `bands`     | 動いている間の帯 (順序図。 `- DB: 1..2` の形で段の番号の区間を書く)                                                                        |
 | `reveal`    | 矢印をいつ出すか (`phase` = 段が名指しする矢印はその段まで描かない (既定) / `all` = 最初から全部描く)                                      |
+| `relations` | 触れた箱の関係を光らせるか (`off` = 何もしない (既定) / `hover` = 触れた箱と繋がる線と相手の箱だけが光る)                     |
 | `direction` | 図の並ぶ向き (`縦` / `横`、英語なら `vertical` / `horizontal`)。 効くのは `flow` と `swimlane` だけ |
 | `palette`   | 図の配色 (`kinari` = 生成りに茶 / `celadon` = 青磁に墨、日本語なら `生成り` / `青磁`) で、ER 図とクラス図は書かなくても `kinari` になり、書いた `palette:` が優先される |
 
@@ -84,7 +85,7 @@ flow:
 
 | 欄              | 何を書くか                                                                     |
 | --------------- | ------------------------------------------------------------------------------ |
-| `kind`          | 見た目の種別 (`card` / `storage` / `service` / `person` 等、`種類` とも書ける) |
+| `kind`          | 見た目の種別 (`card` / `storage` / `service` / `person` 等、`種類` とも書ける)。 種別に無い名前は部品の名前として部品の一覧 (`partsCatalog`) から引き、一覧にも無ければ種別を書かなかった箱になる。 部品を持つ一覧を渡した時は、書いた行に知らせ (`onNotice`) が出て綴りの近い名前を案内する |
 | `subtitle`      | 題の下の補足 (`補足` とも書ける)                                               |
 | `eyebrow`       | 題の上の小見出し                                                               |
 | `value`         | 箱に出す値 (`値` とも書ける)                                                   |
@@ -96,15 +97,17 @@ flow:
 | `initial`       | 状態遷移図で始まりの状態か                                                     |
 | `final`         | 状態遷移図で終わりの状態か                                                     |
 | `tone`          | 色                                                                             |
-| `nodes`         | 見本 (parts) の中の箱を差し替える                                              |
+| `color`         | 色 (`tone` と同じ意味。 両方書いた時は `tone` を採る)                          |
 | `touchpoint`    | 体験の道筋で、利用者が触れる場所                                               |
 | `opportunity`   | 体験の道筋で、改善の余地                                                       |
 | `owner`         | 工程の並びで、担当                                                             |
-| `end`           | 工程の並びで、終わりの位置                                                     |
+| `end`           | 工程の並びで、終わりの位置。 始まりより前の時期は始まりと同じに倒し、知らせ (`onNotice`) が出る |
 | `posX`          | 置く場所の横位置                                                               |
 | `posY`          | 置く場所の縦位置                                                               |
 | `posW`          | 箱の幅                                                                         |
 | `posH`          | 箱の高さ                                                                       |
+| `offsetX`       | 自動で決まった位置から横へずらす量 (JSON の `pos.x`。 `posX` は座標で、こちらはずらし) |
+| `offsetY`       | 自動で決まった位置から縦へずらす量 (JSON の `pos.y`。 片方だけ書くと残りは 0)  |
 | `scale`         | 見本 (parts) の倍率 (`倍率` とも書ける)                                        |
 | `shape`         | 箱の中に描く図形 (水位 / 角度 / 半径を状態で動かす、`図形` とも書ける)         |
 | `visibleIf`     | その箱を出すかどうかの条件 (`出す条件` とも書ける)                             |
@@ -125,24 +128,27 @@ flow:
 
 | 欄               | 何を書くか                                                          |
 | ---------------- | ------------------------------------------------------------------- |
-| `sub`            | 説明の下の補足                                                      |
+| `sub`            | 説明の下の補足 (クラス図では行き先の端の多重度)                     |
+| `tailSub`        | クラス図の出どころ側の多重度 (`1` 等)。 出どころの端の近くに出る     |
 | `guard`          | 状態遷移の条件                                                      |
-| `cardinality`    | 関係の多重度 (`1:N` 等)                                             |
+| `cardinality`    | ER 図の関係の多重度 (`1:1` / `1:N` / `N:1` / `N:M` / `0..1` / `1..*`)。 両端の形が語から決まり (`tailHead` / `head` を書けばそちらが勝つ)、語は説明の下の行に出る。 6 語以外の語と、ER 図以外に書いた多重度は端の形にならず、知らせ (`onNotice`) が出る |
 | `widthBind`      | 線の太さを値に追随させる (状態やつまみの名前を `{名前}` の形で書く) |
 | `strokeBind`     | 線の色を値に追随させる (`widthBind` と同じ読み方)                   |
 | `dashOffsetBind` | 破線の位置を値に追随させる (流れているように見せる)                 |
 | `side`           | 矢印がどの辺から出るか (`top` / `right` / `bottom` / `left`)        |
-| `head`           | 矢印の先の形 (`triangle` 継ぐ / `diamond` 持つ / `open` 使う / `crow` 多 / `one` `zero-one` `many` `zero-many` ER の端 / `none` 描かない) |
+| `head`           | 矢印の先の形 (`triangle` 継承・実装 / `diamond` 集約・コンポジション / `open` 関連・依存 / `crow` 多 / `one` `zero-one` `many` `zero-many` ER の端 / `none` 描かない) |
 | `tailHead`       | 出どころ側の端の形 (ER は端ごとに違う個数を示すので両端に要る) |
 | `headFill`       | 端の印の塗り (`solid` 塗る / `hollow` 白抜き) |
 | `tailHeadFill`   | 出どころ側の印の塗り |
-| `relation`       | クラス図の関係の種類 (`extends` 継ぐ / `implements` 満たす / `aggregates` 持つ / `composes` 抱える / `associates` 結ぶ / `uses` 使う)。 書くと線と端の形と塗りと付く側がまとめて決まる |
+| `relation`       | クラス図の関係の種類 (`extends` 継承 / `implements` 実装 / `aggregates` 集約 / `composes` コンポジション / `associates` 関連 / `uses` 依存)。 書くと線と端の形と塗りと付く側がまとめて決まる |
 | `kind`           | 順序図の言づての種類 (`call` 呼ぶ / `return` 返す / `fire` 投げる) |
 | `role`           | 辺の役目 (`main` 主となる道)。 書いた辺だけ「いま」 の色で引く。 主となる 1 本 (または 1 続き) にだけ書く |
 | `labelPlate`     | 説明文の下地を敷くか (`false` で外す)。 丸い下地は箱と同じ形なので、罫の細い図では名前が小さな箱に見える |
 | `labelOffsetX`   | 説明文の位置を横にずらす                                            |
 | `labelOffsetY`   | 説明文の位置を縦にずらす                                            |
 | `overlay`        | `true` で説明文を線の上に重ねる (分岐図の条件ラベル用)              |
+| `fromPartNode`   | 出どころが部品 (kind に部品の名前を書いた箱) の時、矢印を繋ぐ部品の中の要素の id。 要素を 1 つだけ持つ部品は書かなくてもその要素に繋がり、2 つ以上持つ部品は書かないと矢印を外して知らせる |
+| `toPartNode`     | 行き先が部品の時、矢印を繋ぐ部品の中の要素の id (`fromPartNode` と同じ読み方) |
 
 <!-- notation:flow:end -->
 
@@ -171,6 +177,22 @@ actors:
 `lanes:` の id は組み立て側が作る形に合わせて、字 / 数 / 下線 / hyphen を受ける
 (`lane-idle` のような自動で作られた縦列の幅も書き直せる)。
 
+`groups:` は並べた縦列のうち何本かを 1 つの枠で囲む。 枠は縦列の位置が決まった後に、束ねた縦列と
+中の箱を全て含む位置と大きさで描かれ、縦列と箱の位置は組を書かない図と変わらない。
+
+```yaml
+lanes:
+  web: { label: "受付の層" }
+  app: { label: "処理の層" }
+  db: { label: "保存の層" }
+
+groups:
+  inside: { label: "社内の網", lanes: [app, db] }
+```
+
+図に無い縦列は除いて囲み、1 本も無ければ枠を描かない。 束ねる縦列の間に束ねない縦列を挟むと、
+その縦列ごと囲む。 どちらも知らせが出る。
+
 ### 静止した `type: flow` は書いた矢印の端を使わない
 
 この図種は **登場人物を書いた順に鎖状に繋ぐ**。 矢印の説明文は「その箱を to に持つ行」
@@ -186,8 +208,92 @@ flow:
   - C -> B: "y" # 出来るのは B -> C
 ```
 
-書いた端どおりに繋ぎたい時は箱に `lane:` を書く。 縦列を書いた形は別の組み立てを通り、
-書いた端がそのまま矢印になる。 端が使われなかった行には知らせが出る。
+書いた端どおりに繋ぎたい時は `direction: 縦` を書くか、箱に `lane:` を書く。 向きか縦列を書いた形は
+別の組み立てを通り、書いた端がそのまま矢印になる。 `direction: 縦` は並びも鎖の時と変わらない。
+段 (`animation`) を書いた形も同じく書いた端を使う。 端が使われなかった行には知らせが出る。
+
+部品 (`kind` に部品の名前を書いた箱) は、どの行の端にも書かれていなければ鎖に入らない。
+部品は図の下に並び、`受付 / 部品 / 出荷` と書いても `受付 -> 出荷` が繋がる。
+
+図の下に並ぶ部品と位置を書いた部品は、部品のすぐ上に登場人物の名前の名札を 1 つ出す
+(`flow` / `sequence` / `topology` / `c4`)。 部品の中に縦列を 2 本以上持つ部品でも名札は 1 つで、
+部品が自分の縦列に書いた名札はそのまま残る。 部品をいくつ並べても、縦列が右へ送られて図が横に伸びることはない。
+
+部品の中の要素は、部品の頁と同じ間で並ぶ。 頁で空けた箱の間と段の間が図に置いても詰まらないので、
+部品の中の要素どうしが間隔の検査に掛からない。 頁の配置が使えない部品だけは、部品に書いた縦列の位置と
+段の番号で置く。
+
+### 段の `focus:` で部品の全体か中の 1 つを光らせる
+
+段の `focus:` に部品の名前を書くと、部品の要素と部品の中の線が全て光る。
+中の 1 つだけを光らせる時は `{部品の名前}__{要素の id}` か `{部品の名前}__{中の線の id}` を書く。
+要素の id は矢印の `fromPartNode` / `toPartNode` に書く id と同じ。
+
+```yaml
+title: "注文を 2 つの窓口へ分ける"
+type: swimlane
+
+actors:
+  - 受注: { kind: card }
+  - split: { kind: split-router, phase: false }
+
+flow:
+  - 受注 -> split: "注文" { toPartNode: inP }
+
+animation:
+  - step: "注文が入る" 1.2s
+    focus: [split__inP]
+  - step: "A へ渡す" 1.2s
+    focus: [split__outA, split__sr-a]
+  - step: "まとめて見せる" 1.2s
+    focus: [split]
+```
+
+| 段 | 光る所 |
+|---|---|
+| 注文が入る | 振り分け器の入口 (`inP`) だけ |
+| A へ渡す | 出口 A (`outA`) と、入口から出口 A への中の線 (`sr-a`) |
+| まとめて見せる | 振り分け器の要素と中の線の全て |
+
+部品に無い名前を書くと何も光らず、知らせ (`focus-target-missing`) が部品の要素と中の線の名前を案内する。
+部品の名前そのものが `__` を含む時は、一番長く一致する部品の名前で読む。
+
+### 順序図の段は `focus:` で強調する言づてを選ぶ
+
+`sequence` / `solidity` の図は 1 枚の板に言づてを行で並べる。 段ごとに 1 通を強調し、それより前は
+描き済みとして残し、後ろは隠す。 どの言づてを強調するかは段の `focus:` から決まる。
+
+| `focus:` に書いたもの | 合う言づて |
+|---|---|
+| 矢印 `A -> B` | 元が A で先が B |
+| 箱の名前 2 つ以上 | 元と先の両方が書いた箱に含まれる |
+| 箱の名前 1 つ | 元か先がその箱 |
+
+矢印を 1 本でも書いた段は、矢印だけで言づてを選ぶ。 同じ段の箱の名前は数えない。
+
+言づては先頭から段の数に切り分け、各段が続きの言づてを受け持つ。 切り分けは次の順に良いものを選ぶ。
+
+1. 合う言づてを持つ段が多い (どの段も板を進める)
+2. 段に合う言づての数が多い
+3. 2 つの段に合う言づてを、図全体で合う言づてが少ない段 (狭く指した段) に置く
+
+段はその区間で合う最後の言づてを強調する。 合う言づてが無い段は前の段の強調を保つ。
+
+```yaml
+flow:
+  - 利用者 -> 認証窓口: "POST 認証情報"
+  - 認証窓口 -> DB: "照合"
+  - 認証窓口 -> 利用者: "JWT を発行"
+
+animation:
+  - step: "照合" 1.5s
+    focus: [利用者, 認証窓口, DB]   # 1-2 通目を束ね、「照合」 を強調する
+  - step: "発行" 1.0s
+    focus: [認証窓口, 利用者]       # 3 通目を強調する
+```
+
+段の題と強調する言づてを確実に揃えたい時は、矢印で書く。 同じ 2 者の矢印が続く時は、同じ矢印を段の数だけ
+並べれば 1 通ずつ進む。
 
 ## API
 
@@ -199,7 +305,8 @@ flow:
 
 **JSON DSL (LLM 向け)**
 
-- `jsonToDiagram(json: unknown): CdlDiagram` ... JSON DSL → CdlDiagram、 validation error は throw
+- `jsonToDiagram(json: unknown, opts?): CdlDiagram` ... JSON DSL → CdlDiagram、 validation error は throw。 `opts` は部品の一覧 (`partsCatalog`)、 書いた通りにならなかったことの受け取り口 (`onNotice`)、 書いた場所から行を引く表 (`行の表`) の 3 つ
+- `書いた場所の鍵(...道): string` ... `行の表` の鍵を作る (`書いた場所の鍵("actors", 1)` が `/actors/1`)。 本文の行が分かる入口 (編集画面の YAML 欄) が表を作る時に使い、`jsonToDiagram` が同じ関数で引く
 - `validateDragonJson(json: unknown): { ok, data | errors }` ... compile なしで validation のみ
 - `diagramJsonSchema` ... JSON Schema (Draft 7)、 LLM の tool schema にそのまま注入可能