@umbra.ui/core 0.2.0 → 0.4.0

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

@@ -1,759 +1,87 @@
-# Search Components
+# Search Overlay 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.
+Reusable search UI components that can be dropped into any app.
 
-## Installation/Import
+## Components
 
-```typescript
-import { SearchBar, SearchResults } from "@umbra-ui/core";
-import type { SearchResult } from "@umbra-ui/core";
-```
+- `SearchOverlay.vue`: Generic, Teleport-based search overlay with keyboard handling.
+- `SearchResultCell.vue`: Default result row renderer with highlighted matches and clickable path segments.
 
-**Dependencies:**
+## Quick Integration (AI Agent)
 
-- Vue 3.x
-- @umbra-ui/icons (for magnifier and chevron icons)
-- gsap (for animations)
-- @floating-ui/vue (for positioning)
+1. Render `SearchOverlay` in the view that should host search.
+2. Pass `modelValue`, `query`, `results`, and `activeIndex`.
+3. Use the `result` slot to render rows (use `SearchResultCell` or your own renderer).
+4. Handle emitted events to update state and selection.
 
-## Basic Usage
+### Example
 
 ```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"
+<SearchOverlay
+  :model-value="isOpen"
+  :query="query"
+  :results="results"
+  :active-index="activeIndex"
+  :show-recent="showRecent"
+  :search-label="searchLabel"
+  :results-label="resultsLabel"
+  :can-load-more="canLoadMore"
+  @update:model-value="(value) => (isOpen = value)"
+  @update:query="(value) => (query = value)"
+  @update:active-index="(value) => (activeIndex = value)"
+  @select="selectResult"
+  @load-more="loadMore"
+>
+  <template #result="{ result, query, isActive }">
+    <SearchResultCell
+      :result="result"
+      :query="query"
+      :is-active="isActive"
+      @segment-click="handleSegmentClick"
     />
-  </div>
-</template>
+  </template>
+</SearchOverlay>
 ```
 
-## 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
+## Props (SearchOverlay)
 
-| 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 |
+- `modelValue`: show/hide the overlay.
+- `query`: current input value.
+- `results`: array of `SearchOverlayResult`.
+- `activeIndex`: keyboard selection index.
+- `showRecent`: true to show the “Recent Searches” header.
+- `searchLabel`, `resultsLabel`: text for the header row.
+- `placeholder`: input placeholder text.
+- `recentEmptyLabel`, `resultsEmptyLabel`: empty state copy.
+- `canLoadMore`: shows the “Load More” button.
 
-### SearchResults
+## Events (SearchOverlay)
 
-The results display component (used internally by SearchBar).
+- `update:modelValue`
+- `update:query`
+- `update:activeIndex`
+- `select` (row click or enter key)
+- `load-more` (Load More button)
 
-#### Props
+## Result Shape
 
-| 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      |
+The overlay expects `SearchOverlayResult`:
 
-#### Events
-
-| Event Name | Payload Type   | Description                              |
-| ---------- | -------------- | ---------------------------------------- |
-| `onSelect` | `SearchResult` | Emitted when a search result is selected |
-
-## SearchResult Interface
-
-```typescript
-interface SearchResult {
+```ts
+type SearchOverlayResult = {
   id: string;
-  icon?: string;
+  path: string;
+  pathSegments: Array<{
+    id: string;
+    type: "workspace" | "notebook" | "note" | "collection";
+    title: 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;
+  excerpt: string;
 };
-</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: ReturnType<typeof setTimeout>;
-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
+## 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
+- The overlay scrolls to newly loaded results after `load-more`.
+- Path segments can be wired to navigation using `segment-click` on `SearchResultCell`.