feat(web): add search history navigation (task-3)

- Created useSearchHistory hook with IndexedDB persistence
- Added SearchHistoryDropdown component with history menu
- Integrated search history into SearchInterface
- Tracks up to 50 search queries with FIFO eviction
- Added idb package for IndexedDB helper
- Extended SPECIAL_LIST_IDS with SEARCH_HISTORY constant

Author: Mearman

apps/web/package.json

@@ -50,8 +50,10 @@
     "@vanilla-extract/recipes": "0.5.7",
     "@vanilla-extract/sprinkles": "1.6.5",
     "@xyflow/react": "12.10.0",
+    "clsx": "2.1.1",
     "date-fns": "4.1.0",
     "dexie": "4.2.1",
+    "idb": "8.0.3",
     "posthog-js": "1.318.1",
     "qrcode": "1.5.4",
     "r3f-forcegraph": "1.1.1",

apps/web/src/components/search/SearchHistoryDropdown.tsx

@@ -0,0 +1,135 @@
+/**
+ * Search History Dropdown Component
+ *
+ * Displays search history in a dropdown menu.
+ * Shows recent searches with ability to re-run or remove them.
+ */
+
+import { ActionIcon, Box, Group, Menu, Stack, Text, Tooltip, UnstyledButton } from '@mantine/core';
+import { IconClock, IconHistory, IconTrash, IconX } from '@tabler/icons-react';
+
+import { BORDER_STYLE_GRAY_3, ICON_SIZE } from '@/config/style-constants';
+import { useSearchHistory } from '@/hooks/useSearchHistory';
+
+interface SearchHistoryDropdownProps {
+  onSearchQuerySelect: (query: string) => void;
+}
+
+const MAX_DISPLAY_ITEMS = 10;
+
+export const SearchHistoryDropdown: React.FC<SearchHistoryDropdownProps> = ({
+  onSearchQuerySelect,
+}) => {
+  const { searchHistory, removeSearchQuery, clearSearchHistory } = useSearchHistory();
+  const displayHistory = searchHistory.slice(0, MAX_DISPLAY_ITEMS);
+
+  const handleRemoveQuery = async (id: string, event: React.MouseEvent) => {
+    event.stopPropagation();
+    await removeSearchQuery(id);
+  };
+
+  const handleClearAll = async () => {
+    await clearSearchHistory();
+  };
+
+  if (searchHistory.length === 0) {
+    return null;
+  }
+
+  return (
+    <Menu position="bottom-end" shadow="md" width={300} withinPortal>
+      <Menu.Target>
+        <Tooltip label="Search history" withinPortal>
+          <ActionIcon variant="subtle" size="input-lg">
+            <IconHistory size={ICON_SIZE.MD} />
+          </ActionIcon>
+        </Tooltip>
+      </Menu.Target>
+
+      <Menu.Dropdown>
+        <Stack gap="xs">
+          {/* Header */}
+          <Group justify="space-between" align="center" px="xs">
+            <Group gap="xs" align="center">
+              <IconClock size={ICON_SIZE.SM} />
+              <Text size="sm" fw={500}>
+                Recent Searches
+              </Text>
+            </Group>
+
+            {searchHistory.length > 0 && (
+              <Tooltip label="Clear all history" withinPortal>
+                <ActionIcon
+                  variant="subtle"
+                  color="red"
+                  size="sm"
+                  onClick={handleClearAll}
+                >
+                  <IconTrash size={ICON_SIZE.XS} />
+                </ActionIcon>
+              </Tooltip>
+            )}
+          </Group>
+
+          {/* History Items */}
+          {displayHistory.length === 0 ? (
+            <Text size="sm" c="dimmed" ta="center" py="md">
+              No search history yet
+            </Text>
+          ) : (
+            <Stack gap={2}>
+              {displayHistory.map((entry) => (
+                <UnstyledButton
+                  key={entry.id}
+                  onClick={() => onSearchQuerySelect(entry.query)}
+                  py="xs"
+                  px="sm"
+                  style={{
+                    borderRadius: '4px',
+                    transition: 'background-color 150ms ease',
+                  }}
+                  onMouseEnter={(e) => {
+                    e.currentTarget.style.backgroundColor = 'light-dark(var(--mantine-color-gray-1), var(--mantine-color-dark-8))';
+                  }}
+                  onMouseLeave={(e) => {
+                    e.currentTarget.style.backgroundColor = 'transparent';
+                  }}
+                >
+                  <Group justify="space-between" align="center" wrap="nowrap">
+                    <Text
+                      size="sm"
+                      style={{
+                        overflow: 'hidden',
+                        textOverflow: 'ellipsis',
+                        whiteSpace: 'nowrap',
+                        flex: 1,
+                      }}
+                    >
+                      {entry.query}
+                    </Text>
+
+                    <ActionIcon
+                      variant="transparent"
+                      color="gray"
+                      size="xs"
+                      onClick={(e) => void handleRemoveQuery(entry.id, e)}
+                    >
+                      <IconX size={ICON_SIZE.XS} />
+                    </ActionIcon>
+                  </Group>
+                </UnstyledButton>
+              ))}
+            </Stack>
+          )}
+
+          {/* Footer */}
+          {searchHistory.length > MAX_DISPLAY_ITEMS && (
+            <Text size="xs" c="dimmed" ta="center" py="xs">
+              Showing {MAX_DISPLAY_ITEMS} of {searchHistory.length} searches
+            </Text>
+          )}
+        </Stack>
+      </Menu.Dropdown>
+    </Menu>
+  );
+};

apps/web/src/components/search/SearchInterface.tsx

@@ -6,8 +6,10 @@ import { useCallback, useEffect, useRef, useState } from "react";
 
 import { BORDER_STYLE_GRAY_3, ICON_SIZE } from "@/config/style-constants";
 import { useSearchHotkeys } from "@/hooks/use-hotkeys";
+import { useSearchHistory } from "@/hooks/useSearchHistory";
 import { announceToScreenReader } from "@/utils/accessibility";
 
+import { SearchHistoryDropdown } from "./SearchHistoryDropdown";
 import { AdvancedSearchFilters,SearchFilters } from "./SearchFilters";
 
 interface SearchFilters {
@@ -35,6 +37,7 @@ export const SearchInterface = ({
   const [searchTip, setSearchTip] = useState("");
   const [advancedFilters, setAdvancedFilters] = useState<AdvancedSearchFilters>({});
   const [showFilters, setShowFilters] = useState(false);
+  const { addSearchQuery } = useSearchHistory();
 
   // Set up keyboard shortcuts for search
   useSearchHotkeys(
@@ -48,13 +51,14 @@ export const SearchInterface = ({
       advanced: showFilters && Object.keys(advancedFilters).length > 0 ? advancedFilters : undefined,
     };
 
-    // Announce search to screen readers
+    // Add to search history
     if (filters.query) {
+      void addSearchQuery(filters.query);
       announceToScreenReader(`Searching for: ${filters.query}`);
     }
 
     onSearch(filters);
-  }, [query, advancedFilters, showFilters, onSearch]);
+  }, [query, advancedFilters, showFilters, onSearch, addSearchQuery]);
 
   const handleQueryChange = useCallback((value: string) => {
     setQuery(value);
@@ -65,10 +69,20 @@ export const SearchInterface = ({
           query: normalizeSearchQuery(value),
           advanced: showFilters && Object.keys(advancedFilters).length > 0 ? advancedFilters : undefined,
         };
+        // Add to search history for debounced searches too
+        void addSearchQuery(filters.query);
         onSearch(filters);
       }, value);
     }
-  }, [onSearch, advancedFilters, showFilters]);
+  }, [onSearch, advancedFilters, showFilters, addSearchQuery]);
+
+  const handleHistoryQuerySelect = useCallback((selectedQuery: string) => {
+    setQuery(selectedQuery);
+    handleQueryChange(selectedQuery);
+    if (searchInputRef.current) {
+      searchInputRef.current.focus();
+    }
+  }, [handleQueryChange]);
 
   const handleFiltersChange = useCallback((filters: AdvancedSearchFilters) => {
     setAdvancedFilters(filters);
@@ -251,6 +265,7 @@ export const SearchInterface = ({
           >
             Search
           </Button>
+          <SearchHistoryDropdown onSearchQuerySelect={handleHistoryQuerySelect} />
         </Group>
 
         {/* Search Status */}

apps/web/src/hooks/useSearchHistory.ts

@@ -0,0 +1,149 @@
+/**
+ * Search History Hook
+ *
+ * Manages search query history with IndexedDB persistence.
+ * Stores up to 50 search queries with FIFO eviction.
+ */
+
+import { openDB } from 'idb';
+import { useCallback, useEffect, useState } from 'react';
+
+import { logger } from '@bibgraph/utils';
+
+const SEARCH_HISTORY_DB_NAME = 'bibgraph-search-history';
+const SEARCH_HISTORY_STORE_NAME = 'queries';
+const SEARCH_HISTORY_VERSION = 1;
+const MAX_SEARCH_HISTORY = 50;
+
+interface SearchHistoryEntry {
+  id: string;
+  query: string;
+  timestamp: Date;
+}
+
+interface SearchHistoryDB {
+  [SEARCH_HISTORY_STORE_NAME]: {
+    key: string;
+    value: SearchHistoryEntry;
+  };
+}
+
+const initializeDB = async () => {
+  return openDB<SearchHistoryDB>(SEARCH_HISTORY_DB_NAME, SEARCH_HISTORY_VERSION, {
+    upgrade(db) {
+      if (!db.objectStoreNames.contains(SEARCH_HISTORY_STORE_NAME)) {
+        const store = db.createObjectStore(SEARCH_HISTORY_STORE_NAME, {
+          keyPath: 'id',
+        });
+        store.createIndex('timestamp', 'timestamp');
+      }
+    },
+  });
+};
+
+export const useSearchHistory = () => {
+  const [searchHistory, setSearchHistory] = useState<SearchHistoryEntry[]>([]);
+  const [isInitialized, setIsInitialized] = useState(false);
+
+  // Initialize IndexedDB and load history
+  useEffect(() => {
+    const init = async () => {
+      try {
+        const db = await initializeDB();
+        const allEntries = await db.getAll(SEARCH_HISTORY_STORE_NAME);
+        const sortedEntries = allEntries
+          .sort((a, b) => b.timestamp.getTime() - a.timestamp.getTime())
+          .slice(0, MAX_SEARCH_HISTORY);
+        setSearchHistory(sortedEntries);
+        setIsInitialized(true);
+      } catch (error) {
+        logger.error('search-history', 'Failed to initialize search history', { error });
+        setIsInitialized(true);
+      }
+    };
+
+    void init();
+  }, []);
+
+  const addSearchQuery = useCallback(
+    async (query: string) => {
+      if (!query.trim()) return;
+
+      try {
+        const db = await initializeDB();
+
+        // Create new entry
+        const entry: SearchHistoryEntry = {
+          id: crypto.randomUUID(),
+          query: query.trim(),
+          timestamp: new Date(),
+        };
+
+        // Add to database
+        await db.put(SEARCH_HISTORY_STORE_NAME, entry);
+
+        // Get all entries and enforce FIFO eviction
+        const allEntries = await db.getAll(SEARCH_HISTORY_STORE_NAME);
+        if (allEntries.length > MAX_SEARCH_HISTORY) {
+          // Sort by timestamp (oldest first)
+          const sortedEntries = [...allEntries].sort(
+            (a, b) => a.timestamp.getTime() - b.timestamp.getTime(),
+          );
+
+          // Remove oldest entries
+          const entriesToRemove = sortedEntries.slice(0, allEntries.length - MAX_SEARCH_HISTORY);
+          for (const entry of entriesToRemove) {
+            await db.delete(SEARCH_HISTORY_STORE_NAME, entry.id);
+          }
+        }
+
+        // Update state
+        const updatedHistory = await db.getAll(SEARCH_HISTORY_STORE_NAME);
+        const sortedHistory = updatedHistory
+          .sort((a, b) => b.timestamp.getTime() - a.timestamp.getTime())
+          .slice(0, MAX_SEARCH_HISTORY);
+        setSearchHistory(sortedHistory);
+
+        logger.debug('search-history', 'Added search query to history', { query });
+      } catch (error) {
+        logger.error('search-history', 'Failed to add search query to history', { error, query });
+      }
+    },
+    [],
+  );
+
+  const removeSearchQuery = useCallback(async (id: string) => {
+    try {
+      const db = await initializeDB();
+      await db.delete(SEARCH_HISTORY_STORE_NAME, id);
+
+      // Update state
+      const updatedHistory = searchHistory.filter((entry) => entry.id !== id);
+      setSearchHistory(updatedHistory);
+
+      logger.debug('search-history', 'Removed search query from history', { id });
+    } catch (error) {
+      logger.error('search-history', 'Failed to remove search query from history', { error, id });
+    }
+  }, [searchHistory]);
+
+  const clearSearchHistory = useCallback(async () => {
+    try {
+      const db = await initializeDB();
+      await db.clear(SEARCH_HISTORY_STORE_NAME);
+      setSearchHistory([]);
+
+      logger.debug('search-history', 'Cleared search history');
+    } catch (error) {
+      logger.error('search-history', 'Failed to clear search history', { error });
+    }
+  }, []);
+
+  return {
+    searchHistory: isInitialized ? searchHistory : [],
+    addSearchQuery,
+    removeSearchQuery,
+    clearSearchHistory,
+    isInitialized,
+  };
+};

packages/utils/src/storage/catalogue-db.ts

@@ -61,6 +61,7 @@ export const SPECIAL_LIST_IDS = {
   BOOKMARKS: "bookmarks-list",
   HISTORY: "history-list",
   GRAPH: "graph-list",
+  SEARCH_HISTORY: "search-history",
 } as const;
 
 export const SPECIAL_LIST_TYPES = {