@riebeckite/plugin-vega-lite 0.0.12 → 0.0.14

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 +128 -128
  2. package/README_ja.md +108 -108
  3. package/package.json +2 -2
package/README.md CHANGED
@@ -1,128 +1,128 @@
1
- # @riebeckite/plugin-vega-lite
2
-
3
- Renders ` ```vega-lite ` code blocks as Vega-Lite charts. Charts are drawn in the
4
- browser, and the Vega runtime is imported dynamically only when it is needed.
5
-
6
- [Japanese](./README_ja.md)
7
-
8
- ## Configure
9
-
10
- ```ts
11
- import { defineConfig } from "@riebeckite/core";
12
- import { vegaLite } from "@riebeckite/plugin-vega-lite";
13
-
14
- export default defineConfig({
15
- // ...
16
- plugins: [
17
- vegaLite({
18
- caption: true,
19
- theme: "light",
20
- renderer: "canvas",
21
- }),
22
- ],
23
- });
24
- ```
25
-
26
- The plugin runs with `order: -10`.
27
-
28
- ## Syntax
29
-
30
- Put a Vega-Lite specification as JSON in the body of the code block. Both
31
- `vega-lite` and `vega` are accepted.
32
-
33
- ````markdown
34
- ```vega-lite
35
- {
36
- "title": "Revenue",
37
- "data": {
38
- "values": [
39
- { "category": "A", "value": 28 },
40
- { "category": "B", "value": 55 }
41
- ]
42
- },
43
- "mark": "bar",
44
- "encoding": {
45
- "x": { "field": "category", "type": "nominal" },
46
- "y": { "field": "value", "type": "quantitative" }
47
- }
48
- }
49
- ```
50
- ````
51
-
52
- The caption comes from the code-block `title`, or from the specification's
53
- `title`.
54
-
55
- ## How it renders
56
-
57
- A ` ```vega-lite ` block becomes a `figure.rb-vega-lite`:
58
-
59
- - `figure.rb-vega-lite`: carries `data-vega-lite="pending"` and
60
- `data-vega-lite-spec` (the escaped JSON)
61
- - `div.rb-vega-lite__canvas`: the element the chart is rendered into
62
- (`role="img"`)
63
- - `figcaption.rb-vega-lite__caption`: the caption (enabled by default)
64
- - `details.rb-vega-lite__fallback`: the original spec, folded away
65
-
66
- `initVegaLite` finds `[data-vega-lite]`, `JSON.parse`s `data-vega-lite-spec`,
67
- then dynamically imports `vega`, `vega-lite`, and `vega-embed` and renders with
68
- `vega-embed`. On success the figure becomes `data-vega-lite="rendered"`.
69
-
70
- If loading `vega-embed`, parsing the spec, or embedding fails, the initializer
71
- does not throw: it opens that figure's `details` and marks it
72
- `data-vega-lite="error"`.
73
-
74
- A block whose body is not valid JSON is left as a normal code block, and a
75
- diagnostic with `source: "@riebeckite/plugin-vega-lite"` is emitted.
76
-
77
- ## Options
78
-
79
- | Option | Default | Description |
80
- | --- | --- | --- |
81
- | `caption` | `true` | Show the `title` as a caption |
82
- | `actions` | `null` | Show the `vega-embed` actions menu (`true` / `false` / `null`) |
83
- | `theme` | `"light"` | Colour scheme (`"light"`, `"dark"`, `"none"`) |
84
- | `renderer` | `"canvas"` | Vega renderer (`"canvas"` or `"svg"`) |
85
- | `className` | `"rb-vega-lite"` | Base class applied to the figure |
86
-
87
- When `actions` is `null`, the `vega-embed` default (actions shown) applies. With
88
- `theme` set to `"light"` or `"none"`, Vega's default light styling is used; only
89
- `"dark"` applies the built-in `dark` theme.
90
-
91
- ## Client rendering
92
-
93
- The client initializer is static and receives no plugin options. `actions`,
94
- `theme`, and `renderer` are embedded into the figure's `data-vega-lite-*`
95
- attributes, and `initVegaLite` reads them from there.
96
-
97
- The Vega runtime is loaded with `import()`, so the page still renders when
98
- JavaScript is disabled and the spec stays readable in the fallback `details`.
99
-
100
- ## Output hooks
101
-
102
- - `figure[data-vega-lite]`: state (`pending` / `rendered` / `error`)
103
- - `figure[data-vega-lite-spec]`: the escaped spec JSON
104
- - `figure[data-vega-lite-theme]`, `figure[data-vega-lite-renderer]`,
105
- `figure[data-vega-lite-actions]`
106
- - `[data-vega-lite-canvas]`: the render target
107
- - `details.rb-vega-lite__fallback`: the original spec
108
-
109
- ## Main exports
110
-
111
- - `vegaLite(options?)`: create the plugin (`vegaLitePlugin` is an alias)
112
- - `initVegaLite`: initialize client-side rendering
113
- - Types: `VegaLiteOptions`, `VegaLiteSpec`, `VegaLiteTheme`,
114
- `VegaLiteRenderer`
115
-
116
- ## Limitations
117
-
118
- - Rendering is client-only. Nothing is rendered at build time, so charts are not
119
- visible without JavaScript (the spec remains in the fallback `details`)
120
- - Each chart loads `vega`, `vega-lite`, and `vega-embed`, so pages with many
121
- charts pay for the transfer and render cost repeatedly
122
- - Not every Vega-Lite feature is validated; complex specs surface as browser
123
- errors and reveal the fallback
124
- - `vega`, `vega-lite`, and `vega-embed` are BSD-3-Clause licensed
125
-
126
- ## See also
127
-
128
- - [Plugin system](../../../docs/en/plugin-system.md)
1
+ # @riebeckite/plugin-vega-lite
2
+
3
+ Renders ` ```vega-lite ` code blocks as Vega-Lite charts. Charts are drawn in the
4
+ browser, and the Vega runtime is imported dynamically only when it is needed.
5
+
6
+ [Japanese](./README_ja.md)
7
+
8
+ ## Configure
9
+
10
+ ```ts
11
+ import { defineConfig } from "@riebeckite/core";
12
+ import { vegaLite } from "@riebeckite/plugin-vega-lite";
13
+
14
+ export default defineConfig({
15
+ // ...
16
+ plugins: [
17
+ vegaLite({
18
+ caption: true,
19
+ theme: "light",
20
+ renderer: "canvas",
21
+ }),
22
+ ],
23
+ });
24
+ ```
25
+
26
+ The plugin runs with `order: -10`.
27
+
28
+ ## Syntax
29
+
30
+ Put a Vega-Lite specification as JSON in the body of the code block. Both
31
+ `vega-lite` and `vega` are accepted.
32
+
33
+ ````markdown
34
+ ```vega-lite
35
+ {
36
+ "title": "Revenue",
37
+ "data": {
38
+ "values": [
39
+ { "category": "A", "value": 28 },
40
+ { "category": "B", "value": 55 }
41
+ ]
42
+ },
43
+ "mark": "bar",
44
+ "encoding": {
45
+ "x": { "field": "category", "type": "nominal" },
46
+ "y": { "field": "value", "type": "quantitative" }
47
+ }
48
+ }
49
+ ```
50
+ ````
51
+
52
+ The caption comes from the code-block `title`, or from the specification's
53
+ `title`.
54
+
55
+ ## How it renders
56
+
57
+ A ` ```vega-lite ` block becomes a `figure.rb-vega-lite`:
58
+
59
+ - `figure.rb-vega-lite`: carries `data-vega-lite="pending"` and
60
+ `data-vega-lite-spec` (the escaped JSON)
61
+ - `div.rb-vega-lite__canvas`: the element the chart is rendered into
62
+ (`role="img"`)
63
+ - `figcaption.rb-vega-lite__caption`: the caption (enabled by default)
64
+ - `details.rb-vega-lite__fallback`: the original spec, folded away
65
+
66
+ `initVegaLite` finds `[data-vega-lite]`, `JSON.parse`s `data-vega-lite-spec`,
67
+ then dynamically imports `vega`, `vega-lite`, and `vega-embed` and renders with
68
+ `vega-embed`. On success the figure becomes `data-vega-lite="rendered"`.
69
+
70
+ If loading `vega-embed`, parsing the spec, or embedding fails, the initializer
71
+ does not throw: it opens that figure's `details` and marks it
72
+ `data-vega-lite="error"`.
73
+
74
+ A block whose body is not valid JSON is left as a normal code block, and a
75
+ diagnostic with `source: "@riebeckite/plugin-vega-lite"` is emitted.
76
+
77
+ ## Options
78
+
79
+ | Option | Default | Description |
80
+ | --- | --- | --- |
81
+ | `caption` | `true` | Show the `title` as a caption |
82
+ | `actions` | `null` | Show the `vega-embed` actions menu (`true` / `false` / `null`) |
83
+ | `theme` | `"light"` | Colour scheme (`"light"`, `"dark"`, `"none"`) |
84
+ | `renderer` | `"canvas"` | Vega renderer (`"canvas"` or `"svg"`) |
85
+ | `className` | `"rb-vega-lite"` | Base class applied to the figure |
86
+
87
+ When `actions` is `null`, the `vega-embed` default (actions shown) applies. With
88
+ `theme` set to `"light"` or `"none"`, Vega's default light styling is used; only
89
+ `"dark"` applies the built-in `dark` theme.
90
+
91
+ ## Client rendering
92
+
93
+ The client initializer is static and receives no plugin options. `actions`,
94
+ `theme`, and `renderer` are embedded into the figure's `data-vega-lite-*`
95
+ attributes, and `initVegaLite` reads them from there.
96
+
97
+ The Vega runtime is loaded with `import()`, so the page still renders when
98
+ JavaScript is disabled and the spec stays readable in the fallback `details`.
99
+
100
+ ## Output hooks
101
+
102
+ - `figure[data-vega-lite]`: state (`pending` / `rendered` / `error`)
103
+ - `figure[data-vega-lite-spec]`: the escaped spec JSON
104
+ - `figure[data-vega-lite-theme]`, `figure[data-vega-lite-renderer]`,
105
+ `figure[data-vega-lite-actions]`
106
+ - `[data-vega-lite-canvas]`: the render target
107
+ - `details.rb-vega-lite__fallback`: the original spec
108
+
109
+ ## Main exports
110
+
111
+ - `vegaLite(options?)`: create the plugin (`vegaLitePlugin` is an alias)
112
+ - `initVegaLite`: initialize client-side rendering
113
+ - Types: `VegaLiteOptions`, `VegaLiteSpec`, `VegaLiteTheme`,
114
+ `VegaLiteRenderer`
115
+
116
+ ## Limitations
117
+
118
+ - Rendering is client-only. Nothing is rendered at build time, so charts are not
119
+ visible without JavaScript (the spec remains in the fallback `details`)
120
+ - Each chart loads `vega`, `vega-lite`, and `vega-embed`, so pages with many
121
+ charts pay for the transfer and render cost repeatedly
122
+ - Not every Vega-Lite feature is validated; complex specs surface as browser
123
+ errors and reveal the fallback
124
+ - `vega`, `vega-lite`, and `vega-embed` are BSD-3-Clause licensed
125
+
126
+ ## See also
127
+
128
+ - [Plugin system](../../../docs/en/reference/plugin-api.md)
package/README_ja.md CHANGED
@@ -1,108 +1,108 @@
1
- # @riebeckite/plugin-vega-lite
2
-
3
- ` ```vega-lite ` コードブロックを Vega-Lite のチャートとして表示するプラグインです。チャートはブラウザ側で描画し、Vega ランタイムは必要になったときだけ動的に読み込みます。
4
-
5
- [English](./README.md)
6
-
7
- ## 設定する
8
-
9
- ```ts
10
- import { defineConfig } from "@riebeckite/core";
11
- import { vegaLite } from "@riebeckite/plugin-vega-lite";
12
-
13
- export default defineConfig({
14
- // ...
15
- plugins: [
16
- vegaLite({
17
- caption: true,
18
- theme: "light",
19
- renderer: "canvas",
20
- }),
21
- ],
22
- });
23
- ```
24
-
25
- このプラグインは `order: -10` で実行されます。
26
-
27
- ## 記法
28
-
29
- コードブロックの本文に Vega-Lite の仕様を JSON で書きます。`vega-lite` に加えて `vega` も受け付けます。
30
-
31
- ````markdown
32
- ```vega-lite
33
- {
34
- "title": "売上高",
35
- "data": {
36
- "values": [
37
- { "category": "A", "value": 28 },
38
- { "category": "B", "value": 55 }
39
- ]
40
- },
41
- "mark": "bar",
42
- "encoding": {
43
- "x": { "field": "category", "type": "nominal" },
44
- "y": { "field": "value", "type": "quantitative" }
45
- }
46
- }
47
- ```
48
- ````
49
-
50
- キャプションにはコードブロックの `title`、なければ仕様の `title` を使います。
51
-
52
- ## どのように描画されるか
53
-
54
- ` ```vega-lite ` のコードブロックは `figure.rb-vega-lite` に置き換わります。
55
-
56
- - `figure.rb-vega-lite`: `data-vega-lite="pending"` と `data-vega-lite-spec`（JSON をエスケープしたもの）を持ちます
57
- - `div.rb-vega-lite__canvas`: チャートを描画する領域（`role="img"`）
58
- - `figcaption.rb-vega-lite__caption`: キャプション（既定で有効）
59
- - `details.rb-vega-lite__fallback`: 元の仕様を折りたたんで表示
60
-
61
- `initVegaLite` は `[data-vega-lite]` を探し、`data-vega-lite-spec` を `JSON.parse` してから `vega`、`vega-lite`、`vega-embed` を動的インポートして `vega-embed` で描画します。描画に成功すると `data-vega-lite="rendered"` になります。
62
-
63
- `vega-embed` の読み込み、仕様の `JSON.parse`、描画のいずれかが失敗した場合は例外を投げず、その figure の `details` を開いて元の仕様を見せます（`data-vega-lite="error"`）。
64
-
65
- JSON を解析できないコードブロックは置き換えず、通常のコードブロックのまま残し、`@riebeckite/plugin-vega-lite` を `source` に持つ診断を出します。
66
-
67
- ## オプション
68
-
69
- | 項目 | 既定値 | 説明 |
70
- | --- | --- | --- |
71
- | `caption` | `true` | `title` をキャプションとして表示する |
72
- | `actions` | `null` | `vega-embed` の操作メニューを表示する（`true` / `false` / `null`） |
73
- | `theme` | `"light"` | 配色（`"light"`、`"dark"`、`"none"`） |
74
- | `renderer` | `"canvas"` | Vega のレンダラー（`"canvas"` または `"svg"`） |
75
- | `className` | `"rb-vega-lite"` | figure に付ける基準クラス |
76
-
77
- `actions` が `null` のときは `vega-embed` の既定（操作メニューあり）に従います。`theme` が `"light"` または `"none"` のときは Vega 既定の明るい配色を使い、`"dark"` のときだけ `vega-embed` の `dark` テーマを適用します。
78
-
79
- ## クライアント側の描画
80
-
81
- クライアントの初期化コードは静的なので、プラグインのオプションは受け取りません。`actions`、`theme`、`renderer` は figure の `data-vega-lite-*` 属性に埋め込まれ、`initVegaLite` がそこから読み取ります。
82
-
83
- Vega ランタイムは `import()` で動的に読み込むため、JavaScript を無効にしていてもページは表示され、仕様はフォールバックの `details` から読めます。
84
-
85
- ## 出力のフック
86
-
87
- - `figure[data-vega-lite]`: 状態（`pending` / `rendered` / `error`）
88
- - `figure[data-vega-lite-spec]`: エスケープ済みの仕様 JSON
89
- - `figure[data-vega-lite-theme]`、`figure[data-vega-lite-renderer]`、`figure[data-vega-lite-actions]`
90
- - `[data-vega-lite-canvas]`: 描画先の要素
91
- - `details.rb-vega-lite__fallback`: 元の仕様
92
-
93
- ## 主なエクスポート
94
-
95
- - `vegaLite(options?)`: プラグインを作成する（`vegaLitePlugin` は別名）
96
- - `initVegaLite`: クライアント側の描画を初期化する
97
- - 型: `VegaLiteOptions`、`VegaLiteSpec`、`VegaLiteTheme`、`VegaLiteRenderer`
98
-
99
- ## 制限
100
-
101
- - 描画はクライアント側のみです。ビルド時に SVG などは生成しないため、JavaScript が無効な環境ではチャートは表示されません（仕様の `details` は残ります）
102
- - チャートごとに `vega`、`vega-lite`、`vega-embed` を読み込むため、多数のチャートを含むページでは転送量と描画コストが増えます
103
- - Vega-Lite のすべての機能を検証しているわけではありません。複雑な仕様はブラウザ側のエラーとして扱われ、フォールバックが開きます
104
- - `vega`、`vega-lite`、`vega-embed` は BSD-3-Clause ライセンスです
105
-
106
- ## 関連資料
107
-
108
- - [プラグインシステム](../../../docs/ja/plugin-system.md)
1
+ # @riebeckite/plugin-vega-lite
2
+
3
+ ` ```vega-lite ` コードブロックを Vega-Lite のチャートとして表示するプラグインです。チャートはブラウザ側で描画し、Vega ランタイムは必要になったときだけ動的に読み込みます。
4
+
5
+ [English](./README.md)
6
+
7
+ ## 設定する
8
+
9
+ ```ts
10
+ import { defineConfig } from "@riebeckite/core";
11
+ import { vegaLite } from "@riebeckite/plugin-vega-lite";
12
+
13
+ export default defineConfig({
14
+ // ...
15
+ plugins: [
16
+ vegaLite({
17
+ caption: true,
18
+ theme: "light",
19
+ renderer: "canvas",
20
+ }),
21
+ ],
22
+ });
23
+ ```
24
+
25
+ このプラグインは `order: -10` で実行されます。
26
+
27
+ ## 記法
28
+
29
+ コードブロックの本文に Vega-Lite の仕様を JSON で書きます。`vega-lite` に加えて `vega` も受け付けます。
30
+
31
+ ````markdown
32
+ ```vega-lite
33
+ {
34
+ "title": "売上高",
35
+ "data": {
36
+ "values": [
37
+ { "category": "A", "value": 28 },
38
+ { "category": "B", "value": 55 }
39
+ ]
40
+ },
41
+ "mark": "bar",
42
+ "encoding": {
43
+ "x": { "field": "category", "type": "nominal" },
44
+ "y": { "field": "value", "type": "quantitative" }
45
+ }
46
+ }
47
+ ```
48
+ ````
49
+
50
+ キャプションにはコードブロックの `title`、なければ仕様の `title` を使います。
51
+
52
+ ## どのように描画されるか
53
+
54
+ ` ```vega-lite ` のコードブロックは `figure.rb-vega-lite` に置き換わります。
55
+
56
+ - `figure.rb-vega-lite`: `data-vega-lite="pending"` と `data-vega-lite-spec`（JSON をエスケープしたもの）を持ちます
57
+ - `div.rb-vega-lite__canvas`: チャートを描画する領域（`role="img"`）
58
+ - `figcaption.rb-vega-lite__caption`: キャプション（既定で有効）
59
+ - `details.rb-vega-lite__fallback`: 元の仕様を折りたたんで表示
60
+
61
+ `initVegaLite` は `[data-vega-lite]` を探し、`data-vega-lite-spec` を `JSON.parse` してから `vega`、`vega-lite`、`vega-embed` を動的インポートして `vega-embed` で描画します。描画に成功すると `data-vega-lite="rendered"` になります。
62
+
63
+ `vega-embed` の読み込み、仕様の `JSON.parse`、描画のいずれかが失敗した場合は例外を投げず、その figure の `details` を開いて元の仕様を見せます（`data-vega-lite="error"`）。
64
+
65
+ JSON を解析できないコードブロックは置き換えず、通常のコードブロックのまま残し、`@riebeckite/plugin-vega-lite` を `source` に持つ診断を出します。
66
+
67
+ ## オプション
68
+
69
+ | 項目 | 既定値 | 説明 |
70
+ | --- | --- | --- |
71
+ | `caption` | `true` | `title` をキャプションとして表示する |
72
+ | `actions` | `null` | `vega-embed` の操作メニューを表示する（`true` / `false` / `null`） |
73
+ | `theme` | `"light"` | 配色（`"light"`、`"dark"`、`"none"`） |
74
+ | `renderer` | `"canvas"` | Vega のレンダラー（`"canvas"` または `"svg"`） |
75
+ | `className` | `"rb-vega-lite"` | figure に付ける基準クラス |
76
+
77
+ `actions` が `null` のときは `vega-embed` の既定（操作メニューあり）に従います。`theme` が `"light"` または `"none"` のときは Vega 既定の明るい配色を使い、`"dark"` のときだけ `vega-embed` の `dark` テーマを適用します。
78
+
79
+ ## クライアント側の描画
80
+
81
+ クライアントの初期化コードは静的なので、プラグインのオプションは受け取りません。`actions`、`theme`、`renderer` は figure の `data-vega-lite-*` 属性に埋め込まれ、`initVegaLite` がそこから読み取ります。
82
+
83
+ Vega ランタイムは `import()` で動的に読み込むため、JavaScript を無効にしていてもページは表示され、仕様はフォールバックの `details` から読めます。
84
+
85
+ ## 出力のフック
86
+
87
+ - `figure[data-vega-lite]`: 状態（`pending` / `rendered` / `error`）
88
+ - `figure[data-vega-lite-spec]`: エスケープ済みの仕様 JSON
89
+ - `figure[data-vega-lite-theme]`、`figure[data-vega-lite-renderer]`、`figure[data-vega-lite-actions]`
90
+ - `[data-vega-lite-canvas]`: 描画先の要素
91
+ - `details.rb-vega-lite__fallback`: 元の仕様
92
+
93
+ ## 主なエクスポート
94
+
95
+ - `vegaLite(options?)`: プラグインを作成する（`vegaLitePlugin` は別名）
96
+ - `initVegaLite`: クライアント側の描画を初期化する
97
+ - 型: `VegaLiteOptions`、`VegaLiteSpec`、`VegaLiteTheme`、`VegaLiteRenderer`
98
+
99
+ ## 制限
100
+
101
+ - 描画はクライアント側のみです。ビルド時に SVG などは生成しないため、JavaScript が無効な環境ではチャートは表示されません（仕様の `details` は残ります）
102
+ - チャートごとに `vega`、`vega-lite`、`vega-embed` を読み込むため、多数のチャートを含むページでは転送量と描画コストが増えます
103
+ - Vega-Lite のすべての機能を検証しているわけではありません。複雑な仕様はブラウザ側のエラーとして扱われ、フォールバックが開きます
104
+ - `vega`、`vega-lite`、`vega-embed` は BSD-3-Clause ライセンスです
105
+
106
+ ## 関連資料
107
+
108
+ - [プラグインシステム](../../../docs/ja/reference/plugin-api.md)
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@riebeckite/plugin-vega-lite",
3
- "version": "0.0.12",
3
+ "version": "0.0.14",
4
4
  "license": "Apache-2.0",
5
5
  "type": "module",
6
6
  "main": "./dist/index.js",
@@ -24,7 +24,7 @@
24
24
  "vega": "^6.4.0",
25
25
  "vega-embed": "^7.3.0",
26
26
  "vega-lite": "^6.4.3",
27
- "@riebeckite/core": "0.0.12"
27
+ "@riebeckite/core": "0.0.14"
28
28
  },
29
29
  "publishConfig": {
30
30
  "access": "public"