npm - @maz-ui/mcp - Versions diffs - 5.0.0-beta.2 → 5.0.0-beta.24 - Mend

@maz-ui/mcp 5.0.0-beta.2 → 5.0.0-beta.24

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (142) hide show

package/README.md +1 -1
package/dist/mcp.d.mts +22 -9
package/dist/mcp.d.ts +22 -9
package/dist/mcp.mjs +160 -83
package/docs/generated-docs/maz-avatar.doc.md +25 -25
package/docs/generated-docs/maz-btn.doc.md +1 -1
package/docs/generated-docs/maz-checkbox.doc.md +16 -17
package/docs/generated-docs/maz-circular-progress-bar.doc.md +1 -1
package/docs/generated-docs/maz-code-highlight.doc.md +11 -0
package/docs/generated-docs/maz-date-picker.doc.md +41 -41
package/docs/generated-docs/maz-drawer.doc.md +7 -8
package/docs/generated-docs/maz-expand-animation.doc.md +4 -4
package/docs/generated-docs/maz-fullscreen-loader.doc.md +5 -5
package/docs/generated-docs/maz-gallery.doc.md +15 -15
package/docs/generated-docs/maz-input-code.doc.md +16 -16
package/docs/generated-docs/maz-input-phone-number.doc.md +42 -38
package/docs/generated-docs/maz-input-price.doc.md +14 -14
package/docs/generated-docs/maz-input-tags.doc.md +16 -16
package/docs/generated-docs/maz-input.doc.md +33 -33
package/docs/generated-docs/maz-lazy-img.doc.md +14 -14
package/docs/generated-docs/maz-loading-bar.doc.md +4 -4
package/docs/generated-docs/maz-pull-to-refresh.doc.md +10 -10
package/docs/generated-docs/maz-radio-buttons.doc.md +17 -17
package/docs/generated-docs/maz-radio.doc.md +16 -16
package/docs/generated-docs/maz-reading-progress-bar.doc.md +4 -4
package/docs/generated-docs/maz-sidebar-content.doc.md +5 -0
package/docs/generated-docs/maz-sidebar-footer.doc.md +5 -0
package/docs/generated-docs/maz-sidebar-group.doc.md +11 -0
package/docs/generated-docs/maz-sidebar-header.doc.md +5 -0
package/docs/generated-docs/maz-sidebar-menu-button.doc.md +27 -0
package/docs/generated-docs/maz-sidebar-menu-item.doc.md +5 -0
package/docs/generated-docs/maz-sidebar-menu-sub.doc.md +16 -0
package/docs/generated-docs/maz-sidebar-menu.doc.md +5 -0
package/docs/generated-docs/maz-sidebar-separator.doc.md +0 -0
package/docs/generated-docs/maz-sidebar-trigger.doc.md +5 -0
package/docs/generated-docs/maz-sidebar.doc.md +36 -0
package/docs/generated-docs/maz-slider.doc.md +1 -1
package/docs/generated-docs/maz-spinner.doc.md +4 -4
package/docs/generated-docs/maz-switch.doc.md +14 -14
package/docs/generated-docs/maz-table.doc.md +5 -5
package/docs/generated-docs/maz-textarea.doc.md +25 -24
package/docs/generated-docs/maz-ticker.doc.md +1 -1
package/docs/generated-docs/maz-window-mockup.doc.md +23 -0
package/docs/src/blog/v4.md +1 -1
package/docs/src/blog/v5.md +5 -7
package/docs/src/components/maz-btn.md +1 -1
package/docs/src/components/maz-code-highlight.md +233 -0
package/docs/src/components/maz-container.md +2 -2
package/docs/src/components/maz-date-picker.md +1 -1
package/docs/src/components/maz-dialog.md +46 -0
package/docs/src/components/maz-icon.md +2 -2
package/docs/src/components/maz-input-phone-number.md +106 -103
package/docs/src/components/maz-sidebar.md +719 -0
package/docs/src/components/maz-textarea.md +27 -1
package/docs/src/components/maz-timeline.md +60 -0
package/docs/src/components/maz-window-mockup.md +249 -0
package/docs/src/directives/click-outside.md +8 -15
package/docs/src/directives/fullscreen-img.md +1 -1
package/docs/src/directives/lazy-img.md +5 -5
package/docs/src/directives/tooltip.md +24 -1
package/docs/src/directives/zoom-img.md +1 -1
package/docs/src/ecosystem/eslint-config.md +95 -1
package/docs/src/{guide/icons.md → ecosystem/icons/index.md} +1 -1
package/docs/src/ecosystem/node/exec-promise.md +87 -0
package/docs/src/ecosystem/node/index.md +53 -0
package/docs/src/ecosystem/node/logger.md +146 -0
package/docs/src/ecosystem/node/print-banner.md +93 -0
package/docs/src/{guide → ecosystem}/nuxt.md +81 -47
package/docs/src/{guide → ecosystem}/themes.md +153 -72
package/docs/src/{guide → ecosystem}/translations.md +1 -1
package/docs/src/ecosystem/utils/camel-case.md +31 -0
package/docs/src/{helpers → ecosystem/utils}/capitalize.md +2 -3
package/docs/src/ecosystem/utils/check-availability.md +79 -0
package/docs/src/ecosystem/utils/cookie.md +80 -0
package/docs/src/{helpers → ecosystem/utils}/currency.md +2 -2
package/docs/src/{helpers → ecosystem/utils}/date.md +2 -2
package/docs/src/ecosystem/utils/debounce-callback.md +38 -0
package/docs/src/ecosystem/utils/debounce-id.md +69 -0
package/docs/src/ecosystem/utils/debounce.md +65 -0
package/docs/src/ecosystem/utils/fetch-locale-ip.md +33 -0
package/docs/src/ecosystem/utils/format-json.md +33 -0
package/docs/src/ecosystem/utils/format-phone-number.md +37 -0
package/docs/src/ecosystem/utils/get-browser-locale.md +29 -0
package/docs/src/ecosystem/utils/get-error-message.md +39 -0
package/docs/src/ecosystem/utils/idle-timeout.md +90 -0
package/docs/src/ecosystem/utils/index.md +60 -0
package/docs/src/ecosystem/utils/is-client.md +32 -0
package/docs/src/ecosystem/utils/is-equal.md +38 -0
package/docs/src/ecosystem/utils/is-server.md +31 -0
package/docs/src/ecosystem/utils/is-standalone-mode.md +43 -0
package/docs/src/ecosystem/utils/kebab-case.md +36 -0
package/docs/src/ecosystem/utils/normalize-string.md +77 -0
package/docs/src/{helpers → ecosystem/utils}/number.md +2 -2
package/docs/src/ecosystem/utils/pascal-case.md +35 -0
package/docs/src/ecosystem/utils/script-loader.md +77 -0
package/docs/src/ecosystem/utils/sleep.md +59 -0
package/docs/src/ecosystem/utils/snake-case.md +36 -0
package/docs/src/ecosystem/utils/swipe-handler.md +91 -0
package/docs/src/ecosystem/utils/textarea-autogrow.md +41 -0
package/docs/src/ecosystem/utils/throttle-id.md +48 -0
package/docs/src/ecosystem/utils/throttle.md +57 -0
package/docs/src/ecosystem/utils/truthy-filter.md +31 -0
package/docs/src/ecosystem/utils/types/deep-key-of.md +48 -0
package/docs/src/ecosystem/utils/types/deep-partial.md +42 -0
package/docs/src/ecosystem/utils/types/deep-required.md +39 -0
package/docs/src/ecosystem/utils/types/flatten-object-keys.md +44 -0
package/docs/src/ecosystem/utils/types/generic-instance-type.md +42 -0
package/docs/src/ecosystem/utils/types/infer-maybe-ref.md +35 -0
package/docs/src/ecosystem/utils/upper-first.md +32 -0
package/docs/src/ecosystem/utils/user-visibility.md +69 -0
package/docs/src/guide/getting-started.md +15 -13
package/docs/src/guide/global-defaults.md +101 -0
package/docs/src/guide/maz-ui-provider.md +6 -3
package/docs/src/guide/migration-v4.md +13 -9
package/docs/src/guide/migration-v5.md +67 -12
package/docs/src/guide/resolvers.md +7 -7
package/docs/src/guide/tailwind.md +4 -0
package/docs/src/guide/vue.md +4 -4
package/docs/src/index.md +12 -12
package/docs/src/plugins/aos.md +1 -1
package/docs/src/plugins/wait.md +1 -1
package/package.json +6 -5
package/docs/src/helpers/camel-case.md +0 -14
package/docs/src/helpers/check-availability.md +0 -14
package/docs/src/helpers/debounce-callback.md +0 -14
package/docs/src/helpers/debounce-id.md +0 -14
package/docs/src/helpers/debounce.md +0 -14
package/docs/src/helpers/is-client.md +0 -14
package/docs/src/helpers/is-equal.md +0 -14
package/docs/src/helpers/is-standalone-mode.md +0 -14
package/docs/src/helpers/kebab-case.md +0 -14
package/docs/src/helpers/normalize-string.md +0 -14
package/docs/src/helpers/pascal-case.md +0 -14
package/docs/src/helpers/script-loader.md +0 -14
package/docs/src/helpers/sleep.md +0 -14
package/docs/src/helpers/snake-case.md +0 -14
package/docs/src/helpers/throttle-id.md +0 -14
package/docs/src/helpers/throttle.md +0 -14
/package/docs/src/{guide → ecosystem/icons}/icon-set.md +0 -0
/package/docs/src/{guide → ecosystem}/mcp.md +0 -0
/package/docs/src/{helpers → ecosystem/utils}/country-code-to-unicode-flag.md +0 -0
/package/docs/src/{helpers → ecosystem/utils}/get-country-flag-url.md +0 -0

package/docs/src/{guide → ecosystem}/nuxt.md RENAMED Viewed

@@ -126,11 +126,13 @@ export default defineNuxtConfig({
     theme: {
       preset: 'maz-ui', // 'maz-ui' | 'pristine' | 'ocean' | 'obsidian' | 'nova' | custom object
       strategy: 'runtime', // 'runtime' | 'buildtime'
-      darkModeStrategy: 'class', // 'class' | 'media' | 'auto'
+      darkModeStrategy: 'class', // 'class' | 'media'
+      darkClass: 'dark', // class on <html> when colorMode === 'dark' (default: 'dark')
+      lightClass: 'light', // class on <html> when colorMode === 'light' (default: 'light')
       overrides: {
         colors: {
-          light: { primary: '220 100% 50%' },
-          dark: { primary: '220 100% 70%' }
+          light: { primary: 'oklch(0.65 0.19 254)' },
+          dark: { primary: 'oklch(0.72 0.18 254)' }
         }
       },
       mode: 'both', // 'light' | 'dark' | 'both'
@@ -150,6 +152,13 @@ export default defineNuxtConfig({
       autoImport: true, // All components globally available
     },
+    // Global component defaults (priority: instance prop > defaults[Component] > defaults.global > library default)
+    defaults: {
+      global: { roundedSize: 'lg' }, // cross-cutting (roundedSize, size)
+      MazBtn: { roundedSize: 'full' }, // per-component, wins over global
+      MazCard: { bordered: false, elevation: true },
+    },
     // Plugins (not enabled by default)
     plugins: {
       aos: true,
@@ -220,16 +229,16 @@ const theme = {
   overrides: {
     colors: {
       light: {
-        primary: '220 100% 50%',
-        secondary: '220 14% 96%',
-        surface: '0 0% 100%',
-        foreground: '222 84% 5%',
+        primary: 'oklch(0.6 0.18 254)',
+        secondary: 'oklch(0.96 0.01 254)',
+        surface: 'oklch(1 0 0)',
+        foreground: 'oklch(0.16 0.02 254)',
       },
       dark: {
-        primary: '220 100% 70%',
-        secondary: '220 14% 4%',
-        surface: '222 84% 5%',
-        foreground: '210 40% 98%',
+        primary: 'oklch(0.72 0.18 254)',
+        secondary: 'oklch(0.22 0.02 254)',
+        surface: 'oklch(0.16 0.02 254)',
+        foreground: 'oklch(0.96 0.005 254)',
       }
     },
     // Override other theme properties...
@@ -245,7 +254,14 @@ const theme = {
   strategy: 'runtime', // 'runtime' (recommended) | 'buildtime'
   // Dark mode handling
-  darkModeStrategy: 'class', // 'class' | 'media' | 'auto'
+  darkModeStrategy: 'class', // 'class' | 'media'
+  // Class added to <html> when colorMode === 'dark' (default: 'dark')
+  darkClass: 'dark',
+  // Class added to <html> when colorMode === 'light' (default: 'light')
+  // Mirror of darkClass — used to force `color-scheme: only light`.
+  lightClass: 'light',
   // Persist the active preset name in the `maz-preset` cookie so the
   // user's last-used theme is restored on reload. Default: true.
@@ -253,6 +269,26 @@ const theme = {
 }
 ```
+### Global Component Defaults
+Set default prop values once for every component. Resolution priority, per prop: instance prop > `defaults[Component]` > `defaults.global` > library default. A global default never overrides a prop set on the instance.
+```ts
+const defaults = {
+  // Cross-cutting tokens applied to every component that exposes them
+  global: {
+    roundedSize: 'lg', // 'none' | 'sm' | 'md' | 'lg' | 'xl' | 'full'
+    size: 'sm', // 'mini' | 'xs' | 'sm' | 'md' | 'lg' | 'xl'
+  },
+  // Per-component defaults, strongly typed as Partial<ComponentNameProps>, win over `global`
+  MazBtn: { roundedSize: 'full' },
+  MazCard: { bordered: false, elevation: true },
+  MazContainer: { bordered: false },
+}
+```
+See the [Global component defaults guide](/guide/global-defaults) for the full list of globalizable props.
 ## Theme Strategies Explained
 ### Runtime (Recommended)
@@ -379,41 +415,39 @@ import { definePreset } from '@maz-ui/themes'
 export const customTheme = definePreset({
   base: 'maz-ui',
-  name: 'custom',
-  foundation: {
-    'base-font-size': '14px',
-    'font-family': `Manrope, sans-serif, system-ui, -apple-system`,
-    'space': '0.25rem',
-    'border-width': '0.0625rem',
-  },
-  scales: {
-    rounded: { md: '0.7rem' },
-  },
-  colors: {
-    light: {
-      primary: '350 100% 50%', // Custom pink
-      secondary: '350 14% 96%',
-      surface: '0 0% 100%',
-      foreground: '222 84% 5%',
-      muted: '210 40% 96%',
-      accent: '210 40% 90%',
-      destructive: '0 84% 60%',
-      border: '214 32% 91%',
-      input: '214 32% 91%',
-      ring: '350 100% 50%',
+  overrides: {
+    name: 'custom',
+    foundation: {
+      'base-font-size': '14px',
+      'font-family': `Manrope, sans-serif, system-ui, -apple-system`,
+      'space': '0.25rem',
+      'border-width': '0.0625rem',
+    },
+    scales: {
+      rounded: { md: '0.7rem' },
+    },
+    colors: {
+      light: {
+        primary: 'oklch(0.65 0.27 5)', // Custom pink
+        secondary: 'oklch(0.96 0.01 5)',
+        surface: 'oklch(1 0 0)',
+        foreground: 'oklch(0.16 0.02 254)',
+        muted: 'oklch(0.6 0.01 254)',
+        accent: 'oklch(0.7 0.05 5)',
+        destructive: 'oklch(0.6 0.22 27)',
+        divider: 'oklch(0.92 0.005 254)',
+      },
+      dark: {
+        primary: 'oklch(0.75 0.22 5)',
+        secondary: 'oklch(0.24 0.02 5)',
+        surface: 'oklch(0.16 0.02 254)',
+        foreground: 'oklch(0.96 0.005 254)',
+        muted: 'oklch(0.6 0.01 254)',
+        accent: 'oklch(0.3 0.04 5)',
+        destructive: 'oklch(0.55 0.2 27)',
+        divider: 'oklch(0.3 0.01 254)',
+      }
     },
-    dark: {
-      primary: '350 100% 70%',
-      secondary: '350 14% 4%',
-      surface: '222 84% 5%',
-      foreground: '210 40% 98%',
-      muted: '217 33% 17%',
-      accent: '217 33% 17%',
-      destructive: '0 62% 30%',
-      border: '217 33% 17%',
-      input: '217 33% 17%',
-      ring: '350 100% 70%',
-    }
   },
 })
@@ -429,7 +463,7 @@ export default defineNuxtConfig({
 ```
 ::: tip Subtree Overrides with MazUiProvider
-You can use [`MazUiProvider`](./maz-ui-provider.md) within a Nuxt app to override theme or translations in a specific subtree, while the module handles global defaults.
+You can use [`MazUiProvider`](../guide/maz-ui-provider.md) within a Nuxt app to override theme or translations in a specific subtree, while the module handles global defaults.
 :::
 ## Troubleshooting

package/docs/src/{guide → ecosystem}/themes.md RENAMED Viewed

@@ -1,19 +1,21 @@
 ---
 title: Theming
-description: Modern and performant theme system for Maz-UI with TypeScript, HSL CSS variables and flexible strategies.
+description: Modern and performant theme system for Maz-UI built on native CSS features (light-dark(), color-scheme, color-mix(in oklch)) for v5.
 ---
 # {{ $frontmatter.title }}
-{{ $frontmatter.description }}
+Modern and performant theme system for Maz-UI built on native CSS features (`light-dark()`, `color-scheme`, `color-mix(in oklch)`) for v5.
 <NpmBadge package="@maz-ui/themes"></NpmBadge>
 ## Features
-- **Modern HSL CSS Variables** - Maximum flexibility with colors
-- **Smart Dark Mode** - Automatic support with `prefers-color-scheme`
-- **Automatic Generation** - Color scales (50-950) created automatically
+- **Native `light-dark()` + `color-scheme`** - Modern CSS theming with zero JS overhead for the light/dark switch
+- **Native widget theming** - `color-scheme` makes scrollbars, native `<select>`, date pickers and autofill follow the active mode automatically
+- **Animated theme switch** - Optional full-page View Transitions via `setColorMode(..., { animate: true })`
+- **Anti-FART** - `<meta name="color-scheme">` injected at boot to prevent any Flash of inAccurate coloR Theme (no setup needed)
+- **Automatic color scales** - `--maz-X-50` through `--maz-X-950` derived via OKLCh relative color syntax — perceptually uniform and chroma-preserving
 - **Performance Strategies** - Runtime injection or build-time generation according to your needs
 - **Strict TypeScript** - Complete types for perfect DX
 - **Zero FOUC** - Pass the preset object up front; the full CSS is injected synchronously on first paint
@@ -44,13 +46,17 @@ app.use(MazUi, {
     darkModeStrategy: 'class', // 'class' | 'media' (only if mode is `both`)
     mode: 'both', // 'light' | 'dark' | 'both' (supported color modes)
     colorMode: 'auto', // 'auto' | 'light' | 'dark' (initial color mode, only if mode is 'both')
+    // Class added to <html> when dark mode is forced (default: 'dark')
+    darkClass: 'dark',
+    // Class added to <html> when light mode is forced (default: 'light')
+    lightClass: 'light',
     persistPreset: true, // remember the active preset name across reloads
   }
 })
 ```
 ::: tip Alternative: MazUiProvider
-You can also initialize the theme via the [`MazUiProvider`](./maz-ui-provider.md) component for lazy-loaded pages or subtree-scoped themes.
+You can also initialize the theme via the [`MazUiProvider`](../guide/maz-ui-provider.md) component for lazy-loaded pages or subtree-scoped themes.
 :::
 ### 2. Setup your CSS to support theme foundation and dark mode
@@ -89,10 +95,12 @@ const { toggleDarkMode, isDark, updateTheme } = useTheme()
 - `preset`: The theme preset to use
 - `overrides` (optional): Override specific parts of the theme
-- `strategy` (optional): The rendering strategy to use
-- `darkModeStrategy` (optional): The dark mode strategy to use, only if you use mode `both`
-- `mode` (optional): The supported color modes to use (light, dark, both)
-- `colorMode` (optional): The initial color mode to use (only if mode is 'both')
+- `strategy` (optional, default `'runtime'`): The rendering strategy to use — `'runtime' | 'buildtime'`
+- `darkModeStrategy` (optional, default `'class'`): The dark mode strategy — `'class' | 'media'`, only if you use mode `both`
+- `mode` (optional, default `'both'`): The supported color modes — `'light' | 'dark' | 'both'`
+- `colorMode` (optional, default `'auto'`): The initial color mode — `'light' | 'dark' | 'auto'` (only if mode is `'both'`)
+- `darkClass` (optional, default `'dark'`): Class added to `<html>` when `colorMode === 'dark'`
+- `lightClass` (optional, default `'light'`): Class added to `<html>` when `colorMode === 'light'` — mirror of `darkClass`
 - `persistPreset` (optional, default `true`): Persist the active preset name in the `maz-preset` cookie so it is restored on reload.
 ### Preset persistence
@@ -118,6 +126,48 @@ Useful when:
 - You want zero theme-related cookies (privacy / regulatory).
 - The active preset is fully driven by the consumer app and no end-user switching is exposed.
+## Color modes and class toggling
+`darkClass` and `lightClass` interact with `darkModeStrategy` to control how `<html>` is decorated when the user picks an explicit mode.
+### `darkModeStrategy: 'class'` (default)
+- `setColorMode('dark')` adds `darkClass` (default `.dark`) to `<html>` → `color-scheme: only dark`.
+- `setColorMode('light')` adds `lightClass` (default `.light`) to `<html>` → `color-scheme: only light`.
+- `setColorMode('auto')` removes both classes → `color-scheme: light dark` lets the browser follow the system `prefers-color-scheme`.
+Forcing both classes on the root ensures native widgets (scrollbars, native `<select>`, date pickers, autofill backgrounds, …) match the explicit user choice rather than the OS preference.
+### `darkModeStrategy: 'media'`
+- No class is ever added to `<html>`.
+- The browser always follows `prefers-color-scheme` via `color-scheme: light dark`.
+- `setColorMode()` still updates the persisted cookie but does **not** force a visual override.
+## Animated theme switch
+For a full-page animated swap (rather than per-variable color tweens), pass `{ animate: true }` to `setColorMode` or `toggleDarkMode`:
+```vue
+<script setup>
+import { useTheme } from '@maz-ui/themes'
+const { toggleDarkMode, setColorMode } = useTheme()
+async function onToggle() {
+  await toggleDarkMode({ animate: true })
+}
+async function forceDark() {
+  await setColorMode('dark', { animate: true })
+}
+</script>
+```
+- Wraps the switch in `document.startViewTransition()` so the browser captures a snapshot of the page before/after and crossfades between them.
+- The View Transition glue is **lazy-imported** — when `animate` is not used, it stays out of the boot bundle.
+- **Graceful degradation:** in browsers that don't support the API, the change is applied immediately with no animation (no error thrown).
 ## Interactive Demo
 <ComponentDemo title="Real-time theme control">
@@ -395,14 +445,14 @@ const customTheme = await definePreset({
     },
     colors: {
       light: {
-        primary: '280 100% 60%',
-        secondary: '300 50% 90%',
-        accent: '260 100% 70%'
+        primary: 'oklch(0.62 0.24 305)',
+        secondary: 'oklch(0.94 0.04 320)',
+        accent: 'oklch(0.7 0.22 290)'
       },
       dark: {
-        primary: '280 100% 70%',
-        secondary: '300 30% 20%',
-        accent: '260 100% 80%'
+        primary: 'oklch(0.72 0.22 305)',
+        secondary: 'oklch(0.28 0.06 320)',
+        accent: 'oklch(0.78 0.2 290)'
       }
     }
   },
@@ -449,16 +499,16 @@ const brandTheme = await definePreset({
     },
     colors: {
       light: {
-        primary: '210 100% 50%',
-        secondary: '210 40% 96%',
-        surface: '210 20% 98%',
-        accent: '280 100% 70%'
+        primary: 'oklch(0.6 0.18 254)',
+        secondary: 'oklch(0.96 0.01 254)',
+        surface: 'oklch(0.99 0.005 254)',
+        accent: 'oklch(0.7 0.22 305)'
       },
       dark: {
-        primary: '210 100% 60%',
-        secondary: '210 40% 15%',
-        surface: '210 20% 8%',
-        accent: '280 100% 80%'
+        primary: 'oklch(0.7 0.18 254)',
+        secondary: 'oklch(0.22 0.03 254)',
+        surface: 'oklch(0.18 0.02 254)',
+        accent: 'oklch(0.78 0.2 305)'
       }
     }
   }
@@ -530,7 +580,7 @@ const surfaceTheme = definePreset({
       },
       container: {
         // Cards / dialogs / popovers / drawers — light = page surface, dark = a tier above
-        bg: { light: 'var(--maz-surface)', dark: 'var(--maz-surface-300)' },
+        bg: { light: 'var(--maz-surface)', dark: 'var(--maz-color-surface-300)' },
       },
       input: {
         // All form-control surfaces
@@ -543,23 +593,58 @@ const surfaceTheme = definePreset({
 Components consume these via `maz:bg-container` / `maz:bg-input` Tailwind utilities, so a single override propagates everywhere — no per-component class hunt.
+### Dialog sizing
+`components.dialog` controls the width of [`MazDialog`](./../components/maz-dialog.md) on tablet and up. The two keys are emitted as `--maz-dialog-max-width` / `--maz-dialog-min-width` and consumed by the component through `var(--maz-dialog-max-width, 38rem)` / `var(--maz-dialog-min-width, 32rem)`:
+```typescript
+const wideDialogTheme = definePreset({
+  base: 'maz-ui',
+  overrides: {
+    name: 'wide-dialogs',
+    components: {
+      dialog: {
+        'max-width': '48rem',
+        'min-width': '36rem',
+      },
+    },
+  },
+})
+```
+Both values are in `rem`, so they scale with the preset's `base-font-size`. Bundled presets anchored on `14px` use `38rem` / `32rem`; `ocean` (`16px`) ships scaled rem values (`33.25rem` / `28rem`) to keep the same rendered pixel width. The `max-width` / `min-width` props on `MazDialog` still override the preset per instance.
 ## useTheme Composable API
 ```typescript
 const {
   // Reactive state
+  preset, // ComputedRef<ThemePreset>
   presetName, // ComputedRef<string>
-  colorMode, // ComputedRef<'light' | 'dark' | 'auto'>
+  colorMode, // Ref<'light' | 'dark' | 'auto'> — also accepts assignment (computed setter)
   isDark, // ComputedRef<boolean>
   strategy, // ComputedRef<'runtime' | 'buildtime'>
+  mode, // ComputedRef<'light' | 'dark' | 'both'>
+  darkModeStrategy, // ComputedRef<'class' | 'media'>
   // Actions
-  updateTheme, // (preset: ThemePreset | ThemePresetOverrides) => void
-  setColorMode, // (mode: 'light' | 'dark' | 'auto') => void
-  toggleDarkMode // () => void
+  updateTheme, // (preset: ThemePreset | ThemePresetName | ThemePresetOverrides) => Promise<void>
+  setColorMode, // (mode: 'light' | 'dark' | 'auto', options?: { animate?: boolean }) => Promise<void>
+  toggleDarkMode, // (options?: { animate?: boolean }) => Promise<void>
 } = useTheme()
+// Set the color mode imperatively
+await setColorMode('dark')
+// Or assign to `colorMode` — it's a computed with a setter
+colorMode.value = 'dark'
+// Animated full-page switch via View Transitions
+await toggleDarkMode({ animate: true })
 ```
+`setColorMode` and `toggleDarkMode` are **async** (`Promise<void>`). The promise resolves once the change — and the optional View Transition — has been applied. Callers can ignore the return value when no transition is needed.
 ### Advanced Usage Examples
 ```vue
@@ -623,8 +708,8 @@ const customPreset = definePreset({
   overrides: {
     name: 'custom',
     colors: {
-      light: { primary: '221.2 83.2% 53.3%' },
-      dark: { primary: '217.2 91.2% 59.8%' },
+      light: { primary: 'oklch(0.6 0.18 254)' },
+      dark: { primary: 'oklch(0.7 0.18 254)' },
     },
   },
 })
@@ -687,8 +772,8 @@ const customPreset = definePreset({
   overrides: {
     name: 'custom',
     colors: {
-      light: { primary: '221.2 83.2% 53.3%' },
-      dark: { primary: '217.2 91.2% 59.8%' },
+      light: { primary: 'oklch(0.6 0.18 254)' },
+      dark: { primary: 'oklch(0.7 0.18 254)' },
     },
   },
 })
@@ -729,8 +814,8 @@ const customPreset = definePreset({
   overrides: {
     name: 'custom',
     colors: {
-      light: { primary: '221.2 83.2% 53.3%' },
-      dark: { primary: '217.2 91.2% 59.8%' },
+      light: { primary: 'oklch(0.6 0.18 254)' },
+      dark: { primary: 'oklch(0.7 0.18 254)' },
     },
   },
 })
@@ -819,7 +904,7 @@ const styleTag = createThemeStylesheet(css, {
 ## Token Reference
-Every preset emits the same set of CSS variables on `:root` (and a `.dark` block when `mode: 'both'`). Use these names directly in your own CSS — `var(--maz-primary)`, `calc(var(--maz-space) * 4)`, etc.
+Every preset emits the same set of CSS variables on `:root`. With `mode: 'both'`, each base color is a single `light-dark(L, D)` declaration that the browser resolves to the active scheme. Use these names directly in your own CSS — `var(--maz-primary)`, `calc(var(--maz-space) * 4)`, etc.
 ### Foundation
@@ -893,16 +978,27 @@ Per-component knobs under `components.<key>`. All optional — omit to fall back
 | `btn.font-weight` | `--maz-btn-font-weight` | Font-weight on `.m-btn`. Defaults to `'500'`. |
 | `container.bg.light` / `.dark` | `--maz-container-bg` (per mode) | Background of `Card`, `Container`, `Dialog`, `Popover`, `Drawer`, … Defaults to `var(--maz-surface)`. Bridged to `--color-container`. |
 | `input.bg.light` / `.dark` | `--maz-input-bg` (per mode) | Background of `Input`, `Textarea`, `Select`, `Checkbox`, … Defaults to `var(--maz-surface)` light, `var(--maz-surface-400)` dark. Bridged to `--color-input`. |
+| `dialog.max-width` | `--maz-dialog-max-width` | Max-width of `MazDialog` on tablet and up. Defaults to `38rem` (`33.25rem` on `ocean`). Overridable via the `max-width` prop. |
+| `dialog.min-width` | `--maz-dialog-min-width` | Min-width of `MazDialog` on tablet and up. Defaults to `32rem` (`28rem` on `ocean`). Overridable via the `min-width` prop. |
 ### Sample output
+Each base color is emitted as a `light-dark()` value; scales `--maz-X-50` through `--maz-X-950` are derived via OKLCh relative color syntax so they automatically follow base color overrides at runtime, preserving chroma at every step.
 ```css
 :root {
-  /* Main colors */
-  --maz-primary: oklch(0.6495 0.1913 253.63);
-  --maz-primary-foreground: oklch(1 0 0);
-  --maz-surface: oklch(1 0 0);
-  --maz-foreground: oklch(0.2573 0.0068 248.09);
+  color-scheme: light dark;
+  /* Base colors — one declaration each, resolved by the browser */
+  --maz-primary: light-dark(oklch(0.65 0.19 254), oklch(0.72 0.18 254));
+  --maz-primary-foreground: light-dark(oklch(1 0 0), oklch(0.16 0.01 254));
+  --maz-surface: light-dark(oklch(1 0 0), oklch(0.18 0.01 254));
+  --maz-foreground: light-dark(oklch(0.26 0.01 254), oklch(0.96 0.005 254));
+  /* Auto-generated 50–950 scale — derived via relative color syntax */
+  --maz-primary-500: var(--maz-primary);
+  --maz-primary-600: oklch(from var(--maz-primary) clamp(0, calc(l - 0.07), 1) c h);
+  /* ... */
   /* Foundation */
   --maz-base-font-size: 14px;
@@ -914,35 +1010,19 @@ Per-component knobs under `components.<key>`. All optional — omit to fall back
   /* Scales */
   --maz-rounded-md: 0.7rem;
   --maz-shadow-style-md: 0 4px 6px -1px rgb(0 0 0 / 0.1), …;
-  /* Auto-generated 50–950 scale */
-  --maz-primary-500: oklch(…);
-  /* ... */
 }
-```
-### Dark Mode
-```css
-.dark {
-  --maz-surface: 235 16% 15%;
-  --maz-foreground: 0 0% 85%;
-  /* Variables automatically adapted */
-}
-/* Or with media query */
-@media (prefers-color-scheme: dark) {
-  :root {
-    --maz-surface: 235 16% 15%;
-    --maz-foreground: 0 0% 85%;
-  }
-}
+/* With darkModeStrategy: 'class' — explicit user choice overrides the system */
+.dark  { color-scheme: only dark; }
+.light { color-scheme: only light; }
 ```
+For deeper detail on the generated CSS contract, see the [`@maz-ui/themes` README](https://github.com/LouisMazel/maz-ui/tree/master/packages/themes#generated-css-variables).
 ## Usage with Nuxt
-For Nuxt users, check the [dedicated Nuxt documentation](/guide/nuxt) which covers installation and framework-specific configuration.
+For Nuxt users, check the [dedicated Nuxt documentation](/ecosystem/nuxt) which covers installation and framework-specific configuration.
 ## Migration from Legacy System
@@ -965,20 +1045,21 @@ export default defineConfig({
 ```typescript [After (@maz-ui/themes)]
 // main.ts
 import { definePreset, mazUi } from '@maz-ui/themes'
+import { MazUiTheme } from '@maz-ui/themes/plugin'
 const myTheme = definePreset({
   base: mazUi,
   overrides: {
     colors: {
       light: {
-        primary: '210 100% 56%',
-        secondary: '164 76% 46%'
+        primary: 'oklch(0.65 0.19 254)',
+        secondary: 'oklch(0.72 0.16 168)'
       }
     }
   }
 })
-app.use(MazThemePlugin, { preset: myTheme })
+app.use(MazUiTheme, { preset: myTheme })
 ```
 :::
@@ -1007,14 +1088,14 @@ const customPreset = await definePreset({
     name: 'custom-purple',
     colors: {
       light: {
-        'primary': '280 100% 60%',
-        'secondary': '300 50% 90%',
-        'accent': '260 100% 70%'
+        'primary': 'oklch(0.62 0.24 305)',
+        'secondary': 'oklch(0.94 0.04 320)',
+        'accent': 'oklch(0.7 0.22 290)'
       },
       dark: {
-        'primary': '280 100% 70%',
-        'secondary': '300 30% 20%',
-        'accent': '260 100% 80%'
+        'primary': 'oklch(0.72 0.22 305)',
+        'secondary': 'oklch(0.28 0.06 320)',
+        'accent': 'oklch(0.78 0.2 290)'
       }
     }
   }

package/docs/src/{guide → ecosystem}/translations.md RENAMED Viewed

@@ -73,7 +73,7 @@ app.use(MazUi, {
 ```
 ::: tip Alternative: MazUiProvider
-You can also provide translations via the [`MazUiProvider`](./maz-ui-provider.md) component for lazy-loaded pages or subtree-scoped configurations.
+You can also provide translations via the [`MazUiProvider`](../guide/maz-ui-provider.md) component for lazy-loaded pages or subtree-scoped configurations.
 :::
 ## How it works

package/docs/src/ecosystem/utils/camel-case.md ADDED Viewed

@@ -0,0 +1,31 @@
+---
+title: camelCase
+description: Convert a kebab-case string to camelCase by stripping dashes and uppercasing the following letter.
+---
+# {{ $frontmatter.title }}
+{{ $frontmatter.description }}
+## Usage
+```ts
+import { camelCase } from '@maz-ui/utils'
+camelCase('my-component-name') // → 'myComponentName'
+camelCase('hello-world') // → 'helloWorld'
+```
+## API
+```ts
+function camelCase(str: string): string
+```
+| Parameter | Type     | Description           |
+| --------- | -------- | --------------------- |
+| `str`     | `string` | The string to convert |
+## Notes
+`camelCase` is intentionally minimal — it only handles `kebab-case` input. For more general normalization (snake_case, spaces, PascalCase), use [`normalizeString`](./normalize-string) with the `case: 'camelCase'` option.

package/docs/src/{helpers → ecosystem/utils}/capitalize.md RENAMED Viewed

@@ -10,8 +10,7 @@ description: The module capitalize is a function that adds a capital letter to a
 <MazInput v-model="stringValue" />
 <div
-  style="padding: 16px; margin-top: 16px; background-color: var(--maz-surface-300);"
-  class="flex flex-center rounded gap-05"
+  class="maz:flex maz:flex-center maz:rounded-md maz:gap-0.5 maz:p-4 maz:mt-16 maz:bg-surface-300"
 >
   formatted value: <strong>{{ stringFormatted }}</strong>
 </div>
@@ -32,7 +31,7 @@ const stringFormatted = computed(() =>
   <MazInput v-model="stringValue" />
   <div
-    style="padding: 16px; margin-top: 16px; background-color: var(--maz-surface-300);"
+    class="flex flex-center rounded-md gap-0.5 p-4 mt-16 bg-surface-300"
   >
     {{ stringFormatted }}
   </div>