@maz-ui/mcp 5.0.0-beta.17 → 5.0.0-beta.18

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.

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

@@ -0,0 +1,60 @@
+---
+title: '@maz-ui/utils'
+description: Lightweight, tree-shakeable utility functions and TypeScript helpers for Vue, Nuxt and any JavaScript/TypeScript project.
+---
+
+# {{ $frontmatter.title }}
+
+{{ $frontmatter.description }}
+
+<NpmBadge package="@maz-ui/utils" />
+
+`@maz-ui/utils` ships the runtime helpers and TypeScript type utilities that power maz-ui internally, packaged as a standalone, framework-agnostic library. No Vue dependency, no global side effects — just import what you need.
+
+## Installation
+
+::: code-group
+
+```bash [pnpm]
+pnpm add @maz-ui/utils
+```
+
+```bash [npm]
+npm install @maz-ui/utils
+```
+
+```bash [yarn]
+yarn add @maz-ui/utils
+```
+
+:::
+
+## Basic usage
+
+```ts
+import { debounce, formatCurrency, sleep } from '@maz-ui/utils'
+
+const debounced = debounce(() => console.log('typed'), 300)
+
+const price = formatCurrency(1999.9, 'fr-FR', { currency: 'EUR' })
+
+await sleep(500)
+```
+
+## What's inside
+
+<UtilsCatalogue />
+
+## Tree-shaking
+
+The package is published with `"sideEffects": false`. Named imports — `import { sleep } from '@maz-ui/utils'` — are statically analysed by Vite, Rollup, esbuild and webpack: any helper you don't reference is dropped from your bundle.
+
+For granular bundling you can also import a single helper through its dedicated subpath:
+
+```ts
+import { sleep } from '@maz-ui/utils/helpers/sleep'
+```
+
+## TypeScript helpers
+
+Beyond runtime utilities, `@maz-ui/utils` also exports a set of generic type helpers (`DeepPartial`, `DeepKeyOf`, `FlattenObjectKeys`, …) under `@maz-ui/utils/ts-helpers`. See the **TypeScript Helpers** section in the sidebar.

package/docs/src/ecosystem/utils/is-client.md

@@ -0,0 +1,32 @@
+---
+title: isClient
+description: Check whether the code is running in a browser environment (has a `document`).
+---
+
+# {{ $frontmatter.title }}
+
+{{ $frontmatter.description }}
+
+## Usage
+
+```ts
+import { isClient } from '@maz-ui/utils'
+
+if (isClient()) {
+  document.body.classList.add('hydrated')
+}
+```
+
+## API
+
+```ts
+function isClient(): boolean
+```
+
+Returns `true` if `document` is defined, `false` otherwise (e.g. SSR, Node.js, Web Workers).
+
+## Notes
+
+- The opposite is [`isServer`](./is-server).
+- Implemented as a one-liner: `typeof document !== 'undefined'`.
+- Prefer this over checking `process.client` (Nuxt) or `import.meta.env.SSR` (Vite) when you want a framework-agnostic check.

package/docs/src/ecosystem/utils/is-equal.md

@@ -0,0 +1,38 @@
+---
+title: isEqual
+description: Deep structural equality check for primitives, arrays, plain objects and Dates.
+---
+
+# {{ $frontmatter.title }}
+
+{{ $frontmatter.description }}
+
+## Usage
+
+```ts
+import { isEqual } from '@maz-ui/utils'
+
+isEqual({ a: 1, b: [2, 3] }, { a: 1, b: [2, 3] }) // true
+isEqual([1, 2, 3], [1, 2, 3]) // true
+isEqual(new Date('2024-01-01'), new Date('2024-01-01')) // true
+isEqual({ a: 1 }, { a: 1, b: 2 }) // false
+```
+
+## API
+
+```ts
+function isEqual(a: unknown, b: unknown): boolean
+```
+
+| Parameter | Type      | Description       |
+| --------- | --------- | ----------------- |
+| `a`       | `unknown` | First value       |
+| `b`       | `unknown` | Second value      |
+
+## Behaviour
+
+- **Primitives** (`null`, `undefined`, `string`, `number`, `boolean`, `symbol`, `bigint`) — compared with `===`.
+- **Dates** — compared by `getTime()`.
+- **Arrays** — same length and every element deeply equal.
+- **Plain objects** — same set of keys and every value deeply equal.
+- **Anything else** (Maps, Sets, class instances, functions) is not specifically handled; comparisons fall back to `===`.

package/docs/src/ecosystem/utils/is-server.md

@@ -0,0 +1,31 @@
+---
+title: isServer
+description: Check whether the code is running on the server (no `window` or `document`).
+---
+
+# {{ $frontmatter.title }}
+
+{{ $frontmatter.description }}
+
+## Usage
+
+```ts
+import { isServer } from '@maz-ui/utils'
+
+if (isServer()) {
+  return placeholder
+}
+```
+
+## API
+
+```ts
+function isServer(): boolean
+```
+
+Returns `true` when either `document` or `window` is undefined — covers Node.js, Bun, Deno, Edge runtimes and Web Workers.
+
+## Notes
+
+- The opposite is [`isClient`](./is-client).
+- Useful for guarding `window`-dependent code from SSR errors.

package/docs/src/ecosystem/utils/is-standalone-mode.md

@@ -0,0 +1,43 @@
+---
+title: isStandaloneMode
+description: Check whether the app is running as an installed Progressive Web App (PWA) rather than inside a browser tab.
+---
+
+# {{ $frontmatter.title }}
+
+{{ $frontmatter.description }}
+
+## Usage
+
+```ts
+import { isStandaloneMode } from '@maz-ui/utils'
+
+if (isStandaloneMode()) {
+  console.log('Running as installed PWA')
+}
+```
+
+## API
+
+```ts
+function isStandaloneMode(): boolean
+```
+
+Returns `true` if the page is rendered in standalone display mode, `false` otherwise (including during SSR).
+
+## Detection rules
+
+The check returns `true` when **either**:
+
+- `window.matchMedia('(display-mode: standalone)').matches` — covers Chrome, Edge, Firefox, etc.
+- `navigator.standalone` is truthy — iOS Safari's legacy property.
+
+## Examples
+
+Hide install prompts when already installed:
+
+```ts
+if (!isStandaloneMode()) {
+  showInstallBanner()
+}
+```

package/docs/src/ecosystem/utils/kebab-case.md

@@ -0,0 +1,36 @@
+---
+title: kebabCase
+description: Convert any common string casing to kebab-case — handles camelCase, PascalCase, snake_case, spaces and consecutive capitals.
+---
+
+# {{ $frontmatter.title }}
+
+{{ $frontmatter.description }}
+
+## Usage
+
+```ts
+import { kebabCase } from '@maz-ui/utils'
+
+kebabCase('myComponent') // → 'my-component'
+kebabCase('MyComponent') // → 'my-component'
+kebabCase('XMLParser') // → 'xml-parser'
+kebabCase('hello_world') // → 'hello-world'
+kebabCase('hello world') // → 'hello-world'
+```
+
+## API
+
+```ts
+function kebabCase(str: string): string
+```
+
+| Parameter | Type     | Description           |
+| --------- | -------- | --------------------- |
+| `str`     | `string` | The string to convert |
+
+## Notes
+
+- Consecutive uppercase letters are handled (e.g. `XMLParser` → `xml-parser`).
+- Leading and trailing dashes are stripped.
+- Multiple separators collapse into a single dash.