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

package/docs/components/maz-popover.md

@@ -0,0 +1,794 @@
+---
+title: "MazPopover"
+description: "MazPopover is a versatile Vue component for displaying content in overlays that bypass overflow constraints of parent elements"
+package: "maz-ui"
+url: "https://maz-ui.com/components/maz-popover"
+---
+
+# MazPopover
+
+> MazPopover is a versatile Vue component for displaying content in overlays that bypass overflow constraints of parent elements
+
+- Package: `maz-ui`
+- Import: `import MazPopover from 'maz-ui/components/MazPopover'`
+- Nuxt: auto-imported by `@maz-ui/nuxt`, no import needed in a Nuxt app
+- Web: https://maz-ui.com/components/maz-popover
+
+## Basic usage
+
+```vue
+<template>
+  <MazPopover>
+    <template #trigger>
+      <MazBtn>
+        Click me
+      </MazBtn>
+    </template>
+    <div class="p-4">
+      <h3 class="mb-2 text-lg font-semibold">
+        Popover Content
+      </h3>
+      <p class="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="p-4">
+      <p class="text-sm">
+        This popover appears on hover!
+      </p>
+    </div>
+  </MazPopover>
+</template>
+```
+
+## 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.
+
+```vue
+<template>
+  <!-- Basic adaptive trigger -->
+  <MazPopover trigger="adaptive">
+    <template #trigger>
+      <MazBtn color="primary">
+        Adaptive Trigger
+      </MazBtn>
+    </template>
+    <div class="p-4">
+      <h3 class="text-lg font-semibold mb-2">Smart Behavior</h3>
+      <p class="text-sm mb-2">
+        On desktop: Hover to open, move away to close
+      </p>
+      <p class="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="p-4">
+      <p class="text-sm mb-2">
+        Perfect for dropdown menus that work on all devices
+      </p>
+      <button class="block w-full px-3 py-2 text-start text-sm hover:bg-surface-600 dark:hover:bg-surface-400 rounded-md">
+        Menu Item 1
+      </button>
+      <button class="block w-full px-3 py-2 text-start text-sm hover:bg-surface-600 dark:hover:bg-surface-400 rounded-md">
+        Menu Item 2
+      </button>
+    </div>
+  </MazPopover>
+</template>
+```
+
+## 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.
+
+```vue
+<template>
+  <MazPopover trigger="hover" position="top">
+    <template #trigger>
+      <MazBtn>Top</MazBtn>
+    </template>
+    <div class="p-3">
+      <p class="text-sm">
+        Top positioned popover
+      </p>
+    </div>
+  </MazPopover>
+
+  <MazPopover trigger="hover" position="bottom">
+    <template #trigger>
+      <MazBtn>Bottom</MazBtn>
+    </template>
+    <div class="p-3">
+      <p class="text-sm">
+        Bottom positioned popover
+      </p>
+    </div>
+  </MazPopover>
+
+  <MazPopover trigger="hover" position="left">
+    <template #trigger>
+      <MazBtn>Left</MazBtn>
+    </template>
+    <div class="p-3">
+      <p class="text-sm">
+        Left positioned popover
+      </p>
+    </div>
+  </MazPopover>
+
+  <MazPopover trigger="hover" position="right">
+    <template #trigger>
+      <MazBtn>Right</MazBtn>
+    </template>
+    <div class="p-3">
+      <p class="text-sm">
+        Right positioned popover
+      </p>
+    </div>
+  </MazPopover>
+</template>
+```
+
+## Advanced positions
+
+```vue
+<template>
+  <MazPopover position="top-start">
+    <template #trigger>
+      <MazBtn block size="sm">
+        Top Start
+      </MazBtn>
+    </template>
+    <div class="p-3">
+      <p class="text-sm">Top start aligned</p>
+    </div>
+  </MazPopover>
+  <MazPopover position="top-end">
+    <template #trigger>
+      <MazBtn block size="sm">
+        Top End
+      </MazBtn>
+    </template>
+    <div class="p-3">
+      <p class="text-sm">Top end aligned</p>
+    </div>
+  </MazPopover>
+  <MazPopover position="bottom-start">
+    <template #trigger>
+      <MazBtn block size="sm">
+        Bottom Start
+      </MazBtn>
+    </template>
+    <div class="p-3">
+      <p class="text-sm">Bottom start aligned</p>
+    </div>
+  </MazPopover>
+  <MazPopover position="bottom-end">
+    <template #trigger>
+      <MazBtn block size="sm">
+        Bottom End
+      </MazBtn>
+    </template>
+    <div class="p-3">
+      <p class="text-sm">Bottom end aligned</p>
+    </div>
+  </MazPopover>
+
+  <MazPopover position="left-start">
+    <template #trigger>
+      <MazBtn block size="sm">
+        Left Start
+      </MazBtn>
+    </template>
+    <div class="p-3">
+      <p class="text-sm">Left start aligned</p>
+    </div>
+  </MazPopover>
+  <MazPopover position="left-end">
+    <template #trigger>
+      <MazBtn block size="sm">
+        Left End
+      </MazBtn>
+    </template>
+    <div class="p-3">
+      <p class="text-sm">Left end aligned</p>
+    </div>
+  </MazPopover>
+
+  <MazPopover position="right-start">
+    <template #trigger>
+      <MazBtn block size="sm">
+        Right Start
+      </MazBtn>
+    </template>
+    <div class="p-3">
+      <p class="text-sm">Right start aligned</p>
+    </div>
+  </MazPopover>
+  <MazPopover position="right-end">
+    <template #trigger>
+      <MazBtn block size="sm">
+        Right End
+      </MazBtn>
+    </template>
+    <div class="p-3">
+      <p class="text-sm">Right end aligned</p>
+    </div>
+  </MazPopover>
+
+  <MazPopover position="auto">
+    <template #trigger>
+      <MazBtn color="accent">
+        Auto Position
+      </MazBtn>
+    </template>
+    <div class="p-3">
+      <p class="text-sm">
+        Automatically positioned based on available space
+      </p>
+    </div>
+  </MazPopover>
+</template>
+```
+
+## 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.
+
+```html
+<MazPopover prefer-position="top-start" fallback-position="bottom-start">
+  <template #trigger>
+    <MazBtn>
+      Prefer position and fallback position
+    </MazBtn>
+  </template>
+  <div class="p-4">
+    <p class="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>
+```
+
+## Colors
+
+```vue
+<template>
+  <MazPopover color="surface" trigger="hover">
+    <template #trigger>
+      <MazBtn color="contrast">Background</MazBtn>
+    </template>
+    <div class="p-4">
+      <p class="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="p-4">
+      <p class="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="p-4">
+      <p class="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="p-4">
+      <p class="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="p-4">
+      <p class="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="p-4">
+      <p class="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="p-4">
+      <p class="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="p-4">
+      <p class="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="p-4">
+      <p class="text-sm">This popover has a warning color!</p>
+    </div>
+  </MazPopover>
+</template>
+```
+
+## Tooltip role
+
+A directive is available to more easily add a tooltip to an element, see [vTooltip](../directives/tooltip.md) for more information.
+
+```vue
+<template>
+  <MazPopover role="tooltip" trigger="hover" position="top">
+    <template #trigger>
+      <MazBtn color="info">
+        Hover for tooltip
+      </MazBtn>
+    </template>
+    <div class="p-2">
+      <p class="text-xs">This is a tooltip with proper ARIA attributes</p>
+    </div>
+  </MazPopover>
+  <MazPopover
+    role="tooltip"
+    trigger="hover"
+    position="bottom"
+    panel-class="bg-gray-800! text-white! border-gray-700!"
+  >
+    <template #trigger>
+      <span class="underline cursor-help">
+        Hover this text
+      </span>
+    </template>
+    <div class="p-2">
+      <p class="text-xs">Custom styled tooltip</p>
+    </div>
+  </MazPopover>
+  <MazPopover
+    role="tooltip"
+    trigger="hover"
+    :delay="1000"
+    position="right"
+  >
+    <template #trigger>
+      <MazInformationCircle class="cursor-help text-info text-xl" />
+    </template>
+    <div class="p-2 max-w-48">
+      <p class="text-xs">This tooltip has a 1000ms delay before showing</p>
+    </div>
+  </MazPopover>
+</template>
+```
+
+## Controlled popover
+
+```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="p-4">
+      <h4 class="font-semibold mb-2">Controlled Popover</h4>
+      <p class="text-sm 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="text-sm text-muted">
+    Popover is {{ isOpen ? 'open' : 'closed' }}
+  </span>
+
+  <MazBtn color="secondary" @click="isOpen = !isOpen">
+    {{ isOpen ? 'Close' : 'Open' }} Popover
+  </MazBtn>
+</template>
+```
+
+## Menu example
+
+```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="me-2" />
+        Settings
+        <MazIcon icon="/chevron-down.svg" class="ms-2" />
+      </MazBtn>
+    </template>
+    <div class="py-1 min-w-48">
+      <button
+        v-for="item in menuItems"
+        :key="item.label"
+        class="w-full px-4 py-2 text-start text-sm hover:bg-surface-600 dark:hover:bg-surface-400 flex items-center gap-2"
+        @click="handleMenuClick(item.action)"
+      >
+        <MazIcon :icon="item.icon" class="w-4 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="py-1 min-w-32">
+      <button class="w-full px-3 py-2 text-start text-sm hover:bg-surface-600 dark:hover:bg-surface-400">
+        Edit
+      </button>
+      <button class="w-full px-3 py-2 text-start text-sm hover:bg-surface-600 dark:hover:bg-surface-400">
+        Share
+      </button>
+      <hr class="my-1 border-divider">
+      <button class="w-full px-3 py-2 text-start text-sm hover:bg-surface-600 dark:hover:bg-surface-400 text-destructive">
+        Delete
+      </button>
+    </div>
+  </MazPopover>
+</template>
+```
+
+## 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).
+
+```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="py-1 min-w-32">
+      <button class="w-full px-3 py-2 text-start text-sm hover:bg-surface-600 dark:hover:bg-surface-400">
+        Edit
+      </button>
+      <button class="w-full px-3 py-2 text-start text-sm hover:bg-surface-600 dark:hover:bg-surface-400">
+        Share
+      </button>
+      <hr class="my-1 border-divider">
+      <button class="w-full px-3 py-2 text-start text-sm hover:bg-surface-600 dark:hover:bg-surface-400 text-destructive">
+        Delete
+      </button>
+    </div>
+  </MazPopover>
+</template>
+```
+
+## Form example
+
+```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="me-2" />
+        Add Item
+      </MazBtn>
+    </template>
+    <div class="w-80 p-4">
+      <h3 class="mb-4 text-lg font-semibold">
+        Add New Item
+      </h3>
+      <form class="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="flex 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>
+```
+
+## Configuration options
+
+```vue
+<template>
+  <!-- Persistent popover -->
+  <MazPopover persistent>
+    <template #trigger>
+      <MazBtn color="warning">
+        Persistent Popover
+      </MazBtn>
+    </template>
+    <div class="p-4">
+      <p class="mb-3 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="p-3">
+      <p class="text-sm">
+        20px offset from trigger
+      </p>
+    </div>
+  </MazPopover>
+
+  <!-- Custom styling -->
+  <MazPopover
+    panel-class="bg-linear-to-r from-purple-500 to-pink-500 text-white border-none"
+    position="bottom"
+  >
+    <template #trigger>
+      <MazBtn color="contrast">
+        Styled Popover
+      </MazBtn>
+    </template>
+    <div class="p-4">
+      <p class="text-sm font-semibold">
+        Beautiful gradient background!
+      </p>
+    </div>
+  </MazPopover>
+
+  <!-- Disabled -->
+  <MazPopover disabled>
+    <template #trigger>
+      <MazBtn disabled>
+        Disabled Popover
+      </MazBtn>
+    </template>
+    <div class="p-3">
+      <p class="text-sm">
+        This won't show
+      </p>
+    </div>
+  </MazPopover>
+</template>
+```
+
+## Events
+
+```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="p-4">
+      <p class="text-sm">
+        Check the console for events!
+      </p>
+    </div>
+  </MazPopover>
+</template>
+```
+
+## 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` (Enter / Space 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
+
+## MazPopover API
+
+`import MazPopover from 'maz-ui/components/MazPopover'`
+
+### Props
+
+- `model-value` (`boolean`, default: `false`, `v-model`): Controls the popover open state.
+- `position` (`MazPopoverPosition`, default: `"auto"`): Position of the popover relative to trigger - 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).
+- `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).
+- `trigger` (`MazPopoverTrigger`, default: `"click"`): How the popover is triggered - How the popover is triggered. 'adaptive' uses hover on desktop and click on mobile. Values: `'click'`, `'hover'`, `'manual'`, `'adaptive'` (non exhaustive).
+- `role` (`MazPopoverRole`, default: `"dialog"`): ARIA role for accessibility - ARIA role for accessibility. Values: `'dialog'`, `'tooltip'` (non exhaustive).
+- `aria-label` (`string`): ARIA label for the popover.
+- `announce-changes` (`boolean`, default: `false`): Announce content changes to screen readers.
+- `disabled` (`boolean`, default: `false`): Disables the popover - Disables the popover.
+- `offset` (`number`, default: `8`): Distance between trigger and popover in pixels.
+- `delay` (`number`, default: `0`): Delay before showing/hiding in milliseconds.
+- `hover-delay` (`number`, default: `150`): Delay before closing on hover in milliseconds.
+- `transition` (`string`, default: `"scale-pop"`): CSS transition name for animations - 'scale-pop' | 'scale-fade' for default transitions. 'scale-pop' is a pop effect, 'scale-fade' is a fade effect. Values: `'scale-pop'`, `'scale-fade'`, `'string'` (non exhaustive).
+- `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.
+- `close-on-escape` (`boolean`, default: `true`): Close popover when pressing Escape key.
+- `persistent` (`boolean`, default: `false`): Prevent auto-close (ignores click outside and escape key).
+- `id` (`string`): Custom ID for the popover element.
+- `aria-labelledby` (`string`): ARIA labelledby attribute for accessibility.
+- `aria-describedby` (`string`): ARIA describedby attribute for accessibility.
+- `color` (`"primary" | "secondary" | "accent" | "info" | "success" | "warning" | "destructive" | "contrast" | "transparent" | "surface"`, default: `"surface"`): Color variant of the popover.
+- `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.
+- `block` (`boolean`, default: `false`): The popover will be full width of the trigger.
+- `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 popover state changes
+- `@open`: Emitted when popover opens
+- `@close`: Emitted when popover closes
+- `@toggle` (payload: `value: boolean`): Emitted when popover toggles
+- `@update:modelValue` (payload: `value: boolean`)
+- `@after-close-animation`: Emitted after the close animation
+
+### Slots
+
+- `#trigger`: Trigger element content Bindings: `open: () => void` (Function to open the popover), `close: () => void` (Function to close the popover), `toggle: () => void` (Function to toggle the popover), `isOpen: boolean` (Current open state of the popover), `trigger: "click" | "hover" | "manual"` (The trigger type).
+- `#default`: Popover content Bindings: `open: () => void` (Function to open the popover), `close: () => void` (Function to close the popover), `toggle: () => void` (Function to toggle the popover), `isOpen: true` (Current open state of the popover).
+
+### Exposed (template ref)
+
+- `open`: Open the popover
+- `close`: Close the popover
+- `toggle`: Toggle the popover
+- `isOpen`: Check if the popover is open
+- `updatePosition`: Update the popover position
+- `panelRef`: Panel reference
+- `onTransitionAfterLeave`