@cardenelabs/cdl 0.123.0 → 0.125.0

package/src/kinds/terminal-mark.tsx

@@ -20,6 +20,12 @@ export const MARK_INNER_RATIO = 0.56;
 const RING_WIDTH_ACTIVE = 6;
 const RING_WIDTH_IDLE = 4;
 
+// 路線図は線路幅 10 と釣り合う見本の寸法を保ち、状態遷移図の大きな印とは混ぜない。
+const METRO_START_RADIUS = 17;
+const METRO_END_RADIUS = 19;
+const METRO_END_RING_WIDTH = 3.5;
+const METRO_END_INNER_RADIUS = 10;
+
 /** 印の既定の色。 `tone` を書けばそちらが勝つ */
 const MARK_DEFAULT = "var(--cdl-tone-accent, #2d6a8f)";
 
@@ -44,16 +50,26 @@ function markRadius(node: LaidNode): number {
  * 無い。 枠を足すと線の中心が半径に乗るぶん丸が箱の外へ出て、線との接点がずれる (実測で
  * 太さ 4 の枠を足すと外径が 96 から 100 になった)。 色は `tone` で変えられる。
  */
-export function MarkStartNode({ node }: { node: LaidNode; active: boolean }): JSX.Element {
+export function MarkStartNode({
+  node,
+  metro = false,
+}: {
+  node: LaidNode;
+  active: boolean;
+  metro?: boolean;
+}): JSX.Element {
   const 色 = nodeAccent(node, MARK_DEFAULT);
   return (
-    <g transform={`translate(${node.cx - node.w / 2} ${node.cy - node.h / 2})`}>
+    <g
+      data-cdl-role={metro ? "mark-start" : undefined}
+      transform={`translate(${node.cx - node.w / 2} ${node.cy - node.h / 2})`}
+    >
       <circle
         data-cdl-role="node-body"
         data-cdl-mark="start"
         cx={node.w / 2}
         cy={node.h / 2}
-        r={markRadius(node)}
+        r={metro ? METRO_START_RADIUS : markRadius(node)}
         fill={色}
       />
     </g>
@@ -66,12 +82,23 @@ export function MarkStartNode({ node }: { node: LaidNode; active: boolean }): JS
  * 輪と中身は同じ色で描く。 別の色にすると 2 つの意味を持つ印に見えるが、表しているのは
  * 「ここで終わる」 の 1 つだけ。
  */
-export function MarkEndNode({ node, active }: { node: LaidNode; active: boolean }): JSX.Element {
+export function MarkEndNode({
+  node,
+  active,
+  metro = false,
+}: {
+  node: LaidNode;
+  active: boolean;
+  metro?: boolean;
+}): JSX.Element {
   const 色 = nodeAccent(node, MARK_DEFAULT);
-  const r = markRadius(node);
-  const 輪の太さ = active ? RING_WIDTH_ACTIVE : RING_WIDTH_IDLE;
+  const r = metro ? METRO_END_RADIUS : markRadius(node);
+  const 輪の太さ = metro ? METRO_END_RING_WIDTH : active ? RING_WIDTH_ACTIVE : RING_WIDTH_IDLE;
   return (
-    <g transform={`translate(${node.cx - node.w / 2} ${node.cy - node.h / 2})`}>
+    <g
+      data-cdl-role={metro ? "mark-end" : undefined}
+      transform={`translate(${node.cx - node.w / 2} ${node.cy - node.h / 2})`}
+    >
       <circle
         data-cdl-role="node-body"
         data-cdl-mark="end"
@@ -79,7 +106,7 @@ export function MarkEndNode({ node, active }: { node: LaidNode; active: boolean
         cy={node.h / 2}
         // 輪は線の中心を半径に置くので、外側へ太さの半分だけ出る。 印が箱の短い方の辺に
         // 収まるよう、その分だけ縮める
-        r={Math.max(0, r - 輪の太さ / 2)}
+        r={metro ? r : Math.max(0, r - 輪の太さ / 2)}
         fill="var(--cdl-node-fill, #ffffff)"
         stroke={色}
         strokeWidth={輪の太さ}
@@ -88,7 +115,7 @@ export function MarkEndNode({ node, active }: { node: LaidNode; active: boolean
         data-cdl-role="node-inner"
         cx={node.w / 2}
         cy={node.h / 2}
-        r={Math.max(0, r * MARK_INNER_RATIO)}
+        r={metro ? METRO_END_INNER_RADIUS : Math.max(0, r * MARK_INNER_RATIO)}
         fill={色}
       />
     </g>

package/src/layout/edges.ts

@@ -42,7 +42,7 @@ import {
   ARROW_ENDPOINT_CENTER_TOL,
 } from "./spec";
 import { isSelfLoop, layoutSelfLoops } from "./self-loop";
-import { DEFAULT_LABEL_MARGIN } from "./tokens";
+import { DEFAULT_LABEL_MARGIN, STAGE_COLUMN_GAP } from "./tokens";
 
 /** 縦 detour が obstacle の外側を通る時の余白 (world unit)。 */
 const VERTICAL_DETOUR_GAP = 50;
@@ -273,12 +273,30 @@ export function layoutEdges(
       if (!from) throw new Error(`cdl layout: edge "${e.id}" の from "${e.from}" が node に無い`);
       if (!to) throw new Error(`cdl layout: edge "${e.id}" の to "${e.to}" が node に無い`);
       const c = curvePath(from, to, e, labelMarginExtra, textMetrics);
+      const fromLane = lmap.get(from.lane);
+      const toLane = lmap.get(to.lane);
+      let labelX = c.labelX;
+      if (
+        fromLane?.stage !== undefined &&
+        toLane?.stage !== undefined &&
+        fromLane.id !== toLane.id &&
+        (e.label || e.sub)
+      ) {
+        const [leftLane, rightLane] =
+          fromLane.x <= toLane.x ? [fromLane, toLane] : [toLane, fromLane];
+        const gapLeft = leftLane.x + leftLane.width - STAGE_COLUMN_GAP / 2;
+        const gapRight = rightLane.x + STAGE_COLUMN_GAP / 2;
+        const labelHalfWidth = computeLabelBoxW(e.label, e.sub, textMetrics) / 2;
+        const minX = gapLeft + labelHalfWidth;
+        const maxX = gapRight - labelHalfWidth;
+        if (minX <= maxX) labelX = Math.min(maxX, Math.max(minX, labelX));
+      }
       positionedEdges.push({
         ...e,
         d: c.d,
         fromSide: c.fromSide,
         toSide: c.toSide,
-        labelX: c.labelX + (e.labelOffsetX ?? 0),
+        labelX: labelX + (e.labelOffsetX ?? 0),
         labelY: c.labelY + (e.labelOffsetY ?? 0),
         labelAnchor: c.labelAnchor,
       });
@@ -296,6 +314,7 @@ export function layoutEdges(
         labelX: m.labelX + (e.labelOffsetX ?? 0),
         labelY: m.labelY + (e.labelOffsetY ?? 0),
         labelAnchor: m.labelAnchor,
+        ...(m.metroReturn ? { metroReturn: true as const } : {}),
       });
     } else {
       autoEdges.push(e);
@@ -1522,10 +1541,101 @@ interface Rect {
   h: number;
 }
 
+/** 経路の角の点。 */
+type Vertex = { x: number; y: number };
+
 function nodeRect(n: LaidNode): Rect {
   return { x: n.cx - n.w / 2, y: n.cy - n.h / 2, w: n.w, h: n.h };
 }
 
+/** 絵の `edge-node-cross` と同じ判定で、経路が貫く箱を 1 箱 1 回で数える。 */
+function countPathObstacleCrossings(d: string, obstacles: readonly LaidNode[]): number {
+  const segments = flattenPathSegments(extractPathSegments(d));
+  return obstacles.filter((obstacle) => segmentsCrossRect(segments, nodeRect(obstacle))).length;
+}
+
+type BackDetourCandidate = {
+  d: string;
+  labelX: number;
+  crossings: number;
+  length: number;
+};
+
+/** top-top の戻り線を、帯に掛かる箱を避けた最も近い外側の列へ回す候補を作る。 */
+function makeBackDetourCandidate(
+  A: Vertex,
+  B: Vertex,
+  from: LaidNode,
+  to: LaidNode,
+  obstacles: readonly LaidNode[],
+  detourY: number,
+  side: DetourSide,
+  columnXOverride?: number,
+): BackDetourCandidate {
+  const lowIsA = A.y >= B.y;
+  const low = lowIsA ? A : B;
+  const lowBendY = low.y - VERTICAL_DETOUR_EXIT;
+  const bandTop = Math.min(detourY, lowBendY);
+  const bandBottom = Math.max(detourY, lowBendY);
+  const bandObstacles = obstacles
+    .map(nodeRect)
+    .filter((rect) => rect.y + rect.h >= bandTop && rect.y <= bandBottom);
+  let columnX = columnXOverride ?? detourColumnFor([from, to], side);
+  if (columnXOverride === undefined) {
+    while (true) {
+      const blockers = bandObstacles.filter(
+        (rect) => rect.x - VERTICAL_DETOUR_GAP < columnX
+          && columnX < rect.x + rect.w + VERTICAL_DETOUR_GAP,
+      );
+      if (blockers.length === 0) break;
+      columnX = side === "left"
+        ? Math.min(...blockers.map((rect) => rect.x - VERTICAL_DETOUR_GAP))
+        : Math.max(...blockers.map((rect) => rect.x + rect.w + VERTICAL_DETOUR_GAP));
+    }
+  }
+  const bendAY = lowIsA ? lowBendY : detourY;
+  const bendBY = lowIsA ? detourY : lowBendY;
+  const vertices: Vertex[] = [
+    A,
+    { x: A.x, y: bendAY },
+    { x: columnX, y: bendAY },
+    { x: columnX, y: bendBY },
+    { x: B.x, y: bendBY },
+    B,
+  ];
+  const d = verticesToPath(vertices);
+  const high = lowIsA ? B : A;
+  return {
+    d,
+    labelX: (high.x + columnX) / 2,
+    crossings: countPathObstacleCrossings(d, obstacles),
+    length: vertices.slice(1).reduce((sum, vertex, index) => {
+      const previous = vertices[index]!;
+      return sum + Math.hypot(vertex.x - previous.x, vertex.y - previous.y);
+    }, 0),
+  };
+}
+
+/** 交差数、長さ、終点へ入る線の並びを保つ側の順で、左右候補を 1 つに決める。 */
+function chooseBackDetourCandidate(
+  A: Vertex,
+  B: Vertex,
+  from: LaidNode,
+  to: LaidNode,
+  obstacles: readonly LaidNode[],
+  detourY: number,
+): BackDetourCandidate {
+  const left = makeBackDetourCandidate(A, B, from, to, obstacles, detourY, "left");
+  const right = makeBackDetourCandidate(A, B, from, to, obstacles, detourY, "right");
+  if (left.crossings !== right.crossings) return left.crossings < right.crossings ? left : right;
+  if (Math.abs(left.length - right.length) >= 0.5) return left.length < right.length ? left : right;
+
+  // 同じ長さなら始点側へ回すと、同じ上辺へ入る線の左右の並びを従来から入れ替えずに済む。
+  // 同じ列は左右の基準を持たないため、縦 detour と同じ右を既定にする。
+  const preferred: DetourSide = Math.abs(A.x - B.x) < 0.5 ? "right" : A.x < B.x ? "left" : "right";
+  return preferred === "left" ? left : right;
+}
+
 /** 2 rect の最短距離 (world unit)。 重なっていれば 0。 */
 function rectGap(a: Rect, b: Rect): number {
   const dx = Math.max(0, a.x - (b.x + b.w), b.x - (a.x + a.w));
@@ -1644,8 +1754,8 @@ function routePath(
   obstacles: LaidNode[] = [],
   /** 逆向きの edge と通り道を共有する時に割り当てられる側。 未指定なら右。 */
   detourSide?: DetourSide,
-  _fromLane?: LaidLane,
-  _toLane?: LaidLane,
+  fromLane?: LaidLane,
+  toLane?: LaidLane,
   edge?: CdlEdge,
   labelObstacles: LaidNode[] = obstacles,
   // CAR-541 SSOT ... 同 node 対称対 lower edge の両 endpoint 平行 shift 量 (world unit)。
@@ -2371,21 +2481,66 @@ function routePath(
   // routing v7 = detour 高さを 200 → 100 に縮小。 200px 上に飛ぶと state から遠く label が「浮いて」 見える。
   // 100px = state h/2 (75) + margin 25、 forward path (state 中心線) からは h/2 + 100 = 175px 離れて overlap 回避。
   if (topTopPair) {
-    const detourY = Math.min(A.y, B.y) - 100;
+    // 段階列では、見出しの左側を縦に貫かないよう node 上辺の右寄りから出入りし、
+    // 水平の戻り回廊を全ての段階列より上へ持ち上げる。
+    const stagePoint = (point: Vertex, node: LaidNode, lane: LaidLane | undefined): Vertex =>
+      lane?.stage === undefined
+        ? point
+        : {
+            x: Math.min(node.cx + node.w / 2 - 24, lane.x + lane.width - 24),
+            y: point.y,
+          };
+    const backA = stagePoint(A, from, fromLane);
+    const backB = stagePoint(B, to, toLane);
+    const stageTops = [fromLane, toLane]
+      .filter((lane): lane is LaidLane => lane?.stage !== undefined)
+      .map((lane) => lane.y);
+    const detourY = Math.min(
+      Math.min(backA.y, backB.y) - 100,
+      ...stageTops.map((top) => top - VERTICAL_DETOUR_GAP),
+    );
     const corner = 14;
-    const xDir = B.x > A.x ? 1 : -1;
-    return {
-      d: `M ${A.x} ${A.y}
-        L ${A.x} ${detourY + corner}
-        Q ${A.x} ${detourY}, ${A.x + xDir * corner} ${detourY}
-        L ${B.x - xDir * corner} ${detourY}
-        Q ${B.x} ${detourY}, ${B.x} ${detourY + corner}
-        L ${B.x} ${B.y}`,
-      labelX: (A.x + B.x) / 2,
+    const xDir = backB.x > backA.x ? 1 : -1;
+    const existing = {
+      d: `M ${backA.x} ${backA.y}
+        L ${backA.x} ${detourY + corner}
+        Q ${backA.x} ${detourY}, ${backA.x + xDir * corner} ${detourY}
+        L ${backB.x - xDir * corner} ${detourY}
+        Q ${backB.x} ${detourY}, ${backB.x} ${detourY + corner}
+        L ${backB.x} ${backB.y}`,
+      labelX: (backA.x + backB.x) / 2,
       // CAR-468 SSOT ... 旧 detourY - 30 magic number を LABEL_INIT_CLEARANCE (26、 CAR-570 で 34 → 26 縮小) に置換。
       // CAR-518 SSOT ... dotted-flow は 62 world (marker glow radius 分拡張) を labelInit で参照。
       // top-top detour の水平 segment 上方 labelInit world = spec 準拠距離。
       labelY: detourY - labelInit,
+      labelAnchor: "middle" as const,
+    };
+    const existingCrossings = countPathObstacleCrossings(existing.d, obstacles);
+    if (existingCrossings === 0) return existing;
+
+    // 帯に掛かる箱を避けた最も近い外側の列なら、経路に関わらない遠い箱を足しても列を動かさない。
+    // 遠回りは交差を実際に減らす時だけ採り、減らない時は短く読める従来経路を保って、
+    // 残る交差を `edge-node-cross` に報告させる。
+    // 同じ段階列の中を戻る線は、列面どうしの 48 world の隙間の中央を縦回廊に使う。
+    // 汎用の 50 world clearance で外へ押すと、隣の段階列の面へ入り込むため。
+    const candidate =
+      from.lane === to.lane && fromLane?.stage !== undefined
+        ? makeBackDetourCandidate(
+            backA,
+            backB,
+            from,
+            to,
+            obstacles,
+            detourY,
+            "right",
+            fromLane.x + fromLane.width,
+          )
+        : chooseBackDetourCandidate(backA, backB, from, to, obstacles, detourY);
+    if (candidate.crossings >= existingCrossings) return existing;
+    return {
+      d: candidate.d,
+      labelX: candidate.labelX,
+      labelY: detourY - labelInit,
       labelAnchor: "middle",
     };
   }
@@ -3062,9 +3217,6 @@ const SHARED_RUN_CORNER = VERTICAL_DETOUR_CORNER;
 /** 同じ直線上とみなす座標の差 (world unit)。 */
 const SHARED_RUN_EPS = 0.5;
 
-/** 経路の角の点。 */
-type Vertex = { x: number; y: number };
-
 /**
  * 経路を「角の点の並び」 に開く。 開けない形なら `null` を返す。
  *

package/src/layout/lanes.ts

@@ -1,7 +1,14 @@
 import type { CdlDiagram, CdlEdge, CdlTextMetrics, LaidLane, LaidNode } from "../types";
 import { CLEARANCE_NODE_LABEL } from "./clearance-constants";
 import { computeLabelBoxW, EDGE_STUB_OUT, targetNodeNodeClearance } from "./spec";
-import { CONTAIN_PAD, DEFAULT_LANE_GAP, HEADER_RESERVE, LANE_LABEL_H, LANE_PAD_MIN } from "./tokens";
+import {
+  CONTAIN_PAD,
+  DEFAULT_LANE_GAP,
+  HEADER_RESERVE,
+  LANE_LABEL_H,
+  LANE_PAD_MIN,
+  STAGE_COLUMN_GAP,
+} from "./tokens";
 
 /**
  * lane.x を「動いた」 と見なす最小差分 (world unit)。
@@ -12,6 +19,22 @@ import { CONTAIN_PAD, DEFAULT_LANE_GAP, HEADER_RESERVE, LANE_LABEL_H, LANE_PAD_M
  */
 const LANE_POSITION_EPSILON = 1e-9;
 
+/** 段階列だけを、全列を含む共通の上端と下端へ揃える。 */
+function equalizeStageColumns(lanes: LaidLane[], nodes: readonly LaidNode[] = []): LaidLane[] {
+  const stages = lanes.filter((lane) => lane.stage !== undefined);
+  if (stages.length === 0) return lanes;
+
+  const top = Math.min(...stages.map((lane) => lane.y));
+  const stageIds = new Set(stages.map((lane) => lane.id));
+  const nodeBottoms = nodes
+    .filter((node) => stageIds.has(node.lane))
+    .map((node) => node.cy + node.h / 2 + CONTAIN_PAD);
+  const bottom = Math.max(...stages.map((lane) => lane.y + lane.height), ...nodeBottoms);
+  return lanes.map((lane) =>
+    lane.stage === undefined ? lane : { ...lane, y: top, height: bottom - top },
+  );
+}
+
 export function layoutLanes(diag: CdlDiagram): LaidLane[] {
   // contain なし lane = label 高だけ確保、 contain あり lane は後で recompute で高さを node から決める。
   // lane.x が未指定 (undefined) なら 前 lane の右端 + laneGap で auto 計算 (mermaid 風 auto-layout)。
@@ -28,7 +51,7 @@ export function layoutLanes(diag: CdlDiagram): LaidLane[] {
   // 与えず、 完全に独立した free-form 座標として扱う。 未指定 lane は従来通り。
   const laneGap = diag.viewport?.laneGap ?? diag.viewport?.gap ?? DEFAULT_LANE_GAP;
   let cursorX = 0;
-  return diag.lanes.map((lane) => {
+  const lanes = diag.lanes.map((lane, index) => {
     if (lane.posX !== undefined && lane.posY !== undefined) {
       return {
         ...lane,
@@ -39,7 +62,9 @@ export function layoutLanes(diag: CdlDiagram): LaidLane[] {
       };
     }
     const resolvedX = lane.x ?? cursorX;
-    cursorX = resolvedX + lane.width + laneGap;
+    const nextLane = diag.lanes[index + 1];
+    const gapAfter = lane.stage !== undefined && nextLane?.stage !== undefined ? 0 : laneGap;
+    cursorX = resolvedX + lane.width + gapAfter;
     return {
       ...lane,
       x: resolvedX,
@@ -47,6 +72,7 @@ export function layoutLanes(diag: CdlDiagram): LaidLane[] {
       height: LANE_LABEL_H,
     };
   });
+  return equalizeStageColumns(lanes);
 }
 
 /**
@@ -128,7 +154,9 @@ export function expandLanesForNodes(lanes: LaidLane[], nodes: LaidNode[]): LaidL
     if (lane.posX !== undefined && lane.posY !== undefined) continue;
     const inside = nodes.filter((n) => n.lane === lane.id);
     const maxNodeW = inside.length > 0 ? Math.max(...inside.map((n) => n.w)) : 0;
-    const newWidth = Math.max(lane.width, maxNodeW + padFor(lane) * 2);
+    const stageMinWidth =
+      lane.stage === undefined ? 0 : maxNodeW + CONTAIN_PAD + STAGE_COLUMN_GAP;
+    const newWidth = Math.max(lane.width, maxNodeW + padFor(lane) * 2, stageMinWidth);
     widthOf.set(lane.id, newWidth);
     deltaOf.set(lane.id, newWidth - lane.width);
   }
@@ -203,6 +231,41 @@ export function expandLaneGapsForEdgeLabels(
   // 未指定 lane のみ従来の pitch 均一化 logic に参加、 catalog 100+ backward compat 保証。
   const layoutedLanes = lanes.filter((l) => !(l.posX !== undefined && l.posY !== undefined));
   if (layoutedLanes.length < 2) return lanes;
+  // 段階列は汎用 lane の均一 pitch にせず、curve の札がある境目だけを広げる。
+  // 札が無い境目は列面どうしの 48 world を保つため、stage を持たない図には影響しない。
+  if (
+    layoutedLanes.length === lanes.length &&
+    layoutedLanes.every((lane) => lane.stage !== undefined)
+  ) {
+    const sortedStages = [...layoutedLanes].sort((a, b) => a.x - b.x);
+    const stageIndexById = new Map(sortedStages.map((lane, index) => [lane.id, index]));
+    const nodeLaneById = new Map(nodes.map((node) => [node.id, node.lane]));
+    const requiredSurfaceGaps = new Array<number>(sortedStages.length - 1).fill(STAGE_COLUMN_GAP);
+
+    for (const edge of edges) {
+      if (edge.routing !== "curve" || (!edge.label && !edge.sub)) continue;
+      const fromIndex = stageIndexById.get(nodeLaneById.get(edge.from) ?? "");
+      const toIndex = stageIndexById.get(nodeLaneById.get(edge.to) ?? "");
+      if (fromIndex === undefined || toIndex === undefined || fromIndex === toIndex) continue;
+      const lo = Math.min(fromIndex, toIndex);
+      const hi = Math.max(fromIndex, toIndex);
+      const labelWidth = computeLabelBoxW(edge.label, edge.sub, textMetrics);
+      for (let pair = lo; pair < hi; pair++) {
+        requiredSurfaceGaps[pair] = Math.max(requiredSurfaceGaps[pair]!, labelWidth);
+      }
+    }
+
+    const shiftedXById = new Map<string, number>([[sortedStages[0]!.id, sortedStages[0]!.x]]);
+    for (let index = 1; index < sortedStages.length; index++) {
+      const previous = sortedStages[index - 1]!;
+      const lane = sortedStages[index]!;
+      const previousX = shiftedXById.get(previous.id)!;
+      const authoredGap = Math.max(0, lane.x - (previous.x + previous.width));
+      const laneGap = Math.max(authoredGap, requiredSurfaceGaps[index - 1]! - STAGE_COLUMN_GAP);
+      shiftedXById.set(lane.id, previousX + previous.width + laneGap);
+    }
+    return lanes.map((lane) => ({ ...lane, x: shiftedXById.get(lane.id) ?? lane.x }));
+  }
   // lane を x 昇順に並べる (author が非順序 index / x 手動指定した場合の safe fallback)。
   // shifted x を lane.id で lookup、 最後に元 lane 配列の順序で返却する。
   const nodeById = new Map(nodes.map((n) => [n.id, n]));
@@ -345,7 +408,7 @@ export function recomputeContainedLanes(lanes: LaidLane[], nodes: LaidNode[]): L
     }
   }
 
-  return lanes.map((lane) => {
+  const contained = lanes.map((lane) => {
     if (lane.lifeline) {
       return {
         ...lane,
@@ -363,4 +426,5 @@ export function recomputeContainedLanes(lanes: LaidLane[], nodes: LaidNode[]): L
       height: bottom - top + CONTAIN_PAD * 2 + LANE_LABEL_H,
     };
   });
+  return equalizeStageColumns(contained, nodes);
 }

package/src/layout/legend.ts

@@ -0,0 +1,68 @@
+import { textWidth } from "../kinds/text-width";
+import type { CdlLegendItem, CdlTextMetrics, LaidLegendItem, LaidNode } from "../types";
+import { isRenderedNode } from "./spec";
+import { VIEW_PAD } from "./tokens";
+
+/** 小型の箱の題 (20) に対する見本の比率。 */
+export const LEGEND_FONT_SIZE = 17;
+/** 見本の印 (font-size 21) を凡例の字に合わせる倍率。 */
+export const LEGEND_MARK_SCALE = LEGEND_FONT_SIZE / 21;
+/** 印を描く座標系で、見本 SVG が使う横幅。 */
+export const LEGEND_MARK_REFERENCE_WIDTH = 46;
+/** 見本 SVG の印が使う横幅を、凡例の字に合わせた値。 */
+export const LEGEND_MARK_WIDTH = LEGEND_MARK_REFERENCE_WIDTH * LEGEND_MARK_SCALE;
+/** 印の右端から文字までの間隔。 */
+export const LEGEND_MARK_TEXT_GAP = 12 * LEGEND_MARK_SCALE;
+/** 隣り合う項目の間隔を、図の箱群の幅に対する比で決める。 */
+export const LEGEND_ITEM_GAP_RATIO = 0.07;
+
+const LEGEND_BASELINE_GAP = 32;
+const LEGEND_BOTTOM_EXTENT = 10;
+
+type ViewBox = { x: number; y: number; w: number; h: number };
+
+/**
+ * 凡例を元の図の下へ置き、横一列が切れない viewBox を返す。
+ *
+ * 元の viewBox の末尾には `VIEW_PAD` があるため、その内側を図の下端として使う。
+ * 指定が無い時は呼び出されず、既存の座標と viewBox をそのまま保つ。
+ */
+export function layoutLegend(
+  items: readonly CdlLegendItem[],
+  viewBox: ViewBox,
+  textMetrics: CdlTextMetrics,
+  nodes: readonly LaidNode[],
+): { legend: LaidLegendItem[]; viewBox: ViewBox } {
+  const renderedNodes = nodes.filter(isRenderedNode);
+  const startX =
+    renderedNodes.length > 0
+      ? Math.min(...renderedNodes.map((node) => node.cx - node.w / 2))
+      : viewBox.x + VIEW_PAD;
+  const diagramRight =
+    renderedNodes.length > 0
+      ? Math.max(...renderedNodes.map((node) => node.cx + node.w / 2))
+      : viewBox.x + viewBox.w - VIEW_PAD;
+  const itemGap = (diagramRight - startX) * LEGEND_ITEM_GAP_RATIO;
+  const y = viewBox.y + viewBox.h - VIEW_PAD + LEGEND_BASELINE_GAP;
+  let x = startX;
+  const legend = items.map((item) => {
+    const laid = { ...item, x, y };
+    x +=
+      LEGEND_MARK_WIDTH +
+      LEGEND_MARK_TEXT_GAP +
+      textWidth(item.text, LEGEND_FONT_SIZE, 0, textMetrics) +
+      itemGap;
+    return laid;
+  });
+  const right = x - itemGap;
+  const bottom = y + LEGEND_BOTTOM_EXTENT + VIEW_PAD;
+
+  return {
+    legend,
+    viewBox: {
+      ...viewBox,
+      w: Math.max(viewBox.w, right + VIEW_PAD - viewBox.x),
+      h: Math.max(viewBox.h, bottom - viewBox.y),
+    },
+  };
+}