maz-ui

What this skill does

# Maz-UI v4 - Vue & Nuxt Component Library

Maz-UI is a comprehensive, standalone component library for Vue 3 and Nuxt 3 applications, offering 50+ production-ready components, powerful theming, internationalization, and exceptional developer experience.

**Latest Version**: 4.3.3 (as of 2025-12-29)
**Package**: `maz-ui` | `@maz-ui/nuxt` | `@maz-ui/themes` | `@maz-ui/translations` | `@maz-ui/icons`

## Quick Start

### Vue 3 Installation

```bash
# Install core packages
pnpm add maz-ui @maz-ui/themes

# Or with npm
npm install maz-ui @maz-ui/themes
```

**Setup** in `main.ts`:

```typescript
import { createApp } from 'vue'
import { MazUi } from 'maz-ui/plugins/maz-ui'
import { mazUi } from '@maz-ui/themes'
import { en } from '@maz-ui/translations'
import 'maz-ui/styles'
import App from './App.vue'

const app = createApp(App)

app.use(MazUi, {
  theme: { preset: mazUi },
  translations: { messages: { en } }
})

app.mount('#app')
```

**Use Components**:

```vue
<script setup>
import MazBtn from 'maz-ui/components/MazBtn'
import MazInput from 'maz-ui/components/MazInput'
import { ref } from 'vue'

const inputValue = ref('')
</script>

<template>
  <MazInput v-model="inputValue" label="Name" />
  <MazBtn color="primary">Submit</MazBtn>
</template>
```

###  Nuxt 3 Installation

```bash
# Install Nuxt module
pnpm add @maz-ui/nuxt
```

**Setup** in `nuxt.config.ts`:

```typescript
export default defineNuxtConfig({
  modules: ['@maz-ui/nuxt']
  // That's it! Auto-imports enabled 🎉
})
```

**Use Components** (no imports needed):

```vue
<script setup>
// Auto-imported composables
const theme = useTheme()
const toast = useToast()
const inputValue = ref('')
</script>

<template>
  <!-- Auto-imported components -->
  <MazInput v-model="inputValue" label="Name" />
  <MazBtn color="primary" @click="toast.success('Submitted!')">
    Submit
  </MazBtn>
</template>
```

## Core Capabilities

### 🎨 Components (50+)

**Forms & Inputs**:
- `MazInput` - Text input with validation states
- `MazSelect` - Dropdown select
- `MazTextarea` - Multi-line text input
- `MazCheckbox` - Checkbox with label
- `MazRadio` - Radio buttons
- `MazSwitch` - Toggle switch
- `MazSlider` - Range slider
- `MazInputPhoneNumber` - International phone input with validation
- `MazInputCode` - Code/PIN input
- `MazInputPrice` - Currency input with formatting
- `MazInputTags` - Tag/chip input
- `MazDatePicker` - Date picker
- `MazChecklist` - Searchable checklist

**UI Elements**:
- `MazBtn` - Button with variants
- `MazCard` - Container card
- `MazBadge` - Label badge
- `MazAvatar` - User avatar
- `MazIcon` - Icon display
- `MazSpinner` - Loading spinner
- `MazTable` - Data table with sorting/pagination
- `MazTabs` - Tab navigation
- `MazStepper` - Step indicator
- `MazPagination` - Pagination controls

**Overlays & Modals**:
- `MazDialog` - Modal dialog
- `MazDialogConfirm` - Confirmation dialog
- `MazDrawer` - Slide-out drawer
- `MazBottomSheet` - Mobile bottom sheet
- `MazBackdrop` - Overlay backdrop
- `MazPopover` - Floating popover
- `MazDropdown` - Dropdown menu

**Feedback & Animation**:
- `MazFullscreenLoader` - Loading overlay
- `MazLoadingBar` - Progress bar
- `MazCircularProgressBar` - Circular progress
- `MazReadingProgressBar` - Reading progress indicator
- `MazAnimatedText` - Text animations
- `MazAnimatedElement` - Element animations
- `MazAnimatedCounter` - Number counter animation
- `MazCardSpotlight` - Card with spotlight effect

**Layout & Display**:
- `MazCarousel` - Image carousel
- `MazGallery` - Image gallery
- `MazAccordion` - Collapsible panels
- `MazExpandAnimation` - Expand/collapse animation
- `MazLazyImg` - Lazy-loaded image
- `MazPullToRefresh` - Pull-to-refresh gesture
- `MazChart` - Chart.js integration

### 🔧 Composables (14+)

**Theming**:
- `useTheme()` - Theme and dark mode management

**Translations**:
- `useTranslations()` - i18n management

**UI Interactions**:
- `useToast()` - Toast notifications
- `useDialog()` - Programmatic dialogs
- `useWait()` - Loading states

**Utilities**:
- `useBreakpoints()` - Responsive breakpoints
- `useWindowSize()` - Window dimensions
- `useTimer()` - Timer/countdown
- `useFormValidator()` - Form validation (Valibot)
- `useIdleTimeout()` - Idle detection
- `useUserVisibility()` - Page visibility
- `useSwipe()` - Swipe gestures
- `useReadingTime()` - Reading time calculation
- `useStringMatching()` - String utilities
- `useDisplayNames()` - Localized display names

### 📌 Directives (5)

- `v-tooltip` - Tooltips
- `v-click-outside` - Outside click detection
- `v-lazy-img` - Lazy loading
- `v-zoom-img` - Image zoom
- `v-fullscreen-img` - Fullscreen image viewer

### 🔌 Plugins (4)

- **AOS** - Animations on scroll
- **Dialog** - Template-free dialogs
- **Toast** - Notifications
- **Wait** - Global loading states

## Key Features

✅ **Standalone Components** - Import only what you need, zero bloat
✅ **SSR/SSG Ready** - Full Nuxt 3 support with auto-imports
✅ **TypeScript-First** - Complete type safety out of the box
✅ **Dark Mode** - Built-in dark/light theme switching
✅ **Tree-Shakable** - Optimized bundle sizes
✅ **Responsive** - Mobile-first design
✅ **Accessible** - ARIA-compliant components
✅ **Themeable** - 4 built-in presets + custom themes
✅ **i18n** - Multi-language support with @maz-ui/translations
✅ **840+ Icons** - Optimized SVG icon library (@maz-ui/icons)

## Template Structure

Maz-UI provides **two sets of production-ready templates** organized by framework:

### Vue 3 + Vite Templates (`templates/vue/`)
- ✅ Pure Vue 3 with Vite
- ✅ Uses standard `fetch()` API
- ✅ Explicit imports for all dependencies
- ✅ No framework-specific dependencies
- ✅ Optimized for SPA development

**Use when**: Building Vue 3 applications with Vite

**Available templates**:
- `setup/vite.config.ts` - Vite configuration with auto-imports
- `components/form-basic.vue` - Basic form validation
- `components/form-multi-step.vue` - Multi-step form with stepper
- `components/dialog-confirm.vue` - Dialog confirmation patterns
- `components/data-table.vue` - Data table with pagination, search, sort

### Nuxt 3 Templates (`templates/nuxt/`)
- ✅ Nuxt 3 optimized
- ✅ Uses `$fetch` (Nuxt's ofetch wrapper)
- ✅ Leverages auto-imports for components and composables
- ✅ Showcases SSR patterns and server routes
- ✅ Optimized for full-stack Nuxt development

**Use when**: Building Nuxt 3 applications

**Available templates**:
- `setup/nuxt.config.ts` - Nuxt configuration with Maz-UI module
- `components/form-basic.vue` - Basic form validation (auto-imports)
- `components/form-multi-step.vue` - Multi-step form (auto-imports)
- `components/dialog-confirm.vue` - Dialog patterns (auto-imports)
- `components/data-table.vue` - Data table with reactive data loading

Both template sets:
- ✅ Fix all validation, type inference, and pagination issues
- ✅ Follow framework best practices
- ✅ Are production-ready and fully tested
- ✅ Include setup configs and component examples

## When to Load References

Load reference files based on what you're implementing. All 21 reference files are grouped by purpose for quick discovery:

### Components (4 files)
- **`components-forms.md`** - Building forms, inputs, validation, phone numbers, dates, file uploads, MazInput, MazSelect, MazCheckbox, MazDatePicker
- **`components-feedback.md`** - Adding loaders, progress bars, animations, toasts, MazFullscreenLoader, MazCircularProgressBar, MazAnimatedText, MazCardSpotlight
- **`components-navigation.md`** - Implementing tabs, steppers, pagination, MazTabs, MazStepper, MazPagination
- **`components-layout.md`** - Working with cards, drawers, carousels, galleries, MazCard, MazAccordion, MazDrawer, MazCarousel, MazGallery

### Setup & Configuration (2 files)
- **`setup-vue.md`** - Setting up Maz-UI in Vue 3 project, auto-imports with resolvers, Vite/Webpack configuration, performance optimization
- **`setup-nuxt.md`** - Integrating with Nuxt 3, module configuration, theme strategi