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,83 @@
1
+ ---
2
+ title: "normalizeString"
3
+ description: "Powerful string normalizer - strip accents, normalize whitespace, remove special characters, change case, and apply Unicode normalization forms."
4
+ package: "@maz-ui/utils"
5
+ url: "https://maz-ui.com/ecosystem/utils/normalize-string"
6
+ ---
7
+
8
+ # normalizeString
9
+
10
+ > Powerful string normalizer - strip accents, normalize whitespace, remove special characters, change case, and apply Unicode normalization forms.
11
+
12
+ - Package: `@maz-ui/utils`
13
+ - Import: `import { normalizeString } from '@maz-ui/utils/helpers/normalizeString'`
14
+ - Web: https://maz-ui.com/ecosystem/utils/normalize-string
15
+
16
+ The Swiss-army knife for turning user input into a safe, comparable, slug-ready string.
17
+
18
+ ## Usage
19
+
20
+ ```ts
21
+ import { normalizeString } from '@maz-ui/utils'
22
+
23
+ normalizeString(' Crème Brûlée ')
24
+ // → 'creme-brulee'
25
+
26
+ normalizeString('Élégant Café', { case: 'kebab-case' })
27
+ // → 'elegant-cafe'
28
+
29
+ normalizeString('My Article Title!', {
30
+ case: 'kebab-case',
31
+ removeSpecialCharacters: true,
32
+ })
33
+ // → 'my-article-title'
34
+ ```
35
+
36
+ ## API
37
+
38
+ ```ts
39
+ function normalizeString(
40
+ input: string | number | boolean,
41
+ options?: NormalizeStringOptions,
42
+ ): string
43
+ ```
44
+
45
+ ### Options
46
+
47
+ | Option | Type | Default | Description |
48
+ | -------------------------- | ------------ | ------------------ | -------------------------------------------------------------------------------------------- |
49
+ | `removeAccents` | `boolean` | `true` | Strip diacritics (`é → e`, `ç → c`, …) |
50
+ | `caseSensitive` | `boolean` | `false` | When `false`, lowercases the result unless `case` is set |
51
+ | `replaceSpaces` | `boolean` | `true` | Replace spaces with `-` |
52
+ | `removeSpecialCharacters` | `boolean` | `false` | Strip non-alphanumeric / non-dash characters (Latin alphabet only) |
53
+ | `trim` | `boolean` | `true` | Trim leading/trailing whitespace |
54
+ | `normalizeSpaces` | `boolean` | `true` | Collapse runs of whitespace into a single space |
55
+ | `removeNumbers` | `boolean` | `false` | Strip digits |
56
+ | `case` | `CaseFormat` | `undefined` | Force a target case: `kebab-case`, `camelCase`, `PascalCase`, `snake_case`, `lowercase`, `UPPERCASE` |
57
+ | `customNormalizationForms` | `string[]` | `['NFC', 'NFKD']` | Unicode [normalization forms](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String/normalize) applied at the end |
58
+
59
+ ## Examples
60
+
61
+ Generate a URL-safe slug:
62
+
63
+ ```ts
64
+ const slug = normalizeString(post.title, {
65
+ case: 'kebab-case',
66
+ removeSpecialCharacters: true,
67
+ })
68
+ ```
69
+
70
+ Build a case-insensitive comparison key:
71
+
72
+ ```ts
73
+ const a = normalizeString('Éléphant')
74
+ const b = normalizeString('elephant')
75
+ a === b // true
76
+ ```
77
+
78
+ Preserve original casing but strip diacritics:
79
+
80
+ ```ts
81
+ normalizeString('Crème Brûlée', { caseSensitive: true, replaceSpaces: false })
82
+ // → 'Creme Brulee'
83
+ ```
@@ -0,0 +1,51 @@
1
+ ---
2
+ title: "formatNumber"
3
+ description: "The module formatNumber is a function that formats numbers with the native api [Intl.NumberFormat](https://developer.mozilla.org/fr/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat) from browsers and Node.js"
4
+ package: "@maz-ui/utils"
5
+ url: "https://maz-ui.com/ecosystem/utils/number"
6
+ ---
7
+
8
+ # formatNumber
9
+
10
+ > The module formatNumber is a function that formats numbers with the native api [Intl.NumberFormat](https://developer.mozilla.org/fr/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat) from browsers and Node.js
11
+
12
+ - Package: `@maz-ui/utils`
13
+ - Import: `import { formatNumber } from '@maz-ui/utils/helpers/formatNumber'`
14
+ - Web: https://maz-ui.com/ecosystem/utils/number
15
+
16
+ > This module uses the native api [Intl.NumberFormat](https://developer.mozilla.org/fr/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat) from browsers
17
+
18
+ ```vue
19
+ <script lang="ts" setup>
20
+ import { formatNumber } from '@maz-ui/utils'
21
+ import { computed, ref } from 'vue'
22
+
23
+ const numberValue = ref(69)
24
+
25
+ const numberFormatted = computed(() =>
26
+ formatNumber(numberValue.value, 'en-US'),
27
+ )
28
+ </script>
29
+
30
+ <template>
31
+ <MazInput v-model="numberValue" type="number" />
32
+
33
+ <div
34
+ style="padding: 16px; margin-top: 16px; background-color: var(--maz-surface-300);"
35
+ >
36
+ {{ numberFormatted }}
37
+ </div>
38
+ </template>
39
+ ```
40
+
41
+ ## Options
42
+
43
+ > All options from [Intl.NumberFormat](https://developer.mozilla.org/fr/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat) are available
44
+
45
+ ## Default options
46
+
47
+ ```ts
48
+ const DEFAULT_OPTIONS: Intl.NumberFormatOptions = {
49
+ minimumFractionDigits: 2,
50
+ }
51
+ ```
@@ -0,0 +1,41 @@
1
+ ---
2
+ title: "pascalCase"
3
+ description: "Convert any common string casing - kebab, snake, space-separated, camelCase or UPPERCASE - to PascalCase."
4
+ package: "@maz-ui/utils"
5
+ url: "https://maz-ui.com/ecosystem/utils/pascal-case"
6
+ ---
7
+
8
+ # pascalCase
9
+
10
+ > Convert any common string casing - kebab, snake, space-separated, camelCase or UPPERCASE - to PascalCase.
11
+
12
+ - Package: `@maz-ui/utils`
13
+ - Import: `import { pascalCase } from '@maz-ui/utils/helpers/pascalCase'`
14
+ - Web: https://maz-ui.com/ecosystem/utils/pascal-case
15
+
16
+ ## Usage
17
+
18
+ ```ts
19
+ import { pascalCase } from '@maz-ui/utils'
20
+
21
+ pascalCase('my-component-name') // → 'MyComponentName'
22
+ pascalCase('hello_world') // → 'HelloWorld'
23
+ pascalCase('hello world') // → 'HelloWorld'
24
+ pascalCase('helloWorld') // → 'HelloWorld'
25
+ ```
26
+
27
+ ## API
28
+
29
+ ```ts
30
+ function pascalCase(str: string): string
31
+ ```
32
+
33
+ | Parameter | Type | Description |
34
+ | --------- | -------- | --------------------- |
35
+ | `str` | `string` | The string to convert |
36
+
37
+ ## Notes
38
+
39
+ - Detects `-`, `_` and space separators automatically.
40
+ - Handles ALL-CAPS inputs by lowercasing before re-capitalizing.
41
+ - For fine-grained control, use [`normalizeString`](./normalize-string.md) with `{ case: 'PascalCase' }`.
@@ -0,0 +1,72 @@
1
+ ---
2
+ title: "preventIosInputZoom"
3
+ description: "Stop iOS from zooming the page when a form field gets the focus, without changing the design of the fields."
4
+ package: "@maz-ui/utils"
5
+ url: "https://maz-ui.com/ecosystem/utils/prevent-ios-input-zoom"
6
+ ---
7
+
8
+ # preventIosInputZoom
9
+
10
+ > Stop iOS from zooming the page when a form field gets the focus, without changing the design of the fields.
11
+
12
+ - Package: `@maz-ui/utils`
13
+ - Import: `import { addViewportMaximumScale, preventIosInputZoom } from '@maz-ui/utils/helpers/preventIosInputZoom'`
14
+ - Web: https://maz-ui.com/ecosystem/utils/prevent-ios-input-zoom
15
+
16
+ ## Why
17
+
18
+ iOS zooms the page when a focused field has a font size below `16px`, and does not zoom out afterwards. With the maz-ui presets anchored on a `14px` `base-font-size`, most fields are below this threshold.
19
+
20
+ `preventIosInputZoom` adds `maximum-scale=1` to the `<meta name="viewport">`, **on iOS only**:
21
+
22
+ - iOS no longer zooms on focus, and still lets the user pinch to zoom (Safari ignores `maximum-scale` for the pinch zoom since iOS 10).
23
+ - Android is left untouched: it does not zoom on focus, but `maximum-scale` would block the pinch zoom there.
24
+ - The design of the fields is not changed.
25
+
26
+ ## Usage
27
+
28
+ Call it once, when the app starts:
29
+
30
+ ```ts
31
+ import { preventIosInputZoom } from '@maz-ui/utils'
32
+
33
+ preventIosInputZoom()
34
+ ```
35
+
36
+ **Tip: Nuxt**
37
+
38
+ With [@maz-ui/nuxt](../nuxt.md), enable the `general.preventIosInputZoom` option instead.
39
+
40
+ **Warning: Head managers**
41
+
42
+ If your viewport is managed by a head manager (`@unhead/vue`, `@vueuse/head`...), it can overwrite a direct change of the DOM on its next render. Set the viewport through it with `addViewportMaximumScale` instead:
43
+
44
+ ```ts
45
+ import { addViewportMaximumScale, isIos } from '@maz-ui/utils'
46
+ import { useHead } from '@unhead/vue'
47
+
48
+ const viewport = 'width=device-width, initial-scale=1'
49
+
50
+ useHead({
51
+ meta: [{ name: 'viewport', content: isIos() ? addViewportMaximumScale(viewport) : viewport }],
52
+ })
53
+ ```
54
+
55
+ ## API
56
+
57
+ ```ts
58
+ function preventIosInputZoom(): () => void
59
+
60
+ function addViewportMaximumScale(content: string): string
61
+ ```
62
+
63
+ - `preventIosInputZoom` does nothing outside iOS, during SSR or when the page has no `<meta name="viewport">` (it does not create one). It returns a function that restores the original viewport.
64
+ - `addViewportMaximumScale` returns the viewport content with `maximum-scale=1`, replacing an existing `maximum-scale`.
65
+
66
+ ```ts
67
+ addViewportMaximumScale('width=device-width, initial-scale=1')
68
+ // 'width=device-width, initial-scale=1, maximum-scale=1'
69
+
70
+ addViewportMaximumScale('width=device-width, maximum-scale=5')
71
+ // 'width=device-width, maximum-scale=1'
72
+ ```
@@ -0,0 +1,85 @@
1
+ ---
2
+ title: "ScriptLoader"
3
+ description: "Class to inject and cache a <script> tag in document head, with an awaitable load promise - ideal for third-party SDKs."
4
+ package: "@maz-ui/utils"
5
+ url: "https://maz-ui.com/ecosystem/utils/script-loader"
6
+ ---
7
+
8
+ # ScriptLoader
9
+
10
+ > Class to inject and cache a <script> tag in document head, with an awaitable load promise - ideal for third-party SDKs.
11
+
12
+ - Package: `@maz-ui/utils`
13
+ - Import: `import { ScriptLoader } from '@maz-ui/utils/helpers/scriptLoader'`
14
+ - Web: https://maz-ui.com/ecosystem/utils/script-loader
15
+
16
+ Class to inject and cache a tag in document head, with an awaitable load promise - ideal for third-party SDKs.
17
+
18
+ `ScriptLoader` handles deduplication (won't inject the same script twice), error reporting, and optional one-time loading semantics.
19
+
20
+ ## Usage
21
+
22
+ ```ts
23
+ import { ScriptLoader } from '@maz-ui/utils'
24
+
25
+ const loader = new ScriptLoader({
26
+ identifier: 'stripe-js',
27
+ src: 'https://js.stripe.com/v3/',
28
+ })
29
+
30
+ await loader.load()
31
+ // window.Stripe is now available
32
+ ```
33
+
34
+ ## API
35
+
36
+ ```ts
37
+ class ScriptLoader {
38
+ constructor(options: ScriptLoaderOptions)
39
+ load(): Promise<Event | undefined>
40
+ removeTag(tag: Element | string): void
41
+ }
42
+
43
+ interface ScriptLoaderOptions {
44
+ identifier: string
45
+ src: string
46
+ once?: boolean // default: true
47
+ async?: boolean // default: true
48
+ defer?: boolean // default: true
49
+ }
50
+ ```
51
+
52
+ | Option | Type | Default | Description |
53
+ | ------------ | --------- | ------- | ---------------------------------------------------------------------------- |
54
+ | `identifier` | `string` | - | Unique key used to deduplicate the script across calls (set as `data-identifier`) |
55
+ | `src` | `string` | - | Script URL |
56
+ | `once` | `boolean` | `true` | When `true`, skip injection if a script with the same identifier already loaded |
57
+ | `async` | `boolean` | `true` | Sets the `async` attribute on the `<script>` tag |
58
+ | `defer` | `boolean` | `true` | Sets the `defer` attribute on the `<script>` tag |
59
+
60
+ ### Methods
61
+
62
+ - **`load()`** - Inject the script (or resolve immediately if cached) and return a promise that resolves to the load `Event` once the script is ready.
63
+ - **`removeTag(tag)`** - Remove an injected `<script>` tag by element reference or identifier string.
64
+
65
+ ## Errors
66
+
67
+ `ScriptLoader` throws synchronously in two situations:
68
+
69
+ - `src` or `identifier` is missing.
70
+ - Called in a non-browser environment (no `window` available).
71
+
72
+ ## Examples
73
+
74
+ Reload a script on demand by disabling caching:
75
+
76
+ ```ts
77
+ const loader = new ScriptLoader({
78
+ identifier: 'my-widget',
79
+ src: '/widget.js',
80
+ once: false,
81
+ })
82
+
83
+ await loader.load() // first injection
84
+ await loader.load() // previous tag removed, new one injected
85
+ ```
@@ -0,0 +1,65 @@
1
+ ---
2
+ title: "sleep"
3
+ description: "Pause execution for a given number of milliseconds. Returns a promise that resolves after the delay."
4
+ package: "@maz-ui/utils"
5
+ url: "https://maz-ui.com/ecosystem/utils/sleep"
6
+ ---
7
+
8
+ # sleep
9
+
10
+ > Pause execution for a given number of milliseconds. Returns a promise that resolves after the delay.
11
+
12
+ - Package: `@maz-ui/utils`
13
+ - Import: `import { sleep } from '@maz-ui/utils/helpers/sleep'`
14
+ - Web: https://maz-ui.com/ecosystem/utils/sleep
15
+
16
+ ## Usage
17
+
18
+ ```ts
19
+ import { sleep } from '@maz-ui/utils'
20
+
21
+ await sleep(500)
22
+ console.log('Half a second later')
23
+ ```
24
+
25
+ ## API
26
+
27
+ ```ts
28
+ function sleep(duration: number): Promise<void>
29
+ ```
30
+
31
+ | Parameter | Type | Description |
32
+ | ---------- | -------- | --------------------- |
33
+ | `duration` | `number` | Delay in milliseconds |
34
+
35
+ Returns a `Promise<void>` that resolves once the delay elapses.
36
+
37
+ ## Examples
38
+
39
+ Chain delays in a sequence:
40
+
41
+ ```ts
42
+ async function rampUp() {
43
+ console.log('Starting')
44
+ await sleep(1000)
45
+ console.log('1s later')
46
+ await sleep(2000)
47
+ console.log('3s later')
48
+ }
49
+ ```
50
+
51
+ Use as a guard between retries with exponential backoff:
52
+
53
+ ```ts
54
+ async function withRetry(task: () => Promise<void>, attempts = 3) {
55
+ for (let i = 0; i < attempts; i++) {
56
+ try {
57
+ return await task()
58
+ }
59
+ catch {
60
+ await sleep(2 ** i * 100)
61
+ }
62
+ }
63
+ throw new Error('Max retries exceeded')
64
+ }
65
+ ```
@@ -0,0 +1,42 @@
1
+ ---
2
+ title: "snakeCase"
3
+ description: "Convert any common string casing to snake_case - handles camelCase, PascalCase, kebab-case, spaces and consecutive capitals."
4
+ package: "@maz-ui/utils"
5
+ url: "https://maz-ui.com/ecosystem/utils/snake-case"
6
+ ---
7
+
8
+ # snakeCase
9
+
10
+ > Convert any common string casing to snake_case - handles camelCase, PascalCase, kebab-case, spaces and consecutive capitals.
11
+
12
+ - Package: `@maz-ui/utils`
13
+ - Import: `import { snakeCase } from '@maz-ui/utils/helpers/snakeCase'`
14
+ - Web: https://maz-ui.com/ecosystem/utils/snake-case
15
+
16
+ ## Usage
17
+
18
+ ```ts
19
+ import { snakeCase } from '@maz-ui/utils'
20
+
21
+ snakeCase('myComponent') // → 'my_component'
22
+ snakeCase('MyComponent') // → 'my_component'
23
+ snakeCase('XMLParser') // → 'xml_parser'
24
+ snakeCase('hello-world') // → 'hello_world'
25
+ snakeCase('hello world') // → 'hello_world'
26
+ ```
27
+
28
+ ## API
29
+
30
+ ```ts
31
+ function snakeCase(str: string): string
32
+ ```
33
+
34
+ | Parameter | Type | Description |
35
+ | --------- | -------- | --------------------- |
36
+ | `str` | `string` | The string to convert |
37
+
38
+ ## Notes
39
+
40
+ - Consecutive uppercase letters are handled (e.g. `XMLParser` → `xml_parser`).
41
+ - Leading and trailing underscores are stripped.
42
+ - Multiple separators collapse into a single underscore.
@@ -0,0 +1,97 @@
1
+ ---
2
+ title: "Swipe"
3
+ description: "Detect directional touch swipes on an element with configurable threshold and optional mouse-wheel guards."
4
+ package: "@maz-ui/utils"
5
+ url: "https://maz-ui.com/ecosystem/utils/swipe-handler"
6
+ ---
7
+
8
+ # Swipe
9
+
10
+ > Detect directional touch swipes on an element with configurable threshold and optional mouse-wheel guards.
11
+
12
+ - Package: `@maz-ui/utils`
13
+ - Import: `import { Swipe } from '@maz-ui/utils/helpers/swipeHandler'`
14
+ - Web: https://maz-ui.com/ecosystem/utils/swipe-handler
15
+
16
+ `Swipe` attaches touch listeners to a DOM element and fires callbacks for left, right, up and down swipes once a configurable distance threshold is crossed.
17
+
18
+ ## Usage
19
+
20
+ ```ts
21
+ import { Swipe } from '@maz-ui/utils'
22
+
23
+ const swipe = new Swipe({
24
+ element: '#carousel',
25
+ immediate: true,
26
+ onLeft: () => carousel.next(),
27
+ onRight: () => carousel.prev(),
28
+ })
29
+
30
+ // later
31
+ swipe.stop()
32
+ ```
33
+
34
+ ## API
35
+
36
+ ```ts
37
+ class Swipe {
38
+ constructor(options: SwipeOptions)
39
+
40
+ start(element?: HTMLElement | string | null): void
41
+ stop(): void
42
+
43
+ xStart?: number
44
+ yStart?: number
45
+ xEnd?: number
46
+ yEnd?: number
47
+ xDiff?: number
48
+ yDiff?: number
49
+ }
50
+ ```
51
+
52
+ ### Options
53
+
54
+ | Option | Type | Default | Description |
55
+ | ---------------------------- | ----------------------------------- | ------- | -------------------------------------------------------------------------- |
56
+ | `element` | `HTMLElement \| string \| null` | `null` | Target element or CSS selector. |
57
+ | `threshold` | `number` | `50` | Minimum distance in px before a swipe is recognised. |
58
+ | `onLeft` / `onRight` / `onUp` / `onDown` | `(event: TouchEvent) => void` | - | Direction callbacks. |
59
+ | `onValuesChanged` | `(values: SwipeValues) => void` | - | Fires whenever start/end/diff values are updated - useful for live tracking. |
60
+ | `preventDefaultOnTouchMove` | `boolean` | `false` | Calls `event.preventDefault()` on `touchmove`. |
61
+ | `preventDefaultOnMouseWheel` | `boolean` | `false` | Calls `event.preventDefault()` on `mousewheel`. |
62
+ | `immediate` | `boolean` | `false` | Attach listeners immediately from the constructor. |
63
+ | `triggerOnEnd` | `boolean` | `false` | Fire direction callbacks on `touchend` instead of on every `touchmove`. |
64
+
65
+ ### Methods
66
+
67
+ - **`start(element?)`** - Begin listening. Optionally re-target a new element.
68
+ - **`stop()`** - Detach all listeners. Live values reset.
69
+
70
+ ## Examples
71
+
72
+ Slide-based gallery:
73
+
74
+ ```ts
75
+ new Swipe({
76
+ element: '.gallery',
77
+ immediate: true,
78
+ threshold: 80,
79
+ triggerOnEnd: true,
80
+ onLeft: () => gallery.next(),
81
+ onRight: () => gallery.previous(),
82
+ })
83
+ ```
84
+
85
+ Live progress while dragging:
86
+
87
+ ```ts
88
+ new Swipe({
89
+ element: '.draggable',
90
+ immediate: true,
91
+ onValuesChanged: ({ xDiff }) => {
92
+ if (typeof xDiff === 'number') {
93
+ drawer.style.transform = `translateX(${-xDiff}px)`
94
+ }
95
+ },
96
+ })
97
+ ```
@@ -0,0 +1,47 @@
1
+ ---
2
+ title: "TextareaAutogrow"
3
+ description: "Automatically resize a `<textarea>` element to fit its content as the user types or the window resizes."
4
+ package: "@maz-ui/utils"
5
+ url: "https://maz-ui.com/ecosystem/utils/textarea-autogrow"
6
+ ---
7
+
8
+ # TextareaAutogrow
9
+
10
+ > Automatically resize a `<textarea>` element to fit its content as the user types or the window resizes.
11
+
12
+ - Package: `@maz-ui/utils`
13
+ - Import: `import { TextareaAutogrow } from '@maz-ui/utils/helpers/TextareaAutogrow'`
14
+ - Web: https://maz-ui.com/ecosystem/utils/textarea-autogrow
15
+
16
+ The helper disables manual resize, sets `box-sizing: border-box`, and updates `height` to match `scrollHeight` on input and (debounced) on window resize.
17
+
18
+ ## Usage
19
+
20
+ ```ts
21
+ import { TextareaAutogrow } from '@maz-ui/utils'
22
+
23
+ const textarea = document.querySelector<HTMLTextAreaElement>('textarea#bio')!
24
+ const autogrow = new TextareaAutogrow(textarea)
25
+
26
+ // later
27
+ autogrow.disconnect()
28
+ ```
29
+
30
+ ## API
31
+
32
+ ```ts
33
+ class TextareaAutogrow {
34
+ constructor(element: HTMLTextAreaElement)
35
+ disconnect(): void
36
+ }
37
+ ```
38
+
39
+ | Method | Description |
40
+ | -------------- | ----------------------------------------------------------------- |
41
+ | `disconnect()` | Detach the input and resize listeners. The textarea remains styled. |
42
+
43
+ ## Notes
44
+
45
+ - Listeners are attached on first focus - until then, the textarea is fully styled but the height isn't yet computed.
46
+ - Resize updates are debounced by 200 ms.
47
+ - In a Vue app, use [`MazTextarea`](../../components/maz-textarea.md): it grows with its content.
@@ -0,0 +1,54 @@
1
+ ---
2
+ title: "throttleId"
3
+ description: "Throttle an async function with isolated state per identifier - runs immediately, then at most once per interval."
4
+ package: "@maz-ui/utils"
5
+ url: "https://maz-ui.com/ecosystem/utils/throttle-id"
6
+ ---
7
+
8
+ # throttleId
9
+
10
+ > Throttle an async function with isolated state per identifier - runs immediately, then at most once per interval.
11
+
12
+ - Package: `@maz-ui/utils`
13
+ - Import: `import { throttleId } from '@maz-ui/utils/helpers/throttleId'`
14
+ - Web: https://maz-ui.com/ecosystem/utils/throttle-id
15
+
16
+ `throttleId` is the async, keyed counterpart of [`throttle`](./throttle.md). The first call runs immediately and returns its promise; further calls within `interval` are coalesced and resolve to the result of the last replayed call.
17
+
18
+ ## Usage
19
+
20
+ ```ts
21
+ import { throttleId } from '@maz-ui/utils'
22
+
23
+ const trackEvent = throttleId(
24
+ 'analytics',
25
+ async (event: { name: string }) => {
26
+ return fetch('/track', { method: 'POST', body: JSON.stringify(event) })
27
+ },
28
+ 1000,
29
+ )
30
+
31
+ trackEvent({ name: 'scroll' })
32
+ trackEvent({ name: 'scroll' }) // coalesced into the first call
33
+ ```
34
+
35
+ ## API
36
+
37
+ ```ts
38
+ function throttleId<T, Args extends unknown[]>(
39
+ identifier: string,
40
+ func: (...args: Args) => T | Promise<T>,
41
+ interval: number,
42
+ ): (...args: Args) => Promise<T>
43
+ ```
44
+
45
+ | Parameter | Type | Description |
46
+ | ------------ | ---------- | ------------------------------------------------------ |
47
+ | `identifier` | `string` | Unique key isolating this throttle from others |
48
+ | `func` | `Function` | The async (or sync) function to throttle |
49
+ | `interval` | `number` | Minimum interval between executions, in milliseconds |
50
+
51
+ ## Related
52
+
53
+ - [`debounceId`](./debounce-id.md) - wait for silence instead of rate-limiting.
54
+ - [`throttle`](./throttle.md) - non-async, single-instance throttle.