@umbra.ui/core 0.1.0

package/src/components/menus/ActionMenu/README.md

@@ -0,0 +1,825 @@
+# ActionMenu
+
+A versatile dropdown menu component built with Vue 3 Composition API and TypeScript. The ActionMenu component provides a flexible interface for displaying contextual actions with support for both click-triggered and right-click context menus, custom icons, destructive actions, and smart positioning.
+
+## Installation/Import
+
+```typescript
+import { ActionMenu } from "@umbra-ui/core";
+import type { ActionMenuItem } from "@umbra-ui/core";
+```
+
+**Dependencies:**
+
+- Vue 3.x
+- @umbra-ui/core (for icon components)
+- @floating-ui/vue (for positioning)
+
+## Basic Usage
+
+```vue
+<script setup lang="ts">
+import { ref } from "vue";
+import { ActionMenu, Button } from "@umbra-ui/core";
+import type { ActionMenuItem } from "@umbra-ui/core";
+
+const isMenuOpen = ref(false);
+
+const menuItems: ActionMenuItem[] = [
+  {
+    icon: "edit",
+    title: "Edit",
+    action: () => console.log("Edit clicked"),
+  },
+  {
+    icon: "copy",
+    title: "Copy",
+    action: () => console.log("Copy clicked"),
+  },
+  {
+    icon: "trash",
+    title: "Delete",
+    action: () => console.log("Delete clicked"),
+    isDestructive: true,
+  },
+];
+
+const handleItemClick = (item: ActionMenuItem) => {
+  console.log("Menu item clicked:", item.title);
+};
+</script>
+
+<template>
+  <div>
+    <ActionMenu
+      :items="menuItems"
+      v-model="isMenuOpen"
+      @item-click="handleItemClick"
+    >
+      <Button>Actions</Button>
+    </ActionMenu>
+  </div>
+</template>
+```
+
+## Props
+
+| Prop Name     | Type               | Required | Default | Description                                    |
+| ------------- | ------------------ | -------- | ------- | ---------------------------------------------- |
+| `items`       | `ActionMenuItem[]` | Yes      | -       | Array of menu items to display                 |
+| `modelValue`  | `boolean`          | No       | `false` | Controls the open/closed state of the menu     |
+| `contextMenu` | `boolean`          | No       | `false` | Enables right-click context menu functionality |
+
+## Events
+
+| Event Name          | Payload Type     | Description                              |
+| ------------------- | ---------------- | ---------------------------------------- |
+| `update:modelValue` | `boolean`        | Emitted when the menu open state changes |
+| `item-click`        | `ActionMenuItem` | Emitted when a menu item is clicked      |
+
+## Slots
+
+| Slot Name | Description                             |
+| --------- | --------------------------------------- |
+| `default` | The trigger element that opens the menu |
+
+## Exposed Methods/Refs
+
+The ActionMenu component exposes the following methods via template refs:
+
+| Method Name     | Parameters | Description                        |
+| --------------- | ---------- | ---------------------------------- |
+| `togglePopover` | `()`       | Toggles the menu open/closed state |
+
+### Example Usage
+
+```vue
+<script setup lang="ts">
+import { ref } from "vue";
+import { ActionMenu } from "@umbra-ui/core";
+
+const actionMenuRef = ref<InstanceType<typeof ActionMenu> | null>(null);
+
+const openMenu = () => {
+  actionMenuRef.value?.togglePopover();
+};
+</script>
+
+<template>
+  <ActionMenu ref="actionMenuRef" :items="menuItems">
+    <button @click="openMenu">Open Menu</button>
+  </ActionMenu>
+</template>
+```
+
+## ActionMenuItem Interface
+
+```typescript
+interface ActionMenuItem {
+  icon?: IconKey; // Optional icon from @umbra-ui/icons
+  title: string; // Display text for the menu item
+  action: () => void; // Function to execute when clicked
+  isDestructive?: boolean; // Whether this is a destructive action
+}
+```
+
+## CSS Customization
+
+The ActionMenu component uses CSS custom properties for theming and customization:
+
+### Light Theme Variables
+
+```css
+/* ActionMenu popup colors */
+--actionmenu-popup-bg: #ffffff;
+--actionmenu-popup-border: 1px solid rgba(0, 0, 0, 0.1);
+--actionmenu-popup-shadow: transparent;
+--actionmenu-popup-inset-shadow: rgba(255, 255, 255, 0.8);
+
+/* ActionMenu item colors */
+--actionmenu-item-bg: #ffffff;
+--actionmenu-item-hover-bg: rgba(0, 0, 0, 0.05);
+--actionmenu-item-border: rgba(0, 0, 0, 0.1);
+--actionmenu-item-text: #1f2937;
+--actionmenu-item-icon: #6b7280;
+
+/* ActionMenu destructive colors */
+--actionmenu-destructive-text: #dc2626;
+--actionmenu-destructive-icon: #dc2626;
+
+/* ActionMenu overlay colors */
+--actionmenu-overlay-bg: rgba(0, 0, 0, 0.1);
+--actionmenu-overlay-blur-bg: rgba(0, 0, 0, 0.1);
+```
+
+### Dark Theme Variables
+
+```css
+/* ActionMenu popup colors */
+--actionmenu-popup-bg: #484848;
+--actionmenu-popup-border: none;
+--actionmenu-popup-shadow: rgba(0, 0, 0, 0.21);
+--actionmenu-popup-inset-shadow: rgba(255, 255, 255, 0.1);
+
+/* ActionMenu item colors */
+--actionmenu-item-bg: #484848;
+--actionmenu-item-hover-bg: rgba(255, 255, 255, 0.05);
+--actionmenu-item-border: rgba(255, 255, 255, 0.1);
+--actionmenu-item-text: #eeeeee;
+--actionmenu-item-icon: #eeeeee;
+
+/* ActionMenu destructive colors */
+--actionmenu-destructive-text: #e5484d;
+--actionmenu-destructive-icon: #e5484d;
+
+/* ActionMenu overlay colors */
+--actionmenu-overlay-bg: rgba(0, 0, 0, 0.7);
+--actionmenu-overlay-blur-bg: rgba(0, 0, 0, 0.1);
+```
+
+## Key Features
+
+### Menu Types
+
+- **Click Menu**: Standard dropdown menu triggered by clicking the trigger element
+- **Context Menu**: Right-click context menu with smart positioning and blur overlay
+
+### 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
+- **Size Constraints**: Respects viewport boundaries with padding
+
+### Visual Features
+
+- **Smooth Animations**: Fade-in animations for menu and overlay
+- **Hover Effects**: Interactive hover states with icon scaling
+- **Destructive Actions**: Special styling for dangerous actions
+- **Icon Support**: Full integration with @umbra-ui/icons
+- **Backdrop Blur**: Context menus include backdrop blur effect
+
+### Accessibility
+
+- **Keyboard Navigation**: Full keyboard support
+- **Focus Management**: Proper focus handling
+- **Screen Reader Support**: Semantic markup and ARIA attributes
+- **Click Outside**: Closes menu when clicking outside
+
+## Examples
+
+### Basic Action Menu
+
+```vue
+<script setup lang="ts">
+import { ref } from "vue";
+import { ActionMenu, Button } from "@umbra-ui/core";
+import type { ActionMenuItem } from "@umbra-ui/core";
+
+const isMenuOpen = ref(false);
+
+const menuItems: ActionMenuItem[] = [
+  {
+    icon: "edit",
+    title: "Edit Item",
+    action: () => {
+      console.log("Editing item...");
+      isMenuOpen.value = false;
+    },
+  },
+  {
+    icon: "copy",
+    title: "Copy Link",
+    action: () => {
+      console.log("Copying link...");
+      isMenuOpen.value = false;
+    },
+  },
+  {
+    icon: "share",
+    title: "Share",
+    action: () => {
+      console.log("Sharing...");
+      isMenuOpen.value = false;
+    },
+  },
+];
+
+const handleItemClick = (item: ActionMenuItem) => {
+  console.log("Menu item clicked:", item.title);
+};
+</script>
+
+<template>
+  <div class="basic-menu">
+    <h3>Basic Action Menu</h3>
+
+    <ActionMenu
+      :items="menuItems"
+      v-model="isMenuOpen"
+      @item-click="handleItemClick"
+    >
+      <Button>Show Actions</Button>
+    </ActionMenu>
+
+    <p class="status">Menu is {{ isMenuOpen ? "open" : "closed" }}</p>
+  </div>
+</template>
+
+<style module>
+.basic-menu {
+  padding: 2rem;
+  border: 1px solid #e0e0e0;
+  border-radius: 0.5rem;
+  max-width: 400px;
+}
+
+.status {
+  margin-top: 1rem;
+  color: #666;
+  font-size: 0.875rem;
+}
+</style>
+```
+
+### Context Menu
+
+```vue
+<script setup lang="ts">
+import { ref } from "vue";
+import { ActionMenu } from "@umbra-ui/core";
+import type { ActionMenuItem } from "@umbra-ui/core";
+
+const isContextMenuOpen = ref(false);
+
+const contextMenuItems: ActionMenuItem[] = [
+  {
+    icon: "edit",
+    title: "Edit",
+    action: () => {
+      console.log("Edit from context menu");
+      isContextMenuOpen.value = false;
+    },
+  },
+  {
+    icon: "copy",
+    title: "Copy",
+    action: () => {
+      console.log("Copy from context menu");
+      isContextMenuOpen.value = false;
+    },
+  },
+  {
+    icon: "move",
+    title: "Move",
+    action: () => {
+      console.log("Move from context menu");
+      isContextMenuOpen.value = false;
+    },
+  },
+  {
+    icon: "trash",
+    title: "Delete",
+    action: () => {
+      console.log("Delete from context menu");
+      isContextMenuOpen.value = false;
+    },
+    isDestructive: true,
+  },
+];
+
+const handleContextItemClick = (item: ActionMenuItem) => {
+  console.log("Context menu item clicked:", item.title);
+};
+</script>
+
+<template>
+  <div class="context-menu-demo">
+    <h3>Context Menu Demo</h3>
+    <p>Right-click on the box below to see the context menu:</p>
+
+    <ActionMenu
+      :items="contextMenuItems"
+      v-model="isContextMenuOpen"
+      :context-menu="true"
+      @item-click="handleContextItemClick"
+    >
+      <div class="context-target">
+        <h4>Right-click me!</h4>
+        <p>This box has a context menu attached.</p>
+      </div>
+    </ActionMenu>
+  </div>
+</template>
+
+<style module>
+.context-menu-demo {
+  padding: 2rem;
+  border: 1px solid #e0e0e0;
+  border-radius: 0.5rem;
+  max-width: 500px;
+}
+
+.context-target {
+  padding: 2rem;
+  background-color: #f8f9fa;
+  border: 2px dashed #dee2e6;
+  border-radius: 0.5rem;
+  text-align: center;
+  cursor: context-menu;
+  transition: background-color 0.2s;
+}
+
+.context-target:hover {
+  background-color: #e9ecef;
+}
+
+.context-target h4 {
+  margin: 0 0 0.5rem 0;
+  color: #495057;
+}
+
+.context-target p {
+  margin: 0;
+  color: #6c757d;
+  font-size: 0.875rem;
+}
+</style>
+```
+
+### File Actions Menu
+
+```vue
+<script setup lang="ts">
+import { ref } from "vue";
+import { ActionMenu, Button } from "@umbra-ui/core";
+import type { ActionMenuItem } from "@umbra-ui/core";
+
+interface FileItem {
+  id: string;
+  name: string;
+  type: "file" | "folder";
+  size?: string;
+}
+
+const files = ref<FileItem[]>([
+  { id: "1", name: "document.pdf", type: "file", size: "2.3 MB" },
+  { id: "2", name: "images", type: "folder" },
+  { id: "3", name: "report.docx", type: "file", size: "1.1 MB" },
+  { id: "4", name: "data", type: "folder" },
+]);
+
+const selectedFile = ref<FileItem | null>(null);
+const isMenuOpen = ref(false);
+
+const getFileMenuItems = (file: FileItem): ActionMenuItem[] => {
+  const baseItems: ActionMenuItem[] = [
+    {
+      icon: "download",
+      title: "Download",
+      action: () => {
+        console.log(`Downloading ${file.name}`);
+        isMenuOpen.value = false;
+      },
+    },
+    {
+      icon: "copy",
+      title: "Copy",
+      action: () => {
+        console.log(`Copying ${file.name}`);
+        isMenuOpen.value = false;
+      },
+    },
+    {
+      icon: "edit",
+      title: "Rename",
+      action: () => {
+        console.log(`Renaming ${file.name}`);
+        isMenuOpen.value = false;
+      },
+    },
+  ];
+
+  if (file.type === "file") {
+    baseItems.push({
+      icon: "share",
+      title: "Share",
+      action: () => {
+        console.log(`Sharing ${file.name}`);
+        isMenuOpen.value = false;
+      },
+    });
+  }
+
+  baseItems.push({
+    icon: "trash",
+    title: "Delete",
+    action: () => {
+      console.log(`Deleting ${file.name}`);
+      isMenuOpen.value = false;
+    },
+    isDestructive: true,
+  });
+
+  return baseItems;
+};
+
+const handleFileClick = (file: FileItem) => {
+  selectedFile.value = file;
+  isMenuOpen.value = true;
+};
+
+const handleItemClick = (item: ActionMenuItem) => {
+  console.log("File action:", item.title);
+};
+</script>
+
+<template>
+  <div class="file-actions">
+    <h3>File Actions Menu</h3>
+    <p>Click on a file to see its action menu:</p>
+
+    <div class="file-list">
+      <div
+        v-for="file in files"
+        :key="file.id"
+        class="file-item"
+        @click="handleFileClick(file)"
+      >
+        <div class="file-icon">
+          {{ file.type === "folder" ? "📁" : "📄" }}
+        </div>
+        <div class="file-info">
+          <div class="file-name">{{ file.name }}</div>
+          <div v-if="file.size" class="file-size">{{ file.size }}</div>
+        </div>
+      </div>
+    </div>
+
+    <ActionMenu
+      v-if="selectedFile"
+      :items="getFileMenuItems(selectedFile)"
+      v-model="isMenuOpen"
+      @item-click="handleItemClick"
+    >
+      <div style="display: none;"></div>
+    </ActionMenu>
+  </div>
+</template>
+
+<style module>
+.file-actions {
+  padding: 2rem;
+  border: 1px solid #e0e0e0;
+  border-radius: 0.5rem;
+  max-width: 500px;
+}
+
+.file-list {
+  margin-top: 1rem;
+}
+
+.file-item {
+  display: flex;
+  align-items: center;
+  gap: 0.75rem;
+  padding: 0.75rem;
+  border: 1px solid #e0e0e0;
+  border-radius: 0.25rem;
+  margin-bottom: 0.5rem;
+  cursor: pointer;
+  transition: background-color 0.2s;
+}
+
+.file-item:hover {
+  background-color: #f8f9fa;
+}
+
+.file-icon {
+  font-size: 1.5rem;
+  width: 2rem;
+  text-align: center;
+}
+
+.file-info {
+  flex: 1;
+}
+
+.file-name {
+  font-weight: 500;
+  color: #333;
+}
+
+.file-size {
+  font-size: 0.875rem;
+  color: #666;
+  margin-top: 0.25rem;
+}
+</style>
+```
+
+### User Profile Menu
+
+```vue
+<script setup lang="ts">
+import { ref } from "vue";
+import { ActionMenu, Button } from "@umbra-ui/core";
+import type { ActionMenuItem } from "@umbra-ui/core";
+
+const user = ref({
+  name: "John Doe",
+  email: "john@example.com",
+  avatar: "👤",
+});
+
+const isProfileMenuOpen = ref(false);
+
+const profileMenuItems: ActionMenuItem[] = [
+  {
+    icon: "user",
+    title: "View Profile",
+    action: () => {
+      console.log("Viewing profile...");
+      isProfileMenuOpen.value = false;
+    },
+  },
+  {
+    icon: "settings",
+    title: "Settings",
+    action: () => {
+      console.log("Opening settings...");
+      isProfileMenuOpen.value = false;
+    },
+  },
+  {
+    icon: "bell",
+    title: "Notifications",
+    action: () => {
+      console.log("Opening notifications...");
+      isProfileMenuOpen.value = false;
+    },
+  },
+  {
+    icon: "help",
+    title: "Help & Support",
+    action: () => {
+      console.log("Opening help...");
+      isProfileMenuOpen.value = false;
+    },
+  },
+  {
+    icon: "logout",
+    title: "Sign Out",
+    action: () => {
+      console.log("Signing out...");
+      isProfileMenuOpen.value = false;
+    },
+    isDestructive: true,
+  },
+];
+
+const handleProfileItemClick = (item: ActionMenuItem) => {
+  console.log("Profile menu item clicked:", item.title);
+};
+</script>
+
+<template>
+  <div class="profile-menu">
+    <h3>User Profile Menu</h3>
+
+    <div class="user-info">
+      <div class="user-avatar">{{ user.avatar }}</div>
+      <div class="user-details">
+        <div class="user-name">{{ user.name }}</div>
+        <div class="user-email">{{ user.email }}</div>
+      </div>
+    </div>
+
+    <ActionMenu
+      :items="profileMenuItems"
+      v-model="isProfileMenuOpen"
+      @item-click="handleProfileItemClick"
+    >
+      <Button class="profile-button">
+        <span class="profile-avatar">{{ user.avatar }}</span>
+        <span>{{ user.name }}</span>
+        <span class="dropdown-arrow">▼</span>
+      </Button>
+    </ActionMenu>
+  </div>
+</template>
+
+<style module>
+.profile-menu {
+  padding: 2rem;
+  border: 1px solid #e0e0e0;
+  border-radius: 0.5rem;
+  max-width: 400px;
+}
+
+.user-info {
+  display: flex;
+  align-items: center;
+  gap: 1rem;
+  margin-bottom: 1.5rem;
+  padding: 1rem;
+  background-color: #f8f9fa;
+  border-radius: 0.5rem;
+}
+
+.user-avatar {
+  font-size: 2rem;
+  width: 3rem;
+  height: 3rem;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  background-color: #e9ecef;
+  border-radius: 50%;
+}
+
+.user-details {
+  flex: 1;
+}
+
+.user-name {
+  font-weight: 600;
+  color: #333;
+  margin-bottom: 0.25rem;
+}
+
+.user-email {
+  color: #666;
+  font-size: 0.875rem;
+}
+
+.profile-button {
+  display: flex;
+  align-items: center;
+  gap: 0.5rem;
+  width: 100%;
+  justify-content: space-between;
+}
+
+.profile-avatar {
+  font-size: 1.25rem;
+}
+
+.dropdown-arrow {
+  font-size: 0.75rem;
+  opacity: 0.6;
+}
+</style>
+```
+
+### Custom Styled Menu
+
+```vue
+<script setup lang="ts">
+import { ref } from "vue";
+import { ActionMenu, Button } from "@umbra-ui/core";
+import type { ActionMenuItem } from "@umbra-ui/core";
+
+const isCustomMenuOpen = ref(false);
+
+const customMenuItems: ActionMenuItem[] = [
+  {
+    icon: "star",
+    title: "Add to Favorites",
+    action: () => {
+      console.log("Added to favorites");
+      isCustomMenuOpen.value = false;
+    },
+  },
+  {
+    icon: "bookmark",
+    title: "Bookmark",
+    action: () => {
+      console.log("Bookmarked");
+      isCustomMenuOpen.value = false;
+    },
+  },
+  {
+    icon: "flag",
+    title: "Report",
+    action: () => {
+      console.log("Reported");
+      isCustomMenuOpen.value = false;
+    },
+    isDestructive: true,
+  },
+];
+
+const handleCustomItemClick = (item: ActionMenuItem) => {
+  console.log("Custom menu item clicked:", item.title);
+};
+</script>
+
+<template>
+  <div class="custom-styled-menu">
+    <h3>Custom Styled Action Menu</h3>
+
+    <ActionMenu
+      :items="customMenuItems"
+      v-model="isCustomMenuOpen"
+      @item-click="handleCustomItemClick"
+    >
+      <Button class="custom-trigger">Custom Menu</Button>
+    </ActionMenu>
+  </div>
+</template>
+
+<style module>
+.custom-styled-menu {
+  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 CSS variables for the menu */
+:global(.custom-styled-menu) {
+  --actionmenu-popup-bg: #ffffff;
+  --actionmenu-popup-border: 2px solid #667eea;
+  --actionmenu-popup-shadow: 0 10px 25px rgba(0, 0, 0, 0.1);
+
+  --actionmenu-item-hover-bg: rgba(102, 126, 234, 0.1);
+  --actionmenu-item-text: #333333;
+  --actionmenu-item-icon: #667eea;
+
+  --actionmenu-destructive-text: #e74c3c;
+  --actionmenu-destructive-icon: #e74c3c;
+
+  --actionmenu-overlay-bg: rgba(102, 126, 234, 0.2);
+}
+</style>
+```
+
+## Technical Notes
+
+- ActionMenu provides a flexible dropdown menu system with both click and context menu support
+- Floating UI integration ensures smart positioning that adapts to viewport constraints
+- Context menus include backdrop blur effects for better visual separation
+- Destructive actions are visually distinguished with red coloring
+- Full icon integration with @umbra-ui/icons for consistent visual language
+- Smooth animations and hover effects enhance user experience
+- TypeScript interfaces ensure type safety for menu items and actions
+- CSS custom properties enable easy theming and customization
+- Teleport usage ensures proper z-index layering and positioning
+- Auto-cleanup of positioning listeners prevents memory leaks
+- Responsive design adapts to different screen sizes and orientations