@cardenelabs/cdl 0.5.0 → 0.6.1

package/src/render/nodes.tsx

@@ -11,7 +11,6 @@ import { ChartPieNode } from "../kinds/chart-pie";
 import { ChartBarNode } from "../kinds/chart-bar";
 import { GanttNode } from "../kinds/gantt";
 import { MindMapNode } from "../kinds/mind-map";
-import { MindRadialNode } from "../kinds/mind-radial";
 import { FunnelNode } from "../kinds/funnel";
 import { QuadrantNode } from "../kinds/quadrant";
 import { TreeNode as TreeHierarchyNode } from "../kinds/tree";
@@ -80,7 +79,7 @@ import {
   ShapeCustomerServiceNode,
 } from "../kinds/shape-people";
 import type { LaidNode } from "../types";
-import { interpolate, resolveNumericAttr } from "./utils";
+import { hasUnresolvedRef, interpolate, resolveNumericAttr } from "./utils";
 
 export function CdlNodeView({
   node,
@@ -110,7 +109,9 @@ export function CdlNodeView({
   // (unresolved = `{missingSig}` そのままなら typo と判断、 fail-safe に hidden 側倒す)
   if (node.visibleIf) {
     const resolved = interpolate(node.visibleIf, stateValues).trim().toLowerCase();
-    const unresolved = /^\{\w+(?:[.\[][^}]*)?\}$/.test(resolved) || /\{\w+(?:[.\[][^}]*)?\}/.test(resolved);
+    // 判定は interpolate と同じ式を使う (`hasUnresolvedRef`)。 別に書くと字種がずれ、
+    // 置換されずに残った名前を未解決と見なせず fail-safe が素通りする
+    const unresolved = hasUnresolvedRef(resolved);
     const falsy = resolved === "" || resolved === "0" || resolved === "false" || resolved === "null" || resolved === "undefined" || resolved === "nan";
     if (falsy || unresolved) {
       return <g data-cdl-node={node.id} data-cdl-hidden="true" style={{ display: "none" }} />;
@@ -148,26 +149,27 @@ export function CdlNodeView({
         return <EventNode node={resolvedNode} active={active} progress={progress} />;
       case "card":
         return <CardNode node={resolvedNode} active={active} />;
+      // 図表 7 種は payload の数と語が `{signal}` を取れるので stateValues を渡す
+      // (`render/payload-binding.ts` が描画直前に解決する)。 動かさない 2 種
+      // (mind-map / tree-hierarchy) は構造だけを持つため渡さない。
       case "chart-line":
-        return <ChartLineNode node={resolvedNode} active={active} />;
+        return <ChartLineNode node={resolvedNode} active={active} stateValues={stateValues} />;
       case "chart-pie":
-        return <ChartPieNode node={resolvedNode} active={active} />;
+        return <ChartPieNode node={resolvedNode} active={active} stateValues={stateValues} />;
       case "chart-bar":
-        return <ChartBarNode node={resolvedNode} active={active} />;
+        return <ChartBarNode node={resolvedNode} active={active} stateValues={stateValues} />;
       case "gantt-timeline":
-        return <GanttNode node={resolvedNode} active={active} />;
+        return <GanttNode node={resolvedNode} active={active} stateValues={stateValues} />;
       case "mind-map":
         return <MindMapNode node={resolvedNode} active={active} />;
-      case "mind-radial":
-        return <MindRadialNode node={resolvedNode} active={active} />;
       case "funnel-stages":
-        return <FunnelNode node={resolvedNode} active={active} />;
+        return <FunnelNode node={resolvedNode} active={active} stateValues={stateValues} />;
       case "quadrant-matrix":
-        return <QuadrantNode node={resolvedNode} active={active} />;
+        return <QuadrantNode node={resolvedNode} active={active} stateValues={stateValues} />;
       case "tree-hierarchy":
         return <TreeHierarchyNode node={resolvedNode} active={active} />;
       case "journey-map":
-        return <UserJourneyNode node={resolvedNode} active={active} />;
+        return <UserJourneyNode node={resolvedNode} active={active} stateValues={stateValues} />;
       case "shape-file":
         return <ShapeFileNode node={resolvedNode} active={active} />;
       case "shape-folder":

package/src/render/payload-binding.ts

@@ -0,0 +1,196 @@
+import type {
+  BoundEnum,
+  BoundNumber,
+  ChartDatumPayload,
+  FunnelStagePayload,
+  GanttTaskPayload,
+  JourneyEmotion,
+  JourneyStepPayload,
+  QuadrantItemPayload,
+  QuadrantKey,
+  QuadrantPayload,
+} from "../types";
+import { interpolate } from "./utils";
+
+/**
+ * 図表 payload が状態を読むための解決層 (dragon#1161 段 3)。
+ *
+ * `chart-*` / `funnel-stages` / `gantt-timeline` / `quadrant-matrix` / `journey-map` の 5 系統は
+ * 配列 payload を受け取って一度描くだけで、 状態を読む経路が無かった。 各 kind は描画の直前に
+ * ここの resolver を 1 回呼び、 以降は今までどおり数と語を扱う。
+ *
+ * 解決できない欄の扱いは 1 つに揃えてある。 **項目を落とさず、 既定値で描いて印を付ける**。
+ * 落とすと配列の長さが変わって図の形が別物になり、 どこが壊れたのかが読み取れなくなる
+ * (spec § 4.2 が輪について同じ判断をしている = 1 箇所の壊れで図が消えると原因が分からない)。
+ * 印は各 kind が `data-cdl-unresolved="true"` として DOM に出す。
+ *
+ * 動かさない 2 種 (`mind-map` / `tree-hierarchy`) はここに resolver を持たない。
+ * 構造だけを持ち動かせる数が無く、 動かすとしたら項目の増減になるため (Issue の実装しない条件)。
+ */
+
+/** 解決の結果。 `ok` が false なら既定値に落ちたことを表す */
+export type BindingResult<T> = { value: T; ok: boolean };
+
+/** 解決できなかった欄を持つ項目に付く印。 kind 側が DOM 属性に写す */
+export type UnresolvedMark = { unresolved?: true };
+
+export type ResolvedChartDatum = Omit<ChartDatumPayload, "value"> & { value: number } & UnresolvedMark;
+export type ResolvedFunnelStage = Omit<FunnelStagePayload, "count"> & { count: number } & UnresolvedMark;
+export type ResolvedGanttTask = Omit<GanttTaskPayload, "startIdx" | "endIdx"> & {
+  startIdx: number;
+  endIdx: number;
+} & UnresolvedMark;
+export type ResolvedQuadrantItem = Omit<QuadrantItemPayload, "quadrant"> & {
+  quadrant: QuadrantKey;
+} & UnresolvedMark;
+export type ResolvedJourneyStep = Omit<JourneyStepPayload, "emotion"> & {
+  emotion: JourneyEmotion;
+} & UnresolvedMark;
+export type ResolvedQuadrantData = Omit<QuadrantPayload, "items"> & { items: ResolvedQuadrantItem[] };
+
+export const QUADRANT_KEYS: readonly QuadrantKey[] = [
+  "topLeft",
+  "topRight",
+  "bottomLeft",
+  "bottomRight",
+];
+
+export const JOURNEY_EMOTIONS: readonly JourneyEmotion[] = [
+  "delighted",
+  "happy",
+  "neutral",
+  "frustrated",
+  "angry",
+];
+
+/**
+ * 解決できない項目を置く象限。 4 つは対称なので既定値は本来どれでもよいが、 右上は
+ * 「重要かつ容易」 として読まれる場所なので、 壊れた項目をそこへ置くと図が嘘をつく。
+ * 最も読み違えにくい左下に固定する。
+ */
+const QUADRANT_FALLBACK: QuadrantKey = "bottomLeft";
+
+/** 解決できない段の気持ち。 5 段階の真ん中に置く */
+const EMOTION_FALLBACK: JourneyEmotion = "neutral";
+
+/**
+ * 数の欄を解決する。 数ならそのまま、 文字列なら `{signal}` を状態で埋めてから数として読む。
+ *
+ * 空文字を弾いてから数に直すのは `Number("")` が 0 を返すため。 弾かないと、 参照先が消えた欄が
+ * 「0 と書いてある欄」 と区別できなくなる。 直接書かれた数でも有限でなければ既定値に落とす
+ * (NaN を SVG に流すと path ごと描かれなくなり、 図が黙って消える)。
+ */
+export function resolveBoundNumber(
+  raw: BoundNumber,
+  values: Record<string, string>,
+  fallback: number,
+): BindingResult<number> {
+  if (typeof raw === "number") {
+    return Number.isFinite(raw) ? { value: raw, ok: true } : { value: fallback, ok: false };
+  }
+  const resolved = interpolate(raw, values).trim();
+  if (resolved === "") return { value: fallback, ok: false };
+  const parsed = Number(resolved);
+  return Number.isFinite(parsed) ? { value: parsed, ok: true } : { value: fallback, ok: false };
+}
+
+/**
+ * 語の欄を解決する。 `{signal}` を埋めた結果が決まった語のどれかなら採り、 違えば既定値に落とす。
+ *
+ * 数の欄と違い、 binding が無くても必ずここを通す。 型を `{signal}` も取れるように広げた分だけ
+ * 書き間違いが素通りするようになり、 素通りした語はどの分類にも一致せず項目が黙って消えるため。
+ * 既定値 + 印にすれば、 消えずに「解決できていない」 と読める。
+ */
+export function resolveBoundEnum<T extends string>(
+  raw: BoundEnum<T>,
+  values: Record<string, string>,
+  allowed: readonly T[],
+  fallback: T,
+): BindingResult<T> {
+  const resolved = interpolate(raw, values).trim();
+  if ((allowed as readonly string[]).includes(resolved)) return { value: resolved as T, ok: true };
+  return { value: fallback, ok: false };
+}
+
+/**
+ * その欄が解決を要るかどうか。
+ *
+ * 状態を読む形 (文字列) だけでなく、 **有限でない数** も対象にする。 型だけで判定すると
+ * `NaN` / `Infinity` が近道を素通りし、 `resolveBoundNumber` の有限性の判定に一度も届かない
+ * (実測 = 印も付かず `NaN` がそのまま SVG へ流れ、 図が黙って消える)。
+ */
+function needsResolve(raw: BoundNumber): boolean {
+  return typeof raw !== "number" || !Number.isFinite(raw);
+}
+
+export function resolveChartData(
+  data: ChartDatumPayload[],
+  values: Record<string, string>,
+): ResolvedChartDatum[] {
+  // 全ての値が有限な数なら配列を組み直さない。 状態を読まない図が毎 frame で項目数ぶんの
+  // 割当てを払わないようにするための近道で、 同じ配列をそのまま返すので挙動も変わらない。
+  if (!data.some((d) => needsResolve(d.value))) return data as ResolvedChartDatum[];
+  return data.map((d) => {
+    const v = resolveBoundNumber(d.value, values, 0);
+    return v.ok ? { ...d, value: v.value } : { ...d, value: v.value, unresolved: true as const };
+  });
+}
+
+export function resolveFunnelData(
+  stages: FunnelStagePayload[],
+  values: Record<string, string>,
+): ResolvedFunnelStage[] {
+  if (!stages.some((s) => needsResolve(s.count))) return stages as ResolvedFunnelStage[];
+  return stages.map((s) => {
+    const c = resolveBoundNumber(s.count, values, 0);
+    return c.ok ? { ...s, count: c.value } : { ...s, count: c.value, unresolved: true as const };
+  });
+}
+
+export function resolveGanttData(
+  tasks: GanttTaskPayload[],
+  values: Record<string, string>,
+): ResolvedGanttTask[] {
+  if (!tasks.some((t) => needsResolve(t.startIdx) || needsResolve(t.endIdx))) return tasks as ResolvedGanttTask[];
+  return tasks.map((t) => {
+    const start = resolveBoundNumber(t.startIdx, values, 0);
+    // 終わりの既定値は始まりに合わせて 1 目盛りぶんの帯にする。 0 に落とすと、 横軸の長さが
+    // その帯の終わりから決まる (maxIdx) ため目盛りが 1 本まで縮み、 始まりが 0 でない帯は
+    // 描画領域の外へ押し出されて消える。
+    const end = resolveBoundNumber(t.endIdx, values, start.value);
+    const next = { ...t, startIdx: start.value, endIdx: end.value };
+    return start.ok && end.ok ? next : { ...next, unresolved: true as const };
+  });
+}
+
+export function resolveQuadrantData(
+  data: QuadrantPayload,
+  values: Record<string, string>,
+): ResolvedQuadrantData {
+  const items = data.items;
+  if (items.every((i) => (QUADRANT_KEYS as readonly string[]).includes(i.quadrant))) {
+    return data as ResolvedQuadrantData;
+  }
+  return {
+    ...data,
+    items: items.map((i) => {
+      const q = resolveBoundEnum(i.quadrant, values, QUADRANT_KEYS, QUADRANT_FALLBACK);
+      return q.ok
+        ? { ...i, quadrant: q.value }
+        : { ...i, quadrant: q.value, unresolved: true as const };
+    }),
+  };
+}
+
+export function resolveJourneyData(
+  steps: JourneyStepPayload[],
+  values: Record<string, string>,
+): ResolvedJourneyStep[] {
+  if (steps.every((s) => (JOURNEY_EMOTIONS as readonly string[]).includes(s.emotion))) {
+    return steps as ResolvedJourneyStep[];
+  }
+  return steps.map((s) => {
+    const e = resolveBoundEnum(s.emotion, values, JOURNEY_EMOTIONS, EMOTION_FALLBACK);
+    return e.ok ? { ...s, emotion: e.value } : { ...s, emotion: e.value, unresolved: true as const };
+  });
+}

package/src/render/utils.ts

@@ -1,10 +1,49 @@
 import { lerp } from "../anim";
 import type { LaidDiagram } from "../types";
+import { withDerivedValues } from "./derived-values";
+import { TEMPLATE_LEFTOVER_SRC, TEMPLATE_REF_SRC } from "../template-name";
+
+const TEMPLATE_REF_RE = new RegExp(TEMPLATE_REF_SRC, "g");
+// 残っている参照の判定用。 `g` を付けないので `lastIndex` を持たず、 使い回しても結果が
+// 変わらない (描画経路は node ごと / frame ごとに通るため、 呼出のたびに式を作らない)
+const TEMPLATE_LEFTOVER_TEST_RE = new RegExp(TEMPLATE_LEFTOVER_SRC);
+
+/**
+ * 置換しきれなかった `{名前}` が残っているか。
+ *
+ * `interpolate` は値が無い名前を `{名前}` のまま残すため、 これが残っている = その文字列は
+ * 解決できていない。 読み手はここを見て fail-safe 側に倒す。
+ */
+export function hasUnresolvedRef(text: string): boolean {
+  return TEMPLATE_LEFTOVER_TEST_RE.test(text);
+}
+
+/**
+ * 文字列が読んでいる `{名前}` の名前を全て返す (accessor は落として本体だけ)。
+ *
+ * 検証側が「その名前が定義されているか」 を見るのに使う。 置換する側と同じ式を使うので、
+ * 置換されうる名前が検証を素通りすることが無い。
+ */
+export function templateRefIds(text: string): string[] {
+  // 置換できる形より広い方で拾う。 `{sig.unknown}` も `sig` を読もうとしているので、
+  // 検証側は「その名前が定義されているか」 を見る必要がある
+  const re = new RegExp(TEMPLATE_LEFTOVER_SRC, "g");
+  const out: string[] = [];
+  let m: RegExpExecArray | null;
+  while ((m = re.exec(text)) !== null) {
+    if (m[1]) out.push(m[1]);
+  }
+  return out;
+}
 
 /**
  * 全 state の現時点 value を計算 (現在 phase + これまでの phase の最終 tween 値を集約)。
  * - set = 即時切替 (phase 到達で value 上書き、 lerp なし)
  * - tween = 数値補間 (現 phase 中は progress で lerp、 過去 phase は to 固定)
+ *
+ * 段の値を出した後に `laid.derived` (他の値から自動で決まる値) を参照順で解いて足す。
+ * 毎 frame ここを通るので、 掛け算 / 比較のような端点 2 点では表せない関係も途中の値が
+ * 正しくなる。 同じ名前が `states` にもある場合は解けた値が勝ち、 解けなければ初期値が残る。
  */
 export function computeStateValues(
   laid: LaidDiagram,
@@ -32,7 +71,7 @@ export function computeStateValues(
   }
   const out: Record<string, string> = {};
   for (const [k, v] of Object.entries(values)) out[k] = String(v);
-  return out;
+  return withDerivedValues(out, laid.derived);
 }
 
 /**
@@ -41,10 +80,15 @@ export function computeStateValues(
  *   `{sig[0]}` = 要素 0 の値、 `{sig.length}` = 要素数、
  *   `{sig.sum}` / `{sig.max}` / `{sig.min}` / `{sig.avg}` = 数値集約 (非数値 element は 0 扱い)。
  * array 記法対象外 signal は従来通り `{sig}` で単純置換。
+ *
+ * 名前に使える文字は `template-name.ts` が決める (engine 全体で 1 つ)。 ここだけで
+ * 定義すると、 式を書ける側との間で「読めるが書けない」 「書けるが読めない」 名前ができる。
  */
 export function interpolate(template: string, values: Record<string, string>): string {
-  return template.replace(/\{(\w+)(\.length|\.sum|\.max|\.min|\.avg|\[\d+\])?\}/g, (_, id: string, accessor?: string) => {
-    const raw = values[id];
+  return template.replace(TEMPLATE_REF_RE, (_, id: string, accessor?: string) => {
+    // 自分が持つ名前だけを見る。 継承を辿ると `{constructor}` が「値がある」 と読まれ、
+    // prototype の中身が図に出る (実測)
+    const raw = Object.hasOwn(values, id) ? values[id] : undefined;
     if (raw === undefined) return `{${id}${accessor ?? ""}}`;
     if (!accessor) return raw;
     const arr = parseArraySignal(raw);

package/src/template-name.ts

@@ -0,0 +1,43 @@
+/**
+ * `{名前}` の名前とは何か。 **engine 全体で唯一の定義**。
+ *
+ * 使えるのは英数字と `_` (`\w`)。 呼び出し側の記法もこの範囲で名前を書く
+ * (`dragon` の `states` / `values` はどちらも `[a-zA-Z_][a-zA-Z0-9_]*` に限っている)。
+ *
+ * **読む側 (`render/utils.ts` の `interpolate`) と書ける側 (`formula/parser.ts` の `{...}`)
+ * の両方がここを使う**。 片方だけ広げると、 定義はできるのにどの箱からも読めない名前ができる。
+ * 実測した食い違いが 2 回ある。
+ *
+ * - 読み手が `\w` で拾うのに書ける側が字種を問わなかった時、 その名前は置換されず
+ *   `visibleIf` の fail-safe (未解決なら隠す) も素通りした
+ * - 書ける側が `.` を許した時、 `{v.done}` は式では読めるのに読み手が拾えなかった
+ *   (`.` は accessor `{sig.sum}` の始まりなので名前には使えない)
+ *
+ * どこにも依存しない file に置くのは、 読む側と書ける側が互いを import する輪を作らないため。
+ */
+export const TEMPLATE_NAME_CHARS = "\\w+";
+
+/**
+ * **置換できる**参照を拾う式。 名前 + 決まった accessor (`.sum` / `[0]` 等)。
+ *
+ * 置換する側 (`interpolate`) が使う。 知らない accessor を置換対象にすると、 何に
+ * 置き換えればよいか決まらない。
+ */
+export const TEMPLATE_REF_SRC =
+  `\\{(${TEMPLATE_NAME_CHARS})(\\.length|\\.sum|\\.max|\\.min|\\.avg|\\[\\d+\\])?\\}`;
+
+/**
+ * **残っている**参照を拾う式。 accessor は中身を問わない。
+ *
+ * 置換できる形より広い。 `{sig.unknown}` のように知らない accessor が付いた参照は
+ * 置換されずに残るので、 「解決できていない」 側として数える必要がある
+ * (狭い方で判定していた間、 この形で `visibleIf` の fail-safe が効かず箱が出た)。
+ */
+export const TEMPLATE_LEFTOVER_SRC = `\\{(${TEMPLATE_NAME_CHARS})([.[][^}]*)?\\}`;
+
+const NAME_ONLY_RE = new RegExp(`^${TEMPLATE_NAME_CHARS}$`);
+
+/** その文字列が `{名前}` の名前として使えるか */
+export function isValidTemplateName(name: string): boolean {
+  return NAME_ONLY_RE.test(name);
+}

package/src/types.ts

@@ -4,7 +4,7 @@ export const TONES = ["accent", "teal", "success", "error", "warning", "info"] a
 export type Tone = (typeof TONES)[number];
 
 /**
- * cdl SVG に付与される data-cdl-role attribute の SSOT 型 (CAR-730 で 5 → 10 role に拡張)。
+ * cdl SVG に付与される data-cdl-role attribute の SSOT 型 (現在 12 role)。
  * consumer app (dragon 等) は `[data-cdl-role="<role>"]` selector で CSS を宛てる。 role を追加する時は本 union と該当 render 箇所 (kinds/*.tsx、
  * render/edges.tsx、 render/stage.tsx) を同時に更新する。
  *
@@ -28,7 +28,6 @@ export type Tone = (typeof TONES)[number];
  *   - "lane-container"  ... lane.contain=true の boundary rect
  *   - "lane-lifeline"   ... lane.lifeline=true の縦点線 line
  *   - "lane-label"      ... lane 見出し text
- *   - "mind-radial-halo" ... 放射状の図の中心に敷く光の輪 (意図して淡い飾り)
  */
 export type CdlRole =
   | "node-body"
@@ -42,8 +41,7 @@ export type CdlRole =
   | "edge-label"
   | "lane-container"
   | "lane-lifeline"
-  | "lane-label"
-  | "mind-radial-halo";
+  | "lane-label";
 
 /** 描画できる箱の種類。 検査・記法一覧・型はこの 1 つの列を出所にする。 */
 export const NODE_KINDS = [
@@ -62,8 +60,8 @@ export const NODE_KINDS = [
   "signer", "oracle", "merkle-tree", "decision",
   // Chart 系 (3) ... 1 node に datum 配列を持ち、 kind 内で全 datum を SVG 描画
   "chart-pie", "chart-line", "chart-bar",
-  // Timeline / Radial 系 (3、 CAR-994 Phase B) ... 1 node に payload 配列、 SVG geometry render
-  "gantt-timeline", "mind-map", "mind-radial",
+  // 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
   "funnel-stages", "quadrant-matrix", "tree-hierarchy", "journey-map",
   // Shape-driven basement 8 (CAR-1099) ... 要素形状自体が意味を持つ SVG path node、
@@ -272,8 +270,8 @@ export type CdlNode = {
    */
   ganttData?: GanttTaskPayload[];
   /**
-   * mind-map / mind-radial 専用の branch payload。 tree 構造を 1 node に格納し、
-   * kinds/mind-map.tsx / mind-radial.tsx が中心 + 放射で SVG 描画する。
+   * mind-map 専用の branch payload。 tree 構造を 1 node に格納し、
+   * kinds/mind-map.tsx が中心 + 放射で SVG 描画する。
    */
   mindData?: MindBranchPayload;
   /** funnel-stages 専用の stage 配列 payload、 逆三角形 stage 描画に使う */
@@ -286,10 +284,33 @@ export type CdlNode = {
   journeyData?: JourneyStepPayload[];
 };
 
+/**
+ * 図表 payload の数値欄。 数を直接書くか、 `{signal}` を書いて状態から読む。
+ *
+ * 文字列を許すのは、 図表が状態を読む唯一の経路だから (`render/payload-binding.ts` が
+ * 描画直前に stateValues で解決する)。 **解決できない欄でも項目は落とさず**、 既定値で
+ * 描いて `data-cdl-unresolved="true"` を付ける (落とすと配列の長さが変わって図の形が
+ * 別物になる)。
+ *
+ * 既定値は欄ごとに違う。 数の欄は 0 だが、 `gantt-timeline` の終端は自分の始端
+ * (0 にすると帯が軸の左端まで伸びて別の図に見える)、 `quadrant-matrix` は左下、
+ * `journey-map` は「普通」。 いずれも `render/payload-binding.ts` が持つ。
+ */
+export type BoundNumber = number | string;
+
+/**
+ * 図表 payload の語の欄。 決まった語を直接書くか、 `{signal}` を書いて状態から読む。
+ *
+ * `(string & {})` は「決まった語の候補を出しつつ任意の文字列も許す」 ための書き方。
+ * 素の `string` と union すると候補が消えるため、 補完を残す目的で挟んでいる。
+ */
+export type BoundEnum<T extends string> = T | (string & {});
+
 /** Chart 系 kind の 1 datum payload。 label + value + optional tone (color) */
 export type ChartDatumPayload = {
   label: string;
-  value: number;
+  /** 棒 / 折れ線 / 扇の大きさ。 `{signal}` で状態に追随する */
+  value: BoundNumber;
   tone?: Tone;
 };
 
@@ -297,10 +318,10 @@ export type ChartDatumPayload = {
 export type GanttTaskPayload = {
   id: string;
   title: string;
-  /** 開始 index (0-based 相対位置) */
-  startIdx: number;
-  /** 終了 index (0-based 相対位置、 startIdx と同じなら 1 cell 幅) */
-  endIdx: number;
+  /** 開始 index (0-based 相対位置)。 `{signal}` で状態に追随する */
+  startIdx: BoundNumber;
+  /** 終了 index (0-based 相対位置、 startIdx と同じなら 1 cell 幅)。 `{signal}` 可 */
+  endIdx: BoundNumber;
   /** 開始 label (例 "Q1" / "2026-01") */
   startLabel: string;
   /** 終了 label (例 "Q2" / "2026-03") */
@@ -310,7 +331,7 @@ export type GanttTaskPayload = {
   tone?: Tone;
 };
 
-/** mind-map / mind-radial kind の branch tree payload。 rootId + branch 配列 */
+/** mind-map kind の branch tree payload。 rootId + branch 配列 */
 export type MindBranchPayload = {
   rootId: string;
   rootTitle: string;
@@ -330,7 +351,8 @@ export type MindBranchNode = {
 export type FunnelStagePayload = {
   id: string;
   title: string;
-  count: number;
+  /** 段の人数 / 件数。 `{signal}` で状態に追随する */
+  count: BoundNumber;
   subtitle?: string;
 };
 
@@ -347,11 +369,15 @@ export type QuadrantPayload = {
   items: QuadrantItemPayload[];
 };
 
+/** quadrant-matrix の象限 4 種 */
+export type QuadrantKey = "topLeft" | "topRight" | "bottomLeft" | "bottomRight";
+
 /** quadrant-matrix の 1 item payload */
 export type QuadrantItemPayload = {
   id: string;
   title: string;
-  quadrant: "topLeft" | "topRight" | "bottomLeft" | "bottomRight";
+  /** どの象限に居るか。 `{signal}` を書くと項目が象限を移る */
+  quadrant: BoundEnum<QuadrantKey>;
   subtitle?: string;
 };
 
@@ -364,12 +390,15 @@ export type TreeNodePayload = {
   eyebrow?: string;
 };
 
+/** journey-map の気持ち 5 段階 */
+export type JourneyEmotion = "delighted" | "happy" | "neutral" | "frustrated" | "angry";
+
 /** journey-map kind の 1 step payload */
 export type JourneyStepPayload = {
   id: string;
   title: string;
-  /** emotion 5 段階 (delighted / happy / neutral / frustrated / angry) */
-  emotion: "delighted" | "happy" | "neutral" | "frustrated" | "angry";
+  /** emotion 5 段階 (delighted / happy / neutral / frustrated / angry)。 `{signal}` で動く */
+  emotion: BoundEnum<JourneyEmotion>;
   touchpoint?: string;
   opportunity?: string;
 };
@@ -2204,6 +2233,13 @@ export type CdlDiagram = {
    * 省略時は空 array 相当で下位互換。
    */
   readouts?: CdlReadout[];
+  /**
+   * 他の値から自動で決まる値。 段の補間中も毎 frame 決まり直す (`computeStateValues`)。
+   *
+   * 入力欄の式 (`formulas`) とは経路が別。 あちらは入力欄の signal を読む reactive graph に
+   * 載り、 こちらは段が動かす状態を読む。 省略時は空 array 相当で下位互換。
+   */
+  derived?: CdlDerivedValue[];
   lanes: CdlLane[];
   nodes: CdlNode[];
   edges: CdlEdge[];
@@ -2213,6 +2249,22 @@ export type CdlDiagram = {
   viewport?: CdlViewport;
 };
 
+/**
+ * 他の値から自動で決まる値の宣言。
+ *
+ * 式は `{名前}` で他の値 (`states` / 他の `derived`) を読み、 四則 / 括弧 / 比較 /
+ * `min` / `max` が書ける。 比較の結果は真 = 1 / 偽 = 0 の数として載る。
+ *
+ * 書いた順は結果に影響しない (参照から順序を解く)。 解けない値 (輪 / 存在しない名前 /
+ * 0 除算 / 数でない値) はその値だけ止まり、 残りは動く。
+ */
+export type CdlDerivedValue = {
+  /** 値の名前。 図からは `{名前}` で読む */
+  id: string;
+  /** 式。 例 `"{inflow} - {done}"` */
+  expression: string;
+};
+
 /** Canvas 全体仕様 (v0.5+ syntax `viewport: { width, height, scale, gap, laneGap, nodeGap, labelMargin }`)。
  * 未指定時は layout が node 配置から自動算出する従来挙動。
  *
@@ -2356,6 +2408,8 @@ export type LaidDiagram = {
   edges: LaidEdge[];
   states: CdlState[];
   phases: CdlPhase[];
+  /** 他の値から自動で決まる値 (`CdlDiagram.derived` をそのまま引き継ぐ) */
+  derived?: CdlDerivedValue[];
   /**
    * キャンバス全要素の bounding box list。
    * engine が「ここに何があるか」 を全部把握、 衝突検証 / debug 表示 / validation で使う。

package/src/validate.ts

@@ -1,5 +1,7 @@
 import type { CdlDiagram } from "./types";
 import { TONES as TONE_NAMES, NODE_KINDS } from "./types";
+import { templateRefIds } from "./render/utils";
+import { derivedRefIds } from "./render/derived-values";
 
 const TONES = new Set<string>(TONE_NAMES);
 const KINDS = new Set<string>(NODE_KINDS);
@@ -79,7 +81,14 @@ export function validate(diag: CdlDiagram): void {
   const laneIds = new Set(diag.lanes.map((l) => l.id));
   const nodeIds = new Set(diag.nodes.map((n) => n.id));
   const edgeIds = new Set(diag.edges.map((e) => e.id));
+  // 段が動かせる値。 `tween` / `set` の宛先はこちらでなければならない
   const stateIds = new Set(diag.states.map((s) => s.id));
+  // `{名前}` で読める値。 他の値から自動で決まる値 (`derived`) も読めるので足す。
+  //
+  // 2 つを 1 つに畳んではいけない。 畳むと `tween` の宛先に derived を書けてしまい、
+  // 「式で決まる値を段が動かす」 という成立しない指定が素通りする (derived は毎 frame
+  // 計算し直されるので、 段が入れた値は次の frame で消える)。
+  const readableIds = new Set([...stateIds, ...(diag.derived ?? []).map((d) => d.id)]);
 
   // 「もしかして」 サジェスト (typo 検出): edit distance 1 で最も近い候補 1 件
   const suggest = (target: string, candidates: Set<string>): string => {
@@ -151,16 +160,15 @@ export function validate(diag: CdlDiagram): void {
   // ───────────────────────────────────────────────────────────
   // 6. state 参照 (node.value / node.rows の {stateId}) → 未定義は warning
   // ───────────────────────────────────────────────────────────
-  const refRe = /\{(\w+)\}/g;
   for (const n of diag.nodes) {
     const checks: string[] = [];
     if (n.value) checks.push(n.value);
     if (n.rows) checks.push(...n.rows);
     for (const text of checks) {
-      let m: RegExpExecArray | null;
-      while ((m = refRe.exec(text))) {
-        const id = m[1];
-        if (id && !stateIds.has(id)) {
+      // 名前の切り出しは描画側と同じ式を使う (`templateRefIds`)。 別に書くと字種がずれ、
+      // 置換されうる名前が検証を素通りする
+      for (const id of templateRefIds(text)) {
+        if (!readableIds.has(id)) {
           warnings.push(`node "${n.id}" が未定義 state "${id}" を参照`);
         }
       }
@@ -194,10 +202,30 @@ export function validate(diag: CdlDiagram): void {
   for (const n of diag.nodes) {
     const texts = [n.value, ...(n.rows ?? [])].filter(Boolean) as string[];
     for (const text of texts) {
-      let m: RegExpExecArray | null;
-      const re = /\{(\w+)\}/g;
-      while ((m = re.exec(text))) {
-        if (m[1]) stateUsed.add(m[1]);
+      // 名前の切り出しは描画側と同じ式を使う。 別に書くと字種がずれ、 実際は読まれている
+      // 状態が「どこでも参照されていない」 と報告される
+      for (const id of templateRefIds(text)) stateUsed.add(id);
+    }
+  }
+  // 他の値から決まる値の式も状態を読むので数える。 ただし **その値自体が読まれている時だけ**。
+  //
+  // 式を無条件に使用として数えると、 誰も読まない値の連なりに隠れて未使用の状態が
+  // 見えなくなる (`waiting = {inflow} - 1` を誰も読まなくても `inflow` が使用済になる)。
+  // 読まれている名前から式を辿って広げる形にすれば、 連なりごと使われていない場合に
+  // 先頭も末尾も unused として出る。
+  const derivedById = new Map((diag.derived ?? []).map((dv) => [dv.id, dv]));
+  const queue = [...stateUsed];
+  while (queue.length > 0) {
+    const id = queue.pop()!;
+    const dv = derivedById.get(id);
+    if (!dv) continue;
+    // 式の参照は評価側と同じ抽出を使う (`derivedRefIds`)。 `templateRefIds` は `{名前}` しか
+    // 拾わないため、 素の識別子で書かれた参照を取りこぼす
+    for (const ref of derivedRefIds(dv.expression)) {
+      // 既に数えた名前は辿らない = 式に輪があっても止まる
+      if (!stateUsed.has(ref)) {
+        stateUsed.add(ref);
+        queue.push(ref);
       }
     }
   }
@@ -206,6 +234,11 @@ export function validate(diag: CdlDiagram): void {
       warnings.push(`state "${s.id}" がどこでも参照されていない (unused)`);
     }
   }
+  for (const dv of diag.derived ?? []) {
+    if (!stateUsed.has(dv.id)) {
+      warnings.push(`値 "${dv.id}" がどこでも参照されていない (unused)`);
+    }
+  }
   // 使われない lane も warn (どの node も配置されない)
   const laneUsed = new Set<string>();
   for (const n of diag.nodes) laneUsed.add(n.lane);