@cardenelabs/cdl 0.31.1 → 0.33.0

package/src/kinds/chart-slope.tsx

@@ -0,0 +1,323 @@
+import { type JSX } from "react";
+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 { 進みを畳む, 伸ばすdash } from "./draw-progress";
+
+/**
+ * chart-slope kind ... 2 時点を 1 本の直線でつなぎ、増減と順位の入れ替わりを見せる図 (cdl#688)。
+ *
+ * ## 何のための種別か
+ *
+ * 2 時点を並べる図は既に 2 つあるが、どちらもこの読み方を持たない。
+ *
+ * | 種別 | 見せるもの | 足りないもの |
+ * |---|---|---|
+ * | `chart-stacked-bar` (cdl#551) | 2 時点の構成比 | 全体を 100% に正規化するので、全体が伸びた / 縮んだが消える |
+ * | `chart-line` (cdl#513) | 3 点以上の推移 | 横軸が datum の並びなので 1 node = 1 本になり、系列ごとに 1 本にならない |
+ *
+ * 左右に縦軸を置いて系列ごとに 2 点を直線で結ぶと、3 つが同時に読める。
+ * 線の向きが増減、線の傾きが動いた量、線の交差が順位の入れ替わり。
+ *
+ * ## 前の時点は datum の `previous` で持つ
+ *
+ * `chart-stacked-bar` と同じ欄をそのまま読む。 新しい欄は足さない。
+ *
+ * **1 件も持たない図は線を引かない**。 2 点が無いと傾きが定義できないので、軸 1 本に点を
+ * 並べた形で出す。 持たない件だけを 0 として立ち上げるのは、他の件が前を持つ図に限る =
+ * その図では「前は無かった」 が読みとして成立する (`chart-stacked-bar` の扱いと揃える)。
+ *
+ * ## 尺は 0 に固定しない
+ *
+ * 近い値どうしの差を傾きで読ませる図なので、0 まで伸ばすと線が全部水平に潰れる。
+ * 両時点の全値の最小と最大から取る。 全部同じ値の図では縦の中央に置く (0 で割らない)。
+ *
+ * ## 名札は値を軸側に置く
+ *
+ * 左は 名前 → 値、右は 値 → 名前 の順で軸から外へ並べる。 値を軸に近い側へ置くと、
+ * 左右とも値の列が縦に揃って読み比べられる。
+ */
+
+/** 線を引くのに最低限要る横幅。 名札が長い図でもこれだけは残す */
+export const 線の最小幅 = 120;
+
+type 系列 = {
+  名前: string;
+  前: number;
+  今: number;
+  色: string;
+  未解決: boolean;
+};
+
+export function ChartSlopeNode({
+  node,
+  active,
+  stateValues = {},
+  drawing = false,
+  progress = 1,
+}: {
+  node: LaidNode;
+  active: boolean;
+  stateValues?: Record<string, string>;
+  /** 段の `draw` にこの node が載っている間だけ true */
+  drawing?: boolean;
+  progress?: number;
+}): JSX.Element {
+  const x0 = node.cx - node.w / 2;
+  const y0 = node.cy - node.h / 2;
+  const data = resolveChartData(node.chartData ?? [], stateValues);
+
+  const PAD = 24;
+  const 時点の級 = 12;
+  const 値の級 = 14;
+  const 名前の上限級 = 13;
+  const 名前の下限級 = 9;
+  const 軸から値まで = 10;
+  const 値から名前まで = 8;
+
+  const 前あり = data.some((d) => d.previous !== undefined);
+  const 系列たち: 系列[] = data.map((d, i) => ({
+    名前: d.label ?? "",
+    // 前を持たない件は 0 から立ち上げる。 件を落とすと左右で系列の数が変わり、色の並びが
+    // 対応しなくなる (`chart-stacked-bar` と同じ判断)
+    前: d.previous ?? 0,
+    今: d.value,
+    色: 印の色(d.tone, i),
+    未解決: d.unresolved === true,
+  }));
+
+  const 全部の値 = 前あり
+    ? 系列たち.flatMap((s) => [s.前, s.今])
+    : 系列たち.map((s) => s.今);
+  const 最小 = 全部の値.length > 0 ? Math.min(...全部の値) : 0;
+  const 最大 = 全部の値.length > 0 ? Math.max(...全部の値) : 0;
+  const 尺の幅 = 最大 - 最小;
+
+  const 上端 = PAD + (前あり ? 時点の級 + 12 : 0) + 6;
+  const 下端 = Math.max(上端 + 10, node.h - PAD - 6);
+  const yを取る = (v: number): number =>
+    尺の幅 > 0 ? 下端 - ((v - 最小) / 尺の幅) * (下端 - 上端) : (上端 + 下端) / 2;
+
+  const 左の字 = 系列たち.map((s) => 実値表記(s.前));
+  const 右の字 = 系列たち.map((s) => 実値表記(s.今));
+  const 左値幅 = Math.max(0, ...左の字.map((t) => textWidth(t, 値の級)));
+  const 右値幅 = Math.max(0, ...右の字.map((t) => textWidth(t, 値の級)));
+
+  /** 名札に回せる横幅。 線の幅を先に取り分けてから、残りを左右へ半分ずつ配る */
+  const 名前に使える = Math.max(
+    0,
+    (node.w -
+      PAD * 2 -
+      線の最小幅 -
+      (左値幅 + 軸から値まで + 値から名前まで) -
+      (右値幅 + 軸から値まで + 値から名前まで)) /
+      2,
+  );
+  const 名前の級 = 収める級(系列たち.map((s) => s.名前), 名前に使える, 名前の上限級, 名前の下限級);
+  const 名前幅 = Math.min(
+    名前に使える,
+    Math.max(0, ...系列たち.map((s) => textWidth(s.名前, 名前の級))),
+  );
+
+  const 左の余白 = 名前幅 + 値から名前まで + 左値幅 + 軸から値まで;
+  const 右の余白 = 軸から値まで + 右値幅 + 値から名前まで + 名前幅;
+
+  /**
+   * 軸の位置。 名札が長い図では余白の言い値どおりに置くと軸が交差するため、
+   * **線の幅を先に確保してから** 内側へ寄せる。 箱の内側から出さないことを優先する。
+   */
+  const 左軸x = 前あり
+    ? Math.max(PAD, Math.min(PAD + 左の余白, node.w / 2 - 線の最小幅 / 2))
+    : Math.max(PAD, Math.min(node.w / 2, node.w - PAD));
+  const 右軸x = 前あり
+    ? Math.min(node.w - PAD, Math.max(node.w - PAD - 右の余白, node.w / 2 + 線の最小幅 / 2))
+    : 左軸x;
+
+  const 伸び = 進みを畳む(drawing, progress);
+  /** 右の点と右の名札は、線が届いてから出る */
+  const 右を出す = !drawing || 伸び >= 1;
+
+  return (
+    <g transform={`translate(${x0} ${y0})`}>
+      <rect
+        data-cdl-role="node-body"
+        x={0}
+        y={0}
+        width={node.w}
+        height={node.h}
+        rx={16}
+        fill="var(--cdl-node-fill, #ffffff)"
+        stroke={active ? "var(--cdl-tone-accent, #2d6a8f)" : "var(--cdl-divider, #d4d4d8)"}
+        strokeWidth={active ? 3 : 1.25}
+      />
+
+      {(前あり ? [左軸x, 右軸x] : [左軸x]).map((x, i) => (
+        <line
+          key={`axis-${i}`}
+          data-cdl-role="chart-slope-axis"
+          x1={x}
+          y1={上端 - 6}
+          x2={x}
+          y2={下端 + 6}
+          stroke="var(--cdl-divider, #d4d4d8)"
+          strokeWidth={1}
+        />
+      ))}
+
+      {/* 時点の名前。 軸が 1 本の図では描かない (比べる相手がいない) */}
+      {前あり && (
+        <>
+          <text
+            data-cdl-role="chart-slope-period"
+            x={左軸x}
+            y={PAD + 時点の級}
+            textAnchor="middle"
+            fontSize={時点の級}
+            fontWeight={700}
+            fill="var(--cdl-text-dim, #5a6270)"
+          >
+            前
+          </text>
+          <text
+            data-cdl-role="chart-slope-period"
+            x={右軸x}
+            y={PAD + 時点の級}
+            textAnchor="middle"
+            fontSize={時点の級}
+            fontWeight={700}
+            fill="var(--cdl-text-dim, #5a6270)"
+          >
+            今
+          </text>
+        </>
+      )}
+
+      {系列たち.map((s, i) => {
+        const 左y = yを取る(s.前);
+        const 右y = yを取る(s.今);
+        const 未解決 = s.未解決 ? "true" : undefined;
+        return (
+          <g key={`slope-${i}`}>
+            {前あり && (
+              <path
+                data-cdl-role="chart-slope-line"
+                data-cdl-unresolved={未解決}
+                d={`M ${左軸x} ${左y} L ${右軸x} ${右y}`}
+                fill="none"
+                stroke={s.色}
+                strokeWidth={2.5}
+                strokeLinecap="round"
+                {...伸ばすdash(drawing, 伸び)}
+              />
+            )}
+            {前あり && (
+              <circle
+                data-cdl-role="chart-slope-dot"
+                data-cdl-unresolved={未解決}
+                cx={左軸x}
+                cy={左y}
+                r={4}
+                fill={s.色}
+              />
+            )}
+            {右を出す && (
+              <circle
+                data-cdl-role="chart-slope-dot"
+                data-cdl-unresolved={未解決}
+                cx={右軸x}
+                cy={右y}
+                r={4}
+                fill={s.色}
+              />
+            )}
+
+            {/* 左の名札。 軸が 1 本の図では名前だけを左に置く */}
+            {前あり ? (
+              <>
+                <text
+                  data-cdl-role="chart-slope-label"
+                  x={左軸x - 軸から値まで}
+                  y={左y + 5}
+                  textAnchor="end"
+                  fontSize={値の級}
+                  fontWeight={600}
+                  fill="var(--cdl-text, #1a1f2a)"
+                >
+                  {左の字[i]}
+                </text>
+                <text
+                  data-cdl-role="chart-slope-label"
+                  x={左軸x - 軸から値まで - 左値幅 - 値から名前まで}
+                  y={左y + 5}
+                  textAnchor="end"
+                  fontSize={名前の級}
+                  fill="var(--cdl-text-dim, #5a6270)"
+                >
+                  {s.名前}
+                </text>
+              </>
+            ) : (
+              <text
+                data-cdl-role="chart-slope-label"
+                x={左軸x - 軸から値まで}
+                y={右y + 5}
+                textAnchor="end"
+                fontSize={名前の級}
+                fill="var(--cdl-text-dim, #5a6270)"
+              >
+                {s.名前}
+              </text>
+            )}
+
+            {右を出す && (
+              <>
+                <text
+                  data-cdl-role="chart-slope-label"
+                  x={右軸x + 軸から値まで}
+                  y={右y + 5}
+                  fontSize={値の級}
+                  fontWeight={600}
+                  fill="var(--cdl-text, #1a1f2a)"
+                >
+                  {右の字[i]}
+                </text>
+                {前あり && (
+                  <text
+                    data-cdl-role="chart-slope-label"
+                    x={右軸x + 軸から値まで + 右値幅 + 値から名前まで}
+                    y={右y + 5}
+                    fontSize={名前の級}
+                    fill="var(--cdl-text-dim, #5a6270)"
+                  >
+                    {s.名前}
+                  </text>
+                )}
+              </>
+            )}
+          </g>
+        );
+      })}
+    </g>
+  );
+}
+
+/** 印の色。 明示した色が優先され、無ければ図表の系列の色を順に配る */
+function 印の色(tone: Tone | undefined, idx: number): string {
+  if (tone) return TONE[tone];
+  return chartSeriesColor(idx);
+}
+
+/**
+ * 名前の字の大きさ。 **全部を同じ大きさに揃える** = 名前ごとに変えると列の見え方が乱れる。
+ *
+ * 最長の名前が枠に収まるまで 1 ずつ下げ、下限で止める。 下限でも収まらない図では
+ * 名札が枠から出るが、線と軸は箱の内側に残る。
+ */
+function 収める級(名前たち: readonly string[], 幅: number, 上限: number, 下限: number): number {
+  if (名前たち.length === 0) return 上限;
+  let 級 = 上限;
+  while (級 > 下限 && Math.max(...名前たち.map((n) => textWidth(n, 級))) > 幅) 級 -= 1;
+  return 級;
+}

package/src/layout/spec.ts

@@ -90,6 +90,7 @@ const KINDS_WITHOUT_TITLE_TEXT: ReadonlySet<string> = new Set([
   "chart-stat",
   "chart-waffle",
   "chart-stacked-bar",
+  "chart-slope",
   "gantt-timeline",
   "mind-map",
   "funnel-stages",

package/src/layout/tokens.ts

@@ -62,6 +62,8 @@ export const TOKENS = {
     "chart-waffle": { w: 640, h: 320 },
     // 帯を最大 2 本 + 下に一覧。 縦は帯 2 本ぶんで足りる (cdl#551)
     "chart-stacked-bar": { w: 640, h: 320 },
+    // 左右 2 本の縦軸と、その外に名札。 縦は系列が縦に並ぶぶん要る (cdl#688)
+    "chart-slope": { w: 640, h: 360 },
     // Timeline / Mind 系 (CAR-994 Phase B)
     "gantt-timeline": { w: 720, h: 360 },
     "mind-map": { w: 720, h: 480 },

package/src/presets.ts

@@ -2033,7 +2033,8 @@ export type ChartType =
   | "radial"
   | "stat"
   | "waffle"
-  | "stacked-bar";
+  | "stacked-bar"
+  | "slope";
 
 export type ChartDatum = {
   id: string;
@@ -2100,6 +2101,7 @@ export function chart(preset: ChartPreset): ChartBuilder {
     stat: "chart-stat" as const,
     waffle: "chart-waffle" as const,
     "stacked-bar": "chart-stacked-bar" as const,
+    slope: "chart-slope" as const,
   };
 
   const api: ChartBuilder = {

package/src/render/nodes.tsx

@@ -15,6 +15,7 @@ import { ChartRadialNode } from "../kinds/chart-radial";
 import { ChartStatNode } from "../kinds/chart-stat";
 import { ChartWaffleNode } from "../kinds/chart-waffle";
 import { ChartStackedBarNode } from "../kinds/chart-stacked-bar";
+import { ChartSlopeNode } from "../kinds/chart-slope";
 import { ChartBarNode } from "../kinds/chart-bar";
 import { GanttNode } from "../kinds/gantt";
 import { MindMapNode } from "../kinds/mind-map";
@@ -198,6 +199,17 @@ export function CdlNodeView({
       case "chart-stacked-bar":
         // 帯を割合で区切る。 前の時点を書けば 2 本になる (cdl#551)
         return <ChartStackedBarNode node={resolvedNode} active={active} stateValues={stateValues} />;
+      case "chart-slope":
+        // 2 時点を直線でつなぐ。 前の時点を書かない図は軸 1 本の点の並びになる (cdl#688)
+        return (
+          <ChartSlopeNode
+            node={resolvedNode}
+            active={active}
+            stateValues={stateValues}
+            drawing={drawing}
+            progress={progress}
+          />
+        );
       case "chart-waffle":
         // 1 個 = 1% の印を 100 個。 段の進みで印が埋まる動きは別 Issue (cdl#552 で対象外)
         return <ChartWaffleNode node={resolvedNode} active={active} stateValues={stateValues} />;

package/src/render/template-fields.ts

@@ -56,6 +56,8 @@ type 読まない欄 =
   | "chartFillUnder"
   | "chartValueRise"
   | "chartTrace"
+  // 円グラフの見せ方 (#684)。 決まった値のどれかで、字を差し込む先が無い
+  | "chartPieForm"
   | "ganttData"
   | "ganttAxisMax"
   | "mindData"

package/src/types.ts

@@ -80,7 +80,8 @@ export const NODE_KINDS = [
   // chart-waffle は 100 個の印で割合を数えて確かめる形 (cdl#552)
   "chart-pie", "chart-line", "chart-bar", "chart-gauge", "chart-radial", "chart-stat",
   // chart-stacked-bar は帯を割合で区切り時点を並べる形 (cdl#551)
-  "chart-waffle", "chart-stacked-bar",
+  // chart-slope は 2 時点を直線でつなぎ増減と順位の入れ替わりを見せる形 (cdl#688)
+  "chart-waffle", "chart-stacked-bar", "chart-slope",
   // Timeline / Mind 系 (2、 CAR-994 Phase B) ... 1 node に payload 配列、 SVG geometry render
   "gantt-timeline", "mind-map",
   // Analytic 系 (4、 CAR-994 Phase C) ... 1 node に payload 配列、 SVG geometry render
@@ -469,6 +470,18 @@ export type CdlNode = {
   chartValueRise?: boolean;
   /** chart-line を描き切った後、粒で経路をなぞって点を順に出す */
   chartTrace?: boolean;
+  /**
+   * chart-pie の見せ方 (cdl#684)。 書かない図は `ring` と同じ。
+   *
+   * - `ring` ... 輪を扇に切り分け、外へ引き出し線を伸ばして名札を置く
+   * - `arcs` ... 系列ごとに 1 本の弧を置き、割合を角度ではなく弧の長さで読む
+   * - `table` ... 輪を左に寄せ、右に 名前 / 割合 / 実数 の 3 列の表を組む
+   *
+   * 型の外の値は `ring` として描く = 見せ方が決まらないより、既定の形が出る方がよい。
+   *
+   * `previous` (cdl#680) が効くのは `ring` だけ。 他の形は内側の輪を描かない。
+   */
+  chartPieForm?: ChartPieForm;
   /**
    * gantt-timeline 専用の task payload。 task 全件を 1 node に格納し、
    * kinds/gantt.tsx が縦軸 task lane + 横軸日付 rect bar で SVG 描画する。
@@ -525,6 +538,9 @@ export type BoundNumber = number | string;
 export type BoundEnum<T extends string> = T | (string & {});
 
 /** Chart 系 kind の 1 datum payload。 label + value + optional tone (color) */
+/** chart-pie の見せ方 (cdl#684)。 SSOT は `kinds/chart-pie.tsx` */
+export type ChartPieForm = "ring" | "arcs" | "table";
+
 export type ChartDatumPayload = {
   label: string;
   /** 棒 / 折れ線 / 扇の大きさ。 `{signal}` で状態に追随する */

package/src/validate.ts

@@ -17,6 +17,7 @@ const TONES = new Set<string>(TONE_NAMES);
  * | `chart-line` | 左端 | 線が右へ伸びる |
  * | `chart-bar` | 横軸 | 棒が上へ伸びる |
  * | `chart-pie` | 12 時 | 扇が時計回りに開く |
+ * | `chart-slope` | 左の軸 | 線が右の軸へ伸びる |
  * | `journey-map` | 左端 | 気持ちの線が右へ伸びる |
  * | `mind-map` | 中心 | 枝が中心から外へ伸びる |
  * | `tree-hierarchy` | 根 | 枝が上の段から下の段へ伸びる |
@@ -27,6 +28,7 @@ export const DRAW_KINDS: ReadonlySet<string> = new Set([
   "chart-line",
   "chart-bar",
   "chart-pie",
+  "chart-slope",
   "journey-map",
   "mind-map",
   "tree-hierarchy",

package/src/visual-validate.ts

@@ -246,6 +246,7 @@ export const GRID_ALIGNED_KINDS: ReadonlySet<NodeKind> = new Set([
   "chart-stat",
   "chart-waffle",
   "chart-stacked-bar",
+  "chart-slope",
   "funnel-stages",
   "quadrant-matrix",
 ]);