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

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"}

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,93 @@
+/**
+ * Suggestions Analytics Hook
+ *
+ * Provides analytics tracking for query suggestions components using
+ * Analytics V3 event structure and schema/fields (event_name, event_ts,
+ * correlation_id/search_id via context, and V3 top-level fields such as
+ * original_query, position, section, clicked_item_id, click_type, tab_id,
+ * suggestions_count, etc.). All events are sent via client.trackEvent(payload, context)
+ * so the SDK can attach correlation_id, search_id, event_ts, orgcode, xstoreid.
+ */
+import type { SeekoraClient, SearchContext } 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;
+    /** Optional search context (correlationId, searchId) to attach to events when available */
+    context?: SearchContext | Partial<SearchContext>;
+}
+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,239 @@
+/**
+ * Suggestions Analytics Hook
+ *
+ * Provides analytics tracking for query suggestions components using
+ * Analytics V3 event structure and schema/fields (event_name, event_ts,
+ * correlation_id/search_id via context, and V3 top-level fields such as
+ * original_query, position, section, clicked_item_id, click_type, tab_id,
+ * suggestions_count, etc.). All events are sent via client.trackEvent(payload, context)
+ * so the SDK can attach correlation_id, search_id, event_ts, orgcode, xstoreid.
+ */
+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',
+    // Variant & product interaction events
+    VARIANT_SELECT: 'product.variant_select',
+    VARIANT_HOVER: 'product.variant_hover',
+    ADD_TO_CART: 'product.add_to_cart',
+    PRODUCT_IMPRESSION: 'product.impression',
+    SWATCH_CLICK: 'product.swatch_click',
+};
+// ============================================================================
+// Hook Implementation
+// ============================================================================
+export function useSuggestionsAnalytics(options) {
+    const { client, enabled = true, analyticsTags = [], impressionDebounce = 500, trackImpressions = true, trackClicks = true, context: contextOption, } = 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 (optional context links event to search for v3 analytics)
+    const sendEvent = useCallback(async (eventName, metadata, context) => {
+        if (!enabled || !client)
+            return;
+        const searchContext = context ?? contextOption;
+        try {
+            // Extract query for search-related events (backend requires query at top level for search events)
+            const { query, ...restMetadata } = metadata;
+            const isSearchEvent = eventName.includes('search') || eventName === EVENTS.SEARCH_SUBMIT;
+            await client.trackEvent?.({
+                event_name: eventName,
+                analytics_tags: analyticsTags,
+                // Include query at top level for search events
+                ...(isSearchEvent && query ? { query } : {}),
+                metadata: {
+                    ...restMetadata,
+                    timestamp: Date.now(),
+                    source: 'suggestions_dropdown',
+                },
+            }, searchContext);
+            log.verbose(`Analytics: ${eventName}`, metadata);
+        }
+        catch (error) {
+            log.warn(`Failed to track ${eventName}`, { error });
+        }
+    }, [client, enabled, analyticsTags, contextOption]);
+    // 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 (with context when available)
+        const searchContext = contextOption;
+        if (client?.trackClick) {
+            Promise.resolve(client.trackClick(data.product.id || data.product.objectID || '', data.position + 1, searchContext)).catch(() => { });
+        }
+    }, [client, contextOption, 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/hooks/useVariantSelection.d.ts

@@ -0,0 +1,28 @@
+/**
+ * useVariantSelection – manages variant selection state
+ *
+ * Single source of truth for variant interactions on product pages.
+ * Cards display variants passively; product pages use this hook.
+ */
+import type { ProductOption, ProductVariant } from '@seekora-ai/ui-sdk-types';
+export interface UseVariantSelectionOptions {
+    options?: ProductOption[];
+    variants?: ProductVariant[];
+    initialSelections?: Record<string, string>;
+    onVariantChange?: (variant: ProductVariant | null, selections: Record<string, string>) => void;
+}
+export interface UseVariantSelectionReturn {
+    selections: Record<string, string>;
+    setSelection: (optionName: string, value: string) => void;
+    resetSelections: () => void;
+    selectedVariant: ProductVariant | null;
+    availableValues: Record<string, {
+        value: string;
+        available: boolean;
+    }[]>;
+    isComplete: boolean;
+    effectivePrice: number | null;
+    effectiveComparePrice: number | null;
+}
+export declare function useVariantSelection({ options, variants, initialSelections, onVariantChange, }?: UseVariantSelectionOptions): UseVariantSelectionReturn;
+//# sourceMappingURL=useVariantSelection.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"useVariantSelection.d.ts","sourceRoot":"","sources":["../../src/hooks/useVariantSelection.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAG9E,MAAM,WAAW,0BAA0B;IACzC,OAAO,CAAC,EAAE,aAAa,EAAE,CAAC;IAC1B,QAAQ,CAAC,EAAE,cAAc,EAAE,CAAC;IAC5B,iBAAiB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC3C,eAAe,CAAC,EAAE,CAAC,OAAO,EAAE,cAAc,GAAG,IAAI,EAAE,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,KAAK,IAAI,CAAC;CAChG;AAED,MAAM,WAAW,yBAAyB;IACxC,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACnC,YAAY,EAAE,CAAC,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IAC1D,eAAe,EAAE,MAAM,IAAI,CAAC;IAC5B,eAAe,EAAE,cAAc,GAAG,IAAI,CAAC;IACvC,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,OAAO,CAAA;KAAE,EAAE,CAAC,CAAC;IACzE,UAAU,EAAE,OAAO,CAAC;IACpB,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,qBAAqB,EAAE,MAAM,GAAG,IAAI,CAAC;CACtC;AAED,wBAAgB,mBAAmB,CAAC,EAClC,OAAY,EACZ,QAAa,EACb,iBAAsB,EACtB,eAAe,GAChB,GAAE,0BAA+B,GAAG,yBAAyB,CAwD7D"}