@maz-ui/mcp 5.0.1-beta.0 → 5.1.0-beta.1

package/docs/{src/ecosystem → ecosystem}/utils/snake-case.md

@@ -1,11 +1,17 @@
 ---
-title: snakeCase
-description: Convert any common string casing to snake_case — handles camelCase, PascalCase, kebab-case, spaces and consecutive capitals.
+title: "snakeCase"
+description: "Convert any common string casing to snake_case - handles camelCase, PascalCase, kebab-case, spaces and consecutive capitals."
+package: "@maz-ui/utils"
+url: "https://maz-ui.com/ecosystem/utils/snake-case"
 ---
 
-# {{ $frontmatter.title }}
+# snakeCase
 
-{{ $frontmatter.description }}
+> Convert any common string casing to snake_case - handles camelCase, PascalCase, kebab-case, spaces and consecutive capitals.
+
+- Package: `@maz-ui/utils`
+- Import: `import { snakeCase } from '@maz-ui/utils/helpers/snakeCase'`
+- Web: https://maz-ui.com/ecosystem/utils/snake-case
 
 ## Usage
 

package/docs/{src/ecosystem → ecosystem}/utils/swipe-handler.md

@@ -1,11 +1,17 @@
 ---
-title: Swipe
-description: Detect directional touch swipes on an element with configurable threshold and optional mouse-wheel guards.
+title: "Swipe"
+description: "Detect directional touch swipes on an element with configurable threshold and optional mouse-wheel guards."
+package: "@maz-ui/utils"
+url: "https://maz-ui.com/ecosystem/utils/swipe-handler"
 ---
 
-# {{ $frontmatter.title }}
+# Swipe
 
-{{ $frontmatter.description }}
+> Detect directional touch swipes on an element with configurable threshold and optional mouse-wheel guards.
+
+- Package: `@maz-ui/utils`
+- Import: `import { Swipe } from '@maz-ui/utils/helpers/swipeHandler'`
+- Web: https://maz-ui.com/ecosystem/utils/swipe-handler
 
 `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.
 
@@ -49,8 +55,8 @@ class Swipe {
 | ---------------------------- | ----------------------------------- | ------- | -------------------------------------------------------------------------- |
 | `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. |
+| `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.                          |
@@ -58,8 +64,8 @@ class Swipe {
 
 ### Methods
 
-- **`start(element?)`** — Begin listening. Optionally re-target a new element.
-- **`stop()`** — Detach all listeners. Live values reset.
+- **`start(element?)`** - Begin listening. Optionally re-target a new element.
+- **`stop()`** - Detach all listeners. Live values reset.
 
 ## Examples
 

package/docs/{src/ecosystem → ecosystem}/utils/textarea-autogrow.md

@@ -1,11 +1,17 @@
 ---
-title: TextareaAutogrow
-description: Automatically resize a `<textarea>` element to fit its content as the user types or the window resizes.
+title: "TextareaAutogrow"
+description: "Automatically resize a `<textarea>` element to fit its content as the user types or the window resizes."
+package: "@maz-ui/utils"
+url: "https://maz-ui.com/ecosystem/utils/textarea-autogrow"
 ---
 
-# {{ $frontmatter.title }}
+# TextareaAutogrow
 
-{{ $frontmatter.description }}
+> Automatically resize a `<textarea>` element to fit its content as the user types or the window resizes.
+
+- Package: `@maz-ui/utils`
+- Import: `import { TextareaAutogrow } from '@maz-ui/utils/helpers/TextareaAutogrow'`
+- Web: https://maz-ui.com/ecosystem/utils/textarea-autogrow
 
 The helper disables manual resize, sets `box-sizing: border-box`, and updates `height` to match `scrollHeight` on input and (debounced) on window resize.
 
@@ -36,6 +42,6 @@ class TextareaAutogrow {
 
 ## Notes
 
-- Listeners are attached on first focus — until then, the textarea is fully styled but the height isn't yet computed.
+- 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.
+- In a Vue app, use [`MazTextarea`](../../components/maz-textarea.md): it grows with its content.

package/docs/{src/ecosystem → ecosystem}/utils/throttle-id.md

@@ -1,13 +1,19 @@
 ---
-title: throttleId
-description: Throttle an async function with isolated state per identifier — runs immediately, then at most once per interval.
+title: "throttleId"
+description: "Throttle an async function with isolated state per identifier - runs immediately, then at most once per interval."
+package: "@maz-ui/utils"
+url: "https://maz-ui.com/ecosystem/utils/throttle-id"
 ---
 
-# {{ $frontmatter.title }}
+# throttleId
 
-{{ $frontmatter.description }}
+> Throttle an async function with isolated state per identifier - runs immediately, then at most once per interval.
 
-`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.
+- Package: `@maz-ui/utils`
+- Import: `import { throttleId } from '@maz-ui/utils/helpers/throttleId'`
+- Web: https://maz-ui.com/ecosystem/utils/throttle-id
+
+`throttleId` is the async, keyed counterpart of [`throttle`](./throttle.md). 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
 
@@ -44,5 +50,5 @@ function throttleId<T, Args extends unknown[]>(
 
 ## Related
 
-- [`debounceId`](./debounce-id) — wait for silence instead of rate-limiting.
-- [`throttle`](./throttle) — non-async, single-instance throttle.
+- [`debounceId`](./debounce-id.md) - wait for silence instead of rate-limiting.
+- [`throttle`](./throttle.md) - non-async, single-instance throttle.

package/docs/{src/ecosystem → ecosystem}/utils/throttle.md

@@ -1,13 +1,19 @@
 ---
-title: throttle
-description: Wrap a function so it runs immediately, then at most once every N milliseconds — perfect for scroll, mousemove and resize handlers.
+title: "throttle"
+description: "Wrap a function so it runs immediately, then at most once every N milliseconds - perfect for scroll, mousemove and resize handlers."
+package: "@maz-ui/utils"
+url: "https://maz-ui.com/ecosystem/utils/throttle"
 ---
 
-# {{ $frontmatter.title }}
+# throttle
 
-{{ $frontmatter.description }}
+> Wrap a function so it runs immediately, then at most once every N milliseconds - perfect for scroll, mousemove and resize handlers.
 
-Unlike [`debounce`](./debounce) — which waits for a quiet period — `throttle` lets the first call through and rate-limits the rest.
+- Package: `@maz-ui/utils`
+- Import: `import { throttle } from '@maz-ui/utils/helpers/throttle'`
+- Web: https://maz-ui.com/ecosystem/utils/throttle
+
+Unlike [`debounce`](./debounce.md) - which waits for a quiet period - `throttle` lets the first call through and rate-limits the rest.
 
 ## Usage
 
@@ -35,7 +41,7 @@ function throttle<T extends (...args: any[]) => any>(
 | `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.
+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
 
@@ -53,5 +59,5 @@ window.addEventListener('resize', onResize)
 
 ## Related
 
-- [`throttleId`](./throttle-id) — per-key throttle for async functions, returning a promise.
-- [`debounce`](./debounce) — fires only once activity stops.
+- [`throttleId`](./throttle-id.md) - per-key throttle for async functions, returning a promise.
+- [`debounce`](./debounce.md) - fires only once activity stops.

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

@@ -0,0 +1,37 @@
+---
+title: "truthyFilter"
+description: "Type guard that filters out falsy values (`false`, `''`, `0`, `null`, `undefined`) while narrowing the TypeScript type."
+package: "@maz-ui/utils"
+url: "https://maz-ui.com/ecosystem/utils/truthy-filter"
+---
+
+# truthyFilter
+
+> Type guard that filters out falsy values (`false`, `''`, `0`, `null`, `undefined`) while narrowing the TypeScript type.
+
+- Package: `@maz-ui/utils`
+- Import: `import { truthyFilter } from '@maz-ui/utils/helpers/truthyFilter'`
+- Web: https://maz-ui.com/ecosystem/utils/truthy-filter
+
+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 → ecosystem}/utils/types/deep-key-of.md

@@ -1,11 +1,17 @@
 ---
-title: DeepKeyOf
-description: Recursively build a union of dot-separated key paths for any nested object type.
+title: "DeepKeyOf"
+description: "Recursively build a union of dot-separated key paths for any nested object type."
+package: "@maz-ui/utils"
+url: "https://maz-ui.com/ecosystem/utils/types/deep-key-of"
 ---
 
-# {{ $frontmatter.title }}
+# DeepKeyOf
 
-{{ $frontmatter.description }}
+> Recursively build a union of dot-separated key paths for any nested object type.
+
+- Package: `@maz-ui/utils`
+- Import: `import type { DeepKeyOf } from '@maz-ui/utils/ts-helpers/DeepKeyOf'`
+- Web: https://maz-ui.com/ecosystem/utils/types/deep-key-of
 
 Use it to type i18n keys, nested form paths, or any string that must reference a leaf of a known object shape.
 
@@ -44,5 +50,5 @@ type DeepKeyOf<T> = T extends object
 
 ## Notes
 
-- Numeric and symbol keys are excluded — only `string`-keyed properties are walked.
+- 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 → ecosystem}/utils/types/deep-partial.md

@@ -1,11 +1,17 @@
 ---
-title: DeepPartial
-description: Recursive variant of TypeScript's `Partial<T>` — every property at every depth becomes optional.
+title: "DeepPartial"
+description: "Recursive variant of TypeScript's `Partial<T>` - every property at every depth becomes optional."
+package: "@maz-ui/utils"
+url: "https://maz-ui.com/ecosystem/utils/types/deep-partial"
 ---
 
-# {{ $frontmatter.title }}
+# DeepPartial
 
-{{ $frontmatter.description }}
+> Recursive variant of TypeScript's `Partial<T>` - every property at every depth becomes optional.
+
+- Package: `@maz-ui/utils`
+- Import: `import type { DeepPartial } from '@maz-ui/utils/ts-helpers/DeepPartial'`
+- Web: https://maz-ui.com/ecosystem/utils/types/deep-partial
 
 ## Usage
 

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

@@ -0,0 +1,45 @@
+---
+title: "DeepRequired"
+description: "Recursive variant of TypeScript's `Required<T>` - strips `?` from every property at every depth."
+package: "@maz-ui/utils"
+url: "https://maz-ui.com/ecosystem/utils/types/deep-required"
+---
+
+# DeepRequired
+
+> Recursive variant of TypeScript's `Required<T>` - strips `?` from every property at every depth.
+
+- Package: `@maz-ui/utils`
+- Import: `import type { DeepRequired } from '@maz-ui/utils/ts-helpers/DeepRequired'`
+- Web: https://maz-ui.com/ecosystem/utils/types/deep-required
+
+The mirror image of [`DeepPartial`](./deep-partial.md). 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]>
+}>
+```

package/docs/ecosystem/utils/types/flatten-object-keys.md

@@ -0,0 +1,50 @@
+---
+title: "FlattenObjectKeys"
+description: "Build a union of dot-separated leaf paths for a nested object, with an optional prefix."
+package: "@maz-ui/utils"
+url: "https://maz-ui.com/ecosystem/utils/types/flatten-object-keys"
+---
+
+# FlattenObjectKeys
+
+> Build a union of dot-separated leaf paths for a nested object, with an optional prefix.
+
+- Package: `@maz-ui/utils`
+- Import: `import type { FlattenObjectKeys } from '@maz-ui/utils/ts-helpers/FlattenObjectKeys'`
+- Web: https://maz-ui.com/ecosystem/utils/types/flatten-object-keys
+
+Similar to [`DeepKeyOf`](./deep-key-of.md) but only yields **leaf** paths (skips intermediate object keys), and accepts a `Prefix` parameter for namespacing.
+
+## Usage
+
+```ts
+import type { FlattenObjectKeys } from '@maz-ui/utils'
+
+interface Config {
+  app: {
+    name: string
+    version: number
+  }
+  debug: boolean
+}
+
+type Leaves = FlattenObjectKeys<Config>
+// → 'app.name' | 'app.version' | 'debug'
+
+type Namespaced = FlattenObjectKeys<Config, 'config.'>
+// → 'config.app.name' | 'config.app.version' | 'config.debug'
+```
+
+## API
+
+```ts
+type FlattenObjectKeys<T extends Record<string, any>, Prefix extends string = ''> = {
+  [K in keyof T]: T[K] extends Record<string, any>
+    ? FlattenObjectKeys<T[K], `${Prefix}${K extends string ? K : ''}.`>
+    : `${Prefix}${K extends string ? K : ''}`
+}[keyof T]
+```
+
+## Notes
+
+- Unlike `DeepKeyOf`, intermediate object keys (e.g. `'app'` in the example) are not included - only the paths that resolve to non-object leaves.

package/docs/{src/ecosystem → ecosystem}/utils/types/generic-instance-type.md

@@ -1,11 +1,17 @@
 ---
-title: GenericInstanceType
-description: Extract the public instance type from a generic Vue component — solves the limitation where `InstanceType<typeof Component>` returns `any` for generic SFCs.
+title: "GenericInstanceType"
+description: "Extract the public instance type from a generic Vue component - solves the limitation where `InstanceType<typeof Component>` returns `any` for generic SFCs."
+package: "@maz-ui/utils"
+url: "https://maz-ui.com/ecosystem/utils/types/generic-instance-type"
 ---
 
-# {{ $frontmatter.title }}
+# GenericInstanceType
 
-{{ $frontmatter.description }}
+> Extract the public instance type from a generic Vue component - solves the limitation where `InstanceType<typeof Component>` returns `any` for generic SFCs.
+
+- Package: `@maz-ui/utils`
+- Import: `import type { GenericInstanceType } from '@maz-ui/utils/ts-helpers/GenericInstanceType'`
+- Web: https://maz-ui.com/ecosystem/utils/types/generic-instance-type
 
 Vue's `InstanceType<typeof Component>` does not work on **generic** components (`<script setup lang="ts" generic="T">`). `GenericInstanceType` walks the type to recover the exposed methods/refs typing.
 

package/docs/{src/ecosystem → ecosystem}/utils/types/infer-maybe-ref.md

@@ -1,11 +1,17 @@
 ---
-title: InferMaybeRef
-description: Unwrap a Vue `Ref<U>` to its inner `U` — leaves non-ref types unchanged.
+title: "InferMaybeRef"
+description: "Unwrap a Vue `Ref<U>` to its inner `U` - leaves non-ref types unchanged."
+package: "@maz-ui/utils"
+url: "https://maz-ui.com/ecosystem/utils/types/infer-maybe-ref"
 ---
 
-# {{ $frontmatter.title }}
+# InferMaybeRef
 
-{{ $frontmatter.description }}
+> Unwrap a Vue `Ref<U>` to its inner `U` - leaves non-ref types unchanged.
+
+- Package: `@maz-ui/utils`
+- Import: `import type { InferMaybeRef } from '@maz-ui/utils/ts-helpers/InferMaybeRef'`
+- Web: https://maz-ui.com/ecosystem/utils/types/infer-maybe-ref
 
 Useful when authoring composables that accept either a plain value or a `Ref`, and you want a unified type for the inner value.
 

package/docs/ecosystem/utils/upper-first.md

@@ -0,0 +1,38 @@
+---
+title: "upperFirst"
+description: "Uppercase the first character of a string and leave the rest unchanged."
+package: "@maz-ui/utils"
+url: "https://maz-ui.com/ecosystem/utils/upper-first"
+---
+
+# upperFirst
+
+> Uppercase the first character of a string and leave the rest unchanged.
+
+- Package: `@maz-ui/utils`
+- Import: `import { upperFirst } from '@maz-ui/utils/helpers/upperFirst'`
+- Web: https://maz-ui.com/ecosystem/utils/upper-first
+
+## Usage
+
+```ts
+import { upperFirst } from '@maz-ui/utils'
+
+upperFirst('hello') // → 'Hello'
+upperFirst('hELLO') // → 'HELLO'
+upperFirst('') // → ''
+```
+
+## API
+
+```ts
+function upperFirst(value: string): string
+```
+
+| Parameter | Type     | Description           |
+| --------- | -------- | --------------------- |
+| `value`   | `string` | The string to process |
+
+## Notes
+
+- Does **not** lowercase the remaining characters - use [`capitalize`](./capitalize.md) for the same behaviour when you control the input shape.

package/docs/{src/ecosystem → ecosystem}/utils/user-visibility.md

@@ -1,13 +1,19 @@
 ---
-title: UserVisibility
-description: Track whether the user is currently looking at the tab using the Page Visibility API, with an optional grace timeout before declaring them away.
+title: "UserVisibility"
+description: "Track whether the user is currently looking at the tab using the Page Visibility API, with an optional grace timeout before declaring them away."
+package: "@maz-ui/utils"
+url: "https://maz-ui.com/ecosystem/utils/user-visibility"
 ---
 
-# {{ $frontmatter.title }}
+# UserVisibility
 
-{{ $frontmatter.description }}
+> Track whether the user is currently looking at the tab using the Page Visibility API, with an optional grace timeout before declaring them away.
 
-`UserVisibility` listens to `visibilitychange` events. When the tab becomes hidden, it waits `timeout` ms before invoking the callback with `isVisible: false` — this avoids spurious switches when the user briefly tabs away.
+- Package: `@maz-ui/utils`
+- Import: `import { UserVisibility } from '@maz-ui/utils/helpers/userVisibility'`
+- Web: https://maz-ui.com/ecosystem/utils/user-visibility
+
+`UserVisibility` listens to `visibilitychange` events. When the tab becomes hidden, it waits `timeout` ms before invoking the callback with `isVisible: false` - this avoids spurious switches when the user briefly tabs away.
 
 ## Usage
 
@@ -66,4 +72,4 @@ new UserVisibility(
 
 ## Related
 
-- [`IdleTimeout`](./idle-timeout) — track in-page activity instead of tab visibility.
+- [`IdleTimeout`](./idle-timeout.md) - track in-page activity instead of tab visibility.