@maz-ui/mcp 5.0.1-beta.0 → 5.1.0-beta.0

package/docs/components/maz-avatar.md

@@ -0,0 +1,193 @@
+---
+title: "MazAvatar"
+description: "MazAvatar is a standalone component that displays an image or an icon with a caption. It can be used to display a user's profile picture, a placeholder image, or an icon."
+package: "maz-ui"
+url: "https://maz-ui.com/components/maz-avatar"
+---
+
+# MazAvatar
+
+> MazAvatar is a standalone component that displays an image or an icon with a caption. It can be used to display a user's profile picture, a placeholder image, or an icon.
+
+- Package: `maz-ui`
+- Import: `import MazAvatar from 'maz-ui/components/MazAvatar'`
+- Nuxt: auto-imported by `@maz-ui/nuxt`, no import needed in a Nuxt app
+- Web: https://maz-ui.com/components/maz-avatar
+
+> Before use it, you should install the MazUi plugin in your project, follow instructions in [Getting Started](../guide/getting-started.md)
+
+**Tip:**
+
+This component uses [vLazyImg](../directives/lazy-img.md) directive
+
+## Basic usage
+
+```vue
+<script lang="ts" setup>
+import MazAvatar from 'maz-ui/components/MazAvatar'
+</script>
+
+<template>
+  <MazAvatar src="https://api.dicebear.com/7.x/big-smile/svg?backgroundColor=1d90ff&scale=80" />
+</template>
+```
+
+## Options
+
+**Tip:**
+
+See all the options props here
+
+```vue
+<script lang="ts" setup>
+import MazAvatar from 'maz-ui/components/MazAvatar'
+function clicked() { console.log('clicked') }
+</script>
+
+<template>
+  <MazAvatar
+    caption="Louis Mazel"
+    size="1.5rem"
+  />
+  <MazAvatar
+    src="https://api.dicebear.com/7.x/big-smile/svg?backgroundColor=1d90ff&scale=80&seed=maz-ui"
+    size="2rem"
+    href="https://api.dicebear.com/7.x/big-smile/svg?backgroundColor=1d90ff&scale=80&seed=maz-ui"
+    target="_blank"
+    rounded-size="none"
+    clickable
+  >
+    <template #icon>
+      <MazIcon icon="/eye.svg" />
+    </template>
+  </MazAvatar>
+  <MazAvatar
+    src="https://api.dicebear.com/7.x/big-smile/svg?backgroundColor=1d90ff&scale=80&seed=200"
+    size="2.5rem"
+    clickable
+    rounded-size="xl"
+    @click="clicked"
+  />
+  <MazAvatar
+    src="https://api.dicebear.com/7.x/big-smile/svg?backgroundColor=1d90ff&scale=80&seed=600"
+    size="3rem"
+    bordered
+  />
+</template>
+```
+
+## Initials from caption
+
+When no `src` is provided, `MazAvatar` displays initials generated from the `caption`. The `letter-count` prop (default `2`) controls how many letters are displayed:
+
+- **Single word**: the first `letter-count` characters of the word are used.
+- **Multiple words**: the first letter of each of the first `letter-count` words is used.
+
+Initials are always uppercased.
+
+```vue
+<template>
+  <!-- "AD" -->
+  <MazAvatar caption="admin" />
+  <!-- "ADM" -->
+  <MazAvatar caption="admin" :letter-count="3" />
+  <!-- "LM" -->
+  <MazAvatar caption="Louis Mazel" />
+  <!-- "JCD" -->
+  <MazAvatar caption="Jean Claude Dus" :letter-count="3" />
+</template>
+```
+
+## On Error
+
+When no `src` (and no `caption`) is provided, or when the image fails to load, `MazAvatar` displays the default `no-image` placeholder.
+
+```html
+<MazAvatar @error="error" src="https://broken-link-image-src.example" />
+```
+
+## Fallback image loaded on error
+
+```html
+<MazAvatar
+  src="https://broken-link-image-src.com"
+  fallback-src="https://api.dicebear.com/7.x/big-smile/svg?backgroundColor=1d90ff&scale=80&seed=100"
+/>
+```
+
+## Loading
+
+The props `loading` has 3 possible values: `intersecting`, `lazy`, or `eager`.
+
+By default, the value is `intersecting` which means the image will be loaded when it's intersecting with the `IntersectionObserver` browser API. This mode uses the [`MazLazyImg`](./maz-lazy-img.md) component with [`vLazyImg`](../directives/lazy-img.md) directive to handle the lazy loading.
+
+Native modes:
+
+- `lazy`: The image will be loaded only when it's in the viewport
+- `eager`: The image will be loaded immediately
+
+These modes are native use an `HTMLImageElement` with the `loading` attribute. (see [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#attr-loading)). **Useful for SSR (Server Side Rendering) or when you want to load the image immediately.**
+
+```html
+<MazAvatar
+  loading="intersecting"
+  src="https://api.dicebear.com/7.x/big-smile/svg?backgroundColor=1d90ff&scale=80&seed=123"
+/>
+<MazAvatar loading="lazy" src="https://api.dicebear.com/7.x/big-smile/svg?backgroundColor=1d90ff&scale=80&seed=123" />
+<MazAvatar loading="eager" src="https://api.dicebear.com/7.x/big-smile/svg?backgroundColor=1d90ff&scale=80&seed=123" />
+```
+
+## Image height full
+
+By default the image fills the avatar **width** (`width: 100%`). Enable `image-height-full` to make the image fill the **height** instead: it keeps its aspect ratio, fills 100% of the height and overflows/crops horizontally. This is ideal for wide images or SVGs (like flags) that must cover the whole avatar.
+
+```vue
+<template>
+  <!-- default: width 100% -->
+  <MazAvatar src="https://placedog.net/300/200" />
+  <!-- height 100%, cropped on the sides -->
+  <MazAvatar image-height-full src="https://placedog.net/300/200" />
+</template>
+```
+
+## MazAvatar API
+
+`import MazAvatar from 'maz-ui/components/MazAvatar'`
+
+### Props
+
+- `src` (`string | null`): The source of the image.
+- `caption` (`string | null`): The caption of the avatar.
+- `href` (`string`): The link of the avatar.
+- `to` (`string | Record<string, unknown>`): The link (router-link or nuxt-link) of the avatar.
+- `alt` (`string`, default: `"avatar image"`): The alt of the image.
+- `target` (`string`, default: `"_self"`): The target of the link.
+- `size` (`` `${number}rem` | `${number}px` | `${number}em` | `${number}vw` | `${number}vh` | `${number}vmin` | `${number}vmax` | `${number}%` | `${number}ch` | `${number}cm` | `${number}mm` | `${number}in` | `${number}ex` | `${number}pc` | `${number... ``): The size of the avatar - a keyword from `MazSize` or any CSS size unit. Values: `'mini'`, `'xs'`, `'sm'`, `'md'`, `'lg'`, `'xl'`, `'2rem'`, `'48px'` (non exhaustive).
+- `bordered` (`boolean`): Add a border to the avatar.
+- `clickable` (`boolean`): Make the avatar clickable.
+- `square` (`boolean`): Make the avatar square.
+- `no-elevation` (`boolean`): Remove the shadow.
+- `show-caption` (`boolean`): Show the caption.
+- `image-height-full` (`boolean`): Make the image height full.
+- `hide-loader` (`boolean`): Remove the loader.
+- `button-color` (`"primary" | "secondary" | "accent" | "info" | "success" | "warning" | "destructive" | "contrast" | "transparent"`, default: `"info"`): The color of the clickable button.
+- `hide-clickable-icon` (`boolean`): Remove the icon on hover when component is clickable.
+- `letter-count` (`number`, default: `2`): Number of letters to display in the round text initials. - For a single-word caption, the first `letterCount` characters are used (`'admin'` + `3` -> `'ADM'`). - For a multi-word caption, the first letter of the first `letterCount` words is used (`'Louis Mazel'` -> `'LM'`).
+- `rounded-size` (`MazRoundedSize`): Size of the rounded. Values: `'none'`, `'sm'`, `'md'`, `'lg'`, `'xl'`, `'full'` (non exhaustive).
+- `fallback-src` (`string`): The fallback src to replace the src on loading error.
+- `loading` (`"intersecting" | "lazy" | "eager"`, default: `"intersecting"`): The loading strategy of the image - lazy, eager or intersecting.
+- `color` (`"primary" | "secondary" | "accent" | "info" | "success" | "warning" | "destructive" | "contrast" | "transparent"`, default: `"primary"`): The color of the avatar.
+
+### Events
+
+- `@click` (payload: `event: MouseEvent`): Emitted when the avatar is clicked
+- `@intersecting` (payload: `el: Element`): Emitted when the image is intersecting
+- `@loading` (payload: `el: Element`): Emitted when the image is loading
+- `@loaded` (payload: `el: Element`): Emitted when the image is loaded
+- `@error` (payload: `el: Element`): Emitted when the image is in error
+
+### Slots
+
+- `#round-text`: Replace the initials displayed when a caption is set and no image source is provided
+- `#icon`: The icon displayed on the clickable button overlay (shown on hover/focus)
+- `#caption`: Replace the caption displayed below the avatar (requires `showCaption`)

package/docs/components/maz-backdrop.md

@@ -0,0 +1,178 @@
+---
+title: "MazBackdrop"
+description: "MazBackdrop is a flexible backdrop component that provides a foundation for modals, drawers, bottom sheets and any overlay content. It handles focus management, keyboard navigation, and animations automatically."
+package: "maz-ui"
+url: "https://maz-ui.com/components/maz-backdrop"
+---
+
+# MazBackdrop
+
+> MazBackdrop is a flexible backdrop component that provides a foundation for modals, drawers, bottom sheets and any overlay content. It handles focus management, keyboard navigation, and animations automatically.
+
+- Package: `maz-ui`
+- Import: `import MazBackdrop from 'maz-ui/components/MazBackdrop'`
+- Nuxt: auto-imported by `@maz-ui/nuxt`, no import needed in a Nuxt app
+- Web: https://maz-ui.com/components/maz-backdrop
+
+> Before use it, you should install the MazUi plugin in your project, follow instructions in [Getting Started](../guide/getting-started.md)
+
+**Tip:**
+
+This component uses `<Teleport to="body">` and is the foundation for [MazDialog](./maz-dialog.md), [MazDrawer](./maz-drawer.md), and [MazBottomSheet](./maz-bottom-sheet.md)
+
+## Basic usage
+
+MazBackdrop creates a semi-transparent overlay that covers the entire screen. Think of it like a dark blanket that appears behind your content to make it stand out.
+
+```vue
+<script setup>
+import MazBackdrop from 'maz-ui/components/MazBackdrop'
+import { ref } from 'vue'
+
+const basicOpen = ref(false)
+</script>
+
+<template>
+  <MazBtn @click="basicOpen = true">
+    Open Backdrop
+  </MazBtn>
+
+  <MazBackdrop v-model="basicOpen" justify="center" align="center">
+    <div class="my-content">
+      <h3>Hello! I'm on top of the backdrop</h3>
+      <p>Click outside or press Escape to close</p>
+      <MazBtn @click="basicOpen = false">Close</MazBtn>
+    </div>
+  </MazBackdrop>
+</template>
+
+<style lang="css" scoped>
+.demo-content {
+  background: var(--maz-surface);
+  padding: 2rem;
+  border-radius: var(--maz-rounded-md);
+  box-shadow: 0 10px 25px rgba(0, 0, 0, 0.1);
+  max-width: 400px;
+  text-align: center;
+}
+
+.demo-content h3 {
+  margin-top: 0;
+}
+
+.demo-content p {
+  margin-bottom: 1.5rem;
+  color: var(--maz-muted);
+}
+</style>
+```
+
+## Persistent backdrop
+
+A persistent backdrop cannot be closed by clicking outside or pressing Escape. Perfect for important confirmations!
+
+```html
+<MazBackdrop v-model="persistentOpen" persistent align="center" justify="center">
+  <div class="my-content">
+    <h3>I'm persistent!</h3>
+    <p>You can only close me by clicking the button below</p>
+    <MazBtn @click="persistentOpen = false" color="destructive">
+      Force Close
+    </MazBtn>
+  </div>
+</MazBackdrop>
+```
+
+## Content positioning
+
+You can control where your content appears using `justify` and `align` props. It's like choosing where to place a sticker on your screen!
+
+```html
+<!-- Top Left -->
+<MazBackdrop v-model="topLeftOpen" justify="start" align="start" content-padding>
+  <div class="my-content">
+    <h3>I'm at the top left!</h3>
+    <MazBtn @click="topLeftOpen = false">Close</MazBtn>
+  </div>
+</MazBackdrop>
+
+<!-- Center -->
+<MazBackdrop v-model="centerOpen" justify="center" align="center" content-padding>
+  <div class="my-content">
+    <h3>I'm perfectly centered!</h3>
+    <MazBtn @click="centerOpen = false">Close</MazBtn>
+  </div>
+</MazBackdrop>
+
+<!-- Bottom Right -->
+<MazBackdrop v-model="bottomRightOpen" justify="end" align="end" content-padding>
+  <div class="my-content">
+    <h3>I'm at the bottom right!</h3>
+    <MazBtn @click="bottomRightOpen = false">Close</MazBtn>
+  </div>
+</MazBackdrop>
+```
+
+## Custom animations
+
+MazBackdrop comes with built-in animations, but you can customize them with the `transition-name` prop.
+
+```html
+<MazBackdrop v-model="animatedOpen" transition-name="modal-anim">
+  <div class="my-content">
+    <h3>I slide and scale in!</h3>
+    <p>This uses the same animation as MazDialog</p>
+    <MazBtn @click="animatedOpen = false">Close</MazBtn>
+  </div>
+</MazBackdrop>
+```
+
+## Accessibility features
+
+MazBackdrop automatically handles:
+- **Focus trap**: Tab navigation stays within your content
+- **Keyboard support**: Escape key to close (unless persistent)
+- **Screen readers**: Proper ARIA attributes for accessibility
+- **Scroll lock**: Prevents background scrolling when open
+
+These features work automatically - you don't need to do anything extra!
+
+## MazBackdrop API
+
+`import MazBackdrop from 'maz-ui/components/MazBackdrop'`
+
+### Props
+
+- `model-value` (`boolean`, default: `false`, `v-model`): Modal's model value.
+- `teleport-selector` (`string`, default: `"body"`): Teleport selector.
+- `before-close` (`(() => void | Promise<void>)`): Function called before modal is close.
+- `persistent` (`boolean`, default: `false`): Persistent dialog (not closable by clicking outside and remove close button).
+- `close-on-escape` (`boolean`, default: `true`): Prevent close on escape key.
+- `transition-name` (`string`, default: `"backdrop-anim"`): Transition name.
+- `backdrop-class` (`ClassValue`): Backdrop class.
+- `backdrop-content-class` (`ClassValue`): Backdrop content class.
+- `content-padding` (`boolean`, default: `false`): Add padding to the content.
+- `justify` (`"none" | "center" | "end" | "start" | "space-between" | "space-around"`, default: `"none"`): Justify content.
+- `align` (`"none" | "center" | "end" | "start"`, default: `"none"`): Align content.
+- `variant` (`"bottom-sheet" | "dialog" | "drawer"`): Variant.
+- `aria-labelledby` (`string`): ID for aria-labelledby.
+- `aria-describedby` (`string`): ID for aria-describedby.
+
+### Events
+
+- `@update:model-value` (payload: `value: boolean`): Emitted when modal is open or close
+- `@open` (payload: `value?: void | undefined`): Emitted when modal is open
+- `@close` (payload: `value?: void | undefined`): Emitted when modal is close
+- `@before-close` (payload: `value?: void | undefined`): Emitted before modal is close
+
+### Slots
+
+- `#default`: Place your content here Bindings: `close: () => void` (close function).
+
+### Exposed (template ref)
+
+- `onBackdropAnimationLeave`: Animation leave event
+- `close`: Close the backdrop
+- `present`: The present state of the backdrop
+- `toggleModal`: Toggle the backdrop
+- `onKeyPress`: Key press event

package/docs/{src/components → components}/maz-badge.md

@@ -1,19 +1,22 @@
 ---
-title: MazBadge
-description: MazBadge is a standalone component to show short text in colored container
+title: "MazBadge"
+description: "MazBadge is a standalone component to show short text in colored container"
+package: "maz-ui"
+url: "https://maz-ui.com/components/maz-badge"
 ---
 
-# {{ $frontmatter.title }}
+# MazBadge
 
-{{ $frontmatter.description }}
+> MazBadge is a standalone component to show short text in colored container
 
-<!--@include: ./../../.vitepress/mixins/getting-started.md-->
+- Package: `maz-ui`
+- Import: `import MazBadge from 'maz-ui/components/MazBadge'`
+- Nuxt: auto-imported by `@maz-ui/nuxt`, no import needed in a Nuxt app
+- Web: https://maz-ui.com/components/maz-badge
 
-## Basic usage
+> Before use it, you should install the MazUi plugin in your project, follow instructions in [Getting Started](../guide/getting-started.md)
 
-<MazBadge>
-  Badge
-</MazBadge>
+## Basic usage
 
 ```vue
 <script lang="ts" setup>
@@ -29,18 +32,10 @@ description: MazBadge is a standalone component to show short text in colored co
 
 ## Options
 
-> See all options props [here](#props)
+> See all options props here
 
 ### Colors
 
-<br />
-
-<div class="flex space-between gap-05 items-center flex-wrap">
-  <MazBadge v-for="color in colors" :key="color" :color="color">
-    {{ color }}
-  </MazBadge>
-</div>
-
 ```vue
 <script lang="ts" setup>
   import MazBadge from 'maz-ui/components/MazBadge'
@@ -68,14 +63,6 @@ description: MazBadge is a standalone component to show short text in colored co
 
 ### Outlined
 
-<br />
-
-<div class="flex space-between gap-05 items-center flex-wrap">
-  <MazBadge v-for="color in colors" :key="color" :color="color" outlined>
-    {{ color }}
-  </MazBadge>
-</div>
-
 ```vue
 <script lang="ts" setup>
 import MazBadge from 'maz-ui/components/MazBadge'
@@ -103,14 +90,6 @@ const colors = [
 
 ### Pastel
 
-<br />
-
-<div class="flex space-between gap-05 items-center flex-wrap">
-  <MazBadge v-for="color in colors" :key="color" :color="color" pastel>
-    {{ color }}
-  </MazBadge>
-</div>
-
 ```vue
 <script lang="ts" setup>
   import MazBadge from 'maz-ui/components/MazBadge'
@@ -140,14 +119,6 @@ const colors = [
 
 The `size` prop accepts one of the standardized `MazSize` values (`'mini' | 'xs' | 'sm' | 'md' | 'lg' | 'xl'`). The default is `'md'`. Padding, line-height and dimensions all scale relative to the chosen font-size, so a single keyword controls the whole badge footprint.
 
-<br />
-
-<div class="flex space-between gap-05 items-center flex-wrap">
-  <MazBadge v-for="size in sizes" :key="size" :size="size">
-    {{ size }}
-  </MazBadge>
-</div>
-
 ```vue
 <script lang="ts" setup>
 import MazBadge from 'maz-ui/components/MazBadge'
@@ -164,14 +135,6 @@ const sizes = ['mini', 'xs', 'sm', 'md', 'lg', 'xl']
 
 ### Rounded sizes
 
-<br />
-
-<div class="flex space-between gap-05 items-center flex-wrap">
-  <MazBadge v-for="size in roundedSize" :key="size" :rounded-size="size">
-    {{ size }}
-  </MazBadge>
-</div>
-
 ```vue
 <script lang="ts" setup>
 import MazBadge from 'maz-ui/components/MazBadge'
@@ -186,23 +149,19 @@ const roundedSize = ['none', 'sm', 'md', 'lg', 'xl', 'full']
 </template>
 ```
 
-<script lang="ts" setup>
-  const colors = [
-    'primary',
-    'secondary',
-    'info',
-    'success',
-    'warning',
-    'destructive',
-    'contrast',
-    'accent',
-    'surface',
-    'transparent',
-  ]
+## MazBadge API
 
-  const sizes = ['mini', 'xs', 'sm', 'md', 'lg', 'xl']
+`import MazBadge from 'maz-ui/components/MazBadge'`
 
-  const roundedSize = ['none', 'sm', 'md', 'lg', 'xl', 'full']
-</script>
+### Props
+
+- `color` (`MazBadgeColor`, default: `"primary"`): Color of the badge. Values: `'primary'`, `'secondary'`, `'accent'`, `'info'`, `'success'`, `'warning'`, `'destructive'`, `'contrast'`, `'surface'` (non exhaustive).
+- `size` (`"xs" | "sm" | "md" | "lg" | "xl" | "mini"`, default: `md`): Size of the badge - drives font-size; padding, line-height and dimensions scale relative to it via `em` units.
+- `nowrap` (`boolean`, default: `true`): Will not wrap the text.
+- `outlined` (`boolean`, default: `false`): Will add a border to the badge.
+- `pastel` (`boolean`, default: `false`): Will add a pastel style to the badge.
+- `rounded-size` (`MazBadgeRoundedSize`, default: `md`): Size radius of the component's border. Values: `'none'`, `'sm'`, `'md'`, `'lg'`, `'xl'`, `'full'` (non exhaustive).
+
+### Slots
 
-<!--@include: ./../../.vitepress/generated-docs/maz-badge.doc.md-->
+- `#default`: Badge content