@cardenelabs/cdl 0.7.0 → 0.10.0

package/dist/{render-DquCvgOB.d.cts → render-CH1Qn3Jv.d.cts}

@@ -148,6 +148,17 @@ type CdlNode = {
      */
     posW?: number;
     posH?: number;
+    /**
+     * 図の中での役割。 位置ではなく **組み立てた側が付ける目印** で、 描画側の分岐に使う。
+     *
+     * `lifeline-footer` = 順序図で lane の末尾に置く下端の名札 (`presets.ts` の `build()` が付ける)。
+     * 一部の `shape-` は絵を箱の下端から上へ積むため、 箱が低いと絵が縦線と重なる。 その回避で
+     * 絵を下げる対象がこの名札に限られる。
+     *
+     * **位置で推測してはいけない** = 手で組んだ図で一番下が名札でない `shape-` の node だと、
+     * その絵が下がってしまう (`#458`)。
+     */
+    role?: "lifeline-footer";
     /**
      * node の主色。 未指定なら kind ごとの既定色。
      *
@@ -208,6 +219,19 @@ type CdlNode = {
      * kinds/gantt.tsx が縦軸 task lane + 横軸日付 rect bar で SVG 描画する。
      */
     ganttData?: GanttTaskPayload[];
+    /**
+     * gantt-timeline の横軸を何目盛り分にするか (`#483`)。
+     *
+     * 書かない図では今までどおり全 task の最大値から自動で決まる。 書くと尺がその値で固定され、
+     * 状態で動く task があっても他の task の帯の位置と幅が変わらない。
+     *
+     * 位置は 0 から `ganttAxisMax - 1` までで、 そこから外れる task の帯は右端の目盛りに寄せて
+     * 描く (図の外へ出さない、 `kinds/gantt.tsx` SSOT)。
+     *
+     * 有限の正の数でなければ書かなかったものとして扱う = 尺が壊れて帯が図の外へ出るより、
+     * 自動に落ちる方が読める図になる。
+     */
+    ganttAxisMax?: number;
     /**
      * mind-map 専用の branch payload。 tree 構造を 1 node に格納し、
      * kinds/mind-map.tsx が中心 + 放射で SVG 描画する。
@@ -315,13 +339,20 @@ type QuadrantItemPayload = {
     quadrant: BoundEnum<QuadrantKey>;
     subtitle?: string;
 };
-/** tree-hierarchy kind の 1 node payload */
+/**
+ * tree-hierarchy kind の 1 node payload。
+ *
+ * **上の小ラベル (`eyebrow`) は受けない** (#471)。 箱の高さは段の間隔から出ており
+ * (`Math.min(38, 間隔 * 0.7)`)、 名前と補足で 2 行を使うと 3 行目は入らない。 高さを広げると
+ * 段どうしが近づいて箱が重なる。 受け取って描かない欄は、 書き手から効いていないことが
+ * 読めないため置かない。
+ */
 type TreeNodePayload = {
     id: string;
     title: string;
     parent?: string;
+    /** 箱の 2 行目に出す補足 */
     subtitle?: string;
-    eyebrow?: string;
 };
 /** journey-map の気持ち 5 段階 */
 type JourneyEmotion = "delighted" | "happy" | "neutral" | "frustrated" | "angry";
@@ -2016,6 +2047,20 @@ type CdlPhase = {
     title: string;
     body: string;
     activate: string[];
+    /**
+     * この phase で「左の起点から描き始める」 node の id (cdl#512)。
+     *
+     * `activate` と同じ形で node id を並べる。 対象の node は phase の進み (0→1) に合わせて
+     * 描かれ、 進みが 1 に達した時点で全体が出る。 現在の対象は `chart-line` だけで、
+     * 折れ線が左端から右へ伸び、 点と値の数字は線の先が届いた時に現れる。
+     *
+     * **`activate` を兼ねさせない**。 1 箱で図全体を描く種別 (`chart-*` 等) では焦点が
+     * その箱に解決されるため、 連続する phase で光り続ける図が実在する。 「光っていたら
+     * 描く」 にすると、 値が動くだけの phase でも線を引き直すことになる。
+     *
+     * 書かない phase では従来どおり全長で描く (DOM に dash 属性も付かない)。
+     */
+    draw?: string[];
     /** 数値 state の線形補間 (write phase で 100→90 等) */
     tweens: Array<{
         stateId: string;

package/dist/{render-DquCvgOB.d.ts → render-CH1Qn3Jv.d.ts}

@@ -148,6 +148,17 @@ type CdlNode = {
      */
     posW?: number;
     posH?: number;
+    /**
+     * 図の中での役割。 位置ではなく **組み立てた側が付ける目印** で、 描画側の分岐に使う。
+     *
+     * `lifeline-footer` = 順序図で lane の末尾に置く下端の名札 (`presets.ts` の `build()` が付ける)。
+     * 一部の `shape-` は絵を箱の下端から上へ積むため、 箱が低いと絵が縦線と重なる。 その回避で
+     * 絵を下げる対象がこの名札に限られる。
+     *
+     * **位置で推測してはいけない** = 手で組んだ図で一番下が名札でない `shape-` の node だと、
+     * その絵が下がってしまう (`#458`)。
+     */
+    role?: "lifeline-footer";
     /**
      * node の主色。 未指定なら kind ごとの既定色。
      *
@@ -208,6 +219,19 @@ type CdlNode = {
      * kinds/gantt.tsx が縦軸 task lane + 横軸日付 rect bar で SVG 描画する。
      */
     ganttData?: GanttTaskPayload[];
+    /**
+     * gantt-timeline の横軸を何目盛り分にするか (`#483`)。
+     *
+     * 書かない図では今までどおり全 task の最大値から自動で決まる。 書くと尺がその値で固定され、
+     * 状態で動く task があっても他の task の帯の位置と幅が変わらない。
+     *
+     * 位置は 0 から `ganttAxisMax - 1` までで、 そこから外れる task の帯は右端の目盛りに寄せて
+     * 描く (図の外へ出さない、 `kinds/gantt.tsx` SSOT)。
+     *
+     * 有限の正の数でなければ書かなかったものとして扱う = 尺が壊れて帯が図の外へ出るより、
+     * 自動に落ちる方が読める図になる。
+     */
+    ganttAxisMax?: number;
     /**
      * mind-map 専用の branch payload。 tree 構造を 1 node に格納し、
      * kinds/mind-map.tsx が中心 + 放射で SVG 描画する。
@@ -315,13 +339,20 @@ type QuadrantItemPayload = {
     quadrant: BoundEnum<QuadrantKey>;
     subtitle?: string;
 };
-/** tree-hierarchy kind の 1 node payload */
+/**
+ * tree-hierarchy kind の 1 node payload。
+ *
+ * **上の小ラベル (`eyebrow`) は受けない** (#471)。 箱の高さは段の間隔から出ており
+ * (`Math.min(38, 間隔 * 0.7)`)、 名前と補足で 2 行を使うと 3 行目は入らない。 高さを広げると
+ * 段どうしが近づいて箱が重なる。 受け取って描かない欄は、 書き手から効いていないことが
+ * 読めないため置かない。
+ */
 type TreeNodePayload = {
     id: string;
     title: string;
     parent?: string;
+    /** 箱の 2 行目に出す補足 */
     subtitle?: string;
-    eyebrow?: string;
 };
 /** journey-map の気持ち 5 段階 */
 type JourneyEmotion = "delighted" | "happy" | "neutral" | "frustrated" | "angry";
@@ -2016,6 +2047,20 @@ type CdlPhase = {
     title: string;
     body: string;
     activate: string[];
+    /**
+     * この phase で「左の起点から描き始める」 node の id (cdl#512)。
+     *
+     * `activate` と同じ形で node id を並べる。 対象の node は phase の進み (0→1) に合わせて
+     * 描かれ、 進みが 1 に達した時点で全体が出る。 現在の対象は `chart-line` だけで、
+     * 折れ線が左端から右へ伸び、 点と値の数字は線の先が届いた時に現れる。
+     *
+     * **`activate` を兼ねさせない**。 1 箱で図全体を描く種別 (`chart-*` 等) では焦点が
+     * その箱に解決されるため、 連続する phase で光り続ける図が実在する。 「光っていたら
+     * 描く」 にすると、 値が動くだけの phase でも線を引き直すことになる。
+     *
+     * 書かない phase では従来どおり全長で描く (DOM に dash 属性も付かない)。
+     */
+    draw?: string[];
     /** 数値 state の線形補間 (write phase で 100→90 等) */
     tweens: Array<{
         stateId: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cardenelabs/cdl",
-  "version": "0.7.0",
+  "version": "0.10.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",
@@ -47,7 +47,8 @@
     "src",
     "examples",
     "README.md",
-    "SPEC.md"
+    "SPEC.md",
+    "CHANGELOG.md"
   ],
   "publishConfig": {
     "access": "public"
@@ -62,7 +63,9 @@
     "typecheck": "tsc --noEmit",
     "test": "cd ../.. && vitest run packages/cdl",
     "lint": "tsc --noEmit",
-    "prepublishOnly": "pnpm run typecheck && pnpm run build"
+    "prepublishOnly": "pnpm run typecheck && pnpm run build",
+    "prepack": "node scripts/prepack-check.mjs",
+    "postpack": "node scripts/prepack-check.mjs"
   },
   "peerDependencies": {
     "react": "^19.0.0",

package/src/builder.ts

@@ -1355,6 +1355,11 @@ export type InputChain = {
 
 export type PhaseBuilder = {
   activate: (...ids: string[]) => PhaseBuilder;
+  /**
+   * この phase で左の起点から描き始める node を指定する (cdl#512)。
+   * 対象は phase の進み (0→1) に合わせて描かれる。 現在の対象種別は `chart-line`。
+   */
+  draw: (...ids: string[]) => PhaseBuilder;
   /** 数値 state の線形補間 (write phase で 100→90 等) */
   tween: (stateId: string, from: number, to: number) => PhaseBuilder;
   /** 任意型 state を即時切替 (この phase 到達で value 上書き、 lerp なし) */
@@ -1364,6 +1369,7 @@ export type PhaseBuilder = {
 
 type PhaseAcc = {
   activate: string[];
+  draw: string[];
   tweens: Array<{ stateId: string; from: number; to: number }>;
   sets: Array<{ stateId: string; value: string | number }>;
   badge?: string;
@@ -1375,6 +1381,10 @@ function makePhaseBuilder(acc: PhaseAcc): PhaseBuilder {
       acc.activate.push(...ids);
       return api;
     },
+    draw(...ids) {
+      acc.draw.push(...ids);
+      return api;
+    },
     tween(stateId, from, to) {
       acc.tweens.push({ stateId, from, to });
       return api;
@@ -3690,7 +3700,7 @@ export function diagram(
       },
     },
     phase(phaseId, opts, build) {
-      const acc: PhaseAcc = { activate: [], tweens: [], sets: [] };
+      const acc: PhaseAcc = { activate: [], draw: [], tweens: [], sets: [] };
       build(makePhaseBuilder(acc));
       phases.push({
         id: phaseId,
@@ -3698,6 +3708,8 @@ export function diagram(
         title: opts.title,
         body: opts.body,
         activate: acc.activate,
+        // 空なら欄ごと置かない。 置くと `draw` を使わない図の JSON の形が変わる
+        ...(acc.draw.length > 0 ? { draw: acc.draw } : {}),
         tweens: acc.tweens,
         sets: acc.sets,
         badge: acc.badge,

package/src/kinds/box-lines.ts

@@ -0,0 +1,120 @@
+import { textWidth } from "./text-width";
+
+/**
+ * 箱の中に文字の行を積む (#471)。
+ *
+ * **JSX を持たない module に置く**。 木 (`tree.tsx`) と放射 (`mind-map.tsx`) の両方が使う。
+ * `text-width.ts` が同じ理由で分かれているのに合わせる。
+ *
+ * 箱の大きさは呼び出し側が決めた値をそのまま受ける = **積んだ結果で高さを変えない**。
+ * 木も放射も箱の高さが段の間隔から出ており (`Math.min(38, 間隔 * 0.7)`)、 高さを変えると
+ * 段どうしの間隔まで動いて既存の図の見た目が変わる。 入らない行は落とす方を採る。
+ */
+
+/**
+ * 1 行が字の大きさの何倍の高さを占めるか。
+ *
+ * 詰め気味にするのは、 箱の高さが 30 前後しかないため (放射の枝 = 30、 木 = 最大 38)。
+ * 読みやすさの目安である 1.4-1.5 を採ると 2 行が入らず、 補足が常に落ちる。
+ */
+const 行送りの比 = 1.15;
+
+/** 大文字の高さが字の大きさの何倍か (baseline を出すのに使う) */
+const 字の高さの比 = 0.72;
+
+/** 箱の上下に空ける余白 */
+const 上下の余白 = 2;
+
+/** 箱の左右に空ける余白 (片側) */
+const 左右の余白 = 8;
+
+export type 積む行 = {
+  役割: "title" | "subtitle";
+  text: string;
+  fontSize: number;
+};
+
+export type 積んだ行 = 積む行 & {
+  /** 箱の中心から見た baseline の上下のずれ */
+  dy: number;
+};
+
+/**
+ * 幅に収まるところまでで切り、 切った時は末尾に `…` を付ける。
+ *
+ * 字の幅は実測の見積り (`textWidth`) から出す。 SVG は描く前に実寸を返さないため、
+ * 描いてから測って縮める形は取れない。
+ *
+ * `測る` を差し替えられるのは、 等幅の書体を使う絵があるため (#469)。 等幅は字ごとの幅を
+ * 持たず字数で決まるので、 比例用の見積りを当てると実物とずれる。
+ */
+export function 幅で切る(
+  text: string,
+  fontSize: number,
+  使える幅: number,
+  測る: (s: string, size: number) => number = textWidth,
+): string {
+  if (使える幅 <= 0) return "";
+  if (測る(text, fontSize) <= 使える幅) return text;
+
+  const 省略 = "…";
+  const 省略の幅 = 測る(省略, fontSize);
+  // 省略記号すら入らない幅では何も返さない。 返すと「幅に収まる文字を返す」 という約束を
+  // 破り、 箱から出る (深い放射や葉の多い木で内側の幅が極小になった時に起きる)
+  if (省略の幅 > 使える幅) return "";
+
+  let 出 = "";
+  let 幅 = 0;
+  for (const c of 書記素に分ける(text)) {
+    const 字の幅 = 測る(c, fontSize);
+    if (幅 + 字の幅 + 省略の幅 > 使える幅) break;
+    幅 += 字の幅;
+    出 += c;
+  }
+  return `${出}${省略}`;
+}
+
+/**
+ * 見た目の 1 字 (書記素クラスタ) に分ける。
+ *
+ * `for...of` は符号位置で回るため、 濁点や結合文字の付いた字と、 ZWJ で繋いだ絵文字を
+ * **途中で切る** (実測 = `é` が `e` だけになり、 `👩‍💻` が `👩‍` になった)。 幅の見積り
+ * (`textWidth`) も符号位置で足すので数は合うが、 見た目の 1 字が壊れる。
+ *
+ * `Intl.Segmenter` を持たない環境では符号位置に落ちる。 切り方が粗くなるだけで、 幅の
+ * 見積りとは食い違わない。
+ */
+function 書記素に分ける(text: string): string[] {
+  const 区切り = (Intl as { Segmenter?: new (l?: string, o?: { granularity: string }) => { segment: (s: string) => Iterable<{ segment: string }> } }).Segmenter;
+  if (typeof 区切り !== "function") return [...text];
+  return [...new 区切り(undefined, { granularity: "grapheme" }).segment(text)].map((g) => g.segment);
+}
+
+/**
+ * 箱に入る行だけを選び、 それぞれの baseline を返す。
+ *
+ * 先頭 (名前) は必ず残す。 入り切らない時は **後ろから落とす** = 補足より名前を優先する。
+ * 2 件目以降の空文字は行として数えない (補足を渡していない時に空行が空くのを避ける)。
+ *
+ * 返す `dy` は箱の中心から見たずれで、 行の塊を上下の中央に置いた時の baseline になる。
+ */
+export function 箱に積む(行: 積む行[], 箱の幅: number, 箱の高さ: number): 積んだ行[] {
+  const 候補 = 行.filter((r, i) => i === 0 || r.text.trim() !== "");
+  if (候補.length === 0) return [];
+
+  const 使える高さ = 箱の高さ - 上下の余白 * 2;
+  const 高さ = (rs: 積む行[]): number => rs.reduce((a, r) => a + r.fontSize * 行送りの比, 0);
+
+  // 入るまで後ろから落とす。 先頭は落とさない
+  const 残す = [...候補];
+  while (残す.length > 1 && 高さ(残す) > 使える高さ) 残す.pop();
+
+  const 使える幅 = 箱の幅 - 左右の余白 * 2;
+  const 総高 = 高さ(残す);
+  let 積み = -総高 / 2;
+  return 残す.map((r) => {
+    const dy = 積み + ((行送りの比 + 字の高さの比) / 2) * r.fontSize;
+    積み += r.fontSize * 行送りの比;
+    return { ...r, text: 幅で切る(r.text, r.fontSize, 使える幅), dy };
+  });
+}

package/src/kinds/chart-line.tsx

@@ -7,15 +7,29 @@ import { resolveChartData } from "../render/payload-binding";
  * layout は node bbox (node.w × node.h) 内側に padding (top/right/bottom/left) を確保し、
  * その内側 rect を chart canvas とみなす。 縦軸 = value min-max、 横軸 = datum index。
  * 各 value は数でも `{signal}` でもよく、 後者は状態が動くたび折れ線が追随する。
+ *
+ * phase の `draw` にこの node の id が載っている間は、 折れ線が左の起点から伸びる (cdl#512)。
+ * 伸ばし方は dash (`pathLength` / `strokeDasharray` / `strokeDashoffset`) で、 `points` は
+ * 進みに関わらず全点を持つ。 点と値の数字は線の先が自分の位置に届いた時に現れ、
+ * 軸 / 格子 / 横軸の名前は最初から出る。
  */
 export function ChartLineNode({
   node,
   active,
   stateValues = {},
+  drawing = false,
+  progress = 1,
 }: {
   node: LaidNode;
   active: boolean;
   stateValues?: Record<string, string>;
+  /**
+   * この phase の `draw` に載っているか (cdl#512)。 true の間だけ折れ線が左の起点から
+   * 伸び、 点と値の数字は線の先が自分の位置に届いた時に現れる。
+   */
+  drawing?: boolean;
+  /** phase の進み (0→1)。 `drawing` が true の時だけ読む */
+  progress?: number;
 }): JSX.Element {
   const x0 = node.cx - node.w / 2;
   const y0 = node.cy - node.h / 2;
@@ -45,6 +59,44 @@ export function ChartLineNode({
 
   const points = data.map((d, idx) => `${xAt(idx)},${yAt(d.value)}`).join(" ");
 
+  // dash は polyline の実際の経路長で進むため、 点の表示判定も同じ経路長に揃える。
+  // 点番号の比率では、 急傾斜と平坦な区間が混ざる線で先端と点がずれる。
+  const 点までの長さ: number[] = [];
+  let 線の全長 = 0;
+  let 前の点: { x: number; y: number } | undefined;
+  for (const [idx, datum] of data.entries()) {
+    const 今の点 = { x: xAt(idx), y: yAt(datum.value) };
+    if (前の点) {
+      線の全長 += Math.hypot(今の点.x - 前の点.x, 今の点.y - 前の点.y);
+    }
+    点までの長さ.push(線の全長);
+    前の点 = 今の点;
+  }
+
+  /**
+   * 線がどこまで伸びたか (0..1、 cdl#512)。 描く指定が無ければ常に 1 = 全長。
+   *
+   * 進みは呼出側から来る値なので、 範囲の外 (負 / 1 超 / NaN) が入りうる。 そのまま
+   * `strokeDashoffset` に渡すと線が消えたり逆向きに縮んだりするため、 ここで畳む。
+   */
+  const 伸び = drawing ? Math.min(1, Math.max(0, Number.isFinite(progress) ? progress : 1)) : 1;
+
+  /**
+   * その点まで線の先が届いたか。
+   *
+   * 点の位置は polyline の累積経路長で判定する。 **左端は進み 0 でも出す** = そこが
+   * 線の起点で、 起点が無いと線がどこから伸びているのか読めない。
+   *
+   * 点が 1 つの図では線を引かない (下の `data.length > 1`) ため、 割り算の分母が 0 に
+   * なる形には入らないが、 呼出の順に依らず成り立つよう先に返す。
+   */
+  const 線の先が届いた = (idx: number): boolean => {
+    if (!drawing) return true;
+    if (data.length <= 1) return true;
+    if (線の全長 === 0) return true;
+    return 伸び >= (点までの長さ[idx] ?? 0) / 線の全長;
+  };
+
   const gridCount = 4;
   const gridTicks = Array.from({ length: gridCount + 1 }, (_, i) => {
     const v = vMin + (vRange * i) / gridCount;
@@ -114,6 +166,16 @@ export function ChartLineNode({
           strokeWidth={2.5}
           strokeLinejoin="round"
           strokeLinecap="round"
+          // 伸ばすのは dash で行い、 **`points` は触らない** (cdl#512)。 点を削る形にすると
+          // 利用側が数えている点の数が進みの途中で変わる (dragon の `kind-geometry-check`)。
+          //
+          // `pathLength={1}` を置くのは、 実長を測るには DOM の ref が要り、 静的な書き出しでは
+          // 測れないため。 長さを 1 に正規化すれば進みをそのまま offset に使える。
+          //
+          // 描く指定が無い図には属性を 1 つも足さない = 既存の図の DOM を変えない
+          {...(drawing
+            ? { pathLength: 1, strokeDasharray: 1, strokeDashoffset: 1 - 伸び }
+            : {})}
         />
       )}
       {data.map((d, idx) => {
@@ -129,33 +191,40 @@ export function ChartLineNode({
           (prev === undefined || d.value <= prev) && (next === undefined || d.value <= next);
         const labelAbove = !isValley;
         const labelY = labelAbove ? cy - 12 : cy + 18;
+        // 点と値の数字は線の先に合わせて現れる。 **横軸の名前は最初から出す** =
+        // 名前は図の枠 (軸 / 格子) の側で、 これが順に増えると軸そのものが伸びて見える
+        const 出す = 線の先が届いた(idx);
         return (
           <g key={`pt-${idx}`} data-cdl-unresolved={d.unresolved ? "true" : undefined}>
-            <circle
-              cx={cx}
-              cy={cy}
-              r={5}
-              fill="var(--cdl-node-fill, #ffffff)"
-              stroke="var(--cdl-tone-accent, #2d6a8f)"
-              strokeWidth={2.5}
-            />
-            <circle
-              cx={cx}
-              cy={cy}
-              r={2.5}
-              fill="var(--cdl-tone-accent, #2d6a8f)"
-            />
-            <text
-              data-cdl-role="chart-line-value"
-              x={cx}
-              y={labelY}
-              fontSize={11}
-              fontWeight={600}
-              textAnchor="middle"
-              fill="var(--cdl-text, #1a1f2a)"
-            >
-              {d.value.toLocaleString()}
-            </text>
+            {出す && (
+              <>
+                <circle
+                  cx={cx}
+                  cy={cy}
+                  r={5}
+                  fill="var(--cdl-node-fill, #ffffff)"
+                  stroke="var(--cdl-tone-accent, #2d6a8f)"
+                  strokeWidth={2.5}
+                />
+                <circle
+                  cx={cx}
+                  cy={cy}
+                  r={2.5}
+                  fill="var(--cdl-tone-accent, #2d6a8f)"
+                />
+                <text
+                  data-cdl-role="chart-line-value"
+                  x={cx}
+                  y={labelY}
+                  fontSize={11}
+                  fontWeight={600}
+                  textAnchor="middle"
+                  fill="var(--cdl-text, #1a1f2a)"
+                >
+                  {d.value.toLocaleString()}
+                </text>
+              </>
+            )}
             <text
               x={cx}
               y={PAD_TOP + canvasH + 20}