@cardenelabs/dragon 0.14.0 → 0.16.0

package/dist/index.d.cts

@@ -1,4 +1,136 @@
 import { CdlDiagram, NodeKind, Tone, EdgeStyle, LaidDiagram } from '@cardenelabs/cdl';
+export { CdlDiagram } from '@cardenelabs/cdl';
+
+/**
+ * Text DSL v0.5 parser
+ *
+ * 設計方針:
+ * - keyword は英語のみ (title / type / actors / flow / states / animation / step / focus / tween / set / badge)
+ * - 値の日本語は quote 必須 (`title: "API call"` / `step: "request" 1.5s`)
+ * - YAML 風 + 短縮 keyword + 箇条書き構造
+ * - Mermaid 知ってる人にもゼロ学習、 非エンジニアにも直感的
+ *
+ * syntax 例:
+ *
+ *   title: "API call"
+ *   type: sequence
+ *
+ *   actors:
+ *     - Client
+ *     - API: function
+ *     - DB
+ *
+ *   flow:
+ *     - Client -> API: "GET /items"
+ *     - API -> DB: "SELECT" (success)
+ *
+ *   states:
+ *     request_count: 0
+ *     row_count: 0
+ *
+ *   animation:
+ *     - step: "request" 1.5s
+ *       focus: [Client, API]
+ *       tween:
+ *         request_count: 0 -> 1
+ *       badge: "request"
+ *
+ *     - step: "query" 1.5s
+ *       focus: [API, DB]
+ *       tween:
+ *         row_count: 0 -> 20
+ *       badge: "query"
+ *
+ * 出力は v0.4 と同じ DslDocument。 既存 compile.ts で CdlDiagram に変換できる。
+ */
+
+type V05ParseResult = {
+    ok: true;
+    doc: DslDocument;
+} | {
+    ok: false;
+    errors: DslError[];
+};
+/**
+ * 記法が受ける top-level の項目 (#1190)。
+ *
+ * 読めない行の案内と、記法一覧が全て載せているかの検査が、どちらもここを見る。 一覧に手で
+ * 書くと、項目を足した時に案内か一覧のどちらかが取り残される (実際に `states` / `values` が
+ * 一覧に 1 件も無い状態で放置されていた)。
+ */
+declare const TOP_LEVEL_KEYS: readonly ["title", "type", "actors", "flow", "states", "values", "animation", "viewport", "lanes", "groups", "eyebrow", "axes", "readouts", "inputs", "formulas", "events", "scrolls"];
+/** 受け付ける図種。 記法一覧はここを見る。 */
+declare const PRESET_TYPES: ReadonlySet<PresetType>;
+/**
+ * 記法だけが持つ種類。 描画側には無いが、 図種ごとの組み立てで意味を持つ。
+ *
+ * `contract` / `eoa` / `multisig` / `proxy` / `library` / `interface` は Solidity 図の
+ * 役割分けに、 `entity` / `state` は ER 図と状態遷移図に使う。
+ *
+ * **描画側へ渡す前に必ず読み替える** (`compile.ts` の `描ける種別`)。 読み替えを通さずに渡すと
+ * 図の組み立てが落ちる = 描画側は知らない種類の大きさを引けない (#1420 で実測、
+ * `Cannot read properties of undefined (reading 'h')`)。
+ */
+declare const DSL_ONLY_KINDS: readonly ["entity", "state", "contract", "eoa", "multisig", "proxy", "library", "interface"];
+/** 記法だけが持つ種類。 描画側の `NodeKind` には含まれない */
+type DslOnlyKind = (typeof DSL_ONLY_KINDS)[number];
+/**
+ * 受け付ける箱の種類。 描画できる種類 (cdl の `NODE_KINDS`) に、 記法だけが持つ種類を足す。
+ *
+ * 以前は手書きの 31 種だった。 描画できる 90 種のうち 78 種が記法から書けず、 部品名として
+ * 扱われて「そんな部品は無い」 と警告が出るだけだった。 描画側を出所に加えることで
+ * 「描画できるものは書ける」 が成立する。
+ */
+/**
+ * 記法が受理する種類の全体。 これに載っていない種類は見本 (パーツ) の候補になる。
+ *
+ * 画面側が「本文が見本を使っているか」 を判定するのに使う (#1022)。 手書きの一覧を
+ * 別に持つと、種類が増えた時にそちらだけ取り残されて余分な読み込みが起きる。
+ */
+declare const NODE_KIND_VALID: ReadonlySet<string>;
+declare function parseTextDslV05(src: string): V05ParseResult;
+/**
+ * 対応する引用符だけを外す。
+ *
+ * 先頭と末尾を別々に外すと、対応しない形 (`'300,200"`) が中身だけ取り出せてしまう。
+ * 画面側も同じ関数を使う (#1028) = 別々に持つと、片方だけが読める本文ができる。
+ */
+declare function stripQuotes(s: string): string;
+/**
+ * 段に書ける項目の英語名。 `parsePhase` が受け付ける名前の入口でも使う。
+ *
+ * 誤りの案内で使うほか、**見本が値の名前にこの語を使っていないか** を見るのにも使う
+ * (#1330)。 段の項目と値は階層が違うので衝突しないが、同じ語が 2 つの意味で並ぶと
+ * 見本を読む人が階層から意味を判断することになる。
+ */
+declare const PHASE_ITEM_WORDS: readonly ["focus", "badge", "body", "description", "tween", "set", "draw"];
+/**
+ * `draw:` に書ける語と、その語が効く図種 (#1312 / #1314)。
+ *
+ * **語と図種の対応をここ 1 箇所で持つ**。 受ける語の一覧 (`DRAW_WORDS`) も、組み立て側が見る
+ * 図種の一覧 (`DRAWABLE_DOC_TYPES`) も、この表から導く。 3 つを別々に並べると、語を足した時に
+ * どれかが古いまま残る (#1310 / #1304 で 3 度直した形)。
+ *
+ * | 語 | 図種 | 起点 |
+ * |---|---|---|
+ * | `line` | `line` | 左端から右へ線が伸びる |
+ * | `bar` | `bar` | 横軸から上へ棒が伸びる |
+ * | `pie` | `pie` | 12 時から時計回りに扇が開く |
+ * | `journey` | `journey` | 左端から右へ気持ちの線が伸びる |
+ * | `mind` | `mind` | 中心から外へ枝が伸びる |
+ * | `tree` | `tree` | 根から下へ枝が伸びる |
+ * | `gantt` | `gantt` | 各帯の始端から右へ帯が伸びる |
+ * | `funnel` | `funnel` | 上端から順に段が積まれる |
+ *
+ * `quadrant` は入れない。 4 つの区画に項目を置く図で **項目に順序が無く**、起点を決められない
+ * (順番を書いた順で決めると、動きが図の意味を持たない)。
+ *
+ * いまは語と図種が同じ綴りだが、**同じものとして扱わない**。 語は書き手が書く名前で、
+ * 図種は `type:` が取る値。 片方だけ別名を足したくなった時に、対応が表に残っている形にする。
+ */
+declare const DRAW_TARGETS: ReadonlyMap<string, PresetType>;
+/** `draw:` に書ける語。 表から導く (#1314) */
+declare const DRAW_WORDS: ReadonlySet<string>;
 
 /**
  * 位置を他の要素からの相対で書くための解決。
@@ -82,6 +214,17 @@ declare function orderByDependency(items: ReadonlyArray<{
  * docs/cdl/text-dsl-spec.md の文法を AST に変換した中間表現
  */
 
+/**
+ * 記法が書ける箱の種類 (#1420)。
+ *
+ * 描画できる種類 (`NodeKind`) に、**記法だけが持つ種類** (`contract` / `eoa` など) を足す。
+ * 後者は図種ごとの役割分け (`solidity` の縦列の並べ替えなど) に使い、描画側へ渡す手前で
+ * `compile.ts` の `描ける種別` が読み替える。
+ *
+ * `NodeKind` だけに縛っていた間、記法が受ける値を型が表せていなかった。
+ */
+type DslNodeKind = NodeKind | DslOnlyKind;
+
 /**
  * 箱の中に描く図形 (#1374)。 **描画側の型をそのまま使う**。
  *
@@ -126,7 +269,7 @@ type DslEventBinding = {
     handlerId: string;
     pos: Position;
 };
-type PresetType = "sequence" | "flow" | "swimlane" | "er" | "state" | "topology" | "solidity" | "gantt" | "class" | "pie" | "bar" | "line" | "funnel" | "tree" | "journey" | "quadrant" | "c4" | "mind";
+type PresetType = "sequence" | "flow" | "swimlane" | "er" | "state" | "topology" | "solidity" | "gantt" | "class" | "pie" | "bar" | "line" | "gauge" | "radial" | "stat" | "waffle" | "stacked" | "funnel" | "tree" | "journey" | "quadrant" | "c4" | "mind";
 type Position = {
     line: number;
     column?: number;
@@ -250,7 +393,7 @@ type DslAxes = {
 /** 登場人物 (v0.5+ ... inline option 拡張) */
 type DslActor = {
     name: string;
-    kind: NodeKind;
+    kind: DslNodeKind;
     /**
      * 著者が種類を書いたか。 書かなかった時 `kind` には既定の `actor` が入るため、
      * `kind` の値だけでは「書いた `actor`」 と「書かなかった」 を区別できない。
@@ -264,6 +407,16 @@ type DslActor = {
     subtitle?: string;
     eyebrow?: string;
     value?: string;
+    /**
+     * 前の時点の値 (#1450)。
+     *
+     * 内訳の変化を帯で示す図 (`type: stacked`) が 2 本目の帯として描き、値 1 つを大きく示す図
+     * (`type: stat`) が差として出す。 書かない図は 1 本のまま (従来と同じ)。
+     *
+     * **3 時点以上は持たない**。 描画側が 2 時点で設計されており (`cdl#551`)、足すなら欄の形ごと
+     * 決め直すことになる。
+     */
+    previous?: string;
     rows?: string[];
     /**
      * 箱の中に描く図形 (`shape:`、 #1374)。 水位や角度を状態で動かせる。
@@ -584,6 +737,20 @@ type DslPhase = {
      * 相手の名前は書かせない = 対象の 8 図種はいずれも図全体を 1 箱で描くため相手が決まる。
      */
     draw?: string;
+    /**
+     * 描き終えるまでに段の何割を使うか (#1441)。
+     *
+     * `draw: line 0.4` のように語の後ろに書く。 0 より大きく 1 以下。
+     * 書かなければ段の終わりに描き終わる (従来どおり)。
+     *
+     * **段の長さと描く速さを切り離すための欄**。 伸び具合は段の進みそのものなので、
+     * これが無いと「線はゆっくり引きたいが値の移りは短くしたい」 が書けず、描く速さのために
+     * 段の長さを動かすことになる。 段の長さを動かすと同じ段の `tween` まで遅くなる。
+     *
+     * **`draw` と同じ行に書かせる**。 別の項目にすると「割合だけ書いて `draw` が無い段」 が
+     * 書けてしまい、何も起きない指定になる。 同じ行なら書けない。
+     */
+    drawRatio?: number;
     /**
      * `draw` を書いた行 (#1312)。 知らせの行番号に使う。
      *
@@ -861,124 +1028,6 @@ declare function partsGridCenters(baseNodeCount: number, items: ReadonlyArray<{
     cy: number;
 }>;
 
-/**
- * Text DSL v0.5 parser
- *
- * 設計方針:
- * - keyword は英語のみ (title / type / actors / flow / states / animation / step / focus / tween / set / badge)
- * - 値の日本語は quote 必須 (`title: "API call"` / `step: "request" 1.5s`)
- * - YAML 風 + 短縮 keyword + 箇条書き構造
- * - Mermaid 知ってる人にもゼロ学習、 非エンジニアにも直感的
- *
- * syntax 例:
- *
- *   title: "API call"
- *   type: sequence
- *
- *   actors:
- *     - Client
- *     - API: function
- *     - DB
- *
- *   flow:
- *     - Client -> API: "GET /items"
- *     - API -> DB: "SELECT" (success)
- *
- *   states:
- *     request_count: 0
- *     row_count: 0
- *
- *   animation:
- *     - step: "request" 1.5s
- *       focus: [Client, API]
- *       tween:
- *         request_count: 0 -> 1
- *       badge: "request"
- *
- *     - step: "query" 1.5s
- *       focus: [API, DB]
- *       tween:
- *         row_count: 0 -> 20
- *       badge: "query"
- *
- * 出力は v0.4 と同じ DslDocument。 既存 compile.ts で CdlDiagram に変換できる。
- */
-
-type V05ParseResult = {
-    ok: true;
-    doc: DslDocument;
-} | {
-    ok: false;
-    errors: DslError[];
-};
-/**
- * 記法が受ける top-level の項目 (#1190)。
- *
- * 読めない行の案内と、記法一覧が全て載せているかの検査が、どちらもここを見る。 一覧に手で
- * 書くと、項目を足した時に案内か一覧のどちらかが取り残される (実際に `states` / `values` が
- * 一覧に 1 件も無い状態で放置されていた)。
- */
-declare const TOP_LEVEL_KEYS: readonly ["title", "type", "actors", "flow", "states", "values", "animation", "viewport", "lanes", "groups", "eyebrow", "axes", "readouts", "inputs", "formulas", "events", "scrolls"];
-/** 受け付ける図種。 記法一覧はここを見る。 */
-declare const PRESET_TYPES: ReadonlySet<PresetType>;
-/**
- * 受け付ける箱の種類。 描画できる種類 (cdl の `NODE_KINDS`) に、 記法だけが持つ種類を足す。
- *
- * 以前は手書きの 31 種だった。 描画できる 90 種のうち 78 種が記法から書けず、 部品名として
- * 扱われて「そんな部品は無い」 と警告が出るだけだった。 描画側を出所に加えることで
- * 「描画できるものは書ける」 が成立する。
- */
-/**
- * 記法が受理する種類の全体。 これに載っていない種類は見本 (パーツ) の候補になる。
- *
- * 画面側が「本文が見本を使っているか」 を判定するのに使う (#1022)。 手書きの一覧を
- * 別に持つと、種類が増えた時にそちらだけ取り残されて余分な読み込みが起きる。
- */
-declare const NODE_KIND_VALID: ReadonlySet<string>;
-declare function parseTextDslV05(src: string): V05ParseResult;
-/**
- * 対応する引用符だけを外す。
- *
- * 先頭と末尾を別々に外すと、対応しない形 (`'300,200"`) が中身だけ取り出せてしまう。
- * 画面側も同じ関数を使う (#1028) = 別々に持つと、片方だけが読める本文ができる。
- */
-declare function stripQuotes(s: string): string;
-/**
- * 段に書ける項目の英語名。 `parsePhase` が受け付ける名前の入口でも使う。
- *
- * 誤りの案内で使うほか、**見本が値の名前にこの語を使っていないか** を見るのにも使う
- * (#1330)。 段の項目と値は階層が違うので衝突しないが、同じ語が 2 つの意味で並ぶと
- * 見本を読む人が階層から意味を判断することになる。
- */
-declare const PHASE_ITEM_WORDS: readonly ["focus", "badge", "body", "description", "tween", "set", "draw"];
-/**
- * `draw:` に書ける語と、その語が効く図種 (#1312 / #1314)。
- *
- * **語と図種の対応をここ 1 箇所で持つ**。 受ける語の一覧 (`DRAW_WORDS`) も、組み立て側が見る
- * 図種の一覧 (`DRAWABLE_DOC_TYPES`) も、この表から導く。 3 つを別々に並べると、語を足した時に
- * どれかが古いまま残る (#1310 / #1304 で 3 度直した形)。
- *
- * | 語 | 図種 | 起点 |
- * |---|---|---|
- * | `line` | `line` | 左端から右へ線が伸びる |
- * | `bar` | `bar` | 横軸から上へ棒が伸びる |
- * | `pie` | `pie` | 12 時から時計回りに扇が開く |
- * | `journey` | `journey` | 左端から右へ気持ちの線が伸びる |
- * | `mind` | `mind` | 中心から外へ枝が伸びる |
- * | `tree` | `tree` | 根から下へ枝が伸びる |
- * | `gantt` | `gantt` | 各帯の始端から右へ帯が伸びる |
- * | `funnel` | `funnel` | 上端から順に段が積まれる |
- *
- * `quadrant` は入れない。 4 つの区画に項目を置く図で **項目に順序が無く**、起点を決められない
- * (順番を書いた順で決めると、動きが図の意味を持たない)。
- *
- * いまは語と図種が同じ綴りだが、**同じものとして扱わない**。 語は書き手が書く名前で、
- * 図種は `type:` が取る値。 片方だけ別名を足したくなった時に、対応が表に残っている形にする。
- */
-declare const DRAW_TARGETS: ReadonlyMap<string, PresetType>;
-/** `draw:` に書ける語。 表から導く (#1314) */
-declare const DRAW_WORDS: ReadonlySet<string>;
-
 /**
  * Text DSL i18n キーワード一覧
  * 日本語 / 英語両対応 (大文字小文字無視)
@@ -1486,6 +1535,13 @@ interface JsonActor {
     subtitle?: string;
     eyebrow?: string;
     value?: string;
+    /**
+     * 前の時点の値 (#1450)。 記法の `{ value: "320", previous: "280" }` と同じ。
+     *
+     * 内訳の変化を帯で示す図 (`type: stacked`) が 2 本目の帯として描き、
+     * 値 1 つを大きく示す図 (`type: stat`) が差として出す。 書かない図は 1 本のまま。
+     */
+    previous?: string;
     rows?: string[];
     lane?: string;
     stack?: number;
@@ -1630,6 +1686,13 @@ interface JsonPhase {
      * 受ける 8 語は `DRAW_WORDS` が持つ。 語と同じ図種で、その段の間に図が起点から現れる。
      */
     draw?: string;
+    /**
+     * 描き終えるまでに段の何割を使うか (#1441)。 記法の `draw: line 0.4` の後半と同じ。
+     *
+     * 0 より大きく 1 以下。 書かなければ段の終わりに描き終わる。 `draw` が無い段に書いても
+     * 何も起きない (描く相手が決まらないため、写す時に外す)。
+     */
+    drawRatio?: number;
     /**
      * 段の中で値を動かす (#1186)。 記法の `tween: name 100 -> 90` と同じ。
      *
@@ -1800,6 +1863,10 @@ declare const diagramJsonSchema: {
                             type: string;
                             description: string;
                         };
+                        previous: {
+                            type: string;
+                            description: string;
+                        };
                         rows: {
                             type: string;
                             items: {
@@ -2207,6 +2274,12 @@ declare const diagramJsonSchema: {
                         enum: string[];
                         description: string;
                     };
+                    drawRatio: {
+                        type: string;
+                        exclusiveMinimum: number;
+                        maximum: number;
+                        description: string;
+                    };
                     tween: {
                         type: string;
                         description: string;