maz-ui 5.0.0 → 5.1.0-beta.0

package/docs/ecosystem/nuxt.md

@@ -0,0 +1,551 @@
+---
+title: "Install maz-ui with Nuxt"
+description: "The ultimate Nuxt module for Maz-UI - zero-config setup with auto-imports, theming, internationalization and powerful features out of the box"
+package: "@maz-ui/nuxt"
+url: "https://maz-ui.com/ecosystem/nuxt"
+---
+
+# Install maz-ui with Nuxt
+
+> The ultimate Nuxt module for Maz-UI - zero-config setup with auto-imports, theming, internationalization and powerful features out of the box
+
+- Package: `@maz-ui/nuxt`
+- Web: https://maz-ui.com/ecosystem/nuxt
+
+**Maz-UI Nuxt Module** provides zero-configuration setup, intelligent auto-imports, powerful theming capabilities and internationalization.
+
+**Tip: Model Context Protocol (MCP)**
+
+In development, the module connects the AI coding agents detected in the project (Claude Code, Cursor, Copilot...) to the maz-ui [MCP server](./mcp.md), which gives them the docs and rules of the installed maz-ui. See AI Agents.
+
+Check out the documentation of [@maz-ui/mcp](./mcp.md)
+
+## Why Choose Maz-UI for Nuxt?
+
+- **Zero Configuration** - Works out of the box with sensible defaults
+- **Advanced Theming** - Built-in dark mode, custom themes, and CSS variables
+- **Auto-Import Everything** - Components, composables, and directives automatically available
+- **Performance Optimized** - Tree-shaking, lazy loading, and SSR-friendly CSS injection
+- **Developer Experience** - TypeScript support, DevTools integration, and IntelliSense
+- **Production Ready** - SSR/SSG support with client-side hydration
+
+## Installation
+
+```bash [pnpm]
+pnpm add @maz-ui/nuxt
+```
+
+```bash [npm]
+npm install @maz-ui/nuxt
+```
+
+```bash [yarn]
+yarn add @maz-ui/nuxt
+```
+
+```bash [nuxt]
+pnpx nuxt@latest module add @maz-ui/nuxt
+```
+
+Add the module to your `nuxt.config.ts`:
+
+```ts
+export default defineNuxtConfig({
+  modules: ['@maz-ui/nuxt']
+})
+```
+
+That's it! 🎉 All components and composables are now auto-imported and ready to use.
+
+## Quick Start
+
+### Instant Usage
+
+No imports needed - everything is auto-imported:
+
+```vue
+<script setup>
+// Composables are auto-imported
+const { start, stop, pause, resume, remainingTime } = useTimer({
+  timeout: 4000,
+  callback: () => console.log('Timeout end')
+})
+const { toggleDarkMode, isDark } = useTheme()
+</script>
+
+<template>
+  <div class="bg-surface p-8 text-foreground">
+    <!-- Components are auto-imported -->
+    <MazBtn color="primary" @click="start">
+      Start timer ({{ remainingTime }}ms)
+    </MazBtn>
+
+    <!-- Directives work globally -->
+    <MazBtn @click="toggleDarkMode">
+      Toggle dark mode ({{ isDark ? '🌙' : '☀️' }})
+    </MazBtn>
+  </div>
+</template>
+```
+
+## Configuration
+
+### Minimal Setup
+
+For most use cases, no configuration is needed:
+
+```ts
+export default defineNuxtConfig({
+  modules: ['@maz-ui/nuxt']
+  // That's it! 🎉
+})
+```
+
+### Advanced Configuration
+
+Customize everything to your needs:
+
+```ts
+export default defineNuxtConfig({
+  modules: ['@maz-ui/nuxt'],
+  mazUi: {
+    // General Settings
+    general: {
+      autoImportPrefix: 'Maz', // useMazToast instead of useToast
+      defaultMazIconPath: '/icons', // Default path for <MazIcon />
+      devtools: true, // Enable DevTools integration
+      preventIosInputZoom: true, // No zoom on focused fields on iOS
+    },
+
+    // CSS & Styling
+    css: {
+      injectCss: true, // Auto-inject Maz-UI styles
+    },
+
+    // Theming System
+    theme: {
+      preset: 'maz-ui', // 'maz-ui' | 'pristine' | 'ocean' | 'obsidian' | 'nova' | custom object
+      strategy: 'runtime', // 'runtime' | 'buildtime'
+      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: 'oklch(0.65 0.19 254)' },
+          dark: { primary: 'oklch(0.72 0.18 254)' }
+        }
+      },
+      mode: 'both', // 'light' | 'dark' | 'both'
+    },
+
+    // Translations
+    translations: {
+      locales: 'fr',
+      fallbackLocale: 'en',
+      messages: {
+        // override default messages or add new languages
+      },
+    },
+
+    // Components
+    components: {
+      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 },
+    },
+
+    // Country flags of MazSelectCountry and MazInputPhoneNumber: 'cdn' (default), 'local' (offline) or '/flags/{code}.svg'
+    flags: 'local',
+
+    // Plugins (not enabled by default)
+    plugins: {
+      aos: true,
+      dialog: true,
+      toast: true,
+      wait: true,
+    },
+
+    // Composables (enabled by default)
+    composables: {
+      useFormValidator: true,
+      useFreezeValue: true,
+      useIdleTimeout: false,
+      useInstanceUniqId: false,
+      useMountComponent: false,
+      useReadingTime: false,
+      useStringMatching: false,
+    },
+
+    // Directives (not enabled by default)
+    directives: {
+      vTooltip: true,
+      vLazyImg: true,
+      vClickOutside: true,
+      vFullscreenImg: true,
+      vZoomImg: true,
+    },
+
+    // AI coding agents (default: { rules: false, mcp: true }, false to disable)
+    agents: { rules: true, mcp: true },
+  }
+})
+```
+
+## Complete Configuration Reference
+
+### General Configuration
+
+```ts
+const general = {
+  // Add prefix to all auto-imported composables
+  autoImportPrefix: 'Maz', // only for composables, generates useMazToast, useMazTheme, etc.
+
+  // Default icon path for <MazIcon icon="..." />
+  defaultMazIconPath: '/icons',
+
+  // Enable Nuxt DevTools integration
+  devtools: true,
+
+  // Stop iOS from zooming the page when a form field gets the focus (default: false)
+  // Adds `maximum-scale=1` to the viewport on iOS only, see the preventIosInputZoom helper of @maz-ui/utils
+  preventIosInputZoom: false,
+}
+```
+
+### CSS Configuration
+
+```ts
+const css = {
+  // Auto-inject Maz-UI base styles
+  injectCss: true,
+}
+```
+
+### Theme System
+
+The most powerful theming system for Nuxt applications:
+
+```ts
+const theme = {
+  // Use predefined presets or create custom ones
+  preset: 'maz-ui', // 'mazUi' | 'dark' | 'ocean' | CustomThemeObject
+
+  // Override specific parts of the theme
+  overrides: {
+    colors: {
+      light: {
+        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: '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...
+  },
+
+  // Supported color modes to use
+  mode: 'both', // 'light' | 'dark' | 'both'
+
+  // Initial color mode to use (only if mode is 'both')
+  colorMode: 'auto', // 'light' | 'dark' | 'auto'
+
+  // CSS generation strategy
+  strategy: 'runtime', // 'runtime' (recommended) | 'buildtime'
+
+  // Dark mode handling
+  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.
+  persistPreset: true,
+}
+```
+
+### 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.md) for the full list of globalizable props.
+
+### Country Flags
+
+Source of the flags of `MazSelectCountry` and `MazInputPhoneNumber`. A `flag-src` set on a component wins.
+
+```ts
+export default defineNuxtConfig({
+  mazUi: {
+    // 'cdn' (default): flagcdn.com
+    // 'local': flags of @maz-ui/icons, one chunk per flag loaded when visible, no request to a third party
+    // '/flags/{code}.svg': your own files ({CODE} for uppercase codes)
+    flags: 'local',
+  },
+})
+```
+
+Nothing is added to your build unless `flags` is `'local'`. See [MazSelectCountry](../components/maz-select-country.md#flags-source) for the details (Content Security Policy, PWA precache).
+
+## Theme Strategies Explained
+
+### Runtime (Recommended)
+
+The full theme CSS is generated and injected synchronously on first paint:
+
+- **No FOUC** - The full stylesheet is rendered in the document head before the first paint
+- **SSR-friendly** - On Nuxt SSR, the CSS is inlined via `useHead` during server rendering and re-used on the client
+- **Dynamic** - `useTheme().updateTheme(...)` re-injects the new CSS on the fly
+
+```ts
+export default defineNuxtConfig({
+  mazUi: {
+    theme: {
+      strategy: 'runtime' // Recommended for most use cases
+    }
+  }
+})
+```
+
+### Buildtime
+
+Build-time CSS generation strategy:
+
+- **No runtime injection** - CSS is generated at build time and must be included manually
+- **Consumer responsibility** - You must handle CSS inclusion in your build process and HTML
+- **Optimal performance** - No client-side CSS generation overhead
+- **Static themes only** - Best for applications without dynamic theme switching
+
+```ts
+export default defineNuxtConfig({
+  mazUi: {
+    theme: {
+      strategy: 'buildtime' // For static sites with predefined themes
+    }
+  }
+})
+```
+
+### Components
+
+```ts
+const components = {
+  // Auto-import all 50+ Maz-UI components
+  autoImport: true,
+}
+```
+
+**Available Components:**
+`MazBtn`, `MazInput`, `MazSelect`, `MazDialog`, `MazToast`, `MazIcon`, `MazCard`, `MazTable`, `MazChart`, `MazCarousel`, `MazGallery`, and 50+ more!
+
+### 🎪 Composables
+
+All composables are auto-imported and ready to use:
+
+```ts
+const composables = {
+  // 🎨 Theming
+  useTheme: true, // Theme management and dark mode
+
+  // 🌐 Translations
+  useTranslations: true, // Translation management
+
+  // 📱 Responsive & Detection
+  useWindowSize: true, // Reactive window dimensions
+  useBreakpoints: true, // Responsive breakpoints
+  useUserVisibility: true, // Page visibility detection
+  useIdleTimeout: true, // User idle detection
+
+  // 🛠️ Utilities
+  useTimer: true, // Timer and countdown
+  useFormValidator: true, // Form validation
+  useStringMatching: true, // String utilities
+  useReadingTime: true, // Reading time calculation
+  useDisplayNames: true, // Display localized names
+  useSwipe: true, // Swipe gestures
+  usePullToRefresh: true, // Pull to refresh gesture
+
+  // 🔧 Advanced
+  useFreezeValue: true, // Freeze reactive values
+  useInjectStrict: true, // Strict dependency injection
+  useInstanceUniqId: true, // Unique IDs generation
+  useMountComponent: true, // Dynamic component mounting
+}
+```
+
+### Plugins
+
+```ts
+const plugins = {
+  // Animations
+  aos: true,
+  // 🎭 Display modales without any implementation in template
+  dialog: true,
+  // 🎭 UI Notifications
+  toast: true,
+  // 🔄 Loading States
+  wait: true,
+}
+```
+
+### Directives
+
+Powerful Vue directives for enhanced functionality:
+
+```ts
+const directives = {
+  // Image directives
+  vLazyImg: { threshold: 0.1 }, // Lazy loading with intersection observer
+  vZoomImg: true, // Click to zoom images
+  vFullscreenImg: true, // Fullscreen image viewer
+
+  // Interaction directives
+  vTooltip: { position: 'top' }, // Flexible tooltips
+  vClickOutside: true, // Detect outside clicks
+}
+```
+
+### AI Agents
+
+Connect your AI coding agents (Claude Code, Cursor, GitHub Copilot, Codex, Windsurf...) to maz-ui, version-matched with the installed maz-ui, so they use its components, composables, icons, helpers and theme tokens instead of re-implementing them:
+
+```ts
+const agents = {
+  // Register the maz-ui MCP server in .mcp.json, .cursor/mcp.json, .vscode/mcp.json (default: true)
+  // Its instructions give the maz-ui rules to the agents
+  mcp: true,
+  // Also write the rules in .claude/rules/maz-ui.md and in AGENTS.md, for agents without MCP (default: false)
+  rules: false,
+  // 'claude' | 'agents-md' | 'cursor' | 'vscode' (default: the detected agents)
+  targets: ['claude', 'agents-md'],
+}
+// agents: true enables mcp and rules, agents: false disables everything
+```
+
+The module runs in development only (never in CI nor in tests), only for the agents it detects in the project (`.claude/`, `CLAUDE.md`, `.mcp.json`, `.cursor/`, `.vscode/mcp.json`, `.github/copilot-instructions.md`, `AGENTS.md`, `.codex/`, `.windsurf/`...), and keeps the files up to date when you upgrade maz-ui:
+
+- `.mcp.json`, `.cursor/mcp.json`, `.vscode/mcp.json`: a `maz-ui` server entry, added only when no maz-ui MCP server is already registered
+- with `rules: true`, `.claude/rules/maz-ui.md`: a Claude Code rule (skipped when Claude reads `AGENTS.md`, i.e. without `CLAUDE.md`)
+- with `rules: true`, `AGENTS.md`: a section delimited by `<!-- BEGIN:maz-ui -->` and `<!-- END:maz-ui -->`, read by Codex, Cursor, Copilot, Windsurf...
+
+It never overwrites a file it does not own: your `CLAUDE.md`, your own rules and the other MCP servers are left untouched. Commit the generated files to share them with your team. See the [AI agents guide](../guide/ai-agents.md) for details.
+
+## Advanced Theming
+
+### Custom Theme Creation
+
+```ts
+import { definePreset } from '@maz-ui/themes'
+
+export const customTheme = definePreset({
+  base: 'maz-ui',
+  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)',
+      }
+    },
+  },
+})
+
+export default defineNuxtConfig({
+  modules: ['@maz-ui/nuxt'],
+  mazUi: {
+    theme: {
+      preset: customTheme,
+      strategy: 'runtime',
+    }
+  }
+})
+```
+
+**Tip: Subtree Overrides with MazUiProvider**
+
+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
+
+### Theme System Issues
+
+If you encounter the error `"useTheme must be used within MazUi plugin or MazUiTheme plugin installation"`, ensure that:
+
+1. **Enable useTheme composable** in your configuration:
+
+```ts
+export default defineNuxtConfig({
+  mazUi: {
+    composables: {
+      useTheme: true,
+    }
+  }
+})
+```
+
+2. **Theme system is not disabled**:
+
+```ts
+export default defineNuxtConfig({
+  mazUi: {
+    theme: {
+      // theme config, not false
+      preset: 'maz-ui'
+    }
+  }
+})
+```