@cardenelabs/dragon 0.16.0 → 0.18.0

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-import { CdlDiagram, NodeKind, Tone, EdgeStyle, LaidDiagram } from '@cardenelabs/cdl';
+import { NodeKind, Tone, CdlDiagram, 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", "direction"];
 /** 受け付ける図種。 記法一覧はここを見る。 */
 declare const PRESET_TYPES: ReadonlySet<PresetType>;
 /**
@@ -132,6 +132,25 @@ declare const DRAW_TARGETS: ReadonlyMap<string, PresetType>;
 /** `draw:` に書ける語。 表から導く (#1314) */
 declare const DRAW_WORDS: ReadonlySet<string>;
 
+/**
+ * Text DSL i18n キーワード一覧
+ * 日本語 / 英語両対応 (大文字小文字無視)
+ */
+
+/**
+ * 図の並ぶ向き (`direction:`、 #1494)。
+ *
+ * 縦列 (`lane`) は横、段 (`stack`) は縦に置かれるので、向きは「1 つの縦列に積む」 か
+ * 「1 人ずつ縦列を作る」 かの選択になる。 どちらも組み立て側に既にある経路で、
+ * 記法から名指しできる言葉が無かった。
+ */
+declare const DIRECTIONS: readonly ["縦", "横"];
+type DslDirection = (typeof DIRECTIONS)[number];
+/** NodeKind 別名 (日本語 → English) */
+declare const NODE_KIND_ALIAS: Record<string, NodeKind>;
+/** Tone 別名 */
+declare const TONE_ALIAS: Record<string, Tone>;
+
 /**
  * 位置を他の要素からの相対で書くための解決。
  *
@@ -336,6 +355,33 @@ 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;
+    /**
+     * 図の並ぶ向き (`direction:`、 #1494)。
+     *
+     * `縦` は 1 つの縦列に積み、`横` は 1 人ずつ縦列を作る。 効くのは流れ図と泳法図だけで、
+     * 他の図種は並び方そのものが読み方を担うため書いても効かない (知らせを出す)。
+     *
+     * 全ての箱が縦列を書いた形では、書いた縦列が勝つ (同じく知らせを出す)。
+     */
+    direction?: DslDirection;
+    /** `direction:` を書いた行。 効かない時の知らせで、書いた場所を指すために持つ */
+    directionPos?: {
+        line: number;
+    };
     groups?: Record<string, DslGroup>;
     /**
      * 値を見せる部品 (`readouts:`、 #1374)。 割合の輪や数え上げを図の脇に出す。
@@ -418,6 +464,14 @@ type DslActor = {
      */
     previous?: string;
     rows?: string[];
+    /**
+     * 行頭の印 (#1466)。 `rows` と同じ並びで、空文字はその行に印を付けない。
+     *
+     * **語の意味は図の種類が決める**。 ER は `pk` / `fk` / `opt`、状態遷移は
+     * `entry` / `exit` / `do` / `internal`。 印の 2 軸 (形 × 塗り) は共通だが、その軸が
+     * 何を指すかは種類ごとに違う。
+     */
+    marks?: string[];
     /**
      * 箱の中に描く図形 (`shape:`、 #1374)。 水位や角度を状態で動かせる。
      *
@@ -603,6 +657,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 で説明文を矢印の線の上に重ねる。 分岐図の条件ラベル用。 */
@@ -717,6 +800,12 @@ type DslValue = {
     durationMs: number;
 });
 /** ステップ (phase) */
+/** 動いている間の帯 (#1466)。 順序図で、面がいつ動いているかを段の番号で持つ */
+type DslBand = {
+    actor: string;
+    from: number;
+    to: number;
+};
 type DslPhase = {
     name: string;
     durationMs: number;
@@ -836,7 +925,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" | "direction-not-honored" | "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;
     /** 書かれていた行 */
@@ -1007,6 +1096,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;
 /**
  * 位置を書かなかったパーツを格子に並べた時の、 矩形の中心。
  *
@@ -1017,9 +1119,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;
@@ -1028,16 +1130,6 @@ declare function partsGridCenters(baseNodeCount: number, items: ReadonlyArray<{
     cy: number;
 }>;
 
-/**
- * Text DSL i18n キーワード一覧
- * 日本語 / 英語両対応 (大文字小文字無視)
- */
-
-/** NodeKind 別名 (日本語 → English) */
-declare const NODE_KIND_ALIAS: Record<string, NodeKind>;
-/** Tone 別名 */
-declare const TONE_ALIAS: Record<string, Tone>;
-
 /**
  * Notation lint (author 向け修正システム)。
  *
@@ -1496,6 +1588,16 @@ interface DragonJson {
         label?: string;
         lanes: string[];
     }>;
+    /** 順序図で面が動いている間の帯 (#1466)。 記法の最上位 `bands:` と同じ */
+    bands?: {
+        actor: string;
+        from: number;
+        to: number;
+    }[];
+    /** 矢印をいつ出すか (#1470)。 記法の最上位 `reveal:` と同じ */
+    reveal?: EdgeReveal;
+    /** 図の並ぶ向き (#1494)。 記法の最上位 `direction:` と同じ。 JSON は英語の語で書く */
+    direction?: "vertical" | "horizontal";
 }
 interface JsonActor {
     name: string;
@@ -1617,6 +1719,8 @@ interface JsonActor {
      * 読めない項目名として知らせる)。
      */
     scale?: number;
+    /** 行頭の印 (#1466)。 行と対で読む。 語の意味は図の種類が決める */
+    marks?: string[];
 }
 /** 2 軸で仕分ける図の軸の名前 (#1294)。 記法の `axes:` と同じ形 */
 interface JsonAxes {
@@ -1643,6 +1747,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` 等) も受ける。
      *
@@ -1874,6 +1993,13 @@ declare const diagramJsonSchema: {
                             };
                             description: string;
                         };
+                        marks: {
+                            type: string;
+                            items: {
+                                type: string;
+                            };
+                            description: string;
+                        };
                         lane: {
                             type: string;
                             description: string;
@@ -2158,6 +2284,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;
@@ -2922,6 +3078,41 @@ declare const diagramJsonSchema: {
                 pattern: string;
             };
         };
+        direction: {
+            type: string;
+            enum: string[];
+            description: 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;
@@ -3046,4 +3237,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 トークンの種類, 区間に広げる, 記法を分解する };