feat: add fuzzy search with fuse.js and spec title search

MarkusNeusinger · claude · MarkusNeusinger · commit f23c6ae568bc · 2026-01-14T23:51:09.000+01:00
- Add fuse.js for typo-tolerant fuzzy matching (threshold: 0.3) - Enable extended search for multi-word AND queries - Search spec titles in addition to spec_id - Show spec title as tooltip in dropdown - Add "fuzzy" divider label between exact and fuzzy matches - Add specTitles mapping to API response Closes #3828 Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
diff --git a/api/routers/plots.py b/api/routers/plots.py
@@ -484,13 +484,17 @@ async def get_filtered_plots(request: Request, db: AsyncSession = Depends(requir
     counts = _calculate_contextual_counts(filtered_images, spec_id_to_tags, impl_lookup)
     or_counts = _calculate_or_counts(filter_groups, all_images, spec_id_to_tags, spec_lookup, impl_lookup)
 
+    # Build spec_id -> title mapping for search/tooltips
+    spec_titles = {spec_id: data["spec"].title for spec_id, data in spec_lookup.items() if data["spec"].title}
+
     # Build and cache response
     result = FilteredPlotsResponse(
         total=len(filtered_images),
         images=filtered_images,
         counts=counts,
         globalCounts=global_counts,
         orCounts=or_counts,
+        specTitles=spec_titles,
     )
 
     try:
diff --git a/api/schemas.py b/api/schemas.py
@@ -97,6 +97,7 @@ class FilteredPlotsResponse(BaseModel):
     counts: dict
     globalCounts: dict
     orCounts: list[dict]
+    specTitles: dict[str, str] = {}  # Mapping spec_id -> title for search/tooltips
 
 
 class LibraryInfo(BaseModel):
diff --git a/app/package.json b/app/package.json
@@ -20,6 +20,7 @@
     "@emotion/styled": "^11.14.1",
     "@mui/icons-material": "^7.3.7",
     "@mui/material": "^7.3.7",
+    "fuse.js": "^7.1.0",
     "react": "^19.2.3",
     "react-dom": "^19.2.3",
     "react-helmet-async": "^2.0.5",
diff --git a/app/src/components/FilterBar.tsx b/app/src/components/FilterBar.tsx
@@ -21,12 +21,13 @@ import { useTheme } from '@mui/material/styles';
 import type { FilterCategory, ActiveFilters, FilterCounts } from '../types';
 import { FILTER_LABELS, FILTER_TOOLTIPS, FILTER_CATEGORIES } from '../types';
 import type { ImageSize } from '../constants';
-import { getAvailableValues, getAvailableValuesForGroup, getSearchResults } from '../utils';
+import { getAvailableValues, getAvailableValuesForGroup, getSearchResults, type SearchResult } from '../utils';
 
 interface FilterBarProps {
   activeFilters: ActiveFilters;
   filterCounts: FilterCounts | null;  // Contextual counts (for AND additions)
   orCounts: Record<string, number>[];  // Per-group counts for OR additions
+  specTitles: Record<string, string>;  // Mapping spec_id -> title for search/tooltips
   currentTotal: number;  // Total number of filtered images
   displayedCount: number;  // Currently displayed images
   randomAnimation: { index: number; phase: 'out' | 'in'; oldLabel?: string } | null;
@@ -44,6 +45,7 @@ export function FilterBar({
   activeFilters,
   filterCounts,
   orCounts,
+  specTitles,
   currentTotal,
   displayedCount,
   randomAnimation,
@@ -208,8 +210,8 @@ export function FilterBar({
 
   // Memoize search results to avoid recalculating on every render
   const searchResults = useMemo(
-    () => getSearchResults(filterCounts, activeFilters, searchQuery, selectedCategory),
-    [filterCounts, activeFilters, searchQuery, selectedCategory]
+    () => getSearchResults(filterCounts, activeFilters, searchQuery, selectedCategory, specTitles),
+    [filterCounts, activeFilters, searchQuery, selectedCategory, specTitles]
   );
 
   // Track searches with no results (debounced, to discover missing specs)
@@ -699,38 +701,83 @@ export function FilterBar({
                   ]
                 : []),
               ...(searchResults.length > 0
-                ? searchResults.map(({ category, value, count }, idx) => (
-                    <MenuItem
-                      key={`${category}-${value}`}
-                      onClick={() => handleValueSelect(category, value)}
-                      selected={idx === highlightedIndex}
-                      sx={{ fontFamily: '"MonoLisa", "MonoLisa Fallback", monospace' }}
-                    >
-                      <ListItemText
-                        primary={value}
-                        secondary={!selectedCategory ? FILTER_LABELS[category] : undefined}
-                        primaryTypographyProps={{
-                          fontFamily: '"MonoLisa", "MonoLisa Fallback", monospace',
-                          fontSize: '0.85rem',
-                        }}
-                        secondaryTypographyProps={{
-                          fontFamily: '"MonoLisa", "MonoLisa Fallback", monospace',
-                          fontSize: '0.7rem',
-                          color: '#9ca3af',
-                        }}
-                      />
-                      <Typography
-                        sx={{
-                          fontFamily: '"MonoLisa", "MonoLisa Fallback", monospace',
-                          fontSize: '0.75rem',
-                          color: '#9ca3af',
-                          ml: 2,
-                        }}
-                      >
-                        ({count})
-                      </Typography>
-                    </MenuItem>
-                  ))
+                ? (() => {
+                    // Split results into exact and fuzzy matches
+                    const exactResults = searchResults.filter((r) => r.matchType === 'exact');
+                    const fuzzyResults = searchResults.filter((r) => r.matchType === 'fuzzy');
+
+                    const renderMenuItem = (result: SearchResult, idx: number) => {
+                      const { category, value, count } = result;
+                      const specTitle = category === 'spec' ? specTitles[value] : undefined;
+                      const menuItem = (
+                        <MenuItem
+                          key={`${category}-${value}`}
+                          onClick={() => handleValueSelect(category, value)}
+                          selected={idx === highlightedIndex}
+                          sx={{ fontFamily: '"MonoLisa", "MonoLisa Fallback", monospace' }}
+                        >
+                          <ListItemText
+                            primary={value}
+                            secondary={!selectedCategory ? FILTER_LABELS[category] : undefined}
+                            primaryTypographyProps={{
+                              fontFamily: '"MonoLisa", "MonoLisa Fallback", monospace',
+                              fontSize: '0.85rem',
+                            }}
+                            secondaryTypographyProps={{
+                              fontFamily: '"MonoLisa", "MonoLisa Fallback", monospace',
+                              fontSize: '0.7rem',
+                              color: '#9ca3af',
+                            }}
+                          />
+                          <Typography
+                            sx={{
+                              fontFamily: '"MonoLisa", "MonoLisa Fallback", monospace',
+                              fontSize: '0.75rem',
+                              color: '#9ca3af',
+                              ml: 2,
+                            }}
+                          >
+                            ({count})
+                          </Typography>
+                        </MenuItem>
+                      );
+                      return specTitle ? (
+                        <Tooltip key={`${category}-${value}`} title={specTitle} placement="right" arrow>
+                          <span>{menuItem}</span>
+                        </Tooltip>
+                      ) : (
+                        menuItem
+                      );
+                    };
+
+                    const items: React.ReactNode[] = [];
+                    // Add exact matches
+                    exactResults.forEach((result, i) => {
+                      items.push(renderMenuItem(result, i));
+                    });
+                    // Add fuzzy label/divider if there are fuzzy results
+                    if (fuzzyResults.length > 0) {
+                      items.push(
+                        <Divider key="exact-fuzzy-divider" sx={{ my: 0.5 }}>
+                          <Typography
+                            sx={{
+                              fontSize: '0.65rem',
+                              color: '#9ca3af',
+                              fontFamily: '"MonoLisa", "MonoLisa Fallback", monospace',
+                              px: 1,
+                            }}
+                          >
+                            fuzzy
+                          </Typography>
+                        </Divider>
+                      );
+                    }
+                    // Add fuzzy matches
+                    fuzzyResults.forEach((result, i) => {
+                      items.push(renderMenuItem(result, exactResults.length + i));
+                    });
+                    return items;
+                  })()
                 : [
                     <MenuItem key="no-results" disabled>
                       <Typography
diff --git a/app/src/hooks/useFilterFetch.ts b/app/src/hooks/useFilterFetch.ts
@@ -25,6 +25,7 @@ interface FilterFetchState {
   filterCounts: FilterCounts | null;
   globalCounts: FilterCounts | null;
   orCounts: Record<string, number>[];
+  specTitles: Record<string, string>;
   allImages: PlotImage[];
   displayedImages: PlotImage[];
   hasMore: boolean;
@@ -55,6 +56,7 @@ export function useFilterFetch({
   const [filterCounts, setFilterCounts] = useState<FilterCounts | null>(initialState.filterCounts ?? null);
   const [globalCounts, setGlobalCounts] = useState<FilterCounts | null>(initialState.globalCounts ?? null);
   const [orCounts, setOrCounts] = useState<Record<string, number>[]>(initialState.orCounts ?? []);
+  const [specTitles, setSpecTitles] = useState<Record<string, string>>(initialState.specTitles ?? {});
   const [allImages, setAllImages] = useState<PlotImage[]>(initialState.allImages ?? []);
   const [displayedImages, setDisplayedImages] = useState<PlotImage[]>(initialState.displayedImages ?? []);
   const [hasMore, setHasMore] = useState(initialState.hasMore ?? false);
@@ -97,10 +99,11 @@ export function useFilterFetch({
 
         if (abortController.signal.aborted) return;
 
-        // Update filter counts
+        // Update filter counts and spec titles
         setFilterCounts(data.counts);
         setGlobalCounts(data.globalCounts || data.counts);
         setOrCounts(data.orCounts || []);
+        setSpecTitles(data.specTitles || {});
 
         // Shuffle images randomly on each load
         const shuffled = shuffleArray<PlotImage>(data.images || []);
@@ -128,6 +131,7 @@ export function useFilterFetch({
     filterCounts,
     globalCounts,
     orCounts,
+    specTitles,
     allImages,
     displayedImages,
     hasMore,
diff --git a/app/src/hooks/useFilterState.ts b/app/src/hooks/useFilterState.ts
@@ -31,6 +31,7 @@ interface UseFilterStateReturn {
   filterCounts: FilterCounts | null;
   globalCounts: FilterCounts | null;
   orCounts: Record<string, number>[];
+  specTitles: Record<string, string>;
   allImages: PlotImage[];
   displayedImages: PlotImage[];
   hasMore: boolean;
@@ -86,6 +87,7 @@ export function useFilterState({
     filterCounts,
     globalCounts,
     orCounts,
+    specTitles,
     allImages,
     displayedImages,
     hasMore,
@@ -234,6 +236,7 @@ export function useFilterState({
     filterCounts,
     globalCounts,
     orCounts,
+    specTitles,
     allImages,
     displayedImages,
     hasMore,
diff --git a/app/src/pages/HomePage.tsx b/app/src/pages/HomePage.tsx
@@ -30,6 +30,7 @@ export function HomePage() {
     activeFilters,
     filterCounts,
     orCounts,
+    specTitles,
     allImages,
     displayedImages,
     hasMore,
@@ -167,6 +168,7 @@ export function HomePage() {
         activeFilters={activeFilters}
         filterCounts={filterCounts}
         orCounts={orCounts}
+        specTitles={specTitles}
         currentTotal={allImages.length}
         displayedCount={displayedImages.length}
         randomAnimation={randomAnimation}
diff --git a/app/src/types/index.ts b/app/src/types/index.ts
@@ -96,6 +96,7 @@ export interface FilteredPlotsResponse {
   counts: FilterCounts;  // Contextual counts (for AND additions)
   globalCounts: FilterCounts;  // Global counts (for reference)
   orCounts: Record<string, number>[];  // Per-group counts for OR additions
+  specTitles: Record<string, string>;  // Mapping spec_id -> title for search/tooltips
 }
 
 export interface LibraryInfo {
diff --git a/app/src/utils/filters.ts b/app/src/utils/filters.ts
diff --git a/app/src/utils/fuzzySearch.ts b/app/src/utils/fuzzySearch.ts
diff --git a/app/src/utils/index.ts b/app/src/utils/index.ts
diff --git a/app/yarn.lock b/app/yarn.lock

Original file line number	Diff line number	Diff line change
`@@ -96,6 +96,7 @@ export interface FilteredPlotsResponse {`
`96`	`96`	`counts: FilterCounts; // Contextual counts (for AND additions)`
`97`	`97`	`globalCounts: FilterCounts; // Global counts (for reference)`
`98`	`98`	`orCounts: Record<string, number>[]; // Per-group counts for OR additions`
	`99`	`+ specTitles: Record<string, string>; // Mapping spec_id -> title for search/tooltips`
`99`	`100`	`}`
`100`	`101`
`101`	`102`	`export interface LibraryInfo {`