@riebeckite/plugin-ux 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.
- package/README.md +119 -119
- package/README_ja.md +100 -100
- package/package.json +2 -2
package/README.md
CHANGED
|
@@ -1,119 +1,119 @@
|
|
|
1
|
-
# @riebeckite/plugin-ux
|
|
2
|
-
|
|
3
|
-
Client-side progressive enhancements for reading. The plugin leaves the built
|
|
4
|
-
article HTML untouched and adds a reading progress bar, a back-to-top button,
|
|
5
|
-
table-of-contents scroll-spy, and code copy buttons at runtime.
|
|
6
|
-
|
|
7
|
-
[日本語](./README_ja.md)
|
|
8
|
-
|
|
9
|
-
## Features
|
|
10
|
-
|
|
11
|
-
- **Reading progress bar** — a thin fixed bar (`.rb-ux__progress`) that follows
|
|
12
|
-
the scroll position through the article.
|
|
13
|
-
- **Back-to-top button** — a real `button` (`.rb-ux__back-to-top`) with an
|
|
14
|
-
`aria-label` that appears after scrolling and smooth-scrolls to the top.
|
|
15
|
-
- **TOC scroll-spy** — observes `a[href^="#"]` links inside the article table of
|
|
16
|
-
contents with `IntersectionObserver` and marks the active link with
|
|
17
|
-
`.rb-ux__toc-active`.
|
|
18
|
-
- **Code copy buttons** — wraps each `pre > code` in `.rb-ux__code` and adds a
|
|
19
|
-
copy button (`.rb-ux__copy`) with a transient "copied" state.
|
|
20
|
-
|
|
21
|
-
Every feature is a no-op when the relevant DOM is absent, and `initUx()` is
|
|
22
|
-
idempotent.
|
|
23
|
-
|
|
24
|
-
## Usage
|
|
25
|
-
|
|
26
|
-
```ts
|
|
27
|
-
import { defineConfig } from "@riebeckite/core";
|
|
28
|
-
import { uxPlugin } from "@riebeckite/plugin-ux";
|
|
29
|
-
|
|
30
|
-
export default defineConfig({
|
|
31
|
-
// ...
|
|
32
|
-
plugins: [
|
|
33
|
-
uxPlugin({
|
|
34
|
-
progress: true,
|
|
35
|
-
backToTop: true,
|
|
36
|
-
tocScrollSpy: true,
|
|
37
|
-
codeCopy: true,
|
|
38
|
-
backToTopLabel: "Back to top",
|
|
39
|
-
copyLabel: "Copy",
|
|
40
|
-
copiedLabel: "Copied",
|
|
41
|
-
}),
|
|
42
|
-
],
|
|
43
|
-
});
|
|
44
|
-
```
|
|
45
|
-
|
|
46
|
-
The factory is also exported as `ux`.
|
|
47
|
-
|
|
48
|
-
## Options
|
|
49
|
-
|
|
50
|
-
| Option | Type | Default | Description |
|
|
51
|
-
| --- | --- | --- | --- |
|
|
52
|
-
| `progress` | `boolean` | `true` | Show the reading progress bar |
|
|
53
|
-
| `backToTop` | `boolean` | `true` | Show the back-to-top button |
|
|
54
|
-
| `tocScrollSpy` | `boolean` | `true` | Highlight the active table-of-contents link |
|
|
55
|
-
| `codeCopy` | `boolean` | `true` | Add a copy button to each code block |
|
|
56
|
-
| `backToTopLabel` | `string` | `"Back to top"` | `aria-label` for the back-to-top button |
|
|
57
|
-
| `copyLabel` | `string` | `"Copy"` | Label of the copy button |
|
|
58
|
-
| `copiedLabel` | `string` | `"Copied"` | Transient label shown after copying |
|
|
59
|
-
|
|
60
|
-
## How configuration reaches the client
|
|
61
|
-
|
|
62
|
-
Client initializers are bundled statically and cannot receive plugin options.
|
|
63
|
-
At build time the plugin prepends an inert JSON element to each article HTML:
|
|
64
|
-
|
|
65
|
-
```html
|
|
66
|
-
<script type="application/json" id="rb-ux-config" data-rb-ux-config>{...}</script>
|
|
67
|
-
```
|
|
68
|
-
|
|
69
|
-
`initUx()` reads that element to restore the options; when it is missing, every
|
|
70
|
-
feature falls back to its enabled default. Injection happens in
|
|
71
|
-
`onPostProcessed` (the object `getProcessedContent()` caches and renders) and is
|
|
72
|
-
mirrored onto remaining manifest entries in `onManifestCreated`. The
|
|
73
|
-
`data-rb-ux-config` attribute doubles as the marker that keeps the element from
|
|
74
|
-
being inserted twice per page.
|
|
75
|
-
|
|
76
|
-
## Emitted HTML / CSS hooks
|
|
77
|
-
|
|
78
|
-
| Class | Target |
|
|
79
|
-
| --- | --- |
|
|
80
|
-
| `rb-ux__progress` | Progress bar track (`role="progressbar"`) |
|
|
81
|
-
| `rb-ux__progress-bar` | Bar scaled with `scaleX` |
|
|
82
|
-
| `rb-ux__back-to-top` | Back-to-top button |
|
|
83
|
-
| `rb-ux__back-to-top--visible` | Added while the button is visible |
|
|
84
|
-
| `rb-ux__toc-active` | Active table-of-contents link |
|
|
85
|
-
| `rb-ux__code` | Code block wrapper |
|
|
86
|
-
| `rb-ux__copy` | Copy button |
|
|
87
|
-
| `rb-ux__copy--copied` | Transient copied state |
|
|
88
|
-
|
|
89
|
-
Styles ship as `@riebeckite/plugin-ux/style.css` and use the theme's
|
|
90
|
-
`--rb-color-*` tokens so they do not fight the existing theme.
|
|
91
|
-
|
|
92
|
-
## Accessibility
|
|
93
|
-
|
|
94
|
-
- The back-to-top control is a `button` with an `aria-label`.
|
|
95
|
-
- The progress bar exposes `role="progressbar"` with `aria-valuemin`,
|
|
96
|
-
`aria-valuemax`, and `aria-valuenow`.
|
|
97
|
-
- The active table-of-contents link receives `aria-current="true"`.
|
|
98
|
-
- Under `prefers-reduced-motion: reduce`, progress and back-to-top transitions
|
|
99
|
-
are disabled and the back-to-top jump becomes an immediate scroll.
|
|
100
|
-
- Progress bar, buttons, and copy buttons are hidden when printing.
|
|
101
|
-
|
|
102
|
-
## Limitations
|
|
103
|
-
|
|
104
|
-
- Client-only: without JavaScript nothing is added.
|
|
105
|
-
- No SPA support; a full page load re-initializes the enhancements.
|
|
106
|
-
- The TOC scroll-spy looks for `.rr-table-of-contents`, `.table-of-contents`,
|
|
107
|
-
or `[data-rb-toc]` as the table-of-contents container.
|
|
108
|
-
- Copy buttons are skipped inside `.rr-code` blocks (managed by the
|
|
109
|
-
code-enhance plugin) to avoid duplicate copy UI.
|
|
110
|
-
|
|
111
|
-
## Exports
|
|
112
|
-
|
|
113
|
-
- `uxPlugin(options?)` / `ux(options?)` — plugin factory
|
|
114
|
-
- `initUx` — browser initializer
|
|
115
|
-
- Types: `UxOptions`, `UxResolvedConfig`
|
|
116
|
-
|
|
117
|
-
## See also
|
|
118
|
-
|
|
119
|
-
- [Plugin guide](../../../docs/en/plugin-
|
|
1
|
+
# @riebeckite/plugin-ux
|
|
2
|
+
|
|
3
|
+
Client-side progressive enhancements for reading. The plugin leaves the built
|
|
4
|
+
article HTML untouched and adds a reading progress bar, a back-to-top button,
|
|
5
|
+
table-of-contents scroll-spy, and code copy buttons at runtime.
|
|
6
|
+
|
|
7
|
+
[日本語](./README_ja.md)
|
|
8
|
+
|
|
9
|
+
## Features
|
|
10
|
+
|
|
11
|
+
- **Reading progress bar** — a thin fixed bar (`.rb-ux__progress`) that follows
|
|
12
|
+
the scroll position through the article.
|
|
13
|
+
- **Back-to-top button** — a real `button` (`.rb-ux__back-to-top`) with an
|
|
14
|
+
`aria-label` that appears after scrolling and smooth-scrolls to the top.
|
|
15
|
+
- **TOC scroll-spy** — observes `a[href^="#"]` links inside the article table of
|
|
16
|
+
contents with `IntersectionObserver` and marks the active link with
|
|
17
|
+
`.rb-ux__toc-active`.
|
|
18
|
+
- **Code copy buttons** — wraps each `pre > code` in `.rb-ux__code` and adds a
|
|
19
|
+
copy button (`.rb-ux__copy`) with a transient "copied" state.
|
|
20
|
+
|
|
21
|
+
Every feature is a no-op when the relevant DOM is absent, and `initUx()` is
|
|
22
|
+
idempotent.
|
|
23
|
+
|
|
24
|
+
## Usage
|
|
25
|
+
|
|
26
|
+
```ts
|
|
27
|
+
import { defineConfig } from "@riebeckite/core";
|
|
28
|
+
import { uxPlugin } from "@riebeckite/plugin-ux";
|
|
29
|
+
|
|
30
|
+
export default defineConfig({
|
|
31
|
+
// ...
|
|
32
|
+
plugins: [
|
|
33
|
+
uxPlugin({
|
|
34
|
+
progress: true,
|
|
35
|
+
backToTop: true,
|
|
36
|
+
tocScrollSpy: true,
|
|
37
|
+
codeCopy: true,
|
|
38
|
+
backToTopLabel: "Back to top",
|
|
39
|
+
copyLabel: "Copy",
|
|
40
|
+
copiedLabel: "Copied",
|
|
41
|
+
}),
|
|
42
|
+
],
|
|
43
|
+
});
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
The factory is also exported as `ux`.
|
|
47
|
+
|
|
48
|
+
## Options
|
|
49
|
+
|
|
50
|
+
| Option | Type | Default | Description |
|
|
51
|
+
| --- | --- | --- | --- |
|
|
52
|
+
| `progress` | `boolean` | `true` | Show the reading progress bar |
|
|
53
|
+
| `backToTop` | `boolean` | `true` | Show the back-to-top button |
|
|
54
|
+
| `tocScrollSpy` | `boolean` | `true` | Highlight the active table-of-contents link |
|
|
55
|
+
| `codeCopy` | `boolean` | `true` | Add a copy button to each code block |
|
|
56
|
+
| `backToTopLabel` | `string` | `"Back to top"` | `aria-label` for the back-to-top button |
|
|
57
|
+
| `copyLabel` | `string` | `"Copy"` | Label of the copy button |
|
|
58
|
+
| `copiedLabel` | `string` | `"Copied"` | Transient label shown after copying |
|
|
59
|
+
|
|
60
|
+
## How configuration reaches the client
|
|
61
|
+
|
|
62
|
+
Client initializers are bundled statically and cannot receive plugin options.
|
|
63
|
+
At build time the plugin prepends an inert JSON element to each article HTML:
|
|
64
|
+
|
|
65
|
+
```html
|
|
66
|
+
<script type="application/json" id="rb-ux-config" data-rb-ux-config>{...}</script>
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
`initUx()` reads that element to restore the options; when it is missing, every
|
|
70
|
+
feature falls back to its enabled default. Injection happens in
|
|
71
|
+
`onPostProcessed` (the object `getProcessedContent()` caches and renders) and is
|
|
72
|
+
mirrored onto remaining manifest entries in `onManifestCreated`. The
|
|
73
|
+
`data-rb-ux-config` attribute doubles as the marker that keeps the element from
|
|
74
|
+
being inserted twice per page.
|
|
75
|
+
|
|
76
|
+
## Emitted HTML / CSS hooks
|
|
77
|
+
|
|
78
|
+
| Class | Target |
|
|
79
|
+
| --- | --- |
|
|
80
|
+
| `rb-ux__progress` | Progress bar track (`role="progressbar"`) |
|
|
81
|
+
| `rb-ux__progress-bar` | Bar scaled with `scaleX` |
|
|
82
|
+
| `rb-ux__back-to-top` | Back-to-top button |
|
|
83
|
+
| `rb-ux__back-to-top--visible` | Added while the button is visible |
|
|
84
|
+
| `rb-ux__toc-active` | Active table-of-contents link |
|
|
85
|
+
| `rb-ux__code` | Code block wrapper |
|
|
86
|
+
| `rb-ux__copy` | Copy button |
|
|
87
|
+
| `rb-ux__copy--copied` | Transient copied state |
|
|
88
|
+
|
|
89
|
+
Styles ship as `@riebeckite/plugin-ux/style.css` and use the theme's
|
|
90
|
+
`--rb-color-*` tokens so they do not fight the existing theme.
|
|
91
|
+
|
|
92
|
+
## Accessibility
|
|
93
|
+
|
|
94
|
+
- The back-to-top control is a `button` with an `aria-label`.
|
|
95
|
+
- The progress bar exposes `role="progressbar"` with `aria-valuemin`,
|
|
96
|
+
`aria-valuemax`, and `aria-valuenow`.
|
|
97
|
+
- The active table-of-contents link receives `aria-current="true"`.
|
|
98
|
+
- Under `prefers-reduced-motion: reduce`, progress and back-to-top transitions
|
|
99
|
+
are disabled and the back-to-top jump becomes an immediate scroll.
|
|
100
|
+
- Progress bar, buttons, and copy buttons are hidden when printing.
|
|
101
|
+
|
|
102
|
+
## Limitations
|
|
103
|
+
|
|
104
|
+
- Client-only: without JavaScript nothing is added.
|
|
105
|
+
- No SPA support; a full page load re-initializes the enhancements.
|
|
106
|
+
- The TOC scroll-spy looks for `.rr-table-of-contents`, `.table-of-contents`,
|
|
107
|
+
or `[data-rb-toc]` as the table-of-contents container.
|
|
108
|
+
- Copy buttons are skipped inside `.rr-code` blocks (managed by the
|
|
109
|
+
code-enhance plugin) to avoid duplicate copy UI.
|
|
110
|
+
|
|
111
|
+
## Exports
|
|
112
|
+
|
|
113
|
+
- `uxPlugin(options?)` / `ux(options?)` — plugin factory
|
|
114
|
+
- `initUx` — browser initializer
|
|
115
|
+
- Types: `UxOptions`, `UxResolvedConfig`
|
|
116
|
+
|
|
117
|
+
## See also
|
|
118
|
+
|
|
119
|
+
- [Plugin guide](../../../docs/en/reference/plugin-api.md)
|
package/README_ja.md
CHANGED
|
@@ -1,100 +1,100 @@
|
|
|
1
|
-
# @riebeckite/plugin-ux
|
|
2
|
-
|
|
3
|
-
記事の読みやすさを高めるクライアント側のプログレッシブ・エンハンスメントをまとめたプラグインです。ビルド後の記事 HTML はそのままに、読み進捗バー・トップへ戻るボタン・目次のスクロール連動ハイライト・コードのコピーボタンを追加します。
|
|
4
|
-
|
|
5
|
-
[English](./README.md)
|
|
6
|
-
|
|
7
|
-
## できること
|
|
8
|
-
|
|
9
|
-
- **読み進捗バー**: 画面上部に固定した細いバー（`.rb-ux__progress`）が記事のスクロール量に追従します。
|
|
10
|
-
- **トップへ戻るボタン**: 一定量スクロールすると表示される button 要素（`.rb-ux__back-to-top`）。`aria-label` を持ち、スムーズスクロールで先頭へ戻ります。
|
|
11
|
-
- **目次のスクロール連動**: 記事の目次コンテナ内の `a[href^="#"]` を `IntersectionObserver` で監視し、現在位置の見出しリンクに `.rb-ux__toc-active` を付けます。
|
|
12
|
-
- **コードのコピーボタン**: 各 `pre > code`（`.rb-ux__code` でラップ）にコピーボタン（`.rb-ux__copy`）を追加します。コピー直後は一時的に「コピーしました」表示へ切り替わります。
|
|
13
|
-
|
|
14
|
-
いずれも対応する DOM が無いページでは何もしません。`initUx()` は何度呼んでも二重に初期化しません。
|
|
15
|
-
|
|
16
|
-
## 使い方
|
|
17
|
-
|
|
18
|
-
```ts
|
|
19
|
-
import { defineConfig } from "@riebeckite/core";
|
|
20
|
-
import { uxPlugin } from "@riebeckite/plugin-ux";
|
|
21
|
-
|
|
22
|
-
export default defineConfig({
|
|
23
|
-
// ...
|
|
24
|
-
plugins: [
|
|
25
|
-
uxPlugin({
|
|
26
|
-
progress: true,
|
|
27
|
-
backToTop: true,
|
|
28
|
-
tocScrollSpy: true,
|
|
29
|
-
codeCopy: true,
|
|
30
|
-
backToTopLabel: "トップへ戻る",
|
|
31
|
-
copyLabel: "コピー",
|
|
32
|
-
copiedLabel: "コピーしました",
|
|
33
|
-
}),
|
|
34
|
-
],
|
|
35
|
-
});
|
|
36
|
-
```
|
|
37
|
-
|
|
38
|
-
`uxPlugin` は `ux` という別名でもエクスポートしています。
|
|
39
|
-
|
|
40
|
-
## オプション
|
|
41
|
-
|
|
42
|
-
| 項目 | 型 | 既定値 | 説明 |
|
|
43
|
-
| --- | --- | --- | --- |
|
|
44
|
-
| `progress` | `boolean` | `true` | 読み進捗バーを表示する |
|
|
45
|
-
| `backToTop` | `boolean` | `true` | トップへ戻るボタンを表示する |
|
|
46
|
-
| `tocScrollSpy` | `boolean` | `true` | 目次のスクロール連動ハイライトを有効にする |
|
|
47
|
-
| `codeCopy` | `boolean` | `true` | コードのコピーボタンを追加する |
|
|
48
|
-
| `backToTopLabel` | `string` | `"Back to top"` | トップへ戻るボタンの `aria-label` |
|
|
49
|
-
| `copyLabel` | `string` | `"Copy"` | コピーボタンのラベル |
|
|
50
|
-
| `copiedLabel` | `string` | `"Copied"` | コピー成功時に一時表示するラベル |
|
|
51
|
-
|
|
52
|
-
## 設定がクライアントへ渡る仕組み
|
|
53
|
-
|
|
54
|
-
クライアント側の初期化コードは静的にバンドルされ、プラグインのオプションを直接受け取れません。そのためこのプラグインは、ビルド時に各記事 HTML の先頭へ次の不活性な JSON 要素を挿入します。
|
|
55
|
-
|
|
56
|
-
```html
|
|
57
|
-
<script type="application/json" id="rb-ux-config" data-rb-ux-config>{...}</script>
|
|
58
|
-
```
|
|
59
|
-
|
|
60
|
-
`initUx()` はこの要素を読み取って設定を復元します。要素が無い場合は全機能が有効な既定値で動作します。挿入は `onPostProcessed` で行い、`onManifestCreated` でも未挿入の記事エントリへ反映し、`getProcessedContent()` が返すキャッシュ済み HTML も同時に更新します。挿入はページごとに一度だけで、`data-rb-ux-config` を目印に重複挿入を防ぎます。
|
|
61
|
-
|
|
62
|
-
## 出力される HTML / CSS フック
|
|
63
|
-
|
|
64
|
-
| クラス | 対象 |
|
|
65
|
-
| --- | --- |
|
|
66
|
-
| `rb-ux__progress` | 進捗バーのトラック（`role="progressbar"`） |
|
|
67
|
-
| `rb-ux__progress-bar` | 進捗に応じて `scaleX` されるバー |
|
|
68
|
-
| `rb-ux__back-to-top` | トップへ戻る button |
|
|
69
|
-
| `rb-ux__back-to-top--visible` | 表示状態のとき付与 |
|
|
70
|
-
| `rb-ux__toc-active` | 現在位置の目次リンク |
|
|
71
|
-
| `rb-ux__code` | コードブロックのラッパー |
|
|
72
|
-
| `rb-ux__copy` | コピーボタン |
|
|
73
|
-
| `rb-ux__copy--copied` | コピー直後の一時状態 |
|
|
74
|
-
|
|
75
|
-
スタイルは `@riebeckite/plugin-ux/style.css` として配布し、テーマの `--rb-color-*` トークンを参照するため既存テーマと競合しません。
|
|
76
|
-
|
|
77
|
-
## アクセシビリティ
|
|
78
|
-
|
|
79
|
-
- トップへ戻るボタンは `button` 要素で、`aria-label` を持ちます。
|
|
80
|
-
- 進捗バーは `role="progressbar"` と `aria-valuemin` / `aria-valuemax` / `aria-valuenow` を持ちます。
|
|
81
|
-
- 目次の現在位置には `aria-current="true"` を付けます。
|
|
82
|
-
- `prefers-reduced-motion: reduce` では進捗バーとトップへ戻るボタンのアニメーションを無効化し、トップへ戻る動作も即時スクロールへ切り替えます。
|
|
83
|
-
- 印刷時は進捗バー・ボタン・コピーボタンを非表示にします。
|
|
84
|
-
|
|
85
|
-
## 制限事項
|
|
86
|
-
|
|
87
|
-
- クライアント専用です。JavaScript が無効な環境では何も追加されません。
|
|
88
|
-
- SPA ナビゲーションには対応しません。ページ遷移後は再読み込み時に初期化されます。
|
|
89
|
-
- 目次のスクロール連動は `.rr-table-of-contents`、`.table-of-contents`、`[data-rb-toc]` のいずれかを目次コンテナとして探します。
|
|
90
|
-
- コードのコピーボタンは `.rr-code`（code-enhance プラグインが管理するブロック）には追加しません。二重のコピー UI を避けるためです。
|
|
91
|
-
|
|
92
|
-
## 主なエクスポート
|
|
93
|
-
|
|
94
|
-
- `uxPlugin(options?)` / `ux(options?)`: プラグインを作成する
|
|
95
|
-
- `initUx`: クライアント側の初期化
|
|
96
|
-
- 型: `UxOptions`、`UxResolvedConfig`
|
|
97
|
-
|
|
98
|
-
## 関連資料
|
|
99
|
-
|
|
100
|
-
- [プラグインシステム](../../../docs/ja/plugin-
|
|
1
|
+
# @riebeckite/plugin-ux
|
|
2
|
+
|
|
3
|
+
記事の読みやすさを高めるクライアント側のプログレッシブ・エンハンスメントをまとめたプラグインです。ビルド後の記事 HTML はそのままに、読み進捗バー・トップへ戻るボタン・目次のスクロール連動ハイライト・コードのコピーボタンを追加します。
|
|
4
|
+
|
|
5
|
+
[English](./README.md)
|
|
6
|
+
|
|
7
|
+
## できること
|
|
8
|
+
|
|
9
|
+
- **読み進捗バー**: 画面上部に固定した細いバー（`.rb-ux__progress`）が記事のスクロール量に追従します。
|
|
10
|
+
- **トップへ戻るボタン**: 一定量スクロールすると表示される button 要素（`.rb-ux__back-to-top`）。`aria-label` を持ち、スムーズスクロールで先頭へ戻ります。
|
|
11
|
+
- **目次のスクロール連動**: 記事の目次コンテナ内の `a[href^="#"]` を `IntersectionObserver` で監視し、現在位置の見出しリンクに `.rb-ux__toc-active` を付けます。
|
|
12
|
+
- **コードのコピーボタン**: 各 `pre > code`（`.rb-ux__code` でラップ）にコピーボタン（`.rb-ux__copy`）を追加します。コピー直後は一時的に「コピーしました」表示へ切り替わります。
|
|
13
|
+
|
|
14
|
+
いずれも対応する DOM が無いページでは何もしません。`initUx()` は何度呼んでも二重に初期化しません。
|
|
15
|
+
|
|
16
|
+
## 使い方
|
|
17
|
+
|
|
18
|
+
```ts
|
|
19
|
+
import { defineConfig } from "@riebeckite/core";
|
|
20
|
+
import { uxPlugin } from "@riebeckite/plugin-ux";
|
|
21
|
+
|
|
22
|
+
export default defineConfig({
|
|
23
|
+
// ...
|
|
24
|
+
plugins: [
|
|
25
|
+
uxPlugin({
|
|
26
|
+
progress: true,
|
|
27
|
+
backToTop: true,
|
|
28
|
+
tocScrollSpy: true,
|
|
29
|
+
codeCopy: true,
|
|
30
|
+
backToTopLabel: "トップへ戻る",
|
|
31
|
+
copyLabel: "コピー",
|
|
32
|
+
copiedLabel: "コピーしました",
|
|
33
|
+
}),
|
|
34
|
+
],
|
|
35
|
+
});
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
`uxPlugin` は `ux` という別名でもエクスポートしています。
|
|
39
|
+
|
|
40
|
+
## オプション
|
|
41
|
+
|
|
42
|
+
| 項目 | 型 | 既定値 | 説明 |
|
|
43
|
+
| --- | --- | --- | --- |
|
|
44
|
+
| `progress` | `boolean` | `true` | 読み進捗バーを表示する |
|
|
45
|
+
| `backToTop` | `boolean` | `true` | トップへ戻るボタンを表示する |
|
|
46
|
+
| `tocScrollSpy` | `boolean` | `true` | 目次のスクロール連動ハイライトを有効にする |
|
|
47
|
+
| `codeCopy` | `boolean` | `true` | コードのコピーボタンを追加する |
|
|
48
|
+
| `backToTopLabel` | `string` | `"Back to top"` | トップへ戻るボタンの `aria-label` |
|
|
49
|
+
| `copyLabel` | `string` | `"Copy"` | コピーボタンのラベル |
|
|
50
|
+
| `copiedLabel` | `string` | `"Copied"` | コピー成功時に一時表示するラベル |
|
|
51
|
+
|
|
52
|
+
## 設定がクライアントへ渡る仕組み
|
|
53
|
+
|
|
54
|
+
クライアント側の初期化コードは静的にバンドルされ、プラグインのオプションを直接受け取れません。そのためこのプラグインは、ビルド時に各記事 HTML の先頭へ次の不活性な JSON 要素を挿入します。
|
|
55
|
+
|
|
56
|
+
```html
|
|
57
|
+
<script type="application/json" id="rb-ux-config" data-rb-ux-config>{...}</script>
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
`initUx()` はこの要素を読み取って設定を復元します。要素が無い場合は全機能が有効な既定値で動作します。挿入は `onPostProcessed` で行い、`onManifestCreated` でも未挿入の記事エントリへ反映し、`getProcessedContent()` が返すキャッシュ済み HTML も同時に更新します。挿入はページごとに一度だけで、`data-rb-ux-config` を目印に重複挿入を防ぎます。
|
|
61
|
+
|
|
62
|
+
## 出力される HTML / CSS フック
|
|
63
|
+
|
|
64
|
+
| クラス | 対象 |
|
|
65
|
+
| --- | --- |
|
|
66
|
+
| `rb-ux__progress` | 進捗バーのトラック（`role="progressbar"`） |
|
|
67
|
+
| `rb-ux__progress-bar` | 進捗に応じて `scaleX` されるバー |
|
|
68
|
+
| `rb-ux__back-to-top` | トップへ戻る button |
|
|
69
|
+
| `rb-ux__back-to-top--visible` | 表示状態のとき付与 |
|
|
70
|
+
| `rb-ux__toc-active` | 現在位置の目次リンク |
|
|
71
|
+
| `rb-ux__code` | コードブロックのラッパー |
|
|
72
|
+
| `rb-ux__copy` | コピーボタン |
|
|
73
|
+
| `rb-ux__copy--copied` | コピー直後の一時状態 |
|
|
74
|
+
|
|
75
|
+
スタイルは `@riebeckite/plugin-ux/style.css` として配布し、テーマの `--rb-color-*` トークンを参照するため既存テーマと競合しません。
|
|
76
|
+
|
|
77
|
+
## アクセシビリティ
|
|
78
|
+
|
|
79
|
+
- トップへ戻るボタンは `button` 要素で、`aria-label` を持ちます。
|
|
80
|
+
- 進捗バーは `role="progressbar"` と `aria-valuemin` / `aria-valuemax` / `aria-valuenow` を持ちます。
|
|
81
|
+
- 目次の現在位置には `aria-current="true"` を付けます。
|
|
82
|
+
- `prefers-reduced-motion: reduce` では進捗バーとトップへ戻るボタンのアニメーションを無効化し、トップへ戻る動作も即時スクロールへ切り替えます。
|
|
83
|
+
- 印刷時は進捗バー・ボタン・コピーボタンを非表示にします。
|
|
84
|
+
|
|
85
|
+
## 制限事項
|
|
86
|
+
|
|
87
|
+
- クライアント専用です。JavaScript が無効な環境では何も追加されません。
|
|
88
|
+
- SPA ナビゲーションには対応しません。ページ遷移後は再読み込み時に初期化されます。
|
|
89
|
+
- 目次のスクロール連動は `.rr-table-of-contents`、`.table-of-contents`、`[data-rb-toc]` のいずれかを目次コンテナとして探します。
|
|
90
|
+
- コードのコピーボタンは `.rr-code`（code-enhance プラグインが管理するブロック）には追加しません。二重のコピー UI を避けるためです。
|
|
91
|
+
|
|
92
|
+
## 主なエクスポート
|
|
93
|
+
|
|
94
|
+
- `uxPlugin(options?)` / `ux(options?)`: プラグインを作成する
|
|
95
|
+
- `initUx`: クライアント側の初期化
|
|
96
|
+
- 型: `UxOptions`、`UxResolvedConfig`
|
|
97
|
+
|
|
98
|
+
## 関連資料
|
|
99
|
+
|
|
100
|
+
- [プラグインシステム](../../../docs/ja/reference/plugin-api.md)
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@riebeckite/plugin-ux",
|
|
3
|
-
"version": "0.0.
|
|
3
|
+
"version": "0.0.13",
|
|
4
4
|
"license": "Apache-2.0",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"main": "./dist/index.js",
|
|
@@ -21,7 +21,7 @@
|
|
|
21
21
|
"./style.css": "./style.css"
|
|
22
22
|
},
|
|
23
23
|
"dependencies": {
|
|
24
|
-
"@riebeckite/core": "0.0.
|
|
24
|
+
"@riebeckite/core": "0.0.13"
|
|
25
25
|
},
|
|
26
26
|
"publishConfig": {
|
|
27
27
|
"access": "public"
|