@cardenelabs/cdl 0.40.6 → 0.40.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cardenelabs/cdl",
-  "version": "0.40.6",
+  "version": "0.40.8",
   "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/axis-ticks.ts

@@ -0,0 +1,32 @@
+/**
+ * 目盛りの刻みを、人が読む数から選ぶ (cdl#751)。
+ *
+ * `1 / 2 / 2.5 / 5` に 10 の累乗を掛けた中から、目盛りが目安の本数前後になるものを取る。
+ * 範囲をそのまま本数で割ると `680 / 4 = 170` のような数が目盛りに出て、
+ * 機械が割った数字に見える。
+ *
+ * **棒と折れ線が同じ規則を持つのでここに 1 つだけ置く**。 図ごとに書くと、片方だけ直した
+ * 時に目盛りの出方がずれる (実際に棒を直した cdl#747 で 2 箇所になった)。
+ * 図どうしに上下関係を作らないため、どちらの図でもない場所に置く。
+ *
+ * **天井と床の決め方はここに持たない**。 折れ線は床も動かし、棒は床が必ず 0 で、
+ * 規則が違う。 共有するのは刻みの選び方だけ。
+ */
+
+/**
+ * 刻みを 1 つ選ぶ。
+ *
+ * @param 範囲 縦軸が受け持つ幅。 折れ線は `最大 - 最小`、棒は最小が 0 なので `最大`
+ * @param 目安の本数 目盛りを何本くらい引きたいか
+ * @returns 刻み。 **範囲か本数が 0 以下なら 0 を返す** = 刻みを決められないことを
+ *   0 で表し、呼ぶ側がその図に合った逃げ方を選ぶ (`rules/quality.md` の
+ *   「判定できなかったことを値に潰さない」 に合わせ、勝手に 1 を返さない)
+ */
+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 候補 * 桁;
+}

package/src/kinds/chart-bar.tsx

@@ -2,10 +2,36 @@ import type { JSX } from "react";
 import type { LaidNode } from "../types";
 import { resolveChartData } from "../render/payload-binding";
 import { 進みを畳む } from "./draw-progress";
+import { 目盛りの刻み } from "./axis-ticks";
+
+/**
+ * その数を書き切るのに要る小数の桁数。
+ *
+ * `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(指数)));
+}
+
+/**
+ * 字の大きさ (cdl#753)。
+ *
+ * **値札を軸の名前より大きくする** = 値札は棒の上に載る数そのもので、
+ * 軸の名前は目盛りの側にある。 折れ線 (`chart-line.tsx`) と同じ組にしてある。
+ * 2 図で揃っていることは検査が実物から読んで確かめる (`chart-label-rank.test.tsx`)。
+ */
+const 値札の級 = 12;
+const 軸の名前の級 = 11;
+
+/** 刻みの倍数を足し込んだ時に出る誤差 (`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 +58,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 +67,56 @@ 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;
+  // 棒は床が必ず 0 なので、範囲 = 天井のもと
+  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 +148,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 +172,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 +188,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 +203,23 @@ export function ChartBarNode({
             ) : (
               棒
             )}
+            {/* 値のほうが読ませたい数。 横軸の名前より大きく太くする (cdl#747) */}
             <text
+              data-cdl-role="chart-bar-value"
               x={bx + barW / 2}
-              y={見えている頭 - 6}
-              fontSize={11}
+              y={見えている頭 - 8}
+              fontSize={値札の級}
+              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={軸の名前の級}
               textAnchor="middle"
               fill="var(--cdl-text-dim, #5a6270)"
             >

package/src/kinds/chart-line.tsx

@@ -2,9 +2,24 @@ import type { JSX } from "react";
 import type { LaidNode } from "../types";
 import { resolveChartData } from "../render/payload-binding";
 import { 進みを畳む, 伸ばすdash } from "./draw-progress";
+import { 目盛りの刻み } from "./axis-ticks";
 
 export type ChartLineScale = { min: number; max: number; ticks: number[] };
 
+/** 縦軸に引きたい目盛りの本数の目安 */
+const 目盛りの目安 = 4;
+
+/**
+ * 字の大きさ (cdl#753)。
+ *
+ * **値札を軸の名前より大きくする** = 値札は印の上に載る数そのもので、
+ * 軸の名前は目盛りの側にある。 棒グラフ (`chart-bar.tsx`) と同じ組にしてある。
+ * 凡例を持つ図 (半円ゲージ / 同心の弧 / 100 個の印 / 内訳の帯) は
+ * 名前が行を見分ける鍵になるので逆の順で、そちらは揃えない。
+ */
+const 値札の級 = 12;
+const 軸の名前の級 = 11;
+
 const 数を書く = (value: number): string =>
   value.toLocaleString("en-US", { maximumFractionDigits: 12 });
 
@@ -17,14 +32,13 @@ export function 折れ線の目盛(values: readonly number[]): ChartLineScale {
     rawMax += room;
   }
 
-  const roughStep = (rawMax - rawMin) / 4;
-  const power = 10 ** Math.floor(Math.log10(roughStep));
-  const fraction = roughStep / power;
-  const niceFraction =
-    fraction <= 1 ? 1 : fraction <= 2 ? 2 : fraction <= 2.5 ? 2.5 : fraction <= 5 ? 5 : 10;
-  const step = niceFraction * power;
+  // 折れ線は床も動かすので、範囲 = 最大 - 最小。 直前の広げ方で必ず正になる
+  const step = 目盛りの刻み(rawMax - rawMin, 目盛りの目安);
   const min = Math.floor(rawMin / step) * step;
   const max = Math.ceil(rawMax / step) * step;
+  // 刻みが決まらない入力 (値が数でない) では `tickCount` が数にならず、
+  // 目盛りは空になる。 **この空を守りの分岐で作らない** = 同じものを 2 通りで作ると、
+  // 片方を外しても検査が落ちず、要るのか要らないのか判らなくなる (cdl#751 の変異試験で実測)
   const tickCount = Math.round((max - min) / step);
   const ticks = Array.from({ length: tickCount + 1 }, (_, i) => {
     const value = min + step * i;
@@ -165,6 +179,7 @@ export function ChartLineNode({
             opacity={0.65}
           />
           <text
+            data-cdl-role="chart-line-tick"
             x={PAD_LEFT - 8}
             y={t.y + 4}
             fontSize={11}
@@ -254,7 +269,7 @@ export function ChartLineNode({
               data-cdl-role="chart-line-value"
               x={cx}
               y={labelY}
-              fontSize={11}
+              fontSize={値札の級}
               fontWeight={600}
               textAnchor="middle"
               fill="var(--cdl-text, #1a1f2a)"
@@ -309,9 +324,10 @@ export function ChartLineNode({
           <g key={`pt-${idx}`} data-cdl-unresolved={d.unresolved ? "true" : undefined}>
             {点と値}
             <text
+              data-cdl-role="chart-line-label"
               x={cx}
               y={PAD_TOP + canvasH + 20}
-              fontSize={12}
+              fontSize={軸の名前の級}
               textAnchor="middle"
               fill="var(--cdl-text-dim, #5a6270)"
             >