@cardenelabs/cdl 0.5.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 cardene777
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,343 @@
+# @cardenelabs/cdl
+
+> Declarative TypeScript DSL for animated React + SVG diagrams. UML / ER / state machine / topology / sequence / flow を 1 行で書く OSS library。
+
+[![npm](https://img.shields.io/npm/v/@cardenelabs/cdl.svg)](https://www.npmjs.com/package/@cardenelabs/cdl)
+[![license](https://img.shields.io/npm/l/@cardenelabs/cdl.svg)](LICENSE)
+
+## Documentation
+
+| 目的 | リンク |
+|---|---|
+| **repo root** | [github.com/cardene777/cdl](https://github.com/cardene777/cdl) |
+| **5 分で動かす** | [README quickstart](#quickstart) (本 file 下部) |
+| **playground demo** | `pnpm dev` → http://localhost:4321 ([apps/playground](../../apps/playground/README.md)) |
+| **全 API + preset 一覧** | playground `/docs/reference` |
+| **Text DSL spec** | `apps/playground/src/content/cdl-docs/text-dsl-spec.md` |
+| **LLM prompt guide** | `apps/playground/src/content/cdl-docs/text-dsl-llm-guide.md` |
+| **contribute** | [CONTRIBUTING.md](../../CONTRIBUTING.md) |
+
+## なぜ cdl
+
+mermaid / PlantUML はテキストから静止画像を生成する。 cdl は **TypeScript → animated React + SVG component** で、 phase / state / tween / progress glow 等の動きを宣言的に書ける。
+
+| 形式 | mermaid | cdl |
+|---|---|---|
+| sequence | 静止 | animated + phase 切替 |
+| ER 図 | 静止 | animated + cardinality + sub label |
+| state diagram | 静止 | animated + initial/final marker + guard |
+| flow | 静止 | animated + dotted-flow 進行点 glow |
+| 構成図 / deployment | 限定的 | animated + container group + connection |
+| 自由レイアウト | 限定的 | lane + node + edge で自由構成 |
+
+## Quickstart
+
+```bash
+pnpm add @cardenelabs/cdl react react-dom
+```
+
+### diagram declare
+
+```ts
+import { sequence } from "@cardenelabs/cdl";
+
+export const authSeq = sequence({
+  id: "auth",
+  topic: "User Login",
+  actors: ["User", "API", "DB"],
+})
+  .step({ from: "User", to: "API", label: "POST /login", sub: "email + password" })
+  .step({ from: "API", to: "DB", label: "SELECT credentials" })
+  .step({ from: "DB", to: "API", label: "rows", tone: "success", style: "dotted-flow" })
+  .step({ from: "API", to: "User", label: "200 OK", sub: "JWT token", tone: "success" })
+  .build();
+```
+
+### React で render
+
+```tsx
+import { CdlDiagramView } from "@cardenelabs/cdl";
+import { authSeq } from "./auth-seq";
+
+export function AuthSequenceDemo() {
+  return <CdlDiagramView diagram={authSeq} />;
+}
+```
+
+これで UML sequence diagram が phase 切替 + state diff + 進行点 glow で animated に表示。
+
+## 6 つの preset
+
+低位 API (lane / node / edge 個別宣言) + 高位 preset (1 行で典型図生成)。
+
+### swimlane
+
+横並び 3 lane 自動配置 + slug 自動。
+
+```ts
+swimlane({ id, topic, lanes: ["送信元", "Contract", "出力"] })
+  .node("alice", { lane: "送信元", stack: 0, kind: "actor", title: "Alice" })
+  .node("fn", { lane: "Contract", stack: 0, kind: "function", title: "transfer(...)" })
+  .edge("alice", "fn", { id: "call", label: "call", tone: "accent", style: "dotted-flow" })
+  .build()
+```
+
+### flow
+
+1 lane 縦 stack、 前 step → 次 step 自動 edge。
+
+```ts
+flow({ id, topic, laneLabel: "Auth Flow", defaultTone: "teal" })
+  .step({ id: "user", kind: "person", title: "User" })
+  .step({ id: "api", kind: "api", title: "POST /login" }, "ログイン要求")
+  .step({ id: "db", kind: "database", title: "users 表" }, "credential 検証")
+  .build()
+```
+
+### sequence
+
+UML sequence diagram (actor lifeline + 時系列 message)。
+
+```ts
+sequence({ id, topic, actors: ["User", "API", "DB"] })
+  .step({ from: "User", to: "API", label: "POST /login" })
+  .step({ from: "API", to: "DB", label: "SELECT" })
+  .step({ from: "API", to: "User", label: "200 OK", tone: "success" })
+  .build()
+```
+
+### topology
+
+構成図 / deployment diagram (group + container + connection)。
+
+```ts
+topology({ id, topic })
+  .group("aws", { label: "AWS" })
+    .add({ id: "alb", kind: "service", title: "ALB" })
+    .add({ id: "ecs", kind: "service", title: "ECS Task" })
+    .add({ id: "rds", kind: "database", title: "RDS" })
+  .group("client", { label: "Client" })
+    .add({ id: "browser", kind: "frontend", title: "Browser" })
+  .connect("browser", "alb", { label: "HTTPS" })
+  .connect("ecs", "rds", { label: "TCP 5432", tone: "success" })
+  .build()
+```
+
+### er
+
+ER 図 (entity + cardinality)。
+
+```ts
+er({ id, topic })
+  .entity({ id: "user", title: "User", rows: ["id: PK", "email: string", "createdAt: timestamp"] })
+  .entity({ id: "order", title: "Order", rows: ["id: PK", "userId: FK", "total: number"] })
+  .relation({ from: "user", to: "order", cardinality: "1:N", label: "places" })
+  .build()
+```
+
+cardinality 6 種 ... `"1:1" | "1:N" | "N:1" | "N:M" | "0..1" | "1..*"`。
+
+### stateMachine
+
+FSM / workflow (state + transition trigger + guard)。
+
+```ts
+stateMachine({ id, topic })
+  .state({ id: "idle", title: "Idle", initial: true })
+  .state({ id: "loading", title: "Loading" })
+  .state({ id: "done", title: "Done", final: true })
+  .state({ id: "error", title: "Error" })
+  .transition({ from: "idle", to: "loading", trigger: "submit" })
+  .transition({ from: "loading", to: "done", trigger: "success", tone: "success" })
+  .transition({ from: "loading", to: "error", trigger: "fail", tone: "error" })
+  .transition({ from: "error", to: "idle", trigger: "retry", guard: "if attempts < 3" })
+  .build()
+```
+
+## 低位 API
+
+preset で表現しきれない自由レイアウトは低位 API で。
+
+```ts
+import { diagram } from "@cardenelabs/cdl";
+
+export const custom = diagram("custom", { topic: "Custom" })
+  .lane("left", { x: 0, width: 400 })
+  .lane("right", { x: 500, width: 400 })
+  .node("a", { lane: "left", stack: 0, kind: "actor", title: "Alice" })
+  .node("b", { lane: "right", stack: 0, kind: "function", title: "Bob" })
+  .edge("a", "b", { id: "e", label: "msg", tone: "accent", style: "solid" })
+  .state("counter", { initial: 0 })
+  .phase("p1", { duration: 1500, title: "Phase 1", body: "tween counter" },
+    (p) => p.activate("a", "b", "e").tween("counter", 0, 100).badge("running"))
+  .build();
+```
+
+## NodeKind 29 種
+
+| 系統 | kinds |
+|---|---|
+| 基本 5 | `actor` / `function` / `storage` / `event` / `card` |
+| 人系 5 | `person` / `user-group` / `admin` / `developer` / `external-user` |
+| インフラ 6 | `database` / `cache` / `queue` / `message-bus` / `cloud` / `cdn` |
+| アプリ系 6 | `service` / `api` / `frontend` / `backend` / `webhook` / `microservice` |
+| blockchain 8 | `wallet` / `validator` / `miner` / `blockchain-node` / `mempool` / `block` / `bridge-node` / `relayer` |
+| 暗号 / データ 4 | `signer` / `oracle` / `merkle-tree` / `decision` |
+
+各 kind は shape / color / icon が異なる。 基本 5 は専用 component、 残り 24 種は `GenericNode` で汎用描画。
+
+## EdgeStyle + Tone
+
+| EdgeStyle | 動き |
+|---|---|
+| `solid` | 実線 + 矢頭 marker、 progress 連動で path が伸びる |
+| `dotted-flow` | 点線 + 進行点 glow (3 重円) が path 上を流れる、 node 貫通自動判定 |
+
+| Tone | 色 (hex) | 用途 |
+|---|---|---|
+| `accent` | `#c17f3e` | default |
+| `teal` | `#4a8b7f` | 補助動作 |
+| `success` | `#6b9e5a` | 成功 path |
+| `error` | `#c15a4a` | 失敗 path |
+| `warning` | `#c9a23e` | 警告 |
+| `info` | `#5a8ec1` | 情報 |
+
+## phase / state / tween / set / badge
+
+phase 内で state を tween / set し、 badge を出す。
+
+```ts
+.state("amount", { initial: 0 })
+.state("status", { initial: "idle" })
+.phase("p1", { duration: 1800, title: "Phase 1", body: "tween + set" },
+  (p) => p
+    .activate("a", "b")
+    .tween("amount", 0, 100)    // 数値の線形補間
+    .set("status", "running")    // 文字列の即時切替
+    .badge("processing"))         // header に badge 表示
+```
+
+state placeholder は node の `title` / `subtitle` / `eyebrow` / `value` 内で `{stateId}` 記法で参照。
+
+```ts
+.node("a", { lane: "l", stack: 0, kind: "function", title: "Process", subtitle: "status: {status}" })
+```
+
+phase 切替に連動して `status: idle` → `status: running` のように描画される。
+
+## CdlDiagramView props
+
+```ts
+<CdlDiagramView
+  diagram={d}
+  hideHeader={false}   // header (phase indicator + state diff) 表示
+  focusPhaseId="p1"    // 特定 phase に固定 (autoplay は維持)
+  debug={false}        // bbox + collision を半透明で重ね描き (開発用)
+/>
+```
+
+## 見た目を当てる (role selector)
+
+cdl は形だけを描き、 色や影は持たない (geometry only、 style 不干渉、 CAR-643 SSOT)。
+描かれる各部品には `data-cdl-role` が付くので、 consumer app 側が selector で見た目を当てる。
+
+```css
+[data-cdl-role="node-body"] {
+  fill: #ffffff;
+  stroke: #57534b;
+  stroke-width: 1.75;
+}
+```
+
+明暗の切替は consumer 側の仕組み (`html` の class 等) で行う = cdl は明暗の概念を持たない。
+
+**`CdlRole` 型は実装にある role の全部ではない**。 実装には 33 種の role があり、
+型に載っているのは 13 種。 残り 20 種 (`chart-line` / `tree-edge` / `funnel-stage` /
+`edge-glow` 等) は型を持たないが、 属性は付くので selector は書ける。
+
+型の内外は「共通か kind 固有か」 では分かれていない (共通の描画で使う `edge-glow` が型の外に
+あり、 放射状の図でしか使わない `mind-radial-halo` が型の中にある)。 **型に載っているかどうかは
+selector を書けるかとは無関係**なので、 一覧が要る時は source を `data-cdl-role=` で検索する。
+
+role が付かない小さな部品もある (kind が自前で描く目盛や軸など)。 それらは CSS 変数で色を渡す。
+
+```css
+:root {
+  --cdl-node-fill: #f2f1ec;
+  --cdl-text: #191714;
+  --cdl-tone-accent: #2c68ae;
+}
+```
+
+## CdlDiagramThumbnail
+
+thumbnail として表示、 click で viewport いっぱい (94vw x 94vh) のモーダルで拡大。
+
+```tsx
+import { CdlDiagramThumbnail } from "@cardenelabs/cdl";
+
+<CdlDiagramThumbnail diagram={d} hideHeader />
+```
+
+close は Escape / 背景クリック / × の 3 経路。
+
+## Architecture
+
+```
+src/
+├── builder.ts        — DSL builder
+├── compile.ts        — DSL → CdlDiagram normalization
+├── validate.ts       — schema validation
+├── layout/           — layout engine (6 file)
+│   ├── tokens.ts     — DESIGN TOKENS SSOT
+│   ├── lanes.ts      — lane 配置 + auto width
+│   ├── nodes.ts      — node cy/cx/w/h 確定
+│   ├── edges.ts      — orthogonal routing + label
+│   ├── collisions.ts — bbox + clearance + Liang-Barsky
+│   └── viewbox.ts    — auto viewBox 計算
+├── render/           — React + SVG (7 file)
+│   ├── stage.tsx     — SVG defs + 3 pass
+│   ├── nodes.tsx     — NodeKind 別 switch
+│   ├── edges.tsx     — solid / dotted-flow
+│   ├── header.tsx    — phase indicator + state diff
+│   ├── utils.ts      — interpolate / pathSubpath / shrinkPathEnd
+│   └── tone.ts       — TONE 6 色
+├── kinds/            — 専用 component (actor/function/storage/event/card/generic)
+├── presets.ts        — 6 preset
+├── thumbnail.tsx     — モーダル拡大
+└── types.ts          — public types
+```
+
+## Testing
+
+```sh
+pnpm test
+```
+
+vitest で 36 test (builder / compile / layout / sequence preset / snapshot) を実行、 全 pass 確認。
+
+## Performance baseline
+
+`packages/cdl/test/bench.test.ts` の vitest bench で 5 case (small / medium / large / huge / animation-heavy) × 3 stage (parse / compile / layout) を計測する。
+
+```sh
+pnpm --filter @cardenelabs/cdl exec vitest bench --run
+```
+
+baseline (mean ms、 Apple Silicon / node 24)。
+
+| case (node / edge / phase) | parse | compile | layout (旧) | layout (最適化後) |
+| --- | --- | --- | --- | --- |
+| small (10 / 5 / 0) | 0.002 | 0.020 | 0.260 | **0.192** |
+| medium (100 / 50 / 5) | 0.022 | 1.488 | 25.014 | **0.807** |
+| large (500 / 200 / 20) | 0.092 | 29.953 | 492.96 | **11.63** |
+| huge (1000 / 500 / 50) | 0.200 | 129.88 | 2424.39 | **53.74** |
+| animation-heavy (100 node / 100 phase / 50 tween) | 0.105 | 1.582 | 24.586 | **0.819** |
+
+最適化内容 ... `detectCollisions` / `detectNearCollisions` を全 pair O(n²) から spatial hash (cell size 200px、 max clearance 70px margin) に変更。 巨大 bbox (edge-path 等) は fallback 経路で全件比較。 huge case で約 46x 高速化、 1000 node でも 60ms 以下で完了。
+
+stage 内訳。 parse = `parseTextDslV05` (Text DSL → DslDocument)、 compile = `compileToCdl` (DslDocument → CdlDiagram)、 layout = `layout` (CdlDiagram → LaidDiagram)。 raw 出力は `.context/scratch/bench-baseline.{txt,json}` (vitest `--outputJson` 形式)。
+
+## License
+
+MIT