@dice-roller/vue 1.3.2 → 1.4.0
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 +330 -131
- package/dist/types/accessibility.d.ts +2 -0
- package/dist/types/components/DiceRoller.vue.d.ts +56 -0
- package/dist/types/components/DiceRollerBootstrap.vue.d.ts +121 -0
- package/dist/types/components/DiceRollerRenderless.vue.d.ts +36 -0
- package/dist/types/components/DiceRollerTailwind.vue.d.ts +47 -0
- package/dist/types/composables/idGenerator.d.ts +3 -0
- package/dist/types/composables/useDiceRoller.d.ts +8 -0
- package/dist/types/index.d.mts +1 -0
- package/dist/types/index.d.ts +6 -0
- package/dist/types/package.json +3 -0
- package/dist/types/types.d.ts +67 -0
- package/dist/vue.js +581 -34860
- package/dist/vue.umd.cjs +1 -61
- package/package.json +64 -23
- package/dist/favicon.ico +0 -0
package/README.md
CHANGED
|
@@ -1,221 +1,420 @@
|
|
|
1
1
|
<p align="center">
|
|
2
|
-
|
|
2
|
+
<img src="https://dice-roller.github.io/documentation/dice-roller-logo.png" alt="RPG Dice Roller" width="200"/>
|
|
3
3
|
</p>
|
|
4
4
|
|
|
5
5
|
# RPG Dice Roller Vue Components
|
|
6
6
|
|
|
7
|
-
Vue
|
|
7
|
+
Vue components and a composable for rolling dice with [RPG Dice Roller](https://github.com/dice-roller/rpg-dice-roller). Use the Tailwind or Bootstrap component, style the plain HTML component yourself, or build your own interface with the composable or renderless component.
|
|
8
8
|
|
|
9
|
-
|
|
9
|
+
See the [dice roller documentation](https://dice-roller.github.io/documentation/) for supported notation.
|
|
10
10
|
|
|
11
|
-
##
|
|
11
|
+
## Installation
|
|
12
12
|
|
|
13
|
-
|
|
13
|
+
Requires Vue 3.5.45 or newer within Vue 3.
|
|
14
14
|
|
|
15
15
|
```sh
|
|
16
16
|
npm install @dice-roller/vue
|
|
17
17
|
```
|
|
18
18
|
|
|
19
|
-
|
|
19
|
+
Vue and `@dice-roller/rpg-dice-roller` are required peer dependencies. npm installs required peers automatically; with other package managers, ensure compatible versions are installed in your application.
|
|
20
20
|
|
|
21
|
-
|
|
21
|
+
## Quick start
|
|
22
22
|
|
|
23
|
-
|
|
23
|
+
This example uses the plain HTML component, which has no framework styles:
|
|
24
24
|
|
|
25
25
|
```vue
|
|
26
|
-
<script>
|
|
27
|
-
import {
|
|
26
|
+
<script setup>
|
|
27
|
+
import { ref } from 'vue';
|
|
28
|
+
import { DiceRoller } from '@dice-roller/vue';
|
|
29
|
+
|
|
30
|
+
const notation = ref('4d6');
|
|
31
|
+
|
|
32
|
+
function onRoll(expression, result) {
|
|
33
|
+
if (result) console.log(expression, result.total);
|
|
34
|
+
}
|
|
28
35
|
</script>
|
|
29
36
|
|
|
30
37
|
<template>
|
|
31
|
-
|
|
38
|
+
<DiceRoller v-model:notation="notation" @roll="onRoll" />
|
|
32
39
|
</template>
|
|
33
40
|
```
|
|
34
41
|
|
|
35
|
-
|
|
42
|
+
Changing `notation` updates the input; it does not roll automatically. The user can roll with the button or Enter. The HTML components display results, validation errors and a copy button when clipboard support is available.
|
|
43
|
+
|
|
44
|
+
| Export | Use |
|
|
45
|
+
| ---------------------- | ------------------------------------------------------ |
|
|
46
|
+
| `DiceRoller` | Plain HTML with CSS classes for your own styles |
|
|
47
|
+
| `DiceRollerTailwind` | Pre-styled with Tailwind CSS 3 |
|
|
48
|
+
| `DiceRollerBootstrap` | Styled with Bootstrap 5 |
|
|
49
|
+
| `useDiceRoller` | Rolling and clipboard logic for your own Vue interface |
|
|
50
|
+
| `DiceRollerRenderless` | The same logic exposed through a scoped slot |
|
|
36
51
|
|
|
37
|
-
|
|
52
|
+
## Tailwind
|
|
38
53
|
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
54
|
+
Configure [Tailwind CSS 3](https://v3.tailwindcss.com/docs/installation) in your application, and include this package in its content paths:
|
|
55
|
+
|
|
56
|
+
```js
|
|
57
|
+
// tailwind.config.js — add to your existing content paths
|
|
58
|
+
export default {
|
|
59
|
+
content: [
|
|
60
|
+
'./src/**/*.{vue,js,ts}',
|
|
61
|
+
'./node_modules/@dice-roller/vue/dist/*.js',
|
|
62
|
+
],
|
|
63
|
+
};
|
|
64
|
+
```
|
|
44
65
|
|
|
45
|
-
|
|
66
|
+
Your Tailwind stylesheet should include the usual directives:
|
|
46
67
|
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
68
|
+
```css
|
|
69
|
+
@tailwind base;
|
|
70
|
+
@tailwind components;
|
|
71
|
+
@tailwind utilities;
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
```vue
|
|
75
|
+
<script setup>
|
|
76
|
+
import { DiceRollerTailwind } from '@dice-roller/vue';
|
|
77
|
+
</script>
|
|
50
78
|
|
|
51
|
-
|
|
79
|
+
<template>
|
|
80
|
+
<DiceRollerTailwind notation="4d6" />
|
|
81
|
+
</template>
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
The component's dark styles follow your Tailwind `darkMode` configuration.
|
|
85
|
+
|
|
86
|
+
### Customising colours
|
|
87
|
+
|
|
88
|
+
Set CSS variables globally, on an ancestor, or directly on an instance:
|
|
89
|
+
|
|
90
|
+
```css
|
|
91
|
+
.my-dice-theme {
|
|
92
|
+
--dice-roller-primary: #7c3aed;
|
|
93
|
+
--dice-roller-primary-hover: #6d28d9;
|
|
94
|
+
--dice-roller-on-primary: #fff;
|
|
95
|
+
}
|
|
96
|
+
```
|
|
52
97
|
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
| `roll` | `notation` - Value of the rolled notation.<br>`value` - The response of the roll | Emitted after a roll is made |
|
|
98
|
+
```vue
|
|
99
|
+
<DiceRollerTailwind class="my-dice-theme" notation="4d6" />
|
|
100
|
+
```
|
|
57
101
|
|
|
58
|
-
|
|
102
|
+
`primary` sets both button gradient stops, producing a solid button, and colours the result accent and input/button focus border and ring. `primary-hover` applies on hover and focus; it falls back to `primary`. Set `button-from`, `button-to`, `button-hover-from` and `button-hover-to` to customise the gradient instead.
|
|
103
|
+
|
|
104
|
+
All variable names below start with `--dice-roller-`. Where a dark default is listed, a corresponding `-dark` variable is available, such as `--dice-roller-input-surface-dark`. In dark mode, the dark variable takes precedence, followed by the base variable, then the dark default. Without overrides, the component uses the colours below.
|
|
105
|
+
|
|
106
|
+
| Variable | Default / fallback | Purpose |
|
|
107
|
+
| ------------------------- | ----------------------------------------------- | ----------------------------------------------------- |
|
|
108
|
+
| `primary` | Unset; uses the colours below | Shared button, output accent and focus colour |
|
|
109
|
+
| `primary-hover` | `primary`, then existing hover colours | Button hover/focus colour |
|
|
110
|
+
| `on-primary` | `#111827`; `#1f2937` on hover/focus | Button text |
|
|
111
|
+
| `surface` | `#f1f5f9` / dark `#4b5563` | Outer background |
|
|
112
|
+
| `text` | `#1f2937` / dark `#e5e7eb` | Outer text |
|
|
113
|
+
| `border` | `#d1d5db` / dark `#374151` | Input and button borders |
|
|
114
|
+
| `output-surface` | `#fff` / dark `#1e293b` | Result background |
|
|
115
|
+
| `output-text` | `#000` / dark `#e2e8f0` | Result and copy icon text |
|
|
116
|
+
| `output-accent` | `primary`, then `#d4f4c6` / dark `#6b8f63` | Result's left border |
|
|
117
|
+
| `input-surface` | `#fff` / dark `#0f172a` | Input background |
|
|
118
|
+
| `input-text` | `#111827` / dark `#e2e8f0` | Input text |
|
|
119
|
+
| `input-placeholder` | `#6b7280` / dark `#94a3b8` | Input placeholder |
|
|
120
|
+
| `input-placeholder-focus` | `#9ca3af` / dark `#94a3b8` | Focused input placeholder |
|
|
121
|
+
| `focus` | `primary`, then `#d4f4c6` | Input/button focus border and ring |
|
|
122
|
+
| `focus-outline` | `#1f2937` / dark `#fff` | Keyboard focus outline for the input and both buttons |
|
|
123
|
+
| `error` | `#b91c1c` / dark `#fecaca` | Validation and copy error messages |
|
|
124
|
+
| `input-error-text` | `error`, then `#b91c1c` | Invalid input text |
|
|
125
|
+
| `input-error-border` | `#fecaca` | Invalid input border |
|
|
126
|
+
| `input-error-surface` | `#fef2f2` | Invalid input background |
|
|
127
|
+
| `button-from` | `primary`, then `#eda18b` | First button gradient stop |
|
|
128
|
+
| `button-to` | `primary`, then `#d4f4c6` | Second button gradient stop |
|
|
129
|
+
| `button-hover-from` | `primary-hover`, then `primary`, then `#e88c71` | First hover/focus gradient stop |
|
|
130
|
+
| `button-hover-to` | `primary-hover`, then `primary`, then `#bbf0a3` | Second hover/focus gradient stop |
|
|
131
|
+
| `copy-surface` | `#111827` | Copied confirmation background |
|
|
132
|
+
| `copy-text` | `#fff` | Copied confirmation text |
|
|
133
|
+
|
|
134
|
+
## Bootstrap
|
|
135
|
+
|
|
136
|
+
Include Bootstrap's CSS in your application. If it is not already installed:
|
|
59
137
|
|
|
60
|
-
|
|
138
|
+
```sh
|
|
139
|
+
npm install bootstrap
|
|
140
|
+
```
|
|
61
141
|
|
|
62
142
|
```vue
|
|
63
|
-
<script>
|
|
64
|
-
import
|
|
143
|
+
<script setup>
|
|
144
|
+
import 'bootstrap/dist/css/bootstrap.min.css';
|
|
145
|
+
import { DiceRollerBootstrap } from '@dice-roller/vue';
|
|
65
146
|
</script>
|
|
66
147
|
|
|
67
148
|
<template>
|
|
68
|
-
|
|
149
|
+
<DiceRollerBootstrap notation="4d6" btn-variant="primary" />
|
|
69
150
|
</template>
|
|
70
151
|
```
|
|
71
152
|
|
|
72
|
-
The
|
|
153
|
+
The component uses Bootstrap's card, form and button styles. Bootstrap JavaScript is not required. It inherits Bootstrap's theme colours; where Bootstrap colour modes are available, set `data-bs-theme` on the component or an ancestor:
|
|
73
154
|
|
|
74
|
-
|
|
155
|
+
```vue
|
|
156
|
+
<DiceRollerBootstrap data-bs-theme="dark" notation="4d6" />
|
|
157
|
+
```
|
|
75
158
|
|
|
76
|
-
|
|
159
|
+
### Bootstrap props
|
|
77
160
|
|
|
78
|
-
|
|
79
|
-
| ----------------------- | -------- | ----------- | ------------------------------------------------------------ |
|
|
80
|
-
| `bg-variant` | `String` | | Applies one of the Bootstrap theme colour variants to the background |
|
|
81
|
-
| `border-variant` | `String` | | Applies one of the Bootstrap theme colour variants to the border |
|
|
82
|
-
| `btn-label` | `String` | `"Roll"` | Text content to place in the button |
|
|
83
|
-
| `btn-variant` | `String` | `"primary"` | Applies one of the Bootstrap theme colour variants to the button |
|
|
84
|
-
| `id` | `String` | | The `id` attribute of the component |
|
|
85
|
-
| `notation` | `String` | | Notation string to set on the component |
|
|
86
|
-
| `output-bg-variant` | `String` | | Applies one of the Bootstrap theme colour variants to the background of the output container |
|
|
87
|
-
| `output-border-variant` | `String` | | Applies one of the Bootstrap theme colour variants to the border of the output container |
|
|
88
|
-
| `output-text-variant` | `String` | | Applies one of the Bootstrap theme colour variants to the text of the output container |
|
|
89
|
-
| `output-variant` | `String` | | Applies one of the Bootstrap theme colour variants to the output container. This defines the background colour and contrasting text. See Bootstrap [Color & background](https://getbootstrap.com/docs/5.2/helpers/color-background/). |
|
|
90
|
-
| `text-variant` | `String` | | Applies one of the Bootstrap theme colour variants to the text |
|
|
91
|
-
| `variant` | `String` | | Applies one of the Bootstrap theme colour variants to the component. This defines the background colour and contrasting text. See Bootstrap [Color & background](https://getbootstrap.com/docs/5.2/helpers/color-background/). |
|
|
161
|
+
These are additional to the shared component props below. Only `btn-variant` has a default (`primary`); other variants are unset by default.
|
|
92
162
|
|
|
93
|
-
|
|
163
|
+
| Prop | Purpose | Accepted values |
|
|
164
|
+
| ----------------------------------------- | --------------------------------------------------------------- | ----------------------------------------------------------------- |
|
|
165
|
+
| `variant`, `output-variant` | Combined background and contrasting text for the card or result | Theme variants |
|
|
166
|
+
| `bg-variant`, `output-bg-variant` | Card or result background | Theme variants, `body`, `white`, `transparent` |
|
|
167
|
+
| `text-variant`, `output-text-variant` | Card or result text | Theme variants, `body`, `muted`, `white`, `black-50`, `white-50` |
|
|
168
|
+
| `border-variant`, `output-border-variant` | Card or result border | Theme variants, `white` |
|
|
169
|
+
| `btn-variant` | Roll button style | Theme variants, `outline-` followed by a theme variant, or `link` |
|
|
94
170
|
|
|
95
|
-
|
|
96
|
-
| -------- | ------------------------------ |
|
|
97
|
-
| `button` | Content to place in the button |
|
|
171
|
+
Theme variants are `primary`, `secondary`, `success`, `danger`, `warning`, `info`, `light` and `dark`.
|
|
98
172
|
|
|
99
|
-
|
|
173
|
+
## Plain HTML styling
|
|
100
174
|
|
|
101
|
-
|
|
102
|
-
| - | - | - |
|
|
103
|
-
| `notation:change` | `notation` - Current value of the notation input | Change event triggered by the user interaction. Emitted after the notation is changed |
|
|
104
|
-
| `roll` | `notation` - Value of the rolled notation.<br>`value` - The response of the roll | Emitted after a roll is made |
|
|
175
|
+
`DiceRoller` uses `dice-roller` as its root class and as the prefix for its element classes. Set `class-name` to change both:
|
|
105
176
|
|
|
106
|
-
|
|
177
|
+
```vue
|
|
178
|
+
<DiceRoller class-name="my-roller" notation="4d6" />
|
|
179
|
+
```
|
|
107
180
|
|
|
108
|
-
|
|
181
|
+
For the default prefix, the element classes are:
|
|
109
182
|
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
</script>
|
|
183
|
+
- `dice-roller-input-group`, `dice-roller-label`, `dice-roller-input`, `dice-roller-input-invalid`
|
|
184
|
+
- `dice-roller-button`, `dice-roller-output`, `dice-roller-error`
|
|
185
|
+
- `dice-roller-copy-button`, `dice-roller-copy-icon`, `dice-roller-copy-label`, `dice-roller-copy-label-success`, `dice-roller-copy-status`
|
|
114
186
|
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
187
|
+
Provide your own CSS, including copy-icon sizing and visible keyboard focus. Use global styles or Vue's `:deep()` selectors when styling the component's children from a parent with scoped styles.
|
|
188
|
+
|
|
189
|
+
## Component API
|
|
190
|
+
|
|
191
|
+
### Props
|
|
192
|
+
|
|
193
|
+
These props apply to the three HTML components. The renderless component accepts only `notation` and `labels`.
|
|
194
|
+
|
|
195
|
+
| Prop | Type | Default | Description |
|
|
196
|
+
| ------------- | --------------------------- | -------------------- | --------------------------------------------------------------------- |
|
|
197
|
+
| `notation` | `string` | Empty input | Reactive notation source. Use `v-model:notation` for two-way binding. |
|
|
198
|
+
| `labels` | `Partial<DiceRollerLabels>` | Default labels below | Overrides individual interface and error messages. |
|
|
199
|
+
| `btn-label` | `string` | `Roll` | Roll button text. |
|
|
200
|
+
| `id` | `string` | Unset | Container ID. The input receives its own generated ID. |
|
|
201
|
+
| `input-attrs` | `DiceRollerInputAttrs` | `{}` | Attributes passed to the notation input. |
|
|
202
|
+
| `class-name` | `string` | `dice-roller` | Root class and element-class prefix; `DiceRoller` only. |
|
|
203
|
+
|
|
204
|
+
Ordinary attributes such as `class`, `style` and `data-*` are applied to the outer container. Pass input attributes separately:
|
|
205
|
+
|
|
206
|
+
```vue
|
|
207
|
+
<DiceRoller
|
|
208
|
+
class="my-roller"
|
|
209
|
+
:input-attrs="{ autocomplete: 'off', 'aria-describedby': 'notation-help' }"
|
|
210
|
+
/>
|
|
211
|
+
<p id="notation-help">Enter a dice expression, such as 4d6.</p>
|
|
118
212
|
```
|
|
119
213
|
|
|
120
|
-
|
|
214
|
+
The component manages the input's `id`, `value`, `type`, `name` and validation attributes. Existing `aria-describedby` references are preserved alongside validation messages. Setting `input-attrs.disabled` disables the input and roll button.
|
|
215
|
+
|
|
216
|
+
### Events
|
|
217
|
+
|
|
218
|
+
All four components emit these events:
|
|
219
|
+
|
|
220
|
+
| Event | Arguments | Description |
|
|
221
|
+
| ----------------- | ---------------------------------------------- | ----------------------------------------------------------------------- |
|
|
222
|
+
| `update:notation` | `notation: string` | Local notation changed; used by `v-model:notation`. |
|
|
223
|
+
| `notation:change` | `notation: string` | Local notation changed through user input. |
|
|
224
|
+
| `roll` | `notation: string`, `result: DiceRoll \| null` | A roll was attempted. The result is `null` for an empty or failed roll. |
|
|
121
225
|
|
|
122
|
-
|
|
226
|
+
Parent-driven notation changes do not emit notation-change events. Results are dice roll objects; use `result.total` for the total or `String(result)` for the formatted result.
|
|
123
227
|
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
228
|
+
### Button slot
|
|
229
|
+
|
|
230
|
+
The HTML components provide a `button` slot to replace the roll button's content:
|
|
231
|
+
|
|
232
|
+
```vue
|
|
233
|
+
<DiceRoller notation="4d6">
|
|
234
|
+
<template #button>Roll dice</template>
|
|
235
|
+
</DiceRoller>
|
|
236
|
+
```
|
|
130
237
|
|
|
131
|
-
|
|
238
|
+
### Labels
|
|
132
239
|
|
|
133
|
-
|
|
134
|
-
| -------- | ------------------------------ |
|
|
135
|
-
| `button` | Content to place in the button |
|
|
240
|
+
Pass any of these keys in `labels`; unspecified keys retain their defaults:
|
|
136
241
|
|
|
137
|
-
|
|
242
|
+
| Key | Default |
|
|
243
|
+
| ----------------- | ------------------------------------------------ |
|
|
244
|
+
| `notation` | `Notation` |
|
|
245
|
+
| `copy` | `Copy to clipboard` |
|
|
246
|
+
| `copied` | `Copied!` |
|
|
247
|
+
| `copyError` | `Unable to copy to clipboard. Please try again.` |
|
|
248
|
+
| `invalidNotation` | `Invalid notation` |
|
|
249
|
+
| `error` | `An error has occurred` |
|
|
138
250
|
|
|
139
|
-
|
|
140
|
-
| - | - | - |
|
|
141
|
-
| `notation:change` | `notation` - Current value of the notation input | Change event triggered by the user interaction. Emitted after the notation is changed |
|
|
142
|
-
| `roll` | `notation` - Value of the rolled notation.<br>`value` - The response of the roll | Emitted after a roll is made |
|
|
251
|
+
`invalidNotation` and `error` prefix the underlying error message.
|
|
143
252
|
|
|
144
|
-
|
|
253
|
+
## Composable
|
|
145
254
|
|
|
146
|
-
|
|
255
|
+
Call `useDiceRoller()` synchronously inside `setup()` or `<script setup>`. Each call creates independent state.
|
|
147
256
|
|
|
148
257
|
```vue
|
|
149
|
-
<script>
|
|
150
|
-
import {
|
|
258
|
+
<script setup>
|
|
259
|
+
import { useId } from 'vue';
|
|
260
|
+
import { useDiceRoller } from '@dice-roller/vue';
|
|
261
|
+
|
|
262
|
+
const inputId = useId();
|
|
263
|
+
const { bind, on, roll, output, error, labels, copy } = useDiceRoller({
|
|
264
|
+
notation: '4d6',
|
|
265
|
+
});
|
|
151
266
|
</script>
|
|
152
267
|
|
|
153
268
|
<template>
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
269
|
+
<div>
|
|
270
|
+
<label :for="inputId">{{ labels.notation }}</label>
|
|
271
|
+
<input
|
|
272
|
+
:id="inputId"
|
|
273
|
+
v-bind="bind"
|
|
274
|
+
v-on="on"
|
|
275
|
+
:aria-invalid="error ? 'true' : undefined"
|
|
276
|
+
:aria-describedby="error ? `${inputId}-error` : undefined"
|
|
277
|
+
/>
|
|
278
|
+
<button type="button" :disabled="!bind.value" @click="roll">Roll</button>
|
|
279
|
+
<p v-if="error" :id="`${inputId}-error`" role="alert">{{ error }}</p>
|
|
280
|
+
<output :for="inputId" aria-live="polite">{{ output }}</output>
|
|
281
|
+
<button
|
|
282
|
+
v-if="copy.isSupported && output"
|
|
283
|
+
type="button"
|
|
284
|
+
@click="copy.copy()"
|
|
285
|
+
>
|
|
286
|
+
{{ labels.copy }}
|
|
287
|
+
</button>
|
|
288
|
+
<span role="status">{{
|
|
289
|
+
copy.error || (copy.copied ? labels.copied : '')
|
|
290
|
+
}}</span>
|
|
291
|
+
</div>
|
|
292
|
+
</template>
|
|
293
|
+
```
|
|
157
294
|
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
<button type="button" @click="roll">Roll</button>
|
|
295
|
+
### Options
|
|
161
296
|
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
297
|
+
| Option | Description |
|
|
298
|
+
| ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
299
|
+
| `notation` | String, ref or getter supplying the notation; `null` or `undefined` clears it. Defaults to an empty string. Reactive source changes update the local notation. |
|
|
300
|
+
| `labels` | Object, ref or getter supplying partial label overrides. |
|
|
301
|
+
| `onNotationChange(notation)` | Called once per local edit through the input handlers, `setNotation()` or `currentNotation`. Source updates do not call it. |
|
|
302
|
+
| `onRoll(notation, result)` | Called after each roll attempt, with a dice roll object or `null` for an empty or failed roll. |
|
|
165
303
|
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
304
|
+
A notation ref/getter is an input source, not an automatically updated model. Use the callback for two-way synchronisation:
|
|
305
|
+
|
|
306
|
+
```js
|
|
307
|
+
import { ref } from 'vue';
|
|
308
|
+
import { useDiceRoller } from '@dice-roller/vue';
|
|
309
|
+
|
|
310
|
+
const notation = ref('4d6');
|
|
311
|
+
const roller = useDiceRoller({
|
|
312
|
+
notation,
|
|
313
|
+
onNotationChange: (value) => {
|
|
314
|
+
notation.value = value;
|
|
315
|
+
},
|
|
316
|
+
});
|
|
170
317
|
```
|
|
171
318
|
|
|
172
|
-
|
|
319
|
+
For component props, pass getters such as `notation: () => props.notation` and `labels: () => props.labels` to retain reactivity.
|
|
173
320
|
|
|
174
|
-
|
|
321
|
+
### Return values
|
|
175
322
|
|
|
176
|
-
|
|
177
|
-
| ---------- | -------- | ------- | --------------------------------------- |
|
|
178
|
-
| `notation` | `String` | | Notation string to set on the component |
|
|
323
|
+
Destructure the return object in setup. Refs use `.value` in JavaScript and unwrap as top-level bindings in templates.
|
|
179
324
|
|
|
180
|
-
|
|
325
|
+
| Value | Type | Description |
|
|
326
|
+
| ----------------------- | --------------------- | ----------------------------------------------------------------------------- |
|
|
327
|
+
| `currentNotation` | Writable computed ref | Editable notation. Assigning a different value calls `onNotationChange`. |
|
|
328
|
+
| `setNotation(notation)` | Function | Updates the local notation. |
|
|
329
|
+
| `output` | Ref | Latest `DiceRoll`, or `null` before a roll and after an empty or failed roll. |
|
|
330
|
+
| `error` | Ref | Roll error message or `null`; cleared at the next roll attempt. |
|
|
331
|
+
| `roll()` | Function | Rolls the current notation and updates the result/error state. |
|
|
332
|
+
| `labels` | Computed ref | Resolved interface and error labels. |
|
|
333
|
+
| `bind` | Computed ref | `{ value: string }` input binding. |
|
|
334
|
+
| `on` | Object | `input`, `change` and `keydown` handlers for `v-on`. |
|
|
335
|
+
| `copy` | Reactive object | Clipboard methods and state, described below. |
|
|
181
336
|
|
|
182
|
-
|
|
183
|
-
| --------- | ------------------------ |
|
|
184
|
-
| `default` | Content of the component |
|
|
337
|
+
Use `v-bind="bind"` and `v-on="on"` together. Alternatively, use `v-model="currentNotation"` with `@keydown="on.keydown"`. Enter rolls without submitting a surrounding form; held-key repeats and Enter during IME composition are ignored.
|
|
185
338
|
|
|
186
|
-
|
|
339
|
+
### Clipboard
|
|
187
340
|
|
|
188
|
-
|
|
189
|
-
| - | - | - |
|
|
190
|
-
| `notation:change` | `notation` - Current value of the notation input | Change event triggered by the user interaction. Emitted after the notation is changed |
|
|
191
|
-
| `roll` | `notation` - Value of the rolled notation.<br>`value` - The response of the roll | Emitted after a roll is made |
|
|
341
|
+
The composable and renderless component expose the same `copy` object:
|
|
192
342
|
|
|
193
|
-
|
|
343
|
+
| Member | Description |
|
|
344
|
+
| ------------- | --------------------------------------------------------------------------------- |
|
|
345
|
+
| `copy()` | Asynchronously copies the latest formatted result; does nothing without a result. |
|
|
346
|
+
| `isSupported` | Whether the browser provides the Clipboard API. |
|
|
347
|
+
| `copied` | `true` after a successful copy, resetting after 1.5 seconds. |
|
|
348
|
+
| `text` | Last successfully copied text. |
|
|
349
|
+
| `error` | Copy error message or `null`. |
|
|
194
350
|
|
|
195
|
-
|
|
351
|
+
Access state as `copy.copied`, `copy.error`, etc.; these values are already unwrapped. Destructuring those primitive properties loses reactivity. Clipboard access normally requires HTTPS or localhost and browser permission.
|
|
196
352
|
|
|
197
|
-
|
|
353
|
+
## Renderless component
|
|
198
354
|
|
|
199
|
-
|
|
355
|
+
`DiceRollerRenderless` renders only its default slot. It accepts `notation` and `labels`, supports `v-model:notation`, and emits the shared component events.
|
|
200
356
|
|
|
201
|
-
```
|
|
202
|
-
|
|
357
|
+
```vue
|
|
358
|
+
<script setup>
|
|
359
|
+
import { DiceRollerRenderless } from '@dice-roller/vue';
|
|
360
|
+
</script>
|
|
361
|
+
|
|
362
|
+
<template>
|
|
363
|
+
<DiceRollerRenderless
|
|
364
|
+
notation="4d6"
|
|
365
|
+
v-slot="{ bind, on, roll, output, error }"
|
|
366
|
+
>
|
|
367
|
+
<div>
|
|
368
|
+
<label for="custom-notation">Notation</label>
|
|
369
|
+
<input
|
|
370
|
+
id="custom-notation"
|
|
371
|
+
v-bind="bind"
|
|
372
|
+
v-on="on"
|
|
373
|
+
:aria-invalid="error ? 'true' : undefined"
|
|
374
|
+
:aria-describedby="error ? 'custom-error' : undefined"
|
|
375
|
+
/>
|
|
376
|
+
<button type="button" :disabled="!bind.value" @click="roll">Roll</button>
|
|
377
|
+
<p v-if="error" id="custom-error" role="alert">{{ error }}</p>
|
|
378
|
+
<output for="custom-notation" aria-live="polite">{{ output }}</output>
|
|
379
|
+
</div>
|
|
380
|
+
</DiceRollerRenderless>
|
|
381
|
+
</template>
|
|
203
382
|
```
|
|
204
383
|
|
|
205
|
-
|
|
384
|
+
Use unique input and error IDs when rendering multiple instances.
|
|
206
385
|
|
|
207
|
-
|
|
208
|
-
npm run dev
|
|
209
|
-
```
|
|
386
|
+
### Default slot values
|
|
210
387
|
|
|
211
|
-
|
|
388
|
+
| Value | Description |
|
|
389
|
+
| ----------------- | ---------------------------------------------------------------------------- |
|
|
390
|
+
| `currentNotation` | Current notation string. |
|
|
391
|
+
| `bind` | `{ value: string }` binding for the notation input. |
|
|
392
|
+
| `on` | `input`, `change` and `keydown` event handlers. |
|
|
393
|
+
| `roll` | Function that rolls the current notation. |
|
|
394
|
+
| `output` | Latest `DiceRoll` object or `null`. |
|
|
395
|
+
| `error` | Roll error message or `null`. |
|
|
396
|
+
| `labels` | Resolved interface and error labels. |
|
|
397
|
+
| `copy` | Clipboard object with `copy()`, `isSupported`, `copied`, `text` and `error`. |
|
|
212
398
|
|
|
213
|
-
|
|
214
|
-
|
|
399
|
+
Slot values are already unwrapped; use them directly in the template.
|
|
400
|
+
|
|
401
|
+
## TypeScript
|
|
402
|
+
|
|
403
|
+
Declarations for the components, composable, events and slots are included. No separate types package is needed. Public types can be imported from the same entry point:
|
|
404
|
+
|
|
405
|
+
```ts
|
|
406
|
+
import type { DiceRollerLabels, UseDiceRollerOptions } from '@dice-roller/vue';
|
|
407
|
+
|
|
408
|
+
const labels: Partial<DiceRollerLabels> = { copy: 'Copy result' };
|
|
409
|
+
const options: UseDiceRollerOptions = { notation: '4d6', labels };
|
|
215
410
|
```
|
|
216
411
|
|
|
217
|
-
|
|
412
|
+
## Other import formats
|
|
218
413
|
|
|
219
|
-
|
|
220
|
-
|
|
414
|
+
CommonJS is also supported:
|
|
415
|
+
|
|
416
|
+
```js
|
|
417
|
+
const { DiceRoller, useDiceRoller } = require('@dice-roller/vue');
|
|
221
418
|
```
|
|
419
|
+
|
|
420
|
+
For direct browser scripts, load Vue and the dice roller library's UMD build and its required dependencies before `dist/vue.umd.cjs`. The Vue component package is available as `DiceRollerVue`; its dependencies must provide the globals `Vue` and `rpgDiceRoller`.
|
|
@@ -0,0 +1,56 @@
|
|
|
1
|
+
import type { PropType } from 'vue';
|
|
2
|
+
import type { DiceRollerLabels, DiceRollerInputAttrs, DiceRollerSlots } from '../types.js';
|
|
3
|
+
type __VLS_Slots = DiceRollerSlots;
|
|
4
|
+
declare const __VLS_base: import("vue").DefineComponent<import("vue").ExtractPropTypes<{
|
|
5
|
+
btnLabel: {
|
|
6
|
+
type: StringConstructor;
|
|
7
|
+
default: string;
|
|
8
|
+
};
|
|
9
|
+
className: {
|
|
10
|
+
type: StringConstructor;
|
|
11
|
+
default: string;
|
|
12
|
+
};
|
|
13
|
+
id: StringConstructor;
|
|
14
|
+
notation: StringConstructor;
|
|
15
|
+
labels: PropType<Partial<DiceRollerLabels>>;
|
|
16
|
+
inputAttrs: {
|
|
17
|
+
type: PropType<DiceRollerInputAttrs>;
|
|
18
|
+
default: () => {};
|
|
19
|
+
};
|
|
20
|
+
}>, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
|
|
21
|
+
roll: (notation: string, result: import("@dice-roller/rpg-dice-roller").DiceRoll | null) => any;
|
|
22
|
+
"notation:change": (notation: string) => any;
|
|
23
|
+
"update:notation": (notation: string) => any;
|
|
24
|
+
}, string, import("vue").PublicProps, Readonly<import("vue").ExtractPropTypes<{
|
|
25
|
+
btnLabel: {
|
|
26
|
+
type: StringConstructor;
|
|
27
|
+
default: string;
|
|
28
|
+
};
|
|
29
|
+
className: {
|
|
30
|
+
type: StringConstructor;
|
|
31
|
+
default: string;
|
|
32
|
+
};
|
|
33
|
+
id: StringConstructor;
|
|
34
|
+
notation: StringConstructor;
|
|
35
|
+
labels: PropType<Partial<DiceRollerLabels>>;
|
|
36
|
+
inputAttrs: {
|
|
37
|
+
type: PropType<DiceRollerInputAttrs>;
|
|
38
|
+
default: () => {};
|
|
39
|
+
};
|
|
40
|
+
}>> & Readonly<{
|
|
41
|
+
onRoll?: ((notation: string, result: import("@dice-roller/rpg-dice-roller").DiceRoll | null) => any) | undefined;
|
|
42
|
+
"onNotation:change"?: ((notation: string) => any) | undefined;
|
|
43
|
+
"onUpdate:notation"?: ((notation: string) => any) | undefined;
|
|
44
|
+
}>, {
|
|
45
|
+
btnLabel: string;
|
|
46
|
+
className: string;
|
|
47
|
+
inputAttrs: DiceRollerInputAttrs;
|
|
48
|
+
}, {}, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;
|
|
49
|
+
declare const __VLS_export: __VLS_WithSlots<typeof __VLS_base, __VLS_Slots>;
|
|
50
|
+
declare const _default: typeof __VLS_export;
|
|
51
|
+
export default _default;
|
|
52
|
+
type __VLS_WithSlots<T, S> = T & {
|
|
53
|
+
new (): {
|
|
54
|
+
$slots: S;
|
|
55
|
+
};
|
|
56
|
+
};
|