maz-ui 5.0.0 → 5.1.0-beta.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.
Files changed (186) hide show
  1. package/dist/assets/{MazDropzone.DJ8au25t.css → MazDropzone.BW2grpTi.css} +1 -1
  2. package/dist/chunks/{MazDrawer.DANxKYxJ.js → MazDrawer.CC8zomfx.js} +2 -2
  3. package/dist/chunks/{MazDropzone.POH3pmfi.js → MazDropzone.Dez5j0WP.js} +2 -2
  4. package/dist/components/MazDrawer.js +1 -1
  5. package/dist/components/MazDropzone.js +1 -1
  6. package/dist/components/MazDropzone.vue.d.ts +2 -2
  7. package/dist/components/MazInputPrice.vue.d.ts +1 -1
  8. package/dist/components/index.js +2 -2
  9. package/docs/README.md +207 -0
  10. package/docs/agents/agents-md.md +52 -0
  11. package/docs/agents/claude-rule.md +52 -0
  12. package/docs/components/maz-accordion.md +76 -0
  13. package/docs/components/maz-alert.md +241 -0
  14. package/docs/components/maz-animated-counter.md +87 -0
  15. package/docs/components/maz-animated-element.md +46 -0
  16. package/docs/components/maz-animated-text.md +53 -0
  17. package/docs/components/maz-avatar.md +193 -0
  18. package/docs/components/maz-backdrop.md +178 -0
  19. package/docs/components/maz-badge.md +167 -0
  20. package/docs/components/maz-bottom-sheet.md +257 -0
  21. package/docs/components/maz-btn-group.md +316 -0
  22. package/docs/components/maz-btn.md +423 -0
  23. package/docs/components/maz-card-spotlight.md +84 -0
  24. package/docs/components/maz-card.md +321 -0
  25. package/docs/components/maz-carousel.md +153 -0
  26. package/docs/components/maz-chart.md +206 -0
  27. package/docs/components/maz-checkbox.md +138 -0
  28. package/docs/components/maz-checklist.md +251 -0
  29. package/docs/components/maz-circular-progress-bar.md +109 -0
  30. package/docs/components/maz-code-highlight.md +155 -0
  31. package/docs/components/maz-container.md +241 -0
  32. package/docs/components/maz-date-picker.md +791 -0
  33. package/docs/components/maz-dialog-confirm.md +215 -0
  34. package/docs/components/maz-dialog.md +143 -0
  35. package/docs/components/maz-drawer.md +106 -0
  36. package/docs/components/maz-dropdown.md +419 -0
  37. package/docs/components/maz-dropzone.md +387 -0
  38. package/docs/components/maz-expand-animation.md +82 -0
  39. package/docs/components/maz-fullscreen-loader.md +58 -0
  40. package/docs/components/maz-gallery.md +79 -0
  41. package/docs/components/maz-icon.md +203 -0
  42. package/docs/components/maz-input-code.md +73 -0
  43. package/docs/components/maz-input-number.md +79 -0
  44. package/docs/components/maz-input-phone-number.md +536 -0
  45. package/docs/components/maz-input-price.md +68 -0
  46. package/docs/components/maz-input-tags.md +112 -0
  47. package/docs/components/maz-input.md +334 -0
  48. package/docs/components/maz-lazy-img.md +113 -0
  49. package/docs/components/maz-link.md +146 -0
  50. package/docs/components/maz-loading-bar.md +38 -0
  51. package/docs/components/maz-markdown-editor.md +320 -0
  52. package/docs/components/maz-pagination.md +82 -0
  53. package/docs/components/maz-popover.md +794 -0
  54. package/docs/components/maz-pull-to-refresh.md +222 -0
  55. package/docs/components/maz-radio-buttons.md +313 -0
  56. package/docs/components/maz-radio.md +119 -0
  57. package/docs/components/maz-read-more.md +209 -0
  58. package/docs/components/maz-reading-progress-bar.md +96 -0
  59. package/docs/components/maz-select-country.md +513 -0
  60. package/docs/components/maz-select.md +318 -0
  61. package/docs/components/maz-sidebar-content.md +25 -0
  62. package/docs/components/maz-sidebar-footer.md +25 -0
  63. package/docs/components/maz-sidebar-group.md +27 -0
  64. package/docs/components/maz-sidebar-header.md +25 -0
  65. package/docs/components/maz-sidebar-menu-button.md +41 -0
  66. package/docs/components/maz-sidebar-menu-item.md +25 -0
  67. package/docs/components/maz-sidebar-menu-sub.md +32 -0
  68. package/docs/components/maz-sidebar-menu.md +25 -0
  69. package/docs/components/maz-sidebar-separator.md +21 -0
  70. package/docs/components/maz-sidebar-trigger.md +25 -0
  71. package/docs/components/maz-sidebar.md +507 -0
  72. package/docs/components/maz-skeleton.md +226 -0
  73. package/docs/components/maz-slider.md +165 -0
  74. package/docs/components/maz-spinner.md +84 -0
  75. package/docs/components/maz-stepper.md +301 -0
  76. package/docs/components/maz-switch.md +86 -0
  77. package/docs/components/maz-table-cell.md +27 -0
  78. package/docs/components/maz-table-row.md +28 -0
  79. package/docs/components/maz-table-title.md +27 -0
  80. package/docs/components/maz-table-virtualizer.md +31 -0
  81. package/docs/components/maz-table.md +426 -0
  82. package/docs/components/maz-tabs-bar.md +43 -0
  83. package/docs/components/maz-tabs-content-item.md +27 -0
  84. package/docs/components/maz-tabs-content.md +27 -0
  85. package/docs/components/maz-tabs.md +308 -0
  86. package/docs/components/maz-textarea.md +255 -0
  87. package/docs/components/maz-ticker.md +427 -0
  88. package/docs/components/maz-timeline.md +304 -0
  89. package/docs/components/maz-ui-provider.md +26 -0
  90. package/docs/components/maz-window-mockup.md +182 -0
  91. package/docs/composables/use-aos.md +41 -0
  92. package/docs/composables/use-breakpoints.md +42 -0
  93. package/docs/composables/use-dialog.md +58 -0
  94. package/docs/composables/use-display-names.md +130 -0
  95. package/docs/composables/use-drag.md +185 -0
  96. package/docs/composables/use-form-validator.md +1123 -0
  97. package/docs/composables/use-idle-timeout.md +172 -0
  98. package/docs/composables/use-pull-to-refresh.md +86 -0
  99. package/docs/composables/use-reading-time.md +132 -0
  100. package/docs/composables/use-string-matching.md +41 -0
  101. package/docs/composables/use-swipe.md +171 -0
  102. package/docs/composables/use-timer.md +104 -0
  103. package/docs/composables/use-toast.md +50 -0
  104. package/docs/composables/use-user-visibility.md +127 -0
  105. package/docs/composables/use-wait.md +50 -0
  106. package/docs/composables/use-window-size.md +25 -0
  107. package/docs/directives/click-outside.md +182 -0
  108. package/docs/directives/fullscreen-img.md +83 -0
  109. package/docs/directives/lazy-img.md +182 -0
  110. package/docs/directives/tooltip.md +298 -0
  111. package/docs/directives/zoom-img.md +100 -0
  112. package/docs/ecosystem/eslint-config.md +289 -0
  113. package/docs/ecosystem/icons/icon-set.md +25 -0
  114. package/docs/ecosystem/icons/index.md +584 -0
  115. package/docs/ecosystem/mcp.md +165 -0
  116. package/docs/ecosystem/node/exec-promise.md +93 -0
  117. package/docs/ecosystem/node/index.md +53 -0
  118. package/docs/ecosystem/node/logger.md +152 -0
  119. package/docs/ecosystem/node/print-banner.md +101 -0
  120. package/docs/ecosystem/node/setup-agents.md +102 -0
  121. package/docs/ecosystem/nuxt.md +551 -0
  122. package/docs/ecosystem/stylelint-config.md +310 -0
  123. package/docs/ecosystem/themes.md +966 -0
  124. package/docs/ecosystem/translations.md +1173 -0
  125. package/docs/ecosystem/utils/camel-case.md +37 -0
  126. package/docs/ecosystem/utils/capitalize.md +37 -0
  127. package/docs/ecosystem/utils/check-availability.md +85 -0
  128. package/docs/ecosystem/utils/cookie.md +86 -0
  129. package/docs/ecosystem/utils/country-code-to-unicode-flag.md +128 -0
  130. package/docs/ecosystem/utils/currency.md +53 -0
  131. package/docs/ecosystem/utils/date.md +53 -0
  132. package/docs/ecosystem/utils/debounce-callback.md +44 -0
  133. package/docs/ecosystem/utils/debounce-id.md +75 -0
  134. package/docs/ecosystem/utils/debounce.md +71 -0
  135. package/docs/ecosystem/utils/fetch-locale-ip.md +39 -0
  136. package/docs/ecosystem/utils/format-json.md +39 -0
  137. package/docs/ecosystem/utils/format-phone-number.md +43 -0
  138. package/docs/ecosystem/utils/get-browser-locale.md +35 -0
  139. package/docs/ecosystem/utils/get-country-flag-url.md +67 -0
  140. package/docs/ecosystem/utils/get-error-message.md +45 -0
  141. package/docs/ecosystem/utils/idle-timeout.md +96 -0
  142. package/docs/ecosystem/utils/index.md +57 -0
  143. package/docs/ecosystem/utils/is-client.md +38 -0
  144. package/docs/ecosystem/utils/is-equal.md +44 -0
  145. package/docs/ecosystem/utils/is-ios.md +43 -0
  146. package/docs/ecosystem/utils/is-server.md +37 -0
  147. package/docs/ecosystem/utils/is-standalone-mode.md +49 -0
  148. package/docs/ecosystem/utils/kebab-case.md +42 -0
  149. package/docs/ecosystem/utils/normalize-string.md +83 -0
  150. package/docs/ecosystem/utils/number.md +51 -0
  151. package/docs/ecosystem/utils/pascal-case.md +41 -0
  152. package/docs/ecosystem/utils/prevent-ios-input-zoom.md +72 -0
  153. package/docs/ecosystem/utils/script-loader.md +85 -0
  154. package/docs/ecosystem/utils/sleep.md +65 -0
  155. package/docs/ecosystem/utils/snake-case.md +42 -0
  156. package/docs/ecosystem/utils/swipe-handler.md +97 -0
  157. package/docs/ecosystem/utils/textarea-autogrow.md +47 -0
  158. package/docs/ecosystem/utils/throttle-id.md +54 -0
  159. package/docs/ecosystem/utils/throttle.md +63 -0
  160. package/docs/ecosystem/utils/truthy-filter.md +37 -0
  161. package/docs/ecosystem/utils/types/deep-key-of.md +54 -0
  162. package/docs/ecosystem/utils/types/deep-partial.md +48 -0
  163. package/docs/ecosystem/utils/types/deep-required.md +45 -0
  164. package/docs/ecosystem/utils/types/flatten-object-keys.md +50 -0
  165. package/docs/ecosystem/utils/types/generic-instance-type.md +48 -0
  166. package/docs/ecosystem/utils/types/infer-maybe-ref.md +41 -0
  167. package/docs/ecosystem/utils/upper-first.md +38 -0
  168. package/docs/ecosystem/utils/user-visibility.md +75 -0
  169. package/docs/guide/ai-agents.md +237 -0
  170. package/docs/guide/browser-support.md +88 -0
  171. package/docs/guide/getting-started.md +191 -0
  172. package/docs/guide/global-defaults.md +103 -0
  173. package/docs/guide/maz-ui-provider.md +231 -0
  174. package/docs/guide/migration-v5.md +871 -0
  175. package/docs/guide/resolvers.md +650 -0
  176. package/docs/guide/tailwind.md +483 -0
  177. package/docs/guide/vue.md +286 -0
  178. package/docs/manifest.json +1 -0
  179. package/docs/plugins/aos.md +312 -0
  180. package/docs/plugins/dialog.md +269 -0
  181. package/docs/plugins/toast.md +221 -0
  182. package/docs/plugins/wait.md +78 -0
  183. package/docs/reference/icons.md +46 -0
  184. package/docs/reference/tailwind-tokens.md +191 -0
  185. package/docs/rules.md +57 -0
  186. package/package.json +31 -4
@@ -0,0 +1,222 @@
1
+ ---
2
+ title: "MazPullToRefresh"
3
+ description: "MazPullToRefresh adds a native-feeling pull to refresh gesture to your app or to any scroll container, with a progress ring, haptic feedback and translated, accessible feedback."
4
+ package: "maz-ui"
5
+ url: "https://maz-ui.com/components/maz-pull-to-refresh"
6
+ ---
7
+
8
+ # MazPullToRefresh
9
+
10
+ > MazPullToRefresh adds a native-feeling pull to refresh gesture to your app or to any scroll container, with a progress ring, haptic feedback and translated, accessible feedback.
11
+
12
+ - Package: `maz-ui`
13
+ - Import: `import MazPullToRefresh from 'maz-ui/components/MazPullToRefresh'`
14
+ - Nuxt: auto-imported by `@maz-ui/nuxt`, no import needed in a Nuxt app
15
+ - Web: https://maz-ui.com/components/maz-pull-to-refresh
16
+
17
+ > Before use it, you should install the MazUi plugin in your project, follow instructions in [Getting Started](../guide/getting-started.md)
18
+
19
+ ## Key Features
20
+
21
+ - Works on the window **and on any scroll container**: the closest scrollable ancestor is detected automatically, so it fits app shells with a fixed layout and a scrolling `<main>`
22
+ - Starts only when the container is scrolled to the top, never in the middle of a list
23
+ - Rubber band resistance beyond the trigger distance, and a progress ring that fills while pulling
24
+ - Ignores horizontal swipes and multi-touch gestures, and prevents the native bounce (and the browser's own pull to refresh) while pulling
25
+ - Haptic feedback when the trigger distance is reached (devices supporting `navigator.vibrate`)
26
+ - Texts from [@maz-ui/translations](../ecosystem/translations.md), overridable with the `translations` prop or the slots
27
+ - Accessible: the refresh is announced to screen readers, `aria-busy` is set while refreshing, and `refresh()` is exposed for a button usable with a keyboard or a mouse
28
+ - Optional `standalone-mode` to enable it only in an installed PWA (browsers already have their own pull to refresh)
29
+ - Built on the headless [usePullToRefresh](../composables/use-pull-to-refresh.md) composable
30
+
31
+ ## Demo
32
+
33
+ ## Basic usage
34
+
35
+ Wrap your app (or a page) inside the component and give it the function that reloads your data. The spinner stays visible until the returned promise settles.
36
+
37
+ ```vue
38
+ <script lang="ts" setup>
39
+ import MazPullToRefresh from 'maz-ui/components/MazPullToRefresh'
40
+
41
+ async function refresh() {
42
+ await fetchData()
43
+ }
44
+ </script>
45
+
46
+ <template>
47
+ <MazPullToRefresh :on-refresh="refresh">
48
+ <main>App content</main>
49
+ </MazPullToRefresh>
50
+ </template>
51
+ ```
52
+
53
+ With Nuxt, `refreshNuxtData` reloads every `useFetch` / `useAsyncData` of the page:
54
+
55
+ ```vue
56
+ <template>
57
+ <MazPullToRefresh :on-refresh="() => refreshNuxtData()" standalone-mode>
58
+ <NuxtPage />
59
+ </MazPullToRefresh>
60
+ </template>
61
+ ```
62
+
63
+ ## Inside a scroll container
64
+
65
+ The pull can only start when its scroll container is at the top. By default, the component uses its **closest scrollable ancestor** (`overflow-y: auto | scroll`), or the window if there is none. Typical app shells with a fixed layout and a scrolling `<main>` work without configuration:
66
+
67
+ ```vue
68
+ <template>
69
+ <div class="app-shell fixed inset-0 flex flex-col">
70
+ <header>…</header>
71
+ <main class="flex-1 overflow-y-auto">
72
+ <MazPullToRefresh :on-refresh="refresh">
73
+ <slot />
74
+ </MazPullToRefresh>
75
+ </main>
76
+ </div>
77
+ </template>
78
+ ```
79
+
80
+ Use `container-selector` when the scroll container is not an ancestor of the component:
81
+
82
+ ```vue
83
+ <template>
84
+ <MazPullToRefresh container-selector="#page-scroller" :on-refresh="refresh">
85
+ …
86
+ </MazPullToRefresh>
87
+ </template>
88
+ ```
89
+
90
+ ## Installed apps only
91
+
92
+ Browsers already provide their own pull to refresh. With `standalone-mode`, the component is only active when the app runs as an installed PWA (`display-mode: standalone`):
93
+
94
+ ```vue
95
+ <template>
96
+ <MazPullToRefresh standalone-mode :on-refresh="refresh">
97
+ …
98
+ </MazPullToRefresh>
99
+ </template>
100
+ ```
101
+
102
+ ## Tuning the gesture
103
+
104
+ | Prop | Default | Effect |
105
+ | -------------- | ---------------- | --------------------------------------------------------------------------------------- |
106
+ | `distance` | `80` | Pull distance (px, after resistance) needed to trigger a refresh |
107
+ | `max-distance` | `distance * 1.6` | Upper bound of the rubber band beyond `distance` |
108
+ | `resistance` | `0.5` | Ratio between the finger movement and the pull distance (lower is stiffer) |
109
+ | `min-duration` | `400` | Minimum duration (ms) of the refreshing state, so fast refreshes still show the feedback |
110
+ | `haptic` | `true` | Short vibration when `distance` is reached |
111
+
112
+ ## Customize the indicator
113
+
114
+ The three states have their own slot. Each one receives the pull `progress` (0 to 1) and the current `distance` in px.
115
+
116
+ ```vue
117
+ <template>
118
+ <MazPullToRefresh :on-refresh="refresh" header-class="bg-surface-600">
119
+ <template #pull-before="{ progress }">
120
+ <span>{{ Math.round(progress * 100) }}%</span>
121
+ </template>
122
+ <template #pull-ready>
123
+ <span>Let go!</span>
124
+ </template>
125
+ <template #pull-loading>
126
+ <MazSpinner color="secondary" />
127
+ </template>
128
+
129
+ <main>App content</main>
130
+ </MazPullToRefresh>
131
+ </template>
132
+ ```
133
+
134
+ `spinner-color` sets the color of the progress ring, the ready arrow and the default spinner (`primary` by default).
135
+
136
+ ## Translations
137
+
138
+ Texts come from [@maz-ui/translations](../ecosystem/translations.md) (`pullToRefresh.pull`, `pullToRefresh.release`, `pullToRefresh.refreshing`). Override them per instance with the `translations` prop:
139
+
140
+ ```vue
141
+ <template>
142
+ <MazPullToRefresh
143
+ :on-refresh="refresh"
144
+ :translations="{ pull: 'Swipe down', release: 'Release', refreshing: 'Updating…' }"
145
+ >
146
+ …
147
+ </MazPullToRefresh>
148
+ </template>
149
+ ```
150
+
151
+ ## Accessibility
152
+
153
+ The gesture is touch only. To give keyboard and mouse users the same action, call the exposed `refresh()` from a button: the indicator and the events behave exactly as with the gesture.
154
+
155
+ ```vue
156
+ <script lang="ts" setup>
157
+ import { useTemplateRef } from 'vue'
158
+
159
+ const pullToRefresh = useTemplateRef('pullToRefresh')
160
+ </script>
161
+
162
+ <template>
163
+ <MazBtn :loading="pullToRefresh?.isRefreshing" @click="pullToRefresh?.refresh()">
164
+ Refresh
165
+ </MazBtn>
166
+
167
+ <MazPullToRefresh ref="pullToRefresh" :on-refresh="refresh">
168
+ …
169
+ </MazPullToRefresh>
170
+ </template>
171
+ ```
172
+
173
+ While refreshing, the root element has `aria-busy="true"` and the refreshing text is announced through a polite live region. The visual indicator is hidden from assistive technologies.
174
+
175
+ ## Events
176
+
177
+ The events follow the life of a refresh: `start`, then `loaded` and `response` (with the value resolved by `on-refresh`) or `error`, and always `finish`. An error thrown by `on-refresh` is emitted, never thrown again.
178
+
179
+ ## Headless usage
180
+
181
+ Need a different indicator, or a gesture on an element without wrapping it? Use the [usePullToRefresh](../composables/use-pull-to-refresh.md) composable.
182
+
183
+ ## MazPullToRefresh API
184
+
185
+ `import MazPullToRefresh from 'maz-ui/components/MazPullToRefresh'`
186
+
187
+ ### Props
188
+
189
+ - `on-refresh` (`(() => unknown)`): Function called when the user releases after pulling far enough. The spinner stays visible until the returned promise settles. Without it, the component does nothing.
190
+ - `distance` (`number`, default: `80`): Pull distance (in px, after resistance) required to trigger a refresh.
191
+ - `max-distance` (`number`, default: `distance * 1.6`): Maximum pull distance (in px), reached with a rubber band effect beyond `distance`.
192
+ - `resistance` (`number`, default: `0.5`): Ratio between the finger movement and the pull distance, between 0 and 1. Lower is stiffer.
193
+ - `min-duration` (`number`, default: `400`): Minimum duration (in ms) of the refreshing state, so the feedback stays visible on fast refreshes.
194
+ - `container-selector` (`string`): CSS selector of the scroll container. By default, the closest scrollable ancestor of the component, or the window. The pull only starts when this container is scrolled to the top.
195
+ - `header-class` (`ClassValue`): Class of the header that holds the indicator.
196
+ - `spinner-color` (`"primary" | "secondary" | "accent" | "info" | "success" | "warning" | "destructive" | "contrast" | "transparent"`, default: `"primary"`): Color of the progress ring and the spinner.
197
+ - `disabled` (`boolean`, default: `false`): Disable the pull to refresh.
198
+ - `standalone-mode` (`boolean`, default: `false`): Only enable the pull to refresh when the app runs as an installed PWA (standalone display mode), browsers already provide their own pull to refresh.
199
+ - `haptic` (`boolean`, default: `true`): Vibrate briefly when the pull reaches `distance` (devices supporting `navigator.vibrate`).
200
+ - `translations` (`{ pull?: string | undefined; release?: string | undefined; refreshing?: string | undefined; }`, default: `Translations from`): Translations of the pull to refresh.
201
+ - `offset` (`number`)
202
+
203
+ ### Events
204
+
205
+ - `@loaded`: Emitted when `onRefresh` resolved
206
+ - `@error` (payload: `error: unknown`): Emitted when `onRefresh` threw or rejected
207
+ - `@start`: Emitted when the refresh starts
208
+ - `@response` (payload: `response: unknown`): Emitted with the value resolved by `onRefresh`
209
+ - `@finish`: Emitted when the refresh ends, after `loaded` or `error`
210
+
211
+ ### Slots
212
+
213
+ - `#pull-before`: Content shown while pulling, before the threshold Bindings: `progress: number`, `distance: number`.
214
+ - `#pull-ready`: Content shown once releasing triggers a refresh Bindings: `progress: number`, `distance: number`.
215
+ - `#pull-loading`: Content shown while refreshing Bindings: `progress: number`, `distance: number`.
216
+ - `#default`: Content of the page
217
+
218
+ ### Exposed (template ref)
219
+
220
+ - `refresh`: Run the refresh programmatically (a "refresh" button for keyboard and mouse users)
221
+ - `isRefreshing`: `onRefresh` is running
222
+ - `progress`: Pull progress towards `distance`, from 0 to 1
@@ -0,0 +1,313 @@
1
+ ---
2
+ title: "MazRadioButtons"
3
+ description: "MazRadioButtons is a standalone component to select a value in a list. Made with native HTMLInputElement type radio"
4
+ package: "maz-ui"
5
+ url: "https://maz-ui.com/components/maz-radio-buttons"
6
+ ---
7
+
8
+ # MazRadioButtons
9
+
10
+ > MazRadioButtons is a standalone component to select a value in a list. Made with native HTMLInputElement type radio
11
+
12
+ - Package: `maz-ui`
13
+ - Import: `import MazRadioButtons from 'maz-ui/components/MazRadioButtons'`
14
+ - Nuxt: auto-imported by `@maz-ui/nuxt`, no import needed in a Nuxt app
15
+ - Web: https://maz-ui.com/components/maz-radio-buttons
16
+
17
+ > Before use it, you should install the MazUi plugin in your project, follow instructions in [Getting Started](../guide/getting-started.md)
18
+
19
+ ## Basic usage
20
+
21
+ ```vue
22
+ <template>
23
+ <MazRadioButtons
24
+ v-model="selectedCompetition"
25
+ :options="competitions"
26
+ />
27
+ </template>
28
+
29
+ <script lang="ts" setup>
30
+ import { ref } from 'vue'
31
+
32
+ import MazRadioButtons from 'maz-ui/components/MazRadioButtons'
33
+
34
+ const selectedCompetition = ref<string>()
35
+
36
+ const competitions = [
37
+ {
38
+ value: "1",
39
+ label: "Ligue 1",
40
+ areaName: "France",
41
+ areaEnsignUrl: "https://upload.wikimedia.org/wikipedia/en/c/c3/Flag_of_France.svg",
42
+ },
43
+ {
44
+ value: "2",
45
+ label: "Premier League",
46
+ areaName: "England",
47
+ areaEnsignUrl: "https://crests.football-data.org/770.svg",
48
+ },
49
+ {
50
+ value: "3",
51
+ label: "Bundesliga",
52
+ areaName: "Germany",
53
+ areaEnsignUrl: "https://upload.wikimedia.org/wikipedia/commons/b/ba/Flag_of_Germany.svg",
54
+ },
55
+ {
56
+ value: "4",
57
+ label: "Eredivisie",
58
+ areaName: "Netherlands",
59
+ areaEnsignUrl: "https://upload.wikimedia.org/wikipedia/commons/2/20/Flag_of_the_Netherlands.svg",
60
+ },
61
+ {
62
+ value: "5",
63
+ label: "Serie A",
64
+ areaName: "Italy",
65
+ areaEnsignUrl: "https://upload.wikimedia.org/wikipedia/en/0/03/Flag_of_Italy.svg",
66
+ },
67
+ {
68
+ value: "6",
69
+ label: "Primera Division",
70
+ areaName: "Spain",
71
+ areaEnsignUrl: "https://upload.wikimedia.org/wikipedia/en/9/9a/Flag_of_Spain.svg",
72
+ },
73
+ {
74
+ value: "7",
75
+ label: "Primeira Liga",
76
+ areaName: "Portugal",
77
+ areaEnsignUrl: "https://upload.wikimedia.org/wikipedia/commons/5/5c/Flag_of_Portugal.svg",
78
+ },
79
+ {
80
+ value: "8",
81
+ label: "UEFA Champions League",
82
+ areaName: "Europe",
83
+ areaEnsignUrl: "https://crests.football-data.org/EUR.svg",
84
+ }
85
+ ]
86
+ </script>
87
+ ```
88
+
89
+ ## Custom slot template
90
+
91
+ ```html
92
+ <MazRadioButtons
93
+ v-model="selectedCompetition"
94
+ :options="competitions"
95
+ color="secondary"
96
+ >
97
+ <template #default="{ option, selected }">
98
+ <div style="display: flex;">
99
+ <MazAvatar
100
+ v-if="option.areaEnsignUrl"
101
+ :src="option.areaEnsignUrl"
102
+ style="margin-right: 16px;"
103
+ size="0.8rem"
104
+ />
105
+ <div style="display: flex; flex-direction: column;">
106
+ <span>
107
+ {{ option.label }}
108
+ </span>
109
+ <span :class="{ 'text-muted': !selected }">
110
+ {{ option.areaName }}
111
+ </span>
112
+ </div>
113
+ </div>
114
+ </template>
115
+ </MazRadioButtons>
116
+ ```
117
+
118
+ ## Orientation - Column
119
+
120
+ ```vue
121
+ <template>
122
+ <MazRadioButtons
123
+ v-model="selectedCompetition"
124
+ :options="competitions"
125
+ orientation="col | row"
126
+ v-slot="{ option, selected }"
127
+ >
128
+ <div style="display: flex;">
129
+ <MazAvatar
130
+ v-if="option.areaEnsignUrl"
131
+ :src="option.areaEnsignUrl"
132
+ style="margin-right: 16px;"
133
+ size="0.8rem"
134
+ />
135
+ <div style="display: flex; flex-direction: column;">
136
+ <span>
137
+ {{ option.label }}
138
+ </span>
139
+ <span :class="{ 'text-muted': !selected }">
140
+ {{ option.areaName }}
141
+ </span>
142
+ </div>
143
+ </div>
144
+ </MazRadioButtons>
145
+ </template>
146
+
147
+ <script lang="ts" setup>
148
+ import { ref } from 'vue'
149
+
150
+ import { MazRadioButtons, MazAvatar } from 'maz-ui/components'
151
+
152
+ const selectedCompetition = ref<string>()
153
+
154
+ const competitions = [
155
+ {
156
+ value: "1",
157
+ label: "Ligue 1",
158
+ areaName: "France",
159
+ areaEnsignUrl: "https://upload.wikimedia.org/wikipedia/en/c/c3/Flag_of_France.svg",
160
+ },
161
+ {
162
+ value: "2",
163
+ label: "Premier League",
164
+ areaName: "England",
165
+ areaEnsignUrl: "https://crests.football-data.org/770.svg",
166
+ },
167
+ {
168
+ value: "3",
169
+ label: "Bundesliga",
170
+ areaName: "Germany",
171
+ areaEnsignUrl: "https://upload.wikimedia.org/wikipedia/commons/b/ba/Flag_of_Germany.svg",
172
+ },
173
+ {
174
+ value: "4",
175
+ label: "Eredivisie",
176
+ areaName: "Netherlands",
177
+ areaEnsignUrl: "https://upload.wikimedia.org/wikipedia/commons/2/20/Flag_of_the_Netherlands.svg",
178
+ },
179
+ {
180
+ value: "5",
181
+ label: "Serie A",
182
+ areaName: "Italy",
183
+ areaEnsignUrl: "https://upload.wikimedia.org/wikipedia/en/0/03/Flag_of_Italy.svg",
184
+ },
185
+ {
186
+ value: "6",
187
+ label: "Primera Division",
188
+ areaName: "Spain",
189
+ areaEnsignUrl: "https://upload.wikimedia.org/wikipedia/en/9/9a/Flag_of_Spain.svg",
190
+ },
191
+ {
192
+ value: "7",
193
+ label: "Primeira Liga",
194
+ areaName: "Portugal",
195
+ areaEnsignUrl: "https://upload.wikimedia.org/wikipedia/commons/5/5c/Flag_of_Portugal.svg",
196
+ },
197
+ {
198
+ value: "8",
199
+ label: "UEFA Champions League",
200
+ areaName: "Europe",
201
+ areaEnsignUrl: "https://crests.football-data.org/EUR.svg",
202
+ }
203
+ ]
204
+ </script>
205
+ ```
206
+
207
+ ## Selector icon with options equal-size
208
+
209
+ This option will display a select icon on the left of the label
210
+
211
+ ```vue
212
+ <template>
213
+ <MazRadioButtons
214
+ v-slot="{ option, selected }"
215
+ v-model="selectedMode"
216
+ :options="modeOptions"
217
+ selector
218
+ equal-size
219
+ block
220
+ >
221
+ <div class="flex flex-col items-start p-2">
222
+ <h3 class="mb-2 text-xl font-semibold">
223
+ {{ option.label }}
224
+ </h3>
225
+ <span :class="{ 'text-muted': !selected }">
226
+ {{ option.description }}
227
+ </span>
228
+ </div>
229
+ </MazRadioButtons>
230
+ </template>
231
+
232
+ <script lang="ts" setup>
233
+ import { ref } from 'vue'
234
+ import { type MazRadioButtonsOption } from 'maz-ui/components/MazRadioButtons'
235
+
236
+ const selectedMode = ref('scores')
237
+
238
+ const modeOptions: MazRadioButtonsOption[] = [
239
+ {
240
+ label: 'Scores',
241
+ value: 'scores',
242
+ description:
243
+ 'Predict the score of matches. If you find the outcome of the match you win 5 points, if you get the perfect score you double your score!',
244
+ style: 'min-width: 250px;'
245
+ },
246
+ {
247
+ label: 'Cotes',
248
+ value: 'odds',
249
+ description:
250
+ 'Predict with match odds. If you find the correct winner of the match you earn the points associated with the rating, if you have the perfect score you double your score.',
251
+ style: 'min-width: 250px;'
252
+ },
253
+ ]
254
+ </script>
255
+ ```
256
+
257
+ ## Types
258
+
259
+ ### options
260
+
261
+ The options prop is an array of `ButtonsRadioOption` type
262
+
263
+ ```ts
264
+ export type ButtonsRadioOption = {
265
+ /** The label of the option */
266
+ label: string
267
+ /** The value of the option */
268
+ value: string | number | boolean
269
+ /** The classes to apply to the option */
270
+ classes?: any
271
+ /** The style to apply to the option */
272
+ style?: StyleValue
273
+ } & Record<string, unknown>
274
+ ```
275
+
276
+ ## Accessibility
277
+
278
+ The root element is a `radiogroup` of native radio inputs: pass an `aria-label` (or `aria-labelledby`) to name it. The `hint` describes the group (`aria-describedby`) and `error` sets `aria-invalid`. The arrows move between the options natively.
279
+
280
+ When no `name` is provided, each instance gets a unique one, so two groups of the same page never share their radios.
281
+
282
+ ## MazRadioButtons API
283
+
284
+ `import MazRadioButtons from 'maz-ui/components/MazRadioButtons'`
285
+
286
+ ### Props
287
+
288
+ - `model-value` (`T`, `v-model`): The value of the selected option.
289
+ - `options` (`Option[]`, required): The options to display.
290
+ - `name` (`string`, default: `a unique name per instance`): The name of the radio group.
291
+ - `color` (`"primary" | "secondary" | "accent" | "info" | "success" | "warning" | "destructive" | "contrast" | "transparent" | "surface"`, default: `"primary"`): The color of the selected radio buttons.
292
+ - `elevation` (`boolean`, default: `false`): Add elevation to the radio buttons.
293
+ - `orientation` (`"row" | "col"`, default: `"row"`): The orientation of the radio buttons.
294
+ - `wrap` (`boolean`, default: `true`): Disable the wrap of the radio buttons.
295
+ - `equal-size` (`boolean`, default: `false`): Make all radio buttons the same size.
296
+ - `selector` (`boolean`, default: `false`): Display a selector icon.
297
+ - `block` (`boolean`, default: `false`): The component will be displayed in full width.
298
+ - `error` (`boolean`): Whether there is an error with the input.
299
+ - `success` (`boolean`): Whether the input is successful.
300
+ - `warning` (`boolean`): Whether there is a warning with the input.
301
+ - `hint` (`string`): The hint text to display below the input.
302
+ - `size` (`"xs" | "sm" | "md" | "lg" | "xl" | "mini"`, default: `'md'`): The size of the radio buttons.
303
+
304
+ ### Events
305
+
306
+ - `@update:model-value` (payload: `value: Option["value"]`): Emitted when the selected option change
307
+ - `@blur` (payload: `value: FocusEvent`): Emitted when the a radio button lost focus
308
+ - `@change` (payload: `value: Option["value"]`): Emitted when the selected option change
309
+ - `@focus` (payload: `value: FocusEvent`): Emitted when the a radio button is focused
310
+
311
+ ### Slots
312
+
313
+ - `#default`: Label of the radio Bindings: `option: Option` (The value of the option), `selected: boolean` (If the option is selected).
@@ -0,0 +1,119 @@
1
+ ---
2
+ title: "MazRadio"
3
+ description: "MazRadio is a standalone component"
4
+ package: "maz-ui"
5
+ url: "https://maz-ui.com/components/maz-radio"
6
+ ---
7
+
8
+ # MazRadio
9
+
10
+ > MazRadio is a standalone component
11
+
12
+ - Package: `maz-ui`
13
+ - Import: `import MazRadio from 'maz-ui/components/MazRadio'`
14
+ - Nuxt: auto-imported by `@maz-ui/nuxt`, no import needed in a Nuxt app
15
+ - Web: https://maz-ui.com/components/maz-radio
16
+
17
+ > Before use it, you should install the MazUi plugin in your project, follow instructions in [Getting Started](../guide/getting-started.md)
18
+
19
+ ## Basic usage
20
+
21
+ `v-model=""`
22
+
23
+ **Details: View code**
24
+
25
+ ```vue
26
+ <script lang="ts" setup>
27
+ import MazRadio from 'maz-ui/components/MazRadio'
28
+ import { ref } from 'vue'
29
+
30
+ const chosenColor = ref('primary')
31
+ const chosenSize = ref('mini')
32
+
33
+ const colors: Color[] = [
34
+ 'primary',
35
+ 'secondary',
36
+ 'info',
37
+ 'success',
38
+ 'warning',
39
+ 'destructive',
40
+ 'accent',
41
+ 'contrast',
42
+ ]
43
+ </script>
44
+
45
+ <template>
46
+ <MazRadio
47
+ v-for="color in colors"
48
+ :key="color"
49
+ v-model="chosenColor"
50
+ name="chosenColor"
51
+ :color="color"
52
+ :value="color"
53
+ >
54
+ {{ color }}
55
+ </MazRadio>
56
+ </template>
57
+ ```
58
+
59
+ ## Sizing
60
+
61
+ `v-model=""`
62
+
63
+ **Details: View code**
64
+
65
+ ```vue
66
+ <script lang="ts" setup>
67
+ import MazRadio from 'maz-ui/components/MazRadio'
68
+ import type { Size } from 'maz-ui/components'
69
+ import { ref } from 'vue'
70
+
71
+ const chosenSize = ref('mini')
72
+
73
+ const sizes: Size[] = ['mini', 'xs', 'sm', 'md', 'lg', 'xl']
74
+ </script>
75
+
76
+ <template>
77
+ <MazRadio
78
+ v-for="size in sizes"
79
+ :key="size"
80
+ v-model="chosenSize"
81
+ name="chosenSize"
82
+ :size="size"
83
+ :value="size"
84
+ :label="size"
85
+ />
86
+ </template>
87
+ ```
88
+
89
+ ## Disabled
90
+
91
+ ## MazRadio API
92
+
93
+ `import MazRadio from 'maz-ui/components/MazRadio'`
94
+
95
+ ### Props
96
+
97
+ - `id` (`string`): The id of the radio.
98
+ - `model-value` (`T`, `v-model`): The value of the radio.
99
+ - `value` (`T`, required): The value of the radio.
100
+ - `name` (`string`, required): The name of the radio.
101
+ - `label` (`string`): The label of the radio.
102
+ - `color` (`"primary" | "secondary" | "accent" | "info" | "success" | "warning" | "destructive" | "contrast" | "transparent"`, default: `"primary"`): The color of the radio.
103
+ - `size` (`"xs" | "sm" | "md" | "lg" | "xl" | "mini"`): The size of the radio.
104
+ - `disabled` (`boolean`, default: `false`): The disabled state of the radio.
105
+ - `error` (`boolean`): Whether there is an error with the input.
106
+ - `success` (`boolean`): Whether the input is successful.
107
+ - `warning` (`boolean`): Whether there is a warning with the input.
108
+ - `hint` (`string`): The hint text to display below the input.
109
+
110
+ ### Events
111
+
112
+ - `@update:model-value` (payload: `value: T`): Event emitted when value change
113
+ - `@blur` (payload: `value: FocusEvent`): Emitted when the radio lost focus
114
+ - `@change` (payload: `value: T`): Event emitted when value change
115
+ - `@focus` (payload: `value: FocusEvent`): Emitted when the radio is focused
116
+
117
+ ### Slots
118
+
119
+ - `#default` Bindings: `isSelected: boolean`, `value: T`.