@cardenelabs/dragon 0.7.0

package/examples/quick-start.md

@@ -0,0 +1,142 @@
+# dragon quick-start examples
+
+## 1. YAML DSL (人向け、 5 ブロック箇条書き)
+
+```yaml
+# examples/auth-flow.yaml
+タイトル: User Login
+種類: シーケンス
+登場人物: User, API, DB
+流れ:
+  - User → API: POST /login
+  - API → DB: SELECT credentials
+  - DB → API: rows (成功)
+  - API → User: 200 OK (成功)
+```
+
+TypeScript から:
+
+```tsx
+import { compileText, CdlDiagramView } from "@cardenelabs/dragon";
+import { readFileSync } from "node:fs";
+
+const dsl = readFileSync("examples/auth-flow.yaml", "utf-8");
+const diagram = compileText(dsl);
+
+export default function AuthFlow() {
+  return <CdlDiagramView diagram={diagram} />;
+}
+```
+
+## 2. JSON DSL (LLM / structured output 向け)
+
+```ts
+import { compileJson, CdlDiagramView } from "@cardenelabs/dragon";
+
+const spec = {
+  id: "auth-flow",
+  topic: "User Login",
+  kind: "sequence",
+  actors: ["User", "API", "DB"],
+  steps: [
+    { from: "User", to: "API", label: "POST /login" },
+    { from: "API", to: "DB", label: "SELECT credentials" },
+    { from: "DB", to: "API", label: "rows", tone: "success" },
+    { from: "API", to: "User", label: "200 OK", tone: "success" },
+  ],
+};
+
+const diagram = compileJson(spec);
+```
+
+## 3. flow (フローチャート)
+
+```yaml
+タイトル: 決済フロー
+種類: フロー
+ノード: 受注, 与信, 決済, 完了
+流れ:
+  - 受注 → 与信: カード確認
+  - 与信 → 決済: OK
+  - 決済 → 完了: 成功 (成功)
+```
+
+## 4. state machine (状態遷移)
+
+```yaml
+タイトル: TCP コネクション
+種類: 状態遷移
+状態: CLOSED, LISTEN, ESTABLISHED, CLOSE_WAIT
+遷移:
+  - CLOSED → LISTEN: passive open
+  - LISTEN → ESTABLISHED: SYN + ACK
+  - ESTABLISHED → CLOSE_WAIT: FIN
+  - CLOSE_WAIT → CLOSED: close
+```
+
+## 5. animated pipeline (rich layered animation)
+
+builder API を直接使う (cdl 経路)、 dragon YAML より細かい制御可能:
+
+```ts
+import { diagram, CdlDiagramView } from "@cardenelabs/cdl";
+
+const pipeline = diagram("pipeline", { topic: "ETL パイプライン" })
+  .lane("l1", { x: 0, width: 200 })
+  .lane("l2", { x: 220, width: 200 })
+  .lane("l3", { x: 440, width: 200 })
+  .state("p1", { initial: 0 })
+  .state("p2", { initial: 0 })
+  .state("p3", { initial: 0 })
+  .node("extract", {
+    lane: "l1", stack: 0, kind: "dyn-wave", title: "抽出",
+    subtitle: "{p1}%", w: 180, h: 240,
+    shape: { kind: "wave", level: "{p1}", amplitude: 100, frequency: 2.5, waveHeight: 10, fill: "#4e9dc4" },
+  })
+  .node("transform", {
+    lane: "l2", stack: 0, kind: "dyn-wave", title: "変換",
+    subtitle: "{p2}%", w: 180, h: 240,
+    shape: { kind: "wave", level: "{p2}", amplitude: 100, frequency: 2.5, waveHeight: 10, fill: "#4e9dc4" },
+  })
+  .node("load", {
+    lane: "l3", stack: 0, kind: "dyn-wave", title: "ロード",
+    subtitle: "{p3}%", w: 180, h: 240,
+    shape: { kind: "wave", level: "{p3}", amplitude: 100, frequency: 2.5, waveHeight: 10, fill: "#22c55e" },
+  })
+  .edge("extract", "transform", { label: "raw" })
+  .edge("transform", "load", { label: "clean" })
+  .phase("p1", { duration: 1500, title: "抽出中", body: "" }, (p) =>
+    p.activate("extract").tween("p1", 0, 100).badge("抽出")
+  )
+  .phase("p2", { duration: 1500, title: "変換中", body: "" }, (p) =>
+    p.activate("extract", "transform").tween("p2", 0, 100).badge("変換")
+  )
+  .phase("p3", { duration: 1500, title: "ロード完了", body: "" }, (p) =>
+    p.activate("extract", "transform", "load").tween("p3", 0, 100).badge("完了")
+  )
+  .build();
+
+export default function ETLPipeline() {
+  return <CdlDiagramView diagram={pipeline} />;
+}
+```
+
+## 6. catalog SPA で全実例閲覧
+
+https://github.com/cardene777/dragon の `apps/playground-spa` で 300+ 例が閲覧可能:
+
+- `/catalog/presets` — 定型テンプレート
+- `/catalog/cookbook` — 頻出レシピ
+- `/catalog/patterns` — 汎用構成パターン
+- `/catalog/primitives` — cdl の最小構成
+- `/catalog/text-dsl` — YAML/JSON 記法
+- `/catalog/animation` — 時間軸の物語
+- `/catalog/parts` — 合成用小部品
+- `/catalog/styles` — 線と色
+- `/catalog/interactive` — user 操作で動く要素
+
+## 参考
+
+- README: 全機能 overview
+- CHANGELOG: version 履歴
+- ISSUES: バグ報告 / 機能要望 https://github.com/cardene777/dragon/issues

package/package.json

@@ -0,0 +1,79 @@
+{
+  "name": "@cardenelabs/dragon",
+  "version": "0.7.0",
+  "description": "Dragon — Mermaid 感覚で animated SVG を生成する Text DSL。 cdl engine を内部利用。",
+  "license": "MIT",
+  "author": "cardene777",
+  "homepage": "https://github.com/cardene777/dragon",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/cardene777/dragon.git",
+    "directory": "packages/dragon"
+  },
+  "bugs": {
+    "url": "https://github.com/cardene777/dragon/issues"
+  },
+  "keywords": [
+    "dragon",
+    "diagram",
+    "animation",
+    "text-dsl",
+    "mermaid-alternative",
+    "svg-animation"
+  ],
+  "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"
+    },
+    "./schemas/diagram.json": "./src/schemas/diagram.json"
+  },
+  "files": [
+    "dist",
+    "src",
+    "examples",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit",
+    "test": "cd ../.. && vitest run packages/dragon",
+    "test:watch": "cd ../.. && vitest packages/dragon",
+    "lint": "tsc --noEmit",
+    "prepublishOnly": "pnpm run typecheck && pnpm run test && pnpm run build"
+  },
+  "dependencies": {
+    "@cardenelabs/cdl": "^0.5.0"
+  },
+  "peerDependencies": {
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    },
+    "react-dom": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/react": "^19.1.0",
+    "react": "^19.1.0",
+    "tsup": "^8.5.1",
+    "typescript": "^5.8.0"
+  }
+}

package/src/canvas-bounds.ts

@@ -0,0 +1,52 @@
+/**
+ * canvas pivot 新 spec 図境界計算 helper (dragon canvas pivot spec §diagram-boundary)。
+ *
+ * 図の bounding box (点線四角) を「構成パーツの外接矩形 + 余白」 で計算する SSOT。
+ * CDL の layout() を呼んで LaidDiagram.viewBox から外接矩形を取得し、 spec 準拠の 20px 余白を加える。
+ *
+ * 用途:
+ *   - dragon editor で drag 中の overlay が「図の中」 に入ったか判定 (spec §4 自動調整発動)
+ *   - dragon renderer で図 hover 時に dashed rect を描画 (spec 項目 4 の視覚 UI)
+ *   - PR-B 以降で drag / resize / snap 判定の base rect として参照
+ */
+
+import type { CdlDiagram, LaidDiagram } from "@cardenelabs/cdl";
+import { layout } from "@cardenelabs/cdl";
+
+/** 図境界の padding (SVG unit)、 spec §diagram-boundary で 20 と定めた */
+export const DIAGRAM_BOUNDARY_PADDING = 20;
+
+export type DiagramBoundingBox = {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+};
+
+/**
+ * CdlDiagram の外接矩形 + 20px 余白を計算する。
+ * layout() が返す LaidDiagram.viewBox は既に全 element を包む rect (右端 +80 / 下端 +80 の CDL 既定余白付き)。
+ * それにさらに spec 準拠の 20px を加えて figure 判定 buffer とする。
+ */
+export function computeDiagramBoundingBox(diag: CdlDiagram): DiagramBoundingBox {
+  const laid: LaidDiagram = layout(diag);
+  const vb = laid.viewBox;
+  return {
+    x: vb.x - DIAGRAM_BOUNDARY_PADDING,
+    y: vb.y - DIAGRAM_BOUNDARY_PADDING,
+    width: vb.w + DIAGRAM_BOUNDARY_PADDING * 2,
+    height: vb.h + DIAGRAM_BOUNDARY_PADDING * 2,
+  };
+}
+
+/**
+ * bbox 同士の重なり判定 (dragon canvas pivot spec §4 図内 drag 判定 SSOT)。
+ * user 明示 「1 部でも重なれば中」 = 交差面積 > 0 を判定。
+ */
+export function rectsOverlap(a: DiagramBoundingBox, b: DiagramBoundingBox): boolean {
+  const aRight = a.x + a.width;
+  const aBottom = a.y + a.height;
+  const bRight = b.x + b.width;
+  const bBottom = b.y + b.height;
+  return a.x < bRight && aRight > b.x && a.y < bBottom && aBottom > b.y;
+}

package/src/color.ts

@@ -0,0 +1,172 @@
+/**
+ * 色として読める値かの判定と、 図から外部参照を落とす処理 (#1004)。
+ *
+ * 図の中の文字列は最終的に SVG の属性になる。 色を塗る位置 (`fill` / `stroke` 等) に
+ * `url(https://example.invalid/x)` が入ると、 図を開いた人の環境からその URL へ要求が飛ぶ。
+ * 書き出した SVG を配布しても同じことが起きる。
+ *
+ * 入口は 1 つではない (状態の上書き / phase の `set` / 画面が直接書く背景色 / 埋め込んだ JSON)。
+ * 入口ごとに塞ぐと 1 つ見落とした時に穴が残るため、 **組み立ての最後に図全体を走査する**
+ * 出口の検査を置く。 入口側の判定 (`isColorValue`) は「正しい図を保つ」 ため、
+ * 出口の検査 (`stripExternalPaint`) は「漏れを塞ぐ」 ための二重の構えになっている。
+ */
+
+/**
+ * CSS の標準色名。
+ *
+ * 色名を色として扱わないと、 初期値に `red` を持つ状態が「色ではない」 判定になり、
+ * その状態への上書きが無検査で通る (実測で `fill="url(...)"` が生成された)。
+ * 逆に 16 進の初期値へ正当な `red` を書いた時に元の色へ戻る退行も起きる。
+ *
+ * 完全一致で照合する。 部分一致にすると `red; background:url(x)` のような形が通る。
+ */
+const CSS_COLOR_NAMES: ReadonlySet<string> = new Set([
+  "aliceblue", "antiquewhite", "aqua", "aquamarine", "azure", "beige", "bisque", "black",
+  "blanchedalmond", "blue", "blueviolet", "brown", "burlywood", "cadetblue", "chartreuse",
+  "chocolate", "coral", "cornflowerblue", "cornsilk", "crimson", "cyan", "darkblue", "darkcyan",
+  "darkgoldenrod", "darkgray", "darkgreen", "darkgrey", "darkkhaki", "darkmagenta",
+  "darkolivegreen", "darkorange", "darkorchid", "darkred", "darksalmon", "darkseagreen",
+  "darkslateblue", "darkslategray", "darkslategrey", "darkturquoise", "darkviolet", "deeppink",
+  "deepskyblue", "dimgray", "dimgrey", "dodgerblue", "firebrick", "floralwhite", "forestgreen",
+  "fuchsia", "gainsboro", "ghostwhite", "gold", "goldenrod", "gray", "green", "greenyellow",
+  "grey", "honeydew", "hotpink", "indianred", "indigo", "ivory", "khaki", "lavender",
+  "lavenderblush", "lawngreen", "lemonchiffon", "lightblue", "lightcoral", "lightcyan",
+  "lightgoldenrodyellow", "lightgray", "lightgreen", "lightgrey", "lightpink", "lightsalmon",
+  "lightseagreen", "lightskyblue", "lightslategray", "lightslategrey", "lightsteelblue",
+  "lightyellow", "lime", "limegreen", "linen", "magenta", "maroon", "mediumaquamarine",
+  "mediumblue", "mediumorchid", "mediumpurple", "mediumseagreen", "mediumslateblue",
+  "mediumspringgreen", "mediumturquoise", "mediumvioletred", "midnightblue", "mintcream",
+  "mistyrose", "moccasin", "navajowhite", "navy", "oldlace", "olive", "olivedrab", "orange",
+  "orangered", "orchid", "palegoldenrod", "palegreen", "paleturquoise", "palevioletred",
+  "papayawhip", "peachpuff", "peru", "pink", "plum", "powderblue", "purple", "rebeccapurple",
+  "red", "rosybrown", "royalblue", "saddlebrown", "salmon", "sandybrown", "seagreen", "seashell",
+  "sienna", "silver", "skyblue", "slateblue", "slategray", "slategrey", "snow", "springgreen",
+  "steelblue", "tan", "teal", "thistle", "tomato", "transparent", "turquoise", "violet", "wheat",
+  "white", "whitesmoke", "yellow", "yellowgreen",
+  // 塗らないことを表す値。 色ではないが、 色を書く位置に置ける正当な値
+  "none", "currentcolor",
+]);
+
+/**
+ * 色として読める値か。
+ *
+ * 状態の値は node の `fill` にそのまま入る。 そのため「色の状態を探す」 判定と
+ * 「上書きを受け入れるか」 の判定は同じ物差しでなければならない。 別々に持つと、
+ * 片方だけ直した時に片方が通してしまう。
+ *
+ * 通すのは 16 進の 3 形 (`#rgb` / `#rrggbb` / `#rrggbbaa`) と、 標準の色名。
+ * 桁数を絞るのは、 `#1234` のような半端な形を色として扱うと描画側の解釈に委ねる範囲が
+ * 広がるため。 見本のすべての色が 3 形に収まることは `parts-color-hex-format.test.ts` が検査している。
+ *
+ * `rgb(...)` / `hsl(...)` は通さない。 括弧を含む形を許すと、 括弧の中身を見る判定が要る。
+ * 見本のどのパーツも使っておらず、 通す理由が無い。
+ */
+export function isColorValue(v: unknown): v is string {
+  if (typeof v !== "string") return false;
+  const s = v.trim();
+  if (/^#([0-9a-fA-F]{3}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$/.test(s)) return true;
+  return CSS_COLOR_NAMES.has(s.toLowerCase());
+}
+
+/**
+ * 図の外側を指す値か。
+ *
+ * SVG の `url(...)` は図の中の定義 (`url(#gradient-1)`) も指せる。 これは正当な用途なので、
+ * 括弧の中が `#` で始まる形だけを残し、 それ以外を外向きとみなす。
+ *
+ * 空白と大文字小文字は無視する。 `URL( https://... )` のような書き方で判定を抜けられないため。
+ */
+export function pointsOutside(v: unknown): boolean {
+  if (typeof v !== "string") return false;
+  // 空白をすべて落としてから見る。 `url ( http...)` のように間に空白を挟む形も同じ扱いにする
+  const compact = v.replace(/\s+/g, "").toLowerCase();
+  const m = compact.match(/url\(([^)]*)/);
+  if (m) {
+    const inner = (m[1] ?? "").replace(/^["']/, "");
+    // 図の中の定義を指すものだけ残す
+    return !inner.startsWith("#");
+  }
+  // `url(` を伴わない直書きの参照。 属性によってはこの形でも読み込まれる
+  return /^(https?:)?\/\//.test(compact) || compact.startsWith("data:");
+}
+
+/** 色を塗る位置に使われる key。 ここに入る値は SVG の paint 属性になる */
+const PAINT_KEYS: ReadonlySet<string> = new Set([
+  "fill", "stroke", "color", "bg", "background",
+  "fillbind", "strokebind", "colorbind",
+  "stfill", "strokecolor", "fillcolor",
+]);
+
+/** 落とした時に入れる値。 「塗らない」 を表す SVG の正当な値 */
+const SAFE_PAINT = "none";
+
+/** 落とした場所と値。 呼出側が書いた人に知らせるために使う */
+export type StrippedPaint = { path: string; value: string };
+
+/**
+ * 図の中から、 色を塗る位置に入った外部参照を落とす。
+ *
+ * 対象は 2 種類ある。
+ *
+ * - 色を塗る key (`fill` / `stroke` / `bg` 等) の値
+ * - 状態の値 (`states[].initial` と、 phase が状態へ入れる値)。 状態は `{名前}` の形で
+ *   `fill` に差し込まれるため、 色を塗る位置に届く
+ *
+ * 説明文 (`title` / `subtitle` / `value` / `rows`) は対象外。 文字として出るだけで
+ * 属性にはならないため、 URL を書く正当な用途を壊さない。
+ *
+ * 図を直接書き換える (返り値ではなく引数を変える)。 組み立ての最後に 1 度だけ呼ぶ前提。
+ */
+export function stripExternalPaint(diagram: unknown): StrippedPaint[] {
+  const stripped: StrippedPaint[] = [];
+  walk(diagram, "", false, stripped);
+  return stripped;
+}
+
+/**
+ * 図の中を辿って外部参照を落とす。
+ *
+ * `inStateValue` = 今見ている場所が状態の値かどうか。 状態は key の名前が `initial` や
+ * 状態名そのもの (phase の `sets`) になるため、 key の名前だけでは色かどうか分からない。
+ * 「状態を入れる箱の中にいる」 ことを引き継いで判断する。
+ */
+function walk(node: unknown, path: string, inStateValue: boolean, out: StrippedPaint[]): void {
+  if (node === null || typeof node !== "object") return;
+
+  if (Array.isArray(node)) {
+    for (let i = 0; i < node.length; i++) {
+      walk(node[i], `${path}[${i}]`, inStateValue, out);
+    }
+    return;
+  }
+
+  const obj = node as Record<string, unknown>;
+  for (const [key, value] of Object.entries(obj)) {
+    const here = path ? `${path}.${key}` : key;
+    const lower = key.toLowerCase();
+    // 状態を入れる箱に入ったら、 その中の値はすべて状態の値として扱う
+    const nextInState = inStateValue || lower === "states" || lower === "sets" || lower === "tweens";
+
+    if (typeof value === "string") {
+      const isPaint = PAINT_KEYS.has(lower) || (nextInState && (lower === "initial" || lower === "to" || lower === "from" || !isReservedStateKey(lower)));
+      if (isPaint && pointsOutside(value)) {
+        obj[key] = SAFE_PAINT;
+        out.push({ path: here, value });
+      }
+      continue;
+    }
+    walk(value, here, nextInState, out);
+  }
+}
+
+/**
+ * 状態を入れる箱の中で、 値ではなく仕組みを表す key。
+ *
+ * phase の `sets` は「状態名: 値」 の形なので、 key の名前を列挙して除外できない。
+ * 代わりに、 状態の箱が持つ決まった名前 (`id` / `stateId` / `duration` 等) を除いた残りを
+ * 値とみなす。
+ */
+function isReservedStateKey(lowerKey: string): boolean {
+  return lowerKey === "id" || lowerKey === "stateid" || lowerKey === "duration" ||
+    lowerKey === "title" || lowerKey === "body" || lowerKey === "badge" || lowerKey === "kind";
+}