@cardenelabs/dragon 0.17.0 → 0.18.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cardenelabs/dragon",
-  "version": "0.17.0",
+  "version": "0.18.0",
   "description": "Dragon — Mermaid 感覚で animated SVG を生成する Text DSL。 cdl engine を内部利用。",
   "license": "MIT",
   "author": "cardene777",
@@ -46,8 +46,18 @@
     "node": ">=18"
   },
   "sideEffects": false,
+  "scripts": {
+    "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.18.1"
+    "@cardenelabs/cdl": "^0.20.1"
   },
   "peerDependencies": {
     "react": "^19.0.0",
@@ -66,14 +76,5 @@
     "react": "^19.1.0",
     "tsup": "^8.5.1",
     "typescript": "^5.8.0"
-  },
-  "scripts": {
-    "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"
   }
-}
+}

package/src/compile.ts

@@ -146,6 +146,8 @@ export type CompileNotice = {
     | "external-paint-dropped"
     // 図の中に描く部品を持たない見本を重ねた (#1017)
     | "part-not-drawn"
+    // 向きが効かない形で `向き:` を書いた (#1494)
+    | "direction-not-honored"
     // `倍率:` を書いた見本が、同じ名前の状態も持っていた (#1026)
     | "scale-reserved"
     // 値で描く図 (`pie` / `bar` / `line`) で値を読めなかった (#1154)
@@ -317,6 +319,7 @@ export function compileToCdl(doc: DslDocument, opts?: CompileToCdlOpts): CdlDiag
   reportActorKindNotHonored(書いたまま, opts?.onNotice);
   reportMessageOptionNotHonored(書いたまま, opts?.onNotice);
   reportDocEyebrowNotHonored(書いたまま, opts?.onNotice);
+  reportDirectionNotHonored(書いたまま, opts?.onNotice);
   reportDrawNotHonored(書いたまま, opts?.onNotice);
   reportChartFieldsNotHonored(書いたまま, opts?.onNotice);
   reportAxesNotHonored(書いたまま, opts?.onNotice);
@@ -6215,7 +6218,13 @@ function compileFlow(doc: DslDocument): CdlDiagram {
   // v0.4 ... animation あり時 builder 直接経路で複数 phase 注入
   // **縦列を書いた形は動きの有無に関わらず generic 経路へ** (#1263)。 動く図だけで効かせると、
   // 同じ記法でも静止図では指定が黙って消える (実測 = 縦列 3 本のはずが 1 本になり知らせも出ない)
-  if ((doc.animate && doc.animate.phases.length > 0) || 書いた縦列に置く("flow", doc)) {
+  // **向きを書いた形も generic 経路へ** (#1494)。 静止図の経路は並びを固定で持つので、
+  // ここを通さないと書いた向きが黙って消える (縦列を書いた形と同じ理由)
+  if (
+    (doc.animate && doc.animate.phases.length > 0) ||
+    書いた縦列に置く("flow", doc) ||
+    doc.direction !== undefined
+  ) {
     return compileGenericWithAnimate(doc, { kind: "flow", laneId: "main", laneWidth: 400 });
   }
   // 登場人物が 0 人なら枠も作らない。 描画側の `flow()` は枠を必ず 1 つ作るため、 そのまま
@@ -6251,7 +6260,13 @@ function compileSwimlane(doc: DslDocument): CdlDiagram {
   // v0.4 ... animation あり時 builder 直接経路 (各 actor 別 lane で配置)
   // **縦列を書いた形は動きの有無に関わらず generic 経路へ** (#1263)。 動く図だけで効かせると、
   // 同じ記法でも静止図では指定が黙って消える (実測 = 縦列 3 本のはずが 1 本になり知らせも出ない)
-  if ((doc.animate && doc.animate.phases.length > 0) || 書いた縦列に置く("swimlane", doc)) {
+  // **向きを書いた形も generic 経路へ** (#1494)。 静止図の経路は並びを固定で持つので、
+  // ここを通さないと書いた向きが黙って消える (縦列を書いた形と同じ理由)
+  if (
+    (doc.animate && doc.animate.phases.length > 0) ||
+    書いた縦列に置く("swimlane", doc) ||
+    doc.direction !== undefined
+  ) {
     return compileGenericWithAnimate(doc, { kind: "swimlane", laneWidth: 400 });
   }
   // swimlane preset は lane 配置 + 自由 node/edge。
@@ -6514,6 +6529,65 @@ function 後ろへ戻る矢印か(
   return 先 < 元;
 }
 
+/**
+ * 向きを選べる図種 (#1494)。
+ *
+ * **並び方そのものが読み方を担う図種は外す**。 表の図は「1 縦列 1 表」、クラス図と状態の図は
+ * 設計が格子に置く形、順序図は 1 枚の板で、どれも向きを入れ替えると図の意味が変わる。
+ *
+ * `topology` も外す = 入れ物 (`contain`) を持つ図で、縦列の中に箱を囲む作りが向きと結びついている。
+ */
+const 向きを選べる図種: ReadonlySet<PresetType> = new Set<PresetType>(["flow", "swimlane"]);
+
+/** その図種の既定の向き。 書かなかった時は今までどおりの並びになる。 */
+function 既定の向き(kind: PresetType): "縦" | "横" {
+  return kind === "flow" || kind === "topology" ? "縦" : "横";
+}
+
+/**
+ * 実際に使う向き (#1494)。
+ *
+ * 書いていない図と、効かない図種に書いた図は既定のまま = **書かない図の並びは 1 つも動かない**。
+ */
+function 並べる向き(kind: PresetType, doc: DslDocument): "縦" | "横" {
+  if (doc.direction === undefined) return 既定の向き(kind);
+  if (!向きを選べる図種.has(kind)) return 既定の向き(kind);
+  return doc.direction;
+}
+
+/**
+ * 書いた向きが効かない時に伝える (#1494)。
+ *
+ * 効かない形は 2 つある。 向きを選べない図種に書いた形と、全ての箱が縦列を書いた形。
+ * 後者は書いた縦列が勝つので、向きだけが黙って捨てられる。
+ *
+ * 黙って捨てると「書いたのに変わらない」 が手掛かりなしで起きる。
+ */
+function reportDirectionNotHonored(doc: DslDocument, onNotice?: (n: CompileNotice) => void): void {
+  if (!onNotice) return;
+  if (doc.direction === undefined) return;
+  const 行 = doc.directionPos?.line ?? doc.pos?.line ?? 0;
+  if (!向きを選べる図種.has(doc.type)) {
+    onNotice({
+      kind: "direction-not-honored",
+      actor: doc.title,
+      line: 行,
+      message: `書いた direction は効きません (type: ${doc.type} は並び方そのものが読み方を決めます)`,
+      hint: `direction を書けるのは ${[...向きを選べる図種].join(" / ")} です`,
+    });
+    return;
+  }
+  if (書いた縦列に置く(doc.type, doc)) {
+    onNotice({
+      kind: "direction-not-honored",
+      actor: doc.title,
+      line: 行,
+      message: "書いた direction は効きません (全ての箱が縦列を書いているので、そちらが優先されます)",
+      hint: "direction で並べたい時は箱の `lane` を外してください",
+    });
+  }
+}
+
 /**
  * 縦列を選べる図種 (#1263)。
  *
@@ -6616,12 +6690,18 @@ function compileGenericWithAnimate(doc: DslDocument, opts: GenericOpts): CdlDiag
         title: 箱の題(a),
       });
     });
-  } else if (kind === "flow" || kind === "topology") {
+  } else if (並べる向き(kind, doc) === "縦") {
     // 1 lane に全 actor を縦 stack
     const lid = opts.laneId ?? "main";
     b.lane(lid, {
       width: laneWidth,
-      label: doc.title,
+      /*
+       * **見出しは自然に縦へ積む図種だけ** (#1494)。
+       *
+       * `direction: 縦` を書いた泳法図がここへ来るようになった。 その図に題を渡すと、図の題が
+       * 縦列の見出しとしてもう 1 度出る (実測 = 「認証の流れ」 が題と見出しの 2 箇所に並んだ)。
+       */
+      ...(kind === "flow" || kind === "topology" ? { label: doc.title } : {}),
       ...(kind === "topology" ? { contain: true } : {}),
     });
     doc.actors.forEach((a, idx) => {
@@ -6635,7 +6715,8 @@ function compileGenericWithAnimate(doc: DslDocument, opts: GenericOpts): CdlDiag
       });
     });
   } else {
-    // swimlane / er / state ... actor ごとに 1 lane (横並び)
+    // actor ごとに 1 lane (横並び)。 `swimlane` / `er` / `state` の既定と、
+    // `向き: 横` を書いた流れ図がここに来る (#1494)
     //
     // **見出しを付けるのは `swimlane` だけ** (#1241)。 3 図種とも箱を 1 つずつ持ち、
     // その箱が既に名前を描く。 縦列にも同じ名前を渡すと **同じ字が縦に 2 つ並ぶ**

package/src/json-parser.ts

@@ -187,6 +187,8 @@ export interface DragonJson {
   bands?: { actor: string; from: number; to: number }[];
   /** 矢印をいつ出すか (#1470)。 記法の最上位 `reveal:` と同じ */
   reveal?: EdgeReveal;
+  /** 図の並ぶ向き (#1494)。 記法の最上位 `direction:` と同じ。 JSON は英語の語で書く */
+  direction?: "vertical" | "horizontal";
 }
 
 export interface JsonActor {
@@ -487,6 +489,8 @@ export const ACCEPTED_KEYS = {
     "bands",
     // 矢印をいつ出すか (#1470)
     "reveal",
+    // 図の並ぶ向き (#1494)
+    "direction",
   ],
   actor: [
     "name",
@@ -643,6 +647,8 @@ export const 欄の型表 = {
     bands: "並び",
     // 矢印をいつ出すか (#1470)
     reveal: "非空の文字列",
+    // 図の並ぶ向き (#1494)
+    direction: "非空の文字列",
   },
   actor: {
     name: "必須の非空文字列",
@@ -2494,6 +2500,8 @@ export function jsonToDoc(json: DragonJson): DslDocument {
     bands: json.bands,
     // 矢印をいつ出すか (#1470)
     reveal: json.reveal,
+    // 図の並ぶ向き (#1494)。 JSON は英語で書くので、記法と同じ語に直してから渡す
+    ...(json.direction !== undefined ? { direction: json.direction === "horizontal" ? ("横" as const) : ("縦" as const) } : {}),
     pos: p0,
   };
 }

package/src/keywords.ts

@@ -17,6 +17,34 @@ export const HEADERS = {
 /** preset 名 */
 export const PRESET_NAMES = ["sequence", "flow", "swimlane", "er", "state", "topology"] as const;
 
+/**
+ * 図の並ぶ向き (`direction:`、 #1494)。
+ *
+ * 縦列 (`lane`) は横、段 (`stack`) は縦に置かれるので、向きは「1 つの縦列に積む」 か
+ * 「1 人ずつ縦列を作る」 かの選択になる。 どちらも組み立て側に既にある経路で、
+ * 記法から名指しできる言葉が無かった。
+ */
+export const DIRECTIONS = ["縦", "横"] as const;
+export type DslDirection = (typeof DIRECTIONS)[number];
+
+/**
+ * 向きの別名。 色 (`色` / `color` / `tone`) と同じく日本語と英語の両方で書ける。
+ *
+ * 正規の語を鍵にも入れておく = 引く側が別名かどうかを気にせず 1 度で解決できる。
+ */
+export const DIRECTION_ALIAS: Record<string, DslDirection> = {
+  縦: "縦",
+  横: "横",
+  vertical: "縦",
+  horizontal: "横",
+};
+
+/** 書いた向きを正規の語に直す。 読めない語は `null`。 */
+export function resolveDirection(s: string): DslDirection | null {
+  const k = s.trim().toLowerCase();
+  return Object.hasOwn(DIRECTION_ALIAS, k) ? DIRECTION_ALIAS[k]! : null;
+}
+
 /** NodeKind 別名 (日本語 → English) */
 export const NODE_KIND_ALIAS: Record<string, NodeKind> = {
   // 日本語

package/src/schemas/diagram.json

@@ -1796,6 +1796,11 @@
         "pattern": "^[A-Za-z_][A-Za-z0-9_]*$"
       }
     },
+    "direction": {
+      "type": "string",
+      "enum": ["vertical", "horizontal"],
+      "description": "図の並ぶ向き。 vertical = 1 つの縦列に積む。 horizontal = 1 人ずつ縦列を作る。 効くのは flow と swimlane だけ。"
+    },
     "reveal": {
       "type": "string",
       "enum": ["phase", "all"],

package/src/types.ts

@@ -5,6 +5,7 @@
 
 import type { CdlDiagram, NodeKind, Tone, EdgeStyle, EdgeHead, EdgeHeadFill, EdgeReveal, ClassRelationType, SequenceMessageKind } from "@cardenelabs/cdl";
 import type { DslOnlyKind } from "./v05/parser";
+import type { DslDirection } from "./keywords";
 
 /**
  * 記法が書ける箱の種類 (#1420)。
@@ -166,6 +167,17 @@ export type DslDocument = {
    * 段に関わらず最初から全部描く。 描き手の `CdlDiagram.edgeReveal` にそのまま渡る。
    */
   reveal?: EdgeReveal;
+  /**
+   * 図の並ぶ向き (`direction:`、 #1494)。
+   *
+   * `縦` は 1 つの縦列に積み、`横` は 1 人ずつ縦列を作る。 効くのは流れ図と泳法図だけで、
+   * 他の図種は並び方そのものが読み方を担うため書いても効かない (知らせを出す)。
+   *
+   * 全ての箱が縦列を書いた形では、書いた縦列が勝つ (同じく知らせを出す)。
+   */
+  direction?: DslDirection;
+  /** `direction:` を書いた行。 効かない時の知らせで、書いた場所を指すために持つ */
+  directionPos?: { line: number };
   groups?: Record<string, DslGroup>;
   /**
    * 値を見せる部品 (`readouts:`、 #1374)。 割合の輪や数え上げを図の脇に出す。

package/src/v05/parser.ts

@@ -44,7 +44,8 @@
 import type { NodeKind, Tone, EdgeStyle, EdgeHead, EdgeHeadFill, ClassRelationType, SequenceMessageKind } from "@cardenelabs/cdl";
 import { TONES, NODE_KINDS, EDGE_HEADS, EDGE_HEAD_FILLS, EDGE_STYLES, EDGE_REVEALS, CLASS_RELATION_LOOK, SEQUENCE_MESSAGE_LOOK, parseFormula } from "@cardenelabs/cdl";
 import type { EdgeReveal } from "@cardenelabs/cdl";
-import { TONE_ALIAS, NODE_KIND_ALIAS } from "../keywords";
+import { TONE_ALIAS, NODE_KIND_ALIAS, DIRECTIONS, resolveDirection } from "../keywords";
+import type { DslDirection } from "../keywords";
 import { parseRelativePos, orderByDependency } from "../relative-pos";
 import {
   checkValueExpression,
@@ -141,6 +142,17 @@ export const TOP_LEVEL_KEYS = [
   "bands",
   // 矢印をいつ出すか (#1470)
   "reveal",
+  /*
+   * 図の並ぶ向き (#1494)。
+   *
+   * **最上位の語は英語にする**。 日本語の見出し (`タイトル:` / `種類:` 等) は v0.4 の
+   * 書き方で、2026-12-31 に廃止する側にある。 ここで日本語の語を足すと、消す予定の形を
+   * 増やすことになる。
+   *
+   * 値は日本語と英語の両方を受ける。 箱の項目 (`色` / `種類` / `位置` / `大きさ`) は v0.5 でも
+   * 日本語で書けるので、書き手が自然に言う語 (`縦` / `横`) を残せる。
+   */
+  "direction",
 ] as const;
 
 /**
@@ -426,6 +438,8 @@ export function parseTextDslV05(src: string): V05ParseResult {
   let eyebrow: string | null = null;
   let eyebrowLine = 0;
   let reveal: EdgeReveal | null = null;
+  let direction: DslDirection | null = null;
+  let directionLine = 0;
   let axes: DslAxes | undefined = undefined;
   let axesLine = 0;
   let actors: DslActor[] = [];
@@ -492,6 +506,32 @@ export function parseTextDslV05(src: string): V05ParseResult {
       i += 1;
       continue;
     }
+    if (head.key === "direction") {
+      /*
+       * 図の並ぶ向き (#1494)。
+       *
+       * `縦` は 1 つの縦列に積み、`横` は 1 人ずつ縦列を作る。 どちらも組み立て側に既にある
+       * 経路で、ここで足すのは名指しする言葉だけ。
+       *
+       * **書いた行を覚える**。 効かない図種に書いた時の知らせが、書いた場所を指せるようにする。
+       */
+      const v = (head.value ?? "").trim();
+      if (v.length > 0) {
+        const 解けた = resolveDirection(v);
+        if (解けた !== null) {
+          direction = 解けた;
+          directionLine = line.no;
+        } else {
+          errors.push({
+            line: line.no,
+            message: `direction が読めません (書いた値: ${v})`,
+            hint: `使える語 = ${DIRECTIONS.join(" / ")} / vertical / horizontal`,
+          });
+        }
+      }
+      i += 1;
+      continue;
+    }
     if (head.key === "eyebrow") {
       // 空で書いた形 (`eyebrow:`) は「書かなかった」 と同じにする。 空文字を残すと
       // 描画側が中身のない帯を出す
@@ -966,6 +1006,7 @@ export function parseTextDslV05(src: string): V05ParseResult {
       type: type!,
       ...(eyebrow !== null ? { eyebrow, eyebrowPos: { line: eyebrowLine } } : {}),
       ...(reveal !== null ? { reveal } : {}),
+      ...(direction !== null ? { direction, directionPos: { line: directionLine } } : {}),
       ...(axes !== undefined ? { axes, axesPos: { line: axesLine } } : {}),
       actors,
       flow,