@cardenelabs/dragon 0.7.0 → 0.8.0

package/src/notation-lint.ts

@@ -102,7 +102,6 @@ const KIND_TO_JA: Record<string, string> = {
   tree: "階層ツリー",
   userJourney: "ユーザージャーニー",
   mindMap: "マインドマップ",
-  mindMapRadial: "放射状マインドマップ",
   funnel: "ファネル (段階別離脱)",
   quadrant: "四象限マトリクス",
   gantt: "ガントチャート",
@@ -113,7 +112,7 @@ const KIND_TO_JA: Record<string, string> = {
 function applyTopicAutoFix(topic: string): string {
   // 1. 先頭の kind name を検出、 マッチしたら JA description に置換
   const kindMatch = topic.match(
-    /^\s*(chart|flow|swimlane|sequence|topology|er|stateMachine2?|infrastructure|classDiagram|tree|userJourney|mindMap(?:Radial)?|funnel|quadrant|gantt|flowchart|network|line chart|pie chart|bar chart)\b/i,
+    /^\s*(chart|flow|swimlane|sequence|topology|er|stateMachine2?|infrastructure|classDiagram|tree|userJourney|mindMap|funnel|quadrant|gantt|flowchart|network|line chart|pie chart|bar chart)\b/i,
   );
   if (kindMatch) {
     const kind = kindMatch[1]!.toLowerCase();
@@ -202,10 +201,22 @@ function ruleGanttUnknownDependsOn(d: CdlDiagram): LintIssue[] {
   return out;
 }
 
+/**
+ * 枝の親が実在するかを見る。
+ *
+ * **記法からも届く** (`#1177`)。 一時期は組立て API (`mindMap()` builder) で組んだ図にしか
+ * 当たらなかった = 記法の `type: mind` が `card` を 3 列に並べる別実装で、 `mind-map` 種別を
+ * 作っていなかったため (`#1170` で `type: radial` が消えて唯一の作り手が無くなった)。
+ * `#1177` で `compileMind` を `mind-map` 種別に寄せたので、 前提が揃うようになった。
+ *
+ * ただし **記法から違反が出ることは無い**。 記法の `actors` は「1 つ目が中心、 残りが枝」 の
+ * 並びで親を書く場所が無く、 全ての枝が中心の直下 (必ず実在する) になるため。 違反が出るのは
+ * 組立て API で親を書き間違えた図になる。
+ */
 function ruleMindMapParentReference(d: CdlDiagram): LintIssue[] {
   const out: LintIssue[] = [];
   for (const n of d.nodes) {
-    if ((n.kind === "mind-map" || n.kind === "mind-radial") && n.mindData) {
+    if (n.kind === "mind-map" && n.mindData) {
       const known = new Set<string>([n.mindData.rootId]);
       for (const b of n.mindData.branches) known.add(b.id);
       for (const b of n.mindData.branches) {
@@ -278,13 +289,25 @@ function ruleQuadrantMissingItems(d: CdlDiagram): LintIssue[] {
   return out;
 }
 
+/**
+ * 段の人数が減っていくことを見る。
+ *
+ * 人数の欄は `{名前}` を書ける (状態から取る形、 cdl の `render/payload-binding.ts` が解く)。
+ * その場合ここでは値が決まらないので、**数どうしの組だけを比べる** (#1194)。
+ *
+ * 素通しで比べると文字列の大小比較になり、`{trial}` が `{signup}` より大きいという理由で
+ * 発火する。 実際に見本帳の funnel を状態から取る形にした時、その偽発火が出た。
+ */
 function ruleFunnelMonotonicCount(d: CdlDiagram): LintIssue[] {
   const out: LintIssue[] = [];
   for (const n of d.nodes) {
     if (n.kind === "funnel-stages" && n.funnelData) {
       const stages = n.funnelData;
       for (let i = 1; i < stages.length; i++) {
-        if (stages[i]!.count > stages[i - 1]!.count) {
+        const 今 = stages[i]!.count;
+        const 前 = stages[i - 1]!.count;
+        if (typeof 今 !== "number" || typeof 前 !== "number") continue;
+        if (今 > 前) {
           out.push({
             rule: "funnel-increasing-count",
             severity: "warn",

package/src/schemas/diagram.json

@@ -14,8 +14,12 @@
     },
     "type": {
       "type": "string",
-      "enum": ["sequence", "flow", "swimlane", "er", "state", "topology", "solidity", "gantt", "class", "pie", "c4", "mind"],
-      "description": "preset type = 図の種類。 sequence (時系列 API 呼び出し) / flow (処理 flow) / swimlane (責務分担 flow) / er (DB schema) / state (状態遷移) / topology (network) / solidity (contract) / gantt (schedule) / class (UML class) / pie (円グラフ) / c4 (architecture) / mind (mind map)"
+      "enum": ["sequence", "flow", "swimlane", "er", "state", "topology", "solidity", "gantt", "class", "pie", "bar", "line", "funnel", "tree", "journey", "quadrant", "c4", "mind"],
+      "description": "図の種類。 型ごとに actors の書き方が違う。 [関係を描く] sequence (時系列の呼び出し) / flow (処理の流れ) / swimlane (責務ごとの流れ) / er (DB の schema) / state (状態の遷移) / topology (network) / solidity (contract) / class (UML の class) / c4 (architecture) / mind (発想の枝分かれ) は actors に名前を並べ flow に矢印を書く。 [値を描く] pie (割合) / bar (棒の高さ) / line (線の高さ、 書いた順に並ぶ) は actors に `- 名前: \"45\"` の形で数を書く。 funnel (段ごとに減る数) も同じ形。 [語を描く] journey (体験の起伏) は `- 登録: \"不満\"` の形で 最高 / 満足 / 普通 / 不満 / 怒り のどれかを書く。 quadrant (2 軸の仕分け) は `- 重複削除: \"左上\"` の形で 左上 / 右上 / 左下 / 右下 のどれかを書く。 [時期を描く] gantt (工程の並び) は `- 設計: \"1月\"` の形で始まりの時期を書き、 flow の矢印で前後関係を書く。 [親子を描く] tree (親子の入れ子) は actors に名前を並べ flow の矢印で親子を書く (矢印の先が子)"
+    },
+    "eyebrow": {
+      "type": "string",
+      "description": "図表の箱の上に出す小見出し (省略可)。 効くのは図全体を 1 箱にする型 (pie / bar / line / funnel / tree / journey / quadrant / mind / gantt) だけ。 箱ごとに分かれる型では相手が決まらないため、 actors[].eyebrow に書く"
     },
     "actors": {
       "type": "array",
@@ -67,13 +71,39 @@
           "guard": {"type": "string", "description": "state 遷移の条件 (kind: state 用)"},
           "cardinality": {"type": "string", "description": "ER の多重度 (1..N 等、 kind: er 用)"},
           "labelOffsetX": {"type": "number", "description": "ラベル位置 x 調整"},
-          "labelOffsetY": {"type": "number", "description": "ラベル位置 y 調整"}
+          "labelOffsetY": {"type": "number", "description": "ラベル位置 y 調整"},
+          "overlay": {"type": "boolean", "description": "true で説明文を矢印の線の上に重ねる (分岐図の条件ラベル用)"}
         }
       }
     },
+    "states": {
+      "type": "object",
+      "description": "状態の初期値。 名前 -> 初期値 の object。 optional。 箱の文字に `{名前}` を置くと、 ここに書いた値が描画時に置き換わる。 段で動かすには animation[].tween / animation[].set を使う。",
+      "additionalProperties": false,
+      "patternProperties": {
+        "^[a-zA-Z_][a-zA-Z0-9_]*$": {
+          "type": ["number", "string"],
+          "description": "初期値。 数か文字列。 名前は英字か _ で始め、 英数字と _ だけを使う"
+        }
+      },
+      "examples": [{ "inflow": 0, "done": 0 }]
+    },
+    "values": {
+      "type": "object",
+      "description": "他の値から自動で決まる値。 名前 -> 式 の object。 optional。 式には四則 (+ - * /) と括弧、 比較 (> >= < <= == !=)、 min / max が書ける。 他の値は {名前} で読む。 解くのは描画側で、 参照した値が動けば追随する。",
+      "additionalProperties": false,
+      "patternProperties": {
+        "^[a-zA-Z_][a-zA-Z0-9_]*$": {
+          "type": "string",
+          "minLength": 1,
+          "description": "式。 例 `{inflow} - {done}`"
+        }
+      },
+      "examples": [{ "waiting": "{inflow} - {done}", "busy": "{waiting} > 80" }]
+    },
     "animation": {
       "type": "array",
-      "description": "アニメーション phase 配列。 各 phase で focus 対象を highlight する。 optional。",
+      "description": "アニメーション phase 配列。 各 phase で focus 対象を highlight し、 tween / set で states の値を動かす。 optional。",
       "items": {
         "type": "object",
         "required": ["step"],
@@ -83,7 +113,28 @@
           "duration": {"type": "number", "minimum": 0.1, "description": "phase 時間 (秒、 default 1.4)"},
           "focus": {"type": "array", "items": {"type": "string"}, "description": "この phase で active 化する actor 名 or edge 'A -> B' の配列"},
           "body": {"type": "string", "description": "phase 説明文"},
-          "badge": {"type": "string", "description": "phase 中に表示する badge label"}
+          "badge": {"type": "string", "description": "phase 中に表示する badge label"},
+          "tween": {
+            "type": "object",
+            "description": "この phase で補間する状態。 状態名 -> [開始値, 終了値]。 名前は英字か _ で始め、 英数字と _ だけを使う",
+            "additionalProperties": false,
+            "patternProperties": {
+              "^[a-zA-Z_][a-zA-Z0-9_]*$": {
+                "type": "array",
+                "items": {"type": "number"},
+                "minItems": 2,
+                "maxItems": 2
+              }
+            }
+          },
+          "set": {
+            "type": "object",
+            "description": "この phase の切替で差し替える状態。 状態名 -> 値。 名前は英字か _ で始め、 英数字と _ だけを使う",
+            "additionalProperties": false,
+            "patternProperties": {
+              "^[a-zA-Z_][a-zA-Z0-9_]*$": {"type": ["number", "string"]}
+            }
+          }
         }
       }
     },

package/src/types.ts

@@ -17,6 +17,12 @@ export type PresetType =
   | "gantt"
   | "class"
   | "pie"
+  | "bar"
+  | "line"
+  | "funnel"
+  | "tree"
+  | "journey"
+  | "quadrant"
   | "c4"
   | "mind";
 
@@ -50,9 +56,42 @@ export type LayoutMode = "auto" | "manual";
 export 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>;
@@ -65,6 +104,12 @@ export type DslDocument = {
   pos: Position;
 };
 
+/** 2 軸で仕分ける図の軸の名前 (#1251) */
+export type DslAxes = {
+  x?: { left?: string; right?: string };
+  y?: { bottom?: string; top?: string };
+};
+
 /** 登場人物 (v0.5+ ... inline option 拡張) */
 export type DslActor = {
   name: string;
@@ -83,6 +128,35 @@ export 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;
@@ -189,6 +263,8 @@ export 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 で適用。
@@ -259,6 +335,55 @@ export type DslState = {
   pos: Position;
 };
 
+/**
+ * 値が動き出すきっかけ (#1161 段 2)。
+ *
+ * `step` は段が始まった時、 `reaches` は別の値が境目を越えた時。 どちらも「成り立った瞬間の
+ * 出来事」 で、 常に成り立つ関係を表す式とは別物 (spec § 2.3)。
+ */
+export type DslValueTrigger =
+  | { kind: "step"; step: string }
+  | {
+      kind: "reaches";
+      /** 見張る相手の値の名前 */
+      source: string;
+      op: ">=" | ">" | "<=" | "<" | "==" | "!=";
+      threshold: number;
+    };
+
+/**
+ * 記法の `values:` の 1 件。 形は 2 つある。
+ *
+ * | 形 | 持つもの | 意味 |
+ * |---|---|---|
+ * | 式 | `expression` | 常に成り立つ関係。 時間を持たない |
+ * | きっかけ | `trigger` / `to` / `durationMs` | きっかけから `to` まで動く。 時間を持つ |
+ *
+ * 両方を持つ形は無い (parser が弾く)。 きっかけ形は組み立ての時点で段の時計を読む式へ畳まれる
+ * ため、 図に載る時にはどちらも `derived` になる。
+ */
+export 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) */
 export type DslPhase = {
   name: string;