@seekora-ai/ui-sdk-react 1.0.0

package/dist/hooks/useQuerySuggestionsEnhanced.js

@@ -0,0 +1,376 @@
+/**
+ * Enhanced Query Suggestions Hook
+ *
+ * Provides full support for query suggestions API including:
+ * - Basic suggestions
+ * - Dropdown recommendations (trending, top searches, related)
+ * - Filtered tabs with products
+ * - Recent searches (local storage)
+ * - Analytics tracking
+ */
+import { useState, useEffect, useRef, useCallback, useMemo } from 'react';
+import { log } from '@seekora-ai/ui-sdk-core';
+// ============================================================================
+// Local Storage Helpers
+// ============================================================================
+const RECENT_SEARCHES_DEFAULT_KEY = 'seekora_recent_searches';
+const MAX_RECENT_SEARCHES_DEFAULT = 10;
+function getRecentSearchesFromStorage(key) {
+    if (typeof window === 'undefined')
+        return [];
+    try {
+        const stored = localStorage.getItem(key);
+        if (!stored)
+            return [];
+        return JSON.parse(stored);
+    }
+    catch {
+        return [];
+    }
+}
+function saveRecentSearchesToStorage(key, searches) {
+    if (typeof window === 'undefined')
+        return;
+    try {
+        localStorage.setItem(key, JSON.stringify(searches));
+    }
+    catch (error) {
+        log.warn('Failed to save recent searches to localStorage', { error });
+    }
+}
+// ============================================================================
+// Transform API Response
+// ============================================================================
+function transformSuggestion(raw) {
+    const query = raw.query || raw.text || String(raw);
+    const highlighted = raw._highlightResult?.query?.value;
+    return {
+        query,
+        popularity: raw.popularity,
+        count: raw.instant_search?.exact_nb_hits ?? raw.popularity ?? raw.count,
+        objectID: raw.objectID,
+        highlightedQuery: highlighted ? parseHighlight(highlighted) : undefined,
+        categories: raw.categories?.map((c) => ({
+            value: c.value || c.name,
+            count: c.count,
+            path: c.path,
+        })),
+        facets: raw.instant_search?.facets || raw.facets,
+        metadata: raw,
+    };
+}
+function parseHighlight(highlighted) {
+    // Convert __ais-highlight__ markers to HTML
+    return highlighted
+        .replace(/__ais-highlight__/g, '<mark>')
+        .replace(/__\/ais-highlight__/g, '</mark>');
+}
+function transformProduct(raw) {
+    return {
+        id: raw.id || raw.objectID,
+        objectID: raw.objectID || raw.id,
+        title: raw.title || raw.name || raw.productName,
+        name: raw.name || raw.title,
+        image: raw.image || raw.imageUrl || raw.metadata?.image,
+        price: raw.price || raw.sellPrice || raw.metadata?.sellPrice,
+        currency: raw.currency || raw.metadata?.currency || '',
+        url: raw.url || raw.productId || raw.metadata?.url,
+        clicks: raw.clicks,
+        conversions: raw.conversions,
+        revenue: raw.revenue,
+        trend_score: raw.trend_score,
+        metadata: raw.metadata || raw,
+    };
+}
+function transformFilteredTab(raw) {
+    return {
+        id: raw.id,
+        label: raw.label,
+        filter: raw.filter,
+        products: raw.products?.map(transformProduct) || [],
+        nb_hits: raw.nb_hits,
+        processing_time_ms: raw.processing_time_ms,
+    };
+}
+// ============================================================================
+// Main Hook
+// ============================================================================
+export function useQuerySuggestionsEnhanced(options) {
+    const { client, query, enabled = true, debounceMs = 200, maxSuggestions = 10, minQueryLength = 1, includeDropdownRecommendations = false, includeCategories = false, includeFacets = false, maxCategories = 3, maxFacets = 5, filteredTabs, minPopularity, timeRange, disableTypoTolerance, analyticsTags, enableRecentSearches = true, maxRecentSearches = MAX_RECENT_SEARCHES_DEFAULT, recentSearchesKey = RECENT_SEARCHES_DEFAULT_KEY, onSuggestionsLoaded, onError, } = options;
+    // State
+    const [suggestions, setSuggestions] = useState([]);
+    const [loading, setLoading] = useState(false);
+    const [error, setError] = useState(null);
+    const [dropdownRecommendations, setDropdownRecommendations] = useState(null);
+    const [recentSearches, setRecentSearches] = useState([]);
+    const [processingTimeMs, setProcessingTimeMs] = useState(null);
+    const [totalHits, setTotalHits] = useState(0);
+    const [currentPage, setCurrentPage] = useState(0);
+    const [totalPages, setTotalPages] = useState(0);
+    const [originalQuery, setOriginalQuery] = useState('');
+    // Refs
+    const debounceTimerRef = useRef(null);
+    const abortControllerRef = useRef(null);
+    const mountedRef = useRef(true);
+    // Load recent searches on mount
+    useEffect(() => {
+        if (enableRecentSearches) {
+            const stored = getRecentSearchesFromStorage(recentSearchesKey);
+            setRecentSearches(stored.slice(0, maxRecentSearches));
+        }
+        return () => {
+            mountedRef.current = false;
+        };
+    }, [enableRecentSearches, recentSearchesKey, maxRecentSearches]);
+    // Fetch suggestions
+    const fetchSuggestions = useCallback(async (searchQuery) => {
+        if (!client || !searchQuery.trim()) {
+            setSuggestions([]);
+            setDropdownRecommendations(null);
+            return;
+        }
+        // Cancel previous request
+        if (abortControllerRef.current) {
+            abortControllerRef.current.abort();
+        }
+        abortControllerRef.current = new AbortController();
+        setLoading(true);
+        setError(null);
+        try {
+            const response = await client.getSuggestions?.(searchQuery, {
+                hitsPerPage: maxSuggestions,
+                include_dropdown_recommendations: includeDropdownRecommendations || (filteredTabs && filteredTabs.length > 0),
+                include_categories: includeCategories,
+                include_facets: includeFacets,
+                max_categories: maxCategories,
+                max_facets: maxFacets,
+                filtered_tabs: filteredTabs,
+                min_popularity: minPopularity,
+                time_range: timeRange,
+                disable_typo_tolerance: disableTypoTolerance,
+                analytics_tags: analyticsTags,
+                returnFullResponse: true,
+            });
+            if (!mountedRef.current)
+                return;
+            // Transform suggestions
+            const rawSuggestions = response.suggestions || [];
+            const transformedSuggestions = rawSuggestions.map(transformSuggestion);
+            setSuggestions(transformedSuggestions);
+            // Extract dropdown recommendations from extensions
+            const extensions = (response.extensions || {});
+            const recommendations = {
+                trending_searches: Array.isArray(extensions.trending_searches) ? extensions.trending_searches : [],
+                top_searches: Array.isArray(extensions.top_searches) ? extensions.top_searches : [],
+                related_searches: Array.isArray(extensions.related_searches) ? extensions.related_searches : [],
+                trending_products: Array.isArray(extensions.trending_products) ? extensions.trending_products.map(transformProduct) : [],
+                item_recommendations: Array.isArray(extensions.item_recommendations) ? extensions.item_recommendations.map(transformProduct) : [],
+                popular_brands: Array.isArray(extensions.popular_brands) ? extensions.popular_brands : [],
+                filtered_tabs: Array.isArray(extensions.filtered_tabs) ? extensions.filtered_tabs.map(transformFilteredTab) : [],
+                processing_time_ms: typeof extensions.processing_time_ms === 'number' ? extensions.processing_time_ms : undefined,
+                cached_at: typeof extensions.cached_at === 'string' ? extensions.cached_at : undefined,
+            };
+            setDropdownRecommendations(recommendations);
+            // Extract metadata from raw response
+            const raw = response.raw;
+            const rawResultsArr = raw?.results;
+            const rawResult = (rawResultsArr?.[0] ?? raw ?? {});
+            const num = (v) => (typeof v === 'number' && !Number.isNaN(v) ? v : 0);
+            const str = (v) => (typeof v === 'string' ? v : '');
+            setProcessingTimeMs(typeof rawResult.processingTimeMS === 'number' ? rawResult.processingTimeMS : null);
+            setTotalHits(num(rawResult.nbHits) || transformedSuggestions.length);
+            setCurrentPage(num(rawResult.page) || 0);
+            setTotalPages(num(rawResult.nbPages) || 1);
+            setOriginalQuery(str(rawResult.query) || searchQuery);
+            // Callback
+            if (onSuggestionsLoaded) {
+                onSuggestionsLoaded({
+                    suggestions: transformedSuggestions,
+                    nbHits: num(rawResult.nbHits) || transformedSuggestions.length,
+                    page: num(rawResult.page) || 0,
+                    nbPages: num(rawResult.nbPages) || 1,
+                    hitsPerPage: num(rawResult.hitsPerPage) || maxSuggestions,
+                    processingTimeMS: typeof rawResult.processingTimeMS === 'number' ? rawResult.processingTimeMS : undefined,
+                    query: str(rawResult.query) || searchQuery,
+                    dropdownRecommendations: recommendations,
+                    results: Array.isArray(response.results) ? response.results : undefined,
+                    extensions,
+                });
+            }
+            log.verbose('Query suggestions loaded', {
+                query: searchQuery,
+                suggestionsCount: transformedSuggestions.length,
+                hasRecommendations: Object.keys(recommendations).some(k => Array.isArray(recommendations[k]) && recommendations[k].length > 0),
+            });
+        }
+        catch (err) {
+            if (!mountedRef.current)
+                return;
+            const error = err instanceof Error ? err : new Error(String(err));
+            if (error.name === 'AbortError')
+                return;
+            log.error('Failed to fetch query suggestions', { query: searchQuery, error: error.message });
+            setError(error);
+            setSuggestions([]);
+            setDropdownRecommendations(null);
+            if (onError) {
+                onError(error);
+            }
+        }
+        finally {
+            if (mountedRef.current) {
+                setLoading(false);
+            }
+        }
+    }, [
+        client,
+        maxSuggestions,
+        includeDropdownRecommendations,
+        includeCategories,
+        includeFacets,
+        maxCategories,
+        maxFacets,
+        filteredTabs,
+        minPopularity,
+        timeRange,
+        disableTypoTolerance,
+        analyticsTags,
+        onSuggestionsLoaded,
+        onError,
+    ]);
+    // Debounced fetch effect
+    useEffect(() => {
+        if (debounceTimerRef.current) {
+            clearTimeout(debounceTimerRef.current);
+        }
+        if (!enabled || query.length < minQueryLength) {
+            setSuggestions([]);
+            setLoading(false);
+            setError(null);
+            return;
+        }
+        setLoading(true);
+        debounceTimerRef.current = setTimeout(() => {
+            fetchSuggestions(query);
+        }, debounceMs);
+        return () => {
+            if (debounceTimerRef.current) {
+                clearTimeout(debounceTimerRef.current);
+            }
+        };
+    }, [query, enabled, minQueryLength, debounceMs, fetchSuggestions]);
+    // Recent search management
+    const addRecentSearch = useCallback((searchQuery, resultsCount) => {
+        if (!enableRecentSearches || !searchQuery.trim())
+            return;
+        setRecentSearches(prev => {
+            // Remove existing entry for same query
+            const filtered = prev.filter(s => s.query.toLowerCase() !== searchQuery.toLowerCase());
+            // Add new entry at the beginning
+            const newSearch = {
+                query: searchQuery.trim(),
+                timestamp: Date.now(),
+                resultsCount,
+            };
+            const updated = [newSearch, ...filtered].slice(0, maxRecentSearches);
+            saveRecentSearchesToStorage(recentSearchesKey, updated);
+            return updated;
+        });
+    }, [enableRecentSearches, maxRecentSearches, recentSearchesKey]);
+    const removeRecentSearch = useCallback((searchQuery) => {
+        setRecentSearches(prev => {
+            const updated = prev.filter(s => s.query !== searchQuery);
+            saveRecentSearchesToStorage(recentSearchesKey, updated);
+            return updated;
+        });
+    }, [recentSearchesKey]);
+    const clearRecentSearches = useCallback(() => {
+        setRecentSearches([]);
+        saveRecentSearchesToStorage(recentSearchesKey, []);
+    }, [recentSearchesKey]);
+    // Manual refetch
+    const refetch = useCallback(async () => {
+        if (query.length >= minQueryLength) {
+            await fetchSuggestions(query);
+        }
+    }, [query, minQueryLength, fetchSuggestions]);
+    // Derived values
+    const trendingSearches = dropdownRecommendations?.trending_searches || [];
+    const topSearches = dropdownRecommendations?.top_searches || [];
+    const relatedSearches = dropdownRecommendations?.related_searches || [];
+    const popularBrands = dropdownRecommendations?.popular_brands || [];
+    const filteredTabsResult = dropdownRecommendations?.filtered_tabs || [];
+    const trendingProducts = dropdownRecommendations?.trending_products || [];
+    const hasContent = useMemo(() => {
+        return (suggestions.length > 0 ||
+            recentSearches.length > 0 ||
+            trendingSearches.length > 0 ||
+            topSearches.length > 0 ||
+            relatedSearches.length > 0 ||
+            popularBrands.length > 0 ||
+            filteredTabsResult.length > 0 ||
+            trendingProducts.length > 0);
+    }, [
+        suggestions,
+        recentSearches,
+        trendingSearches,
+        topSearches,
+        relatedSearches,
+        popularBrands,
+        filteredTabsResult,
+        trendingProducts,
+    ]);
+    // Get all navigable items for keyboard navigation
+    const getAllNavigableItems = useCallback(() => {
+        const items = [];
+        let index = 0;
+        // Recent searches first (when query is empty)
+        if (query.length === 0 && recentSearches.length > 0) {
+            recentSearches.forEach(search => {
+                items.push({ type: 'recent', index: index++, data: search });
+            });
+        }
+        // Suggestions
+        suggestions.forEach(suggestion => {
+            items.push({ type: 'suggestion', index: index++, data: suggestion });
+        });
+        // Trending searches
+        trendingSearches.forEach(trending => {
+            items.push({ type: 'trending', index: index++, data: trending });
+        });
+        // Products
+        trendingProducts.forEach(product => {
+            items.push({ type: 'product', index: index++, data: product });
+        });
+        // Brands
+        popularBrands.forEach(brand => {
+            items.push({ type: 'brand', index: index++, data: brand });
+        });
+        return items;
+    }, [query, recentSearches, suggestions, trendingSearches, trendingProducts, popularBrands]);
+    return {
+        suggestions,
+        loading,
+        error,
+        dropdownRecommendations,
+        trendingSearches,
+        topSearches,
+        relatedSearches,
+        popularBrands,
+        filteredTabs: filteredTabsResult,
+        trendingProducts,
+        recentSearches,
+        processingTimeMs,
+        totalHits,
+        currentPage,
+        totalPages,
+        originalQuery,
+        addRecentSearch,
+        removeRecentSearch,
+        clearRecentSearches,
+        refetch,
+        hasContent,
+        getAllNavigableItems,
+    };
+}
+export default useQuerySuggestionsEnhanced;

package/dist/hooks/useSearchState.d.ts

@@ -0,0 +1,35 @@
+/**
+ * useSearchState Hook
+ *
+ * React hook for accessing and managing search state via SearchStateManager
+ * Provides reactive state and methods to update search parameters
+ */
+import type { SearchResponse } from '@seekora-ai/search-sdk';
+import { SearchStateManager, type SearchState } from '@seekora-ai/ui-sdk-core';
+export interface UseSearchStateReturn {
+    query: string;
+    refinements: Array<{
+        field: string;
+        value: string;
+    }>;
+    currentPage: number;
+    itemsPerPage: number;
+    sortBy?: string;
+    results: SearchState['results'];
+    loading: boolean;
+    error: Error | null;
+    setQuery: (query: string, triggerSearch?: boolean) => void;
+    addRefinement: (field: string, value: string, triggerSearch?: boolean) => void;
+    removeRefinement: (field: string, value: string, triggerSearch?: boolean) => void;
+    clearRefinements: (triggerSearch?: boolean) => void;
+    setPage: (page: number, triggerSearch?: boolean) => void;
+    setSortBy: (sortBy: string, triggerSearch?: boolean) => void;
+    search: (additionalOptions?: Parameters<SearchStateManager['search']>[0]) => Promise<SearchResponse | null>;
+    clear: () => void;
+}
+/**
+ * Hook to access and manage search state
+ * Automatically subscribes to state changes and re-renders when state updates
+ */
+export declare const useSearchState: () => UseSearchStateReturn;
+//# sourceMappingURL=useSearchState.d.ts.map

package/dist/hooks/useSearchState.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useSearchState.d.ts","sourceRoot":"","sources":["../../src/hooks/useSearchState.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAC7D,OAAO,EAAE,kBAAkB,EAAE,KAAK,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAG/E,MAAM,WAAW,oBAAoB;IAEnC,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,KAAK,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACrD,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,WAAW,CAAC,SAAS,CAAC,CAAC;IAChC,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;IAGpB,QAAQ,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,aAAa,CAAC,EAAE,OAAO,KAAK,IAAI,CAAC;IAC3D,aAAa,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,aAAa,CAAC,EAAE,OAAO,KAAK,IAAI,CAAC;IAC/E,gBAAgB,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,aAAa,CAAC,EAAE,OAAO,KAAK,IAAI,CAAC;IAClF,gBAAgB,EAAE,CAAC,aAAa,CAAC,EAAE,OAAO,KAAK,IAAI,CAAC;IACpD,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,aAAa,CAAC,EAAE,OAAO,KAAK,IAAI,CAAC;IACzD,SAAS,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,aAAa,CAAC,EAAE,OAAO,KAAK,IAAI,CAAC;IAC7D,MAAM,EAAE,CAAC,iBAAiB,CAAC,EAAE,UAAU,CAAC,kBAAkB,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC,CAAC;IAC5G,KAAK,EAAE,MAAM,IAAI,CAAC;CACnB;AAED;;;GAGG;AACH,eAAO,MAAM,cAAc,QAAO,oBAkEjC,CAAC"}

package/dist/hooks/useSearchState.js

@@ -0,0 +1,68 @@
+/**
+ * useSearchState Hook
+ *
+ * React hook for accessing and managing search state via SearchStateManager
+ * Provides reactive state and methods to update search parameters
+ */
+import { useState, useEffect, useCallback } from 'react';
+import { useSearchContext } from '../components/SearchProvider';
+/**
+ * Hook to access and manage search state
+ * Automatically subscribes to state changes and re-renders when state updates
+ */
+export const useSearchState = () => {
+    const { stateManager } = useSearchContext();
+    const [state, setState] = useState(stateManager.getState());
+    // Subscribe to state changes
+    useEffect(() => {
+        const unsubscribe = stateManager.subscribe((newState) => {
+            setState(newState);
+        });
+        return unsubscribe;
+    }, [stateManager]);
+    // Memoized action methods
+    const setQuery = useCallback((query, triggerSearch = true) => {
+        stateManager.setQuery(query, triggerSearch);
+    }, [stateManager]);
+    const addRefinement = useCallback((field, value, triggerSearch = true) => {
+        stateManager.addRefinement(field, value, triggerSearch);
+    }, [stateManager]);
+    const removeRefinement = useCallback((field, value, triggerSearch = true) => {
+        stateManager.removeRefinement(field, value, triggerSearch);
+    }, [stateManager]);
+    const clearRefinements = useCallback((triggerSearch = true) => {
+        stateManager.clearRefinements(triggerSearch);
+    }, [stateManager]);
+    const setPage = useCallback((page, triggerSearch = true) => {
+        stateManager.setPage(page, triggerSearch);
+    }, [stateManager]);
+    const setSortBy = useCallback((sortBy, triggerSearch = true) => {
+        stateManager.setSortBy(sortBy, triggerSearch);
+    }, [stateManager]);
+    const search = useCallback((additionalOptions) => {
+        return stateManager.search(additionalOptions);
+    }, [stateManager]);
+    const clear = useCallback(() => {
+        stateManager.clear();
+    }, [stateManager]);
+    return {
+        // State
+        query: state.query,
+        refinements: state.refinements,
+        currentPage: state.currentPage,
+        itemsPerPage: state.itemsPerPage,
+        sortBy: state.sortBy,
+        results: state.results,
+        loading: state.loading,
+        error: state.error,
+        // Actions
+        setQuery,
+        addRefinement,
+        removeRefinement,
+        clearRefinements,
+        setPage,
+        setSortBy,
+        search,
+        clear,
+    };
+};

package/dist/hooks/useSeekoraSearch.d.ts

@@ -0,0 +1,20 @@
+/**
+ * useSeekoraSearch Hook
+ *
+ * Hook for performing searches with the Seekora SDK
+ */
+import type { SeekoraClient, SearchOptions, SearchResponse, SearchContext } from '@seekora-ai/search-sdk';
+export interface UseSeekoraSearchOptions {
+    client: SeekoraClient;
+    autoTrack?: boolean;
+}
+export interface UseSeekoraSearchReturn {
+    search: (options: SearchOptions) => Promise<SearchResponse | null>;
+    results: SearchResponse | null;
+    loading: boolean;
+    error: Error | null;
+    context: SearchContext | null;
+    clearResults: () => void;
+}
+export declare const useSeekoraSearch: ({ client, autoTrack, }: UseSeekoraSearchOptions) => UseSeekoraSearchReturn;
+//# sourceMappingURL=useSeekoraSearch.d.ts.map

package/dist/hooks/useSeekoraSearch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useSeekoraSearch.d.ts","sourceRoot":"","sources":["../../src/hooks/useSeekoraSearch.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,KAAK,EAAE,aAAa,EAAE,aAAa,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAG1G,MAAM,WAAW,uBAAuB;IACtC,MAAM,EAAE,aAAa,CAAC;IACtB,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED,MAAM,WAAW,sBAAsB;IACrC,MAAM,EAAE,CAAC,OAAO,EAAE,aAAa,KAAK,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC,CAAC;IACnE,OAAO,EAAE,cAAc,GAAG,IAAI,CAAC;IAC/B,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;IACpB,OAAO,EAAE,aAAa,GAAG,IAAI,CAAC;IAC9B,YAAY,EAAE,MAAM,IAAI,CAAC;CAC1B;AAED,eAAO,MAAM,gBAAgB,GAAI,wBAG9B,uBAAuB,KAAG,sBA8D5B,CAAC"}

package/dist/hooks/useSeekoraSearch.js

@@ -0,0 +1,63 @@
+/**
+ * useSeekoraSearch Hook
+ *
+ * Hook for performing searches with the Seekora SDK
+ */
+import { useState, useCallback } from 'react';
+import { log } from '@seekora-ai/ui-sdk-core';
+export const useSeekoraSearch = ({ client, autoTrack = true, }) => {
+    const [results, setResults] = useState(null);
+    const [loading, setLoading] = useState(false);
+    const [error, setError] = useState(null);
+    const [context, setContext] = useState(null);
+    const search = useCallback(async (options) => {
+        setLoading(true);
+        setError(null);
+        const query = options.q || '';
+        log.verbose('useSeekoraSearch: Starting search', { query, options });
+        try {
+            const { q, ...restOptions } = options;
+            const query = typeof q === 'string' ? q : '';
+            const response = await client.search(query, restOptions);
+            log.info('useSeekoraSearch: Search completed', {
+                query,
+                resultsCount: Array.isArray(response?.results) ? response.results.length : 0,
+                hasContext: !!response?.context,
+            });
+            setResults(response);
+            // Extract context from response
+            if (response.context != null) {
+                setContext(response.context);
+            }
+            return response;
+        }
+        catch (err) {
+            const error = err instanceof Error ? err : new Error(String(err));
+            log.error('useSeekoraSearch: Search failed', {
+                query,
+                error: error.message,
+                stack: error.stack,
+            });
+            setError(error);
+            setResults(null);
+            setContext(null);
+            return null;
+        }
+        finally {
+            setLoading(false);
+        }
+    }, [client]);
+    const clearResults = useCallback(() => {
+        setResults(null);
+        setError(null);
+        setContext(null);
+    }, []);
+    return {
+        search,
+        results,
+        loading,
+        error,
+        context,
+        clearResults,
+    };
+};

package/dist/hooks/useSmartSuggestions.d.ts

@@ -0,0 +1,55 @@
+/**
+ * useSmartSuggestions Hook
+ *
+ * AI-enhanced query suggestions with intent understanding
+ * Provides context-aware suggestions based on user behavior and query patterns
+ */
+export interface SmartSuggestion {
+    text: string;
+    type: 'query' | 'correction' | 'expansion' | 'related' | 'trending';
+    confidence: number;
+    metadata?: {
+        intent?: string;
+        category?: string;
+        correctedFrom?: string;
+        expandedTo?: string[];
+    };
+}
+export interface SmartSuggestionsOptions {
+    /** Minimum query length */
+    minQueryLength?: number;
+    /** Maximum suggestions to return */
+    maxSuggestions?: number;
+    /** Debounce delay in ms */
+    debounceMs?: number;
+    /** Enable spell correction */
+    enableSpellCorrection?: boolean;
+    /** Enable query expansion */
+    enableQueryExpansion?: boolean;
+    /** Enable intent detection */
+    enableIntentDetection?: boolean;
+    /** Include trending queries when query is empty */
+    includeTrending?: boolean;
+    /** User context for personalization */
+    userContext?: {
+        recentSearches?: string[];
+        preferences?: Record<string, any>;
+    };
+}
+export interface UseSmartSuggestionsReturn {
+    suggestions: SmartSuggestion[];
+    loading: boolean;
+    error: Error | null;
+    /** Detected intent from the query */
+    detectedIntent: string | null;
+    /** Suggested corrections if query has typos */
+    corrections: string[];
+    /** Expanded query terms */
+    expansions: string[];
+    /** Process a query for smart suggestions */
+    getSuggestions: (query: string) => Promise<SmartSuggestion[]>;
+    /** Clear current suggestions */
+    clear: () => void;
+}
+export declare function useSmartSuggestions(query: string, options?: SmartSuggestionsOptions): UseSmartSuggestionsReturn;
+//# sourceMappingURL=useSmartSuggestions.d.ts.map

package/dist/hooks/useSmartSuggestions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useSmartSuggestions.d.ts","sourceRoot":"","sources":["../../src/hooks/useSmartSuggestions.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAKH,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,OAAO,GAAG,YAAY,GAAG,WAAW,GAAG,SAAS,GAAG,UAAU,CAAC;IACpE,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE;QACT,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,aAAa,CAAC,EAAE,MAAM,CAAC;QACvB,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;KACvB,CAAC;CACH;AAED,MAAM,WAAW,uBAAuB;IACtC,2BAA2B;IAC3B,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,oCAAoC;IACpC,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,2BAA2B;IAC3B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,8BAA8B;IAC9B,qBAAqB,CAAC,EAAE,OAAO,CAAC;IAChC,6BAA6B;IAC7B,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAC/B,8BAA8B;IAC9B,qBAAqB,CAAC,EAAE,OAAO,CAAC;IAChC,mDAAmD;IACnD,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,uCAAuC;IACvC,WAAW,CAAC,EAAE;QACZ,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;QAC1B,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;KACnC,CAAC;CACH;AAED,MAAM,WAAW,yBAAyB;IACxC,WAAW,EAAE,eAAe,EAAE,CAAC;IAC/B,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;IACpB,qCAAqC;IACrC,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,+CAA+C;IAC/C,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,2BAA2B;IAC3B,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,4CAA4C;IAC5C,cAAc,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,eAAe,EAAE,CAAC,CAAC;IAC9D,gCAAgC;IAChC,KAAK,EAAE,MAAM,IAAI,CAAC;CACnB;AAsHD,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,uBAA4B,GACpC,yBAAyB,CA6J3B"}