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

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]>
+}>
+```

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

@@ -0,0 +1,44 @@
+---
+title: FlattenObjectKeys
+description: Build a union of dot-separated leaf paths for a nested object, with an optional prefix.
+---
+
+# {{ $frontmatter.title }}
+
+{{ $frontmatter.description }}
+
+Similar to [`DeepKeyOf`](./deep-key-of) 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/utils/types/generic-instance-type.md

@@ -0,0 +1,42 @@
+---
+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.
+---
+
+# {{ $frontmatter.title }}
+
+{{ $frontmatter.description }}
+
+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.
+
+See the underlying TypeScript / Vue Language Tools issue: [vuejs/language-tools#3206](https://github.com/vuejs/language-tools/issues/3206).
+
+## Usage
+
+```ts
+import type { GenericInstanceType } from '@maz-ui/utils'
+import { ref } from 'vue'
+import MyGenericList from './MyGenericList.vue'
+
+const listRef = ref<GenericInstanceType<typeof MyGenericList> | null>(null)
+
+// listRef.value.focus() is fully typed
+```
+
+## API
+
+```ts
+type GenericInstanceType<T> = T extends new (...args: any[]) => infer R
+  ? R
+  : T extends (...args: any[]) => infer R
+    ? R extends { __ctx?: infer K }
+      ? Exclude<K, void> extends { expose: (...args: infer Y) => void }
+        ? Y[0] & InstanceType<DefineComponent>
+        : any
+      : any
+    : any
+```
+
+## Notes
+
+- Use this only for generic components. For non-generic SFCs, plain `InstanceType<typeof Component>` already works and is clearer.

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

@@ -0,0 +1,35 @@
+---
+title: InferMaybeRef
+description: Unwrap a Vue `Ref<U>` to its inner `U` — leaves non-ref types unchanged.
+---
+
+# {{ $frontmatter.title }}
+
+{{ $frontmatter.description }}
+
+Useful when authoring composables that accept either a plain value or a `Ref`, and you want a unified type for the inner value.
+
+## Usage
+
+```ts
+import type { InferMaybeRef } from '@maz-ui/utils'
+import { ref } from 'vue'
+
+const a = ref(42)
+const b = 42
+
+type A = InferMaybeRef<typeof a> // number
+type B = InferMaybeRef<typeof b> // number
+```
+
+## API
+
+```ts
+import type { Ref } from 'vue'
+
+type InferMaybeRef<T> = T extends Ref<infer U> ? U : T
+```
+
+## Notes
+
+- Pairs well with Vue's built-in [`unref()`](https://vuejs.org/api/reactivity-utilities.html#unref), which provides the same behaviour at runtime.

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

@@ -0,0 +1,32 @@
+---
+title: upperFirst
+description: Uppercase the first character of a string and leave the rest unchanged.
+---
+
+# {{ $frontmatter.title }}
+
+{{ $frontmatter.description }}
+
+## 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) for the same behaviour when you control the input shape.

package/docs/src/ecosystem/utils/user-visibility.md

@@ -0,0 +1,69 @@
+---
+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.
+---
+
+# {{ $frontmatter.title }}
+
+{{ $frontmatter.description }}
+
+`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
+
+```ts
+import { UserVisibility } from '@maz-ui/utils'
+
+const watcher = new UserVisibility(
+  ({ isVisible }) => {
+    if (isVisible) {
+      resumeVideo()
+    }
+    else {
+      pauseVideo()
+    }
+  },
+  { timeout: 3000 },
+)
+
+// later
+watcher.destroy()
+```
+
+## API
+
+```ts
+class UserVisibility {
+  constructor(callback: UserVisibilyCallback, options?: UserVisibilyOptions)
+
+  start(): void
+  destroy(): void
+}
+
+type UserVisibilyCallback = (payload: { isVisible: boolean }) => void
+```
+
+### Options
+
+| Option      | Type      | Default | Description                                                                       |
+| ----------- | --------- | ------- | --------------------------------------------------------------------------------- |
+| `timeout`   | `number`  | `5000`  | Grace period in ms before a hidden tab fires the `isVisible: false` callback.    |
+| `immediate` | `boolean` | `true`  | Fire the callback once on construction with the current visibility state.        |
+| `once`      | `boolean` | `false` | Auto-destroy after the first callback invocation.                                |
+
+## Examples
+
+Pause expensive timers when the user tabs away:
+
+```ts
+new UserVisibility(
+  ({ isVisible }) => {
+    isVisible ? animations.resume() : animations.pause()
+  },
+  { timeout: 0 }, // react immediately
+)
+```
+
+## Related
+
+- [`IdleTimeout`](./idle-timeout) — track in-page activity instead of tab visibility.

package/docs/src/guide/getting-started.md

@@ -55,7 +55,7 @@ Start by choosing your framework:
     </template>
   </MazCard>
   <MazCard
-    href="/guide/nuxt"
+    href="/ecosystem/nuxt"
     class="maz:flex-1"
     content-title="Nuxt Users Guide"
     :gallery="{
@@ -70,7 +70,7 @@ Start by choosing your framework:
       </h3>
     </template>
     <template #footer>
-      <MazBtn color="contrast" href="/guide/nuxt">
+      <MazBtn color="contrast" href="/ecosystem/nuxt">
         Nuxt guide
       </MazBtn>
     </template>
@@ -93,8 +93,9 @@ npm install @maz-ui/themes
 
 **Features:**
 
-- 🎨 OKLCh color system with perceptually uniform 11-step scales
-- 🌓 Smart dark mode detection and class/media/auto strategies
+- 🎨 Native `light-dark()` + `color-scheme` + OKLCh scales via relative color syntax
+- 🌓 Smart dark mode — `class` or `media` strategies, with smooth transitions on toggle
+- ✨ Optional animated theme switch via View Transitions (`setColorMode(..., { animate: true })`)
 - ⚡ `runtime` and `buildtime` rendering strategies
 - 🍪 Active preset persisted across reloads (opt-out)
 - 🛡️ Full TypeScript support
@@ -163,15 +164,6 @@ npm install @maz-ui/icons
 Maz-UI v5 is built with tree-shaking in mind. Import only what you need for optimal bundle sizes:
 
 ```typescript
-/**
- * Utilities
- */
-
-// ❌ Avoid importing everything
-import { formatCurrency, debounce } from '@maz-ui/utils'
-// ✅ Import from @maz-ui/utils
-import { formatCurrency, debounce } from '@maz-ui/utils'
-
 /**
  * Components
  */
@@ -215,6 +207,16 @@ import { vClickOutside } from 'maz-ui/directives/vClickOutside'
 import { MazUi } from 'maz-ui/plugins'
 // ✅✅ Direct plugin import (most optimized)
 import { MazUi } from 'maz-ui/plugins/maz-ui'
+
+/**
+ * Utilities
+ */
+
+// ❌ Avoid importing everything
+import { formatCurrency, debounce } from '@maz-ui/utils'
+// ✅ Import from @maz-ui/utils
+import { debounce } from '@maz-ui/utils/helpers/debounce'
+import { formatCurrency } from '@maz-ui/utils/helpers/formatCurrency'
 ```
 
 ::: tip Maximum Optimization

package/docs/src/guide/global-defaults.md

@@ -0,0 +1,101 @@
+---
+title: Global component defaults
+description: Set default prop values once for every Maz-UI component through the MazUi plugin or the Nuxt module
+head:
+  - - meta
+    - name: keywords
+      content: maz-ui defaults, global props, default props, rounded size, component configuration, vue, nuxt
+---
+
+# {{ $frontmatter.title }}
+
+{{ $frontmatter.description }}
+
+Instead of repeating the same prop on every instance (`<MazBtn rounded-size="lg" />` everywhere), you can set a default once and let every component pick it up.
+
+## Priority
+
+A resolved prop always follows this order, from highest to lowest priority:
+
+1. The prop set on the component instance
+2. `defaults.<ComponentName>` (per-component default)
+3. `defaults.global` (cross-cutting default)
+4. The library's built-in default
+
+A global default **never** overrides a prop set on the instance. Without any `defaults` config, every component keeps its built-in default, so this feature is fully opt-in and backward compatible.
+
+## Vue
+
+Pass `defaults` to the `MazUi` plugin:
+
+```ts
+import { MazUi } from 'maz-ui/plugins/maz-ui'
+import { mazUi as mazUiPreset } from '@maz-ui/themes/presets/mazUi'
+import 'maz-ui/style.css'
+
+app.use(MazUi, {
+  theme: { preset: mazUiPreset },
+  defaults: {
+    global: { roundedSize: 'lg' },
+    MazBtn: { roundedSize: 'full' }, // wins over global for MazBtn
+    MazCard: { bordered: false, elevation: true },
+    MazContainer: { bordered: false },
+  },
+})
+```
+
+## Nuxt
+
+Set it in `nuxt.config` under the `mazUi` key:
+
+```ts
+export default defineNuxtConfig({
+  modules: ['@maz-ui/nuxt'],
+  mazUi: {
+    defaults: {
+      global: { roundedSize: 'lg' },
+      MazBtn: { roundedSize: 'full' },
+      MazCard: { bordered: false, elevation: true },
+    },
+  },
+})
+```
+
+## `global` vs per-component
+
+- `defaults.global` holds **cross-cutting** props shared by many components: `roundedSize` and `size`. Set them once and every component that exposes them picks the value up.
+- `defaults.<ComponentName>` holds **per-component** props (including booleans such as `bordered`, `elevation`, `padding`). A per-component entry always wins over `global`.
+
+```ts
+defaults: {
+  global: { roundedSize: 'lg', size: 'sm' },
+  MazBtn: { roundedSize: 'full' }, // MazBtn is 'full', everything else 'lg'
+}
+```
+
+## Type safety
+
+`defaults` is fully typed. Each component entry is typed as `Partial<ComponentNameProps>`, so you get autocompletion and a TypeScript error on an unknown or mistyped prop:
+
+```ts
+defaults: {
+  MazBtn: { roundedSiz: 'lg' }, // ❌ TS error: 'roundedSiz' does not exist
+}
+```
+
+## Globalizable props
+
+| Prop | Type | Components |
+| --- | --- | --- |
+| `roundedSize` | `MazRoundedSize` (`'none' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| 'full'`) | `MazBtn`, `MazBtnGroup`, `MazContainer`, `MazInput`, `MazTextarea`, `MazTable`, `MazBadge`, `MazAlert`, `MazAvatar`, `MazSkeleton`, `MazTimeline` |
+| `size` | `MazSize` (`'mini' \| 'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl'`) | `MazBtn`, `MazBtnGroup`, `MazBadge`, `MazInput`, `MazSelect`, `MazSelectCountry`, `MazInputNumber`, `MazInputTags`, `MazInputPhoneNumber`, `MazCheckbox`, `MazRadio`, `MazRadioButtons`, `MazDropdown`, `MazPagination`, `MazTable`, `MazTimeline` |
+| `bordered`, `elevation`, `padding`, `transparent`, `overflowHidden` | `boolean` | `MazContainer` |
+| `bordered`, `elevation`, `padding`, `radius`, `scale`, `overflowHidden` | `boolean` | `MazCard` |
+
+::: tip Note
+Components whose `size` is a free CSS length (`MazSizeUnit`, e.g. `MazSpinner`, `MazAvatar`, `MazDrawer`, `MazSlider`, `MazCircularProgressBar`, `MazFullscreenLoader`) do not take the global `size` token - the value would not be valid for them. `MazAlert` and `MazTimeline` keep their own wider `roundedSize` scale; a `defaults.global.roundedSize` value still applies to them, and their extra steps (`2xl`, `3xl`) are reachable through their per-component entry.
+:::
+
+## Relation to the theme system
+
+This is **not** a duplicate of [`@maz-ui/themes`](/ecosystem/themes). The theme system controls *what a token looks like* (the CSS value of `rounded-md`, `shadow-elevation`, colors…). Global defaults control *which prop value a component selects by default* (whether `MazBtn` defaults to `roundedSize="lg"`). Both work together: the theme defines what `lg` renders as, the defaults decide which step a component uses.

package/docs/src/guide/maz-ui-provider.md

@@ -97,12 +97,15 @@ The entire Maz-UI setup is now code-split into the Dashboard chunk.
 
 ```typescript
 interface ThemeOptions {
-  preset: ThemePreset              // Required - Theme preset (mazUi, ocean, pristine, obsidian, or custom)
-  overrides?: ThemePresetOverrides // Partial overrides for colors, foundation, etc.
-  strategy?: 'runtime' | 'buildtime' // CSS generation strategy (default: 'runtime')
+  preset: ThemePreset                            // Required - Theme preset (mazUi, ocean, pristine, obsidian, nova, or custom)
+  overrides?: ThemePresetOverrides               // Partial overrides for colors, foundation, etc.
+  strategy?: 'runtime' | 'buildtime'             // CSS generation strategy (default: 'runtime')
   darkModeStrategy?: 'class' | 'media'           // Dark mode handling (default: 'class')
   colorMode?: 'light' | 'dark' | 'auto'          // Initial color mode (default: 'auto')
   mode?: 'light' | 'dark' | 'both'               // Supported color modes (default: 'both')
+  darkClass?: string                             // Class on <html> when colorMode === 'dark' (default: 'dark')
+  lightClass?: string                            // Class on <html> when colorMode === 'light' (default: 'light')
+  persistPreset?: boolean                        // Persist active preset in cookie (default: true)
 }
 ```