maz-ui 5.0.0 → 5.1.0-beta.0

package/docs/ecosystem/utils/camel-case.md

@@ -0,0 +1,37 @@
+---
+title: "camelCase"
+description: "Convert a kebab-case string to camelCase by stripping dashes and uppercasing the following letter."
+package: "@maz-ui/utils"
+url: "https://maz-ui.com/ecosystem/utils/camel-case"
+---
+
+# camelCase
+
+> Convert a kebab-case string to camelCase by stripping dashes and uppercasing the following letter.
+
+- Package: `@maz-ui/utils`
+- Import: `import { camelCase } from '@maz-ui/utils/helpers/camelCase'`
+- Web: https://maz-ui.com/ecosystem/utils/camel-case
+
+## Usage
+
+```ts
+import { camelCase } from '@maz-ui/utils'
+
+camelCase('my-component-name') // → 'myComponentName'
+camelCase('hello-world') // → 'helloWorld'
+```
+
+## API
+
+```ts
+function camelCase(str: string): string
+```
+
+| Parameter | Type     | Description           |
+| --------- | -------- | --------------------- |
+| `str`     | `string` | The string to convert |
+
+## Notes
+
+`camelCase` is intentionally minimal - it only handles `kebab-case` input. For more general normalization (snake_case, spaces, PascalCase), use [`normalizeString`](./normalize-string.md) with the `case: 'camelCase'` option.

package/docs/ecosystem/utils/capitalize.md

@@ -0,0 +1,37 @@
+---
+title: "capitalize"
+description: "The module capitalize is a function that adds a capital letter to a string"
+package: "@maz-ui/utils"
+url: "https://maz-ui.com/ecosystem/utils/capitalize"
+---
+
+# capitalize
+
+> The module capitalize is a function that adds a capital letter to a string
+
+- Package: `@maz-ui/utils`
+- Import: `import { capitalize } from '@maz-ui/utils/helpers/capitalize'`
+- Web: https://maz-ui.com/ecosystem/utils/capitalize
+
+```vue
+<script lang="ts" setup>
+import { capitalize } from '@maz-ui/utils'
+import { computed, ref } from 'vue'
+
+const stringValue = ref('string value')
+
+const stringFormatted = computed(() =>
+  capitalize(stringValue.value),
+)
+</script>
+
+<template>
+  <MazInput v-model="stringValue" />
+
+  <div
+    class="flex flex-center rounded-md gap-0.5 p-4 mt-16 bg-surface-300"
+  >
+    {{ stringFormatted }}
+  </div>
+</template>
+```

package/docs/ecosystem/utils/check-availability.md

@@ -0,0 +1,85 @@
+---
+title: "checkAvailability"
+description: "Poll a getter until a value is available (or matches an expected value), then run a callback - with timeout and configurable retry interval."
+package: "@maz-ui/utils"
+url: "https://maz-ui.com/ecosystem/utils/check-availability"
+---
+
+# checkAvailability
+
+> Poll a getter until a value is available (or matches an expected value), then run a callback - with timeout and configurable retry interval.
+
+- Package: `@maz-ui/utils`
+- Import: `import { checkAvailability } from '@maz-ui/utils/helpers/checkAvailability'`
+- Web: https://maz-ui.com/ecosystem/utils/check-availability
+
+Useful for waiting on a third-party SDK to attach itself to `window`, on a Vue ref to be populated after mount, or on any asynchronously-available value.
+
+## Usage
+
+```ts
+import { checkAvailability } from '@maz-ui/utils'
+
+checkAvailability(
+  () => window.Stripe,
+  (Stripe) => {
+    const stripe = Stripe('pk_...')
+  },
+)
+```
+
+## API
+
+```ts
+function checkAvailability<T>(
+  getRef: () => T | null | undefined,
+  callback: (value: NonNullable<T>) => void,
+  options?: {
+    maxAttempts?: number
+    interval?: number
+    expectedValue?: T
+    errorMessage?: string
+    onError?: (error: Error) => void
+  },
+): void
+```
+
+| Option          | Type       | Default | Description                                                            |
+| --------------- | ---------- | ------- | ---------------------------------------------------------------------- |
+| `maxAttempts`   | `number`   | `20`    | Number of polls before giving up                                       |
+| `interval`      | `number`   | `100`   | Delay between polls, in milliseconds                                   |
+| `expectedValue` | `T`        | - | When set, callback fires only when `getRef()` strictly equals this value |
+| `errorMessage`  | `string`   | - | Custom error message when `maxAttempts` is exceeded                    |
+| `onError`       | `Function` | - | Called with the timeout `Error` instead of throwing                    |
+
+With default options, the helper polls every 100 ms up to 20 times - a 2 second timeout in total.
+
+## Examples
+
+Wait for a global SDK with a custom timeout:
+
+```ts
+checkAvailability(
+  () => window.gtag,
+  (gtag) => {
+    gtag('event', 'page_view')
+  },
+  {
+    maxAttempts: 50,
+    interval: 200,
+    onError: (err) => {
+      console.warn('gtag never loaded', err)
+    },
+  },
+)
+```
+
+Wait for a specific value (e.g. SDK becomes ready):
+
+```ts
+checkAvailability(
+  () => window.__SDK_STATE__,
+  () => boot(),
+  { expectedValue: 'ready' },
+)
+```

package/docs/ecosystem/utils/cookie.md

@@ -0,0 +1,86 @@
+---
+title: "cookie"
+description: "Read, write and delete browser cookies with full attribute support - `path`, `domain`, `maxAge`, `expires`, `secure`, `sameSite`, `partitioned`."
+package: "@maz-ui/utils"
+url: "https://maz-ui.com/ecosystem/utils/cookie"
+---
+
+# cookie
+
+> Read, write and delete browser cookies with full attribute support - `path`, `domain`, `maxAge`, `expires`, `secure`, `sameSite`, `partitioned`.
+
+- Package: `@maz-ui/utils`
+- Import: `import { getCookie, setCookie, deleteCookie } from '@maz-ui/utils/helpers/cookie'`
+- Web: https://maz-ui.com/ecosystem/utils/cookie
+
+The module exports three functions: `getCookie`, `setCookie`, `deleteCookie`. Reads work both on the client (via `document.cookie`) and on the server (when you pass the raw `Cookie` header).
+
+## getCookie
+
+```ts
+import { getCookie } from '@maz-ui/utils'
+
+const theme = getCookie('theme') // 'dark' | null
+```
+
+```ts
+function getCookie(key: string, cookieHeader?: string): string | null
+```
+
+| Parameter      | Type     | Description                                                                                  |
+| -------------- | -------- | -------------------------------------------------------------------------------------------- |
+| `key`          | `string` | Cookie name                                                                                  |
+| `cookieHeader` | `string` | (Optional) Raw `Cookie` request header - pass during SSR (e.g. from `useSSRContext()` in Nuxt) |
+
+Returns the URL-decoded value, or `null` when the cookie is absent.
+
+## setCookie
+
+```ts
+import { setCookie } from '@maz-ui/utils'
+
+setCookie('theme', 'dark')
+
+setCookie('session', token, {
+  maxAge: 60 * 60, // 1 hour
+  secure: true,
+  sameSite: 'Strict',
+})
+```
+
+```ts
+function setCookie(key: string, value: string, options?: CookieOptions): void
+```
+
+No-op on the server.
+
+### Options
+
+| Option        | Type      | Default          | Description                                                                       |
+| ------------- | --------- | ---------------- | --------------------------------------------------------------------------------- |
+| `path`        | `string`  | `'/'`            | Path attribute. Pass `null` to omit.                                              |
+| `domain`      | `string`  | - | Domain attribute.                                                                 |
+| `maxAge`      | `number`  | `31_536_000` (1y) | Lifetime in seconds. Pass `null` for a session cookie.                            |
+| `expires`     | `Date`    | - | Explicit expiration date. Takes precedence over `maxAge`.                         |
+| `secure`      | `boolean` | - | Restrict to HTTPS.                                                                |
+| `sameSite`    | `'Lax' \| 'Strict' \| 'None'` | `'Lax'` | Same-site policy. Pass `null` to omit.                                            |
+| `partitioned` | `boolean` | - | Mark the cookie as partitioned (CHIPS).                                           |
+
+**Warning: `HttpOnly`**
+
+`HttpOnly` cannot be set from `document.cookie` - browsers reject it. Use a server-set cookie for that.
+
+## deleteCookie
+
+```ts
+import { deleteCookie } from '@maz-ui/utils'
+
+deleteCookie('session')
+deleteCookie('analytics-id', { domain: '.example.com' })
+```
+
+```ts
+function deleteCookie(key: string, options?: Pick<CookieOptions, 'path' | 'domain'>): void
+```
+
+For the deletion to take effect, `path` and `domain` must match the values used when the cookie was set.

package/docs/ecosystem/utils/country-code-to-unicode-flag.md

@@ -0,0 +1,128 @@
+---
+title: "country-code-to-unicode-flag"
+description: "Convert country code in unicode flag"
+package: "@maz-ui/utils"
+url: "https://maz-ui.com/ecosystem/utils/country-code-to-unicode-flag"
+---
+
+# country-code-to-unicode-flag
+
+> Convert country code in unicode flag
+
+- Package: `@maz-ui/utils`
+- Import: `import { countryCodeToUnicodeFlag } from '@maz-ui/utils/helpers/countryCodeToUnicodeFlag'`
+- Web: https://maz-ui.com/ecosystem/utils/country-code-to-unicode-flag
+
+**Warning:**
+
+  This feature does not work with Windows but you can use this polyfill: [https://www.npmjs.com/package/country-flag-emoji-polyfill](https://www.npmjs.com/package/country-flag-emoji-polyfill)
+
+  Use can also use [get-country-flag-url](./get-country-flag-url.md) instead.
+
+## Basic usage
+
+```vue
+<template>
+  <span style="font-size: 2rem;">
+    {{ unicodeFlag }}
+  </span>
+</template>
+
+<script lang="ts" setup >
+  import { countryCodeToUnicodeFlag } from '@maz-ui/utils'
+
+  const unicodeFlag = countryCodeToUnicodeFlag('FR')
+</script>
+```
+
+## Example
+
+**Details: Show full code**
+
+```vue
+
+<template>
+  <div class="gap-2 flex flex-wrap items-center">
+    <span class="text-xs">{{ flag }}</span>
+    <span class="text-sm">{{ flag }}</span>
+    <span class="text-base">{{ flag }}</span>
+    <span class="text-lg">{{ flag }}</span>
+    <span class="text-xl">{{ flag }}</span>
+    <span class="text-2xl">{{ flag }}</span>
+    <span class="text-3xl">{{ flag }}</span>
+    <span class="text-4xl">{{ flag }}</span>
+    <span class="text-5xl">{{ flag }}</span>
+    <span class="text-6xl">{{ flag }}</span>
+    <span class="text-7xl">{{ flag }}</span>
+  </div>
+
+  <MazSelect
+    v-model="countryCode"
+    :options="countryOptions"
+    label="Select country"
+    search
+    search-placeholder="Search country"
+    @selected-option="(option) => console.log('option', option)"
+  >
+    <template #default="{ option, isSelected }">
+      <div
+        class="flex items-center gap-3"
+      >
+        <span class="text-lg">
+          {{ option.unicodeFlag }}
+        </span>
+        <MazBadge
+          pastel
+          size="0.7rem"
+          class="w-9"
+          :class="{ 'text-muted': !isSelected }"
+        >
+          {{ option.value }}
+        </MazBadge>
+        <span :class="{ 'font-semibold': isSelected }">
+          {{ option.label }}
+        </span>
+      </div>
+    </template>
+  </MazSelect>
+</template>
+
+<script lang="ts" setup>
+  import { computed, ref, onMounted } from 'vue'
+  import { countryCodeToUnicodeFlag } from '@maz-ui/utils'
+  import { getCountries } from 'libphonenumber-js'
+
+  const countryCode = ref('FR')
+  const flag = computed(() => countryCodeToUnicodeFlag(countryCode.value))
+
+  const countryOptions = ref(getCountriesList())
+
+  onMounted(() => {
+    const listOfCountries = getCountriesList(window.navigator.language)
+    if (listOfCountries.length > 1) {
+      countryOptions.value = listOfCountries
+    }
+  })
+
+  function getCountriesList(
+    locale?: string,
+  ) {
+    const countriesList = []
+    const isoList = getCountries()
+
+    for (const iso2 of isoList) {
+      const name = new Intl.DisplayNames([locale ?? 'en-US'], { type: 'region' }).of(iso2)
+
+      if (name) {
+        countriesList.push({
+          value: iso2,
+          label: name,
+          unicodeFlag: countryCodeToUnicodeFlag(iso2)
+        })
+      }
+    }
+
+    return countriesList
+  }
+</script>
+```

package/docs/ecosystem/utils/currency.md

@@ -0,0 +1,53 @@
+---
+title: "formatCurrency"
+description: "The module formatCurrency is a function that formats numbers to currency with the native api [Intl.NumberFormat](https://developer.mozilla.org/fr/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat) from browsers and Node.js"
+package: "@maz-ui/utils"
+url: "https://maz-ui.com/ecosystem/utils/currency"
+---
+
+# formatCurrency
+
+> The module formatCurrency is a function that formats numbers to currency with the native api [Intl.NumberFormat](https://developer.mozilla.org/fr/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat) from browsers and Node.js
+
+- Package: `@maz-ui/utils`
+- Import: `import { formatCurrency } from '@maz-ui/utils/helpers/formatCurrency'`
+- Web: https://maz-ui.com/ecosystem/utils/currency
+
+**Tip:**
+
+This module uses the native api [Intl.NumberFormat](https://developer.mozilla.org/fr/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat) from browsers
+
+Enter only numbers
+
+```vue
+<script lang="ts" setup>
+import { formatCurrency } from '@maz-ui/utils'
+import { computed, ref } from 'vue'
+
+const numberValue = ref(69)
+
+const priceFormatted = computed(() =>
+  formatCurrency(numberValue.value, 'fr-FR', { currency: 'EUR' }),
+)
+</script>
+
+<template>
+  <MazInput v-model="numberValue" type="number" />
+
+  <div
+    style="padding: 16px; margin-top: 16px; background-color: var(--maz-surface-300);"
+  >
+    {{ priceFormatted }}
+  </div>
+</template>
+```
+
+## Options
+
+> All options from [Intl.NumberFormat](https://developer.mozilla.org/fr/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat) are availables
+
+```ts
+export interface FilterCurrencyOptions extends Intl.NumberFormatOptions {
+  round?: boolean
+}
+```

package/docs/ecosystem/utils/date.md

@@ -0,0 +1,53 @@
+---
+title: "formatDate"
+description: "The module formatDate is a function that formats dates with the native api [Intl.DateTimeFormat](https://developer.mozilla.org/fr/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat) from browsers and Node.js"
+package: "@maz-ui/utils"
+url: "https://maz-ui.com/ecosystem/utils/date"
+---
+
+# formatDate
+
+> The module formatDate is a function that formats dates with the native api [Intl.DateTimeFormat](https://developer.mozilla.org/fr/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat) from browsers and Node.js
+
+- Package: `@maz-ui/utils`
+- Import: `import { formatDate } from '@maz-ui/utils/helpers/formatDate'`
+- Web: https://maz-ui.com/ecosystem/utils/date
+
+> This module use the native api [Intl.DateTimeFormat](https://developer.mozilla.org/fr/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat) from browsers
+
+```vue
+<script lang="ts" setup>
+import { formatDate } from '@maz-ui/utils'
+import { computed, ref } from 'vue'
+
+const dateValue = ref('2022-02-01')
+
+const dateFormatted = computed(() =>
+  dateValue.value ? formatDate(dateValue.value, 'en-US') : undefined,
+)
+</script>
+
+<template>
+  <MazInput v-model="dateValue" type="date" />
+
+  <div
+    style="padding: 16px; margin-top: 16px; background-color: var(--maz-surface-300);"
+  >
+    {{ dateFormatted }}
+  </div>
+</template>
+```
+
+## Options
+
+> All options from [Intl.DateTimeFormat](https://developer.mozilla.org/fr/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat) are available
+
+## Default options
+
+```ts
+const DEFAULT_OPTIONS: Intl.DateTimeFormatOptions = {
+  month: 'short',
+  day: 'numeric',
+  year: 'numeric',
+}
+```

package/docs/ecosystem/utils/debounce-callback.md

@@ -0,0 +1,44 @@
+---
+title: "debounceCallback"
+description: "Module-scoped one-shot debounce - schedule a callback that gets reset on each new call."
+package: "@maz-ui/utils"
+url: "https://maz-ui.com/ecosystem/utils/debounce-callback"
+---
+
+# debounceCallback
+
+> Module-scoped one-shot debounce - schedule a callback that gets reset on each new call.
+
+- Package: `@maz-ui/utils`
+- Import: `import { debounceCallback } from '@maz-ui/utils/helpers/debounceCallback'`
+- Web: https://maz-ui.com/ecosystem/utils/debounce-callback
+
+Unlike [`debounce`](./debounce.md), which builds a debounced wrapper around a function, `debounceCallback` is a procedural helper: each call schedules a callback after `delay` ms, cancelling any previous pending callback.
+
+**Warning: Shared module state**
+
+`debounceCallback` uses a single module-level timer. All consumers of this function share the same timer slot, so calling it from two unrelated places will cancel each other. Use [`debounceId`](./debounce-id.md) for isolated debounces.
+
+## Usage
+
+```ts
+import { debounceCallback } from '@maz-ui/utils'
+
+debounceCallback(() => {
+  console.log('runs only if no other call happens in the next 300 ms')
+}, 300)
+```
+
+## API
+
+```ts
+function debounceCallback(
+  callback: (...args: unknown[]) => unknown,
+  delay: number,
+): void
+```
+
+| Parameter  | Type       | Description                                |
+| ---------- | ---------- | ------------------------------------------ |
+| `callback` | `Function` | Function to run after the quiet window     |
+| `delay`    | `number`   | Quiet window before firing, in milliseconds |

package/docs/ecosystem/utils/debounce-id.md

@@ -0,0 +1,75 @@
+---
+title: "debounceId"
+description: "Debounce an async function with isolated state per identifier - only the last call resolves, others are cancelled."
+package: "@maz-ui/utils"
+url: "https://maz-ui.com/ecosystem/utils/debounce-id"
+---
+
+# debounceId
+
+> Debounce an async function with isolated state per identifier - only the last call resolves, others are cancelled.
+
+- Package: `@maz-ui/utils`
+- Import: `import { debounceId } from '@maz-ui/utils/helpers/debounceId'`
+- Web: https://maz-ui.com/ecosystem/utils/debounce-id
+
+`debounceId` is the right tool when:
+
+- You need to debounce **async** work and `await` the result.
+- You want **per-key isolation** - debounces for `'search'` shouldn't interfere with debounces for `'autosave'`.
+
+## Usage
+
+```ts
+import { debounceId } from '@maz-ui/utils'
+
+const searchUsers = debounceId(
+  'user-search',
+  async (query: string) => {
+    const res = await fetch(`/api/users?q=${query}`)
+    return res.json()
+  },
+  300,
+)
+
+const users = await searchUsers('alice')
+```
+
+## API
+
+```ts
+function debounceId<T, Args extends unknown[]>(
+  identifier: string,
+  func: (...args: Args) => T | Promise<T>,
+  delay: number,
+): (...args: Args) => Promise<T>
+```
+
+| Parameter    | Type            | Description                                                  |
+| ------------ | --------------- | ------------------------------------------------------------ |
+| `identifier` | `string`        | Unique key - calls with the same key share a debounce timer |
+| `func`       | `Function`      | The async (or sync) function to debounce                     |
+| `delay`      | `number`        | Quiet window before the call resolves, in ms                 |
+
+Returns a function that always returns a `Promise<T>`. Earlier pending promises are cancelled - only the last invocation resolves.
+
+## Examples
+
+Autosave a form, keyed by document ID, so concurrent edits to different documents don't share state:
+
+```ts
+import { debounceId } from '@maz-ui/utils'
+
+async function saveDocument(id: string, payload: unknown) {
+  const save = debounceId(
+    `doc-${id}`,
+    (body: unknown) => fetch(`/docs/${id}`, { method: 'PUT', body: JSON.stringify(body) }),
+    500,
+  )
+  return save(payload)
+}
+```
+
+## Related
+
+- [`throttleId`](./throttle-id.md) - same shape, but throttles instead of debounces.

package/docs/ecosystem/utils/debounce.md

@@ -0,0 +1,71 @@
+---
+title: "debounce"
+description: "Wrap a function so it only runs after a quiet period - every new call resets the timer."
+package: "@maz-ui/utils"
+url: "https://maz-ui.com/ecosystem/utils/debounce"
+---
+
+# debounce
+
+> Wrap a function so it only runs after a quiet period - every new call resets the timer.
+
+- Package: `@maz-ui/utils`
+- Import: `import { debounce } from '@maz-ui/utils/helpers/debounce'`
+- Web: https://maz-ui.com/ecosystem/utils/debounce
+
+Useful for input handlers, resize listeners, search-as-you-type and any callback that should not fire on every event.
+
+## Usage
+
+```ts
+import { debounce } from '@maz-ui/utils'
+
+const onSearch = debounce((query: string) => {
+  console.log('searching for', query)
+}, 300)
+
+onSearch('h')
+onSearch('he')
+onSearch('hel')
+// only the last call (with "hel") runs, 300 ms after the third call
+```
+
+## API
+
+```ts
+function debounce<F extends (...args: any[]) => any>(
+  fn: F,
+  delay: number,
+): (...args: Parameters<F>) => void
+```
+
+| Parameter | Type       | Description                                   |
+| --------- | ---------- | --------------------------------------------- |
+| `fn`      | `Function` | The function to debounce                      |
+| `delay`   | `number`   | Quiet window in milliseconds before `fn` runs |
+
+The returned function shares no state with other debounced wrappers - each call to `debounce()` creates a fresh timer.
+
+## Examples
+
+Debounce a Vue input handler:
+
+```vue
+<script setup lang="ts">
+import { debounce } from '@maz-ui/utils'
+
+const onInput = debounce((event: Event) => {
+  console.log((event.target as HTMLInputElement).value)
+}, 250)
+</script>
+
+<template>
+  <input @input="onInput">
+</template>
+```
+
+## Related
+
+- [`debounceId`](./debounce-id.md) - debounce an async function, keyed by an identifier, returning a promise.
+- [`debounceCallback`](./debounce-callback.md) - module-scoped one-shot debounce.
+- [`throttle`](./throttle.md) - rate-limits instead of waiting for silence.