@maz-ui/mcp 5.0.0-beta.3 → 5.0.0-beta.30

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.

package/docs/src/ecosystem/utils/normalize-string.md

@@ -0,0 +1,77 @@
+---
+title: normalizeString
+description: Powerful string normalizer — strip accents, normalize whitespace, remove special characters, change case, and apply Unicode normalization forms.
+---
+
+# {{ $frontmatter.title }}
+
+{{ $frontmatter.description }}
+
+The Swiss-army knife for turning user input into a safe, comparable, slug-ready string.
+
+## Usage
+
+```ts
+import { normalizeString } from '@maz-ui/utils'
+
+normalizeString('  Crème Brûlée  ')
+// → 'creme-brulee'
+
+normalizeString('Élégant Café', { case: 'kebab-case' })
+// → 'elegant-cafe'
+
+normalizeString('My Article Title!', {
+  case: 'kebab-case',
+  removeSpecialCharacters: true,
+})
+// → 'my-article-title'
+```
+
+## API
+
+```ts
+function normalizeString(
+  input: string | number | boolean,
+  options?: NormalizeStringOptions,
+): string
+```
+
+### Options
+
+| Option                     | Type         | Default            | Description                                                                                  |
+| -------------------------- | ------------ | ------------------ | -------------------------------------------------------------------------------------------- |
+| `removeAccents`            | `boolean`    | `true`             | Strip diacritics (`é → e`, `ç → c`, …)                                                       |
+| `caseSensitive`            | `boolean`    | `false`            | When `false`, lowercases the result unless `case` is set                                     |
+| `replaceSpaces`            | `boolean`    | `true`             | Replace spaces with `-`                                                                      |
+| `removeSpecialCharacters`  | `boolean`    | `false`            | Strip non-alphanumeric / non-dash characters (Latin alphabet only)                           |
+| `trim`                     | `boolean`    | `true`             | Trim leading/trailing whitespace                                                             |
+| `normalizeSpaces`          | `boolean`    | `true`             | Collapse runs of whitespace into a single space                                              |
+| `removeNumbers`            | `boolean`    | `false`            | Strip digits                                                                                 |
+| `case`                     | `CaseFormat` | `undefined`        | Force a target case: `kebab-case`, `camelCase`, `PascalCase`, `snake_case`, `lowercase`, `UPPERCASE` |
+| `customNormalizationForms` | `string[]`   | `['NFC', 'NFKD']`  | Unicode [normalization forms](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String/normalize) applied at the end |
+
+## Examples
+
+Generate a URL-safe slug:
+
+```ts
+const slug = normalizeString(post.title, {
+  case: 'kebab-case',
+  removeSpecialCharacters: true,
+})
+```
+
+Build a case-insensitive comparison key:
+
+```ts
+const a = normalizeString('Éléphant')
+const b = normalizeString('elephant')
+a === b // true
+```
+
+Preserve original casing but strip diacritics:
+
+```ts
+normalizeString('Crème Brûlée', { caseSensitive: true, replaceSpaces: false })
+// → 'Creme Brulee'
+```

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

@@ -12,7 +12,7 @@ description: The module formatNumber is a function that formats numbers with the
 <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="maz:flex maz:flex-center maz:rounded-md maz:gap-0.5"
 >
   formatted value: <strong>{{ numberFormatted }}</strong>
@@ -34,7 +34,7 @@ const numberFormatted = 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);"
   >
     {{ numberFormatted }}
   </div>

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

@@ -0,0 +1,35 @@
+---
+title: pascalCase
+description: Convert any common string casing — kebab, snake, space-separated, camelCase or UPPERCASE — to PascalCase.
+---
+
+# {{ $frontmatter.title }}
+
+{{ $frontmatter.description }}
+
+## Usage
+
+```ts
+import { pascalCase } from '@maz-ui/utils'
+
+pascalCase('my-component-name') // → 'MyComponentName'
+pascalCase('hello_world') // → 'HelloWorld'
+pascalCase('hello world') // → 'HelloWorld'
+pascalCase('helloWorld') // → 'HelloWorld'
+```
+
+## API
+
+```ts
+function pascalCase(str: string): string
+```
+
+| Parameter | Type     | Description           |
+| --------- | -------- | --------------------- |
+| `str`     | `string` | The string to convert |
+
+## Notes
+
+- Detects `-`, `_` and space separators automatically.
+- Handles ALL-CAPS inputs by lowercasing before re-capitalizing.
+- For fine-grained control, use [`normalizeString`](./normalize-string) with `{ case: 'PascalCase' }`.

package/docs/src/ecosystem/utils/script-loader.md

@@ -0,0 +1,77 @@
+---
+title: ScriptLoader
+description: Class to inject and cache a <script> tag in document head, with an awaitable load promise — ideal for third-party SDKs.
+---
+
+# {{ $frontmatter.title }}
+
+{{ $frontmatter.description }}
+
+`ScriptLoader` handles deduplication (won't inject the same script twice), error reporting, and optional one-time loading semantics.
+
+## Usage
+
+```ts
+import { ScriptLoader } from '@maz-ui/utils'
+
+const loader = new ScriptLoader({
+  identifier: 'stripe-js',
+  src: 'https://js.stripe.com/v3/',
+})
+
+await loader.load()
+// window.Stripe is now available
+```
+
+## API
+
+```ts
+class ScriptLoader {
+  constructor(options: ScriptLoaderOptions)
+  load(): Promise<Event | undefined>
+  removeTag(tag: Element | string): void
+}
+
+interface ScriptLoaderOptions {
+  identifier: string
+  src: string
+  once?: boolean   // default: true
+  async?: boolean  // default: true
+  defer?: boolean  // default: true
+}
+```
+
+| Option       | Type      | Default | Description                                                                  |
+| ------------ | --------- | ------- | ---------------------------------------------------------------------------- |
+| `identifier` | `string`  | —       | Unique key used to deduplicate the script across calls (set as `data-identifier`) |
+| `src`        | `string`  | —       | Script URL                                                                   |
+| `once`       | `boolean` | `true`  | When `true`, skip injection if a script with the same identifier already loaded |
+| `async`      | `boolean` | `true`  | Sets the `async` attribute on the `<script>` tag                             |
+| `defer`      | `boolean` | `true`  | Sets the `defer` attribute on the `<script>` tag                             |
+
+### Methods
+
+- **`load()`** — Inject the script (or resolve immediately if cached) and return a promise that resolves to the load `Event` once the script is ready.
+- **`removeTag(tag)`** — Remove an injected `<script>` tag by element reference or identifier string.
+
+## Errors
+
+`ScriptLoader` throws synchronously in two situations:
+
+- `src` or `identifier` is missing.
+- Called in a non-browser environment (no `window` available).
+
+## Examples
+
+Reload a script on demand by disabling caching:
+
+```ts
+const loader = new ScriptLoader({
+  identifier: 'my-widget',
+  src: '/widget.js',
+  once: false,
+})
+
+await loader.load() // first injection
+await loader.load() // previous tag removed, new one injected
+```

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

@@ -0,0 +1,59 @@
+---
+title: sleep
+description: Pause execution for a given number of milliseconds. Returns a promise that resolves after the delay.
+---
+
+# {{ $frontmatter.title }}
+
+{{ $frontmatter.description }}
+
+## Usage
+
+```ts
+import { sleep } from '@maz-ui/utils'
+
+await sleep(500)
+console.log('Half a second later')
+```
+
+## API
+
+```ts
+function sleep(duration: number): Promise<void>
+```
+
+| Parameter  | Type     | Description           |
+| ---------- | -------- | --------------------- |
+| `duration` | `number` | Delay in milliseconds |
+
+Returns a `Promise<void>` that resolves once the delay elapses.
+
+## Examples
+
+Chain delays in a sequence:
+
+```ts
+async function rampUp() {
+  console.log('Starting')
+  await sleep(1000)
+  console.log('1s later')
+  await sleep(2000)
+  console.log('3s later')
+}
+```
+
+Use as a guard between retries with exponential backoff:
+
+```ts
+async function withRetry(task: () => Promise<void>, attempts = 3) {
+  for (let i = 0; i < attempts; i++) {
+    try {
+      return await task()
+    }
+    catch {
+      await sleep(2 ** i * 100)
+    }
+  }
+  throw new Error('Max retries exceeded')
+}
+```

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

@@ -0,0 +1,36 @@
+---
+title: snakeCase
+description: Convert any common string casing to snake_case — handles camelCase, PascalCase, kebab-case, spaces and consecutive capitals.
+---
+
+# {{ $frontmatter.title }}
+
+{{ $frontmatter.description }}
+
+## Usage
+
+```ts
+import { snakeCase } from '@maz-ui/utils'
+
+snakeCase('myComponent') // → 'my_component'
+snakeCase('MyComponent') // → 'my_component'
+snakeCase('XMLParser') // → 'xml_parser'
+snakeCase('hello-world') // → 'hello_world'
+snakeCase('hello world') // → 'hello_world'
+```
+
+## API
+
+```ts
+function snakeCase(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 underscores are stripped.
+- Multiple separators collapse into a single underscore.

package/docs/src/ecosystem/utils/swipe-handler.md

@@ -0,0 +1,91 @@
+---
+title: Swipe
+description: Detect directional touch swipes on an element with configurable threshold and optional mouse-wheel guards.
+---
+
+# {{ $frontmatter.title }}
+
+{{ $frontmatter.description }}
+
+`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.
+
+## Usage
+
+```ts
+import { Swipe } from '@maz-ui/utils'
+
+const swipe = new Swipe({
+  element: '#carousel',
+  immediate: true,
+  onLeft: () => carousel.next(),
+  onRight: () => carousel.prev(),
+})
+
+// later
+swipe.stop()
+```
+
+## API
+
+```ts
+class Swipe {
+  constructor(options: SwipeOptions)
+
+  start(element?: HTMLElement | string | null): void
+  stop(): void
+
+  xStart?: number
+  yStart?: number
+  xEnd?: number
+  yEnd?: number
+  xDiff?: number
+  yDiff?: number
+}
+```
+
+### Options
+
+| Option                       | Type                                | Default | Description                                                                |
+| ---------------------------- | ----------------------------------- | ------- | -------------------------------------------------------------------------- |
+| `element`                    | `HTMLElement \| string \| null`     | `null`  | Target element or CSS selector.                                            |
+| `threshold`                  | `number`                            | `50`    | Minimum distance in px before a swipe is recognised.                       |
+| `onLeft` / `onRight` / `onUp` / `onDown` | `(event: TouchEvent) => void`       | —       | Direction callbacks.                                                       |
+| `onValuesChanged`            | `(values: SwipeValues) => void`     | —       | Fires whenever start/end/diff values are updated — useful for live tracking. |
+| `preventDefaultOnTouchMove`  | `boolean`                           | `false` | Calls `event.preventDefault()` on `touchmove`.                             |
+| `preventDefaultOnMouseWheel` | `boolean`                           | `false` | Calls `event.preventDefault()` on `mousewheel`.                            |
+| `immediate`                  | `boolean`                           | `false` | Attach listeners immediately from the constructor.                          |
+| `triggerOnEnd`               | `boolean`                           | `false` | Fire direction callbacks on `touchend` instead of on every `touchmove`.    |
+
+### Methods
+
+- **`start(element?)`** — Begin listening. Optionally re-target a new element.
+- **`stop()`** — Detach all listeners. Live values reset.
+
+## Examples
+
+Slide-based gallery:
+
+```ts
+new Swipe({
+  element: '.gallery',
+  immediate: true,
+  threshold: 80,
+  triggerOnEnd: true,
+  onLeft: () => gallery.next(),
+  onRight: () => gallery.previous(),
+})
+```
+
+Live progress while dragging:
+
+```ts
+new Swipe({
+  element: '.draggable',
+  immediate: true,
+  onValuesChanged: ({ xDiff }) => {
+    if (typeof xDiff === 'number') {
+      drawer.style.transform = `translateX(${-xDiff}px)`
+    }
+  },
+})
+```

package/docs/src/ecosystem/utils/textarea-autogrow.md

@@ -0,0 +1,41 @@
+---
+title: TextareaAutogrow
+description: Automatically resize a `<textarea>` element to fit its content as the user types or the window resizes.
+---
+
+# {{ $frontmatter.title }}
+
+{{ $frontmatter.description }}
+
+The helper disables manual resize, sets `box-sizing: border-box`, and updates `height` to match `scrollHeight` on input and (debounced) on window resize.
+
+## Usage
+
+```ts
+import { TextareaAutogrow } from '@maz-ui/utils'
+
+const textarea = document.querySelector<HTMLTextAreaElement>('textarea#bio')!
+const autogrow = new TextareaAutogrow(textarea)
+
+// later
+autogrow.disconnect()
+```
+
+## API
+
+```ts
+class TextareaAutogrow {
+  constructor(element: HTMLTextAreaElement)
+  disconnect(): void
+}
+```
+
+| Method         | Description                                                       |
+| -------------- | ----------------------------------------------------------------- |
+| `disconnect()` | Detach the input and resize listeners. The textarea remains styled. |
+
+## Notes
+
+- Listeners are attached on first focus — until then, the textarea is fully styled but the height isn't yet computed.
+- Resize updates are debounced by 200 ms.
+- For a Vue-idiomatic API, see the [`v-fullsize-textarea`](/directives/v-fullsize-textarea) directive.