@umbra.ui/core 0.1.0

package/src/components/inputs/search/README.md

@@ -0,0 +1,759 @@
+# Search Components
+
+A comprehensive search system built with Vue 3 Composition API and TypeScript. The search components provide a powerful search interface with real-time filtering, animated results display, and advanced features like pagination, highlighting, and keyboard navigation.
+
+## Installation/Import
+
+```typescript
+import { SearchBar, SearchResults } from "@umbra-ui/core";
+import type { SearchResult } from "@umbra-ui/core";
+```
+
+**Dependencies:**
+
+- Vue 3.x
+- @umbra-ui/icons (for magnifier and chevron icons)
+- gsap (for animations)
+- @floating-ui/vue (for positioning)
+
+## Basic Usage
+
+```vue
+<script setup lang="ts">
+import { ref } from "vue";
+import { SearchBar, SearchResults } from "@umbra-ui/core";
+import type { SearchResult } from "@umbra-ui/core";
+
+const searchQuery = ref("");
+const searchItems = ref<SearchResult[]>([
+  {
+    id: "1",
+    title: "Example Item",
+    description: "This is an example search result",
+    caption: "Category",
+    footnote: "Tag",
+    icon: "📄",
+  },
+]);
+
+const handleSearchSelect = (result: SearchResult) => {
+  console.log("Selected:", result);
+  searchQuery.value = result.title;
+};
+
+const handleSearchFocus = () => {
+  console.log("Search focused");
+};
+</script>
+
+<template>
+  <div>
+    <SearchBar
+      v-model:query="searchQuery"
+      :items="searchItems"
+      type="documents"
+      placeholder="Search documents..."
+      @onSelect="handleSearchSelect"
+      @onFocus="handleSearchFocus"
+    />
+  </div>
+</template>
+```
+
+## Components
+
+### SearchBar
+
+The main search input component with dropdown results.
+
+#### Props
+
+| Prop Name     | Type             | Required | Default    | Description                                |
+| ------------- | ---------------- | -------- | ---------- | ------------------------------------------ |
+| `type`        | `string`         | No       | `"items"`  | Type of items being searched (for display) |
+| `query`       | `string`         | No       | `""`       | The search query value                     |
+| `items`       | `SearchResult[]` | No       | `[]`       | Array of searchable items                  |
+| `placeholder` | `string`         | No       | `"Search"` | Placeholder text for the search input      |
+
+#### Events
+
+| Event Name     | Payload Type   | Description                                  |
+| -------------- | -------------- | -------------------------------------------- |
+| `update:query` | `string`       | Emitted when the search query changes        |
+| `onSelect`     | `SearchResult` | Emitted when a search result is selected     |
+| `onFocus`      | `void`         | Emitted when the search input receives focus |
+
+### SearchResults
+
+The results display component (used internally by SearchBar).
+
+#### Props
+
+| Prop Name | Type             | Required | Description                  |
+| --------- | ---------------- | -------- | ---------------------------- |
+| `type`    | `string`         | Yes      | Type of items being searched |
+| `query`   | `string`         | Yes      | Current search query         |
+| `matches` | `SearchResult[]` | Yes      | Filtered search results      |
+
+#### Events
+
+| Event Name | Payload Type   | Description                              |
+| ---------- | -------------- | ---------------------------------------- |
+| `onSelect` | `SearchResult` | Emitted when a search result is selected |
+
+## SearchResult Interface
+
+```typescript
+interface SearchResult {
+  id: string;
+  icon?: string;
+  title: string;
+  description: string;
+  caption: string;
+  footnote: string;
+}
+```
+
+## CSS Customization
+
+The search components use CSS custom properties for theming and customization:
+
+### SearchBar Variables
+
+```css
+/* Search Bar Colors */
+--search-bar-bg: var(--search-bar-background);
+--search-bar-text: var(--search-bar-text-color);
+--search-bar-placeholder: var(--search-bar-placeholder-color);
+--search-bar-border: var(--search-bar-border-color);
+--search-bar-focus-border: var(--search-bar-focus-border-color);
+--search-bar-shadow: var(--search-bar-shadow-color);
+--search-bar-inset-shadow: var(--search-bar-inset-shadow-color);
+
+/* Search Overlay */
+--search-overlay-bg: var(--search-overlay-background);
+```
+
+### SearchResults Variables
+
+```css
+/* Results Container */
+--search-results-bg: var(--search-results-background);
+--search-results-border: var(--search-results-border-color);
+--search-results-shadow: var(--search-results-shadow-color);
+--search-results-inset-shadow: var(--search-results-inset-shadow-color);
+
+/* Subheader */
+--search-subheader-bg: var(--search-subheader-background);
+--search-subheader-border: var(--search-subheader-border-color);
+--search-subheader-text: var(--search-subheader-text-color);
+
+/* Result Items */
+--search-result-bg: var(--search-result-background);
+--search-result-hover-bg: var(--search-result-hover-background);
+--search-result-border: var(--search-result-border-color);
+--search-result-text: var(--search-result-text-color);
+
+/* Icons */
+--search-icon-bg: var(--search-icon-background);
+--search-icon-border: var(--search-icon-border-color);
+
+/* Footnotes */
+--search-footnote-bg: var(--search-footnote-background);
+
+/* Empty State */
+--search-nothing-text: var(--search-nothing-text-color);
+
+/* Load More */
+--search-load-more-bg: var(--search-load-more-background);
+--search-load-more-hover-bg: var(--search-load-more-hover-background);
+--search-load-more-text: var(--search-load-more-text-color);
+
+/* Highlighting */
+--search-highlight-bg: var(--search-highlight-background);
+```
+
+## Key Features
+
+### Search Functionality
+
+- **Real-time Filtering**: Results update as you type
+- **Multi-field Search**: Searches across title, description, caption, and footnote
+- **Case-insensitive**: Search is not case-sensitive
+- **Highlighting**: Query terms are highlighted in results
+
+### User Experience
+
+- **Animated Dropdown**: Smooth animations for showing/hiding results
+- **Floating Positioning**: Results are positioned using Floating UI
+- **Keyboard Navigation**: Full keyboard support with escape to close
+- **Click Outside**: Clicking outside closes the search results
+- **Loading States**: Shows loading indicator while building search index
+
+### Results Display
+
+- **Pagination**: Load more results with pagination
+- **Rich Content**: Support for icons, titles, descriptions, captions, and footnotes
+- **Icon Support**: Both emoji and image icons
+- **Hover Effects**: Visual feedback on result hover
+- **Empty States**: Proper handling of no results
+
+### Accessibility
+
+- **ARIA Labels**: Proper labeling for screen readers
+- **Keyboard Navigation**: Full keyboard support
+- **Focus Management**: Proper focus handling
+- **Screen Reader Support**: Accessible result announcements
+
+## Examples
+
+### Basic Search
+
+```vue
+<script setup lang="ts">
+import { ref } from "vue";
+import { SearchBar } from "@umbra-ui/core";
+import type { SearchResult } from "@umbra-ui/core";
+
+const searchQuery = ref("");
+const searchItems = ref<SearchResult[]>([
+  {
+    id: "1",
+    title: "Getting Started Guide",
+    description: "Learn how to get started with our platform",
+    caption: "Documentation",
+    footnote: "Guide",
+    icon: "📚",
+  },
+  {
+    id: "2",
+    title: "API Reference",
+    description: "Complete API documentation and examples",
+    caption: "Documentation",
+    footnote: "API",
+    icon: "🔧",
+  },
+  {
+    id: "3",
+    title: "User Manual",
+    description: "Detailed user manual with step-by-step instructions",
+    caption: "Documentation",
+    footnote: "Manual",
+    icon: "📖",
+  },
+]);
+
+const handleSearchSelect = (result: SearchResult) => {
+  console.log("Selected:", result);
+  searchQuery.value = result.title;
+};
+</script>
+
+<template>
+  <div class="basic-search">
+    <h3>Documentation Search</h3>
+
+    <SearchBar
+      v-model:query="searchQuery"
+      :items="searchItems"
+      type="documents"
+      placeholder="Search documentation..."
+      @onSelect="handleSearchSelect"
+    />
+
+    <div v-if="searchQuery" class="search-info">
+      <p>Searching for: "{{ searchQuery }}"</p>
+    </div>
+  </div>
+</template>
+
+<style module>
+.basic-search {
+  max-width: 500px;
+  padding: 2rem;
+  border: 1px solid #e0e0e0;
+  border-radius: 0.5rem;
+}
+
+.search-info {
+  margin-top: 1rem;
+  padding: 1rem;
+  background-color: #f8f9fa;
+  border-radius: 0.25rem;
+}
+
+.search-info p {
+  margin: 0;
+  color: #666;
+  font-size: 0.875rem;
+}
+</style>
+```
+
+### Advanced Search with Custom Data
+
+```vue
+<script setup lang="ts">
+import { ref, computed } from "vue";
+import { SearchBar } from "@umbra-ui/core";
+import type { SearchResult } from "@umbra-ui/core";
+
+const searchQuery = ref("");
+const allItems = ref<SearchResult[]>([
+  {
+    id: "1",
+    title: "Vue.js Framework",
+    description:
+      "Progressive JavaScript framework for building user interfaces",
+    caption: "Framework",
+    footnote: "JavaScript",
+    icon: "🟢",
+  },
+  {
+    id: "2",
+    title: "React Library",
+    description: "A JavaScript library for building user interfaces",
+    caption: "Library",
+    footnote: "JavaScript",
+    icon: "⚛️",
+  },
+  {
+    id: "3",
+    title: "Angular Platform",
+    description: "Platform for building mobile and desktop web applications",
+    caption: "Platform",
+    footnote: "TypeScript",
+    icon: "🔴",
+  },
+  {
+    id: "4",
+    title: "Svelte Compiler",
+    description:
+      "Cybernetically enhanced web apps with compile-time optimizations",
+    caption: "Compiler",
+    footnote: "JavaScript",
+    icon: "🧡",
+  },
+]);
+
+const filteredItems = computed(() => {
+  if (!searchQuery.value.trim()) {
+    return allItems.value;
+  }
+
+  const query = searchQuery.value.toLowerCase();
+  return allItems.value.filter((item) => {
+    const searchText =
+      `${item.title} ${item.description} ${item.caption} ${item.footnote}`.toLowerCase();
+    return searchText.includes(query);
+  });
+});
+
+const handleSearchSelect = (result: SearchResult) => {
+  console.log("Selected framework:", result);
+  searchQuery.value = result.title;
+};
+
+const handleSearchFocus = () => {
+  console.log("Search focused - showing all items");
+};
+</script>
+
+<template>
+  <div class="advanced-search">
+    <h3>Framework Search</h3>
+
+    <SearchBar
+      v-model:query="searchQuery"
+      :items="filteredItems"
+      type="frameworks"
+      placeholder="Search JavaScript frameworks..."
+      @onSelect="handleSearchSelect"
+      @onFocus="handleSearchFocus"
+    />
+
+    <div class="search-stats">
+      <p>Total items: {{ allItems.length }}</p>
+      <p v-if="searchQuery">Filtered results: {{ filteredItems.length }}</p>
+    </div>
+  </div>
+</template>
+
+<style module>
+.advanced-search {
+  max-width: 600px;
+  padding: 2rem;
+  border: 1px solid #e0e0e0;
+  border-radius: 0.5rem;
+}
+
+.search-stats {
+  margin-top: 1rem;
+  padding: 1rem;
+  background-color: #f8f9fa;
+  border-radius: 0.25rem;
+  display: flex;
+  gap: 2rem;
+}
+
+.search-stats p {
+  margin: 0;
+  color: #666;
+  font-size: 0.875rem;
+}
+</style>
+```
+
+### Search with API Integration
+
+```vue
+<script setup lang="ts">
+import { ref, watch } from "vue";
+import { SearchBar } from "@umbra-ui/core";
+import type { SearchResult } from "@umbra-ui/core";
+
+const searchQuery = ref("");
+const searchItems = ref<SearchResult[]>([]);
+const isLoading = ref(false);
+const error = ref("");
+
+const searchAPI = async (query: string) => {
+  if (!query.trim()) {
+    searchItems.value = [];
+    return;
+  }
+
+  isLoading.value = true;
+  error.value = "";
+
+  try {
+    // Simulate API call
+    await new Promise((resolve) => setTimeout(resolve, 1000));
+
+    // Simulate API response
+    const mockResults: SearchResult[] = [
+      {
+        id: "1",
+        title: `Search Result for "${query}"`,
+        description: `This is a mock result for the query "${query}"`,
+        caption: "API Result",
+        footnote: "Mock",
+        icon: "🔍",
+      },
+      {
+        id: "2",
+        title: `Another Result for "${query}"`,
+        description: `Another mock result for the query "${query}"`,
+        caption: "API Result",
+        footnote: "Mock",
+        icon: "📄",
+      },
+    ];
+
+    searchItems.value = mockResults;
+  } catch (err) {
+    error.value = "Failed to search. Please try again.";
+    searchItems.value = [];
+  } finally {
+    isLoading.value = false;
+  }
+};
+
+// Debounced search
+let searchTimeout: NodeJS.Timeout;
+watch(searchQuery, (newQuery) => {
+  clearTimeout(searchTimeout);
+  searchTimeout = setTimeout(() => {
+    searchAPI(newQuery);
+  }, 300);
+});
+
+const handleSearchSelect = (result: SearchResult) => {
+  console.log("Selected from API:", result);
+  searchQuery.value = result.title;
+};
+</script>
+
+<template>
+  <div class="api-search">
+    <h3>API-Powered Search</h3>
+
+    <SearchBar
+      v-model:query="searchQuery"
+      :items="searchItems"
+      type="api-results"
+      placeholder="Search with API..."
+      @onSelect="handleSearchSelect"
+    />
+
+    <div v-if="isLoading" class="loading-state">
+      <p>Searching...</p>
+    </div>
+
+    <div v-if="error" class="error-state">
+      <p>{{ error }}</p>
+    </div>
+
+    <div v-if="searchQuery && !isLoading && !error" class="search-info">
+      <p>Found {{ searchItems.length }} results for "{{ searchQuery }}"</p>
+    </div>
+  </div>
+</template>
+
+<style module>
+.api-search {
+  max-width: 500px;
+  padding: 2rem;
+  border: 1px solid #e0e0e0;
+  border-radius: 0.5rem;
+}
+
+.loading-state {
+  margin-top: 1rem;
+  padding: 1rem;
+  background-color: #e3f2fd;
+  border-radius: 0.25rem;
+  text-align: center;
+}
+
+.loading-state p {
+  margin: 0;
+  color: #1976d2;
+  font-weight: 500;
+}
+
+.error-state {
+  margin-top: 1rem;
+  padding: 1rem;
+  background-color: #ffebee;
+  border-radius: 0.25rem;
+  text-align: center;
+}
+
+.error-state p {
+  margin: 0;
+  color: #d32f2f;
+  font-weight: 500;
+}
+
+.search-info {
+  margin-top: 1rem;
+  padding: 1rem;
+  background-color: #f8f9fa;
+  border-radius: 0.25rem;
+}
+
+.search-info p {
+  margin: 0;
+  color: #666;
+  font-size: 0.875rem;
+}
+</style>
+```
+
+### Search with Custom Styling
+
+```vue
+<script setup lang="ts">
+import { ref } from "vue";
+import { SearchBar } from "@umbra-ui/core";
+import type { SearchResult } from "@umbra-ui/core";
+
+const searchQuery = ref("");
+const searchItems = ref<SearchResult[]>([
+  {
+    id: "1",
+    title: "Custom Styled Search",
+    description: "This search has custom styling applied",
+    caption: "Custom",
+    footnote: "Styled",
+    icon: "🎨",
+  },
+  {
+    id: "2",
+    title: "Themed Results",
+    description: "Results with custom theme colors",
+    caption: "Theme",
+    footnote: "Custom",
+    icon: "🌈",
+  },
+]);
+
+const handleSearchSelect = (result: SearchResult) => {
+  console.log("Selected:", result);
+  searchQuery.value = result.title;
+};
+</script>
+
+<template>
+  <div class="custom-search">
+    <h3>Custom Styled Search</h3>
+
+    <SearchBar
+      v-model:query="searchQuery"
+      :items="searchItems"
+      type="custom-items"
+      placeholder="Search with custom styling..."
+      @onSelect="handleSearchSelect"
+    />
+  </div>
+</template>
+
+<style module>
+.custom-search {
+  max-width: 500px;
+  padding: 2rem;
+  border: 1px solid #e0e0e0;
+  border-radius: 0.5rem;
+}
+
+/* Custom CSS variables for theming */
+.custom-search {
+  --search-bar-bg: #f8f9fa;
+  --search-bar-text: #495057;
+  --search-bar-placeholder: #6c757d;
+  --search-bar-border: 2px solid #dee2e6;
+  --search-bar-focus-border: #007bff;
+
+  --search-results-bg: #ffffff;
+  --search-results-border: 1px solid #dee2e6;
+  --search-results-shadow: 0 0.5rem 1rem rgba(0, 0, 0, 0.15);
+
+  --search-subheader-bg: #e9ecef;
+  --search-subheader-text: #495057;
+
+  --search-result-bg: #ffffff;
+  --search-result-hover-bg: #f8f9fa;
+  --search-result-text: #212529;
+
+  --search-icon-bg: #e9ecef;
+  --search-icon-border: #dee2e6;
+
+  --search-highlight-bg: rgba(255, 193, 7, 0.3);
+  --search-overlay-bg: rgba(0, 0, 0, 0.5);
+}
+</style>
+```
+
+### Search with Keyboard Shortcuts
+
+```vue
+<script setup lang="ts">
+import { ref, onMounted, onUnmounted } from "vue";
+import { SearchBar } from "@umbra-ui/core";
+import type { SearchResult } from "@umbra-ui/core";
+
+const searchQuery = ref("");
+const searchItems = ref<SearchResult[]>([
+  {
+    id: "1",
+    title: "Keyboard Shortcuts",
+    description: "Learn about keyboard shortcuts in our application",
+    caption: "Help",
+    footnote: "Shortcuts",
+    icon: "⌨️",
+  },
+  {
+    id: "2",
+    title: "Search Tips",
+    description: "Tips and tricks for better search results",
+    caption: "Help",
+    footnote: "Tips",
+    icon: "💡",
+  },
+]);
+
+const searchBarRef = ref();
+
+const handleKeyDown = (event: KeyboardEvent) => {
+  // Ctrl/Cmd + K to focus search
+  if ((event.ctrlKey || event.metaKey) && event.key === "k") {
+    event.preventDefault();
+    searchBarRef.value?.focus();
+  }
+
+  // Escape to clear search
+  if (event.key === "Escape" && searchQuery.value) {
+    searchQuery.value = "";
+  }
+};
+
+onMounted(() => {
+  document.addEventListener("keydown", handleKeyDown);
+});
+
+onUnmounted(() => {
+  document.removeEventListener("keydown", handleKeyDown);
+});
+
+const handleSearchSelect = (result: SearchResult) => {
+  console.log("Selected:", result);
+  searchQuery.value = result.title;
+};
+</script>
+
+<template>
+  <div class="keyboard-search">
+    <h3>Search with Keyboard Shortcuts</h3>
+
+    <div class="shortcuts-info">
+      <p><kbd>Ctrl</kbd> + <kbd>K</kbd> to focus search</p>
+      <p><kbd>Escape</kbd> to clear search</p>
+    </div>
+
+    <SearchBar
+      ref="searchBarRef"
+      v-model:query="searchQuery"
+      :items="searchItems"
+      type="help-items"
+      placeholder="Search help articles..."
+      @onSelect="handleSearchSelect"
+    />
+  </div>
+</template>
+
+<style module>
+.keyboard-search {
+  max-width: 500px;
+  padding: 2rem;
+  border: 1px solid #e0e0e0;
+  border-radius: 0.5rem;
+}
+
+.shortcuts-info {
+  margin-bottom: 1rem;
+  padding: 1rem;
+  background-color: #f8f9fa;
+  border-radius: 0.25rem;
+}
+
+.shortcuts-info p {
+  margin: 0.25rem 0;
+  color: #666;
+  font-size: 0.875rem;
+}
+
+kbd {
+  background-color: #f8f9fa;
+  border: 1px solid #dee2e6;
+  border-radius: 0.25rem;
+  padding: 0.125rem 0.25rem;
+  font-size: 0.75rem;
+  font-family: monospace;
+}
+</style>
+```
+
+## Technical Notes
+
+- Search components provide a comprehensive search interface with real-time filtering
+- Floating UI is used for precise positioning of search results
+- GSAP animations provide smooth transitions for showing/hiding results
+- Search results support pagination with "Load More" functionality
+- Query highlighting uses regex to highlight matching terms in results
+- Keyboard navigation includes escape to close and full arrow key support
+- Click outside functionality closes the search results
+- Responsive design adapts to different screen sizes
+- CSS custom properties enable easy theming for light and dark modes
+- TypeScript interfaces ensure type safety for search results
+- Accessibility features include ARIA labels and screen reader support