@umbra.ui/core 0.1.0

package/src/components/models/Popover/README.md

@@ -0,0 +1,885 @@
+# Popover
+
+A flexible and feature-rich popover component built with Vue 3 Composition API and TypeScript. The Popover component provides a powerful interface for displaying contextual content with smart positioning, smooth animations, and comprehensive customization options.
+
+## Installation/Import
+
+```typescript
+import { Popover } from "@umbra-ui/core";
+import type { PopoverProps } from "@umbra-ui/core";
+```
+
+**Dependencies:**
+
+- Vue 3.x
+- @floating-ui/vue (for positioning)
+- gsap (for animations)
+
+## Basic Usage
+
+```vue
+<script setup lang="ts">
+import { ref } from "vue";
+import { Popover, Button } from "@umbra-ui/core";
+
+const isPopoverOpen = ref(false);
+
+const handleOpen = () => {
+  console.log("Popover opened");
+};
+
+const handleClose = () => {
+  console.log("Popover closed");
+};
+</script>
+
+<template>
+  <div>
+    <Popover
+      v-model="isPopoverOpen"
+      placement="bottom"
+      :show-arrow="true"
+      @open="handleOpen"
+      @close="handleClose"
+    >
+      <template #trigger>
+        <Button>Open Popover</Button>
+      </template>
+
+      <div class="popover-content">
+        <h3>Popover Title</h3>
+        <p>This is the popover content. It can contain any HTML elements.</p>
+        <Button @click="isPopoverOpen = false">Close</Button>
+      </div>
+    </Popover>
+  </div>
+</template>
+
+<style>
+.popover-content {
+  padding: 1rem;
+  min-width: 200px;
+}
+</style>
+```
+
+## Props
+
+| Prop Name               | Type                 | Required | Default    | Description                                   |
+| ----------------------- | -------------------- | -------- | ---------- | --------------------------------------------- |
+| `modelValue`            | `boolean`            | Yes      | -          | Controls the open/closed state of the popover |
+| `placement`             | `Placement`          | No       | `"bottom"` | Placement relative to trigger element         |
+| `offsetDistance`        | `number`             | No       | `8`        | Distance from trigger element in pixels       |
+| `dismissOnClickOutside` | `boolean`            | No       | `true`     | Whether clicking outside closes the popover   |
+| `showArrow`             | `boolean`            | No       | `true`     | Whether to show an arrow pointing to trigger  |
+| `showOverlay`           | `boolean`            | No       | `false`    | Whether to show a backdrop overlay            |
+| `overlayOpacity`        | `number`             | No       | `0.5`      | Overlay opacity (0-1)                         |
+| `animationDuration`     | `number`             | No       | `0.2`      | Animation duration in seconds                 |
+| `zIndex`                | `number`             | No       | `1000`     | Z-index for the popover                       |
+| `viewportPadding`       | `number`             | No       | `16`       | Padding from viewport edges                   |
+| `maxWidth`              | `string`             | No       | `"none"`   | Maximum width of the popover                  |
+| `maxHeight`             | `string`             | No       | `"none"`   | Maximum height of the popover                 |
+| `trigger`               | `"click" \| "hover"` | No       | `"click"`  | Trigger event type                            |
+| `hoverShowDelay`        | `number`             | No       | `0`        | Delay before showing on hover (ms)            |
+| `hoverHideDelay`        | `number`             | No       | `0`        | Delay before hiding on hover (ms)             |
+
+## Events
+
+| Event Name          | Payload Type | Description                                 |
+| ------------------- | ------------ | ------------------------------------------- |
+| `update:modelValue` | `boolean`    | Emitted when the popover open state changes |
+| `open`              | `void`       | Emitted when the popover opens              |
+| `close`             | `void`       | Emitted when the popover closes             |
+| `after-enter`       | `void`       | Emitted after the open animation completes  |
+| `after-leave`       | `void`       | Emitted after the close animation completes |
+
+## Slots
+
+| Slot Name | Description                              |
+| --------- | ---------------------------------------- |
+| `trigger` | The element that triggers the popover    |
+| `default` | The content displayed inside the popover |
+
+## Exposed Methods/Refs
+
+The Popover component exposes the following methods and properties via template refs:
+
+| Method/Property  | Type           | Description                            |
+| ---------------- | -------------- | -------------------------------------- |
+| `open`           | `() => void`   | Opens the popover programmatically     |
+| `close`          | `() => void`   | Closes the popover programmatically    |
+| `isVisible`      | `Ref<boolean>` | Reactive reference to visibility state |
+| `isAnimating`    | `Ref<boolean>` | Reactive reference to animation state  |
+| `updatePosition` | `() => void`   | Updates the popover position           |
+
+### Example Usage
+
+```vue
+<script setup lang="ts">
+import { ref } from "vue";
+import { Popover } from "@umbra-ui/core";
+
+const popoverRef = ref<InstanceType<typeof Popover> | null>(null);
+
+const openPopover = () => {
+  popoverRef.value?.open();
+};
+
+const closePopover = () => {
+  popoverRef.value?.close();
+};
+
+const updatePosition = () => {
+  popoverRef.value?.updatePosition();
+};
+</script>
+
+<template>
+  <Popover ref="popoverRef" :model-value="false">
+    <template #trigger>
+      <button @click="openPopover">Open</button>
+    </template>
+
+    <div class="content">
+      <p>Popover content</p>
+      <button @click="closePopover">Close</button>
+    </div>
+  </Popover>
+</template>
+```
+
+## Placement Options
+
+The `placement` prop accepts the following values from Floating UI:
+
+- `"top"` - Above the trigger
+- `"top-start"` - Above the trigger, aligned to start
+- `"top-end"` - Above the trigger, aligned to end
+- `"bottom"` - Below the trigger (default)
+- `"bottom-start"` - Below the trigger, aligned to start
+- `"bottom-end"` - Below the trigger, aligned to end
+- `"left"` - To the left of the trigger
+- `"left-start"` - To the left of the trigger, aligned to start
+- `"left-end"` - To the left of the trigger, aligned to end
+- `"right"` - To the right of the trigger
+- `"right-start"` - To the right of the trigger, aligned to start
+- `"right-end"` - To the right of the trigger, aligned to end
+
+## CSS Customization
+
+The Popover component uses CSS custom properties for theming and customization:
+
+### Light Theme Variables
+
+```css
+/* Popover colors */
+--popover-bg: #ffffff;
+--popover-border: 1px solid rgba(0, 0, 0, 0.1);
+--popover-shadow: none;
+--popover-inset-shadow: rgba(255, 255, 255, 0.8);
+
+/* Popover arrow colors */
+--popover-arrow-bg: #ffffff;
+--popover-arrow-shadow: rgba(0, 0, 0, 0.05);
+
+/* Popover overlay colors */
+--popover-overlay-bg: rgba(0, 0, 0, 0.5);
+```
+
+### Dark Theme Variables
+
+```css
+/* Popover colors */
+--popover-bg: #484848;
+--popover-border: none;
+--popover-shadow: rgba(0, 0, 0, 0.21);
+--popover-inset-shadow: rgba(255, 255, 255, 0.1);
+
+/* Popover arrow colors */
+--popover-arrow-bg: #484848;
+--popover-arrow-shadow: rgba(0, 0, 0, 0.05);
+
+/* Popover overlay colors */
+--popover-overlay-bg: rgba(0, 0, 0, 0.5);
+```
+
+## Key Features
+
+### Smart Positioning
+
+- **Floating UI Integration**: Uses Floating UI for intelligent positioning
+- **Auto-flip**: Automatically flips to opposite side if no space available
+- **Auto-shift**: Shifts position to stay within viewport bounds
+- **Viewport Padding**: Respects viewport boundaries with configurable padding
+
+### Animation System
+
+- **GSAP Animations**: Smooth, performant animations using GSAP
+- **Directional Animations**: Animations adapt to popover placement
+- **Customizable Duration**: Configurable animation timing
+- **Easing Functions**: Professional easing for natural motion
+
+### Trigger Options
+
+- **Click Trigger**: Standard click-to-toggle behavior
+- **Hover Trigger**: Hover to show with configurable delays
+- **Keyboard Support**: Escape key closes popover
+- **Click Outside**: Configurable click-outside-to-close
+
+### Visual Features
+
+- **Arrow Support**: Optional arrow pointing to trigger element
+- **Overlay Backdrop**: Optional semi-transparent overlay
+- **Custom Styling**: Full CSS customization support
+- **Z-index Management**: Configurable layering
+
+## Examples
+
+### Basic Popover
+
+```vue
+<script setup lang="ts">
+import { ref } from "vue";
+import { Popover, Button } from "@umbra-ui/core";
+
+const isOpen = ref(false);
+
+const handleOpen = () => {
+  console.log("Popover opened");
+};
+
+const handleClose = () => {
+  console.log("Popover closed");
+};
+</script>
+
+<template>
+  <div class="basic-popover">
+    <h3>Basic Popover</h3>
+
+    <Popover
+      v-model="isOpen"
+      placement="bottom"
+      :show-arrow="true"
+      @open="handleOpen"
+      @close="handleClose"
+    >
+      <template #trigger>
+        <Button>Click to Open</Button>
+      </template>
+
+      <div class="popover-content">
+        <h4>Popover Title</h4>
+        <p>This is a basic popover with default settings.</p>
+        <div class="actions">
+          <Button @click="isOpen = false" size="small">Close</Button>
+        </div>
+      </div>
+    </Popover>
+
+    <p class="status">Popover is {{ isOpen ? "open" : "closed" }}</p>
+  </div>
+</template>
+
+<style module>
+.basic-popover {
+  padding: 2rem;
+  border: 1px solid #e0e0e0;
+  border-radius: 0.5rem;
+  max-width: 400px;
+}
+
+.popover-content {
+  padding: 1rem;
+  min-width: 200px;
+}
+
+.popover-content h4 {
+  margin: 0 0 0.5rem 0;
+  color: #333;
+}
+
+.popover-content p {
+  margin: 0 0 1rem 0;
+  color: #666;
+  line-height: 1.5;
+}
+
+.actions {
+  display: flex;
+  gap: 0.5rem;
+  justify-content: flex-end;
+}
+
+.status {
+  margin-top: 1rem;
+  color: #666;
+  font-size: 0.875rem;
+}
+</style>
+```
+
+### Hover Popover
+
+```vue
+<script setup lang="ts">
+import { ref } from "vue";
+import { Popover, Button } from "@umbra-ui/core";
+
+const isHoverOpen = ref(false);
+</script>
+
+<template>
+  <div class="hover-popover">
+    <h3>Hover Popover</h3>
+    <p>Hover over the button to see the popover:</p>
+
+    <Popover
+      v-model="isHoverOpen"
+      trigger="hover"
+      placement="top"
+      :hover-show-delay="300"
+      :hover-hide-delay="200"
+      :show-arrow="true"
+    >
+      <template #trigger>
+        <Button>Hover Me</Button>
+      </template>
+
+      <div class="popover-content">
+        <h4>Hover Popover</h4>
+        <p>This popover appears on hover with a delay.</p>
+        <ul>
+          <li>300ms delay before showing</li>
+          <li>200ms delay before hiding</li>
+          <li>Stays open while hovering over content</li>
+        </ul>
+      </div>
+    </Popover>
+  </div>
+</template>
+
+<style module>
+.hover-popover {
+  padding: 2rem;
+  border: 1px solid #e0e0e0;
+  border-radius: 0.5rem;
+  max-width: 400px;
+}
+
+.popover-content {
+  padding: 1rem;
+  min-width: 250px;
+}
+
+.popover-content h4 {
+  margin: 0 0 0.5rem 0;
+  color: #333;
+}
+
+.popover-content p {
+  margin: 0 0 0.75rem 0;
+  color: #666;
+}
+
+.popover-content ul {
+  margin: 0;
+  padding-left: 1.25rem;
+  color: #666;
+}
+
+.popover-content li {
+  margin-bottom: 0.25rem;
+}
+</style>
+```
+
+### Popover with Overlay
+
+```vue
+<script setup lang="ts">
+import { ref } from "vue";
+import { Popover, Button } from "@umbra-ui/core";
+
+const isOverlayOpen = ref(false);
+</script>
+
+<template>
+  <div class="overlay-popover">
+    <h3>Popover with Overlay</h3>
+
+    <Popover
+      v-model="isOverlayOpen"
+      placement="center"
+      :show-overlay="true"
+      :overlay-opacity="0.7"
+      :dismiss-on-click-outside="true"
+      :show-arrow="false"
+    >
+      <template #trigger>
+        <Button>Open Modal Popover</Button>
+      </template>
+
+      <div class="modal-content">
+        <h4>Modal Popover</h4>
+        <p>This popover has a backdrop overlay and behaves like a modal.</p>
+        <p>Click outside or press Escape to close.</p>
+        <div class="actions">
+          <Button @click="isOverlayOpen = false" variant="secondary"
+            >Cancel</Button
+          >
+          <Button @click="isOverlayOpen = false">Confirm</Button>
+        </div>
+      </div>
+    </Popover>
+  </div>
+</template>
+
+<style module>
+.overlay-popover {
+  padding: 2rem;
+  border: 1px solid #e0e0e0;
+  border-radius: 0.5rem;
+  max-width: 400px;
+}
+
+.modal-content {
+  padding: 1.5rem;
+  min-width: 300px;
+  text-align: center;
+}
+
+.modal-content h4 {
+  margin: 0 0 1rem 0;
+  color: #333;
+}
+
+.modal-content p {
+  margin: 0 0 0.75rem 0;
+  color: #666;
+  line-height: 1.5;
+}
+
+.actions {
+  display: flex;
+  gap: 0.75rem;
+  justify-content: center;
+  margin-top: 1.5rem;
+}
+</style>
+```
+
+### Different Placements
+
+```vue
+<script setup lang="ts">
+import { ref } from "vue";
+import { Popover, Button } from "@umbra-ui/core";
+
+const placements = [
+  "top",
+  "top-start",
+  "top-end",
+  "bottom",
+  "bottom-start",
+  "bottom-end",
+  "left",
+  "left-start",
+  "left-end",
+  "right",
+  "right-start",
+  "right-end",
+];
+
+const openPopovers = ref<Record<string, boolean>>({});
+
+const togglePopover = (placement: string) => {
+  openPopovers.value[placement] = !openPopovers.value[placement];
+};
+</script>
+
+<template>
+  <div class="placement-demo">
+    <h3>Popover Placements</h3>
+    <p>Click the buttons to see different placement options:</p>
+
+    <div class="placement-grid">
+      <div
+        v-for="placement in placements"
+        :key="placement"
+        class="placement-item"
+      >
+        <Popover
+          v-model="openPopovers[placement]"
+          :placement="placement"
+          :show-arrow="true"
+        >
+          <template #trigger>
+            <Button @click="togglePopover(placement)" size="small">
+              {{ placement }}
+            </Button>
+          </template>
+
+          <div class="placement-content">
+            <h5>{{ placement }}</h5>
+            <p>This popover is positioned {{ placement }} of the trigger.</p>
+          </div>
+        </Popover>
+      </div>
+    </div>
+  </div>
+</template>
+
+<style module>
+.placement-demo {
+  padding: 2rem;
+  border: 1px solid #e0e0e0;
+  border-radius: 0.5rem;
+  max-width: 800px;
+}
+
+.placement-grid {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(150px, 1fr));
+  gap: 1rem;
+  margin-top: 1rem;
+}
+
+.placement-item {
+  display: flex;
+  justify-content: center;
+  align-items: center;
+  min-height: 60px;
+}
+
+.placement-content {
+  padding: 1rem;
+  min-width: 200px;
+  text-align: center;
+}
+
+.placement-content h5 {
+  margin: 0 0 0.5rem 0;
+  color: #333;
+  text-transform: capitalize;
+}
+
+.placement-content p {
+  margin: 0;
+  color: #666;
+  font-size: 0.875rem;
+}
+</style>
+```
+
+### Custom Styled Popover
+
+```vue
+<script setup lang="ts">
+import { ref } from "vue";
+import { Popover, Button } from "@umbra-ui/core";
+
+const isCustomOpen = ref(false);
+</script>
+
+<template>
+  <div class="custom-popover">
+    <h3>Custom Styled Popover</h3>
+
+    <Popover
+      v-model="isCustomOpen"
+      placement="bottom"
+      :show-arrow="true"
+      :animation-duration="0.3"
+      max-width="400px"
+    >
+      <template #trigger>
+        <Button class="custom-trigger">Custom Style</Button>
+      </template>
+
+      <div class="custom-content">
+        <div class="custom-header">
+          <h4>Custom Popover</h4>
+          <button @click="isCustomOpen = false" class="close-btn">×</button>
+        </div>
+        <div class="custom-body">
+          <p>This popover has custom styling with:</p>
+          <ul>
+            <li>Custom colors and gradients</li>
+            <li>Rounded corners and shadows</li>
+            <li>Custom header with close button</li>
+            <li>Longer animation duration</li>
+          </ul>
+        </div>
+        <div class="custom-footer">
+          <Button @click="isCustomOpen = false" size="small">Got it!</Button>
+        </div>
+      </div>
+    </Popover>
+  </div>
+</template>
+
+<style module>
+.custom-popover {
+  padding: 2rem;
+  border: 1px solid #e0e0e0;
+  border-radius: 0.5rem;
+  max-width: 400px;
+}
+
+.custom-trigger {
+  background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
+  color: white;
+  border: none;
+  padding: 0.75rem 1.5rem;
+  border-radius: 0.5rem;
+  font-weight: 600;
+  transition: transform 0.2s;
+}
+
+.custom-trigger:hover {
+  transform: translateY(-2px);
+  box-shadow: 0 4px 12px rgba(102, 126, 234, 0.4);
+}
+
+.custom-content {
+  background: linear-gradient(135deg, #f093fb 0%, #f5576c 100%);
+  color: white;
+  border-radius: 1rem;
+  overflow: hidden;
+  box-shadow: 0 10px 25px rgba(0, 0, 0, 0.2);
+}
+
+.custom-header {
+  display: flex;
+  justify-content: space-between;
+  align-items: center;
+  padding: 1rem 1.5rem;
+  background: rgba(255, 255, 255, 0.1);
+  backdrop-filter: blur(10px);
+}
+
+.custom-header h4 {
+  margin: 0;
+  font-size: 1.125rem;
+}
+
+.close-btn {
+  background: none;
+  border: none;
+  color: white;
+  font-size: 1.5rem;
+  cursor: pointer;
+  padding: 0;
+  width: 24px;
+  height: 24px;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  border-radius: 50%;
+  transition: background-color 0.2s;
+}
+
+.close-btn:hover {
+  background: rgba(255, 255, 255, 0.2);
+}
+
+.custom-body {
+  padding: 1.5rem;
+}
+
+.custom-body p {
+  margin: 0 0 1rem 0;
+  opacity: 0.9;
+}
+
+.custom-body ul {
+  margin: 0;
+  padding-left: 1.25rem;
+  opacity: 0.9;
+}
+
+.custom-body li {
+  margin-bottom: 0.5rem;
+}
+
+.custom-footer {
+  padding: 1rem 1.5rem;
+  background: rgba(255, 255, 255, 0.1);
+  backdrop-filter: blur(10px);
+  display: flex;
+  justify-content: flex-end;
+}
+
+/* Override popover CSS variables */
+:global(.custom-popover) {
+  --popover-bg: transparent;
+  --popover-border: none;
+  --popover-shadow: none;
+  --popover-inset-shadow: none;
+  --popover-arrow-bg: #f5576c;
+}
+</style>
+```
+
+### Form in Popover
+
+```vue
+<script setup lang="ts">
+import { ref } from "vue";
+import { Popover, Button } from "@umbra-ui/core";
+
+const isFormOpen = ref(false);
+const formData = ref({
+  name: "",
+  email: "",
+  message: "",
+});
+
+const handleSubmit = () => {
+  console.log("Form submitted:", formData.value);
+  isFormOpen.value = false;
+  // Reset form
+  formData.value = { name: "", email: "", message: "" };
+};
+
+const handleCancel = () => {
+  isFormOpen.value = false;
+  // Reset form
+  formData.value = { name: "", email: "", message: "" };
+};
+</script>
+
+<template>
+  <div class="form-popover">
+    <h3>Form in Popover</h3>
+
+    <Popover
+      v-model="isFormOpen"
+      placement="bottom-start"
+      :show-arrow="true"
+      :dismiss-on-click-outside="false"
+      max-width="400px"
+    >
+      <template #trigger>
+        <Button>Contact Us</Button>
+      </template>
+
+      <div class="form-content">
+        <h4>Send us a message</h4>
+        <form @submit.prevent="handleSubmit">
+          <div class="form-group">
+            <label for="name">Name</label>
+            <input
+              id="name"
+              v-model="formData.name"
+              type="text"
+              required
+              placeholder="Your name"
+            />
+          </div>
+
+          <div class="form-group">
+            <label for="email">Email</label>
+            <input
+              id="email"
+              v-model="formData.email"
+              type="email"
+              required
+              placeholder="your@email.com"
+            />
+          </div>
+
+          <div class="form-group">
+            <label for="message">Message</label>
+            <textarea
+              id="message"
+              v-model="formData.message"
+              required
+              placeholder="Your message..."
+              rows="3"
+            ></textarea>
+          </div>
+
+          <div class="form-actions">
+            <Button type="button" @click="handleCancel" variant="secondary">
+              Cancel
+            </Button>
+            <Button type="submit">Send Message</Button>
+          </div>
+        </form>
+      </div>
+    </Popover>
+  </div>
+</template>
+
+<style module>
+.form-popover {
+  padding: 2rem;
+  border: 1px solid #e0e0e0;
+  border-radius: 0.5rem;
+  max-width: 400px;
+}
+
+.form-content {
+  padding: 1.5rem;
+}
+
+.form-content h4 {
+  margin: 0 0 1.5rem 0;
+  color: #333;
+  text-align: center;
+}
+
+.form-group {
+  margin-bottom: 1rem;
+}
+
+.form-group label {
+  display: block;
+  margin-bottom: 0.5rem;
+  font-weight: 500;
+  color: #333;
+}
+
+.form-group input,
+.form-group textarea {
+  width: 100%;
+  padding: 0.75rem;
+  border: 1px solid #ddd;
+  border-radius: 0.25rem;
+  font-size: 1rem;
+  font-family: inherit;
+  box-sizing: border-box;
+}
+
+.form-group input:focus,
+.form-group textarea:focus {
+  outline: none;
+  border-color: #007bff;
+  box-shadow: 0 0 0 2px rgba(0, 123, 255, 0.25);
+}
+
+.form-actions {
+  display: flex;
+  gap: 0.75rem;
+  justify-content: flex-end;
+  margin-top: 1.5rem;
+}
+</style>
+```
+
+## Technical Notes
+
+- Popover provides a comprehensive floating content system with advanced positioning and animation
+- Floating UI integration ensures smart positioning that adapts to viewport constraints and available space
+- GSAP animations provide smooth, performant transitions with directional awareness
+- Teleport usage ensures proper z-index layering and positioning outside component tree
+- Auto-cleanup of positioning listeners and event handlers prevents memory leaks
+- Hover triggers with configurable delays provide flexible interaction patterns
+- Click-outside detection with configurable behavior for different use cases
+- Arrow positioning automatically adjusts based on popover placement and available space
+- TypeScript interfaces ensure type safety for all props and events
+- CSS custom properties enable easy theming and customization
+- Responsive design adapts to different screen sizes and orientations
+- Accessibility features include keyboard navigation and proper focus management