feat: add fuzzy search with fuse.js (#3829)

## Summary
- Add fuse.js for typo-tolerant fuzzy matching ("scater" → "scatter",
"heatmp" → "heatmap")
- Enable extended search for multi-word AND queries ("hi k" →
"histogram-kde")
- Search spec titles in addition to spec_id
- Show spec title as tooltip in dropdown for spec category
- Add "fuzzy" divider label between exact and fuzzy matches in dropdown

## Configuration
- FUZZY_THRESHOLD: 0.3 (max 30% dissimilarity)
- EXACT_THRESHOLD: 0.1 (score < 0.1 = exact match)
- minMatchCharLength: 1 (single characters allowed)

## Test plan
- [ ] Search "scater" → finds "scatter-*" specs
- [ ] Search "heatmp" → finds "heatmap-*" specs
- [ ] Search "hi k" → finds "histogram-kde"
- [ ] Exact matches appear above "fuzzy" divider
- [ ] Spec tooltips show full title on hover

Closes #3828

🤖 Generated with [Claude Code](https://claude.ai/code)

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: MarkusNeusinger

.github/workflows/ci-tests.yml

@@ -139,3 +139,74 @@ jobs:
     - name: Skip notice
       if: steps.check.outputs.should_test == 'false'
       run: echo "::notice::Tests skipped - no testable Python changes (only plots/ or non-Python files)"
+
+  test-frontend:
+    name: Run Frontend Tests
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+
+    steps:
+    - uses: actions/checkout@v6
+      with:
+        fetch-depth: 0
+
+    - name: Check for frontend changes
+      id: check
+      run: |
+        if [[ "${{ github.event_name }}" == "pull_request" ]]; then
+          BASE_SHA="${{ github.event.pull_request.base.sha }}"
+          HEAD_SHA="${{ github.event.pull_request.head.sha }}"
+          CHANGED_FILES=$(git diff --name-only $BASE_SHA $HEAD_SHA)
+        else
+          CHANGED_FILES=$(git diff --name-only HEAD~1 HEAD 2>/dev/null || echo "")
+        fi
+
+        echo "Changed files:"
+        echo "$CHANGED_FILES"
+
+        # Check for frontend changes
+        FRONTEND_CHANGES=$(echo "$CHANGED_FILES" | grep '^app/' || true)
+
+        # Force run on workflow_dispatch with force_run=true
+        if [[ "${{ github.event_name }}" == "workflow_dispatch" && "${{ inputs.force_run }}" == "true" ]]; then
+          echo "Manual trigger with force_run=true, will run frontend tests"
+          echo "should_test=true" >> $GITHUB_OUTPUT
+        elif [[ -n "$FRONTEND_CHANGES" ]]; then
+          echo "Found frontend changes, will run tests"
+          echo "should_test=true" >> $GITHUB_OUTPUT
+        else
+          echo "No frontend changes, skipping frontend tests"
+          echo "should_test=false" >> $GITHUB_OUTPUT
+        fi
+
+    - name: Set up Node.js
+      if: steps.check.outputs.should_test == 'true'
+      uses: actions/setup-node@v4
+      with:
+        node-version: '20'
+        cache: 'yarn'
+        cache-dependency-path: app/yarn.lock
+
+    - name: Install dependencies
+      if: steps.check.outputs.should_test == 'true'
+      working-directory: app
+      run: yarn install --frozen-lockfile
+
+    - name: Run frontend tests with coverage
+      if: steps.check.outputs.should_test == 'true'
+      working-directory: app
+      run: yarn test --coverage
+
+    - name: Upload frontend coverage to Codecov
+      if: steps.check.outputs.should_test == 'true'
+      uses: codecov/codecov-action@v5
+      with:
+        token: ${{ secrets.CODECOV_TOKEN }}
+        files: ./app/coverage/coverage-final.json
+        flags: frontend
+        fail_ci_if_error: false
+
+    - name: Skip notice
+      if: steps.check.outputs.should_test == 'false'
+      run: echo "::notice::Frontend tests skipped - no app/ changes"

.gitignore

@@ -216,6 +216,7 @@ dist/
 *.tsbuildinfo
 .yarn/
 .pnp.*
+app/coverage/
 
 # OS-specific files
 .DS_Store

api/routers/plots.py

@@ -379,7 +379,7 @@ def _collect_all_images(all_specs: list) -> list[dict]:
         all_specs: List of Spec objects
 
     Returns:
-        List of image dicts with spec_id, library, quality, url, thumb, and html
+        List of image dicts with spec_id, library, quality, url, thumb, html, and title
     """
     all_images: list[dict] = []
     for spec_obj in all_specs:
@@ -395,6 +395,7 @@ def _collect_all_images(all_specs: list) -> list[dict]:
                         "url": impl.preview_url,
                         "thumb": impl.preview_thumb,
                         "html": impl.preview_html,
+                        "title": spec_obj.title,
                     }
                 )
     return all_images
@@ -483,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:

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):

app/package.json

@@ -9,7 +9,9 @@
     "build": "tsc && vite build",
     "preview": "vite preview",
     "lint": "eslint src --ext ts,tsx",
-    "type-check": "tsc --noEmit"
+    "type-check": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
   },
   "engines": {
     "node": ">=20"
@@ -20,6 +22,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",
@@ -31,7 +34,9 @@
     "@types/react-dom": "^19.1.7",
     "@types/react-syntax-highlighter": "^15.5.13",
     "@vitejs/plugin-react-swc": "^4.0.0",
+    "@vitest/coverage-v8": "^4.0.17",
     "typescript": "^5.9.2",
-    "vite": "^7.3.1"
+    "vite": "^7.3.1",
+    "vitest": "^4.0.17"
   }
 }

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

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,

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,

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}

app/src/types/index.ts

@@ -7,6 +7,7 @@ export interface PlotImage {
   html?: string;
   code?: string;
   spec_id?: string;
+  title?: string;
 }
 
 // Filter system types
@@ -95,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 {