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

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

@@ -1,31 +1,26 @@
 ---
-title: MazSelect - with "multiple" options
-description: MazSelect is a standalone component that replaces the standard html input select with a beautiful design system. There are many options like multiple values, search text field, custom templates options, colors, sizes, disabled, loading, error, warning, valid states, error messages, and icons.
+title: "MazSelect - with \"multiple\" options"
+description: "MazSelect is a standalone component that replaces the standard html input select with a beautiful design system. There are many options like multiple values, search text field, custom templates options, colors, sizes, disabled, loading, error, warning, valid states, error messages, and icons."
+package: "maz-ui"
+url: "https://maz-ui.com/components/maz-select"
 ---
 
-# {{ $frontmatter.title }}
+# MazSelect - with "multiple" options
 
-{{ $frontmatter.description }}
+> MazSelect is a standalone component that replaces the standard html input select with a beautiful design system. There are many options like multiple values, search text field, custom templates options, colors, sizes, disabled, loading, error, warning, valid states, error messages, and icons.
 
-<!--@include: ./../../.vitepress/mixins/getting-started.md-->
+- Package: `maz-ui`
+- Import: `import MazSelect from 'maz-ui/components/MazSelect'`
+- Nuxt: auto-imported by `@maz-ui/nuxt`, no import needed in a Nuxt app
+- Web: https://maz-ui.com/components/maz-select
 
-<!--@include: ./../../.vitepress/mixins/translated-component.md-->
+> Before use it, you should install the MazUi plugin in your project, follow instructions in [Getting Started](../guide/getting-started.md)
 
-## Basic usage
-
-<ComponentDemo expanded>
-  <MazSelect
-    label="Select color"
-    v-model="selectedValue"
-    :options="['primary', 'secondary', 'info', 'success', 'destructive', 'warning', 'white', 'black', 'red', 'green', 'blue', 'yellow', 'purple', 'orange', 'pink', 'brown', 'gray']"
-  />
-
-  <br />
-  <br />
+**Tip:**
 
-selectedValue: {{ selectedValue }}
+This component can be translated globally using the [MazUi](../ecosystem/translations.md) plugin.
 
-<template #code>
+## Basic usage
 
 ```vue
 <script setup lang="ts">
@@ -47,42 +42,21 @@ const selectedValue = ref()
 </template>
 ```
 
-  </template>
-</ComponentDemo>
-
 ## Multiple
 
-<ComponentDemo>
-  <MazSelect
-    v-model="selectedValues"
-    :options="colors"
-    label="Choose options"
-    multiple
-  />
-
-  <br />
-  <br />
-
-selectedValues: {{ selectedValues }}
-
-<template #code>
-
 ```html
 <MazSelect v-model="selectedValues" :options="colors" label="Choose options" multiple />
 ```
 
-</template>
-
-</ComponentDemo>
-
 ## Search
 
 Use `search` property to add a search input in the options list
 
-::: tip
+**Tip:**
+
 You can use your own template to replace the empty icon when no results are found
 
-::: details View code
+**Details: View code**
 
 ```html
 <MazSelect>
@@ -92,44 +66,22 @@ You can use your own template to replace the empty icon when no results are foun
 </MazSelect>
 ```
 
-:::
+**Note:**
 
-::: info
 You can adjust the search results by using `search-threshold` where 1 is a perfect match and 0 is a match with any character
 
 ```html
 <MazSelect :search-threshold="0.75" :options="[...]" />
 ```
 
-:::
-
-<ComponentDemo>
-  <MazSelect label="Select color" v-model="selectedValue" :options="colors" search />
-
-<template #code>
-
 ```html
 <MazSelect v-model="selectedValue" label="Select color" :options="colors" search />
 ```
 
-  </template>
-</ComponentDemo>
-
 ### Custom search function
 
 You can provide your own search function to customize the search behavior
 
-<ComponentDemo>
-  <MazSelect
-    placeholder="Select color"
-    v-model="selectedValue"
-    :options="colors"
-    search
-    :search-function="customSearchFunction"
-  />
-
-<template #code>
-
 ```vue
 <script lang="ts" setup>
 import MazSelect from 'maz-ui/components/MazSelect'
@@ -154,23 +106,10 @@ function customSearchFunction(query: string, options: typeof colors) {
 </template>
 ```
 
-</template>
-</ComponentDemo>
-
 ## Opt Group
 
 Group your options like a native optgroup
 
-<ComponentDemo>
-  <MazSelect
-    v-model="optGroupValue"
-    label="Select options"
-    :options="optGroup"
-    multiple
-  />
-
-<template #code>
-
 ```vue
 <script setup lang="ts">
 import { ref } from 'vue'
@@ -191,21 +130,8 @@ const optGroup = [
 </template>
 ```
 
-  </template>
-</ComponentDemo>
-
 ## Disabled
 
-<ComponentDemo>
-  <MazSelect
-    label="Select color"
-    v-model="selectedValue"
-    :options="colors"
-    disabled
-  />
-
-  <template #code>
-
 ```html
 <MazSelect
   label="Select color"
@@ -215,25 +141,8 @@ const optGroup = [
 />
 ```
 
-  </template>
-</ComponentDemo>
-
 ## Size
 
-<ComponentDemo>
-  <div class="maz:flex maz:flex-col maz:gap-2">
-    <MazSelect
-      v-for="size in sizes"
-      :key="size"
-      label="Select color"
-      v-model="selectedValue"
-      :options="colors"
-      :size="size"
-    />
-  </div>
-
-  <template #code>
-
 ```vue
 <template>
   <MazSelect
@@ -256,31 +165,10 @@ const optGroup = [
 </script>
 ```
 
-  </template>
-</ComponentDemo>
-
 ## Custom template options
 
 Customize the options list with your own template
 
-<ComponentDemo>
-  <MazSelect
-    label="Select color"
-  v-model="selectedUser"
-  :options="customTemplateOptions"
-  v-slot="{ option, isSelected }"
-  search
->
-  <div class="flex items-center" style="width: 100%; gap: 1rem">
-    <MazAvatar size="0.8rem" :src="option.picture" />
-    <strong>
-      {{ option.label }}
-    </strong>
-  </div>
-</MazSelect>
-
-<template #code>
-
 ```vue{6}
 <template>
   <MazSelect
@@ -314,9 +202,6 @@ Customize the options list with your own template
 </script>
 ```
 
-  </template>
-</ComponentDemo>
-
 ## Custom options model
 
 By default, the options should be an array of `{ value: any, label: string }`
@@ -329,21 +214,6 @@ If you want custom keys of these options, you can use:
 
 ### Example
 
-<br />
-
-<ComponentDemo>
-  <MazSelect
-    v-model="selectedValueCustom"
-    :options="customOptions"
-    :color="selectedValueCustom"
-    option-value-key="valueOption"
-    option-label-key="labelOption"
-    option-input-value-key="inputLabel"
-    search
-  />
-
-<template #code>
-
 ```vue
 <script lang="ts" setup>
 import { ref } from 'vue'
@@ -374,61 +244,6 @@ const customOptions = [
 </template>
 ```
 
-  </template>
-</ComponentDemo>
-
-<script setup lang="ts">
-  import { ref } from 'vue'
-
-  const optGroupValue = ref()
-  const selectedValue = ref()
-  const selectedValueCustom = ref('destructive')
-  const selectedUser = ref()
-  const selectedValues = ref()
-
-  const sizes = ['mini', 'xs', 'sm', 'md', 'lg', 'xl']
-
-  const colors = [
-    { label: 'primary', value: 'primary' },
-    { label: 'secondary', value: 'secondary' },
-    { label: 'info', value: 'info' },
-    { label: 'success', value: 'success' },
-    { label: 'warning', value: 'warning' },
-    { label: 'destructive', value: 'destructive' },
-    { label: 'white', value: 'white' },
-    { label: 'black', value: 'black' },
-  ]
-
-  const optGroup = [
-    { label: 'Basic colors', options: ['primary', 'secondary', 'destructive'] },
-    { label: 'Custom colors', options: [{ label: 'third', value: 'third' }] },
-  ]
-
-  const customTemplateOptions = [
-    { picture: 'https://api.dicebear.com/7.x/big-smile/svg?backgroundColor=1d90ff&seed=JamesSmile', label: 'James Smile', value: 1 },
-    { picture: 'https://api.dicebear.com/7.x/big-smile/svg?backgroundColor=1d90ff&seed=BradSmile', label: 'Brad Smile', value: 2 },
-    { picture: 'https://api.dicebear.com/7.x/big-smile/svg?backgroundColor=1d90ff&seed=CedricSmile', label: 'Cedric Smile', value: 3 },
-    { picture: 'https://api.dicebear.com/7.x/big-smile/svg?backgroundColor=1d90ff&seed=HarrySmile', label: 'Harry Smile', value: 4 },
-  ]
-
-  const customOptions = [
-    { valueOption: 'primary', labelOption: 'primary label', inputLabel: 'primary input', },
-    { valueOption: 'secondary', labelOption: 'secondary label', inputLabel: 'secondary input', },
-    { valueOption: 'info', labelOption: 'info label', inputLabel: 'info input', },
-    { valueOption: 'success', labelOption: 'success label', inputLabel: 'success input', },
-    { valueOption: 'warning', labelOption: 'warning label', inputLabel: 'warning input', },
-    { valueOption: 'destructive', labelOption: 'destructive label', inputLabel: 'destructive input', },
-    { valueOption: 'white', labelOption: 'white label', inputLabel: 'white input', },
-    { valueOption: 'black', labelOption: 'black label', inputLabel: 'black input', },
-  ]
-
-  const alwaysShowMembersBets = ref()
-
-  function customSearchFunction(query: string, options: typeof colors) {
-    return options.filter((option) => option.label.toLowerCase().includes(query.toLowerCase()))
-  }
-</script>
-
 ### Types
 
 ```ts
@@ -441,8 +256,63 @@ type ModelValueSimple = string | number | null | undefined | boolean
 
 - The input is a `combobox` (`aria-haspopup="listbox"`, `aria-expanded`, `aria-controls`).
 - The list is a `listbox` (`aria-multiselectable` in multiple mode) labelled by the `label`, `top-label` or `placeholder`, each option is an `option` with `aria-selected`.
-- **Keyboard**: <kbd>↓</kbd> / <kbd>↑</kbd> / <kbd>Space</kbd> or a letter open the list, the arrows move between options, <kbd>Home</kbd> / <kbd>End</kbd> go to the first / last option, <kbd>Enter</kbd> selects, <kbd>Esc</kbd> closes.
+- **Keyboard**: ↓ / ↑ / Space or a letter open the list, the arrows move between options, Home / End go to the first / last option, Enter selects, Esc closes.
 - The labels read by screen readers (toggle button, empty results) come from `@maz-ui/translations` (`aria` namespace).
 
-<!--@include: ./../../.vitepress/mixins/maz-input-props.md-->
-<!--@include: ./../../.vitepress/generated-docs/maz-select.doc.md-->
+## MazSelect API
+
+`import MazSelect from 'maz-ui/components/MazSelect'`
+
+### Props
+
+- `id` (`string`): The id of the select.
+- `label` (`string`): The label of the select.
+- `top-label` (`string`): Static label displayed above the input field. Unlike the floating label, this remains fixed.
+- `placeholder` (`string`): The placeholder of the select.
+- `model-value` (`(Multiple extends true ? Value[] : Value)`, `v-model`): The value of the select.
+- `options` (`Option[]`, required): The options of the select.
+- `option-value-key` (`string`, default: `"value"`): The key of the option value.
+- `option-label-key` (`string`, default: `"label"`): The key of the option label.
+- `option-input-value-key` (`string`, default: `"label"`): The key of the option input value.
+- `list-position` (`MazPopoverPosition`, default: `"auto"`): The position of the list (auto by default - will switch between bottom-start and top-start).
+- `prefer-position` (`MazPopoverPreferPosition`, default: `"bottom-start"`): The prefer position of the list.
+- `fallback-position` (`MazPopoverFallbackPosition`, default: `"top-start"`): The fallback position of the list.
+- `item-height` (`number`): The height of the option list item.
+- `max-list-height` (`number`, default: `240`): The max height of the option list.
+- `max-list-width` (`number`): The max width of the option list.
+- `min-list-height` (`number`): The min height of the option list.
+- `min-list-width` (`number`): The min width of the option list.
+- `size` (`"xs" | "sm" | "md" | "lg" | "xl" | "mini"`, default: `'md'`): The size of the select.
+- `color` (`"primary" | "secondary" | "accent" | "info" | "success" | "warning" | "destructive" | "contrast" | "transparent"`, default: `"primary"`): The color of the select.
+- `search` (`boolean`): Display search input in option list.
+- `search-function` (`((query: string, options: Option[]) => Option[] | undefined)`): Replace the default search function to provide a custom search function.
+- `search-threshold` (`number`, default: `0.75`): The threshold for the search input where 1 is a perfect match and 0 is a match with any character.
+- `multiple` (`Multiple`, default: `false`): Enable the multiple selection.
+- `required` (`boolean`): Make the input required in the form.
+- `disabled` (`boolean`): Disable the component.
+- `block` (`boolean`): The input will be displayed in full width.
+- `autocomplete` (`string`, default: `"off"`): The autocomplete attribute of the input.
+- `translations` (`Partial<{ searchPlaceholder: string; }>`, default: `{ searchPlaceholder: 'Search in options', }`): The translations of the component.
+- `format-input-value` (`((value: Multiple extends true ? Value[] : Value) => string)`): The function to format the input value.
+- `transition` (`string`, default: `"scale-fade"`): The transition name of the panel list options.
+- `open` (`boolean`, default: `false`, `v-model:open`)
+
+### Events
+
+- `@update:model-value` (payload: `value: Multiple extends true ? Value[] : Value`): On model value update, returns the new value
+- `@open`: On list is opened
+- `@close`: On list is closed
+- `@blur` (payload: `value: Event`): On input blur
+- `@change` (payload: `value: Event`): On input change value
+- `@focus` (payload: `value?: Event | undefined`): On input focus
+- `@input` (payload: `value: Event`): On input value
+- `@selected-option` (payload: `value: Option`): On selected value, returns the option object
+- `@update:open` (payload: `value: boolean`)
+
+### Slots
+
+- `#start-icon`: Add a custom inline-start icon (left in LTR, right in RTL) Bindings: `isOpen: false` (Current open state of the popover), `close: () => void` (Function to close the popover), `open: () => void` (Function to open the popover), `toggle: () => void` (Function to toggle the popover).
+- `#end-icon`: Add and replace a custom inline-end icon (right in LTR, left in RTL) Bindings: `isOpen: false` (Current open state of the popover), `close: () => void` (Function to close the popover), `open: () => void` (Function to open the popover), `toggle: () => void` (Function to toggle the popover).
+- `#no-results`: No results slot - Displayed when no results corresponding with search query
+- `#optgroup`: Custom optgroup label Bindings: `label: string | number | true` (the label of the optgroup).
+- `#default`: Custom option Bindings: `option: Option` (the option object), `isSelected: boolean` (if the option is selected), `isOpen: false` (if the popover is open), `close: () => void` (function to close the popover), `open: () => void` (function to open the popover), `toggle: () => void` (function to toggle the popover).

package/docs/components/maz-sidebar-content.md

@@ -0,0 +1,25 @@
+---
+title: "MazSidebarContent"
+description: "MazSidebarContent component."
+package: "maz-ui"
+---
+
+# MazSidebarContent
+
+> MazSidebarContent component.
+
+- Package: `maz-ui`
+- Import: `import MazSidebarContent from 'maz-ui/components/MazSidebarContent'`
+- Nuxt: auto-imported by `@maz-ui/nuxt`, no import needed in a Nuxt app
+
+## MazSidebarContent API
+
+`import MazSidebarContent from 'maz-ui/components/MazSidebarContent'`
+
+### Props
+
+No props.
+
+### Slots
+
+- `#default`

package/docs/components/maz-sidebar-footer.md

@@ -0,0 +1,25 @@
+---
+title: "MazSidebarFooter"
+description: "MazSidebarFooter component."
+package: "maz-ui"
+---
+
+# MazSidebarFooter
+
+> MazSidebarFooter component.
+
+- Package: `maz-ui`
+- Import: `import MazSidebarFooter from 'maz-ui/components/MazSidebarFooter'`
+- Nuxt: auto-imported by `@maz-ui/nuxt`, no import needed in a Nuxt app
+
+## MazSidebarFooter API
+
+`import MazSidebarFooter from 'maz-ui/components/MazSidebarFooter'`
+
+### Props
+
+No props.
+
+### Slots
+
+- `#default`

package/docs/components/maz-sidebar-group.md

@@ -0,0 +1,27 @@
+---
+title: "MazSidebarGroup"
+description: "MazSidebarGroup is a building block of MazSidebar."
+package: "maz-ui"
+---
+
+# MazSidebarGroup
+
+> MazSidebarGroup is a building block of MazSidebar.
+
+- Package: `maz-ui`
+- Import: `import MazSidebarGroup from 'maz-ui/components/MazSidebarGroup'`
+- Nuxt: auto-imported by `@maz-ui/nuxt`, no import needed in a Nuxt app
+
+Used inside [MazSidebar](./maz-sidebar.md): read its page for complete examples.
+
+## MazSidebarGroup API
+
+`import MazSidebarGroup from 'maz-ui/components/MazSidebarGroup'`
+
+### Props
+
+- `label` (`string`): Optional label for the group.
+
+### Slots
+
+- `#default`

package/docs/components/maz-sidebar-header.md

@@ -0,0 +1,25 @@
+---
+title: "MazSidebarHeader"
+description: "MazSidebarHeader component."
+package: "maz-ui"
+---
+
+# MazSidebarHeader
+
+> MazSidebarHeader component.
+
+- Package: `maz-ui`
+- Import: `import MazSidebarHeader from 'maz-ui/components/MazSidebarHeader'`
+- Nuxt: auto-imported by `@maz-ui/nuxt`, no import needed in a Nuxt app
+
+## MazSidebarHeader API
+
+`import MazSidebarHeader from 'maz-ui/components/MazSidebarHeader'`
+
+### Props
+
+No props.
+
+### Slots
+
+- `#default`

package/docs/components/maz-sidebar-menu-button.md

@@ -0,0 +1,41 @@
+---
+title: "MazSidebarMenuButton"
+description: "MazSidebarMenuButton is a building block of MazSidebar."
+package: "maz-ui"
+---
+
+# MazSidebarMenuButton
+
+> MazSidebarMenuButton is a building block of MazSidebar.
+
+- Package: `maz-ui`
+- Import: `import MazSidebarMenuButton from 'maz-ui/components/MazSidebarMenuButton'`
+- Nuxt: auto-imported by `@maz-ui/nuxt`, no import needed in a Nuxt app
+
+Used inside [MazSidebar](./maz-sidebar.md): read its page for complete examples.
+
+## MazSidebarMenuButton API
+
+`import MazSidebarMenuButton from 'maz-ui/components/MazSidebarMenuButton'`
+
+### Props
+
+- `to` (`string | Record<string, unknown>`): Route for router-link navigation.
+- `href` (`string`): URL for anchor navigation.
+- `icon` (`any`): Icon to display before the label. Accepts a bare icon value (Vue component, raw SVG string, URL) or a full `MazIconProps` object for fine-grained control (size, title, fallback, …).
+- `label` (`string`): Label text.
+- `badge` (`MazSidebarMenuButtonBadge`): Badge content. Pass a `string`/`number` for a simple primary badge, or a full `MazBadgeProps` object (with optional `text`) to customise color, size, outlined, ….
+- `tooltip` (`string`): Tooltip text. When provided, shows a tooltip on hover via the `v-tooltip` directive.
+- `tooltip-mode` (`MazSidebarTooltipMode`): Controls when the tooltip should be displayed. - `always`: tooltip shows on hover regardless of the sidebar state - `closed`: tooltip only shows on hover when the sidebar is collapsed Overrides the parent `MazSidebar`'s `tooltipMode`. Falls back to the sidebar value (which defaults to `always`) when not provided.
+- `active` (`boolean`): Whether the item is active (highlights with `aria-current="page"`).
+- `disabled` (`boolean`): Whether the item is disabled.
+- `size` (`"sm" | "md" | "lg"`, default: `"md"`): Size of the button.
+
+### Events
+
+- `@click` (payload: `event: MouseEvent`)
+
+### Slots
+
+- `#icon`
+- `#default`

package/docs/components/maz-sidebar-menu-item.md

@@ -0,0 +1,25 @@
+---
+title: "MazSidebarMenuItem"
+description: "MazSidebarMenuItem component."
+package: "maz-ui"
+---
+
+# MazSidebarMenuItem
+
+> MazSidebarMenuItem component.
+
+- Package: `maz-ui`
+- Import: `import MazSidebarMenuItem from 'maz-ui/components/MazSidebarMenuItem'`
+- Nuxt: auto-imported by `@maz-ui/nuxt`, no import needed in a Nuxt app
+
+## MazSidebarMenuItem API
+
+`import MazSidebarMenuItem from 'maz-ui/components/MazSidebarMenuItem'`
+
+### Props
+
+No props.
+
+### Slots
+
+- `#default`

package/docs/components/maz-sidebar-menu-sub.md

@@ -0,0 +1,32 @@
+---
+title: "MazSidebarMenuSub"
+description: "MazSidebarMenuSub is a building block of MazSidebar."
+package: "maz-ui"
+---
+
+# MazSidebarMenuSub
+
+> MazSidebarMenuSub is a building block of MazSidebar.
+
+- Package: `maz-ui`
+- Import: `import MazSidebarMenuSub from 'maz-ui/components/MazSidebarMenuSub'`
+- Nuxt: auto-imported by `@maz-ui/nuxt`, no import needed in a Nuxt app
+
+Used inside [MazSidebar](./maz-sidebar.md): read its page for complete examples.
+
+## MazSidebarMenuSub API
+
+`import MazSidebarMenuSub from 'maz-ui/components/MazSidebarMenuSub'`
+
+### Props
+
+- `label` (`string`): Label for the sub-menu trigger button.
+- `icon` (`any`): Icon to display before the label. Accepts a bare icon value (Vue component, raw SVG string, URL) or a full `MazIconProps` object for fine-grained control.
+- `default-open` (`boolean`, default: `false`): Whether the sub-menu is open by default.
+
+### Slots
+
+- `#icon`
+- `#label`
+- `#chevron`
+- `#default`

package/docs/components/maz-sidebar-menu.md

@@ -0,0 +1,25 @@
+---
+title: "MazSidebarMenu"
+description: "MazSidebarMenu component."
+package: "maz-ui"
+---
+
+# MazSidebarMenu
+
+> MazSidebarMenu component.
+
+- Package: `maz-ui`
+- Import: `import MazSidebarMenu from 'maz-ui/components/MazSidebarMenu'`
+- Nuxt: auto-imported by `@maz-ui/nuxt`, no import needed in a Nuxt app
+
+## MazSidebarMenu API
+
+`import MazSidebarMenu from 'maz-ui/components/MazSidebarMenu'`
+
+### Props
+
+No props.
+
+### Slots
+
+- `#default`

package/docs/components/maz-sidebar-separator.md

@@ -0,0 +1,21 @@
+---
+title: "MazSidebarSeparator"
+description: "MazSidebarSeparator component."
+package: "maz-ui"
+---
+
+# MazSidebarSeparator
+
+> MazSidebarSeparator component.
+
+- Package: `maz-ui`
+- Import: `import MazSidebarSeparator from 'maz-ui/components/MazSidebarSeparator'`
+- Nuxt: auto-imported by `@maz-ui/nuxt`, no import needed in a Nuxt app
+
+## MazSidebarSeparator API
+
+`import MazSidebarSeparator from 'maz-ui/components/MazSidebarSeparator'`
+
+### Props
+
+No props.

package/docs/components/maz-sidebar-trigger.md

@@ -0,0 +1,25 @@
+---
+title: "MazSidebarTrigger"
+description: "MazSidebarTrigger component."
+package: "maz-ui"
+---
+
+# MazSidebarTrigger
+
+> MazSidebarTrigger component.
+
+- Package: `maz-ui`
+- Import: `import MazSidebarTrigger from 'maz-ui/components/MazSidebarTrigger'`
+- Nuxt: auto-imported by `@maz-ui/nuxt`, no import needed in a Nuxt app
+
+## MazSidebarTrigger API
+
+`import MazSidebarTrigger from 'maz-ui/components/MazSidebarTrigger'`
+
+### Props
+
+No props.
+
+### Slots
+
+- `#default`