@cardenelabs/cdl 0.36.0 → 0.38.0

package/CHANGELOG.md

@@ -5,6 +5,50 @@ CDL (Chainome Diagram Language) の主要変更履歴。
 
 ## [Unreleased]
 
+## [0.38.0] - 2026-09-07
+
+### Fixed
+
+- **図を描く動きが前半に寄って読めないのを直した** (#711)
+
+  段の進みは `easeOutQuint` を通っており、`1.2s` の段で半分に達するのが 158 ms だった
+  (直線なら 600 ms)。 値が落ち着く動きには合う曲線だが、線を引く動きはペンの速さなので、
+  同じ曲線を当てると飛び出して這う。
+
+  折れ線は線の先が点に届いた時に値の字を出すが、5 点のうち 4 点が 292 ms の間に出て、
+  最後の 1 点まで 908 ms 空いていた。「1 つずつ現れる」 という読ませ方が成立していない。
+
+  `Timeline` が曲げる前の進み (`phaseLinearProgress`) も持つようにし、描く動き
+  (`draw` の node と、その段で初めて出る矢印) だけがそれを読む。 値の補間は今までどおり
+  曲げた進みで動く。
+
+  直線にしたのは、5 点が等間隔の時刻に出る唯一の曲線だったため (実測 = 直線 294 ms 間隔、
+  `easeOut` は 188 / 219 / 275 / 518、`easeInOut` は真ん中の 3 点が寄る)。
+
+  `drawRatio` も直っている。 曲げた進みで割っていたため `0.4` と書くと段の 4.8% で
+  描き終わっていた。 これからは書いた割合が実時間の割合になる。
+
+## [0.37.0] - 2026-09-07
+
+### Added
+
+- **傾き図に縦の位置を順位にする見せ方を足した** (#707)
+
+  `chartSlopeForm` に `rank` を書くと、縦の位置が値ではなく順位の段 (等間隔) になる。
+
+  この図は「線の交差が順位の入れ替わり」 を読ませるが、縦の位置は値なので交差点の位置が
+  順位と噛み合わなかった。 どの交差が本当に順位を変えた交差なのかは、値を読み比べないと
+  決まらない。
+
+  段を等間隔に置くと交差が入れ替わりと 1 対 1 になり、水平線が「順位が動かなかった」 を
+  意味する。 軸の脇の字は値のままにして、量が図から消えないようにしている。
+
+  `rank` では「線の傾きが動いた量」 が成立しない (`+40` と `+30` がどちらも水平線)。
+  書いた図だけに効く割り切りで、量は字を読む。
+
+  同じ値の系列は同じ段に重なる。 系列が 1 本の図は縦の中央に置く。
+  前の時点を持たない図と型の外の値は今までどおり `values` として描く。
+
 ## [0.36.0] - 2026-09-07
 
 ### Added
@@ -1696,7 +1740,9 @@ Initial OSS release.
 使わない = annotated tag を push しても GitHub Release は作られず、 Release を作っていない版で
 行き止まりになる。
 
-[Unreleased]: https://github.com/cardene777/cdl/compare/v0.36.0...HEAD
+[Unreleased]: https://github.com/cardene777/cdl/compare/v0.38.0...HEAD
+[0.38.0]: https://github.com/cardene777/cdl/compare/v0.37.0...v0.38.0
+[0.37.0]: https://github.com/cardene777/cdl/compare/v0.36.0...v0.37.0
 [0.36.0]: https://github.com/cardene777/cdl/compare/v0.35.0...v0.36.0
 [0.35.0]: https://github.com/cardene777/cdl/compare/v0.34.0...v0.35.0
 [0.34.0]: https://github.com/cardene777/cdl/compare/v0.33.0...v0.34.0

package/README.md

@@ -297,28 +297,51 @@ phase 切替に連動して `status: idle` → `status: running` のように描
 値だけに字体を当てられるようにするため。
 系列の名前はその線と同じ色で描く。 線を目で辿らずに名前と線の対応が取れる。
 
-### 右の列に何を出すか
+### 傾き図の見せ方
 
-`chart-slope` は `chartSlopeForm` で右の列の中身を選ぶ。 欄を書かない図は `values` と同じ。
+`chart-slope` は `chartSlopeForm` で見せ方を選ぶ。 欄を書かない図は `values` と同じ。
 
-| 値 | 右の列 | 向くもの |
-|---|---|---|
-| `values` (既定) | 今の値 | 2 時点の水準をそれぞれ読ませたい図 |
-| `delta` | 増減 (`+40` / `-90`) | どれがどれだけ動いたかを読ませたい図 |
+| 値 | 縦の位置 | 右の列 | 向くもの |
+|---|---|---|---|
+| `values` (既定) | 値 | 今の値 | 2 時点の水準をそれぞれ読ませたい図 |
+| `delta` | 値 | 増減 (`+40` / `-90`) | どれがどれだけ動いたかを読ませたい図 |
+| `rank` | 順位の段 (等間隔) | 今の値 | 順位の入れ替わりを読ませたい図 |
 
 ```ts
 .node("move", { lane: "l", stack: 0, kind: "chart-slope", chartSlopeForm: "delta", chartData: [...] })
 ```
 
-左の列はどちらでも前の値。 `前 + 増減 = 今` なので `delta` でも今の値は足せば戻る。
+左の列はどれでも前の値。
+
+#### `delta` は右の列だけを変える
+
+`前 + 増減 = 今` なので `delta` でも今の値は足せば戻る。
 3 つ目の数を足さないので、 名札の高さも線を引く幅も変わらない。
 
-`delta` の増減は `chart-slope-delta` で出す。 今の値とは意味が違い、 消費側が増減だけに色を
+増減は `chart-slope-delta` で出す。 今の値とは意味が違い、 消費側が増減だけに色を
 当てられるようにするため。 engine 側では色を分けない = 系列の色を名前に当てているので、
 増減にも色を当てると 1 つの図に 2 つの色の体系が混ざる。 向きは符号が持つ。
 
+#### `rank` は縦の位置を変える
+
+段を等間隔に置くので、 **線の交差が順位の入れ替わりと 1 対 1** になり、 水平線が
+「順位が動かなかった」 を意味する。 既定 (値の尺) では交差点の位置が順位と噛み合わず、
+どの交差が本当に順位を変えた交差なのかは値を読み比べないと決まらない。
+
+軸の脇の字は値のまま。 字も順位にすると `380 → 420` と `60 → 90` がどちらも同じ水平線に
+なり、 量が図から完全に消える。 位置が順位を、 字が量を担う。
+
+**`rank` では「線の傾きが動いた量」 が成立しない**。 `+40` と `+30` がどちらも水平線に
+なるので、 量は字を読む。
+
+同じ値の系列は同じ段に重なる = 無理に 1 つずつずらすと、 書いていない差を絵が主張する。
+系列が 1 本の図は段が 1 つしか無いので縦の中央に置く。
+
+#### どの形でも同じ扱い
+
 型の外の値を書いた図は `values` として描く。
-前の時点を持たない図も `values` として描く = 引く相手がいないため。
+前の時点を持たない図も `values` として描く = `delta` は引く相手がいないため、
+`rank` は軸が 1 本で並べ替える相手がいないため。
 
 ## 円グラフの見せ方
 

package/dist/index.cjs

@@ -14158,6 +14158,8 @@ var Timeline = class {
   rafHandle = null;
   phaseIndex = 0;
   phaseProgress = 0;
+  /** 曲線を通す前の進み (cdl#711)。 経過時間そのものの割合で、 描く動きが読む */
+  phaseLinearProgress = 0;
   phaseStartedAt = 0;
   status = "idle";
   /**
@@ -14186,12 +14188,12 @@ var Timeline = class {
     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
     };
   }
@@ -14213,13 +14215,14 @@ var Timeline = class {
   }
   snapshot() {
     const cached = this.cachedSnapshot;
-    if (cached && cached.status === this.status && cached.phaseIndex === this.phaseIndex && cached.phaseProgress === this.phaseProgress && cached.totalPhases === this.phases.length) {
+    if (cached && cached.status === this.status && cached.phaseIndex === this.phaseIndex && cached.phaseProgress === this.phaseProgress && cached.phaseLinearProgress === this.phaseLinearProgress && cached.totalPhases === this.phases.length) {
       return cached;
     }
     const next = {
       status: this.status,
       phaseIndex: this.phaseIndex,
       phaseProgress: this.phaseProgress,
+      phaseLinearProgress: this.phaseLinearProgress,
       totalPhases: this.phases.length
     };
     this.cachedSnapshot = next;
@@ -14242,7 +14245,7 @@ var Timeline = class {
     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();
   }
@@ -14282,14 +14285,14 @@ var Timeline = class {
     if (this.phaseIndex <= 0) return;
     this.cancelRaf();
     this.phaseIndex -= 1;
-    this.phaseProgress = 1;
+    this.setProgress(1);
     this.status = "paused";
     this.emit();
   }
   reset() {
     this.cancelRaf();
     this.phaseIndex = 0;
-    this.phaseProgress = 0;
+    this.setProgress(0);
     this.status = "idle";
     this.emit();
   }
@@ -14310,7 +14313,7 @@ var Timeline = class {
     this.subscribers.clear();
     this.status = this.initialState.status;
     this.phaseIndex = this.initialState.phaseIndex;
-    this.phaseProgress = this.initialState.phaseProgress;
+    this.setProgress(this.initialState.phaseLinearProgress);
   }
   // ─── internals ───────────────────────────────────────────────
   advancePhase() {
@@ -14346,20 +14349,20 @@ var Timeline = class {
     }, ms);
   }
   beginPhaseTransition() {
-    this.phaseProgress = 0;
+    this.setProgress(0);
     this.phaseStartedAt = performance.now();
     this.cancelRaf();
     const step = (now) => {
       const duration = 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") {
         if (this.phaseIndex < this.phases.length - 1) {
@@ -14374,6 +14377,19 @@ var Timeline = class {
     };
     this.rafHandle = requestAnimationFrame(step);
   }
+  /**
+   * 段の進みを 2 つ同時に置く (cdl#711)。
+   *
+   * **代入する場所を 1 つに閉じる**。 曲げた進みと曲げる前の進みを別々に書くと、
+   * どちらかを更新し忘れた経路が「前の段の値のまま」 で残る。
+   *
+   * 両端 (0 と 1) は曲線を通さず、 そのまま置く。 曲線は差し替えられる欄なので、
+   * `easing(1)` が 1 を返す保証がない。 段の始まりと終わりの値は曲線に委ねない。
+   */
+  setProgress(linear2) {
+    this.phaseLinearProgress = linear2;
+    this.phaseProgress = linear2 <= 0 ? 0 : linear2 >= 1 ? 1 : this.easing(linear2);
+  }
   cancelRaf() {
     if (this.rafHandle != null) {
       cancelAnimationFrame(this.rafHandle);
@@ -25527,7 +25543,12 @@ function ChartSlopeNode({
   const \u4E0A\u7AEF = PAD + (\u524D\u3042\u308A ? \u6642\u70B9\u306E\u7D1A + 12 : 0) + 6;
   const \u4E0B\u7AEF = Math.max(\u4E0A\u7AEF + 10, node.h - PAD - 6);
   const y\u3092\u53D6\u308B = (v) => \u5C3A\u306E\u5E45 > 0 ? \u4E0B\u7AEF - (v - \u6700\u5C0F) / \u5C3A\u306E\u5E45 * (\u4E0B\u7AEF - \u4E0A\u7AEF) : (\u4E0A\u7AEF + \u4E0B\u7AEF) / 2;
-  const \u5F62 = \u524D\u3042\u308A && node.chartSlopeForm === "delta" ? "delta" : "values";
+  const \u66F8\u3044\u305F\u5F62 = node.chartSlopeForm;
+  const \u5F62 = \u524D\u3042\u308A && (\u66F8\u3044\u305F\u5F62 === "delta" || \u66F8\u3044\u305F\u5F62 === "rank") ? \u66F8\u3044\u305F\u5F62 : "values";
+  const \u9806\u4F4D\u3092\u53D6\u308B = (v, \u5168\u90E8) => \u5168\u90E8.filter((x) => x > v).length + 1;
+  const \u524D\u306E\u9806\u4F4D = \u7CFB\u5217\u305F\u3061.map((s) => \u9806\u4F4D\u3092\u53D6\u308B(s.\u524D, \u7CFB\u5217\u305F\u3061.map((x) => x.\u524D)));
+  const \u4ECA\u306E\u9806\u4F4D = \u7CFB\u5217\u305F\u3061.map((s) => \u9806\u4F4D\u3092\u53D6\u308B(s.\u4ECA, \u7CFB\u5217\u305F\u3061.map((x) => x.\u4ECA)));
+  const \u6BB5\u306Ey\u3092\u53D6\u308B = (\u9806\u4F4D) => \u7CFB\u5217\u305F\u3061.length > 1 ? \u4E0A\u7AEF + (\u9806\u4F4D - 1) / (\u7CFB\u5217\u305F\u3061.length - 1) * (\u4E0B\u7AEF - \u4E0A\u7AEF) : (\u4E0A\u7AEF + \u4E0B\u7AEF) / 2;
   const \u5897\u6E1B\u8868\u8A18 = (\u524D, \u4ECA) => {
     const \u5DEE = \u4ECA - \u524D;
     return \u5DEE > 0 ? `+${\u5B9F\u5024\u8868\u8A18(\u5DEE)}` : \u5B9F\u5024\u8868\u8A18(\u5DEE);
@@ -25610,8 +25631,8 @@ function ChartSlopeNode({
       )
     ] }),
     \u7CFB\u5217\u305F\u3061.map((s, i) => {
-      const \u5DE6y = y\u3092\u53D6\u308B(s.\u524D);
-      const \u53F3y = y\u3092\u53D6\u308B(s.\u4ECA);
+      const \u5DE6y = \u5F62 === "rank" ? \u6BB5\u306Ey\u3092\u53D6\u308B(\u524D\u306E\u9806\u4F4D[i]) : y\u3092\u53D6\u308B(s.\u524D);
+      const \u53F3y = \u5F62 === "rank" ? \u6BB5\u306Ey\u3092\u53D6\u308B(\u4ECA\u306E\u9806\u4F4D[i]) : y\u3092\u53D6\u308B(s.\u4ECA);
       const \u672A\u89E3\u6C7A = s.\u672A\u89E3\u6C7A ? "true" : void 0;
       return /* @__PURE__ */ jsxRuntime.jsxs("g", { children: [
         \u524D\u3042\u308A && /* @__PURE__ */ jsxRuntime.jsx(
@@ -30642,6 +30663,7 @@ function CdlStage({
   laid,
   currentPhase,
   progress,
+  drawProgress,
   stateValues,
   debug,
   compact = false,
@@ -30699,7 +30721,8 @@ function CdlStage({
     }
     return scales;
   }, [laid]);
-  const \u63CF\u304F\u9032\u307F = \u63CF\u304F\u9032\u307F\u306B\u76F4\u3059(progress, currentPhase?.drawRatio);
+  const \u63CF\u304F\u7D20\u306E\u9032\u307F = drawProgress ?? progress;
+  const \u63CF\u304F\u9032\u307F = \u63CF\u304F\u9032\u307F\u306B\u76F4\u3059(\u63CF\u304F\u7D20\u306E\u9032\u307F, currentPhase?.drawRatio);
   const { lifelineStarts, uniformFooterTop } = react.useMemo(() => {
     const starts = lifelineStartYs(laid.nodes);
     return {
@@ -30878,7 +30901,7 @@ function CdlStage({
               edge,
               active: activeSet.has(edge.id),
               drawing: \u77E2\u5370\u306E\u51FA\u756A.\u4F38\u3070\u3059\u304B(edge.id),
-              progress,
+              progress: \u77E2\u5370\u306E\u51FA\u756A.\u4F38\u3070\u3059\u304B(edge.id) ? \u63CF\u304F\u9032\u307F : progress,
               stateValues
             },
             edge.id
@@ -31109,6 +31132,7 @@ function CdlDiagramView({ diagram: diagram2, laid: laidProp, hideHeader = false,
   const phaseIdx = focusPhaseId ? laid.phases.findIndex((p) => p.id === focusPhaseId) : state.phaseIndex;
   const currentPhase = laid.phases[Math.max(0, phaseIdx)] ?? laid.phases[0];
   const progress = reduced ? 1 : state.phaseProgress;
+  const drawProgress = reduced ? 1 : state.phaseLinearProgress;
   const baseStateValues = computeStateValues(laid, phaseIdx, progress);
   const isInteractive = hasInteractivePrimitives(diagram2);
   const interactive = useInteractiveIntegration(
@@ -31150,7 +31174,7 @@ function CdlDiagramView({ diagram: diagram2, laid: laidProp, hideHeader = false,
           }
         ),
         isInteractive && interactive.panel,
-        /* @__PURE__ */ jsxRuntime.jsx(CdlStage, { laid, currentPhase, progress, stateValues, debug, compact: hideHeader, svgRef: isInteractive ? interactive.svgRef : void 0 }),
+        /* @__PURE__ */ jsxRuntime.jsx(CdlStage, { laid, currentPhase, progress, drawProgress, stateValues, debug, compact: hideHeader, svgRef: isInteractive ? interactive.svgRef : void 0 }),
         hideHeader && !hideMiniPhaseIndicator && currentPhase && laid.phases.length > 1 && /* @__PURE__ */ jsxRuntime.jsxs("div", { className: "flex items-center justify-between gap-3 border-t border-[var(--cdl-divider,#d4d4d8)]/40 bg-[var(--cdl-stage-bg,#f1f5f9)]/50 px-3 py-2 text-xs", children: [
           /* @__PURE__ */ jsxRuntime.jsxs("div", { className: "flex items-center gap-1.5", children: [
             laid.phases.map((p, i) => /* @__PURE__ */ jsxRuntime.jsx(