maz-ui 5.0.0 → 5.1.0-beta.0

package/docs/components/maz-alert.md

@@ -0,0 +1,241 @@
+---
+title: "MazAlert"
+description: "MazAlert is an accessible component for displaying contextual feedback messages like success, warning, error, or informational notifications with customizable colors, icons, and styling options"
+package: "maz-ui"
+url: "https://maz-ui.com/components/maz-alert"
+---
+
+# MazAlert
+
+> MazAlert is an accessible component for displaying contextual feedback messages like success, warning, error, or informational notifications with customizable colors, icons, and styling options
+
+- Package: `maz-ui`
+- Import: `import MazAlert from 'maz-ui/components/MazAlert'`
+- Nuxt: auto-imported by `@maz-ui/nuxt`, no import needed in a Nuxt app
+- Web: https://maz-ui.com/components/maz-alert
+
+> Before use it, you should install the MazUi plugin in your project, follow instructions in [Getting Started](../guide/getting-started.md)
+
+## Basic usage
+
+```vue
+<template>
+  <MazAlert title="Information" content="This is an informational alert message." />
+</template>
+
+<script lang="ts" setup>
+  import MazAlert from 'maz-ui/components/MazAlert'
+</script>
+```
+
+## Variants
+
+MazAlert supports two visual variants: `soft` (default) with transparent background, and `solid` with full color background.
+
+### Soft variant (default)
+
+The soft variant uses a transparent background with colored text.
+
+```vue
+<template>
+  <MazAlert color="info" variant="soft" title="Soft Info" content="..." />
+  <MazAlert color="success" variant="soft" title="Soft Success" content="..." />
+  <MazAlert color="destructive" variant="soft" title="Soft Error" content="..." />
+</template>
+```
+
+### Solid variant
+
+The solid variant uses the full color as background with contrasting text.
+
+```vue
+<template>
+  <MazAlert color="info" variant="solid" title="Solid Info" content="..." />
+  <MazAlert color="success" variant="solid" title="Solid Success" content="..." />
+  <MazAlert color="destructive" variant="solid" title="Solid Error" content="..." />
+</template>
+```
+
+### All colors with solid variant
+
+```vue
+<template>
+  <MazAlert color="info" variant="solid" title="Info" content="..." />
+  <MazAlert color="success" variant="solid" title="Success" content="..." />
+  <MazAlert color="warning" variant="solid" title="Warning" content="..." />
+  <MazAlert color="destructive" variant="solid" title="Error" content="..." />
+  <!-- ... other colors -->
+</template>
+```
+
+## Colors
+
+MazAlert supports all theme colors to convey different types of messages.
+
+```vue
+<template>
+  <MazAlert color="info" title="Info" content="This is an info alert." />
+  <MazAlert color="success" title="Success" content="Operation completed successfully!" />
+  <MazAlert color="warning" title="Warning" content="Please review before proceeding." />
+  <MazAlert color="destructive" title="Error" content="An error occurred." />
+  <MazAlert color="primary" title="Primary" content="This is a primary alert." />
+  <MazAlert color="secondary" title="Secondary" content="This is a secondary alert." />
+  <MazAlert color="accent" title="Accent" content="This is an accent alert." />
+  <MazAlert color="contrast" title="Contrast" content="This is a contrast alert." />
+</template>
+```
+
+## With slots
+
+Use slots for more complex content with custom HTML.
+
+```vue
+<template>
+  <MazAlert color="destructive">
+    <template #title>
+      3 errors found
+    </template>
+    <ul class="m-0 list-inside list-disc pl-0">
+      <li>firstname - Invalid length: Expected >=5 but received 0</li>
+      <li>lastname - Invalid length: Expected >=2 but received 0</li>
+      <li>age - Invalid type: Expected number but received ""</li>
+    </ul>
+  </MazAlert>
+</template>
+```
+
+## Without border
+
+Remove the border with `:bordered="false"`.
+
+```vue
+<template>
+  <MazAlert
+    color="success"
+    title="Without border"
+    content="This alert has no border."
+    :bordered="false"
+  />
+
+  <MazAlert
+    color="success"
+    title="With border (default)"
+    content="This alert has a border."
+  />
+</template>
+```
+
+## Rounded sizes
+
+Customize the border radius with the `rounded-size` prop.
+
+```vue
+<template>
+  <MazAlert rounded-size="none" title="Rounded: none" content="..." />
+  <MazAlert rounded-size="sm" title="Rounded: sm" content="..." />
+  <MazAlert rounded-size="md" title="Rounded: md" content="..." />
+  <MazAlert rounded-size="base" title="Rounded: base (default)" content="..." />
+  <MazAlert rounded-size="lg" title="Rounded: lg" content="..." />
+  <MazAlert rounded-size="xl" title="Rounded: xl" content="..." />
+  <MazAlert rounded-size="2xl" title="Rounded: 2xl" content="..." />
+  <MazAlert rounded-size="3xl" title="Rounded: 3xl" content="..." />
+</template>
+```
+
+## Hide icon
+
+Hide the default icon with `hide-icon`.
+
+```vue
+<template>
+  <MazAlert color="warning" title="With icon (default)" content="The icon is visible." />
+  <MazAlert color="warning" title="Without icon" content="The icon is hidden." hide-icon />
+</template>
+```
+
+## Custom icon
+
+Provide a custom icon using the `icon` prop.
+
+```vue
+<template>
+  <MazAlert
+    color="primary"
+    title="Custom icon"
+    content="This alert uses a custom icon."
+    icon="/bell.svg"
+  />
+</template>
+```
+
+## Title only or content only
+
+You can use either title, content, or both.
+
+```vue
+<template>
+  <MazAlert color="info" title="Title only alert" />
+  <MazAlert color="success" content="Content only alert without a title." />
+  <MazAlert color="warning" title="Both title and content" content="This alert has both." />
+</template>
+```
+
+## Use cases
+
+### Form validation errors
+
+```vue
+<template>
+  <MazAlert color="destructive" title="Please fix the following errors:">
+    <ul class="m-0 list-inside list-disc pl-0">
+      <li>Email address is required</li>
+      <li>Password must be at least 8 characters</li>
+    </ul>
+  </MazAlert>
+</template>
+```
+
+### Success notification
+
+```vue
+<template>
+  <MazAlert
+    color="success"
+    title="Payment successful!"
+    content="Your order #12345 has been confirmed. You will receive an email confirmation shortly."
+  />
+</template>
+```
+
+### Warning message
+
+```vue
+<template>
+  <MazAlert
+    color="warning"
+    title="Session expiring soon"
+    content="Your session will expire in 5 minutes. Please save your work to avoid losing any changes."
+  />
+</template>
+```
+
+## MazAlert API
+
+`import MazAlert from 'maz-ui/components/MazAlert'`
+
+### Props
+
+- `title` (`string`): Title of the alert.
+- `content` (`string`): Content of the alert.
+- `icon` (`string | IconComponent`): Icon of the alert - can be a component or icon name string.
+- `hide-icon` (`boolean`, default: `false`): Hide the icon.
+- `color` (`MazAlertColor`, default: `"info"`): Color of the alert. Values: `'success'`, `'warning'`, `'destructive'`, `'info'`, `'primary'`, `'secondary'`, `'accent'`, `'contrast'` (non exhaustive).
+- `icon-size` (`MazIconSize`, default: `"md"`): Size of the icon.
+- `rounded-size` (`MazAlertRoundedSize`, default: `'md'`): Size of the rounded corners. Values: `'none'`, `'sm'`, `'md'`, `'lg'`, `'xl'`, `'2xl'`, `'3xl'` (non exhaustive).
+- `bordered` (`boolean`, default: `true`): Add border to the component.
+- `variant` (`MazAlertVariant`, default: `"soft"`): Visual variant of the alert. Values: `'soft'`, `'solid'` (non exhaustive).
+
+### Slots
+
+- `#title`: Title slot - overrides title prop
+- `#default`: Default slot for alert content - overrides content prop

package/docs/components/maz-animated-counter.md

@@ -0,0 +1,87 @@
+---
+title: "MazAnimatedCounter"
+description: "MazAnimatedCounter is a standalone component that allows you to animate a number from 0 to a specific value. Fully animated with CSS."
+package: "maz-ui"
+url: "https://maz-ui.com/components/maz-animated-counter"
+---
+
+# MazAnimatedCounter
+
+> MazAnimatedCounter is a standalone component that allows you to animate a number from 0 to a specific value. Fully animated with CSS.
+
+- Package: `maz-ui`
+- Import: `import MazAnimatedCounter from 'maz-ui/components/MazAnimatedCounter'`
+- Nuxt: auto-imported by `@maz-ui/nuxt`, no import needed in a Nuxt app
+- Web: https://maz-ui.com/components/maz-animated-counter
+
+> Before use it, you should install the MazUi plugin in your project, follow instructions in [Getting Started](../guide/getting-started.md)
+
+## Basic usage
+
+```vue
+<script lang="ts" setup>
+import MazAnimatedCounter from 'maz-ui/components/MazAnimatedCounter'
+
+const count = ref(Math.floor(Math.random() * 99999))
+
+onMounted(() => {
+  setInterval(() => {
+    count.value = Math.floor(Math.random() * 99999)
+  }, 3000)
+})
+</script>
+
+<template>
+  <MazAnimatedCounter :count="4000" />
+</template>
+```
+
+## duration
+
+You can set the duration of the animation with the `duration` prop. The default value is `1000` ms.
+
+```vue
+<MazAnimatedCounter :count="4000" :duration="5000" />
+```
+
+## prefix and suffix
+
+You can add a prefix and a suffix to the number with props or slots.
+
+Be careful, you can't use both at the same time.
+
+```html
+<p class="font-semibold">Prefixed</p>
+
+<MazAnimatedCounter :count="20" prefix="$" />
+
+<MazAnimatedCounter :count="20">
+  <template #prefix>$</template>
+</MazAnimatedCounter>
+
+<p class="font-semibold">Suffixed</p>
+
+<MazAnimatedCounter :count="100" suffix="%" />
+
+<MazAnimatedCounter :count="100">
+  <template #suffix>%</template>
+</MazAnimatedCounter>
+```
+
+## MazAnimatedCounter API
+
+`import MazAnimatedCounter from 'maz-ui/components/MazAnimatedCounter'`
+
+### Props
+
+- `count` (`number`, required): The number to animate.
+- `duration` (`number`, default: `1000`): Duration of the animation in milliseconds.
+- `prefix` (`string`): Suffix to display next to the number.
+- `suffix` (`string`): Suffix to display next to the number.
+- `delay` (`number`, default: `100`): Delay before the animation starts in milliseconds.
+- `once` (`boolean`, default: `true`): Play the animation only once.
+
+### Slots
+
+- `#prefix`
+- `#suffix`

package/docs/components/maz-animated-element.md

@@ -0,0 +1,46 @@
+---
+title: "MazAnimatedElement"
+description: "MazAnimatedElement is a standalone component that animates its content with a sliding blur effect when it enters the viewport. It supports different animation directions (up, down, left, right) and allows customizing the animation delay and duration."
+package: "maz-ui"
+url: "https://maz-ui.com/components/maz-animated-element"
+---
+
+# MazAnimatedElement
+
+> MazAnimatedElement is a standalone component that animates its content with a sliding blur effect when it enters the viewport. It supports different animation directions (up, down, left, right) and allows customizing the animation delay and duration.
+
+- Package: `maz-ui`
+- Import: `import MazAnimatedElement from 'maz-ui/components/MazAnimatedElement'`
+- Nuxt: auto-imported by `@maz-ui/nuxt`, no import needed in a Nuxt app
+- Web: https://maz-ui.com/components/maz-animated-element
+
+> Before use it, you should install the MazUi plugin in your project, follow instructions in [Getting Started](../guide/getting-started.md)
+
+## Basic usage
+
+```vue
+<script lang="ts" setup>
+import MazAnimatedElement from 'maz-ui/components/MazAnimatedElement'
+</script>
+
+<template>
+  <MazAnimatedElement direction="up" :delay="1000" :duration="2000">
+    <MazAvatar src="https://github.com/LouisMazel.png" size="lg" />
+  </MazAnimatedElement>
+</template>
+```
+
+## MazAnimatedElement API
+
+`import MazAnimatedElement from 'maz-ui/components/MazAnimatedElement'`
+
+### Props
+
+- `direction` (`"up" | "down" | "left" | "right"`, default: `"up"`): The direction of the animation.
+- `delay` (`number`, default: `0`): The delay of the animation.
+- `duration` (`number`, default: `2000`): The duration of the animation.
+- `once` (`boolean`, default: `true`): Play the animation only once.
+
+### Slots
+
+- `#default`

package/docs/components/maz-animated-text.md

@@ -0,0 +1,53 @@
+---
+title: "MazAnimatedText"
+description: "MazAnimatedText is a standalone component that animates text with a sliding blur effect. It can highlight the last word with a gradient background and supports different animation directions (up, down, left, right)."
+package: "maz-ui"
+url: "https://maz-ui.com/components/maz-animated-text"
+---
+
+# MazAnimatedText
+
+> MazAnimatedText is a standalone component that animates text with a sliding blur effect. It can highlight the last word with a gradient background and supports different animation directions (up, down, left, right).
+
+- Package: `maz-ui`
+- Import: `import MazAnimatedText from 'maz-ui/components/MazAnimatedText'`
+- Nuxt: auto-imported by `@maz-ui/nuxt`, no import needed in a Nuxt app
+- Web: https://maz-ui.com/components/maz-animated-text
+
+> Before use it, you should install the MazUi plugin in your project, follow instructions in [Getting Started](../guide/getting-started.md)
+
+## Basic usage
+
+**Tip:**
+
+This component is SSR friendly. It will display the brut text on the server side with the chosen tag, and the animated text on the client side.
+
+```vue
+<script lang="ts" setup>
+import MazAnimatedText from 'maz-ui/components/MazAnimatedText'
+</script>
+
+<template>
+  <MazAnimatedText tag="h1" text="Hello" last-word="world" :delay="1000" :duration="2000" direction="up" :column-gap="0.5" :row-gap="0.5" />
+</template>
+```
+
+## MazAnimatedText API
+
+`import MazAnimatedText from 'maz-ui/components/MazAnimatedText'`
+
+### Props
+
+- `text` (`string`, required): The text to animate.
+- `last-word` (`string`): The last word(s) to be highlighted.
+- `delay` (`number`, default: `0`): The delay of the animation.
+- `direction` (`"up" | "down" | "left" | "right"`, default: `"up"`): The direction of the animation.
+- `tag` (`string`, default: `"span"`): The tag to use for the text.
+- `word-delay` (`number`, default: `75`): The delay between each word.
+- `column-gap` (`number`, default: `0.5`): The column gap between each word.
+- `row-gap` (`number`, default: `0`): The row gap between each word.
+- `duration` (`number`, default: `2000`): The duration of the animation.
+- `once` (`boolean`, default: `true`): Play the animation only once.
+- `gradient-from` (`"primary" | "secondary" | "accent" | "info" | "success" | "warning" | "destructive" | "contrast" | "transparent"`, default: `"primary"`): The gradient from color.
+- `gradient-via` (`"primary" | "secondary" | "accent" | "info" | "success" | "warning" | "destructive" | "contrast" | "transparent"`, default: `"info"`): The gradient via color.
+- `gradient-to` (`"primary" | "secondary" | "accent" | "info" | "success" | "warning" | "destructive" | "contrast" | "transparent"`, default: `"secondary"`): The gradient to color.

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`)