@cardenelabs/cdl 0.40.5 → 0.40.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cardenelabs/cdl",
-  "version": "0.40.5",
+  "version": "0.40.7",
   "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-bar.tsx

@@ -3,9 +3,41 @@ import type { LaidNode } from "../types";
 import { resolveChartData } from "../render/payload-binding";
 import { 進みを畳む } from "./draw-progress";
 
+/**
+ * 目盛りの刻みを、人が読む数から選ぶ (cdl#747)。
+ *
+ * `1 / 2 / 2.5 / 5` に 10 の累乗を掛けた中から、目盛りが目安の本数前後になるものを取る。
+ * 最大値をそのまま割ると `680 / 4 = 170` のような数が目盛りに出て、機械が割った数字に見える。
+ *
+ * 最大が 0 以下の図では刻みを決められないので 0 を返す (呼ぶ側が今までの割り方に落ちる)。
+ */
+export function 目盛りの刻み(最大: number, 目安の本数: number): number {
+  if (!(最大 > 0) || !(目安の本数 > 0)) return 0;
+  const 粗い = 最大 / 目安の本数;
+  const 桁 = 10 ** Math.floor(Math.log10(粗い));
+  const 正規 = 粗い / 桁;
+  const 候補 = 正規 <= 1 ? 1 : 正規 <= 2 ? 2 : 正規 <= 2.5 ? 2.5 : 正規 <= 5 ? 5 : 10;
+  return 候補 * 桁;
+}
+
+/**
+ * その数を書き切るのに要る小数の桁数。
+ *
+ * `String(0.0000025)` は指数の形になり `indexOf(".")` では数えられないため、
+ * 仮数と指数に分けて数える (`2.5e-7` = 仮数の小数 1 桁 - 指数 -7 = 8 桁)。
+ */
+function 小数の桁(n: number): number {
+  const [仮数, 指数] = n.toExponential().split("e");
+  const 小数部 = (仮数 ?? "").split(".")[1]?.length ?? 0;
+  return Math.min(20, Math.max(0, 小数部 - Number(指数)));
+}
+
+/** 刻みの倍数を足し込んだ時に出る誤差 (`0.1 * 3 = 0.30000000000000004`) を落とす */
+const 桁で丸める = (v: number, 桁: number): number => Number(v.toFixed(桁));
+
 /**
  * chart-bar kind ... 1 node に datum 配列 (chartData) を保持し、 SVG rect で棒グラフ描画する。
- * layout は node bbox 内側の canvas に縦棒を等間隔配置、 縦軸 = value 0-max、 横軸 = datum label。
+ * layout は node bbox 内側の canvas に縦棒を等間隔配置、 縦軸 = value 0-天井、 横軸 = datum label。
  * 各 value は数でも `{signal}` でもよく、 後者は状態が動くたび棒の高さが追随する。
  *
  * phase の `draw` にこの node の id が載っている間は、 棒が横軸から上へ伸びる (cdl#516)。
@@ -32,7 +64,8 @@ export function ChartBarNode({
   const y0 = node.cy - node.h / 2;
   const data = resolveChartData(node.chartData ?? [], stateValues);
 
-  const PAD_TOP = 20;
+  // 値札を枠に重ねない余白 (cdl#747)。 天井まで届いた棒の数字がここに収まる
+  const PAD_TOP = 34;
   const PAD_RIGHT = 24;
   const PAD_BOTTOM = 44;
   const PAD_LEFT = 60;
@@ -40,21 +73,55 @@ export function ChartBarNode({
   const canvasH = node.h - PAD_TOP - PAD_BOTTOM;
 
   const vMax = data.length > 0 ? Math.max(...data.map((d) => d.value)) : 1;
-  const vRange = vMax || 1;
 
-  const barGap = 10;
+  const 目盛りの目安 = 4;
+  /**
+   * 目盛りを引く元の高さ。 値が 0 以下しか無い図 (と値を読めない図) では 1 を使う =
+   * 最大値をそのまま使うと 0 が 5 つ並ぶ縦軸になり、何も読めない。
+   */
+  const 天井のもと = vMax > 0 ? vMax : 1;
+  const 刻み = 目盛りの刻み(天井のもと, 目盛りの目安);
+  const 刻みの桁 = 小数の桁(刻み);
+  /**
+   * 縦軸の天井。 **最大値をそのまま天井にしない** (cdl#747)。
+   * 刻みの倍数へ切り上げるので、目盛りが人の読む数になる。
+   *
+   * **天井を水増しして余白を作らない** = 最大 100 の図は `0 / 25 / 50 / 75 / 100` が
+   * 正しい形で、余白のために `125` へ伸ばすと目盛りが不自然になる。
+   * 値札が枠に重ならない余白は `PAD_TOP` が持つ。
+   */
+  const 天井 = 桁で丸める(Math.ceil(天井のもと / 刻み - 1e-9) * 刻み, 刻みの桁);
+
+  /** 棒 1 本に対する隙間の割合。 棒 : 隙間 = この比 (cdl#747) */
+  const 棒と隙間の比 = 2.2;
+  /** 棒の太さの上限。 本数が少ない図で棒が塀のように太るのを止める */
+  const 棒の上限 = 96;
   const barCount = data.length || 1;
-  const barW = (canvasW - barGap * (barCount + 1)) / barCount;
+  // 隙間 1 つ分を単位に、棒 barCount 本 + 隙間 (barCount + 1) 個で canvas を割る
+  const 単位 = canvasW / (barCount * 棒と隙間の比 + (barCount + 1));
+  const barW = Math.max(0, Math.min(単位 * 棒と隙間の比, 棒の上限));
+  // 上限で余った幅は隙間へ均等に配る = 棒の並びが片寄らない
+  const barGap = (canvasW - barW * barCount) / (barCount + 1);
 
-  const yAt = (v: number) => PAD_TOP + canvasH - (v / vRange) * canvasH;
+  const yAt = (v: number) => PAD_TOP + canvasH - (v / 天井) * canvasH;
   const xAt = (idx: number) => PAD_LEFT + barGap + idx * (barW + barGap);
 
-  const gridCount = 4;
-  const gridTicks = Array.from({ length: gridCount + 1 }, (_, i) => {
-    const v = (vMax * i) / gridCount;
+  const 目盛りの本数 = Math.round(天井 / 刻み);
+  const gridTicks = Array.from({ length: 目盛りの本数 + 1 }, (_, i) => {
+    const v = 桁で丸める(刻み * i, 刻みの桁);
     return { y: yAt(v), value: v };
   });
 
+  /**
+   * 棒の濃さ。 **いちばん大きい棒だけ濃く出す** (cdl#747)。
+   *
+   * 色は 1 つのまま濃さだけを変える = 棒グラフは同じ量どうしの比較で、色は量を表さない。
+   * 4 本に 4 色を配ると「色に意味がある」 と誤読する余地が残る。
+   */
+  const 濃さ = (v: number): number => (vMax > 0 ? (v >= vMax ? 1 : 0.45) : 0.9);
+  /** 角丸は棒の太さに合わせる。 太い棒に固定値を当てると直角に見える */
+  const 角丸 = Math.min(barW * 0.06, 8);
+
   /** 棒がどこまで伸びたか (0..1、 cdl#516)。 畳み方は `draw-progress.ts` が持つ */
   const 伸び = 進みを畳む(drawing, progress);
   /** 棒の足元。 ここを動かさない点として上へ伸ばす */
@@ -86,13 +153,14 @@ export function ChartBarNode({
             opacity={0.65}
           />
           <text
+            data-cdl-role="chart-bar-tick"
             x={PAD_LEFT - 8}
             y={t.y + 4}
             fontSize={11}
             textAnchor="end"
             fill="var(--cdl-text-dim, #5a6270)"
           >
-            {Math.round(t.value)}
+            {t.value}
           </text>
         </g>
       ))}
@@ -109,7 +177,8 @@ export function ChartBarNode({
       {data.map((d, idx) => {
         const bx = xAt(idx);
         const by = yAt(d.value);
-        const bh = PAD_TOP + canvasH - by;
+        // 負の値は下へ伸ばす軸を持たないので足元で止める (`rect` に負の高さを書かない)
+        const bh = Math.max(0, PAD_TOP + canvasH - by);
         // 見えている棒の頭。 数字はここに付いて動く = 空いた場所に数字だけ浮かない
         const 見えている頭 = 横軸のy - (横軸のy - by) * 伸び;
         /**
@@ -124,9 +193,9 @@ export function ChartBarNode({
             y={by}
             width={barW}
             height={bh}
-            rx={2}
+            rx={角丸}
             fill="var(--cdl-tone-accent, #2d6a8f)"
-            fillOpacity={0.9}
+            fillOpacity={濃さ(d.value)}
           />
         );
         return (
@@ -139,19 +208,23 @@ export function ChartBarNode({
             ) : (
               棒
             )}
+            {/* 値のほうが読ませたい数。 横軸の名前より大きく太くする (cdl#747) */}
             <text
+              data-cdl-role="chart-bar-value"
               x={bx + barW / 2}
-              y={見えている頭 - 6}
-              fontSize={11}
+              y={見えている頭 - 8}
+              fontSize={12}
+              fontWeight={600}
               textAnchor="middle"
               fill="var(--cdl-text, #1a1f2a)"
             >
               {d.value.toLocaleString()}
             </text>
             <text
+              data-cdl-role="chart-bar-label"
               x={bx + barW / 2}
               y={PAD_TOP + canvasH + 18}
-              fontSize={12}
+              fontSize={11}
               textAnchor="middle"
               fill="var(--cdl-text-dim, #5a6270)"
             >

package/src/validate.ts

@@ -1,4 +1,4 @@
-import type { CdlDiagram } from "./types";
+import type { CdlDiagram, CdlNode } from "./types";
 import { TONES as TONE_NAMES, NODE_KINDS } from "./types";
 import { templateRefIds } from "./render/utils";
 import { nodeTemplateTexts } from "./render/template-fields";
@@ -46,6 +46,31 @@ export const DRAW_KINDS: ReadonlySet<string> = new Set([
 const KINDS = new Set<string>(NODE_KINDS);
 const ENG_BANNED = /\b(FUNCTION|STORAGE|EVENT LOG|BALANCES MAPPING|READ|WRITE|EMIT|CALL)\b/;
 
+/**
+ * 図表の荷 (payload) を持つ節の欄 (cdl#743)。
+ *
+ * これらの欄を持つ節は **その節自体が図** で、段が指し示す相手ではない。 記法にも図表の節を
+ * activate する書き方が無いため、「どの phase でも activate されていない」 は書き手に直せない。
+ *
+ * **種別の一覧を持たない** = 図表の種別は増える (実測で 15 種)。 一覧を手で書くと、種別を
+ * 足した時にここへの追記を忘れて警告が復活する。 荷の欄で判定すれば自動で追従する
+ * (`rules/quality.md § 導出可能記述は人手で書かない` の経路 1)。
+ */
+const 図表の荷の欄 = [
+  "chartData",
+  "ganttData",
+  "mindData",
+  "funnelData",
+  "quadrantData",
+  "treeData",
+  "journeyData",
+] as const satisfies readonly (keyof CdlNode)[];
+
+/** 図表の荷を 1 つでも持つか。 持つ節は「使われていない」 の判定から外す */
+function 図表の節(n: CdlNode): boolean {
+  return 図表の荷の欄.some((欄) => n[欄] !== undefined);
+}
+
 /**
  * cdl が compile される前に通る validator。
  * 構造的破綻 (重複 id / 不存在 id 参照 / 必須要素 0 件 等) は throw、
@@ -263,7 +288,7 @@ export function validate(diag: CdlDiagram): void {
     for (const id of p.activate) allActivated.add(id);
   }
   for (const n of diag.nodes) {
-    if (!allActivated.has(n.id)) {
+    if (!allActivated.has(n.id) && !図表の節(n)) {
       warnings.push(`node "${n.id}" がどの phase でも activate されていない (unused、 typo の可能性)`);
     }
   }