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

package/docs/components/maz-dropdown.md

@@ -0,0 +1,419 @@
+---
+title: "MazDropdown"
+description: "MazDropdown is a standalone dropdown menu component and versatile designed for various use cases."
+package: "maz-ui"
+url: "https://maz-ui.com/components/maz-dropdown"
+---
+
+# MazDropdown
+
+> MazDropdown is a standalone dropdown menu component and versatile designed for various use cases.
+
+- Package: `maz-ui`
+- Import: `import MazDropdown from 'maz-ui/components/MazDropdown'`
+- Nuxt: auto-imported by `@maz-ui/nuxt`, no import needed in a Nuxt app
+- Web: https://maz-ui.com/components/maz-dropdown
+
+> Before use it, you should install the MazUi plugin in your project, follow instructions in [Getting Started](../guide/getting-started.md)
+
+**Tip:**
+
+This component can be translated globally using the [MazUi](../ecosystem/translations.md) plugin.
+
+## Basic usage
+
+```vue
+<template>
+  <MazDropdown
+    :items="[
+      { label: 'Action', onClick: () => toast.success('CLICKED') },
+      { label: 'Link (href)', href: 'https://www.google.com', target: '_blank', color: 'secondary' },
+      { label: 'Router Link', to: { name: 'index' }, color: 'destructive' },
+    ]"
+  >
+    Dropdown Menu
+  </MazDropdown>
+</template>
+
+<script lang="ts" setup>
+  import MazDropdown from 'maz-ui/components/MazDropdown'
+</script>
+```
+
+## Open dropdown with adaptive trigger
+
+The `adaptive` trigger mode automatically adapts to the user's device:
+- **Desktop**: Uses hover behavior (mouseenter/mouseleave)
+- **Mobile/Touch devices**: Uses click behavior
+
+This provides the best user experience across all devices without requiring manual configuration.
+
+```html{7}
+<MazDropdown
+  :items="[
+    { label: 'Action', onClick: () => toast.success('CLICKED') },
+    { label: 'Link (href)', href: 'https://www.google.com', target: '_blank' },
+    { label: 'Router Link', to: { name: 'index' } },
+  ]"
+  trigger="adaptive"
+>
+  Adaptive trigger
+</MazDropdown>
+```
+
+## Open dropdown only on click
+
+```html{7}
+<MazDropdown
+  :items="[
+    { label: 'Action', onClick: () => toast.success('CLICKED') },
+    { label: 'Link (href)', href: 'https://www.google.com', target: '_blank' },
+    { label: 'Router Link', to: { name: 'index' } },
+  ]"
+  trigger="click"
+>
+  Click me
+</MazDropdown>
+```
+
+## Open dropdown only on hover
+
+```html{7}
+<MazDropdown
+  :items="[
+    { label: 'Action', onClick: () => toast.success('CLICKED') },
+    { label: 'Link (href)', href: 'https://www.google.com', target: '_blank' },
+    { label: 'Router Link', to: { name: 'index' } },
+  ]"
+  trigger="hover"
+>
+  Hover me
+</MazDropdown>
+```
+
+## Custom dropdown icon
+
+You can provide an icon to replace the default chevron icon and disable the animation
+
+```vue{7}
+<script lang="ts" setup>
+  // Use vite-svg-loader to import SVG as Vue component
+  import MazChevronUpDown from '@maz-ui/icons/chevron-up-down.svg?component'
+</script>
+
+<template>
+  <MazDropdown
+    :items="[
+      { label: 'Action', onClick: () => toast.success('CLICKED') },
+      { label: 'Link (href)', href: 'https://www.google.com', target: '_blank' },
+      { label: 'Router Link', to: { name: 'index' } },
+    ]"
+    trigger="hover"
+    :dropdown-icon="MazChevronUpDown"
+  >
+    Hover me
+  </MazDropdown>
+
+  <MazDropdown
+    :items="[
+      { label: 'Action', onClick: () => toast.success('CLICKED') },
+      { label: 'Link (href)', href: 'https://www.google.com', target: '_blank' },
+      { label: 'Router Link', to: { name: 'index' } },
+    ]"
+    trigger="hover"
+    :dropdown-icon="MazChevronUpDown"
+    :dropdown-icon-animation="false"
+  >
+    No icon animation
+  </MazDropdown>
+</template>
+```
+
+`dropdownIcon` also accepts a full `MazIconProps` object - pass the same shape `<MazIcon>` accepts when you need to set a `<title>` for screen readers, override the size, or attach `svgAttributes`.
+
+```vue
+<MazDropdown
+  :items="items"
+  :dropdown-icon="{
+    icon: MazChevronUpDown,
+    size: 'lg',
+    title: 'Open menu',
+  }"
+>
+  Custom icon
+</MazDropdown>
+```
+
+## Custom dropdown main button without chevron icon
+
+**Tip:**
+
+  This component uses [MazBtn](./maz-btn.md) has a menu button, so it inherits all its props
+
+**Details: View code**
+
+```vue{7-13}
+<script lang="ts" setup>
+  import { MazBars3 } from '@maz-ui/icons/raw/MazBars3'
+</script>
+
+<template>
+  <MazDropdown
+    color="primary"
+    fab
+    pastel
+    :chevron="false"
+    :icon="MazBars3"
+    items-size="sm"
+    size="xl"
+    :items="[
+      { label: 'Action', onClick: () => toast.success('CLICKED') },
+      { label: 'Link (href)', href: 'https://www.google.com', target: '_blank' },
+      { label: 'Router Link', to: { name: 'index' } },
+    ]"
+    :close-on-click="false"
+  />
+</template>
+```
+
+## Custom slots
+
+### Custom dropdown panel
+
+You can provide a template to replace the default dropdown panel
+
+**Details: View code**
+
+```html
+<MazDropdown>
+  Customized dropdown panel
+
+  <template #dropdown>
+    <div class="grid grid-cols-3 gap-2">
+      <MazBtn color="transparent"> Item </MazBtn>
+      <MazBtn color="transparent"> Item </MazBtn>
+      <MazBtn color="transparent"> Item </MazBtn>
+      <MazBtn color="transparent"> Item </MazBtn>
+      <MazBtn color="transparent"> Item </MazBtn>
+      <MazBtn color="transparent"> Item </MazBtn>
+      <MazBtn color="transparent"> Item </MazBtn>
+      <MazBtn color="transparent"> Item </MazBtn>
+      <MazBtn color="transparent"> Item </MazBtn>
+      <MazBtn color="transparent"> Item </MazBtn>
+      <MazBtn color="transparent"> Item </MazBtn>
+      <MazBtn color="transparent"> Item </MazBtn>
+    </div>
+  </template>
+</MazDropdown>
+```
+
+### Custom menuitem labels
+
+You can provide a template to replace menuitem labels to add more elements in each menuitem
+
+**Details: View code**
+
+```html
+<MazDropdown
+  :items="[
+    { label: 'Action', onClick: () => toast.success('CLICKED'), additionnalData: 'https://placedog.net/240/200' },
+    { label: 'Link (href)', href: 'https://www.google.com', target: '_blank', additionnalData: 'https://placedog.net/340/300' },
+    { label: 'Router Link', to: { name: 'index' }, additionnalData: 'https://placedog.net/440/400' },
+  ]"
+>
+  <template #default>
+    Customized labels
+  </template>
+
+  <template #menuitem-label="{ item }">
+    <div class="flex items-center gap-2">
+      <MazAvatar :src="item.additionnalData" />
+      <span>
+        {{ item.label }}
+      </span>
+    </div>
+  </template>
+</MazDropdown>
+```
+
+### Custom control triggered element
+
+You can provide an HTML element or a component to replace the default button
+
+**Warning:**
+
+Add `tabindex="-1"` attribute to your element to avoid a double focus with Tab key
+
+**Details: View code**
+
+```html
+<MazDropdown
+  :items="[
+    {
+      label: 'Action',
+      onClick: () => toast.success('CLICKED'),
+      additionnalData: 'https://placedog.net/240/200',
+    },
+    {
+      label: 'Link (href)',
+      href: 'https://www.google.com',
+      target: '_blank',
+      additionnalData: 'https://placedog.net/340/300',
+    },
+    {
+      label: 'Router Link',
+      to: { name: 'index' },
+      additionnalData: 'https://placedog.net/440/400',
+    },
+  ]"
+>
+  <template #element>
+    <MazAvatar
+      clickable
+      hide-clickable-icon
+      src="https://cdn.artphotolimited.com/images/5ff5a529bd40b83c5a537440/1000x1000/gerard-depardieu-1983.jpg"
+      tabindex="-1"
+    />
+  </template>
+</MazDropdown>
+
+<MazDropdown
+  position="top"
+  :items="[
+    {
+      label: 'Action',
+      onClick: () => toast.success('CLICKED'),
+      additionnalData: 'https://placedog.net/240/200',
+    },
+    {
+      label: 'Link (href)',
+      href: 'https://www.google.com',
+      target: '_blank',
+      additionnalData: 'https://placedog.net/340/300',
+    },
+    {
+      label: 'Router Link',
+      to: { name: 'index' },
+      additionnalData: 'https://placedog.net/440/400',
+    },
+  ]"
+>
+  <template #element="{ isOpen }">
+    <button class="border border-solid border-divider-400 p-2 hover:bg-surface-400" tabindex="-1">
+      HTMLButtonElement: isOpen {{ isOpen }}
+    </button>
+  </template>
+</MazDropdown>
+```
+
+## Open programmatically
+
+isOpen:
+
+```vue
+<template>
+  <MazDropdown
+    v-model="isOpen"
+    :items="[
+      { label: 'Action', onClick: () => toast.success('CLICKED') },
+      { label: 'Link (href)', href: 'https://www.google.com', target: '_blank' },
+      { label: 'Router Link', to: { name: 'index' } },
+    ]"
+  >
+    Open
+  </MazDropdown>
+
+  <MazBtn @click="isOpen = !isOpen">
+    Open Dropdown
+  </MazBtn>
+</template>
+
+<script lang="ts" setup>
+  import { ref } from 'vue'
+
+  const isOpen = ref(false)
+</script>
+```
+
+## Position
+
+## Types
+
+### MazDropdownMenuItem
+
+```ts
+type MazDropdownMenuItem = {
+  label: string
+  onClick?: () => unknown
+  target?: string
+  href?: string
+  to?: RouteLocationRaw
+  class?: string
+} & Record<string, unknown>
+```
+
+## Accessibility
+
+The trigger button exposes the menu state (`aria-haspopup="menu"`, `aria-expanded`, `aria-controls`), the panel is a `menu` and each item a `menuitem`. ↓ / ↑ move between the items, Enter runs the focused item and Esc closes the menu.
+
+## MazDropdown API
+
+`import MazDropdown from 'maz-ui/components/MazDropdown'`
+
+### Props
+
+- `model-value` (`boolean`, default: `false`, `v-model`): Controls whether the dropdown menu is open.
+- `items` (`MazDropdownMenuItem[]`, default: `[]`): Menu items to display in the dropdown Each item can be either a link (with href/to properties) or an action (with onClick function).
+- `items-size` (`"xs" | "sm" | "md" | "lg" | "xl" | "mini"`): Size of the dropdown menu items.
+- `id` (`string`): Unique identifier for the dropdown component.
+- `trigger` (`MazPopoverTrigger`, default: `"adaptive"`): Determines how the dropdown should be triggered. Values: `'click'`, `'hover'`, `'manual'`, `'adaptive'` (non exhaustive).
+- `color` (`"primary" | "secondary" | "accent" | "info" | "success" | "warning" | "destructive" | "contrast" | "transparent"`, default: `"transparent"`): Color theme for the dropdown button.
+- `position` (`MazPopoverPosition`, default: `"auto"`): Position of the menu relative to trigger. Values: `'auto'`, `'top'`, `'bottom'`, `'left'`, `'right'`, `'top-start'`, `'top-end'`, `'bottom-start'`, `'bottom-end'`, `'left-start'`, `'left-end'`, `'right-start'`, `'right-end'` (non exhaustive).
+- `close-on-click` (`boolean`, default: `false`): Controls whether the dropdown menu closes when a menu item is clicked.
+- `disabled` (`boolean`, default: `false`): Disables the dropdown functionality.
+- `chevron` (`boolean`, default: `true`): Controls whether to show the chevron icon in the trigger button.
+- `screen-reader-description` (`string`, default: `MazUiTranslationsSchema['dropdown']['screenReaderDescription']`): Accessible description for screen readers describing the dropdown functionality If not provided, the default translation of MazUiTranslations plugin will be used.
+- `menu-panel-class` (`ClassValue`): Additional CSS classes to apply to the dropdown menu panel Useful for customizing the dropdown appearance (background, border, etc.).
+- `menu-panel-style` (`StyleValue`): Inline styles to apply to the dropdown menu panel Useful for custom styling. You may use `!important` to override default styles.
+- `block` (`boolean`, default: `false`): Makes the dropdown button expand to full width of its container.
+- `dropdown-icon` (`any`): Icon to use instead of the default chevron for the dropdown indicator Custom icon to display in place of the default chevron. Accepts a bare value (Vue component, raw SVG string, URL or `data:` URI) or a full `MazIconProps` object.
+- `dropdown-icon-animation` (`boolean`, default: `true`): Controls whether the dropdown icon rotates when the dropdown is opened.
+- `size` (`"xs" | "sm" | "md" | "lg" | "xl" | "mini"`, default: `'md'`): Size of the dropdown button.
+- `transition` (`string`, default: `"scale-pop"`): Transition to use when the dropdown is opened or closed. Values: `'scale-pop'`, `'scale-fade'`, `'string'` (non exhaustive).
+- `delay` (`number`, default: `0`): Delay before showing/hiding in milliseconds.
+- `persistent` (`boolean`, default: `false`): Prevent auto-close (ignores click outside and escape key).
+- `close-on-escape` (`boolean`, default: `true`): Close popover when pressing Escape key.
+- `aria-labelledby` (`string`): ARIA labelledby attribute for accessibility.
+- `aria-describedby` (`string`): ARIA describedby attribute for accessibility.
+- `aria-label` (`string`): ARIA label for the popover.
+- `offset` (`number`, default: `8`): Distance between trigger and popover in pixels.
+- `prefer-position` (`MazPopoverPreferPosition`, default: `"bottom-start"`): Preferred position of the popover relative to trigger when auto position is used - Preferred position of the popover relative to trigger. Values: `'auto'`, `'top'`, `'bottom'`, `'left'`, `'right'`, `'top-start'`, `'top-end'`, `'bottom-start'`, `'bottom-end'`, `'left-start'`, `'left-end'`, `'right-start'`, `'right-end'` (non exhaustive).
+- `fallback-position` (`MazPopoverFallbackPosition`, default: `auto`): Fallback position of the popover relative to trigger when prefer position is not visible - Fallback position of the popover relative to trigger. Values: `'auto'`, `'top'`, `'bottom'`, `'left'`, `'right'`, `'top-start'`, `'top-end'`, `'bottom-start'`, `'bottom-end'`, `'left-start'`, `'left-end'`, `'right-start'`, `'right-end'` (non exhaustive).
+- `announce-changes` (`boolean`, default: `false`): Announce content changes to screen readers.
+- `hover-delay` (`number`, default: `150`): Delay before closing on hover in milliseconds.
+- `teleport-to` (`string`, default: `'body'`): Teleport target selector.
+- `overlay-class` (`ClassValue`): Additional CSS classes for the overlay wrapper.
+- `panel-class` (`ClassValue`): Additional CSS classes for the popover panel.
+- `panel-style` (`StyleValue`): Inline styles for the popover panel.
+- `close-on-click-outside` (`boolean`, default: `true`): Close popover when clicking outside.
+- `trap-focus` (`boolean`, default: `true`): Trap focus inside the popover.
+- `keep-open-on-hover` (`boolean`, default: `false`): Keep popover open when hovering over the panel.
+- `position-reference` (`string | HTMLElement`): CSS selector or element reference to use for positioning calculations - When provided, the popover will position relative to this element instead of the trigger Useful for components with labels where you want to position relative to the actual input.
+
+### Events
+
+- `@update:model-value` (payload: `value: boolean`): Emitted when the dropdown open state changes
+- `@update:modelValue` (payload: `value: boolean`)
+- `@menuitem-clicked` (payload: `event: Event`): Emitted when a menu item is clicked
+
+### Slots
+
+- `#screen-reader-description`: description for screen readers (hidden from visual display)
+- `#trigger`: trigger element for the dropdown Bindings: `isOpen: boolean` (Current state of the dropdown (true when open, false when closed)), `toggle: () => void` (Function to toggle the dropdown), `close: () => void` (Function to close the dropdown), `open: () => void` (Function to open the dropdown).
+- `#default`: Text content of the trigger element
+- `#dropdown-icon`: Dropdown indicator icon Bindings: `isOpen: boolean` (Current state of the dropdown (true when open, false when closed)), `toggle: () => void`, `close: () => void`, `open: () => void`.
+- `#dropdown`: Dropdown menu panel content Bindings: `items: MazDropdownMenuItem[]` (Array of menu items passed via the items prop), `open: () => void` (Function to open the dropdown), `close: () => void` (Function to close the dropdown), `isOpen: boolean` (Current state of the dropdown (true when open, false when closed)), `toggle: () => void` (Function to toggle the dropdown).
+- `#prepend-menu`: Prepend to the list of menu items Bindings: `isOpen: boolean` (Current state of the dropdown (true when open, false when closed)), `open: () => void` (Function to open the dropdown), `close: () => void` (Function to close the dropdown), `toggle: () => void` (Function to toggle the dropdown).
+- `#menuitem`: Menu item component Bindings: `item: MazDropdownMenuItem` (Individual menu item object with properties like label, href, onClick, etc.), `open: () => void` (Function to open the dropdown), `close: () => void` (Function to close the dropdown), `isOpen: boolean` (Current state of the dropdown (true when open, false when closed)), `toggle: () => void` (Function to toggle the dropdown).
+- `#menuitem-label`: Label content for menu item Bindings: `item: MazDropdownMenuItem` (Individual menu item object containing label and other properties), `open: () => void` (Function to open the dropdown), `close: () => void` (Function to close the dropdown), `isOpen: boolean` (Current state of the dropdown (true when open, false when closed)), `toggle: () => void` (Function to toggle the dropdown).
+- `#append-menu`: Append to the list of menu items Bindings: `isOpen: boolean` (Current state of the dropdown (true when open, false when closed)), `open: () => void` (Function to open the dropdown), `close: () => void` (Function to close the dropdown), `toggle: () => void` (Function to toggle the dropdown).