@cardenelabs/cdl 0.10.0 → 0.11.0

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

@@ -2051,8 +2051,15 @@ type CdlPhase = {
      * この phase で「左の起点から描き始める」 node の id (cdl#512)。
      *
      * `activate` と同じ形で node id を並べる。 対象の node は phase の進み (0→1) に合わせて
-     * 描かれ、 進みが 1 に達した時点で全体が出る。 現在の対象は `chart-line` だけで、
-     * 折れ線が左端から右へ伸び、 点と値の数字は線の先が届いた時に現れる。
+     * 描かれ、 進みが 1 に達した時点で全体が出る。 起点は種別ごとに違う。
+     *
+     * | kind | 起点 | 動き | 添える値 |
+     * |---|---|---|---|
+     * | `chart-line` | 左端 | 線が右へ伸びる | 点と数字は線の先が届いた時 |
+     * | `chart-bar` | 横軸 | 棒が上へ伸びる | 数字は棒の頭に付いて動く |
+     * | `chart-pie` | 12 時 | 扇が時計回りに開く | 凡例はその扇が開き始めた時 |
+     *
+     * 対象種別の一覧は `validate.ts` の `DRAW_KINDS` が持つ。
      *
      * **`activate` を兼ねさせない**。 1 箱で図全体を描く種別 (`chart-*` 等) では焦点が
      * その箱に解決されるため、 連続する phase で光り続ける図が実在する。 「光っていたら

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

@@ -2051,8 +2051,15 @@ type CdlPhase = {
      * この phase で「左の起点から描き始める」 node の id (cdl#512)。
      *
      * `activate` と同じ形で node id を並べる。 対象の node は phase の進み (0→1) に合わせて
-     * 描かれ、 進みが 1 に達した時点で全体が出る。 現在の対象は `chart-line` だけで、
-     * 折れ線が左端から右へ伸び、 点と値の数字は線の先が届いた時に現れる。
+     * 描かれ、 進みが 1 に達した時点で全体が出る。 起点は種別ごとに違う。
+     *
+     * | kind | 起点 | 動き | 添える値 |
+     * |---|---|---|---|
+     * | `chart-line` | 左端 | 線が右へ伸びる | 点と数字は線の先が届いた時 |
+     * | `chart-bar` | 横軸 | 棒が上へ伸びる | 数字は棒の頭に付いて動く |
+     * | `chart-pie` | 12 時 | 扇が時計回りに開く | 凡例はその扇が開き始めた時 |
+     *
+     * 対象種別の一覧は `validate.ts` の `DRAW_KINDS` が持つ。
      *
      * **`activate` を兼ねさせない**。 1 箱で図全体を描く種別 (`chart-*` 等) では焦点が
      * その箱に解決されるため、 連続する phase で光り続ける図が実在する。 「光っていたら

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cardenelabs/cdl",
-  "version": "0.10.0",
+  "version": "0.11.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",

package/src/kinds/chart-bar.tsx

@@ -6,15 +6,26 @@ import { resolveChartData } from "../render/payload-binding";
  * chart-bar kind ... 1 node に datum 配列 (chartData) を保持し、 SVG rect で棒グラフ描画する。
  * layout は node bbox 内側の canvas に縦棒を等間隔配置、 縦軸 = value 0-max、 横軸 = datum label。
  * 各 value は数でも `{signal}` でもよく、 後者は状態が動くたび棒の高さが追随する。
+ *
+ * phase の `draw` にこの node の id が載っている間は、 棒が横軸から上へ伸びる (cdl#516)。
+ * 伸ばすのは棒を包む `<g>` の `transform` で、 `rect` の `x` / `y` / `width` / `height` は
+ * 進みに関わらず実値のまま。 値の数字は棒の頭に付いて動く。
+ * 軸 / 格子 / 横軸の名前は最初から出る。
  */
 export function ChartBarNode({
   node,
   active,
   stateValues = {},
+  drawing = false,
+  progress = 1,
 }: {
   node: LaidNode;
   active: boolean;
   stateValues?: Record<string, string>;
+  /** この phase の `draw` に載っているか (cdl#516) */
+  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;
@@ -43,6 +54,16 @@ export function ChartBarNode({
     return { y: yAt(v), value: v };
   });
 
+  /**
+   * 棒がどこまで伸びたか (0..1、 cdl#516)。 描く指定が無ければ常に 1 = 全高。
+   *
+   * 進みは呼出側から来る値なので範囲の外 (負 / 1 超 / NaN) が入りうる。 そのまま倍率に
+   * 渡すと棒が上下反転したり突き抜けたりするため、 ここで畳む。
+   */
+  const 伸び = drawing ? Math.min(1, Math.max(0, Number.isFinite(progress) ? progress : 1)) : 1;
+  /** 棒の足元。 ここを動かさない点として上へ伸ばす */
+  const 横軸のy = PAD_TOP + canvasH;
+
   return (
     <g transform={`translate(${x0} ${y0})`}>
       <rect
@@ -93,22 +114,38 @@ export function ChartBarNode({
         const bx = xAt(idx);
         const by = yAt(d.value);
         const bh = PAD_TOP + canvasH - by;
+        // 見えている棒の頭。 数字はここに付いて動く = 空いた場所に数字だけ浮かない
+        const 見えている頭 = 横軸のy - (横軸のy - by) * 伸び;
+        /**
+         * **`rect` の属性は触らない** (cdl#516)。 高さを直接動かすと、棒の高さで値を測る
+         * 利用側の検査が進みの途中で別の値を読む。 足元を動かさない点にした倍率で包む。
+         */
+        const 棒 = (
+          <rect
+            data-cdl-role="chart-bar"
+            data-cdl-unresolved={d.unresolved ? "true" : undefined}
+            x={bx}
+            y={by}
+            width={barW}
+            height={bh}
+            rx={2}
+            fill="var(--cdl-tone-accent, #2d6a8f)"
+            fillOpacity={0.9}
+          />
+        );
         return (
           <g key={`bar-${idx}`}>
-            <rect
-              data-cdl-role="chart-bar"
-              data-cdl-unresolved={d.unresolved ? "true" : undefined}
-              x={bx}
-              y={by}
-              width={barW}
-              height={bh}
-              rx={2}
-              fill="var(--cdl-tone-accent, #2d6a8f)"
-              fillOpacity={0.9}
-            />
+            {/* 描く指定が無い図には包みを足さない = 既存の図の DOM を 1 要素も変えない */}
+            {drawing ? (
+              <g transform={`translate(0 ${横軸のy}) scale(1 ${伸び}) translate(0 ${-横軸のy})`}>
+                {棒}
+              </g>
+            ) : (
+              棒
+            )}
             <text
               x={bx + barW / 2}
-              y={by - 6}
+              y={見えている頭 - 6}
               fontSize={11}
               textAnchor="middle"
               fill="var(--cdl-text, #1a1f2a)"

package/src/kinds/chart-pie.tsx

@@ -1,4 +1,4 @@
-import type { JSX } from "react";
+import { useId, type JSX } from "react";
 import type { LaidNode, Tone } from "../types";
 import { TONE } from "../render/tone";
 import { resolveChartData } from "../render/payload-binding";
@@ -7,16 +7,29 @@ import { resolveChartData } from "../render/payload-binding";
  * chart-pie kind ... 1 node に datum 配列 (chartData) を保持し、 SVG path arc で円グラフ描画する。
  * layout は node bbox 内側の左半分に円を配置、 右半分に凡例 (label + %) を stack 表示する。
  * 各 value は数でも `{signal}` でもよく、 後者は状態が動くたび扇の角度が追随する。
+ *
+ * phase の `draw` にこの node の id が載っている間は、 円が 12 時から時計回りに開く (cdl#516)。
+ * 開き方は扇形の切り抜き (`clipPath`) で、 各扇の `d` は進みに関わらず実値のまま。
+ * 凡例はその扇が開き始めた時に出る。
  */
 export function ChartPieNode({
   node,
   active,
   stateValues = {},
+  drawing = false,
+  progress = 1,
 }: {
   node: LaidNode;
   active: boolean;
   stateValues?: Record<string, string>;
+  /** この phase の `draw` に載っているか (cdl#516) */
+  drawing?: boolean;
+  /** phase の進み (0→1)。 `drawing` が true の時だけ読む */
+  progress?: number;
 }): JSX.Element {
+  // node id は diagram 内だけで一意。 同じ page に複数 diagram がある時も SVG の参照先が
+  // ぶつからないよう、 React が component instance ごとに割り当てる id を使う。
+  const instanceId = useId().replace(/[^A-Za-z0-9_-]/g, "");
   const x0 = node.cx - node.w / 2;
   const y0 = node.cy - node.h / 2;
   const data = resolveChartData(node.chartData ?? [], stateValues);
@@ -31,12 +44,16 @@ export function ChartPieNode({
   const cy = PAD_TOP + chartAreaH / 2;
 
   let cumAngle = -Math.PI / 2;
+  /** その扇が始まるまでの取り分の累計。 開き始めたかの判定に使う (cdl#516) */
+  let cumFrac = 0;
   const slices = data.map((d) => {
     const frac = d.value / total;
     const angle = frac * Math.PI * 2;
     const a0 = cumAngle;
     const a1 = cumAngle + angle;
     cumAngle = a1;
+    const startFrac = cumFrac;
+    cumFrac += frac;
 
     const x1 = cx + radius * Math.cos(a0);
     const y1 = cy + radius * Math.sin(a0);
@@ -44,9 +61,21 @@ export function ChartPieNode({
     const y2 = cy + radius * Math.sin(a1);
     const large = angle > Math.PI ? 1 : 0;
     const path = `M ${cx} ${cy} L ${x1} ${y1} A ${radius} ${radius} 0 ${large} 1 ${x2} ${y2} Z`;
-    return { d, frac, path };
+    return { d, frac, path, startFrac };
   });
 
+  /**
+   * 円がどこまで開いたか (0..1、 cdl#516)。 描く指定が無ければ常に 1 = 全周。
+   *
+   * 進みは呼出側から来る値なので範囲の外 (負 / 1 超 / NaN) が入りうる。 そのまま角度に
+   * 掛けると 1 周を超えて切り抜きが壊れるため、 ここで畳む。
+   */
+  const 開き = drawing ? Math.min(1, Math.max(0, Number.isFinite(progress) ? progress : 1)) : 1;
+  // SVG の id は document 全体の名前空間。 node id ではなく instance id で分ける
+  const 切り抜きid = `cdl-pie-draw-${instanceId}`;
+  /** その扇が開き始めたか。 開き始めた扇の凡例だけを出す */
+  const 開き始めた = (startFrac: number): boolean => !drawing || 開き > startFrac;
+
   const legendX = pieAreaW + 8;
   const legendGap = Math.min(28, chartAreaH / Math.max(data.length, 1));
   const legendStartY = PAD_TOP + (chartAreaH - legendGap * data.length) / 2 + legendGap / 2;
@@ -64,20 +93,40 @@ export function ChartPieNode({
         stroke={active ? "var(--cdl-tone-accent, #2d6a8f)" : "var(--cdl-divider, #d4d4d8)"}
         strokeWidth={active ? 3 : 1.25}
       />
-      {slices.map((s, idx) => (
-        <path
-          key={`slice-${idx}`}
-          data-cdl-role="chart-pie-slice"
-          data-cdl-unresolved={s.d.unresolved ? "true" : undefined}
-          d={s.path}
-          fill={sliceColor(s.d.tone, idx)}
-          fillOpacity={active ? 0.95 : 0.85}
-          stroke="var(--cdl-node-fill, #ffffff)"
-          strokeWidth={1.5}
-        />
-      ))}
+      {drawing && (
+        <defs>
+          <clipPath id={切り抜きid}>{扇形の切り抜き(cx, cy, radius + 2, 開き)}</clipPath>
+        </defs>
+      )}
+      {/*
+        **扇の `d` は触らない** (cdl#516)。 進みで再計算すると、扇の形から取り分を測る
+        利用側が進みの途中で別の値を読む。 見える範囲だけを切り抜きで変える。
+
+        描く指定が無い図には包みも `clip-path` も足さない = 既存の図の DOM を変えない
+      */}
+      <g {...(drawing ? { clipPath: `url(#${切り抜きid})` } : {})}>
+        {slices.map((s, idx) => (
+          <path
+            key={`slice-${idx}`}
+            data-cdl-role="chart-pie-slice"
+            data-cdl-unresolved={s.d.unresolved ? "true" : undefined}
+            d={s.path}
+            fill={sliceColor(s.d.tone, idx)}
+            fillOpacity={active ? 0.95 : 0.85}
+            stroke="var(--cdl-node-fill, #ffffff)"
+            strokeWidth={1.5}
+          />
+        ))}
+      </g>
 
-      {slices.map((s, idx) => (
+      {/*
+        行の位置は `idx` から決まる。 いまの開き方は必ず先頭からの連続なので、開いた扇だけを
+        `filter` で抜いても位置は同じになる (変異試験で実測 = 差が出ない)。
+
+        それでも `idx` を保つ形で書くのは、位置の計算が抜き方に依存しないため。 開く順が
+        先頭からでなくなった時に、この場所を直し忘れても位置がずれない
+      */}
+      {slices.map((s, idx) => !開き始めた(s.startFrac) ? null : (
         <g key={`legend-${idx}`} transform={`translate(${legendX} ${legendStartY + idx * legendGap})`}>
           <rect
             x={0}
@@ -110,6 +159,22 @@ export function ChartPieNode({
 }
 
 
+/**
+ * 12 時から時計回りに開く扇形 (cdl#516)。 円を切り抜く形に使う。
+ *
+ * 1 周ちょうどは扇形で表せない (始点と終点が同じ点になり、 弧の向きが決まらない)。
+ * その時だけ円をそのまま返す = 進み 1 で図が消える形を避ける。
+ */
+function 扇形の切り抜き(cx: number, cy: number, r: number, 開き: number): JSX.Element | null {
+  if (開き <= 0) return null;
+  if (開き >= 1) return <circle cx={cx} cy={cy} r={r} />;
+  const a0 = -Math.PI / 2;
+  const a1 = a0 + 開き * Math.PI * 2;
+  const large = 開き > 0.5 ? 1 : 0;
+  const d = `M ${cx} ${cy} L ${cx + r * Math.cos(a0)} ${cy + r * Math.sin(a0)} A ${r} ${r} 0 ${large} 1 ${cx + r * Math.cos(a1)} ${cy + r * Math.sin(a1)} Z`;
+  return <path d={d} />;
+}
+
 const FALLBACK_ORDER: Tone[] = ["accent", "teal", "warning", "success", "info", "error"];
 
 function sliceColor(tone: Tone | undefined, idx: number): string {

package/src/render/nodes.tsx

@@ -170,9 +170,25 @@ export function CdlNodeView({
           />
         );
       case "chart-pie":
-        return <ChartPieNode node={resolvedNode} active={active} stateValues={stateValues} />;
+        return (
+          <ChartPieNode
+            node={resolvedNode}
+            active={active}
+            stateValues={stateValues}
+            drawing={drawing}
+            progress={progress}
+          />
+        );
       case "chart-bar":
-        return <ChartBarNode node={resolvedNode} active={active} stateValues={stateValues} />;
+        return (
+          <ChartBarNode
+            node={resolvedNode}
+            active={active}
+            stateValues={stateValues}
+            drawing={drawing}
+            progress={progress}
+          />
+        );
       case "gantt-timeline":
         return <GanttNode node={resolvedNode} active={active} stateValues={stateValues} />;
       case "mind-map":

package/src/types.ts

@@ -2128,8 +2128,15 @@ export type CdlPhase = {
    * この phase で「左の起点から描き始める」 node の id (cdl#512)。
    *
    * `activate` と同じ形で node id を並べる。 対象の node は phase の進み (0→1) に合わせて
-   * 描かれ、 進みが 1 に達した時点で全体が出る。 現在の対象は `chart-line` だけで、
-   * 折れ線が左端から右へ伸び、 点と値の数字は線の先が届いた時に現れる。
+   * 描かれ、 進みが 1 に達した時点で全体が出る。 起点は種別ごとに違う。
+   *
+   * | kind | 起点 | 動き | 添える値 |
+   * |---|---|---|---|
+   * | `chart-line` | 左端 | 線が右へ伸びる | 点と数字は線の先が届いた時 |
+   * | `chart-bar` | 横軸 | 棒が上へ伸びる | 数字は棒の頭に付いて動く |
+   * | `chart-pie` | 12 時 | 扇が時計回りに開く | 凡例はその扇が開き始めた時 |
+   *
+   * 対象種別の一覧は `validate.ts` の `DRAW_KINDS` が持つ。
    *
    * **`activate` を兼ねさせない**。 1 箱で図全体を描く種別 (`chart-*` 等) では焦点が
    * その箱に解決されるため、 連続する phase で光り続ける図が実在する。 「光っていたら

package/src/validate.ts

@@ -5,6 +5,20 @@ import { nodeTemplateTexts } from "./render/template-fields";
 import { derivedRefIds } from "./render/derived-values";
 
 const TONES = new Set<string>(TONE_NAMES);
+
+/**
+ * phase の `draw` が効く kind (cdl#512 / cdl#516)。
+ *
+ * **一覧を 1 箇所で持つ**。 知らせの文面もここから組み立てる = 対応種別が増えた時に
+ * 片方だけ古くなる形を作らない。
+ *
+ * | kind | 起点 | 動き |
+ * |---|---|---|
+ * | `chart-line` | 左端 | 線が右へ伸びる |
+ * | `chart-bar` | 横軸 | 棒が上へ伸びる |
+ * | `chart-pie` | 12 時 | 扇が時計回りに開く |
+ */
+export const DRAW_KINDS: ReadonlySet<string> = new Set(["chart-line", "chart-bar", "chart-pie"]);
 const KINDS = new Set<string>(NODE_KINDS);
 const ENG_BANNED = /\b(FUNCTION|STORAGE|EVENT LOG|BALANCES MAPPING|READ|WRITE|EMIT|CALL)\b/;
 
@@ -166,8 +180,10 @@ export function validate(diag: CdlDiagram): void {
       // 描き方を持たない種別を指しても図は出るが、 書いた指定は何もしない。
       // 黙って捨てると「書いたのに伸びない」 が手掛かりなしで起きる
       const kind = diag.nodes.find((n) => n.id === id)?.kind;
-      if (kind !== "chart-line") {
-        warnings.push(`phase "${p.id}" の draw "${id}" は kind "${kind}" で、 左から描く動きを持たない (対象は chart-line)`);
+      if (!DRAW_KINDS.has(String(kind))) {
+        warnings.push(
+          `phase "${p.id}" の draw "${id}" は kind "${kind}" で、 起点から描く動きを持たない (対象は ${[...DRAW_KINDS].join(" / ")})`,
+        );
       }
     }
     for (const t of p.tweens) {