@dice-roller/vue 1.3.3 → 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 CHANGED
@@ -1,221 +1,420 @@
1
1
  <p align="center">
2
- <img src="https://dice-roller.github.io/documentation/dice-roller-logo.png" alt="RPG Dice Roller" style="max-width: 100%;" width="200"/>
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.js component which allows rolling dice.
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
- It is built upon this [RPG dice roller](https://github.com/dice-roller/rpg-dice-roller), and is used in the [documentation](https://dice-roller.github.io/documentation/).
9
+ See the [dice roller documentation](https://dice-roller.github.io/documentation/) for supported notation.
10
10
 
11
- ## Get started
11
+ ## Installation
12
12
 
13
- ### Install
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
- ### Components
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
- ### Tailwind
21
+ ## Quick start
22
22
 
23
- If you're using [Tailwind](https://tailwindcss.com/) v3, you can use the pre-styled Tailwind component:
23
+ This example uses the plain HTML component, which has no framework styles:
24
24
 
25
25
  ```vue
26
- <script>
27
- import { DiceRollerTailwind } from '@dice-roller/vue'
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
- <DiceRollerTailwind />
38
+ <DiceRoller v-model:notation="notation" @roll="onRoll" />
32
39
  </template>
33
40
  ```
34
41
 
35
- #### Component reference
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
- ##### Properties
52
+ ## Tailwind
38
53
 
39
- | Property | Type | Default | Description |
40
- | ----------- | -------- | -------- | --------------------------------------- |
41
- | `btn-label` | `String` | `"Roll"` | Text content to place in the button |
42
- | `id` | `String` | | The `id` attribute of the component |
43
- | `notation` | `String` | | Notation string to set on the component |
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
- ##### Slots
66
+ Your Tailwind stylesheet should include the usual directives:
46
67
 
47
- | Name | Description |
48
- | -------- | ------------------------------ |
49
- | `button` | Content to place in the button |
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
- ##### Events
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
- | Event | Arguments | Description |
54
- | - | - | - |
55
- | `notation:change` | `notation` - Current value of the notation input | Change event triggered by the user interaction. Emitted after the notation is changed |
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
- ### Bootstrap
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
- If you're using [Bootstrap](https://getbootstrap.com/) v5, you can use the Bootstrap component:
138
+ ```sh
139
+ npm install bootstrap
140
+ ```
61
141
 
62
142
  ```vue
63
- <script>
64
- import { DiceRollerBootstrap } from '@dice-roller/vue'
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
- <DiceRollerBootstrap />
149
+ <DiceRollerBootstrap notation="4d6" btn-variant="primary" />
69
150
  </template>
70
151
  ```
71
152
 
72
- The Bootstrap component is wrapped in a [card](https://getbootstrap.com/docs/5.2/components/card/), and uses other bootstrap components. It can be easily styled.
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
- #### Component reference
155
+ ```vue
156
+ <DiceRollerBootstrap data-bs-theme="dark" notation="4d6" />
157
+ ```
75
158
 
76
- ##### Properties
159
+ ### Bootstrap props
77
160
 
78
- | Property | Type | Default | Description |
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
- ##### Slots
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
- | Name | Description |
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
- ##### Events
173
+ ## Plain HTML styling
100
174
 
101
- | Event | Arguments | Description |
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
- ### Plain HTML
177
+ ```vue
178
+ <DiceRoller class-name="my-roller" notation="4d6" />
179
+ ```
107
180
 
108
- There's also a basic component, which provides HTML markup, without any styling. It applies a class to the elements, so you can style it with your own CSS.
181
+ For the default prefix, the element classes are:
109
182
 
110
- ```vue
111
- <script>
112
- import { DiceRoller } from '@dice-roller/vue'
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
- <template>
116
- <DiceRoller />
117
- </template>
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
- #### Component reference
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
- ##### Properties
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
- | Property | Type | Default | Description |
125
- | ------------ | -------- | --------------- | --------------------------------------- |
126
- | `btn-label` | `String` | `"Roll"` | Text content to place in the button |
127
- | `class-name` | `String` | `"dice-roller"` | The class name of the component |
128
- | `id` | `String` | | The `id` attribute of the component |
129
- | `notation` | `String` | | Notation string to set on the component |
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
- ##### Slots
238
+ ### Labels
132
239
 
133
- | Name | Description |
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
- ##### Events
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
- | Event | Arguments | Description |
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
- ### Renderless component
253
+ ## Composable
145
254
 
146
- If you want to write your own HTML markup, you can use the renderless component instead. This provides the logic and functionality, without any markup, so you can build your own.
255
+ Call `useDiceRoller()` synchronously inside `setup()` or `<script setup>`. Each call creates independent state.
147
256
 
148
257
  ```vue
149
- <script>
150
- import { DiceRollerRenderless } from '@dice-roller/vue';
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
- <DiceRollerRenderless v-slot="{ currentNotation, error, output, roll, on, bind }">
155
- <div>
156
- <div v-if="error">{{ error }}</div>
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
- <input type="text" v-on="on" v-bind="bind" />
159
-
160
- <button type="button" @click="roll">Roll</button>
295
+ ### Options
161
296
 
162
- <div>
163
- <strong>Notation:</strong> <em>{{ currentNotation }}</em>
164
- </div>
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
- <output v-if="output">{{ output }}</output>
167
- </div>
168
- </DiceRollerRenderless>
169
- </template>
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
- #### Component reference
319
+ For component props, pass getters such as `notation: () => props.notation` and `labels: () => props.labels` to retain reactivity.
173
320
 
174
- ##### Properties
321
+ ### Return values
175
322
 
176
- | Property | Type | Default | Description |
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
- ##### Slots
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
- | Name | Description |
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
- ##### Events
339
+ ### Clipboard
187
340
 
188
- | Event | Arguments | Description |
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
- ## Development
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
- ### Customise configuration
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
- See [Vite Configuration Reference](https://vitejs.dev/config/).
353
+ ## Renderless component
198
354
 
199
- ### Project Setup
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
- ```sh
202
- npm install @dice-roller/vue
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
- #### Compile and Hot-Reload for Development
384
+ Use unique input and error IDs when rendering multiple instances.
206
385
 
207
- ```sh
208
- npm run dev
209
- ```
386
+ ### Default slot values
210
387
 
211
- #### Compile and Minify for Production
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
- ```sh
214
- npm run build
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
- #### Lint with [ESLint](https://eslint.org/)
412
+ ## Other import formats
218
413
 
219
- ```sh
220
- npm run lint
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,2 @@
1
+ import type { CSSProperties } from 'vue';
2
+ export declare const visuallyHiddenStyle: CSSProperties;
@@ -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
+ };