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

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` (`any`): 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

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

@@ -1,23 +1,25 @@
 ---
-title: MazBtnGroup
-description: MazBtnGroup is a component to group multiple MazBtn buttons together with seamless styling. Supports props-based or slot-based rendering with customizable orientation, size, and color.
+title: "MazBtnGroup"
+description: "MazBtnGroup is a component to group multiple MazBtn buttons together with seamless styling. Supports props-based or slot-based rendering with customizable orientation, size, and color."
+package: "maz-ui"
+url: "https://maz-ui.com/components/maz-btn-group"
 ---
 
-# {{ $frontmatter.title }}
+# MazBtnGroup
 
-{{ $frontmatter.description }}
+> MazBtnGroup is a component to group multiple MazBtn buttons together with seamless styling. Supports props-based or slot-based rendering with customizable orientation, size, and color.
 
-<!--@include: ./../../.vitepress/mixins/getting-started.md-->
+- Package: `maz-ui`
+- Import: `import MazBtnGroup from 'maz-ui/components/MazBtnGroup'`
+- Nuxt: auto-imported by `@maz-ui/nuxt`, no import needed in a Nuxt app
+- Web: https://maz-ui.com/components/maz-btn-group
+
+> Before use it, you should install the MazUi plugin in your project, follow instructions in [Getting Started](../guide/getting-started.md)
 
 ## Basic usage with items
 
 Use the `items` prop to quickly create a button group from an array of button configurations.
 
-<ComponentDemo>
-  <MazBtnGroup :items="basicItems" />
-
-  <template #code>
-
 ```vue
 <template>
   <MazBtnGroup :items="items" />
@@ -35,22 +37,10 @@ const items: MazButtonGroupOption[] = [
 </script>
 ```
 
-  </template>
-</ComponentDemo>
-
 ## Slot-based usage
 
 Use the default slot to pass `MazBtn` components directly for full control over each button.
 
-<ComponentDemo>
-  <MazBtnGroup>
-    <MazBtn>Edit</MazBtn>
-    <MazBtn :active="true">Save</MazBtn>
-    <MazBtn>Delete</MazBtn>
-  </MazBtnGroup>
-
-  <template #code>
-
 ```vue
 <template>
   <MazBtnGroup>
@@ -66,27 +56,10 @@ import MazBtn from 'maz-ui/components/MazBtn'
 </script>
 ```
 
-  </template>
-</ComponentDemo>
-
 ## Orientation
 
 Use the `orientation` prop to arrange buttons horizontally (`row`) or vertically (`col`).
 
-<ComponentDemo>
-  <div class="maz:flex maz:gap-8 maz:flex-wrap">
-    <div>
-      <p class="maz:mb-2 maz:text-muted">Row (default)</p>
-      <MazBtnGroup :items="basicItems" orientation="row" />
-    </div>
-    <div>
-      <p class="maz:mb-2 maz:text-muted">Column</p>
-      <MazBtnGroup :items="basicItems" orientation="col" />
-    </div>
-  </div>
-
-  <template #code>
-
 ```vue
 <template>
   <MazBtnGroup :items="items" orientation="row" />
@@ -94,20 +67,10 @@ Use the `orientation` prop to arrange buttons horizontally (`row`) or vertically
 </template>
 ```
 
-  </template>
-</ComponentDemo>
-
 ## Sizes
 
 Use the `size` prop to apply a size to all buttons in the group.
 
-<ComponentDemo>
-  <div class="maz:flex maz:flex-col maz:gap-4 maz:items-start">
-    <MazBtnGroup v-for="size in sizes" :key="size" :items="basicItems" :size="size" />
-  </div>
-
-  <template #code>
-
 ```vue
 <template>
   <MazBtnGroup :items="items" size="mini" />
@@ -119,20 +82,10 @@ Use the `size` prop to apply a size to all buttons in the group.
 </template>
 ```
 
-  </template>
-</ComponentDemo>
-
 ## Colors
 
 Use the `color` prop to apply a color to all buttons in the group.
 
-<ComponentDemo>
-  <div class="maz:flex maz:flex-col maz:gap-4 maz:items-start">
-    <MazBtnGroup v-for="color in colors" :key="color" :items="basicItems" :color="color" />
-  </div>
-
-  <template #code>
-
 ```vue
 <template>
   <MazBtnGroup :items="items" color="primary" />
@@ -144,22 +97,12 @@ Use the `color` prop to apply a color to all buttons in the group.
 </template>
 ```
 
-  </template>
-</ComponentDemo>
-
 ## Button variants
 
 Use the `outlined` or `pastel` properties on individual buttons or apply different variants to buttons in the group.
 
 ### Outlined
 
-<br />
-
-<ComponentDemo>
-  <MazBtnGroup :items="outlinedItems" />
-
-  <template #code>
-
 ```vue
 <template>
   <MazBtnGroup :items="items" />
@@ -177,18 +120,8 @@ const items: MazButtonGroupOption[] = [
 </script>
 ```
 
-  </template>
-</ComponentDemo>
-
 ### Pastel
 
-<br />
-
-<ComponentDemo>
-  <MazBtnGroup :items="pastelItems" />
-
-  <template #code>
-
 ```vue
 <template>
   <MazBtnGroup :items="items" />
@@ -206,29 +139,8 @@ const items: MazButtonGroupOption[] = [
 </script>
 ```
 
-  </template>
-</ComponentDemo>
-
 ### Slot-based variants
 
-<br />
-
-<ComponentDemo>
-  <div class="maz:flex maz:flex-col maz:gap-4 maz:items-start">
-    <MazBtnGroup>
-      <MazBtn outlined>Edit</MazBtn>
-      <MazBtn outlined>Save</MazBtn>
-      <MazBtn outlined>Delete</MazBtn>
-    </MazBtnGroup>
-    <MazBtnGroup>
-      <MazBtn pastel>Edit</MazBtn>
-      <MazBtn pastel>Save</MazBtn>
-      <MazBtn pastel>Delete</MazBtn>
-    </MazBtnGroup>
-  </div>
-
-  <template #code>
-
 ```vue
 <template>
   <MazBtnGroup>
@@ -245,18 +157,10 @@ const items: MazButtonGroupOption[] = [
 </template>
 ```
 
-  </template>
-</ComponentDemo>
-
 ## Click handlers
 
 Add click handlers to buttons using the `onClick` property in items.
 
-<ComponentDemo>
-  <MazBtnGroup :items="clickableItems" />
-
-  <template #code>
-
 ```vue
 <template>
   <MazBtnGroup :items="items" />
@@ -273,21 +177,10 @@ const items: MazButtonGroupOption[] = [
 </script>
 ```
 
-  </template>
-</ComponentDemo>
-
 ## With icons
 
 Use the `startIcon` or `endIcon` properties to add icons to buttons.
 
-<ComponentDemo>
-  <MazBtnGroup :items="iconItems" />
-  <br />
-  <br />
-  <MazBtnGroup :items="iconOnlyItems" />
-
-  <template #code>
-
 ```vue
 <template>
   <MazBtnGroup :items="items" />
@@ -312,18 +205,10 @@ const iconOnlyItems: MazButtonGroupOption[] = [
 </script>
 ```
 
-  </template>
-</ComponentDemo>
-
 ## With links
 
 Use the `href` or `to` properties to create link buttons.
 
-<ComponentDemo>
-  <MazBtnGroup :items="linkItems" />
-
-  <template #code>
-
 ```vue
 <template>
   <MazBtnGroup :items="items" />
@@ -340,18 +225,10 @@ const items: MazButtonGroupOption[] = [
 </script>
 ```
 
-  </template>
-</ComponentDemo>
-
 ## Mixed button styles
 
 Combine different button styles within the same group.
 
-<ComponentDemo>
-  <MazBtnGroup :items="mixedItems" />
-
-  <template #code>
-
 ```vue
 <template>
   <MazBtnGroup :items="items" />
@@ -370,9 +247,6 @@ const items: MazButtonGroupOption[] = [
 </script>
 ```
 
-  </template>
-</ComponentDemo>
-
 ## Types
 
 ### MazButtonGroupOption
@@ -421,59 +295,23 @@ interface MazButtonGroupProps {
 }
 ```
 
-<!--@include: ./../../.vitepress/generated-docs/maz-btn-group.doc.md-->
-
-<script lang="ts" setup>
-import type { MazButtonGroupOption } from 'maz-ui/components/MazBtnGroup'
-import { MazArrowLeft } from '@maz-ui/icons/raw/MazArrowLeft'
-import { MazArrowRight } from '@maz-ui/icons/raw/MazArrowRight'
-import { MazBars3 } from '@maz-ui/icons/raw/MazBars3'
-import { MazSquares2x2 } from '@maz-ui/icons/raw/MazSquares2x2'
-
-const sizes = ['mini', 'xs', 'sm', 'md', 'lg', 'xl'] as const
-const colors = ['primary', 'secondary', 'info', 'success', 'warning', 'destructive'] as const
-
-const basicItems: MazButtonGroupOption[] = [
-  { text: 'Day' },
-  { text: 'Week', active: true },
-  { text: 'Month' },
-]
-
-const outlinedItems: MazButtonGroupOption[] = [
-  { text: 'Day', outlined: true },
-  { text: 'Week', outlined: true, active: true },
-  { text: 'Month', outlined: true },
-]
+## MazBtnGroup API
 
-const pastelItems: MazButtonGroupOption[] = [
-  { text: 'Day', pastel: true },
-  { text: 'Week', pastel: true },
-  { text: 'Month', pastel: true },
-]
+`import MazBtnGroup from 'maz-ui/components/MazBtnGroup'`
 
-const clickableItems: MazButtonGroupOption[] = [
-  { text: 'Alert', onClick: () => alert('Clicked Alert!') },
-  { text: 'Console', onClick: () => console.log('Clicked Console!') },
-]
+### Props
 
-const iconItems: MazButtonGroupOption[] = [
-  { text: 'Previous', startIcon: MazArrowLeft },
-  { text: 'Next', endIcon: MazArrowRight },
-]
-const iconOnlyItems: MazButtonGroupOption[] = [
-  { icon: MazBars3, color: 'primary', active: true },
-  { icon: MazSquares2x2, color: 'transparent', outlined: true },
-]
+- `items` (`MazButtonGroupOption[]`): The items for the button group (optional when using slot-based approach).
+- `orientation` (`"row" | "col"`, default: `"row"`): The orientation of the button group.
+- `size` (`"xs" | "sm" | "md" | "lg" | "xl" | "mini"`, default: `'md'`): The size of all buttons (only applies to props-based buttons).
+- `color` (`"primary" | "secondary" | "accent" | "info" | "success" | "warning" | "destructive" | "contrast" | "transparent"`, default: `"primary"`): The color of all buttons (only applies to props-based buttons).
+- `rounded-size` (`MazRoundedSize`, default: `'lg'`): The rounded size of the buttons.
+- `outlined` (`boolean`, default: `false`): The outlined state of the buttons.
+- `pastel` (`boolean`, default: `false`): The pastel state of the buttons.
+- `loading` (`boolean`, default: `false`): The loading state of the buttons.
+- `disabled` (`boolean`, default: `false`): The disabled state of the buttons.
 
-const linkItems: MazButtonGroupOption[] = [
-  { text: 'External Link', href: 'https://maz-ui.com' },
-  { text: 'Router Link', to: { path: '/components/maz-btn' } },
-]
+### Slots
 
-const mixedItems: MazButtonGroupOption[] = [
-  { text: 'Primary', color: 'primary' },
-  { text: 'Success', color: 'success' },
-  { text: 'Warning', color: 'warning', outlined: true },
-  { text: 'Destructive', color: 'destructive', pastel: true },
-]
-</script>
+- `#default`: Slot for passing MazBtn components directly
+- `#button-{index}`: One slot per `index`: `#button-<index>`.