maz-ui 5.0.0 → 5.1.0-beta.0

package/docs/plugins/toast.md

@@ -0,0 +1,221 @@
+---
+title: "Toast"
+description: "A powerful toast notification system for Vue.js that displays user-friendly messages with customizable positioning, styling, and behavior options"
+package: "maz-ui"
+url: "https://maz-ui.com/plugins/toast"
+---
+
+# Toast
+
+> A powerful toast notification system for Vue.js that displays user-friendly messages with customizable positioning, styling, and behavior options
+
+- Package: `maz-ui`
+- Import: `import { ToastPlugin } from 'maz-ui/plugins/toast'`
+- Web: https://maz-ui.com/plugins/toast
+
+**Tip:**
+
+This plugin has a composable for easier use, after installing it you can use [useToast](../composables/use-toast.md)
+
+## Installation
+
+```ts [Vue]
+import { ToastPlugin } from 'maz-ui/plugins/toast'
+import { createApp } from 'vue'
+
+const app = createApp(App)
+
+const toastOptions: ToastOptions = {
+  position: 'bottom-right',
+  timeout: 10_000,
+  persistent: false,
+}
+
+app.use(ToastPlugin, toastOptions)
+app.mount('#app')
+```
+
+```ts [Nuxt]
+export default defineNuxtConfig({
+  modules: ['@maz-ui/nuxt'],
+  mazUi: {
+    composables: {
+      useToast: true,
+    },
+  },
+})
+```
+
+## Basic usage
+
+```vue
+<script lang="ts" setup>
+  import { useToast } from 'maz-ui/composables/useToast'
+
+  const toast = useToast()
+</script>
+
+<template>
+  <MazBtn color="contrast" @click="toast.message('Message text')">
+    Message
+  </MazBtn>
+  <MazBtn color="info" @click="toast.info('Info message', { position: 'top', button: { href: 'https://www.loicmazuel.com' } })">
+    Info toast on top
+  </MazBtn>
+  <MazBtn color="destructive" @click="toast.error('Error message', { position: 'bottom', timeout: 1000 })">
+    Error toast on bottom with 1s timeout
+  </MazBtn>
+  <MazBtn color="warning" @click="toast.warning('Warning message', { position: 'top-right' })">
+    Warning toast on top right
+  </MazBtn>
+  <MazBtn color="contrast" @click="toast.message(`<ul><li>Item <b>1</b></li><li>Item <b>2</b></li><li>Item <b>3</b></li></ul>`, { position: 'bottom-left', html: true })">
+    Toast with html content
+  </MazBtn>
+  <MazBtn color="contrast" @click="toast.message('No timeout toast', { timeout: false })">
+    Persistent with no timeout
+  </MazBtn>
+</template>
+```
+
+### Action and link
+
+Toast can have a link or an action
+
+```vue
+<script lang="ts" setup>
+  import { useToast } from 'maz-ui/composables/useToast'
+
+  const toast = useToast()
+
+  function showInfoWithLink() {
+    toast.info('Toast with link, click -->', {
+      button: {
+        href: 'https://www.loicmazuel.com',
+      }
+    })
+  }
+
+  function showInfoWithExternalLink() {
+    toast.warning('Toast with link', {
+      button: {
+        href: 'https://www.loicmazuel.com',
+        target: '_blank',
+        closeToast: true,
+        text: 'Follow link'
+      }
+    })
+  }
+
+  function showInfoWithAction() {
+    toast.error('Toast with action', {
+      button: {
+        onClick: () => new Promise((resolve) => {
+          sleep(3000)
+          resolve()
+          toast.success('Promise executed')
+        }),
+        text: 'Exec promise',
+        closeToast: true,
+      },
+    })
+  }
+</script>
+
+<template>
+  <MazBtn color="info" @click="showInfoWithLink">
+    Toast with  link
+  </MazBtn>
+  <MazBtn color="warning" @click="showInfoWithExternalLink">
+    Toast with blank link
+  </MazBtn>
+  <MazBtn color="destructive" @click="showInfoWithAction">
+    Toast with action
+  </MazBtn>
+</template>
+```
+
+## Close toast programmatically
+
+You can close a toast programmatically by using the `close` method returned by the `toast` function
+
+```typescript
+function showToast() {
+  const toastMessage = toast.message('Toast message closed by code')
+
+  setTimeout(() => {
+    toastMessage.close()
+  }, 2000)
+}
+```
+
+### Type
+
+```ts
+interface ToastOptions {
+  /**
+   * The position of the toast on the screen
+   * @default 'bottom-right'
+   */
+  position?: ToastPosition
+  /**
+   * The timeout is in ms, it's the time before the toast is automatically closed
+   * if set to `false`, the toast will not be closed automatically
+   * @default 10000
+   */
+  timeout?: number | boolean
+  /**
+   * If the toast is persistent, it can't be closed by user interaction (only on timeout or programmatically)
+   * @default false
+   */
+  persistent?: boolean
+  /**
+   * Display an icon in the toast
+   * @default true
+   */
+  icon?: boolean
+  /**
+   * The action will be displayed as a button in the toast
+   * @default undefined
+   */
+  button?: MazBtnProps & {
+    text: string
+    onClick: () => unknown
+    href?: string
+    text?: string
+    /** @default _self */
+    target?: string
+    /** @default false */
+    closeToast?: boolean
+  }
+  buttons?: (MazBtnProps & {
+    text: string
+    onClick: () => unknown
+    href?: string
+    text?: string
+    /** @default _self */
+    target?: string
+    /** @default false */
+    closeToast?: boolean
+  })[]
+  /**
+   * If the toast is queued, it will be displayed in the order of the toasts
+   * @default false
+   */
+  queue?: boolean
+  /**
+   * The maximum number of toasts to display
+   * @default false
+   */
+  maxToasts?: number | boolean
+  /**
+   * If the toast is paused on hover, it will be paused when the mouse is over the toast
+   * @default true
+   */
+  pauseOnHover?: boolean
+  /**
+   * If the message is HTML
+   * @default false
+   */
+  html?: boolean
+}
+```

package/docs/plugins/wait.md

@@ -0,0 +1,78 @@
+---
+title: "wait"
+description: "A comprehensive loading state management plugin for Vue.js that provides easy-to-use utilities for handling async operations, loading indicators, and user feedback during data processing or any other async operation"
+package: "maz-ui"
+url: "https://maz-ui.com/plugins/wait"
+---
+
+# wait
+
+> A comprehensive loading state management plugin for Vue.js that provides easy-to-use utilities for handling async operations, loading indicators, and user feedback during data processing or any other async operation
+
+- Package: `maz-ui`
+- Import: `import { WaitPlugin } from 'maz-ui/plugins/wait'`
+- Web: https://maz-ui.com/plugins/wait
+
+**Tip:**
+
+This plugin has a composable for easier use, after installing it you can use [useWait](../composables/use-wait.md)
+
+## Installation
+
+```ts [Vue]
+import { WaitPlugin } from 'maz-ui/plugins/wait'
+import { createApp } from 'vue'
+
+const app = createApp(App)
+
+app.use(WaitPlugin)
+app.mount('#app')
+```
+
+```ts [Nuxt]
+export default defineNuxtConfig({
+  modules: ['@maz-ui/nuxt'],
+  mazUi: {
+    composables: {
+      useWait: true,
+    },
+  },
+})
+```
+
+## Basic usage
+
+```vue
+<script lang="ts" setup>
+import { useWait } from 'maz-ui/composables'
+import { ref } from 'vue'
+
+const wait = useWait()
+
+const submitted = ref(false)
+
+function sleep(ms: number) {
+  return new Promise(resolve => setTimeout(resolve, ms))
+}
+
+async function submitData() {
+  submitted.value = false
+  wait.start('DATA_SUBMITTING')
+
+  await sleep(2000)
+
+  submitted.value = true
+  wait.stop('DATA_SUBMITTING')
+}
+</script>
+
+<template>
+  <MazBtn :loading="wait.isLoading('DATA_SUBMITTING')" @click="submitData">
+    Submit Data
+  </MazBtn>
+
+  <div v-if="submitted">
+    Data Submitted
+  </div>
+</template>
+```

package/docs/reference/icons.md

@@ -0,0 +1,46 @@
+# Icons reference
+
+> The 861 icons of `@maz-ui/icons`. Use them instead of inline SVG or another icon library.
+
+## Usage
+
+```vue
+<script setup lang="ts">
+import { MazTrash } from '@maz-ui/icons/static/MazTrash' // one icon, tree-shakable
+import { MazXMark } from '@maz-ui/icons/lazy/MazXMark' // lazy-loaded async component
+</script>
+
+<template>
+  <MazTrash class="size-5 text-destructive" />
+  <MazBtn :start-icon="MazTrash" color="destructive">Delete</MazBtn>
+</template>
+```
+
+- Barrel import: `import { MazTrash, LazyMazTrash } from '@maz-ui/icons'`. Raw SVG string: `import { MazTrash } from '@maz-ui/icons/raw/MazTrash'`.
+- Auto-import with unplugin-vue-components: `import { MazIconsResolver } from '@maz-ui/icons/resolvers'`.
+- maz-ui components accept icons as props (`start-icon`, `end-icon`, `icon`...): pass the component itself, not a string.
+- Size and color come from CSS: `class="size-5 text-primary"` (icons use `currentColor`).
+
+## Interface icons (329)
+
+Heroicons-based outline icons (`MazTrash`, `MazXMark`, `MazMagnifyingGlass`...)
+
+MazAcademicCap, MazAdjustmentsHorizontal, MazAdjustmentsVertical, MazArchiveBox, MazArchiveBoxArrowDown, MazArchiveBoxXMark, MazArrowDown, MazArrowDownCircle, MazArrowDownLeft, MazArrowDownOnSquare, MazArrowDownOnSquareStack, MazArrowDownRight, MazArrowDownTray, MazArrowLeft, MazArrowLeftCircle, MazArrowLeftEndOnRectangle, MazArrowLeftOnRectangle, MazArrowLeftStartOnRectangle, MazArrowLongDown, MazArrowLongLeft, MazArrowLongRight, MazArrowLongUp, MazArrowPath, MazArrowPathRoundedSquare, MazArrowRight, MazArrowRightCircle, MazArrowRightEndOnRectangle, MazArrowRightOnRectangle, MazArrowRightStartOnRectangle, MazArrowSmallDown, MazArrowSmallLeft, MazArrowSmallRight, MazArrowSmallUp, MazArrowsPointingIn, MazArrowsPointingOut, MazArrowsRightLeft, MazArrowsUpDown, MazArrowTopRightOnSquare, MazArrowTrendingDown, MazArrowTrendingUp, MazArrowTurnDownLeft, MazArrowTurnDownRight, MazArrowTurnLeftDown, MazArrowTurnLeftUp, MazArrowTurnRightDown, MazArrowTurnRightUp, MazArrowTurnUpLeft, MazArrowTurnUpRight, MazArrowUp, MazArrowUpCircle, MazArrowUpLeft, MazArrowUpOnSquare, MazArrowUpOnSquareStack, MazArrowUpRight, MazArrowUpTray, MazArrowUturnDown, MazArrowUturnLeft, MazArrowUturnRight, MazArrowUturnUp, MazAtSymbol, MazBackspace, MazBackward, MazBanknotes, MazBars2, MazBars3, MazBars3BottomLeft, MazBars3BottomRight, MazBars3CenterLeft, MazBars4, MazBarsArrowDown, MazBarsArrowUp, MazBattery0, MazBattery100, MazBattery50, MazBeaker, MazBell, MazBellAlert, MazBellSlash, MazBellSnooze, MazBold, MazBolt, MazBoltSlash, MazBookmark, MazBookmarkSlash, MazBookmarkSquare, MazBookOpen, MazBriefcase, MazBugAnt, MazBuildingLibrary, MazBuildingOffice, MazBuildingOffice2, MazBuildingStorefront, MazCake, MazCalculator, MazCalendar, MazCalendarDateRange, MazCalendarDays, MazCamera, MazChartBar, MazChartBarSquare, MazChartPie, MazChatBubbleBottomCenter, MazChatBubbleBottomCenterText, MazChatBubbleLeft, MazChatBubbleLeftEllipsis, MazChatBubbleLeftRight, MazChatBubbleOvalLeft, MazChatBubbleOvalLeftEllipsis, MazCheck, MazCheckBadge, MazCheckCircle, MazChevronDoubleDown, MazChevronDoubleLeft, MazChevronDoubleRight, MazChevronDoubleUp, MazChevronDown, MazChevronLeft, MazChevronRight, MazChevronUp, MazChevronUpDown, MazCircleStack, MazClipboard, MazClipboardDocument, MazClipboardDocumentCheck, MazClipboardDocumentList, MazClock, MazCloud, MazCloudArrowDown, MazCloudArrowUp, MazCodeBracket, MazCodeBracketSquare, MazCog, MazCog6Tooth, MazCog8Tooth, MazCommandLine, MazComputerDesktop, MazCpuChip, MazCreditCard, MazCube, MazCubeTransparent, MazCurrencyBangladeshi, MazCurrencyDollar, MazCurrencyEuro, MazCurrencyPound, MazCurrencyRupee, MazCurrencyYen, MazCursorArrowRays, MazCursorArrowRipple, MazDevicePhoneMobile, MazDeviceTablet, MazDivide, MazDocumentArrowDown, MazDocumentArrowUp, MazDocumentChartBar, MazDocumentCheck, MazDocumentCurrencyBangladeshi, MazDocumentCurrencyDollar, MazDocumentCurrencyEuro, MazDocumentCurrencyPound, MazDocumentCurrencyRupee, MazDocumentCurrencyYen, MazDocumentDuplicate, MazDocumentIcon, MazDocumentMagnifyingGlass, MazDocumentMinus, MazDocumentPlus, MazDocumentText, MazEllipsisHorizontal, MazEllipsisHorizontalCircle, MazEllipsisVertical, MazEnvelope, MazEnvelopeOpen, MazEquals, MazExclamationCircle, MazExclamationTriangle, MazEye, MazEyeDropper, MazEyeSlash, MazFaceFrown, MazFaceSmile, MazFilm, MazFingerPrint, MazFire, MazFlag, MazFolder, MazFolderArrowDown, MazFolderMinus, MazFolderOpen, MazFolderPlus, MazFork, MazForward, MazFunnel, MazGif, MazGift, MazGiftTop, MazGithub, MazGlobeAlt, MazGlobeAmericas, MazGlobeAsiaAustralia, MazGlobeEuropeAfrica, MazH1, MazH2, MazH3, MazHandRaised, MazHandThumbDown, MazHandThumbUp, MazHashtag, MazHeart, MazHome, MazHomeModern, MazIdentification, MazInbox, MazInboxArrowDown, MazInboxStack, MazInformationCircle, MazItalic, MazKey, MazLanguage, MazLifebuoy, MazLightBulb, MazLinkIcon, MazLinkSlash, MazListBullet, MazLockClosed, MazLockOpen, MazMagnifyingGlass, MazMagnifyingGlassCircle, MazMagnifyingGlassMinus, MazMagnifyingGlassPlus, MazMapIcon, MazMapPin, MazMegaphone, MazMicrophone, MazMinus, MazMinusCircle, MazMinusSmall, MazMoon, MazMusicalNote, MazNewspaper, MazNoImage, MazNoSymbol, MazNumberedList, MazPaintBrush, MazPaperAirplane, MazPaperClip, MazPause, MazPauseCircle, MazPencil, MazPencilSquare, MazPercentBadge, MazPhone, MazPhoneArrowDownLeft, MazPhoneArrowUpRight, MazPhoneXMark, MazPhoto, MazPlay, MazPlayCircle, MazPlayPause, MazPlus, MazPlusCircle, MazPlusSmall, MazPower, MazPresentationChartBar, MazPresentationChartLine, MazPrinter, MazPuzzlePiece, MazQrCode, MazQuestionMarkCircle, MazQueueList, MazQuote, MazRadioIcon, MazReceiptPercent, MazReceiptRefund, MazRectangleGroup, MazRectangleStack, MazRocketLaunch, MazRss, MazScale, MazScissors, MazServer, MazServerStack, MazShare, MazShieldCheck, MazShieldExclamation, MazShoppingBag, MazShoppingCart, MazSignal, MazSignalSlash, MazSlash, MazSparkles, MazSpeakerWave, MazSpeakerXMark, MazSquare2Stack, MazSquare3Stack3d, MazSquares2x2, MazSquaresPlus, MazStar, MazStarSolid, MazStop, MazStopCircle, MazStrikethrough, MazSun, MazSwatch, MazTableCells, MazTag, MazTelevision, MazTicket, MazTrash, MazTrophy, MazTruck, MazUnderline, MazUser, MazUserCircle, MazUserGroup, MazUserMinus, MazUserPlus, MazUsers, MazVariable, MazVideoCamera, MazVideoCameraSlash, MazViewColumns, MazViewfinderCircle, MazWallet, MazWifi, MazWindowIcon, MazWrench, MazWrenchScrewdriver, MazXCircle, MazXMark
+
+## Logos (20)
+
+Brand and file-type logos
+
+MazLogoAndroid, MazLogoApple, MazLogoCsv, MazLogoFacebook, MazLogoHtml, MazLogoInstagram, MazLogoJs, MazLogoJson, MazLogoLinkedin, MazLogoMarkdown, MazLogoNpm, MazLogoProperties, MazLogoReact, MazLogoTwitter, MazLogoTxt, MazLogoTypescript, MazLogoVue, MazLogoXliff, MazLogoXls, MazLogoXml
+
+## Country flags (3x2) (256)
+
+`MazFlag` + ISO 3166-1 alpha-2 code in uppercase (`MazFlagFR`, `MazFlagUS`)
+
+MazFlagAC, MazFlagAD, MazFlagAE, MazFlagAF, MazFlagAG, MazFlagAI, MazFlagAL, MazFlagAM, MazFlagAO, MazFlagAQ, MazFlagAR, MazFlagAS, MazFlagAT, MazFlagAU, MazFlagAW, MazFlagAX, MazFlagAZ, MazFlagBA, MazFlagBB, MazFlagBD, MazFlagBE, MazFlagBF, MazFlagBG, MazFlagBH, MazFlagBI, MazFlagBJ, MazFlagBL, MazFlagBM, MazFlagBN, MazFlagBO, MazFlagBQ, MazFlagBR, MazFlagBS, MazFlagBT, MazFlagBV, MazFlagBW, MazFlagBY, MazFlagBZ, MazFlagCA, MazFlagCC, MazFlagCD, MazFlagCF, MazFlagCG, MazFlagCH, MazFlagCI, MazFlagCK, MazFlagCL, MazFlagCM, MazFlagCN, MazFlagCO, MazFlagCR, MazFlagCU, MazFlagCV, MazFlagCW, MazFlagCX, MazFlagCY, MazFlagCZ, MazFlagDE, MazFlagDJ, MazFlagDK, MazFlagDM, MazFlagDO, MazFlagDZ, MazFlagEC, MazFlagEE, MazFlagEG, MazFlagEH, MazFlagER, MazFlagES, MazFlagET, MazFlagEU, MazFlagFI, MazFlagFJ, MazFlagFK, MazFlagFM, MazFlagFO, MazFlagFR, MazFlagGA, MazFlagGB, MazFlagGD, MazFlagGE, MazFlagGEAB, MazFlagGEOS, MazFlagGF, MazFlagGG, MazFlagGH, MazFlagGI, MazFlagGL, MazFlagGM, MazFlagGN, MazFlagGP, MazFlagGQ, MazFlagGR, MazFlagGS, MazFlagGT, MazFlagGU, MazFlagGW, MazFlagGY, MazFlagHK, MazFlagHM, MazFlagHN, MazFlagHR, MazFlagHT, MazFlagHU, MazFlagIC, MazFlagID, MazFlagIE, MazFlagIL, MazFlagIM, MazFlagIN, MazFlagIO, MazFlagIQ, MazFlagIR, MazFlagIS, MazFlagIT, MazFlagJE, MazFlagJM, MazFlagJO, MazFlagJP, MazFlagKE, MazFlagKG, MazFlagKH, MazFlagKI, MazFlagKM, MazFlagKN, MazFlagKP, MazFlagKR, MazFlagKW, MazFlagKY, MazFlagKZ, MazFlagLA, MazFlagLB, MazFlagLC, MazFlagLI, MazFlagLK, MazFlagLR, MazFlagLS, MazFlagLT, MazFlagLU, MazFlagLV, MazFlagLY, MazFlagMA, MazFlagMC, MazFlagMD, MazFlagME, MazFlagMF, MazFlagMG, MazFlagMH, MazFlagMK, MazFlagML, MazFlagMM, MazFlagMN, MazFlagMO, MazFlagMP, MazFlagMQ, MazFlagMR, MazFlagMS, MazFlagMT, MazFlagMU, MazFlagMV, MazFlagMW, MazFlagMX, MazFlagMY, MazFlagMZ, MazFlagNA, MazFlagNC, MazFlagNE, MazFlagNF, MazFlagNG, MazFlagNI, MazFlagNL, MazFlagNO, MazFlagNP, MazFlagNR, MazFlagNU, MazFlagNZ, MazFlagOM, MazFlagPA, MazFlagPE, MazFlagPF, MazFlagPG, MazFlagPH, MazFlagPK, MazFlagPL, MazFlagPM, MazFlagPN, MazFlagPR, MazFlagPS, MazFlagPT, MazFlagPW, MazFlagPY, MazFlagQA, MazFlagRE, MazFlagRO, MazFlagRS, MazFlagRU, MazFlagRW, MazFlagSA, MazFlagSB, MazFlagSC, MazFlagSD, MazFlagSE, MazFlagSG, MazFlagSH, MazFlagSI, MazFlagSJ, MazFlagSK, MazFlagSL, MazFlagSM, MazFlagSN, MazFlagSO, MazFlagSR, MazFlagSS, MazFlagST, MazFlagSV, MazFlagSX, MazFlagSY, MazFlagSZ, MazFlagTA, MazFlagTC, MazFlagTD, MazFlagTF, MazFlagTG, MazFlagTH, MazFlagTJ, MazFlagTK, MazFlagTL, MazFlagTM, MazFlagTN, MazFlagTO, MazFlagTR, MazFlagTT, MazFlagTV, MazFlagTW, MazFlagTZ, MazFlagUA, MazFlagUG, MazFlagUM, MazFlagUS, MazFlagUY, MazFlagUZ, MazFlagVA, MazFlagVC, MazFlagVE, MazFlagVG, MazFlagVI, MazFlagVN, MazFlagVU, MazFlagWF, MazFlagWS, MazFlagXK, MazFlagYE, MazFlagYT, MazFlagZA, MazFlagZM, MazFlagZW
+
+## Country flags (1x1) (256)
+
+`MazFlagSquare` + ISO code (`MazFlagSquareFR`)
+
+MazFlagSquareAC, MazFlagSquareAD, MazFlagSquareAE, MazFlagSquareAF, MazFlagSquareAG, MazFlagSquareAI, MazFlagSquareAL, MazFlagSquareAM, MazFlagSquareAO, MazFlagSquareAQ, MazFlagSquareAR, MazFlagSquareAS, MazFlagSquareAT, MazFlagSquareAU, MazFlagSquareAW, MazFlagSquareAX, MazFlagSquareAZ, MazFlagSquareBA, MazFlagSquareBB, MazFlagSquareBD, MazFlagSquareBE, MazFlagSquareBF, MazFlagSquareBG, MazFlagSquareBH, MazFlagSquareBI, MazFlagSquareBJ, MazFlagSquareBL, MazFlagSquareBM, MazFlagSquareBN, MazFlagSquareBO, MazFlagSquareBQ, MazFlagSquareBR, MazFlagSquareBS, MazFlagSquareBT, MazFlagSquareBV, MazFlagSquareBW, MazFlagSquareBY, MazFlagSquareBZ, MazFlagSquareCA, MazFlagSquareCC, MazFlagSquareCD, MazFlagSquareCF, MazFlagSquareCG, MazFlagSquareCH, MazFlagSquareCI, MazFlagSquareCK, MazFlagSquareCL, MazFlagSquareCM, MazFlagSquareCN, MazFlagSquareCO, MazFlagSquareCR, MazFlagSquareCU, MazFlagSquareCV, MazFlagSquareCW, MazFlagSquareCX, MazFlagSquareCY, MazFlagSquareCZ, MazFlagSquareDE, MazFlagSquareDJ, MazFlagSquareDK, MazFlagSquareDM, MazFlagSquareDO, MazFlagSquareDZ, MazFlagSquareEC, MazFlagSquareEE, MazFlagSquareEG, MazFlagSquareEH, MazFlagSquareER, MazFlagSquareES, MazFlagSquareET, MazFlagSquareEU, MazFlagSquareFI, MazFlagSquareFJ, MazFlagSquareFK, MazFlagSquareFM, MazFlagSquareFO, MazFlagSquareFR, MazFlagSquareGA, MazFlagSquareGB, MazFlagSquareGD, MazFlagSquareGE, MazFlagSquareGEAB, MazFlagSquareGEOS, MazFlagSquareGF, MazFlagSquareGG, MazFlagSquareGH, MazFlagSquareGI, MazFlagSquareGL, MazFlagSquareGM, MazFlagSquareGN, MazFlagSquareGP, MazFlagSquareGQ, MazFlagSquareGR, MazFlagSquareGS, MazFlagSquareGT, MazFlagSquareGU, MazFlagSquareGW, MazFlagSquareGY, MazFlagSquareHK, MazFlagSquareHM, MazFlagSquareHN, MazFlagSquareHR, MazFlagSquareHT, MazFlagSquareHU, MazFlagSquareIC, MazFlagSquareID, MazFlagSquareIE, MazFlagSquareIL, MazFlagSquareIM, MazFlagSquareIN, MazFlagSquareIO, MazFlagSquareIQ, MazFlagSquareIR, MazFlagSquareIS, MazFlagSquareIT, MazFlagSquareJE, MazFlagSquareJM, MazFlagSquareJO, MazFlagSquareJP, MazFlagSquareKE, MazFlagSquareKG, MazFlagSquareKH, MazFlagSquareKI, MazFlagSquareKM, MazFlagSquareKN, MazFlagSquareKP, MazFlagSquareKR, MazFlagSquareKW, MazFlagSquareKY, MazFlagSquareKZ, MazFlagSquareLA, MazFlagSquareLB, MazFlagSquareLC, MazFlagSquareLI, MazFlagSquareLK, MazFlagSquareLR, MazFlagSquareLS, MazFlagSquareLT, MazFlagSquareLU, MazFlagSquareLV, MazFlagSquareLY, MazFlagSquareMA, MazFlagSquareMC, MazFlagSquareMD, MazFlagSquareME, MazFlagSquareMF, MazFlagSquareMG, MazFlagSquareMH, MazFlagSquareMK, MazFlagSquareML, MazFlagSquareMM, MazFlagSquareMN, MazFlagSquareMO, MazFlagSquareMP, MazFlagSquareMQ, MazFlagSquareMR, MazFlagSquareMS, MazFlagSquareMT, MazFlagSquareMU, MazFlagSquareMV, MazFlagSquareMW, MazFlagSquareMX, MazFlagSquareMY, MazFlagSquareMZ, MazFlagSquareNA, MazFlagSquareNC, MazFlagSquareNE, MazFlagSquareNF, MazFlagSquareNG, MazFlagSquareNI, MazFlagSquareNL, MazFlagSquareNO, MazFlagSquareNP, MazFlagSquareNR, MazFlagSquareNU, MazFlagSquareNZ, MazFlagSquareOM, MazFlagSquarePA, MazFlagSquarePE, MazFlagSquarePF, MazFlagSquarePG, MazFlagSquarePH, MazFlagSquarePK, MazFlagSquarePL, MazFlagSquarePM, MazFlagSquarePN, MazFlagSquarePR, MazFlagSquarePS, MazFlagSquarePT, MazFlagSquarePW, MazFlagSquarePY, MazFlagSquareQA, MazFlagSquareRE, MazFlagSquareRO, MazFlagSquareRS, MazFlagSquareRU, MazFlagSquareRW, MazFlagSquareSA, MazFlagSquareSB, MazFlagSquareSC, MazFlagSquareSD, MazFlagSquareSE, MazFlagSquareSG, MazFlagSquareSH, MazFlagSquareSI, MazFlagSquareSJ, MazFlagSquareSK, MazFlagSquareSL, MazFlagSquareSM, MazFlagSquareSN, MazFlagSquareSO, MazFlagSquareSR, MazFlagSquareSS, MazFlagSquareST, MazFlagSquareSV, MazFlagSquareSX, MazFlagSquareSY, MazFlagSquareSZ, MazFlagSquareTA, MazFlagSquareTC, MazFlagSquareTD, MazFlagSquareTF, MazFlagSquareTG, MazFlagSquareTH, MazFlagSquareTJ, MazFlagSquareTK, MazFlagSquareTL, MazFlagSquareTM, MazFlagSquareTN, MazFlagSquareTO, MazFlagSquareTR, MazFlagSquareTT, MazFlagSquareTV, MazFlagSquareTW, MazFlagSquareTZ, MazFlagSquareUA, MazFlagSquareUG, MazFlagSquareUM, MazFlagSquareUS, MazFlagSquareUY, MazFlagSquareUZ, MazFlagSquareVA, MazFlagSquareVC, MazFlagSquareVE, MazFlagSquareVG, MazFlagSquareVI, MazFlagSquareVN, MazFlagSquareVU, MazFlagSquareWF, MazFlagSquareWS, MazFlagSquareXK, MazFlagSquareYE, MazFlagSquareYT, MazFlagSquareZA, MazFlagSquareZM, MazFlagSquareZW

package/docs/reference/tailwind-tokens.md

@@ -0,0 +1,191 @@
+# Tailwind CSS theme reference
+
+> Every Tailwind utility, variant and CSS variable provided by the maz-ui 5.0.1-beta.0 theme. Generated from the `maz-ui/tailwindcss/*.css` sources: it is always in sync with the installed version.
+
+## Setup
+
+```css
+/* your Tailwind entry, e.g. app/assets/css/main.css */
+@import 'tailwindcss';
+@import 'maz-ui/tailwindcss/theme.css';
+@import 'maz-ui/tailwindcss/utilities.css';
+```
+
+- Use the classes **without prefix**: `bg-primary`, `rounded-md`, `tab-m:flex`. The `maz:` prefix you may see in the library sources is internal to maz-ui and does not exist in your project.
+- Every value is a runtime CSS variable driven by the active `@maz-ui/themes` preset: switching preset or color mode restyles every utility without rebuild.
+- See `guide/tailwind.md` to extend the theme (custom colors, fonts, animations, variants).
+
+### Entry points
+
+| Import | Content |
+| --- | --- |
+| `maz-ui/tailwindcss/theme.css` | Every theme token (colors, spacing, radius, breakpoints, shadows, z-index, typography, component surfaces, dark variant) |
+| `maz-ui/tailwindcss/utilities.css` | maz-ui custom utilities (flex-center, padded-container, cap-f, disabled-*...) |
+| `maz-ui/tailwindcss/theme-colors.css` | Colors only |
+| `maz-ui/tailwindcss/theme-spacing.css` | Spacing scale only |
+| `maz-ui/tailwindcss/theme-radius.css` | Border radius only |
+| `maz-ui/tailwindcss/theme-breakpoints.css` | Breakpoints only |
+| `maz-ui/tailwindcss/theme-shadows.css` | Shadows only |
+| `maz-ui/tailwindcss/theme-z-index.css` | z-index scale only |
+| `maz-ui/tailwindcss/theme-typography.css` | Fonts, border width, durations and easings only |
+| `maz-ui/tailwindcss/theme-components.css` | bg-container and bg-input surfaces only |
+| `maz-ui/tailwindcss/theme-variants.css` | `dark:` variant wired to the `.dark` class only |
+
+## Colors
+
+Each color works with every color utility (bg-, text-, border-, ring-, outline-, fill-, stroke-, divide-, from-, via-, to-, decoration-, placeholder-, accent-, caret-, shadow-) and with opacity modifiers (`bg-primary/50`). Colors are light/dark aware (`light-dark()`): **do not add `dark:` overrides for theme colors**.
+
+| Color | Utilities | Foreground | Scale | CSS variable | Use for |
+| --- | --- | --- | --- | --- | --- |
+| `primary` | `bg-primary` `text-primary` `border-primary` | `text-primary-foreground` | `-50` to `-950` | `--maz-primary` | Brand primary: main actions, links, focus |
+| `secondary` | `bg-secondary` `text-secondary` `border-secondary` | `text-secondary-foreground` | `-50` to `-950` | `--maz-secondary` | Brand secondary |
+| `accent` | `bg-accent` `text-accent` `border-accent` | `text-accent-foreground` | `-50` to `-950` | `--maz-accent` | Brand accent, highlights |
+| `destructive` | `bg-destructive` `text-destructive` `border-destructive` | `text-destructive-foreground` | `-50` to `-950` | `--maz-destructive` | Error / danger state, destructive actions |
+| `success` | `bg-success` `text-success` `border-success` | `text-success-foreground` | `-50` to `-950` | `--maz-success` | Success state |
+| `warning` | `bg-warning` `text-warning` `border-warning` | `text-warning-foreground` | `-50` to `-950` | `--maz-warning` | Warning state |
+| `info` | `bg-info` `text-info` `border-info` | `text-info-foreground` | `-50` to `-950` | `--maz-info` | Informational state |
+| `contrast` | `bg-contrast` `text-contrast` `border-contrast` | `text-contrast-foreground` | `-50` to `-950` | `--maz-contrast` | Neutral high-contrast color (near black in light mode, near white in dark mode) |
+| `surface` | `bg-surface` `text-surface` `border-surface` | - | `-50` to `-950` | `--maz-surface` | Page and container backgrounds |
+| `foreground` | `bg-foreground` `text-foreground` `border-foreground` | - | `-50` to `-950` | `--maz-foreground` | Body text |
+| `divider` | `bg-divider` `text-divider` `border-divider` | - | `-50` to `-950` | `--maz-divider` | Borders and separators |
+| `shadow` | `shadow-shadow/20` `bg-shadow` | - | `-50` to `-950` | `--maz-shadow` | Shadow tint (used by the shadow-* utilities) |
+| `overlay` | `bg-overlay` `bg-overlay/60` | - | `-50` to `-950` | `--maz-overlay` | Backdrops and scrims behind dialogs |
+| `muted` | `bg-muted` `text-muted` `border-muted` | - | `-50` to `-950` | `--maz-muted` | Secondary text, placeholders, disabled content |
+| `container` | `bg-container` | - | - | `--maz-container-bg` | Background of MazCard, MazContainer, MazDialog, MazPopover, MazDrawer... (follows the preset `components.container`) |
+| `input` | `bg-input` | - | - | `--maz-input-bg` | Background of MazInput, MazSelect, MazTextarea, MazCheckbox... (follows the preset `components.input`) |
+
+- `-foreground` is the readable text color on top of the base color: `bg-primary text-primary-foreground`.
+- Scales go from light (`-50`) to dark (`-950`), `-500` is the base color. They are derived from the base color in OKLCh, so they follow the preset.
+- Never use the Tailwind default palette (`bg-blue-500`, `text-gray-600`, `bg-white`, `text-black`) nor hard-coded colors (`#fff`, `rgb()`): pick the matching theme color (`bg-surface`, `text-foreground`, `text-muted`, `border-divider`, `bg-primary`...).
+
+## Border radius
+
+| Utility | Value |
+| --- | --- |
+| `rounded-xs` | `var(--maz-rounded-xs)` |
+| `rounded-sm` | `var(--maz-rounded-sm)` |
+| `rounded-md` | `var(--maz-rounded-md)` |
+| `rounded-lg` | `var(--maz-rounded-lg)` |
+| `rounded-xl` | `var(--maz-rounded-xl)` |
+| `rounded-2xl` | `var(--maz-rounded-2xl)` |
+| `rounded-3xl` | `var(--maz-rounded-3xl)` |
+| `rounded` | `var(--maz-rounded-md)` |
+
+`rounded-full` and `rounded-none` keep their Tailwind values.
+
+## Shadows
+
+| Utility | Value |
+| --- | --- |
+| `shadow-xs` | `0 1px 2px 0 color-mix(in srgb, var(--color-elevation) 5%, transparent)` |
+| `shadow-sm` | `var(--maz-shadow-style-sm)` |
+| `shadow-md` | `var(--maz-shadow-style-md)` |
+| `shadow-lg` | `var(--maz-shadow-style-lg)` |
+| `shadow-xl` | `var(--maz-shadow-style-xl)` |
+| `shadow-elevation` | `var(--maz-shadow-style-elevation)` |
+
+Use `shadow-elevation` for raised surfaces (cards, popovers, menus).
+
+## Spacing
+
+`--spacing` is `var(--maz-space)` (`0.25rem` by default): every spacing utility (`p-4`, `gap-2`, `mt-6`, `w-10`, `inset-1`...) is a multiple of the preset `space` token. Use the scale, avoid arbitrary values like `p-[13px]`.
+
+## Breakpoints
+
+Mobile-first `min-width` variants, added on top of the Tailwind defaults (`sm:` to `2xl:` still work). Prefix them with `max-` for max-width queries (`max-tab-m:hidden`).
+
+| Variant | Min width |
+| --- | --- |
+| `mob-s:` | 320px |
+| `mob-m:` | 425px |
+| `mob-l:` | 576px |
+| `tab-s:` | 640px |
+| `tab-m:` | 768px |
+| `tab-l:` | 992px |
+| `lap-s:` | 1024px |
+| `lap-m:` | 1280px |
+| `lap-l:` | 1366px |
+| `lap-xl:` | 1440px |
+| `lap-2xl:` | 1680px |
+| `lap-3xl:` | 1920px |
+
+In TypeScript: `import { screens } from 'maz-ui/tailwindcss'`, or the `useBreakpoints` composable.
+
+## Typography and motion
+
+| Utility | Value |
+| --- | --- |
+| `font-sans` | `var(--maz-font-family)` |
+| `font-mono` | `var(--maz-font-mono-stack)` |
+| `font-display` | `var(--maz-font-display-stack)` |
+| `duration-(--duration-fast)` | `var(--maz-motion-fast, 100ms)` |
+| `duration-(--duration-normal)` | `var(--maz-motion-normal, 200ms)` |
+| `duration-(--duration-slow)` | `var(--maz-motion-slow, 300ms)` |
+| `ease-out` | `var(--maz-easing-out, cubic-bezier(0.4, 0, 0.2, 1))` |
+| `ease-in` | `var(--maz-easing-in, cubic-bezier(0.4, 0, 1, 1))` |
+| `ease-in-out` | `var(--maz-easing-in-out, cubic-bezier(0.4, 0, 0.2, 1))` |
+
+- The default border width and the default transition duration and easing also follow the preset.
+- Durations are theme variables, use them with the arbitrary syntax: `transition-colors duration-(--duration-fast)`.
+
+## z-index
+
+| Utility | Value |
+| --- | --- |
+| `z-1` | `1` |
+| `z-2` | `2` |
+| `z-3` | `3` |
+| `z-4` | `4` |
+| `z-5` | `5` |
+| `z-15` | `15` |
+| `z-25` | `25` |
+| `z-35` | `35` |
+| `z-45` | `45` |
+| `z-75` | `75` |
+| `z-100` | `100` |
+| `z-default-backdrop` | `1050` |
+
+## Custom utilities
+
+From `maz-ui/tailwindcss/utilities.css`:
+
+| Utility | CSS |
+| --- | --- |
+| `flex-center` | `align-items: center; justify-content: center;` |
+| `z-default-backdrop` | `z-index: 1050;` |
+| `padded-container-no-p` | `inline-size: 100%; padding-inline: calc(50% - var(--maz-container-max-width) / 2);` |
+| `padded-container` | `inline-size: 100%; padding-inline: var(--maz-container-padding);` |
+| `cap-f` | `&::first-letter { text-transform: capitalize; }` |
+| `disabled-cursor` | `cursor: var(--maz-disabled-cursor);` |
+| `disabled-opacity` | `opacity: var(--maz-disabled-opacity);` |
+| `disabled-state` | `cursor: var(--maz-disabled-cursor); opacity: var(--maz-disabled-opacity);` |
+
+## Variants
+
+| Variant | Selector |
+| --- | --- |
+| `dark:` | `&:where(.dark, .dark *)` |
+
+`dark:` matches the `.dark` class toggled by `useTheme()` (`darkModeStrategy: 'class'`, the default). Theme colors already adapt to dark mode: keep `dark:` for real layout or content differences.
+
+## Layout variables
+
+Override them in your CSS (`:root { --maz-container-max-width: 1024px; }`), they drive the `padded-container` utilities:
+
+| Variable | Default |
+| --- | --- |
+| `--maz-container-padding-mobile` | `1rem` |
+| `--maz-container-padding-tablet` | `2rem` |
+| `--maz-container-padding-desktop` | `2.5rem` |
+| `--maz-container-padding-value` | `var(--maz-container-padding-mobile)` |
+| `--maz-container-width` | `calc(100% - var(--maz-container-padding-value) * 2)` |
+| `--maz-container-padding` | `calc(50% - var(--maz-container-width) / 2)` |
+| `--maz-container-max-width` | `1440px` |
+
+## Vue transitions
+
+Transition names shipped in `maz-ui/style.css`, usable with `<Transition name="...">`: `maz-expand`, `maz-scale`, `maz-scale-fade`, `maz-scale-loading`, `maz-slide`, `maz-slideinvert`, `maz-slidevnext`, `maz-slidevprev`, `maz-tags`, `maz-tags-invert`.
+
+## CSS variables in custom CSS
+
+In `<style>` blocks or plain CSS, use the runtime variables instead of literal values: `var(--maz-primary)`, `var(--maz-surface)`, `var(--maz-foreground)`, `var(--maz-divider)`, `var(--maz-rounded-md)`, `var(--maz-shadow-style-elevation)`, `calc(var(--maz-space) * 4)`, `var(--maz-font-family)`, `var(--maz-easing-out)`. With Tailwind, prefer `@apply` after `@reference "<your tailwind entry>"` in Vue SFC style blocks.

package/docs/rules.md

@@ -0,0 +1,57 @@
+---
+title: "maz-ui rules for AI agents"
+description: "How to use maz-ui and its ecosystem in this project: look-up workflow, components, icons, helpers, Tailwind theme tokens, imports."
+---
+
+# maz-ui rules for AI agents
+
+> maz-ui 5.0.1-beta.0 is installed: these rules and the docs in `node_modules/maz-ui/docs` match this version.
+
+This project is built with **maz-ui** and its ecosystem (`@maz-ui/themes`, `@maz-ui/icons`, `@maz-ui/utils`, `@maz-ui/translations`, `@maz-ui/nuxt`). Reuse what it provides instead of re-implementing it: most UI elements, helpers, icons and styles you need already exist.
+
+### Look it up before you write it
+
+Before creating a component, composable, helper, icon or style, check what maz-ui offers:
+
+- **MCP server `maz-ui`** (when available): `search_docs` (describe the need: "confirm before delete", "phone input"), `get_component_api` (exact props, events, slots), `find_icons`, `get_theme_tokens` (Tailwind classes), `get_doc`, `review_code`.
+- **Version-matched docs** in `node_modules/maz-ui/docs/` (start with `README.md`; in a monorepo, resolve `maz-ui` from the app package). Read the relevant page before using an API.
+
+Never guess an API: only use props, events, slots and imports that are documented.
+
+### Components
+
+- Use `Maz*` components instead of native elements or hand-made widgets: `MazBtn` (not `<button>`), `MazInput`, `MazSelect`, `MazCheckbox`, `MazSwitch`, `MazTextarea`, `MazDialog`, `MazDialogConfirm`, `MazDrawer`, `MazBottomSheet`, `MazPopover`, `MazDropdown`, `MazTabs`, `MazTable`, `MazCard`, `MazAvatar`, `MazBadge`, `MazAlert`, `MazSkeleton`, `MazSpinner`, `MazDatePicker`, `MazInputPhoneNumber`, `MazDropzone`, `MazStepper`, `MazSidebar`, `MazPagination`...
+- Prop values are typed: colors are `primary | secondary | accent | info | success | warning | destructive | contrast | transparent` (plus `surface` on some components), sizes `mini | xs | sm | md | lg | xl`.
+- Feedback and overlays: `useToast()` for notifications, `useDialog()` or `MazDialogConfirm` for confirmations, `useWait()` for loading states.
+- Forms: `useFormValidator` / `useFormField` with your Standard Schema library (Zod, Valibot, ArkType).
+
+### Icons
+
+Use `@maz-ui/icons` (860+ icons: `MazTrash`, `MazXMark`, `MazMagnifyingGlass`, `MazFlagFR`, `MazLogoVue`...). Never inline SVG or add another icon library. Pass icon components to icon props: `<MazBtn :start-icon="MazTrash">`.
+
+### Helpers and composables
+
+Use `@maz-ui/utils` and maz-ui composables instead of lodash, VueUse or hand-written code: `debounce`, `throttle`, `sleep`, `isEqual`, `capitalize`, `formatCurrency`, `formatDate`, `formatNumber`, `formatPhoneNumber`, `getCookie`/`setCookie`, `useBreakpoints`, `useWindowSize`, `useTimer`, `useIdleTimeout`, `useSwipe`, `vClickOutside`, `vTooltip`, `vLazyImg`...
+
+### Styling with Tailwind
+
+The maz-ui theme is exposed to Tailwind (`@import 'maz-ui/tailwindcss/theme.css'`). Only use its tokens:
+
+- Colors: `primary`, `secondary`, `accent`, `info`, `success`, `warning`, `destructive`, `contrast` (each with `-foreground` and `-50` to `-950`), `surface`, `foreground`, `muted`, `divider`, `overlay`, plus `bg-container` and `bg-input`. Example: `bg-surface text-foreground border-divider`, `bg-primary text-primary-foreground`, `text-muted`.
+- Never use the default Tailwind palette (`bg-blue-500`, `text-gray-600`, `bg-white`, `text-black`) nor hard-coded colors (`#fff`, `rgb()`, `bg-[#...]`). Theme colors already adapt to dark mode: do not add `dark:` color overrides.
+- Radius `rounded-*`, shadows `shadow-sm` to `shadow-xl` and `shadow-elevation`, spacing scale (`p-4`, `gap-2`), breakpoints `mob-*`, `tab-*`, `lap-*` (plus `sm` to `2xl`), utilities `flex-center`, `padded-container`.
+- **No `maz:` prefix** in this project: it is internal to the maz-ui library and its documentation.
+- In custom CSS, use the variables: `var(--maz-primary)`, `var(--maz-rounded-md)`, `calc(var(--maz-space) * 4)`.
+
+### Theme
+
+Brand colors, fonts, radius and spacing come from a `@maz-ui/themes` preset (`definePreset`), not from overrides scattered in CSS. Use `useTheme()` for dark mode and presets (`toggleDarkMode`, `setColorMode`, `updateTheme`), never toggle the `dark` class or store the mode yourself.
+
+### Imports
+
+- Deep imports: `maz-ui/components/MazBtn`, `maz-ui/composables/useToast`, `maz-ui/directives/vTooltip`, `@maz-ui/utils/helpers/debounce`, `@maz-ui/icons/static/MazTrash`. The `maz-ui` root entry only exports types. Never import from `maz-ui/src` or `maz-ui/dist`.
+- With `@maz-ui/nuxt`, components and composables are auto-imported: do not import them.
+
+### Before you finish
+
+Run `review_code` (MCP) on the files you changed, or `npx @maz-ui/mcp review <files>`, and fix every finding.