@maz-ui/mcp 5.0.0-beta.2 → 5.0.0-beta.24

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

@@ -0,0 +1,79 @@
+---
+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.
+---
+
+# {{ $frontmatter.title }}
+
+{{ $frontmatter.description }}
+
+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/src/ecosystem/utils/cookie.md

@@ -0,0 +1,80 @@
+---
+title: cookie
+description: Read, write and delete browser cookies with full attribute support — `path`, `domain`, `maxAge`, `expires`, `secure`, `sameSite`, `partitioned`.
+---
+
+# {{ $frontmatter.title }}
+
+{{ $frontmatter.description }}
+
+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/src/{helpers → ecosystem/utils}/currency.md

@@ -16,7 +16,7 @@ Enter only numbers
 <MazInput v-model="numberValue" type="number" />
 
 <div
-  style="padding: 16px; margin-top: 16px; background-color: var(--maz-surface-300);"
+  style="padding: 16px; margin-top: 16px; background-color: var(--maz-color-surface-300);"
   class="flex flex-center rounded gap-05"
 >
   formatted value: <strong>{{ priceFormatted }}</strong>
@@ -38,7 +38,7 @@ const priceFormatted = computed(() =>
   <MazInput v-model="numberValue" type="number" />
 
   <div
-    style="padding: 16px; margin-top: 16px; background-color: var(--maz-surface-300);"
+    style="padding: 16px; margin-top: 16px; background-color: var(--maz-color-surface-300);"
   >
     {{ priceFormatted }}
   </div>

package/docs/src/{helpers → ecosystem/utils}/date.md

@@ -12,7 +12,7 @@ description: The module formatDate is a function that formats dates with the nat
 <MazInput v-model="dateValue" type="date" />
 
 <div
-  style="padding: 16px; margin-top: 16px; background-color: var(--maz-surface-300);"
+  style="padding: 16px; margin-top: 16px; background-color: var(--maz-color-surface-300);"
   class="flex flex-center rounded gap-05"
 >
   formatted value: <strong>{{ dateFormatted }}</strong>
@@ -34,7 +34,7 @@ const dateFormatted = computed(() =>
   <MazInput v-model="dateValue" type="date" />
 
   <div
-    style="padding: 16px; margin-top: 16px; background-color: var(--maz-surface-300);"
+    style="padding: 16px; margin-top: 16px; background-color: var(--maz-color-surface-300);"
   >
     {{ dateFormatted }}
   </div>

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

@@ -0,0 +1,38 @@
+---
+title: debounceCallback
+description: Module-scoped one-shot debounce — schedule a callback that gets reset on each new call.
+---
+
+# {{ $frontmatter.title }}
+
+{{ $frontmatter.description }}
+
+Unlike [`debounce`](./debounce), 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) 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/src/ecosystem/utils/debounce-id.md

@@ -0,0 +1,69 @@
+---
+title: debounceId
+description: Debounce an async function with isolated state per identifier — only the last call resolves, others are cancelled.
+---
+
+# {{ $frontmatter.title }}
+
+{{ $frontmatter.description }}
+
+`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) — same shape, but throttles instead of debounces.

package/docs/src/ecosystem/utils/debounce.md

@@ -0,0 +1,65 @@
+---
+title: debounce
+description: Wrap a function so it only runs after a quiet period — every new call resets the timer.
+---
+
+# {{ $frontmatter.title }}
+
+{{ $frontmatter.description }}
+
+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) — debounce an async function, keyed by an identifier, returning a promise.
+- [`debounceCallback`](./debounce-callback) — module-scoped one-shot debounce.
+- [`throttle`](./throttle) — rate-limits instead of waiting for silence.

package/docs/src/ecosystem/utils/fetch-locale-ip.md

@@ -0,0 +1,33 @@
+---
+title: fetchLocaleIp
+description: Resolve the visitor's ISO country code from their IP address using the free `ipwho.is` service.
+---
+
+# {{ $frontmatter.title }}
+
+{{ $frontmatter.description }}
+
+Useful for pre-filling locale-aware UI — phone-number country selectors, currency hints, default language — before the user has interacted with the page.
+
+## Usage
+
+```ts
+import { fetchLocaleIp } from '@maz-ui/utils'
+
+const countryCode = await fetchLocaleIp()
+// 'FR' | 'US' | …  or undefined if the request fails
+```
+
+## API
+
+```ts
+function fetchLocaleIp(): Promise<string | undefined>
+```
+
+Returns the ISO 3166-1 alpha-2 country code (e.g. `'FR'`), or `undefined` if the request fails. Errors are caught and logged via `console.error` — the call never throws.
+
+## Notes
+
+- Hits `https://ipwho.is` — a public, no-key service. Consider rate limits and privacy for production usage.
+- Returns `undefined` rather than throwing so a fallback path (default locale, manual selection) can be wired without `try/catch`.
+- For a static locale source, see [`getBrowserLocale`](./get-browser-locale).

package/docs/src/ecosystem/utils/format-json.md

@@ -0,0 +1,33 @@
+---
+title: formatJson
+description: Tiny wrapper around `JSON.stringify` with sensible default indentation.
+---
+
+# {{ $frontmatter.title }}
+
+{{ $frontmatter.description }}
+
+## Usage
+
+```ts
+import { formatJson } from '@maz-ui/utils'
+
+formatJson({ name: 'Alice', age: 30 })
+// {
+//   "name": "Alice",
+//   "age": 30
+// }
+
+formatJson({ a: 1 }, 4) // → indent with 4 spaces
+```
+
+## API
+
+```ts
+function formatJson(json: unknown, indent?: number): string
+```
+
+| Parameter | Type      | Default | Description                              |
+| --------- | --------- | ------- | ---------------------------------------- |
+| `json`    | `unknown` | —       | Any JSON-serialisable value              |
+| `indent`  | `number`  | `2`     | Number of spaces per indentation level   |

package/docs/src/ecosystem/utils/format-phone-number.md

@@ -0,0 +1,37 @@
+---
+title: formatPhoneNumber
+description: Format an arbitrary phone-number string into its international representation using `libphonenumber-js`.
+---
+
+# {{ $frontmatter.title }}
+
+{{ $frontmatter.description }}
+
+If the input can't be parsed, the original string is returned unchanged.
+
+## Usage
+
+```ts
+import { formatPhoneNumber } from '@maz-ui/utils'
+
+formatPhoneNumber('+33612345678') // → '+33 6 12 34 56 78'
+formatPhoneNumber('0612345678') // → '0612345678' (unparseable without country context — returned as-is)
+```
+
+## API
+
+```ts
+function formatPhoneNumber(phoneNumber: string): string
+```
+
+| Parameter     | Type     | Description                              |
+| ------------- | -------- | ---------------------------------------- |
+| `phoneNumber` | `string` | The phone number to format (E.164 ideal) |
+
+Throws a `TypeError` when `phoneNumber` is empty.
+
+## Notes
+
+- For maximum portability, supply the input in E.164 (`+CCXXXXXXXXX`). Otherwise, parsing falls back to passing the input through unchanged.
+- For interactive phone-number input with country selection, see the [`MazInputPhoneNumber`](/components/maz-input-phone-number) component.
+- Built on [`libphonenumber-js`](https://github.com/catamphetamine/libphonenumber-js).

package/docs/src/ecosystem/utils/get-browser-locale.md

@@ -0,0 +1,29 @@
+---
+title: getBrowserLocale
+description: Read the user's browser language tag (e.g. `'fr-FR'`, `'en-US'`) — returns `undefined` on the server.
+---
+
+# {{ $frontmatter.title }}
+
+{{ $frontmatter.description }}
+
+## Usage
+
+```ts
+import { getBrowserLocale } from '@maz-ui/utils'
+
+const locale = getBrowserLocale() // 'fr-FR' | 'en-US' | … | undefined
+```
+
+## API
+
+```ts
+function getBrowserLocale(): string | undefined
+```
+
+Returns `navigator.language` on the client. On the server (no `navigator`), returns `undefined`.
+
+## Notes
+
+- For IP-based country detection instead of the browser-declared locale, see [`fetchLocaleIp`](./fetch-locale-ip).
+- The returned tag follows [BCP 47](https://www.rfc-editor.org/info/bcp47).

package/docs/src/ecosystem/utils/get-error-message.md

@@ -0,0 +1,39 @@
+---
+title: getErrorMessage
+description: Extract a human-readable message from anything thrown — `Error`, `string`, `{ message }` objects, or arbitrary values.
+---
+
+# {{ $frontmatter.title }}
+
+{{ $frontmatter.description }}
+
+Especially useful inside `catch` blocks where the caught value is typed `unknown`.
+
+## Usage
+
+```ts
+import { getErrorMessage } from '@maz-ui/utils'
+
+try {
+  await doSomething()
+}
+catch (error) {
+  console.error(getErrorMessage(error))
+}
+```
+
+## API
+
+```ts
+function getErrorMessage(error: unknown): string
+```
+
+## Resolution rules
+
+The helper inspects `error` in this order:
+
+1. `error instanceof Error` → returns `error.message`.
+2. `typeof error === 'string'` → returns `error` as-is.
+3. `error` is a plain object with a `message` property → returns `String(error.message)`.
+4. `error` is otherwise truthy → returns `String(error)`.
+5. `error` is falsy → returns `'An unexpected error occurred'`.

package/docs/src/ecosystem/utils/idle-timeout.md

@@ -0,0 +1,90 @@
+---
+title: IdleTimeout
+description: Detect user inactivity (mouse, keyboard, touch, scroll) and run a callback when the user becomes idle.
+---
+
+# {{ $frontmatter.title }}
+
+{{ $frontmatter.description }}
+
+`IdleTimeout` listens for a range of user-input events (`mousedown`, `keydown`, `touchstart`, `wheel`, …) on a target element. When none of them fire for `timeout` ms, the user is considered idle and your callback is invoked.
+
+## Usage
+
+```ts
+import { IdleTimeout } from '@maz-ui/utils'
+
+const watcher = new IdleTimeout(
+  ({ isIdle }) => {
+    if (isIdle) {
+      console.log('User went idle')
+    }
+    else {
+      console.log('User is back')
+    }
+  },
+  { timeout: 60_000 }, // 1 minute
+)
+
+// later
+watcher.destroy()
+```
+
+## API
+
+```ts
+class IdleTimeout {
+  constructor(callback: IdleTimeoutCallback, options?: IdleTimeoutOptions)
+
+  start(): void
+  pause(): void
+  resume(): void
+  reset(): void
+  destroy(): void
+
+  readonly destroyed: boolean
+  idle: boolean
+  timeout: number
+}
+
+type IdleTimeoutCallback = (payload: {
+  isIdle: boolean
+  eventType?: string
+  instance: IdleTimeout
+}) => unknown
+```
+
+### Options
+
+| Option      | Type                       | Default     | Description                                                                            |
+| ----------- | -------------------------- | ----------- | -------------------------------------------------------------------------------------- |
+| `timeout`   | `number`                   | `300_000`   | Idle duration in milliseconds (default 5 minutes).                                    |
+| `element`   | `HTMLElement \| Document`  | `document.body` | Element to attach event listeners to.                                                  |
+| `once`      | `boolean`                  | `false`     | When `true`, automatically calls `destroy()` after the first idle trigger.            |
+| `immediate` | `boolean`                  | `true`      | Fire the callback once on construction. Useful to set `false` in SSR contexts.        |
+
+### Methods
+
+- **`start()`** — Attach listeners and (re)start the timer. The constructor calls this automatically on the client.
+- **`pause()` / `resume()`** — Freeze and unfreeze the countdown without losing the elapsed time.
+- **`reset()`** — Restart the timer from scratch.
+- **`destroy()`** — Detach all listeners. The watcher cannot be reused after destroy.
+
+## Examples
+
+Auto-logout after 10 minutes of inactivity:
+
+```ts
+const idle = new IdleTimeout(
+  ({ isIdle }) => {
+    if (isIdle) {
+      logout()
+    }
+  },
+  { timeout: 10 * 60 * 1000, once: true },
+)
+```
+
+## Related
+
+- [`UserVisibility`](./user-visibility) — track tab focus / visibility instead of in-page activity.