search-component-advanced

Un componente de búsqueda avanzado para React con filtros, historial y sugerencias.

🚀 Instalación

npm install search-component-advanced

📖 Uso Básico

import React from 'react';
import SearchComponent from 'search-component-advanced';
import type { SearchItem } from 'search-component-advanced';

function App() {
  const handleSearch = async (query: string, filter?: string): Promise<SearchItem[]> => {
    // Tu lógica de búsqueda
    const response = await fetch(`/api/search?q=${query}&filter=${filter}`);
    return response.json();
  };

  const handleItemSelect = (item: SearchItem) => {
    console.log('Item seleccionado:', item);
  };

  return (
    <SearchComponent
      placeholder="Buscar eventos, equipos, jugadores..."
      onSearch={handleSearch}
      onItemSelect={handleItemSelect}
      showHistory={true}
      showFilters={true}
      maxResults={20}
      filters={[
        { id: "all", label: "Todos", icon: "🔍" },
        { id: "football", label: "Fútbol", icon: "⚽" },
        { id: "basketball", label: "Baloncesto", icon: "🏀" }
      ]}
      popularSuggestions={[
        "Real Madrid", "Barcelona", "Champions League"
      ]}
    />
  );
}

🎛️ Props

| Prop | Tipo | Default | Descripción | |------|------|---------|-------------| | onSearch | (query: string, filter?: string) => Promise<SearchItem[]> | - | Requerido. Función para realizar búsquedas | | placeholder | string | "Buscar..." | Placeholder del input | | maxResults | number | 10 | Máximo número de resultados | | showHistory | boolean | true | Mostrar historial de búsquedas | | showFilters | boolean | true | Mostrar filtros | | debounceMs | number | 300 | Delay del debounce en ms | | filters | SearchFilter[] | [] | Array de filtros disponibles | | popularSuggestions | string[] | [] | Sugerencias populares | | onItemSelect | (item: SearchItem) => void | - | Callback al seleccionar un item | | onHistoryClick | (query: string) => void | - | Callback al hacer click en historial | | onSuggestionClick | (suggestion: string) => void | - | Callback al hacer click en sugerencia |

📝 Tipos

interface SearchItem {
  id: number | string;
  title: string;
  description?: string;
  date?: string;
  imageUrl?: string;
  metadata?: Record<string, any>;
}

interface SearchFilter {
  id: string;
  label: string;
  icon: string;
}

✨ Características

• ✅ Búsqueda en tiempo real con debounce
• ✅ Historial de búsquedas persistente (localStorage)
• ✅ Sugerencias populares personalizables
• ✅ Sistema de filtros flexible
• ✅ Navegación completa por teclado (↑↓ Enter Escape)
• ✅ Diseño responsive y moderno
• ✅ TypeScript completo
• ✅ Sin dependencias externas (iconos incluidos)
• ✅ Componentes modulares exportables individualmente

🎨 Personalización

El componente incluye clases CSS que puedes personalizar:

/* Contenedor principal */
.search-component { }

/* Estados del input */
.search-input-inactive { }
.search-input-active { }

/* Resultados */
.search-results { }
.search-result-item { }
.search-result-selected { }

/* Filtros */
.search-filters { }
.search-filter-active { }

/* Historial */
.search-history { }

🔧 Uso Avanzado

Componentes Individuales

import { 
  SearchInput, 
  SearchFilters, 
  SearchHistory, 
  SearchResults,
  useSearchInput 
} from 'search-component-advanced';

// Usar componentes individualmente
function CustomSearch() {
  const searchProps = useSearchInput({
    onSearch: handleSearch,
    filters: myFilters
  });

  return (
    <div>
      <SearchInput {...searchProps} />
      <SearchFilters {...searchProps} />
      <SearchResults {...searchProps} />
    </div>
  );
}

Hook Personalizado

import { useSearchInput } from 'search-component-advanced';

function MyCustomComponent() {
  const {
    inputValue,
    isActive,
    searchResults,
    handleInputChange,
    handleSearch
  } = useSearchInput({
    onSearch: mySearchFunction,
    debounceMs: 500
  });

  // Tu implementación personalizada
}

📦 Exportaciones

// Componente principal
import SearchComponent from 'search-component-advanced';

// Componentes individuales
import { 
  SearchInput, 
  SearchFilters, 
  SearchHistory, 
  SearchResults 
} from 'search-component-advanced';

// Hook
import { useSearchInput } from 'search-component-advanced';

// Tipos
import type { 
  SearchItem, 
  SearchFilter, 
  SearchProps 
} from 'search-component-advanced';

// Utilidades
import { debounce } from 'search-component-advanced';

🧪 Desarrollo

# Clonar repositorio
git clone https://github.com/tu-usuario/search-component.git

# Instalar dependencias
cd search-component
npm install

# Desarrollar con watch mode
npm run dev

# Build para producción
npm run build

# Ejecutar tests
npm test

# Linting
npm run lint

📄 Licencia

MIT

Desarrollado con ❤️ para mejorar la experiencia de búsqueda en aplicaciones React