@cardenelabs/dragon 0.7.0 → 0.8.0

package/dist/index.d.cts

@@ -82,7 +82,7 @@ declare function orderByDependency(items: ReadonlyArray<{
  * docs/cdl/text-dsl-spec.md の文法を AST に変換した中間表現
  */
 
-type PresetType = "sequence" | "flow" | "swimlane" | "er" | "state" | "topology" | "solidity" | "gantt" | "class" | "pie" | "c4" | "mind";
+type PresetType = "sequence" | "flow" | "swimlane" | "er" | "state" | "topology" | "solidity" | "gantt" | "class" | "pie" | "bar" | "line" | "funnel" | "tree" | "journey" | "quadrant" | "c4" | "mind";
 type Position = {
     line: number;
     column?: number;
@@ -110,9 +110,42 @@ type LayoutMode = "auto" | "manual";
 type DslDocument = {
     title: string;
     type: PresetType;
+    /**
+     * 図全体を 1 箱にする図種 (`pie` / `bar` / `line` / `funnel` / `tree` / `journey` /
+     * `quadrant` / `mind` / `gantt`) で、 その箱の上に出す小見出し (#1247)。
+     *
+     * これらの図種は箱を 1 つしか作らないため「どの箱の小見出しか」 が決まる。 箱ごとに
+     * 分かれる図種では決まらないので、 書かれていたら組み立て側が知らせる。
+     */
+    eyebrow?: string;
+    /**
+     * `eyebrow` を書いた行 (#1247)。 知らせの行番号に使う。
+     *
+     * 図の `pos` は常に 1 行目を指すため、 そこを使うと「10 行目に書いた `eyebrow` が効かない」
+     * を 1 行目として知らせることになり、 書いた場所に辿り着けない。
+     */
+    eyebrowPos?: Position;
+    /**
+     * 2 軸で仕分ける図 (`type: quadrant`) の軸の名前 (#1251)。
+     *
+     * 書かないと「小さい / 大きい」 のままになり、何を判断する図か読めない。
+     * 区画の名前 (`右上` 等) は軸の名前から `{上} × {右}` の形で決まる。
+     *
+     * 他の図種には軸が無いため、書かれていたら組み立て側が知らせる。
+     */
+    axes?: DslAxes;
+    /** `axes` を書いた行 (#1251)。 知らせの行番号に使う */
+    axesPos?: Position;
     actors: DslActor[];
     flow: DslStep[];
     animate?: DslAnimate;
+    /**
+     * 他の値から自動で決まる値 (`values:`)。 時間を持たず、 参照した値が動けば常に追随する。
+     *
+     * `states` (初期値だけを持つ) と `animation` (いつ何を動かすか) の間に置く層で、
+     * 値どうしの関係を書く場所。 書かなければ今までと同じ挙動。
+     */
+    values?: DslValue[];
     /** v0.5+ 拡張 ... viewport / lanes / groups */
     viewport?: DslViewport;
     lanes?: Record<string, DslLane>;
@@ -124,6 +157,17 @@ type DslDocument = {
     layout?: LayoutMode;
     pos: Position;
 };
+/** 2 軸で仕分ける図の軸の名前 (#1251) */
+type DslAxes = {
+    x?: {
+        left?: string;
+        right?: string;
+    };
+    y?: {
+        bottom?: string;
+        top?: string;
+    };
+};
 /** 登場人物 (v0.5+ ... inline option 拡張) */
 type DslActor = {
     name: string;
@@ -142,6 +186,35 @@ type DslActor = {
     eyebrow?: string;
     value?: string;
     rows?: string[];
+    /**
+     * 工程の並び (`type: gantt`) で、その工程の担当 (#1251)。
+     *
+     * 他の図種では相手が無いため、書かれていたら組み立て側が知らせる。
+     */
+    owner?: string;
+    /**
+     * 工程の並び (`type: gantt`) で、その工程が終わる時期 (#1251)。
+     *
+     * 書かなければ始まりと同じ時期に終わる (帯が 1 コマ)。 `{名前}` を書くと状態から取り、
+     * 段で帯が伸び縮みする様子を見せられる。
+     *
+     * 他の図種では相手が無いため、書かれていたら組み立て側が知らせる。
+     */
+    end?: string;
+    /**
+     * 体験の道筋 (`type: journey`) で、その段階が起きる場所 (#1251)。
+     *
+     * 「どこで起きたか」 を段の下に出す。 他の図種では相手が無いため、書かれていたら
+     * 組み立て側が知らせる。
+     */
+    touchpoint?: string;
+    /**
+     * 体験の道筋 (`type: journey`) で、その段階の改善の余地 (#1251)。
+     *
+     * 気持ちが落ちる段に「何を直せるか」 を添える。 他の図種では相手が無いため、
+     * 書かれていたら組み立て側が知らせる。
+     */
+    opportunity?: string;
     lane?: string;
     stack?: number;
     initial?: boolean;
@@ -246,6 +319,8 @@ type DslStep = {
     cardinality?: string;
     labelOffsetX?: number;
     labelOffsetY?: number;
+    /** true で説明文を矢印の線の上に重ねる。 分岐図の条件ラベル用。 */
+    overlay?: boolean;
     /**
      * canvas pivot (CAR-1693 Phase 1) DSL 表面 `pos: {x, y}` 由来の layout offset。 step の edge
      * label 位置を auto layout compute から (dx, dy) shift する。 未指定は auto、 set 済は Phase 2 で適用。
@@ -310,6 +385,51 @@ type DslState = {
     initial: number | string;
     pos: Position;
 };
+/**
+ * 値が動き出すきっかけ (#1161 段 2)。
+ *
+ * `step` は段が始まった時、 `reaches` は別の値が境目を越えた時。 どちらも「成り立った瞬間の
+ * 出来事」 で、 常に成り立つ関係を表す式とは別物 (spec § 2.3)。
+ */
+type DslValueTrigger = {
+    kind: "step";
+    step: string;
+} | {
+    kind: "reaches";
+    /** 見張る相手の値の名前 */
+    source: string;
+    op: ">=" | ">" | "<=" | "<" | "==" | "!=";
+    threshold: number;
+};
+/**
+ * 記法の `values:` の 1 件。 形は 2 つある。
+ *
+ * | 形 | 持つもの | 意味 |
+ * |---|---|---|
+ * | 式 | `expression` | 常に成り立つ関係。 時間を持たない |
+ * | きっかけ | `trigger` / `to` / `durationMs` | きっかけから `to` まで動く。 時間を持つ |
+ *
+ * 両方を持つ形は無い (parser が弾く)。 きっかけ形は組み立ての時点で段の時計を読む式へ畳まれる
+ * ため、 図に載る時にはどちらも `derived` になる。
+ */
+type DslValue = {
+    name: string;
+    pos: Position;
+} & ({
+    /** 式そのもの。 評価は描画側が毎 frame 行う */
+    expression: string;
+    trigger?: never;
+    to?: never;
+    durationMs?: never;
+} | {
+    expression?: never;
+    /** 動き出すきっかけ */
+    trigger: DslValueTrigger;
+    /** 動いた先の値 */
+    to: number;
+    /** 動く長さ (ms) */
+    durationMs: number;
+});
 /** ステップ (phase) */
 type DslPhase = {
     name: string;
@@ -397,7 +517,7 @@ interface CompileToCdlOpts {
 }
 /** 図は出せるが書いた通りにならなかった、 という知らせ。 */
 type CompileNotice = {
-    kind: "relative-position-ignored" | "focus-target-missing" | "state-override-rejected" | "external-paint-dropped" | "part-not-drawn" | "scale-reserved";
+    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";
     /** 対象の名前。 光らせる相手なら書かれた指定そのまま */
     actor: string;
     /** 書かれていた行 */
@@ -639,6 +759,14 @@ type V05ParseResult = {
     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"];
 /** 受け付ける図種。 記法一覧はここを見る。 */
 declare const PRESET_TYPES: ReadonlySet<PresetType>;
 /**
@@ -911,6 +1039,9 @@ interface InputSize {
  * **段の中身 (光らせる相手 / 遷移 / 即時変更) も数える**。 段の数だけを見ると、
  * 1 段に 1,000 件の相手を書いた形が 1 件として通る。 実測ではこの形が組み立ての中で
  * 約 100 万件に展開され、 呼び出しの深さが上限を超えて落ちた。
+ *
+ * **他の値から決まる値 (`values:`) も数える** (#1162)。 これらは毎 frame 解かれるので、
+ * 数に入れないと上限をすり抜けた本文が描画のたびに重さを持つ。
  */
 declare function countDocElements(doc: DslDocument): number;
 /**
@@ -933,6 +1064,7 @@ declare function countDiagramElements(diagram: {
     formulas?: unknown[];
     scrollTriggers?: unknown[];
     eventBindings?: unknown[];
+    derived?: unknown[];
 }): number;
 /** 本文の大きさを byte で数える (文字数ではなく実際の大きさ) */
 declare function countBytes(src: string): number;
@@ -981,10 +1113,35 @@ interface DragonJson {
     title: string;
     /** preset type (必須): sequence / flow / swimlane / er / state / topology / solidity / gantt / class / pie / c4 / mind */
     type: PresetType;
+    /**
+     * 図表の箱の上に出す小見出し (optional)。 記法の最上位 `eyebrow:` と同じ (#1247)。
+     *
+     * 効くのは図全体を 1 箱にする図種 (`pie` / `bar` / `line` / `funnel` / `tree` / `journey` /
+     * `quadrant` / `mind` / `gantt`) だけ。 箱ごとに分かれる図種では相手が決まらないため、
+     * 組み立て側が知らせを出す。 そちらは `actors[].eyebrow` に書く。
+     */
+    eyebrow?: string;
     /** 登場人物 (必須): 文字列 or { name, kind, ... } object */
     actors: (string | JsonActor)[];
     /** flow step 配列 (必須): { from, to, label, ... } */
     flow: JsonStep[];
+    /**
+     * 状態の初期値 (optional)。 記法の `states:` と同じ (#1181)。
+     *
+     * `{名前}` を箱の文字に置くと、ここに書いた値が描画側で置き換わる。 名前は英数字と `_`
+     * だけ (描画側が置き換える時に見る範囲と揃える)。
+     *
+     * ここに書けるのは初期値まで。 段で動かすのは `animation[].tween` / `animation[].set`
+     * (`#1186` で追加、記法の `tween:` / `set:` と同じ)。
+     */
+    states?: Record<string, number | string>;
+    /**
+     * 他の値から自動で決まる値 (optional)。 記法の `values:` と同じ (#1181)。
+     *
+     * 式には四則 (`+ - * /`) と括弧、比較 (`> >= < <= == !=`)、`min` / `max` が書ける。
+     * 他の値は `{名前}` で読む。 解くのは描画側で、毎 frame 参照から順に決まる。
+     */
+    values?: Record<string, string>;
     /** animation phase 配列 (optional) */
     animation?: JsonPhase[];
     /** viewport (optional): 全体 canvas size / gap */
@@ -1063,6 +1220,8 @@ interface JsonStep {
     cardinality?: string;
     labelOffsetX?: number;
     labelOffsetY?: number;
+    /** true で説明文を矢印の線の上に重ねる。 分岐図の条件ラベル用。 */
+    overlay?: boolean;
     /**
      * canvas pivot (CAR-1693 Phase 1) DSL 表面 `pos: {x, y}` = edge label offset。 未指定は
      * backward compat、 set 済は Phase 2 の applyPosOffset で edge label 位置を shift する。
@@ -1080,6 +1239,19 @@ interface JsonPhase {
     body?: string;
     /** badge label */
     badge?: string;
+    /**
+     * 段の中で値を動かす (#1186)。 記法の `tween: name 100 -> 90` と同じ。
+     *
+     * 足すまで JSON の入口は `states:` で初期値を書けても **動かす手段が無かった** ため、
+     * 同じ図を記法で書くと動き JSON で書くと静止する状態だった (#1181 で状態を足した時の残り)。
+     */
+    tween?: Record<string, readonly [number, number]>;
+    /**
+     * 段の切替で値を差し替える (#1186)。 記法の `set: name value` と同じ。
+     *
+     * `tween` が段の中を補間するのに対し、こちらは段の切替時に 1 度だけ変える。
+     */
+    set?: Record<string, number | string>;
 }
 /**
  * JSON DSL error。 line 概念がないため、 field path (JSON pointer style) で位置を示す。
@@ -1112,6 +1284,7 @@ interface JsonDslError {
  */
 declare function jsonToDiagram(json: unknown, opts?: {
     partsCatalog?: Record<string, CdlDiagram>;
+    onNotice?: CompileToCdlOpts["onNotice"];
 }): CdlDiagram;
 /**
  * JSON DSL を validate だけ実施 (compile しない)。 error 詳細を配列で取得したい場合に使う。
@@ -1164,6 +1337,10 @@ declare const diagramJsonSchema: {
             enum: string[];
             description: string;
         };
+        eyebrow: {
+            type: string;
+            description: string;
+        };
         actors: {
             type: string;
             minItems: number;
@@ -1280,9 +1457,44 @@ declare const diagramJsonSchema: {
                         type: string;
                         description: string;
                     };
+                    overlay: {
+                        type: string;
+                        description: string;
+                    };
                 };
             };
         };
+        states: {
+            type: string;
+            description: string;
+            additionalProperties: boolean;
+            patternProperties: {
+                "^[a-zA-Z_][a-zA-Z0-9_]*$": {
+                    type: string[];
+                    description: string;
+                };
+            };
+            examples: {
+                inflow: number;
+                done: number;
+            }[];
+        };
+        values: {
+            type: string;
+            description: string;
+            additionalProperties: boolean;
+            patternProperties: {
+                "^[a-zA-Z_][a-zA-Z0-9_]*$": {
+                    type: string;
+                    minLength: number;
+                    description: string;
+                };
+            };
+            examples: {
+                waiting: string;
+                busy: string;
+            }[];
+        };
         animation: {
             type: string;
             description: string;
@@ -1316,6 +1528,31 @@ declare const diagramJsonSchema: {
                         type: string;
                         description: string;
                     };
+                    tween: {
+                        type: string;
+                        description: string;
+                        additionalProperties: boolean;
+                        patternProperties: {
+                            "^[a-zA-Z_][a-zA-Z0-9_]*$": {
+                                type: string;
+                                items: {
+                                    type: string;
+                                };
+                                minItems: number;
+                                maxItems: number;
+                            };
+                        };
+                    };
+                    set: {
+                        type: string;
+                        description: string;
+                        additionalProperties: boolean;
+                        patternProperties: {
+                            "^[a-zA-Z_][a-zA-Z0-9_]*$": {
+                                type: string[];
+                            };
+                        };
+                    };
                 };
             };
         };
@@ -1448,4 +1685,4 @@ interface CompileOpts {
  */
 declare function textDslToDiagram(src: string, opts?: CompileOpts): CdlDiagram;
 
-export { type AnchorBox, type CompileNotice, type CompileOpts, DIAGRAM_BOUNDARY_PADDING, 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 DslViewport, type FocusEntry, type InputSize, type JsonActor, 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, PRESET_TYPES, type PresetType, RELATIVE_GAP_DEFAULT, type RelativeDirection, type RelativePos, TONE_ALIAS, 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 };
+export { type AnchorBox, type CompileNotice, type CompileOpts, DIAGRAM_BOUNDARY_PADDING, 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, type JsonActor, 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, 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 };