Implementing Search Filter

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "Search Filter Configuration",
  "description": "Configuration schema for search and filter interfaces",
  "type": "object",
  "properties": {
    "searchConfig": {
      "type": "object",
      "properties": {
        "enabled": {
          "type": "boolean",
          "default": true,
          "description": "Enable search functionality"
        },
        "debounceMs": {
          "type": "integer",
          "minimum": 0,
          "maximum": 2000,
          "default": 300,
          "description": "Debounce delay in milliseconds"
        },
        "minChars": {
          "type": "integer",
          "minimum": 0,
          "maximum": 10,
          "default": 2,
          "description": "Minimum characters before triggering search"
        },
        "maxLength": {
          "type": "integer",
          "minimum": 10,
          "maximum": 500,
          "default": 200,
          "description": "Maximum search query length"
        },
        "placeholder": {
          "type": "string",
          "default": "Search...",
          "description": "Search input placeholder text"
        },
        "searchFields": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "default": ["title", "description", "tags"],
          "description": "Fields to search in"
        },
        "enableAutocomplete": {
          "type": "boolean",
          "default": true,
          "description": "Enable autocomplete suggestions"
        },
        "autocompleteLimit": {
          "type": "integer",
          "minimum": 1,
          "maximum": 50,
          "default": 10,
          "description": "Maximum autocomplete suggestions"
        }
      }
    },
    "filters": {
      "type": "array",
      "items": {
        "$ref": "#/definitions/filterDefinition"
      },
      "description": "List of available filters"
    },
    "facets": {
      "type": "object",
      "properties": {
        "enabled": {
          "type": "boolean",
          "default": true,
          "description": "Enable faceted search"
        },
        "showCounts": {
          "type": "boolean",
          "default": true,
          "description": "Show result counts for each facet"
        },
        "dynamicCounts": {
          "type": "boolean",
          "default": true,
          "description": "Update counts dynamically as filters change"
        },
        "collapsible": {
          "type": "boolean",
          "default": true,
          "description": "Allow facet sections to be collapsed"
        }
      }
    },
    "sorting": {
      "type": "object",
      "properties": {
        "enabled": {
          "type": "boolean",
          "default": true,
          "description": "Enable sorting options"
        },
        "defaultSort": {
          "type": "string",
          "default": "relevance",
          "description": "Default sort order"
        },
        "options": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/sortOption"
          },
          "description": "Available sort options"
        }
      }
    },
    "pagination": {
      "type": "object",
      "properties": {
        "enabled": {
          "type": "boolean",
          "default": true,
          "description": "Enable pagination"
        },
        "defaultPerPage": {
          "type": "integer",
          "minimum": 1,
          "maximum": 100,
          "default": 20,
          "description": "Default results per page"
        },
        "perPageOptions": {
          "type": "array",
          "items": {
            "type": "integer"
          },
          "default": [10, 20, 50, 100],
          "description": "Available per-page options"
        },
        "maxPages": {
          "type": "integer",
          "minimum": 1,
          "maximum": 1000,
          "default": 100,
          "description": "Maximum number of pages"
        },
        "showInfo": {
          "type": "boolean",
          "default": true,
          "description": "Show pagination info (e.g., 'Showing 1-20 of 100')"
        }
      }
    },
    "ui": {
      "type": "object",
      "properties": {
        "layout": {
          "type": "string",
          "enum": ["sidebar", "top", "modal", "drawer"],
          "default": "sidebar",
          "description": "Filter panel layout"
        },
        "mobileLayout": {
          "type": "string",
          "enum": ["drawer", "modal", "accordion"],
          "default": "drawer",
          "description": "Mobile filter layout"
        },
        "showActiveFilters": {
          "type": "boolean",
          "default": true,
          "description": "Display active filter chips"
        },
        "showClearAll": {
          "type": "boolean",
          "default": true,
          "description": "Show 'Clear all' button"
        },
        "animations": {
          "type": "boolean",
          "default": true,
          "description": "Enable UI animations"
        },
        "theme": {
          "type": "string",
          "enum": ["light", "dark", "auto"],
          "default": "auto",
          "description": "UI theme"
        }
      }
    },
    "performance": {
      "type": "object",
      "properties": {
        "caching": {
          "type": "object",
          "properties": {
            "enabled": {
              "type": "boolean",
              "default": true,
              "description": "Enable result caching"
            },
            "ttl": {
              "type": "integer",
              "minimum": 0,
              "maximum": 3600,
              "default": 300,
              "description": "Cache TTL in seconds"
            },
            "maxSize": {
              "type": "integer",
              "minimum": 0,
              "maximum": 1000,
              "default": 100,
              "description": "Maximum cache entries"
            }
          }
        },
        "virtualization": {
          "type": "object",
          "properties": {
            "enabled": {
              "type": "boolean",
              "default": false,
              "description": "Enable virtual scrolling for large result sets"
            },
            "threshold": {
              "type": "integer",
              "minimum": 100,
              "maximum": 10000,
              "default": 1000,
              "description": "Item count threshold for virtualization"
            }
          }
        },
        "lazyLoading": {
          "type": "object",
          "properties": {
            "enabled": {
              "type": "boolean",
              "default": true,
              "description": "Enable lazy loading of results"
            },
            "imageLoading": {
              "type": "string",
              "enum": ["eager", "lazy", "auto"],
              "default": "lazy",
              "description": "Image loading strategy"
            }
          }
        }
      }
    },
    "api": {
      "type": "object",
      "properties": {
        "searchEndpoint": {
          "type": "string",
          "format": "uri",
          "description": "Search API endpoint"
        },
        "autocompleteEndpoint": {
          "type": "string",
          "format": "uri",
          "description": "Autocomplete API endpoint"
        },
        "method": {
          "type": "string",
          "enum": ["GET", "POST"],
          "default": "POST",
          "description": "HTTP method for search requests"
        },
        "headers": {
          "type": "object",
          "additionalProperties": {
            "type": "string"
          },
          "description": "Additional headers for API requests"
        },
        "timeout": {
          "type": "integer",
          "minimum": 1000,
          "maximum": 60000,
          "default": 10000,
          "description": "API request timeout in milliseconds"
        },
        "retries": {
          "type": "integer",
          "minimum": 0,
          "maximum": 5,
          "default": 3,
          "description": "Number of retry attempts on failure"
        }
      },
      "required": ["searchEndpoint"]
    }
  },
  "definitions": {
    "filterDefinition": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "description": "Unique filter identifier"
        },
        "label": {
          "type": "string",
          "description": "Display label for the filter"
        },
        "type": {
          "type": "string",
          "enum": ["checkbox", "radio", "range", "dropdown", "date", "boolean"],
          "description": "Filter UI type"
        },
        "field": {
          "type": "string",
          "description": "Field name in data/API"
        },
        "dataType": {
          "type": "string",
          "enum": ["string", "number", "boolean", "date"],
          "description": "Data type of the field"
        },
        "options": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "value": {
                "type": ["string", "number", "boolean"]
              },
              "label": {
                "type": "string"
              },
              "count": {
                "type": "integer",
                "minimum": 0
              }
            },
            "required": ["value", "label"]
          },
          "description": "Predefined options for select-type filters"
        },
        "range": {
          "type": "object",
          "properties": {
            "min": {
              "type": "number"
            },
            "max": {
              "type": "number"
            },
            "step": {
              "type": "number"
            },
            "prefix": {
              "type": "string"
            },
            "suffix": {
              "type": "string"
            }
          },
          "description": "Configuration for range filters"
        },
        "multiple": {
          "type": "boolean",
          "default": true,
          "description": "Allow multiple selections"
        },
        "required": {
          "type": "boolean",
          "default": false,
          "description": "Is this filter required"
        },
        "defaultValue": {
          "description": "Default filter value"
        },
        "placeholder": {
          "type": "string",
          "description": "Placeholder text for input filters"
        },
        "validation": {
          "type": "object",
          "properties": {
            "pattern": {
              "type": "string",
              "description": "Regex pattern for validation"
            },
            "min": {
              "type": "number",
              "description": "Minimum value"
            },
            "max": {
              "type": "number",
              "description": "Maximum value"
            },
            "minLength": {
              "type": "integer",
              "description": "Minimum string length"
            },
            "maxLength": {
              "type": "integer",
              "description": "Maximum string length"
            }
          }
        }
      },
      "required": ["id", "label", "type", "field"]
    },
    "sortOption": {
      "type": "object",
      "properties": {
        "value": {
          "type": "string",
          "description": "Sort value sent to API"
        },
        "label": {
          "type": "string",
          "description": "Display label"
        },
        "field": {
          "type": "string",
          "description": "Field to sort by"
        },
        "order": {
          "type": "string",
          "enum": ["asc", "desc"],
          "description": "Sort order"
        }
      },
      "required": ["value", "label", "field", "order"]
    }
  },
  "required": ["api"]
}

{
  "openapi": "3.0.3",
  "info": {
    "title": "Search & Filter API",
    "description": "RESTful API specification for search and filter functionality",
    "version": "1.0.0"
  },
  "servers": [
    {
      "url": "https://api.example.com/v1",
      "description": "Production server"
    },
    {
      "url": "http://localhost:8000/v1",
      "description": "Development server"
    }
  ],
  "paths": {
    "/search": {
      "get": {
        "summary": "Search with query parameters",
        "description": "Perform search using URL query parameters. Suitable for simple searches.",
        "operationId": "searchGet",
        "tags": ["Search"],
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "description": "Search query text",
            "required": false,
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 200
            },
            "example": "laptop"
          },
          {
            "name": "category",
            "in": "query",
            "description": "Filter by categories",
            "required": false,
            "style": "form",
            "explode": true,
            "schema": {
              "type": "array",
              "items": {
                "type": "string"
              }
            }
          },
          {
            "name": "brand",
            "in": "query",
            "description": "Filter by brands",
            "required": false,
            "style": "form",
            "explode": true,
            "schema": {
              "type": "array",
              "items": {
                "type": "string"
              }
            }
          },
          {
            "name": "min_price",
            "in": "query",
            "description": "Minimum price filter",
            "required": false,
            "schema": {
              "type": "number",
              "minimum": 0
            }
          },
          {
            "name": "max_price",
            "in": "query",
            "description": "Maximum price filter",
            "required": false,
            "schema": {
              "type": "number",
              "minimum": 0
            }
          },
          {
            "name": "in_stock",
            "in": "query",
            "description": "Filter for in-stock items only",
            "required": false,
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "sort",
            "in": "query",
            "description": "Sort order",
            "required": false,
            "schema": {
              "type": "string",
              "enum": ["relevance", "price_asc", "price_desc", "newest", "rating"],
              "default": "relevance"
            }
          },
          {
            "name": "page",
            "in": "query",
            "description": "Page number",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 1
            }
          },
          {
            "name": "per_page",
            "in": "query",
            "description": "Results per page",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 20
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful search",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SearchResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid parameters",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      },
      "post": {
        "summary": "Search with request body",
        "description": "Perform search using JSON request body. Suitable for complex searches.",
        "operationId": "searchPost",
        "tags": ["Search"],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SearchRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful search",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SearchResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/autocomplete": {
      "get": {
        "summary": "Get search suggestions",
        "description": "Returns autocomplete suggestions based on query prefix",
        "operationId": "autocomplete",
        "tags": ["Search"],
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "description": "Query prefix",
            "required": true,
            "schema": {
              "type": "string",
              "minLength": 2,
              "maxLength": 50
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Maximum suggestions",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 20,
              "default": 10
            }
          },
          {
            "name": "type",
            "in": "query",
            "description": "Suggestion type filter",
            "required": false,
            "schema": {
              "type": "string",
              "enum": ["all", "products", "categories", "brands"]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Suggestions found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AutocompleteResponse"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "SearchRequest": {
        "type": "object",
        "properties": {
          "query": {
            "type": "string",
            "minLength": 1,
            "maxLength": 200,
            "description": "Search query text"
          },
          "filters": {
            "$ref": "#/components/schemas/SearchFilters"
          },
          "sort_by": {
            "type": "string",
            "enum": ["relevance", "price_asc", "price_desc", "newest", "rating"],
            "default": "relevance",
            "description": "Sort order"
          },
          "page": {
            "type": "integer",
            "minimum": 1,
            "maximum": 100,
            "default": 1,
            "description": "Page number"
          },
          "per_page": {
            "type": "integer",
            "minimum": 1,
            "maximum": 100,
            "default": 20,
            "description": "Results per page"
          },
          "include_facets": {
            "type": "boolean",
            "default": true,
            "description": "Include facet counts in response"
          }
        }
      },
      "SearchFilters": {
        "type": "object",
        "properties": {
          "categories": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "maxItems": 20,
            "description": "Category filters"
          },
          "brands": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "maxItems": 20,
            "description": "Brand filters"
          },
          "min_price": {
            "type": "number",
            "minimum": 0,
            "description": "Minimum price"
          },
          "max_price": {
            "type": "number",
            "minimum": 0,
            "description": "Maximum price"
          },
          "in_stock": {
            "type": "boolean",
            "description": "Only in-stock items"
          },
          "min_rating": {
            "type": "number",
            "minimum": 1,
            "maximum": 5,
            "description": "Minimum rating"
          },
          "tags": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Tag filters"
          }
        }
      },
      "SearchResponse": {
        "type": "object",
        "required": ["products", "total", "page", "per_page", "total_pages"],
        "properties": {
          "products": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Product"
            },
            "description": "Search results"
          },
          "total": {
            "type": "integer",
            "minimum": 0,
            "description": "Total number of results"
          },
          "page": {
            "type": "integer",
            "minimum": 1,
            "description": "Current page"
          },
          "per_page": {
            "type": "integer",
            "minimum": 1,
            "description": "Results per page"
          },
          "total_pages": {
            "type": "integer",
            "minimum": 0,
            "description": "Total number of pages"
          },
          "facets": {
            "$ref": "#/components/schemas/Facets"
          },
          "query_time_ms": {
            "type": "number",
            "description": "Query execution time in milliseconds"
          },
          "cached": {
            "type": "boolean",
            "description": "Whether result was served from cache"
          }
        }
      },
      "Product": {
        "type": "object",
        "required": ["id", "title", "price", "category", "brand"],
        "properties": {
          "id": {
            "type": "string",
            "description": "Unique product identifier"
          },
          "title": {
            "type": "string",
            "description": "Product title"
          },
          "description": {
            "type": "string",
            "description": "Product description"
          },
          "price": {
            "type": "number",
            "minimum": 0,
            "description": "Product price"
          },
          "category": {
            "type": "string",
            "description": "Product category"
          },
          "brand": {
            "type": "string",
            "description": "Product brand"
          },
          "rating": {
            "type": "number",
            "minimum": 0,
            "maximum": 5,
            "description": "Average rating"
          },
          "review_count": {
            "type": "integer",
            "minimum": 0,
            "description": "Number of reviews"
          },
          "in_stock": {
            "type": "boolean",
            "description": "Stock availability"
          },
          "image_url": {
            "type": "string",
            "format": "uri",
            "description": "Product image URL"
          },
          "tags": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Product tags"
          }
        }
      },
      "Facets": {
        "type": "object",
        "properties": {
          "categories": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Facet"
            }
          },
          "brands": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Facet"
            }
          },
          "price_ranges": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PriceRangeFacet"
            }
          },
          "ratings": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Facet"
            }
          }
        }
      },
      "Facet": {
        "type": "object",
        "required": ["value", "count"],
        "properties": {
          "value": {
            "type": "string",
            "description": "Facet value"
          },
          "count": {
            "type": "integer",
            "minimum": 0,
            "description": "Number of items"
          }
        }
      },
      "PriceRangeFacet": {
        "type": "object",
        "required": ["min", "max", "count", "label"],
        "properties": {
          "min": {
            "type": "number",
            "description": "Minimum price in range"
          },
          "max": {
            "type": "number",
            "description": "Maximum price in range (null for open-ended)"
          },
          "label": {
            "type": "string",
            "description": "Display label"
          },
          "count": {
            "type": "integer",
            "minimum": 0,
            "description": "Number of items in range"
          }
        }
      },
      "AutocompleteResponse": {
        "type": "object",
        "required": ["query", "suggestions"],
        "properties": {
          "query": {
            "type": "string",
            "description": "Original query"
          },
          "suggestions": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Suggestion"
            }
          }
        }
      },
      "Suggestion": {
        "type": "object",
        "required": ["text", "type"],
        "properties": {
          "text": {
            "type": "string",
            "description": "Suggestion text"
          },
          "type": {
            "type": "string",
            "enum": ["product", "category", "brand", "query"],
            "description": "Suggestion type"
          },
          "category": {
            "type": "string",
            "description": "Associated category"
          },
          "product_id": {
            "type": "string",
            "description": "Product ID (for product suggestions)"
          },
          "count": {
            "type": "integer",
            "description": "Result count for this suggestion"
          }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "required": ["error", "message", "timestamp"],
        "properties": {
          "error": {
            "type": "string",
            "description": "Error code"
          },
          "message": {
            "type": "string",
            "description": "Error message"
          },
          "details": {
            "type": "object",
            "description": "Additional error details"
          },
          "timestamp": {
            "type": "string",
            "format": "date-time",
            "description": "Error timestamp"
          }
        }
      }
    }
  }
}

/**
 * Advanced autocomplete search implementation with Downshift
 *
 * Features:
 * - Accessible autocomplete with keyboard navigation
 * - Debounced API calls
 * - Recent searches and suggestions
 * - Highlighting of matched text
 * - Loading states and error handling
 */

import React, { useState, useEffect, useCallback, useRef } from 'react';
import { useCombobox } from 'downshift';
import { Search, Clock, TrendingUp, X, Loader2 } from 'lucide-react';
import { useDebounce } from '../hooks/useDebounce';

// Types
interface Suggestion {
  id: string;
  text: string;
  type: 'product' | 'category' | 'brand' | 'recent' | 'trending';
  category?: string;
  count?: number;
  metadata?: any;
}

interface AutocompleteProps {
  onSearch: (query: string) => void;
  onSelect: (item: Suggestion) => void;
  placeholder?: string;
  minChars?: number;
  debounceMs?: number;
  maxSuggestions?: number;
}

export function AutocompleteSearch({
  onSearch,
  onSelect,
  placeholder = 'Search products, categories, brands...',
  minChars = 2,
  debounceMs = 300,
  maxSuggestions = 10
}: AutocompleteProps) {
  // State
  const [inputValue, setInputValue] = useState('');
  const [suggestions, setSuggestions] = useState<Suggestion[]>([]);
  const [recentSearches, setRecentSearches] = useState<Suggestion[]>([]);
  const [isLoading, setIsLoading] = useState(false);
  const [error, setError] = useState<string | null>(null);

  // Refs
  const abortControllerRef = useRef<AbortController | null>(null);

  // Debounced search value
  const debouncedSearchTerm = useDebounce(inputValue, debounceMs);

  // Load recent searches from localStorage
  useEffect(() => {
    const stored = localStorage.getItem('recentSearches');
    if (stored) {
      try {
        const parsed = JSON.parse(stored);
        setRecentSearches(parsed.slice(0, 5));
      } catch (e) {
        console.error('Failed to parse recent searches:', e);
      }
    }
  }, []);

  // Fetch suggestions
  const fetchSuggestions = useCallback(async (query: string) => {
    // Cancel previous request
    if (abortControllerRef.current) {
      abortControllerRef.current.abort();
    }

    // Don't search if query too short
    if (query.length < minChars) {
      setSuggestions([]);
      return;
    }

    // Create new abort controller
    abortControllerRef.current = new AbortController();

    setIsLoading(true);
    setError(null);

    try {
      const response = await fetch(`/api/autocomplete?q=${encodeURIComponent(query)}&limit=${maxSuggestions}`, {
        signal: abortControllerRef.current.signal
      });

      if (!response.ok) {
        throw new Error('Failed to fetch suggestions');
      }

      const data = await response.json();
      setSuggestions(data.suggestions);
    } catch (err) {
      if (err.name === 'AbortError') {
        // Request was cancelled, ignore
        return;
      }
      setError('Failed to load suggestions');
      setSuggestions([]);
    } finally {
      setIsLoading(false);
    }
  }, [minChars, maxSuggestions]);

  // Fetch suggestions when debounced value changes
  useEffect(() => {
    if (debouncedSearchTerm) {
      fetchSuggestions(debouncedSearchTerm);
    } else {
      setSuggestions([]);
    }
  }, [debouncedSearchTerm, fetchSuggestions]);

  // Save to recent searches
  const saveToRecent = useCallback((text: string) => {
    const newRecent: Suggestion = {
      id: `recent-${Date.now()}`,
      text,
      type: 'recent'
    };

    const updated = [
      newRecent,
      ...recentSearches.filter(r => r.text !== text)
    ].slice(0, 5);

    setRecentSearches(updated);
    localStorage.setItem('recentSearches', JSON.stringify(updated));
  }, [recentSearches]);

  // Get display items (suggestions or recent/trending)
  const displayItems = inputValue.length >= minChars
    ? suggestions
    : recentSearches;

  // Setup Downshift
  const {
    isOpen,
    getMenuProps,
    getInputProps,
    highlightedIndex,
    getItemProps,
    selectedItem,
    reset
  } = useCombobox({
    items: displayItems,
    inputValue,
    onInputValueChange: ({ inputValue: newValue }) => {
      setInputValue(newValue || '');
    },
    onSelectedItemChange: ({ selectedItem }) => {
      if (selectedItem) {
        setInputValue(selectedItem.text);
        onSelect(selectedItem);
        saveToRecent(selectedItem.text);
        reset();
      }
    },
    itemToString: (item) => item?.text || ''
  });

  // Handle form submission
  const handleSubmit = (e: React.FormEvent) => {
    e.preventDefault();
    if (inputValue.trim()) {
      onSearch(inputValue);
      saveToRecent(inputValue);
      reset();
    }
  };

  // Clear input
  const handleClear = () => {
    setInputValue('');
    setSuggestions([]);
    reset();
  };

  return (
    <div className="autocomplete-search">
      <form onSubmit={handleSubmit} className="search-form">
        <div className="search-input-wrapper">
          <Search className="search-icon" size={20} />

          <input
            {...getInputProps()}
            className="search-input"
            placeholder={placeholder}
            aria-label="Search"
            aria-autocomplete="list"
            aria-describedby="search-instructions"
          />

          <span id="search-instructions" className="sr-only">
            Type to search. Use arrow keys to navigate suggestions.
          </span>

          {/* Loading indicator */}
          {isLoading && (
            <div className="loading-indicator">
              <Loader2 className="animate-spin" size={16} />
            </div>
          )}

          {/* Clear button */}
          {inputValue && (
            <button
              type="button"
              onClick={handleClear}
              className="clear-button"
              aria-label="Clear search"
            >
              <X size={16} />
            </button>
          )}
        </div>
      </form>

      {/* Suggestions dropdown */}
      <div {...getMenuProps()} className="suggestions-dropdown">
        {isOpen && displayItems.length > 0 && (
          <>
            {/* Show section header for recent searches */}
            {inputValue.length < minChars && recentSearches.length > 0 && (
              <div className="suggestions-section">
                <div className="section-header">
                  <Clock size={14} />
                  <span>Recent Searches</span>
                  <button
                    onClick={() => {
                      setRecentSearches([]);
                      localStorage.removeItem('recentSearches');
                    }}
                    className="clear-recent"
                  >
                    Clear
                  </button>
                </div>
              </div>
            )}

            {/* Render suggestions */}
            {displayItems.map((item, index) => (
              <SuggestionItem
                key={item.id}
                item={item}
                isHighlighted={highlightedIndex === index}
                query={inputValue}
                {...getItemProps({ item, index })}
              />
            ))}
          </>
        )}

        {/* No results message */}
        {isOpen && inputValue.length >= minChars && !isLoading && suggestions.length === 0 && (
          <div className="no-suggestions">
            No suggestions found for "{inputValue}"
          </div>
        )}

        {/* Error message */}
        {error && (
          <div className="suggestions-error">
            {error}
          </div>
        )}
      </div>
    </div>
  );
}

// Suggestion Item Component
interface SuggestionItemProps {
  item: Suggestion;
  isHighlighted: boolean;
  query: string;
}

function SuggestionItem({
  item,
  isHighlighted,
  query,
  ...props
}: SuggestionItemProps & React.HTMLAttributes<HTMLLIElement>) {
  return (
    <li
      className={`suggestion-item ${isHighlighted ? 'highlighted' : ''} ${item.type}`}
      {...props}
    >
      <div className="suggestion-content">
        {/* Icon based on type */}
        <div className="suggestion-icon">
          {item.type === 'recent' && <Clock size={16} />}
          {item.type === 'trending' && <TrendingUp size={16} />}
          {item.type === 'product' && <Search size={16} />}
        </div>

        {/* Main text with highlighting */}
        <div className="suggestion-text">
          <HighlightText text={item.text} highlight={query} />

          {/* Additional metadata */}
          {item.category && (
            <span className="suggestion-category">in {item.category}</span>
          )}
        </div>

        {/* Result count */}
        {item.count !== undefined && (
          <span className="suggestion-count">{item.count}</span>
        )}
      </div>
    </li>
  );
}

// Highlight matching text
interface HighlightTextProps {
  text: string;
  highlight: string;
}

function HighlightText({ text, highlight }: HighlightTextProps) {
  if (!highlight.trim()) {
    return <span>{text}</span>;
  }

  const regex = new RegExp(`(${highlight})`, 'gi');
  const parts = text.split(regex);

  return (
    <span>
      {parts.map((part, index) =>
        regex.test(part) ? (
          <mark key={index} className="highlight">
            {part}
          </mark>
        ) : (
          <span key={index}>{part}</span>
        )
      )}
    </span>
  );
}

// Custom debounce hook
function useDebounce<T>(value: T, delay: number): T {
  const [debouncedValue, setDebouncedValue] = useState<T>(value);

  useEffect(() => {
    const handler = setTimeout(() => {
      setDebouncedValue(value);
    }, delay);

    return () => {
      clearTimeout(handler);
    };
  }, [value, delay]);

  return debouncedValue;
}

// Styles (CSS-in-JS or separate stylesheet)
const styles = `
.autocomplete-search {
  position: relative;
  width: 100%;
  max-width: 600px;
}

.search-form {
  width: 100%;
}

.search-input-wrapper {
  position: relative;
  display: flex;
  align-items: center;
  background: var(--search-input-bg);
  border: 1px solid var(--search-input-border);
  border-radius: var(--search-border-radius);
  padding: 0 12px;
  transition: all 0.2s ease;
}

.search-input-wrapper:focus-within {
  border-color: var(--search-input-focus-border);
  box-shadow: 0 0 0 3px var(--search-input-focus-ring);
}

.search-icon {
  color: var(--search-icon-color);
  flex-shrink: 0;
}

.search-input {
  flex: 1;
  border: none;
  background: none;
  padding: 12px;
  font-size: 16px;
  outline: none;
}

.loading-indicator {
  margin-left: 8px;
}

.clear-button {
  margin-left: 8px;
  padding: 4px;
  background: none;
  border: none;
  cursor: pointer;
  color: var(--color-text-secondary);
  transition: color 0.2s;
}

.clear-button:hover {
  color: var(--color-text-primary);
}

.suggestions-dropdown {
  position: absolute;
  top: 100%;
  left: 0;
  right: 0;
  margin-top: 4px;
  background: var(--color-white);
  border: 1px solid var(--color-border);
  border-radius: var(--radius-md);
  box-shadow: var(--shadow-lg);
  max-height: 400px;
  overflow-y: auto;
  z-index: 1000;
}

.suggestions-section {
  padding: 8px 12px;
  border-bottom: 1px solid var(--color-border);
}

.section-header {
  display: flex;
  align-items: center;
  gap: 8px;
  font-size: 12px;
  color: var(--color-text-secondary);
}

.clear-recent {
  margin-left: auto;
  background: none;
  border: none;
  color: var(--color-primary);
  cursor: pointer;
  font-size: 12px;
}

.suggestion-item {
  padding: 12px;
  cursor: pointer;
  transition: background 0.1s;
}

.suggestion-item:hover,
.suggestion-item.highlighted {
  background: var(--color-gray-50);
}

.suggestion-content {
  display: flex;
  align-items: center;
  gap: 12px;
}

.suggestion-icon {
  color: var(--color-text-secondary);
  flex-shrink: 0;
}

.suggestion-text {
  flex: 1;
}

.suggestion-category {
  margin-left: 8px;
  font-size: 12px;
  color: var(--color-text-secondary);
}

.suggestion-count {
  font-size: 12px;
  color: var(--color-text-secondary);
  background: var(--color-gray-100);
  padding: 2px 8px;
  border-radius: var(--radius-sm);
}

.highlight {
  background: var(--result-highlight-bg);
  color: var(--result-highlight-text);
  font-weight: 500;
}

.no-suggestions,
.suggestions-error {
  padding: 16px;
  text-align: center;
  color: var(--color-text-secondary);
}

.suggestions-error {
  color: var(--color-error);
}

.animate-spin {
  animation: spin 1s linear infinite;
}

@keyframes spin {
  from { transform: rotate(0deg); }
  to { transform: rotate(360deg); }
}

.sr-only {
  position: absolute;
  width: 1px;
  height: 1px;
  padding: 0;
  margin: -1px;
  overflow: hidden;
  clip: rect(0, 0, 0, 0);
  white-space: nowrap;
  border: 0;
}
`;

"""
Django REST Framework filter backend implementation.

This example demonstrates advanced filtering with Django REST Framework,
including custom filter backends, faceted search, and query optimization.
"""

from django.db import models
from django.db.models import Q, Count, Avg, F, Value, CharField
from django.contrib.postgres.search import SearchVector, SearchQuery, SearchRank
from django.contrib.postgres.aggregates import ArrayAgg
from rest_framework import viewsets, filters, status
from rest_framework.decorators import action
from rest_framework.response import Response
from rest_framework.pagination import PageNumberPagination
from django_filters import rest_framework as df
from django.core.cache import cache
from typing import Dict, List, Any
import json
import hashlib


# Models
class Product(models.Model):
    """Product model with search-optimized fields."""

    title = models.CharField(max_length=200, db_index=True)
    description = models.TextField()
    category = models.ForeignKey('Category', on_delete=models.CASCADE, related_name='products')
    brand = models.ForeignKey('Brand', on_delete=models.CASCADE, related_name='products')
    price = models.DecimalField(max_digits=10, decimal_places=2, db_index=True)
    rating = models.DecimalField(max_digits=3, decimal_places=2, null=True, blank=True)
    in_stock = models.BooleanField(default=True, db_index=True)
    tags = models.ManyToManyField('Tag', related_name='products')
    created_at = models.DateTimeField(auto_now_add=True, db_index=True)
    updated_at = models.DateTimeField(auto_now=True)

    # PostgreSQL specific: Full-text search vector
    search_vector = SearchVector('title', weight='A') + SearchVector('description', weight='B')

    class Meta:
        indexes = [
            models.Index(fields=['category', 'brand']),
            models.Index(fields=['price', '-created_at']),
            models.Index(fields=['-rating', 'in_stock']),
        ]

    def __str__(self):
        return self.title


class Category(models.Model):
    name = models.CharField(max_length=50, unique=True)
    parent = models.ForeignKey('self', null=True, blank=True, on_delete=models.CASCADE)
    slug = models.SlugField(unique=True)

    class Meta:
        verbose_name_plural = 'Categories'


class Brand(models.Model):
    name = models.CharField(max_length=50, unique=True)
    slug = models.SlugField(unique=True)


class Tag(models.Model):
    name = models.CharField(max_length=30, unique=True)


# Custom Filter Backend
class FacetedSearchBackend(filters.BaseFilterBackend):
    """Custom filter backend for faceted search with dynamic counts."""

    def filter_queryset(self, request, queryset, view):
        """Apply filters while maintaining facet counts."""

        # Get filter parameters
        params = request.query_params

        # Text search
        query = params.get('q', '').strip()
        if query:
            queryset = self._apply_text_search(queryset, query)

        # Category filter
        categories = params.getlist('category')
        if categories:
            queryset = queryset.filter(category__slug__in=categories)

        # Brand filter
        brands = params.getlist('brand')
        if brands:
            queryset = queryset.filter(brand__slug__in=brands)

        # Price range
        min_price = params.get('min_price')
        max_price = params.get('max_price')
        if min_price:
            queryset = queryset.filter(price__gte=min_price)
        if max_price:
            queryset = queryset.filter(price__lte=max_price)

        # Stock filter
        in_stock = params.get('in_stock')
        if in_stock:
            queryset = queryset.filter(in_stock=in_stock.lower() == 'true')

        # Rating filter
        min_rating = params.get('min_rating')
        if min_rating:
            queryset = queryset.filter(rating__gte=min_rating)

        return queryset

    def _apply_text_search(self, queryset, query):
        """Apply PostgreSQL full-text search."""
        from django.db import connection

        if connection.vendor == 'postgresql':
            # Use PostgreSQL full-text search
            search_query = SearchQuery(query, config='english')
            search_vector = SearchVector('title', weight='A') + \
                          SearchVector('description', weight='B')

            queryset = queryset.annotate(
                search=search_vector,
                rank=SearchRank(search_vector, search_query)
            ).filter(search=search_query).order_by('-rank')
        else:
            # Fallback to LIKE queries
            queryset = queryset.filter(
                Q(title__icontains=query) |
                Q(description__icontains=query)
            )

        return queryset


# Django Filter
class ProductFilter(df.FilterSet):
    """Product filter using django-filter."""

    q = df.CharFilter(method='search')
    category = df.ModelMultipleChoiceFilter(
        field_name='category__slug',
        to_field_name='slug',
        queryset=Category.objects.all()
    )
    brand = df.ModelMultipleChoiceFilter(
        field_name='brand__slug',
        to_field_name='slug',
        queryset=Brand.objects.all()
    )
    min_price = df.NumberFilter(field_name='price', lookup_expr='gte')
    max_price = df.NumberFilter(field_name='price', lookup_expr='lte')
    in_stock = df.BooleanFilter()
    min_rating = df.NumberFilter(field_name='rating', lookup_expr='gte')
    tags = df.ModelMultipleChoiceFilter(
        field_name='tags__name',
        to_field_name='name',
        queryset=Tag.objects.all()
    )

    # Date filters
    created_after = df.DateFilter(field_name='created_at', lookup_expr='gte')
    created_before = df.DateFilter(field_name='created_at', lookup_expr='lte')

    # Ordering
    o = df.OrderingFilter(
        fields=(
            ('price', 'price'),
            ('rating', 'rating'),
            ('created_at', 'newest'),
        ),
        field_labels={
            'price': 'Price',
            '-price': 'Price (high to low)',
            'rating': 'Rating (low to high)',
            '-rating': 'Rating (high to low)',
            '-created_at': 'Newest first',
        }
    )

    def search(self, queryset, name, value):
        """Custom search method with relevance scoring."""
        if not value:
            return queryset

        # PostgreSQL full-text search
        from django.db import connection

        if connection.vendor == 'postgresql':
            search_query = SearchQuery(value, config='english')
            search_vector = SearchVector('title', weight='A') + \
                          SearchVector('description', weight='B')

            return queryset.annotate(
                rank=SearchRank(search_vector, search_query)
            ).filter(
                Q(title__icontains=value) |
                Q(description__icontains=value)
            ).order_by('-rank')

        # Fallback for other databases
        return queryset.filter(
            Q(title__icontains=value) |
            Q(description__icontains=value)
        )

    class Meta:
        model = Product
        fields = ['q', 'category', 'brand', 'min_price', 'max_price',
                 'in_stock', 'min_rating', 'tags']


# Serializers
from rest_framework import serializers


class ProductSerializer(serializers.ModelSerializer):
    """Product serializer with nested relationships."""

    category = serializers.StringRelatedField()
    brand = serializers.StringRelatedField()
    tags = serializers.StringRelatedField(many=True)

    class Meta:
        model = Product
        fields = ['id', 'title', 'description', 'category', 'brand',
                 'price', 'rating', 'in_stock', 'tags', 'created_at']


class FacetSerializer(serializers.Serializer):
    """Facet serializer for filter options."""

    value = serializers.CharField()
    label = serializers.CharField()
    count = serializers.IntegerField()


class SearchResultSerializer(serializers.Serializer):
    """Search result with facets."""

    products = ProductSerializer(many=True)
    facets = serializers.DictField(child=FacetSerializer(many=True))
    total = serializers.IntegerField()
    page = serializers.IntegerField()
    page_size = serializers.IntegerField()


# Custom Pagination
class SearchPagination(PageNumberPagination):
    """Custom pagination for search results."""

    page_size = 20
    page_size_query_param = 'page_size'
    max_page_size = 100

    def get_paginated_response(self, data):
        """Include additional metadata in response."""
        return Response({
            'products': data,
            'pagination': {
                'total': self.page.paginator.count,
                'page': self.page.number,
                'page_size': self.get_page_size(self.request),
                'total_pages': self.page.paginator.num_pages,
                'next': self.get_next_link(),
                'previous': self.get_previous_link()
            }
        })


# ViewSet
class ProductViewSet(viewsets.ReadOnlyModelViewSet):
    """Product search and filter viewset."""

    queryset = Product.objects.all()
    serializer_class = ProductSerializer
    filter_backends = [
        FacetedSearchBackend,
        df.DjangoFilterBackend,
        filters.OrderingFilter
    ]
    filterset_class = ProductFilter
    pagination_class = SearchPagination
    ordering_fields = ['price', 'rating', 'created_at']
    ordering = ['-created_at']

    def get_queryset(self):
        """Optimize queryset with select/prefetch related."""
        queryset = super().get_queryset()

        # Optimize database queries
        queryset = queryset.select_related('category', 'brand')
        queryset = queryset.prefetch_related('tags')

        # Add annotations for computed fields
        queryset = queryset.annotate(
            review_count=Count('reviews', distinct=True),
            avg_rating=Avg('reviews__rating')
        )

        return queryset

    def list(self, request, *args, **kwargs):
        """Override list to include facets."""

        # Check cache
        cache_key = self._get_cache_key(request)
        cached_result = cache.get(cache_key)

        if cached_result:
            return Response(cached_result)

        # Get filtered queryset
        queryset = self.filter_queryset(self.get_queryset())

        # Get facets before pagination
        facets = self._get_facets(queryset, request)

        # Paginate
        page = self.paginate_queryset(queryset)
        if page is not None:
            serializer = self.get_serializer(page, many=True)
            response = self.get_paginated_response(serializer.data)
            response.data['facets'] = facets

            # Cache result
            cache.set(cache_key, response.data, 300)  # 5 minutes

            return response

        serializer = self.get_serializer(queryset, many=True)
        return Response({
            'products': serializer.data,
            'facets': facets
        })

    def _get_facets(self, queryset, request):
        """Generate facet counts for filters."""

        facets = {}

        # Category facets
        category_facets = queryset.values('category__name', 'category__slug')\
            .annotate(count=Count('id'))\
            .order_by('-count')[:20]

        facets['categories'] = [
            {
                'value': item['category__slug'],
                'label': item['category__name'],
                'count': item['count']
            }
            for item in category_facets
        ]

        # Brand facets
        brand_facets = queryset.values('brand__name', 'brand__slug')\
            .annotate(count=Count('id'))\
            .order_by('-count')[:20]

        facets['brands'] = [
            {
                'value': item['brand__slug'],
                'label': item['brand__name'],
                'count': item['count']
            }
            for item in brand_facets
        ]

        # Price range facets
        price_ranges = [
            (0, 50, 'Under $50'),
            (50, 100, '$50-$100'),
            (100, 200, '$100-$200'),
            (200, 500, '$200-$500'),
            (500, None, 'Over $500')
        ]

        price_facets = []
        for min_price, max_price, label in price_ranges:
            count_query = queryset.filter(price__gte=min_price)
            if max_price:
                count_query = count_query.filter(price__lt=max_price)

            count = count_query.count()
            if count > 0:
                price_facets.append({
                    'value': f'{min_price}-{max_price or "inf"}',
                    'label': label,
                    'count': count
                })

        facets['price_ranges'] = price_facets

        # In stock count
        in_stock_count = queryset.filter(in_stock=True).count()
        out_of_stock_count = queryset.filter(in_stock=False).count()

        facets['availability'] = [
            {'value': 'true', 'label': 'In Stock', 'count': in_stock_count},
            {'value': 'false', 'label': 'Out of Stock', 'count': out_of_stock_count}
        ]

        return facets

    def _get_cache_key(self, request):
        """Generate cache key from request parameters."""
        params = dict(request.query_params)
        # Sort for consistent hashing
        params_str = json.dumps(params, sort_keys=True)
        return f'search:{hashlib.md5(params_str.encode()).hexdigest()}'

    @action(detail=False, methods=['get'])
    def autocomplete(self, request):
        """Autocomplete endpoint for search suggestions."""

        query = request.query_params.get('q', '').strip()
        if len(query) < 2:
            return Response({'suggestions': []})

        # Get suggestions from products
        suggestions = Product.objects.filter(
            Q(title__icontains=query) |
            Q(brand__name__icontains=query) |
            Q(category__name__icontains=query)
        ).values('title').distinct()[:10]

        # Format response
        return Response({
            'query': query,
            'suggestions': [
                {
                    'text': item['title'],
                    'type': 'product'
                }
                for item in suggestions
            ]
        })

    @action(detail=False, methods=['get'])
    def export(self, request):
        """Export search results to CSV."""

        queryset = self.filter_queryset(self.get_queryset())

        # Limit export size
        queryset = queryset[:1000]

        import csv
        from django.http import HttpResponse

        response = HttpResponse(content_type='text/csv')
        response['Content-Disposition'] = 'attachment; filename="products.csv"'

        writer = csv.writer(response)
        writer.writerow(['ID', 'Title', 'Category', 'Brand', 'Price', 'In Stock'])

        for product in queryset:
            writer.writerow([
                product.id,
                product.title,
                product.category.name,
                product.brand.name,
                product.price,
                product.in_stock
            ])

        return response


# Management Command for Search Index
from django.core.management.base import BaseCommand


class Command(BaseCommand):
    """Management command to rebuild search index."""

    help = 'Rebuild PostgreSQL search index'

    def handle(self, *args, **options):
        from django.db import connection

        with connection.cursor() as cursor:
            # Create GIN index for full-text search
            cursor.execute("""
                CREATE INDEX IF NOT EXISTS products_search_vector_idx
                ON products_product
                USING GIN(
                    to_tsvector('english',
                        COALESCE(title, '') || ' ' ||
                        COALESCE(description, '')
                    )
                )
            """)

            self.stdout.write(
                self.style.SUCCESS('Successfully created search index')
            )


# URLs
from django.urls import path, include
from rest_framework.routers import DefaultRouter

router = DefaultRouter()
router.register('products', ProductViewSet)

urlpatterns = [
    path('api/', include(router.urls)),
]