@seekora-ai/ui-sdk-react 1.0.0

package/dist/hooks/useSmartSuggestions.js

@@ -0,0 +1,236 @@
+/**
+ * useSmartSuggestions Hook
+ *
+ * AI-enhanced query suggestions with intent understanding
+ * Provides context-aware suggestions based on user behavior and query patterns
+ */
+import { useState, useEffect, useCallback, useMemo, useRef } from 'react';
+import { useSearchContext } from '../components/SearchProvider';
+/**
+ * Pattern-based intent detection (client-side fallback)
+ */
+function detectIntent(query) {
+    const patterns = [
+        { pattern: /^(buy|purchase|order|get)\s+/i, intent: 'purchase' },
+        { pattern: /^(find|search|looking for|where)\s+/i, intent: 'search' },
+        { pattern: /^(compare|vs|versus)\s+/i, intent: 'compare' },
+        { pattern: /^(how (to|do)|what is|why)\s+/i, intent: 'informational' },
+        { pattern: /under\s*\$?\d+|less than\s*\$?\d+|cheap|affordable/i, intent: 'price_sensitive' },
+        { pattern: /best|top|recommended|popular/i, intent: 'recommendation' },
+        { pattern: /\d+\s*(gb|tb|inch|cm|mm|kg|lb)/i, intent: 'specification' },
+        { pattern: /(red|blue|green|black|white|pink|purple|yellow)\s+/i, intent: 'color_preference' },
+        { pattern: /(size|small|medium|large|xl|xxl)\s+/i, intent: 'size_preference' },
+    ];
+    for (const { pattern, intent } of patterns) {
+        if (pattern.test(query)) {
+            return { intent, confidence: 0.8 };
+        }
+    }
+    return null;
+}
+/**
+ * Simple Levenshtein distance for spell checking
+ */
+function levenshteinDistance(a, b) {
+    const matrix = [];
+    for (let i = 0; i <= b.length; i++) {
+        matrix[i] = [i];
+    }
+    for (let j = 0; j <= a.length; j++) {
+        matrix[0][j] = j;
+    }
+    for (let i = 1; i <= b.length; i++) {
+        for (let j = 1; j <= a.length; j++) {
+            if (b.charAt(i - 1) === a.charAt(j - 1)) {
+                matrix[i][j] = matrix[i - 1][j - 1];
+            }
+            else {
+                matrix[i][j] = Math.min(matrix[i - 1][j - 1] + 1, matrix[i][j - 1] + 1, matrix[i - 1][j] + 1);
+            }
+        }
+    }
+    return matrix[b.length][a.length];
+}
+/**
+ * Find potential corrections from a dictionary
+ */
+function findCorrections(query, dictionary, maxDistance = 2) {
+    const words = query.toLowerCase().split(/\s+/);
+    const corrections = [];
+    words.forEach(word => {
+        if (word.length < 3)
+            return;
+        dictionary.forEach(dictWord => {
+            const distance = levenshteinDistance(word, dictWord.toLowerCase());
+            if (distance > 0 && distance <= maxDistance && distance < word.length / 2) {
+                const corrected = query.replace(new RegExp(word, 'gi'), dictWord);
+                if (!corrections.includes(corrected)) {
+                    corrections.push(corrected);
+                }
+            }
+        });
+    });
+    return corrections.slice(0, 3);
+}
+/**
+ * Expand query with synonyms and related terms
+ */
+function expandQuery(query) {
+    const expansions = {
+        phone: ['smartphone', 'mobile', 'cellphone'],
+        laptop: ['notebook', 'computer', 'pc'],
+        tv: ['television', 'smart tv', 'monitor'],
+        headphones: ['earbuds', 'earphones', 'headset'],
+        shoes: ['footwear', 'sneakers', 'boots'],
+        shirt: ['top', 'blouse', 'tee'],
+        pants: ['trousers', 'jeans', 'bottoms'],
+        cheap: ['affordable', 'budget', 'inexpensive'],
+        best: ['top-rated', 'popular', 'recommended'],
+    };
+    const queryLower = query.toLowerCase();
+    const expanded = [];
+    Object.entries(expansions).forEach(([term, synonyms]) => {
+        if (queryLower.includes(term)) {
+            synonyms.forEach(syn => {
+                const exp = query.replace(new RegExp(term, 'gi'), syn);
+                if (!expanded.includes(exp)) {
+                    expanded.push(exp);
+                }
+            });
+        }
+    });
+    return expanded.slice(0, 3);
+}
+export function useSmartSuggestions(query, options = {}) {
+    const { minQueryLength = 1, maxSuggestions = 10, debounceMs = 200, enableSpellCorrection = true, enableQueryExpansion = true, enableIntentDetection = true, includeTrending = true, userContext, } = options;
+    const { stateManager } = useSearchContext();
+    const [suggestions, setSuggestions] = useState([]);
+    const [loading, setLoading] = useState(false);
+    const [error, setError] = useState(null);
+    const [detectedIntent, setDetectedIntent] = useState(null);
+    const [corrections, setCorrections] = useState([]);
+    const [expansions, setExpansions] = useState([]);
+    const debounceTimer = useRef(null);
+    // Sample dictionary for spell checking (in production, this would come from the API)
+    const dictionary = useMemo(() => [
+        'phone', 'laptop', 'computer', 'tablet', 'headphones', 'camera',
+        'television', 'speaker', 'watch', 'keyboard', 'mouse', 'monitor',
+        'shirt', 'pants', 'shoes', 'jacket', 'dress', 'skirt', 'sweater',
+        'electronics', 'clothing', 'accessories', 'furniture', 'appliances',
+    ], []);
+    const processQuery = useCallback(async (q) => {
+        const results = [];
+        // Detect intent
+        if (enableIntentDetection) {
+            const intent = detectIntent(q);
+            if (intent) {
+                setDetectedIntent(intent.intent);
+            }
+            else {
+                setDetectedIntent(null);
+            }
+        }
+        // Find spell corrections
+        if (enableSpellCorrection && q.length >= 3) {
+            const correctionResults = findCorrections(q, dictionary);
+            setCorrections(correctionResults);
+            correctionResults.forEach(correction => {
+                results.push({
+                    text: correction,
+                    type: 'correction',
+                    confidence: 0.9,
+                    metadata: { correctedFrom: q },
+                });
+            });
+        }
+        // Expand query
+        if (enableQueryExpansion) {
+            const expansionResults = expandQuery(q);
+            setExpansions(expansionResults);
+            expansionResults.forEach(exp => {
+                results.push({
+                    text: exp,
+                    type: 'expansion',
+                    confidence: 0.7,
+                    metadata: { expandedTo: [exp] },
+                });
+            });
+        }
+        // Add the original query as a suggestion
+        results.unshift({
+            text: q,
+            type: 'query',
+            confidence: 1.0,
+        });
+        // Add related suggestions based on context
+        if (userContext?.recentSearches) {
+            userContext.recentSearches
+                .filter(s => s.toLowerCase().includes(q.toLowerCase()) && s !== q)
+                .slice(0, 2)
+                .forEach(s => {
+                results.push({
+                    text: s,
+                    type: 'related',
+                    confidence: 0.6,
+                });
+            });
+        }
+        return results.slice(0, maxSuggestions);
+    }, [dictionary, enableIntentDetection, enableSpellCorrection, enableQueryExpansion, maxSuggestions, userContext]);
+    const getSuggestions = useCallback(async (q) => {
+        if (q.length < minQueryLength) {
+            return [];
+        }
+        return processQuery(q);
+    }, [minQueryLength, processQuery]);
+    // Debounced effect
+    useEffect(() => {
+        if (debounceTimer.current) {
+            clearTimeout(debounceTimer.current);
+        }
+        if (query.length < minQueryLength) {
+            setSuggestions([]);
+            setCorrections([]);
+            setExpansions([]);
+            setDetectedIntent(null);
+            return;
+        }
+        setLoading(true);
+        debounceTimer.current = setTimeout(async () => {
+            try {
+                const results = await processQuery(query);
+                setSuggestions(results);
+                setError(null);
+            }
+            catch (err) {
+                setError(err instanceof Error ? err : new Error(String(err)));
+                setSuggestions([]);
+            }
+            finally {
+                setLoading(false);
+            }
+        }, debounceMs);
+        return () => {
+            if (debounceTimer.current) {
+                clearTimeout(debounceTimer.current);
+            }
+        };
+    }, [query, minQueryLength, debounceMs, processQuery]);
+    const clear = useCallback(() => {
+        setSuggestions([]);
+        setCorrections([]);
+        setExpansions([]);
+        setDetectedIntent(null);
+        setError(null);
+    }, []);
+    return {
+        suggestions,
+        loading,
+        error,
+        detectedIntent,
+        corrections,
+        expansions,
+        getSuggestions,
+        clear,
+    };
+}

package/dist/hooks/useSuggestionsAnalytics.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Suggestions Analytics Hook
+ *
+ * Provides analytics tracking for query suggestions components:
+ * - Suggestion clicks/selections
+ * - Suggestion impressions
+ * - Product clicks from dropdown
+ * - Category/brand clicks
+ * - Search submissions from suggestions
+ */
+import type { SeekoraClient } from '@seekora-ai/search-sdk';
+import type { SuggestionItem, ProductItem, SuggestionCategory, PopularBrand, FilteredTab, RecentSearch, TrendingSearch } from '@seekora-ai/ui-sdk-types';
+export interface UseSuggestionsAnalyticsOptions {
+    /** Seekora client instance */
+    client: SeekoraClient;
+    /** Enable analytics tracking */
+    enabled?: boolean;
+    /** Analytics tags to include with all events */
+    analyticsTags?: string[];
+    /** Debounce impression events (ms) */
+    impressionDebounce?: number;
+    /** Track suggestion impressions automatically */
+    trackImpressions?: boolean;
+    /** Track clicks automatically */
+    trackClicks?: boolean;
+}
+export interface SuggestionClickEventData {
+    /** The clicked suggestion */
+    suggestion: SuggestionItem;
+    /** Position in the list (0-indexed) */
+    position: number;
+    /** Section where the suggestion appeared */
+    section?: 'suggestions' | 'trending' | 'recent' | 'related';
+    /** Original query that triggered suggestions */
+    query?: string;
+    /** Total suggestions shown */
+    totalSuggestions?: number;
+}
+export interface ProductClickEventData {
+    /** The clicked product */
+    product: ProductItem;
+    /** Position in the list (0-indexed) */
+    position: number;
+    /** Section where the product appeared */
+    section?: 'products' | 'trending' | 'recommendations' | 'filtered_tab';
+    /** Tab ID if from filtered tab */
+    tabId?: string;
+    /** Original query */
+    query?: string;
+}
+export interface SuggestionImpressionEventData {
+    /** Suggestions that were shown */
+    suggestions: SuggestionItem[];
+    /** Products that were shown */
+    products?: ProductItem[];
+    /** Categories that were shown */
+    categories?: SuggestionCategory[];
+    /** Brands that were shown */
+    brands?: PopularBrand[];
+    /** Original query */
+    query: string;
+    /** Timestamp when impressions occurred */
+    timestamp: number;
+}
+export interface UseSuggestionsAnalyticsReturn {
+    /** Track a suggestion click */
+    trackSuggestionClick: (data: SuggestionClickEventData) => void;
+    /** Track a product click from suggestions dropdown */
+    trackProductClick: (data: ProductClickEventData) => void;
+    /** Track a category click */
+    trackCategoryClick: (category: SuggestionCategory, query?: string) => void;
+    /** Track a brand click */
+    trackBrandClick: (brand: PopularBrand, query?: string) => void;
+    /** Track a tab selection */
+    trackTabSelect: (tab: FilteredTab, query?: string) => void;
+    /** Track recent search click */
+    trackRecentSearchClick: (search: RecentSearch) => void;
+    /** Track trending search click */
+    trackTrendingClick: (trending: TrendingSearch, position: number) => void;
+    /** Track suggestions impression */
+    trackImpression: (data: SuggestionImpressionEventData) => void;
+    /** Track search submission from suggestion */
+    trackSearchSubmit: (query: string, fromSuggestion: boolean, suggestion?: SuggestionItem) => void;
+    /** Track dropdown open */
+    trackDropdownOpen: (query: string) => void;
+    /** Track dropdown close */
+    trackDropdownClose: (query: string, selectedSuggestion?: string) => void;
+}
+export declare function useSuggestionsAnalytics(options: UseSuggestionsAnalyticsOptions): UseSuggestionsAnalyticsReturn;
+export default useSuggestionsAnalytics;
+//# sourceMappingURL=useSuggestionsAnalytics.d.ts.map

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

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

package/dist/hooks/useSuggestionsAnalytics.js

@@ -0,0 +1,226 @@
+/**
+ * Suggestions Analytics Hook
+ *
+ * Provides analytics tracking for query suggestions components:
+ * - Suggestion clicks/selections
+ * - Suggestion impressions
+ * - Product clicks from dropdown
+ * - Category/brand clicks
+ * - Search submissions from suggestions
+ */
+import { useCallback, useRef, useEffect } from 'react';
+import { log } from '@seekora-ai/ui-sdk-core';
+// ============================================================================
+// Event Names
+// ============================================================================
+const EVENTS = {
+    SUGGESTION_CLICK: 'suggestions.click',
+    SUGGESTION_IMPRESSION: 'suggestions.impression',
+    PRODUCT_CLICK: 'suggestions.product_click',
+    CATEGORY_CLICK: 'suggestions.category_click',
+    BRAND_CLICK: 'suggestions.brand_click',
+    TAB_SELECT: 'suggestions.tab_select',
+    RECENT_CLICK: 'suggestions.recent_click',
+    TRENDING_CLICK: 'suggestions.trending_click',
+    SEARCH_SUBMIT: 'suggestions.search_submit',
+    DROPDOWN_OPEN: 'suggestions.dropdown_open',
+    DROPDOWN_CLOSE: 'suggestions.dropdown_close',
+};
+// ============================================================================
+// Hook Implementation
+// ============================================================================
+export function useSuggestionsAnalytics(options) {
+    const { client, enabled = true, analyticsTags = [], impressionDebounce = 500, trackImpressions = true, trackClicks = true, } = options;
+    // Refs for debouncing and tracking
+    const impressionTimerRef = useRef(null);
+    const lastImpressionRef = useRef(null);
+    const dropdownOpenTimeRef = useRef(null);
+    // Cleanup on unmount
+    useEffect(() => {
+        return () => {
+            if (impressionTimerRef.current) {
+                clearTimeout(impressionTimerRef.current);
+            }
+        };
+    }, []);
+    // Helper to send event
+    const sendEvent = useCallback(async (eventName, metadata) => {
+        if (!enabled || !client)
+            return;
+        try {
+            await client.trackEvent?.({
+                event_name: eventName,
+                analytics_tags: analyticsTags,
+                metadata: {
+                    ...metadata,
+                    timestamp: Date.now(),
+                    source: 'suggestions_dropdown',
+                },
+            });
+            log.verbose(`Analytics: ${eventName}`, metadata);
+        }
+        catch (error) {
+            log.warn(`Failed to track ${eventName}`, { error });
+        }
+    }, [client, enabled, analyticsTags]);
+    // Track suggestion click
+    const trackSuggestionClick = useCallback((data) => {
+        if (!trackClicks)
+            return;
+        sendEvent(EVENTS.SUGGESTION_CLICK, {
+            suggestion_query: data.suggestion.query,
+            suggestion_id: data.suggestion.objectID,
+            suggestion_popularity: data.suggestion.popularity,
+            position: data.position,
+            section: data.section || 'suggestions',
+            original_query: data.query,
+            total_suggestions: data.totalSuggestions,
+        });
+    }, [sendEvent, trackClicks]);
+    // Track product click
+    const trackProductClick = useCallback((data) => {
+        if (!trackClicks)
+            return;
+        sendEvent(EVENTS.PRODUCT_CLICK, {
+            product_id: data.product.id || data.product.objectID,
+            product_title: data.product.title || data.product.name,
+            product_price: data.product.price,
+            position: data.position,
+            section: data.section || 'products',
+            tab_id: data.tabId,
+            original_query: data.query,
+        });
+        // Also track as a general product click for analytics
+        if (client) {
+            Promise.resolve(client.trackClick?.(data.product.id || data.product.objectID || '', data.position + 1)).catch(() => { });
+        }
+    }, [client, sendEvent, trackClicks]);
+    // Track category click
+    const trackCategoryClick = useCallback((category, query) => {
+        if (!trackClicks)
+            return;
+        sendEvent(EVENTS.CATEGORY_CLICK, {
+            category_value: category.value,
+            category_count: category.count,
+            category_path: category.path,
+            original_query: query,
+        });
+    }, [sendEvent, trackClicks]);
+    // Track brand click
+    const trackBrandClick = useCallback((brand, query) => {
+        if (!trackClicks)
+            return;
+        sendEvent(EVENTS.BRAND_CLICK, {
+            brand_name: brand.name,
+            brand_count: brand.count,
+            original_query: query,
+        });
+    }, [sendEvent, trackClicks]);
+    // Track tab selection
+    const trackTabSelect = useCallback((tab, query) => {
+        sendEvent(EVENTS.TAB_SELECT, {
+            tab_id: tab.id,
+            tab_label: tab.label,
+            tab_filter: tab.filter,
+            products_count: tab.products?.length || 0,
+            nb_hits: tab.nb_hits,
+            original_query: query,
+        });
+    }, [sendEvent]);
+    // Track recent search click
+    const trackRecentSearchClick = useCallback((search) => {
+        if (!trackClicks)
+            return;
+        sendEvent(EVENTS.RECENT_CLICK, {
+            query: search.query,
+            original_timestamp: search.timestamp,
+            results_count: search.resultsCount,
+        });
+    }, [sendEvent, trackClicks]);
+    // Track trending click
+    const trackTrendingClick = useCallback((trending, position) => {
+        if (!trackClicks)
+            return;
+        sendEvent(EVENTS.TRENDING_CLICK, {
+            query: trending.query,
+            count: trending.count,
+            trend_score: trending.trend_score,
+            position,
+        });
+    }, [sendEvent, trackClicks]);
+    // Track impression (debounced)
+    const trackImpression = useCallback((data) => {
+        if (!trackImpressions)
+            return;
+        // Create a hash of the impression to avoid duplicates
+        const impressionHash = `${data.query}:${data.suggestions.length}:${data.products?.length || 0}`;
+        if (impressionHash === lastImpressionRef.current)
+            return;
+        // Clear existing timer
+        if (impressionTimerRef.current) {
+            clearTimeout(impressionTimerRef.current);
+        }
+        // Debounce the impression
+        impressionTimerRef.current = setTimeout(() => {
+            lastImpressionRef.current = impressionHash;
+            sendEvent(EVENTS.SUGGESTION_IMPRESSION, {
+                query: data.query,
+                suggestions_count: data.suggestions.length,
+                suggestions: data.suggestions.slice(0, 10).map((s, i) => ({
+                    query: s.query,
+                    position: i,
+                    popularity: s.popularity,
+                })),
+                products_count: data.products?.length || 0,
+                categories_count: data.categories?.length || 0,
+                brands_count: data.brands?.length || 0,
+                impression_timestamp: data.timestamp,
+            });
+        }, impressionDebounce);
+    }, [sendEvent, trackImpressions, impressionDebounce]);
+    // Track search submit
+    const trackSearchSubmit = useCallback((query, fromSuggestion, suggestion) => {
+        sendEvent(EVENTS.SEARCH_SUBMIT, {
+            query,
+            from_suggestion: fromSuggestion,
+            suggestion_query: suggestion?.query,
+            suggestion_id: suggestion?.objectID,
+            suggestion_popularity: suggestion?.popularity,
+        });
+    }, [sendEvent]);
+    // Track dropdown open
+    const trackDropdownOpen = useCallback((query) => {
+        dropdownOpenTimeRef.current = Date.now();
+        sendEvent(EVENTS.DROPDOWN_OPEN, {
+            query,
+            has_query: query.length > 0,
+        });
+    }, [sendEvent]);
+    // Track dropdown close
+    const trackDropdownClose = useCallback((query, selectedSuggestion) => {
+        const duration = dropdownOpenTimeRef.current
+            ? Date.now() - dropdownOpenTimeRef.current
+            : null;
+        sendEvent(EVENTS.DROPDOWN_CLOSE, {
+            query,
+            selected_suggestion: selectedSuggestion,
+            had_selection: !!selectedSuggestion,
+            duration_ms: duration,
+        });
+        dropdownOpenTimeRef.current = null;
+    }, [sendEvent]);
+    return {
+        trackSuggestionClick,
+        trackProductClick,
+        trackCategoryClick,
+        trackBrandClick,
+        trackTabSelect,
+        trackRecentSearchClick,
+        trackTrendingClick,
+        trackImpression,
+        trackSearchSubmit,
+        trackDropdownOpen,
+        trackDropdownClose,
+    };
+}
+export default useSuggestionsAnalytics;

package/dist/index.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Seekora UI SDK
+ *
+ * Main entry point for the UI Components Library
+ */
+export { SearchBar } from './components/SearchBar';
+export { SearchResults } from './components/SearchResults';
+export { SearchProvider, useSearchContext } from './components/SearchProvider';
+export { Stats } from './components/Stats';
+export { Pagination } from './components/Pagination';
+export { SortBy } from './components/SortBy';
+export { Facets } from './components/Facets';
+export { CurrentRefinements } from './components/CurrentRefinements';
+export { ClearRefinements } from './components/ClearRefinements';
+export { SearchLayout } from './components/SearchLayout';
+export { RangeInput } from './components/RangeInput';
+export { HitsPerPage } from './components/HitsPerPage';
+export { InfiniteHits } from './components/InfiniteHits';
+export { Highlight, Snippet } from './components/Highlight';
+export { HierarchicalMenu } from './components/HierarchicalMenu';
+export { RangeSlider } from './components/RangeSlider';
+export { Breadcrumb } from './components/Breadcrumb';
+export { MobileFilters, MobileFiltersButton } from './components/MobileFilters';
+export { RelatedProducts, TrendingItems, FrequentlyBoughtTogether, RecentlyViewed, addToRecentlyViewed, } from './components/Recommendations';
+export { QuerySuggestions } from './components/QuerySuggestions';
+export { QuerySuggestionsDropdown } from './components/QuerySuggestionsDropdown';
+export { RichQuerySuggestions } from './components/RichQuerySuggestions';
+export { FederatedDropdown } from './components/FederatedDropdown';
+export { SearchBarWithSuggestions } from './components/SearchBarWithSuggestions';
+export { SuggestionSearchBar, // All-in-one: input + dropdown + data fetching
+type SuggestionSearchBarProps, type SuggestionSearchBarRef, } from './components/suggestions';
+export { AmazonDropdown, // Amazon-style with department scoping
+GoogleDropdown, // Google-style clean search
+PinterestDropdown, // Visual discovery style
+SpotlightDropdown, // macOS Spotlight / Command palette
+ShopifyDropdown, // Modern e-commerce
+MobileSheetDropdown, // Mobile-first bottom sheet
+MinimalDropdown, // Ultra-clean editorial style
+SuggestionDropdownVariants, type SuggestionDropdownVariant, type BaseDropdownProps, type DropdownRef, type SuggestionFieldMapping, type ProductFieldMapping, type CategoryFieldMapping, type BrandFieldMapping, type SectionConfig, type ProductDisplayConfig, type SuggestionDisplayConfig, type DropdownThemeConfig, type AnalyticsConfig, type DropdownEventHandlers, type DropdownClassNames, extractSuggestion, extractProduct, extractCategory, extractBrand, formatPrice as formatSuggestionPrice, highlightText, getRecentSearches, addRecentSearch, removeRecentSearch, clearRecentSearches, useResponsive, breakpoints, mediaQueries, touchTargets, injectGlobalResponsiveStyles, useInjectResponsiveStyles, type ResponsiveState, } from './components/suggestions';
+export { useSeekoraSearch } from './hooks/useSeekoraSearch';
+export { useQuerySuggestions } from './hooks/useQuerySuggestions';
+export { useQuerySuggestionsEnhanced } from './hooks/useQuerySuggestionsEnhanced';
+export { useSuggestionsAnalytics } from './hooks/useSuggestionsAnalytics';
+export { useAnalytics } from './hooks/useAnalytics';
+export { useSearchState } from './hooks/useSearchState';
+export { useSmartSuggestions } from './hooks/useSmartSuggestions';
+export { useNaturalLanguageFilters, formatParsedFilters } from './hooks/useNaturalLanguageFilters';
+export type { SearchBarProps, SearchBarTheme, } from './components/SearchBar';
+export type { SearchResultsProps, SearchResultsTheme } from './components/SearchResults';
+export type { ResultItem, FieldMapping, ViewMode } from '@seekora-ai/ui-sdk-types';
+export type { QuerySuggestionsProps, QuerySuggestionsTheme, SuggestionItem, } from './components/QuerySuggestions';
+export type { QuerySuggestionsDropdownProps, QuerySuggestionsDropdownRef, } from './components/QuerySuggestionsDropdown';
+export type { RichQuerySuggestionsProps, RichQuerySuggestionsRef, } from './components/RichQuerySuggestions';
+export type { FederatedDropdownProps, FederatedDropdownRef, } from './components/FederatedDropdown';
+export type { SearchBarWithSuggestionsProps, SearchBarWithSuggestionsRef, } from './components/SearchBarWithSuggestions';
+export type { SearchProviderProps, } from './components/SearchProvider';
+export type { ClearRefinementsProps, ClearRefinementsTheme, } from './components/ClearRefinements';
+export type { HitsPerPageProps, HitsPerPageTheme, HitsPerPageItem, } from './components/HitsPerPage';
+export type { InfiniteHitsProps, InfiniteHitsTheme, } from './components/InfiniteHits';
+export type { HighlightProps, HighlightTheme, SnippetProps, SnippetTheme, } from './components/Highlight';
+export type { HierarchicalMenuProps, HierarchicalMenuTheme, HierarchicalMenuItem, } from './components/HierarchicalMenu';
+export type { RangeSliderProps, RangeSliderTheme, } from './components/RangeSlider';
+export type { BreadcrumbProps, BreadcrumbTheme, BreadcrumbItem, } from './components/Breadcrumb';
+export type { MobileFiltersProps, MobileFiltersTheme, MobileFiltersButtonProps, } from './components/MobileFilters';
+export type { RelatedProductsProps, TrendingItemsProps, FrequentlyBoughtTogetherProps, RecentlyViewedProps, RecommendationItem, RecommendationTheme, } from './components/Recommendations';
+export type { UseQuerySuggestionsEnhancedOptions, UseQuerySuggestionsEnhancedReturn, NavigableItem, } from './hooks/useQuerySuggestionsEnhanced';
+export type { UseSuggestionsAnalyticsOptions, UseSuggestionsAnalyticsReturn, SuggestionClickEventData, ProductClickEventData, SuggestionImpressionEventData, } from './hooks/useSuggestionsAnalytics';
+export type { SmartSuggestion, SmartSuggestionsOptions, UseSmartSuggestionsReturn, } from './hooks/useSmartSuggestions';
+export type { ParsedFilter, NaturalLanguageResult, NaturalLanguageFiltersOptions, } from './hooks/useNaturalLanguageFilters';
+export type { Theme, ThemeConfig, } from './themes/types';
+export { defaultTheme } from './themes/default';
+export { darkTheme } from './themes/dark';
+export { minimalTheme } from './themes/minimal';
+export { lightThemeVariables, darkThemeVariables, minimalThemeVariables, brandPresets, createSuggestionsTheme, generateSuggestionsStylesheet, injectSuggestionsStyles, updateSuggestionsStyles, } from './themes/suggestions';
+export type { SuggestionsThemeVariables } from './themes/suggestions';
+export { createTheme } from './themes/createTheme';
+export { mergeThemes } from './themes/mergeThemes';
+export { getSuggestionsCache, createSuggestionsCache, clearSuggestionsCache, } from './components/suggestions/utils';
+export type { SuggestionsCache } from './components/suggestions/utils';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

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