@cardenelabs/cdl 0.36.0 → 0.38.0

package/dist/{render-R7v2bfyz.d.cts → render-BYdmSviQ.d.cts}

@@ -424,18 +424,29 @@ type CdlNode = {
      */
     chartPieForm?: ChartPieForm;
     /**
-     * chart-slope の見せ方 (cdl#702)。 右の列に何の数を出すかを決める。
+     * chart-slope の見せ方 (cdl#702 / cdl#707)。
      *
-     * - `values` ... 今の値
-     * - `delta` ... 増減 (`+40` / `-90`)
+     * | 値 | 縦の位置 | 左の列 | 右の列 |
+     * |---|---|---|---|
+     * | `values` | 値 | 前の値 | 今の値 |
+     * | `delta` | 値 | 前の値 | 増減 (`+40` / `-90`) |
+     * | `rank` | 順位の段 (等間隔) | 前の値 | 今の値 |
      *
-     * 左の列は どちらでも前の値。 `前 + 増減 = 今` なので、 `delta` でも今の値は足せば戻る。
+     * `values` と `delta` は縦の位置が同じで、右の列の字だけが違う。
+     * `前 + 増減 = 今` なので、 `delta` でも今の値は足せば戻る。
      * 3 つ目の数を足さないので、 名札の高さも線を引く幅も変わらない。
      *
+     * `rank` は **縦の位置** を変える (cdl#707)。 段を等間隔に置くので、線の交差が
+     * 順位の入れ替わりと 1 対 1 になり、水平線が「順位が動かなかった」 を意味する。
+     * 字は値のままにして、量が図から消えないようにしている。
+     *
+     * `rank` では「線の傾きが動いた量」 という読み方が成立しない (`+40` と `+30` が
+     * どちらも水平線になる)。 書いた図だけに効く割り切りで、量は字を読む。
+     *
      * 型の外の値は `values` として描く = 見せ方が決まらないより、既定の形が出る方がよい。
      *
-     * 前の時点を持たない図 (`previous` が 1 件も無い) は右の列そのものが無いため、
-     * この欄を書いても絵は変わらない。
+     * 前の時点を持たない図 (`previous` が 1 件も無い) は軸が 1 本で並べ替える相手が
+     * いないため、 この欄を書いても絵は変わらない。
      */
     chartSlopeForm?: ChartSlopeForm;
     /**
@@ -493,8 +504,8 @@ 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` */
 type ChartPieForm = "ring" | "arcs" | "table";
-/** chart-slope の見せ方 (cdl#702)。 SSOT は `kinds/chart-slope.tsx` */
-type ChartSlopeForm = "values" | "delta";
+/** chart-slope の見せ方 (cdl#702 / cdl#707)。 SSOT は `kinds/chart-slope.tsx` */
+type ChartSlopeForm = "values" | "delta" | "rank";
 type ChartDatumPayload = {
     label: string;
     /** 棒 / 折れ線 / 扇の大きさ。 `{signal}` で状態に追随する */

package/dist/{render-R7v2bfyz.d.ts → render-BYdmSviQ.d.ts}

@@ -424,18 +424,29 @@ type CdlNode = {
      */
     chartPieForm?: ChartPieForm;
     /**
-     * chart-slope の見せ方 (cdl#702)。 右の列に何の数を出すかを決める。
+     * chart-slope の見せ方 (cdl#702 / cdl#707)。
      *
-     * - `values` ... 今の値
-     * - `delta` ... 増減 (`+40` / `-90`)
+     * | 値 | 縦の位置 | 左の列 | 右の列 |
+     * |---|---|---|---|
+     * | `values` | 値 | 前の値 | 今の値 |
+     * | `delta` | 値 | 前の値 | 増減 (`+40` / `-90`) |
+     * | `rank` | 順位の段 (等間隔) | 前の値 | 今の値 |
      *
-     * 左の列は どちらでも前の値。 `前 + 増減 = 今` なので、 `delta` でも今の値は足せば戻る。
+     * `values` と `delta` は縦の位置が同じで、右の列の字だけが違う。
+     * `前 + 増減 = 今` なので、 `delta` でも今の値は足せば戻る。
      * 3 つ目の数を足さないので、 名札の高さも線を引く幅も変わらない。
      *
+     * `rank` は **縦の位置** を変える (cdl#707)。 段を等間隔に置くので、線の交差が
+     * 順位の入れ替わりと 1 対 1 になり、水平線が「順位が動かなかった」 を意味する。
+     * 字は値のままにして、量が図から消えないようにしている。
+     *
+     * `rank` では「線の傾きが動いた量」 という読み方が成立しない (`+40` と `+30` が
+     * どちらも水平線になる)。 書いた図だけに効く割り切りで、量は字を読む。
+     *
      * 型の外の値は `values` として描く = 見せ方が決まらないより、既定の形が出る方がよい。
      *
-     * 前の時点を持たない図 (`previous` が 1 件も無い) は右の列そのものが無いため、
-     * この欄を書いても絵は変わらない。
+     * 前の時点を持たない図 (`previous` が 1 件も無い) は軸が 1 本で並べ替える相手が
+     * いないため、 この欄を書いても絵は変わらない。
      */
     chartSlopeForm?: ChartSlopeForm;
     /**
@@ -493,8 +504,8 @@ 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` */
 type ChartPieForm = "ring" | "arcs" | "table";
-/** chart-slope の見せ方 (cdl#702)。 SSOT は `kinds/chart-slope.tsx` */
-type ChartSlopeForm = "values" | "delta";
+/** chart-slope の見せ方 (cdl#702 / cdl#707)。 SSOT は `kinds/chart-slope.tsx` */
+type ChartSlopeForm = "values" | "delta" | "rank";
 type ChartDatumPayload = {
     label: string;
     /** 棒 / 折れ線 / 扇の大きさ。 `{signal}` で状態に追随する */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cardenelabs/cdl",
-  "version": "0.36.0",
+  "version": "0.38.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/anim/core/timeline.ts

@@ -60,6 +60,8 @@ export class Timeline {
   private rafHandle: number | null = null;
   private phaseIndex = 0;
   private phaseProgress = 0;
+  /** 曲線を通す前の進み (cdl#711)。 経過時間そのものの割合で、 描く動きが読む */
+  private phaseLinearProgress = 0;
   private phaseStartedAt = 0;
   private status: TimelineStatus = "idle";
   /**
@@ -75,7 +77,7 @@ export class Timeline {
    */
   private readonly initialState: {
     phaseIndex: number;
-    phaseProgress: number;
+    phaseLinearProgress: number;
     status: TimelineStatus;
   };
 
@@ -94,12 +96,12 @@ export class Timeline {
     const initial = options.initialPhaseIndex;
     if (initial != null && initial > 0 && initial < phases.length) {
       this.phaseIndex = initial;
-      this.phaseProgress = 1;
+      this.setProgress(1);
       this.status = initial === phases.length - 1 ? "settled" : "paused";
     }
     this.initialState = {
       phaseIndex: this.phaseIndex,
-      phaseProgress: this.phaseProgress,
+      phaseLinearProgress: this.phaseLinearProgress,
       status: this.status,
     };
   }
@@ -133,6 +135,7 @@ export class Timeline {
       cached.status === this.status &&
       cached.phaseIndex === this.phaseIndex &&
       cached.phaseProgress === this.phaseProgress &&
+      cached.phaseLinearProgress === this.phaseLinearProgress &&
       cached.totalPhases === this.phases.length
     ) {
       return cached;
@@ -141,6 +144,7 @@ export class Timeline {
       status: this.status,
       phaseIndex: this.phaseIndex,
       phaseProgress: this.phaseProgress,
+      phaseLinearProgress: this.phaseLinearProgress,
       totalPhases: this.phases.length,
     };
     this.cachedSnapshot = next;
@@ -168,7 +172,7 @@ export class Timeline {
     const clamped = Math.max(0, Math.min(this.phases.length - 1, index));
     this.cancelRaf();
     this.phaseIndex = clamped;
-    this.phaseProgress = 1;
+    this.setProgress(1);
     this.status = clamped === this.phases.length - 1 ? "settled" : "paused";
     this.emit();
   }
@@ -212,7 +216,7 @@ export class Timeline {
     if (this.phaseIndex <= 0) return;
     this.cancelRaf();
     this.phaseIndex -= 1;
-    this.phaseProgress = 1;
+    this.setProgress(1);
     this.status = "paused";
     this.emit();
   }
@@ -220,7 +224,7 @@ export class Timeline {
   reset(): void {
     this.cancelRaf();
     this.phaseIndex = 0;
-    this.phaseProgress = 0;
+    this.setProgress(0);
     this.status = "idle";
     this.emit();
   }
@@ -242,7 +246,7 @@ export class Timeline {
     this.subscribers.clear();
     this.status = this.initialState.status;
     this.phaseIndex = this.initialState.phaseIndex;
-    this.phaseProgress = this.initialState.phaseProgress;
+    this.setProgress(this.initialState.phaseLinearProgress);
   }
 
   // ─── internals ───────────────────────────────────────────────
@@ -284,7 +288,7 @@ export class Timeline {
   }
 
   private beginPhaseTransition(): void {
-    this.phaseProgress = 0;
+    this.setProgress(0);
     this.phaseStartedAt = performance.now();
     this.cancelRaf();
     const step = (now: number) => {
@@ -292,13 +296,13 @@ export class Timeline {
         this.autoAdvanceMsOverride ?? this.getPhase().durationMs ?? 600;
       const elapsed = now - this.phaseStartedAt;
       const linearT = clamp01(elapsed / duration);
-      this.phaseProgress = this.easing(linearT);
+      this.setProgress(linearT);
       this.emit();
       if (linearT < 1) {
         this.rafHandle = requestAnimationFrame(step);
         return;
       }
-      this.phaseProgress = 1;
+      this.setProgress(1);
       this.emit();
       if (this.status === "playing") {
         // 自動進行中は次 Phase へ
@@ -315,6 +319,20 @@ export class Timeline {
     this.rafHandle = requestAnimationFrame(step);
   }
 
+  /**
+   * 段の進みを 2 つ同時に置く (cdl#711)。
+   *
+   * **代入する場所を 1 つに閉じる**。 曲げた進みと曲げる前の進みを別々に書くと、
+   * どちらかを更新し忘れた経路が「前の段の値のまま」 で残る。
+   *
+   * 両端 (0 と 1) は曲線を通さず、 そのまま置く。 曲線は差し替えられる欄なので、
+   * `easing(1)` が 1 を返す保証がない。 段の始まりと終わりの値は曲線に委ねない。
+   */
+  private setProgress(linear: number): void {
+    this.phaseLinearProgress = linear;
+    this.phaseProgress = linear <= 0 ? 0 : linear >= 1 ? 1 : this.easing(linear);
+  }
+
   private cancelRaf(): void {
     if (this.rafHandle != null) {
       cancelAnimationFrame(this.rafHandle);

package/src/anim/core/types.ts

@@ -37,6 +37,18 @@ export type TimelineState = {
   phaseIndex: number;
   /** 現在 Phase 内の進行度 (0..1)、 視覚要素の補間に使う */
   phaseProgress: number;
+  /**
+   * 曲線を通す前の進行度 (0..1、 cdl#711)。 経過時間そのものの割合。
+   *
+   * `phaseProgress` は既定で `easeOutQuint` を通るため前半に動きが寄る。
+   * **値が落ち着く動きには合うが、 線を引く動きには合わない** =
+   * `1.2s` の段で半分に達するのが 158 ms になり、 折れ線の 5 点のうち 4 点が
+   * 292 ms の間に出てしまう (実測)。
+   *
+   * 描く動き (`draw` の node と伸ばす edge) はこちらを読む。
+   * 両端 (0 と 1) は 2 つとも同じ値になる。
+   */
+  phaseLinearProgress: number;
   /** 全 Phase 数 */
   totalPhases: number;
 };

package/src/kinds/chart-slope.tsx

@@ -50,6 +50,24 @@ import { 進みを畳む, 伸ばすdash } from "./draw-progress";
  *
  * 色を持たせるのは **名前だけ**。 値は太字の濃い色のままにして、数の読み比べを保つ。
  * identity は色が、量は字が担う。
+ *
+ * ## 順位で見せる形は縦の位置を変える (cdl#707)
+ *
+ * この図は「線の交差が順位の入れ替わり」 を読ませるが、縦の位置は値なので **交差点の
+ * 位置が順位と噛み合わない**。 どの交差が本当に順位を変えた交差なのかは、値を読み比べ
+ * ないと決まらない。
+ *
+ * `rank` は段を等間隔に置く。 交差が入れ替わりと 1 対 1 になり、水平線が「順位が
+ * 動かなかった」 を意味する。
+ *
+ * **字は値のままにする**。 字も順位にすると `380 → 420` と `60 → 90` がどちらも
+ * 同じ水平線になり、量が図から完全に消える。 位置が順位を、字が量を担う。
+ *
+ * 順位と値を **両方** 出す案は落とした = 3 つ目の数を足す形で、実物に当てると値の列が
+ * 伸びて名前と重なった (`delta` で落としたのと同じ形、cdl#702)。
+ *
+ * **この形では「線の傾きが動いた量」 が成立しない**。 `+40` と `+30` がどちらも水平線に
+ * なる。 書いた図だけに効く割り切りで、量は字を読む。
  */
 
 /** 線を引くのに最低限要る横幅。 名札が長い図でもこれだけは残す */
@@ -113,14 +131,39 @@ export function ChartSlopeNode({
     尺の幅 > 0 ? 下端 - ((v - 最小) / 尺の幅) * (下端 - 上端) : (上端 + 下端) / 2;
 
   /**
-   * 見せ方 (cdl#702)。 **型の外の値は `values` に落とす** = 見せ方が決まらないより、
-   * 既定の形が出る方がよい (円グラフと同じ判断)。
+   * 見せ方 (cdl#702 / cdl#707)。 **型の外の値は `values` に落とす** = 見せ方が
+   * 決まらないより、既定の形が出る方がよい (円グラフと同じ判断)。
+   *
+   * **前の時点を持たない図では `values` に落とす**。 `delta` は引く相手がいないので、
+   * 増減を出すと「0 から増えた」 という書いていない主張になる (前を持たない件を 0 から
+   * 立ち上げるのは線を引くための扱いで、前が 0 だったという意味ではない)。
+   * `rank` は軸が 1 本で並べ替える相手がいない。
+   */
+  const 書いた形 = node.chartSlopeForm;
+  const 形: ChartSlopeForm =
+    前あり && (書いた形 === "delta" || 書いた形 === "rank") ? 書いた形 : "values";
+
+  /**
+   * 順位。 **自分より大きい値の件数 + 1** で決める。
+   *
+   * 同じ値なら同じ順位になり、段も重なる。 無理に 1 つずつずらすと、書いていない差を
+   * 絵が主張することになる。
+   */
+  const 順位を取る = (v: number, 全部: number[]): number =>
+    全部.filter((x) => x > v).length + 1;
+
+  const 前の順位 = 系列たち.map((s) => 順位を取る(s.前, 系列たち.map((x) => x.前)));
+  const 今の順位 = 系列たち.map((s) => 順位を取る(s.今, 系列たち.map((x) => x.今)));
+
+  /**
+   * 段の y。 1 位を上端、系列の数を下端にして等間隔に置く。
    *
-   * **前の時点を持たない図では `values` に落とす**。 引く相手がいないので、増減を出すと
-   * 「0 から増えた」 という書いていない主張になる (前を持たない件を 0 から立ち上げるのは
-   * 線を引くための扱いで、前が 0 だったという意味ではない)。
+   * **系列が 1 本の図では割り算ができない**ので縦の中央に置く (尺の幅が 0 の時と同じ扱い)。
    */
-  const 形: ChartSlopeForm = 前あり && node.chartSlopeForm === "delta" ? "delta" : "values";
+  const 段のyを取る = (順位: number): number =>
+    系列たち.length > 1
+      ? 上端 + ((順位 - 1) / (系列たち.length - 1)) * (下端 - 上端)
+      : (上端 + 下端) / 2;
 
   /**
    * 増減の表記。 符号を前に付ける。
@@ -233,8 +276,9 @@ export function ChartSlopeNode({
       )}
 
       {系列たち.map((s, i) => {
-        const 左y = yを取る(s.前);
-        const 右y = yを取る(s.今);
+        // `rank` は縦の位置を順位の段にする (cdl#707)。 値の尺は使わない
+        const 左y = 形 === "rank" ? 段のyを取る(前の順位[i]!) : yを取る(s.前);
+        const 右y = 形 === "rank" ? 段のyを取る(今の順位[i]!) : yを取る(s.今);
         const 未解決 = s.未解決 ? "true" : undefined;
         return (
           <g key={`slope-${i}`}>

package/src/render/stage.tsx

@@ -28,6 +28,7 @@ export function CdlStage({
   laid,
   currentPhase,
   progress,
+  drawProgress,
   stateValues,
   debug,
   compact = false,
@@ -36,6 +37,13 @@ export function CdlStage({
   laid: LaidDiagram;
   currentPhase: CdlPhase | undefined;
   progress: number;
+  /**
+   * 描く動きが読む進み (cdl#711)。 曲線を通す前の値で、 経過時間そのものの割合。
+   *
+   * 書かない呼出は `progress` と同じ値になる = 曲線を通した進みで描く従来の形。
+   * 検査から直接呼ぶ経路が既に多数あり、 そこでは 2 つを分ける意味がない。
+   */
+  drawProgress?: number;
   stateValues: Record<string, string>;
   debug: boolean;
   compact?: boolean;
@@ -112,9 +120,15 @@ export function CdlStage({
     }
     return scales;
   }, [laid]);
-  // 描く対象から見た進み (cdl#570)。 `drawRatio` を書かない phase では `progress` と同値で、
+  /**
+   * 描く動きの素の進み (cdl#711)。 渡されなければ従来どおり曲線を通した進みを使う。
+   *
+   * **`??` で受ける** = 0 は正しい進み (段の始まり) なので、 偽としては落とせない。
+   */
+  const 描く素の進み = drawProgress ?? progress;
+  // 描く対象から見た進み (cdl#570)。 `drawRatio` を書かない phase では `描く素の進み` と同値で、
   // 描く速さを phase の長さから切り離すためだけに使う
-  const 描く進み = 描く進みに直す(progress, currentPhase?.drawRatio);
+  const 描く進み = 描く進みに直す(描く素の進み, currentPhase?.drawRatio);
   // 縦線の終点は全 lane で 1 つに揃える (等長保証)。 値の決め方と、 1 lane の異常が図全体から
   // 縦線を消していた形の対処は `uniformLifelineEndY` の説明。
   //
@@ -345,7 +359,7 @@ export function CdlStage({
             edge={edge}
             active={activeSet.has(edge.id)}
             drawing={矢印の出番.伸ばすか(edge.id)}
-            progress={progress}
+            progress={矢印の出番.伸ばすか(edge.id) ? 描く進み : progress}
             stateValues={stateValues}
           />
         ))}

package/src/render.tsx

@@ -133,6 +133,13 @@ export function CdlDiagramView({ diagram, laid: laidProp, hideHeader = false, hi
     : state.phaseIndex;
   const currentPhase = laid.phases[Math.max(0, phaseIdx)] ?? laid.phases[0];
   const progress = reduced ? 1 : state.phaseProgress;
+  /**
+   * 描く動きが読む進み (cdl#711)。 曲線を通さない = 経過時間そのものの割合。
+   *
+   * 線を引く動きに `easeOutQuint` を当てると前半に寄り、 折れ線の 5 点のうち 4 点が
+   * 292 ms の間に出る。 ペンの速さは一定であるほど「1 つずつ現れる」 が読める。
+   */
+  const drawProgress = reduced ? 1 : state.phaseLinearProgress;
 
   // state 値を計算 (現在 phase + これまでの phase の最終 tween 値を集約)
   const baseStateValues = computeStateValues(laid, phaseIdx, progress);
@@ -184,7 +191,7 @@ export function CdlDiagramView({ diagram, laid: laidProp, hideHeader = false, hi
       {/* interactive panel = input widget / formula readout / scroll readout (SVG の上に配置)、
           diagram に interactive primitive がなければ null (SSR / render 影響なし) */}
       {isInteractive && interactive.panel}
-      <CdlStage laid={laid} currentPhase={currentPhase} progress={progress} stateValues={stateValues} debug={debug} compact={hideHeader} svgRef={isInteractive ? interactive.svgRef : undefined} />
+      <CdlStage laid={laid} currentPhase={currentPhase} progress={progress} drawProgress={drawProgress} stateValues={stateValues} debug={debug} compact={hideHeader} svgRef={isInteractive ? interactive.svgRef : undefined} />
       {/* hideHeader + multi-phase 時、 phase indicator が消えると動きが読めないため
           mini indicator (dot 列 + 現在 phase title + badge) を bottom に追加 */}
       {hideHeader && !hideMiniPhaseIndicator && currentPhase && laid.phases.length > 1 && (

package/src/types.ts

@@ -483,18 +483,29 @@ export type CdlNode = {
    */
   chartPieForm?: ChartPieForm;
   /**
-   * chart-slope の見せ方 (cdl#702)。 右の列に何の数を出すかを決める。
+   * chart-slope の見せ方 (cdl#702 / cdl#707)。
    *
-   * - `values` ... 今の値
-   * - `delta` ... 増減 (`+40` / `-90`)
+   * | 値 | 縦の位置 | 左の列 | 右の列 |
+   * |---|---|---|---|
+   * | `values` | 値 | 前の値 | 今の値 |
+   * | `delta` | 値 | 前の値 | 増減 (`+40` / `-90`) |
+   * | `rank` | 順位の段 (等間隔) | 前の値 | 今の値 |
    *
-   * 左の列は どちらでも前の値。 `前 + 増減 = 今` なので、 `delta` でも今の値は足せば戻る。
+   * `values` と `delta` は縦の位置が同じで、右の列の字だけが違う。
+   * `前 + 増減 = 今` なので、 `delta` でも今の値は足せば戻る。
    * 3 つ目の数を足さないので、 名札の高さも線を引く幅も変わらない。
    *
+   * `rank` は **縦の位置** を変える (cdl#707)。 段を等間隔に置くので、線の交差が
+   * 順位の入れ替わりと 1 対 1 になり、水平線が「順位が動かなかった」 を意味する。
+   * 字は値のままにして、量が図から消えないようにしている。
+   *
+   * `rank` では「線の傾きが動いた量」 という読み方が成立しない (`+40` と `+30` が
+   * どちらも水平線になる)。 書いた図だけに効く割り切りで、量は字を読む。
+   *
    * 型の外の値は `values` として描く = 見せ方が決まらないより、既定の形が出る方がよい。
    *
-   * 前の時点を持たない図 (`previous` が 1 件も無い) は右の列そのものが無いため、
-   * この欄を書いても絵は変わらない。
+   * 前の時点を持たない図 (`previous` が 1 件も無い) は軸が 1 本で並べ替える相手が
+   * いないため、 この欄を書いても絵は変わらない。
    */
   chartSlopeForm?: ChartSlopeForm;
   /**
@@ -556,8 +567,8 @@ export type BoundEnum<T extends string> = T | (string & {});
 /** chart-pie の見せ方 (cdl#684)。 SSOT は `kinds/chart-pie.tsx` */
 export type ChartPieForm = "ring" | "arcs" | "table";
 
-/** chart-slope の見せ方 (cdl#702)。 SSOT は `kinds/chart-slope.tsx` */
-export type ChartSlopeForm = "values" | "delta";
+/** chart-slope の見せ方 (cdl#702 / cdl#707)。 SSOT は `kinds/chart-slope.tsx` */
+export type ChartSlopeForm = "values" | "delta" | "rank";
 
 export type ChartDatumPayload = {
   label: string;