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,172 @@
1
+ ---
2
+ title: "useIdleTimeout"
3
+ description: "A Vue composable that provides an easy way to track user inactivity on your website and execute a callback function when the user becomes idle."
4
+ package: "maz-ui"
5
+ url: "https://maz-ui.com/composables/use-idle-timeout"
6
+ ---
7
+
8
+ # useIdleTimeout
9
+
10
+ > A Vue composable that provides an easy way to track user inactivity on your website and execute a callback function when the user becomes idle.
11
+
12
+ - Package: `maz-ui`
13
+ - Import: `import { useIdleTimeout } from 'maz-ui/composables/useIdleTimeout'`
14
+ - Nuxt: auto-imported by `@maz-ui/nuxt`, no import needed in a Nuxt app
15
+ - Web: https://maz-ui.com/composables/use-idle-timeout
16
+
17
+ **Note:**
18
+
19
+ A plugin to know the amount of time a user has spent on your website
20
+
21
+ ## Demo
22
+
23
+ ```vue
24
+ <script lang="ts" setup>
25
+ import { MazBtn, MazCard } from 'maz-ui/components'
26
+
27
+ import { useDialog, useIdleTimeout } from 'maz-ui/composables'
28
+
29
+ import { onBeforeUnmount, onMounted, ref } from 'vue'
30
+
31
+ const dialog = useDialog()
32
+
33
+ const event = ref({})
34
+
35
+ const timeout = 5000
36
+
37
+ const idleTimeout = useIdleTimeout({
38
+ callback,
39
+ options: {
40
+ timeout,
41
+ immediate: false,
42
+ once: false,
43
+ },
44
+ })
45
+
46
+ async function callback({ isIdle, eventType, instance }) {
47
+ console.log({ isIdle, eventType })
48
+ event.value = { isIdle, eventType }
49
+
50
+ if (isIdle) {
51
+ try {
52
+ instance.destroy()
53
+ await dialog.open({
54
+ title: 'Are you still here?',
55
+ message: `You have been inactive for ${timeout / 1000} secondes, do you want to continue?`,
56
+ cancelText: 'No',
57
+ confirmText: 'Yes',
58
+ }).promise
59
+ instance.start()
60
+ }
61
+ catch (e) {
62
+ // do something like logout the user
63
+ }
64
+ }
65
+ }
66
+
67
+ onMounted(() => {
68
+ // should be executed on client side
69
+ idleTimeout.start()
70
+ })
71
+
72
+ onBeforeUnmount(() => {
73
+ // Destroy the instance when the component is destroyed to avoid memory leaks
74
+ idleTimeout.destroy()
75
+ })
76
+ </script>
77
+
78
+ <template>
79
+ <MazBtn color="info" @click="idle.start()">
80
+ Start
81
+ </MazBtn>
82
+ <MazBtn color="warning" @click="idle.pause()">
83
+ Pause
84
+ </MazBtn>
85
+ <MazBtn @click="idle.resume()">
86
+ Resume
87
+ </MazBtn>
88
+ <MazBtn color="secondary" @click="idle.reset()">
89
+ Reset
90
+ </MazBtn>
91
+ <MazBtn color="destructive" @click="idle.destroy()">
92
+ Destroy
93
+ </MazBtn>
94
+
95
+ <MazCard block>
96
+ <div style="display: flex;">
97
+ <div style="flex: 1;">
98
+ isIdle: {{ event.isIdle }}
99
+ </div>
100
+ <div v-if="event.eventType" style="flex: 1; padding-left: 10px;">
101
+ eventType: {{ event.eventType }}
102
+ </div>
103
+ </div>
104
+ </MazCard>
105
+ </template>
106
+ ```
107
+
108
+ ## Callback
109
+
110
+ ```ts
111
+ type IdleTimeoutCallback = (payload: {
112
+ isIdle: boolean
113
+ eventType?: string
114
+ }) => void
115
+ ```
116
+
117
+ ## Options
118
+
119
+ ```ts
120
+ interface IdleTimeoutStrictOption {
121
+ /** @default document.body */
122
+ element?: HTMLElement | Document
123
+ /** @default 60 * 1000 * 5 --> 5 minutes */
124
+ timeout?: number
125
+ /** @default false */
126
+ once?: boolean
127
+ /** @default true */
128
+ immediate?: boolean
129
+ }
130
+ ```
131
+
132
+ ## Actions
133
+
134
+ ### Start
135
+
136
+ Start tracking user - needed for SSR when `immediate` option is set to false (execute it on client side)
137
+
138
+ ```ts
139
+ idleTimeout.start()
140
+ ```
141
+
142
+ ### Pause
143
+
144
+ Will pause the timeout and events, can't be executed when the timeout has expired
145
+
146
+ ```ts
147
+ idleTimeout.pause()
148
+ ```
149
+
150
+ ### Resume
151
+
152
+ Resume the instance will reinit the timeout
153
+
154
+ ```ts
155
+ idleTimeout.resume()
156
+ ```
157
+
158
+ ### Reset
159
+
160
+ Reset the timeout of the instance like a restart
161
+
162
+ ```ts
163
+ idleTimeout.reset()
164
+ ```
165
+
166
+ ### Destroy
167
+
168
+ Will destroy the instance and stop tracking
169
+
170
+ ```ts
171
+ idleTimeout.destroy()
172
+ ```
@@ -0,0 +1,86 @@
1
+ ---
2
+ title: "usePullToRefresh"
3
+ description: "usePullToRefresh is a headless Vue composable for the pull to refresh gesture on the window or any scroll container."
4
+ package: "maz-ui"
5
+ url: "https://maz-ui.com/composables/use-pull-to-refresh"
6
+ ---
7
+
8
+ # usePullToRefresh
9
+
10
+ > usePullToRefresh is a headless Vue composable for the pull to refresh gesture on the window or any scroll container.
11
+
12
+ - Package: `maz-ui`
13
+ - Import: `import { usePullToRefresh } from 'maz-ui/composables/usePullToRefresh'`
14
+ - Nuxt: auto-imported by `@maz-ui/nuxt`, no import needed in a Nuxt app
15
+ - Web: https://maz-ui.com/composables/use-pull-to-refresh
16
+
17
+ ## Introduction
18
+
19
+ `usePullToRefresh` tracks the pull to refresh gesture and gives you its state (distance, progress, ready, refreshing) to build your own indicator. It powers [MazPullToRefresh](../components/maz-pull-to-refresh.md): use the component for a ready-made indicator, the composable when you need full control over the rendering.
20
+
21
+ The pull only starts when the target is scrolled to the top, follows a rubber band beyond the threshold, ignores horizontal and multi-touch gestures, and prevents the native bounce while pulling.
22
+
23
+ ## Basic usage
24
+
25
+ ```vue
26
+ <script lang="ts" setup>
27
+ import { usePullToRefresh } from 'maz-ui/composables'
28
+ import { useTemplateRef } from 'vue'
29
+
30
+ const scroller = useTemplateRef<HTMLElement>('scroller')
31
+
32
+ const { distance, progress, isReady, isRefreshing } = usePullToRefresh({
33
+ target: scroller,
34
+ onRefresh: () => fetchData(),
35
+ })
36
+ </script>
37
+
38
+ <template>
39
+ <div ref="scroller" class="h-screen overflow-y-auto">
40
+ <div class="flex items-end justify-center overflow-hidden" :style="{ height: `${distance}px` }">
41
+ <span v-if="isRefreshing">Refreshing…</span>
42
+ <span v-else-if="isReady">Release to refresh</span>
43
+ <span v-else :style="{ opacity: progress }">Pull to refresh</span>
44
+ </div>
45
+
46
+ <p>Content</p>
47
+ </div>
48
+ </template>
49
+ ```
50
+
51
+ Without `target`, the gesture is tracked on the window.
52
+
53
+ ## Options
54
+
55
+ | Option | Type | Default | Description |
56
+ | ------------- | -------------------------------------------- | ----------------- | ------------------------------------------------------------------------------------ |
57
+ | `onRefresh` | `() => unknown` | - | Called on release past the threshold, or by `refresh()` |
58
+ | `target` | `MaybeRefOrGetter<HTMLElement \| Window \| null>` | `window` | Scroll container receiving the gesture |
59
+ | `threshold` | `MaybeRefOrGetter<number>` | `80` | Pull distance (px, after resistance) needed to trigger a refresh |
60
+ | `maxDistance` | `MaybeRefOrGetter<number>` | `threshold * 1.6` | Upper bound of the rubber band |
61
+ | `resistance` | `MaybeRefOrGetter<number>` | `0.5` | Ratio between the finger movement and the pull distance |
62
+ | `minDuration` | `MaybeRefOrGetter<number>` | `400` | Minimum duration (ms) of the refreshing state |
63
+ | `haptic` | `MaybeRefOrGetter<boolean>` | `true` | Vibrate briefly when the threshold is reached |
64
+ | `disabled` | `MaybeRefOrGetter<boolean>` | `false` | Disable the gesture |
65
+ | `onError` | `(error: unknown) => void` | - | Called when `onRefresh` throws or rejects (the error is also exposed in `error`) |
66
+
67
+ ## Return
68
+
69
+ | Property | Type | Description |
70
+ | -------------- | --------------------------- | ------------------------------------------------------------ |
71
+ | `distance` | `Readonly<Ref<number>>` | Current pull distance in px |
72
+ | `progress` | `ComputedRef<number>` | Progress towards the threshold, from 0 to 1 |
73
+ | `isPulling` | `Readonly<Ref<boolean>>` | The user is pulling |
74
+ | `isReady` | `ComputedRef<boolean>` | Releasing now triggers a refresh |
75
+ | `isRefreshing` | `Readonly<Ref<boolean>>` | `onRefresh` is running |
76
+ | `error` | `Readonly<Ref<unknown>>` | Error of the last refresh, reset on each refresh |
77
+ | `refresh` | `() => Promise<void>` | Run the refresh programmatically (for a keyboard-usable button) |
78
+ | `start` | `() => void` | Attach the listeners (done automatically on mount) |
79
+ | `stop` | `() => void` | Detach the listeners (done automatically on unmount) |
80
+
81
+ ## Notes
82
+
83
+ - Inside a component, listeners are attached on mount and removed when the scope is disposed. Outside of a component, they are attached right away.
84
+ - When `target` changes (for example a ref resolved later), the listeners move to the new element.
85
+ - `refresh()` never throws: errors go to `error` and `onError`. Calling it while a refresh is running does nothing.
86
+ - SSR safe: nothing touches the DOM before mount.
@@ -0,0 +1,132 @@
1
+ ---
2
+ title: "useReadingTime"
3
+ description: "This composable allows you to calculate the reading time of a text"
4
+ package: "maz-ui"
5
+ url: "https://maz-ui.com/composables/use-reading-time"
6
+ ---
7
+
8
+ # useReadingTime
9
+
10
+ > This composable allows you to calculate the reading time of a text
11
+
12
+ - Package: `maz-ui`
13
+ - Import: `import { useReadingTime } from 'maz-ui/composables/useReadingTime'`
14
+ - Nuxt: auto-imported by `@maz-ui/nuxt`, no import needed in a Nuxt app
15
+ - Web: https://maz-ui.com/composables/use-reading-time
16
+
17
+ ## Basic usage
18
+
19
+ Time to read this page: minutes
20
+
21
+ ```vue
22
+ <script lang="ts" setup>
23
+ import { useReadingTime } from 'maz-ui/composables'
24
+
25
+ const { duration } = useReadingTime({
26
+ content: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Lectus quam id leo in. Placerat vestibulum lectus mauris ultrices eros in cursus turpis. Et tortor consequat id porta nibh venenatis cras sed. Praesent tristique magna sit amet. Iaculis at erat pellentesque adipiscing commodo elit at. Interdum velit euismod in pellentesque massa placerat duis. Eget nunc scelerisque viverra mauris in aliquam. Nulla facilisi morbi tempus iaculis urna id volutpat lacus. Pellentesque eu tincidunt tortor aliquam nulla facilisi cras fermentum odio. Egestas integer eget aliquet nibh praesent tristique magna sit amet. Volutpat blandit aliquam etiam erat velit scelerisque. Eget nullam non nisi est sit amet. Turpis egestas sed tempus urna et pharetra. Nisl rhoncus mattis rhoncus urna neque viverra justo. Rutrum tellus pellentesque eu tincidunt tortor aliquam. Non odio euismod lacinia at. Magna eget est lorem ipsum. Et ultrices neque ornare aenean euismod elementum nisi. Ullamcorper eget nulla facilisi etiam dignissim diam quis enim lobortis. Lobortis feugiat vivamus at augue eget arcu. Ut diam quam nulla porttitor massa id neque. Turpis in eu mi bibendum neque egestas. Vivamus at augue eget arcu dictum varius duis at. Nunc sed blandit libero volutpat. Convallis a cras semper auctor neque vitae tempus. Odio facilisis mauris sit amet massa vitae tortor condimentum. Condimentum id venenatis a condimentum. Tincidunt praesent semper feugiat nibh sed pulvinar. Dolor magna eget est lorem ipsum dolor. Ultricies mi eget mauris pharetra et ultrices neque ornare aenean. Sapien pellentesque habitant morbi tristique senectus et netus. Tortor vitae purus faucibus ornare suspendisse sed nisi. Est lorem ipsum dolor sit amet consectetur adipiscing elit pellentesque. Enim neque volutpat ac tincidunt vitae. Iaculis at erat pellentesque adipiscing commodo elit at imperdiet. Scelerisque felis imperdiet proin fermentum leo vel orci porta non. Ut etiam sit amet nisl purus in mollis nunc sed. Sed velit dignissim sodales ut eu sem integer. Odio tempor orci dapibus ultrices in iaculis nunc. Id semper risus in hendrerit gravida. Aliquam faucibus purus in massa tempor nec. Mattis nunc sed blandit libero volutpat sed cras ornare arcu. Quisque id diam vel quam elementum pulvinar etiam non quam. Et egestas quis ipsum suspendisse ultrices gravida dictum. Velit aliquet sagittis id consectetur purus ut faucibus pulvinar elementum. In hac habitasse platea dictumst quisque. Amet nisl purus in mollis nunc sed id semper. Sollicitudin tempor id eu nisl nunc mi. Dictumst vestibulum rhoncus est pellentesque elit ullamcorper dignissim. In iaculis nunc sed augue lacus viverra vitae.'
27
+ })
28
+ </script>
29
+
30
+ <template>
31
+ <div>
32
+ Time to read this page: <strong>{{ duration }} minutes</strong>
33
+ </div>
34
+ </template>
35
+ ```
36
+
37
+ ## With content selector
38
+
39
+ **Warning:**
40
+
41
+ This method is not SSR friendly (only on client side, with Nuxt use this composable in `onMounted(() => { ... })`) and not recommended because it is less performant than the previous one
42
+
43
+ Time to read this page: minutes
44
+
45
+ ```vue
46
+ <script lang="ts" setup>
47
+ import { useReadingTime } from 'maz-ui/composables'
48
+
49
+ const readingTime = ref<number>()
50
+
51
+ const { duration } = useReadingTime({
52
+ contentSelector: '#content-to-read'
53
+ })
54
+
55
+ readingTime.value = duration
56
+
57
+ onMounted(() => {
58
+ const { duration } = useReadingTime({
59
+ contentSelector: '#content-to-read'
60
+ })
61
+
62
+ readingTime.value = duration
63
+ })
64
+ </script>
65
+
66
+ <template>
67
+ <div>
68
+ Time to read this page: <strong>{{ duration }} minutes</strong>
69
+ </div>
70
+
71
+ <MazCard collapsible class="w-full" title="Content to read">
72
+ <div id="content-to-read" class="px-4">
73
+ <p>
74
+ Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Lectus quam id leo in. Placerat vestibulum lectus mauris ultrices eros in cursus turpis. Et tortor consequat id porta nibh venenatis cras sed. Praesent tristique magna sit amet. Iaculis at erat pellentesque adipiscing commodo elit at. Interdum velit euismod in pellentesque massa placerat duis. Eget nunc scelerisque viverra mauris in aliquam. Nulla facilisi morbi tempus iaculis urna id volutpat lacus. Pellentesque eu tincidunt tortor aliquam nulla facilisi cras fermentum odio. Egestas integer eget aliquet nibh praesent tristique magna sit amet. Volutpat blandit aliquam etiam erat velit scelerisque. Eget nullam non nisi est sit amet. Turpis egestas sed tempus urna et pharetra. Nisl rhoncus mattis rhoncus urna neque viverra justo. Rutrum tellus pellentesque eu tincidunt tortor aliquam. Non odio euismod lacinia at. Magna eget est lorem ipsum.
75
+ </p>
76
+ <p>
77
+ Et ultrices neque ornare aenean euismod elementum nisi. Ullamcorper eget nulla facilisi etiam dignissim diam quis enim lobortis. Lobortis feugiat vivamus at augue eget arcu. Ut diam quam nulla porttitor massa id neque. Turpis in eu mi bibendum neque egestas. Vivamus at augue eget arcu dictum varius duis at. Nunc sed blandit libero volutpat. Convallis a cras semper auctor neque vitae tempus. Odio facilisis mauris sit amet massa vitae tortor condimentum. Condimentum id venenatis a condimentum. Tincidunt praesent semper feugiat nibh sed pulvinar. Dolor magna eget est lorem ipsum dolor. Ultricies mi eget mauris pharetra et ultrices neque ornare aenean. Sapien pellentesque habitant morbi tristique senectus et netus. Tortor vitae purus faucibus ornare suspendisse sed nisi. Est lorem ipsum dolor sit amet consectetur adipiscing elit pellentesque. Enim neque volutpat ac tincidunt vitae.
78
+ </p>
79
+ <p>
80
+ Iaculis at erat pellentesque adipiscing commodo elit at imperdiet. Scelerisque felis imperdiet proin fermentum leo vel orci porta non. Ut etiam sit amet nisl purus in mollis nunc sed. Sed velit dignissim sodales ut eu sem integer. Odio tempor orci dapibus ultrices in iaculis nunc. Id semper risus in hendrerit gravida. Aliquam faucibus purus in massa tempor nec. Mattis nunc sed blandit libero volutpat sed cras ornare arcu. Quisque id diam vel quam elementum pulvinar etiam non quam. Et egestas quis ipsum suspendisse ultrices gravida dictum. Velit aliquet sagittis id consectetur purus ut faucibus pulvinar elementum. In hac habitasse platea dictumst quisque. Amet nisl purus in mollis nunc sed id semper. Sollicitudin tempor id eu nisl nunc mi. Dictumst vestibulum rhoncus est pellentesque elit ullamcorper dignissim. In iaculis nunc sed augue lacus viverra vitae.
81
+ </p>
82
+ </div>
83
+ </MazCard>
84
+ </template>
85
+ ```
86
+
87
+ ## Velocity
88
+
89
+ > The velocity is the number of words per minute. By default it is 150 words per minute.
90
+
91
+ **Velocity**: words per minute
92
+
93
+ Time to read this page: minutes
94
+
95
+ ## Types
96
+
97
+ ### Options
98
+
99
+ ```ts
100
+ export interface ReadingTimeOptions {
101
+ /**
102
+ * Content to calculate the reading time
103
+ * @default undefined
104
+ */
105
+ content?: string | Ref<string>
106
+ /**
107
+ * Selector of the content to calculate the reading time
108
+ * @default undefined
109
+ */
110
+ contentSelector?: string | Ref<string>
111
+ /**
112
+ * Words per minute
113
+ * @default 150
114
+ */
115
+ velocity?: number
116
+ }
117
+ ```
118
+
119
+ ### Returns
120
+
121
+ ```ts
122
+ export interface ReadingTimeReturn {
123
+ /** Content to calculate the reading time */
124
+ content: ComputedRef<string | undefined | null>
125
+ /** Number of words in the content */
126
+ wordCount: ComputedRef<number>
127
+ /** Words per minute */
128
+ velocity: ComputedRef<number>
129
+ /** Reading time in minutes */
130
+ duration: ComputedRef<number>
131
+ }
132
+ ```
@@ -0,0 +1,41 @@
1
+ ---
2
+ title: "useStringMatching"
3
+ description: "Efficient composable for string matching tasks, utilizing Levenshtein distance calculation. Simplify comparison operations with minimal setup. Enhance text similarity checks effortlessly."
4
+ package: "maz-ui"
5
+ url: "https://maz-ui.com/composables/use-string-matching"
6
+ ---
7
+
8
+ # useStringMatching
9
+
10
+ > Efficient composable for string matching tasks, utilizing Levenshtein distance calculation. Simplify comparison operations with minimal setup. Enhance text similarity checks effortlessly.
11
+
12
+ - Package: `maz-ui`
13
+ - Import: `import { useStringMatching } from 'maz-ui/composables/useStringMatching'`
14
+ - Nuxt: auto-imported by `@maz-ui/nuxt`, no import needed in a Nuxt app
15
+ - Web: https://maz-ui.com/composables/use-string-matching
16
+
17
+ ## Usage
18
+
19
+ ```vue
20
+ <script lang="ts" setup>
21
+ import { useStringMatching } from 'maz-ui/composables'
22
+ import { ref } from 'vue'
23
+
24
+ const string1 = ref<string>('maz-ui')
25
+ const string2 = ref<string>('màéz-uiok')
26
+
27
+ const { score, isMatching } = useStringMatching(string1, string2)
28
+ </script>
29
+
30
+ <template>
31
+ <MazInput v-model="string1" label="Enter first string" />
32
+ <MazInput v-model="string2" label="Enter second string" />
33
+
34
+ <p>
35
+ <b>isMatching:</b> {{ isMatching }}
36
+ </p>
37
+ <p>
38
+ <b>score:</b> {{ score }}
39
+ </p>
40
+ </template>
41
+ ```
@@ -0,0 +1,171 @@
1
+ ---
2
+ title: "useSwipe"
3
+ description: "useSwipe is a Vue composable that simplifies the management of \"swipe\" interactions on HTML elements."
4
+ package: "maz-ui"
5
+ url: "https://maz-ui.com/composables/use-swipe"
6
+ ---
7
+
8
+ # useSwipe
9
+
10
+ > useSwipe is a Vue composable that simplifies the management of "swipe" interactions on HTML elements.
11
+
12
+ - Package: `maz-ui`
13
+ - Import: `import { useSwipe } from 'maz-ui/composables/useSwipe'`
14
+ - Nuxt: auto-imported by `@maz-ui/nuxt`, no import needed in a Nuxt app
15
+ - Web: https://maz-ui.com/composables/use-swipe
16
+
17
+ ## Introduction
18
+
19
+ `useSwipe` allows you to detect and react to swiping movements on an HTML element. It provides you with various information about the swipe movement, such as the direction, distance, start, and end coordinates.
20
+ You can use this information to implement specific interactions in your application, such as scrolling a carousel, opening a side menu, etc.
21
+
22
+ It is built on top of [Pointer Events](https://developer.mozilla.org/en-US/docs/Web/API/Pointer_events), so it works with **touch, mouse and pen** out of the box.
23
+
24
+ **Tip:**
25
+
26
+ For a real-time drag gesture (follow the pointer, snap back, drag-to-dismiss…) rather than discrete directional detection, use [useDrag](./use-drag.md).
27
+
28
+ ## Key Features
29
+
30
+ - Detects swipes in all 4 directions (left, right, up, down)
31
+ - Works with touch, mouse and pen (Pointer Events)
32
+ - Provides key information about the swipe movement (start/end coordinates, horizontal/vertical distance)
33
+ - Allows you to configure callbacks for each swipe direction
34
+ - Restrict the gesture to specific pointer types
35
+ - Possibility to customize the swipe detection threshold
36
+ - Automatically handles the addition and removal of event listeners
37
+ - Can be used with any HTML element
38
+
39
+ ## Basic Usage
40
+
41
+ Here's an example of using the useSwipe composable:
42
+
43
+ ```vue
44
+ <script lang="ts" setup>
45
+ import { useSwipe } from 'maz-ui/composables'
46
+ import { onMounted, onUnmounted, ref } from 'vue'
47
+
48
+ const swipeContainer = ref<HTMLDivElement>()
49
+
50
+ const lastSwipeDirection = ref<string>('None')
51
+
52
+ const { xDiff, yDiff, start, stop } = useSwipe({
53
+ element: swipeContainer,
54
+ onLeft: () => lastSwipeDirection.value = 'Swiped left',
55
+ onRight: () => lastSwipeDirection.value = 'Swiped right',
56
+ onUp: () => lastSwipeDirection.value = 'Swiped up',
57
+ onDown: () => lastSwipeDirection.value = 'Swiped down',
58
+ threshold: 50,
59
+ })
60
+
61
+ /**
62
+ * Start listening for swipe events
63
+ * You can also call start() directly
64
+ * But it's better to call it in onMounted specially for SSR
65
+ */
66
+ onMounted(() => {
67
+ start()
68
+ })
69
+
70
+ // Stop listening for swipe events
71
+ onUnmounted(() => {
72
+ stop()
73
+ })
74
+ </script>
75
+
76
+ <template>
77
+ <div ref="swipeContainer" class="swipe-container">
78
+ <p>
79
+ Swipe in any direction<br>
80
+ <span class="text-sm text-muted">
81
+ (works with touch, mouse and pen)
82
+ </span>
83
+ <br><br>
84
+ Last swipe direction: {{ lastSwipeDirection || 'None' }}
85
+ </p>
86
+ </div>
87
+ </template>
88
+
89
+ <style>
90
+ .swipe-container {
91
+ border: 1px solid #e2e2e3;
92
+ border-radius: 10px;
93
+ height: 200px;
94
+ display: flex;
95
+ justify-content: center;
96
+ align-items: center;
97
+ text-align: center;
98
+ font-size: 1.2rem;
99
+ }
100
+ </style>
101
+ ```
102
+
103
+ ```ts
104
+ interface UseSwipeOptions {
105
+ /**
106
+ * The HTML element on which the swipe events will be handled. This can be either a direct reference to the element or a CSS selector.
107
+ * @required
108
+ */
109
+ element: HTMLElement | string | Ref<HTMLElement>
110
+ /** Callback executed when a left swipe is detected. */
111
+ onLeft?: (event: PointerEvent) => void
112
+ /** Callback executed when a right swipe is detected. */
113
+ onRight?: (event: PointerEvent) => void
114
+ /** Callback executed when an up swipe is detected. */
115
+ onUp?: (event: PointerEvent) => void
116
+ /** Callback executed when a down swipe is detected. */
117
+ onDown?: (event: PointerEvent) => void
118
+ /**
119
+ * The minimum distance the swipe must travel to be considered valid.
120
+ * @default 50
121
+ */
122
+ threshold?: number
123
+ /**
124
+ * Pointer types that can trigger the swipe.
125
+ * @default ['mouse', 'touch', 'pen']
126
+ */
127
+ pointerTypes?: ('mouse' | 'touch' | 'pen')[]
128
+ /**
129
+ * Whether to prevent the default behavior of the pointer move event
130
+ * (the move listener becomes non-passive when enabled).
131
+ * @default false
132
+ */
133
+ preventDefaultOnMove?: boolean
134
+ /**
135
+ * Whether to prevent the default behavior of the mousewheel event.
136
+ * @default false
137
+ */
138
+ preventDefaultOnMouseWheel?: boolean
139
+ /**
140
+ * Whether to start listening immediately on instantiation.
141
+ * @default false
142
+ */
143
+ immediate?: boolean
144
+ /**
145
+ * Whether to trigger the swipe event only on pointer up.
146
+ * @default false
147
+ */
148
+ triggerOnEnd?: boolean
149
+ }
150
+ ```
151
+
152
+ ```ts
153
+ interface UseSwipeReturn {
154
+ /** A function to start listening for swipe events. */
155
+ start: () => void
156
+ /** A function to stop listening for swipe events. */
157
+ stop: () => void
158
+ /** The horizontal difference between the start and end coordinates of the swipe. */
159
+ xDiff: Ref<number | undefined>
160
+ /** The vertical difference between the start and end coordinates of the swipe. */
161
+ yDiff: Ref<number | undefined>
162
+ /** The horizontal start coordinate of the swipe. */
163
+ xStart: Ref<number | undefined>
164
+ /** The horizontal end coordinate of the swipe. */
165
+ xEnd: Ref<number | undefined>
166
+ /** The vertical start coordinate of the swipe. */
167
+ yStart: Ref<number | undefined>
168
+ /** The vertical end coordinate of the swipe. */
169
+ yEnd: Ref<number | undefined>
170
+ }
171
+ ```