@seekora-ai/ui-sdk-react 0.2.4 → 0.2.7

package/dist/src/index.d.ts

@@ -2,7 +2,7 @@ import * as React$1 from 'react';
 import React__default, { ReactNode, CSSProperties } from 'react';
 import { SearchOptions, SearchResponse, SeekoraClient, SearchContext, DataTypesEventPayload, ExtendedEventPayload } from '@seekora-ai/search-sdk';
 import * as _seekora_ai_ui_sdk_types from '@seekora-ai/ui-sdk-types';
-import { ResultItem, ViewMode, FieldMapping, ThemeConfig, Theme, QuerySuggestionsEventHandlers, HighlightConfig, KeyboardNavConfig, AnimationConfig, QuerySuggestionsClassNames, SuggestionItem as SuggestionItem$2, RecentSearch, DropdownSectionConfig, SuggestionCategory, TrendingSearch, ProductItem, PopularBrand, FilteredTab, QuerySuggestionsVariant, QuerySuggestionsResponse, DropdownRecommendations, TopSearch, RelatedSearch } from '@seekora-ai/ui-sdk-types';
+import { ResultItem, ViewMode, FieldMapping, ThemeConfig, Theme, QuerySuggestionsEventHandlers, HighlightConfig, KeyboardNavConfig, AnimationConfig, QuerySuggestionsClassNames, SuggestionItem as SuggestionItem$3, RecentSearch, DropdownSectionConfig, SuggestionCategory, TrendingSearch, ProductItem, PopularBrand, FilteredTab, QuerySuggestionsVariant, QuerySuggestionsResponse, DropdownRecommendations, TopSearch, RelatedSearch } from '@seekora-ai/ui-sdk-types';
 export { FieldMapping, ResultItem, Theme, ThemeConfig, ViewMode } from '@seekora-ai/ui-sdk-types';
 import { SearchStateManagerConfig, SearchStateManager, HighlightPart, SearchState } from '@seekora-ai/ui-sdk-core';
 export { Fingerprint, FingerprintComponents, FingerprintConfig, FingerprintResult, getFingerprint, mergeThemes } from '@seekora-ai/ui-sdk-core';
@@ -930,7 +930,7 @@ declare function addToRecentlyViewed(item: RecommendationItem, storageKey?: stri
  * Standalone component for displaying query suggestions
  */
 
-interface SuggestionItem$1 {
+interface SuggestionItem$2 {
     query: string;
     count?: number;
     metadata?: Record<string, any>;
@@ -951,7 +951,7 @@ interface QuerySuggestionsProps {
     debounceMs?: number;
     minQueryLength?: number;
     onSuggestionClick?: (suggestion: string) => void;
-    renderSuggestion?: (suggestion: SuggestionItem$1, index: number) => React__default.ReactNode;
+    renderSuggestion?: (suggestion: SuggestionItem$2, index: number) => React__default.ReactNode;
     renderLoading?: () => React__default.ReactNode;
     renderEmpty?: () => React__default.ReactNode;
     showTitle?: boolean;
@@ -1006,7 +1006,7 @@ interface QuerySuggestionsDropdownProps extends QuerySuggestionsEventHandlers {
     /** Custom CSS styles */
     style?: React__default.CSSProperties;
     /** Custom render for suggestion item */
-    renderSuggestion?: (suggestion: SuggestionItem$2, index: number, isActive: boolean, highlight: (text: string) => React__default.ReactNode) => React__default.ReactNode;
+    renderSuggestion?: (suggestion: SuggestionItem$3, index: number, isActive: boolean, highlight: (text: string) => React__default.ReactNode) => React__default.ReactNode;
     /** Custom render for recent search item */
     renderRecentSearch?: (search: RecentSearch, index: number, isActive: boolean) => React__default.ReactNode;
     /** Custom render for loading state */
@@ -1089,7 +1089,7 @@ interface RichQuerySuggestionsProps extends QuerySuggestionsEventHandlers {
     /** Custom CSS styles */
     style?: React__default.CSSProperties;
     /** Custom render for suggestion */
-    renderSuggestion?: (suggestion: SuggestionItem$2, isActive: boolean) => React__default.ReactNode;
+    renderSuggestion?: (suggestion: SuggestionItem$3, isActive: boolean) => React__default.ReactNode;
     /** Custom render for category pill */
     renderCategory?: (category: SuggestionCategory) => React__default.ReactNode;
     /** Custom render for trending item */
@@ -1180,7 +1180,7 @@ interface FederatedDropdownProps extends QuerySuggestionsEventHandlers {
     /** Custom product card renderer */
     renderProduct?: (product: ProductItem, index: number) => React__default.ReactNode;
     /** Custom suggestion renderer */
-    renderSuggestion?: (suggestion: SuggestionItem$2, index: number, isActive: boolean) => React__default.ReactNode;
+    renderSuggestion?: (suggestion: SuggestionItem$3, index: number, isActive: boolean) => React__default.ReactNode;
     /** Custom brand renderer */
     renderBrand?: (brand: PopularBrand, index: number) => React__default.ReactNode;
     /** Custom tab renderer */
@@ -1199,6 +1199,12 @@ interface FederatedDropdownProps extends QuerySuggestionsEventHandlers {
     zIndex?: number;
     /** Analytics tags */
     analyticsTags?: string[];
+    /** Include facets in suggestions API response */
+    includeFacets?: boolean;
+    /** Include categories in suggestions API response */
+    includeCategories?: boolean;
+    /** Include dropdown recommendations (trending products, top searches, etc.) */
+    includeDropdownRecommendations?: boolean;
 }
 interface FederatedDropdownRef {
     getActiveIndex: () => number;
@@ -1232,7 +1238,7 @@ interface SearchBarWithSuggestionsProps {
     /** Callback when search is submitted */
     onSearch?: (query: string) => void;
     /** Callback when suggestion is selected */
-    onSuggestionSelect?: (suggestion: SuggestionItem$2) => void;
+    onSuggestionSelect?: (suggestion: SuggestionItem$3) => void;
     /** Callback when product is clicked */
     onProductClick?: (product: ProductItem) => void;
     /** Show search button */
@@ -1247,6 +1253,8 @@ interface SearchBarWithSuggestionsProps {
     minQueryLength?: number;
     /** Max suggestions to show */
     maxSuggestions?: number;
+    /** Max products to show in dropdown (federated/rich) */
+    maxProducts?: number;
     /** Debounce delay (ms) */
     debounceMs?: number;
     /** Show recent searches */
@@ -1265,6 +1273,10 @@ interface SearchBarWithSuggestionsProps {
     enableAnalytics?: boolean;
     /** Analytics tags */
     analyticsTags?: string[];
+    /** Include facets in suggestions API response (federated/rich) */
+    includeFacets?: boolean;
+    /** Include categories in suggestions API response (federated/rich) */
+    includeCategories?: boolean;
     /** Dropdown width */
     dropdownWidth?: string | number;
     /** Dropdown max height */
@@ -1308,6 +1320,612 @@ interface SearchBarWithSuggestionsRef {
 }
 declare const SearchBarWithSuggestions: React__default.ForwardRefExoticComponent<SearchBarWithSuggestionsProps & React__default.RefAttributes<SearchBarWithSuggestionsRef>>;
 
+/**
+ * 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
+ */
+
+interface UseQuerySuggestionsEnhancedOptions {
+    /** Seekora client instance */
+    client: SeekoraClient;
+    /** Current search query */
+    query: string;
+    /** Enable/disable the hook */
+    enabled?: 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;
+    /** 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;
+}
+interface UseQuerySuggestionsEnhancedReturn {
+    /** Basic suggestion items */
+    suggestions: SuggestionItem$3[];
+    /** 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[];
+}
+interface NavigableItem {
+    type: 'suggestion' | 'recent' | 'trending' | 'product' | 'category' | 'brand' | 'tab';
+    index: number;
+    data: SuggestionItem$3 | RecentSearch | TrendingSearch | ProductItem | SuggestionCategory | PopularBrand | FilteredTab;
+}
+declare function useQuerySuggestionsEnhanced(options: UseQuerySuggestionsEnhancedOptions): UseQuerySuggestionsEnhancedReturn;
+
+/**
+ * Suggestions Context
+ *
+ * Type definitions and React context for composable suggestions primitives.
+ * Consuming components use useSuggestionsContext() for state and actions.
+ */
+
+interface SuggestionsContextValue {
+    query: string;
+    setQuery: (query: string) => void;
+    isOpen: boolean;
+    setIsOpen: (open: boolean) => void;
+    activeIndex: number;
+    setActiveIndex: (index: number) => void;
+    suggestions: SuggestionItem$3[];
+    recentSearches: RecentSearch[];
+    trendingSearches: TrendingSearch[];
+    trendingProducts: ProductItem[];
+    filteredTabs: FilteredTab[];
+    activeTabId: string;
+    setActiveTabId: (id: string) => void;
+    loading: boolean;
+    error: Error | null;
+    hasContent: boolean;
+    getAllNavigableItems: () => NavigableItem[];
+    selectSuggestion: (suggestion: SuggestionItem$3, position: number) => void;
+    selectProduct: (product: ProductItem, position: number, section?: string, tabId?: string) => void;
+    selectRecentSearch: (search: RecentSearch) => void;
+    selectTrendingSearch: (trending: TrendingSearch, position: number) => void;
+    setActiveTab: (tab: FilteredTab) => void;
+    submitSearch: (query: string, fromSuggestion?: boolean, suggestion?: SuggestionItem$3) => void;
+    close: () => void;
+    navigateNext: () => void;
+    navigatePrev: () => void;
+    selectActive: () => void;
+}
+declare function useSuggestionsContext(): SuggestionsContextValue;
+
+/**
+ * SuggestionsProvider
+ *
+ * Provides suggestions state (query, suggestions, products, recent, trending, tabs),
+ * actions (selectSuggestion, selectProduct, submitSearch, etc.), and keyboard navigation.
+ * Uses useQuerySuggestionsEnhanced and useSuggestionsAnalytics; must be inside SearchProvider.
+ */
+
+interface SuggestionsProviderProps {
+    children: React__default.ReactNode;
+    /** Min query length to fetch suggestions */
+    minQueryLength?: number;
+    /** Debounce ms for suggestion fetch */
+    debounceMs?: number;
+    /** Max suggestions */
+    maxSuggestions?: number;
+    /** Include dropdown recommendations (trending, products, etc.) */
+    includeDropdownRecommendations?: boolean;
+    /** Filtered tabs config */
+    filteredTabs?: Array<{
+        id?: string;
+        label: string;
+        filter: string;
+    }>;
+    /** Enable analytics (V3) */
+    enableAnalytics?: boolean;
+    /** Analytics tags */
+    analyticsTags?: string[];
+    /** Callback when user submits search (e.g. navigate to results page) */
+    onSearch?: (query: string) => void;
+    /** Callback when user selects a suggestion */
+    onSuggestionSelect?: (suggestion: SuggestionItem$3) => void;
+    /** Callback when user clicks a product */
+    onProductClick?: (product: ProductItem) => void;
+}
+declare function SuggestionsProvider({ children, minQueryLength, debounceMs, maxSuggestions, includeDropdownRecommendations, filteredTabs, enableAnalytics, analyticsTags, onSearch, onSuggestionSelect, onProductClick, }: SuggestionsProviderProps): React__default.JSX.Element;
+
+/**
+ * SearchInput – suggestion-scoped search input (primitive)
+ *
+ * Single input bound to suggestions context: query, setQuery, focus opens dropdown,
+ * keydown ArrowUp/Down/Enter/Escape delegates to context. Overridable via className/style.
+ */
+
+interface SearchInputProps {
+    placeholder?: string;
+    autoFocus?: boolean;
+    showClearButton?: boolean;
+    className?: string;
+    style?: React__default.CSSProperties;
+    inputClassName?: string;
+    inputStyle?: React__default.CSSProperties;
+    ariaLabel?: string;
+}
+declare function SearchInput({ placeholder, autoFocus, showClearButton, className, style, inputClassName, inputStyle, ariaLabel, }: SearchInputProps): React__default.JSX.Element;
+
+/**
+ * DropdownPanel – floating panel for suggestions (primitive)
+ *
+ * Shows when isOpen; handles click-outside and Escape to close. Children = any composition
+ * of SuggestionList, ProductGrid, etc. Position and z-index configurable.
+ */
+
+interface DropdownPanelProps {
+    children: React__default.ReactNode;
+    position?: 'absolute' | 'fixed';
+    /** CSS top offset (e.g. '100%', '4px') */
+    top?: string | number;
+    left?: string | number;
+    right?: string | number;
+    width?: string | number;
+    maxHeight?: string | number;
+    zIndex?: number;
+    className?: string;
+    style?: React__default.CSSProperties;
+    closeOnClickOutside?: boolean;
+    closeOnEscape?: boolean;
+}
+declare function DropdownPanel({ children, position, top, left, right, width, maxHeight, zIndex, className, style, closeOnClickOutside, closeOnEscape, }: DropdownPanelProps): React__default.JSX.Element | null;
+
+interface SuggestionListProps {
+    maxItems?: number;
+    className?: string;
+    style?: React__default.CSSProperties;
+    listClassName?: string;
+    renderItem?: (suggestion: _seekora_ai_ui_sdk_types.SuggestionItem, index: number, isActive: boolean, onSelect: () => void) => React__default.ReactNode;
+}
+declare function SuggestionList({ maxItems, className, style, listClassName, renderItem, }: SuggestionListProps): React__default.JSX.Element | null;
+
+/**
+ * SuggestionItem – single text suggestion row (primitive)
+ *
+ * Highlights when isActive; onClick calls context selectSuggestion. Overridable via className/style.
+ */
+
+interface SuggestionItemProps {
+    suggestion: SuggestionItem$3;
+    index: number;
+    isActive: boolean;
+    onSelect: () => void;
+    className?: string;
+    style?: React__default.CSSProperties;
+    renderHighlight?: (text: string) => React__default.ReactNode;
+}
+declare function SuggestionItem$1({ suggestion, index, isActive, onSelect, className, style, renderHighlight, }: SuggestionItemProps): React__default.JSX.Element;
+
+/**
+ * ItemCard – generic item tile (primitive)
+ *
+ * Domain-agnostic: works for docs, articles, products, or any hit with id, title,
+ * optional description, image, url. Overridable via className/style. Use for
+ * search results, section blocks, or any list; for e-commerce products use ProductCard.
+ */
+
+/** Generic item shape for ItemCard – compatible with ResultItem and most hit types */
+interface GenericItem {
+    id: string;
+    title: string;
+    description?: string;
+    image?: string;
+    /** Multiple images for carousel/hover/thumbStrip */
+    images?: string[];
+    url?: string;
+    /** Widget/display fields */
+    primaryText?: string;
+    secondaryText?: string;
+    tertiaryText?: string;
+    imageUrl?: string;
+    [key: string]: unknown;
+}
+type ImageDisplayVariant$1 = 'single' | 'carousel' | 'hover' | 'thumbStrip' | 'thumbList';
+interface ItemCardProps {
+    item: GenericItem;
+    /** Position in list (for analytics) */
+    position?: number;
+    onSelect?: () => void;
+    className?: string;
+    style?: React__default.CSSProperties;
+    /** Render as link (anchor) when item.url is set; otherwise button */
+    asLink?: boolean;
+    /** When multiple images, use ImageDisplay with this variant */
+    imageVariant?: ImageDisplayVariant$1;
+}
+declare function ItemCard({ item, position, onSelect, className, style, asLink, imageVariant, }: ItemCardProps): React__default.JSX.Element;
+
+/**
+ * ItemGrid – generic grid of items (primitive)
+ *
+ * Domain-agnostic: accepts any items[] and onItemClick. Renders ItemCard by default
+ * or custom renderItem. Use for search hits, section blocks, docs, articles; for
+ * product-only lists use ProductGrid.
+ */
+
+interface ItemGridProps<T = GenericItem> {
+    items: T[];
+    onItemClick?: (item: T, index: number) => void;
+    /** Map item to GenericItem for default ItemCard rendering */
+    getItemId?: (item: T) => string;
+    getItemTitle?: (item: T) => string;
+    getItemImage?: (item: T) => string | undefined;
+    getItemDescription?: (item: T) => string | undefined;
+    getItemUrl?: (item: T) => string | undefined;
+    /** Custom render for each item; overrides default ItemCard */
+    renderItem?: (item: T, index: number) => React__default.ReactNode;
+    maxItems?: number;
+    columns?: number;
+    className?: string;
+    style?: React__default.CSSProperties;
+    gridClassName?: string;
+}
+declare function ItemGrid<T = GenericItem>({ items, onItemClick, getItemId, getItemTitle, getItemImage, getItemDescription, getItemUrl, renderItem, maxItems, columns, className, style, gridClassName, }: ItemGridProps<T>): React__default.JSX.Element | null;
+
+/**
+ * ProductCard – one product tile (primitive)
+ *
+ * Minimal layout: image (via ImageDisplay when imageVariant set), title, price.
+ * onClick calls context selectProduct. Overridable via className/style.
+ */
+
+type ProductCardImageVariant = 'single' | 'carousel' | 'hover' | 'thumbStrip' | 'thumbList';
+interface ProductCardProps {
+    product: ProductItem;
+    position: number;
+    section?: string;
+    tabId?: string;
+    onSelect: () => void;
+    className?: string;
+    style?: React__default.CSSProperties;
+    imageVariant?: ProductCardImageVariant;
+}
+declare function ProductCard({ product, position, section, tabId, onSelect, className, style, imageVariant, }: ProductCardProps): React__default.JSX.Element;
+
+/**
+ * ProductGrid – grid of product cards from context (primitive)
+ *
+ * Uses trendingProducts or active tab products; each click calls context selectProduct.
+ */
+
+interface ProductGridProps {
+    maxItems?: number;
+    /** 'trending' | tab id for filtered tab products */
+    source?: 'trending' | string;
+    columns?: number;
+    className?: string;
+    style?: React__default.CSSProperties;
+    gridClassName?: string;
+}
+declare function ProductGrid({ maxItems, source, columns, className, style, gridClassName, }: ProductGridProps): React__default.JSX.Element | null;
+
+/**
+ * CategoriesTabs – horizontal tabs (e.g. filtered tabs) (primitive)
+ *
+ * Active tab from context; on select updates context and tracks analytics.
+ */
+
+interface CategoriesTabsProps {
+    className?: string;
+    style?: React__default.CSSProperties;
+    tabClassName?: string;
+}
+declare function CategoriesTabs({ className, style, tabClassName }: CategoriesTabsProps): React__default.JSX.Element | null;
+
+/**
+ * RecentSearchesList – list of recent queries (primitive)
+ *
+ * Reads recentSearches from context; each click calls selectRecentSearch. Optional title/render.
+ */
+
+interface RecentSearchesListProps {
+    title?: string;
+    maxItems?: number;
+    className?: string;
+    style?: React__default.CSSProperties;
+    listClassName?: string;
+    renderItem?: (search: RecentSearch, index: number, onSelect: () => void) => React__default.ReactNode;
+}
+declare function RecentSearchesList({ title, maxItems, className, style, listClassName, renderItem, }: RecentSearchesListProps): React__default.JSX.Element | null;
+
+/**
+ * TrendingList – list of trending searches (primitive)
+ *
+ * Reads trendingSearches from context; each click calls selectTrendingSearch. Optional title/render.
+ */
+
+interface TrendingListProps {
+    title?: string;
+    maxItems?: number;
+    className?: string;
+    style?: React__default.CSSProperties;
+    listClassName?: string;
+    renderItem?: (trending: TrendingSearch, index: number, onSelect: () => void) => React__default.ReactNode;
+}
+declare function TrendingList({ title, maxItems, className, style, listClassName, renderItem, }: TrendingListProps): React__default.JSX.Element | null;
+
+/**
+ * SuggestionsLoading – loading indicator (primitive)
+ */
+
+interface SuggestionsLoadingProps {
+    className?: string;
+    style?: React__default.CSSProperties;
+    text?: string;
+}
+declare function SuggestionsLoading({ className, style, text }: SuggestionsLoadingProps): React__default.JSX.Element | null;
+
+/**
+ * SuggestionsError – error message (primitive)
+ */
+
+interface SuggestionsErrorProps {
+    className?: string;
+    style?: React__default.CSSProperties;
+    render?: (error: Error) => React__default.ReactNode;
+}
+declare function SuggestionsError({ className, style, render }: SuggestionsErrorProps): React__default.JSX.Element | null;
+
+/**
+ * SuggestionsDropdownComposition – reference composition
+ *
+ * Example layout built from primitives: SearchInput + DropdownPanel containing
+ * RecentSearchesList (when query empty), SuggestionList, CategoriesTabs, ProductGrid, TrendingList.
+ * Wrap with SearchProvider and SuggestionsProvider. Use as reference or replace
+ * with your own arrangement of the same primitives.
+ */
+
+interface SuggestionsDropdownCompositionProps extends Omit<SuggestionsProviderProps, 'children'> {
+    /** Show recent searches when query is empty */
+    showRecentSearches?: boolean;
+    /** Show trending list */
+    showTrending?: boolean;
+    /** Show categories/filtered tabs */
+    showTabs?: boolean;
+    /** Show product grid */
+    showProducts?: boolean;
+    /** SearchInput placeholder */
+    placeholder?: string;
+}
+declare function SuggestionsDropdownComposition({ showRecentSearches, showTrending, showTabs, showProducts, placeholder, ...providerProps }: SuggestionsDropdownCompositionProps): React__default.JSX.Element;
+
+/**
+ * ImageDisplay – configurable multi-image display (primitive)
+ *
+ * Variants: single, carousel, hover, thumbStrip, thumbList. Use in ItemCard,
+ * ProductCard, ProductGallery. Overridable via className/style.
+ */
+
+type ImageDisplayVariant = 'single' | 'carousel' | 'hover' | 'thumbStrip' | 'thumbList';
+interface ImageDisplayProps {
+    images: string[];
+    variant?: ImageDisplayVariant;
+    alt?: string;
+    className?: string;
+    style?: React__default.CSSProperties;
+    carouselAutoplay?: boolean;
+    carouselIntervalMs?: number;
+}
+declare function ImageDisplay({ images, variant, alt, className, style, carouselAutoplay, carouselIntervalMs, }: ImageDisplayProps): React__default.JSX.Element;
+
+/**
+ * SectionSearchProvider – preset query + filter section
+ *
+ * Runs client.search(query, { refinements, hitsPerPage, sortBy }) on mount and when
+ * query/filters change. Does not use global SearchStateManager. Use for menus,
+ * sidebar, front-page blocks (e.g. "New arrivals", "On sale").
+ */
+
+interface RefinementInput {
+    field: string;
+    value: string;
+}
+interface SectionSearchProviderProps {
+    children: React__default.ReactNode;
+    query: string;
+    refinements?: RefinementInput[];
+    maxItems?: number;
+    sortBy?: string;
+    enabled?: boolean;
+    sectionId?: string;
+}
+declare function SectionSearchProvider({ children, query, refinements, maxItems, sortBy, enabled, sectionId, }: SectionSearchProviderProps): React__default.JSX.Element;
+
+/**
+ * SectionSearchContext – preset query/filter section state
+ *
+ * For menus, sidebar, front-page blocks. Independent of main search state.
+ */
+
+interface SectionSearchContextValue {
+    items: unknown[];
+    loading: boolean;
+    error: Error | null;
+    totalCount: number;
+    sectionId?: string;
+    trackClick: (item: unknown, position: number) => void;
+}
+declare function useSectionSearchContext(): SectionSearchContextValue;
+
+/**
+ * SectionItemGrid – generic grid of items from SectionSearchProvider (primitive)
+ */
+
+interface SectionItemGridProps {
+    columns?: number;
+    maxItems?: number;
+    className?: string;
+    style?: React__default.CSSProperties;
+    getItemId?: (item: unknown) => string;
+    getItemTitle?: (item: unknown) => string;
+    getItemImage?: (item: unknown) => string | undefined;
+    getItemDescription?: (item: unknown) => string | undefined;
+    getItemUrl?: (item: unknown) => string | undefined;
+    renderItem?: (item: unknown, index: number) => React__default.ReactNode;
+}
+declare function SectionItemGrid({ columns, maxItems, className, style, getItemId, getItemTitle, getItemImage, getItemDescription, getItemUrl, renderItem, }: SectionItemGridProps): React__default.JSX.Element;
+
+/**
+ * SectionLoading – loading state for section (primitive)
+ */
+
+interface SectionLoadingProps {
+    className?: string;
+    style?: React__default.CSSProperties;
+    text?: string;
+}
+declare function SectionLoading({ className, style, text }: SectionLoadingProps): React__default.JSX.Element | null;
+
+/**
+ * SectionError – error state for section (primitive)
+ */
+
+interface SectionErrorProps {
+    className?: string;
+    style?: React__default.CSSProperties;
+    render?: (error: Error) => React__default.ReactNode;
+}
+declare function SectionError({ className, style, render }: SectionErrorProps): React__default.JSX.Element | null;
+
+/**
+ * ProductGallery – product detail image gallery (primitive)
+ *
+ * Uses ImageDisplay with configurable variant (carousel, thumbStrip, etc.).
+ * For use on individual product page.
+ */
+
+interface ProductGalleryProps {
+    images: string[];
+    variant?: ImageDisplayVariant;
+    alt?: string;
+    className?: string;
+    style?: React__default.CSSProperties;
+    carouselAutoplay?: boolean;
+    carouselIntervalMs?: number;
+}
+declare function ProductGallery({ images, variant, alt, className, style, carouselAutoplay, carouselIntervalMs, }: ProductGalleryProps): React__default.JSX.Element;
+
+/**
+ * ProductInfo – product detail block (primitive)
+ *
+ * Title, description, price, optional variant selector and CTA. Minimal layout;
+ * override with className/style. For use on individual product page.
+ */
+
+interface ProductInfoProps {
+    title: string;
+    description?: string;
+    price?: number | string;
+    currency?: string;
+    /** Optional variant selector (e.g. size/color) */
+    renderVariantSelector?: () => React__default.ReactNode;
+    /** Optional CTA (e.g. Add to cart) */
+    renderCTA?: () => React__default.ReactNode;
+    className?: string;
+    style?: React__default.CSSProperties;
+}
+declare function ProductInfo({ title, description, price, currency, renderVariantSelector, renderCTA, className, style, }: ProductInfoProps): React__default.JSX.Element;
+
+/**
+ * ProductRecommendations – related / frequently bought (primitive)
+ *
+ * Renders a section of recommended items (generic ItemGrid or product list).
+ * Pass items and onItemClick; or wrap SectionSearchProvider with preset query for "related".
+ * For use on individual product page.
+ */
+
+interface ProductRecommendationsProps {
+    title?: string;
+    items: GenericItem[] | unknown[];
+    onItemClick?: (item: unknown, index: number) => void;
+    maxItems?: number;
+    columns?: number;
+    className?: string;
+    style?: React__default.CSSProperties;
+    renderItem?: (item: unknown, index: number) => React__default.ReactNode;
+}
+declare function ProductRecommendations({ title, items, onItemClick, maxItems, columns, className, style, renderItem, }: ProductRecommendationsProps): React__default.JSX.Element | null;
+
 /**
  * Shared Types for Query Suggestions Components
  *
@@ -2416,6 +3034,8 @@ interface DocSearchProps {
     initialOpen?: boolean;
     disableShortcut?: boolean;
     shortcutKey?: string;
+    /** Post-process results per source (e.g. filter by permission, resolve :storeId). */
+    processGroupedResults?: (sourceId: string, items: DocSearchSuggestion[]) => DocSearchSuggestion[];
 }
 interface DocSearchButtonProps {
     onClick: () => void;
@@ -2470,7 +3090,7 @@ type DocSearchAction = {
     type: 'RESET';
 };
 
-declare function DocSearch({ storeId, storeSecret, seekoraApiEndpoint, apiEndpoint, apiKey, sources, placeholder, maxResults, debounceMs, onSelect, onClose, translations, renderButton, buttonComponent: ButtonComponent, initialOpen, disableShortcut, shortcutKey, }: DocSearchProps): React__default.JSX.Element;
+declare function DocSearch({ storeId, storeSecret, seekoraApiEndpoint, apiEndpoint, apiKey, sources, placeholder, maxResults, debounceMs, onSelect, onClose, translations, renderButton, buttonComponent: ButtonComponent, initialOpen, disableShortcut, shortcutKey, processGroupedResults, }: DocSearchProps): React__default.JSX.Element;
 
 declare function DocSearchButton({ onClick, placeholder }: DocSearchButtonProps): React__default.JSX.Element;
 
@@ -2480,6 +3100,7 @@ interface UseDocSearchOptions {
     sources?: SearchSource[];
     maxResults?: number;
     debounceMs?: number;
+    processGroupedResults?: (sourceId: string, items: DocSearchSuggestion[]) => DocSearchSuggestion[];
 }
 declare function useDocSearch(options: UseDocSearchOptions): {
     sources: SearchSource[];
@@ -2595,127 +3216,15 @@ interface UseQuerySuggestionsReturn {
 }
 declare const useQuerySuggestions: ({ client, query, enabled, debounceMs, maxSuggestions, }: UseQuerySuggestionsOptions) => UseQuerySuggestionsReturn;
 
-/**
- * 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
- */
-
-interface UseQuerySuggestionsEnhancedOptions {
-    /** Seekora client instance */
-    client: SeekoraClient;
-    /** Current search query */
-    query: string;
-    /** Enable/disable the hook */
-    enabled?: 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;
-    /** 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;
-}
-interface UseQuerySuggestionsEnhancedReturn {
-    /** Basic suggestion items */
-    suggestions: SuggestionItem$2[];
-    /** 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[];
-}
-interface NavigableItem {
-    type: 'suggestion' | 'recent' | 'trending' | 'product' | 'category' | 'brand' | 'tab';
-    index: number;
-    data: SuggestionItem$2 | RecentSearch | TrendingSearch | ProductItem | SuggestionCategory | PopularBrand | FilteredTab;
-}
-declare function useQuerySuggestionsEnhanced(options: UseQuerySuggestionsEnhancedOptions): UseQuerySuggestionsEnhancedReturn;
-
 /**
  * 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
+ * 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.
  */
 
 interface UseSuggestionsAnalyticsOptions {
@@ -2736,7 +3245,7 @@ interface UseSuggestionsAnalyticsOptions {
 }
 interface SuggestionClickEventData {
     /** The clicked suggestion */
-    suggestion: SuggestionItem$2;
+    suggestion: SuggestionItem$3;
     /** Position in the list (0-indexed) */
     position: number;
     /** Section where the suggestion appeared */
@@ -2760,7 +3269,7 @@ interface ProductClickEventData {
 }
 interface SuggestionImpressionEventData {
     /** Suggestions that were shown */
-    suggestions: SuggestionItem$2[];
+    suggestions: SuggestionItem$3[];
     /** Products that were shown */
     products?: ProductItem[];
     /** Categories that were shown */
@@ -2790,7 +3299,7 @@ interface UseSuggestionsAnalyticsReturn {
     /** Track suggestions impression */
     trackImpression: (data: SuggestionImpressionEventData) => void;
     /** Track search submission from suggestion */
-    trackSearchSubmit: (query: string, fromSuggestion: boolean, suggestion?: SuggestionItem$2) => void;
+    trackSearchSubmit: (query: string, fromSuggestion: boolean, suggestion?: SuggestionItem$3) => void;
     /** Track dropdown open */
     trackDropdownOpen: (query: string) => void;
     /** Track dropdown close */
@@ -3096,5 +3605,5 @@ declare function updateSuggestionsStyles(theme: SuggestionsThemeVariables): void
 
 declare const createTheme: (config: ThemeConfig) => _seekora_ai_ui_sdk_types.Theme;
 
-export { AmazonDropdown, Breadcrumb, ClearRefinements, CurrentRefinements, DocSearch, DocSearchButton, Facets, FederatedDropdown, FrequentlyBoughtTogether, GoogleDropdown, HierarchicalMenu, Highlight, HitsPerPage, InfiniteHits, MinimalDropdown, MobileFilters, MobileFiltersButton, MobileSheetDropdown, Pagination, PinterestDropdown, QuerySuggestions, QuerySuggestionsDropdown, RangeInput, RangeSlider, RecentlyViewed, RelatedProducts, RichQuerySuggestions, SearchBar, SearchBarWithSuggestions, SearchLayout, SearchProvider, SearchResults, ShopifyDropdown, Snippet, SortBy, SpotlightDropdown, Stats, SuggestionDropdownVariants, SuggestionSearchBar, SuggestionsCache, TrendingItems, addRecentSearch, addToRecentlyViewed, brandPresets, breakpoints, clearRecentSearches, clearSuggestionsCache, createSuggestionsCache, createSuggestionsTheme, createTheme, darkTheme, darkThemeVariables, defaultTheme, extractBrand, extractCategory, extractProduct, extractSuggestion, formatParsedFilters, formatPrice as formatSuggestionPrice, generateSuggestionsStylesheet, getRecentSearches, getShortcutText, getSuggestionsCache, highlightText, injectGlobalResponsiveStyles, injectSuggestionsStyles, lightThemeVariables, mediaQueries, minimalTheme, minimalThemeVariables, removeRecentSearch, touchTargets, updateSuggestionsStyles, useAnalytics, useDocSearch, useSeekoraSearch$1 as useDocSearchSeekoraSearch, useInjectResponsiveStyles, useKeyboard, useNaturalLanguageFilters, useQuerySuggestions, useQuerySuggestionsEnhanced, useResponsive, useSearchContext, useSearchState, useSeekoraSearch, useSmartSuggestions, useSuggestionsAnalytics };
-export type { AnalyticsConfig, AnalyticsEventPayload, BaseDropdownProps, BrandFieldMapping, BreadcrumbItem, BreadcrumbProps, BreadcrumbTheme, CategoryFieldMapping, ClearRefinementsProps, ClearRefinementsTheme, DocSearchAction, DocSearchButtonProps, DocSearchHit, DocSearchProps, DocSearchResponse, DocSearchState, DocSearchSuggestion, DocSearchSuggestionsResponse, DocSearchTranslations, DropdownClassNames, DropdownEventHandlers, DropdownRef, DropdownThemeConfig, FederatedDropdownProps, FederatedDropdownRef, FrequentlyBoughtTogetherProps, HierarchicalMenuItem, HierarchicalMenuProps, HierarchicalMenuTheme, HighlightProps, HighlightTheme, HitsPerPageItem, HitsPerPageProps, HitsPerPageTheme, InfiniteHitsProps, InfiniteHitsTheme, MobileFiltersButtonProps, MobileFiltersProps, MobileFiltersTheme, NaturalLanguageFiltersOptions, NaturalLanguageResult, NavigableItem, ParsedFilter, ProductClickEventData, ProductDisplayConfig, ProductFieldMapping, QuerySuggestionsDropdownProps, QuerySuggestionsDropdownRef, QuerySuggestionsProps, QuerySuggestionsTheme, RangeSliderProps, RangeSliderTheme, RecentlyViewedProps, RecommendationItem, RecommendationTheme, RelatedProductsProps, ResponsiveState, RichQuerySuggestionsProps, RichQuerySuggestionsRef, SearchBarProps, SearchBarTheme, SearchBarWithSuggestionsProps, SearchBarWithSuggestionsRef, SearchProviderProps, SearchResultsProps, SearchResultsTheme, SearchSource, SectionConfig, SmartSuggestion, SmartSuggestionsOptions, SnippetProps, SnippetTheme, SuggestionClickEventData, SuggestionDisplayConfig, SuggestionDropdownVariant, SuggestionFieldMapping, SuggestionImpressionEventData, SuggestionItem$1 as SuggestionItem, SuggestionSearchBarProps, SuggestionSearchBarRef, SuggestionsThemeVariables, TrendingItemsProps, UseAnalyticsOptions, UseAnalyticsReturn, UseSeekoraSearchOptions$1 as UseDocSearchSeekoraSearchOptions, UseSeekoraSearchResult as UseDocSearchSeekoraSearchResult, UseQuerySuggestionsEnhancedOptions, UseQuerySuggestionsEnhancedReturn, UseSmartSuggestionsReturn, UseSuggestionsAnalyticsOptions, UseSuggestionsAnalyticsReturn };
+export { AmazonDropdown, Breadcrumb, CategoriesTabs, ClearRefinements, CurrentRefinements, DocSearch, DocSearchButton, DropdownPanel, Facets, FederatedDropdown, FrequentlyBoughtTogether, GoogleDropdown, HierarchicalMenu, Highlight, HitsPerPage, ImageDisplay, InfiniteHits, ItemCard, ItemGrid, MinimalDropdown, MobileFilters, MobileFiltersButton, MobileSheetDropdown, Pagination, PinterestDropdown, ProductCard, ProductGallery, ProductGrid, ProductInfo, ProductRecommendations, QuerySuggestions, QuerySuggestionsDropdown, RangeInput, RangeSlider, RecentSearchesList, RecentlyViewed, RelatedProducts, RichQuerySuggestions, SearchBar, SearchBarWithSuggestions, SearchInput, SearchLayout, SearchProvider, SearchResults, SectionError, SectionItemGrid, SectionLoading, SectionSearchProvider, ShopifyDropdown, Snippet, SortBy, SpotlightDropdown, Stats, SuggestionDropdownVariants, SuggestionItem$1 as SuggestionItem, SuggestionList, SuggestionSearchBar, SuggestionsCache, SuggestionsDropdownComposition, SuggestionsError, SuggestionsLoading, SuggestionsProvider, TrendingItems, TrendingList, addRecentSearch, addToRecentlyViewed, brandPresets, breakpoints, clearRecentSearches, clearSuggestionsCache, createSuggestionsCache, createSuggestionsTheme, createTheme, darkTheme, darkThemeVariables, defaultTheme, extractBrand, extractCategory, extractProduct, extractSuggestion, formatParsedFilters, formatPrice as formatSuggestionPrice, generateSuggestionsStylesheet, getRecentSearches, getShortcutText, getSuggestionsCache, highlightText, injectGlobalResponsiveStyles, injectSuggestionsStyles, lightThemeVariables, mediaQueries, minimalTheme, minimalThemeVariables, removeRecentSearch, touchTargets, updateSuggestionsStyles, useAnalytics, useDocSearch, useSeekoraSearch$1 as useDocSearchSeekoraSearch, useInjectResponsiveStyles, useKeyboard, useNaturalLanguageFilters, useQuerySuggestions, useQuerySuggestionsEnhanced, useResponsive, useSearchContext, useSearchState, useSectionSearchContext, useSeekoraSearch, useSmartSuggestions, useSuggestionsAnalytics, useSuggestionsContext };
+export type { AnalyticsConfig, AnalyticsEventPayload, BaseDropdownProps, BrandFieldMapping, BreadcrumbItem, BreadcrumbProps, BreadcrumbTheme, CategoriesTabsProps, CategoryFieldMapping, ClearRefinementsProps, ClearRefinementsTheme, DocSearchAction, DocSearchButtonProps, DocSearchHit, DocSearchProps, DocSearchResponse, DocSearchState, DocSearchSuggestion, DocSearchSuggestionsResponse, DocSearchTranslations, DropdownClassNames, DropdownEventHandlers, DropdownPanelProps, DropdownRef, DropdownThemeConfig, FederatedDropdownProps, FederatedDropdownRef, FrequentlyBoughtTogetherProps, GenericItem, HierarchicalMenuItem, HierarchicalMenuProps, HierarchicalMenuTheme, HighlightProps, HighlightTheme, HitsPerPageItem, HitsPerPageProps, HitsPerPageTheme, ImageDisplayProps, ImageDisplayVariant, InfiniteHitsProps, InfiniteHitsTheme, ImageDisplayVariant$1 as ItemCardImageVariant, ItemCardProps, ItemGridProps, MobileFiltersButtonProps, MobileFiltersProps, MobileFiltersTheme, NaturalLanguageFiltersOptions, NaturalLanguageResult, NavigableItem, ParsedFilter, ProductCardImageVariant, ProductCardProps, ProductClickEventData, ProductDisplayConfig, ProductFieldMapping, ProductGalleryProps, ProductGridProps, ProductInfoProps, ProductRecommendationsProps, QuerySuggestionsDropdownProps, QuerySuggestionsDropdownRef, QuerySuggestionsProps, QuerySuggestionsTheme, RangeSliderProps, RangeSliderTheme, RecentSearchesListProps, RecentlyViewedProps, RecommendationItem, RecommendationTheme, RefinementInput, RelatedProductsProps, ResponsiveState, RichQuerySuggestionsProps, RichQuerySuggestionsRef, SearchBarProps, SearchBarTheme, SearchBarWithSuggestionsProps, SearchBarWithSuggestionsRef, SearchInputProps, SearchProviderProps, SearchResultsProps, SearchResultsTheme, SearchSource, SectionConfig, SectionErrorProps, SectionItemGridProps, SectionLoadingProps, SectionSearchContextValue, SectionSearchProviderProps, SmartSuggestion, SmartSuggestionsOptions, SnippetProps, SnippetTheme, SuggestionClickEventData, SuggestionDisplayConfig, SuggestionDropdownVariant, SuggestionFieldMapping, SuggestionImpressionEventData, SuggestionItemProps, SuggestionListProps, SuggestionSearchBarProps, SuggestionSearchBarRef, SuggestionsContextValue, SuggestionsDropdownCompositionProps, SuggestionsErrorProps, SuggestionsLoadingProps, SuggestionsProviderProps, SuggestionsThemeVariables, TrendingItemsProps, TrendingListProps, UseAnalyticsOptions, UseAnalyticsReturn, UseSeekoraSearchOptions$1 as UseDocSearchSeekoraSearchOptions, UseSeekoraSearchResult as UseDocSearchSeekoraSearchResult, UseQuerySuggestionsEnhancedOptions, UseQuerySuggestionsEnhancedReturn, UseSmartSuggestionsReturn, UseSuggestionsAnalyticsOptions, UseSuggestionsAnalyticsReturn };