maz-ui 5.0.0 → 5.1.0-beta.0

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/components/maz-badge.md

@@ -0,0 +1,167 @@
+---
+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"
+---
+
+# MazBadge
+
+> MazBadge is a standalone component to show short text in colored container
+
+- 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
+
+> 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 MazBadge from 'maz-ui/components/MazBadge'
+</script>
+
+<template>
+  <MazBadge>
+    Badge
+  </MazBadge>
+</template>
+```
+
+## Options
+
+> See all options props here
+
+### Colors
+
+```vue
+<script lang="ts" setup>
+  import MazBadge from 'maz-ui/components/MazBadge'
+
+  const colors = [
+    'primary',
+    'secondary',
+    'info',
+    'success',
+    'warning',
+    'destructive',
+    'contrast',
+    'accent',
+    'surface',
+    'transparent',
+  ]
+</script>
+
+<template>
+  <MazBadge v-for="color in color" :key="color" :color="color">
+    {{ color }}
+  </MazBadge>
+</template>
+```
+
+### Outlined
+
+```vue
+<script lang="ts" setup>
+import MazBadge from 'maz-ui/components/MazBadge'
+
+const colors = [
+  'primary',
+  'secondary',
+  'info',
+  'success',
+  'warning',
+  'destructive',
+  'contrast',
+  'accent',
+  'surface',
+  'transparent',
+]
+</script>
+
+<template>
+  <MazBadge v-for="color in color" :key="color" :color="color" outlined>
+    {{ color }}
+  </MazBadge>
+</template>
+```
+
+### Pastel
+
+```vue
+<script lang="ts" setup>
+  import MazBadge from 'maz-ui/components/MazBadge'
+
+  const colors = [
+    'primary',
+    'secondary',
+    'info',
+    'success',
+    'warning',
+    'destructive',
+    'contrast',
+    'accent',
+    'surface',
+    'transparent',
+  ]
+</script>
+
+<template>
+  <MazBadge v-for="color in color" :key="color" :color="color" pastel>
+    {{ color }}
+  </MazBadge>
+</template>
+```
+
+### Size
+
+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.
+
+```vue
+<script lang="ts" setup>
+import MazBadge from 'maz-ui/components/MazBadge'
+
+const sizes = ['mini', 'xs', 'sm', 'md', 'lg', 'xl']
+</script>
+
+<template>
+  <MazBadge v-for="size in sizes" :key="size" :size="size">
+    {{ size }}
+  </MazBadge>
+</template>
+```
+
+### Rounded sizes
+
+```vue
+<script lang="ts" setup>
+import MazBadge from 'maz-ui/components/MazBadge'
+
+const roundedSize = ['none', 'sm', 'md', 'lg', 'xl', 'full']
+</script>
+
+<template>
+  <MazBadge v-for="size in roundedSize" :key="size" :rounded-size="size">
+    {{ size }}
+  </MazBadge>
+</template>
+```
+
+## MazBadge API
+
+`import MazBadge from 'maz-ui/components/MazBadge'`
+
+### 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
+
+- `#default`: Badge content

package/docs/components/maz-bottom-sheet.md

@@ -0,0 +1,257 @@
+---
+title: "MazBottomSheet"
+description: "MazBottomSheet is a standalone component like a simple dialog but anchored at the bottom of the screen. Full-width on mobile and constrained/centered on desktop, with a header (icon, title, close button), a footer and many replaceable slots. Useful for mobile UX."
+package: "maz-ui"
+url: "https://maz-ui.com/components/maz-bottom-sheet"
+---
+
+# MazBottomSheet
+
+> MazBottomSheet is a standalone component like a simple dialog but anchored at the bottom of the screen. Full-width on mobile and constrained/centered on desktop, with a header (icon, title, close button), a footer and many replaceable slots. Useful for mobile UX.
+
+- Package: `maz-ui`
+- Import: `import MazBottomSheet from 'maz-ui/components/MazBottomSheet'`
+- Nuxt: auto-imported by `@maz-ui/nuxt`, no import needed in a Nuxt app
+- Web: https://maz-ui.com/components/maz-bottom-sheet
+
+> 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 the `<Teleport to="body">` with [MazBackdrop](./maz-backdrop.md), so you can implement this component anywhere and it inherits all its props (`persistent`, `closeOnEscape`, etc.)
+
+## Basic usage
+
+The sheet has a header (with the `title` and a close button) and an optional `footer` slot. It opens full-width on mobile and is constrained/centered on desktop (see Max width).
+
+```vue
+<script setup>
+import MazBottomSheet from 'maz-ui/components/MazBottomSheet'
+import { ref } from 'vue'
+
+const basicOpened = ref(false)
+</script>
+
+<template>
+  <MazBtn @click="basicOpened = true">
+    Open Bottom Sheet
+  </MazBtn>
+
+  <MazBottomSheet v-model="basicOpened" title="Bottom Sheet Title">
+    <p>Your content goes here.</p>
+
+    <template #footer="{ close }">
+      <MazBtn color="transparent" @click="close">
+        Cancel
+      </MazBtn>
+      <MazBtn @click="close">
+        Confirm
+      </MazBtn>
+    </template>
+  </MazBottomSheet>
+</template>
+```
+
+## Swipe to close (iOS-like)
+
+By default a drag handle (grab bar) is shown at the top of the sheet, and you can **close the sheet by dragging that handle down** - the sheet follows your pointer and either dismisses (past the threshold) or snaps back. This works with both touch and mouse.
+
+Disable it with `:swipe-to-close="false"` (the handle is then hidden too), or replace the handle with the `#handle` slot. A `persistent` sheet never dismisses on swipe: it snaps back instead.
+
+```html
+<!-- enabled by default -->
+<MazBottomSheet v-model="swipeOpened" title="Drag me down">
+  <p>Grab the bar at the top and drag down to close.</p>
+</MazBottomSheet>
+
+<!-- disable the handle and the gesture -->
+<MazBottomSheet v-model="swipeOpened" :swipe-to-close="false" title="No swipe" />
+
+<!-- custom handle -->
+<MazBottomSheet v-model="swipeOpened" title="Custom handle">
+  <template #handle>
+    <span class="h-1.5 w-12 rounded-full bg-primary" />
+  </template>
+</MazBottomSheet>
+```
+
+## Header with an icon
+
+Pass an `icon` (an icon value or a full `MazIconProps` object) to display it on the left of the title.
+
+```html
+<MazBottomSheet v-model="iconOpened" title="Notifications" icon="/bell.svg">
+  <p>You have 3 new notifications.</p>
+
+  <template #footer="{ close }">
+    <MazBtn @click="close">Mark all as read</MazBtn>
+  </template>
+</MazBottomSheet>
+```
+
+## Replaceable slots
+
+Everything in the header is replaceable: use `#icon` and `#title` to customize parts of the default header, or `#header` to replace the whole header (you get the `close` function as a binding).
+
+```html
+<MazBottomSheet v-model="slotsOpened">
+  <template #icon>
+    <MazAvatar src="/avatar.jpg" size="sm" />
+  </template>
+
+  <template #title>
+    <span class="text-primary">Custom title</span>
+  </template>
+
+  <p>The icon and the title slots are fully replaceable.</p>
+</MazBottomSheet>
+
+<!-- or replace the whole header -->
+<MazBottomSheet v-model="slotsOpened">
+  <template #header="{ close }">
+    <div class="flex items-center justify-between p-4">
+      <strong>My header</strong>
+      <MazBtn size="sm" color="transparent" @click="close">Close</MazBtn>
+    </div>
+  </template>
+</MazBottomSheet>
+```
+
+## Max width
+
+On mobile the sheet is always **full-width**. From the tablet breakpoint and up, it is **constrained** to `max-width` and centered horizontally. The default `max-width` is `35rem`; pass the `max-width` prop (a `MazSizeUnit`) to override it.
+
+```html
+<MazBottomSheet v-model="wideOpened" title="Wide sheet" max-width="60rem">
+  <p>This sheet is constrained to 60rem on desktop and full-width on mobile.</p>
+</MazBottomSheet>
+```
+
+## Without header
+
+Hide the whole header with `hide-header`, or only the close button with `hide-close-button`.
+
+```html
+<MazBottomSheet v-model="noHeaderOpened" hide-header>
+  <div class="flex flex-col gap-3 text-center">
+    <p>No header here, you control the whole layout.</p>
+    <MazBtn @click="noHeaderOpened = false">Got it</MazBtn>
+  </div>
+</MazBottomSheet>
+```
+
+## Persistent
+
+A `persistent` sheet cannot be closed by clicking outside or pressing escape, and the close button is removed. Provide your own action to close it.
+
+```html
+<MazBottomSheet v-model="persistentOpened" title="Action required" persistent>
+  <p>You must confirm before closing this sheet.</p>
+
+  <template #footer>
+    <MazBtn @click="persistentOpened = false">I understand</MazBtn>
+  </template>
+</MazBottomSheet>
+```
+
+## Full example
+
+```vue
+<script setup>
+import MazBottomSheet from 'maz-ui/components/MazBottomSheet'
+import { reactive, ref } from 'vue'
+
+const isProductOpen = ref(false)
+const quantity = ref(1)
+const selectedOptions = reactive({ size: '', color: '' })
+
+function openProductOptions() {
+  isProductOpen.value = true
+}
+</script>
+
+<template>
+  <MazBtn color="primary" @click="openProductOptions">
+    Customize Options
+  </MazBtn>
+
+  <MazBottomSheet v-model="isProductOpen" title="Customize Your Shoes" icon="/cog.svg" :padding="false">
+    <div class="space-y-6 p-6">
+      <h4 class="mb-3 text-lg font-semibold">
+        Select Size
+      </h4>
+      <div class="grid grid-cols-4 gap-2">
+        <MazBtn
+          v-for="size in sizes"
+          :key="size"
+          :color="selectedOptions.size === size ? 'primary' : 'secondary'"
+          size="sm"
+          @click="selectedOptions.size = size"
+        >
+          {{ size }}
+        </MazBtn>
+      </div>
+    </div>
+
+    <template #footer="{ close }">
+      <MazBtn color="transparent" @click="close">
+        Cancel
+      </MazBtn>
+      <MazBtn color="primary" @click="addToCart">
+        Add to Cart (${{ (129.99 * quantity).toFixed(2) }})
+      </MazBtn>
+    </template>
+  </MazBottomSheet>
+</template>
+```
+
+## Accessibility
+
+The bottom sheet is a modal `dialog` labelled by its `title` and described by its content. The focus is trapped inside while it is open, Esc closes it, and the rest of the page is `inert` (except the toasts and the live regions).
+
+## MazBottomSheet API
+
+`import MazBottomSheet from 'maz-ui/components/MazBottomSheet'`
+
+### Props
+
+- `model-value` (`boolean`, `v-model`): Modal's model value.
+- `title` (`string`): Title of the bottom sheet in the header.
+- `icon` (`MazIconLike`): Icon displayed on the left of the header. Accepts an icon value or a full `MazIconProps` object.
+- `max-width` (`` `${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... ``, default: `"40rem"`): Bottom sheet's max-width, applied from the tablet breakpoint and up (full-width below).
+- `hide-close-button` (`boolean`, default: `false`): Remove the close button in the header.
+- `hide-header` (`boolean`, default: `false`): Remove the whole header.
+- `padding` (`boolean`, default: `true`): Add the padding on the content area.
+- `persistent` (`boolean`): Persistent bottom sheet (not closable by clicking outside and remove close button) Persistent dialog (not closable by clicking outside and remove close button).
+- `swipe-to-close` (`boolean`, default: `true`): Show the drag handle at the top and allow closing the sheet by swiping it down (iOS-like). The swipe never closes a `persistent` sheet (it snaps back instead).
+- `teleport-selector` (`string`): Teleport selector.
+- `before-close` (`(() => void | Promise<void>)`): Function called before modal is close.
+- `close-on-escape` (`boolean`, default: `true`): Prevent close on escape key.
+- `transition-name` (`string`): Transition name.
+- `backdrop-class` (`ClassValue`): Backdrop class.
+- `backdrop-content-class` (`ClassValue`): Backdrop content class.
+- `content-padding` (`boolean`): Add padding to the content.
+- `justify` (`"none" | "center" | "end" | "start" | "space-between" | "space-around"`): Justify content.
+- `align` (`"none" | "center" | "end" | "start"`): 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 the model value is updated
+- `@open` (payload: `value?: void | undefined`): Emitted when the component is opened
+- `@close` (payload: `value?: void | undefined`): Emitted when the component is closed
+
+### Slots
+
+- `#handle`: Drag handle (grab bar) displayed at the top when `swipeToClose` is enabled
+- `#header`: Header slot Bindings: `close: () => void` (close function).
+- `#icon`: Icon slot in the header
+- `#title`: Title slot in the header
+- `#default`: Default content Bindings: `close: () => void` (close function).
+- `#footer`: Footer slot Bindings: `close: () => void` (close function).
+
+### Exposed (template ref)
+
+- `close`: Close the bottom sheet