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

package/docs/src/components/maz-popover.md

@@ -1,1416 +0,0 @@
----
-title: MazPopover
-description: MazPopover is a versatile Vue component for displaying content in overlays that bypass overflow constraints of parent elements
----
-
-# {{ $frontmatter.title }}
-
-{{ $frontmatter.description }}
-
-## Basic usage
-
-<ComponentDemo>
-  <div class="maz:flex maz:gap-4 maz:flex-wrap">
-    <MazPopover trigger="click">
-      <template #trigger>
-        <MazBtn>
-          Click me
-        </MazBtn>
-      </template>
-      <div class="maz:p-4">
-        <h3 class="maz:text-lg maz:font-semibold maz:mb-2">Popover Content</h3>
-        <p class="maz:text-sm">This is the content inside the popover.</p>
-      </div>
-    </MazPopover>
-    <MazPopover trigger="hover">
-      <template #trigger>
-        <MazBtn color="secondary">
-          Hover me
-        </MazBtn>
-      </template>
-      <div class="maz:p-4">
-        <p class="maz:text-sm">This popover appears on hover!</p>
-      </div>
-    </MazPopover>
-    <MazPopover trigger="manual">
-      <template #trigger="{ toggle }">
-        <MazBtn color="accent" @click="toggle">
-          Manual trigger
-        </MazBtn>
-      </template>
-      <div class="maz:p-4">
-        <p class="maz:text-sm">This popover appears manually!</p>
-      </div>
-    </MazPopover>
-  </div>
-
-<template #code>
-
-```vue
-<template>
-  <MazPopover>
-    <template #trigger>
-      <MazBtn>
-        Click me
-      </MazBtn>
-    </template>
-    <div class="maz:p-4">
-      <h3 class="maz:mb-2 maz:text-lg maz:font-semibold">
-        Popover Content
-      </h3>
-      <p class="maz:text-sm">
-        This is the content inside the popover.
-      </p>
-    </div>
-  </MazPopover>
-
-  <MazPopover trigger="hover">
-    <template #trigger>
-      <MazBtn color="secondary">
-        Hover me
-      </MazBtn>
-    </template>
-    <div class="maz:p-4">
-      <p class="maz:text-sm">
-        This popover appears on hover!
-      </p>
-    </div>
-  </MazPopover>
-</template>
-```
-
-  </template>
-</ComponentDemo>
-
-## 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.
-
-<ComponentDemo>
-  <div class="maz:flex maz:gap-4 maz:flex-wrap">
-    <MazPopover trigger="adaptive">
-      <template #trigger>
-        <MazBtn color="primary">
-          Adaptive Trigger
-        </MazBtn>
-      </template>
-      <div class="maz:p-4">
-        <h3 class="maz:text-lg maz:font-semibold maz:mb-2">Smart Behavior</h3>
-        <p class="maz:text-sm maz:mb-2">
-          On desktop: Hover to open, move away to close
-        </p>
-        <p class="maz:text-sm">
-          On mobile: Tap to open, tap outside to close
-        </p>
-      </div>
-    </MazPopover>
-    <MazPopover trigger="adaptive" keep-open-on-hover>
-      <template #trigger>
-        <MazBtn color="secondary">
-          Adaptive + Keep Open
-        </MazBtn>
-      </template>
-      <div class="maz:p-4">
-        <p class="maz:text-sm maz:mb-2">
-          This combines adaptive behavior with keep-open-on-hover for menus.
-        </p>
-        <button class="maz:block maz:w-full maz:px-3 maz:py-2 maz:text-start maz:text-sm maz:hover:bg-surface-600 maz:dark:hover:bg-surface-400 maz:rounded-md">
-          Menu Item 1
-        </button>
-        <button class="maz:block maz:w-full maz:px-3 maz:py-2 maz:text-start maz:text-sm maz:hover:bg-surface-600 maz:dark:hover:bg-surface-400 maz:rounded-md">
-          Menu Item 2
-        </button>
-      </div>
-    </MazPopover>
-  </div>
-
-<template #code>
-
-```vue
-<template>
-  <!-- Basic adaptive trigger -->
-  <MazPopover trigger="adaptive">
-    <template #trigger>
-      <MazBtn color="primary">
-        Adaptive Trigger
-      </MazBtn>
-    </template>
-    <div class="maz:p-4">
-      <h3 class="maz:text-lg maz:font-semibold maz:mb-2">Smart Behavior</h3>
-      <p class="maz:text-sm maz:mb-2">
-        On desktop: Hover to open, move away to close
-      </p>
-      <p class="maz:text-sm">
-        On mobile: Tap to open, tap outside to close
-      </p>
-    </div>
-  </MazPopover>
-
-  <!-- Adaptive with keep-open-on-hover for menus -->
-  <MazPopover trigger="adaptive" keep-open-on-hover>
-    <template #trigger>
-      <MazBtn color="secondary">
-        Adaptive Menu
-      </MazBtn>
-    </template>
-    <div class="maz:p-4">
-      <p class="maz:text-sm maz:mb-2">
-        Perfect for dropdown menus that work on all devices
-      </p>
-      <button class="maz:block maz:w-full maz:px-3 maz:py-2 maz:text-start maz:text-sm maz:hover:bg-surface-600 maz:dark:hover:bg-surface-400 maz:rounded-md">
-        Menu Item 1
-      </button>
-      <button class="maz:block maz:w-full maz:px-3 maz:py-2 maz:text-start maz:text-sm maz:hover:bg-surface-600 maz:dark:hover:bg-surface-400 maz:rounded-md">
-        Menu Item 2
-      </button>
-    </div>
-  </MazPopover>
-</template>
-```
-
-  </template>
-</ComponentDemo>
-
-## Positions
-
-::: tip
-
-The position prop is used to position the popover relative to the trigger. The chosen position will force the popover to be displayed in the chosen position.
-
-:::
-
-<ComponentDemo>
-  <div class="maz:grid maz:grid-cols-2 maz:gap-4 maz:md:grid-cols-4">
-    <MazPopover trigger="hover" position="top">
-      <template #trigger>
-        <MazBtn block>
-          Top
-        </MazBtn>
-      </template>
-      <div class="maz:p-3">
-        <p class="maz:text-sm">Top positioned popover</p>
-      </div>
-    </MazPopover>
-    <MazPopover trigger="hover" position="bottom">
-      <template #trigger>
-        <MazBtn block>
-          Bottom
-        </MazBtn>
-      </template>
-      <div class="maz:p-3">
-        <p class="maz:text-sm">Bottom positioned popover</p>
-      </div>
-    </MazPopover>
-    <MazPopover trigger="hover" position="left">
-      <template #trigger>
-        <MazBtn block>
-          Left
-        </MazBtn>
-      </template>
-      <div class="maz:p-3">
-        <p class="maz:text-sm">Left positioned popover</p>
-      </div>
-    </MazPopover>
-    <MazPopover trigger="hover" position="right">
-      <template #trigger>
-        <MazBtn block>
-          Right
-        </MazBtn>
-      </template>
-      <div class="maz:p-3">
-        <p class="maz:text-sm">Right positioned popover</p>
-      </div>
-    </MazPopover>
-  </div>
-
-<template #code>
-
-```vue
-<template>
-  <MazPopover trigger="hover" position="top">
-    <template #trigger>
-      <MazBtn>Top</MazBtn>
-    </template>
-    <div class="maz:p-3">
-      <p class="maz:text-sm">
-        Top positioned popover
-      </p>
-    </div>
-  </MazPopover>
-
-  <MazPopover trigger="hover" position="bottom">
-    <template #trigger>
-      <MazBtn>Bottom</MazBtn>
-    </template>
-    <div class="maz:p-3">
-      <p class="maz:text-sm">
-        Bottom positioned popover
-      </p>
-    </div>
-  </MazPopover>
-
-  <MazPopover trigger="hover" position="left">
-    <template #trigger>
-      <MazBtn>Left</MazBtn>
-    </template>
-    <div class="maz:p-3">
-      <p class="maz:text-sm">
-        Left positioned popover
-      </p>
-    </div>
-  </MazPopover>
-
-  <MazPopover trigger="hover" position="right">
-    <template #trigger>
-      <MazBtn>Right</MazBtn>
-    </template>
-    <div class="maz:p-3">
-      <p class="maz:text-sm">
-        Right positioned popover
-      </p>
-    </div>
-  </MazPopover>
-</template>
-```
-
-  </template>
-</ComponentDemo>
-
-## Advanced positions
-
-<ComponentDemo>
-  <div class="maz:grid maz:grid-cols-2 maz:gap-4 maz:md:grid-cols-3">
-    <MazPopover position="top-start">
-      <template #trigger>
-        <MazBtn block size="sm">
-          Top Start
-        </MazBtn>
-      </template>
-      <div class="maz:p-3">
-        <p class="maz:text-sm">Top start aligned</p>
-      </div>
-    </MazPopover>
-    <MazPopover position="top-end">
-      <template #trigger>
-        <MazBtn block size="sm">
-          Top End
-        </MazBtn>
-      </template>
-      <div class="maz:p-3">
-        <p class="maz:text-sm">Top end aligned</p>
-      </div>
-    </MazPopover>
-    <MazPopover position="bottom-start">
-      <template #trigger>
-        <MazBtn block size="sm">
-          Bottom Start
-        </MazBtn>
-      </template>
-      <div class="maz:p-3">
-        <p class="maz:text-sm">Bottom start aligned</p>
-      </div>
-    </MazPopover>
-    <MazPopover position="bottom-end">
-      <template #trigger>
-        <MazBtn block size="sm">
-          Bottom End
-        </MazBtn>
-      </template>
-      <div class="maz:p-3">
-        <p class="maz:text-sm">Bottom end aligned</p>
-      </div>
-    </MazPopover>
-    <MazPopover position="left-start">
-      <template #trigger>
-        <MazBtn block size="sm">
-          Left Start
-        </MazBtn>
-      </template>
-      <div class="maz:p-3">
-        <p class="maz:text-sm">Left start aligned</p>
-      </div>
-    </MazPopover>
-    <MazPopover position="left-end">
-      <template #trigger>
-        <MazBtn block size="sm">
-          Left End
-        </MazBtn>
-      </template>
-      <div class="maz:p-3">
-        <p class="maz:text-sm">Left end aligned</p>
-      </div>
-    </MazPopover>
-    <MazPopover position="right-start">
-      <template #trigger>
-        <MazBtn block size="sm">
-          Right Start
-        </MazBtn>
-      </template>
-      <div class="maz:p-3">
-        <p class="maz:text-sm">Right start aligned</p>
-      </div>
-    </MazPopover>
-    <MazPopover position="right-end">
-      <template #trigger>
-        <MazBtn block size="sm">
-          Right End
-        </MazBtn>
-      </template>
-      <div class="maz:p-3">
-        <p class="maz:text-sm">Right end aligned</p>
-      </div>
-    </MazPopover>
-    <MazPopover position="auto">
-      <template #trigger>
-        <MazBtn block size="sm" color="accent">
-          Auto Position
-        </MazBtn>
-      </template>
-      <div class="maz:p-3">
-        <p class="maz:text-sm">Automatically positioned based on available space</p>
-      </div>
-    </MazPopover>
-  </div>
-
-<template #code>
-
-```vue
-<template>
-  <MazPopover position="top-start">
-    <template #trigger>
-      <MazBtn block size="sm">
-        Top Start
-      </MazBtn>
-    </template>
-    <div class="maz:p-3">
-      <p class="maz:text-sm">Top start aligned</p>
-    </div>
-  </MazPopover>
-  <MazPopover position="top-end">
-    <template #trigger>
-      <MazBtn block size="sm">
-        Top End
-      </MazBtn>
-    </template>
-    <div class="maz:p-3">
-      <p class="maz:text-sm">Top end aligned</p>
-    </div>
-  </MazPopover>
-  <MazPopover position="bottom-start">
-    <template #trigger>
-      <MazBtn block size="sm">
-        Bottom Start
-      </MazBtn>
-    </template>
-    <div class="maz:p-3">
-      <p class="maz:text-sm">Bottom start aligned</p>
-    </div>
-  </MazPopover>
-  <MazPopover position="bottom-end">
-    <template #trigger>
-      <MazBtn block size="sm">
-        Bottom End
-      </MazBtn>
-    </template>
-    <div class="maz:p-3">
-      <p class="maz:text-sm">Bottom end aligned</p>
-    </div>
-  </MazPopover>
-
-  <MazPopover position="left-start">
-    <template #trigger>
-      <MazBtn block size="sm">
-        Left Start
-      </MazBtn>
-    </template>
-    <div class="maz:p-3">
-      <p class="maz:text-sm">Left start aligned</p>
-    </div>
-  </MazPopover>
-  <MazPopover position="left-end">
-    <template #trigger>
-      <MazBtn block size="sm">
-        Left End
-      </MazBtn>
-    </template>
-    <div class="maz:p-3">
-      <p class="maz:text-sm">Left end aligned</p>
-    </div>
-  </MazPopover>
-
-  <MazPopover position="right-start">
-    <template #trigger>
-      <MazBtn block size="sm">
-        Right Start
-      </MazBtn>
-    </template>
-    <div class="maz:p-3">
-      <p class="maz:text-sm">Right start aligned</p>
-    </div>
-  </MazPopover>
-  <MazPopover position="right-end">
-    <template #trigger>
-      <MazBtn block size="sm">
-        Right End
-      </MazBtn>
-    </template>
-    <div class="maz:p-3">
-      <p class="maz:text-sm">Right end aligned</p>
-    </div>
-  </MazPopover>
-
-  <MazPopover position="auto">
-    <template #trigger>
-      <MazBtn color="accent">
-        Auto Position
-      </MazBtn>
-    </template>
-    <div class="maz:p-3">
-      <p class="maz:text-sm">
-        Automatically positioned based on available space
-      </p>
-    </div>
-  </MazPopover>
-</template>
-```
-
-  </template>
-</ComponentDemo>
-
-## Prefer position and fallback position
-
-::: tip
-
-The prefer-position and fallback-position props are used to position the popover relative to the trigger. The prefer-position is the position that will be used if it's available, and the fallback-position is the position that will be used if the prefer-position is not available.
-
-When you not specify a fallback position, the popover will fallback on the best position available.
-
-:::
-
-<ComponentDemo>
-  <div class="maz:flex maz:gap-4">
-    <MazPopover prefer-position="top-start" fallback-position="bottom-start">
-      <template #trigger>
-        <MazBtn>
-          Prefer position and fallback position
-        </MazBtn>
-      </template>
-      <div class="maz:p-4">
-        <p class="maz:text-sm">This popover will prefer the top position, but if it's not available, it will fallback to the bottom position.</p>
-      </div>
-    </MazPopover>
-  </div>
-
-<template #code>
-
-```html
-<MazPopover prefer-position="top-start" fallback-position="bottom-start">
-  <template #trigger>
-    <MazBtn>
-      Prefer position and fallback position
-    </MazBtn>
-  </template>
-  <div class="maz:p-4">
-    <p class="maz:text-sm">This popover will prefer the top position, but if it's not available, it will fallback to the bottom position.</p>
-  </div>
-</MazPopover>
-```
-
-</template>
-</ComponentDemo>
-
-
-## Colors
-
-<ComponentDemo>
-  <div class="maz:flex maz:gap-4 maz:flex-wrap">
-    <MazPopover color="surface" trigger="hover">
-      <template #trigger>
-        <MazBtn color="contrast">Background</MazBtn>
-      </template>
-      <div class="maz:p-4">
-        <p class="maz:text-sm">This popover has a default color!</p>
-      </div>
-    </MazPopover>
-    <MazPopover color="primary" trigger="hover">
-      <template #trigger>
-        <MazBtn color="primary">Primary</MazBtn>
-      </template>
-      <div class="maz:p-4">
-        <p class="maz:text-sm">This popover has a primary color!</p>
-      </div>
-    </MazPopover>
-    <MazPopover color="secondary" trigger="hover">
-      <template #trigger>
-        <MazBtn color="secondary">Secondary</MazBtn>
-      </template>
-      <div class="maz:p-4">
-        <p class="maz:text-sm">This popover has a secondary color!</p>
-      </div>
-    </MazPopover>
-    <MazPopover color="accent" trigger="hover">
-      <template #trigger>
-        <MazBtn color="accent">Accent</MazBtn>
-      </template>
-      <div class="maz:p-4">
-        <p class="maz:text-sm">This popover has a accent color!</p>
-      </div>
-    </MazPopover>
-    <MazPopover color="contrast" trigger="hover">
-      <template #trigger>
-        <MazBtn color="contrast">Contrast</MazBtn>
-      </template>
-      <div class="maz:p-4">
-        <p class="maz:text-sm">This popover has a contrast color!</p>
-      </div>
-    </MazPopover>
-    <MazPopover color="success" trigger="hover">
-      <template #trigger>
-        <MazBtn color="success">Success</MazBtn>
-      </template>
-      <div class="maz:p-4">
-        <p class="maz:text-sm">This popover has a success color!</p>
-      </div>
-    </MazPopover>
-    <MazPopover color="info" trigger="hover">
-      <template #trigger>
-        <MazBtn color="info">Info</MazBtn>
-      </template>
-      <div class="maz:p-4">
-        <p class="maz:text-sm">This popover has a info color!</p>
-      </div>
-    </MazPopover>
-    <MazPopover color="destructive" trigger="hover">
-      <template #trigger>
-        <MazBtn color="destructive">Destructive</MazBtn>
-      </template>
-      <div class="maz:p-4">
-        <p class="maz:text-sm">This popover has a destructive color!</p>
-      </div>
-    </MazPopover>
-    <MazPopover color="warning" trigger="hover">
-      <template #trigger>
-        <MazBtn color="warning">Warning</MazBtn>
-      </template>
-      <div class="maz:p-4">
-        <p class="maz:text-sm">This popover has a warning color!</p>
-      </div>
-    </MazPopover>
-  </div>
-
-<template #code>
-
-```vue
-<template>
-  <MazPopover color="surface" trigger="hover">
-    <template #trigger>
-      <MazBtn color="contrast">Background</MazBtn>
-    </template>
-    <div class="maz:p-4">
-      <p class="maz:text-sm">This popover has a default color!</p>
-    </div>
-  </MazPopover>
-  <MazPopover color="primary" trigger="hover">
-    <template #trigger>
-      <MazBtn color="primary">Primary</MazBtn>
-    </template>
-    <div class="maz:p-4">
-      <p class="maz:text-sm">This popover has a primary color!</p>
-    </div>
-  </MazPopover>
-  <MazPopover color="secondary" trigger="hover">
-    <template #trigger>
-      <MazBtn color="secondary">Secondary</MazBtn>
-    </template>
-    <div class="maz:p-4">
-      <p class="maz:text-sm">This popover has a secondary color!</p>
-    </div>
-  </MazPopover>
-  <MazPopover color="accent" trigger="hover">
-    <template #trigger>
-      <MazBtn color="accent">Accent</MazBtn>
-    </template>
-    <div class="maz:p-4">
-      <p class="maz:text-sm">This popover has a accent color!</p>
-    </div>
-  </MazPopover>
-  <MazPopover color="contrast" trigger="hover">
-    <template #trigger>
-      <MazBtn color="contrast">Contrast</MazBtn>
-    </template>
-    <div class="maz:p-4">
-      <p class="maz:text-sm">This popover has a contrast color!</p>
-    </div>
-  </MazPopover>
-  <MazPopover color="success" trigger="hover">
-    <template #trigger>
-      <MazBtn color="success">Success</MazBtn>
-    </template>
-    <div class="maz:p-4">
-      <p class="maz:text-sm">This popover has a success color!</p>
-    </div>
-  </MazPopover>
-  <MazPopover color="info" trigger="hover">
-    <template #trigger>
-      <MazBtn color="info">Info</MazBtn>
-    </template>
-    <div class="maz:p-4">
-      <p class="maz:text-sm">This popover has a info color!</p>
-    </div>
-  </MazPopover>
-  <MazPopover color="destructive" trigger="hover">
-    <template #trigger>
-      <MazBtn color="destructive">Destructive</MazBtn>
-    </template>
-    <div class="maz:p-4">
-      <p class="maz:text-sm">This popover has a destructive color!</p>
-    </div>
-  </MazPopover>
-  <MazPopover color="warning" trigger="hover">
-    <template #trigger>
-      <MazBtn color="warning">Warning</MazBtn>
-    </template>
-    <div class="maz:p-4">
-      <p class="maz:text-sm">This popover has a warning color!</p>
-    </div>
-  </MazPopover>
-</template>
-```
-
-</template>
-
-</ComponentDemo>
-
-## Tooltip role
-
-A directive is available to more easily add a tooltip to an element, see [vTooltip](./../directives/tooltip.md) for more information.
-
-<ComponentDemo>
-  <div class="maz:flex maz:gap-4 maz:flex-wrap maz:items-center">
-    <MazPopover role="tooltip" trigger="hover" position="top">
-      <template #trigger>
-        <MazBtn color="info">
-          Hover for tooltip
-        </MazBtn>
-      </template>
-      <div class="maz:p-2">
-        <p class="maz:text-xs">This is a tooltip with proper ARIA attributes</p>
-      </div>
-    </MazPopover>
-    <MazPopover
-      role="tooltip"
-      trigger="hover"
-      position="bottom"
-      panel-class="maz:bg-gray-800! maz:text-white! maz:border-gray-700!"
-    >
-      <template #trigger>
-        <span class="maz:underline maz:cursor-help">
-          Hover this text
-        </span>
-      </template>
-      <div class="maz:p-2">
-        <p class="maz:text-xs">Custom styled tooltip</p>
-      </div>
-    </MazPopover>
-    <MazPopover
-      role="tooltip"
-      trigger="hover"
-      :delay="1000"
-      position="right"
-    >
-      <template #trigger>
-        <MazInformationCircle class="maz:cursor-help maz:text-info maz:text-xl" />
-      </template>
-      <div class="maz:p-2 maz:max-w-48">
-        <p class="maz:text-xs">This tooltip has a 1000ms delay before showing</p>
-      </div>
-    </MazPopover>
-  </div>
-
-<template #code>
-
-```vue
-<template>
-  <MazPopover role="tooltip" trigger="hover" position="top">
-    <template #trigger>
-      <MazBtn color="info">
-        Hover for tooltip
-      </MazBtn>
-    </template>
-    <div class="maz:p-2">
-      <p class="maz:text-xs">This is a tooltip with proper ARIA attributes</p>
-    </div>
-  </MazPopover>
-  <MazPopover
-    role="tooltip"
-    trigger="hover"
-    position="bottom"
-    panel-class="maz:bg-gray-800! maz:text-white! maz:border-gray-700!"
-  >
-    <template #trigger>
-      <span class="maz:underline maz:cursor-help">
-        Hover this text
-      </span>
-    </template>
-    <div class="maz:p-2">
-      <p class="maz:text-xs">Custom styled tooltip</p>
-    </div>
-  </MazPopover>
-  <MazPopover
-    role="tooltip"
-    trigger="hover"
-    :delay="1000"
-    position="right"
-  >
-    <template #trigger>
-      <MazInformationCircle class="maz:cursor-help maz:text-info maz:text-xl" />
-    </template>
-    <div class="maz:p-2 maz:max-w-48">
-      <p class="maz:text-xs">This tooltip has a 1000ms delay before showing</p>
-    </div>
-  </MazPopover>
-</template>
-```
-
-  </template>
-</ComponentDemo>
-
-## Controlled popover
-
-<ComponentDemo>
-  <div class="maz:flex maz:gap-4 maz:flex-wrap maz:items-center">
-    <MazPopover v-model="isOpen" trigger="manual">
-      <template #trigger="{ toggle }">
-        <MazBtn @click="toggle">
-          Controlled Trigger
-        </MazBtn>
-      </template>
-      <div class="maz:p-4">
-        <h4 class="maz:font-semibold maz:mb-2">Controlled Popover</h4>
-        <p class="maz:text-sm maz:mb-3">This popover is controlled externally.</p>
-        <MazBtn @click="isOpen = false" size="sm" color="destructive">
-          Close
-        </MazBtn>
-      </div>
-    </MazPopover>
-    <MazBtn @click="isOpen = !isOpen" color="secondary">
-      {{ isOpen ? 'Close' : 'Open' }} Popover
-    </MazBtn>
-    <span class="maz:text-sm maz:text-muted">
-      Popover is {{ isOpen ? 'open' : 'closed' }}
-    </span>
-  </div>
-
-<template #code>
-
-```vue
-<script setup>
-import { ref } from 'vue'
-
-const isOpen = ref(false)
-</script>
-
-<template>
-  <MazPopover v-model="isOpen" trigger="manual">
-    <template #trigger="{ toggle }">
-      <MazBtn @click="toggle">
-        Controlled Trigger
-      </MazBtn>
-    </template>
-    <div class="maz:p-4">
-      <h4 class="maz:font-semibold maz:mb-2">Controlled Popover</h4>
-      <p class="maz:text-sm maz:mb-3">This popover is controlled externally.</p>
-      <MazBtn @click="isOpen = false" size="sm" color="destructive">
-        Close
-      </MazBtn>
-    </div>
-  </MazPopover>
-  <MazBtn @click="isOpen = !isOpen" color="secondary">
-    {{ isOpen ? 'Close' : 'Open' }} Popover
-  </MazBtn>
-  <span class="maz:text-sm maz:text-muted">
-    Popover is {{ isOpen ? 'open' : 'closed' }}
-  </span>
-
-  <MazBtn color="secondary" @click="isOpen = !isOpen">
-    {{ isOpen ? 'Close' : 'Open' }} Popover
-  </MazBtn>
-</template>
-```
-
-  </template>
-</ComponentDemo>
-
-## Menu example
-
-<ComponentDemo>
-  <div class="maz:flex maz:gap-4">
-    <MazPopover position="bottom-start">
-      <template #trigger>
-        <MazBtn>
-          <MazIcon icon="/cog-6-tooth.svg" class="maz:me-2" />
-          Settings
-          <MazIcon icon="/chevron-down.svg" class="maz:ms-2" />
-        </MazBtn>
-      </template>
-      <div class="maz:py-1 maz:min-w-48">
-        <button
-          v-for="item in menuItems"
-          :key="item.label"
-          class="maz:w-full maz:px-4 maz:py-2 maz:text-start maz:text-sm maz:hover:bg-surface-600 maz:dark:hover:bg-surface-400 maz:flex maz:items-center maz:gap-2"
-          @click="handleMenuClick(item.action)"
-        >
-          <MazIcon :icon="item.icon" class="maz:w-4 maz:h-4" />
-          {{ item.label }}
-        </button>
-      </div>
-    </MazPopover>
-    <MazPopover position="bottom-end">
-      <template #trigger>
-        <MazBtn color="transparent" fab :icon="MazEllipsisVertical" />
-      </template>
-      <div class="maz:py-1 maz:min-w-32">
-        <button class="maz:w-full maz:px-3 maz:py-2 maz:text-start maz:text-sm maz:hover:bg-surface-600 maz:dark:hover:bg-surface-400">
-          Edit
-        </button>
-        <button class="maz:w-full maz:px-3 maz:py-2 maz:text-start maz:text-sm maz:hover:bg-surface-600 maz:dark:hover:bg-surface-400">
-          Share
-        </button>
-        <hr class="maz:my-1 maz:border-divider">
-        <button class="maz:w-full maz:px-3 maz:py-2 maz:text-start maz:text-sm maz:hover:bg-surface-600 maz:dark:hover:bg-surface-400 maz:text-destructive">
-          Delete
-        </button>
-      </div>
-    </MazPopover>
-  </div>
-
-<template #code>
-
-```vue
-<script setup>
-const menuItems = [
-  { label: 'Profile', icon: 'user', action: 'profile' },
-  { label: 'Settings', icon: 'cog-6-tooth', action: 'settings' },
-  { label: 'Sign out', icon: 'arrow-right-on-rectangle', action: 'signout' }
-]
-
-function handleMenuClick(action) {
-  console.log('Menu action:', action)
-}
-</script>
-
-<template>
-  <MazPopover position="bottom-start">
-    <template #trigger>
-      <MazBtn>
-        <MazIcon icon="/cog-6-tooth.svg" class="maz:me-2" />
-        Settings
-        <MazIcon icon="/chevron-down.svg" class="maz:ms-2" />
-      </MazBtn>
-    </template>
-    <div class="maz:py-1 maz:min-w-48">
-      <button
-        v-for="item in menuItems"
-        :key="item.label"
-        class="maz:w-full maz:px-4 maz:py-2 maz:text-start maz:text-sm maz:hover:bg-surface-600 maz:dark:hover:bg-surface-400 maz:flex maz:items-center maz:gap-2"
-        @click="handleMenuClick(item.action)"
-      >
-        <MazIcon :icon="item.icon" class="maz:w-4 maz:h-4" />
-        {{ item.label }}
-      </button>
-    </div>
-  </MazPopover>
-
-  <MazPopover position="bottom-end">
-    <template #trigger>
-      <MazBtn color="transparent" size="sm">
-        <MazIcon icon="/ellipsis-vertical.svg" />
-      </MazBtn>
-    </template>
-    <div class="maz:py-1 maz:min-w-32">
-      <button class="maz:w-full maz:px-3 maz:py-2 maz:text-start maz:text-sm maz:hover:bg-surface-600 maz:dark:hover:bg-surface-400">
-        Edit
-      </button>
-      <button class="maz:w-full maz:px-3 maz:py-2 maz:text-start maz:text-sm maz:hover:bg-surface-600 maz:dark:hover:bg-surface-400">
-        Share
-      </button>
-      <hr class="maz:my-1 maz:border-divider">
-      <button class="maz:w-full maz:px-3 maz:py-2 maz:text-start maz:text-sm maz:hover:bg-surface-600 maz:dark:hover:bg-surface-400 maz:text-destructive">
-        Delete
-      </button>
-    </div>
-  </MazPopover>
-</template>
-```
-
-  </template>
-</ComponentDemo>
-
-## Keep open on hover
-
-> With this option, the popover will stay open when you hover over it (a timeout is used to close the popover after a certain time).
-
-<ComponentDemo>
-  <MazPopover position="bottom-end" keep-open-on-hover trigger="hover">
-    <template #trigger>
-      <MazBtn color="secondary">
-        Keep open on hover
-      </MazBtn>
-    </template>
-    <div class="maz:py-1 maz:min-w-32">
-      <button class="maz:w-full maz:px-3 maz:py-2 maz:text-start maz:text-sm maz:hover:bg-surface-600 maz:dark:hover:bg-surface-400">
-        Edit
-      </button>
-      <button class="maz:w-full maz:px-3 maz:py-2 maz:text-start maz:text-sm maz:hover:bg-surface-600 maz:dark:hover:bg-surface-400">
-        Share
-      </button>
-      <hr class="maz:my-1 maz:border-divider">
-      <button class="maz:w-full maz:px-3 maz:py-2 maz:text-start maz:text-sm maz:hover:bg-surface-600 maz:dark:hover:bg-surface-400 maz:text-destructive">
-        Delete
-      </button>
-    </div>
-  </MazPopover>
-
-<template #code>
-
-```vue
-<template>
-  <MazPopover position="bottom-end" keep-open-on-hover trigger="hover">
-    <template #trigger>
-      <MazBtn color="secondary">
-        Keep open on hover
-      </MazBtn>
-    </template>
-    <div class="maz:py-1 maz:min-w-32">
-      <button class="maz:w-full maz:px-3 maz:py-2 maz:text-start maz:text-sm maz:hover:bg-surface-600 maz:dark:hover:bg-surface-400">
-        Edit
-      </button>
-      <button class="maz:w-full maz:px-3 maz:py-2 maz:text-start maz:text-sm maz:hover:bg-surface-600 maz:dark:hover:bg-surface-400">
-        Share
-      </button>
-      <hr class="maz:my-1 maz:border-divider">
-      <button class="maz:w-full maz:px-3 maz:py-2 maz:text-start maz:text-sm maz:hover:bg-surface-600 maz:dark:hover:bg-surface-400 maz:text-destructive">
-        Delete
-      </button>
-    </div>
-  </MazPopover>
-</template>
-```
-
-</template>
-</ComponentDemo>
-
-## Form example
-
-<ComponentDemo>
-  <div class="maz:max-w-md">
-    <MazPopover position="bottom-start" :close-on-click-outside="false" :close-on-escape="false">
-      <template #trigger>
-        <MazBtn block>
-          <MazIcon icon="/plus.svg" class="maz:me-2" />
-          Add Item
-        </MazBtn>
-      </template>
-      <div class="maz:p-4 maz:w-80">
-        <h3 class="maz:text-lg maz:font-semibold maz:mb-4">Add New Item</h3>
-        <form @submit.prevent="handleSubmit" class="maz:space-y-4">
-          <MazInput
-            v-model="formData.name"
-            label="Name"
-            required
-          />
-          <MazTextarea
-            v-model="formData.description"
-            label="Description"
-            rows="3"
-          />
-          <div class="maz:flex maz:gap-2">
-            <MazBtn type="submit" color="success" size="sm">
-              Save
-            </MazBtn>
-            <MazBtn type="button" color="transparent" size="sm" @click="resetForm">
-              Reset
-            </MazBtn>
-          </div>
-        </form>
-      </div>
-    </MazPopover>
-  </div>
-
-<template #code>
-
-```vue
-<script setup>
-import { reactive } from 'vue'
-
-const formData = reactive({
-  name: '',
-  description: ''
-})
-
-function handleSubmit() {
-  console.log('Form submitted:', formData)
-  resetForm()
-}
-
-function resetForm() {
-  formData.name = ''
-  formData.description = ''
-}
-</script>
-
-<template>
-  <MazPopover position="bottom-start" :close-on-click-outside="false">
-    <template #trigger>
-      <MazBtn block>
-        <MazIcon icon="/plus.svg" class="maz:me-2" />
-        Add Item
-      </MazBtn>
-    </template>
-    <div class="maz:w-80 maz:p-4">
-      <h3 class="maz:mb-4 maz:text-lg maz:font-semibold">
-        Add New Item
-      </h3>
-      <form class="maz:space-y-4" @submit.prevent="handleSubmit">
-        <MazInput
-          v-model="formData.name"
-          label="Name"
-          placeholder="Enter item name"
-          required
-        />
-        <MazTextarea
-          v-model="formData.description"
-          label="Description"
-          placeholder="Enter description"
-          rows="3"
-        />
-        <div class="maz:flex maz:gap-2">
-          <MazBtn type="submit" color="success" size="sm">
-            Save
-          </MazBtn>
-          <MazBtn type="button" color="transparent" size="sm" @click="resetForm">
-            Reset
-          </MazBtn>
-        </div>
-      </form>
-    </div>
-  </MazPopover>
-</template>
-```
-
-  </template>
-</ComponentDemo>
-
-## Configuration options
-
-<ComponentDemo>
-  <div class="maz:grid maz:grid-cols-1 maz:md:grid-cols-2 maz:gap-4">
-    <div>
-      <h4 class="maz:font-semibold maz:mb-3">Persistent (no auto-close)</h4>
-      <MazPopover persistent>
-        <template #trigger>
-          <MazBtn color="warning">
-            Persistent Popover
-          </MazBtn>
-        </template>
-        <template #default="{ close }">
-          <div class="maz:p-4">
-            <p class="maz:text-sm maz:mb-3">This popover won't close on click outside or ESC.</p>
-              <MazBtn @click="close" size="sm" color="destructive">
-                Close manually
-              </MazBtn>
-          </div>
-        </template>
-      </MazPopover>
-    </div>
-    <div>
-      <h4 class="maz:font-semibold maz:mb-3">Custom offset</h4>
-      <MazPopover :offset="20" position="top">
-        <template #trigger>
-          <MazBtn color="accent">
-            Large Offset
-          </MazBtn>
-        </template>
-        <div class="maz:p-3">
-          <p class="maz:text-sm">20px offset from trigger</p>
-        </div>
-      </MazPopover>
-    </div>
-    <div>
-      <h4 class="maz:font-semibold maz:mb-3">Custom styling</h4>
-      <MazPopover
-        panel-class="maz:bg-linear-to-r maz:from-purple-500 maz:to-pink-500 maz:text-white maz:border-none"
-        position="bottom"
-      >
-        <template #trigger>
-          <MazBtn color="contrast">
-            Styled Popover
-          </MazBtn>
-        </template>
-        <div class="maz:p-4">
-          <p class="maz:text-sm maz:font-semibold">Beautiful gradient background!</p>
-        </div>
-      </MazPopover>
-    </div>
-    <div>
-      <h4 class="maz:font-semibold maz:mb-3">Disabled state</h4>
-      <MazPopover disabled>
-        <template #trigger>
-          <MazBtn disabled>
-            Disabled Popover
-          </MazBtn>
-        </template>
-        <div class="maz:p-3">
-          <p class="maz:text-sm">This won't show</p>
-        </div>
-      </MazPopover>
-    </div>
-  </div>
-
-<template #code>
-
-```vue
-<template>
-  <!-- Persistent popover -->
-  <MazPopover persistent>
-    <template #trigger>
-      <MazBtn color="warning">
-        Persistent Popover
-      </MazBtn>
-    </template>
-    <div class="maz:p-4">
-      <p class="maz:mb-3 maz:text-sm">
-        This popover won't close on click outside or ESC.
-      </p>
-      <MazBtn size="sm" color="destructive" @click="close">
-        Close manually
-      </MazBtn>
-    </div>
-  </MazPopover>
-
-  <!-- Custom offset -->
-  <MazPopover :offset="20" position="top">
-    <template #trigger>
-      <MazBtn color="accent">
-        Large Offset
-      </MazBtn>
-    </template>
-    <div class="maz:p-3">
-      <p class="maz:text-sm">
-        20px offset from trigger
-      </p>
-    </div>
-  </MazPopover>
-
-  <!-- Custom styling -->
-  <MazPopover
-    panel-class="maz:bg-linear-to-r maz:from-purple-500 maz:to-pink-500 maz:text-white maz:border-none"
-    position="bottom"
-  >
-    <template #trigger>
-      <MazBtn color="contrast">
-        Styled Popover
-      </MazBtn>
-    </template>
-    <div class="maz:p-4">
-      <p class="maz:text-sm maz:font-semibold">
-        Beautiful gradient background!
-      </p>
-    </div>
-  </MazPopover>
-
-  <!-- Disabled -->
-  <MazPopover disabled>
-    <template #trigger>
-      <MazBtn disabled>
-        Disabled Popover
-      </MazBtn>
-    </template>
-    <div class="maz:p-3">
-      <p class="maz:text-sm">
-        This won't show
-      </p>
-    </div>
-  </MazPopover>
-</template>
-```
-
-  </template>
-</ComponentDemo>
-
-## Events
-
-<ComponentDemo>
-  <div class="maz:flex maz:flex-col maz:gap-4">
-    <MazPopover
-      @open="onOpen"
-      @close="onClose"
-      @toggle="onToggle"
-    >
-      <template #trigger>
-        <MazBtn>
-          Event Example
-        </MazBtn>
-      </template>
-      <div class="maz:p-4">
-        <p class="maz:text-sm">Check the console for events!</p>
-      </div>
-    </MazPopover>
-    <div class="maz:p-4 maz:border maz:dark:bg-surface-400 maz:rounded-md maz:text-sm">
-      <h4 class="maz:font-semibold maz:mb-2">Event Log:</h4>
-      <div v-if="events.length === 0" class="maz:text-muted">
-        No events yet. Try opening the popover above.
-      </div>
-      <div v-for="(event, index) in events" :key="index" class="maz:mb-1">
-        <span class="maz:font-mono maz:text-primary">{{ event.type }}</span>
-        <span class="maz:text-muted maz:ms-2">{{ event.time }}</span>
-      </div>
-    </div>
-  </div>
-
-<template #code>
-
-```vue
-<script setup>
-import { ref } from 'vue'
-
-const events = ref([])
-
-function onOpen() {
-  console.log('Popover opened')
-  events.value.push({
-    type: 'open',
-    time: new Date().toLocaleTimeString()
-  })
-}
-
-function onClose() {
-  console.log('Popover closed')
-  events.value.push({
-    type: 'close',
-    time: new Date().toLocaleTimeString()
-  })
-}
-
-function onToggle(isOpen) {
-  console.log('Popover toggled:', isOpen)
-  events.value.push({
-    type: `toggle (${isOpen ? 'open' : 'close'})`,
-    time: new Date().toLocaleTimeString()
-  })
-}
-</script>
-
-<template>
-  <MazPopover
-    @open="onOpen"
-    @close="onClose"
-    @toggle="onToggle"
-  >
-    <template #trigger>
-      <MazBtn>
-        Event Example
-      </MazBtn>
-    </template>
-    <div class="maz:p-4">
-      <p class="maz:text-sm">
-        Check the console for events!
-      </p>
-    </div>
-  </MazPopover>
-</template>
-```
-
-  </template>
-</ComponentDemo>
-
-## Position values
-
-- `auto` - Automatically choose best position
-- `top`, `bottom`, `left`, `right` - Basic positions
-- `top-start`, `top-end` - Top with start/end alignment
-- `bottom-start`, `bottom-end` - Bottom with start/end alignment
-- `left-start`, `left-end` - Left with start/end alignment
-- `right-start`, `right-end` - Right with start/end alignment
-
-## Accessibility
-
-MazPopover follows WAI-ARIA guidelines:
-
-- **Focus management**: Automatically manages focus when opening/closing
-- **Keyboard navigation**: Supports Escape key and Tab navigation
-- **ARIA attributes**: Proper `role`, `aria-modal`, `aria-labelledby`, etc.
-- **Screen reader support**: Appropriate roles for different use cases
-- **Trigger ARIA on the real control**: `aria-expanded`, `aria-haspopup` and `aria-controls` are set on the interactive element of the `trigger` slot (your button, link...), never on a wrapper around it. ARIA attributes you set yourself on that element are kept, and a `combobox` keeps managing its own state. When the slot has no interactive element, the wrapper becomes a focusable `button` (<kbd>Enter</kbd> / <kbd>Space</kbd> toggle the popover).
-
-### Best practices
-
-- Use `role="tooltip"` for simple informational overlays
-- Use `role="dialog"` for interactive content
-- Provide meaningful `aria-labelledby` or `aria-describedby` attributes
-- Ensure trigger elements are focusable and have proper labels
-
-<script setup>
-import { ref, reactive } from 'vue'
-import MazPopover from 'maz-ui/components/MazPopover'
-import { MazInformationCircle } from '@maz-ui/icons/static/MazInformationCircle'
-import { MazEllipsisVertical } from '@maz-ui/icons/raw/MazEllipsisVertical'
-
-const isOpen = ref(false)
-const events = ref([])
-
-const formData = reactive({
-  name: '',
-  description: ''
-})
-
-const menuItems = [
-  { label: 'Profile', icon: 'user', action: 'profile' },
-  { label: 'Settings', icon: 'cog-6-tooth', action: 'settings' },
-  { label: 'Sign out', icon: 'arrow-right-on-rectangle', action: 'signout' }
-]
-
-function handleMenuClick(action) {
-  console.log('Menu action:', action)
-}
-
-function handleSubmit() {
-  console.log('Form submitted:', formData)
-  resetForm()
-}
-
-function resetForm() {
-  formData.name = ''
-  formData.description = ''
-}
-
-function onOpen() {
-  console.log('Popover opened')
-  events.value.push({
-    type: 'open',
-    time: new Date().toLocaleTimeString()
-  })
-}
-
-function onClose() {
-  console.log('Popover closed')
-  events.value.push({
-    type: 'close',
-    time: new Date().toLocaleTimeString()
-  })
-}
-
-function onToggle(isOpenValue) {
-  console.log('Popover toggled:', isOpenValue)
-  events.value.push({
-    type: `toggle (${isOpenValue ? 'open' : 'close'})`,
-    time: new Date().toLocaleTimeString()
-  })
-}
-</script>
-
-<!--@include: ./../../.vitepress/generated-docs/maz-popover.doc.md-->