@maz-ui/mcp 5.0.0-beta.5 → 5.0.0-beta.51

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,102 @@
+---
+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`, `size` and `flagSrc`. 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` |
+| `flagSrc` | `MazCountryFlagSrc` (URL template or function, e.g. `loadCountryFlag` from `maz-ui/country-flags`) | `MazSelectCountry`, `MazInputPhoneNumber` (see [flags source](../components/maz-select-country.md#flags-source)) |
+| `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)
 }
 ```
 

package/docs/src/guide/migration-v4.md

@@ -13,7 +13,7 @@ Performance has also been significantly improved thanks to optimal tree-shaking,
 
 ::: tip Connected to Maz-UI MCP
 
-Follow the [MCP](/guide/mcp) guide to connect your AI assistant to Maz-UI's documentation for a smooth migration process.
+Follow the [MCP](/ecosystem/mcp) guide to connect your AI assistant to Maz-UI's documentation for a smooth migration process.
 
 :::
 
@@ -41,6 +41,10 @@ v4.0.0 isn't just an update, it's a **complete rebuild** that transforms Maz-UI
 - **Dynamic CSS Variables**: Automatic CSS variable generation
 - **Intelligent dark mode**: Configurable strategies for dark mode based on system preferences and user choice stored in cookies
 
+::: tip Theming further evolved in v5
+The theme system has been rewritten on top of native `light-dark()` + `color-scheme` + `color-mix(in oklch)` in v5. If you are upgrading past v4, see the dedicated [v5 migration guide](./migration-v5.md#theming-native-css-rewrite-new-non-breaking-by-default) for the full theming changes (new `lightClass`, `Promise<void>` returns, removed JS helpers).
+:::
+
 #### Complete Internationalization
 
 - **9 supported languages by default**: EN, FR, DE, ES, IT, PT, JA, ZH-CN
@@ -688,12 +692,12 @@ app.use(MazUi, {
 <script setup>
 import { useTheme } from 'maz-ui/composables'
 
-const { isDark, toggleDarkMode, setTheme } = useTheme()
+const { isDark, toggleDarkMode, updateTheme } = useTheme()
 
 // Change theme
-setTheme('ocean')
+updateTheme('ocean')
 
-// Toggle dark mode
+// Toggle dark mode (v5: returns Promise<void>, optional { animate } param)
 toggleDarkMode()
 </script>
 
@@ -704,7 +708,7 @@ toggleDarkMode()
 </template>
 ```
 
-**📖 Complete documentation:** [Theme Guide](/guide/themes)
+**📖 Complete documentation:** [Theme Guide](/ecosystem/themes)
 
 ## Translation System
 
@@ -744,7 +748,7 @@ setLocale('fr')
 </template>
 ```
 
-**📖 Complete documentation:** [Translation Guide](/guide/translations)
+**📖 Complete documentation:** [Translation Guide](/ecosystem/translations)
 
 ## Common Errors and Solutions
 
@@ -901,10 +905,10 @@ app.use(MazUi)
 ## Additional Resources
 
 - **[Official v4 Documentation](https://maz-ui.com)** - Complete documentation
-- **[Theme Guide](/guide/themes)** - Advanced theme system
-- **[Translation Guide](/guide/translations)** - Internationalization
+- **[Theme Guide](/ecosystem/themes)** - Advanced theme system
+- **[Translation Guide](/ecosystem/translations)** - Internationalization
 - **[Vue Installation Guide](/guide/vue)** - Vue setup
-- **[Nuxt Installation Guide](/guide/nuxt)** - Nuxt setup
+- **[Nuxt Installation Guide](/ecosystem/nuxt)** - Nuxt setup
 - **[Resolvers Guide](/guide/resolvers)** - Smart auto-imports
 - **[Complete Changelog](https://github.com/LouisMazel/maz-ui/blob/master/CHANGELOG.md)** - All changes