@cardenelabs/cdl 0.83.0 → 0.102.0

package/dist/{render-DfXCs3Eh.d.cts → render-oEmwYN-q.d.cts}

@@ -625,12 +625,30 @@ type QuadrantPayload = {
 };
 /** quadrant-matrix の象限 4 種 */
 type QuadrantKey = "topLeft" | "topRight" | "bottomLeft" | "bottomRight";
-/** quadrant-matrix の 1 item payload */
+/**
+ * quadrant-matrix の中の位置。 描画域の左下を (0, 0)、 右上を (1, 1) とする。
+ *
+ * **y は上向き**。 SVG の座標とは逆で、 図に出る軸の名前 (`↑ 大きい`) と同じ向きにする。
+ * 書き手が読む向きと書く向きが逆だと、 値を反転して書くことになる。
+ */
+type QuadrantAt = {
+    x: BoundNumber;
+    y: BoundNumber;
+};
+/**
+ * quadrant-matrix の 1 item payload。
+ *
+ * 位置の決め方は 2 通りで、**どちらか片方だけを読む**。 `at` があれば座標で置き、
+ * 無ければ `quadrant` の象限に積む。 両方を読むと同じことが 2 か所に書かれ、
+ * 食い違った時にどちらが正しいか決められない。
+ */
 type QuadrantItemPayload = {
     id: string;
     title: string;
-    /** どの象限に居るか。 `{signal}` を書くと項目が象限を移る */
-    quadrant: BoundEnum<QuadrantKey>;
+    /** どの象限に居るか。 `{signal}` を書くと項目が象限を移る。 `at` がある項目では読まない */
+    quadrant?: BoundEnum<QuadrantKey>;
+    /** 描画域の中の位置。 書くと点として描かれ、象限は座標から決まる */
+    at?: QuadrantAt;
     subtitle?: string;
 };
 /**

package/dist/{render-DfXCs3Eh.d.ts → render-oEmwYN-q.d.ts}

@@ -625,12 +625,30 @@ type QuadrantPayload = {
 };
 /** quadrant-matrix の象限 4 種 */
 type QuadrantKey = "topLeft" | "topRight" | "bottomLeft" | "bottomRight";
-/** quadrant-matrix の 1 item payload */
+/**
+ * quadrant-matrix の中の位置。 描画域の左下を (0, 0)、 右上を (1, 1) とする。
+ *
+ * **y は上向き**。 SVG の座標とは逆で、 図に出る軸の名前 (`↑ 大きい`) と同じ向きにする。
+ * 書き手が読む向きと書く向きが逆だと、 値を反転して書くことになる。
+ */
+type QuadrantAt = {
+    x: BoundNumber;
+    y: BoundNumber;
+};
+/**
+ * quadrant-matrix の 1 item payload。
+ *
+ * 位置の決め方は 2 通りで、**どちらか片方だけを読む**。 `at` があれば座標で置き、
+ * 無ければ `quadrant` の象限に積む。 両方を読むと同じことが 2 か所に書かれ、
+ * 食い違った時にどちらが正しいか決められない。
+ */
 type QuadrantItemPayload = {
     id: string;
     title: string;
-    /** どの象限に居るか。 `{signal}` を書くと項目が象限を移る */
-    quadrant: BoundEnum<QuadrantKey>;
+    /** どの象限に居るか。 `{signal}` を書くと項目が象限を移る。 `at` がある項目では読まない */
+    quadrant?: BoundEnum<QuadrantKey>;
+    /** 描画域の中の位置。 書くと点として描かれ、象限は座標から決まる */
+    at?: QuadrantAt;
     subtitle?: string;
 };
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cardenelabs/cdl",
-  "version": "0.83.0",
+  "version": "0.102.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/chart-gauge.tsx

@@ -3,7 +3,8 @@ import type { LaidNode, Tone } from "../types";
 import { TONE, chartSeriesColor } from "../render/tone";
 import { resolveChartData } from "../render/payload-binding";
 import { textWidth } from "./text-width";
-import { 実値表記, 割合表記 } from "./chart-number";
+import { 実値表記, 割合表記, 値と割合の文字 } from "./chart-number";
+import { 値と割合の字 } from "./chart-legend-number";
 import { 進みを畳む } from "./draw-progress";
 import { 扇形の切り抜き } from "./draw-arc";
 
@@ -88,7 +89,7 @@ export function ChartGaugeNode({
    */
   /** 内訳 1 件の数値の行 (実値と割合) */
   const 数値の行 = (d: { value: number }): string =>
-    `${実値表記(d.value)}  ${割合表記(d.value / total)}`;
+    値と割合の文字(実値表記(d.value), 割合表記(d.value / total), total);
 
   /**
    * 件の並びから、1 行に置ける件数と段数を出す。
@@ -387,6 +388,14 @@ export function ChartGaugeNode({
         const y = 内訳のy + 段の高さ * 段;
         /** 区画に収まる字幅。 名前も数値も同じ幅で切る */
         const 収まる幅 = 内訳の幅 - 区画の間;
+        /**
+         * 数の行。 切らずに済む時だけ色で 2 つに分ける (cdl#911)。
+         *
+         * 切る時は 1 つの字として扱う = 切った後の字を値と割合に分け直すと、
+         * 切れ目が値の途中に来た行だけ色が付かない形になる。
+         */
+        const 数の行 = 内訳の数値[idx] ?? "";
+        const 切った数の行 = 切り詰める(数の行, 収まる幅, 数値の級);
         return (
           <g key={`legend-${idx}`} data-cdl-role="chart-gauge-item">
             <rect
@@ -408,7 +417,15 @@ export function ChartGaugeNode({
             </text>
             {/* **数値も切り詰める** = 切らないと隣の区画の字とくっつく (cdl#731) */}
             <text x={x} y={y + 46} fontSize={数値の級} fill="var(--cdl-text-dim, #5a6270)">
-              {切り詰める(内訳の数値[idx] ?? "", 収まる幅, 数値の級)}
+              {切った数の行 === 数の行 ? (
+                <値と割合の字
+                  値={実値表記(d.value)}
+                  割合={割合表記(d.value / total)}
+                  合計={total}
+                />
+              ) : (
+                切った数の行
+              )}
             </text>
           </g>
         );

package/src/kinds/chart-legend-number.tsx

@@ -0,0 +1,33 @@
+import type { JSX } from "react";
+import { 値と割合の組 } from "./chart-number";
+
+/**
+ * 一覧の数の行を組む (cdl#911)。
+ *
+ * 値を濃く、割合を薄くして **色で 2 つに分ける**。 中黒のような区切りを字で足すと 1 件の幅が
+ * 増え、幅から置ける件数を決めている半円ゲージでは実測で件数 20 が 12 まで畳まれた。
+ * 色なら空白 1 つで並べられるので、繋ぐ前 (空白 2 つ) より狭くなる。
+ *
+ * **幅の見積りは `値と割合の文字` が持つ**。 描く側と測る側で別の字を組むと、収まるはずの
+ * 行が溢れる。 組み方をこの 1 か所に置いて、3 つの種別から呼ぶ。
+ */
+export function 値と割合の字({
+  値,
+  割合,
+  合計,
+}: {
+  値: string;
+  割合: string;
+  合計: number;
+}): JSX.Element {
+  const 組 = 値と割合の組(値, 割合, 合計);
+  if (組.値 === null) return <tspan data-cdl-role="chart-legend-share">{組.割合}</tspan>;
+  return (
+    <>
+      <tspan data-cdl-role="chart-legend-value" fill="var(--cdl-text, #1a1f2a)">
+        {`${組.値} `}
+      </tspan>
+      <tspan data-cdl-role="chart-legend-share">{組.割合}</tspan>
+    </>
+  );
+}

package/src/kinds/chart-number.ts

@@ -31,3 +31,36 @@ export function 割合表記(frac: number): string {
   const v = Math.round(frac * 1000) / 10;
   return `${Number.isInteger(v) ? v : v.toFixed(1)}%`;
 }
+
+/**
+ * 一覧の 1 行に出す「値と割合」 (cdl#911)。
+ *
+ * **2 つの数を字で繋がない**。 `78  78%` のように空白 2 つで繋ぐと 1 つの数に見えるが、
+ * 中黒などの区切りを足すと 1 件あたりの幅が増える。 半円ゲージの内訳は幅で置ける件数を
+ * 決めているため、実測では件数 20 が 12 まで畳まれた (中黒に空白を添えない形でも同じ)。
+ * **色で分ける** = 値を濃く、割合を薄くすれば、空白 1 つで並べても 2 つの数として読める。
+ * 幅は繋ぐ前より狭くなる。
+ *
+ * **合計が 100 の図は割合だけを出す**。 値と割合が同じ数になり、同じ数を 2 度並べることに
+ * なる。 `chart-pie` が既に同じ判断を持っており (名前と値が同じ時は片方を落とす)、
+ * そこから形を揃えた。
+ *
+ * 判定に幅を持たせるのは、合計が小数の足し合わせで作られる図があるため。
+ */
+export function 値と割合の組(値: string, 割合: string, 合計: number): {
+  値: string | null;
+  割合: string;
+} {
+  return Math.abs(合計 - 100) < 1e-9 ? { 値: null, 割合 } : { 値, 割合 };
+}
+
+/**
+ * 同じ 1 行を 1 つの字として読んだ形 (cdl#911)。
+ *
+ * 幅を測る時に使う。 描く時は `値と割合の組` を使って色で分ける = 描画と幅の見積りで
+ * 別々の字を組むと、収まるはずの行が溢れる。
+ */
+export function 値と割合の文字(値: string, 割合: string, 合計: number): string {
+  const 組 = 値と割合の組(値, 割合, 合計);
+  return 組.値 === null ? 組.割合 : `${組.値} ${組.割合}`;
+}

package/src/kinds/chart-radial.tsx

@@ -3,7 +3,8 @@ import type { LaidNode, Tone } from "../types";
 import { TONE, chartSeriesColor } from "../render/tone";
 import { resolveChartData } from "../render/payload-binding";
 import { textWidth } from "./text-width";
-import { 実値表記, 割合表記 } from "./chart-number";
+import { 実値表記, 割合表記, 値と割合の文字 } from "./chart-number";
+import { 値と割合の字 } from "./chart-legend-number";
 import { 進みを畳む } from "./draw-progress";
 import { 扇形の切り抜き } from "./draw-arc";
 
@@ -67,7 +68,10 @@ export function ChartRadialNode({
   /** 一覧と弧の間 */
   const 一覧と弧の間 = 28;
 
-  const 数値の文字 = data.map((d) => `${実値表記(d.value)}  ${割合表記(d.value / total)}`);
+  /** 合計が 100 なら値と割合が同じ数になるので、一覧には割合だけを出す (cdl#911) */
+  const 数値の文字 = data.map((d) =>
+    値と割合の文字(実値表記(d.value), 割合表記(d.value / total), total),
+  );
   /** 一覧の幅。 **中身から決める** = 割り当てを固定すると使わない分が死ぬ (cdl#542) */
   const 一覧の幅 =
     印の幅 +
@@ -97,7 +101,16 @@ export function ChartRadialNode({
   const 帯1本 = 使える厚み / Math.max(data.length, 1);
   const 帯の幅 = 帯1本 * 0.66;
 
-  const 弧のcx = PAD + 一覧の幅 + 一覧と弧の間 + 外半径;
+  /**
+   * 一覧と弧を合わせた塊を、箱の横中央へ置く (cdl#911)。
+   *
+   * 外半径は高さでも決まるため、箱が横に長いほど右が余る。 左端から順に置いていた形では
+   * 実測で 37% が右に空いていた。
+   * **塊の単位で寄せる** = 一覧と弧を別々に中央へ寄せると 2 つが重なる。
+   */
+  const 中身の幅 = 一覧の幅 + 一覧と弧の間 + 外半径 * 2;
+  const 一覧の左 = Math.max(PAD, (node.w - 中身の幅) / 2);
+  const 弧のcx = 一覧の左 + 一覧の幅 + 一覧と弧の間 + 外半径;
   const cy = PAD + 使える高さ / 2;
 
   const rings = data.map((d, idx) => {
@@ -209,9 +222,9 @@ export function ChartRadialNode({
         const y = 一覧の始まり + 行の高さ * idx;
         return (
           <g key={`item-${idx}`} data-cdl-role="chart-radial-item">
-            <rect x={PAD} y={y - 11} width={4} height={22} rx={2} fill={arcColor(d.tone, idx)} />
+            <rect x={一覧の左} y={y - 11} width={4} height={22} rx={2} fill={arcColor(d.tone, idx)} />
             <text
-              x={PAD + 印の幅}
+              x={一覧の左 + 印の幅}
               y={y + 1}
               fontSize={名前の級}
               fontWeight={700}
@@ -220,12 +233,16 @@ export function ChartRadialNode({
               {d.label}
             </text>
             <text
-              x={PAD + 印の幅}
+              x={一覧の左 + 印の幅}
               y={y + 20}
               fontSize={数値の級}
               fill="var(--cdl-text-dim, #5a6270)"
             >
-              {数値の文字[idx]}
+              <値と割合の字
+                値={実値表記(d.value)}
+                割合={割合表記(d.value / total)}
+                合計={total}
+              />
             </text>
           </g>
         );

package/src/kinds/chart-stat.tsx

@@ -53,7 +53,7 @@ export function ChartStatNode({
    */
   const 前を出す = data.some((d) => d.previous !== undefined);
 
-  const 区画 = 区画の割付(node.w, node.h, data.length, 前を出す);
+  const 区画 = 区画の割付(node.w, node.h, data.length, 前を出す, data.length > 1);
 
   /**
    * 割合を出すか (cdl#759)。
@@ -207,17 +207,24 @@ export function ChartStatNode({
  * 件数で横に等分する。 **縦の位置は件数に依らない** = 件数が変わると数値の高さが動く形に
  * すると、同じ図を並べた時に数値の行が揃わない。
  */
-function 区画の割付(w: number, h: number, 件数: number, 前を出す: boolean) {
+function 区画の割付(
+  w: number,
+  h: number,
+  件数: number,
+  前を出す: boolean,
+  割合を出す: boolean,
+) {
   const 余白 = 20;
   const 幅 = 件数 > 0 ? w / 件数 : w;
   const 名前の級 = 14;
-  /** 数値の級。 **名前より大きい** のがこの種別の中身 */
-  const 数値の級 = 40;
   /** 前の時点の級。 名前と同じにする = 数値より大きくすると主役が入れ替わる (cdl#763) */
   const 前の級 = 名前の級;
   const 割合の級 = 12;
   const 弧の半径 = 20;
   const 弧の太さ = 4;
+  /** 数値の級の下限と上限 (cdl#911)。 下限は寄せる前の値で、上限は箱を大きくしても伸ばさない線 */
+  const 数値の級の下限 = 40;
+  const 数値の級の上限 = 112;
 
   /**
    * 前の行が使う縦の量 (cdl#763)。
@@ -227,8 +234,31 @@ function 区画の割付(w: number, h: number, 件数: number, 前を出す: boo
    */
   const 前の高さ = 前を出す ? 8 + 前の級 : 0;
 
+  /**
+   * 弧と割合が使う縦の量 (cdl#911)。
+   *
+   * **描かない図では 0 にする**。 前の行 (`前の高さ`) と同じ判断で、寄せる前はここだけ
+   * 常に 76 を数えていた。 件が 1 つの図は弧も割合も描かないのに縦だけ取られ、
+   * 中身が上へ寄って箱の下半分が空いていた。
+   */
+  const 弧と割合の高さ = 割合を出す ? 16 + 弧の半径 * 2 + 8 + 割合の級 : 0;
+
+  /**
+   * 数値の級。 **名前より大きい** のがこの種別の中身 (cdl#911)。
+   *
+   * 弧も割合も描かない図では、空いた縦を数値に回す = 数値 1 つのために箱を空けない。
+   * 上限を置くのは、箱が大きいほど字が伸び続けると図ではなく看板になるため。
+   * 幅に収める縮めは描く側の `収める級` が持つので、ここでは縦だけを見る。
+   */
+  const 数値の級 = 割合を出す
+    ? 数値の級の下限
+    : Math.max(
+        数値の級の下限,
+        Math.min(数値の級の上限, Math.floor(h - 余白 * 2 - 名前の級 - 12 - 前の高さ)),
+      );
+
   // 上から 名前 / 数値 / 前 / 弧 / 割合 の順に積む。 中身の高さを出してから縦中央に寄せる
-  const 中身の高さ = 名前の級 + 12 + 数値の級 + 前の高さ + 16 + 弧の半径 * 2 + 8 + 割合の級;
+  const 中身の高さ = 名前の級 + 12 + 数値の級 + 前の高さ + 弧と割合の高さ;
   const 上端 = Math.max(余白, (h - 中身の高さ) / 2);
 
   const 名前のy = 上端 + 名前の級;

package/src/kinds/chart-waffle.tsx

@@ -3,7 +3,8 @@ import type { LaidNode, Tone } from "../types";
 import { TONE, chartSeriesColor } from "../render/tone";
 import { resolveChartData } from "../render/payload-binding";
 import { textWidth } from "./text-width";
-import { 実値表記 } from "./chart-number";
+import { 実値表記, 値と割合の文字 } from "./chart-number";
+import { 値と割合の字 } from "./chart-legend-number";
 import { 進みを畳む } from "./draw-progress";
 
 /**
@@ -104,7 +105,11 @@ export function ChartWaffleNode({
   const 一覧と格子の間 = 28;
   const 印の幅 = 18;
 
-  const 数値の文字 = data.map((d, i) => `${実値表記(d.value)}  ${配分[i] ?? 0}%`);
+  /** 合計が 100 なら値と割合が同じ数になるので、一覧には割合だけを出す (cdl#911) */
+  const 実値の合計 = data.reduce((acc, d) => acc + d.value, 0);
+  const 数値の文字 = data.map((d, i) =>
+    値と割合の文字(実値表記(d.value), `${配分[i] ?? 0}%`, 実値の合計),
+  );
   /** 一覧の幅。 中身から決める = 割り当てを固定すると使わない分が死ぬ (cdl#542) */
   const 一覧の幅 =
     印の幅 +
@@ -120,7 +125,16 @@ export function ChartWaffleNode({
   /** 升の 1 辺。 縦横の小さい方に収める (格子は正方形) */
   const 升 = Math.max(4, Math.min(使える高さ, 格子に使える幅) / WAFFLE_COLS);
   const 印 = 升 * 0.78;
-  const 格子の左 = PAD + 一覧の幅 + 一覧と格子の間;
+  /**
+   * 一覧と格子を合わせた塊を、箱の横中央へ置く (cdl#911)。
+   *
+   * 格子の 1 辺は高さで決まるため、箱が横に長いほど右が余る。 左端から順に置いていた形では
+   * 実測で 39% が右に空き、「何かが入るはずの空き」 に見えていた。
+   * **塊の単位で寄せる** = 一覧と格子を別々に中央へ寄せると 2 つが重なる。
+   */
+  const 中身の幅 = 一覧の幅 + 一覧と格子の間 + 升 * WAFFLE_COLS;
+  const 一覧の左 = Math.max(PAD, (node.w - 中身の幅) / 2);
+  const 格子の左 = 一覧の左 + 一覧の幅 + 一覧と格子の間;
   const 格子の上 = PAD + (使える高さ - 升 * WAFFLE_COLS) / 2;
 
   /** 印 1 個ごとの持ち主。 上の行から左詰めで配る = 読む向きと同じで数えやすい */
@@ -187,9 +201,9 @@ export function ChartWaffleNode({
         const y = 一覧の始まり + 行の高さ * idx;
         return (
           <g key={`item-${idx}`} data-cdl-role="chart-waffle-item">
-            <rect x={PAD} y={y - 11} width={4} height={22} rx={2} fill={印の色(d.tone, idx)} />
+            <rect x={一覧の左} y={y - 11} width={4} height={22} rx={2} fill={印の色(d.tone, idx)} />
             <text
-              x={PAD + 印の幅}
+              x={一覧の左 + 印の幅}
               y={y + 1}
               fontSize={名前の級}
               fontWeight={700}
@@ -200,12 +214,16 @@ export function ChartWaffleNode({
             <text
               data-cdl-role="chart-waffle-count"
               data-cdl-unresolved={d.unresolved ? "true" : undefined}
-              x={PAD + 印の幅}
+              x={一覧の左 + 印の幅}
               y={y + 20}
               fontSize={数値の級}
               fill="var(--cdl-text-dim, #5a6270)"
             >
-              {数値の文字[idx]}
+              <値と割合の字
+                値={実値表記(d.value)}
+                割合={`${配分[idx] ?? 0}%`}
+                合計={実値の合計}
+              />
             </text>
           </g>
         );

package/src/kinds/dyn-shape.tsx

@@ -60,18 +60,78 @@ export function DynShapeNode({
   const fillColor = shape.fill ?? "var(--cdl-fill, #e0e6ef)";
   const activeOpacity = active ? 1 : 0.85;
 
-  switch (shape.kind) {
-    case "rect":
-      return renderRect(shape, x, y, w, h, stateValues, fillColor, strokeColor, activeOpacity, node);
-    case "circle":
-      return renderCircle(shape, cx, cy, w, h, stateValues, fillColor, strokeColor, activeOpacity);
-    case "arc":
-      return renderArc(shape, cx, cy, w, h, stateValues, fillColor, strokeColor, activeOpacity);
-    case "wave":
-      return <WaveShape shape={shape} x={x} y={y} w={w} h={h} stateValues={stateValues} fillColor={fillColor} strokeColor={strokeColor} opacity={activeOpacity} node={node} />;
-    case "polygon":
-      return renderPolygon(shape, cx, cy, stateValues, fillColor, strokeColor, activeOpacity);
-  }
+  const 形 = (() => {
+    switch (shape.kind) {
+      case "rect":
+        return renderRect(shape, x, y, w, h, stateValues, fillColor, strokeColor, activeOpacity, node);
+      case "circle":
+        return renderCircle(shape, cx, cy, w, h, stateValues, fillColor, strokeColor, activeOpacity);
+      case "arc":
+        return renderArc(shape, cx, cy, w, h, stateValues, fillColor, strokeColor, activeOpacity);
+      case "wave":
+        return <WaveShape shape={shape} x={x} y={y} w={w} h={h} stateValues={stateValues} fillColor={fillColor} strokeColor={strokeColor} opacity={activeOpacity} node={node} />;
+      case "polygon":
+        return renderPolygon(shape, cx, cy, stateValues, fillColor, strokeColor, activeOpacity);
+    }
+  })();
+
+  // 名前と値は箱の外に置く (#925)。 中に置くと、内側の塗りが値で動くたびに文字と重なる。
+  //
+  // **差し込みはここで通さない**。 `render/nodes.tsx` が `{名前}` を解決した節を渡してくるので、
+  // ここで通しても何も変わらない (実測 = 通さない形に変えても検査が 1 件も落ちなかった)。
+  // しかも向こうは値ごとの呼び名の表を持っており、ここには無い = 二重に通すと、
+  // 呼び名を持つ図だけ結果が変わる余地を作る。
+  const 名前 = (node.title ?? "").trim();
+  const 値 = (node.subtitle ?? "").trim();
+  // どちらも書かれていない節では包む `<g>` も足さない = 書かない図の DOM を 1 要素も変えない
+  if (名前 === "" && 値 === "") return 形;
+  const 揃え = 箱いっぱいに描く(shape.kind) ? "start" : "middle";
+  return (
+    <g>
+      {形}
+      {名前 !== "" && (
+        <text
+          data-cdl-role="shape-name"
+          x={揃え === "start" ? x : cx}
+          y={y - NAME_GAP}
+          textAnchor={揃え}
+          fontSize={13}
+          fontWeight={600}
+          fill="var(--cdl-text, #23201b)"
+        >
+          {名前}
+        </text>
+      )}
+      {値 !== "" && (
+        <text
+          data-cdl-role="shape-value"
+          x={cx}
+          y={y + h + VALUE_GAP}
+          textAnchor="middle"
+          fontSize={12}
+          fill="var(--cdl-text-dim, #5a6270)"
+        >
+          {値}
+        </text>
+      )}
+    </g>
+  );
+}
+
+/** 名前の下端から箱の上端までの間 (world unit)。 読み取り値 (`y - 6`) と同じ高さに並ぶ */
+const NAME_GAP = 6;
+/** 箱の下端から値の上端までの間 (world unit) */
+const VALUE_GAP = 18;
+
+/**
+ * その形が箱いっぱいに描くか (#925)。
+ *
+ * 名前を揃える先が形の描き方で分かれる。 `rect` と `wave` は箱いっぱいに描くので、
+ * 箱の左端が形の左端になる。 `circle` / `arc` / `polygon` は箱の中心に描くので、
+ * 左端には何も無い = 左に揃えると名前だけが離れて浮く。
+ */
+function 箱いっぱいに描く(kind: CdlDynShape["kind"]): boolean {
+  return kind === "rect" || kind === "wave";
 }
 
 function renderRect(

package/src/kinds/funnel.tsx

@@ -2,6 +2,7 @@ import { useId, type JSX } from "react";
 import type { LaidNode, Tone } from "../types";
 import { TONE } from "../render/tone";
 import { resolveFunnelData } from "../render/payload-binding";
+import { 収める倍率 } from "../layout/text-width";
 import { 進みを畳む } from "./draw-progress";
 
 /**
@@ -68,6 +69,10 @@ export function FunnelNode({
     return canvasW * (topRatio + (bottomRatio - topRatio) * t);
   };
 
+  /** 段の名前と補足の素の大きさ。 補足は名前より 1 段小さくして、読む順を名前から先にする */
+  const 名前の字 = 14;
+  const 補足の字 = 10.5;
+
   const 段 = stages.map((s, idx) => {
     const prev = idx > 0 ? stages[idx - 1]! : null;
     // 前段が 0 件なら離脱率は決まらない (0 で割ることになる)。 静止画では起きなかったが、
@@ -82,6 +87,34 @@ export function FunnelNode({
     const points = `${topX},${y} ${topX + topW},${y} ${bottomX + bottomW},${y + stageH} ${bottomX},${y + stageH}`;
     const tone = toneByIndex(idx);
     const legendX = PAD_LEFT + canvasW + 24;
+
+    /*
+      補足を段の中に置く (#931)。 書いた補足が 1 文字も描かれていなかった。
+
+      収まる幅は **その段の下辺** で測る。 段は下へ向かって狭まるため、上辺で測ると
+      下辺より広い補足が台形の外へ出る。 左右に 8 ずつ空けて辺に触れないようにする。
+
+      縦は 2 行ぶんの高さが段に入るかで決める。 入らない時は両方を同じ倍率で縮める =
+      片方だけ縮めると名前と補足の大小が入れ替わって読む順が崩れる。 落とさないのは
+      書いた値を消さないため (この Issue が直しているのがまさにその形)。
+
+      補足が無い段は 1 行のままにする。 位置の式を変えると、補足を書いていない図の
+      焼き付けた見た目が動く。
+    */
+    const 補足 = (s.subtitle ?? "").trim();
+    const 補足あり = 補足 !== "";
+    const 二行の高さ = 名前の字 * 1.2 + 補足の字 * 1.25;
+    const 縦倍 = 補足あり ? Math.min(1, Math.max(0, stageH - 8) / 二行の高さ) : 1;
+    const 名前の実字 = 名前の字 * 縦倍;
+    const 補足の枠字 = 補足の字 * 縦倍;
+    const 収まる幅 = Math.max(0, bottomW - 16);
+    const 補足の実字 =
+      補足の枠字 * 収める倍率(補足, { fontSize: 補足の枠字, fontWeight: 500 }, 収まる幅);
+    // 2 行の塊を段の中央に積む。 縦の位置は枠の字 (縮める前) で決める = 幅で縮めた分だけ
+    // 行が上下に動くと、段ごとに行の高さが揃わない
+    const 塊の上 = y + stageH / 2 - (名前の実字 * 1.2 + 補足の枠字 * 1.25) / 2;
+    const 名前のy = 補足あり ? 塊の上 + 名前の実字 * 0.95 : y + stageH / 2 + 5;
+    const 補足のy = 塊の上 + 名前の実字 * 1.2 + 補足の枠字 * 0.95;
     return (
       <g key={`stage-${s.id}`}>
         <polygon
@@ -95,14 +128,29 @@ export function FunnelNode({
         />
         <text
           x={cx}
-          y={y + stageH / 2 + 5}
-          fontSize={14}
+          y={名前のy}
+          fontSize={名前の実字}
           fontWeight={700}
           textAnchor="middle"
           fill="var(--cdl-node-fill, #ffffff)"
         >
           {s.title}
         </text>
+        {補足あり && (
+          <text
+            data-cdl-role="funnel-stage-subtitle"
+            x={cx}
+            y={補足のy}
+            fontSize={補足の実字}
+            fontWeight={500}
+            letterSpacing={0}
+            textAnchor="middle"
+            fill="var(--cdl-node-fill, #ffffff)"
+            fillOpacity={0.82}
+          >
+            {補足}
+          </text>
+        )}
         {/* 件数と離脱率は段が出切ってから。 切り抜きだけでは途中から見えるため自分で判定する */}
         {段が出切った(idx) && (
           <text