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

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/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.

package/docs/src/ecosystem/utils/throttle-id.md

@@ -0,0 +1,48 @@
+---
+title: throttleId
+description: Throttle an async function with isolated state per identifier — runs immediately, then at most once per interval.
+---
+
+# {{ $frontmatter.title }}
+
+{{ $frontmatter.description }}
+
+`throttleId` is the async, keyed counterpart of [`throttle`](./throttle). 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.
+
+## Usage
+
+```ts
+import { throttleId } from '@maz-ui/utils'
+
+const trackEvent = throttleId(
+  'analytics',
+  async (event: { name: string }) => {
+    return fetch('/track', { method: 'POST', body: JSON.stringify(event) })
+  },
+  1000,
+)
+
+trackEvent({ name: 'scroll' })
+trackEvent({ name: 'scroll' }) // coalesced into the first call
+```
+
+## API
+
+```ts
+function throttleId<T, Args extends unknown[]>(
+  identifier: string,
+  func: (...args: Args) => T | Promise<T>,
+  interval: number,
+): (...args: Args) => Promise<T>
+```
+
+| Parameter    | Type       | Description                                            |
+| ------------ | ---------- | ------------------------------------------------------ |
+| `identifier` | `string`   | Unique key isolating this throttle from others         |
+| `func`       | `Function` | The async (or sync) function to throttle               |
+| `interval`   | `number`   | Minimum interval between executions, in milliseconds   |
+
+## Related
+
+- [`debounceId`](./debounce-id) — wait for silence instead of rate-limiting.
+- [`throttle`](./throttle) — non-async, single-instance throttle.

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

@@ -0,0 +1,57 @@
+---
+title: throttle
+description: Wrap a function so it runs immediately, then at most once every N milliseconds — perfect for scroll, mousemove and resize handlers.
+---
+
+# {{ $frontmatter.title }}
+
+{{ $frontmatter.description }}
+
+Unlike [`debounce`](./debounce) — which waits for a quiet period — `throttle` lets the first call through and rate-limits the rest.
+
+## Usage
+
+```ts
+import { throttle } from '@maz-ui/utils'
+
+const onScroll = throttle(() => {
+  console.log('scroll position', window.scrollY)
+}, 200)
+
+window.addEventListener('scroll', onScroll)
+```
+
+## API
+
+```ts
+function throttle<T extends (...args: any[]) => any>(
+  func: T,
+  limit: number,
+): (...args: Parameters<T>) => void
+```
+
+| Parameter | Type       | Description                                |
+| --------- | ---------- | ------------------------------------------ |
+| `func`    | `Function` | The function to throttle                   |
+| `limit`   | `number`   | Minimum interval between executions, in ms |
+
+The first call always runs immediately. Subsequent calls within `limit` are coalesced — only the most recent set of arguments is replayed once the window elapses.
+
+## Examples
+
+Throttle a window resize handler:
+
+```ts
+import { throttle } from '@maz-ui/utils'
+
+const onResize = throttle(() => {
+  console.log('width:', window.innerWidth)
+}, 250)
+
+window.addEventListener('resize', onResize)
+```
+
+## Related
+
+- [`throttleId`](./throttle-id) — per-key throttle for async functions, returning a promise.
+- [`debounce`](./debounce) — fires only once activity stops.

package/docs/src/ecosystem/utils/truthy-filter.md

@@ -0,0 +1,31 @@
+---
+title: truthyFilter
+description: Type guard that filters out falsy values (`false`, `''`, `0`, `null`, `undefined`) while narrowing the TypeScript type.
+---
+
+# {{ $frontmatter.title }}
+
+{{ $frontmatter.description }}
+
+Pass it directly to `Array.prototype.filter` to drop nullish/empty entries while telling TypeScript the result no longer contains those types.
+
+## Usage
+
+```ts
+import { truthyFilter } from '@maz-ui/utils'
+
+const items: (string | null | undefined)[] = ['a', null, 'b', undefined, '']
+const cleaned = items.filter(truthyFilter)
+// cleaned has type string[]
+// cleaned = ['a', 'b']
+```
+
+## API
+
+```ts
+type Truthy<T> = T extends false | '' | 0 | null | undefined ? never : T
+
+function truthyFilter<T>(value: T): value is Truthy<T>
+```
+
+The function returns `Boolean(value)` — its real value is in the type predicate, which narrows away the falsy variants for downstream type-checking.

package/docs/src/ecosystem/utils/types/deep-key-of.md

@@ -0,0 +1,48 @@
+---
+title: DeepKeyOf
+description: Recursively build a union of dot-separated key paths for any nested object type.
+---
+
+# {{ $frontmatter.title }}
+
+{{ $frontmatter.description }}
+
+Use it to type i18n keys, nested form paths, or any string that must reference a leaf of a known object shape.
+
+## Usage
+
+```ts
+import type { DeepKeyOf } from '@maz-ui/utils'
+
+interface Config {
+  app: {
+    name: string
+    theme: {
+      mode: 'light' | 'dark'
+      primary: string
+    }
+  }
+  version: number
+}
+
+type Keys = DeepKeyOf<Config>
+// → 'app.name' | 'app.theme.mode' | 'app.theme.primary' | 'version'
+```
+
+## API
+
+```ts
+type DeepKeyOf<T> = T extends object
+  ? { [K in keyof T]: K extends string
+      ? T[K] extends object
+        ? `${K}.${DeepKeyOf<T[K]>}`
+        : K
+      : never
+    }[keyof T]
+  : never
+```
+
+## Notes
+
+- Numeric and symbol keys are excluded — only `string`-keyed properties are walked.
+- Array types are objects, so `DeepKeyOf<{ items: string[] }>` produces `'items.0' | 'items.1' | …` only if the array has tuple typing. With a regular `string[]`, the recursion terminates at `'items'`.

package/docs/src/ecosystem/utils/types/deep-partial.md

@@ -0,0 +1,42 @@
+---
+title: DeepPartial
+description: Recursive variant of TypeScript's `Partial<T>` — every property at every depth becomes optional.
+---
+
+# {{ $frontmatter.title }}
+
+{{ $frontmatter.description }}
+
+## Usage
+
+```ts
+import type { DeepPartial } from '@maz-ui/utils'
+
+interface UserSettings {
+  notifications: {
+    email: boolean
+    push: boolean
+  }
+  theme: {
+    primary: string
+    secondary: string
+  }
+}
+
+const update: DeepPartial<UserSettings> = {
+  notifications: { email: false },
+}
+```
+
+## API
+
+```ts
+type DeepPartial<T> = T extends object
+  ? { [P in keyof T]?: DeepPartial<T[P]> }
+  : T
+```
+
+## Notes
+
+- Primitives (`string`, `number`, `boolean`, `null`, `undefined`, …) are returned unchanged.
+- Useful for partial-update payloads (`PATCH` requests, merge functions, default-options patterns).

package/docs/src/ecosystem/utils/types/deep-required.md

@@ -0,0 +1,39 @@
+---
+title: DeepRequired
+description: Recursive variant of TypeScript's `Required<T>` — strips `?` from every property at every depth.
+---
+
+# {{ $frontmatter.title }}
+
+{{ $frontmatter.description }}
+
+The mirror image of [`DeepPartial`](./deep-partial). Useful when you want a fully-resolved internal type derived from a public options interface.
+
+## Usage
+
+```ts
+import type { DeepRequired } from '@maz-ui/utils'
+
+interface Options {
+  cache?: {
+    ttl?: number
+    strategy?: 'memory' | 'disk'
+  }
+}
+
+type ResolvedOptions = DeepRequired<Options>
+// {
+//   cache: {
+//     ttl: number
+//     strategy: 'memory' | 'disk'
+//   }
+// }
+```
+
+## API
+
+```ts
+type DeepRequired<T> = Required<{
+  [K in keyof T]: T[K] extends Required<T[K]> ? T[K] : DeepRequired<T[K]>
+}>
+```