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.
- package/dist/assets/{MazDropzone.DJ8au25t.css → MazDropzone.BW2grpTi.css} +1 -1
- package/dist/chunks/{MazDrawer.DANxKYxJ.js → MazDrawer.CC8zomfx.js} +2 -2
- package/dist/chunks/{MazDropzone.POH3pmfi.js → MazDropzone.Dez5j0WP.js} +2 -2
- package/dist/components/MazDrawer.js +1 -1
- package/dist/components/MazDropzone.js +1 -1
- package/dist/components/MazDropzone.vue.d.ts +2 -2
- package/dist/components/MazInputPrice.vue.d.ts +1 -1
- package/dist/components/index.js +2 -2
- package/docs/README.md +207 -0
- package/docs/agents/agents-md.md +52 -0
- package/docs/agents/claude-rule.md +52 -0
- package/docs/components/maz-accordion.md +76 -0
- package/docs/components/maz-alert.md +241 -0
- package/docs/components/maz-animated-counter.md +87 -0
- package/docs/components/maz-animated-element.md +46 -0
- package/docs/components/maz-animated-text.md +53 -0
- package/docs/components/maz-avatar.md +193 -0
- package/docs/components/maz-backdrop.md +178 -0
- package/docs/components/maz-badge.md +167 -0
- package/docs/components/maz-bottom-sheet.md +257 -0
- package/docs/components/maz-btn-group.md +316 -0
- package/docs/components/maz-btn.md +423 -0
- package/docs/components/maz-card-spotlight.md +84 -0
- package/docs/components/maz-card.md +321 -0
- package/docs/components/maz-carousel.md +153 -0
- package/docs/components/maz-chart.md +206 -0
- package/docs/components/maz-checkbox.md +138 -0
- package/docs/components/maz-checklist.md +251 -0
- package/docs/components/maz-circular-progress-bar.md +109 -0
- package/docs/components/maz-code-highlight.md +155 -0
- package/docs/components/maz-container.md +241 -0
- package/docs/components/maz-date-picker.md +791 -0
- package/docs/components/maz-dialog-confirm.md +215 -0
- package/docs/components/maz-dialog.md +143 -0
- package/docs/components/maz-drawer.md +106 -0
- package/docs/components/maz-dropdown.md +419 -0
- package/docs/components/maz-dropzone.md +387 -0
- package/docs/components/maz-expand-animation.md +82 -0
- package/docs/components/maz-fullscreen-loader.md +58 -0
- package/docs/components/maz-gallery.md +79 -0
- package/docs/components/maz-icon.md +203 -0
- package/docs/components/maz-input-code.md +73 -0
- package/docs/components/maz-input-number.md +79 -0
- package/docs/components/maz-input-phone-number.md +536 -0
- package/docs/components/maz-input-price.md +68 -0
- package/docs/components/maz-input-tags.md +112 -0
- package/docs/components/maz-input.md +334 -0
- package/docs/components/maz-lazy-img.md +113 -0
- package/docs/components/maz-link.md +146 -0
- package/docs/components/maz-loading-bar.md +38 -0
- package/docs/components/maz-markdown-editor.md +320 -0
- package/docs/components/maz-pagination.md +82 -0
- package/docs/components/maz-popover.md +794 -0
- package/docs/components/maz-pull-to-refresh.md +222 -0
- package/docs/components/maz-radio-buttons.md +313 -0
- package/docs/components/maz-radio.md +119 -0
- package/docs/components/maz-read-more.md +209 -0
- package/docs/components/maz-reading-progress-bar.md +96 -0
- package/docs/components/maz-select-country.md +513 -0
- package/docs/components/maz-select.md +318 -0
- package/docs/components/maz-sidebar-content.md +25 -0
- package/docs/components/maz-sidebar-footer.md +25 -0
- package/docs/components/maz-sidebar-group.md +27 -0
- package/docs/components/maz-sidebar-header.md +25 -0
- package/docs/components/maz-sidebar-menu-button.md +41 -0
- package/docs/components/maz-sidebar-menu-item.md +25 -0
- package/docs/components/maz-sidebar-menu-sub.md +32 -0
- package/docs/components/maz-sidebar-menu.md +25 -0
- package/docs/components/maz-sidebar-separator.md +21 -0
- package/docs/components/maz-sidebar-trigger.md +25 -0
- package/docs/components/maz-sidebar.md +507 -0
- package/docs/components/maz-skeleton.md +226 -0
- package/docs/components/maz-slider.md +165 -0
- package/docs/components/maz-spinner.md +84 -0
- package/docs/components/maz-stepper.md +301 -0
- package/docs/components/maz-switch.md +86 -0
- package/docs/components/maz-table-cell.md +27 -0
- package/docs/components/maz-table-row.md +28 -0
- package/docs/components/maz-table-title.md +27 -0
- package/docs/components/maz-table-virtualizer.md +31 -0
- package/docs/components/maz-table.md +426 -0
- package/docs/components/maz-tabs-bar.md +43 -0
- package/docs/components/maz-tabs-content-item.md +27 -0
- package/docs/components/maz-tabs-content.md +27 -0
- package/docs/components/maz-tabs.md +308 -0
- package/docs/components/maz-textarea.md +255 -0
- package/docs/components/maz-ticker.md +427 -0
- package/docs/components/maz-timeline.md +304 -0
- package/docs/components/maz-ui-provider.md +26 -0
- package/docs/components/maz-window-mockup.md +182 -0
- package/docs/composables/use-aos.md +41 -0
- package/docs/composables/use-breakpoints.md +42 -0
- package/docs/composables/use-dialog.md +58 -0
- package/docs/composables/use-display-names.md +130 -0
- package/docs/composables/use-drag.md +185 -0
- package/docs/composables/use-form-validator.md +1123 -0
- package/docs/composables/use-idle-timeout.md +172 -0
- package/docs/composables/use-pull-to-refresh.md +86 -0
- package/docs/composables/use-reading-time.md +132 -0
- package/docs/composables/use-string-matching.md +41 -0
- package/docs/composables/use-swipe.md +171 -0
- package/docs/composables/use-timer.md +104 -0
- package/docs/composables/use-toast.md +50 -0
- package/docs/composables/use-user-visibility.md +127 -0
- package/docs/composables/use-wait.md +50 -0
- package/docs/composables/use-window-size.md +25 -0
- package/docs/directives/click-outside.md +182 -0
- package/docs/directives/fullscreen-img.md +83 -0
- package/docs/directives/lazy-img.md +182 -0
- package/docs/directives/tooltip.md +298 -0
- package/docs/directives/zoom-img.md +100 -0
- package/docs/ecosystem/eslint-config.md +289 -0
- package/docs/ecosystem/icons/icon-set.md +25 -0
- package/docs/ecosystem/icons/index.md +584 -0
- package/docs/ecosystem/mcp.md +165 -0
- package/docs/ecosystem/node/exec-promise.md +93 -0
- package/docs/ecosystem/node/index.md +53 -0
- package/docs/ecosystem/node/logger.md +152 -0
- package/docs/ecosystem/node/print-banner.md +101 -0
- package/docs/ecosystem/node/setup-agents.md +102 -0
- package/docs/ecosystem/nuxt.md +551 -0
- package/docs/ecosystem/stylelint-config.md +310 -0
- package/docs/ecosystem/themes.md +966 -0
- package/docs/ecosystem/translations.md +1173 -0
- package/docs/ecosystem/utils/camel-case.md +37 -0
- package/docs/ecosystem/utils/capitalize.md +37 -0
- package/docs/ecosystem/utils/check-availability.md +85 -0
- package/docs/ecosystem/utils/cookie.md +86 -0
- package/docs/ecosystem/utils/country-code-to-unicode-flag.md +128 -0
- package/docs/ecosystem/utils/currency.md +53 -0
- package/docs/ecosystem/utils/date.md +53 -0
- package/docs/ecosystem/utils/debounce-callback.md +44 -0
- package/docs/ecosystem/utils/debounce-id.md +75 -0
- package/docs/ecosystem/utils/debounce.md +71 -0
- package/docs/ecosystem/utils/fetch-locale-ip.md +39 -0
- package/docs/ecosystem/utils/format-json.md +39 -0
- package/docs/ecosystem/utils/format-phone-number.md +43 -0
- package/docs/ecosystem/utils/get-browser-locale.md +35 -0
- package/docs/ecosystem/utils/get-country-flag-url.md +67 -0
- package/docs/ecosystem/utils/get-error-message.md +45 -0
- package/docs/ecosystem/utils/idle-timeout.md +96 -0
- package/docs/ecosystem/utils/index.md +57 -0
- package/docs/ecosystem/utils/is-client.md +38 -0
- package/docs/ecosystem/utils/is-equal.md +44 -0
- package/docs/ecosystem/utils/is-ios.md +43 -0
- package/docs/ecosystem/utils/is-server.md +37 -0
- package/docs/ecosystem/utils/is-standalone-mode.md +49 -0
- package/docs/ecosystem/utils/kebab-case.md +42 -0
- package/docs/ecosystem/utils/normalize-string.md +83 -0
- package/docs/ecosystem/utils/number.md +51 -0
- package/docs/ecosystem/utils/pascal-case.md +41 -0
- package/docs/ecosystem/utils/prevent-ios-input-zoom.md +72 -0
- package/docs/ecosystem/utils/script-loader.md +85 -0
- package/docs/ecosystem/utils/sleep.md +65 -0
- package/docs/ecosystem/utils/snake-case.md +42 -0
- package/docs/ecosystem/utils/swipe-handler.md +97 -0
- package/docs/ecosystem/utils/textarea-autogrow.md +47 -0
- package/docs/ecosystem/utils/throttle-id.md +54 -0
- package/docs/ecosystem/utils/throttle.md +63 -0
- package/docs/ecosystem/utils/truthy-filter.md +37 -0
- package/docs/ecosystem/utils/types/deep-key-of.md +54 -0
- package/docs/ecosystem/utils/types/deep-partial.md +48 -0
- package/docs/ecosystem/utils/types/deep-required.md +45 -0
- package/docs/ecosystem/utils/types/flatten-object-keys.md +50 -0
- package/docs/ecosystem/utils/types/generic-instance-type.md +48 -0
- package/docs/ecosystem/utils/types/infer-maybe-ref.md +41 -0
- package/docs/ecosystem/utils/upper-first.md +38 -0
- package/docs/ecosystem/utils/user-visibility.md +75 -0
- package/docs/guide/ai-agents.md +237 -0
- package/docs/guide/browser-support.md +88 -0
- package/docs/guide/getting-started.md +191 -0
- package/docs/guide/global-defaults.md +103 -0
- package/docs/guide/maz-ui-provider.md +231 -0
- package/docs/guide/migration-v5.md +871 -0
- package/docs/guide/resolvers.md +650 -0
- package/docs/guide/tailwind.md +483 -0
- package/docs/guide/vue.md +286 -0
- package/docs/manifest.json +1 -0
- package/docs/plugins/aos.md +312 -0
- package/docs/plugins/dialog.md +269 -0
- package/docs/plugins/toast.md +221 -0
- package/docs/plugins/wait.md +78 -0
- package/docs/reference/icons.md +46 -0
- package/docs/reference/tailwind-tokens.md +191 -0
- package/docs/rules.md +57 -0
- 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`.
|