@cardenelabs/dragon 0.14.0 → 0.16.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cardenelabs/dragon",
-  "version": "0.14.0",
+  "version": "0.16.0",
   "description": "Dragon — Mermaid 感覚で animated SVG を生成する Text DSL。 cdl engine を内部利用。",
   "license": "MIT",
   "author": "cardene777",
@@ -50,13 +50,14 @@
     "build": "tsup",
     "dev": "tsup --watch",
     "typecheck": "tsc --noEmit",
+    "typecheck:test": "tsc --noEmit -p tsconfig.test.json",
     "test": "cd ../.. && vitest run packages/dragon",
     "test:watch": "cd ../.. && vitest packages/dragon",
     "lint": "tsc --noEmit",
     "prepublishOnly": "pnpm run typecheck && pnpm run test && pnpm run build"
   },
   "dependencies": {
-    "@cardenelabs/cdl": "^0.14.0"
+    "@cardenelabs/cdl": "^0.15.0"
   },
   "peerDependencies": {
     "react": "^19.0.0",

package/src/compile.ts

@@ -25,6 +25,7 @@ import type {
   ErRelationCardinality,
   FormulaAst,
   LaidDiagram,
+  NodeKind,
 } from "@cardenelabs/cdl";
 import {
   sequence,
@@ -45,7 +46,7 @@ import {
   inputDefaultValue,
 } from "@cardenelabs/cdl";
 import { parseFocusEntry } from "./focus";
-import { DRAW_TARGETS } from "./v05/parser";
+import { DRAW_TARGETS, DSL_ONLY_KINDS } from "./v05/parser";
 import { isColorValue, pointsOutside, stripExternalPaint } from "./color";
 import {
   MAX_INPUT_ELEMENTS,
@@ -60,6 +61,56 @@ import {
   type RelativeDirection,
 } from "./relative-pos";
 
+/**
+ * 記法だけが持つ種類を、描画できる種類へ読み替える (#1420)。
+ *
+ * 記法は `contract` / `eoa` のような **描画側に無い種類** を受け付ける
+ * (`v05/parser.ts` の `DSL_ONLY_KINDS`)。 図種ごとの役割分け (`solidity` の縦列の並べ替え
+ * など) に使うためで、記法としては正しい。
+ *
+ * **そのまま描画側へ渡すと図の組み立てが落ちる**。 描画側は知らない種類の大きさを引けず、
+ * `Cannot read properties of undefined (reading 'h')` で止まる (実測)。
+ *
+ * `solidity` と `er` は組み立ての中で別の種類に置き換えていたが、`flow` / `swimlane` /
+ * `state` / `topology` は `a.kind` をそのまま渡していた。 記法が受ける値で図が出ない状態
+ * だったので、渡す手前で必ず通す。
+ *
+ * ## 読み替え先
+ *
+ * | 種類 | 読み替え先 | なぜ |
+ * |---|---|---|
+ * | `entity` | `storage` | 表を持つ = ER 図の実体 |
+ * | `state` | `card` | 状態は札で表す |
+ * | `contract` / `proxy` / `library` / `interface` | `card` | 契約は札で表す (`solidity` の置き換え先に合わせた) |
+ * | `eoa` | `person` | 人が持つ財布 |
+ * | `multisig` | `signer` | 複数人で署名する (`solidity` の置き換え先に合わせた) |
+ *
+ * **表は `DSL_ONLY_KINDS` を鍵にして書く**。 種類を足した時に読み替え先が無いと
+ * 型検査が落ちるので、足し忘れが残らない。
+ */
+const 記法だけの種類の読み替え: Readonly<
+  Record<(typeof DSL_ONLY_KINDS)[number], NodeKind>
+> = {
+  entity: "storage",
+  state: "card",
+  contract: "card",
+  proxy: "card",
+  library: "card",
+  interface: "card",
+  eoa: "person",
+  multisig: "signer",
+};
+
+/** 描画側へ渡せる種類にする。 記法だけの種類はここで読み替わる (#1420) */
+function 描ける種別(kind: string | undefined): NodeKind {
+  if (kind === undefined) return "actor";
+  const 読み替え先 = (
+    記法だけの種類の読み替え as Record<string, NodeKind | undefined>
+  )[kind];
+  return 読み替え先 ?? (kind as NodeKind);
+}
+
+
 export interface CompileToCdlOpts {
   /**
    * CAR-1657 = parts identifier lookup catalog、 caller (CdlEditor / test) が inject。
@@ -204,6 +255,21 @@ export function compileToCdl(doc: DslDocument, opts?: CompileToCdlOpts): CdlDiag
     case "line":
       diagram = compileValueChart(doc, "line", "chart-line", opts?.onNotice);
       break;
+    case "gauge":
+      diagram = compileValueChart(doc, "gauge", "chart-gauge", opts?.onNotice);
+      break;
+    case "radial":
+      diagram = compileValueChart(doc, "radial", "chart-radial", opts?.onNotice);
+      break;
+    case "stat":
+      diagram = compileValueChart(doc, "stat", "chart-stat", opts?.onNotice);
+      break;
+    case "waffle":
+      diagram = compileValueChart(doc, "waffle", "chart-waffle", opts?.onNotice);
+      break;
+    case "stacked":
+      diagram = compileValueChart(doc, "stacked", "chart-stacked-bar", opts?.onNotice);
+      break;
     case "funnel":
       diagram = compileFunnel(doc, opts?.onNotice);
       break;
@@ -649,6 +715,11 @@ const 図種の作り: Record<PresetType, "登場人物ごとに箱" | "図全
   pie: "図全体を 1 箱",
   bar: "図全体を 1 箱",
   line: "図全体を 1 箱",
+  gauge: "図全体を 1 箱",
+  radial: "図全体を 1 箱",
+  stat: "図全体を 1 箱",
+  waffle: "図全体を 1 箱",
+  stacked: "図全体を 1 箱",
   funnel: "図全体を 1 箱",
   tree: "図全体を 1 箱",
   journey: "図全体を 1 箱",
@@ -1011,6 +1082,11 @@ const 空の形の逃げ先: Record<PresetType, string[]> = {
   pie: [],
   bar: [],
   line: [],
+  gauge: [],
+  radial: [],
+  stat: [],
+  waffle: [],
+  stacked: [],
   funnel: [],
   tree: [],
   journey: [],
@@ -4540,8 +4616,16 @@ function 参照する名前(value: number | string | null): string | null {
  */
 function compileValueChart(
   doc: DslDocument,
-  型: "pie" | "bar" | "line",
-  kind: "chart-pie" | "chart-bar" | "chart-line",
+  型: "pie" | "bar" | "line" | "gauge" | "radial" | "stat" | "waffle" | "stacked",
+  kind:
+    | "chart-pie"
+    | "chart-bar"
+    | "chart-line"
+    | "chart-gauge"
+    | "chart-radial"
+    | "chart-stat"
+    | "chart-waffle"
+    | "chart-stacked-bar",
   onNotice?: (notice: CompileNotice) => void,
 ): CdlDiagram {
   const b = diagram(slugify(doc.title), { topic: doc.title });
@@ -4549,11 +4633,19 @@ function compileValueChart(
   // **高さは型で違い、 格子に載せる**。 描画側 (`cdl` の `chart()` preset) は `pie` を 320、
   // 棒と折れ線を 360 とした上で **16 の倍数へ切り上げる** (360 は 16 で割り切れないので 368)。
   // 切り上げないと下端が格子から外れ、 全図で位置の警告が出る (review 指摘)
-  const CHART_H = 型 === "pie" ? 320 : 368;
+  // 半円と弧は縦を使わないので円と同じ 320。 描画側 (`cdl` の `chart()` preset) が
+  // `pie` / `gauge` / `radial` を 320、棒と折れ線を 360 とし、16 の倍数へ切り上げる
+  // 縦に余白が要らない型。 描画側 (`cdl` の `chart()` preset) と揃える。
+  // 半円 / 弧 / 割合の印 は縦を使わず、値 1 つを大きく示す図も縦に伸びない
+  const 低い型 =
+    型 === "pie" || 型 === "gauge" || 型 === "radial" || 型 === "waffle" || 型 === "stat";
+  const CHART_H = 低い型 ? 320 : 368;
   b.lane("chart", { width: CHART_W + 64 });
 
   const data: NonNullable<CdlDiagram["nodes"][number]["chartData"]> = [];
   const 読めない: string[] = [];
+  const 前が読めない: string[] = [];
+  let 前が読めない行 = 0;
   const 未宣言: string[] = [];
   let 未宣言行 = 0;
   const 参照できる = 数の欄から参照できる名前(doc);
@@ -4580,16 +4672,37 @@ function compileValueChart(
       continue;
     }
     // 色はそのまま渡す。 箱が 1 つになっても、 書いた色が消えないようにする
-    data.push({ label: 箱の題(a), value, ...(a.tone !== undefined ? { tone: a.tone } : {}) });
+    // 前の時点の値 (#1450)。 読めない形は黙って捨てず知らせる = 書いたのに 2 本目の帯が
+    // 出ない状態になり、手掛かりが残らない
+    const 前 = a.previous === undefined ? null : parseChartValue(a.previous);
+    if (a.previous !== undefined && 前 === null) {
+      if (前が読めない.length === 0) 前が読めない行 = a.pos?.line ?? 0;
+      前が読めない.push(a.name);
+    }
+    data.push({
+      label: 箱の題(a),
+      value,
+      ...(前 === null ? {} : { previous: 前 }),
+      ...(a.tone !== undefined ? { tone: a.tone } : {}),
+    });
   }
   // 案内の言葉は型ごとに変える。 共通化した時に `pie` の「割合 / 円 / 45%」 が「値 / 図 / 45」 に
   // 薄まり、 既存の案内が後退した (review 指摘)。 何を書けばよいかは型ごとに違う
-  const 語 =
-    型 === "pie"
-      ? { 量: "割合", 図: "円", 例: '"45%"' }
-      : 型 === "bar"
-        ? { 量: "値", 図: "棒", 例: '"420"' }
-        : { 量: "値", 図: "折れ線", 例: '"180"' };
+  // 何を書けばよいかは型ごとに違う。 まとめると「割合 / 円 / 45%」 が「値 / 図 / 45」 に薄まる
+  //
+  // **表で持つ**。 三項の連鎖にすると、型が増えるたびに深さが増え、最後の枝が
+  // 「それ以外」 になるため型検査が新しい型の漏れを教えてくれない
+  const 語の表: Record<typeof 型, { 量: string; 図: string; 例: string }> = {
+    pie: { 量: "割合", 図: "円", 例: '"45%"' },
+    bar: { 量: "値", 図: "棒", 例: '"420"' },
+    line: { 量: "値", 図: "折れ線", 例: '"180"' },
+    gauge: { 量: "値", 図: "半円", 例: '"680"' },
+    radial: { 量: "値", 図: "弧", 例: '"72"' },
+    stat: { 量: "値", 図: "大きな数字", 例: '"1200"' },
+    waffle: { 量: "割合", 図: "100 個の印", 例: '"45%"' },
+    stacked: { 量: "内訳の値", 図: "帯", 例: '"320"' },
+  };
+  const 語 = 語の表[型];
 
   /**
    * 利用者に伝える。 **`console.warn` だけにしない**。 エディタは受け取った notice を画面に
@@ -4618,6 +4731,15 @@ function compileValueChart(
       未宣言行,
     );
   }
+  if (前が読めない.length > 0) {
+    伝える(
+      "chart-value-unreadable",
+      前が読めない[0]!,
+      `type: ${型} で前の時点の値を読めない項目があります (前の値を使いません): ${前が読めない.join(", ")}。` +
+        " `- 名前: { value: " + 語.例 + ", previous: " + 語.例 + " }` の形で書いてください",
+      前が読めない行,
+    );
+  }
   if (doc.flow.length > 0) {
     伝える(
       "chart-edge-dropped",
@@ -5330,7 +5452,7 @@ function compileC4(doc: DslDocument): CdlDiagram {
     b.node(x.id, {
       lane: lid,
       stack,
-      kind: x.actor.kind,
+      kind: 描ける種別(x.actor.kind),
       title: x.actor.name,
     });
   }
@@ -5442,6 +5564,8 @@ type 放射で描けない欄 =
   | "stack"
   | "initial"
   | "final"
+  // 前の時点の値 (#1450)。 放射の枝は 1 時点しか描かない = 2 本目の帯に当たるものが無い
+  | "previous"
   | "colorHex"
   | "stateOverride"
   | "posX"
@@ -5505,6 +5629,7 @@ const 放射で描けない欄の名前: Record<放射で描けない欄, string
   stack: "積む順",
   initial: "始まり / 終わり の印",
   final: "始まり / 終わり の印",
+  previous: "前の時点の値",
   colorHex: "色番号",
   stateOverride: "状態の上書き",
   // 位置は「登場人物ごとの箱をどこに置くか」 の指定で、 箱が 1 つの図では置く先が無い
@@ -6123,6 +6248,9 @@ function injectPhasesFallback(diagram: CdlDiagram, doc: DslDocument): void {
       body: p.body ?? "",
       activate: activateIds,
       ...(drawIds.length > 0 ? { draw: drawIds } : {}),
+      // 描く速さ (#1441)。 **描く相手が決まった段にだけ載せる** = 語が効かない図種
+      // (`drawIds` が空) で割合だけ渡すと、描画側が「draw が空なのに割合がある」 と知らせる
+      ...(drawIds.length > 0 && p.drawRatio !== undefined ? { drawRatio: p.drawRatio } : {}),
       tweens: (p.tweens ?? []).map((t) => ({ stateId: t.state, from: t.from, to: t.to })),
       sets: (p.sets ?? []).map((s) => ({ stateId: s.state, value: s.value })),
       ...(p.badge ? { badge: p.badge } : {}),
@@ -6384,7 +6512,7 @@ function compileFlow(doc: DslDocument): CdlDiagram {
     flowBuilder.step(
       {
         id: slugify(a.name) || `n${i}`,
-        kind: a.kind,
+        kind: 描ける種別(a.kind),
         title: 箱の題(a),
       },
       edgeLabel,
@@ -6423,7 +6551,7 @@ function compileSwimlane(doc: DslDocument): CdlDiagram {
       swim.node(nodeId, {
         lane: laneId,
         stack,
-        kind: actor?.kind ?? "actor",
+        kind: 描ける種別(actor?.kind),
         title: actorName,
       });
       laneStackCount.set(laneId, stack + 1);
@@ -6454,7 +6582,7 @@ function compileSwimlane(doc: DslDocument): CdlDiagram {
       swim.node(slugify(a.name) || `n${i}`, {
         lane: swim.laneId(a.name),
         stack: 0,
-        kind: a.kind ?? "actor",
+        kind: 描ける種別(a.kind),
         title: 箱の題(a),
       });
     });
@@ -6519,9 +6647,35 @@ function 始まりと終わりの決め方(doc: DslDocument): {
   };
 }
 
+/** 状態の図で `stateMachine` preset が全ての箱に使う種類 */
+const 状態の図の既定の種類: NodeKind = "card";
+
+/**
+ * 状態の図で、既定と違う種類を書いた登場人物がいるか (#1450)。
+ *
+ * `stateMachine` preset は全ての状態を `card` で描くため、書いた `kind:` が黙って消える。
+ * 始点終点の印 (`mark-start` / `mark-end`) を書けるようにするには、書いた形を効かせる必要がある。
+ *
+ * **「書いたか」 だけでは広すぎる**。 記法だけの種類 (`kind: state` 等) は `card` に読み替わり、
+ * preset の出す形と同じになる = 書いても何も変わらないので経路を切り替える理由が無い。
+ * 切り替えると既存の図の id と枠の作りが変わる (実測で golden 8 件が落ちた)。
+ *
+ * 読み替えた後の種類が既定と違う時だけ切り替える。 こうすると「書いたのに効かない」 は消え、
+ * 「書いたが結果が同じ」 は従来の経路に留まる。
+ */
+function 既定と違う種類を書いた(doc: DslDocument): boolean {
+  return doc.actors.some(
+    (a) => a.kindWritten === true && 描ける種別(a.kind) !== 状態の図の既定の種類,
+  );
+}
+
 function compileState(doc: DslDocument): CdlDiagram {
   // v0.4 ... animation あり時 builder 直接経路 (各 state を lane で配置、 transition を edge)
-  if (doc.animate && doc.animate.phases.length > 0) {
+  //
+  // **種類を書いた形は動きの有無に関わらず generic 経路へ** (#1450、 #1263 と同じ理由)。
+  // 動く図だけで効かせると、同じ記法でも静止図では指定が黙って消える
+  // (実測 = `kind: mark-start` を書いた箱が `card` になり知らせも出ない)
+  if ((doc.animate && doc.animate.phases.length > 0) || 既定と違う種類を書いた(doc)) {
     return compileGenericWithAnimate(doc, { kind: "state", laneWidth: 360 });
   }
   // stateMachine preset ... actors を state に、 流れ を transition に
@@ -6577,7 +6731,7 @@ function compileTopology(doc: DslDocument): CdlDiagram {
   for (const a of doc.actors) {
     groupBuilder.add({
       id: slugify(a.name) || a.name,
-      kind: a.kind,
+      kind: 描ける種別(a.kind),
       title: 箱の題(a),
     });
   }
@@ -6717,7 +6871,12 @@ function compileGenericWithAnimate(doc: DslDocument, opts: GenericOpts): CdlDiag
         while (集合?.has(stack)) stack += 1;
         埋める(lid, stack);
       }
-      b.node(id, { lane: lid, stack, kind: a.kind, title: 箱の題(a) });
+      b.node(id, {
+        lane: lid,
+        stack,
+        kind: 描ける種別(a.kind),
+        title: 箱の題(a),
+      });
     });
   } else if (kind === "flow" || kind === "topology") {
     // 1 lane に全 actor を縦 stack
@@ -6730,7 +6889,12 @@ function compileGenericWithAnimate(doc: DslDocument, opts: GenericOpts): CdlDiag
     doc.actors.forEach((a, idx) => {
       const id = slugify(a.name) || `n${idx}`;
       actorToNodeId.set(a.name, id);
-      b.node(id, { lane: lid, stack: idx, kind: a.kind, title: 箱の題(a) });
+      b.node(id, {
+        lane: lid,
+        stack: idx,
+        kind: 描ける種別(a.kind),
+        title: 箱の題(a),
+      });
     });
   } else {
     // swimlane / er / state ... actor ごとに 1 lane (横並び)
@@ -6755,7 +6919,7 @@ function compileGenericWithAnimate(doc: DslDocument, opts: GenericOpts): CdlDiag
       b.node(id, {
         lane: lid,
         stack: 0,
-        kind: a.kind,
+        kind: 描ける種別(a.kind),
         title: 箱の題(a),
         ...(isInitial ? { eyebrow: "初期" } : {}),
         ...(isFinal ? { eyebrow: "最終" } : {}),

package/src/index.ts

@@ -11,6 +11,17 @@
 export { parseTextDsl } from "./parser";
 export { compileToCdl } from "./compile";
 export type { CompileNotice } from "./compile";
+/**
+ * 組み立てた図の型 (#1415)。
+ *
+ * `textDslToDiagram` が返す型そのもので、実体は `@cardenelabs/cdl` が持つ。 使う側が
+ * 戻り値に型を付けるには必ず要るので、ここから引けるようにする。
+ *
+ * 再 export が無い間、使う側は `@cardenelabs/cdl` を直接の依存に足す必要があった。
+ * 足さずに書くと **型が暗黙の `any` に落ち、その先の `.map((n) => ...)` まで検査が効かなく
+ * なる** (実測 = この 1 件が 39 件の暗黙 `any` を生んでいた)。
+ */
+export type { CdlDiagram } from "@cardenelabs/cdl";
 export { parseTextDslV05 } from "./v05";
 // 記法一覧が「実際に受け付ける値」 を実装から引くための公開。 手書きすると説明と実装がずれる。
 export { DRAW_TARGETS, DRAW_WORDS, PHASE_ITEM_WORDS, PRESET_TYPES, TOP_LEVEL_KEYS } from "./v05/parser";

package/src/json-parser.ts

@@ -212,6 +212,13 @@ export 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;
@@ -354,6 +361,13 @@ export interface JsonPhase {
    * 受ける 8 語は `DRAW_WORDS` が持つ。 語と同じ図種で、その段の間に図が起点から現れる。
    */
   draw?: string;
+  /**
+   * 描き終えるまでに段の何割を使うか (#1441)。 記法の `draw: line 0.4` の後半と同じ。
+   *
+   * 0 より大きく 1 以下。 書かなければ段の終わりに描き終わる。 `draw` が無い段に書いても
+   * 何も起きない (描く相手が決まらないため、写す時に外す)。
+   */
+  drawRatio?: number;
   /**
    * 段の中で値を動かす (#1186)。 記法の `tween: name 100 -> 90` と同じ。
    *
@@ -444,6 +458,8 @@ export const ACCEPTED_KEYS = {
     "subtitle",
     "eyebrow",
     "value",
+    // 前の時点の値 (#1450)。 内訳の変化を帯で示す図と、値 1 つを大きく示す図が読む
+    "previous",
     "rows",
     "lane",
     "stack",
@@ -496,7 +512,7 @@ export const ACCEPTED_KEYS = {
     "overlay",
     "pos",
   ],
-  phase: ["step", "duration", "focus", "body", "badge", "tween", "set", "draw"],
+  phase: ["step", "duration", "focus", "body", "badge", "tween", "set", "draw", "drawRatio"],
   viewport: ["width", "height", "scale", "laneWidth", "gap", "laneGap", "nodeGap", "labelMargin"],
   lane: ["x", "width", "label", "contain", "lifeline", "pos"],
   group: ["label", "lanes"],
@@ -583,6 +599,7 @@ export const 欄の型表 = {
     subtitle: "文字列",
     eyebrow: "文字列",
     value: "文字列",
+    previous: "文字列",
     rows: "文字列の並び",
     lane: "文字列",
     stack: "数",
@@ -644,6 +661,7 @@ export const 欄の型表 = {
     tween: "object",
     set: "object",
     draw: "描くもの",
+    drawRatio: "数",
   },
   viewport: {
     width: "数",
@@ -2161,6 +2179,7 @@ export function jsonToDoc(json: DragonJson): DslDocument {
       subtitle: a.subtitle,
       eyebrow: a.eyebrow,
       value: a.value,
+      previous: a.previous,
       rows: a.rows,
       lane: a.lane,
       stack: a.stack,
@@ -2286,6 +2305,9 @@ export function jsonToDoc(json: DragonJson): DslDocument {
     badge: p.badge,
     // 書いた段だけが欄を持つ。 空文字を置くと「書いた」 と「書いていない」 が同じ形になる
     ...(p.draw !== undefined ? { draw: p.draw, drawPos: p0 } : {}),
+    // 割合は `draw` がある段にだけ写す。 単独で書いても描く相手が決まらず何も起きないので、
+    // 記法側 (同じ行に書かせる形) と同じ状態に揃える
+    ...(p.draw !== undefined && p.drawRatio !== undefined ? { drawRatio: p.drawRatio } : {}),
     // 段の中で動かす分 (#1186)。 記法側の `tweens` / `sets` と同じ形に写す。
     // 空の配列を置かないのは、記法側が「無ければ field ごと持たない」 形だから
     ...(p.tween && Object.keys(p.tween).length > 0

package/src/schemas/diagram.json

@@ -27,6 +27,11 @@
         "pie",
         "bar",
         "line",
+        "gauge",
+        "radial",
+        "stat",
+        "waffle",
+        "stacked",
         "funnel",
         "tree",
         "journey",
@@ -34,11 +39,11 @@
         "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 の矢印で親子を書く (矢印の先が子)"
+      "description": "図の種類。 型ごとに actors の書き方が違う。 [関係を描く] sequence (時系列の呼び出し) / flow (処理の流れ) / swimlane (責務ごとの流れ) / er (DB の schema) / state (状態の遷移) / topology (network) / solidity (contract) / class (UML の class) / c4 (architecture) / mind (発想の枝分かれ) は actors に名前を並べ flow に矢印を書く。 [値を描く] pie (割合) / bar (棒の高さ) / line (線の高さ、 書いた順に並ぶ) / gauge (合計を半円で示す) / radial (弧の長さで比べる) / stat (値 1 つを大きく示す) / waffle (割合を 100 個の印で示す) / stacked (内訳を帯で示す) は actors に `- 名前: \"45\"` の形で数を書く。 stat と stacked は `- 名前: { value: \"320\", previous: \"280\" }` の形で前の時点の値も書ける。 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 に書く"
+      "description": "図表の箱の上に出す小見出し (省略可)。 効くのは図全体を 1 箱にする型 (pie / bar / line / gauge / radial / stat / waffle / stacked / funnel / tree / journey / quadrant / mind / gantt) だけ。 箱ごとに分かれる型では相手が決まらないため、 actors[].eyebrow に書く"
     },
     "axes": {
       "type": "object",
@@ -107,6 +112,10 @@
                 "type": "string",
                 "description": "actor 数値表示 (kind: actor 用)"
               },
+              "previous": {
+                "type": "string",
+                "description": "前の時点の値。 type: stacked が 2 本目の帯として描き、type: stat が差として出す。 書かない図は 1 本のまま"
+              },
               "rows": {
                 "type": "array",
                 "items": {
@@ -584,6 +593,12 @@
             "enum": ["line", "bar", "pie", "journey", "mind", "tree", "gantt", "funnel"],
             "description": "この phase で起点から描くもの。 語は図種と揃える。 line / journey = 線が左端から右へ伸びる / bar = 棒が横軸から上へ伸びる / pie = 扇が 12 時から時計回りに開く / mind = 枝が中心から外へ伸びる / tree = 枝が根から下へ伸びる / gantt = 帯が各始端から右へ伸びる / funnel = 段が上端から順に積まれる"
           },
+          "drawRatio": {
+            "type": "number",
+            "exclusiveMinimum": 0,
+            "maximum": 1,
+            "description": "描き終えるまでに phase の何割を使うか。 0.4 なら進みが 0.4 に達した時点で描き終わり、残りは描き終わった姿のまま値だけが動く。 書かなければ phase の終わりに描き終わる。 draw と一緒に書く (draw が無いと何も起きない)"
+          },
           "tween": {
             "type": "object",
             "description": "この phase で補間する状態。 状態名 -> [開始値, 終了値]。 名前は英字か _ で始め、 英数字と _ だけを使う",

package/src/types.ts

@@ -4,6 +4,18 @@
  */
 
 import type { CdlDiagram, NodeKind, Tone, EdgeStyle } from "@cardenelabs/cdl";
+import type { DslOnlyKind } from "./v05/parser";
+
+/**
+ * 記法が書ける箱の種類 (#1420)。
+ *
+ * 描画できる種類 (`NodeKind`) に、**記法だけが持つ種類** (`contract` / `eoa` など) を足す。
+ * 後者は図種ごとの役割分け (`solidity` の縦列の並べ替えなど) に使い、描画側へ渡す手前で
+ * `compile.ts` の `描ける種別` が読み替える。
+ *
+ * `NodeKind` だけに縛っていた間、記法が受ける値を型が表せていなかった。
+ */
+export type DslNodeKind = NodeKind | DslOnlyKind;
 import type { RelativePos } from "./relative-pos";
 
 /**
@@ -59,6 +71,11 @@ export type PresetType =
   | "pie"
   | "bar"
   | "line"
+  | "gauge"
+  | "radial"
+  | "stat"
+  | "waffle"
+  | "stacked"
   | "funnel"
   | "tree"
   | "journey"
@@ -188,7 +205,7 @@ export type DslAxes = {
 /** 登場人物 (v0.5+ ... inline option 拡張) */
 export type DslActor = {
   name: string;
-  kind: NodeKind;
+  kind: DslNodeKind;
   /**
    * 著者が種類を書いたか。 書かなかった時 `kind` には既定の `actor` が入るため、
    * `kind` の値だけでは「書いた `actor`」 と「書かなかった」 を区別できない。
@@ -202,6 +219,16 @@ export 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)。 水位や角度を状態で動かせる。
@@ -534,6 +561,20 @@ export type DslPhase = {
    * 相手の名前は書かせない = 対象の 8 図種はいずれも図全体を 1 箱で描くため相手が決まる。
    */
   draw?: string;
+  /**
+   * 描き終えるまでに段の何割を使うか (#1441)。
+   *
+   * `draw: line 0.4` のように語の後ろに書く。 0 より大きく 1 以下。
+   * 書かなければ段の終わりに描き終わる (従来どおり)。
+   *
+   * **段の長さと描く速さを切り離すための欄**。 伸び具合は段の進みそのものなので、
+   * これが無いと「線はゆっくり引きたいが値の移りは短くしたい」 が書けず、描く速さのために
+   * 段の長さを動かすことになる。 段の長さを動かすと同じ段の `tween` まで遅くなる。
+   *
+   * **`draw` と同じ行に書かせる**。 別の項目にすると「割合だけ書いて `draw` が無い段」 が
+   * 書けてしまい、何も起きない指定になる。 同じ行なら書けない。
+   */
+  drawRatio?: number;
   /**
    * `draw` を書いた行 (#1312)。 知らせの行番号に使う。
    *