@riebeckite/plugin-flashcards 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 +120 -120
  2. package/README_ja.md +93 -93
  3. package/package.json +2 -2
package/README.md CHANGED
@@ -1,120 +1,120 @@
1
- # @riebeckite/plugin-flashcards
2
-
3
- Turn a `flashcards` code block into a study island: a small deck of cards that
4
- shows a question, reveals the answer, and can be navigated and shuffled in the
5
- browser. The build emits an accessible static list first, so the deck stays
6
- readable with no JavaScript at all.
7
-
8
- [日本語](./README_ja.md)
9
-
10
- ## Overview
11
-
12
- `flashcards()` recognises fenced blocks
13
-
14
- ````md
15
- ```flashcards
16
- What is the capital of France? :: Paris
17
-
18
- What is 2 + 2? :: 4
19
- ```
20
- ````
21
-
22
- and replaces them with an interactive deck.
23
-
24
- ## Usage
25
-
26
- ```ts
27
- import { defineConfig } from "@riebeckite/core";
28
- import { flashcardsPlugin } from "@riebeckite/plugin-flashcards";
29
-
30
- export default defineConfig({
31
- // ...
32
- plugins: [flashcardsPlugin()],
33
- });
34
- ```
35
-
36
- The plugin adds `style.css` and a client entry. The script tag is emitted by the
37
- site layout; the plugin only declares it.
38
-
39
- ## Block syntax
40
-
41
- A block holds one or more cards. Each card is a `Question :: Answer` pair. Cards
42
- are separated by a blank line or by a `---` line, and an answer may span
43
- multiple lines:
44
-
45
- ````md
46
- ```flashcards
47
- Which language is this plugin written in? :: TypeScript
48
-
49
- What does the client render? :: An interactive deck
50
- ---
51
- Describe the fallback. :: A static ordered list.
52
- It stays readable without JavaScript.
53
- ```
54
- ````
55
-
56
- A block with no cards, a card without `::`, or a card with an empty side is
57
- reported as a diagnostic (`invalid-flashcards`) and left as a code block.
58
-
59
- ## Output
60
-
61
- At build time the block becomes
62
-
63
- ```html
64
- <div class="rb-flashcards" data-flashcards data-flashcards-count="2">
65
- <script type="application/json" data-flashcards-payload>
66
- {"cards":[{"front":"...","back":"..."}]}
67
- </script>
68
- <ol class="rb-flashcards__list" data-flashcards-fallback>
69
- <li class="rb-flashcards__item">
70
- <span class="rb-flashcards__front">...</span>
71
- <span class="rb-flashcards__back">...</span>
72
- </li>
73
- </ol>
74
- </div>
75
- ```
76
-
77
- The payload is inert and escaped, so card text containing `<`, `>`, or `&` can
78
- never close the script element. The ordered list is the no-JavaScript fallback.
79
-
80
- ## Client behaviour
81
-
82
- `initFlashcards()` reads the payload of every `[data-flashcards]` element and
83
- adds an interactive deck above the fallback. It supports:
84
-
85
- - Reveal / hide the answer
86
- - Previous and next card with wrap-around
87
- - Shuffle
88
- - A live card counter
89
- - Keyboard control: `Space` reveals, `ArrowLeft` / `ArrowRight` navigate
90
-
91
- On success the root gets `data-flashcards="ready"` and the static list is
92
- hidden. If the payload is missing or invalid the client leaves the fallback
93
- untouched. No options are passed from the build to the client; the deck reads
94
- `data-flashcards-shuffle` when it is present.
95
-
96
- ## Options
97
-
98
- | Option | Type | Default | Description |
99
- | ------ | ---- | ------- | ----------- |
100
- | `className` | `string` | `"rb-flashcards"` | Root CSS class for the deck |
101
- | `language` | `string` | `"flashcards"` | Fence language to target |
102
- | `shuffle` | `boolean` | `false` | Start the deck in a shuffled order |
103
- | `fallback` | `boolean` | `true` | Emit the static ordered list |
104
-
105
- ## Exports
106
-
107
- - `flashcards(options?)` / `flashcardsPlugin(options?)` — plugin factory
108
- - `initFlashcards(root?)` — client initializer
109
- - `parseFlashcards(source)` — parse a block into cards
110
- - `splitFlashcardGroups(source)` — split a block into card groups
111
- - `remarkFlashcards(options?)` — the remark transform on its own
112
- - `renderFlashcards(cards, options)` / `renderFlashcardsPayload(cards)` /
113
- `renderFlashcardsFallback(cards, className?)` — build-time rendering helpers
114
- - `resolveFlashcardsOptions(options?)`, `createFlashcardsRuntime(options?)`
115
- - Types: `FlashcardsOptions`, `FlashcardsCard`, `FlashcardsPayload`,
116
- `ResolvedFlashcardsOptions`
117
-
118
- ## See also
119
-
120
- - [Plugin guide](../../../docs/en/plugin-system.md)
1
+ # @riebeckite/plugin-flashcards
2
+
3
+ Turn a `flashcards` code block into a study island: a small deck of cards that
4
+ shows a question, reveals the answer, and can be navigated and shuffled in the
5
+ browser. The build emits an accessible static list first, so the deck stays
6
+ readable with no JavaScript at all.
7
+
8
+ [日本語](./README_ja.md)
9
+
10
+ ## Overview
11
+
12
+ `flashcards()` recognises fenced blocks
13
+
14
+ ````md
15
+ ```flashcards
16
+ What is the capital of France? :: Paris
17
+
18
+ What is 2 + 2? :: 4
19
+ ```
20
+ ````
21
+
22
+ and replaces them with an interactive deck.
23
+
24
+ ## Usage
25
+
26
+ ```ts
27
+ import { defineConfig } from "@riebeckite/core";
28
+ import { flashcardsPlugin } from "@riebeckite/plugin-flashcards";
29
+
30
+ export default defineConfig({
31
+ // ...
32
+ plugins: [flashcardsPlugin()],
33
+ });
34
+ ```
35
+
36
+ The plugin adds `style.css` and a client entry. The script tag is emitted by the
37
+ site layout; the plugin only declares it.
38
+
39
+ ## Block syntax
40
+
41
+ A block holds one or more cards. Each card is a `Question :: Answer` pair. Cards
42
+ are separated by a blank line or by a `---` line, and an answer may span
43
+ multiple lines:
44
+
45
+ ````md
46
+ ```flashcards
47
+ Which language is this plugin written in? :: TypeScript
48
+
49
+ What does the client render? :: An interactive deck
50
+ ---
51
+ Describe the fallback. :: A static ordered list.
52
+ It stays readable without JavaScript.
53
+ ```
54
+ ````
55
+
56
+ A block with no cards, a card without `::`, or a card with an empty side is
57
+ reported as a diagnostic (`invalid-flashcards`) and left as a code block.
58
+
59
+ ## Output
60
+
61
+ At build time the block becomes
62
+
63
+ ```html
64
+ <div class="rb-flashcards" data-flashcards data-flashcards-count="2">
65
+ <script type="application/json" data-flashcards-payload>
66
+ {"cards":[{"front":"...","back":"..."}]}
67
+ </script>
68
+ <ol class="rb-flashcards__list" data-flashcards-fallback>
69
+ <li class="rb-flashcards__item">
70
+ <span class="rb-flashcards__front">...</span>
71
+ <span class="rb-flashcards__back">...</span>
72
+ </li>
73
+ </ol>
74
+ </div>
75
+ ```
76
+
77
+ The payload is inert and escaped, so card text containing `<`, `>`, or `&` can
78
+ never close the script element. The ordered list is the no-JavaScript fallback.
79
+
80
+ ## Client behaviour
81
+
82
+ `initFlashcards()` reads the payload of every `[data-flashcards]` element and
83
+ adds an interactive deck above the fallback. It supports:
84
+
85
+ - Reveal / hide the answer
86
+ - Previous and next card with wrap-around
87
+ - Shuffle
88
+ - A live card counter
89
+ - Keyboard control: `Space` reveals, `ArrowLeft` / `ArrowRight` navigate
90
+
91
+ On success the root gets `data-flashcards="ready"` and the static list is
92
+ hidden. If the payload is missing or invalid the client leaves the fallback
93
+ untouched. No options are passed from the build to the client; the deck reads
94
+ `data-flashcards-shuffle` when it is present.
95
+
96
+ ## Options
97
+
98
+ | Option | Type | Default | Description |
99
+ | ------ | ---- | ------- | ----------- |
100
+ | `className` | `string` | `"rb-flashcards"` | Root CSS class for the deck |
101
+ | `language` | `string` | `"flashcards"` | Fence language to target |
102
+ | `shuffle` | `boolean` | `false` | Start the deck in a shuffled order |
103
+ | `fallback` | `boolean` | `true` | Emit the static ordered list |
104
+
105
+ ## Exports
106
+
107
+ - `flashcards(options?)` / `flashcardsPlugin(options?)` — plugin factory
108
+ - `initFlashcards(root?)` — client initializer
109
+ - `parseFlashcards(source)` — parse a block into cards
110
+ - `splitFlashcardGroups(source)` — split a block into card groups
111
+ - `remarkFlashcards(options?)` — the remark transform on its own
112
+ - `renderFlashcards(cards, options)` / `renderFlashcardsPayload(cards)` /
113
+ `renderFlashcardsFallback(cards, className?)` — build-time rendering helpers
114
+ - `resolveFlashcardsOptions(options?)`, `createFlashcardsRuntime(options?)`
115
+ - Types: `FlashcardsOptions`, `FlashcardsCard`, `FlashcardsPayload`,
116
+ `ResolvedFlashcardsOptions`
117
+
118
+ ## See also
119
+
120
+ - [Plugin guide](../../../docs/en/reference/plugin-api.md)
package/README_ja.md CHANGED
@@ -1,93 +1,93 @@
1
- # @riebeckite/plugin-flashcards
2
-
3
- `flashcards` コードブロックを学習用のカードデッキに変えるプラグインです。質問を表示して答えをめくり、前後の移動とシャッフルができます。ビルド時には静的なリストを先に出力するため、JavaScript がなくても内容を読めます。
4
-
5
- [English](./README.md)
6
-
7
- ## 設定する
8
-
9
- ```ts
10
- import { defineConfig } from "@riebeckite/core";
11
- import { flashcardsPlugin } from "@riebeckite/plugin-flashcards";
12
-
13
- export default defineConfig({
14
- // ...
15
- plugins: [flashcardsPlugin()],
16
- });
17
- ```
18
-
19
- このプラグインは `style.css` とクライアントエントリを追加します。script タグの出力はサイトのレイアウト側が行い、プラグインは宣言だけを担います。
20
-
21
- ## ブロックの書き方
22
-
23
- ブロックには 1 枚以上のカードを書きます。カードは `質問 :: 答え` の組です。カード同士は空行または `---` の行で区切り、答えは複数行にまたがってもかまいません。
24
-
25
- ````md
26
- ```flashcards
27
- Which language is this plugin written in? :: TypeScript
28
-
29
- What does the client render? :: An interactive deck
30
- ---
31
- Describe the fallback. :: A static ordered list.
32
- It stays readable without JavaScript.
33
- ```
34
- ````
35
-
36
- カードが 1 枚もない、`::` のないカードがある、どちらかの側が空である、といった場合は `invalid-flashcards` の診断を出し、コードブロックのまま残します。
37
-
38
- ## 出力
39
-
40
- ビルド時に、ブロックは次の要素に置き換わります。
41
-
42
- ```html
43
- <div class="rb-flashcards" data-flashcards data-flashcards-count="2">
44
- <script type="application/json" data-flashcards-payload>
45
- {"cards":[{"front":"...","back":"..."}]}
46
- </script>
47
- <ol class="rb-flashcards__list" data-flashcards-fallback>
48
- <li class="rb-flashcards__item">
49
- <span class="rb-flashcards__front">...</span>
50
- <span class="rb-flashcards__back">...</span>
51
- </li>
52
- </ol>
53
- </div>
54
- ```
55
-
56
- payload は実行されない JSON で、`<` `>` `&` はエスケープ済みです。カードの文言にこれらの文字が含まれていても script 要素を閉じることはできません。順序付きリストは JavaScript がない場合の代替表示です。
57
-
58
- ## クライアントの動作
59
-
60
- `initFlashcards()` は各 `[data-flashcards]` 要素の payload を読み、代替リストの上に操作できるデッキを組み立てます。対応している操作は次のとおりです。
61
-
62
- - 答えの表示・非表示
63
- - 前後のカードへの移動（端で折り返す）
64
- - シャッフル
65
- - カード位置の表示
66
- - キーボード操作: `Space` で答えを表示、`ArrowLeft` / `ArrowRight` で移動
67
-
68
- 成功するとルートに `data-flashcards="ready"` が付き、静的なリストは非表示になります。payload がない、または壊れている場合は代替表示をそのまま残します。ビルドからクライアントへオプションは渡しません。シャッフルの初期状態は `data-flashcards-shuffle` 属性で伝えます。
69
-
70
- ## オプション
71
-
72
- | 項目 | 型 | 既定値 | 説明 |
73
- | --- | --- | --- | --- |
74
- | `className` | `string` | `"rb-flashcards"` | デッキのルート CSS クラス |
75
- | `language` | `string` | `"flashcards"` | 対象にするフェンス言語 |
76
- | `shuffle` | `boolean` | `false` | 最初からシャッフルした順で表示する |
77
- | `fallback` | `boolean` | `true` | 静的な順序付きリストを出力する |
78
-
79
- ## 主なエクスポート
80
-
81
- - `flashcards(options?)` / `flashcardsPlugin(options?)`: プラグインを作成する
82
- - `initFlashcards(root?)`: クライアント側を初期化する
83
- - `parseFlashcards(source)`: ブロックをカードに分解する
84
- - `splitFlashcardGroups(source)`: ブロックをカードのまとまりに分割する
85
- - `remarkFlashcards(options?)`: remark 変換を単体で使う
86
- - `renderFlashcards(cards, options)` / `renderFlashcardsPayload(cards)` /
87
- `renderFlashcardsFallback(cards, className?)`: ビルド時の描画ヘルパー
88
- - `resolveFlashcardsOptions(options?)`、`createFlashcardsRuntime(options?)`
89
- - 型: `FlashcardsOptions`、`FlashcardsCard`、`FlashcardsPayload`、`ResolvedFlashcardsOptions`
90
-
91
- ## 関連資料
92
-
93
- - [プラグインシステム](../../../docs/ja/plugin-system.md)
1
+ # @riebeckite/plugin-flashcards
2
+
3
+ `flashcards` コードブロックを学習用のカードデッキに変えるプラグインです。質問を表示して答えをめくり、前後の移動とシャッフルができます。ビルド時には静的なリストを先に出力するため、JavaScript がなくても内容を読めます。
4
+
5
+ [English](./README.md)
6
+
7
+ ## 設定する
8
+
9
+ ```ts
10
+ import { defineConfig } from "@riebeckite/core";
11
+ import { flashcardsPlugin } from "@riebeckite/plugin-flashcards";
12
+
13
+ export default defineConfig({
14
+ // ...
15
+ plugins: [flashcardsPlugin()],
16
+ });
17
+ ```
18
+
19
+ このプラグインは `style.css` とクライアントエントリを追加します。script タグの出力はサイトのレイアウト側が行い、プラグインは宣言だけを担います。
20
+
21
+ ## ブロックの書き方
22
+
23
+ ブロックには 1 枚以上のカードを書きます。カードは `質問 :: 答え` の組です。カード同士は空行または `---` の行で区切り、答えは複数行にまたがってもかまいません。
24
+
25
+ ````md
26
+ ```flashcards
27
+ Which language is this plugin written in? :: TypeScript
28
+
29
+ What does the client render? :: An interactive deck
30
+ ---
31
+ Describe the fallback. :: A static ordered list.
32
+ It stays readable without JavaScript.
33
+ ```
34
+ ````
35
+
36
+ カードが 1 枚もない、`::` のないカードがある、どちらかの側が空である、といった場合は `invalid-flashcards` の診断を出し、コードブロックのまま残します。
37
+
38
+ ## 出力
39
+
40
+ ビルド時に、ブロックは次の要素に置き換わります。
41
+
42
+ ```html
43
+ <div class="rb-flashcards" data-flashcards data-flashcards-count="2">
44
+ <script type="application/json" data-flashcards-payload>
45
+ {"cards":[{"front":"...","back":"..."}]}
46
+ </script>
47
+ <ol class="rb-flashcards__list" data-flashcards-fallback>
48
+ <li class="rb-flashcards__item">
49
+ <span class="rb-flashcards__front">...</span>
50
+ <span class="rb-flashcards__back">...</span>
51
+ </li>
52
+ </ol>
53
+ </div>
54
+ ```
55
+
56
+ payload は実行されない JSON で、`<` `>` `&` はエスケープ済みです。カードの文言にこれらの文字が含まれていても script 要素を閉じることはできません。順序付きリストは JavaScript がない場合の代替表示です。
57
+
58
+ ## クライアントの動作
59
+
60
+ `initFlashcards()` は各 `[data-flashcards]` 要素の payload を読み、代替リストの上に操作できるデッキを組み立てます。対応している操作は次のとおりです。
61
+
62
+ - 答えの表示・非表示
63
+ - 前後のカードへの移動（端で折り返す）
64
+ - シャッフル
65
+ - カード位置の表示
66
+ - キーボード操作: `Space` で答えを表示、`ArrowLeft` / `ArrowRight` で移動
67
+
68
+ 成功するとルートに `data-flashcards="ready"` が付き、静的なリストは非表示になります。payload がない、または壊れている場合は代替表示をそのまま残します。ビルドからクライアントへオプションは渡しません。シャッフルの初期状態は `data-flashcards-shuffle` 属性で伝えます。
69
+
70
+ ## オプション
71
+
72
+ | 項目 | 型 | 既定値 | 説明 |
73
+ | --- | --- | --- | --- |
74
+ | `className` | `string` | `"rb-flashcards"` | デッキのルート CSS クラス |
75
+ | `language` | `string` | `"flashcards"` | 対象にするフェンス言語 |
76
+ | `shuffle` | `boolean` | `false` | 最初からシャッフルした順で表示する |
77
+ | `fallback` | `boolean` | `true` | 静的な順序付きリストを出力する |
78
+
79
+ ## 主なエクスポート
80
+
81
+ - `flashcards(options?)` / `flashcardsPlugin(options?)`: プラグインを作成する
82
+ - `initFlashcards(root?)`: クライアント側を初期化する
83
+ - `parseFlashcards(source)`: ブロックをカードに分解する
84
+ - `splitFlashcardGroups(source)`: ブロックをカードのまとまりに分割する
85
+ - `remarkFlashcards(options?)`: remark 変換を単体で使う
86
+ - `renderFlashcards(cards, options)` / `renderFlashcardsPayload(cards)` /
87
+ `renderFlashcardsFallback(cards, className?)`: ビルド時の描画ヘルパー
88
+ - `resolveFlashcardsOptions(options?)`、`createFlashcardsRuntime(options?)`
89
+ - 型: `FlashcardsOptions`、`FlashcardsCard`、`FlashcardsPayload`、`ResolvedFlashcardsOptions`
90
+
91
+ ## 関連資料
92
+
93
+ - [プラグインシステム](../../../docs/ja/reference/plugin-api.md)
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@riebeckite/plugin-flashcards",
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",
@@ -23,7 +23,7 @@
23
23
  "dependencies": {
24
24
  "@types/mdast": "^4.0.4",
25
25
  "unist-util-visit": "^5.1.0",
26
- "@riebeckite/core": "0.0.12"
26
+ "@riebeckite/core": "0.0.13"
27
27
  },
28
28
  "publishConfig": {
29
29
  "access": "public"