@cardenelabs/dragon 0.15.0 → 0.17.0

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-import { CdlDiagram, NodeKind, Tone, EdgeStyle, LaidDiagram } from '@cardenelabs/cdl';
+import { CdlDiagram, NodeKind, Tone, EdgeStyle, EdgeHead, EdgeHeadFill, ClassRelationType, SequenceMessageKind, EdgeReveal, LaidDiagram } from '@cardenelabs/cdl';
 export { CdlDiagram } from '@cardenelabs/cdl';
 
 /**
@@ -58,7 +58,7 @@ type V05ParseResult = {
  * 書くと、項目を足した時に案内か一覧のどちらかが取り残される (実際に `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 TOP_LEVEL_KEYS: readonly ["title", "type", "actors", "flow", "states", "values", "animation", "viewport", "lanes", "groups", "eyebrow", "axes", "readouts", "inputs", "formulas", "events", "scrolls", "bands", "reveal"];
 /** 受け付ける図種。 記法一覧はここを見る。 */
 declare const PRESET_TYPES: ReadonlySet<PresetType>;
 /**
@@ -269,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;
@@ -336,6 +336,20 @@ type DslDocument = {
     /** v0.5+ 拡張 ... viewport / lanes / groups */
     viewport?: DslViewport;
     lanes?: Record<string, DslLane>;
+    /**
+     * 動いている間の帯 (#1466)。 順序図だけが読む。
+     *
+     * 書かなければ面ごとに「最初に関わった段から最後まで」 の 1 本。 途中で手が空く面を
+     * 分けたい図だけ書く = どこで手が空くかは言づての並びからは決まらない。
+     */
+    bands?: DslBand[];
+    /**
+     * 矢印をいつ出すか (`reveal:`、 #1470)。
+     *
+     * 既定 (`phase`) は「段が名指しする矢印は、その段が来るまで描かない」。 `all` と書くと
+     * 段に関わらず最初から全部描く。 描き手の `CdlDiagram.edgeReveal` にそのまま渡る。
+     */
+    reveal?: EdgeReveal;
     groups?: Record<string, DslGroup>;
     /**
      * 値を見せる部品 (`readouts:`、 #1374)。 割合の輪や数え上げを図の脇に出す。
@@ -407,7 +421,25 @@ type DslActor = {
     subtitle?: string;
     eyebrow?: string;
     value?: string;
+    /**
+     * 前の時点の値 (#1450)。
+     *
+     * 内訳の変化を帯で示す図 (`type: stacked`) が 2 本目の帯として描き、値 1 つを大きく示す図
+     * (`type: stat`) が差として出す。 書かない図は 1 本のまま (従来と同じ)。
+     *
+     * **3 時点以上は持たない**。 描画側が 2 時点で設計されており (`cdl#551`)、足すなら欄の形ごと
+     * 決め直すことになる。
+     */
+    previous?: string;
     rows?: string[];
+    /**
+     * 行頭の印 (#1466)。 `rows` と同じ並びで、空文字はその行に印を付けない。
+     *
+     * **語の意味は図の種類が決める**。 ER は `pk` / `fk` / `opt`、状態遷移は
+     * `entry` / `exit` / `do` / `internal`。 印の 2 軸 (形 × 塗り) は共通だが、その軸が
+     * 何を指すかは種類ごとに違う。
+     */
+    marks?: string[];
     /**
      * 箱の中に描く図形 (`shape:`、 #1374)。 水位や角度を状態で動かせる。
      *
@@ -593,6 +625,35 @@ type DslStep = {
     dashOffsetBind?: string;
     /** 矢印がどの辺から出るか (#1385)。 書かなければ描画側が自動で選ぶ */
     side?: "top" | "right" | "bottom" | "left";
+    /**
+     * 矢印の先の形 (#1462)。 書かなければ従来どおり塗った三角。
+     *
+     * 4 図の設計は **端の形で関係の種類を示す** = 三角 (継ぐ) / 菱 (持つ) /
+     * 開いた矢 (使う) / 鳥の足 (多)。 書けないと 4 種とも同じ三角になり、
+     * 線の種類 (実線 / 点線) だけで 6 種の関係を区別することになる。
+     *
+     * 受ける語は描画側の `EDGE_HEADS` から導く = 描画側が増やせば書けるようになる。
+     */
+    head?: EdgeHead;
+    /** 出どころ側の端の形 (#1466)。 ER は端ごとに違う個数を示すので両端に要る */
+    tailHead?: EdgeHead;
+    /** 端の印の塗り (#1466)。 白抜きの菱が「持つ」、塗った菱が「抱える」 */
+    headFill?: EdgeHeadFill;
+    /** 出どころ側の印の塗り (#1466) */
+    tailHeadFill?: EdgeHeadFill;
+    /**
+     * クラス図の関係の種類 (#1466)。 書くと線と端の形と塗りと付く側がまとめて決まる。
+     *
+     * 4 つを個別に書かせないのは、組合せが 6 通りしか無く、1 つでも書き違えると読み手に
+     * 別の意味で伝わるため (菱を逆に置くと持ち主が入れ替わる)。
+     */
+    relation?: ClassRelationType;
+    /**
+     * 言づての種類 (#1466)。 順序図で線と矢の形がまとめて決まる。
+     *
+     * `kind` にしないのは、箱の種類 (`DslActor.kind`) と同じ語が別の意味を持つため。
+     */
+    msgKind?: SequenceMessageKind;
     labelOffsetX?: number;
     labelOffsetY?: number;
     /** true で説明文を矢印の線の上に重ねる。 分岐図の条件ラベル用。 */
@@ -707,6 +768,12 @@ type DslValue = {
     durationMs: number;
 });
 /** ステップ (phase) */
+/** 動いている間の帯 (#1466)。 順序図で、面がいつ動いているかを段の番号で持つ */
+type DslBand = {
+    actor: string;
+    from: number;
+    to: number;
+};
 type DslPhase = {
     name: string;
     durationMs: number;
@@ -727,6 +794,20 @@ type DslPhase = {
      * 相手の名前は書かせない = 対象の 8 図種はいずれも図全体を 1 箱で描くため相手が決まる。
      */
     draw?: string;
+    /**
+     * 描き終えるまでに段の何割を使うか (#1441)。
+     *
+     * `draw: line 0.4` のように語の後ろに書く。 0 より大きく 1 以下。
+     * 書かなければ段の終わりに描き終わる (従来どおり)。
+     *
+     * **段の長さと描く速さを切り離すための欄**。 伸び具合は段の進みそのものなので、
+     * これが無いと「線はゆっくり引きたいが値の移りは短くしたい」 が書けず、描く速さのために
+     * 段の長さを動かすことになる。 段の長さを動かすと同じ段の `tween` まで遅くなる。
+     *
+     * **`draw` と同じ行に書かせる**。 別の項目にすると「割合だけ書いて `draw` が無い段」 が
+     * 書けてしまい、何も起きない指定になる。 同じ行なら書けない。
+     */
+    drawRatio?: number;
     /**
      * `draw` を書いた行 (#1312)。 知らせの行番号に使う。
      *
@@ -812,7 +893,7 @@ interface CompileToCdlOpts {
 }
 /** 図は出せるが書いた通りにならなかった、 という知らせ。 */
 type CompileNotice = {
-    kind: "relative-position-ignored" | "focus-target-missing" | "state-override-rejected" | "external-paint-dropped" | "part-not-drawn" | "scale-reserved" | "chart-value-unreadable" | "chart-edge-dropped" | "value-shadows-state" | "value-unresolved" | "value-duplicate" | "flow-actor-missing" | "value-trigger-unresolved" | "flow-self-loop" | "lane-not-honored" | "lane-declared-empty" | "eyebrow-not-honored" | "flow-endpoint-not-honored" | "draw-not-honored" | "draw-target-mismatch" | "formula-unresolved" | "event-target-missing";
+    kind: "relative-position-ignored" | "focus-target-missing" | "state-override-rejected" | "external-paint-dropped" | "part-not-drawn" | "scale-reserved" | "chart-value-unreadable" | "chart-edge-dropped" | "value-shadows-state" | "value-unresolved" | "value-duplicate" | "flow-actor-missing" | "value-trigger-unresolved" | "lane-not-honored" | "lane-declared-empty" | "eyebrow-not-honored" | "flow-endpoint-not-honored" | "draw-not-honored" | "draw-target-mismatch" | "formula-unresolved" | "event-target-missing" | "actor-kind-not-honored" | "sub-node-not-found" | "message-option-not-honored";
     /** 対象の名前。 光らせる相手なら書かれた指定そのまま */
     actor: string;
     /** 書かれていた行 */
@@ -983,6 +1064,19 @@ declare function partVisualSize(part: CdlDiagram, targetW?: number, targetH?: nu
     w: number;
     h: number;
 };
+/**
+ * 既存の図が縦に何段ぶんを占めるかの目安 (#1481)。
+ *
+ * **箱の数では数えない**。 数で数えると、図を丸ごと 1 つの箱で描く種別が 1 段に潰れる。
+ * 順序図は `#1466` で 1 枚の板になり、高さ 432 の箱 1 つになった = 1 段 (280) と見積もられ、
+ * その下に置いたパーツが板に 31px 重なっていた (実測)。
+ *
+ * 大きさを自分で持つ箱は、その高さから段数を出す。 持たない箱は今までどおり 1 段と数えるので、
+ * 高さを書かない図の並び方は変わらない。
+ */
+declare function partsBaseRows(nodes: ReadonlyArray<{
+    h?: number;
+}>): number;
 /**
  * 位置を書かなかったパーツを格子に並べた時の、 矩形の中心。
  *
@@ -993,9 +1087,9 @@ declare function partVisualSize(part: CdlDiagram, targetW?: number, targetH?: nu
  * 隣と重なる (実測 = 400 の次に 200 を置くと 280 重なった)。 段の高さも段内の最大高で揃える。
  * 縦は自分の高さの半分だけ段の上端から下げて、 段内で上端を揃える。
  *
- * @param baseNodeCount パーツ以外の箱の数。 既存の図の下から並べ始めるために使う
+ * @param baseRows 既存の図が占める段数の目安 (`partsBaseRows`)。 図の下から並べ始めるために使う
  */
-declare function partsGridCenters(baseNodeCount: number, items: ReadonlyArray<{
+declare function partsGridCenters(baseRows: number, items: ReadonlyArray<{
     id: string;
     w: number;
     h: number;
@@ -1472,6 +1566,14 @@ interface DragonJson {
         label?: string;
         lanes: string[];
     }>;
+    /** 順序図で面が動いている間の帯 (#1466)。 記法の最上位 `bands:` と同じ */
+    bands?: {
+        actor: string;
+        from: number;
+        to: number;
+    }[];
+    /** 矢印をいつ出すか (#1470)。 記法の最上位 `reveal:` と同じ */
+    reveal?: EdgeReveal;
 }
 interface JsonActor {
     name: string;
@@ -1511,6 +1613,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;
@@ -1586,6 +1695,8 @@ interface JsonActor {
      * 読めない項目名として知らせる)。
      */
     scale?: number;
+    /** 行頭の印 (#1466)。 行と対で読む。 語の意味は図の種類が決める */
+    marks?: string[];
 }
 /** 2 軸で仕分ける図の軸の名前 (#1294)。 記法の `axes:` と同じ形 */
 interface JsonAxes {
@@ -1612,6 +1723,21 @@ interface JsonStep {
     sub?: string;
     /** 矢印がどの辺から出るか (#1385)。 記法の `side:` と同じ */
     side?: "top" | "right" | "bottom" | "left";
+    /**
+     * 矢印の先の形 (#1462)。 記法の `{ head: triangle }` と同じ。
+     *
+     * 三角 (継ぐ) / 菱 (持つ) / 開いた矢 (使う) / 鳥の足 (多)。
+     * 書かなければ従来どおり塗った三角になる。
+     */
+    head?: EdgeHead;
+    /** 出どころ側の端の形と、両端の塗り (#1466)。 記法の `{ tailHead: diamond }` 等と同じ */
+    tailHead?: EdgeHead;
+    headFill?: EdgeHeadFill;
+    tailHeadFill?: EdgeHeadFill;
+    /** クラス図の関係の語 (#1466)。 書くと端の形 / 塗り / 線種がまとめて決まる */
+    relation?: ClassRelationType;
+    /** 順序図の言づての種類 (#1466)。 `call` / `return` / `fire` */
+    kind?: SequenceMessageKind;
     /**
      * 矢印の色 (#1304)。 記法の `(成功)` と同じく別名 (`成功` / `neutral` 等) も受ける。
      *
@@ -1655,6 +1781,13 @@ interface JsonPhase {
      * 受ける 8 語は `DRAW_WORDS` が持つ。 語と同じ図種で、その段の間に図が起点から現れる。
      */
     draw?: string;
+    /**
+     * 描き終えるまでに段の何割を使うか (#1441)。 記法の `draw: line 0.4` の後半と同じ。
+     *
+     * 0 より大きく 1 以下。 書かなければ段の終わりに描き終わる。 `draw` が無い段に書いても
+     * 何も起きない (描く相手が決まらないため、写す時に外す)。
+     */
+    drawRatio?: number;
     /**
      * 段の中で値を動かす (#1186)。 記法の `tween: name 100 -> 90` と同じ。
      *
@@ -1825,6 +1958,10 @@ declare const diagramJsonSchema: {
                             type: string;
                             description: string;
                         };
+                        previous: {
+                            type: string;
+                            description: string;
+                        };
                         rows: {
                             type: string;
                             items: {
@@ -1832,6 +1969,13 @@ declare const diagramJsonSchema: {
                             };
                             description: string;
                         };
+                        marks: {
+                            type: string;
+                            items: {
+                                type: string;
+                            };
+                            description: string;
+                        };
                         lane: {
                             type: string;
                             description: string;
@@ -2116,6 +2260,36 @@ declare const diagramJsonSchema: {
                         enum: string[];
                         description: string;
                     };
+                    head: {
+                        type: string;
+                        enum: string[];
+                        description: string;
+                    };
+                    tailHead: {
+                        type: string;
+                        enum: string[];
+                        description: string;
+                    };
+                    headFill: {
+                        type: string;
+                        enum: string[];
+                        description: string;
+                    };
+                    tailHeadFill: {
+                        type: string;
+                        enum: string[];
+                        description: string;
+                    };
+                    relation: {
+                        type: string;
+                        enum: string[];
+                        description: string;
+                    };
+                    kind: {
+                        type: string;
+                        enum: string[];
+                        description: string;
+                    };
                     labelOffsetX: {
                         type: string;
                         description: string;
@@ -2232,6 +2406,12 @@ declare const diagramJsonSchema: {
                         enum: string[];
                         description: string;
                     };
+                    drawRatio: {
+                        type: string;
+                        exclusiveMinimum: number;
+                        maximum: number;
+                        description: string;
+                    };
                     tween: {
                         type: string;
                         description: string;
@@ -2874,6 +3054,36 @@ declare const diagramJsonSchema: {
                 pattern: string;
             };
         };
+        reveal: {
+            type: string;
+            enum: string[];
+            description: string;
+        };
+        bands: {
+            type: string;
+            description: string;
+            items: {
+                type: string;
+                required: string[];
+                additionalProperties: boolean;
+                properties: {
+                    actor: {
+                        type: string;
+                        description: string;
+                    };
+                    from: {
+                        type: string;
+                        minimum: number;
+                        description: string;
+                    };
+                    to: {
+                        type: string;
+                        minimum: number;
+                        description: string;
+                    };
+                };
+            };
+        };
         events: {
             type: string;
             description: string;
@@ -2998,4 +3208,4 @@ interface CompileOpts {
  */
 declare function textDslToDiagram(src: string, opts?: CompileOpts): CdlDiagram;
 
-export { type AnchorBox, type CompileNotice, type CompileOpts, DIAGRAM_BOUNDARY_PADDING, DRAW_TARGETS, DRAW_WORDS, type DiagramBoundingBox, type DragonJson, type DslActor, type DslAnimate, type DslDocument, type DslError, type DslGroup, type DslLane, type DslPhase, type DslSet, type DslState, type DslStep, type DslTween, type DslValue, type DslViewport, type FocusEntry, type InputSize, JSONを分解する, type JsonActor, type JsonActorNodeOverride, type JsonAxes, type JsonDslError, type JsonPhase, type JsonStep, type LayoutMode, type LayoutPos, type LintIssue, type LintReport, type LintSeverity, MAX_INPUT_BYTES, MAX_INPUT_ELEMENTS, MAX_PART_SCALE, NODE_KIND_ALIAS, NODE_KIND_VALID, PHASE_ITEM_WORDS, PRESET_TYPES, type PresetType, RELATIVE_GAP_DEFAULT, type RelativeDirection, type RelativePos, TONE_ALIAS, TOP_LEVEL_KEYS, autoFix, compileToCdl, computeDiagramBoundingBox, countBytes, countDiagramElements, countDocElements, describeOversize, describeOversizeSource, diagramJsonSchema, isColorValue, jsonToDiagram, lintDiagram, measureActorBoxes, normalizePartScale, orderByDependency, parseFocusEntry, parseRelativePos, parseTextDsl, parseTextDslV05, partBoxInFrame, partDrawsInDiagram, partIsMeasurable, partRenderSize, partScaleFactor, partTargetScale, partTargetSize, partVisualSize, partsGridCenters, pointsOutside, rectsOverlap, resolveRelativePos, stripExternalPaint, stripQuotes, textDslToDiagram, validateDragonJson, writeActorPosition, type トークン, type トークンの種類, 区間に広げる, 記法を分解する };
+export { type AnchorBox, type CompileNotice, type CompileOpts, DIAGRAM_BOUNDARY_PADDING, DRAW_TARGETS, DRAW_WORDS, type DiagramBoundingBox, type DragonJson, type DslActor, type DslAnimate, type DslDocument, type DslError, type DslGroup, type DslLane, type DslPhase, type DslSet, type DslState, type DslStep, type DslTween, type DslValue, type DslViewport, type FocusEntry, type InputSize, JSONを分解する, type JsonActor, type JsonActorNodeOverride, type JsonAxes, type JsonDslError, type JsonPhase, type JsonStep, type LayoutMode, type LayoutPos, type LintIssue, type LintReport, type LintSeverity, MAX_INPUT_BYTES, MAX_INPUT_ELEMENTS, MAX_PART_SCALE, NODE_KIND_ALIAS, NODE_KIND_VALID, PHASE_ITEM_WORDS, PRESET_TYPES, type PresetType, RELATIVE_GAP_DEFAULT, type RelativeDirection, type RelativePos, TONE_ALIAS, TOP_LEVEL_KEYS, autoFix, compileToCdl, computeDiagramBoundingBox, countBytes, countDiagramElements, countDocElements, describeOversize, describeOversizeSource, diagramJsonSchema, isColorValue, jsonToDiagram, lintDiagram, measureActorBoxes, normalizePartScale, orderByDependency, parseFocusEntry, parseRelativePos, parseTextDsl, parseTextDslV05, partBoxInFrame, partDrawsInDiagram, partIsMeasurable, partRenderSize, partScaleFactor, partTargetScale, partTargetSize, partVisualSize, partsBaseRows, partsGridCenters, pointsOutside, rectsOverlap, resolveRelativePos, stripExternalPaint, stripQuotes, textDslToDiagram, validateDragonJson, writeActorPosition, type トークン, type トークンの種類, 区間に広げる, 記法を分解する };