@cardenelabs/cdl 0.19.0 → 0.20.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cardenelabs/cdl",
-  "version": "0.19.0",
+  "version": "0.20.0",
   "description": "CDL (Chainome Diagram Language). Mermaid-like declarative DSL that compiles to animated SVG diagrams. Built for blockchain / Solidity flows, generic enough for sequence / flow / state / ER / topology diagrams.",
   "license": "MIT",
   "author": "cardene777",

package/src/kinds/actor.tsx

@@ -2,13 +2,17 @@ import type { JSX } from "react";
 import type { LaidNode } from "../types";
 import { nodeAccent } from "./node-tone";
 import { titlePlacement } from "./compact-title";
+import { 目印なしの繰り上げ } from "../layout/spec";
 
 export function ActorNode({ node, active, value }: { node: LaidNode; active: boolean; value: string | undefined }): JSX.Element {
   const accent = nodeAccent(node, "var(--cdl-tone-accent, #2d6a8f)");
   const x = node.cx - node.w / 2;
   const y = node.cy - node.h / 2;
+  // 小見出しを書かない時は、そのために空けた帯のぶん字を上へ繰り上げる (#589)。
+  // 繰り上げ量は `layout/spec.ts` が持つ = 高さを出す側と同じ値を引く
+  const 繰り上げ = node.eyebrow ? 0 : 目印なしの繰り上げ("actor");
   // 小型の箱では名前を中央に置く。 固定の位置のままだと下端をまたぐ (#416)
-  const 名前 = titlePlacement(node, { x: 26, y: 86, size: 32 }, { hasEyebrow: Boolean(node.eyebrow) });
+  const 名前 = titlePlacement(node, { x: 26, y: 86 - 繰り上げ, size: 32 }, { hasEyebrow: Boolean(node.eyebrow) });
   return (
     <g transform={`translate(${x} ${y})`}>
       <rect
@@ -50,14 +54,14 @@ export function ActorNode({ node, active, value }: { node: LaidNode; active: boo
         <line
           data-cdl-role="node-row-divider"
           x1={26}
-          y1={110}
+          y1={110 - 繰り上げ}
           x2={node.w - 26}
-          y2={110}
+          y2={110 - 繰り上げ}
           stroke="var(--cdl-row-divider, #7e848e)"
         />
       )}
       {node.subtitle && (
-        <text x={26} y={140} fontSize={20} fill="var(--cdl-text-dim, #5a6270)">
+        <text x={26} y={140 - 繰り上げ} fontSize={20} fill="var(--cdl-text-dim, #5a6270)">
           {node.subtitle}
         </text>
       )}

package/src/kinds/card.tsx

@@ -2,6 +2,7 @@ import type { JSX } from "react";
 import type { LaidNode } from "../types";
 import { nodeAccent } from "./node-tone";
 import { fitTextSize, isCompactBox } from "./compact-title";
+import { 目印なしの繰り上げ } from "../layout/spec";
 
 export function CardNode({ node, active }: { node: LaidNode; active: boolean }): JSX.Element {
   const accent = nodeAccent(node, "var(--cdl-tone-accent, #2d6a8f)");
@@ -16,7 +17,9 @@ export function CardNode({ node, active }: { node: LaidNode; active: boolean }):
   const compact = isCompactBox(node.h);
   // 小型の箱でも呼び名を出す (#578)。 出す時は題を上へ寄せて、2 行を箱の中で釣り合わせる
   const 小型に呼び名 = compact && Boolean(node.subtitle);
-  const titleY = compact ? (小型に呼び名 ? node.h / 2 - 2 : node.h / 2 + 8) : 86;
+  // 小見出しを書かない時の繰り上げ (#589)。 値は `layout/spec.ts` SSOT
+  const 繰り上げ = node.eyebrow ? 0 : 目印なしの繰り上げ("card");
+  const titleY = compact ? (小型に呼び名 ? node.h / 2 - 2 : node.h / 2 + 8) : 86 - 繰り上げ;
   const titleX = compact ? node.w / 2 : 26;
   const paddingX = compact ? 16 : 52;
   const availableW = node.w - paddingX;
@@ -54,7 +57,7 @@ export function CardNode({ node, active }: { node: LaidNode; active: boolean }):
         {node.title}
       </text>
       {!compact && node.subtitle && (
-        <text x={26} y={124} fontSize={subtitleSize} fill="var(--cdl-text-dim, #5a6270)">
+        <text x={26} y={124 - 繰り上げ} fontSize={subtitleSize} fill="var(--cdl-text-dim, #5a6270)">
           {node.subtitle}
         </text>
       )}

package/src/kinds/event.tsx

@@ -2,6 +2,7 @@ import type { JSX } from "react";
 import type { LaidNode } from "../types";
 import { nodeAccent } from "./node-tone";
 import { titlePlacement } from "./compact-title";
+import { 目印なしの繰り上げ } from "../layout/spec";
 
 export function EventNode({
   node,
@@ -15,8 +16,10 @@ export function EventNode({
   const accent = nodeAccent(node, "var(--cdl-tone-success, #4ea36a)");
   const x = node.cx - node.w / 2;
   const y = node.cy - node.h / 2;
+  // 小見出しを書かない時の繰り上げ (#589)。 値は `layout/spec.ts` SSOT
+  const 繰り上げ = node.eyebrow ? 0 : 目印なしの繰り上げ("event");
   // 小型の箱では名前を中央に置く。 固定の位置のままだと下端をまたぐ (#416)
-  const 名前 = titlePlacement(node, { x: 26, y: 88, size: 26 }, { hasEyebrow: Boolean(node.eyebrow) });
+  const 名前 = titlePlacement(node, { x: 26, y: 88 - 繰り上げ, size: 26 }, { hasEyebrow: Boolean(node.eyebrow) });
   const scale = active ? 0.78 + 0.22 * progress : 0.92;
   const opacity = active ? 0.5 + 0.5 * progress : 0.65;
   return (
@@ -56,7 +59,7 @@ export function EventNode({
         {node.subtitle && (
           <text
             x={26}
-            y={128}
+            y={128 - 繰り上げ}
             fontSize={21}
             fill="var(--cdl-text-dim, #5a6270)"
             style={{ fontFamily: "'JetBrains Mono', monospace" }}

package/src/kinds/function.tsx

@@ -2,6 +2,7 @@ import type { JSX } from "react";
 import type { LaidNode } from "../types";
 import { nodeAccent } from "./node-tone";
 import { titlePlacement } from "./compact-title";
+import { 目印なしの繰り上げ } from "../layout/spec";
 
 export function FunctionNode({ node, active }: { node: LaidNode; active: boolean }): JSX.Element {
   const accent = nodeAccent(node, "var(--cdl-tone-teal, #2f8770)");
@@ -10,8 +11,10 @@ export function FunctionNode({ node, active }: { node: LaidNode; active: boolean
   const stroke = nodeAccent(node, active ? "var(--cdl-tone-accent, #2d6a8f)" : "var(--cdl-tone-teal, #2f8770)");
   const x = node.cx - node.w / 2;
   const y = node.cy - node.h / 2;
+  // 小見出しを書かない時の繰り上げ (#589)。 値は `layout/spec.ts` SSOT
+  const 繰り上げ = node.eyebrow ? 0 : 目印なしの繰り上げ("function");
   // 小型の箱では名前を中央に置く。 固定の位置のままだと下端をまたぐ (#416)
-  const 名前 = titlePlacement(node, { x: 26, y: 86, size: 24 }, { hasEyebrow: Boolean(node.eyebrow) });
+  const 名前 = titlePlacement(node, { x: 26, y: 86 - 繰り上げ, size: 24 }, { hasEyebrow: Boolean(node.eyebrow) });
   return (
     <g transform={`translate(${x} ${y})`}>
       <rect
@@ -44,7 +47,7 @@ export function FunctionNode({ node, active }: { node: LaidNode; active: boolean
         {node.title}
       </text>
       {node.subtitle && (
-        <text x={26} y={126} fontSize={20} fill="var(--cdl-text-dim, #5a6270)">
+        <text x={26} y={126 - 繰り上げ} fontSize={20} fill="var(--cdl-text-dim, #5a6270)">
           {node.subtitle}
         </text>
       )}

package/src/kinds/generic.tsx

@@ -7,6 +7,7 @@ import {
   genericTextShift,
   genericTitleBaselineY,
   rowBaselineY,
+  目印なしの繰り上げ,
 } from "../layout/spec";
 import {
   GENERIC_ROW_LEFT_SIZE_PX,
@@ -300,9 +301,12 @@ export function GenericNode({
   // cylinder は上 ellipse (ry=14) の下に text を置く。 ずらし量は `spec.ts` が持つ
   const cylinderShift = genericTextShift(node.kind);
   // 中心揃え時は h/2 を baseline 中心 (dominantBaseline=middle で計算するため text y を h/2 ベースに統一)
+  // 小見出しを書かない時は、そのために空けた帯のぶん字を上へ繰り上げる (#589)。
+  // 中央へ寄せる形と行を持つ形では繰り上げない (前者は塊の置き方が違い、後者は 1 行目と重なる)
+  const 繰り上げ = node.eyebrow || centered ? 0 : 目印なしの繰り上げ(node.kind, hasRows);
   const eyebrowY = centered ? h / 2 - 26 : 32 + cylinderShift;
-  const titleY = genericTitleBaselineY(node.kind, h, hasRows);
-  const subtitleY = centered ? h / 2 + 28 : 96 + cylinderShift;
+  const titleY = genericTitleBaselineY(node.kind, h, hasRows) - 繰り上げ;
+  const subtitleY = centered ? h / 2 + 28 : 96 + cylinderShift - 繰り上げ;
   // icon 位置 (diamond / cloud は title の真右の少し上、 中心配置に合わせる)
   const iconX = centered ? w / 2 + 40 : w - 48;
   const iconY = centered ? h / 2 - 44 : 18 + cylinderShift;

package/src/kinds/storage.tsx

@@ -2,6 +2,7 @@ import type { JSX } from "react";
 import type { LaidNode, RowMark } from "../types";
 import { nodeAccent } from "./node-tone";
 import { titlePlacement } from "./compact-title";
+import { 目印なしの繰り上げ } from "../layout/spec";
 import {
   ROW_PITCH_STORAGE,
   ROW_TOP_STORAGE,
@@ -98,8 +99,11 @@ export function StorageNode({
   const accent = nodeAccent(node, "var(--cdl-tone-accent, #2d6a8f)");
   const x = node.cx - node.w / 2;
   const y = node.cy - node.h / 2;
+  // 小見出しを書かない時の繰り上げ (#589)。 行を持つ形では繰り上げない (1 行目と重なる)
+  const 繰り上げ =
+    node.eyebrow || rows.length > 0 ? 0 : 目印なしの繰り上げ("storage");
   // 小型の箱では名前を中央に置く。 固定の位置のままだと下端をまたぐ (#416)
-  const 名前 = titlePlacement(node, { x: 26, y: STORAGE_TITLE_BASELINE, size: STORAGE_TITLE_FONT }, { hasEyebrow: Boolean(node.eyebrow) });
+  const 名前 = titlePlacement(node, { x: 26, y: STORAGE_TITLE_BASELINE - 繰り上げ, size: STORAGE_TITLE_FONT }, { hasEyebrow: Boolean(node.eyebrow) });
   // 全 row を delimiter (`:` / ` = ` / ` → ` / ` -> `) で left / right に分割し、
   // left 列 max 文字数を算出 → 右列の固定 x 位置を決める (DB table / UML class box 風)。
   // 結果として全 row の右列開始 x が揃い、 区切り線がガタつかなくなる。
@@ -166,7 +170,7 @@ export function StorageNode({
         <text
           data-cdl-role="node-subtitle"
           x={ROW_PAD_X_PX}
-          y={SUBTITLE_BASELINE}
+          y={SUBTITLE_BASELINE - 繰り上げ}
           fontSize={SUBTITLE_FONT}
           fill="var(--cdl-text-dim, #5a6270)"
         >

package/src/layout/edges.ts

@@ -355,10 +355,12 @@ export function layoutEdges(diag: CdlDiagram, nodes: LaidNode[], lanes: LaidLane
   //   4. 結果 = 全 pill Y 揃え + X 方向のみ最小限 shift で重なり回避、 idx=0 pill (最左 X) は
   //      shift 0 で SSOT LABEL_TO_PATH_CLEARANCE 維持、 他 pill も全て同 Y (path から SSOT 距離)。
   //
-  // CAR-636 fan dispersion X 分散の pill 間 gap (world unit)。 label bbox 端 + 20 world で
-  // 視覚的に明確な間隔を確保、 SSOT clearance-constants の CLEARANCE_NODE_LABEL (16 相当) より
-  // 大きめに設定 (pill 同士の可読性重視、 node 押し出しとは別軸の SSOT)。
-  const FAN_LABEL_GAP = 20;
+  // fan dispersion で X に分散する時の pill 間 gap (world unit)。
+  //
+  // **検査が要求する値そのものを使う** (#589)。 20 を独自に持っていた間、掃いた結果が
+  // `clearance` 軸の要求 (36) に届かず、実測で 32 しか空かない図が残った。 掃く側と見る側で
+  // 別の値を持つと、掃いても落ちる。
+  const FAN_LABEL_GAP = CLEARANCE_LABEL_LABEL;
 
   // CAR-541 SSOT ... 同 node の対称対 edge (out + in が同 side) を上下配置ルールで分離。
   //
@@ -1045,7 +1047,27 @@ export function layoutEdges(diag: CdlDiagram, nodes: LaidNode[], lanes: LaidLane
   const applyFanDispersion = (list: RoutedEdge[], tracked: Set<string> | null): void => {
     if (list.length < 2) return;
     const obstaclePatterns = new Set(list.map((r) => detectsBlockingObstacle(r.p)));
-    if (obstaclePatterns.size > 1) return;
+    if (obstaclePatterns.size > 1) {
+      /*
+       * 形の違う線が混ざる群を **まとめて掃かない** のは元のとおり (Y の差が 100 world 以上
+       * 開き、当たり判定がずれるため)。 ただし丸ごと諦めると、同じ形どうしの重なりまで
+       * 残る (#589)。
+       *
+       * 形ごとに分けてから掃く。 実測 = 4 段の網の図で、迂回する 2 本の説明が 25 しか離れず
+       * `clearance` が error を出していた (要る間隔は 36)。 箱が低くなって間隔が縮んだ時に
+       * 出た = 形の違う 1 本が混ざっていたせいで、残る 2 本も掃かれていなかった。
+       */
+      const 形ごと = new Map<boolean, RoutedEdge[]>();
+      for (const r of list) {
+        const 形 = detectsBlockingObstacle(r.p);
+        形ごと.set(形, [...(形ごと.get(形) ?? []), r]);
+      }
+      for (const 同じ形 of 形ごと.values()) {
+        // 分けた結果が元と同じ大きさになることは無い (種類が 2 つ以上ある)。 念のため守る
+        if (同じ形.length < list.length) applyFanDispersion(同じ形, tracked);
+      }
+      return;
+    }
     // CAR-615 SSOT ... group 内に overlay:true edge が 1 本でもあれば fan dispersion skip。
     // overlay:true (flowchart 等の true/false condition label、 CAR-549) は「label を path 上に
     // 重ねる」 semantic を持つため、 fan offset を加えると pill が path から離れて overlay 意図が

package/src/layout/nodes.ts

@@ -6,6 +6,9 @@ import {
   requiredVerticalLabelGap,
   requiredRowsHeight,
   SUBTITLE_ROW_SHIFT,
+  中身から出す高さ,
+  目印なしの繰り上げ,
+  段を積む箱か,
 } from "./spec";
 import { DEFAULT_NODE_GAP, HEADER_RESERVE, LANE_TOP_PAD, NODE_SIZE, STACK_GAP } from "./tokens";
 
@@ -21,7 +24,14 @@ import { DEFAULT_NODE_GAP, HEADER_RESERVE, LANE_TOP_PAD, NODE_SIZE, STACK_GAP }
  * `row-vertical-spacing` (軸 16) が同じ `rowBaselineY` を見て検査する。
  */
 function autoStorageHeight(
-  n: { kind: string; rows?: string[]; rowMarks?: readonly unknown[]; subtitle?: string; h?: number },
+  n: {
+    kind: string;
+    rows?: string[];
+    rowMarks?: readonly unknown[];
+    subtitle?: string;
+    eyebrow?: string;
+    h?: number;
+  },
   defaultH: number,
 ): number {
   if (n.kind !== "storage") return n.h ?? defaultH;
@@ -32,7 +42,9 @@ function autoStorageHeight(
   // 字の高さ 73.2 に上の余白 21 を上下ぶん足して 115 にする。
   const 印あり = n.rowMarks !== undefined;
   const 呼び名の分 = 印あり && n.subtitle ? SUBTITLE_ROW_SHIFT : 0;
-  if (!n.rows || n.rows.length === 0) return 115 + 呼び名の分;
+  // 小見出しを書かない形では字を上へ繰り上げるので、その分だけ箱も低くする (#589)
+  const 繰り上げ = n.eyebrow ? 0 : 目印なしの繰り上げ("storage");
+  if (!n.rows || n.rows.length === 0) return 115 + 呼び名の分 - 繰り上げ;
   const 必要 = requiredRowsHeight("storage", n.rows.length) ?? defaultH;
   // 行頭の印を持つ箱は **中身の足し算だけ** で高さを決める (#578)。 下限を残すと、行が
   // 1 つしか無い箱が 4 行の箱と同じ高さになり、下が空いたまま並ぶ。
@@ -61,6 +73,37 @@ function autoRowsWidth(n: { kind: string; rows?: string[]; w?: number }, default
   return Math.max(defaultW, required);
 }
 
+/**
+ * node 1 つの高さ (SSOT)。
+ *
+ * 2 段で決める。 `storage` は行の数から出し (`autoStorageHeight`)、段を積む種別は
+ * **書いた段の数** から出す (`中身から出す高さ`、#589)。 どちらにも当たらない種別は
+ * 種別ごとの既定値をそのまま使う。
+ *
+ * 著者が `h` を書いた時はその値が勝つ。
+ */
+function 箱の高さ(
+  n: {
+    kind: string;
+    h?: number;
+    rows?: string[];
+    rowMarks?: readonly unknown[];
+    subtitle?: string;
+    eyebrow?: string;
+    value?: string;
+  },
+  既定h: number,
+): number {
+  if (n.h != null) return n.h;
+  if (n.kind === "storage") return autoStorageHeight(n, 既定h);
+  return 中身から出す高さ(n.kind, 既定h, {
+    hasEyebrow: Boolean(n.eyebrow),
+    hasSubtitle: Boolean(n.subtitle),
+    hasValue: Boolean(n.value),
+    hasRows: (n.rows?.length ?? 0) > 0,
+  });
+}
+
 /**
  * 同 lane 内で隣り合う row を繋ぐ edge の label が収まる stack gap を求める (Issue #202)。
  *
@@ -124,7 +167,7 @@ export function layoutNodes(diag: CdlDiagram, lanes: LaidLane[]): LaidNode[] {
   const rowH = new Map<number, number>();
   for (const stack of allStacks) {
     const nodesAtStack = diag.nodes.filter((n) => n.stack === stack);
-    const h = Math.max(...nodesAtStack.map((n) => autoStorageHeight(n, NODE_SIZE[n.kind].h)));
+    const h = Math.max(...nodesAtStack.map((n) => 箱の高さ(n, NODE_SIZE[n.kind].h)));
     rowH.set(stack, h);
   }
   const rowCy = new Map<number, number>();
@@ -201,8 +244,12 @@ export function layoutNodes(diag: CdlDiagram, lanes: LaidLane[]): LaidNode[] {
      * 図全体が上へ寄って見えた (user 指摘)。 芯で揃えると上端も下端も箱ごとに違うが、
      * 並びの重心が 1 本に通る。 見た目検査の `row-alignment` もこの前提で書かれている。
      */
-    const 自前の高さ = n.rowMarks !== undefined;
-    const h = n.h ?? (自前の高さ ? autoStorageHeight(n, size.h) : 段の高さ);
+    //
+    // 段を積む箱 (#589) も同じ扱いにする。 書いた段の数から高さを出しているので、段の高さへ
+    // 伸ばすとその値が捨てられる = 名前だけの箱が 3 段の箱と同じ高さに戻る。
+    const 自前の高さ =
+      n.rowMarks !== undefined || 段を積む箱か(n.kind, (n.rows?.length ?? 0) > 0);
+    const h = n.h ?? (自前の高さ ? 箱の高さ(n, size.h) : 段の高さ);
     const cy = 段の芯;
     // n.w 明示時は尊重、 未指定で rows[] を持つ node は内容長に合わせて auto 拡張。
     const w = autoRowsWidth(n, size.w);

package/src/layout/spec.ts

@@ -996,3 +996,131 @@ export function buildDiagramAltText(
   else if (body) parts.push(body);
   return parts.join(" ");
 }
+
+/**
+ * 箱の中身から高さを出すための、描き手が使う段の位置 (#589)。
+ *
+ * ## なぜ要るか
+ *
+ * 箱の高さは種別ごとの固定値で、小見出し + 名前 + 説明の 3 段が入る前提で決まっている。
+ * 名前 1 語だけの箱も 3 段ぶんの高さになり、実測で `function` は 151 に対し字が 29 しか
+ * 無かった (上 63 / 下 59)。
+ *
+ * 空きは上下の両方に出る。 小見出しを書かないと、そのために空けた帯が上にそのまま残る。
+ * 説明を書かないと、説明の段が下に残る。
+ *
+ * ## 何を持つか
+ *
+ * 描き手 (`kinds/*.tsx`) が持つ baseline と字の大きさを、layout から引ける形で 1 箇所に置く。
+ * 描き手はここから繰り上げ量を引き、layout はここから高さを出す = **同じ値を 2 箇所に書かない**。
+ *
+ * 高さそのものは持たない。 3 段を書いた時の高さは `NODE_SIZE` が SSOT で、ここは
+ * 「そこから何を引くか」 だけを決める。
+ */
+type 段の並び = {
+  目印: { y: number; size: number };
+  名前: { y: number; size: number };
+  説明: { y: number; size: number };
+};
+
+/**
+ * 描き手ごとの段の位置。
+ *
+ * `storage` も入れる。 行を持たない形の高さは `autoStorageHeight` が出すが (#586 で 115)、
+ * 小見出しを書かない形では字が下に寄る (実測で上 53 / 下 21)。 繰り上げ量はここから引く。
+ *
+ * 字を中央へ寄せる 2 種別 (`cloud` / `decision`) も入れない。 段を積む形ではないので
+ * 繰り上げの考え方が当たらない (cardene777/cdl#588 で別に扱う)。
+ */
+const 段の位置: Readonly<Record<string, 段の並び>> = {
+  actor: { 目印: { y: 38, size: 18 }, 名前: { y: 86, size: 32 }, 説明: { y: 140, size: 20 } },
+  function: { 目印: { y: 38, size: 18 }, 名前: { y: 86, size: 24 }, 説明: { y: 126, size: 20 } },
+  event: { 目印: { y: 38, size: 18 }, 名前: { y: 88, size: 26 }, 説明: { y: 128, size: 21 } },
+  card: { 目印: { y: 38, size: 18 }, 名前: { y: 86, size: 24 }, 説明: { y: 124, size: 21 } },
+  storage: {
+    目印: { y: 38, size: 18 },
+    名前: { y: STORAGE_TITLE_BASELINE, size: STORAGE_TITLE_FONT },
+    説明: { y: 118, size: 20 },
+  },
+};
+
+/** `kinds/generic.tsx` が描く 21 種別の段の位置 (円柱のずらしは呼ぶ側が足す) */
+const 汎用の段: 段の並び = {
+  目印: { y: 32, size: 17 },
+  名前: { y: GENERIC_TITLE_TOP, size: GENERIC_TITLE_FONT },
+  説明: { y: 96, size: 17 },
+};
+
+/**
+ * その種別が中身から高さを出せるか。 出せない種別は従来どおり固定の高さを使う。
+ *
+ * 行を持つ形は対象外 = 行は箱の上端から数えて置かれるので、繰り上げると 1 行目と名前が重なる。
+ */
+export function 段を積む箱か(kind: string | undefined, hasRows: boolean): boolean {
+  if (hasRows) return false;
+  if (kind === undefined) return false;
+  if (genericTextCentered(kind, false)) return false;
+  return kind in 段の位置 || rendersRows(kind);
+}
+
+function 段を引く(kind: string): 段の並び | null {
+  const 固有 = 段の位置[kind];
+  if (固有) return 固有;
+  // `rendersRows` が真の種別のうち `storage` を除いた 21 種別が `generic.tsx` に回る
+  if (rendersRows(kind)) return 汎用の段;
+  return null;
+}
+
+/**
+ * 小見出しを書かない時に、字の塊を上へ繰り上げる量 (SSOT)。
+ *
+ * **名前の上端が、小見出しの上端と同じところへ来る** 値にする。 小見出しのために空けた帯を
+ * 名前が引き継ぐ形で、上の余白は書き方に依らず同じになる。
+ *
+ * 字形の上端は baseline から `GLYPH_CAP_RATIO` 割上と見込む (`compact-title.ts` と同じ目安)。
+ */
+export function 目印なしの繰り上げ(kind: string | undefined, hasRows = false): number {
+  if (!段を積む箱か(kind, hasRows)) return 0;
+  const 段 = 段を引く(kind!);
+  if (!段) return 0;
+  const 上げる =
+    段.名前.y - 段.目印.y + (段.目印.size - 段.名前.size) * GLYPH_CAP_RATIO;
+  return Math.max(0, Math.round(上げる));
+}
+
+/** 説明を書かない時に、箱が縮む量 (SSOT)。 名前と説明の段の間隔そのもの */
+export function 説明なしで縮む量(kind: string | undefined, hasRows = false): number {
+  if (!段を積む箱か(kind, hasRows)) return 0;
+  const 段 = 段を引く(kind!);
+  if (!段) return 0;
+  return Math.max(0, 段.説明.y - 段.名前.y);
+}
+
+/**
+ * 書いた段の数から箱の高さを出す (#589)。
+ *
+ * 3 段すべてを書いた形が `満載h` で、書かなかった段のぶんを引く。 3 段を書いた箱の高さは
+ * 変わらない = 既存の図の見た目を動かさない。
+ *
+ * 値 (`value`) を持つ箱は縮めない。 値は箱の下端から置かれるので、縮めると名前と重なる。
+ */
+export function 中身から出す高さ(
+  kind: string | undefined,
+  満載h: number,
+  中身: { hasEyebrow: boolean; hasSubtitle: boolean; hasValue: boolean; hasRows: boolean },
+): number {
+  if (!段を積む箱か(kind, 中身.hasRows)) return 満載h;
+  if (中身.hasValue) return 満載h;
+  const 引く =
+    (中身.hasEyebrow ? 0 : 目印なしの繰り上げ(kind)) +
+    (中身.hasSubtitle ? 0 : 説明なしで縮む量(kind));
+  return Math.max(MIN_BOX_H, 満載h - 引く);
+}
+
+/**
+ * 中身から出した高さの下限。
+ *
+ * これを下回ると箱として読めない。 名前だけの箱で最も低くなるのは `generic` の 21 種別で、
+ * 実測の見込みは 54 なので、下限が効くのは 3 段の高さを著者が縮めた形に限る。
+ */
+export const MIN_BOX_H = 44;