@cardenelabs/cdl 0.123.0 → 0.125.0

package/src/types.ts

@@ -30,7 +30,7 @@ export type Tone = (typeof TONES)[number];
 export type CdlTextMetrics = "proportional" | "monospace";
 
 /**
- * cdl SVG に付与される data-cdl-role attribute の SSOT 型 (現在 12 role)。
+ * cdl SVG に付与される data-cdl-role attribute の SSOT 型。
  * consumer app (dragon 等) は `[data-cdl-role="<role>"]` selector で CSS を宛てる。 role を追加する時は本 union と該当 render 箇所 (kinds/*.tsx、
  * render/edges.tsx、 render/stage.tsx) を同時に更新する。
  *
@@ -54,6 +54,21 @@ export type CdlTextMetrics = "proportional" | "monospace";
  *   - "lane-container"  ... lane.contain=true の boundary rect
  *   - "lane-lifeline"   ... lane.lifeline=true の縦点線 line
  *   - "lane-label"      ... lane 見出し text
+ *   - "metro-lane-badge" ... 路線用 lane の担当を示す名札
+ *   - "metro-lane-guide" ... 路線用 lane の名札から右へ伸びる案内線
+ *   - "mark-start"      ... 路線図の始まりの印
+ *   - "mark-end"        ... 路線図の終わりの印
+ *   - "legend"          ... 図の下へ横一列に置く凡例全体
+ *   - "legend-item"     ... 凡例の 1 項目
+ *   - "legend-mark"     ... 凡例項目の印
+ *   - "legend-text"     ... 凡例項目の文字
+ *   - "stage-column"    ... lane.stage を持つ段階列の面
+ *   - "stage-number"    ... 段階列の見出しに出す番号
+ *   - "stage-name"      ... 段階列の見出しに出す名前
+ *   - "stage-divider"   ... 段階列の見出しと中身を分ける線
+ *   - "stage-note"      ... 段階列にある札か、補助線を持つ札の右側へ置く補足
+ *   - "timeline-axis"   ... lane.timelineAxis=true の縦実線
+ *   - "timeline-leader" ... node.leaderTo で札から時間軸の番号へ結ぶ矢印なしの補助線
  */
 export type CdlRole =
   | "node-body"
@@ -67,7 +82,44 @@ export type CdlRole =
   | "edge-label"
   | "lane-container"
   | "lane-lifeline"
-  | "lane-label";
+  | "lane-label"
+  | "metro-lane-badge"
+  | "metro-lane-guide"
+  | "mark-start"
+  | "mark-end"
+  | "legend"
+  | "legend-item"
+  | "legend-mark"
+  | "legend-text"
+  | "stage-column"
+  | "stage-number"
+  | "stage-name"
+  | "stage-divider"
+  | "stage-note"
+  | "timeline-axis"
+  | "timeline-leader";
+
+/** 凡例に描ける印。 配置・描画・検査はこの 1 つの列を出所にする。 */
+export const LEGEND_MARKS = [
+  "diamond",
+  "filled-circle",
+  "double-circle",
+  "dotted-line",
+  "solid-line",
+  "curved-line",
+  "rounded-label",
+  "numbered-circle",
+  "station",
+  "arrow",
+] as const;
+
+export type LegendMark = (typeof LEGEND_MARKS)[number];
+
+/** 図の下へ置く凡例の 1 項目。 */
+export type CdlLegendItem = {
+  mark: LegendMark;
+  text: string;
+};
 
 /** 描画できる箱の種類。 検査・記法一覧・型はこの 1 つの列を出所にする。 */
 export const NODE_KINDS = [
@@ -191,12 +243,14 @@ export const NODE_KINDS = [
   "shape-lawyer",
   "shape-trader",
   "shape-customer-service",
-  // 流れの始まりと終わりの印 2 種 (#560) ... 塗った丸と輪で囲んだ丸。
-  // 状態遷移図が使う。 印そのものが意味を持つので文字は描かない
+  // 流れの始まりと終わりの印 2 種 (#560) ... 始点と終点は線の端から推測せず、著者が
+  // `kind: "mark-start"` / `kind: "mark-end"` の node を明示する。印は文字を描かない
   "mark-start",
   "mark-end",
   // 路線図の駅 (#996) ... 線路上の点を小さな丸で示し、名前と説明は丸の外に置く
   "station",
+  // 時間軸の番号 (#1017) ... 実線の軸上に番号を入れた丸を置く。路線図の駅とは別の意味を持つ。
+  "timeline-number",
   // 時系列のやり取り (#578) ... 1 つの箱が図を丸ごと描く。 縦が時間で、参加者は箱を持たない
   "sequence-board",
 ] as const;
@@ -222,10 +276,12 @@ export type EdgeStyle = "solid" | "dotted-flow" | "dashed";
  * 線の道筋。
  *
  * - `"default"` ... 自動。 箱を避け、角を丸めた直角の線を引く。 書かない時も同じ
- * - `"back-detour"` ... 箱の上を回って前の箱へ戻る
+ * - `"back-detour"` ... 箱の上を回って前の箱へ戻り、途中の箱と交わる時は外側を回る
  * - `"curve"` ... 始点から水平に出て終点へ水平に入る 3 次曲線。 途中の箱は避けず、
  *   2 点が同じ高さなら直線になる。 終点の矢印は水平を向く
- * - `"metro"` ... 横線と傾き ±1 の斜線だけで結び、角を半径 r の円弧で丸める。
+ * - `"metro"` ... 通常は横線と傾き ±1 の斜線で結び、角を円弧で丸める。
+ *   `decision` からの枝は、行き先が同じ横位置なら上下の角から真っ直ぐ、右にあれば右の角から出て曲がる。
+ *   左へ戻る `dashed` は行き先側へ横に出して駅の上下へ入る。
  *   途中の箱は避けず、2 点が同じ高さなら横 1 本になる
  */
 export type EdgeRouting = "default" | "back-detour" | "curve" | "metro";
@@ -407,7 +463,29 @@ export type CdlLane = {
    */
   width: number;
   label?: string;
+  /**
+   * 路線図の担当として描く lane。 `label` を名札の名前、`subtitle` をその補足に使う。
+   *
+   * 書いた lane だけが名札と案内線を出す。書かない lane の出力は変わらない。
+   */
+  metro?: {
+    subtitle?: string;
+  };
   contain?: boolean;
+  /**
+   * lane を同じ上端・高さの段階列として描く時の見出し。
+   *
+   * `number` と `name` は別の SVG text に出るため、利用側は `stage-number` と `stage-name` を
+   * 個別に選べる。この lane にある `card` node の `subtitle` は、札の右側へ `stage-note` として
+   * 描き、通常の card の補足位置には出さない。
+   * `leaderTo` を持つ `card` も、段階列の内外にかかわらず同じ `stage-note` を使う。
+   *
+   * 書かない lane は既存の縦列のままで、`lane-container` / `lane-label` の入力と出力は変わらない。
+   */
+  stage?: {
+    number: string;
+    name: string;
+  };
   /**
    * この lane を何のために置いているか (既定 = `"column"`)。
    *
@@ -427,6 +505,12 @@ export type CdlLane = {
   role?: "column" | "overlay";
   /** UML sequence diagram の lifeline (= lane の中央 x に縦の点線を描画) */
   lifeline?: boolean;
+  /**
+   * lane の中央 x に時間軸の実線を描く。線はこの lane にある描画対象 node の中心間を結ぶ。
+   *
+   * `lifeline` の点線とは独立しており、両方を書いた lane では両方を描く。
+   */
+  timelineAxis?: boolean;
   /**
    * 明示指定した座標。 `posX` と `posY` の **両方**が揃った lane は「置いた位置に置く」
    * 扱いになる。 片方だけでは何も変わらない。
@@ -453,6 +537,11 @@ export type CdlNode = {
   title: string;
   eyebrow?: string;
   subtitle?: string;
+  /**
+   * この箱から指定した node へ矢印なしの補助線を引く。edge ではないため `laid.edges` には入らない。
+   * `card` の `subtitle` は札の右側へ `stage-note` として描き、通常の補足位置には出さない。
+   */
+  leaderTo?: string;
   /** mono 数値表示用、 `{stateId}` を含めれば state 値で動的置換 */
   value?: string;
   /** kind=storage 時の行 (各 mono、 state 参照可) */
@@ -891,7 +980,8 @@ export type CdlEdge = {
   /** label の y 方向 fine offset (default 0、 + で下、 - で上) */
   labelOffsetY?: number;
   /**
-   * 線の道筋。 `default` は箱を避ける自動経路、 `back-detour` は箱の上を回る戻り線、
+   * 線の道筋。 `default` は箱を避ける自動経路、 `back-detour` は箱の上を回り、途中の箱と
+   * 交わる時は外側を回る戻り線、
    * `curve` は途中の箱を避けず、両端で水平になる 3 次曲線。 `metro` は途中の箱を避けず、
    * 横線と傾き ±1 の斜線を半径 r の円弧で結ぶ。2 点が同じ高さなら横 1 本。書かなければ `default`。
    */
@@ -2782,6 +2872,8 @@ export type CdlDiagram = {
    * 種類を書いていない図にも当たる。
    */
   type?: string;
+  /** SVG 内の図の下へ、指定順の横一列で置く凡例。 */
+  legend?: readonly CdlLegendItem[];
   /**
    * 矢印をいつ出すか (既定 = `"phase"`、 #582)。
    *
@@ -2972,6 +3064,14 @@ export type LaidEdge = CdlEdge & {
   labelX: number;
   labelY: number;
   labelAnchor: "start" | "middle" | "end";
+  /** 前の station へ戻る metro 線だけが持つ、専用の点線と矢印を描く目印。 */
+  metroReturn?: true;
+};
+
+export type LaidLegendItem = CdlLegendItem & {
+  x: number;
+  /** 文字の baseline。 印はこの値を基準に同じ行へ揃える。 */
+  y: number;
 };
 
 /**
@@ -3007,6 +3107,8 @@ export type LaidDiagram = {
   textMetrics?: "monospace";
   /** どの種類の図か (#645)。 `CdlDiagram.type` をそのまま持ち越す */
   type?: string;
+  /** 指定がある図だけが持つ、配置済みの凡例。 */
+  legend?: readonly LaidLegendItem[];
   viewBox: { x: number; y: number; w: number; h: number };
   /**
    * 図全体の倍率 (`CdlViewport.scale` を正規化した値)。

package/src/validate.ts

@@ -191,6 +191,11 @@ export function validate(diag: CdlDiagram): void {
         `[cdl] unknown-ref: node "${n.id}" の lane "${n.lane}" が未定義です${suggest(n.lane, laneIds)}\n  → 修正例: .lane("${n.lane}", { x: 0, width: 400 }) を node 宣言前に追加`,
       );
     }
+    if (n.leaderTo !== undefined && !nodeIds.has(n.leaderTo)) {
+      errors.push(
+        `[cdl] unknown-ref: node "${n.id}" の leaderTo "${n.leaderTo}" が node に存在しません${suggest(n.leaderTo, nodeIds, "node")}`,
+      );
+    }
   }
   for (const e of diag.edges) {
     if (!nodeIds.has(e.from)) {

package/src/visual-validate.ts

@@ -151,11 +151,10 @@ import {
   rendersTitleText,
   fitsOwnTitleWidth,
   skipsNodeTitleWidthCheck,
-  drawsTitleOutsideBox,
   titleScalesToFit,
   MIN_TITLE_FONT_SIZE,
   titleFontSize,
-  TITLE_BOX_PADDING,
+  titleUsableWidth,
   rowBaselineY,
   rowGlyphDepth,
   laneVerticalRange,
@@ -2007,8 +2006,10 @@ function runAxes(
   const LIFELINE_W_THRESHOLD = 8;
   for (const n of laid.nodes) {
     if (n.w < LIFELINE_W_THRESHOLD) continue;
-    // 駅は文字を収める箱ではなく線路上の印なので、箱向けの最小寸法を要求しない。
-    if (n.kind === "station") continue;
+    // 駅と丸い番号は文字を収める箱ではなく軸上の印なので、箱向けの最小寸法を要求しない。
+    // 丸い番号は見本の半径 24 と縁 4 から大きさが決まり、80×40 を求めると軸より太くなる。
+    // 番号の字が読めるかは軸 3 (text-readability) が引き続き見る。
+    if (n.kind === "station" || n.kind === "timeline-number") continue;
     if (n.w < MIN_NODE_W || n.h < MIN_NODE_H) {
       push(
         "node-visibility",
@@ -2065,8 +2066,7 @@ function runAxes(
     //
     // 箱の内側の余白 (52) は、題を箱の中に描く種別にだけ足す。 箱の外に描く種別 (`dyn-*` の
     // 名前と図表の題) は内側の余白に縛られないので、足すと収まっている題まで挙がる。
-    const 余白 = drawsTitleOutsideBox(n.kind) ? 0 : TITLE_BOX_PADDING;
-    const 使える幅 = n.w - 余白;
+    const 使える幅 = titleUsableWidth(n.kind, n.w, n.h);
     const 実幅 = measureTextWidth(titleTrimmed, {
       fontSize: titleFontSize(n.kind),
       bound: "drawn",
@@ -2089,7 +2089,7 @@ function runAxes(
       push(
         "text-readability",
         // 字ごとの実幅は小数になるので、読む人に出す時だけ丸める (判定は丸めない)
-        `node "${n.id}" title "${n.title}" が node 幅 ${n.w}px を超過する可能性 (期待 ${Math.round(実幅 + 余白)}px)`,
+        `node "${n.id}" title "${n.title}" が node 幅 ${n.w}px を超過する可能性 (期待 ${Math.round(実幅 + (n.w - 使える幅))}px)`,
         "warn",
       );
     }