@umbra.ui/core 0.1.0

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

@@ -0,0 +1,1161 @@
+# IconPicker
+
+A comprehensive icon picker component built with Vue 3 Composition API and TypeScript. The IconPicker provides an intuitive interface for selecting icons from the @umbra-ui/icons library with support for custom icon lists, smart positioning using Floating UI, and smooth animations.
+
+## Installation/Import
+
+```typescript
+import { IconPicker } from "@umbra-ui/core";
+import type { IconKey } from "@umbra-ui/icons";
+```
+
+**Dependencies:**
+
+- Vue 3.x
+- @floating-ui/vue (for positioning)
+- @umbra-ui/icons (for icon library)
+
+## Basic Usage
+
+```vue
+<script setup lang="ts">
+import { ref } from "vue";
+import { IconPicker } from "@umbra-ui/core";
+import type { IconKey } from "@umbra-ui/icons";
+
+const selectedIcon = ref<IconKey>("home");
+
+const handleIconChange = (icon: IconKey) => {
+  console.log("Selected icon:", icon);
+};
+</script>
+
+<template>
+  <div class="app">
+    <h2>Choose an Icon</h2>
+
+    <IconPicker v-model:icon="selectedIcon" @update:icon="handleIconChange" />
+
+    <div v-if="selectedIcon" class="icon-info">
+      <p>
+        Selected icon: <strong>{{ selectedIcon }}</strong>
+      </p>
+    </div>
+  </div>
+</template>
+
+<style module>
+.app {
+  padding: 24px;
+  max-width: 400px;
+}
+
+.icon-info {
+  margin-top: 20px;
+  padding: 16px;
+  background: #f8f9fa;
+  border-radius: 8px;
+}
+
+.icon-info p {
+  margin: 0;
+  color: #495057;
+}
+</style>
+```
+
+## Props
+
+| Prop Name       | Type        | Required | Default     | Description                               |
+| --------------- | ----------- | -------- | ----------- | ----------------------------------------- |
+| `icon`          | `string`    | Yes      | `""`        | Currently selected icon key               |
+| `pickerOffsetX` | `number`    | No       | `0`         | Horizontal offset for picker positioning  |
+| `preventPopup`  | `boolean`   | No       | `false`     | Whether to prevent the popup from opening |
+| `iconList`      | `IconKey[]` | No       | `undefined` | Custom list of available icons            |
+| `iconSize`      | `number`    | No       | `18`        | Size of the displayed icon                |
+
+## Events
+
+| Event Name    | Payload Type | Description                      |
+| ------------- | ------------ | -------------------------------- |
+| `update:icon` | `string`     | Emitted when an icon is selected |
+
+## Available Icons
+
+The IconPicker includes access to the complete @umbra-ui/icons library with over 250 icons across various categories:
+
+### Icon Categories
+
+- **Navigation**: home, search, menu, back, forward, etc.
+- **Actions**: edit, delete, save, copy, paste, etc.
+- **Communication**: mail, phone, message, notification, etc.
+- **Media**: play, pause, stop, volume, image, video, etc.
+- **Files**: folder, file, document, download, upload, etc.
+- **Interface**: settings, user, lock, unlock, eye, etc.
+- **Arrows**: up, down, left, right, chevron variants, etc.
+- **Shapes**: circle, square, triangle, star, heart, etc.
+
+### Accessing Icons
+
+```typescript
+import { icons, type IconKey } from "@umbra-ui/icons";
+
+// Get all available icon keys
+const allIcons = Object.keys(icons) as IconKey[];
+
+// Filter icons by category
+const navigationIcons = allIcons.filter((key) =>
+  ["home", "search", "menu", "back", "forward"].includes(key)
+);
+
+// Use specific icons
+const homeIcon = icons.home;
+const searchIcon = icons.search;
+```
+
+## CSS Customization
+
+### Layout Variables
+
+```css
+.icon-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-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-selection-bar-text: #212529;
+  --picker-selection-bar-border: #e9ecef;
+  --picker-overlay-bg: rgba(0, 0, 0, 0.1);
+  --iconpicker-icon-cell-bg: #f3f4f6;
+  --iconpicker-icon-cell-border: #d1d5db;
+  --iconpicker-icon-cell-hover-bg: #e5e7eb;
+  --iconpicker-icon-cell-selected-bg: #acd8fc;
+  --iconpicker-icon-cell-selected-border: #5eb1ef;
+  --iconpicker-icon-color: #374151;
+}
+```
+
+### Container Styling
+
+```css
+.icon-picker {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  max-width: fit-content;
+}
+```
+
+### Button Styling
+
+```css
+.icon-picker .button {
+  padding: 0.588rem;
+  border-radius: 0.353rem;
+  cursor: pointer;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  gap: 0;
+  transition: all 0.3s ease;
+  background-color: var(--picker-button-bg);
+  border: var(--picker-button-border);
+}
+```
+
+### Icon Grid Styling
+
+```css
+.icon-picker .icon_list {
+  display: grid;
+  grid-template-columns: repeat(7, 1fr);
+  gap: 0.588rem;
+  padding: 0.588rem;
+}
+
+.icon-picker .icon_cell {
+  width: 2rem;
+  height: 2rem;
+  border-radius: 0.353rem;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  background-color: var(--iconpicker-icon-cell-bg);
+  cursor: pointer;
+  transition: border 0.3s ease;
+}
+```
+
+## Examples
+
+### Navigation Icon Selector
+
+```vue
+<script setup lang="ts">
+import { ref } from "vue";
+import { IconPicker } from "@umbra-ui/core";
+import type { IconKey } from "@umbra-ui/icons";
+
+const navigationIcons: IconKey[] = [
+  "home",
+  "search",
+  "menu",
+  "back",
+  "forward",
+  "up",
+  "down",
+  "left",
+  "right",
+  "chevron-up",
+  "chevron-down",
+  "chevron-left",
+  "chevron-right",
+  "arrow-up",
+  "arrow-down",
+  "arrow-left",
+  "arrow-right",
+  "external-link",
+  "link",
+];
+
+const selectedNavIcon = ref<IconKey>("home");
+
+const handleNavIconChange = (icon: IconKey) => {
+  console.log("Navigation icon changed to:", icon);
+};
+</script>
+
+<template>
+  <div class="navigation-selector">
+    <div class="selector-header">
+      <h3>Navigation Icon</h3>
+      <p>Choose an icon for your navigation menu</p>
+    </div>
+
+    <IconPicker
+      v-model:icon="selectedNavIcon"
+      :icon-list="navigationIcons"
+      :icon-size="20"
+      @update:icon="handleNavIconChange"
+    />
+
+    <div class="icon-preview">
+      <h4>Preview</h4>
+      <div class="preview-nav">
+        <div class="nav-item">
+          <IconPicker
+            v-model:icon="selectedNavIcon"
+            :icon-list="navigationIcons"
+            :icon-size="16"
+            :prevent-popup="true"
+          />
+          <span>Home</span>
+        </div>
+      </div>
+    </div>
+  </div>
+</template>
+
+<style module>
+.navigation-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: 24px;
+  font-weight: 600;
+  color: #1a202c;
+  margin: 0 0 8px 0;
+}
+
+.selector-header p {
+  color: #718096;
+  margin: 0;
+}
+
+.icon-preview {
+  margin-top: 32px;
+  padding-top: 24px;
+  border-top: 1px solid #e5e7eb;
+}
+
+.icon-preview h4 {
+  font-size: 18px;
+  font-weight: 500;
+  color: #2d3748;
+  margin: 0 0 16px 0;
+}
+
+.preview-nav {
+  padding: 16px;
+  background: #f7fafc;
+  border-radius: 8px;
+}
+
+.nav-item {
+  display: flex;
+  align-items: center;
+  gap: 12px;
+  padding: 8px 12px;
+  background: white;
+  border-radius: 6px;
+  border: 1px solid #e2e8f0;
+}
+
+.nav-item span {
+  font-size: 14px;
+  font-weight: 500;
+  color: #374151;
+}
+</style>
+```
+
+### Action Icon Selector
+
+```vue
+<script setup lang="ts">
+import { ref } from "vue";
+import { IconPicker } from "@umbra-ui/core";
+import type { IconKey } from "@umbra-ui/icons";
+
+const actionIcons: IconKey[] = [
+  "edit",
+  "delete",
+  "save",
+  "copy",
+  "paste",
+  "cut",
+  "undo",
+  "redo",
+  "plus",
+  "minus",
+  "check",
+  "x",
+  "trash",
+  "download",
+  "upload",
+  "refresh",
+  "reload",
+  "sync",
+  "settings",
+  "gear",
+];
+
+const selectedActionIcon = ref<IconKey>("edit");
+
+const handleActionIconChange = (icon: IconKey) => {
+  console.log("Action icon changed to:", icon);
+};
+</script>
+
+<template>
+  <div class="action-selector">
+    <div class="selector-header">
+      <h3>Action Icon</h3>
+      <p>Choose an icon for your action button</p>
+    </div>
+
+    <IconPicker
+      v-model:icon="selectedActionIcon"
+      :icon-list="actionIcons"
+      :icon-size="18"
+      @update:icon="handleActionIconChange"
+    />
+
+    <div class="action-preview">
+      <h4>Button Preview</h4>
+      <div class="preview-buttons">
+        <button class="action-btn primary">
+          <IconPicker
+            v-model:icon="selectedActionIcon"
+            :icon-list="actionIcons"
+            :icon-size="16"
+            :prevent-popup="true"
+          />
+          Action
+        </button>
+        <button class="action-btn secondary">
+          <IconPicker
+            v-model:icon="selectedActionIcon"
+            :icon-list="actionIcons"
+            :icon-size="16"
+            :prevent-popup="true"
+          />
+          Secondary
+        </button>
+      </div>
+    </div>
+  </div>
+</template>
+
+<style module>
+.action-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: 24px;
+  font-weight: 600;
+  color: #1a202c;
+  margin: 0 0 8px 0;
+}
+
+.selector-header p {
+  color: #718096;
+  margin: 0;
+}
+
+.action-preview {
+  margin-top: 32px;
+  padding-top: 24px;
+  border-top: 1px solid #e5e7eb;
+}
+
+.action-preview h4 {
+  font-size: 18px;
+  font-weight: 500;
+  color: #2d3748;
+  margin: 0 0 16px 0;
+}
+
+.preview-buttons {
+  display: flex;
+  gap: 12px;
+}
+
+.action-btn {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  padding: 8px 16px;
+  border: none;
+  border-radius: 6px;
+  font-size: 14px;
+  font-weight: 500;
+  cursor: pointer;
+  transition: all 0.2s ease;
+}
+
+.action-btn.primary {
+  background: #3b82f6;
+  color: white;
+}
+
+.action-btn.primary:hover {
+  background: #2563eb;
+}
+
+.action-btn.secondary {
+  background: #f3f4f6;
+  color: #374151;
+  border: 1px solid #d1d5db;
+}
+
+.action-btn.secondary:hover {
+  background: #e5e7eb;
+}
+</style>
+```
+
+### Media Icon Selector
+
+```vue
+<script setup lang="ts">
+import { ref } from "vue";
+import { IconPicker } from "@umbra-ui/core";
+import type { IconKey } from "@umbra-ui/icons";
+
+const mediaIcons: IconKey[] = [
+  "play",
+  "pause",
+  "stop",
+  "skip-back",
+  "skip-forward",
+  "volume-high",
+  "volume-low",
+  "volume-mute",
+  "image",
+  "video",
+  "camera",
+  "microphone",
+  "headphones",
+  "speaker",
+  "music",
+  "film",
+  "tv",
+  "radio",
+];
+
+const selectedMediaIcon = ref<IconKey>("play");
+
+const handleMediaIconChange = (icon: IconKey) => {
+  console.log("Media icon changed to:", icon);
+};
+</script>
+
+<template>
+  <div class="media-selector">
+    <div class="selector-header">
+      <h3>Media Icon</h3>
+      <p>Choose an icon for your media controls</p>
+    </div>
+
+    <IconPicker
+      v-model:icon="selectedMediaIcon"
+      :icon-list="mediaIcons"
+      :icon-size="22"
+      @update:icon="handleMediaIconChange"
+    />
+
+    <div class="media-preview">
+      <h4>Media Player Preview</h4>
+      <div class="preview-player">
+        <div class="player-controls">
+          <button class="control-btn">
+            <IconPicker
+              v-model:icon="selectedMediaIcon"
+              :icon-list="mediaIcons"
+              :icon-size="20"
+              :prevent-popup="true"
+            />
+          </button>
+          <div class="progress-bar">
+            <div class="progress-fill"></div>
+          </div>
+          <div class="time-display">2:34 / 4:12</div>
+        </div>
+      </div>
+    </div>
+  </div>
+</template>
+
+<style module>
+.media-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: 24px;
+  font-weight: 600;
+  color: #1a202c;
+  margin: 0 0 8px 0;
+}
+
+.selector-header p {
+  color: #718096;
+  margin: 0;
+}
+
+.media-preview {
+  margin-top: 32px;
+  padding-top: 24px;
+  border-top: 1px solid #e5e7eb;
+}
+
+.media-preview h4 {
+  font-size: 18px;
+  font-weight: 500;
+  color: #2d3748;
+  margin: 0 0 16px 0;
+}
+
+.preview-player {
+  padding: 20px;
+  background: #1f2937;
+  border-radius: 8px;
+}
+
+.player-controls {
+  display: flex;
+  align-items: center;
+  gap: 16px;
+}
+
+.control-btn {
+  width: 40px;
+  height: 40px;
+  background: #3b82f6;
+  color: white;
+  border: none;
+  border-radius: 50%;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  cursor: pointer;
+  transition: background 0.2s ease;
+}
+
+.control-btn:hover {
+  background: #2563eb;
+}
+
+.progress-bar {
+  flex: 1;
+  height: 4px;
+  background: #374151;
+  border-radius: 2px;
+  overflow: hidden;
+}
+
+.progress-fill {
+  width: 60%;
+  height: 100%;
+  background: #3b82f6;
+  border-radius: 2px;
+}
+
+.time-display {
+  color: #9ca3af;
+  font-size: 12px;
+  font-weight: 500;
+  min-width: 60px;
+  text-align: right;
+}
+</style>
+```
+
+### Custom Icon Set
+
+```vue
+<script setup lang="ts">
+import { ref } from "vue";
+import { IconPicker } from "@umbra-ui/core";
+import type { IconKey } from "@umbra-ui/icons";
+
+const customIcons: IconKey[] = [
+  "star",
+  "heart",
+  "thumbs-up",
+  "thumbs-down",
+  "bookmark",
+  "flag",
+  "bell",
+  "mail",
+  "phone",
+  "message",
+  "chat",
+  "comment",
+  "user",
+  "users",
+  "user-plus",
+  "user-minus",
+  "shield",
+  "lock",
+];
+
+const selectedCustomIcon = ref<IconKey>("star");
+
+const handleCustomIconChange = (icon: IconKey) => {
+  console.log("Custom icon changed to:", icon);
+};
+
+const addToFavorites = () => {
+  console.log("Added to favorites with icon:", selectedCustomIcon.value);
+};
+
+const shareContent = () => {
+  console.log("Shared content with icon:", selectedCustomIcon.value);
+};
+</script>
+
+<template>
+  <div class="custom-icon-selector">
+    <div class="selector-header">
+      <h3>Custom Icon Set</h3>
+      <p>Choose from a curated set of social and interaction icons</p>
+    </div>
+
+    <IconPicker
+      v-model:icon="selectedCustomIcon"
+      :icon-list="customIcons"
+      :icon-size="20"
+      @update:icon="handleCustomIconChange"
+    />
+
+    <div class="custom-preview">
+      <h4>Interactive Elements</h4>
+      <div class="preview-elements">
+        <button class="interactive-btn" @click="addToFavorites">
+          <IconPicker
+            v-model:icon="selectedCustomIcon"
+            :icon-list="customIcons"
+            :icon-size="16"
+            :prevent-popup="true"
+          />
+          Add to Favorites
+        </button>
+
+        <button class="interactive-btn" @click="shareContent">
+          <IconPicker
+            v-model:icon="selectedCustomIcon"
+            :icon-list="customIcons"
+            :icon-size="16"
+            :prevent-popup="true"
+          />
+          Share
+        </button>
+
+        <div class="social-stats">
+          <div class="stat-item">
+            <IconPicker
+              v-model:icon="selectedCustomIcon"
+              :icon-list="customIcons"
+              :icon-size="14"
+              :prevent-popup="true"
+            />
+            <span>1.2k</span>
+          </div>
+        </div>
+      </div>
+    </div>
+  </div>
+</template>
+
+<style module>
+.custom-icon-selector {
+  padding: 24px;
+  max-width: 600px;
+  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: 24px;
+  font-weight: 600;
+  color: #1a202c;
+  margin: 0 0 8px 0;
+}
+
+.selector-header p {
+  color: #718096;
+  margin: 0;
+}
+
+.custom-preview {
+  margin-top: 32px;
+  padding-top: 24px;
+  border-top: 1px solid #e5e7eb;
+}
+
+.custom-preview h4 {
+  font-size: 18px;
+  font-weight: 500;
+  color: #2d3748;
+  margin: 0 0 16px 0;
+}
+
+.preview-elements {
+  display: flex;
+  flex-direction: column;
+  gap: 16px;
+}
+
+.interactive-btn {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  padding: 12px 16px;
+  background: #f8fafc;
+  border: 1px solid #e2e8f0;
+  border-radius: 8px;
+  font-size: 14px;
+  font-weight: 500;
+  color: #374151;
+  cursor: pointer;
+  transition: all 0.2s ease;
+}
+
+.interactive-btn:hover {
+  background: #f1f5f9;
+  border-color: #cbd5e1;
+}
+
+.social-stats {
+  display: flex;
+  gap: 16px;
+}
+
+.stat-item {
+  display: flex;
+  align-items: center;
+  gap: 6px;
+  padding: 8px 12px;
+  background: #fef3c7;
+  border-radius: 6px;
+  font-size: 12px;
+  font-weight: 600;
+  color: #92400e;
+}
+
+.stat-item span {
+  font-size: 14px;
+}
+</style>
+```
+
+### Disabled State Example
+
+```vue
+<script setup lang="ts">
+import { ref } from "vue";
+import { IconPicker } from "@umbra-ui/core";
+import type { IconKey } from "@umbra-ui/icons";
+
+const selectedIcon = ref<IconKey>("home");
+const isDisabled = ref(false);
+
+const toggleDisabled = () => {
+  isDisabled.value = !isDisabled.value;
+};
+
+const handleIconChange = (icon: IconKey) => {
+  console.log("Icon changed to:", icon);
+};
+</script>
+
+<template>
+  <div class="disabled-example">
+    <h3>Disabled State</h3>
+
+    <div class="controls">
+      <button @click="toggleDisabled" class="toggle-btn">
+        {{ isDisabled ? "Enable" : "Disable" }} Icon Picker
+      </button>
+    </div>
+
+    <IconPicker
+      v-model:icon="selectedIcon"
+      :prevent-popup="isDisabled"
+      :icon-size="20"
+      @update:icon="handleIconChange"
+    />
+
+    <div class="status">
+      <p>Status: {{ isDisabled ? "Disabled" : "Enabled" }}</p>
+      <p>Selected: {{ selectedIcon || "None" }}</p>
+    </div>
+  </div>
+</template>
+
+<style module>
+.disabled-example {
+  padding: 24px;
+  max-width: 400px;
+}
+
+.controls {
+  margin-bottom: 20px;
+}
+
+.toggle-btn {
+  padding: 8px 16px;
+  background: #4299e1;
+  color: white;
+  border: none;
+  border-radius: 6px;
+  cursor: pointer;
+  font-weight: 500;
+  transition: background 0.2s ease;
+}
+
+.toggle-btn:hover {
+  background: #3182ce;
+}
+
+.status {
+  margin-top: 20px;
+  padding: 16px;
+  background: #f7fafc;
+  border-radius: 8px;
+}
+
+.status p {
+  margin: 0 0 8px 0;
+  color: #4a5568;
+}
+
+.status p:last-child {
+  margin-bottom: 0;
+}
+</style>
+```
+
+## Advanced Usage
+
+### Dynamic Icon Filtering
+
+```vue
+<script setup lang="ts">
+import { ref, computed } from "vue";
+import { IconPicker } from "@umbra-ui/core";
+import type { IconKey } from "@umbra-ui/icons";
+import { icons } from "@umbra-ui/icons";
+
+const searchQuery = ref("");
+const selectedIcon = ref<IconKey>("home");
+
+const allIcons = Object.keys(icons) as IconKey[];
+
+const filteredIcons = computed(() => {
+  if (!searchQuery.value) return allIcons;
+
+  return allIcons.filter((iconKey) =>
+    iconKey.toLowerCase().includes(searchQuery.value.toLowerCase())
+  );
+});
+
+const handleIconChange = (icon: IconKey) => {
+  selectedIcon.value = icon;
+  console.log("Selected icon:", icon);
+};
+
+const clearSearch = () => {
+  searchQuery.value = "";
+};
+</script>
+
+<template>
+  <div class="dynamic-filtering">
+    <h3>Dynamic Icon Filtering</h3>
+
+    <div class="search-section">
+      <div class="search-input">
+        <input
+          v-model="searchQuery"
+          type="text"
+          placeholder="Search icons..."
+          class="search-field"
+        />
+        <button @click="clearSearch" class="clear-btn">×</button>
+      </div>
+      <p class="search-results">{{ filteredIcons.length }} icons found</p>
+    </div>
+
+    <IconPicker
+      v-model:icon="selectedIcon"
+      :icon-list="filteredIcons"
+      :icon-size="18"
+      @update:icon="handleIconChange"
+    />
+
+    <div class="icon-info">
+      <h4>Selected Icon</h4>
+      <div class="icon-display">
+        <IconPicker
+          v-model:icon="selectedIcon"
+          :icon-list="filteredIcons"
+          :icon-size="32"
+          :prevent-popup="true"
+        />
+        <div class="icon-details">
+          <p class="icon-name">{{ selectedIcon }}</p>
+          <p class="icon-category">
+            Category: {{ getIconCategory(selectedIcon) }}
+          </p>
+        </div>
+      </div>
+    </div>
+  </div>
+</template>
+
+<style module>
+.dynamic-filtering {
+  padding: 24px;
+  max-width: 600px;
+}
+
+.search-section {
+  margin-bottom: 24px;
+}
+
+.search-input {
+  position: relative;
+  margin-bottom: 8px;
+}
+
+.search-field {
+  width: 100%;
+  padding: 12px 40px 12px 12px;
+  border: 1px solid #d1d5db;
+  border-radius: 6px;
+  font-size: 14px;
+  transition: border-color 0.2s ease;
+}
+
+.search-field:focus {
+  outline: none;
+  border-color: #3b82f6;
+  box-shadow: 0 0 0 3px rgba(59, 130, 246, 0.1);
+}
+
+.clear-btn {
+  position: absolute;
+  right: 8px;
+  top: 50%;
+  transform: translateY(-50%);
+  width: 24px;
+  height: 24px;
+  background: #6b7280;
+  color: white;
+  border: none;
+  border-radius: 50%;
+  font-size: 16px;
+  font-weight: bold;
+  cursor: pointer;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  transition: background 0.2s ease;
+}
+
+.clear-btn:hover {
+  background: #4b5563;
+}
+
+.search-results {
+  color: #6b7280;
+  font-size: 12px;
+  margin: 0;
+}
+
+.icon-info {
+  margin-top: 32px;
+  padding-top: 24px;
+  border-top: 1px solid #e5e7eb;
+}
+
+.icon-info h4 {
+  font-size: 18px;
+  font-weight: 500;
+  color: #2d3748;
+  margin: 0 0 16px 0;
+}
+
+.icon-display {
+  display: flex;
+  align-items: center;
+  gap: 16px;
+  padding: 20px;
+  background: #f9fafb;
+  border-radius: 8px;
+  border: 1px solid #e5e7eb;
+}
+
+.icon-details {
+  flex: 1;
+}
+
+.icon-name {
+  font-size: 16px;
+  font-weight: 600;
+  color: #374151;
+  margin: 0 0 4px 0;
+}
+
+.icon-category {
+  font-size: 14px;
+  color: #6b7280;
+  margin: 0;
+}
+</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 Filtering**: Efficient filtering of animated icons from the default list
+- **Computed Properties**: Reactive icon list computation for optimal performance
+
+## Accessibility
+
+- **Keyboard Navigation**: Support for keyboard interaction
+- **Screen Reader Support**: Proper ARIA labels and semantic structure
+- **Focus Management**: Focus is properly managed during interactions
+- **Icon Information**: Displays icon names for screen readers
+- **High Contrast**: Supports high contrast mode with appropriate styling
+
+## 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. **Icons not displaying**: Check that @umbra-ui/icons is properly installed
+2. **Picker not positioning correctly**: Ensure the trigger button has proper positioning context
+3. **Icon not updating**: Verify the v-model binding is correctly set up
+4. **Custom icon list not working**: Ensure the iconList prop contains valid IconKey values
+
+### Debug Mode
+
+```vue
+<script setup lang="ts">
+import { ref, watch } from "vue";
+import { IconPicker } from "@umbra-ui/core";
+
+const selectedIcon = ref("");
+
+// Watch for changes
+watch(selectedIcon, (newIcon) => {
+  console.log("Selected icon changed:", newIcon);
+});
+</script>
+```
+
+## Migration Guide
+
+### From v1 to v2
+
+- `v-model` prop is now `v-model:icon`
+- 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:icon`
+- Changed event names from camelCase to kebab-case
+- Updated icon prop to use string keys instead of components
+- Modified CSS class naming convention