@riebeckite/plugin-d2 0.0.12 → 0.0.13

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +129 -129
  2. package/README_ja.md +104 -104
  3. package/package.json +2 -2
package/README.md CHANGED
@@ -1,129 +1,129 @@
1
- # @riebeckite/plugin-d2
2
-
3
- D2 diagram rendering for ` ```d2 ` code blocks.
4
-
5
- [日本語](./README_ja.md)
6
-
7
- ## Overview
8
-
9
- `d2()` replaces D2 code blocks with a `<figure class="rb-d2">` that renders to
10
- SVG. Diagrams are rendered at build time by the D2 WebAssembly engine running in
11
- Node, with an automatic client-side fallback. It runs with `order: -10`.
12
-
13
- ## Usage
14
-
15
- ```ts
16
- import { defineConfig } from "@riebeckite/core";
17
- import { d2 } from "@riebeckite/plugin-d2";
18
-
19
- export default defineConfig({
20
- // ...
21
- plugins: [
22
- d2({
23
- render: "build",
24
- theme: { light: 0, dark: 1 },
25
- layout: "dagre",
26
- }),
27
- ],
28
- });
29
- ```
30
-
31
- ## Syntax
32
-
33
- ````markdown
34
- ```d2 title="Request flow"
35
- client -> server: request
36
- server -> database: query
37
- ```
38
- ````
39
-
40
- A caption can also be written as the first line of the block. D2 uses `#` for
41
- comments, so a leading `# caption: ...` line is treated as a caption and removed
42
- before rendering:
43
-
44
- ````markdown
45
- ```d2
46
- # caption: Request flow
47
- client -> server: request
48
- ```
49
- ````
50
-
51
- ## Behavior
52
-
53
- ### Build
54
-
55
- - Replaces each ` ```d2 ` `<pre>` with a `figure.rb-d2` containing:
56
- - `figcaption.rb-d2__caption` — from the code block title or a
57
- `# caption: ...` line
58
- - `div.rb-d2__canvas` — the diagram (`role="img"`, labelled by the caption
59
- when present)
60
- - `details.rb-d2__fallback` — collapsible diagram source
61
- - Static SVG is rendered at build time when `render` is `"build"` or `"both"`
62
- by running the D2.js WebAssembly engine (`@d2lang/d2`) directly in Node. No
63
- browser, network access, or system D2 binary is required.
64
- - The generated figure always carries `data-d2`, `data-d2-source`, and
65
- `data-d2-layout` attributes. `data-d2` is `rendered` when static SVG is
66
- present and `pending` when the client must take over.
67
- - Invalid diagrams report `ruleId: "invalid-diagram"`; renderer failures report
68
- `ruleId: "renderer-error"`. When build SVG is unavailable, the figure remains
69
- `data-d2="pending"` for client fallback.
70
-
71
- ### Client (`initD2Diagrams`)
72
-
73
- - Loads D2.js as an ESM module from jsDelivr unless `globalThis.d2` or an
74
- injected module is provided
75
- - Renders every `[data-d2="pending"]` figure; failures set `data-d2="error"`
76
- (placeholder message via CSS)
77
- - When `theme` is `{ light, dark }`, the theme is chosen from
78
- `html[data-theme]` or `prefers-color-scheme`
79
-
80
- ## Options
81
-
82
- | Option | Type | Default | Description |
83
- | ------ | ---- | ------- | ----------- |
84
- | `render` | `"build" \| "client" \| "both"` | `"build"` | When diagrams are rendered |
85
- | `theme` | `number \| { light: number; dark: number }` | `{ light: 0, dark: 1 }` | D2 theme id(s) |
86
- | `layout` | `"dagre" \| "elk"` | `"dagre"` | D2 layout engine |
87
- | `caption` | `boolean` | `true` | Show title / `# caption:` as `figcaption` |
88
- | `fallback` | `boolean` | `true` | Show the diagram source in `<details>` |
89
- | `className` | `string` | `"rb-d2"` | Base CSS class for the figure |
90
-
91
- `render` modes:
92
-
93
- - `"build"` — render SVG at build time; diagrams that fail fall back to client
94
- rendering
95
- - `"client"` — skip build-time rendering, render in the browser only
96
- - `"both"` — compatibility alias. It currently behaves like `"build"`: build
97
- first, then client fallback only when build rendering fails
98
-
99
- ## Offline requirements
100
-
101
- Build-time rendering is fully offline: `@d2lang/d2` ships a WebAssembly build
102
- that is loaded from `node_modules`. Client rendering (`render: "client"` or a
103
- build failure) downloads D2.js from jsDelivr; point `moduleUrl` at a self-hosted
104
- copy if the deployment has no outbound network access.
105
-
106
- ## Output hooks
107
-
108
- - Set `globalThis.d2` to a preloaded D2.js module to skip the CDN import.
109
- - Pass `api` and `moduleUrl` to `initD2Diagrams()` when calling it directly.
110
-
111
- ## Exports
112
-
113
- - `d2(options?)` — plugin factory (`d2Plugin` is an alias)
114
- - `initD2Diagrams` — client initializer
115
- - Types: `D2Options`, `D2ClientOptions`, `D2RenderMode`, `D2Layout`, `D2Theme`,
116
- `D2ModuleApi`
117
-
118
- ## Limitations
119
-
120
- - A diagram is rendered per build with a fresh D2 worker; very large batches pay
121
- the WASM startup cost repeatedly.
122
- - `layout: "elk"` uses D2's ELK engine, which is slower than `dagre`.
123
- - Multi-board and animated D2 output are not configured by this plugin.
124
- - The renderer is `@d2lang/d2` (MPL-2.0), the current package for the D2.js WASM
125
- build; `@terrastruct/d2` is its compatibility alias.
126
-
127
- ## See also
128
-
129
- - [Plugin guide](../../../docs/en/plugin-system.md)
1
+ # @riebeckite/plugin-d2
2
+
3
+ D2 diagram rendering for ` ```d2 ` code blocks.
4
+
5
+ [日本語](./README_ja.md)
6
+
7
+ ## Overview
8
+
9
+ `d2()` replaces D2 code blocks with a `<figure class="rb-d2">` that renders to
10
+ SVG. Diagrams are rendered at build time by the D2 WebAssembly engine running in
11
+ Node, with an automatic client-side fallback. It runs with `order: -10`.
12
+
13
+ ## Usage
14
+
15
+ ```ts
16
+ import { defineConfig } from "@riebeckite/core";
17
+ import { d2 } from "@riebeckite/plugin-d2";
18
+
19
+ export default defineConfig({
20
+ // ...
21
+ plugins: [
22
+ d2({
23
+ render: "build",
24
+ theme: { light: 0, dark: 1 },
25
+ layout: "dagre",
26
+ }),
27
+ ],
28
+ });
29
+ ```
30
+
31
+ ## Syntax
32
+
33
+ ````markdown
34
+ ```d2 title="Request flow"
35
+ client -> server: request
36
+ server -> database: query
37
+ ```
38
+ ````
39
+
40
+ A caption can also be written as the first line of the block. D2 uses `#` for
41
+ comments, so a leading `# caption: ...` line is treated as a caption and removed
42
+ before rendering:
43
+
44
+ ````markdown
45
+ ```d2
46
+ # caption: Request flow
47
+ client -> server: request
48
+ ```
49
+ ````
50
+
51
+ ## Behavior
52
+
53
+ ### Build
54
+
55
+ - Replaces each ` ```d2 ` `<pre>` with a `figure.rb-d2` containing:
56
+ - `figcaption.rb-d2__caption` — from the code block title or a
57
+ `# caption: ...` line
58
+ - `div.rb-d2__canvas` — the diagram (`role="img"`, labelled by the caption
59
+ when present)
60
+ - `details.rb-d2__fallback` — collapsible diagram source
61
+ - Static SVG is rendered at build time when `render` is `"build"` or `"both"`
62
+ by running the D2.js WebAssembly engine (`@d2lang/d2`) directly in Node. No
63
+ browser, network access, or system D2 binary is required.
64
+ - The generated figure always carries `data-d2`, `data-d2-source`, and
65
+ `data-d2-layout` attributes. `data-d2` is `rendered` when static SVG is
66
+ present and `pending` when the client must take over.
67
+ - Invalid diagrams report `ruleId: "invalid-diagram"`; renderer failures report
68
+ `ruleId: "renderer-error"`. When build SVG is unavailable, the figure remains
69
+ `data-d2="pending"` for client fallback.
70
+
71
+ ### Client (`initD2Diagrams`)
72
+
73
+ - Loads D2.js as an ESM module from jsDelivr unless `globalThis.d2` or an
74
+ injected module is provided
75
+ - Renders every `[data-d2="pending"]` figure; failures set `data-d2="error"`
76
+ (placeholder message via CSS)
77
+ - When `theme` is `{ light, dark }`, the theme is chosen from
78
+ `html[data-theme]` or `prefers-color-scheme`
79
+
80
+ ## Options
81
+
82
+ | Option | Type | Default | Description |
83
+ | ------ | ---- | ------- | ----------- |
84
+ | `render` | `"build" \| "client" \| "both"` | `"build"` | When diagrams are rendered |
85
+ | `theme` | `number \| { light: number; dark: number }` | `{ light: 0, dark: 1 }` | D2 theme id(s) |
86
+ | `layout` | `"dagre" \| "elk"` | `"dagre"` | D2 layout engine |
87
+ | `caption` | `boolean` | `true` | Show title / `# caption:` as `figcaption` |
88
+ | `fallback` | `boolean` | `true` | Show the diagram source in `<details>` |
89
+ | `className` | `string` | `"rb-d2"` | Base CSS class for the figure |
90
+
91
+ `render` modes:
92
+
93
+ - `"build"` — render SVG at build time; diagrams that fail fall back to client
94
+ rendering
95
+ - `"client"` — skip build-time rendering, render in the browser only
96
+ - `"both"` — compatibility alias. It currently behaves like `"build"`: build
97
+ first, then client fallback only when build rendering fails
98
+
99
+ ## Offline requirements
100
+
101
+ Build-time rendering is fully offline: `@d2lang/d2` ships a WebAssembly build
102
+ that is loaded from `node_modules`. Client rendering (`render: "client"` or a
103
+ build failure) downloads D2.js from jsDelivr; point `moduleUrl` at a self-hosted
104
+ copy if the deployment has no outbound network access.
105
+
106
+ ## Output hooks
107
+
108
+ - Set `globalThis.d2` to a preloaded D2.js module to skip the CDN import.
109
+ - Pass `api` and `moduleUrl` to `initD2Diagrams()` when calling it directly.
110
+
111
+ ## Exports
112
+
113
+ - `d2(options?)` — plugin factory (`d2Plugin` is an alias)
114
+ - `initD2Diagrams` — client initializer
115
+ - Types: `D2Options`, `D2ClientOptions`, `D2RenderMode`, `D2Layout`, `D2Theme`,
116
+ `D2ModuleApi`
117
+
118
+ ## Limitations
119
+
120
+ - A diagram is rendered per build with a fresh D2 worker; very large batches pay
121
+ the WASM startup cost repeatedly.
122
+ - `layout: "elk"` uses D2's ELK engine, which is slower than `dagre`.
123
+ - Multi-board and animated D2 output are not configured by this plugin.
124
+ - The renderer is `@d2lang/d2` (MPL-2.0), the current package for the D2.js WASM
125
+ build; `@terrastruct/d2` is its compatibility alias.
126
+
127
+ ## See also
128
+
129
+ - [Plugin guide](../../../docs/en/reference/plugin-api.md)
package/README_ja.md CHANGED
@@ -1,104 +1,104 @@
1
- # @riebeckite/plugin-d2
2
-
3
- ` ```d2 ` コードブロックを SVG の図として表示するプラグインです。既定ではビルド時に描画し、描画できなかった図だけをブラウザ側で再試行します。
4
-
5
- [English](./README.md)
6
-
7
- ## 設定する
8
-
9
- ```ts
10
- import { defineConfig } from "@riebeckite/core";
11
- import { d2 } from "@riebeckite/plugin-d2";
12
-
13
- export default defineConfig({
14
- // ...
15
- plugins: [
16
- d2({
17
- render: "build",
18
- theme: { light: 0, dark: 1 },
19
- layout: "dagre",
20
- }),
21
- ],
22
- });
23
- ```
24
-
25
- このプラグインは `order: -10` で実行されます。
26
-
27
- ## 記法
28
-
29
- ````markdown
30
- ```d2 title="リクエストの流れ"
31
- client -> server: request
32
- server -> database: query
33
- ```
34
- ````
35
-
36
- キャプションはコードブロックの先頭行にも書けます。D2 は `#` をコメントとして扱うため、先頭の `# caption: ...` 行をキャプションとして取り込み、描画前に取り除きます。
37
-
38
- ````markdown
39
- ```d2
40
- # caption: リクエストの流れ
41
- client -> server: request
42
- ```
43
- ````
44
-
45
- ## どのように描画されるか
46
-
47
- ### ビルド時
48
-
49
- ` ```d2 ` のコードブロックは `figure.rb-d2` に置き換わります。
50
-
51
- - `figcaption.rb-d2__caption`: コードブロックの title、または `# caption:` 行
52
- - `div.rb-d2__canvas`: 図本体（`role="img"`、キャプションがある場合はそれをラベルに使用）
53
- - `details.rb-d2__fallback`: 元の D2 記法を折りたたんで表示
54
-
55
- `render: "build"` または `"both"` では、D2.js の WebAssembly 版（`@d2lang/d2`）を Node 上で直接実行して静的な SVG を生成します。ブラウザ、ネットワーク接続、D2 本体のインストールはいずれも不要です。
56
-
57
- 生成される figure には常に `data-d2`、`data-d2-source`、`data-d2-layout` が付きます。`data-d2` は静的 SVG があれば `rendered`、クライアント側の描画に委ねる場合は `pending` になります。
58
-
59
- 構文エラーは `invalid-diagram`、描画環境の問題は `renderer-error` として区別して診断します。
60
-
61
- ### クライアント側
62
-
63
- `initD2Diagrams` は保留中の図だけを描画します。D2.js がなければ jsDelivr から ESM として読み込みます。描画に失敗した場合は `data-d2="error"` となり、CSS のプレースホルダー表示に切り替わります。
64
-
65
- 明暗別のテーマを指定した場合は、`html[data-theme]` を優先し、なければ OS の配色設定に従います。
66
-
67
- ## オプション
68
-
69
- | 項目 | 既定値 | 説明 |
70
- | --- | --- | --- |
71
- | `render` | `"build"` | `"build"`、`"client"`、`"both"` のいずれで描画するか |
72
- | `theme` | `{ light: 0, dark: 1 }` | D2 のテーマ ID、または明暗別のテーマ ID |
73
- | `layout` | `"dagre"` | D2 のレイアウトエンジン（`"dagre"` または `"elk"`） |
74
- | `caption` | `true` | タイトルまたは `# caption:` をキャプションとして表示する |
75
- | `fallback` | `true` | 元の D2 記法を `<details>` に残す |
76
- | `className` | `"rb-d2"` | figure に付ける基準クラス |
77
-
78
- `"client"` はビルド時の描画を行いません。`"both"` は後方互換の値で、現在は `"build"` と同じくビルドを優先し、失敗時だけクライアント側へ切り替えます。
79
-
80
- ## オフラインでの利用
81
-
82
- ビルド時の描画は完全にオフラインです。`@d2lang/d2` が同梱する WebAssembly を `node_modules` から読み込むだけで、外部通信は発生しません。クライアント側の描画（`render: "client"` またはビルド失敗時）は jsDelivr から D2.js を取得します。外部通信を避けたい場合は `moduleUrl` に自前でホストしたモジュールを指定してください。
83
-
84
- ## 出力のフック
85
-
86
- - `globalThis.d2` に読み込み済みの D2.js モジュールを設定すると、CDN からの読み込みを省略できます
87
- - `initD2Diagrams()` を直接呼ぶ場合は `api` と `moduleUrl` を渡せます
88
-
89
- ## 主なエクスポート
90
-
91
- - `d2(options?)`: プラグインを作成する（`d2Plugin` は別名）
92
- - `initD2Diagrams`: クライアント側の描画を初期化する
93
- - 型: `D2Options`、`D2ClientOptions`、`D2RenderMode`、`D2Layout`、`D2Theme`、`D2ModuleApi`
94
-
95
- ## 制限
96
-
97
- - 図ごとに新しい D2 ワーカーを起動するため、大量の図を含むビルドでは WASM の起動コストが繰り返し発生します
98
- - `layout: "elk"` は D2 の ELK エンジンを使うため `dagre` より遅くなります
99
- - マルチボードやアニメーション付きの出力はこのプラグインでは設定できません
100
- - レンダラーには `@d2lang/d2`（MPL-2.0）を使用しています。`@terrastruct/d2` はその後方互換パッケージです
101
-
102
- ## 関連資料
103
-
104
- - [プラグインシステム](../../../docs/ja/plugin-system.md)
1
+ # @riebeckite/plugin-d2
2
+
3
+ ` ```d2 ` コードブロックを SVG の図として表示するプラグインです。既定ではビルド時に描画し、描画できなかった図だけをブラウザ側で再試行します。
4
+
5
+ [English](./README.md)
6
+
7
+ ## 設定する
8
+
9
+ ```ts
10
+ import { defineConfig } from "@riebeckite/core";
11
+ import { d2 } from "@riebeckite/plugin-d2";
12
+
13
+ export default defineConfig({
14
+ // ...
15
+ plugins: [
16
+ d2({
17
+ render: "build",
18
+ theme: { light: 0, dark: 1 },
19
+ layout: "dagre",
20
+ }),
21
+ ],
22
+ });
23
+ ```
24
+
25
+ このプラグインは `order: -10` で実行されます。
26
+
27
+ ## 記法
28
+
29
+ ````markdown
30
+ ```d2 title="リクエストの流れ"
31
+ client -> server: request
32
+ server -> database: query
33
+ ```
34
+ ````
35
+
36
+ キャプションはコードブロックの先頭行にも書けます。D2 は `#` をコメントとして扱うため、先頭の `# caption: ...` 行をキャプションとして取り込み、描画前に取り除きます。
37
+
38
+ ````markdown
39
+ ```d2
40
+ # caption: リクエストの流れ
41
+ client -> server: request
42
+ ```
43
+ ````
44
+
45
+ ## どのように描画されるか
46
+
47
+ ### ビルド時
48
+
49
+ ` ```d2 ` のコードブロックは `figure.rb-d2` に置き換わります。
50
+
51
+ - `figcaption.rb-d2__caption`: コードブロックの title、または `# caption:` 行
52
+ - `div.rb-d2__canvas`: 図本体（`role="img"`、キャプションがある場合はそれをラベルに使用）
53
+ - `details.rb-d2__fallback`: 元の D2 記法を折りたたんで表示
54
+
55
+ `render: "build"` または `"both"` では、D2.js の WebAssembly 版（`@d2lang/d2`）を Node 上で直接実行して静的な SVG を生成します。ブラウザ、ネットワーク接続、D2 本体のインストールはいずれも不要です。
56
+
57
+ 生成される figure には常に `data-d2`、`data-d2-source`、`data-d2-layout` が付きます。`data-d2` は静的 SVG があれば `rendered`、クライアント側の描画に委ねる場合は `pending` になります。
58
+
59
+ 構文エラーは `invalid-diagram`、描画環境の問題は `renderer-error` として区別して診断します。
60
+
61
+ ### クライアント側
62
+
63
+ `initD2Diagrams` は保留中の図だけを描画します。D2.js がなければ jsDelivr から ESM として読み込みます。描画に失敗した場合は `data-d2="error"` となり、CSS のプレースホルダー表示に切り替わります。
64
+
65
+ 明暗別のテーマを指定した場合は、`html[data-theme]` を優先し、なければ OS の配色設定に従います。
66
+
67
+ ## オプション
68
+
69
+ | 項目 | 既定値 | 説明 |
70
+ | --- | --- | --- |
71
+ | `render` | `"build"` | `"build"`、`"client"`、`"both"` のいずれで描画するか |
72
+ | `theme` | `{ light: 0, dark: 1 }` | D2 のテーマ ID、または明暗別のテーマ ID |
73
+ | `layout` | `"dagre"` | D2 のレイアウトエンジン（`"dagre"` または `"elk"`） |
74
+ | `caption` | `true` | タイトルまたは `# caption:` をキャプションとして表示する |
75
+ | `fallback` | `true` | 元の D2 記法を `<details>` に残す |
76
+ | `className` | `"rb-d2"` | figure に付ける基準クラス |
77
+
78
+ `"client"` はビルド時の描画を行いません。`"both"` は後方互換の値で、現在は `"build"` と同じくビルドを優先し、失敗時だけクライアント側へ切り替えます。
79
+
80
+ ## オフラインでの利用
81
+
82
+ ビルド時の描画は完全にオフラインです。`@d2lang/d2` が同梱する WebAssembly を `node_modules` から読み込むだけで、外部通信は発生しません。クライアント側の描画（`render: "client"` またはビルド失敗時）は jsDelivr から D2.js を取得します。外部通信を避けたい場合は `moduleUrl` に自前でホストしたモジュールを指定してください。
83
+
84
+ ## 出力のフック
85
+
86
+ - `globalThis.d2` に読み込み済みの D2.js モジュールを設定すると、CDN からの読み込みを省略できます
87
+ - `initD2Diagrams()` を直接呼ぶ場合は `api` と `moduleUrl` を渡せます
88
+
89
+ ## 主なエクスポート
90
+
91
+ - `d2(options?)`: プラグインを作成する（`d2Plugin` は別名）
92
+ - `initD2Diagrams`: クライアント側の描画を初期化する
93
+ - 型: `D2Options`、`D2ClientOptions`、`D2RenderMode`、`D2Layout`、`D2Theme`、`D2ModuleApi`
94
+
95
+ ## 制限
96
+
97
+ - 図ごとに新しい D2 ワーカーを起動するため、大量の図を含むビルドでは WASM の起動コストが繰り返し発生します
98
+ - `layout: "elk"` は D2 の ELK エンジンを使うため `dagre` より遅くなります
99
+ - マルチボードやアニメーション付きの出力はこのプラグインでは設定できません
100
+ - レンダラーには `@d2lang/d2`（MPL-2.0）を使用しています。`@terrastruct/d2` はその後方互換パッケージです
101
+
102
+ ## 関連資料
103
+
104
+ - [プラグインシステム](../../../docs/ja/reference/plugin-api.md)
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@riebeckite/plugin-d2",
3
- "version": "0.0.12",
3
+ "version": "0.0.13",
4
4
  "license": "Apache-2.0",
5
5
  "type": "module",
6
6
  "main": "./dist/index.js",
@@ -22,7 +22,7 @@
22
22
  },
23
23
  "dependencies": {
24
24
  "@d2lang/d2": "^0.1.34",
25
- "@riebeckite/core": "0.0.12"
25
+ "@riebeckite/core": "0.0.13"
26
26
  },
27
27
  "publishConfig": {
28
28
  "access": "public"