@umbra.ui/core 0.1.0

package/src/components/pickers/CollectionPicker/README.md

@@ -0,0 +1,1115 @@
+# CollectionPicker
+
+A versatile collection picker component built with Vue 3 Composition API and TypeScript. The CollectionPicker provides an intuitive interface for selecting items from a collection with support for creating new items, customizable icons, and smart positioning using Floating UI.
+
+## Installation/Import
+
+```typescript
+import { CollectionPicker } from "@umbra-ui/core";
+import type { CollectionItem } from "@umbra-ui/core";
+```
+
+**Dependencies:**
+
+- Vue 3.x
+- @floating-ui/vue (for positioning)
+- @umbra-ui/icons (for icon support)
+- @umbra-ui/core (for IconButton)
+
+## Basic Usage
+
+```vue
+<script setup lang="ts">
+import { ref } from "vue";
+import { CollectionPicker } from "@umbra-ui/core";
+import type { CollectionItem } from "@umbra-ui/core";
+
+const items = ref<CollectionItem[]>([
+  { id: "1", title: "Project Alpha" },
+  { id: "2", title: "Project Beta" },
+  { id: "3", title: "Project Gamma" },
+]);
+
+const selectedItem = ref<CollectionItem | null>(null);
+
+const handleItemSelected = (item: CollectionItem) => {
+  console.log("Selected item:", item);
+};
+
+const handleItemCreate = (title: string) => {
+  const newItem: CollectionItem = {
+    id: Date.now().toString(),
+    title: title,
+  };
+  items.value.push(newItem);
+  selectedItem.value = newItem;
+  console.log("Created new item:", newItem);
+};
+</script>
+
+<template>
+  <div class="app">
+    <h2>Select a Project</h2>
+
+    <CollectionPicker
+      v-model:selected-item="selectedItem"
+      :items="items"
+      button-label="Choose Project"
+      header-label="Select a Project"
+      new-item-label="Create New Project"
+      @item-selected="handleItemSelected"
+      @item-create="handleItemCreate"
+    />
+
+    <div v-if="selectedItem" class="selected-info">
+      <p>Selected: {{ selectedItem.title }}</p>
+    </div>
+  </div>
+</template>
+
+<style module>
+.app {
+  padding: 24px;
+  max-width: 400px;
+}
+
+.selected-info {
+  margin-top: 16px;
+  padding: 12px;
+  background: #f8f9fa;
+  border-radius: 6px;
+}
+</style>
+```
+
+## Props
+
+| Prop Name      | Type                     | Required | Default            | Description                             |
+| -------------- | ------------------------ | -------- | ------------------ | --------------------------------------- |
+| `items`        | `CollectionItem[]`       | Yes      | `[]`               | Array of items to display in the picker |
+| `selectedItem` | `CollectionItem \| null` | No       | `null`             | Currently selected item                 |
+| `loading`      | `boolean`                | No       | `false`            | Whether the picker is in loading state  |
+| `buttonLabel`  | `string`                 | No       | `"Select Item"`    | Label for the trigger button            |
+| `headerLabel`  | `string`                 | No       | `"Choose an Item"` | Header text in the picker               |
+| `newItemLabel` | `string`                 | No       | `"New Item"`       | Label for the create new item option    |
+| `itemIcon`     | `string`                 | No       | `"note"`           | Icon name for items                     |
+| `newItemIcon`  | `string`                 | No       | `"circle-plus"`    | Icon name for create new item           |
+| `allowCreate`  | `boolean`                | No       | `true`             | Whether to allow creating new items     |
+| `placeholder`  | `string`                 | No       | `"Enter name..."`  | Placeholder text for new item input     |
+
+## CollectionItem Interface
+
+```typescript
+interface CollectionItem {
+  id: string;
+  title: string;
+  [key: string]: any; // Allow additional properties
+}
+```
+
+### CollectionItem Properties
+
+| Property        | Type     | Description                    |
+| --------------- | -------- | ------------------------------ |
+| `id`            | `string` | Unique identifier for the item |
+| `title`         | `string` | Display text for the item      |
+| `[key: string]` | `any`    | Additional custom properties   |
+
+## Events
+
+| Event Name            | Payload Type             | Description                                |
+| --------------------- | ------------------------ | ------------------------------------------ |
+| `item-selected`       | `CollectionItem`         | Emitted when an item is selected           |
+| `item-create`         | `string`                 | Emitted when a new item is created (title) |
+| `update:selectedItem` | `CollectionItem \| null` | Emitted when the selected item changes     |
+
+## CSS Customization
+
+### Layout Variables
+
+```css
+.collection-picker {
+  --picker-button-bg: #ffffff;
+  --picker-button-border: 1px solid #e9ecef;
+  --picker-button-hover-bg: #f8f9fa;
+  --picker-button-hover-border: 1px solid #dee2e6;
+  --picker-button-hover-shadow: rgba(0, 0, 0, 0.1);
+  --picker-button-hover-inset-shadow: rgba(255, 255, 255, 0.1);
+  --picker-button-selected-bg: #e3f2fd;
+  --picker-picker-bg: #ffffff;
+  --picker-picker-border: 1px solid #e9ecef;
+  --picker-picker-shadow: rgba(0, 0, 0, 0.1);
+  --picker-picker-inset-shadow: rgba(255, 255, 255, 0.1);
+  --picker-selection-bar-bg: #f8f9fa;
+  --picker-border-light: #e9ecef;
+  --picker-text-primary: #212529;
+  --picker-text-secondary: #6c757d;
+  --picker-bg-hover: #f8f9fa;
+  --picker-overlay-bg: rgba(0, 0, 0, 0.1);
+}
+```
+
+### Container Styling
+
+```css
+.collection-picker {
+  display: flex;
+  flex-direction: column;
+  align-items: start;
+  gap: 0.235rem;
+}
+```
+
+### Button Styling
+
+```css
+.collection-picker .button {
+  border-radius: 0.353rem;
+  padding: 0.588rem;
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  cursor: default;
+  background-color: var(--picker-button-bg);
+  border: var(--picker-button-border);
+  transition: all 0.3s ease;
+}
+```
+
+### Picker Styling
+
+```css
+.collection-picker .picker {
+  position: absolute;
+  background-color: var(--picker-picker-bg);
+  border-radius: 0.353rem;
+  min-width: 18.824rem;
+  overflow: hidden;
+  z-index: 1000;
+  box-shadow: var(--picker-picker-shadow);
+  border: var(--picker-picker-border);
+}
+```
+
+## Examples
+
+### Project Selector
+
+```vue
+<script setup lang="ts">
+import { ref } from "vue";
+import { CollectionPicker } from "@umbra-ui/core";
+import type { CollectionItem } from "@umbra-ui/core";
+
+const projects = ref<CollectionItem[]>([
+  { id: "1", title: "E-commerce Platform", status: "active" },
+  { id: "2", title: "Mobile App", status: "development" },
+  { id: "3", title: "API Service", status: "completed" },
+  { id: "4", title: "Dashboard", status: "planning" },
+]);
+
+const selectedProject = ref<CollectionItem | null>(null);
+
+const handleProjectSelected = (project: CollectionItem) => {
+  console.log("Selected project:", project);
+};
+
+const handleProjectCreate = (title: string) => {
+  const newProject: CollectionItem = {
+    id: Date.now().toString(),
+    title: title,
+    status: "planning",
+  };
+  projects.value.push(newProject);
+  selectedProject.value = newProject;
+  console.log("Created new project:", newProject);
+};
+</script>
+
+<template>
+  <div class="project-selector">
+    <div class="selector-header">
+      <h3>Project Management</h3>
+      <p>Select or create a project to work on</p>
+    </div>
+
+    <CollectionPicker
+      v-model:selected-item="selectedProject"
+      :items="projects"
+      button-label="Choose Project"
+      header-label="Select a Project"
+      new-item-label="Create New Project"
+      item-icon="folder"
+      new-item-icon="plus"
+      placeholder="Enter project name..."
+      @item-selected="handleProjectSelected"
+      @item-create="handleProjectCreate"
+    />
+
+    <div v-if="selectedProject" class="project-details">
+      <h4>{{ selectedProject.title }}</h4>
+      <p>Status: {{ selectedProject.status }}</p>
+    </div>
+  </div>
+</template>
+
+<style module>
+.project-selector {
+  padding: 24px;
+  max-width: 500px;
+  background: #ffffff;
+  border-radius: 12px;
+  box-shadow: 0 2px 8px rgba(0, 0, 0, 0.1);
+}
+
+.selector-header {
+  margin-bottom: 24px;
+}
+
+.selector-header h3 {
+  font-size: 20px;
+  font-weight: 600;
+  color: #1a202c;
+  margin: 0 0 8px 0;
+}
+
+.selector-header p {
+  color: #718096;
+  margin: 0;
+}
+
+.project-details {
+  margin-top: 20px;
+  padding: 16px;
+  background: #f7fafc;
+  border-radius: 8px;
+  border-left: 4px solid #4299e1;
+}
+
+.project-details h4 {
+  font-size: 16px;
+  font-weight: 600;
+  color: #2d3748;
+  margin: 0 0 8px 0;
+}
+
+.project-details p {
+  color: #4a5568;
+  margin: 0;
+}
+</style>
+```
+
+### Category Picker
+
+```vue
+<script setup lang="ts">
+import { ref } from "vue";
+import { CollectionPicker } from "@umbra-ui/core";
+import type { CollectionItem } from "@umbra-ui/core";
+
+const categories = ref<CollectionItem[]>([
+  { id: "1", title: "Technology", color: "#3b82f6", count: 15 },
+  { id: "2", title: "Design", color: "#8b5cf6", count: 8 },
+  { id: "3", title: "Business", color: "#10b981", count: 12 },
+  { id: "4", title: "Marketing", color: "#f59e0b", count: 6 },
+]);
+
+const selectedCategory = ref<CollectionItem | null>(null);
+
+const handleCategorySelected = (category: CollectionItem) => {
+  console.log("Selected category:", category);
+};
+
+const handleCategoryCreate = (title: string) => {
+  const newCategory: CollectionItem = {
+    id: Date.now().toString(),
+    title: title,
+    color: "#6b7280",
+    count: 0,
+  };
+  categories.value.push(newCategory);
+  selectedCategory.value = newCategory;
+  console.log("Created new category:", newCategory);
+};
+</script>
+
+<template>
+  <div class="category-picker">
+    <div class="picker-header">
+      <h3>Content Categories</h3>
+      <p>Organize your content with categories</p>
+    </div>
+
+    <CollectionPicker
+      v-model:selected-item="selectedCategory"
+      :items="categories"
+      button-label="Select Category"
+      header-label="Choose a Category"
+      new-item-label="Add New Category"
+      item-icon="tag"
+      new-item-icon="tag-plus"
+      placeholder="Category name..."
+      @item-selected="handleCategorySelected"
+      @item-create="handleCategoryCreate"
+    />
+
+    <div v-if="selectedCategory" class="category-info">
+      <div class="category-header">
+        <div
+          class="category-color"
+          :style="{ backgroundColor: selectedCategory.color }"
+        />
+        <h4>{{ selectedCategory.title }}</h4>
+      </div>
+      <p>{{ selectedCategory.count }} items in this category</p>
+    </div>
+  </div>
+</template>
+
+<style module>
+.category-picker {
+  padding: 24px;
+  max-width: 400px;
+  background: #ffffff;
+  border-radius: 12px;
+  box-shadow: 0 2px 8px rgba(0, 0, 0, 0.1);
+}
+
+.picker-header {
+  margin-bottom: 24px;
+}
+
+.picker-header h3 {
+  font-size: 20px;
+  font-weight: 600;
+  color: #1a202c;
+  margin: 0 0 8px 0;
+}
+
+.picker-header p {
+  color: #718096;
+  margin: 0;
+}
+
+.category-info {
+  margin-top: 20px;
+  padding: 16px;
+  background: #f7fafc;
+  border-radius: 8px;
+}
+
+.category-header {
+  display: flex;
+  align-items: center;
+  gap: 12px;
+  margin-bottom: 8px;
+}
+
+.category-color {
+  width: 16px;
+  height: 16px;
+  border-radius: 50%;
+}
+
+.category-header h4 {
+  font-size: 16px;
+  font-weight: 600;
+  color: #2d3748;
+  margin: 0;
+}
+
+.category-info p {
+  color: #4a5568;
+  margin: 0;
+  font-size: 14px;
+}
+</style>
+```
+
+### Team Member Selector
+
+```vue
+<script setup lang="ts">
+import { ref } from "vue";
+import { CollectionPicker } from "@umbra-ui/core";
+import type { CollectionItem } from "@umbra-ui/core";
+
+const teamMembers = ref<CollectionItem[]>([
+  { id: "1", title: "Alice Johnson", role: "Frontend Developer", avatar: "👩‍💻" },
+  { id: "2", title: "Bob Smith", role: "Backend Developer", avatar: "👨‍💻" },
+  { id: "3", title: "Carol Davis", role: "UI/UX Designer", avatar: "👩‍🎨" },
+  { id: "4", title: "David Wilson", role: "Project Manager", avatar: "👨‍💼" },
+]);
+
+const selectedMember = ref<CollectionItem | null>(null);
+
+const handleMemberSelected = (member: CollectionItem) => {
+  console.log("Selected team member:", member);
+};
+
+const handleMemberCreate = (title: string) => {
+  const newMember: CollectionItem = {
+    id: Date.now().toString(),
+    title: title,
+    role: "Team Member",
+    avatar: "👤",
+  };
+  teamMembers.value.push(newMember);
+  selectedMember.value = newMember;
+  console.log("Added new team member:", newMember);
+};
+</script>
+
+<template>
+  <div class="team-selector">
+    <div class="selector-header">
+      <h3>Team Assignment</h3>
+      <p>Assign tasks to team members</p>
+    </div>
+
+    <CollectionPicker
+      v-model:selected-item="selectedMember"
+      :items="teamMembers"
+      button-label="Assign to Team Member"
+      header-label="Select Team Member"
+      new-item-label="Add New Member"
+      item-icon="user"
+      new-item-icon="user-plus"
+      placeholder="Member name..."
+      @item-selected="handleMemberSelected"
+      @item-create="handleMemberCreate"
+    />
+
+    <div v-if="selectedMember" class="member-details">
+      <div class="member-header">
+        <span class="member-avatar">{{ selectedMember.avatar }}</span>
+        <div class="member-info">
+          <h4>{{ selectedMember.title }}</h4>
+          <p>{{ selectedMember.role }}</p>
+        </div>
+      </div>
+    </div>
+  </div>
+</template>
+
+<style module>
+.team-selector {
+  padding: 24px;
+  max-width: 450px;
+  background: #ffffff;
+  border-radius: 12px;
+  box-shadow: 0 2px 8px rgba(0, 0, 0, 0.1);
+}
+
+.selector-header {
+  margin-bottom: 24px;
+}
+
+.selector-header h3 {
+  font-size: 20px;
+  font-weight: 600;
+  color: #1a202c;
+  margin: 0 0 8px 0;
+}
+
+.selector-header p {
+  color: #718096;
+  margin: 0;
+}
+
+.member-details {
+  margin-top: 20px;
+  padding: 16px;
+  background: #f7fafc;
+  border-radius: 8px;
+  border-left: 4px solid #4299e1;
+}
+
+.member-header {
+  display: flex;
+  align-items: center;
+  gap: 12px;
+}
+
+.member-avatar {
+  font-size: 24px;
+  width: 40px;
+  height: 40px;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  background: #e2e8f0;
+  border-radius: 50%;
+}
+
+.member-info h4 {
+  font-size: 16px;
+  font-weight: 600;
+  color: #2d3748;
+  margin: 0 0 4px 0;
+}
+
+.member-info p {
+  color: #4a5568;
+  margin: 0;
+  font-size: 14px;
+}
+</style>
+```
+
+### File Type Picker
+
+```vue
+<script setup lang="ts">
+import { ref } from "vue";
+import { CollectionPicker } from "@umbra-ui/core";
+import type { CollectionItem } from "@umbra-ui/core";
+
+const fileTypes = ref<CollectionItem[]>([
+  { id: "1", title: "Documents", extension: ".doc,.docx,.pdf", icon: "📄" },
+  { id: "2", title: "Images", extension: ".jpg,.png,.gif", icon: "🖼️" },
+  { id: "3", title: "Videos", extension: ".mp4,.avi,.mov", icon: "🎥" },
+  { id: "4", title: "Audio", extension: ".mp3,.wav,.flac", icon: "🎵" },
+  { id: "5", title: "Archives", extension: ".zip,.rar,.7z", icon: "📦" },
+]);
+
+const selectedFileType = ref<CollectionItem | null>(null);
+
+const handleFileTypeSelected = (fileType: CollectionItem) => {
+  console.log("Selected file type:", fileType);
+};
+
+const handleFileTypeCreate = (title: string) => {
+  const newFileType: CollectionItem = {
+    id: Date.now().toString(),
+    title: title,
+    extension: ".*",
+    icon: "📁",
+  };
+  fileTypes.value.push(newFileType);
+  selectedFileType.value = newFileType;
+  console.log("Created new file type:", newFileType);
+};
+</script>
+
+<template>
+  <div class="file-type-picker">
+    <div class="picker-header">
+      <h3>File Type Filter</h3>
+      <p>Filter files by type</p>
+    </div>
+
+    <CollectionPicker
+      v-model:selected-item="selectedFileType"
+      :items="fileTypes"
+      button-label="Select File Type"
+      header-label="Choose File Type"
+      new-item-label="Add Custom Type"
+      item-icon="file"
+      new-item-icon="file-plus"
+      placeholder="File type name..."
+      @item-selected="handleFileTypeSelected"
+      @item-create="handleFileTypeCreate"
+    />
+
+    <div v-if="selectedFileType" class="file-type-info">
+      <div class="file-type-header">
+        <span class="file-type-icon">{{ selectedFileType.icon }}</span>
+        <div class="file-type-details">
+          <h4>{{ selectedFileType.title }}</h4>
+          <p>Extensions: {{ selectedFileType.extension }}</p>
+        </div>
+      </div>
+    </div>
+  </div>
+</template>
+
+<style module>
+.file-type-picker {
+  padding: 24px;
+  max-width: 400px;
+  background: #ffffff;
+  border-radius: 12px;
+  box-shadow: 0 2px 8px rgba(0, 0, 0, 0.1);
+}
+
+.picker-header {
+  margin-bottom: 24px;
+}
+
+.picker-header h3 {
+  font-size: 20px;
+  font-weight: 600;
+  color: #1a202c;
+  margin: 0 0 8px 0;
+}
+
+.picker-header p {
+  color: #718096;
+  margin: 0;
+}
+
+.file-type-info {
+  margin-top: 20px;
+  padding: 16px;
+  background: #f7fafc;
+  border-radius: 8px;
+  border-left: 4px solid #10b981;
+}
+
+.file-type-header {
+  display: flex;
+  align-items: center;
+  gap: 12px;
+}
+
+.file-type-icon {
+  font-size: 24px;
+  width: 40px;
+  height: 40px;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  background: #d1fae5;
+  border-radius: 8px;
+}
+
+.file-type-details h4 {
+  font-size: 16px;
+  font-weight: 600;
+  color: #2d3748;
+  margin: 0 0 4px 0;
+}
+
+.file-type-details p {
+  color: #4a5568;
+  margin: 0;
+  font-size: 14px;
+}
+</style>
+```
+
+### Loading State Example
+
+```vue
+<script setup lang="ts">
+import { ref, onMounted } from "vue";
+import { CollectionPicker } from "@umbra-ui/core";
+import type { CollectionItem } from "@umbra-ui/core";
+
+const items = ref<CollectionItem[]>([]);
+const selectedItem = ref<CollectionItem | null>(null);
+const loading = ref(true);
+
+// Simulate loading data
+onMounted(async () => {
+  // Simulate API call
+  await new Promise((resolve) => setTimeout(resolve, 2000));
+
+  items.value = [
+    { id: "1", title: "Item 1" },
+    { id: "2", title: "Item 2" },
+    { id: "3", title: "Item 3" },
+  ];
+
+  loading.value = false;
+});
+
+const handleItemSelected = (item: CollectionItem) => {
+  console.log("Selected item:", item);
+};
+
+const handleItemCreate = (title: string) => {
+  const newItem: CollectionItem = {
+    id: Date.now().toString(),
+    title: title,
+  };
+  items.value.push(newItem);
+  selectedItem.value = newItem;
+  console.log("Created new item:", newItem);
+};
+</script>
+
+<template>
+  <div class="loading-example">
+    <h3>Loading State Example</h3>
+
+    <CollectionPicker
+      v-model:selected-item="selectedItem"
+      :items="items"
+      :loading="loading"
+      button-label="Select Item"
+      header-label="Choose an Item"
+      new-item-label="Create New Item"
+      @item-selected="handleItemSelected"
+      @item-create="handleItemCreate"
+    />
+
+    <div v-if="loading" class="loading-message">
+      <p>Loading items...</p>
+    </div>
+  </div>
+</template>
+
+<style module>
+.loading-example {
+  padding: 24px;
+  max-width: 400px;
+}
+
+.loading-message {
+  margin-top: 16px;
+  padding: 12px;
+  background: #f8f9fa;
+  border-radius: 6px;
+  text-align: center;
+}
+
+.loading-message p {
+  color: #6c757d;
+  margin: 0;
+}
+</style>
+```
+
+## Advanced Usage
+
+### Custom Item Properties
+
+```vue
+<script setup lang="ts">
+import { ref } from "vue";
+import { CollectionPicker } from "@umbra-ui/core";
+import type { CollectionItem } from "@umbra-ui/core";
+
+// Extend the base interface for custom properties
+interface CustomItem extends CollectionItem {
+  description: string;
+  priority: "low" | "medium" | "high";
+  tags: string[];
+}
+
+const items = ref<CustomItem[]>([
+  {
+    id: "1",
+    title: "Bug Fix",
+    description: "Fix critical authentication bug",
+    priority: "high",
+    tags: ["bug", "auth"],
+  },
+  {
+    id: "2",
+    title: "Feature Request",
+    description: "Add dark mode support",
+    priority: "medium",
+    tags: ["feature", "ui"],
+  },
+  {
+    id: "3",
+    title: "Documentation",
+    description: "Update API documentation",
+    priority: "low",
+    tags: ["docs", "api"],
+  },
+]);
+
+const selectedItem = ref<CustomItem | null>(null);
+
+const handleItemSelected = (item: CustomItem) => {
+  console.log("Selected item with custom properties:", item);
+};
+
+const handleItemCreate = (title: string) => {
+  const newItem: CustomItem = {
+    id: Date.now().toString(),
+    title: title,
+    description: "New item",
+    priority: "medium",
+    tags: [],
+  };
+  items.value.push(newItem);
+  selectedItem.value = newItem;
+};
+</script>
+
+<template>
+  <div class="custom-properties">
+    <CollectionPicker
+      v-model:selected-item="selectedItem"
+      :items="items"
+      button-label="Select Task"
+      header-label="Choose a Task"
+      new-item-label="Create New Task"
+      item-icon="checklist"
+      new-item-icon="plus"
+      @item-selected="handleItemSelected"
+      @item-create="handleItemCreate"
+    />
+
+    <div v-if="selectedItem" class="item-details">
+      <h4>{{ selectedItem.title }}</h4>
+      <p>{{ selectedItem.description }}</p>
+      <div class="item-meta">
+        <span class="priority" :class="`priority-${selectedItem.priority}`">
+          {{ selectedItem.priority }}
+        </span>
+        <div class="tags">
+          <span v-for="tag in selectedItem.tags" :key="tag" class="tag">
+            {{ tag }}
+          </span>
+        </div>
+      </div>
+    </div>
+  </div>
+</template>
+
+<style module>
+.custom-properties {
+  padding: 24px;
+  max-width: 500px;
+}
+
+.item-details {
+  margin-top: 20px;
+  padding: 16px;
+  background: #f7fafc;
+  border-radius: 8px;
+}
+
+.item-details h4 {
+  font-size: 16px;
+  font-weight: 600;
+  color: #2d3748;
+  margin: 0 0 8px 0;
+}
+
+.item-details p {
+  color: #4a5568;
+  margin: 0 0 12px 0;
+}
+
+.item-meta {
+  display: flex;
+  align-items: center;
+  gap: 12px;
+}
+
+.priority {
+  padding: 4px 8px;
+  border-radius: 4px;
+  font-size: 12px;
+  font-weight: 500;
+  text-transform: uppercase;
+}
+
+.priority-low {
+  background: #d1fae5;
+  color: #065f46;
+}
+
+.priority-medium {
+  background: #fef3c7;
+  color: #92400e;
+}
+
+.priority-high {
+  background: #fee2e2;
+  color: #991b1b;
+}
+
+.tags {
+  display: flex;
+  gap: 4px;
+}
+
+.tag {
+  padding: 2px 6px;
+  background: #e5e7eb;
+  color: #374151;
+  border-radius: 3px;
+  font-size: 11px;
+}
+</style>
+```
+
+### Integration with API
+
+```vue
+<script setup lang="ts">
+import { ref, onMounted } from "vue";
+import { CollectionPicker } from "@umbra-ui/core";
+import type { CollectionItem } from "@umbra-ui/core";
+
+const items = ref<CollectionItem[]>([]);
+const selectedItem = ref<CollectionItem | null>(null);
+const loading = ref(false);
+
+// Simulate API calls
+const fetchItems = async () => {
+  loading.value = true;
+  try {
+    // Simulate API call
+    await new Promise((resolve) => setTimeout(resolve, 1000));
+    items.value = [
+      { id: "1", title: "API Item 1" },
+      { id: "2", title: "API Item 2" },
+      { id: "3", title: "API Item 3" },
+    ];
+  } catch (error) {
+    console.error("Failed to fetch items:", error);
+  } finally {
+    loading.value = false;
+  }
+};
+
+const createItem = async (title: string) => {
+  try {
+    // Simulate API call
+    await new Promise((resolve) => setTimeout(resolve, 500));
+    const newItem: CollectionItem = {
+      id: Date.now().toString(),
+      title: title,
+    };
+    items.value.push(newItem);
+    selectedItem.value = newItem;
+    return newItem;
+  } catch (error) {
+    console.error("Failed to create item:", error);
+    throw error;
+  }
+};
+
+const handleItemSelected = (item: CollectionItem) => {
+  console.log("Selected item:", item);
+};
+
+const handleItemCreate = async (title: string) => {
+  try {
+    await createItem(title);
+    console.log("Item created successfully");
+  } catch (error) {
+    console.error("Failed to create item");
+  }
+};
+
+onMounted(() => {
+  fetchItems();
+});
+</script>
+
+<template>
+  <div class="api-integration">
+    <h3>API Integration Example</h3>
+
+    <CollectionPicker
+      v-model:selected-item="selectedItem"
+      :items="items"
+      :loading="loading"
+      button-label="Select Item"
+      header-label="Choose an Item"
+      new-item-label="Create New Item"
+      @item-selected="handleItemSelected"
+      @item-create="handleItemCreate"
+    />
+
+    <div class="actions">
+      <button @click="fetchItems" :disabled="loading" class="refresh-btn">
+        {{ loading ? "Loading..." : "Refresh Items" }}
+      </button>
+    </div>
+  </div>
+</template>
+
+<style module>
+.api-integration {
+  padding: 24px;
+  max-width: 400px;
+}
+
+.actions {
+  margin-top: 16px;
+}
+
+.refresh-btn {
+  padding: 8px 16px;
+  background: #007bff;
+  color: white;
+  border: none;
+  border-radius: 6px;
+  cursor: pointer;
+  transition: background 0.2s ease;
+}
+
+.refresh-btn:hover:not(:disabled) {
+  background: #0056b3;
+}
+
+.refresh-btn:disabled {
+  opacity: 0.6;
+  cursor: not-allowed;
+}
+</style>
+```
+
+## Performance Considerations
+
+- **Floating UI**: Smart positioning with automatic updates and cleanup
+- **Teleport**: Overlay and picker are teleported to body for proper z-index management
+- **Event Cleanup**: Proper cleanup of auto-update listeners on unmount
+- **Icon Loading**: Icons are loaded on-demand from the @umbra-ui/icons package
+
+## Accessibility
+
+- **Keyboard Navigation**: Support for Enter and Escape keys in input
+- **Screen Reader Support**: Proper ARIA labels and semantic structure
+- **Focus Management**: Focus is properly managed during interactions
+- **Overlay Interaction**: Click outside to close functionality
+
+## Browser Support
+
+- **Modern Browsers**: Chrome 88+, Firefox 85+, Safari 14+, Edge 88+
+- **Mobile Browsers**: iOS Safari 14+, Chrome Mobile 88+
+- **CSS Features**: Uses CSS Grid and modern layout features
+- **JavaScript**: Requires ES2020+ support
+
+## Troubleshooting
+
+### Common Issues
+
+1. **Picker not positioning correctly**: Ensure the trigger button has proper positioning context
+2. **Items not displaying**: Check that the items array is properly formatted with id and title
+3. **Icons not showing**: Verify icon names match those available in @umbra-ui/icons
+4. **Overlay not closing**: Ensure the overlay click handler is properly bound
+
+### Debug Mode
+
+```vue
+<script setup lang="ts">
+import { ref, watch } from "vue";
+import { CollectionPicker } from "@umbra-ui/core";
+
+const selectedItem = ref(null);
+
+// Watch for changes
+watch(selectedItem, (newItem) => {
+  console.log("Selected item changed:", newItem);
+});
+</script>
+```
+
+## Migration Guide
+
+### From v1 to v2
+
+- `v-model` prop is now `v-model:selected-item`
+- Event names have been updated to use kebab-case
+- Icon system has been updated to use @umbra-ui/icons
+- Floating UI integration has been improved
+
+### Breaking Changes
+
+- Removed `value` prop in favor of `v-model:selected-item`
+- Changed event names from camelCase to kebab-case
+- Updated icon prop to use string names instead of components
+- Modified CSS class naming convention