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

package/docs/components/maz-dialog-confirm.md

@@ -0,0 +1,215 @@
+---
+title: "MazDialogConfirm"
+description: "MazDialogConfirm is a standalone component that dialogs with the user to show important information and propose confirmation. You should wait for this response with await."
+package: "maz-ui"
+url: "https://maz-ui.com/components/maz-dialog-confirm"
+---
+
+# MazDialogConfirm
+
+> MazDialogConfirm is a standalone component that dialogs with the user to show important information and propose confirmation. You should wait for this response with await.
+
+- Package: `maz-ui`
+- Import: `import MazDialogConfirm from 'maz-ui/components/MazDialogConfirm'`
+- Nuxt: auto-imported by `@maz-ui/nuxt`, no import needed in a Nuxt app
+- Web: https://maz-ui.com/components/maz-dialog-confirm
+
+> Before use it, you should install the MazUi plugin in your project, follow instructions in [Getting Started](../guide/getting-started.md)
+
+**Note:**
+
+This component uses [MazDialog](./maz-dialog.md), so it inherits all its props
+
+**Tip:**
+
+This component uses `<Teleport to="body">` with [MazBackdrop](./maz-backdrop.md), so you can implement this component anywhere and it inherits all its props
+
+## Basic usage
+
+```vue
+<script setup>
+import MazDialogConfirm, { useMazDialogConfirm } from 'maz-ui/components/MazDialogConfirm'
+import MazDialog from 'maz-ui/components/MazDialog'
+
+import { ref } from 'vue'
+
+const confirmDialog = ref(false)
+
+const { showDialogAndWaitChoice, data } = useMazDialogConfirm()
+
+data.value = {
+  title: 'Delete user',
+  message: 'Are you sure you want to delete this user?',
+}
+
+const buttons: DialogCustomButton[] = [
+  {
+    text: 'Cancel',
+    type: 'reject',
+    color: 'destructive',
+    outlined: true,
+    response: 'cancel',
+    size: 'sm',
+  },
+  {
+    text: 'Delete!',
+    type: 'resolve',
+    color: 'success',
+    response: 'delete',
+    size: 'lg',
+  },
+]
+
+async function askToUser() {
+  try {
+    const acceptResponse = await showDialogAndWaitChoice('one')
+    toast.success(acceptResponse, {
+      position: 'top-right'
+    })
+    const rejectResponse = await showDialogAndWaitChoice('two')
+    toast.success(rejectResponse, {
+      position: 'top-right'
+    })
+    confirmDialog.value = true
+  }
+  catch (rejectResponse) {
+    toast.error(rejectResponse, {
+      position: 'top-right'
+    })
+  }
+}
+</script>
+
+<template>
+  <MazBtn @click="askToUser">
+    Ask user
+  </MazBtn>
+
+  <MazDialogConfirm
+    :data="dataPromiseOne"
+    identifier="one"
+  />
+
+  <MazDialogConfirm identifier="two" :buttons="buttons">
+    <template #title>
+      Do you really want to delete this user?
+    </template>
+    <template #default>
+      Are you really sure you want to delete this user?
+    </template>
+  </MazDialogConfirm>
+
+  <MazDialog v-model="confirmDialog">
+    <template #title>
+      User deleted
+    </template>
+    <template #default>
+      User has been deleted!
+    </template>
+    <template #footer="{ close }">
+      <MazBtn @click="close">
+        Ok
+      </MazBtn>
+    </template>
+  </MazDialog>
+</template>
+```
+
+## Types
+
+```ts
+interface MazDialogConfirmData {
+  /**
+   * Dialog title
+   */
+  title?: string
+  /**
+   * Dialog message
+   */
+  message?: string
+  /**
+   * Dialog custom buttons
+   * @default [{ text: 'Confirm', color: 'success', type: 'accept' }, { text: 'Cancel', color: 'destructive', type: 'reject' }]
+   * @type {MazDialogConfirmButton[]}
+   */
+  buttons?: MazDialogConfirmButton[]
+}
+
+// All props of MazBtn
+interface MazDialogConfirmButton {
+  text?: string
+  block?: boolean
+  color?: Color
+  disabled?: boolean
+  loading?: boolean
+  outlined?: boolean
+  rounded?: boolean
+  size?: Size
+  text: string
+  type: 'accept' | 'reject'
+  response?: unknown
+}
+
+type Color = 'primary'
+    | 'secondary'
+    | 'info'
+    | 'success'
+    | 'warning'
+    | 'destructive'
+    | 'accent'
+    | 'contrast'
+    | 'transparent'
+
+type Size = 'mini' | 'xs' | 'sm' | 'md' | 'lg' | 'xl'
+```
+
+## MazDialogConfirm API
+
+`import MazDialogConfirm from 'maz-ui/components/MazDialogConfirm'`
+
+### Props
+
+- `identifier` (`string`, required): Uniq identifier of the dialog - This is used to identify the dialog in the state.
+- `title` (`string`): Dialog title displayed in the header Title of the modal in header.
+- `message` (`string`): Dialog message displayed in the body.
+- `reject-text` (`string`): Text for the reject button - will be applied only if buttons props is not provided.
+- `reject-props` (`(Omit<MazBtnProps, "type"> & MazDialogConfirmButton)`, default: `{ color: 'destructive', type: 'reject', text: 'Cancel', response: 'reject' }`): Props for the reject button - will be applied only if buttons props is not provided.
+- `hide-reject-button` (`boolean`, default: `true`): Whether to display the reject button.
+- `accept-text` (`string`): Text for the accept button.
+- `accept-props` (`(Omit<MazBtnProps, "type"> & MazDialogConfirmButton)`, default: `{ color: 'success', type: 'accept', text: 'Confirm', response: 'accept' }`): Props for the accept button - will be applied only if buttons props is not provided.
+- `hide-accept-button` (`boolean`, default: `true`): Whether to display the accept button.
+- `buttons` (`MazDialogConfirmButton[]`): Buttons to display in the footer.
+- `model-value` (`boolean`): Modal's model value.
+- `hide-close-button` (`boolean`): Remove the close button in header.
+- `max-width` (`string`, default: `` Theme preset `components.dialog.max-width` via `var(--maz-dialog-max-width, 38rem)` ``): Modal's max-width.
+- `min-width` (`string`, default: `` Theme preset `components.dialog.min-width` via `var(--maz-dialog-min-width, 32rem)` ``): Modal's min-width.
+- `scrollable` (`boolean`): Modal's content becomes scrollable - warning: a overflow is applied.
+- `persistent` (`boolean`): Persistent dialog (not closable by clicking outside and remove close button).
+- `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
+
+- `@open` (payload: `value?: void | undefined`): Emitted when modal is open
+- `@close` (payload: `value?: void | undefined`): Emitted when modal is close
+
+### Slots
+
+- `#title`: title slot - Place your title
+- `#default`: Default slot - Place your content Bindings: `accept: (reason?: unknown) => Promise<unknown>` (accept function), `reject: (reason?: unknown) => Promise<unknown>` (reject function).
+- `#footer-button`: Footer slot Bindings: `accept: (reason?: unknown) => Promise<unknown>` (accept function), `reject: (reason?: unknown) => Promise<unknown>` (reject function).
+
+### Exposed (template ref)
+
+- `close`: Close the dialog
+- `isActive`: Check if the dialog is active

package/docs/components/maz-dialog.md

@@ -0,0 +1,143 @@
+---
+title: "MazDialog"
+description: "MazDialog is a standalone dialog component to show important informations to the user or propose specific action. Many options are available. You can hide the header or the footer, full-size layout, differents states etc."
+package: "maz-ui"
+url: "https://maz-ui.com/components/maz-dialog"
+---
+
+# MazDialog
+
+> MazDialog is a standalone dialog component to show important informations to the user or propose specific action. Many options are available. You can hide the header or the footer, full-size layout, differents states etc.
+
+- Package: `maz-ui`
+- Import: `import MazDialog from 'maz-ui/components/MazDialog'`
+- Nuxt: auto-imported by `@maz-ui/nuxt`, no import needed in a Nuxt app
+- Web: https://maz-ui.com/components/maz-dialog
+
+> 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">` with [MazBackdrop](./maz-backdrop.md), so you can implement this component anywhere and it inherits all its props
+
+## Basic usage
+
+```vue
+<script setup>
+import MazDialog from 'maz-ui/components/MazDialog'
+import { ref } from 'vue'
+
+const isOpen = ref(false)
+</script>
+
+<template>
+  <MazBtn @click="isOpen = true">
+    Open Dialog
+  </MazBtn>
+
+  <MazDialog v-model="isOpen" title="Dialog Title">
+    <p>
+      Your content
+    </p>
+
+    <template #footer="{ close }">
+      <MazBtn @click="close">
+        Confirm
+      </MazBtn>
+    </template>
+  </MazDialog>
+</template>
+```
+
+## Scrollable
+
+For long content, you can enable scrolling in content part (Header and footer slot remain visible at top and bottom)
+
+```html
+<MazDialog v-model="scollableOpened" title="Dialog Title" max-height="400px" scrollable>
+  <template #title> Scrollable Dialog Title </template>
+
+  <template #default>
+    <p v-for="i in 40" :key="i" style="padding-bottom: 2rem">Scroll down</p>
+  </template>
+
+  <template #footer>
+    <MazBtn @click="scollableOpened = false"> Confirm </MazBtn>
+  </template>
+</MazDialog>
+```
+
+## Width
+
+On tablet and up, the dialog is sized by two CSS variables coming from the active theme preset (`components.dialog`):
+
+- `--maz-dialog-max-width` (default `38rem`)
+- `--maz-dialog-min-width` (default `32rem`)
+
+You can set these defaults globally per preset - see [the theme `components.dialog` documentation](../ecosystem/themes.md#dialog-sizing). To change the width of a single dialog, pass the `max-width` / `min-width` props - they always override the preset:
+
+```vue
+<template>
+  <MazDialog
+    v-model="isOpen"
+    title="Custom width"
+    max-width="50rem"
+    min-width="40rem"
+  >
+    <p>This dialog overrides the preset width through props.</p>
+  </MazDialog>
+</template>
+```
+
+**Tip:**
+
+The default widths are expressed in `rem`, so they scale with the preset's `base-font-size`. Presets with a larger base size (e.g. `ocean` at `16px`) ship rem values adjusted to keep the rendered pixel width consistent across presets.
+
+## Accessibility
+
+- The dialog is a modal `dialog` (`aria-modal`), labelled by its title and described by its content (override them with the `aria-labelledby` / `aria-describedby` props).
+- The focus moves into the dialog on open, stays trapped inside and goes back to the previous element on close. Esc closes it (`close-on-escape`).
+- While it is open, the rest of the page is `inert` (no focus, no click, hidden from assistive technologies), except the toasts and the live regions.
+
+## MazDialog API
+
+`import MazDialog from 'maz-ui/components/MazDialog'`
+
+### Props
+
+- `model-value` (`boolean`, `v-model`): Modal's model value.
+- `title` (`string`): Title of the modal in header.
+- `hide-close-button` (`boolean`): Remove the close button in header.
+- `max-width` (`string`, default: `"var(--maz-dialog-max-width, 38rem)"`): Modal's max-width.
+- `min-width` (`string`, default: `"var(--maz-dialog-min-width, 32rem)"`): Modal's min-width.
+- `scrollable` (`boolean`): Modal's content becomes scrollable - warning: a overflow is applied.
+- `persistent` (`boolean`): Persistent dialog (not closable by clicking outside and remove close button).
+- `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 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
+
+### Slots
+
+- `#header`: Header slot Bindings: `close: () => void` (close function).
+- `#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 dialog

package/docs/components/maz-drawer.md

@@ -0,0 +1,106 @@
+---
+title: "MazDrawer"
+description: "MazDrawer is a standalone component to add a collapsible sidebar at the top and bottom bar"
+package: "maz-ui"
+url: "https://maz-ui.com/components/maz-drawer"
+---
+
+# MazDrawer
+
+> MazDrawer is a standalone component to add a collapsible sidebar at the top and bottom bar
+
+- Package: `maz-ui`
+- Import: `import MazDrawer from 'maz-ui/components/MazDrawer'`
+- Nuxt: auto-imported by `@maz-ui/nuxt`, no import needed in a Nuxt app
+- Web: https://maz-ui.com/components/maz-drawer
+
+> 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">` with [MazBackdrop](./maz-backdrop.md), so you can implement this component anywhere and it inherits all its props
+
+## Basic usage
+
+```html
+<MazBtn @click="isOpenedTop = !isOpenedTop"> Open top drawer </MazBtn>
+<MazBtn @click="isOpenedLeft = !isOpenedLeft"> Open left drawer </MazBtn>
+<MazBtn @click="isOpenedRight = !isOpenedRight"> Open right drawer </MazBtn>
+<MazBtn @click="isOpenedBottom = !isOpenedBottom"> Open bottom drawer </MazBtn>
+
+<MazDrawer variant="top" v-model="isOpenedTop">
+  <template #title> Drawer top </template>
+  <template #default="{ close }">
+    <div style="padding: 16px">
+      <p>Content</p>
+      <div class="flex flex-wrap gap-2 mt-4">
+        <MazBtn color="destructive" @click="close"> Close </MazBtn>
+      </div>
+    </div>
+  </template>
+</MazDrawer>
+
+<MazDrawer variant="bottom" v-model="isOpenedBottom">
+  <template #title> Drawer bottom </template>
+  <template #default="{ close }">
+    <div style="padding: 16px">
+      <p>Content</p>
+      <div class="flex flex-wrap gap-2 mt-4">
+        <MazBtn color="destructive" @click="close"> Close </MazBtn>
+      </div>
+    </div>
+  </template>
+</MazDrawer>
+
+<MazDrawer variant="start" v-model="isOpenedLeft">
+  <template #title> Drawer left </template>
+  <template #default="{ close }">
+    <div style="padding: 16px">
+      <p>Content</p>
+      <div class="flex flex-wrap gap-2 mt-4">
+        <MazBtn color="destructive" @click="close"> Close </MazBtn>
+      </div>
+    </div>
+  </template>
+</MazDrawer>
+
+<MazDrawer variant="end" v-model="isOpenedRight">
+  <template #title> Drawer right </template>
+  <template #default="{ close }">
+    <div style="padding: 16px">
+      <p>Content</p>
+      <div class="flex flex-wrap gap-2 mt-4">
+        <MazBtn color="destructive" @click="close"> Close </MazBtn>
+      </div>
+    </div>
+  </template>
+</MazDrawer>
+```
+
+## Accessibility
+
+The drawer is a modal `dialog` labelled by its `title`. 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). The close button is labelled from `@maz-ui/translations` (`aria.close`).
+
+## MazDrawer API
+
+`import MazDrawer from 'maz-ui/components/MazDrawer'`
+
+### Props
+
+- `title` (`string`): The title of the drawer.
+- `variant` (`"end" | "start" | "bottom" | "top"`, default: `"end"`): The edge from which the drawer slides in. `start` (= left in LTR, right in RTL) and `end` (= right in LTR, left in RTL) follow the document direction; `top` and `bottom` are physical.
+- `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... ``, default: `"30rem"`): The size of the drawer.
+- `backdrop-class` (`string`): The class of the backdrop.
+- `hide-close-button` (`boolean`): Disable the close button.
+
+### Events
+
+- `@update:model-value` (payload: `value: boolean`): emitted when drawer is open or close
+- `@open`: emitted when drawer is open
+- `@close`: emitted when drawer is close (after animation)
+- `@before-close`: emitted before drawer is close
+
+### Slots
+
+- `#title` Bindings: `close: () => void`.
+- `#default` Bindings: `close: () => void`.