@cardenelabs/dragon 0.28.0 → 0.30.0

package/README.md

@@ -65,7 +65,7 @@ flow:
 | `eyebrow`   | 図全体を 1 箱にする図種で、その箱の上に出す小見出し                                                                                        |
 | `axes`      | 2 軸で仕分ける図の軸の名前                                                                                                                 |
 | `readouts`  | 値を見せる部品 (割合の輪 / 数え上げ / 目盛り)                                                                                              |
-| `inputs`    | 読む人が動かすつまみ (すべり / 選び / 入り切り など 14 種。 選択肢を `{ value, label }` の組で、入り切りを `onLabel` / `offLabel` で書くと、値は綴りのまま名前で描く) |
+| `inputs`    | 読む人が動かすつまみ (すべり / 選び / 入り切り など。 書ける種類は、知らない種類を書いた時の知らせが `使える種類 = ...` の形で全て並べる。 選択肢を `{ value, label }` の組で、入り切りを `onLabel` / `offLabel` で書くと、値は綴りのまま名前で描く) |
 | `formulas`  | つまみの値から決まる値 (式。 `values` は段が動かす状態を読み、こちらはつまみを読む。 `{ expression, label }` の組で書くと操作部に名札を出す) |
 | `events`    | 押下などの出来事で動く仕掛け (相手は名前で指す)                                                                                            |
 | `scrolls`   | 巻き上げに応じて進む値 (画面を巻き上げた量から 0 から 1 を作る)                                                                            |
@@ -85,7 +85,7 @@ flow:
 
 | 欄              | 何を書くか                                                                     |
 | --------------- | ------------------------------------------------------------------------------ |
-| `kind`          | 見た目の種別 (`card` / `storage` / `service` / `person` 等、`種類` とも書ける) |
+| `kind`          | 見た目の種別 (`card` / `storage` / `service` / `person` 等、`種類` とも書ける)。 種別に無い名前は部品の名前として部品の一覧 (`partsCatalog`) から引き、一覧にも無ければ種別を書かなかった箱になる。 部品を持つ一覧を渡した時は、書いた行に知らせ (`onNotice`) が出て綴りの近い名前を案内する |
 | `subtitle`      | 題の下の補足 (`補足` とも書ける)                                               |
 | `eyebrow`       | 題の上の小見出し                                                               |
 | `value`         | 箱に出す値 (`値` とも書ける)                                                   |
@@ -101,7 +101,7 @@ flow:
 | `touchpoint`    | 体験の道筋で、利用者が触れる場所                                               |
 | `opportunity`   | 体験の道筋で、改善の余地                                                       |
 | `owner`         | 工程の並びで、担当                                                             |
-| `end`           | 工程の並びで、終わりの位置                                                     |
+| `end`           | 工程の並びで、終わりの位置。 始まりより前の時期は始まりと同じに倒し、知らせ (`onNotice`) が出る |
 | `posX`          | 置く場所の横位置                                                               |
 | `posY`          | 置く場所の縦位置                                                               |
 | `posW`          | 箱の幅                                                                         |
@@ -131,7 +131,7 @@ flow:
 | `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` | 破線の位置を値に追随させる (流れているように見せる)                 |
@@ -223,6 +223,78 @@ flow:
 部品の中の要素どうしが間隔の検査に掛からない。 頁の配置が使えない部品だけは、部品に書いた縦列の位置と
 段の番号で置く。
 
+### 段の `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
 
 **Text DSL (人向け YAML)**
@@ -233,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 にそのまま注入可能