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

package/dist/hooks/useNaturalLanguageFilters.d.ts

@@ -0,0 +1,48 @@
+/**
+ * useNaturalLanguageFilters Hook
+ *
+ * Convert natural language queries to structured filters
+ * Examples:
+ * - "red shirts under $50" → color: red, category: shirts, price: <= 50
+ * - "size large blue jeans" → size: L, color: blue, category: jeans
+ */
+export interface ParsedFilter {
+    field: string;
+    value: string;
+    operator: '=' | '>' | '<' | '>=' | '<=' | 'contains';
+    confidence: number;
+    matchedText: string;
+}
+export interface NaturalLanguageResult {
+    /** Cleaned query with filter terms removed */
+    cleanedQuery: string;
+    /** Extracted filters */
+    filters: ParsedFilter[];
+    /** Original query */
+    originalQuery: string;
+    /** Whether any filters were detected */
+    hasFilters: boolean;
+}
+export interface NaturalLanguageFiltersOptions {
+    /** Custom field mappings */
+    fieldMappings?: Record<string, string>;
+    /** Custom value mappings */
+    valueMappings?: Record<string, Record<string, string>>;
+    /** Whether to auto-apply filters to search state */
+    autoApply?: boolean;
+    /** Currency symbol for price parsing */
+    currencySymbol?: string;
+}
+export declare function useNaturalLanguageFilters(options?: NaturalLanguageFiltersOptions): {
+    /** Parse a natural language query */
+    parse: (query: string) => NaturalLanguageResult;
+    /** Apply parsed filters to search state */
+    applyFilters: (filters: ParsedFilter[]) => void;
+    /** Parse and apply in one step */
+    parseAndApply: (query: string) => NaturalLanguageResult;
+};
+/**
+ * Utility to format parsed filters for display
+ */
+export declare function formatParsedFilters(filters: ParsedFilter[]): string;
+//# sourceMappingURL=useNaturalLanguageFilters.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"useNaturalLanguageFilters.d.ts","sourceRoot":"","sources":["../../src/hooks/useNaturalLanguageFilters.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAKH,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,IAAI,GAAG,IAAI,GAAG,UAAU,CAAC;IACrD,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,qBAAqB;IACpC,8CAA8C;IAC9C,YAAY,EAAE,MAAM,CAAC;IACrB,wBAAwB;IACxB,OAAO,EAAE,YAAY,EAAE,CAAC;IACxB,qBAAqB;IACrB,aAAa,EAAE,MAAM,CAAC;IACtB,wCAAwC;IACxC,UAAU,EAAE,OAAO,CAAC;CACrB;AAED,MAAM,WAAW,6BAA6B;IAC5C,4BAA4B;IAC5B,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACvC,4BAA4B;IAC5B,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACvD,oDAAoD;IACpD,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,wCAAwC;IACxC,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAsDD,wBAAgB,yBAAyB,CACvC,OAAO,GAAE,6BAAkC,GAC1C;IACD,qCAAqC;IACrC,KAAK,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,qBAAqB,CAAC;IAChD,2CAA2C;IAC3C,YAAY,EAAE,CAAC,OAAO,EAAE,YAAY,EAAE,KAAK,IAAI,CAAC;IAChD,kCAAkC;IAClC,aAAa,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,qBAAqB,CAAC;CACzD,CA8KA;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,YAAY,EAAE,GAAG,MAAM,CAInE"}

package/dist/hooks/useNaturalLanguageFilters.js

@@ -0,0 +1,221 @@
+/**
+ * useNaturalLanguageFilters Hook
+ *
+ * Convert natural language queries to structured filters
+ * Examples:
+ * - "red shirts under $50" → color: red, category: shirts, price: <= 50
+ * - "size large blue jeans" → size: L, color: blue, category: jeans
+ */
+import { useMemo, useCallback } from 'react';
+import { useSearchState } from './useSearchState';
+// Default patterns for parsing natural language
+const DEFAULT_PATTERNS = {
+    // Price patterns
+    price: [
+        { pattern: /under\s*\$?(\d+(?:\.\d{2})?)/i, operator: '<=', field: 'price' },
+        { pattern: /less than\s*\$?(\d+(?:\.\d{2})?)/i, operator: '<', field: 'price' },
+        { pattern: /over\s*\$?(\d+(?:\.\d{2})?)/i, operator: '>=', field: 'price' },
+        { pattern: /more than\s*\$?(\d+(?:\.\d{2})?)/i, operator: '>', field: 'price' },
+        { pattern: /\$(\d+(?:\.\d{2})?)\s*-\s*\$?(\d+(?:\.\d{2})?)/i, operator: 'range', field: 'price' },
+        { pattern: /between\s*\$?(\d+(?:\.\d{2})?)\s*and\s*\$?(\d+(?:\.\d{2})?)/i, operator: 'range', field: 'price' },
+        { pattern: /\$(\d+(?:\.\d{2})?)/i, operator: '<=', field: 'price' },
+    ],
+    // Color patterns
+    colors: ['red', 'blue', 'green', 'black', 'white', 'pink', 'purple', 'yellow', 'orange', 'brown', 'gray', 'grey', 'navy', 'beige', 'gold', 'silver'],
+    // Size patterns
+    sizes: {
+        'extra small': 'XS',
+        'xs': 'XS',
+        'small': 'S',
+        's': 'S',
+        'medium': 'M',
+        'm': 'M',
+        'large': 'L',
+        'l': 'L',
+        'extra large': 'XL',
+        'xl': 'XL',
+        'xxl': 'XXL',
+        '2xl': 'XXL',
+        'xxxl': 'XXXL',
+        '3xl': 'XXXL',
+    },
+    // Brand patterns (common examples)
+    brandIndicators: ['by', 'from', 'brand'],
+    // Rating patterns
+    ratings: [
+        { pattern: /(\d+)\s*\+?\s*stars?/i, field: 'rating', operator: '>=' },
+        { pattern: /rated\s*(\d+)/i, field: 'rating', operator: '>=' },
+        { pattern: /top\s*rated/i, field: 'rating', value: '4', operator: '>=' },
+    ],
+    // Availability patterns
+    availability: [
+        { pattern: /in\s*stock/i, field: 'inStock', value: 'true' },
+        { pattern: /available/i, field: 'inStock', value: 'true' },
+        { pattern: /on\s*sale/i, field: 'onSale', value: 'true' },
+    ],
+};
+export function useNaturalLanguageFilters(options = {}) {
+    const { fieldMappings = {}, valueMappings = {}, autoApply = false, currencySymbol = '$', } = options;
+    const { addRefinement, removeRefinement, clearRefinements, setQuery } = useSearchState();
+    // Merge default patterns with custom mappings
+    const patterns = useMemo(() => ({
+        ...DEFAULT_PATTERNS,
+        colors: [...DEFAULT_PATTERNS.colors, ...(valueMappings.color ? Object.keys(valueMappings.color) : [])],
+        sizes: { ...DEFAULT_PATTERNS.sizes, ...(valueMappings.size || {}) },
+    }), [valueMappings]);
+    const parse = useCallback((query) => {
+        const filters = [];
+        let cleanedQuery = query;
+        // Parse price filters
+        for (const pricePattern of patterns.price) {
+            const match = query.match(pricePattern.pattern);
+            if (match) {
+                if (pricePattern.operator === 'range' && match[2]) {
+                    // Handle price range
+                    filters.push({
+                        field: fieldMappings.price || 'price',
+                        value: `>=${match[1]}`,
+                        operator: '>=',
+                        confidence: 0.95,
+                        matchedText: match[0],
+                    });
+                    filters.push({
+                        field: fieldMappings.price || 'price',
+                        value: `<=${match[2]}`,
+                        operator: '<=',
+                        confidence: 0.95,
+                        matchedText: match[0],
+                    });
+                }
+                else if (match[1]) {
+                    filters.push({
+                        field: fieldMappings.price || 'price',
+                        value: `${pricePattern.operator}${match[1]}`,
+                        operator: pricePattern.operator,
+                        confidence: 0.95,
+                        matchedText: match[0],
+                    });
+                }
+                cleanedQuery = cleanedQuery.replace(match[0], ' ');
+                break; // Only match first price pattern
+            }
+        }
+        // Parse colors
+        const colorRegex = new RegExp(`\\b(${patterns.colors.join('|')})\\b`, 'gi');
+        const colorMatches = query.match(colorRegex);
+        if (colorMatches) {
+            colorMatches.forEach(color => {
+                const normalizedColor = valueMappings.color?.[color.toLowerCase()] || color.toLowerCase();
+                filters.push({
+                    field: fieldMappings.color || 'color',
+                    value: normalizedColor,
+                    operator: '=',
+                    confidence: 0.9,
+                    matchedText: color,
+                });
+                cleanedQuery = cleanedQuery.replace(new RegExp(`\\b${color}\\b`, 'gi'), ' ');
+            });
+        }
+        // Parse sizes
+        const sizeEntries = Object.entries(patterns.sizes);
+        for (const [sizeText, sizeValue] of sizeEntries) {
+            const sizeRegex = new RegExp(`\\b${sizeText}\\b`, 'gi');
+            if (sizeRegex.test(query)) {
+                filters.push({
+                    field: fieldMappings.size || 'size',
+                    value: sizeValue,
+                    operator: '=',
+                    confidence: 0.85,
+                    matchedText: sizeText,
+                });
+                cleanedQuery = cleanedQuery.replace(sizeRegex, ' ');
+                break; // Only match first size
+            }
+        }
+        // Parse ratings
+        for (const ratingPattern of patterns.ratings) {
+            if ('value' in ratingPattern) {
+                if (ratingPattern.pattern.test(query)) {
+                    filters.push({
+                        field: fieldMappings.rating || ratingPattern.field,
+                        value: `${ratingPattern.operator}${ratingPattern.value}`,
+                        operator: ratingPattern.operator,
+                        confidence: 0.8,
+                        matchedText: query.match(ratingPattern.pattern)?.[0] || '',
+                    });
+                    cleanedQuery = cleanedQuery.replace(ratingPattern.pattern, ' ');
+                }
+            }
+            else {
+                const match = query.match(ratingPattern.pattern);
+                if (match && match[1]) {
+                    filters.push({
+                        field: fieldMappings.rating || ratingPattern.field,
+                        value: `${ratingPattern.operator}${match[1]}`,
+                        operator: ratingPattern.operator,
+                        confidence: 0.85,
+                        matchedText: match[0],
+                    });
+                    cleanedQuery = cleanedQuery.replace(match[0], ' ');
+                }
+            }
+        }
+        // Parse availability
+        for (const availPattern of patterns.availability) {
+            if (availPattern.pattern.test(query)) {
+                filters.push({
+                    field: fieldMappings[availPattern.field] || availPattern.field,
+                    value: availPattern.value,
+                    operator: '=',
+                    confidence: 0.9,
+                    matchedText: query.match(availPattern.pattern)?.[0] || '',
+                });
+                cleanedQuery = cleanedQuery.replace(availPattern.pattern, ' ');
+            }
+        }
+        // Clean up the query
+        cleanedQuery = cleanedQuery
+            .replace(/\s+/g, ' ')
+            .trim();
+        return {
+            cleanedQuery,
+            filters,
+            originalQuery: query,
+            hasFilters: filters.length > 0,
+        };
+    }, [patterns, fieldMappings, valueMappings]);
+    const applyFilters = useCallback((filters) => {
+        filters.forEach(filter => {
+            addRefinement(filter.field, filter.value, false);
+        });
+        // Trigger search after all filters are added
+        if (filters.length > 0) {
+            // The last addRefinement with triggerSearch=true would be called
+            // But we add them all with false and rely on the query change to trigger
+        }
+    }, [addRefinement]);
+    const parseAndApply = useCallback((query) => {
+        const result = parse(query);
+        if (result.hasFilters) {
+            applyFilters(result.filters);
+            // Update the query to the cleaned version
+            if (result.cleanedQuery !== query) {
+                setQuery(result.cleanedQuery, true);
+            }
+        }
+        return result;
+    }, [parse, applyFilters, setQuery]);
+    return {
+        parse,
+        applyFilters,
+        parseAndApply,
+    };
+}
+/**
+ * Utility to format parsed filters for display
+ */
+export function formatParsedFilters(filters) {
+    return filters
+        .map(f => `${f.field}: ${f.value}`)
+        .join(', ');
+}

package/dist/hooks/useProductAnalytics.d.ts

@@ -0,0 +1,49 @@
+/**
+ * useProductAnalytics – analytics event binding hook for custom components
+ *
+ * Returns event handler props ready to spread onto any element, plus imperative
+ * tracking methods. Builds on existing useAnalytics infrastructure.
+ */
+import type { SeekoraClient, SearchContext } from '@seekora-ai/search-sdk';
+import type { ProductItem, ProductVariant } from '@seekora-ai/ui-sdk-types';
+export interface UseProductAnalyticsOptions {
+    client: SeekoraClient;
+    product: ProductItem;
+    position?: number;
+    section?: string;
+    tabId?: string;
+    query?: string;
+    context?: SearchContext | Partial<SearchContext>;
+    enabled?: boolean;
+}
+export interface UseProductAnalyticsReturn {
+    /** Spread onto any clickable element to track product click */
+    clickProps: {
+        onClick: (e?: React.MouseEvent) => void;
+        'data-seekora-product-id': string;
+        'data-seekora-position': number;
+    };
+    /** Spread onto any element to track variant selection */
+    variantSelectProps: (optionName: string, value: string) => {
+        onClick: (e?: React.MouseEvent) => void;
+        'data-seekora-variant-option': string;
+        'data-seekora-variant-value': string;
+    };
+    /** Spread onto any element to track add-to-cart */
+    addToCartProps: (variant?: ProductVariant) => {
+        onClick: (e?: React.MouseEvent) => void;
+        'data-seekora-action': 'add-to-cart';
+    };
+    /** Spread onto any element to track impression (uses IntersectionObserver) */
+    impressionRef: React.RefCallback<HTMLElement>;
+    /** Imperative: track product click */
+    trackClick: () => void;
+    /** Imperative: track variant select */
+    trackVariantSelect: (optionName: string, value: string) => void;
+    /** Imperative: track add to cart */
+    trackAddToCart: (variant?: ProductVariant) => void;
+    /** Imperative: track custom event with product context */
+    trackCustomEvent: (eventName: string, metadata?: Record<string, any>) => void;
+}
+export declare function useProductAnalytics({ client, product, position, section, tabId, query, context, enabled, }: UseProductAnalyticsOptions): UseProductAnalyticsReturn;
+//# sourceMappingURL=useProductAnalytics.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"useProductAnalytics.d.ts","sourceRoot":"","sources":["../../src/hooks/useProductAnalytics.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAC3E,OAAO,KAAK,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAG5E,MAAM,WAAW,0BAA0B;IACzC,MAAM,EAAE,aAAa,CAAC;IACtB,OAAO,EAAE,WAAW,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC;IACjD,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,yBAAyB;IACxC,+DAA+D;IAC/D,UAAU,EAAE;QACV,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,CAAC,UAAU,KAAK,IAAI,CAAC;QACxC,yBAAyB,EAAE,MAAM,CAAC;QAClC,uBAAuB,EAAE,MAAM,CAAC;KACjC,CAAC;IACF,yDAAyD;IACzD,kBAAkB,EAAE,CAAC,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK;QACzD,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,CAAC,UAAU,KAAK,IAAI,CAAC;QACxC,6BAA6B,EAAE,MAAM,CAAC;QACtC,4BAA4B,EAAE,MAAM,CAAC;KACtC,CAAC;IACF,mDAAmD;IACnD,cAAc,EAAE,CAAC,OAAO,CAAC,EAAE,cAAc,KAAK;QAC5C,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,CAAC,UAAU,KAAK,IAAI,CAAC;QACxC,qBAAqB,EAAE,aAAa,CAAC;KACtC,CAAC;IACF,8EAA8E;IAC9E,aAAa,EAAE,KAAK,CAAC,WAAW,CAAC,WAAW,CAAC,CAAC;IAC9C,sCAAsC;IACtC,UAAU,EAAE,MAAM,IAAI,CAAC;IACvB,uCAAuC;IACvC,kBAAkB,EAAE,CAAC,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IAChE,oCAAoC;IACpC,cAAc,EAAE,CAAC,OAAO,CAAC,EAAE,cAAc,KAAK,IAAI,CAAC;IACnD,0DAA0D;IAC1D,gBAAgB,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,KAAK,IAAI,CAAC;CAC/E;AAED,wBAAgB,mBAAmB,CAAC,EAClC,MAAM,EACN,OAAO,EACP,QAAY,EACZ,OAAO,EACP,KAAK,EACL,KAAK,EACL,OAAO,EACP,OAAc,GACf,EAAE,0BAA0B,GAAG,yBAAyB,CAyIxD"}

package/dist/hooks/useProductAnalytics.js

@@ -0,0 +1,116 @@
+/**
+ * useProductAnalytics – analytics event binding hook for custom components
+ *
+ * Returns event handler props ready to spread onto any element, plus imperative
+ * tracking methods. Builds on existing useAnalytics infrastructure.
+ */
+import { useCallback, useRef, useEffect } from 'react';
+import { log } from '@seekora-ai/ui-sdk-core';
+export function useProductAnalytics({ client, product, position = 0, section, tabId, query, context, enabled = true, }) {
+    const impressionTrackedRef = useRef(false);
+    const observerRef = useRef(null);
+    const elementRef = useRef(null);
+    const productId = product.id || product.objectID || '';
+    const sendEvent = useCallback(async (eventName, metadata) => {
+        if (!enabled || !client)
+            return;
+        try {
+            await client.trackEvent?.({
+                event_name: eventName,
+                metadata: {
+                    product_id: productId,
+                    product_title: product.title || product.name,
+                    product_price: product.price,
+                    position,
+                    section,
+                    tab_id: tabId,
+                    original_query: query,
+                    timestamp: Date.now(),
+                    source: 'product_analytics',
+                    ...metadata,
+                },
+            }, context);
+            log.verbose(`ProductAnalytics: ${eventName}`, metadata);
+        }
+        catch (error) {
+            log.warn(`Failed to track ${eventName}`, { error });
+        }
+    }, [client, enabled, productId, product, position, section, tabId, query, context]);
+    const trackClick = useCallback(() => {
+        sendEvent('product.click', {});
+        // Also fire via client.trackClick for V3 compat
+        if (client?.trackClick) {
+            Promise.resolve(client.trackClick(productId, position + 1, context)).catch(() => { });
+        }
+    }, [sendEvent, client, productId, position, context]);
+    const trackVariantSelect = useCallback((optionName, value) => {
+        sendEvent('product.variant_select', {
+            option_name: optionName,
+            option_value: value,
+        });
+    }, [sendEvent]);
+    const trackAddToCart = useCallback((variant) => {
+        sendEvent('product.add_to_cart', {
+            variant_id: variant?.id,
+            variant_sku: variant?.sku,
+            variant_title: variant?.title,
+            variant_price: variant?.price,
+        });
+    }, [sendEvent]);
+    const trackCustomEvent = useCallback((eventName, metadata) => {
+        sendEvent(eventName, metadata ?? {});
+    }, [sendEvent]);
+    // Impression tracking via IntersectionObserver
+    const impressionRef = useCallback((node) => {
+        // Cleanup previous observer
+        if (observerRef.current) {
+            observerRef.current.disconnect();
+            observerRef.current = null;
+        }
+        elementRef.current = node;
+        if (!node || !enabled || impressionTrackedRef.current)
+            return;
+        if (typeof IntersectionObserver === 'undefined')
+            return;
+        observerRef.current = new IntersectionObserver((entries) => {
+            for (const entry of entries) {
+                if (entry.isIntersecting && !impressionTrackedRef.current) {
+                    impressionTrackedRef.current = true;
+                    sendEvent('product.impression', {});
+                    observerRef.current?.disconnect();
+                }
+            }
+        }, { threshold: 0.5 });
+        observerRef.current.observe(node);
+    }, [enabled, sendEvent]);
+    // Cleanup on unmount
+    useEffect(() => {
+        return () => {
+            observerRef.current?.disconnect();
+        };
+    }, []);
+    const clickProps = {
+        onClick: () => trackClick(),
+        'data-seekora-product-id': productId,
+        'data-seekora-position': position,
+    };
+    const variantSelectProps = (optionName, value) => ({
+        onClick: () => trackVariantSelect(optionName, value),
+        'data-seekora-variant-option': optionName,
+        'data-seekora-variant-value': value,
+    });
+    const addToCartProps = (variant) => ({
+        onClick: () => trackAddToCart(variant),
+        'data-seekora-action': 'add-to-cart',
+    });
+    return {
+        clickProps,
+        variantSelectProps,
+        addToCartProps,
+        impressionRef,
+        trackClick,
+        trackVariantSelect,
+        trackAddToCart,
+        trackCustomEvent,
+    };
+}

package/dist/hooks/useQuerySuggestions.d.ts

@@ -0,0 +1,21 @@
+/**
+ * useQuerySuggestions Hook
+ *
+ * Hook for fetching query suggestions with debouncing
+ */
+import type { SeekoraClient } from '@seekora-ai/search-sdk';
+import type { SuggestionItem } from '../types';
+export interface UseQuerySuggestionsOptions {
+    client: SeekoraClient;
+    query: string;
+    enabled?: boolean;
+    debounceMs?: number;
+    maxSuggestions?: number;
+}
+export interface UseQuerySuggestionsReturn {
+    suggestions: SuggestionItem[];
+    loading: boolean;
+    error: Error | null;
+}
+export declare const useQuerySuggestions: ({ client, query, enabled, debounceMs, maxSuggestions, }: UseQuerySuggestionsOptions) => UseQuerySuggestionsReturn;
+//# sourceMappingURL=useQuerySuggestions.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"useQuerySuggestions.d.ts","sourceRoot":"","sources":["../../src/hooks/useQuerySuggestions.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAE5D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAE/C,MAAM,WAAW,0BAA0B;IACzC,MAAM,EAAE,aAAa,CAAC;IACtB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,yBAAyB;IACxC,WAAW,EAAE,cAAc,EAAE,CAAC;IAC9B,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;CACrB;AAED,eAAO,MAAM,mBAAmB,GAAI,yDAMjC,0BAA0B,KAAG,yBAuF/B,CAAC"}

package/dist/hooks/useQuerySuggestions.js

@@ -0,0 +1,84 @@
+/**
+ * useQuerySuggestions Hook
+ *
+ * Hook for fetching query suggestions with debouncing
+ */
+import { useState, useEffect, useRef } from 'react';
+import { log } from '@seekora-ai/ui-sdk-core';
+export const useQuerySuggestions = ({ client, query, enabled = true, debounceMs = 300, maxSuggestions = 10, }) => {
+    const [suggestions, setSuggestions] = useState([]);
+    const [loading, setLoading] = useState(false);
+    const [error, setError] = useState(null);
+    const debounceTimerRef = useRef(null);
+    useEffect(() => {
+        // Clear previous timer
+        if (debounceTimerRef.current) {
+            clearTimeout(debounceTimerRef.current);
+        }
+        if (!enabled || !query.trim()) {
+            setSuggestions([]);
+            setLoading(false);
+            setError(null);
+            return;
+        }
+        setLoading(true);
+        setError(null);
+        debounceTimerRef.current = setTimeout(async () => {
+            try {
+                const response = await client.getSuggestions?.(query, maxSuggestions);
+                // Transform suggestions to SuggestionItem format
+                // getSuggestions returns an array of suggestion objects with structure:
+                // { query: string, popularity: number, objectID: string, ... }
+                const rawSuggestions = Array.isArray(response) ? response : [];
+                const suggestionItems = rawSuggestions.map((suggestion) => {
+                    // Extract query - it should be in suggestion.query
+                    const suggestionQuery = suggestion.query || suggestion.text || suggestion;
+                    // Extract count/popularity
+                    const count = suggestion.popularity !== undefined ? suggestion.popularity : (suggestion.count !== undefined ? suggestion.count : undefined);
+                    const item = {
+                        query: typeof suggestionQuery === 'string' ? suggestionQuery : String(suggestionQuery),
+                        count: typeof count === 'number' ? count : undefined,
+                        metadata: suggestion,
+                    };
+                    return item;
+                });
+                setSuggestions(suggestionItems);
+            }
+            catch (err) {
+                const error = err instanceof Error ? err : new Error(String(err));
+                // 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([]);
+                    setError(null);
+                }
+                else {
+                    // For other errors, log and set error state
+                    log.error('Error in useQuerySuggestions:', error);
+                    setError(error);
+                    setSuggestions([]);
+                }
+            }
+            finally {
+                setLoading(false);
+            }
+        }, debounceMs);
+        return () => {
+            if (debounceTimerRef.current) {
+                clearTimeout(debounceTimerRef.current);
+            }
+        };
+    }, [client, query, enabled, debounceMs, maxSuggestions]);
+    return {
+        suggestions,
+        loading,
+        error,
+    };
+};

package/dist/hooks/useQuerySuggestionsEnhanced.d.ts

@@ -0,0 +1,120 @@
+/**
+ * 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 type { SeekoraClient } from '@seekora-ai/search-sdk';
+import type { SuggestionItem, ProductItem, FilteredTab, DropdownRecommendations, RecentSearch, QuerySuggestionsResponse, TrendingSearch, TopSearch, RelatedSearch, PopularBrand, SuggestionCategory } from '@seekora-ai/ui-sdk-types';
+export interface UseQuerySuggestionsEnhancedOptions {
+    /** Seekora client instance */
+    client: SeekoraClient;
+    /** Current search query */
+    query: string;
+    /** Enable/disable the hook */
+    enabled?: boolean;
+    /** Prefetch initial (empty-query) data on mount even if not enabled yet */
+    prefetch?: boolean;
+    /** Debounce delay in ms */
+    debounceMs?: number;
+    /** Max suggestions to fetch */
+    maxSuggestions?: number;
+    /** Minimum query length to trigger search */
+    minQueryLength?: number;
+    /** Include dropdown recommendations (trending, products, etc.) */
+    includeDropdownRecommendations?: boolean;
+    /** When false, omit product hits list from dropdown (default true) */
+    includeDropdownProductList?: boolean;
+    /** When false, omit filtered_tabs from dropdown extensions (default true) */
+    includeFilteredTabs?: boolean;
+    /** Include categories in suggestions */
+    includeCategories?: boolean;
+    /** Include facets in suggestions */
+    includeFacets?: boolean;
+    /** Max categories per suggestion */
+    maxCategories?: number;
+    /** Max facets per suggestion */
+    maxFacets?: number;
+    /** Filtered tabs configuration */
+    filteredTabs?: Array<{
+        id?: string;
+        label: string;
+        filter: string;
+    }>;
+    /** Minimum popularity threshold */
+    minPopularity?: number;
+    /** Time range for analytics data */
+    timeRange?: '7d' | '30d' | '90d';
+    /** Disable typo tolerance */
+    disableTypoTolerance?: boolean;
+    /** Analytics tags */
+    analyticsTags?: string[];
+    /** Enable recent searches from localStorage */
+    enableRecentSearches?: boolean;
+    /** Max recent searches to store */
+    maxRecentSearches?: number;
+    /** Local storage key for recent searches */
+    recentSearchesKey?: string;
+    /** Callback when suggestions are loaded */
+    onSuggestionsLoaded?: (response: QuerySuggestionsResponse) => void;
+    /** Callback on error */
+    onError?: (error: Error) => void;
+}
+export interface UseQuerySuggestionsEnhancedReturn {
+    /** Basic suggestion items */
+    suggestions: SuggestionItem[];
+    /** Loading state */
+    loading: boolean;
+    /** Error state */
+    error: Error | null;
+    /** Dropdown recommendations */
+    dropdownRecommendations: DropdownRecommendations | null;
+    /** Trending searches */
+    trendingSearches: TrendingSearch[];
+    /** Top searches */
+    topSearches: TopSearch[];
+    /** Related searches */
+    relatedSearches: RelatedSearch[];
+    /** Popular brands */
+    popularBrands: PopularBrand[];
+    /** Filtered tabs with products */
+    filteredTabs: FilteredTab[];
+    /** Trending products */
+    trendingProducts: ProductItem[];
+    /** Recent searches (from localStorage) */
+    recentSearches: RecentSearch[];
+    /** Processing time in ms */
+    processingTimeMs: number | null;
+    /** Total hits count */
+    totalHits: number;
+    /** Current page */
+    currentPage: number;
+    /** Total pages */
+    totalPages: number;
+    /** Original query */
+    originalQuery: string;
+    /** Add a search to recent searches */
+    addRecentSearch: (query: string, resultsCount?: number) => void;
+    /** Remove a search from recent searches */
+    removeRecentSearch: (query: string) => void;
+    /** Clear all recent searches */
+    clearRecentSearches: () => void;
+    /** Manually refetch suggestions */
+    refetch: () => Promise<void>;
+    /** Check if dropdown has any content to show */
+    hasContent: boolean;
+    /** Get all items for keyboard navigation (flattened) */
+    getAllNavigableItems: () => NavigableItem[];
+}
+export interface NavigableItem {
+    type: 'suggestion' | 'recent' | 'trending' | 'product' | 'category' | 'brand' | 'tab';
+    index: number;
+    data: SuggestionItem | RecentSearch | TrendingSearch | ProductItem | SuggestionCategory | PopularBrand | FilteredTab;
+}
+export declare function useQuerySuggestionsEnhanced(options: UseQuerySuggestionsEnhancedOptions): UseQuerySuggestionsEnhancedReturn;
+export default useQuerySuggestionsEnhanced;
+//# sourceMappingURL=useQuerySuggestionsEnhanced.d.ts.map