@cardenelabs/cdl 0.5.0

package/examples/quick-start.md

@@ -0,0 +1,88 @@
+# cdl quick-start examples
+
+cdl は engine 層 — 通常は [dragon](https://github.com/cardene777/dragon) 経由で使う。 但し builder API を直接使うと 細かい制御 (49 kind / dyn-shape / phase 制御 / interactive signal) が可能。
+
+## 1. シンプル sequence
+
+```tsx
+import { sequence, CdlDiagramView } from "@cardenelabs/cdl";
+
+const login = sequence({
+  id: "login",
+  topic: "User Login",
+  actors: ["User", "API", "DB"],
+})
+  .step({ from: "User", to: "API", label: "POST /login" })
+  .step({ from: "API", to: "DB", label: "SELECT" })
+  .step({ from: "DB", to: "API", label: "rows", tone: "success" })
+  .step({ from: "API", to: "User", label: "200 OK", tone: "success" })
+  .build();
+
+export default function Demo() {
+  return <CdlDiagramView diagram={login} />;
+}
+```
+
+## 2. dyn-wave gauge (液面 metaphor)
+
+```tsx
+import { diagram, CdlDiagramView } from "@cardenelabs/cdl";
+
+const tank = diagram("tank", { topic: "貯水タンク水位" })
+  .lane("l", { x: 0, width: 400 })
+  .state("water", { initial: 100 })
+  .node("t", {
+    lane: "l", stack: 0, kind: "dyn-wave", title: "タンク", subtitle: "{water}%",
+    w: 380, h: 400,
+    shape: { kind: "wave", level: "{water}", amplitude: 100, frequency: 2.5, waveHeight: 10, fill: "#4e9dc4" },
+  })
+  .phase("p1", { duration: 3000, title: "水位低下", body: "" }, (p) =>
+    p.activate("t").tween("water", 100, 30).badge("使用中")
+  )
+  .phase("p2", { duration: 2000, title: "補充", body: "" }, (p) =>
+    p.activate("t").tween("water", 30, 100).badge("満水")
+  )
+  .build();
+```
+
+## 3. interactive slider
+
+```tsx
+import { diagram, CdlDiagramView } from "@cardenelabs/cdl";
+
+const priceGauge = diagram("price", { topic: "価格 slider" })
+  .input.slider("price", { min: 0, max: 1000, defaultValue: 100, label: "価格" })
+  .lane("l", { x: 0, width: 400 })
+  .node("g", {
+    lane: "l", stack: 0, kind: "dyn-arc", title: "価格 gauge", subtitle: "{price} 円",
+    w: 380, h: 380,
+    shape: { kind: "arc", angle: "{price}", sweepMax: 1000, outerRadius: 140, innerRadius: 100, fill: "#4e9dc4" },
+  })
+  .phase("p", { duration: 3000, title: "slider で操作", body: "" }, (p) => p.activate("g"))
+  .build();
+```
+
+## 4. React に埋込み
+
+```tsx
+import { CdlDiagramView } from "@cardenelabs/cdl";
+// ...
+<CdlDiagramView diagram={myDiagram} hideHeader />  // header 非表示
+<CdlDiagramView diagram={myDiagram} debug />       // 座標 debug 表示
+```
+
+## 5. compile from JSON
+
+```ts
+import { compile, CdlDiagramView } from "@cardenelabs/cdl";
+
+const spec = { /* CdlDiagramSpec JSON */ };
+const diagram = compile(spec);
+```
+
+## 参考
+
+- SPEC.md: cdl 記法仕様書
+- README: 12 preset + shape kind 一覧
+- dragon: `@cardenelabs/dragon` — YAML/JSON 記法 wrapper
+- ISSUES: https://github.com/cardene777/cdl/issues

package/package.json

@@ -0,0 +1,79 @@
+{
+  "name": "@cardenelabs/cdl",
+  "version": "0.5.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",
+  "homepage": "https://github.com/cardene777/cdl",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/cardene777/cdl.git"
+  },
+  "bugs": {
+    "url": "https://github.com/cardene777/cdl/issues"
+  },
+  "keywords": [
+    "diagram",
+    "animation",
+    "svg",
+    "mermaid-alternative",
+    "solidity",
+    "solidity-diagram",
+    "blockchain",
+    "yaml-dsl",
+    "text-dsl",
+    "sequence-diagram",
+    "react",
+    "typescript"
+  ],
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./react": {
+      "types": "./dist/react.d.ts",
+      "import": "./dist/react.js",
+      "require": "./dist/react.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "examples",
+    "README.md",
+    "SPEC.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit",
+    "test": "cd ../.. && vitest run packages/cdl",
+    "lint": "tsc --noEmit",
+    "prepublishOnly": "pnpm run typecheck && pnpm run build"
+  },
+  "peerDependencies": {
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
+  },
+  "devDependencies": {
+    "@types/react": "^19.1.0",
+    "react": "^19.1.0",
+    "tsup": "^8.5.1",
+    "typedoc": "^0.28.19",
+    "typedoc-plugin-markdown": "^4.12.0",
+    "typescript": "^5.8.0"
+  }
+}

package/src/anim/core/easing.ts

@@ -0,0 +1,77 @@
+import type { EasingFn } from "./types";
+
+/**
+ * Cubic Bezier easing を 0..1 input から 0..1 output へ近似する自作実装。
+ * P0 = (0, 0)、 P3 = (1, 1) 固定、 P1 = (x1, y1)、 P2 = (x2, y2)。
+ *
+ * Newton-Raphson + binary subdivision で t を求める。
+ * tolerance = 1e-5 (60fps 描画には十分)
+ */
+export function cubicBezier(x1: number, y1: number, x2: number, y2: number): EasingFn {
+  const A = (a: number, b: number) => 1.0 - 3.0 * b + 3.0 * a;
+  const B = (a: number, b: number) => 3.0 * b - 6.0 * a;
+  const C = (a: number) => 3.0 * a;
+
+  const sampleCurveX = (t: number) => ((A(x1, x2) * t + B(x1, x2)) * t + C(x1)) * t;
+  const sampleCurveY = (t: number) => ((A(y1, y2) * t + B(y1, y2)) * t + C(y1)) * t;
+  const sampleDerivativeX = (t: number) =>
+    3.0 * A(x1, x2) * t * t + 2.0 * B(x1, x2) * t + C(x1);
+
+  function solveCurveX(x: number): number {
+    if (x <= 0) return 0;
+    if (x >= 1) return 1;
+    // Newton-Raphson 8 iterations
+    let t = x;
+    for (let i = 0; i < 8; i += 1) {
+      const currentX = sampleCurveX(t) - x;
+      if (Math.abs(currentX) < 1e-5) return t;
+      const currentSlope = sampleDerivativeX(t);
+      if (Math.abs(currentSlope) < 1e-5) break;
+      t -= currentX / currentSlope;
+    }
+    // Fallback to bisection
+    let lo = 0;
+    let hi = 1;
+    let guess = x;
+    while (lo < hi) {
+      const currentX = sampleCurveX(guess);
+      if (Math.abs(currentX - x) < 1e-5) return guess;
+      if (x > currentX) lo = guess;
+      else hi = guess;
+      guess = (hi - lo) / 2 + lo;
+    }
+    return guess;
+  }
+
+  return (t: number) => {
+    if (t <= 0) return 0;
+    if (t >= 1) return 1;
+    return sampleCurveY(solveCurveX(t));
+  };
+}
+
+/** Linear (no easing) */
+export const linear: EasingFn = (t) => t;
+
+/** Standard easings (CSS spec aligned) */
+export const easeInOut = cubicBezier(0.42, 0, 0.58, 1);
+export const easeOut = cubicBezier(0, 0, 0.58, 1);
+export const easeIn = cubicBezier(0.42, 0, 1, 1);
+
+/** "Spring out" feel without an actual spring solver, good for UI reveals */
+export const easeOutBack = cubicBezier(0.34, 1.56, 0.64, 1);
+
+/** Smooth deceleration; recommended default for phase transitions */
+export const easeOutQuint = cubicBezier(0.22, 1, 0.36, 1);
+
+/** Clamp a number to [0, 1] */
+export function clamp01(value: number): number {
+  if (value < 0) return 0;
+  if (value > 1) return 1;
+  return value;
+}
+
+/** Linear interpolation */
+export function lerp(start: number, end: number, t: number): number {
+  return start + (end - start) * t;
+}

package/src/anim/core/timeline.ts

@@ -0,0 +1,335 @@
+import { clamp01, easeOutQuint } from "./easing";
+import type {
+  EasingFn,
+  PhaseDescriptor,
+  PhaseId,
+  TimelineState,
+  TimelineStatus,
+} from "./types";
+
+/**
+ * 自作 Timeline
+ *
+ * 設計方針。
+ * - requestAnimationFrame ベースの単一 raf loop で進行
+ * - 「Phase 間の遷移」 のみが時系列、 Phase 内は同期 0..1 補間値を提供
+ * - Subscriber 一覧に毎フレームの状態を push、 view 側で interpolate して描画
+ * - 完全独立、 React / DOM 依存ゼロ (テスト + node でも動かせる作りに後で寄せる)
+ *
+ * 利用パターン (典型)。
+ *   const t = new Timeline([{ id: "call", label: "Call" }, ...]);
+ *   const unsub = t.subscribe((state) => { ... });
+ *   t.goto(0);  // Phase 0 へ
+ *   t.play();   // 自動進行開始
+ *   t.next();   // 1 つ進める
+ *   t.prev();   // 1 つ戻る
+ *   unsub();
+ *   t.destroy();
+ */
+
+export type TimelineOptions = {
+  /** 自動進行時の Phase 間 wait (ms)、 デフォルト Phase の durationMs に従う */
+  autoAdvanceMs?: number;
+  /** Phase 内補間の easing、 デフォルト easeOutQuint */
+  easing?: EasingFn;
+  /** loop 再生するか (settled 後に最初に戻る)、 デフォルト false */
+  loop?: boolean;
+  /** 初期 Phase index、 デフォルト 0 (= 最初の Phase) */
+  initialPhaseIndex?: number;
+  /** Phase 完了後、 次の Phase に進む前の hold ms (Phase の意味を見せる間)、 デフォルト 0 */
+  phaseHoldMs?: number;
+  /** loop 時、 最後の Phase が終わってから loop 先頭に戻るまでの wait ms、 デフォルト phaseHoldMs と同じ */
+  loopRestartDelayMs?: number;
+  /** mount 時に自動で再生開始するか、 デフォルト false */
+  autoplay?: boolean;
+};
+
+type Subscriber = (state: TimelineState) => void;
+
+export class Timeline {
+  private readonly phases: PhaseDescriptor[];
+  private readonly easing: EasingFn;
+  private readonly loop: boolean;
+  private readonly autoAdvanceMsOverride: number | undefined;
+  private readonly phaseHoldMs: number;
+  private readonly loopRestartDelayMs: number;
+  private readonly autoplay: boolean;
+  private readonly subscribers = new Set<Subscriber>();
+  private holdTimerHandle: ReturnType<typeof setTimeout> | null = null;
+
+  private rafHandle: number | null = null;
+  private phaseIndex = 0;
+  private phaseProgress = 0;
+  private phaseStartedAt = 0;
+  private status: TimelineStatus = "idle";
+  /**
+   * snapshot を「state が変わった時のみ」 新 object として返すためのキャッシュ。
+   * useSyncExternalStore は getSnapshot() の戻り値が前回と参照同値の時に
+   * re-render を skip する設計なので、 これがないと毎 frame 別 object で
+   * 無限 render → React #185 になる。
+   */
+  private cachedSnapshot: TimelineState | null = null;
+  /**
+   * constructor 直後の state snapshot。 destroy() で復元して StrictMode 二重 mount 経路の
+   * autostart() が正しく初期状態から再開できるようにする (initialPhaseIndex + autoplay 組合せ保持)。
+   */
+  private readonly initialState: {
+    phaseIndex: number;
+    phaseProgress: number;
+    status: TimelineStatus;
+  };
+
+  constructor(phases: PhaseDescriptor[], options: TimelineOptions = {}) {
+    if (phases.length === 0) {
+      throw new Error("Timeline requires at least one phase");
+    }
+    this.phases = phases;
+    this.easing = options.easing ?? easeOutQuint;
+    this.loop = options.loop ?? false;
+    this.autoAdvanceMsOverride = options.autoAdvanceMs;
+    this.phaseHoldMs = options.phaseHoldMs ?? 0;
+    this.loopRestartDelayMs = options.loopRestartDelayMs ?? this.phaseHoldMs;
+    this.autoplay = options.autoplay ?? false;
+
+    const initial = options.initialPhaseIndex;
+    if (initial != null && initial > 0 && initial < phases.length) {
+      this.phaseIndex = initial;
+      this.phaseProgress = 1;
+      this.status = initial === phases.length - 1 ? "settled" : "paused";
+    }
+    this.initialState = {
+      phaseIndex: this.phaseIndex,
+      phaseProgress: this.phaseProgress,
+      status: this.status,
+    };
+  }
+
+  /**
+   * mount 後に呼んで autoplay opt-in が真なら play を発火する。
+   * constructor で呼ぶと SSR 環境で rAF が動いて失敗するので別経路に分離。
+   */
+  autostart(): void {
+    if (this.autoplay && this.status === "idle") {
+      this.play();
+    }
+  }
+
+  // ─── public API ──────────────────────────────────────────────
+
+  subscribe(subscriber: Subscriber): () => void {
+    // 登録時に即時呼び出すと React 19 の useSyncExternalStore で
+    // Maximum update depth exceeded (#185) になるため、 同期呼び出しはしない。
+    // 初期値は subscribe 利用側が getSnapshot で取る契約。
+    this.subscribers.add(subscriber);
+    return () => {
+      this.subscribers.delete(subscriber);
+    };
+  }
+
+  snapshot(): TimelineState {
+    const cached = this.cachedSnapshot;
+    if (
+      cached &&
+      cached.status === this.status &&
+      cached.phaseIndex === this.phaseIndex &&
+      cached.phaseProgress === this.phaseProgress &&
+      cached.totalPhases === this.phases.length
+    ) {
+      return cached;
+    }
+    const next: TimelineState = {
+      status: this.status,
+      phaseIndex: this.phaseIndex,
+      phaseProgress: this.phaseProgress,
+      totalPhases: this.phases.length,
+    };
+    this.cachedSnapshot = next;
+    return next;
+  }
+
+  getPhase(): PhaseDescriptor {
+    // phaseIndex は constructor で phases.length >= 1 を保証しているため
+    // 必ず有効なインデックスを返す
+    const phase = this.phases[this.phaseIndex];
+    if (!phase) {
+      throw new Error(`Invalid phase index ${this.phaseIndex}`);
+    }
+    return phase;
+  }
+
+  /** Phase ID 指定でジャンプ (見つからない場合は no-op) */
+  gotoId(id: PhaseId): void {
+    const index = this.phases.findIndex((phase) => phase.id === id);
+    if (index >= 0) this.goto(index);
+  }
+
+  /** Phase index 指定でジャンプ */
+  goto(index: number): void {
+    const clamped = Math.max(0, Math.min(this.phases.length - 1, index));
+    this.cancelRaf();
+    this.phaseIndex = clamped;
+    this.phaseProgress = 1;
+    this.status = clamped === this.phases.length - 1 ? "settled" : "paused";
+    this.emit();
+  }
+
+  play(): void {
+    if (this.status === "playing") return;
+    this.status = "playing";
+    if (this.phaseProgress >= 1 && this.phaseIndex < this.phases.length - 1) {
+      this.advancePhase();
+    } else {
+      this.beginPhaseTransition();
+    }
+    this.emit();
+  }
+
+  pause(): void {
+    if (this.status !== "playing") return;
+    this.cancelRaf();
+    this.status = "paused";
+    this.emit();
+  }
+
+  next(): void {
+    if (this.phaseIndex >= this.phases.length - 1) {
+      if (this.loop) {
+        this.goto(0);
+        this.play();
+      }
+      return;
+    }
+    this.cancelRaf();
+    this.phaseIndex += 1;
+    this.beginPhaseTransition();
+    if (this.status !== "playing") {
+      this.status = "paused";
+    }
+    this.emit();
+  }
+
+  prev(): void {
+    if (this.phaseIndex <= 0) return;
+    this.cancelRaf();
+    this.phaseIndex -= 1;
+    this.phaseProgress = 1;
+    this.status = "paused";
+    this.emit();
+  }
+
+  reset(): void {
+    this.cancelRaf();
+    this.phaseIndex = 0;
+    this.phaseProgress = 0;
+    this.status = "idle";
+    this.emit();
+  }
+
+  /**
+   * cleanup + reset for-remount。 subscribers.clear() + cancelRaf() で active resource を
+   * 全解放した後、 (phaseIndex, phaseProgress, status) を constructor 直後の initialState に
+   * 復元する。 API 名は "destroy" だが object dead / GC-ready 契約ではなく、 destroy 後も
+   * subscribe / autostart / snapshot / play が正しく動作する reusable reset object として設計。
+   *
+   * 主 caller = React `useEffect` の cleanup で、 StrictMode の dev 二重 mount 経路で
+   * setup 再実行時に autostart() が正しく再発火するよう status を initialState に戻す。
+   *
+   * 詳細 = active edge が pathSubpath(d, 0) = "M x y" のみで空 line 描画される
+   * regression (dragon Issue #381) を防ぐため、 destroy() は「破棄」 でなく「再利用可能な reset」。
+   */
+  destroy(): void {
+    this.cancelRaf();
+    this.subscribers.clear();
+    this.status = this.initialState.status;
+    this.phaseIndex = this.initialState.phaseIndex;
+    this.phaseProgress = this.initialState.phaseProgress;
+  }
+
+  // ─── internals ───────────────────────────────────────────────
+
+  private advancePhase(): void {
+    if (this.phaseIndex >= this.phases.length - 1) {
+      if (this.loop) {
+        // 最後の Phase 完了 → 先頭に戻る (loopRestartDelayMs hold)
+        this.scheduleHold(this.loopRestartDelayMs, () => {
+          this.phaseIndex = 0;
+          this.beginPhaseTransition();
+        });
+      } else {
+        this.status = "settled";
+        this.emit();
+      }
+      return;
+    }
+    // 次 Phase へ (phaseHoldMs hold)
+    this.scheduleHold(this.phaseHoldMs, () => {
+      this.phaseIndex += 1;
+      this.beginPhaseTransition();
+    });
+  }
+
+  private scheduleHold(ms: number, after: () => void): void {
+    if (this.holdTimerHandle != null) {
+      clearTimeout(this.holdTimerHandle);
+      this.holdTimerHandle = null;
+    }
+    if (ms <= 0) {
+      after();
+      return;
+    }
+    this.holdTimerHandle = setTimeout(() => {
+      this.holdTimerHandle = null;
+      if (this.status === "playing") after();
+    }, ms);
+  }
+
+  private beginPhaseTransition(): void {
+    this.phaseProgress = 0;
+    this.phaseStartedAt = performance.now();
+    this.cancelRaf();
+    const step = (now: number) => {
+      const duration =
+        this.autoAdvanceMsOverride ?? this.getPhase().durationMs ?? 600;
+      const elapsed = now - this.phaseStartedAt;
+      const linearT = clamp01(elapsed / duration);
+      this.phaseProgress = this.easing(linearT);
+      this.emit();
+      if (linearT < 1) {
+        this.rafHandle = requestAnimationFrame(step);
+        return;
+      }
+      this.phaseProgress = 1;
+      this.emit();
+      if (this.status === "playing") {
+        // 自動進行中は次 Phase へ
+        if (this.phaseIndex < this.phases.length - 1) {
+          this.advancePhase();
+        } else if (this.loop) {
+          this.advancePhase();
+        } else {
+          this.status = "settled";
+          this.emit();
+        }
+      }
+    };
+    this.rafHandle = requestAnimationFrame(step);
+  }
+
+  private cancelRaf(): void {
+    if (this.rafHandle != null) {
+      cancelAnimationFrame(this.rafHandle);
+      this.rafHandle = null;
+    }
+    if (this.holdTimerHandle != null) {
+      clearTimeout(this.holdTimerHandle);
+      this.holdTimerHandle = null;
+    }
+  }
+
+  private emit(): void {
+    const snapshot = this.snapshot();
+    for (const subscriber of this.subscribers) {
+      subscriber(snapshot);
+    }
+  }
+}

package/src/anim/core/types.ts

@@ -0,0 +1,42 @@
+/**
+ * Phase = アニメーションの 1 ステップ。
+ * 学習用アニメーションは通常「処理が時系列で進む」 構成のため、
+ * 連続した時間軸ではなく、 ユーザーが任意で進める / 戻れる Phase 単位を採用する。
+ */
+export type PhaseId = string;
+
+export type PhaseDescriptor = {
+  id: PhaseId;
+  /** 表示名 (UI のタイムラインに出る短いラベル) */
+  label: string;
+  /** Phase の説明文 */
+  description?: string;
+  /** Phase の進入アニメ完了までの目安 ms。 デフォルト 600ms */
+  durationMs?: number;
+};
+
+/**
+ * 自作の easing 関数群。
+ * 入力 0..1 を受け取り 0..1 を返す。
+ */
+export type EasingFn = (t: number) => number;
+
+/**
+ * Timeline 内部状態。
+ * - status ... ユーザー操作の結果としての timeline の意図状態
+ *   - idle    ... 未開始 (まだ Phase 0 に未到達)
+ *   - playing ... 自動進行中
+ *   - paused  ... 自動進行を停止
+ *   - settled ... 全 Phase 終了して停止
+ */
+export type TimelineStatus = "idle" | "playing" | "paused" | "settled";
+
+export type TimelineState = {
+  status: TimelineStatus;
+  /** 現在 Phase index */
+  phaseIndex: number;
+  /** 現在 Phase 内の進行度 (0..1)、 視覚要素の補間に使う */
+  phaseProgress: number;
+  /** 全 Phase 数 */
+  totalPhases: number;
+};

package/src/anim/index.ts

@@ -0,0 +1,20 @@
+export { Timeline } from "./core/timeline";
+export type { TimelineOptions } from "./core/timeline";
+export type {
+  EasingFn,
+  PhaseDescriptor,
+  PhaseId,
+  TimelineState,
+  TimelineStatus,
+} from "./core/types";
+export {
+  clamp01,
+  cubicBezier,
+  easeIn,
+  easeInOut,
+  easeOut,
+  easeOutBack,
+  easeOutQuint,
+  lerp,
+  linear,
+} from "./core/easing";

package/src/anim/react/index.ts

@@ -0,0 +1,3 @@
+export { useTimeline } from "./useTimeline";
+export type { UseTimelineReturn } from "./useTimeline";
+export { useReducedMotion } from "./useReducedMotion";

package/src/anim/react/useReducedMotion.ts

@@ -0,0 +1,27 @@
+import { useSyncExternalStore } from "react";
+
+const MEDIA_QUERY = "(prefers-reduced-motion: reduce)";
+
+function getSnapshot(): boolean {
+  if (typeof window === "undefined" || !window.matchMedia) return false;
+  return window.matchMedia(MEDIA_QUERY).matches;
+}
+
+function subscribe(callback: () => void): () => void {
+  if (typeof window === "undefined" || !window.matchMedia) return () => {};
+  const mql = window.matchMedia(MEDIA_QUERY);
+  mql.addEventListener("change", callback);
+  return () => mql.removeEventListener("change", callback);
+}
+
+function getServerSnapshot(): boolean {
+  return false;
+}
+
+/**
+ * `prefers-reduced-motion: reduce` を react で購読する hook。
+ * true を返したら animation の duration を 0 にする / 即座に終端へ飛ばす等の対応を呼び出し側で行う。
+ */
+export function useReducedMotion(): boolean {
+  return useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot);
+}