@seekora-ai/ui-sdk-react 0.0.0-stage-20260517092419

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

@@ -0,0 +1 @@
+{"version":3,"file":"useQuerySuggestionsEnhanced.d.ts","sourceRoot":"","sources":["../../src/hooks/useQuerySuggestionsEnhanced.ts"],"names":[],"mappings":"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"}

package/dist/hooks/useQuerySuggestionsEnhanced.js

@@ -0,0 +1,444 @@
+/**
+ * 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) {
+    const meta = raw.metadata || {};
+    return {
+        id: raw.id || raw.objectID,
+        objectID: raw.objectID || raw.id,
+        title: raw.title || raw.name || raw.productName || meta.name || meta.productName || '',
+        name: raw.name || raw.title || meta.name || meta.productName || '',
+        image: raw.image || raw.imageUrl || meta.image || meta.image_url || meta.images?.[0] || '',
+        price: raw.price ?? raw.sellPrice ?? meta.sellPrice ?? meta.price,
+        currency: raw.currency || meta.currency || '',
+        url: raw.url || raw.productId || meta.url || meta.productId || '',
+        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, prefetch = false, debounceMs = 200, maxSuggestions = 10, minQueryLength = 1, includeDropdownRecommendations = false, includeDropdownProductList = true, includeFilteredTabs = true, includeCategories = true, includeFacets = true, // CHANGED: Enable facets by default
+    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)
+            return;
+        // When minQueryLength is 0, allow empty query so overlay can show default/trending recommendations on open
+        if (!searchQuery.trim() && minQueryLength > 0) {
+            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_dropdown_product_list: includeDropdownProductList,
+                include_filtered_tabs: includeFilteredTabs,
+                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 rawResults = response.results;
+            const secondResultHits = Array.isArray(rawResults?.[1]?.hits) ? rawResults[1].hits : [];
+            // Multi-index response: results[0]=suggestions, results[1]=product hits; expose results[1].hits as product_hits for fallback when extensions have no products
+            const productHits = secondResultHits.length > 0 ? secondResultHits.map((h) => transformProduct(h)) : [];
+            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) : [],
+                product_hits: productHits.length > 0 ? productHits : undefined,
+                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;
+            // Check if it's a 404 error (suggestions not enabled for this store).
+            // The search SDK wraps axios errors into plain Error objects with the status
+            // embedded in the message, e.g. "[getSuggestions] ... (404)".
+            const errMsg = error.message || '';
+            const is404 = err?.response?.status === 404 ||
+                err?.status === 404 ||
+                /\(404\)/.test(errMsg);
+            if (is404) {
+                // Silently handle 404 - suggestions feature not enabled
+                log.verbose('Query suggestions not enabled for this store (404)');
+                setSuggestions([]);
+                setDropdownRecommendations(null);
+                setError(null);
+            }
+            else {
+                // For other errors, log and set error state
+                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,
+        minQueryLength,
+        maxSuggestions,
+        includeDropdownRecommendations,
+        includeDropdownProductList,
+        includeFilteredTabs,
+        includeCategories,
+        includeFacets,
+        maxCategories,
+        maxFacets,
+        filteredTabs,
+        minPopularity,
+        timeRange,
+        disableTypoTolerance,
+        analyticsTags,
+        onSuggestionsLoaded,
+        onError,
+    ]);
+    // Prefetch: fire initial empty-query fetch once client is ready (before dropdown opens)
+    const prefetchedRef = useRef(false);
+    useEffect(() => {
+        if (!prefetch || prefetchedRef.current)
+            return;
+        if (minQueryLength > 0)
+            return;
+        if (!client?.getSuggestions)
+            return;
+        prefetchedRef.current = true;
+        fetchSuggestions('');
+    }, [prefetch, client, minQueryLength, fetchSuggestions]);
+    // Debounced fetch effect
+    useEffect(() => {
+        if (debounceTimerRef.current) {
+            clearTimeout(debounceTimerRef.current);
+        }
+        if (!enabled || query.length < minQueryLength) {
+            // Don't clear prefetched data when dropdown is closed
+            if (prefetch && prefetchedRef.current && query === '') {
+                // Keep prefetched data intact
+                setLoading(false);
+                setError(null);
+                return;
+            }
+            setSuggestions([]);
+            setDropdownRecommendations(null);
+            setLoading(false);
+            setError(null);
+            return;
+        }
+        // When dropdown opens with empty query and we already have prefetched data, skip re-fetch
+        if (prefetch && prefetchedRef.current && query === '') {
+            return;
+        }
+        setLoading(true);
+        debounceTimerRef.current = setTimeout(() => {
+            fetchSuggestions(query);
+        }, debounceMs);
+        return () => {
+            if (debounceTimerRef.current) {
+                clearTimeout(debounceTimerRef.current);
+            }
+        };
+    }, [query, enabled, prefetch, 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 || [];
+    // Use trending_products, then item_recommendations, then first filtered_tab's products, then results[1].hits (product_hits) so grid shows for any API shape
+    const trendingProducts = useMemo(() => {
+        const fromTrending = dropdownRecommendations?.trending_products;
+        if (fromTrending && fromTrending.length > 0)
+            return fromTrending;
+        const fromItemRecs = dropdownRecommendations?.item_recommendations;
+        if (fromItemRecs && fromItemRecs.length > 0)
+            return fromItemRecs;
+        const firstTab = dropdownRecommendations?.filtered_tabs?.[0];
+        if (firstTab?.products && firstTab.products.length > 0)
+            return firstTab.products;
+        return dropdownRecommendations?.product_hits ?? [];
+    }, [dropdownRecommendations?.trending_products, dropdownRecommendations?.item_recommendations, dropdownRecommendations?.filtered_tabs, dropdownRecommendations?.product_hits]);
+    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,
+    };
+};