PixelPilot uiux-fuzzy-search.instructions.md

UI/UX Fuzzy Search

Implement typo-tolerant search with match highlighting and suggestions. Uses Fuse.js for client-side fuzzy matching with token-aware styling.

---

OVERVIEW

This skill covers:

1. Fuse.js/lunr.js setup and configuration
2. Debounced input handling
3. Match highlighting
4. "Did you mean?" suggestions
5. Empty state and no results handling
6. Token-aware styling

---

INSTALLATION

# Fuse.js (recommended for most use cases)
npm install fuse.js

# lunr.js (for larger datasets with full-text search)
npm install lunr

---

FUSE.JS IMPLEMENTATION

Basic Setup

import Fuse from 'fuse.js';

interface SearchItem {
  id: string;
  title: string;
  description: string;
  category: string;
  tags: string[];
}

const fuseOptions: Fuse.IFuseOptions<SearchItem> = {
  // Which keys to search
  keys: [
    { name: 'title', weight: 2 },      // Higher weight = more important
    { name: 'description', weight: 1 },
    { name: 'category', weight: 1.5 },
    { name: 'tags', weight: 1 }
  ],
  
  // Fuzzy matching settings
  threshold: 0.4,          // 0 = exact match, 1 = match anything
  distance: 100,           // How far to search for a match
  minMatchCharLength: 2,   // Minimum characters before searching
  
  // Include match info for highlighting
  includeScore: true,
  includeMatches: true,
  
  // Performance
  ignoreLocation: true,    // Search entire string, not just beginning
  useExtendedSearch: true, // Enable advanced search patterns
};

// Create the search index
const fuse = new Fuse(items, fuseOptions);

// Search
const results = fuse.search('serch query'); // Typo-tolerant!

Search Component

import { useState, useMemo, useCallback } from 'react';
import Fuse from 'fuse.js';
import { Search, X, Loader2 } from 'lucide-react';
import { useDebounce } from '@/hooks/useDebounce';

interface FuzzySearchProps<T> {
  items: T[];
  keys: Fuse.FuseOptionKey<T>[];
  placeholder?: string;
  onSelect?: (item: T) => void;
  renderItem?: (item: T, matches: Fuse.FuseResultMatch[]) => React.ReactNode;
  emptyMessage?: string;
  threshold?: number;
}

export function FuzzySearch<T extends { id: string }>({
  items,
  keys,
  placeholder = 'Search...',
  onSelect,
  renderItem,
  emptyMessage = 'No results found',
  threshold = 0.4
}: FuzzySearchProps<T>) {
  const [query, setQuery] = useState('');
  const [isOpen, setIsOpen] = useState(false);
  const [selectedIndex, setSelectedIndex] = useState(0);
  
  const debouncedQuery = useDebounce(query, 200);
  
  // Create Fuse instance
  const fuse = useMemo(() => {
    return new Fuse(items, {
      keys,
      threshold,
      includeMatches: true,
      includeScore: true,
      minMatchCharLength: 2,
    });
  }, [items, keys, threshold]);
  
  // Get search results
  const results = useMemo(() => {
    if (!debouncedQuery.trim()) return [];
    return fuse.search(debouncedQuery).slice(0, 10);
  }, [fuse, debouncedQuery]);
  
  // Handle keyboard navigation
  const handleKeyDown = useCallback((e: React.KeyboardEvent) => {
    switch (e.key) {
      case 'ArrowDown':
        e.preventDefault();
        setSelectedIndex(i => Math.min(i + 1, results.length - 1));
        break;
      case 'ArrowUp':
        e.preventDefault();
        setSelectedIndex(i => Math.max(i - 1, 0));
        break;
      case 'Enter':
        e.preventDefault();
        if (results[selectedIndex]) {
          onSelect?.(results[selectedIndex].item);
          setQuery('');
          setIsOpen(false);
        }
        break;
      case 'Escape':
        setIsOpen(false);
        break;
    }
  }, [results, selectedIndex, onSelect]);
  
  return (
    <div className="fuzzy-search" role="combobox" aria-expanded={isOpen}>
      <div className="fuzzy-search__input-wrap">
        <Search className="fuzzy-search__icon" aria-hidden="true" />
        <input
          type="text"
          className="fuzzy-search__input"
          value={query}
          onChange={(e) => {
            setQuery(e.target.value);
            setIsOpen(true);
            setSelectedIndex(0);
          }}
          onFocus={() => setIsOpen(true)}
          onBlur={() => setTimeout(() => setIsOpen(false), 200)}
          onKeyDown={handleKeyDown}
          placeholder={placeholder}
          aria-label="Search"
          aria-autocomplete="list"
          aria-controls="search-results"
        />
        {query && (
          <button 
            className="fuzzy-search__clear"
            onClick={() => setQuery('')}
            aria-label="Clear search"
          >
            <X size={16} />
          </button>
        )}
      </div>
      
      {isOpen && query.length >= 2 && (
        <ul 
          id="search-results"
          className="fuzzy-search__results"
          role="listbox"
        >
          {results.length > 0 ? (
            results.map((result, index) => (
              <li
                key={result.item.id}
                className={`fuzzy-search__result ${
                  index === selectedIndex ? 'fuzzy-search__result--selected' : ''
                }`}
                role="option"
                aria-selected={index === selectedIndex}
                onClick={() => {
                  onSelect?.(result.item);
                  setQuery('');
                  setIsOpen(false);
                }}
              >
                {renderItem ? (
                  renderItem(result.item, result.matches || [])
                ) : (
                  <HighlightedText 
                    text={(result.item as any).title || ''} 
                    matches={result.matches?.find(m => m.key === 'title')?.indices || []}
                  />
                )}
                {result.score !== undefined && (
                  <span className="fuzzy-search__score">
                    {Math.round((1 - result.score) * 100)}% match
                  </span>
                )}
              </li>
            ))
          ) : (
            <li className="fuzzy-search__empty">
              {emptyMessage}
              <DidYouMean query={query} items={items} keys={keys} />
            </li>
          )}
        </ul>
      )}
    </div>
  );
}